create-egregore 0.21.0-runtime-mvp.27 → 0.21.0

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.27
+// egregore-launcher-version: 0.21.0
 //
 // 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.27";
+const VERSION = "0.21.0";
 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");
@@ -753,72 +753,121 @@ async function renderCodexStartupCard(egregoreDir) {
   return false;
 }
 
-function codexSupportMessage(egregoreDir) {
-  return [
-    "Codex harness support is missing from this Egregore checkout.",
-    `  path: ${egregoreDir}`,
-    "",
-    "This checkout needs a newer Egregore core with:",
-    "  bin/codex-session-start.sh",
-    "  bin/codex-install-skills.sh",
-    "  .codex/config.toml",
-    "  .codex/skills/",
-    "  .codex/hooks.json",
-    "  .codex/hooks/",
-    "",
-    "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");
+const CORE_SUPPORT_PATHS = {
+  codex: [
+    "AGENTS.md",
+    "bin/codex-session-start.sh",
+    "bin/codex-install-skills.sh",
+    ".codex/config.toml",
+    ".codex/skills",
+    ".codex/hooks.json",
+    ".codex/hooks",
+  ],
+  pi: [
+    "bin/pi-session-start.sh",
+    ".pi/APPEND_SYSTEM.md",
+    ".pi/settings.json",
+    ".pi/extensions/egregore.ts",
+    ".codex/skills",
+  ],
+  prime: [
+    "bin/prime-session-start.sh",
+    ".prime/agent/APPEND_SYSTEM.md",
+    ".prime/agent/settings.json",
+    ".prime/agent/extensions/egregore.ts",
+    ".codex/skills",
+  ],
+};
+
+function missingCorePaths(runtime, egregoreDir) {
+  return (CORE_SUPPORT_PATHS[runtime] || []).filter(
+    (rel) => !fs.existsSync(path.join(egregoreDir, ...rel.split("/"))),
+  );
 }
 
 function hasCodexCoreSupport(egregoreDir) {
-  return (
-    fs.existsSync(path.join(egregoreDir, "bin", "codex-session-start.sh")) &&
-    fs.existsSync(path.join(egregoreDir, "bin", "codex-install-skills.sh")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "config.toml")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "skills")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "hooks.json")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "hooks"))
-  );
+  return missingCorePaths("codex", egregoreDir).length === 0;
 }
 
 function hasPiCoreSupport(egregoreDir) {
-  return (
-    fs.existsSync(path.join(egregoreDir, "bin", "pi-session-start.sh")) &&
-    fs.existsSync(path.join(egregoreDir, ".pi", "APPEND_SYSTEM.md")) &&
-    fs.existsSync(path.join(egregoreDir, ".pi", "settings.json")) &&
-    fs.existsSync(path.join(egregoreDir, ".pi", "extensions", "egregore.ts")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "skills"))
-  );
+  return missingCorePaths("pi", egregoreDir).length === 0;
 }
 
-function piSupportMessage(egregoreDir) {
-  return [
-    "Pi meta-harness support is missing from this Egregore checkout.",
+function hasPrimeCoreSupport(egregoreDir) {
+  return missingCorePaths("prime", egregoreDir).length === 0;
+}
+
+// The repair command is pinned to this launcher's own release. `@latest`
+// once pulled another release channel's files into an instance; the
+// launcher and the files it installs must always be the same version.
+function harnessAddCommand(runtime) {
+  return `npx -y ${PUBLIC_NPX_PACKAGE}@${VERSION} --add-harness ${runtimeShort(runtime)}`;
+}
+
+function harnessSupportMessage(runtime, egregoreDir) {
+  const label = runtimeLabel(runtime);
+  const missing = missingCorePaths(runtime, egregoreDir);
+  const lines = [
+    `${label} support is missing from this Egregore checkout.`,
     `  path: ${egregoreDir}`,
+  ];
+  if (missing.length > 0) {
+    lines.push("", "Missing:");
+    for (const rel of missing) lines.push(`  ${rel}`);
+  }
+  lines.push(
     "",
-    "Restore this instance using its installed runtime version, then rerun egregore.",
-  ].join("\n");
+    `Add ${label} support to this instance (missing files only, nothing overwritten):`,
+    `  cd ${egregoreDir}`,
+    `  ${harnessAddCommand(runtime)}`,
+    "Then rerun egregore.",
+  );
+  if (runtime === "codex") {
+    lines.push("Egregore workflows appear as slash commands. In Codex, invoke them with the matching $skill token or ask in natural language.");
+  }
+  return lines.join("\n");
 }
 
-function hasPrimeCoreSupport(egregoreDir) {
-  return (
-    fs.existsSync(path.join(egregoreDir, "bin", "prime-session-start.sh")) &&
-    fs.existsSync(path.join(egregoreDir, ".prime", "agent", "APPEND_SYSTEM.md")) &&
-    fs.existsSync(path.join(egregoreDir, ".prime", "agent", "settings.json")) &&
-    fs.existsSync(path.join(egregoreDir, ".prime", "agent", "extensions", "egregore.ts")) &&
-    fs.existsSync(path.join(egregoreDir, ".codex", "skills"))
-  );
+function codexSupportMessage(egregoreDir) {
+  return harnessSupportMessage("codex", egregoreDir);
+}
+
+function piSupportMessage(egregoreDir) {
+  return harnessSupportMessage("pi", egregoreDir);
 }
 
 function primeSupportMessage(egregoreDir) {
-  return [
-    "Prime Agent runtime support is missing from this Egregore checkout.",
-    `  path: ${egregoreDir}`,
+  return harnessSupportMessage("prime", egregoreDir);
+}
+
+// A launch that fails the support check offers to add exactly that harness
+// to exactly this instance, using this launcher's own release. Without a
+// terminal to ask, print the command and stop; never install unattended.
+async function ensureHarnessSupport(inst, runtime) {
+  if (missingCorePaths(runtime, inst.path).length === 0) return;
+  const message = harnessSupportMessage(runtime, inst.path);
+  if (!canPrompt()) die(message);
+  const label = runtimeLabel(runtime);
+  const name = inst.name || inst.slug || path.basename(inst.path);
+  process.stdout.write([
     "",
-    "Restore this instance using its installed runtime version, then rerun egregore.",
-  ].join("\n");
+    `  ${BOLD}${label} support is missing from ${name}.${RESET}`,
+    `  ${DIM}Missing: ${missingCorePaths(runtime, inst.path).join(", ")}${RESET}`,
+    `  ${DIM}Egregore can add it now. Only missing files are written; nothing is overwritten:${RESET}`,
+    `    ${harnessAddCommand(runtime)}`,
+    "",
+  ].join("\n"));
+  const yes = await confirmLine(`Add ${label} support to ${name} now?`);
+  if (!yes) die(message);
+  const result = spawnSync(
+    "npx",
+    ["-y", `${PUBLIC_NPX_PACKAGE}@${VERSION}`, "--add-harness", runtimeShort(runtime)],
+    { cwd: inst.path, stdio: "inherit", env: process.env, timeout: 3 * 60 * 1000 },
+  );
+  if (result.error || result.status !== 0 || missingCorePaths(runtime, inst.path).length > 0) {
+    die(`${label} support could not be added automatically.\n\n${harnessSupportMessage(runtime, inst.path)}`);
+  }
+  process.stdout.write(`  ${GREEN}✓${RESET} ${label} support added to ${name}\n\n`);
 }
 
 // Minimal y/N line prompt for pre-launch decisions (the TUI select machinery
@@ -873,7 +922,7 @@ function primeAuthHint() {
 
 function installCodexSkills(egregoreDir) {
   const script = path.join(egregoreDir, "bin", "codex-install-skills.sh");
-  if (!fs.existsSync(script)) return false;
+  if (!fs.existsSync(script)) return { ok: false, stderr: `missing ${script}` };
   try {
     const result = spawnSync("bash", [script], {
       cwd: egregoreDir,
@@ -881,9 +930,9 @@ function installCodexSkills(egregoreDir) {
       encoding: "utf-8",
       maxBuffer: 1024 * 1024,
     });
-    return result.status === 0;
-  } catch {
-    return false;
+    return { ok: result.status === 0, stderr: (result.stderr || "").trim() };
+  } catch (err) {
+    return { ok: false, stderr: String(err && err.message ? err.message : err) };
   }
 }
 
@@ -966,29 +1015,31 @@ async function launch(inst, runtimeOverride) {
     }
   }
   if (runtime === "codex") {
-    // Launching never changes an instance's runtime or release channel.
-    if (!hasCodexCoreSupport(inst.path)) die(codexSupportMessage(inst.path));
-    const skillsInstalled = installCodexSkills(inst.path);
+    // Launching never changes an instance's runtime or release channel. A
+    // missing harness is added only with the user's consent, one harness
+    // into this one instance, at this launcher's own version.
+    await ensureHarnessSupport(inst, runtime);
+    const skills = installCodexSkills(inst.path);
+    if (!skills.ok) {
+      die(`Codex skill setup failed in ${inst.path} (bin/codex-install-skills.sh):\n${skills.stderr || "  (no error output)"}`);
+    }
     const cardRendered = await renderCodexStartupCard(inst.path);
-    if (!skillsInstalled || !cardRendered) {
-      die(codexSupportMessage(inst.path));
+    if (!cardRendered) {
+      die(`Codex startup card failed in ${inst.path} (bin/codex-session-start.sh exited non-zero; its output is above).`);
     }
   } else if (runtime === "pi") {
-    if (!hasPiCoreSupport(inst.path)) {
-      die(piSupportMessage(inst.path));
-    }
+    await ensureHarnessSupport(inst, runtime);
   }
   let launchArgs = null;
   if (runtime === "prime") {
+    await ensureHarnessSupport(inst, runtime);
     // Cover the gap between choosing the harness and Prime's first paint:
-    // the loader runs through the launcher-side pre-flight (core-support
-    // check + the trust-flag probe, which shells out to the binary), then a
-    // single handoff line explains the remaining in-harness startup.
+    // the loader runs through the launcher-side pre-flight (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");
-    const coreOk = hasPrimeCoreSupport(inst.path);
-    launchArgs = coreOk ? runtimeLaunchArgs(runtime, inst.path) : null;
+    launchArgs = runtimeLaunchArgs(runtime, inst.path);
     stopLoader();
-    if (!coreOk) die(primeSupportMessage(inst.path));
     primeAuthHint();
     process.stdout.write(`  ${CYAN}◆${RESET} ${BOLD}Prime Agent starting${RESET}${DIM} — the Egregore greeting loads inside in a few seconds${RESET}\n`);
   }
@@ -1304,7 +1355,10 @@ function compareReleaseVersions(a, b) {
 }
 
 function cliUpdateState(latest) {
-  if (!parseReleaseVersion(latest)) return null;
+  // The global refresh follows latest; prerelease testing is selected explicitly.
+  const parsed = parseReleaseVersion(latest);
+  if (!RUNTIME_STABLE_VERSION_RE.test(latest || "") || !parsed
+      || !parsed.parts.every(Number.isSafeInteger)) return null;
   return {
     current: VERSION,
     latest,
@@ -1395,7 +1449,7 @@ function cmdCliUpdate(latest) {
   );
   if (result.status !== 0) {
     console.log(`\r${ANSI.clearLine}  [1/2] ${YELLOW}!${RESET} Install failed`);
-    const detail = String(result.stderr || result.stdout || "").trim().split("\n").filter(Boolean).pop();
+    const detail = adapterErrorText(result.stderr || result.stdout || "").trim().split("\n").filter(Boolean).pop();
     if (detail) console.error(`        ${DIM}${detail}${RESET}`);
     console.error(`        Retry: npx -y ${PUBLIC_NPX_PACKAGE}@${latest} --refresh-launcher\n`);
     process.exitCode = 1;
@@ -1567,10 +1621,39 @@ function persistConnectState(inst, fields) {
   writeJsonFileAtomic(file, state);
 }
 
+// Older installed adapters and API versions may still use storage terminology.
+// Normalize only diagnostic display text; protocol fields and payloads stay intact.
+function adapterErrorText(detail) {
+  return String(detail)
+    // Describe a retired technical reference as a whole. Replacing one word
+    // inside a path/module or shell invocation would invent a runnable command.
+    .replace(/(^|\s)(?:(?:\/[^\s"'`]+)*\/)?(?:bash|sh|zsh)\s+(?:"([^"\n]+)"|'([^'\n]+)'|([^\s;"'`]+))/g,
+      (command, prefix, quoted, singleQuoted, bare) => {
+        const script = quoted || singleQuoted || bare;
+        if (!/(?:graph|neo4j)/i.test(script)) return command;
+        return prefix + (/sync-graph\.sh$/i.test(script) ? "the memory sync operation" : "the hosted storage operation");
+      })
+    .replace(/[^\s"'`()\[\]{},;:]+/g, (token) => {
+      if (!/(?:graph|neo4j)/i.test(token)) return token;
+      if (/[/\\]/.test(token)) {
+        if (/[/\\]bin[/\\][^/\\]+\.sh$/i.test(token) || /^bin[/\\][^/\\]+\.sh$/i.test(token)) {
+          return /sync-graph\.sh$/i.test(token) ? "the memory sync adapter" : "the hosted storage adapter";
+        }
+        return "the hosted storage path";
+      }
+      if (/^[a-z_][\w-]*(?:\.[a-z_][\w-]*)+\.?$/i.test(token)) return "the hosted storage component";
+      return token;
+    })
+    .replace(/\bknowledge graph\b/gi, "shared memory")
+    .replace(/\bgraph database\b/gi, "hosted storage")
+    .replace(/\bneo4j\b/gi, "hosted storage")
+    .replace(/\bgraph\b/gi, "storage");
+}
+
 function connectError(result, fallback) {
   if (!result) return fallback;
   const data = result.data || {};
-  return data.detail || data.message || (typeof data === "string" ? data : fallback);
+  return adapterErrorText(data.detail || data.message || (typeof data === "string" ? data : fallback));
 }
 
 function sleep(ms) {
@@ -1596,7 +1679,7 @@ function backfillSummaryLines(summary) {
 
   if (sessions !== null && artifacts !== null && quests !== null) {
     if (sessions + artifacts + quests === 0) {
-      lines.push("Graph already contained all sessions, artifacts, and quests");
+      lines.push("Hosted memory is already up to date for sessions, artifacts, and quests");
     } else {
       lines.push(`Added ${[
         backfillCountLabel(sessions, "session", "sessions"),
@@ -1614,6 +1697,23 @@ function backfillSummaryLines(summary) {
   return lines;
 }
 
+function connectedOrganizationId(config, response) {
+  const current = String(config.org_id || "");
+  const returned = String(response?.org_id || "");
+  if (!/^(?:org_[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/.test(returned) ||
+      (current && !current.startsWith("legacy-org:") && returned !== current)) {
+    die("Connected did not confirm this Egregore's existing identity. Local configuration is unchanged; update the hosted service before retrying.");
+  }
+  return returned || current;
+}
+
+function hostedMemorySyncEnabled(config) {
+  const override = process.env.EGREGORE_GRAPH_PROJECTION;
+  if (["1", "true", "enabled"].includes(override)) return true;
+  if (["0", "false", "disabled"].includes(override)) return false;
+  return config.features?.graph_projection === true;
+}
+
 async function cmdConnect(args) {
   const fresh = args.includes("--fresh");
   const positional = args.filter((a) => !String(a).startsWith("--"));
@@ -1631,6 +1731,8 @@ async function cmdConnect(args) {
     die(`GITHUB_TOKEN is missing for ${inst.slug}.\n  Add it to ${path.join(inst.path, ".env")} and retry.`);
   }
   const activation = state.connected_activation || {};
+  let expectedOrgId = cfg.org_id && !String(cfg.org_id).startsWith("legacy-org:")
+    ? cfg.org_id : activation.org_id || "";
   if (cfg.mode === "connected" && activation.status === "connected") {
     if (activation.intent_id) {
       const repaired = await connectedApiRequest(
@@ -1644,8 +1746,10 @@ async function cmdConnect(args) {
           `Connected is active, but its shared configuration could not be published: ${connectError(repaired, `HTTP ${repaired.status}`)}`,
         );
       }
+      const orgId = connectedOrganizationId(cfg, repaired.data);
       writeJsonFileAtomic(path.join(inst.path, "egregore.json"), {
         ...cfg,
+        ...(orgId ? { org_id: orgId } : {}),
         mode: "connected",
         api_url: repaired.data.api_url,
       });
@@ -1701,16 +1805,18 @@ async function cmdConnect(args) {
     // Local installs may have skipped platform registration (DO_NOT_TRACK
     // gates it as telemetry). Connect requires it functionally, and choosing
     // Connect is the consent — register on demand. Idempotent for members of
-    // already-registered orgs; a 409 (registered by someone else) falls
-    // through to the billing-actor check on intent creation.
+    // already-registered orgs. Identity conflicts must stop before checkout.
     const registration = await connectedApiRequest(githubToken, "POST", "/api/org/register", {
       org_name: cfg.org_name || inst.slug,
       github_org: cfg.github_org || "",
       slug: cfg.slug || inst.slug,
+      ...(cfg.org_id && !String(cfg.org_id).startsWith("legacy-org:") ? { org_id: cfg.org_id } : {}),
+      repo_name: cfg.repo_name || "egregore",
     });
-    if (registration.status !== 200 && registration.status !== 409) {
+    if (registration.status !== 200) {
       die(`could not register this Egregore with the platform: ${connectError(registration, `HTTP ${registration.status}`)}`);
     }
+    expectedOrgId = connectedOrganizationId(cfg, registration.data);
     console.log(`  [1/5] ${DIM}Creating connection intent…${RESET}`);
     const checkout = await connectedApiRequest(
       githubToken,
@@ -1724,6 +1830,7 @@ async function cmdConnect(args) {
           mode: cfg.mode || "local",
           repo_name: cfg.repo_name || "",
           managed_repo_count: Array.isArray(cfg.repos) ? cfg.repos.length : 0,
+          hosted_memory_sync: hostedMemorySyncEnabled(cfg),
           fresh,
         },
       },
@@ -1736,6 +1843,7 @@ async function cmdConnect(args) {
     connectUrl = checkout.data.connect_url;
     persistConnectState(inst, {
       intent_id: intentId,
+      org_id: expectedOrgId,
       connect_ticket: checkout.data.connect_ticket,
       connect_ticket_expires_at: checkout.data.connect_ticket_expires_at,
       connect_url: connectUrl,
@@ -1743,6 +1851,17 @@ async function cmdConnect(args) {
     });
     console.log(`  [1/5] ${GREEN}✓${RESET} Connection intent`);
   } else {
+    if (!expectedOrgId) {
+      const registration = await connectedApiRequest(githubToken, "POST", "/api/org/register", {
+        org_name: cfg.org_name || inst.slug, github_org: cfg.github_org || "",
+        slug: cfg.slug || inst.slug, repo_name: cfg.repo_name || "egregore",
+      });
+      if (registration.status !== 200) {
+        die(`could not confirm this Egregore's identity: ${connectError(registration, `HTTP ${registration.status}`)}`);
+      }
+      expectedOrgId = connectedOrganizationId(cfg, registration.data);
+      persistConnectState(inst, { org_id: expectedOrgId });
+    }
     console.log(`  [1/5] ${GREEN}✓${RESET} Resuming connection intent`);
   }
 
@@ -1802,8 +1921,11 @@ async function cmdConnect(args) {
   const configFile = path.join(inst.path, "egregore.json");
   const envFile = path.join(inst.path, ".env");
   const currentConfig = readJsonFile(configFile);
+  const orgId = connectedOrganizationId({ ...currentConfig, org_id: expectedOrgId || currentConfig.org_id }, claim.data);
+  const syncEnabled = hostedMemorySyncEnabled(currentConfig);
   writeJsonFileAtomic(configFile, {
     ...currentConfig,
+    ...(orgId ? { org_id: orgId } : {}),
     mode: "connected",
     api_url: claim.data.api_url,
   });
@@ -1814,19 +1936,22 @@ async function cmdConnect(args) {
     status: "backfilling",
     activation_protocol: claim.data.activation_protocol,
   });
-  console.log(`  [4/5] ${GREEN}✓${RESET} Connected credential and graph node`);
+  console.log(`  [4/5] ${GREEN}✓${RESET} Hosted access and organization ready`);
 
   let backfillSummary = { replayed: true };
   if (fresh) {
     // Fresh install — no existing memory to project; skip the replay entirely.
-    console.log(`  [5/5] ${GREEN}✓${RESET} Fresh instance — nothing to project yet`);
+    console.log(`  [5/5] ${GREEN}✓${RESET} Fresh instance — no existing memory to sync`);
     backfillSummary = { fresh: true, replayed: false };
+  } else if (!syncEnabled) {
+    backfillSummary = { replayed: false, reason: "local_memory" };
+    console.log(`  [5/5] ${GREEN}✓${RESET} Memory and retrieval remain local`);
   } else {
     const syncScript = path.join(inst.path, "bin", "sync-graph.sh");
     if (!fs.existsSync(syncScript)) {
-      die("bin/sync-graph.sh is missing. Update the installed Egregore version, then run egregore connect again.");
+      die("The memory sync adapter is missing. Update the installed Egregore version, then run egregore connect again.");
     }
-    console.log(`  [5/5] ${CYAN}◦${RESET} Projecting existing memory into the graph…`);
+    console.log(`  [5/5] ${CYAN}◦${RESET} Syncing existing memory with hosted services…`);
     console.log(`        ${DIM}Scanning sessions, artifacts, quests, and ingest history${RESET}`);
     const sync = spawnSync("bash", [syncScript], {
       cwd: inst.path,
@@ -1835,8 +1960,8 @@ async function cmdConnect(args) {
       timeout: 10 * 60 * 1000,
     });
     if (sync.status !== 0) {
-      const detail = (sync.stderr || sync.stdout || "graph replay failed").trim();
-      die(`Connected is configured, but graph replay did not finish.\n  ${detail}\n  Run egregore connect ${inst.slug} to retry; existing data is unchanged.`);
+      const detail = adapterErrorText(sync.stderr || sync.stdout || "memory sync failed").trim();
+      die(`Connected is configured, but memory sync did not finish.\n  ${detail}\n  Run egregore connect ${inst.slug} to retry; existing data is unchanged.`);
     }
     try { backfillSummary = JSON.parse((sync.stdout || "").trim()); } catch {}
   }
@@ -1853,15 +1978,15 @@ async function cmdConnect(args) {
     await sleep(250 * (attempt + 1));
   }
   if (complete.status !== 200) {
-    die(`graph replay finished, but activation could not be finalized: ${connectError(complete, `HTTP ${complete.status}`)}`);
+    die(`Hosted access is configured, but activation could not be finalized: ${connectError(complete, `HTTP ${complete.status}`)}`);
   }
   persistConnectState(inst, {
     status: "connected",
     connected_at: new Date().toISOString(),
     backfill_summary: backfillSummary,
   });
-  if (!fresh) {
-    console.log(`  [5/5] ${GREEN}✓${RESET} Existing memory projected into the graph`);
+  if (!fresh && syncEnabled) {
+    console.log(`  [5/5] ${GREEN}✓${RESET} Existing memory synced with hosted services`);
     for (const line of backfillSummaryLines(backfillSummary)) {
       console.log(`        ${DIM}${line}${RESET}`);
     }
@@ -2295,43 +2420,23 @@ function settingsDump(inst) {
 // explicit verbs — one source of truth, no JS reimplementation.
 
 const RUNTIME_MVP_VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-runtime-mvp\.(0|[1-9]\d*)$/;
-const RUNTIME_MVP_REGISTRY_URL = process.env.EGREGORE_RUNTIME_MVP_REGISTRY_URL
-  || "https://registry.npmjs.org/create-egregore/runtime-mvp";
+const RUNTIME_STABLE_VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 
-function upgradeScriptPath(inst) {
-  return path.join(inst.path, "bin", "runtime-upgrade.sh");
+function isRuntimeCandidate(version) {
+  return typeof version === "string"
+    && (RUNTIME_MVP_VERSION_RE.test(version) || RUNTIME_STABLE_VERSION_RE.test(version))
+    && parseReleaseVersion(version).parts.every(Number.isSafeInteger)
+    && compareReleaseVersions(version, "0.21.0-runtime-mvp.0") >= 0;
 }
 
-// After the Runtime cutover, a Connected instance's hosted link no longer
-// serves retrieval — saying "hosted graph active" would misstate what the
-// connection is for. Mirror the shell gate (bin/search.sh): stable org
-// identity composed with the main installation path keys the activation
-// record; only a real record flips the wording.
-function upgradedGraphRetrievalOff(instPath) {
-  try {
-    const cfg = JSON.parse(fs.readFileSync(path.join(instPath, "egregore.json"), "utf-8"));
-    const orgId = String(cfg.org_id || "").trim();
-    if (!orgId) return false;
-    let main = instPath;
-    const gitFile = path.join(instPath, ".git");
-    if (fs.existsSync(gitFile) && fs.statSync(gitFile).isFile()) {
-      const m = /^gitdir: (.*)$/m.exec(fs.readFileSync(gitFile, "utf-8"));
-      if (m && m[1].includes("/.git/worktrees/")) main = m[1].split("/.git/worktrees/")[0];
-    }
-    main = fs.realpathSync(main);
-    const key = crypto.createHash("sha256").update(`${orgId}|${main}`).digest("hex").slice(0, 16);
-    const base = process.env.EGREGORE_UPGRADE_ROOT || path.join(os.homedir(), ".egregore", "runtime", "upgrade");
-    const record = JSON.parse(fs.readFileSync(path.join(base, key, "active.json"), "utf-8"));
-    return record.retrieval === "runtime-qmd";
-  } catch {
-    return false;
-  }
+function upgradeScriptPath(inst) {
+  return path.join(inst.path, "bin", "runtime-upgrade.sh");
 }
 
-function connectedModeSuffix(instPath) {
-  return upgradedGraphRetrievalOff(instPath)
-    ? "· hosted services · graph retrieval off"
-    : "· hosted graph active";
+// Connected describes the hosted service relationship. Retrieval health is
+// shown separately in Runtime settings, including on fresh installations.
+function connectedModeSuffix() {
+  return "· hosted services";
 }
 
 // An instance that predates the bridge (0.20.1 and earlier) is still
@@ -2357,8 +2462,23 @@ function packagedUpgradeScript() {
 
 function resolveUpgradeBridge(inst) {
   const own = upgradeScriptPath(inst);
-  if (fs.existsSync(own)) return { script: own, env: {} };
   const packaged = packagedUpgradeScript();
+  if (fs.existsSync(own)) {
+    // Older MVP engines reject stable versions. Probe without identity setup
+    // or state writes; use the launcher's engine for the entire transaction
+    // when the installed engine predates this protocol advertisement.
+    if (!packaged || !fs.existsSync(packaged)) return { script: own, env: { EGREGORE_INSTANCE_ROOT: inst.path } };
+    try {
+      const probe = spawnSync("bash", upgradeBridgeArgs({ script: own }, ["capabilities"]), {
+        cwd: inst.path, encoding: "utf-8", timeout: 2000,
+        env: { ...process.env, EGREGORE_INSTANCE_ROOT: inst.path },
+      });
+      const capability = probe.status === 0 ? JSON.parse(probe.stdout) : null;
+      if (capability?.upgrade_protocol === 1 && capability.stable_candidates === true) {
+        return { script: own, env: { EGREGORE_INSTANCE_ROOT: inst.path } };
+      }
+    } catch { /* Missing/legacy capability response uses the packaged engine. */ }
+  }
   if (packaged && fs.existsSync(packaged)) {
     return { script: packaged, env: { EGREGORE_INSTANCE_ROOT: inst.path } };
   }
@@ -2449,8 +2569,8 @@ function formatPrivacyLines(snapshot) {
   lines.push(`Personal read roots: ${personalRoots.length ? personalRoots.join(", ") : "none"}`);
   lines.push(
     snapshot.graph_retrieval === "not-used-by-this-runtime"
-      ? "Graph retrieval: not used by this Runtime"
-      : "Graph retrieval: legacy configuration",
+      ? "Search: local to this Egregore"
+      : "Search: check Runtime status",
   );
   return lines;
 }
@@ -2569,14 +2689,20 @@ function retrievalHealthAsync(inst, cb) {
   } catch { cb(null); }
 }
 
-// Exact candidate resolution: the runtime-mvp dist-tag only, validated
-// against the prerelease scheme — never latest, never a retired scheme.
-// EGREGORE_RUNTIME_MVP_CANDIDATE is the offline/test seam.
-async function fetchRuntimeMvpCandidate() {
-  const seeded = process.env.EGREGORE_RUNTIME_MVP_CANDIDATE;
-  if (seeded !== undefined) return RUNTIME_MVP_VERSION_RE.test(seeded) ? seeded : null;
+// Stable is the default even for an existing MVP installation. Testing the
+// prerelease channel requires an explicit selection; dist-tags never reach init.
+async function fetchRuntimeCandidate() {
+  const channel = process.env.EGREGORE_RUNTIME_CHANNEL || "stable";
+  if (!["stable", "runtime-mvp"].includes(channel)) return null;
+  const mvp = channel === "runtime-mvp";
+  const accepts = (version) => isRuntimeCandidate(version)
+    && (mvp ? RUNTIME_MVP_VERSION_RE : RUNTIME_STABLE_VERSION_RE).test(version);
+  const seeded = process.env[mvp ? "EGREGORE_RUNTIME_MVP_CANDIDATE" : "EGREGORE_RUNTIME_STABLE_CANDIDATE"];
+  if (seeded !== undefined) return accepts(seeded) ? seeded : null;
+  const registryUrl = process.env[mvp ? "EGREGORE_RUNTIME_MVP_REGISTRY_URL" : "EGREGORE_RUNTIME_STABLE_REGISTRY_URL"]
+    || `https://registry.npmjs.org/create-egregore/${mvp ? "runtime-mvp" : "latest"}`;
   try {
-    const url = new URL(RUNTIME_MVP_REGISTRY_URL);
+    const url = new URL(registryUrl);
     const result = await requestJson({
       hostname: url.hostname,
       port: url.port || undefined,
@@ -2588,7 +2714,7 @@ async function fetchRuntimeMvpCandidate() {
       headers: { Accept: "application/json" },
     });
     const version = result.status === 200 && result.data && result.data.version;
-    return version && RUNTIME_MVP_VERSION_RE.test(version) ? version : null;
+    return accepts(version) ? version : null;
   } catch {
     return null;
   }
@@ -2599,6 +2725,7 @@ async function fetchRuntimeMvpCandidate() {
 // staged must not dead-end into a CLI instruction referencing a tarball the
 // user does not have — the registry has it, digest-verified.
 function fetchCandidateTarball(version, cb) {
+  if (!isRuntimeCandidate(version)) return cb(new Error("an exact supported Runtime version is required"));
   const metaUrl = new URL(`https://registry.npmjs.org/${PUBLIC_NPX_PACKAGE}/${version}`);
   requestJson({
     hostname: metaUrl.hostname,
@@ -2609,7 +2736,12 @@ function fetchCandidateTarball(version, cb) {
     headers: { Accept: "application/json" },
   }).then((meta) => {
     const dist = meta && meta.status === 200 && meta.data && meta.data.dist;
-    if (!dist || !dist.tarball) return cb(new Error(`candidate ${version} not found on the registry`));
+    if (!dist || !dist.tarball || meta.data.name !== PUBLIC_NPX_PACKAGE || meta.data.version !== version) {
+      return cb(new Error(`candidate ${version} not found on the registry`));
+    }
+    if (typeof dist.integrity !== "string" || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(dist.integrity)) {
+      return cb(new Error("candidate sha512 integrity is missing or invalid — refusing to stage"));
+    }
     const dest = path.join(os.tmpdir(), `egregore-candidate-${version}.tgz`);
     const fetchTarball = (url, redirects) => {
       https.get(url, { headers: { "User-Agent": "egregore-launcher" } }, (res) => {
@@ -2660,7 +2792,7 @@ const UPGRADE_STATUS_LABEL = {
 // transaction state, not the condition the user needs to see.
 function runtimeUpdateAvailable(st, candidate) {
   return st?.status === "active"
-    && RUNTIME_MVP_VERSION_RE.test(candidate || "")
+    && isRuntimeCandidate(candidate)
     && compareReleaseVersions(candidate, st.active_version) > 0;
 }
 
@@ -2716,14 +2848,14 @@ function formatUpgradeLines(inst, st, { candidate = "", retrieval = null } = {})
   // 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 && (["failed", "interrupted", "unavailable"].includes(d.status))) {
-    lines.push(`Attention: ${d.failure.message}`);
+    lines.push(`Attention: ${adapterErrorText(d.failure.message)}`);
   }
   if (d.rollback_version && d.status !== "none") lines.push(`Rollback target: ${d.rollback_version}`);
   const ts = d.team_sync;
   if (ts && ts.label) lines.push(`Team memory: ${ts.label}`);
   if (d.status === "active") {
     lines.push("Organizational retrieval: Runtime/QMD");
-    lines.push("Graph retrieval: not used by this Runtime version");
+    lines.push("Search: local to this Egregore");
   } else if (d.status !== "none") {
     lines.push("Previous Runtime remains active until activation.");
   }
@@ -2752,10 +2884,10 @@ function formatUpgradeLines(inst, st, { candidate = "", retrieval = null } = {})
           parts.push(`${upgradeElapsed(d)} elapsed`);
           detail = ` — ${parts.join(" · ")}`;
         } else if (stage.state === "done" && stage.detail) {
-          detail = ` — ${stage.detail}`;
+          detail = ` — ${adapterErrorText(stage.detail)}`;
         }
       } else if (stage.state === "failed" && stage.detail) {
-        detail = ` — ${stage.detail}`;
+        detail = ` — ${adapterErrorText(stage.detail)}`;
       }
       lines.push(`  ${glyph} ${stage.label}${detail}`);
     }
@@ -2775,7 +2907,7 @@ const UPGRADE_CHANGES = [
   "Runtime version",
   "Organizational retrieval moves to Runtime/QMD",
   "Keyword and meaning search become owned by this Egregore",
-  "Graph retrieval stops after activation (kept only for rollback)",
+  "Previous search is replaced after activation (kept for rollback)",
   "Cross-session continuity uses the new Runtime",
   "Readiness and synchronization become visible here in Settings",
 ];
@@ -2802,22 +2934,28 @@ async function cmdSettingsRuntime(inst, args) {
   if (action === "init") {
     const version = (args[1] || "").trim();
     const tarball = (args[2] || "").trim();
-    if (!RUNTIME_MVP_VERSION_RE.test(version)) {
-      process.stderr.write("Runtime update needs an exact candidate like 0.21.0-runtime-mvp.1.\n");
+    if (!isRuntimeCandidate(version)) {
+      process.stderr.write("Runtime update needs an exact version like 0.21.0 or 0.21.0-runtime-mvp.1.\n");
       process.exitCode = 1; return;
     }
     if (!tarball || !fs.existsSync(tarball)) {
       process.stderr.write("Runtime update installs actual packaged bytes: egregore settings <slug> runtime init <version> <candidate.tgz>\n");
       process.exitCode = 1; return;
     }
+    const current = upgradeStatus(inst);
+    if (!current || current.status === "unavailable" || (current.active_version && (!parseReleaseVersion(current.active_version)
+        || compareReleaseVersions(version, current.active_version) <= 0))) {
+      process.stderr.write("Runtime update requires a version newer than the verified active version; use rollback for recovery.\n");
+      process.exitCode = 1; return;
+    }
     const r = runUpgrade(inst, ["init", "--candidate", version, "--tarball", path.resolve(tarball)]);
-    if (r.status !== 0) { process.stderr.write(r.stderr || "could not stage the candidate\n"); process.exitCode = r.status; return; }
+    if (r.status !== 0) { process.stderr.write(adapterErrorText(r.stderr || "could not stage the candidate\n")); process.exitCode = r.status; return; }
     emit(upgradeStatus(inst) || null);
     return;
   }
   if (["prepare", "activate", "cancel", "rollback"].includes(action)) {
     const r = runUpgrade(inst, [action]);
-    if (r.status !== 0) { process.stderr.write(r.stderr || `${action} failed\n`); process.exitCode = r.status; return; }
+    if (r.status !== 0) { process.stderr.write(adapterErrorText(r.stderr || `${action} failed\n`)); process.exitCode = r.status; return; }
     const st = upgradeStatus(inst);
     emit(st);
     if (action === "activate" && st && st.status === "active") {
@@ -3925,17 +4063,17 @@ async function browser(args = {}) {
               const r = runUpgrade(inst, ["prepare"]);
               state.upgradeNotice = r.status === 0
                 ? `${DIM}Preparing in the background — safe to leave this screen.${RESET}`
-                : `${YELLOW}${(r.stderr || "prepare failed").trim().split("\n")[0]}${RESET}`;
+                : `${YELLOW}${adapterErrorText(r.stderr || "prepare failed").trim().split("\n")[0]}${RESET}`;
             } else if (mode === "confirm-activate") {
               const r = runUpgrade(inst, ["activate"]);
               state.upgradeNotice = r.status === 0
                 ? `${GREEN}Update complete. Start a session to work on the new Runtime.${RESET}`
-                : `${YELLOW}${(r.stderr || "activation refused — a gate has not passed").trim().split("\n")[0]}${RESET}`;
+                : `${YELLOW}${adapterErrorText(r.stderr || "activation refused — a gate has not passed").trim().split("\n")[0]}${RESET}`;
             } else if (mode === "confirm-rollback") {
               const r = runUpgrade(inst, ["rollback"]);
               state.upgradeNotice = r.status === 0
                 ? `${DIM}Rolled back. The previous Runtime is active again.${RESET}`
-                : `${YELLOW}${(r.stderr || "rollback failed").trim().split("\n")[0]}${RESET}`;
+                : `${YELLOW}${adapterErrorText(r.stderr || "rollback failed").trim().split("\n")[0]}${RESET}`;
             } else if (mode === "confirm-cancel") {
               runUpgrade(inst, ["cancel"]);
               state.upgradeNotice = `${DIM}Preparation cancelled. The current Runtime was never touched.${RESET}`;
@@ -3958,8 +4096,10 @@ async function browser(args = {}) {
             && state.upgradeData.candidate_version;
           if (!staged) {
             const candidate = state.upgradeCandidate;
-            if (!candidate) {
-              state.upgradeNotice = `${DIM}No published candidate found. Stage one manually: egregore settings ${state.upgradeInst.slug} runtime init --candidate <version> --tarball <candidate.tgz>${RESET}`;
+            if (!candidate || (state.upgradeData?.active_version
+                && (!parseReleaseVersion(state.upgradeData.active_version)
+                  || compareReleaseVersions(candidate, state.upgradeData.active_version) <= 0))) {
+              state.upgradeNotice = `${DIM}No published candidate found. Stage one manually: egregore settings ${state.upgradeInst.slug} runtime init <version> <candidate.tgz>${RESET}`;
               render(); return;
             }
             if (state.upgradeFetching) { render(); return; }
@@ -3976,7 +4116,7 @@ async function browser(args = {}) {
               }
               const r = runUpgrade(inst, ["init", "--candidate", candidate, "--tarball", tgz]);
               if (r === null || r.status !== 0) {
-                const detail = ((r && (r.stderr || r.stdout)) || "staging failed").trim().split("\n")[0];
+                const detail = adapterErrorText((r && (r.stderr || r.stdout)) || "staging failed").trim().split("\n")[0];
                 state.upgradeNotice = `${YELLOW}${detail}${RESET}`;
                 render(); return;
               }
@@ -4276,7 +4416,7 @@ async function browser(args = {}) {
             });
             refreshUpgrade();
             if (!state.upgradeCandidate) {
-              fetchRuntimeMvpCandidate().then((v) => {
+              fetchRuntimeCandidate().then((v) => {
                 state.upgradeCandidate = v || "";
                 if (state.upgradeInst) render();
               });
@@ -4570,7 +4710,7 @@ async function browser(args = {}) {
           if (state.settingsInst === pick && !state.upgradeInst) render();
         });
         if (!state.upgradeCandidate) {
-          fetchRuntimeMvpCandidate().then((v) => {
+          fetchRuntimeCandidate().then((v) => {
             state.upgradeCandidate = v || "";
             if (state.settingsInst === pick && !state.upgradeInst) render();
           });