create-egregore 0.20.2 → 0.21.0-runtime-mvp.1

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.20.2
+// egregore-launcher-version: 0.21.0-runtime-mvp.1
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -14,6 +14,8 @@
 //   egregore ls | list          list instances (non-interactive table)
 //   egregore use <slug>         set the default for bare `egregore`
 //   egregore connect [slug]     activate Connected for an existing instance
+//   egregore telemetry <verb>   manage local telemetry for an instance
+//   egregore runtime <verb>     inspect or synchronize Local retrieval
 //   egregore /invite <user>     invite a GitHub user to an instance
 //   egregore settings [slug]    hosting on/off, managed repos, admins (s in browser)
 //   egregore prune [--dry-run]  remove entries whose path is gone
@@ -33,7 +35,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.21.0-runtime-mvp.1";
 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");
@@ -360,6 +362,52 @@ function initialCursorForCwd(registry, cwd = safeCwd()) {
   return 0;
 }
 
+function currentWorktreeInstance(registry, cwd = safeCwd()) {
+  // Development checkouts are intentionally not persisted as separate
+  // Egregore instances, but launching from one must preserve the exact code
+  // under test. A linked worktree has a `.git` file; a safe standalone clone
+  // has a `.git` directory. Walk upward and borrow only display/runtime
+  // preferences from a registered parent when one exists.
+  let candidate = path.resolve(cwd);
+  const filesystemRoot = path.parse(candidate).root;
+  while (candidate !== filesystemRoot) {
+    const marker = path.join(candidate, ".git");
+    const config = path.join(candidate, "egregore.json");
+    try {
+      const gitMarker = fs.statSync(marker);
+      if ((gitMarker.isFile() || gitMarker.isDirectory()) && fs.statSync(config).isFile()) {
+        const exact = registry.find(
+          (entry) => entry?.path && path.resolve(entry.path) === candidate,
+        );
+        if (exact) return null;
+        const parent = registry
+          .filter((entry) => entry?.path && pathContains(entry.path, candidate))
+          .sort((a, b) => path.resolve(b.path).length - path.resolve(a.path).length)[0];
+        if (parent) return { ...parent, path: candidate, transientWorktree: true };
+        const local = JSON.parse(fs.readFileSync(config, "utf-8"));
+        return {
+          slug: local.slug || path.basename(candidate),
+          name: local.org_name || local.slug || path.basename(candidate),
+          path: candidate,
+          transientWorktree: true,
+        };
+      }
+    } catch {
+      // Keep walking: normal subdirectories do not contain both markers.
+    }
+    candidate = path.dirname(candidate);
+  }
+  return null;
+}
+
+function isLinkedGitWorktree(directory) {
+  try {
+    return fs.statSync(path.join(directory, ".git")).isFile();
+  } catch {
+    return false;
+  }
+}
+
 // ── launch ──────────────────────────────────────────────────────────
 
 function normalizeRuntime(raw) {
@@ -676,7 +724,7 @@ async function renderCodexStartupCard(egregoreDir) {
       }, "Preparing Codex startup");
       let output = result.stdout || "";
       if (isConnectedPath(egregoreDir) && !output.includes("◆ CONNECTED")) {
-        const connectedLine = "  ◆ CONNECTED · hosted graph active\n";
+        const connectedLine = `  ◆ CONNECTED ${connectedModeSuffix(egregoreDir)}\n`;
         output = output.includes("\nWhat are you working on?")
           ? output.replace("\nWhat are you working on?", `\n${connectedLine}\nWhat are you working on?`)
           : `${output}${output.endsWith("\n") || !output ? "" : "\n"}${connectedLine}`;
@@ -846,6 +894,9 @@ function installCodexSkills(egregoreDir) {
 }
 
 function claudeLaunchArgs(egregoreDir) {
+  // Claude treats the positional value as the initial user prompt. Egregore
+  // deliberately submits `start` so the opening experience renders without
+  // requiring the user to type first.
   const args = ["start"];
   const memoryLink = path.join(egregoreDir, "memory");
   try {
@@ -863,14 +914,21 @@ function claudeLaunchArgs(egregoreDir) {
   return args;
 }
 
-function runtimeLaunchArgs(runtime, egregoreDir) {
+function runtimeLaunchArgs(runtime, egregoreDir, options = {}) {
   if (runtime === "codex") {
-    return [
+    const args = [
       "--enable", "hooks",
       "--sandbox", "danger-full-access",
       "--ask-for-approval", "never",
       "--cd", egregoreDir,
     ];
+    // Codex treats each linked worktree as a separate hook-trust root, while
+    // project hooks may still be discovered from the registered primary
+    // checkout. The Egregore launcher validates the Runtime surface above;
+    // trust that bounded hook set for this transient invocation so Observe
+    // and the branch guard are not silently skipped in the worktree.
+    if (options.bypassHookTrust) args.push("--dangerously-bypass-hook-trust");
+    return args;
   }
   if (runtime === "pi") return piTrustArgs();
   if (runtime === "prime") return primeTrustArgs();
@@ -894,6 +952,12 @@ async function launch(inst, runtimeOverride) {
   }
   const runtime = await chooseRuntimeForLaunch(inst, runtimeOverride);
   if (!runtime) return;
+  if (runtime === "claude-code" && isLinkedGitWorktree(inst.path)) {
+    die(
+      "Claude Code automatically removes linked Git worktrees when its worktree session ends.\n" +
+      "  Launch Claude from a standalone clone of this branch instead; Codex, Pi, and Prime may use this worktree directly.",
+    );
+  }
   if (runtime === "claude-code") {
     normalizeClaudeDenyRules(inst.path);
     ensureClaudeModeStatusLine(inst.path);
@@ -949,9 +1013,12 @@ async function launch(inst, runtimeOverride) {
   const launchEnv = {
     ...process.env,
     EGREGORE_RUNTIME: runtime,
+    EGREGORE_TRANSIENT_CHECKOUT: inst.transientWorktree ? "1" : process.env.EGREGORE_TRANSIENT_CHECKOUT,
     EGREGORE_CODEX_TRUSTED: runtime === "codex" ? "1" : process.env.EGREGORE_CODEX_TRUSTED,
   };
-  const child = spawn(binary, launchArgs || runtimeLaunchArgs(runtime, inst.path), {
+  const child = spawn(binary, launchArgs || runtimeLaunchArgs(runtime, inst.path, {
+    bypassHookTrust: runtime === "codex" && Boolean(inst.transientWorktree),
+  }), {
     cwd: inst.path,
     stdio: "inherit",
     env: launchEnv,
@@ -1080,8 +1147,11 @@ function cmdHelp() {
     `    ${CYAN}egregore ls${RESET} ${DIM}| list${RESET}            list installed instances`,
     `    ${CYAN}egregore use${RESET} ${DIM}<slug>${RESET}          set the default for bare ${BOLD}egregore${RESET}`,
     `    ${CYAN}egregore connect${RESET} ${DIM}[slug]${RESET}     activate Connected for an existing instance`,
+    `    ${CYAN}egregore telemetry${RESET} ${DIM}<verb>${RESET}   status, inspect, enable, disable, export, or share`,
+    `    ${CYAN}egregore runtime${RESET} ${DIM}<verb>${RESET}     status, sync, start, or stop Local retrieval`,
     `    ${CYAN}egregore /invite${RESET} ${DIM}<user> [slug]${RESET} invite a GitHub user`,
     `    ${CYAN}egregore settings${RESET} ${DIM}[slug]${RESET}      hosting on/off, repos, admins`,
+    `    ${CYAN}egregore settings${RESET} ${DIM}<slug> runtime${RESET}  Runtime update: review, prepare, activate, roll back`,
     `    ${CYAN}egregore prune${RESET} ${DIM}[--dry-run]${RESET}   remove entries with missing paths`,
     `    ${CYAN}egregore rm${RESET} ${DIM}<slug|path>${RESET}     remove a specific entry`,
     ``,
@@ -2116,6 +2186,79 @@ async function cmdInvite(args) {
   return inviteToInstance(inst, username);
 }
 
+function cmdTelemetry(args) {
+  const registry = readRegistry();
+  if (registry.length === 0) die("no egregores installed yet.\n  run: npx -y create-egregore@latest");
+
+  const forwarded = args.slice();
+  let instanceQuery = "";
+  const marker = forwarded.indexOf("--instance");
+  if (marker !== -1) {
+    instanceQuery = forwarded[marker + 1] || "";
+    if (!instanceQuery) die("usage: egregore telemetry <verb> [args] --instance <slug>");
+    forwarded.splice(marker, 2);
+  }
+  if (forwarded.length === 0) forwarded.push("status");
+
+  const inst = resolveInviteInstance(registry, instanceQuery);
+  if (!inst) {
+    die("multiple egregores installed; choose one:\n  egregore telemetry <verb> --instance <slug>\n  run: egregore ls");
+  }
+  const script = path.join(inst.path, "bin", "telemetry.sh");
+  if (!fs.existsSync(script)) {
+    die("bin/telemetry.sh not found — update this Egregore before managing telemetry");
+  }
+  const result = spawnSync("bash", [script, ...forwarded], {
+    cwd: inst.path,
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (result.error) die(`telemetry command failed: ${result.error.message}`);
+  process.exitCode = result.status ?? 1;
+}
+
+function cmdRuntime(args) {
+  const registry = readRegistry();
+  if (registry.length === 0) die("no egregores installed yet.\n  run: npx -y create-egregore@latest");
+
+  const forwarded = args.slice();
+  let instanceQuery = "";
+  const marker = forwarded.indexOf("--instance");
+  if (marker !== -1) {
+    instanceQuery = forwarded[marker + 1] || "";
+    if (!instanceQuery) die("usage: egregore runtime <status|sync|start|stop> --instance <slug>");
+    forwarded.splice(marker, 2);
+  }
+  const verb = forwarded[0] || "status";
+  if (!["status", "sync", "start", "stop", "update"].includes(verb) || forwarded.length > 1) {
+    die("usage: egregore runtime <status|sync|start|stop> [--instance <slug>]");
+  }
+  const inst = resolveInviteInstance(registry, instanceQuery);
+  if (!inst) {
+    die("multiple egregores installed; choose one:\n  egregore runtime status --instance <slug>\n  run: egregore ls");
+  }
+
+  let script;
+  let scriptArgs;
+  if (verb === "sync" || verb === "update") {
+    script = path.join(inst.path, "bin", "agent.sh");
+    scriptArgs = ["sync"];
+  } else {
+    script = path.join(inst.path, "bin", "search.sh");
+    scriptArgs = [verb];
+  }
+  if (!fs.existsSync(script)) {
+    die("Local Runtime controls are missing — update this Egregore before managing retrieval");
+  }
+  const result = spawnSync("bash", [script, ...scriptArgs], {
+    cwd: inst.path,
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (result.error) die(`runtime command failed: ${result.error.message}`);
+  process.exitCode = result.status ?? 1;
+}
+
 // ── settings ───────────────────────────────────────────────────────
 //
 // The launcher stays a THIN caller: every config change shells out to the
@@ -2145,17 +2288,440 @@ function settingsDump(inst) {
   try { return JSON.parse(r.stdout); } catch { return null; }
 }
 
+// ── runtime upgrade (per-instance, settings-first) ──────────────────
+// The launcher stays a thin caller: the transactional engine, gates,
+// activation, and rollback live in the instance's Python Runtime behind
+// bin/runtime-upgrade.sh. The launcher renders that state and forwards
+// 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";
+
+function upgradeScriptPath(inst) {
+  return path.join(inst.path, "bin", "runtime-upgrade.sh");
+}
+
+// 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 connectedModeSuffix(instPath) {
+  return upgradedGraphRetrievalOff(instPath)
+    ? "· hosted services · graph retrieval off"
+    : "· hosted graph active";
+}
+
+// An instance that predates the bridge (0.20.1 and earlier) is still
+// upgradable: the installed launcher package carries the candidate's own
+// engine, so the bootstrap never depends on a git sync delivering it.
+// EGREGORE_RUNTIME_PACKAGED_BRIDGE is the test seam ("" disables).
+function packagedUpgradeScript() {
+  const seeded = process.env.EGREGORE_RUNTIME_PACKAGED_BRIDGE;
+  if (seeded !== undefined) return seeded || null;
+  const script = path.join(__dirname, "..", "runtime", "claude", "bin", "runtime-upgrade.sh");
+  return fs.existsSync(script) ? script : null;
+}
+
+function resolveUpgradeBridge(inst) {
+  const own = upgradeScriptPath(inst);
+  if (fs.existsSync(own)) return { script: own, env: {} };
+  const packaged = packagedUpgradeScript();
+  if (packaged && fs.existsSync(packaged)) {
+    return { script: packaged, env: { EGREGORE_INSTANCE_ROOT: inst.path } };
+  }
+  return null;
+}
+
+function runUpgrade(inst, args, timeout = 60000) {
+  const bridge = resolveUpgradeBridge(inst);
+  if (!bridge) {
+    return { status: 127, stdout: "", stderr: "Runtime update is unavailable — no upgrade engine in this egregore or the installed launcher package.\n", missing: true };
+  }
+  try {
+    return spawnSync("bash", [bridge.script, ...args], { cwd: inst.path, stdio: "pipe", encoding: "utf-8", timeout, env: { ...process.env, ...bridge.env } });
+  } catch (err) {
+    return { status: 1, stdout: "", stderr: String(err) };
+  }
+}
+
+// ── privacy & access + telemetry (Settings sections) ───────────────
+// Thin callers over deterministic adapters: bin/settings.sh privacy and
+// bin/telemetry.sh. The Runtime authorization backend supplies identity,
+// membership, and capability truth; the launcher only renders it. No model
+// round-trip, no raw JSON shown, no secrets or internal paths.
+
+function runTelemetry(inst, args) {
+  const script = path.join(inst.path, "bin", "telemetry.sh");
+  if (!fs.existsSync(script)) return { status: 127, stdout: "", stderr: "telemetry adapter unavailable\n" };
+  try {
+    return spawnSync("bash", [script, ...args], { cwd: inst.path, stdio: "pipe", encoding: "utf-8", timeout: 15000 });
+  } catch (err) {
+    return { status: 1, stdout: "", stderr: String(err) };
+  }
+}
+
+function privacySnapshot(inst) {
+  const r = runSettings(inst, ["privacy"]);
+  if (!r || r.status !== 0 || !r.stdout) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+function telemetrySnapshot(inst) {
+  const r = runTelemetry(inst, ["status", "--json"]);
+  if (!r || r.status !== 0 || !r.stdout) return null;
+  try { return JSON.parse(r.stdout); } catch { return null; }
+}
+
+function formatPrivacyLines(snapshot) {
+  if (!snapshot) return ["Privacy & access state is unavailable for this egregore."];
+  const a = snapshot.access || {};
+  const b = snapshot.boundary || {};
+  const lines = [];
+  if (a.status !== "ok") {
+    lines.push("Access needs attention — identity could not be resolved.");
+    return lines;
+  }
+  lines.push(`Member: ${a.display_name || "unknown"}`);
+  lines.push(`Organization: ${a.org_name || "unknown"} — membership ${a.membership_status || "unknown"}`);
+  lines.push(`Details: actor ${String(a.actor_id || "").slice(0, 18)}…`);
+  lines.push("");
+  const caps = a.capabilities || {};
+  const capLine = ["read", "create", "update", "publish", "notify", "org_settings"]
+    .map((k) => `${k.replace("_", " ")} ${caps[k] ? "yes" : "no"}`)
+    .join(" · ");
+  lines.push(`Authorized capabilities: ${capLine}`);
+  lines.push("For publish and notify, yes means you may request the action —");
+  lines.push("every delivery still needs its own explicit approval.");
+  lines.push("Custom roles: not enabled in this MVP.");
+  lines.push(a.admin ? "Admin content: visible (you are an organization admin)" : "Admin content: hidden on Egregore surfaces");
+  lines.push("");
+  lines.push("Shared memory: available to authorized organization members");
+  lines.push("Per-document restrictions: not enabled (raw repository access is organization-wide)");
+  lines.push("Admin-marked content: hidden in Egregore surfaces from non-admin members");
+  lines.push("External publication of admin-marked content: blocked unless an authorized admin separately confirms");
+  lines.push("Publications require approval; notifications require separate exact approval.");
+  lines.push("");
+  lines.push(`Boundary posture: ${b.posture || "standard"}${b.locked ? " · organization policy locked" : ""}`);
+  lines.push(`Other Egregore instances: ${snapshot.isolation ? snapshot.isolation.foreign_instances_denied : 0} isolated (hard, no consent path)`);
+  const orgRoots = (b.org_read_roots || []).length;
+  const personalRoots = b.personal_read_roots || [];
+  lines.push(`Organization read roots: ${orgRoots} (managed by your organization)`);
+  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",
+  );
+  return lines;
+}
+
+function telemetryEvents(inst, n = 50) {
+  const r = runTelemetry(inst, ["inspect", String(n), "--json"]);
+  if (!r || r.status !== 0 || !r.stdout) return [];
+  try {
+    const events = JSON.parse(r.stdout);
+    return Array.isArray(events) ? events : [];
+  } catch { return []; }
+}
+
+function formatEventRow(event) {
+  const at = String(event.occurred_at || "").replace("T", " ").slice(0, 16) || "????-?? ??:??";
+  const metrics = event.metrics || {};
+  const what = metrics.command || metrics.subcommand || metrics.action || "";
+  const extras = [];
+  if (metrics.duration_ms != null) extras.push(`${metrics.duration_ms}ms`);
+  if (metrics.model) extras.push(String(metrics.model));
+  if (metrics.result) extras.push(String(metrics.result));
+  return `${at}  ${pad(String(event.event_type || "event"), 12)} ${pad(String(what), 16)} ${extras.join(" · ")}`;
+}
+
+function listSubdirectories(dir, showHidden) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && (showHidden || !entry.name.startsWith(".")))
+      .map((entry) => entry.name)
+      .sort();
+  } catch { return []; }
+}
+
+function formatTelemetryLines(status) {
+  if (!status) return ["Telemetry state is unavailable for this egregore."];
+  const lines = [];
+  lines.push(`Telemetry: ${status.enabled ? "On" : "Off"}${status.reason ? ` (${status.reason})` : ""}`);
+  lines.push(`Notice shown: ${status.notice_shown ? "yes" : "not yet"}`);
+  lines.push(
+    status.buffered_events > 0
+      ? `Local events waiting: ${status.buffered_events}`
+      : "No buffered events",
+  );
+  if (status.last_event_at) lines.push(`Last event: ${status.last_event_at}`);
+  lines.push("Events are held in a local buffer and never shared automatically.");
+  lines.push("Collected: command names, timings, counts, model tiers — documented metadata only.");
+  lines.push("Never collected: file contents, code, prompts, document excerpts,");
+  lines.push("environment values, credentials, message bodies, personal memory content.");
+  lines.push("Turning telemetry on or off is a personal setting for this member only.");
+  return lines;
+}
+
+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; }
+}
+
+function upgradeStatusAsync(inst, cb) {
+  const bridge = resolveUpgradeBridge(inst);
+  if (!bridge) return cb(null);
+  let buf = "";
+  try {
+    const child = spawn("bash", [bridge.script, "status"], { cwd: inst.path, stdio: ["ignore", "pipe", "ignore"], 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); }
+}
+
+// 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;
+  try {
+    const url = new URL(RUNTIME_MVP_REGISTRY_URL);
+    const result = await requestJson({
+      hostname: url.hostname,
+      port: url.port || undefined,
+      path: `${url.pathname}${url.search}`,
+      method: "GET",
+      protocol: url.protocol,
+      timeoutMs: 1500,
+      unref: true,
+      headers: { Accept: "application/json" },
+    });
+    const version = result.status === 200 && result.data && result.data.version;
+    return version && RUNTIME_MVP_VERSION_RE.test(version) ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+const UPGRADE_STATUS_LABEL = {
+  none: "no update staged",
+  pending: "staged, not started",
+  preparing: "preparing…",
+  interrupted: "interrupted — resume to continue",
+  failed: "needs attention",
+  "ready-to-activate": "ready to activate",
+  active: "active",
+  cancelled: "cancelled",
+  "rolled-back": "rolled back",
+};
+
+function upgradeSummary(st) {
+  if (!st || st.status === "none") return "up to date";
+  if (st.status === "active") return `${st.active_version || "?"} active`;
+  return UPGRADE_STATUS_LABEL[st.status] || st.status;
+}
+
+function upgradeElapsed(st) {
+  const worker = (st && st.worker) || {};
+  const from = worker.started_at || st?.started_at;
+  if (!from) return "";
+  const s = Math.max(0, Math.floor(Date.now() / 1000 - from));
+  return s >= 3600 ? `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m` : s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+}
+
+// Plain-language body shared by the non-interactive `settings <slug> runtime`
+// output and the interactive panel. Returns undecorated strings; callers add
+// color. Never JSON, never internal paths beyond the instance's own root.
+function formatUpgradeLines(inst, st, { candidate = "" } = {}) {
+  const lines = [];
+  const d = st || { status: "none" };
+  lines.push(`Selected Egregore: ${inst.name || inst.slug} (${inst.slug || "?"})`);
+  lines.push(`Location: ${inst.path}`);
+  lines.push("");
+  lines.push(`Runtime: ${d.active_version || "unknown"} active`
+    + (d.candidate_version ? ` → candidate ${d.candidate_version}` : candidate ? ` → candidate ${candidate} available` : ""));
+  lines.push(`Status: ${UPGRADE_STATUS_LABEL[d.status] || d.status}`);
+  if (d.candidate_digest) lines.push(`Package digest: sha256 ${String(d.candidate_digest).slice(0, 16)}…`);
+  if (d.failure && d.failure.message) lines.push(`Attention: ${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");
+  } else if (d.status !== "none") {
+    lines.push("Previous Runtime remains active until activation.");
+  }
+  if (Array.isArray(d.stages) && d.status !== "none" && d.status !== "active") {
+    lines.push("");
+    for (const stage of d.stages) {
+      const glyph = stage.state === "done" ? "✓" : stage.state === "running" ? "◦" : stage.state === "failed" ? "✗" : "·";
+      let detail = "";
+      if (stage.key === "embed" || stage.key === "delta") {
+        const p = d.progress || {};
+        if (stage.state === "running") {
+          const parts = [];
+          if (p.vectors) parts.push(`${p.vectors} chunks embedded`);
+          if (p.pending) parts.push(`${p.pending} pending`);
+          parts.push(`${upgradeElapsed(d)} elapsed`);
+          detail = ` — ${parts.join(" · ")}`;
+        } else if (stage.state === "done" && stage.detail) {
+          detail = ` — ${stage.detail}`;
+        }
+      } else if (stage.state === "failed" && stage.detail) {
+        detail = ` — ${stage.detail}`;
+      }
+      lines.push(`  ${glyph} ${stage.label}${detail}`);
+    }
+  }
+  return lines;
+}
+
+const UPGRADE_STAYS = [
+  "Your team memory and organizational history",
+  "Your identity and organization membership",
+  "Permissions and authorization",
+  "Projects, handoffs, and artifacts",
+  "Connection configuration",
+  "The current Runtime, until the new one is fully ready",
+];
+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)",
+  "Cross-session continuity uses the new Runtime",
+  "Readiness and synchronization become visible here in Settings",
+];
+
+async function cmdSettingsRuntime(inst, args) {
+  const action = args[0] || "status";
+  const fetchFlag = args.includes("--fetch");
+  const emit = (st, extra = {}) => {
+    for (const line of formatUpgradeLines(inst, st, extra)) process.stdout.write(line + "\n");
+  };
+  if (action === "status" || action === "review") {
+    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 (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`);
+      process.stdout.write("What changes:\n");
+      for (const c of UPGRADE_CHANGES) process.stdout.write(`  · ${c}\n`);
+    }
+    return;
+  }
+  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");
+      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 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; }
+    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; }
+    const st = upgradeStatus(inst);
+    emit(st);
+    if (action === "activate" && st && st.status === "active") {
+      process.stdout.write("\nUpdate complete. Start a session to work on the new Runtime.\n");
+    }
+    return;
+  }
+  process.stderr.write("usage: egregore settings <slug> runtime [status|review|init <version>|prepare|activate|cancel|rollback]\n");
+  process.exitCode = 2;
+}
+
 async function cmdSettings(args) {
   const registry = readRegistry();
   if (registry.length === 0) die("no egregores installed yet.\n  run: npx -y create-egregore@latest");
-  const DOMAINS = new Set(["hosting", "workflow", "repo", "admin", "people", "dump"]);
+  const DOMAINS = new Set(["hosting", "workflow", "repo", "admin", "people", "dump", "runtime", "privacy", "telemetry", "boundary"]);
   let rest = args.slice();
   let slug = "";
   if (rest.length && !DOMAINS.has(rest[0])) { slug = rest[0]; rest = rest.slice(1); }
   const inst = resolveInviteInstance(registry, slug);
   if (!inst) {
-    die(`multiple egregores installed; choose one:\n  egregore settings <slug> [hosting|workflow|repo|admin|people]\n  run: egregore ls`);
+    die(`multiple egregores installed; choose one:\n  egregore settings <slug> [runtime|hosting|workflow|repo|admin|people|privacy|telemetry]\n  run: egregore ls`);
+  }
+  // Runtime update is Runtime-owned state, not org config — it routes to the
+  // upgrade bridge instead of bin/settings.sh.
+  if (rest[0] === "runtime") return cmdSettingsRuntime(inst, rest.slice(1));
+  // Privacy & access: rendered plain-language snapshot backed by the Runtime
+  // authorization decision — never raw JSON, secrets, or internal paths.
+  if (rest[0] === "privacy") {
+    for (const line of formatPrivacyLines(privacySnapshot(inst))) console.log(line);
+    return;
+  }
+  // Telemetry: personal, opt-out, content-free. Mutations require the exact
+  // --confirm because a non-interactive verb has no y/N checkpoint.
+  if (rest[0] === "telemetry") {
+    const verb = rest[1] || "status";
+    if (verb === "status") {
+      for (const line of formatTelemetryLines(telemetrySnapshot(inst))) console.log(line);
+      return;
+    }
+    if (verb === "inspect") {
+      const n = /^\d+$/.test(rest[2] || "") ? Number(rest[2]) : 20;
+      const events = telemetryEvents(inst, n);
+      if (!events.length) { console.log("No buffered events."); return; }
+      for (const event of events) console.log(formatEventRow(event));
+      return;
+    }
+    if (verb === "on" || verb === "off" || verb === "clear") {
+      if (!rest.includes("--confirm")) {
+        const what = verb === "clear"
+          ? `delete ${(telemetrySnapshot(inst) || {}).buffered_events || 0} locally buffered event(s); nothing else is removed`
+          : `turn telemetry ${verb} for this member only`;
+        process.stderr.write(`this will ${what}.\nre-run with --confirm to proceed: egregore settings ${inst.slug} telemetry ${verb} --confirm\n`);
+        process.exitCode = 1;
+        return;
+      }
+      const r = runTelemetry(inst, [verb]);
+      if (r.stdout) process.stdout.write(r.stdout);
+      if (r.stderr) process.stderr.write(r.stderr);
+      process.exitCode = r.status || 0;
+      return;
+    }
+    die("usage: egregore settings <slug> telemetry [status|inspect [n]|on|off|clear] [--confirm]");
   }
+
   // Interactive editing lives in the launcher (press `s`). With no verb, print
   // the snapshot; otherwise forward straight to the deterministic verb.
   if (rest.length === 0) rest = ["dump"];
@@ -2373,7 +2939,7 @@ function renderRuntimePanel({ inst, cursor, width, height }) {
     boxLine(`${DIM}${inst.path}${RESET}`, innerWidth, margin),
     boxLine(
       isConnectedInstance(inst)
-        ? `${CYAN}◆ CONNECTED${RESET} ${DIM}· hosted graph active${RESET}`
+        ? `${CYAN}◆ CONNECTED${RESET} ${DIM}${connectedModeSuffix(inst.path)}${RESET}`
         : `${DIM}◇ LOCAL · Markdown + Git${RESET}`,
       innerWidth,
       margin,
@@ -2413,7 +2979,67 @@ const SETTINGS_DOMAIN_LABEL = { repo: "Managed repos", admin: "Admins", people:
 const SETTINGS_DOMAIN_NOUN = { repo: "repo name", admin: "github handle", people: "github handle" };
 
 // Same box geometry as renderRuntimePanel so pressing `s` keeps the frame put.
-function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCursor, mode, input, notice, width }) {
+// Runtime-update panel: renders the durable upgrade state from the Python
+// engine. Same geometry as the settings panel; plain-language body from
+// formatUpgradeLines with launcher glyph decoration only.
+function renderUpgradePanel({ inst, data, candidate, mode, notice, width }) {
+  const outerWidth = Math.min(Math.max(50, width - 2), 126);
+  const innerWidth = Math.max(48, outerWidth - 2);
+  const margin = " ".repeat(Math.max(0, Math.floor((width - outerWidth) / 2)));
+  const label = " runtime update ";
+  const lines = [
+    `${margin}${DIM}┌${"─".repeat(2)}${label}${"─".repeat(Math.max(0, innerWidth - label.length - 2))}┐${RESET}`,
+    emptyBoxLine(innerWidth, margin),
+  ];
+  const body = data === undefined
+    ? ["Checking this egregore's Runtime state…"]
+    : data === null
+      ? ["Runtime update state is unavailable for this egregore."]
+      : formatUpgradeLines(inst, data, { candidate });
+  for (const raw of body) {
+    let line = raw;
+    if (/^  ✓ /.test(raw)) line = `  ${GREEN}✓${RESET} ${raw.slice(4)}`;
+    else if (/^  ◦ /.test(raw)) line = `  ${CYAN}◦${RESET} ${raw.slice(4)}`;
+    else if (/^  ✗ /.test(raw)) line = `  ${RED}✗${RESET} ${raw.slice(4)}`;
+    else if (/^  · /.test(raw)) line = `  ${DIM}·${RESET} ${DIM}${raw.slice(4)}${RESET}`;
+    else if (/^(Location|Rollback target):/.test(raw)) line = `${DIM}${raw}${RESET}`;
+    lines.push(boxLine(line, innerWidth, margin));
+  }
+  const status = data && data.status;
+  if (mode === "confirm-prepare") {
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(boxLine(`${BOLD}What stays${RESET}`, innerWidth, margin));
+    for (const s of UPGRADE_STAYS) lines.push(boxLine(`  · ${s}`, innerWidth, margin));
+    lines.push(boxLine(`${BOLD}What changes${RESET}`, innerWidth, margin));
+    for (const c of UPGRADE_CHANGES) lines.push(boxLine(`  · ${c}`, innerWidth, margin));
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(boxLine(`${YELLOW}Prepare the update for ${BOLD}${inst.slug}${RESET}${YELLOW} at this location only?${RESET} ${DIM}y / N${RESET}`, innerWidth, margin));
+  } else if (mode === "confirm-activate") {
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(boxLine(`${YELLOW}Activate the new Runtime for ${BOLD}${inst.slug}${RESET}${YELLOW}?${RESET} ${DIM}y / N${RESET}`, innerWidth, margin));
+  } else if (mode === "confirm-rollback") {
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(boxLine(`${YELLOW}Roll ${BOLD}${inst.slug}${RESET}${YELLOW} back to ${data?.rollback_version || "the previous Runtime"}?${RESET} ${DIM}y / N${RESET}`, innerWidth, margin));
+  } else if (mode === "confirm-cancel") {
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(boxLine(`${YELLOW}Cancel preparation? The current Runtime stays untouched.${RESET} ${DIM}y / N${RESET}`, innerWidth, margin));
+  } else {
+    lines.push(emptyBoxLine(innerWidth, margin));
+    if (notice) lines.push(boxLine(notice, innerWidth, margin));
+    const keys = [];
+    if (!status || status === "none" || ["pending", "failed", "interrupted", "cancelled", "rolled-back"].includes(status)) keys.push(`${BOLD}p${RESET}${DIM} prepare${RESET}`);
+    if (status === "ready-to-activate") keys.push(`${BOLD}a${RESET}${DIM} activate${RESET}`);
+    if (status === "preparing") keys.push(`${BOLD}c${RESET}${DIM} cancel${RESET}`);
+    if (status === "active") keys.push(`${BOLD}r${RESET}${DIM} roll back${RESET}`);
+    keys.push(`${DIM}← back · q quit${RESET}`);
+    lines.push(boxLine(keys.join(`${DIM} · ${RESET}`), innerWidth, margin));
+  }
+  lines.push(emptyBoxLine(innerWidth, margin));
+  lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+  return lines;
+}
+
+function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCursor, mode, input, notice, width, upgrade }) {
   const title = inst.slug || inst.name || path.basename(inst.path);
   const outerWidth = Math.min(Math.max(50, width - 2), 126);
   const innerWidth = Math.max(48, outerWidth - 2);
@@ -2428,6 +3054,114 @@ function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCurs
     emptyBoxLine(innerWidth, margin),
   ];
 
+  if (view === "privacy" || view === "telemetry") {
+    lines.push(boxLine(`${BOLD}${view === "privacy" ? "Privacy & access" : "Telemetry"}${RESET}`, innerWidth, margin));
+    lines.push(emptyBoxLine(innerWidth, margin));
+    if (mode === "shareinfo") {
+      const shareLines = (data && data.shareLines) || ["share proposal unavailable"];
+      lines.push(boxLine(`${BOLD}Share proposal${RESET} ${DIM}(nothing has been sent)${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      for (const line of shareLines.slice(0, 16)) {
+        lines.push(boxLine(`${line.includes("--confirm") ? "" : DIM}${line}${RESET}`, innerWidth, margin));
+      }
+      lines.push(emptyBoxLine(innerWidth, margin));
+      lines.push(boxLine(`${DIM}Sharing completes only by running the confirm command above in a terminal. ← back${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+      return lines;
+    }
+    if (mode === "events") {
+      const events = (data && data.telemetryEvents) || [];
+      lines.push(boxLine(`${BOLD}Local events${RESET} ${DIM}(newest last · nothing here ever uploads by itself)${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (!events.length) {
+        lines.push(boxLine(`${DIM}(no buffered events)${RESET}`, innerWidth, margin));
+      } else {
+        const cursorAt = Math.min(listCursor || 0, events.length - 1);
+        const windowSize = 12;
+        const start = Math.max(0, Math.min(cursorAt - Math.floor(windowSize / 2), events.length - windowSize));
+        events.slice(start, start + windowSize).forEach((event, i) => {
+          const sel = start + i === cursorAt;
+          lines.push(boxLine(`${sel ? `${CYAN}❯${RESET} ` : "  "}${sel ? "" : DIM}${formatEventRow(event)}${RESET}`, innerWidth, margin));
+        });
+        if (events.length > windowSize) lines.push(boxLine(`${DIM}${cursorAt + 1}/${events.length}${RESET}`, innerWidth, margin));
+      }
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (notice) lines.push(boxLine(notice, innerWidth, margin));
+      lines.push(boxLine(`${DIM}↑↓ scroll · ${RESET}${BOLD}e${RESET}${DIM} export to file · ${RESET}${BOLD}s${RESET}${DIM} share (two-step consent) · ← back${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+      return lines;
+    }
+    if (mode === "pickdir") {
+      const pick = (data && data.dirPick) || { dir: os.homedir(), entries: [], cursor: 0, hidden: false };
+      lines.push(boxLine(`${BOLD}Choose a directory to allow reading${RESET}`, innerWidth, margin));
+      lines.push(boxLine(`${DIM}${pick.dir}${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (!pick.entries.length) {
+        lines.push(boxLine(`${DIM}(no subdirectories${pick.hidden ? "" : " — press . to show hidden"})${RESET}`, innerWidth, margin));
+      } else {
+        const windowSize = 10;
+        const start = Math.max(0, Math.min(pick.cursor - Math.floor(windowSize / 2), pick.entries.length - windowSize));
+        pick.entries.slice(start, start + windowSize).forEach((name, i) => {
+          const sel = start + i === pick.cursor;
+          lines.push(boxLine(`${sel ? `${CYAN}❯${RESET} ` : "  "}${sel ? BOLD : DIM}${name}/${RESET}`, innerWidth, margin));
+        });
+      }
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (notice) lines.push(boxLine(notice, innerWidth, margin));
+      lines.push(boxLine(`${DIM}↑↓ nav · → enter descend · ← up · ${RESET}${BOLD}space${RESET}${DIM} allow this directory · . hidden · esc cancel${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+      return lines;
+    }
+    if (mode === "pickroot") {
+      const roots = (data && data.privacySnapshot && data.privacySnapshot.boundary && data.privacySnapshot.boundary.personal_read_roots) || [];
+      lines.push(boxLine(`${BOLD}Remove a personal read root${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (!roots.length) {
+        lines.push(boxLine(`${DIM}(no personal read roots)${RESET}`, innerWidth, margin));
+      } else {
+        roots.forEach((root, i) => {
+          const sel = i === (listCursor || 0);
+          lines.push(boxLine(`${sel ? `${CYAN}❯${RESET} ` : "  "}${sel ? BOLD : DIM}${root}${RESET}`, innerWidth, margin));
+        });
+      }
+      lines.push(emptyBoxLine(innerWidth, margin));
+      if (notice) lines.push(boxLine(notice, innerWidth, margin));
+      lines.push(boxLine(`${DIM}↑↓ nav · enter remove · esc cancel${RESET}`, innerWidth, margin));
+      lines.push(emptyBoxLine(innerWidth, margin));
+      lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+      return lines;
+    }
+    const body = view === "privacy" ? formatPrivacyLines(data && data.privacySnapshot) : formatTelemetryLines(data && data.telemetrySnapshot);
+    for (const line of body) {
+      lines.push(line === "" ? emptyBoxLine(innerWidth, margin) : boxLine(`${line.startsWith("Access needs") || line.startsWith("Telemetry needs") ? YELLOW : ""}${line}${RESET}`, innerWidth, margin));
+    }
+    lines.push(emptyBoxLine(innerWidth, margin));
+    if (mode === "confirm" && input) {
+      lines.push(boxLine(`${YELLOW}${input}${RESET}`, innerWidth, margin));
+    } else if (mode === "input") {
+      lines.push(boxLine(`${BOLD}directory:${RESET} ${input}${DIM}▌${RESET}`, innerWidth, margin));
+    }
+    if (notice) lines.push(boxLine(notice, innerWidth, margin));
+    if (view === "privacy") {
+      const locked = !!(data && data.privacySnapshot && data.privacySnapshot.boundary && data.privacySnapshot.boundary.locked);
+      lines.push(boxLine(
+        locked
+          ? `${DIM}Boundary policy is managed by your organization. ← back · q quit${RESET}`
+          : `${DIM}${RESET}${BOLD}a${RESET}${DIM} add personal read root · ${RESET}${BOLD}r${RESET}${DIM} remove · ← back · q quit${RESET}`,
+        innerWidth, margin,
+      ));
+    } else {
+      const on = !!(data && data.telemetrySnapshot && data.telemetrySnapshot.enabled);
+      lines.push(boxLine(`${DIM}${RESET}${BOLD}i${RESET}${DIM} view events · ${RESET}${BOLD}t${RESET}${DIM} turn ${on ? "off" : "on"} · ${RESET}${BOLD}x${RESET}${DIM} clear local buffer · ← back · q quit${RESET}`, innerWidth, margin));
+    }
+    lines.push(emptyBoxLine(innerWidth, margin));
+    lines.push(`${margin}${DIM}└${"─".repeat(innerWidth)}┘${RESET}`);
+    return lines;
+  }
+
   if (view === "list") {
     lines.push(boxLine(`${BOLD}${SETTINGS_DOMAIN_LABEL[domain] || domain}${RESET}`, innerWidth, margin));
     lines.push(emptyBoxLine(innerWidth, margin));
@@ -2450,7 +3184,19 @@ function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCurs
       lines.push(boxLine(`${DIM}↑↓ nav · ${RESET}${BOLD}a${RESET}${DIM} add · ${RESET}${BOLD}d${RESET}${DIM} delete · ← back · q quit${RESET}`, innerWidth, margin));
     }
   } else {
+    const upgradeValue = upgrade === undefined
+      ? `${DIM}checking…${RESET}`
+      : upgrade === null
+        ? `${DIM}unavailable${RESET}`
+        : upgrade.status === "ready-to-activate"
+          ? `${GREEN}${upgradeSummary(upgrade)}${RESET}`
+          : upgrade.status === "failed" || upgrade.status === "interrupted"
+            ? `${YELLOW}${upgradeSummary(upgrade)}${RESET}`
+            : `${DIM}${upgradeSummary(upgrade)}${RESET}`;
     const rows = [
+      { name: "Runtime update", value: upgradeValue },
+      { name: "Privacy & access", value: `${DIM}identity · boundary · consent${RESET}` },
+      { name: "Telemetry", value: `${DIM}personal · opt-out${RESET}` },
       { name: "Hosted Artifacts", value: (d.hosting !== false) ? `${GREEN}ON${RESET}` : `${YELLOW}OFF${RESET}` },
       {
         name: "Git workflow",
@@ -2472,7 +3218,7 @@ function renderSettingsPanel({ inst, data, cursor, view, domain, items, listCurs
     });
     lines.push(emptyBoxLine(innerWidth, margin));
     if (notice) lines.push(boxLine(notice, innerWidth, margin));
-    lines.push(boxLine(`${DIM}↑↓ nav · ${RESET}${BOLD}enter${RESET}${DIM} ${cursor < 2 ? "toggle" : "open"} · ← back · q quit${RESET}`, innerWidth, margin));
+    lines.push(boxLine(`${DIM}↑↓ nav · ${RESET}${BOLD}enter${RESET}${DIM} ${cursor === 3 || cursor === 4 ? "toggle" : "open"} · ← back · q quit${RESET}`, innerWidth, margin));
   }
 
   lines.push(emptyBoxLine(innerWidth, margin));
@@ -2597,6 +3343,22 @@ async function browser(args = {}) {
       return;
     }
 
+    if (state.upgradeInst) {
+      const upgradeLines = renderUpgradePanel({
+        inst: state.upgradeInst,
+        data: state.upgradeData,
+        candidate: state.upgradeCandidate,
+        mode: state.upgradeMode,
+        notice: state.upgradeNotice,
+        width: w,
+      });
+      for (const line of upgradeLines) out.push(line + ANSI.clearLine + "\n");
+      const upgradeRemaining = Math.max(0, h - upgradeLines.length - 1);
+      for (let i = 0; i < upgradeRemaining; i++) out.push(ANSI.clearLine + "\n");
+      process.stdout.write(out.join(""));
+      return;
+    }
+
     if (state.settingsInst) {
       const settingsLines = renderSettingsPanel({
         inst: state.settingsInst,
@@ -2610,6 +3372,7 @@ async function browser(args = {}) {
         input: state.settingsInput,
         notice: state.settingsNotice,
         width: w,
+        upgrade: state.settingsUpgrade,
       });
       for (const line of settingsLines) out.push(line + ANSI.clearLine + "\n");
       const remainingRows = Math.max(0, h - settingsLines.length - 1);
@@ -2736,7 +3499,7 @@ async function browser(args = {}) {
         : `  ${label("path")} ${truncate(selected.path, valW)}`);
       if (pv.org) previewLines.push(`  ${label("org")} ${truncate(`${pv.org} ${DIM}(${pv.githubOrg || "?"})${RESET}`, valW)}`);
       previewLines.push(pv.connected
-        ? `  ${label("mode")} ${CYAN}◆ CONNECTED${RESET} ${DIM}· hosted graph active${RESET}`
+        ? `  ${label("mode")} ${CYAN}◆ CONNECTED${RESET} ${DIM}${connectedModeSuffix(selected.path)}${RESET}`
         : `  ${label("mode")} ${DIM}◇ LOCAL · Markdown + Git${RESET}`);
       if (pv.branch) previewLines.push(`  ${label("branch")} ${BOLD}${pv.branch}${RESET}`);
       if (pv.lastCommit) previewLines.push(`  ${label("last")} ${DIM}${truncate(pv.lastCommit, valW)}${RESET}`);
@@ -2837,9 +3600,27 @@ async function browser(args = {}) {
   const onResize = () => render(); // render() itself no-ops once done is set
   let onSigint;
   let onSigterm;
+  const stopUpgradePoll = () => {
+    if (state.upgradePoll) { clearInterval(state.upgradePoll); state.upgradePoll = null; }
+  };
+  const refreshUpgrade = () => {
+    if (!state.upgradeInst) return;
+    upgradeStatusAsync(state.upgradeInst, (st) => {
+      if (!state.upgradeInst) return;
+      state.upgradeData = st;
+      if (st && st.status === "preparing") {
+        if (!state.upgradePoll) state.upgradePoll = setInterval(refreshUpgrade, 2500);
+      } else {
+        stopUpgradePoll();
+      }
+      render();
+    });
+  };
+
   const cleanup = () => {
     if (done) return;
     done = true;
+    stopUpgradePoll();
     process.stdin.setRawMode(false);
     process.stdin.pause();
     process.stdin.removeAllListeners("keypress");
@@ -2893,11 +3674,195 @@ async function browser(args = {}) {
       if (!key) return;
       if (isMouseEvent(chunk, key)) return; // drop scroll-wheel / mouse escape sequences
 
+      if (state.upgradeInst) {
+        if (key.ctrl && key.name === "c") { cleanup(); process.exit(130); }
+        if (key.name === "q") { cleanup(); resolve(); return; }
+        if (state.upgradeMode && state.upgradeMode.startsWith("confirm-")) {
+          const mode = state.upgradeMode;
+          state.upgradeMode = "view";
+          if (chunk === "y" || chunk === "Y") {
+            const inst = state.upgradeInst;
+            if (mode === "confirm-prepare") {
+              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}`;
+            } 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}`;
+            } 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}`;
+            } else if (mode === "confirm-cancel") {
+              runUpgrade(inst, ["cancel"]);
+              state.upgradeNotice = `${DIM}Preparation cancelled. The current Runtime was never touched.${RESET}`;
+            }
+            refreshUpgrade();
+          }
+          render(); return;
+        }
+        if (key.name === "escape" || key.name === "left") {
+          stopUpgradePoll();
+          state.settingsUpgrade = state.upgradeData;
+          state.upgradeInst = null; state.upgradeNotice = "";
+          render(); return;
+        }
+        const status = state.upgradeData && state.upgradeData.status;
+        if (chunk === "p" && (!status || ["none", "pending", "failed", "interrupted", "cancelled", "rolled-back"].includes(status))) {
+          const staged = state.upgradeData
+            && !["none", "cancelled", "rolled-back"].includes(status)
+            && state.upgradeData.candidate_version;
+          if (!staged) {
+            state.upgradeNotice = `${DIM}Stage a candidate package first: egregore settings ${state.upgradeInst.slug} runtime init <version> <candidate.tgz>${RESET}`;
+            render(); return;
+          }
+          state.upgradeMode = "confirm-prepare"; render(); return;
+        }
+        if (chunk === "a" && status === "ready-to-activate") { state.upgradeMode = "confirm-activate"; render(); return; }
+        if (chunk === "c" && status === "preparing") { state.upgradeMode = "confirm-cancel"; render(); return; }
+        if (chunk === "r" && status === "active") { state.upgradeMode = "confirm-rollback"; render(); return; }
+        return;
+      }
+
       if (state.settingsInst) {
         const S = state;
         if (key.ctrl && key.name === "c") { cleanup(); process.exit(130); }
         if (key.name === "q") { cleanup(); resolve(); return; }
 
+        if (S.settingsView === "privacy" || S.settingsView === "telemetry") {
+          const backToMenu = () => {
+            S.settingsView = "menu"; S.settingsMode = "browse"; S.settingsInput = ""; S.settingsNotice = ""; render();
+          };
+          const refreshPanel = () => {
+            if (S.settingsView === "privacy") S.settingsData = { ...(S.settingsData || {}), privacySnapshot: privacySnapshot(S.settingsInst) };
+            else S.settingsData = { ...(S.settingsData || {}), telemetrySnapshot: telemetrySnapshot(S.settingsInst) };
+          };
+          if (S.settingsMode === "events") {
+            const events = (S.settingsData && S.settingsData.telemetryEvents) || [];
+            if (key.name === "escape" || key.name === "left") { S.settingsMode = "browse"; S.settingsListCursor = 0; S.settingsNotice = ""; render(); return; }
+            if (key.name === "up" || key.name === "k") { S.settingsListCursor = Math.max(0, (S.settingsListCursor || 0) - 1); render(); return; }
+            if (key.name === "down" || key.name === "j") { S.settingsListCursor = Math.min(Math.max(0, events.length - 1), (S.settingsListCursor || 0) + 1); render(); return; }
+            if (chunk === "e") {
+              const stamp = new Date().toISOString().slice(0, 10);
+              S.settingsPendingDir = path.join(os.homedir(), "Desktop", `egregore-telemetry-${S.settingsInst.slug}-${stamp}.jsonl`);
+              S.settingsAction = "tele-export";
+              S.settingsMode = "confirm";
+              S.settingsInput = `Export ${events.length} local event(s) to ${S.settingsPendingDir}? [y/N]`;
+              render(); return;
+            }
+            if (chunk === "s") {
+              const r = runTelemetry(S.settingsInst, ["share"]);
+              const shareLines = ((r && (r.stdout || r.stderr)) || "share preview unavailable").split("\n").filter(Boolean);
+              S.settingsData = { ...(S.settingsData || {}), shareLines };
+              S.settingsMode = "shareinfo"; S.settingsNotice = "";
+              render(); return;
+            }
+            return;
+          }
+          if (S.settingsMode === "shareinfo") {
+            if (key.name === "escape" || key.name === "left") { S.settingsMode = "events"; render(); return; }
+            return;
+          }
+          if (S.settingsMode === "pickdir") {
+            const pick = S.settingsData.dirPick;
+            const reload = () => { pick.entries = listSubdirectories(pick.dir, pick.hidden); pick.cursor = Math.min(pick.cursor, Math.max(0, pick.entries.length - 1)); };
+            if (key.name === "escape") { S.settingsMode = "browse"; S.settingsNotice = ""; render(); return; }
+            if (key.name === "up" || key.name === "k") { pick.cursor = Math.max(0, pick.cursor - 1); render(); return; }
+            if (key.name === "down" || key.name === "j") { pick.cursor = Math.min(Math.max(0, pick.entries.length - 1), pick.cursor + 1); render(); return; }
+            if (key.name === "right" || key.name === "return") {
+              if (pick.entries.length) { pick.dir = path.join(pick.dir, pick.entries[pick.cursor]); pick.cursor = 0; reload(); }
+              render(); return;
+            }
+            if (key.name === "left") {
+              const parent = path.dirname(pick.dir);
+              if (parent !== pick.dir) { pick.dir = parent; pick.cursor = 0; reload(); }
+              render(); return;
+            }
+            if (chunk === ".") { pick.hidden = !pick.hidden; reload(); render(); return; }
+            if (chunk === " ") {
+              S.settingsPendingDir = pick.dir;
+              S.settingsAction = "add";
+              S.settingsMode = "confirm";
+              S.settingsInput = `Allow reading ${pick.dir} for this member? [y/N]`;
+              render(); return;
+            }
+            return;
+          }
+          if (S.settingsMode === "pickroot") {
+            const roots = (S.settingsData.privacySnapshot && S.settingsData.privacySnapshot.boundary && S.settingsData.privacySnapshot.boundary.personal_read_roots) || [];
+            if (key.name === "escape" || key.name === "left") { S.settingsMode = "browse"; S.settingsListCursor = 0; render(); return; }
+            if (key.name === "up" || key.name === "k") { S.settingsListCursor = Math.max(0, (S.settingsListCursor || 0) - 1); render(); return; }
+            if (key.name === "down" || key.name === "j") { S.settingsListCursor = Math.min(Math.max(0, roots.length - 1), (S.settingsListCursor || 0) + 1); render(); return; }
+            if (key.name === "return" && roots.length) {
+              S.settingsPendingDir = roots[Math.min(S.settingsListCursor || 0, roots.length - 1)];
+              S.settingsAction = "remove";
+              S.settingsMode = "confirm";
+              S.settingsInput = `Stop allowing reads of ${S.settingsPendingDir}? [y/N]`;
+              render(); return;
+            }
+            return;
+          }
+          if (S.settingsMode === "confirm") {
+            if (chunk === "y" || chunk === "Y") {
+              let r = null;
+              if (S.settingsAction === "add" || S.settingsAction === "remove") {
+                r = runSettings(S.settingsInst, ["boundary", S.settingsAction, S.settingsPendingDir]);
+              } else if (S.settingsAction === "tele-export") {
+                r = runTelemetry(S.settingsInst, ["export", S.settingsPendingDir]);
+              } else if (S.settingsAction === "tele-on") {
+                r = runTelemetry(S.settingsInst, ["on"]);
+              } else if (S.settingsAction === "tele-off") {
+                r = runTelemetry(S.settingsInst, ["off"]);
+              } else if (S.settingsAction === "tele-clear") {
+                r = runTelemetry(S.settingsInst, ["clear"]);
+              }
+              S.settingsNotice = r && r.status === 0
+                ? `${GREEN}done${RESET}`
+                : `${YELLOW}${((r && (r.stderr || r.stdout)) || "action failed").split("\n")[0]}${RESET}`;
+              S.settingsMode = "browse"; S.settingsInput = ""; S.settingsPendingDir = "";
+              refreshPanel(); render(); return;
+            }
+            S.settingsMode = "browse"; S.settingsInput = ""; S.settingsPendingDir = ""; S.settingsNotice = ""; render(); return;
+          }
+          if (key.name === "escape" || key.name === "left") { backToMenu(); return; }
+          if (S.settingsView === "privacy") {
+            const locked = !!(S.settingsData && S.settingsData.privacySnapshot && S.settingsData.privacySnapshot.boundary && S.settingsData.privacySnapshot.boundary.locked);
+            if (!locked && chunk === "a") {
+              const dir = os.homedir();
+              S.settingsData = { ...(S.settingsData || {}), dirPick: { dir, entries: listSubdirectories(dir, false), cursor: 0, hidden: false } };
+              S.settingsMode = "pickdir"; S.settingsNotice = ""; render(); return;
+            }
+            if (!locked && chunk === "r") {
+              S.settingsMode = "pickroot"; S.settingsListCursor = 0; S.settingsNotice = ""; render(); return;
+            }
+            return;
+          }
+          // telemetry view
+          if (chunk === "i") {
+            S.settingsData = { ...(S.settingsData || {}), telemetryEvents: telemetryEvents(S.settingsInst, 100) };
+            S.settingsMode = "events"; S.settingsListCursor = 0; S.settingsNotice = ""; render(); return;
+          }
+          if (chunk === "t") {
+            const on = !!(S.settingsData && S.settingsData.telemetrySnapshot && S.settingsData.telemetrySnapshot.enabled);
+            S.settingsAction = on ? "tele-off" : "tele-on";
+            S.settingsMode = "confirm";
+            S.settingsInput = `Turn telemetry ${on ? "off" : "on"} for this member only? [y/N]`;
+            render(); return;
+          }
+          if (chunk === "x") {
+            const count = (S.settingsData && S.settingsData.telemetrySnapshot && S.settingsData.telemetrySnapshot.buffered_events) || 0;
+            S.settingsAction = "tele-clear";
+            S.settingsMode = "confirm";
+            S.settingsInput = `Delete ${count} locally buffered telemetry event(s)? Nothing else is removed. [y/N]`;
+            render(); return;
+          }
+          return;
+        }
+
         if (S.settingsView === "list") {
           if (S.settingsMode === "add") {
             if (key.name === "escape") { S.settingsMode = "browse"; S.settingsInput = ""; render(); return; }
@@ -2930,19 +3895,40 @@ async function browser(args = {}) {
 
         // menu view
         if (key.name === "escape" || key.name === "left") { S.settingsInst = null; S.settingsNotice = ""; render(); return; }
-        if (key.name === "up" || key.name === "k") { S.settingsCursor = (S.settingsCursor - 1 + 5) % 5; render(); return; }
-        if (key.name === "down" || key.name === "j") { S.settingsCursor = (S.settingsCursor + 1) % 5; render(); return; }
+        if (key.name === "up" || key.name === "k") { S.settingsCursor = (S.settingsCursor - 1 + 8) % 8; render(); return; }
+        if (key.name === "down" || key.name === "j") { S.settingsCursor = (S.settingsCursor + 1) % 8; render(); return; }
         if (key.name === "return" || chunk === " ") {
           if (S.settingsCursor === 0) {
+            state.upgradeInst = S.settingsInst;
+            state.upgradeData = S.settingsUpgrade;
+            state.upgradeMode = "view";
+            state.upgradeNotice = "";
+            refreshUpgrade();
+            if (!state.upgradeCandidate) {
+              fetchRuntimeMvpCandidate().then((v) => {
+                state.upgradeCandidate = v || "";
+                if (state.upgradeInst) render();
+              });
+            }
+            render();
+          } else if (S.settingsCursor === 1) {
+            S.settingsView = "privacy"; S.settingsMode = "browse"; S.settingsInput = ""; S.settingsNotice = "";
+            S.settingsData = { ...(S.settingsData || {}), privacySnapshot: privacySnapshot(S.settingsInst) };
+            render();
+          } else if (S.settingsCursor === 2) {
+            S.settingsView = "telemetry"; S.settingsMode = "browse"; S.settingsInput = ""; S.settingsNotice = "";
+            S.settingsData = { ...(S.settingsData || {}), telemetrySnapshot: telemetrySnapshot(S.settingsInst) };
+            render();
+          } else if (S.settingsCursor === 3) {
             const on = (S.settingsData && S.settingsData.hosting) !== false;
             settingsRunVerb(["hosting", on ? "off" : "on"]);
             render();
-          } else if (S.settingsCursor === 1) {
+          } else if (S.settingsCursor === 4) {
             const simple = (S.settingsData && S.settingsData.workflow) === "simple";
             settingsRunVerb(["workflow", simple ? "staged" : "simple"]);
             render();
           } else {
-            const domain = S.settingsCursor === 2 ? "repo" : S.settingsCursor === 3 ? "admin" : "people";
+            const domain = S.settingsCursor === 5 ? "repo" : S.settingsCursor === 6 ? "admin" : "people";
             S.settingsView = "list"; S.settingsDomain = domain;
             S.settingsItems = settingsItemsFor(S.settingsData, domain);
             S.settingsListCursor = 0; S.settingsMode = "browse"; S.settingsNotice = "";
@@ -3201,6 +4187,11 @@ async function browser(args = {}) {
         state.settingsData = settingsDump(pick) || { hosting: true, workflow: "staged", base_branch: "develop", repos: [], admins: [], people: [] };
         state.settingsCursor = 0;
         state.settingsView = "menu";
+        state.settingsUpgrade = undefined;
+        upgradeStatusAsync(pick, (st) => {
+          state.settingsUpgrade = st;
+          if (state.settingsInst === pick && !state.upgradeInst) render();
+        });
         state.settingsNotice = "";
         render();
         return;
@@ -3328,6 +4319,8 @@ function main() {
   if (cmd === "ls" || cmd === "list") return cmdLs();
   if (cmd === "use") return cmdUse(args[1]);
   if (cmd === "connect") return cmdConnect(args.slice(1));
+  if (cmd === "telemetry") return cmdTelemetry(args.slice(1));
+  if (cmd === "runtime") return cmdRuntime(args.slice(1));
   if (cmd === "/invite" || cmd === "invite") return cmdInvite(args.slice(1));
   if (cmd === "settings" || cmd === "config") return cmdSettings(args.slice(1));
   if (cmd === "prune") return cmdPruneNonInteractive(args[1] === "--dry-run" || args[1] === "-n");
@@ -3338,6 +4331,8 @@ function main() {
   if (cmd.startsWith("-")) die(`unknown flag: ${cmd}\n  run: egregore help`);
 
   const registry = readRegistry();
+  const worktree = currentWorktreeInstance(registry);
+  if (!cmd && worktree) return launch(worktree, runtimeOverride);
   if (registry.length === 0) {
     if (canPrompt()) return setupNewEgregore(runtimeOverride);
     die("no egregores installed yet.\n  run: npx -y create-egregore@latest");