create-egregore 0.19.11 → 0.19.13

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.7.3
+// egregore-launcher-version: 0.19.13
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -13,6 +13,7 @@
 //   egregore <slug|name>        pick a harness for the matching instance
 //   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 /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
@@ -28,13 +29,25 @@ const path = require("node:path");
 const os = require("node:os");
 const http = require("node:http");
 const https = require("node:https");
+const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.7.3";
+const VERSION = "0.19.13";
 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");
 const PUBLIC_NPX_PACKAGE = "create-egregore";
+const UPDATE_REGISTRY_URL =
+  process.env.EGREGORE_UPDATE_REGISTRY_URL ||
+  `https://registry.npmjs.org/${PUBLIC_NPX_PACKAGE}/latest`;
+const UPDATE_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+const UPDATE_FAILURE_TTL_MS = 30 * 60 * 1000;
+const UPDATE_CHECK_TIMEOUT_MS = 1500;
+const CONNECT_API_URL = (
+  process.env.EGREGORE_CONNECT_API_URL ||
+  "https://egregore-production-55f2.up.railway.app"
+).replace(/\/+$/, "");
 
 const NATIVE_CODEX_SKILLS = [
   "activity",
@@ -864,6 +877,7 @@ function cmdHelp() {
     `    ${CYAN}egregore browse${RESET}              force the full-screen browser`,
     `    ${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 /invite${RESET} ${DIM}<user> [slug]${RESET} invite a GitHub user`,
     `    ${CYAN}egregore settings${RESET} ${DIM}[slug]${RESET}      hosting on/off, repos, admins`,
     `    ${CYAN}egregore prune${RESET} ${DIM}[--dry-run]${RESET}   remove entries with missing paths`,
@@ -874,6 +888,7 @@ function cmdHelp() {
     `    ${DIM}enter${RESET}       choose selected instance`,
     `    ${DIM}/${RESET}           filter (type to narrow; esc to clear)`,
     `    ${DIM}n / +${RESET}       create a new Egregore`,
+    `    ${DIM}c${RESET}           connect selected instance`,
     `    ${DIM}u${RESET}           set selected as default`,
     `    ${DIM}i${RESET}           invite a GitHub user to selected instance`,
     `    ${DIM}s${RESET}           settings (hosting on/off, repos, admins)`,
@@ -968,11 +983,145 @@ function requestJson(options, body) {
       });
     });
     req.on("error", (err) => resolve({ status: 0, data: { message: err.message } }));
+    if (options.unref) {
+      req.on("socket", (socket) => socket.unref());
+    }
+    if (options.timeoutMs) {
+      req.setTimeout(options.timeoutMs, () => req.destroy(new Error("request timed out")));
+    }
     if (payload) req.write(payload);
     req.end();
   });
 }
 
+function parseReleaseVersion(value) {
+  const match = String(value || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    parts: match.slice(1, 4).map(Number),
+    prerelease: match[4] || "",
+  };
+}
+
+function compareReleaseVersions(a, b) {
+  const left = parseReleaseVersion(a);
+  const right = parseReleaseVersion(b);
+  if (!left || !right) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (left.parts[i] !== right.parts[i]) return left.parts[i] > right.parts[i] ? 1 : -1;
+  }
+  if (left.prerelease === right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  return left.prerelease.localeCompare(right.prerelease);
+}
+
+function cliUpdateState(latest) {
+  if (!parseReleaseVersion(latest)) return null;
+  return {
+    current: VERSION,
+    latest,
+    available: compareReleaseVersions(latest, VERSION) > 0,
+  };
+}
+
+function readUpdateCache() {
+  try {
+    const cache = JSON.parse(fs.readFileSync(UPDATE_CACHE_FILE, "utf-8"));
+    if (!cache || !cache.checked_at) return null;
+    const age = Date.now() - new Date(cache.checked_at).getTime();
+    const ttl = cache.latest ? UPDATE_CACHE_TTL_MS : UPDATE_FAILURE_TTL_MS;
+    if (!Number.isFinite(age) || age < 0 || age > ttl) return null;
+    if (!cache.latest) return { current: VERSION, latest: null, available: false };
+    return cliUpdateState(cache.latest);
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCache(latest) {
+  try {
+    fs.mkdirSync(path.dirname(UPDATE_CACHE_FILE), { recursive: true });
+    atomicWrite(
+      UPDATE_CACHE_FILE,
+      JSON.stringify({ checked_at: new Date().toISOString(), latest: latest || null }, null, 2) + "\n",
+      0o600,
+    );
+  } catch {}
+}
+
+async function checkForCliUpdate() {
+  if (process.env.EGREGORE_DISABLE_UPDATE_CHECK === "1") return null;
+  if (process.env.EGREGORE_UPDATE_LATEST_VERSION) {
+    return cliUpdateState(process.env.EGREGORE_UPDATE_LATEST_VERSION);
+  }
+
+  const cached = readUpdateCache();
+  if (cached) return cached;
+
+  try {
+    const url = new URL(UPDATE_REGISTRY_URL);
+    const result = await requestJson({
+      hostname: url.hostname,
+      port: url.port || undefined,
+      path: `${url.pathname}${url.search}`,
+      method: "GET",
+      protocol: url.protocol,
+      timeoutMs: UPDATE_CHECK_TIMEOUT_MS,
+      unref: true,
+      headers: { Accept: "application/json" },
+    });
+    const latest = result.status === 200 && result.data && result.data.version;
+    const update = cliUpdateState(latest);
+    writeUpdateCache(update?.latest || null);
+    return update;
+  } catch {
+    return null;
+  }
+}
+
+function cmdCliUpdate(latest) {
+  if (!parseReleaseVersion(latest)) {
+    console.error(`\n  ${YELLOW}!${RESET} Could not verify the CLI release version.\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  console.log(`  ${BOLD}${CYAN}↑ CLI UPDATE${RESET}`);
+  console.log(`  ${DIM}${VERSION} → ${latest}${RESET}`);
+  console.log("");
+  process.stdout.write(`  [1/2] Installing ${PUBLIC_NPX_PACKAGE}@${latest}…`);
+  const result = spawnSync(
+    "npx",
+    ["-y", `${PUBLIC_NPX_PACKAGE}@${latest}`, "--refresh-launcher"],
+    { encoding: "utf-8", stdio: ["inherit", "pipe", "pipe"], env: { ...process.env } },
+  );
+  if (result.status !== 0) {
+    console.log(`\r  [1/2] ${YELLOW}!${RESET} Install failed`);
+    const detail = String(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;
+    return;
+  }
+  console.log(`\r  [1/2] ${GREEN}✓${RESET} CLI ${latest} installed`);
+
+  if (process.env.EGREGORE_UPDATE_NO_RELAUNCH === "1") {
+    console.log(`  [2/2] ${GREEN}✓${RESET} Ready for the next launch\n`);
+    return;
+  }
+
+  console.log(`  [2/2] ${GREEN}✓${RESET} Reopening Egregore\n`);
+  const relaunched = spawnSync(process.execPath, [process.argv[1], "browse"], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+  if (relaunched.error) {
+    console.error(`  ${YELLOW}!${RESET} Updated successfully. Run ${BOLD}egregore${RESET} to reopen.\n`);
+  }
+}
+
 function githubRequest(token, method, apiPath, body) {
   return requestJson({
     hostname: "api.github.com",
@@ -994,6 +1143,252 @@ function apiRequest(apiUrl, apiKey, apiPath, body) {
   }, body);
 }
 
+function connectedApiRequest(githubToken, method, apiPath, body, headers = {}) {
+  const url = new URL(apiPath, CONNECT_API_URL + "/");
+  return requestJson({
+    hostname: url.hostname,
+    port: url.port || undefined,
+    path: `${url.pathname}${url.search}`,
+    method,
+    protocol: url.protocol,
+    headers: {
+      Authorization: `Bearer ${githubToken}`,
+      ...headers,
+    },
+  }, body);
+}
+
+function openExternalUrl(url) {
+  try {
+    if (process.platform === "darwin") {
+      spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+    } else if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+    } else {
+      spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function atomicWrite(file, content, mode) {
+  const temp = path.join(
+    path.dirname(file),
+    `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`,
+  );
+  fs.writeFileSync(temp, content, { mode });
+  fs.renameSync(temp, file);
+}
+
+function writeJsonFileAtomic(file, value) {
+  atomicWrite(file, JSON.stringify(value, null, 2) + "\n", 0o644);
+}
+
+function writeEnvValueAtomic(file, key, value) {
+  const lines = fs.existsSync(file)
+    ? fs.readFileSync(file, "utf-8").split(/\r?\n/)
+    : [];
+  let replaced = false;
+  const next = lines
+    .filter((line, index) => !(index === lines.length - 1 && line === ""))
+    .map((line) => {
+      if (!line.startsWith(`${key}=`)) return line;
+      replaced = true;
+      return `${key}=${value}`;
+    });
+  if (!replaced) next.push(`${key}=${value}`);
+  atomicWrite(file, next.join("\n") + "\n", 0o600);
+}
+
+function persistConnectState(inst, fields) {
+  const file = path.join(inst.path, ".egregore-state.json");
+  const state = readJsonFile(file);
+  state.connected_activation = {
+    ...(state.connected_activation || {}),
+    ...fields,
+    updated_at: new Date().toISOString(),
+  };
+  writeJsonFileAtomic(file, state);
+}
+
+function connectError(result, fallback) {
+  if (!result) return fallback;
+  const data = result.data || {};
+  return data.detail || data.message || (typeof data === "string" ? data : fallback);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function cmdConnect(args) {
+  const registry = readRegistry();
+  if (registry.length === 0) die("no egregores installed yet.\n  run: npx -y create-egregore@latest");
+  const inst = resolveInviteInstance(registry, args[0] || "");
+  if (!inst) {
+    die("multiple egregores installed; choose one:\n  egregore connect <slug>\n  run: egregore ls");
+  }
+  if (!fs.existsSync(inst.path)) die(`instance path is missing: ${inst.path}`);
+
+  const { cfg, state, env } = configForInstance(inst);
+  const githubToken = env.GITHUB_TOKEN || "";
+  if (!githubToken) {
+    die(`GITHUB_TOKEN is missing for ${inst.slug}.\n  Add it to ${path.join(inst.path, ".env")} and retry.`);
+  }
+  const activation = state.connected_activation || {};
+  if (cfg.mode === "connected" && activation.status === "connected") {
+    console.log(`\n  ${GREEN}✓${RESET} ${BOLD}${inst.slug}${RESET} is already connected.\n`);
+    return;
+  }
+
+  console.log("");
+  console.log(`  ${BOLD}CONNECT${RESET}  ${DIM}${inst.slug}${RESET}`);
+  console.log(`  ${DIM}€500/month · Stripe checkout · existing Markdown and Git stay in place${RESET}`);
+  console.log("");
+
+  let intentId = activation.intent_id || "";
+  let connectUrl = activation.connect_url || "";
+  if (!intentId || !["checkout_pending", "entitled", "backfilling"].includes(activation.status)) {
+    console.log(`  [1/5] ${DIM}Creating connection intent…${RESET}`);
+    const checkout = await connectedApiRequest(
+      githubToken,
+      "POST",
+      "/api/billing/checkout",
+      {
+        org_slug: cfg.slug || inst.slug,
+        plan: "connect",
+        instance_metadata: {
+          launcher_version: VERSION,
+          mode: cfg.mode || "local",
+          repo_name: cfg.repo_name || "",
+          managed_repo_count: Array.isArray(cfg.repos) ? cfg.repos.length : 0,
+        },
+      },
+      { "X-Idempotency-Key": `cli:${inst.slug}:${crypto.randomUUID()}` },
+    );
+    if (checkout.status !== 200) {
+      die(`could not start Connected checkout: ${connectError(checkout, `HTTP ${checkout.status}`)}`);
+    }
+    intentId = checkout.data.connection_intent_id;
+    connectUrl = checkout.data.connect_url;
+    persistConnectState(inst, {
+      intent_id: intentId,
+      checkout_session_id: checkout.data.checkout_session_id,
+      connect_url: connectUrl,
+      status: "checkout_pending",
+    });
+    console.log(`  [1/5] ${GREEN}✓${RESET} Connection intent`);
+  } else {
+    console.log(`  [1/5] ${GREEN}✓${RESET} Resuming connection intent`);
+  }
+
+  if (activation.status !== "backfilling") {
+    if (connectUrl) {
+      const opened = openExternalUrl(connectUrl);
+      const mark = opened ? `${GREEN}✓${RESET}` : `${YELLOW}!${RESET}`;
+      console.log(`  [2/5] ${mark} ${opened ? "Opened" : "Open"} Egregore Connect`);
+      console.log(`        ${CYAN}${connectUrl}${RESET}`);
+    }
+    console.log(`  ${DIM}Complete checkout in the browser. Promotion codes are entered in Stripe.${RESET}`);
+  } else {
+    console.log(`  [2/5] ${GREEN}✓${RESET} Subscription already confirmed`);
+  }
+
+  const pollMs = Math.max(100, Number(process.env.EGREGORE_CONNECT_POLL_INTERVAL_MS || 2000));
+  const timeoutMs = Math.max(pollMs, Number(process.env.EGREGORE_CONNECT_TIMEOUT_MS || 30 * 60 * 1000));
+  const deadline = Date.now() + timeoutMs;
+  let status;
+  while (Date.now() < deadline) {
+    const result = await connectedApiRequest(
+      githubToken,
+      "GET",
+      `/api/billing/connect/${encodeURIComponent(intentId)}`,
+    );
+    if (result.status === 200) {
+      status = result.data;
+      if (
+        status.entitled ||
+        ["entitled", "provisioning", "backfilling", "connected"].includes(status.status)
+      ) break;
+      if (["canceled", "failed"].includes(status.status)) {
+        persistConnectState(inst, { status: status.status });
+        die(`Connected checkout ${status.status}. Your local Egregore was not changed.`);
+      }
+    } else if (result.status !== 0) {
+      die(`could not read Connected status: ${connectError(result, `HTTP ${result.status}`)}`);
+    }
+    await sleep(pollMs);
+  }
+  if (!status || !(status.entitled || ["entitled", "provisioning", "backfilling", "connected"].includes(status.status))) {
+    die("timed out waiting for checkout. Run the same command to resume.");
+  }
+  console.log(`  [3/5] ${GREEN}✓${RESET} Subscription confirmed`);
+  persistConnectState(inst, { status: "entitled" });
+
+  const claim = await connectedApiRequest(
+    githubToken,
+    "POST",
+    `/api/billing/connect/${encodeURIComponent(intentId)}/claim`,
+    {},
+  );
+  if (claim.status !== 200) {
+    die(`could not activate Connected infrastructure: ${connectError(claim, `HTTP ${claim.status}`)}`);
+  }
+
+  const configFile = path.join(inst.path, "egregore.json");
+  const envFile = path.join(inst.path, ".env");
+  const currentConfig = readJsonFile(configFile);
+  writeJsonFileAtomic(configFile, {
+    ...currentConfig,
+    mode: "connected",
+    api_url: claim.data.api_url,
+  });
+  writeEnvValueAtomic(envFile, "EGREGORE_API_KEY", claim.data.api_key);
+  persistConnectState(inst, {
+    status: "backfilling",
+    activation_protocol: claim.data.activation_protocol,
+  });
+  console.log(`  [4/5] ${GREEN}✓${RESET} Connected credential and graph node`);
+
+  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.");
+  }
+  const sync = spawnSync("bash", [syncScript], {
+    cwd: inst.path,
+    encoding: "utf-8",
+    stdio: "pipe",
+    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.`);
+  }
+  let backfillSummary = { replayed: true };
+  try { backfillSummary = JSON.parse((sync.stdout || "").trim()); } catch {}
+
+  const complete = await connectedApiRequest(
+    githubToken,
+    "POST",
+    `/api/billing/connect/${encodeURIComponent(intentId)}/complete`,
+    { backfill_summary: backfillSummary },
+  );
+  if (complete.status !== 200) {
+    die(`graph replay finished, but activation could not be finalized: ${connectError(complete, `HTTP ${complete.status}`)}`);
+  }
+  persistConnectState(inst, {
+    status: "connected",
+    connected_at: new Date().toISOString(),
+    backfill_summary: backfillSummary,
+  });
+  console.log(`  [5/5] ${GREEN}✓${RESET} Existing memory projected into the graph`);
+  console.log("");
+  console.log(`  ${GREEN}✓${RESET} ${BOLD}${inst.slug}${RESET} is connected. Local files remain the source of truth.`);
+  console.log("");
+}
+
 function accessLabel(status) {
   if (status === 201) return `${GREEN}sent${RESET}`;
   if (status === 204) return `${GREEN}already added${RESET}`;
@@ -1435,7 +1830,7 @@ function selectedWorkflowLine(pv, width) {
   return joinShort(available.map(skillToken), Math.max(12, width));
 }
 
-function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, filterMode }) {
+function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, filterMode, cliUpdate }) {
   const outerWidth = Math.min(Math.max(50, width - 2), 126);
   const innerWidth = Math.max(48, outerWidth - 2);
   const bodyWidth = Math.max(8, innerWidth - 2);
@@ -1487,7 +1882,17 @@ function renderHeroPanel({ selected, pv, width, height, countSuffix, filter, fil
   lines.push(mid);
   lines.push(boxLine(`${BOLD}${title}${RESET} ${DIM}· ${org} · ${runtime} · ${countSuffix} · ${filterText}${RESET}`, innerWidth, margin));
   lines.push(boxLine(`${DIM}skills${RESET} ${skillStatus}`, innerWidth, margin));
-  lines.push(emptyBoxLine(innerWidth, margin));
+  if (cliUpdate?.available) {
+    lines.push(boxLine(
+      `${YELLOW}→ CLI update ${cliUpdate.latest} available${RESET} ${DIM}· installed ${cliUpdate.current} · ${RESET}${BOLD}U${RESET}${DIM} install${RESET}`,
+      innerWidth,
+      margin,
+    ));
+  } else {
+    // Reserve the status row so the list never jumps when the async version
+    // check resolves and reveals an available release.
+    lines.push(emptyBoxLine(innerWidth, margin));
+  }
 
   const sigilWidth = Math.max(...EGREGORE_SIGIL.map((line) => line.length));
   const twoColumn = bodyWidth >= 68;
@@ -1684,6 +2089,7 @@ async function browser(args = {}) {
     message: null, // ephemeral info line (e.g. "default set to X")
     messageKind: "info", // "info" | "success" | "warn"
     messageUntil: 0,
+    cliUpdate: null,
   };
 
   const newAction = {
@@ -1787,6 +2193,7 @@ async function browser(args = {}) {
       countSuffix,
       filter: state.filter,
       filterMode: state.filterMode,
+      cliUpdate: state.cliUpdate,
     });
     for (const line of heroLines) out.push(line + ANSI.clearLine + "\n");
     out.push(ANSI.clearLine + "\n");
@@ -1952,8 +2359,8 @@ async function browser(args = {}) {
       footer = band(`● ${stripAnsi(state.message)}`, bg);
     } else {
       footer = blockWidth < 96
-        ? band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("i", "invite")}  ${key("s", "settings")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46)
-        : band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("/", "filter")}  ${key("i", "invite")}  ${key("s", "settings")}  ${key("u", "default")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46);
+        ? band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("c", "connect")}  ${key("i", "invite")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46)
+        : band(`${key("↑↓", "nav")}  ${key("enter", "select")}  ${key("n/+", "new")}  ${key("/", "filter")}  ${key("c", "connect")}  ${key("i", "invite")}  ${key("s", "settings")}  ${key("u", "default")}  ${key("d", "delete")}  ${key("?", "help")}  ${key("q", "quit")}`, 46);
     }
     out.push(M + footer + "\n");
     if (state.showHelp) {
@@ -2310,6 +2717,19 @@ async function browser(args = {}) {
         resolve(setupNewEgregore(args.runtimeOverride));
         return;
       }
+      if (chunk === "c") {
+        const pick = visible()[state.cursor]?.e;
+        if (!pick) return;
+        cleanup();
+        resolve(cmdConnect([pick.slug]));
+        return;
+      }
+      if (chunk === "U" && state.cliUpdate?.available) {
+        const latest = state.cliUpdate.latest;
+        cleanup();
+        resolve(cmdCliUpdate(latest));
+        return;
+      }
       if (chunk === "i") {
         const pick = visible()[state.cursor]?.e;
         if (!pick) return;
@@ -2396,6 +2816,11 @@ async function browser(args = {}) {
     });
 
     render();
+    checkForCliUpdate().then((update) => {
+      if (done || !update) return;
+      state.cliUpdate = update;
+      if (update.available) render();
+    });
   });
 }
 
@@ -2451,6 +2876,7 @@ function main() {
   // Non-interactive subcommands
   if (cmd === "ls" || cmd === "list") return cmdLs();
   if (cmd === "use") return cmdUse(args[1]);
+  if (cmd === "connect") return cmdConnect(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");

package/bin/cli.js

@@ -223,6 +223,8 @@ function parseArgs(argv) {
       // already served as the entry screen — a second alt-screen welcome
       // would otherwise demand a redundant Enter and churn the alt buffer.
       args.noWelcome = true;
+    } else if (argv[i] === "--refresh-launcher") {
+      args.refreshLauncher = true;
     } else if (argv[i] === "--codex") {
       args.runtime = "codex";
     } else if (argv[i] === "--pi") {
@@ -395,6 +397,7 @@ function showHelp() {
   ui.info("  --force           Skip the in-repo detection check");
   ui.info("  --no-autolaunch   Don't launch the harness at the end (for CI)");
   ui.info("  --no-screens      Skip the full-screen welcome/ready bookends");
+  ui.info("  --refresh-launcher Refresh only the Egregore CLI, then exit");
   ui.info("  -h, --help        Show this help");
   ui.info("");
 }
@@ -443,6 +446,21 @@ async function main() {
     }
   }
 
+  if (args.refreshLauncher) {
+    const instances = readLocalInstances();
+    if (instances.length === 0) {
+      ui.error("No installed Egregore instance was found. Run create-egregore without --refresh-launcher.");
+      process.exit(1);
+    }
+    const alias = await installLauncherBinary(instances[0].path, ui);
+    if (!alias || !alias.binaryPath) {
+      ui.error("Could not refresh the Egregore CLI.");
+      process.exit(1);
+    }
+    ui.success(`Egregore CLI is current at ${alias.binaryPath}`);
+    return;
+  }
+
   // Local-first product surface: if the user already has egregores installed
   // and didn't pass an explicit mode flag, refresh the launcher and open the
   // same TUI as bare `egregore`. With no installed instances, make bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.19.11",
+  "version": "0.19.13",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {
@@ -12,7 +12,7 @@
   "scripts": {
     "build:runtime": "node scripts/build-runtime-bundle.mjs && node scripts/build-pi-runtime-bundle.mjs",
     "build:pi-runtime": "node scripts/build-pi-runtime-bundle.mjs",
-    "test": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/context.test.js test/parse-join-target.test.js test/skip-repos.test.js test/onboarding-shortcircuit.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js",
+    "test": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/context.test.js test/parse-join-target.test.js test/skip-repos.test.js test/onboarding-shortcircuit.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js test/launcher-connect.test.js test/launcher-update.test.js",
     "test:e2e": "node --test test/e2e-local.test.js",
     "test:all": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/"
   },

package/runtime/codex/.codex/skills/save/SKILL.md

@@ -43,7 +43,11 @@ esac
 4. Synthesize:
    - a short topic from the work,
    - a clear commit message,
-   - a one-line user-facing scope summary.
+   - a one-line user-facing scope summary,
+   - a PR description following `.claude/context/pr-format.md`:
+     `## What` (1–4 bullets), `## Why` (1–3 sentences), and
+     `## Verification` (how the change was checked — required when the
+     diff touches non-markdown files; be honest if unverified).
 5. If the scope is ambiguous or includes unrelated changes, ask for one compact
    confirmation. Use structured Codex question tooling when available;
    otherwise render:
@@ -58,11 +62,13 @@ Other:
 6. Run the bridge command:
 
 ```bash
-bin/agent.sh save --message "$MESSAGE" --topic "$TOPIC"
+bin/agent.sh save --message "$MESSAGE" --topic "$TOPIC" --pr-body "$PR_BODY"
 ```
 
 The bridge owns the mechanical workflow: sync memory, ensure a task branch,
 commit repo changes, push, and create or reuse a pull request when available.
+Always pass the synthesized `--pr-body` — the bridge only auto-generates a
+skeleton body as a last resort, and the CI `pr-format` check gates every PR.
 
 7. Parse the output and report only useful user information:
    - branch name,

package/runtime/codex/.codex/spec-manifest.json

@@ -41,7 +41,7 @@
     {
       "section": "Config Files",
       "action": "keep",
-      "sourceHash": "81b7bf09901b",
+      "sourceHash": "8d7f1bd0f2d9",
       "note": "Kept verbatim — shell facts, runtime-neutral."
     },
     {
@@ -83,7 +83,7 @@
     {
       "section": "Git Workflow",
       "action": "keep",
-      "sourceHash": "d058d1f8da11",
+      "sourceHash": "49fd4625fa1e",
       "note": "Kept; slash tokens rendered as $skill tokens. Branch diagram unchanged (code fence)."
     },
     {
@@ -119,8 +119,8 @@
     {
       "section": "Environment Isolation",
       "action": "replace",
-      "sourceHash": "ed47e96248bd",
-      "note": "boundary-check is a Claude PreToolUse hook with no .codex equivalent — behavior stated as a standing instruction; AskUserQuestion remediation -> numbered options."
+      "sourceHash": "086e2c1d9019",
+      "note": "boundary-check is a Claude PreToolUse hook with no .codex equivalent — two-tier model stated as a standing instruction; AskUserQuestion remediation -> numbered options, now including the two consent-grant options (session grant -> .egregore-boundary-consent, instance grant -> .egregore-boundary.local.json read[])."
     }
   ]
 }

package/runtime/codex/AGENTS.md

@@ -35,7 +35,8 @@ Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 ```bash
 bin/agent.sh branch --topic "auth review"
-bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review" \
+  --pr-body "$PR_BODY"   # body per .claude/context/pr-format.md (auto-skeleton if omitted)
 bin/agent.sh wrap --from alice --topic "auth review" \
   --summary "Implemented the OAuth callback parser and documented follow-ups." \
   --body "Open threads: review error cases and browser redirects."
@@ -191,7 +192,7 @@ If the startup card output contains `onboarding_needed`, invoke the `$onboarding
 
 ## Config Files
 
-- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. **Never put secrets here.**
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. Optional `boundary { posture, read[], locked }` sets the org's isolation posture (see Environment Isolation). **Never put secrets here.**
 - **`.env`** — gitignored. Personal secrets. Local mode: `GITHUB_TOKEN` only. Connected mode: `GITHUB_TOKEN` + `EGREGORE_API_KEY`. **Never use `source .env`** — use `grep '^KEY=' .env | cut -d'=' -f2-`.
 
 In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API server only — `bin/graph.sh` and `bin/notify.sh` route through the API gateway.
@@ -280,6 +281,10 @@ main ← stable (/release)
 - **Memory repo**: stays on main (separate repo, auto-merge).
 - **Never push directly to main or develop.** All changes flow through PRs.
 
+### Pull request format (all harnesses)
+
+Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
+
 ### Managed Repos
 
 Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `$save` scans all managed repos for uncommitted changes.
@@ -368,19 +373,22 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## Environment Isolation
 
-Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Never modify `~/.egregore/instances.json`** — managed by session-start.sh
-- **Never access another instance's files** — refuse even if asked
-- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
+- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   ```text
   That path is outside this Egregore's boundary. How should we proceed?
-    1. Paste the contents inline
-    2. Move the file into the repo and point me at the new path
-    3. Cancel
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   ```
 
-See DEVELOPMENT.md §3 for boundary details.
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.
 
 <!-- END GENERATED EGREGORE CODEX SPEC -->

package/runtime/codex/bin/agent.sh

@@ -32,7 +32,10 @@ Runtime-neutral commands:
                                    Hybrid recall over shared memory (qmd)
   people                           List known people from memory/people
   branch --topic TEXT              Create or reuse a task branch/worktree
-  save [--message TEXT]            Commit and push current repo + memory changes
+  save [--message TEXT] [--pr-body TEXT|--pr-body-file PATH]
+                                   Commit and push current repo + memory changes;
+                                   PR body follows .claude/context/pr-format.md
+                                   (auto-generated skeleton if not provided)
   wrap --topic T --summary TEXT    Write a session wrap to memory/wraps
   handoff --from A --to B --topic T [--intent action|feedback|fyi]
       [--body TEXT|--body-file PATH] [--no-push] [--no-publish] [--no-notify] [--json]
@@ -332,13 +335,26 @@ ensure_working_branch() {
   echo "$branch"
 }
 
+build_pr_body() {
+  # Compliant fallback PR body (spec: .claude/context/pr-format.md) built
+  # from the commit log + diff when the calling agent supplies none.
+  local topic="${1:-portable save}" commits stat
+  commits="$(git -C "$SCRIPT_DIR" log --pretty='- %s' "origin/develop..HEAD" 2>/dev/null | head -8)"
+  [ -n "$commits" ] || commits="- (commit list unavailable — see the Files tab)"
+  stat="$(git -C "$SCRIPT_DIR" diff --shortstat "origin/develop...HEAD" 2>/dev/null | sed 's/^ *//')"
+  printf '## What\n%s\n\n## Why\nShell-agent session save — topic: %s. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description.\n\n## Verification\nNot verified — auto-generated skeleton; review the diff before merging.%s\n\n🤖 Saved via bin/agent.sh\n' \
+    "$commits" "$topic" "${stat:+ ($stat)}"
+}
+
 cmd_save() {
-  local message="" topic="" no_pr=0 branch pushed="false" committed="false" pr_url="" existing_pr="" pr_number="" non_md="" merged="false"
+  local message="" topic="" no_pr=0 branch pushed="false" committed="false" pr_url="" existing_pr="" pr_number="" non_md="" merged="false" pr_body="" pr_body_file=""
 
   while [ $# -gt 0 ]; do
     case "$1" in
       --message|-m) message="${2:-}"; shift 2 ;;
       --topic) topic="${2:-}"; shift 2 ;;
+      --pr-body) pr_body="${2:-}"; shift 2 ;;
+      --pr-body-file) pr_body_file="${2:-}"; shift 2 ;;
       --no-pr) no_pr=1; shift ;;
       *) die "unknown save option: $1" ;;
     esac
@@ -376,7 +392,11 @@ cmd_save() {
     if [ -n "$existing_pr" ]; then
       pr_url="$existing_pr"
     else
-      pr_url="$(gh pr create --base develop --head "$branch" --title "$message" --body "Saved via bin/agent.sh save." 2>/dev/null || true)"
+      if [ -z "$pr_body" ] && [ -n "$pr_body_file" ] && [ -f "$pr_body_file" ]; then
+        pr_body="$(cat "$pr_body_file")"
+      fi
+      [ -n "$pr_body" ] || pr_body="$(build_pr_body "$topic")"
+      pr_url="$(gh pr create --base develop --head "$branch" --title "$message" --body "$pr_body" 2>/dev/null || true)"
     fi
   fi
 

package/runtime/codex/bin/codex-render-spec.mjs

@@ -79,7 +79,8 @@ Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 \`\`\`bash
 bin/agent.sh branch --topic "auth review"
-bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review" \\
+  --pr-body "$PR_BODY"   # body per .claude/context/pr-format.md (auto-skeleton if omitted)
 bin/agent.sh wrap --from alice --topic "auth review" \\
   --summary "Implemented the OAuth callback parser and documented follow-ups." \\
   --body "Open threads: review error cases and browser redirects."
@@ -251,20 +252,23 @@ Codex has no structured question tool — render each batch as compact numbered
 
 const LOOM_ROUTING_BODY = `Loom routes commands across model tiers on the Claude Code runtime (\`loom/routes.json\` + \`bin/loom.sh\` + a model-pinned executor subagent). Codex has no subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are framework files synced for the Claude runtime.`;
 
-const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Never modify \`~/.egregore/instances.json\`** — managed by session-start.sh
-- **Never access another instance's files** — refuse even if asked
-- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify \`~/.egregore/instances.json\` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (\`~/Downloads\`, \`~/Desktop\`) are readable without consent under the default posture; writes outside the project always need consent. Posture (\`strict | standard | open\`) and extra read roots come from \`egregore.json\` -> \`boundary { posture, read[], locked }\` (org, committed) merged with \`.egregore-boundary.local.json\` (personal, gitignored). \`locked: true\` removes the consent path entirely.
+- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   \`\`\`text
   That path is outside this Egregore's boundary. How should we proceed?
-    1. Paste the contents inline
-    2. Move the file into the repo and point me at the new path
-    3. Cancel
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   \`\`\`
 
-See DEVELOPMENT.md §3 for boundary details.`;
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; \`locked: true\` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and \`memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md\` for the design decisions.`;
 
 // ── per-section rules ────────────────────────────────────────────────────
 const RULES = {
@@ -326,7 +330,7 @@ const RULES = {
   'Environment Isolation': {
     action: 'replace',
     body: ISOLATION_BODY,
-    note: 'boundary-check is a Claude PreToolUse hook with no .codex equivalent — behavior stated as a standing instruction; AskUserQuestion remediation -> numbered options.',
+    note: 'boundary-check is a Claude PreToolUse hook with no .codex equivalent — two-tier model stated as a standing instruction; AskUserQuestion remediation -> numbered options, now including the two consent-grant options (session grant -> .egregore-boundary-consent, instance grant -> .egregore-boundary.local.json read[]).',
   },
 };
 

package/runtime/codex/bin/codex-session-start.sh

@@ -6,7 +6,7 @@ set -o pipefail
 # libraries as Claude's SessionStart, then renders a terminal greeting before
 # Codex itself starts.
 
-FRAMEWORK_VERSION="6"
+FRAMEWORK_VERSION="7"
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$SCRIPT_DIR" || exit 1
 
@@ -21,6 +21,9 @@ fi
 # Clear any branch-guard consent from a previous session — consent to write on
 # a protected branch is asked fresh each session (see AGENTS.md branch-guard protocol).
 rm -f "$SCRIPT_DIR/.egregore-branch-consent" "$MAIN_PROJECT_DIR/.egregore-branch-consent" 2>/dev/null
+# Same for boundary-crossing consent — grants are session-scoped (AGENTS.md
+# environment-isolation protocol); durable grants belong in .egregore-boundary.local.json.
+rm -f "$SCRIPT_DIR/.egregore-boundary-consent" "$MAIN_PROJECT_DIR/.egregore-boundary-consent" 2>/dev/null
 
 if [ -f "$SCRIPT_DIR/bin/lib/worktree-links.sh" ]; then
   source "$SCRIPT_DIR/bin/lib/worktree-links.sh" >/dev/null 2>/dev/null || true

package/runtime/pi/.codex/skills/save/SKILL.md

@@ -43,7 +43,11 @@ esac
 4. Synthesize:
    - a short topic from the work,
    - a clear commit message,
-   - a one-line user-facing scope summary.
+   - a one-line user-facing scope summary,
+   - a PR description following `.claude/context/pr-format.md`:
+     `## What` (1–4 bullets), `## Why` (1–3 sentences), and
+     `## Verification` (how the change was checked — required when the
+     diff touches non-markdown files; be honest if unverified).
 5. If the scope is ambiguous or includes unrelated changes, ask for one compact
    confirmation. Use structured Codex question tooling when available;
    otherwise render:
@@ -58,11 +62,13 @@ Other:
 6. Run the bridge command:
 
 ```bash
-bin/agent.sh save --message "$MESSAGE" --topic "$TOPIC"
+bin/agent.sh save --message "$MESSAGE" --topic "$TOPIC" --pr-body "$PR_BODY"
 ```
 
 The bridge owns the mechanical workflow: sync memory, ensure a task branch,
 commit repo changes, push, and create or reuse a pull request when available.
+Always pass the synthesized `--pr-body` — the bridge only auto-generates a
+skeleton body as a last resort, and the CI `pr-format` check gates every PR.
 
 7. Parse the output and report only useful user information:
    - branch name,

package/runtime/pi/.codex/spec-manifest.json

@@ -41,7 +41,7 @@
     {
       "section": "Config Files",
       "action": "keep",
-      "sourceHash": "81b7bf09901b",
+      "sourceHash": "8d7f1bd0f2d9",
       "note": "Kept verbatim — shell facts, runtime-neutral."
     },
     {
@@ -83,7 +83,7 @@
     {
       "section": "Git Workflow",
       "action": "keep",
-      "sourceHash": "d058d1f8da11",
+      "sourceHash": "49fd4625fa1e",
       "note": "Kept; slash tokens rendered as $skill tokens. Branch diagram unchanged (code fence)."
     },
     {
@@ -119,8 +119,8 @@
     {
       "section": "Environment Isolation",
       "action": "replace",
-      "sourceHash": "ed47e96248bd",
-      "note": "boundary-check is a Claude PreToolUse hook with no .codex equivalent — behavior stated as a standing instruction; AskUserQuestion remediation -> numbered options."
+      "sourceHash": "086e2c1d9019",
+      "note": "boundary-check is a Claude PreToolUse hook with no .codex equivalent — two-tier model stated as a standing instruction; AskUserQuestion remediation -> numbered options, now including the two consent-grant options (session grant -> .egregore-boundary-consent, instance grant -> .egregore-boundary.local.json read[])."
     }
   ]
 }

package/runtime/pi/.pi/APPEND_SYSTEM.md

@@ -118,7 +118,7 @@ If the startup card output contains `onboarding_needed`, invoke the `/onboarding
 
 ## Config Files
 
-- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. **Never put secrets here.**
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. Optional `boundary { posture, read[], locked }` sets the org's isolation posture (see Environment Isolation). **Never put secrets here.**
 - **`.env`** — gitignored. Personal secrets. Local mode: `GITHUB_TOKEN` only. Connected mode: `GITHUB_TOKEN` + `EGREGORE_API_KEY`. **Never use `source .env`** — use `grep '^KEY=' .env | cut -d'=' -f2-`.
 
 In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API server only — `bin/graph.sh` and `bin/notify.sh` route through the API gateway.
@@ -207,6 +207,10 @@ main ← stable (/release)
 - **Memory repo**: stays on main (separate repo, auto-merge).
 - **Never push directly to main or develop.** All changes flow through PRs.
 
+### Pull request format (all harnesses)
+
+Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
+
 ### Managed Repos
 
 Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `/save` scans all managed repos for uncommitted changes.
@@ -275,17 +279,20 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## Environment Isolation
 
-Sessions are confined to this project + memory + managed repos. On Pi this boundary is a standing instruction, not an enforced hook — hold it yourself.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Pi the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Never modify `~/.egregore/instances.json`** — managed by session-start.sh
-- **Never access another instance's files** — refuse even if asked
-- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
+- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   ```text
   That path is outside this Egregore's boundary. How should we proceed?
-    1. Paste the contents inline
-    2. Move the file into the repo and point me at the new path
-    3. Cancel
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   ```
 
-See DEVELOPMENT.md §3 for boundary details.
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.

package/runtime/pi/.pi/spec-manifest.json

@@ -1,8 +1,8 @@
 {
   "generatedBy": "bin/pi-render-spec.mjs",
   "source": "AGENTS.md generated Codex spec",
-  "sourceHash": "e0336f66e9b4",
-  "outputHash": "da44541a50fb",
+  "sourceHash": "6ad94ccc38d8",
+  "outputHash": "7a3db92a611e",
   "adaptations": [
     "Pi project trust and APPEND_SYSTEM delivery",
     "Pi tool_call branch gate",

package/runtime/pi/AGENTS.md

@@ -35,7 +35,8 @@ Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 ```bash
 bin/agent.sh branch --topic "auth review"
-bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review" \
+  --pr-body "$PR_BODY"   # body per .claude/context/pr-format.md (auto-skeleton if omitted)
 bin/agent.sh wrap --from alice --topic "auth review" \
   --summary "Implemented the OAuth callback parser and documented follow-ups." \
   --body "Open threads: review error cases and browser redirects."
@@ -191,7 +192,7 @@ If the startup card output contains `onboarding_needed`, invoke the `$onboarding
 
 ## Config Files
 
-- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. **Never put secrets here.**
+- **`egregore.json`** — committed. Non-secret org config: `org_name`, `github_org`, `memory_repo`, `slug`, `mode`. `api_url` is connected-mode only. Optional `boundary { posture, read[], locked }` sets the org's isolation posture (see Environment Isolation). **Never put secrets here.**
 - **`.env`** — gitignored. Personal secrets. Local mode: `GITHUB_TOKEN` only. Connected mode: `GITHUB_TOKEN` + `EGREGORE_API_KEY`. **Never use `source .env`** — use `grep '^KEY=' .env | cut -d'=' -f2-`.
 
 In connected mode, infrastructure credentials (Neo4j, Telegram) live on the API server only — `bin/graph.sh` and `bin/notify.sh` route through the API gateway.
@@ -280,6 +281,10 @@ main ← stable (/release)
 - **Memory repo**: stays on main (separate repo, auto-merge).
 - **Never push directly to main or develop.** All changes flow through PRs.
 
+### Pull request format (all harnesses)
+
+Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
+
 ### Managed Repos
 
 Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `$save` scans all managed repos for uncommitted changes.
@@ -368,19 +373,22 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## Environment Isolation
 
-Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Never modify `~/.egregore/instances.json`** — managed by session-start.sh
-- **Never access another instance's files** — refuse even if asked
-- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
+- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   ```text
   That path is outside this Egregore's boundary. How should we proceed?
-    1. Paste the contents inline
-    2. Move the file into the repo and point me at the new path
-    3. Cancel
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   ```
 
-See DEVELOPMENT.md §3 for boundary details.
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.
 
 <!-- END GENERATED EGREGORE CODEX SPEC -->

package/runtime/pi/bin/agent.sh

@@ -32,7 +32,10 @@ Runtime-neutral commands:
                                    Hybrid recall over shared memory (qmd)
   people                           List known people from memory/people
   branch --topic TEXT              Create or reuse a task branch/worktree
-  save [--message TEXT]            Commit and push current repo + memory changes
+  save [--message TEXT] [--pr-body TEXT|--pr-body-file PATH]
+                                   Commit and push current repo + memory changes;
+                                   PR body follows .claude/context/pr-format.md
+                                   (auto-generated skeleton if not provided)
   wrap --topic T --summary TEXT    Write a session wrap to memory/wraps
   handoff --from A --to B --topic T [--intent action|feedback|fyi]
       [--body TEXT|--body-file PATH] [--no-push] [--no-publish] [--no-notify] [--json]
@@ -332,13 +335,26 @@ ensure_working_branch() {
   echo "$branch"
 }
 
+build_pr_body() {
+  # Compliant fallback PR body (spec: .claude/context/pr-format.md) built
+  # from the commit log + diff when the calling agent supplies none.
+  local topic="${1:-portable save}" commits stat
+  commits="$(git -C "$SCRIPT_DIR" log --pretty='- %s' "origin/develop..HEAD" 2>/dev/null | head -8)"
+  [ -n "$commits" ] || commits="- (commit list unavailable — see the Files tab)"
+  stat="$(git -C "$SCRIPT_DIR" diff --shortstat "origin/develop...HEAD" 2>/dev/null | sed 's/^ *//')"
+  printf '## What\n%s\n\n## Why\nShell-agent session save — topic: %s. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description.\n\n## Verification\nNot verified — auto-generated skeleton; review the diff before merging.%s\n\n🤖 Saved via bin/agent.sh\n' \
+    "$commits" "$topic" "${stat:+ ($stat)}"
+}
+
 cmd_save() {
-  local message="" topic="" no_pr=0 branch pushed="false" committed="false" pr_url="" existing_pr="" pr_number="" non_md="" merged="false"
+  local message="" topic="" no_pr=0 branch pushed="false" committed="false" pr_url="" existing_pr="" pr_number="" non_md="" merged="false" pr_body="" pr_body_file=""
 
   while [ $# -gt 0 ]; do
     case "$1" in
       --message|-m) message="${2:-}"; shift 2 ;;
       --topic) topic="${2:-}"; shift 2 ;;
+      --pr-body) pr_body="${2:-}"; shift 2 ;;
+      --pr-body-file) pr_body_file="${2:-}"; shift 2 ;;
       --no-pr) no_pr=1; shift ;;
       *) die "unknown save option: $1" ;;
     esac
@@ -376,7 +392,11 @@ cmd_save() {
     if [ -n "$existing_pr" ]; then
       pr_url="$existing_pr"
     else
-      pr_url="$(gh pr create --base develop --head "$branch" --title "$message" --body "Saved via bin/agent.sh save." 2>/dev/null || true)"
+      if [ -z "$pr_body" ] && [ -n "$pr_body_file" ] && [ -f "$pr_body_file" ]; then
+        pr_body="$(cat "$pr_body_file")"
+      fi
+      [ -n "$pr_body" ] || pr_body="$(build_pr_body "$topic")"
+      pr_url="$(gh pr create --base develop --head "$branch" --title "$message" --body "$pr_body" 2>/dev/null || true)"
     fi
   fi
 

package/runtime/pi/bin/codex-render-spec.mjs

@@ -79,7 +79,8 @@ Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 \`\`\`bash
 bin/agent.sh branch --topic "auth review"
-bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review" \\
+  --pr-body "$PR_BODY"   # body per .claude/context/pr-format.md (auto-skeleton if omitted)
 bin/agent.sh wrap --from alice --topic "auth review" \\
   --summary "Implemented the OAuth callback parser and documented follow-ups." \\
   --body "Open threads: review error cases and browser redirects."
@@ -251,20 +252,23 @@ Codex has no structured question tool — render each batch as compact numbered
 
 const LOOM_ROUTING_BODY = `Loom routes commands across model tiers on the Claude Code runtime (\`loom/routes.json\` + \`bin/loom.sh\` + a model-pinned executor subagent). Codex has no subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are framework files synced for the Claude runtime.`;
 
-const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Never modify \`~/.egregore/instances.json\`** — managed by session-start.sh
-- **Never access another instance's files** — refuse even if asked
-- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify \`~/.egregore/instances.json\` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (\`~/Downloads\`, \`~/Desktop\`) are readable without consent under the default posture; writes outside the project always need consent. Posture (\`strict | standard | open\`) and extra read roots come from \`egregore.json\` -> \`boundary { posture, read[], locked }\` (org, committed) merged with \`.egregore-boundary.local.json\` (personal, gitignored). \`locked: true\` removes the consent path entirely.
+- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   \`\`\`text
   That path is outside this Egregore's boundary. How should we proceed?
-    1. Paste the contents inline
-    2. Move the file into the repo and point me at the new path
-    3. Cancel
+    1. Allow its directory for this session (recorded in .egregore-boundary-consent)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    3. Paste the contents inline
+    4. Cancel
   \`\`\`
 
-See DEVELOPMENT.md §3 for boundary details.`;
+  Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; \`locked: true\` removes options 1 and 2.
+
+See DEVELOPMENT.md §3 for boundary details and \`memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md\` for the design decisions.`;
 
 // ── per-section rules ────────────────────────────────────────────────────
 const RULES = {
@@ -326,7 +330,7 @@ const RULES = {
   'Environment Isolation': {
     action: 'replace',
     body: ISOLATION_BODY,
-    note: 'boundary-check is a Claude PreToolUse hook with no .codex equivalent — behavior stated as a standing instruction; AskUserQuestion remediation -> numbered options.',
+    note: 'boundary-check is a Claude PreToolUse hook with no .codex equivalent — two-tier model stated as a standing instruction; AskUserQuestion remediation -> numbered options, now including the two consent-grant options (session grant -> .egregore-boundary-consent, instance grant -> .egregore-boundary.local.json read[]).',
   },
 };
 

package/runtime/pi/bin/codex-session-start.sh

@@ -6,7 +6,7 @@ set -o pipefail
 # libraries as Claude's SessionStart, then renders a terminal greeting before
 # Codex itself starts.
 
-FRAMEWORK_VERSION="6"
+FRAMEWORK_VERSION="7"
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$SCRIPT_DIR" || exit 1
 
@@ -21,6 +21,9 @@ fi
 # Clear any branch-guard consent from a previous session — consent to write on
 # a protected branch is asked fresh each session (see AGENTS.md branch-guard protocol).
 rm -f "$SCRIPT_DIR/.egregore-branch-consent" "$MAIN_PROJECT_DIR/.egregore-branch-consent" 2>/dev/null
+# Same for boundary-crossing consent — grants are session-scoped (AGENTS.md
+# environment-isolation protocol); durable grants belong in .egregore-boundary.local.json.
+rm -f "$SCRIPT_DIR/.egregore-boundary-consent" "$MAIN_PROJECT_DIR/.egregore-boundary-consent" 2>/dev/null
 
 if [ -f "$SCRIPT_DIR/bin/lib/worktree-links.sh" ]; then
   source "$SCRIPT_DIR/bin/lib/worktree-links.sh" >/dev/null 2>/dev/null || true