create-egregore 0.21.1 → 0.21.3

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.21.1
+// egregore-launcher-version: 0.21.3
 //
 // 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.3";
 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.3",
   "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/context/telemetry.md

@@ -153,51 +153,30 @@ On the first session where telemetry events are emitted, if `telemetry_noticed`
 
 Then set `telemetry_noticed: true` in the state file. Never repeat this notice.
 
-## Session Reports
-
-Separate from telemetry. Users can optionally share session reports during `/wrap` or via `/issue egregore:`. Reports are **opt-in per session** — the user is asked each time and must explicitly agree.
-
-### How it works
-
-`bin/session-report.sh` handles report submission. It POSTs directly to Supabase via the anon key (no API server needed). The agent generates a structured report from the session context inline — no separate LLM call.
-
-```bash
-# Submit a report (reads JSON from stdin)
-echo '{"topic":"...","summary":"..."}' | bash bin/session-report.sh submit
-
-# Check reporting status
-bash bin/session-report.sh status
-```
-
-### What is sent
-
-- AI-analyzed topic + summary (same as what's written to memory)
-- Gap analysis: `{type, detail}` where type is `missing_skill`, `missing_tool`, `repeated_failure`, `wrong_info`, or `confusing_ux`
-- User's own description (if provided)
-- System info: mode, platform, shell, framework version
-- Session duration and message count
-
-### What is NEVER sent
-
-- Code, file contents, or file paths
-- Conversation transcript or user prompts
-- Environment variables or secrets
-- Org-specific data (sanitized before sending — org names, person names, tokens replaced)
-
-### Opt-out
-
-- `EGREGORE_NO_REPORTS=1` in `.env`
-- `.egregore-state.json` → `"session_reports": false`
-- Simply answer "No thanks" when prompted during `/wrap`
-- `DO_NOT_TRACK=1` also disables reports
-
-### Transport
-
-- Direct to Supabase via anon key (INSERT-only RLS policy)
-- If network fails: saved locally to `~/.egregore/reports/` as fallback
-- Telegram notification to maintainers fires server-side via Supabase DB webhook
-- Optional: GitHub issue creation on `egregore-labs/egregore` (user chooses each time)
-
-### Configuration
-
-Reports require `report_url` and `report_key` in `egregore.json`. New OSS installations get these automatically via `create-egregore`. If missing, the report prompt is skipped entirely.
+## Framework support and legacy session feedback
+
+For an Egregore bug, including the historical `/issue egregore:` wording, use
+the [issue workflow](../skills/issue/SKILL.md). Connected instances prepare an
+exact private support preview and submit only after confirmation. Local users
+can explicitly choose a public upstream report. An internal issue stays within
+its organization's memory or configured tracker; it does not automatically
+reach Egregore support. `/wrap` does not collect or submit session feedback.
+
+The older `bin/session-report.sh` is a feedback-storage compatibility helper,
+not a support-reporting route. It inserts selected feedback into `session_reports`
+when `report_url` and `report_key` are configured. A `submitted` receipt means
+only that storage accepted the feedback: no GitHub issue was created and no
+Telegram message was sent. The authenticated database callback acknowledges
+storage without planning or dispatching a notification to a named teammate.
+Transport failure saves feedback locally under `~/.egregore/reports/`; that
+does not establish remote storage or delivery. Missing configuration skips
+submission.
+
+Never invoke legacy feedback automatically, generate it from a transcript, or
+use it as a fallback when private support fails. Only explicitly selected and
+reviewed content may be shared. The helper adds legacy user and organization
+labels; it does not guarantee anonymization or scrub arbitrary input.
+
+Legacy feedback can be disabled with `EGREGORE_NO_REPORTS=1` or
+`DO_NOT_TRACK=1` in the process environment, or `"session_reports": false` in
+`.egregore-state.json`. These switches do not grant consent to submit content.

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

@@ -67,6 +67,12 @@ its default recipient is **Egregore support, private**. Local/OSS users may
 explicitly choose `upstream` for a **public** report. Connected users can also
 choose public upstream explicitly. Never fall back from private to public.
 
+Treat the historical `egregore:` prefix as framework-support intent and use
+this reviewed reporting flow. Never route a framework bug through the
+legacy session-feedback helper: it only stores feedback and does not
+file a support issue or send a Telegram notification. Being Connected does not
+turn an internal issue in the customer's memory into a report to Egregore.
+
 Use `'{title}'` for the concise title derived from the user's report and
 `'{report}'` for the report text the user supplied or reviewed.
 Write an embedded single quote as `'\''` in each substituted value.
@@ -119,6 +125,13 @@ review the private issue in its Project/Archive. Keep a failed/uncertain report'
 request ID; no backend failure authorizes public publication or a fresh blind
 submission.
 
+Report the confirmed outcome precisely: a preview is not submitted; a local
+issue is saved within this organization; only a matching private receipt with
+`submission_state: filed` means filed with Egregore support. Other states need
+recovery using the same request ID. A filed issue does not prove Telegram
+delivery: `notification_state: unverified` must never be described as sent or
+received. Only a separate delivery receipt can establish that.
+
 Public reports use the reporter's GitHub authentication and return a public
 issue URL. Destination comes only from HTTPS GitHub `upstream_url`; absent means
 `egregore-labs/egregore`, `none` means no upstream. Do not infer it from remotes.

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