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

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.0-runtime-mvp.19
+// egregore-launcher-version: 0.21.0-runtime-mvp.21
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -35,7 +35,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.21.0-runtime-mvp.19";
+const VERSION = "0.21.0-runtime-mvp.21";
 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");
@@ -2341,8 +2341,18 @@ function connectedModeSuffix(instPath) {
 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;
+  // The launcher is copied into a PATH directory as a standalone executable,
+  // so __dirname normally points at /usr/local/bin or ~/.local/bin rather than
+  // the npm package that supplied it. installLauncherBinary keeps the matching
+  // Runtime engine in a versioned per-user directory outside every Egregore
+  // checkout. The package-adjacent fallback keeps direct source/package runs
+  // working without a separate install step.
+  const runtimeBase = process.env.EGREGORE_LAUNCHER_RUNTIME_DIR
+    || path.join(os.homedir(), ".egregore", "launcher-runtime");
+  const installed = path.join(runtimeBase, VERSION, "claude", "bin", "runtime-upgrade.sh");
+  if (fs.existsSync(installed)) return installed;
+  const adjacent = path.join(__dirname, "..", "runtime", "claude", "bin", "runtime-upgrade.sh");
+  return fs.existsSync(adjacent) ? adjacent : null;
 }
 
 function resolveUpgradeBridge(inst) {

package/bin/cli.js

@@ -471,6 +471,10 @@ async function main() {
       ui.error("Could not refresh the Egregore CLI.");
       process.exit(1);
     }
+    if (!alias.runtimeBridgePath || !fs.existsSync(alias.runtimeBridgePath)) {
+      ui.error("Could not refresh the Runtime update engine.");
+      process.exit(1);
+    }
     ui.success(`Egregore CLI is current at ${alias.binaryPath}`);
     return;
   }

package/lib/setup.js

@@ -1283,6 +1283,7 @@ async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
 // browser, better rendering, and richer keybinds.
 const LAUNCHER_TEMPLATE_JS = path.join(__dirname, "..", "assets", "egregore-launcher.js");
 const LAUNCHER_TEMPLATE_SH = path.join(__dirname, "..", "assets", "egregore-launcher.sh");
+const LAUNCHER_RUNTIME_TEMPLATE = path.join(__dirname, "..", "runtime", "claude");
 
 function readLauncherTemplate() {
   // Prefer the Node launcher; fall back to bash only if the .js is missing.
@@ -1294,6 +1295,50 @@ function currentTemplatePath() {
   return fs.existsSync(LAUNCHER_TEMPLATE_JS) ? LAUNCHER_TEMPLATE_JS : LAUNCHER_TEMPLATE_SH;
 }
 
+function launcherRuntimeRoot(version) {
+  const base = process.env.EGREGORE_LAUNCHER_RUNTIME_DIR
+    || path.join(os.homedir(), ".egregore", "launcher-runtime");
+  return version ? path.join(base, version) : null;
+}
+
+function launcherRuntimeBridge(version) {
+  const root = launcherRuntimeRoot(version);
+  return root ? path.join(root, "claude", "bin", "runtime-upgrade.sh") : null;
+}
+
+// The PATH launcher is a copied standalone file, not an npm shim, so it cannot
+// reach runtime/ through __dirname after installation. Keep the matching
+// upgrade engine in a versioned per-user directory. This is deliberately
+// outside registered Egregore checkouts: refreshing the global CLI must never
+// spray framework files into an instance or dirty its Git working tree.
+function installLauncherRuntime(version, ui) {
+  const destination = launcherRuntimeRoot(version);
+  const bridge = launcherRuntimeBridge(version);
+  if (!destination || !fs.existsSync(LAUNCHER_RUNTIME_TEMPLATE)) return null;
+  if (bridge && fs.existsSync(bridge)) return bridge;
+
+  const parent = path.dirname(destination);
+  const temporary = path.join(parent, `.${path.basename(destination)}.tmp-${process.pid}`);
+  try {
+    fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+    fs.rmSync(temporary, { recursive: true, force: true });
+    fs.mkdirSync(temporary, { recursive: true, mode: 0o700 });
+    fs.cpSync(LAUNCHER_RUNTIME_TEMPLATE, path.join(temporary, "claude"), {
+      recursive: true,
+      dereference: false,
+    });
+    const stagedBridge = path.join(temporary, "claude", "bin", "runtime-upgrade.sh");
+    if (!fs.existsSync(stagedBridge)) throw new Error("packaged runtime-upgrade.sh is missing");
+    fs.rmSync(destination, { recursive: true, force: true });
+    fs.renameSync(temporary, destination);
+    return bridge;
+  } catch (err) {
+    try { fs.rmSync(temporary, { recursive: true, force: true }); } catch {}
+    ui.warn(`Could not install the Runtime update engine: ${err.message}`);
+    return null;
+  }
+}
+
 // Parse a semver from a version-stamp comment. Accepts both styles so we can
 // upgrade a bash launcher to the Node launcher across a major line:
 //   # egregore-launcher-version: X.Y.Z   (bash)
@@ -1400,6 +1445,8 @@ function appendLocalBinToRc(ui) {
  */
 async function installLauncherBinary(egregoreDir, ui) {
   const template = readLauncherTemplate();
+  const templateVer = launcherVersion(template);
+  const packagedBridge = installLauncherRuntime(templateVer, ui);
   // Tests, containers, and managed installations can pin the launcher to an
   // isolated directory.  When explicitly configured, never fall through to a
   // machine-wide path: isolation is the reason the override exists.
@@ -1444,7 +1491,7 @@ async function installLauncherBinary(egregoreDir, ui) {
         try { fs.chmodSync(binaryPath, 0o755); } catch {}
         if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
         removeShadowingEgregoreAliases(ui);
-        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false, runtimeBridgePath: packagedBridge };
       }
 
       // Different content — decide upgrade vs preserve via version stamps.
@@ -1458,18 +1505,18 @@ async function installLauncherBinary(egregoreDir, ui) {
           ui.success(`Upgraded ${ui.dim("egregore")} at ${binaryPath} ${ui.dim(`(${existingVer} → ${templateVer})`)}`);
           if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
           removeShadowingEgregoreAliases(ui);
-          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true };
+          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true, runtimeBridgePath: packagedBridge };
         }
         if (compareVersions(templateVer, existingVer) < 0) {
           // Template is older — don't downgrade. Warn lightly.
           ui.warn(`Existing ${binaryPath} (v${existingVer}) is newer than this installer's template (v${templateVer}) — leaving it alone.`);
           removeShadowingEgregoreAliases(ui);
-          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+          return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false, runtimeBridgePath: launcherRuntimeBridge(existingVer) };
         }
         // Equal stamps but different content → user edited the file. Don't clobber.
         ui.warn(`Existing ${binaryPath} has been edited locally — not overwriting.`);
         ui.info(`  To reset: cp ${currentTemplatePath()} ${binaryPath}`);
-        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false, runtimeBridgePath: packagedBridge };
       }
 
       // No version stamp on existing. If it looks like one of OUR old
@@ -1485,11 +1532,11 @@ async function installLauncherBinary(egregoreDir, ui) {
         ui.success(`Upgraded ${ui.dim("egregore")} at ${binaryPath} ${ui.dim(`(pre-0.4.1 → ${templateVer})`)}`);
         if (chosen.location === "user" && !dirOnPath(chosen.dir)) appendLocalBinToRc(ui);
         removeShadowingEgregoreAliases(ui);
-        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true };
+        return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: true, runtimeBridgePath: packagedBridge };
       }
       ui.warn(`Existing ${binaryPath} doesn't look like an egregore launcher — not overwriting.`);
       ui.info(`  If you meant to install: rm ${binaryPath} and re-run create-egregore.`);
-      return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false };
+      return { aliasName: "egregore", binaryPath, location: chosen.location, replaced: false, runtimeBridgePath: null };
     } catch {
       // Fall through to write
     }
@@ -1509,7 +1556,7 @@ async function installLauncherBinary(egregoreDir, ui) {
 
   removeShadowingEgregoreAliases(ui);
   ui.success(`Installed ${ui.dim("egregore")} at ${binaryPath}`);
-  return { aliasName: "egregore", binaryPath, location: chosen.location, replaced };
+  return { aliasName: "egregore", binaryPath, location: chosen.location, replaced, runtimeBridgePath: packagedBridge };
 }
 
 // Strip legacy `alias egregore=...` lines from common shell rc files. These

package/package.json

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

package/runtime/claude/.claude/hooks/memory-read-guard.sh

@@ -8,8 +8,8 @@
 # memory files right after a clean search), so this hook enforces it.
 #
 # Scope: a retrieval episode. The guard engages only while this session's
-# evidence packet is fresh (written within the last EGREGORE_RETRIEVAL_WINDOW_MIN
-# minutes, default 15). Outside an episode — editing a decision record, a skill
+# retrieval episode is fresh (a search or open within the last
+# EGREGORE_RETRIEVAL_WINDOW_MIN minutes, default 15). Outside an episode — editing a decision record, a skill
 # reading memory, ordinary work — memory reads are untouched. Edit and Write
 # are never the guard's business. Searching memory with grep passes.
 #
@@ -26,10 +26,14 @@ case "$TOOL" in Bash|Read) ;; *) exit 0 ;; esac
 # --- Retrieval episode: this session's packet exists and is fresh ---------
 SESSION=$(cat "$PROJECT_DIR/.egregore-session-id" 2>/dev/null | tr -cd 'A-Za-z0-9_.-')
 [ -n "$SESSION" ] || exit 0
-PACKET="${TMPDIR:-/tmp}/egregore-retrieval-context/$SESSION.context"
-[ -f "$PACKET" ] || exit 0
+# The packet itself is consumed by the PostToolUse hook the moment it is
+# attached, so the episode is recorded by a marker that bin/search.sh and the
+# PostToolUse hook both touch. The packet is checked too, for the window
+# between its write and its consumption.
+CTX_DIR="${TMPDIR:-/tmp}/egregore-retrieval-context"
 WINDOW_MIN="${EGREGORE_RETRIEVAL_WINDOW_MIN:-15}"
-[ -n "$(find "$PACKET" -mmin "-$WINDOW_MIN" 2>/dev/null)" ] || exit 0
+_fresh() { [ -f "$1" ] && [ -n "$(find "$1" -mmin "-$WINDOW_MIN" 2>/dev/null)" ]; }
+_fresh "$CTX_DIR/$SESSION.episode" || _fresh "$CTX_DIR/$SESSION.context" || exit 0
 
 _block() {
   printf 'Egregore: memory sources are opened through the private evidence packet, not printed into the transcript.\n' >&2

package/runtime/claude/.claude/hooks/retrieval-context.sh

@@ -39,5 +39,8 @@ jq -Rs '{
     )
   }
 }' "$PACKET"
+# The packet is one-shot, but the retrieval episode is not: leave a marker so
+# memory-read-guard.sh keeps routing raw memory reads through the opener.
+touch "${PACKET%.context}.episode" 2>/dev/null || true
 rm -f "$PACKET"
 exit 0

package/runtime/claude/bin/search.sh

@@ -283,6 +283,10 @@ cmd_query() {
     }
     umask 077
     printf '%s\n' "$out" > "$packet"
+    # The PostToolUse hook consumes the packet the moment it attaches it; the
+    # episode marker outlives that so the memory-read guard knows a retrieval
+    # just happened.
+    touch "${packet%.context}.episode" 2>/dev/null || true
     _banner_and_emit "$label" "$t0" "$emit" "$out" 1
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
@@ -343,6 +347,7 @@ case "${1:-}" in
       umask 077
       if _runtime open "$OPEN_PATH" > "$packet" 2>"$packet.err"; then
         rm -f "$packet.err"
+        touch "${packet%.context}.episode" 2>/dev/null || true
         echo "↳ opened $OPEN_PATH · content attached privately"
       else
         cat "$packet.err" >&2 2>/dev/null

package/runtime/codex/bin/search.sh

@@ -283,6 +283,10 @@ cmd_query() {
     }
     umask 077
     printf '%s\n' "$out" > "$packet"
+    # The PostToolUse hook consumes the packet the moment it attaches it; the
+    # episode marker outlives that so the memory-read guard knows a retrieval
+    # just happened.
+    touch "${packet%.context}.episode" 2>/dev/null || true
     _banner_and_emit "$label" "$t0" "$emit" "$out" 1
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
@@ -343,6 +347,7 @@ case "${1:-}" in
       umask 077
       if _runtime open "$OPEN_PATH" > "$packet" 2>"$packet.err"; then
         rm -f "$packet.err"
+        touch "${packet%.context}.episode" 2>/dev/null || true
         echo "↳ opened $OPEN_PATH · content attached privately"
       else
         cat "$packet.err" >&2 2>/dev/null

package/runtime/pi/bin/search.sh

@@ -283,6 +283,10 @@ cmd_query() {
     }
     umask 077
     printf '%s\n' "$out" > "$packet"
+    # The PostToolUse hook consumes the packet the moment it attaches it; the
+    # episode marker outlives that so the memory-read guard knows a retrieval
+    # just happened.
+    touch "${packet%.context}.episode" 2>/dev/null || true
     _banner_and_emit "$label" "$t0" "$emit" "$out" 1
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
@@ -343,6 +347,7 @@ case "${1:-}" in
       umask 077
       if _runtime open "$OPEN_PATH" > "$packet" 2>"$packet.err"; then
         rm -f "$packet.err"
+        touch "${packet%.context}.episode" 2>/dev/null || true
         echo "↳ opened $OPEN_PATH · content attached privately"
       else
         cat "$packet.err" >&2 2>/dev/null

package/runtime/prime/bin/search.sh

@@ -283,6 +283,10 @@ cmd_query() {
     }
     umask 077
     printf '%s\n' "$out" > "$packet"
+    # The PostToolUse hook consumes the packet the moment it attaches it; the
+    # episode marker outlives that so the memory-read guard knows a retrieval
+    # just happened.
+    touch "${packet%.context}.episode" 2>/dev/null || true
     _banner_and_emit "$label" "$t0" "$emit" "$out" 1
   else
     _banner_and_emit "$label" "$t0" "$emit" "$out"
@@ -343,6 +347,7 @@ case "${1:-}" in
       umask 077
       if _runtime open "$OPEN_PATH" > "$packet" 2>"$packet.err"; then
         rm -f "$packet.err"
+        touch "${packet%.context}.episode" 2>/dev/null || true
         echo "↳ opened $OPEN_PATH · content attached privately"
       else
         cat "$packet.err" >&2 2>/dev/null