create-egregore 0.21.1 → 0.21.2

package/runtime/claude/egregore_runtime/upgrade.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import signal
 import subprocess
 import sys
 import time
@@ -27,6 +28,8 @@ from typing import Any, Mapping
 from .adapters.qmd import QMD_VERSION, RERANKING_ENABLED, QmdLocalRetriever
 
 SCHEMA_VERSION = "egregore-runtime-upgrade/v1"
+_RENDERER_INSTALL_TIMEOUT_SECONDS = 180
+_RENDERER_TERMINATE_GRACE_SECONDS = 5
 
 # Stage keys in preparation order. Labels are the user-facing truth shown by
 # Settings; keep them in plain team language.
@@ -628,6 +631,54 @@ class UpgradeEngine:
         if probe.returncode != 0:
             self._fail(state, "node", "the selected Node runtime failed its version probe")
             return False
+        # Explicit Runtime preparation owns package provisioning. Preview and
+        # session startup only resolve installed renderers. Older candidates
+        # predate this helper and retain their original upgrade contract.
+        renderer_installer = (
+            Path(state.get("installed_path") or "")
+            / "runtime" / APPLY_TREE / "bin" / "artifact-renderer-install.sh"
+        )
+        if renderer_installer.is_file():
+            environment = {**os.environ, **self.retriever.environment}
+            environment["PATH"] = str(Path(node).parent) + os.pathsep + environment.get("PATH", "")
+            try:
+                with subprocess.Popen(
+                    ("bash", str(renderer_installer), "--root", str(self.repository_root)),
+                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                    cwd=self.repository_root, env=environment, start_new_session=True,
+                ) as renderer:
+                    try:
+                        stdout, stderr = renderer.communicate(timeout=_RENDERER_INSTALL_TIMEOUT_SECONDS)
+                    except subprocess.TimeoutExpired:
+                        # npm is a child of the installer shell. Stop the entire
+                        # group so its EXIT cleanup can run without an orphaned
+                        # package manager still writing into the staging tree.
+                        try:
+                            os.killpg(renderer.pid, signal.SIGTERM)
+                        except ProcessLookupError:
+                            pass
+                        try:
+                            renderer.communicate(timeout=_RENDERER_TERMINATE_GRACE_SECONDS)
+                        except subprocess.TimeoutExpired:
+                            pass
+                        finally:
+                            # A child may ignore TERM even after Bash exits.
+                            try:
+                                os.killpg(renderer.pid, signal.SIGKILL)
+                            except ProcessLookupError:
+                                pass
+                            renderer.communicate()
+                        raise
+            except subprocess.TimeoutExpired:
+                self._fail(state, "node", f"artifact renderer provisioning timed out after {_RENDERER_INSTALL_TIMEOUT_SECONDS} seconds; retry preparation")
+                return False
+            except OSError as exc:
+                self._fail(state, "node", f"artifact renderer provisioning failed: {exc}")
+                return False
+            if renderer.returncode != 0:
+                detail = (stderr or stdout).strip()
+                self._fail(state, "node", f"artifact renderer provisioning failed: {detail}")
+                return False
         self._mark(state, "node", "done", f"{probe.stdout.strip()} at instance-selected path")
         return True
 

package/runtime/claude/manifest.json

@@ -135,6 +135,8 @@
     "bin/agent.sh",
     "bin/api-call.sh",
     "bin/artifact-register.sh",
+    "bin/artifact-renderer-install.sh",
+    "bin/artifact-renderer.sh",
     "bin/artifact-writeback.sh",
     "bin/artifacts.sh",
     "bin/attendant.sh",
@@ -182,6 +184,8 @@
     "bin/issue.sh",
     "bin/knowledge.sh",
     "bin/lib/artifact-id.sh",
+    "bin/lib/artifact-renderer/dependencies-lock.json",
+    "bin/lib/artifact-renderer/dependencies.json",
     "bin/lib/config.sh",
     "bin/lib/context.sh",
     "bin/lib/dashboard-artifact.sh",

package/runtime/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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/codex/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

package/runtime/codex/egregore_runtime/upgrade.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import signal
 import subprocess
 import sys
 import time
@@ -27,6 +28,8 @@ from typing import Any, Mapping
 from .adapters.qmd import QMD_VERSION, RERANKING_ENABLED, QmdLocalRetriever
 
 SCHEMA_VERSION = "egregore-runtime-upgrade/v1"
+_RENDERER_INSTALL_TIMEOUT_SECONDS = 180
+_RENDERER_TERMINATE_GRACE_SECONDS = 5
 
 # Stage keys in preparation order. Labels are the user-facing truth shown by
 # Settings; keep them in plain team language.
@@ -628,6 +631,54 @@ class UpgradeEngine:
         if probe.returncode != 0:
             self._fail(state, "node", "the selected Node runtime failed its version probe")
             return False
+        # Explicit Runtime preparation owns package provisioning. Preview and
+        # session startup only resolve installed renderers. Older candidates
+        # predate this helper and retain their original upgrade contract.
+        renderer_installer = (
+            Path(state.get("installed_path") or "")
+            / "runtime" / APPLY_TREE / "bin" / "artifact-renderer-install.sh"
+        )
+        if renderer_installer.is_file():
+            environment = {**os.environ, **self.retriever.environment}
+            environment["PATH"] = str(Path(node).parent) + os.pathsep + environment.get("PATH", "")
+            try:
+                with subprocess.Popen(
+                    ("bash", str(renderer_installer), "--root", str(self.repository_root)),
+                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                    cwd=self.repository_root, env=environment, start_new_session=True,
+                ) as renderer:
+                    try:
+                        stdout, stderr = renderer.communicate(timeout=_RENDERER_INSTALL_TIMEOUT_SECONDS)
+                    except subprocess.TimeoutExpired:
+                        # npm is a child of the installer shell. Stop the entire
+                        # group so its EXIT cleanup can run without an orphaned
+                        # package manager still writing into the staging tree.
+                        try:
+                            os.killpg(renderer.pid, signal.SIGTERM)
+                        except ProcessLookupError:
+                            pass
+                        try:
+                            renderer.communicate(timeout=_RENDERER_TERMINATE_GRACE_SECONDS)
+                        except subprocess.TimeoutExpired:
+                            pass
+                        finally:
+                            # A child may ignore TERM even after Bash exits.
+                            try:
+                                os.killpg(renderer.pid, signal.SIGKILL)
+                            except ProcessLookupError:
+                                pass
+                            renderer.communicate()
+                        raise
+            except subprocess.TimeoutExpired:
+                self._fail(state, "node", f"artifact renderer provisioning timed out after {_RENDERER_INSTALL_TIMEOUT_SECONDS} seconds; retry preparation")
+                return False
+            except OSError as exc:
+                self._fail(state, "node", f"artifact renderer provisioning failed: {exc}")
+                return False
+            if renderer.returncode != 0:
+                detail = (stderr or stdout).strip()
+                self._fail(state, "node", f"artifact renderer provisioning failed: {detail}")
+                return False
         self._mark(state, "node", "done", f"{probe.stdout.strip()} at instance-selected path")
         return True