create-egregore 0.21.1 → 0.21.2

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.1
+// egregore-launcher-version: 0.21.2
 //
 // 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.1";
+const VERSION = "0.21.2";
 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");

package/lib/renderer-install.js

@@ -0,0 +1,42 @@
+"use strict";
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+
+// An installer starts npm children. Kill the whole group on timeout so retries
+// cannot race a download left behind by a terminated setup process.
+function runRendererInstaller(root, { timeoutMs = 180000, killGraceMs = 1000 } = {}) {
+  return new Promise((resolve) => {
+    const grouped = process.platform !== "win32";
+    const child = spawn("bash", [path.join(root, "bin", "artifact-renderer-install.sh")], {
+      cwd: root, detached: grouped, stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "", stderr = "", error;
+    let forceTimer;
+    const stop = (signal) => {
+      try {
+        if (grouped && child.pid) process.kill(-child.pid, signal);
+        else child.kill(signal);
+      } catch (err) {
+        if (err.code !== "ESRCH") error = err;
+      }
+    };
+    child.stdout.on("data", (data) => { stdout += data; });
+    child.stderr.on("data", (data) => { stderr += data; });
+    child.once("error", (err) => { error = err; });
+    const timer = setTimeout(() => {
+      error = new Error("Artifact renderer installation timed out");
+      stop("SIGTERM");
+      forceTimer = setTimeout(() => stop("SIGKILL"), killGraceMs);
+    }, timeoutMs);
+    child.once("close", (status) => {
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      // A descendant may have detached its output pipes before Bash exited.
+      if (error && grouped) stop("SIGKILL");
+      resolve({ status, stdout, stderr, error });
+    });
+  });
+}
+
+module.exports = { runRendererInstaller };

package/lib/setup.js

@@ -7,6 +7,7 @@ const { execSync, execFileSync, spawnSync, spawn } = require("node:child_process
 const fs = require("node:fs");
 const path = require("node:path");
 const os = require("node:os");
+const { runRendererInstaller } = require("./renderer-install");
 const {
   hasCodexRuntimeSupport,
   installCodexRuntime,
@@ -111,6 +112,20 @@ async function finalizeRuntimeSetup(egregoreDir, ui, {
 
   if (afterRuntimeInstall) await afterRuntimeInstall(runtimeSummary, preferredRuntime);
 
+  // Provision the pinned renderer during explicit installation, not at first
+  // preview or session launch. All harnesses share this managed local install.
+  const rendererInstaller = path.join(egregoreDir, "bin", "artifact-renderer-install.sh");
+  if (!fs.existsSync(rendererInstaller)) {
+    throw new Error("Artifact renderer setup is unavailable in this Runtime; update create-egregore and retry.");
+  }
+  ui.info("Preparing artifact renderer…");
+  const renderer = await runRendererInstaller(egregoreDir);
+  if (renderer.error || renderer.status !== 0) {
+    const detail = String(renderer.stderr || renderer.error?.message || `installer exited ${renderer.status}`).trim();
+    throw new Error(`Artifact renderer setup did not complete. ${detail}\nFrom this Egregore, run bash bin/artifact-renderer-install.sh, then retry setup.`);
+  }
+  ui.success("Artifact renderer ready");
+
   // Connect is an authenticated additive overlay on the exact OSS runtime.
   // Local instances return immediately; network failure never breaks setup.
   try {
@@ -725,20 +740,6 @@ async function install(data, ui, targetDir, opts = {}) {
     }
   }
 
-  // Warm the npx cache for egregore-artifacts so the first /view or
-  // publish-artifact call doesn't pay a cold npm download (~5-10s).
-  // Background + detached — we don't care about completion, and any
-  // failure is silent. The first real use benefits if this finishes in
-  // time, otherwise it costs nothing.
-  try {
-    const { spawn } = require("child_process");
-    const warm = spawn("npx", ["-y", "egregore-artifacts@latest", "--help"], {
-      detached: true,
-      stdio: "ignore",
-    });
-    warm.unref();
-  } catch { /* ignore — cosmetic warmup */ }
-
   // Done — full-screen summary bookend if we can; inline workspace list
   // otherwise. Same contract as localFounderFlow.
   const workspaces = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "description": "Set up Egregore for your team in one command \u2014 installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {
@@ -19,7 +19,7 @@
     "test:e2e": "node --test test/e2e-local.test.js",
     "test:all": "npm run test:runtime && node --test test/",
     "test:runtime": "node ../../bin/capability-distribution.mjs validate --root ../.. && node scripts/build-runtime-bundle.mjs --check && node scripts/build-claude-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node scripts/build-prime-runtime-bundle.mjs --check && node ../../bin/prime-render-spec.mjs --check && node ../../bin/pi-render-spec.mjs --check && node ../../api/scripts/build-connect-runtime-pack.mjs --check && bash ../../bin/tests/test-codex-native-skills.sh && bash ../../bin/tests/test-codex-spec-render.sh && node ../../bin/capability-distribution.mjs skill-contract --root ../.. --strict-contract && bash ../../bin/tests/test-bundle-skill-scripts.sh && node --test test/bundle-skill-scripts.test.js",
-    "test:package": "node --test --test-concurrency=1 test/invite-install.test.js test/capability-distribution.test.js test/connect-runtime.test.js test/context.test.js test/path-lookup.test.js test/nixos-portability.test.js test/parse-join-target.test.js test/skip-repos.test.js test/install-origin-guard.test.js test/onboarding-shortcircuit.test.js test/runtime-identity.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/claude-runtime.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/prime-runtime.test.js test/prime-branch-policy.test.js test/prime-bridge-skill.test.js test/pi-observe-context.test.js test/native-command-observe.test.js test/prime-rpc-driver.test.js test/pi-session-smoke.test.js test/prime-session-smoke.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/runtime-ownership.test.js test/installer-finalization.test.js test/runtime-readiness.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/installer-connect-choice.test.js test/launcher-connected-status.test.js test/launcher-telemetry.test.js test/launcher-runtime.test.js test/launcher-settings.test.js test/launcher-runtime-candidate.test.js test/launcher-permissions.test.js test/launcher-update.test.js test/harness-add.test.js test/connected-config.test.js test/workflow-settings.test.js"
+    "test:package": "node --test --test-concurrency=1 test/invite-install.test.js test/capability-distribution.test.js test/connect-runtime.test.js test/context.test.js test/path-lookup.test.js test/nixos-portability.test.js test/parse-join-target.test.js test/skip-repos.test.js test/install-origin-guard.test.js test/onboarding-shortcircuit.test.js test/runtime-identity.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/claude-runtime.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/prime-runtime.test.js test/prime-branch-policy.test.js test/prime-bridge-skill.test.js test/pi-observe-context.test.js test/native-command-observe.test.js test/prime-rpc-driver.test.js test/pi-session-smoke.test.js test/prime-session-smoke.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/runtime-ownership.test.js test/installer-finalization.test.js test/renderer-install.test.js test/runtime-readiness.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/installer-connect-choice.test.js test/launcher-connected-status.test.js test/launcher-telemetry.test.js test/launcher-runtime.test.js test/launcher-settings.test.js test/launcher-runtime-candidate.test.js test/launcher-permissions.test.js test/launcher-update.test.js test/harness-add.test.js test/connected-config.test.js test/workflow-settings.test.js"
   },
   "files": [
     "bin/",

package/runtime/claude/.claude/skills/view/SKILL.md

@@ -151,7 +151,8 @@ authorized result path; everything else is `document`.
 
 **On the script route, `bin/view-render.sh` owns everything in this section**:
 it resolves the packaged renderer locally (checked-out
-`packages/egregore-artifacts` first, then the installed `egregore-artifacts`;
+`packages/egregore-artifacts` with dependencies first, then the instance's
+managed renderer, then an installed `egregore-artifacts` on PATH;
 never `npx`, never a registry fetch), stages complete `memory/...` documents
 through the existing authorized `Runtime.open_source` adapter (ordinary model
 evidence reads remain bounded), serves unchanged content from the content-addressed

package/runtime/claude/bin/artifact-renderer-install.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# Explicit setup/update/repair only. Rendering and startup must never install.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+TARGET_ROOT="$SCRIPT_DIR"
+CHECK_ONLY=0
+LOCK_FD=""
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --root)
+      [ "$#" -ge 2 ] && [ -n "$2" ] || { echo 'artifact renderer: --root needs a directory' >&2; exit 2; }
+      TARGET_ROOT="$2"; shift 2 ;;
+    --check) CHECK_ONLY=1; shift ;;
+    --lock-fd) LOCK_FD="${2:?missing lock descriptor}"; shift 2 ;;
+    *) echo 'Usage: bash bin/artifact-renderer-install.sh [--root <instance>] [--check]' >&2; exit 2 ;;
+  esac
+done
+# npm 11 treats a symlinked --prefix as a linked root package, which makes
+# `ci` reject the lockfile (including macOS's /var -> /private/var alias).
+TARGET_ROOT="$(cd "$TARGET_ROOT" && pwd -P)"
+MANIFEST_DIR="$SCRIPT_DIR/bin/lib/artifact-renderer"
+
+for required in dependencies.json dependencies-lock.json; do
+  [ -f "$MANIFEST_DIR/$required" ] || {
+    echo "artifact renderer: pinned $required is missing; update the framework and retry" >&2
+    exit 1
+  }
+done
+NODE_BIN="$(bash "$SCRIPT_DIR/bin/node-run.sh" -p 'process.execPath')"
+export PATH="$(dirname "$NODE_BIN"):$PATH"
+MANIFEST_INFO="$(python3 - "$MANIFEST_DIR" <<'PY'
+import hashlib, json, pathlib, re, sys
+source = pathlib.Path(sys.argv[1])
+version = json.loads((source / 'dependencies.json').read_text())['dependencies']['egregore-artifacts']
+if not isinstance(version, str) or not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?', version):
+    raise SystemExit('artifact renderer: an exact package version is required')
+digest = hashlib.sha256((source / 'dependencies-lock.json').read_bytes()).hexdigest()[:16]
+print(version, version + '-' + digest)
+PY
+)"
+read -r VERSION INSTALL_ID <<< "$MANIFEST_INFO"
+TOOLS_DIR="$TARGET_ROOT/.egregore/tools/artifact-renderer"
+PREFIX="$TOOLS_DIR/$INSTALL_ID"
+
+renderer_ready() {
+  local candidate="$1"
+  cmp -s "$MANIFEST_DIR/dependencies.json" "$candidate/package.json" || return 1
+  cmp -s "$MANIFEST_DIR/dependencies-lock.json" "$candidate/package-lock.json" || return 1
+  "$NODE_BIN" -e '
+    const fs = require("node:fs");
+    const path = require("node:path");
+    const actual = JSON.parse(fs.readFileSync(path.join(process.argv[1], "node_modules/egregore-artifacts/package.json"), "utf8"));
+    if (actual.version !== process.argv[2]) process.exit(1);
+  ' "$candidate" "$VERSION" >/dev/null 2>&1 || return 1
+  "$NODE_BIN" "$candidate/node_modules/egregore-artifacts/bin/cli.js" --help >/dev/null 2>&1
+}
+
+if renderer_ready "$PREFIX"; then
+  printf 'Artifact renderer %s is ready\n' "$VERSION"
+  exit 0
+fi
+if [ "$CHECK_ONLY" = 1 ]; then
+  printf 'Artifact renderer %s is not ready; run bash bin/artifact-renderer-install.sh\n' "$VERSION" >&2
+  exit 1
+fi
+
+NPM_BIN="$(command -v npm || true)"
+[ -n "$NPM_BIN" ] && "$NPM_BIN" --version >/dev/null 2>&1 || {
+  echo 'artifact renderer: npm is unavailable; install Node with npm, then retry' >&2
+  exit 1
+}
+mkdir -p "$TOOLS_DIR"
+[ ! -L "$PREFIX" ] || { echo 'artifact renderer: managed install must not be a symbolic link' >&2; exit 1; }
+LOCK="$TOOLS_DIR/.$INSTALL_ID.lock"
+# A kernel lock survives in children while they are still installing and is
+# released after forced interruption. Its persistent file never means "busy".
+# Re-exec under the inherited descriptor so Bash, npm, and cleanup all share
+# ownership; unlike mkdir locks, a killed process cannot leave a stale owner.
+if [ -z "$LOCK_FD" ]; then
+  exec python3 - "$LOCK" "$SCRIPT_DIR/bin/artifact-renderer-install.sh" "$TARGET_ROOT" <<'PY'
+import fcntl, os, stat, sys
+lock, script, root = sys.argv[1:]
+fd = os.open(lock, os.O_CREAT | os.O_RDWR | getattr(os, 'O_NOFOLLOW', 0), 0o600)
+if not stat.S_ISREG(os.fstat(fd).st_mode):
+    raise SystemExit('artifact renderer: invalid install lock')
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except BlockingIOError:
+    raise SystemExit('artifact renderer: another install is in progress; retry after it finishes')
+os.set_inheritable(fd, True)
+os.execvp('bash', ['bash', script, '--root', root, '--lock-fd', str(fd)])
+PY
+fi
+# Validate the internal descriptor instead of accepting an unlocked re-entry.
+python3 - "$LOCK_FD" "$LOCK" <<'PY'
+import fcntl, os, sys
+try:
+    fd = int(sys.argv[1])
+    if not os.path.samestat(os.fstat(fd), os.stat(sys.argv[2])):
+        raise ValueError('wrong lock file')
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except (ValueError, OSError):
+    raise SystemExit('artifact renderer: install lock is unavailable')
+PY
+STAGE=""
+BACKUP="$TOOLS_DIR/.$INSTALL_ID.previous"
+cleanup() {
+  if [ -n "$BACKUP" ] && [ -d "$BACKUP" ] && [ ! -e "$PREFIX" ]; then mv "$BACKUP" "$PREFIX"; fi
+  [ -z "$STAGE" ] || rm -rf "$STAGE"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+# Recover an interrupted swap and discard only this pin's abandoned staging
+# trees. Another Runtime's version/lock and in-progress install stay untouched.
+if [ -d "$BACKUP" ]; then
+  if [ ! -e "$PREFIX" ]; then mv "$BACKUP" "$PREFIX"; else rm -rf "$BACKUP"; fi
+fi
+for abandoned in "$TOOLS_DIR/.$INSTALL_ID.stage."*; do
+  [ ! -d "$abandoned" ] || rm -rf "$abandoned"
+done
+
+# Recheck under the lock in case another explicit installer just completed.
+if renderer_ready "$PREFIX"; then
+  printf 'Artifact renderer %s is ready\n' "$VERSION"
+  exit 0
+fi
+STAGE="$(mktemp -d "$TOOLS_DIR/.$INSTALL_ID.stage.XXXXXX")"
+cp "$MANIFEST_DIR/dependencies.json" "$STAGE/package.json"
+cp "$MANIFEST_DIR/dependencies-lock.json" "$STAGE/package-lock.json"
+printf 'Installing artifact renderer %s with locked dependencies…\n' "$VERSION"
+if ! "$NPM_BIN" ci --prefix "$STAGE" --ignore-scripts --omit=dev --no-audit --no-fund >"$STAGE/install.log" 2>&1; then
+  echo 'artifact renderer: installation failed; the previous install was kept' >&2
+  # npm often appends a long usage guide after the actionable error.
+  head -12 "$STAGE/install.log" >&2
+  if [ "$(wc -l < "$STAGE/install.log")" -gt 20 ]; then
+    echo '… npm output abbreviated …' >&2
+    tail -8 "$STAGE/install.log" >&2
+  fi
+  exit 1
+fi
+if ! renderer_ready "$STAGE"; then
+  echo 'artifact renderer: the installed package failed its readiness check; the previous install was kept' >&2
+  exit 1
+fi
+rm -f "$STAGE/install.log"
+# Both renames are on the same filesystem. No live install is removed until
+# the complete replacement has passed its version/dependency probe.
+if [ -e "$PREFIX" ]; then
+  mv "$PREFIX" "$BACKUP"
+fi
+mv "$STAGE" "$PREFIX"
+STAGE=""
+[ ! -d "$BACKUP" ] || rm -rf "$BACKUP"
+printf 'Artifact renderer %s installed\n' "$VERSION"

package/runtime/claude/bin/artifact-renderer.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# One offline resolver for source checkouts and installed Egregore instances.
+# Provisioning is explicit (setup/update/artifact-renderer-install.sh), never
+# a side effect of rendering private content.
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+resolve_renderer() {
+  local source_cli="$ROOT/packages/egregore-artifacts/bin/cli.js"
+  local manifest_dir="$ROOT/bin/lib/artifact-renderer"
+  local managed="" install_id=""
+  local installed=""
+
+  if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && \
+     [ -f "$source_cli" ] && \
+     [ -d "$ROOT/packages/egregore-artifacts/node_modules/react" ]; then
+    printf '%s\n' "$source_cli"
+    return 0
+  fi
+  if [ -f "$manifest_dir/dependencies.json" ] && [ -f "$manifest_dir/dependencies-lock.json" ]; then
+    install_id="$(python3 - "$manifest_dir" <<'PY'
+import hashlib, json, pathlib, re, sys
+source = pathlib.Path(sys.argv[1])
+version = json.loads((source / 'dependencies.json').read_text())['dependencies']['egregore-artifacts']
+if not isinstance(version, str) or not re.fullmatch(r'[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?', version):
+    raise SystemExit('artifact renderer: an exact package version is required')
+digest = hashlib.sha256((source / 'dependencies-lock.json').read_bytes()).hexdigest()[:16]
+print(version + '-' + digest)
+PY
+)" || return 1
+    managed="$ROOT/.egregore/tools/artifact-renderer/$install_id"
+    if cmp -s "$manifest_dir/dependencies.json" "$managed/package.json" && \
+       cmp -s "$manifest_dir/dependencies-lock.json" "$managed/package-lock.json" && \
+       [ -f "$managed/node_modules/egregore-artifacts/bin/cli.js" ] && \
+       [ -d "$managed/node_modules/react" ]; then
+      printf '%s\n' "$managed/node_modules/egregore-artifacts/bin/cli.js"
+      return 0
+    fi
+  fi
+  installed="$(command -v egregore-artifacts 2>/dev/null || true)"
+  if [ -n "$installed" ] && [ -f "$installed" ]; then
+    printf '%s\n' "$installed"
+    return 0
+  fi
+  echo "The artifact renderer is not installed or its dependencies are missing." >&2
+  echo "Run bash bin/artifact-renderer-install.sh from this instance, then retry." >&2
+  return 1
+}
+
+renderer="$(resolve_renderer)" || exit 1
+if [ "${1:-}" = "--resolve" ]; then
+  [ "$#" -eq 1 ] || { echo "--resolve takes no arguments" >&2; exit 2; }
+  printf '%s\n' "$renderer"
+  exit 0
+fi
+exec bash "$ROOT/bin/node-run.sh" "$renderer" "$@"

package/runtime/claude/bin/handoff-preview.sh

@@ -110,13 +110,11 @@ preview() {
 
   local render_ok=0
   if [ -n "$composed" ]; then
-    if bash "$ROOT/bin/node-run.sh" \
-      "$ROOT/packages/egregore-artifacts/bin/cli.js" composed "$spec_file" \
+    if bash "$ROOT/bin/artifact-renderer.sh" composed "$spec_file" \
       --source "$content_file" --verify-fidelity; then
       render_ok=1
     fi
-  elif bash "$ROOT/bin/node-run.sh" \
-    "$ROOT/packages/egregore-artifacts/bin/cli.js" handoff "$content_file" \
+  elif bash "$ROOT/bin/artifact-renderer.sh" handoff "$content_file" \
     --verify-fidelity; then
     render_ok=1
   fi

package/runtime/claude/bin/handoff-run.sh

@@ -414,21 +414,14 @@ PID_MEMORY=$!
       # keep their familiar look.
       RENDERED_HTML="$TMPD/handoff.html"
       RENDER_OK=0
-      LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
       FIDELITY_ARGS=(--verify-fidelity)
       if [ "$RENDER_TYPE" = "composed" ]; then
         FIDELITY_ARGS+=(--source "$ABS_FILE")
       fi
-      # Node always runs through the adapter (broken Volta/NVM shims are a
-      # live hazard in harness shells), and there is no npx/@latest fallback:
-      # a hidden registry fetch of a floating version is never an acceptable
-      # renderer. Missing local renderer → structured-only handoff.
-      if [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-        if bash "$SCRIPT_DIR/bin/node-run.sh" "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
-          RENDER_OK=1
-        fi
-      else
-        echo "local egregore-artifacts renderer unavailable; sending structured handoff without custom HTML" > "$TMPD/render-error"
+      # Resolve exactly as previews do, without a registry fetch. An unavailable
+      # renderer still leaves the existing structured-only handoff fallback.
+      if bash "$SCRIPT_DIR/bin/artifact-renderer.sh" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
+        RENDER_OK=1
       fi
 
       # Step 2: build the emissary payload. If rendering succeeded AND the

package/runtime/claude/bin/lib/artifact-renderer/dependencies-lock.json

@@ -0,0 +1,94 @@
+{
+  "name": "egregore-managed-artifact-renderer",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "egregore-managed-artifact-renderer",
+      "version": "1.0.0",
+      "dependencies": {
+        "egregore-artifacts": "0.30.0"
+      }
+    },
+    "node_modules/@json-render/core": {
+      "version": "0.16.0",
+      "resolved": "https://registry.npmjs.org/@json-render/core/-/core-0.16.0.tgz",
+      "integrity": "sha512-qQp8BB/3pWYapTGXBDSBMXRCdrC05VJPLL3drXMPX/QbUB3nuvtyXUGmAZFUz8eLUy7JImODvb3GNIq38dGzhQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "zod": "^4.3.6"
+      },
+      "peerDependencies": {
+        "zod": "^4.0.0"
+      }
+    },
+    "node_modules/@json-render/react": {
+      "version": "0.16.0",
+      "resolved": "https://registry.npmjs.org/@json-render/react/-/react-0.16.0.tgz",
+      "integrity": "sha512-PJQjLftGYZ5LNlA1IFww+yNOAJZRW2feEcH/L10u/8M/b/zImr9wfqQVMDyC87myoEzhyucpkQ6joISeZdKxsw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@json-render/core": "0.16.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.3"
+      }
+    },
+    "node_modules/egregore-artifacts": {
+      "version": "0.30.0",
+      "resolved": "https://registry.npmjs.org/egregore-artifacts/-/egregore-artifacts-0.30.0.tgz",
+      "integrity": "sha512-0mihiLED2+n3CT4/VNBW7driwTdQwNaDztJ0T5/TFZ9qJhtUAJCyeawKfnOXgjuTkwwu+d6dY/KMuZMGONGDvQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@json-render/core": "^0.16.0",
+        "@json-render/react": "^0.16.0",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
+        "zod": "^4.3.6"
+      },
+      "bin": {
+        "egregore-artifacts": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.3.0.tgz",
+      "integrity": "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.3.0",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.0.tgz",
+      "integrity": "sha512-JDk8dgif51OjFoDE70+OT9ICyYr+69HlmihNwp1+Nsfbna3t5sIiCa9ZJktDmQ4/1b/rn26hIAR2uYXDMr5r0Q==",
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.28.0"
+      },
+      "peerDependencies": {
+        "react": "^19.3.0"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+      "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+      "license": "MIT"
+    },
+    "node_modules/zod": {
+      "version": "4.6.5",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz",
+      "integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package/runtime/claude/bin/lib/artifact-renderer/dependencies.json

@@ -0,0 +1,8 @@
+{
+  "name": "egregore-managed-artifact-renderer",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "egregore-artifacts": "0.30.0"
+  }
+}

package/runtime/claude/bin/lib/dashboard-artifact.sh

@@ -121,7 +121,7 @@ mkdir -p /tmp
 } > "$_DB_MD" 2>/dev/null
 
 # --- Publish markdown → HTML → hosted URL ---
-# publish-artifact.sh handles HTML generation internally (npx egregore-artifacts)
+# publish-artifact.sh handles HTML generation with the provisioned renderer.
 # then uploads. Don't pre-generate HTML — that causes double-wrapping.
 # https:// URLs are universally cmd+clickable across all terminal emulators.
 #
@@ -233,7 +233,7 @@ else
   if [ -z "$DASHBOARD_URL" ]; then
     _DB_HTML="/tmp/egregore-artifacts/dashboard-${EGREGORE_SESSION_ID}.html"
     mkdir -p /tmp/egregore-artifacts
-    if npx egregore-artifacts@latest document "$_DB_MD" --output "$_DB_HTML" --no-open >/dev/null 2>&1 && [ -f "$_DB_HTML" ]; then
+    if bash "$SCRIPT_DIR/bin/artifact-renderer.sh" document "$_DB_MD" --output "$_DB_HTML" --no-open >/dev/null 2>&1 && [ -f "$_DB_HTML" ]; then
       DASHBOARD_URL="file://${_DB_HTML}"
     fi
   fi

package/runtime/claude/bin/lib/greeting.sh

@@ -481,19 +481,8 @@ bash "$SCRIPT_DIR/bin/telemetry.sh" emit "session_start" \
 # --- Health check-in (background, non-blocking) ---
 bash "$SCRIPT_DIR/bin/startup-check.sh" >/dev/null 2>&1 &
 
-# --- Warm npx cache for egregore-artifacts (background, throttled) ---
-# publish-artifact.sh spawns `npx egregore-artifacts` — first run in a
-# fresh npx cache pays a 5-10s npm download. Warmup is throttled to
-# once per hour via a marker file so we don't storm npm when a user
-# opens many tabs, and don't start runaway retry loops when offline.
-_WARM_TS_FILE="$HOME/.cache/egregore/npx-warm-ts"
-mkdir -p "$(dirname "$_WARM_TS_FILE")" 2>/dev/null
-_WARM_LAST=$(cat "$_WARM_TS_FILE" 2>/dev/null || echo 0)
-_WARM_NOW=$(date +%s)
-if [ $(( _WARM_NOW - _WARM_LAST )) -gt 3600 ]; then
-  (npx -y egregore-artifacts@latest --help >/dev/null 2>&1 \
-    && echo "$_WARM_NOW" > "$_WARM_TS_FILE" &) >/dev/null 2>&1
-fi
+# Artifact dependencies are provisioned during explicit setup/update. Startup
+# must not warm a floating npx cache that the offline renderer cannot resolve.
 
 # Clean up temp files
 rm -rf "$CTX_DIR"

package/runtime/claude/bin/post-update.sh

@@ -10,6 +10,11 @@
 
 set -euo pipefail
 
+# This migration entry point is invoked by explicit /update, never startup.
+# The helper preserves a previous working install if provisioning fails.
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+bash "$SCRIPT_DIR/bin/artifact-renderer-install.sh"
+
 MIGRATED=0
 
 # --- Migration: commands → skills (CC 2.0+) ---

package/runtime/claude/bin/publish-artifact.sh

@@ -242,34 +242,13 @@ else
     fi
   fi
 
-  # Prefer the in-repo package copy when it's present AND its dependencies
-  # have been installed — that way local edits to packages/egregore-artifacts
-  # are exercised without waiting for an npm release. Fall back to the
-  # published `npx egregore-artifacts` otherwise.
-  # Set EGREGORE_USE_PUBLISHED=1 to force the npm-published renderer even
-  # when a local install is present — useful in the upstream dev repo to
-  # dogfood what teammates and OSS users actually run.
-  LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+  # Use the same provisioned renderer as previews and /view. Rendering never
+  # downloads a package; EGREGORE_USE_PUBLISHED skips the source checkout.
   RENDER_ERROR="/tmp/egregore-artifacts/render-error-$$.log"
-  if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
-      sed -n '1,4p' "$RENDER_ERROR" >&2
-      rm -f "$RENDER_ERROR"
-      exit 5
-    fi
-  else
-    # Installed published renderer only — never npx/@latest: a hidden
-    # registry fetch of a floating version is not an acceptable renderer.
-    PUBLISHED_CLI="$(command -v egregore-artifacts || true)"
-    if [ -z "$PUBLISHED_CLI" ]; then
-      echo "no artifact renderer available: the checked-out packages/egregore-artifacts is unusable and no installed egregore-artifacts was found" >&2
-      exit 5
-    fi
-    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$PUBLISHED_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
-      sed -n '1,4p' "$RENDER_ERROR" >&2
-      rm -f "$RENDER_ERROR"
-      exit 5
-    fi
+  if ! bash "$SCRIPT_DIR/bin/artifact-renderer.sh" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+    sed -n '1,4p' "$RENDER_ERROR" >&2
+    rm -f "$RENDER_ERROR"
+    exit 5
   fi
   rm -f "$RENDER_ERROR"
 fi

package/runtime/claude/bin/view-render.sh

@@ -49,19 +49,8 @@ _open() {
 }
 
 # --- Resolve the packaged deterministic renderer (never fetch, never npx) ---
-if [ -f "$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-  RENDER=(bash "$SCRIPT_DIR/bin/node-run.sh" "$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js")
-  RENDER_ID="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
-elif [ -f "$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js" ]; then
-  echo "The checked-out artifact renderer is missing its local dependencies." >&2
-  exit 1
-elif command -v egregore-artifacts >/dev/null 2>&1; then
-  RENDER=(bash "$SCRIPT_DIR/bin/node-run.sh" "$(command -v egregore-artifacts)")
-  RENDER_ID="$(command -v egregore-artifacts)"
-else
-  echo "The local artifact renderer is not installed for this instance." >&2
-  exit 1
-fi
+RENDER_ID="$(bash "$SCRIPT_DIR/bin/artifact-renderer.sh" --resolve)" || exit 1
+RENDER=(bash "$SCRIPT_DIR/bin/node-run.sh" "$RENDER_ID")
 
 # --- Live surfaces render fresh every time (their data is the present) ------
 case "$TYPE" in