create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Derive Pi's project-local system appendix from the generated Codex protocol.
+// CLAUDE.md remains canonical: CLAUDE.md -> AGENTS.md -> .pi/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Pi.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = path.join(ROOT, "AGENTS.md");
+const OUTPUT = path.join(ROOT, ".pi", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".pi", "spec-manifest.json");
+const CODEX_BEGIN = "<!-- BEGIN GENERATED EGREGORE CODEX SPEC";
+const CODEX_END = "<!-- END GENERATED EGREGORE CODEX SPEC -->";
+
+function hash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function extractSpec(source) {
+  const begin = source.indexOf(CODEX_BEGIN);
+  const contentStart = source.indexOf("\n", begin);
+  const end = source.indexOf(CODEX_END, contentStart);
+  if (begin < 0 || contentStart < 0 || end < 0) {
+    throw new Error("AGENTS.md does not contain the generated Codex spec");
+  }
+  return source.slice(contentStart + 1, end).trim();
+}
+
+function replaceSection(markdown, heading, body) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
+}
+
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`pi/prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
+function adapt(sourceSpec) {
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec. A missing anchor once no-opped silently (the tool_call gate
+  // wording vanished from this file for a whole PR cycle before a test caught
+  // it) — now it fails the render loudly so the anchor gets updated alongside
+  // the Codex text that moved.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Pi"],
+    ["Codex-native", "Pi-native"],
+    ["Codex sessions", "Pi sessions"],
+    ["On Codex", "On Pi"],
+    ["Codex has no", "Pi has no built-in"],
+    ["bin/codex-session-start.sh", "bin/pi-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".pi/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded after Pi project trust)"],
+    ["If this Codex build does not support hooks", "If Pi project resources are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.pi/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`pi-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
+    .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
+    .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
+
+  text = replaceSection(text, "Egregore on Pi", `You are Pi running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Pi resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of \`CLAUDE.md\`, the behavioral source of truth. Pi loads it through \`.pi/APPEND_SYSTEM.md\` after the launcher grants project trust for this run. Egregore workflows are shared from \`.codex/skills/\` using Pi's documented cross-harness skill support and exposed as familiar slash commands by \`.pi/extensions/egregore.ts\`.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Pi extension renders the Egregore startup card (identity, handoffs, team activity) inside Pi via \`bin/pi-session-start.sh\`. This works for direct \`pi\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Pi, run \`bash bin/pi-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Pi slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.pi/extensions/egregore.ts\`. Pi also exposes the underlying Agent Skills as \`/skill:name\`, and natural-language requests work normally. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Pi, run referenced \`bin/\` scripts directly, use ordinary Pi shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no Pi UI question surface is available.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Pi\n\nThis file is generated by \`bin/pi-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
+}
+
+const check = process.argv.includes("--check");
+const source = fs.readFileSync(SOURCE, "utf8");
+const sourceSpec = extractSpec(source);
+const rendered = adapt(sourceSpec);
+const manifest = `${JSON.stringify({
+  generatedBy: "bin/pi-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Pi project trust and APPEND_SYSTEM delivery",
+    "Pi tool_call branch gate",
+    "Pi slash-command extension over shared portable skills",
+    "plain-text question fallback and direct shell/network execution",
+  ],
+}, null, 2)}\n`;
+
+if (check) {
+  const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
+  if (currentOutput !== rendered || currentManifest !== manifest) {
+    console.error("pi spec out of date — run: bash bin/node-run.sh bin/pi-render-spec.mjs");
+    process.exit(1);
+  }
+  console.log("pi spec up to date");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`pi spec rendered: .pi/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

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

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Post-update migrations for Egregore framework.
+#
+# This script is synced from upstream on every /update. All migration
+# logic lives here — not in the /update skill itself. This avoids the
+# chicken-and-egg problem: the dumb syncer pulls this script, then
+# this script handles whatever needs to happen.
+#
+# Migrations must be idempotent — they run on every update.
+
+set -euo pipefail
+
+MIGRATED=0
+
+# --- Migration: commands → skills (CC 2.0+) ---
+# CC 2.0 dropped .claude/commands/ support. If skills exist (synced from
+# upstream) and commands still exist locally, remove commands to prevent
+# duplicate entries in the slash menu.
+if [ -d ".claude/skills" ] && [ -d ".claude/commands" ]; then
+  CC_MAJOR=$(claude --version 2>/dev/null | grep -oE '^[0-9]+' || echo "0")
+  if [ "${CC_MAJOR:-0}" -ge 2 ]; then
+    git rm -r .claude/commands/ 2>/dev/null || rm -rf .claude/commands/
+    echo "  ✓ Removed .claude/commands/ (migrated to skills)"
+    MIGRATED=1
+  fi
+fi
+
+# --- Future migrations go here ---
+# Each migration should:
+# 1. Check if it needs to run (idempotent guard)
+# 2. Do the work
+# 3. Echo a status line
+# 4. Set MIGRATED=1
+
+if [ "$MIGRATED" -eq 0 ]; then
+  echo "  ✓ No migrations needed"
+fi

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Derive Prime Agent's project-local system appendix from the generated Codex
+// protocol. CLAUDE.md remains canonical:
+// CLAUDE.md -> AGENTS.md -> .prime/agent/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Prime.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = path.join(ROOT, "AGENTS.md");
+const OUTPUT = path.join(ROOT, ".prime", "agent", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".prime", "agent", "spec-manifest.json");
+const CODEX_BEGIN = "<!-- BEGIN GENERATED EGREGORE CODEX SPEC";
+const CODEX_END = "<!-- END GENERATED EGREGORE CODEX SPEC -->";
+
+function hash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function extractSpec(source) {
+  const begin = source.indexOf(CODEX_BEGIN);
+  const contentStart = source.indexOf("\n", begin);
+  const end = source.indexOf(CODEX_END, contentStart);
+  if (begin < 0 || contentStart < 0 || end < 0) {
+    throw new Error("AGENTS.md does not contain the generated Codex spec");
+  }
+  return source.slice(contentStart + 1, end).trim();
+}
+
+function replaceSection(markdown, heading, body) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
+}
+
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
+function adapt(sourceSpec) {
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec — a missing anchor no-ops silently and drops Prime-specific
+  // wording (see the tool_call gate incident). Fail the render loudly instead.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Prime Agent"],
+    ["Codex-native", "Prime-native"],
+    ["Codex sessions", "Prime Agent sessions"],
+    ["On Codex", "On Prime Agent"],
+    ["Codex has no", "Prime Agent has no built-in"],
+    ["bin/codex-session-start.sh", "bin/prime-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".prime/agent/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded from the project-local extension)"],
+    ["If this Codex build does not support hooks", "If Prime Agent project extensions are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.prime/agent/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`prime-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
+    .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
+    .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
+
+  text = replaceSection(text, "Egregore on Prime Agent", `You are Prime Agent running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Prime Agent resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of \`CLAUDE.md\`, the behavioral source of truth. Prime Agent loads it through \`.prime/agent/APPEND_SYSTEM.md\`. Egregore workflows are shared from \`.codex/skills/\` through the Agent Skills standard (via \`.agents/skills\` and project settings) and exposed as familiar slash commands by \`.prime/agent/extensions/egregore.ts\`.
+
+Your subagent mechanism (\`rlm(...)\`) spawns Prime Agent child sessions, not Egregore Loom lanes. Ignore Loom routing preambles inside shared skills: run those workflows inline.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Prime Agent extension renders the Egregore startup card (identity, handoffs, team activity) inside the session via \`bin/prime-session-start.sh\`. This works for direct \`prime-agent\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Prime Agent, run \`bash bin/prime-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Prime Agent slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.prime/agent/extensions/egregore.ts\`; the duplicate \`/skill:name\` listings are disabled so each workflow appears once. Natural-language requests work normally — and are the route for any workflow whose name collides with a Prime Agent built-in: **say "update egregore" rather than typing \`/update\`**, which is Prime Agent's own self-updater. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Prime Agent, run referenced \`bin/\` scripts through the IPython kernel (or the bash tool when active), use ordinary shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no UI question surface is available.
+
+The \`egregore\` Python-backed skill exposes the mechanics as kernel functions — \`import egregore\`, then \`egregore.search(query)\`, \`egregore.activity()\`, \`egregore.handoff(to, topic, body)\`, \`egregore.save(message, topic)\`, \`egregore.branch(topic)\`, \`egregore.notify_plan(recipient, message)\`. Prefer these over re-deriving \`bin/\` CLI usage by reading scripts. \`notify_plan\` is proposal-only: approval and dispatch always pass through the explicit human Send / Edit / Cancel checkpoint.
+
+"Get the latest changes" inside a session means \`/reload\` — it re-reads instructions, context files, skills, and extensions from disk. Never \`git pull\`, \`git reset\`, or \`git checkout\` the working branch to pick up updates. When pivoting topics inside a worktree that carries unmerged branch work, create the new branch from the current HEAD, not \`origin/{base}\` — branching from the configured base in such a worktree removes the unmerged files from disk.
+
+Kernel shell escapes can be time-capped by the harness. Egregore \`bin/\` scripts that sync git state or query the connected graph legitimately run 10–120 seconds: run them with a generous timeout (a \`%%bash\` cell, or the longest limit the harness exposes). If a command dies suspiciously fast (~5s) with partial output, treat it as a timeout — rerun once with a longer limit or render the workflow's designed one-line fallback. Never debug data plumbing inside a product workflow. Connected mode works normally here: graph reads and \`bin/search.sh\` enrichment use the instance's configured credentials, and when graph data is degraded say so in one plain line rather than narrating connectivity theories.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Prime Agent\n\nThis file is generated by \`bin/prime-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
+}
+
+const check = process.argv.includes("--check");
+const source = fs.readFileSync(SOURCE, "utf8");
+const sourceSpec = extractSpec(source);
+const rendered = adapt(sourceSpec);
+const manifest = `${JSON.stringify({
+  generatedBy: "bin/prime-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Prime Agent APPEND_SYSTEM delivery from .prime/agent/",
+    "Prime Agent tool_call branch gate incl. ipython classification",
+    "Prime Agent slash-command extension over shared portable skills",
+    "rlm() subagents are not Loom lanes; Loom preambles run inline",
+  ],
+}, null, 2)}\n`;
+
+if (check) {
+  const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
+  if (currentOutput !== rendered || currentManifest !== manifest) {
+    console.error("prime spec out of date — run: bash bin/node-run.sh bin/prime-render-spec.mjs");
+    process.exit(1);
+  }
+  console.log("prime spec up to date");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`prime spec rendered: .prime/agent/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

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

@@ -41,6 +41,7 @@ DESCRIPTION=""
 ARTIFACT_ID=""
 RAW_HTML=0
 SKIP_REFERENCES=0
+ALLOW_ADMIN=0
 PAIR=""
 VERIFY_FIDELITY=0
 FIDELITY_SOURCE=""
@@ -55,6 +56,7 @@ while [[ $# -gt 0 ]]; do
     --verify-fidelity) VERIFY_FIDELITY=1; shift ;;
     --source) FIDELITY_SOURCE="$2"; shift 2 ;;
     --raw-html) RAW_HTML=1; shift ;;
+    --allow-admin) ALLOW_ADMIN=1; shift ;;
     --no-references) SKIP_REFERENCES=1; shift ;;
     *)
       if [ -z "$TYPE" ]; then
@@ -149,6 +151,50 @@ if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
   fi
 fi
 
+# --- Admin-content gate (the refusal documented in bin/lib/permissions.sh) --
+# `admin: true` sources — including backtick-referenced memory files — are
+# refused before any render or upload. An authorized admin (stable identity,
+# github.username alias against egregore.json admins) may proceed only with
+# the explicit --allow-admin confirmation, which is separate from and never
+# replaces normal publication approval. This protects the Egregore surface;
+# repository members can still read raw Git files.
+# shellcheck source=bin/lib/permissions.sh
+source "$SCRIPT_DIR/bin/lib/permissions.sh"
+ADMIN_MARKED=()
+if _is_admin_only_file "$FILE"; then
+  ADMIN_MARKED+=("$FILE")
+fi
+if [ "$RAW_HTML" -eq 0 ]; then
+  while IFS= read -r ref; do
+    [ -z "$ref" ] && continue
+    rel="${ref#\`}"
+    rel="${rel%\`}"
+    if [ -f "$SCRIPT_DIR/$rel" ] && _is_admin_only_file "$SCRIPT_DIR/$rel"; then
+      ADMIN_MARKED+=("$rel")
+    fi
+  done < <(grep -Eo '`memory/[^`[:space:]]+\.(md|html)`' "$FILE" 2>/dev/null | sort -u)
+fi
+if [ "${#ADMIN_MARKED[@]}" -gt 0 ]; then
+  IS_ADMIN="false"
+  ADMIN_JSON=$(cd "$SCRIPT_DIR" && EGREGORE_ROOT="$SCRIPT_DIR" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.harness_cli admin-status 2>/dev/null) || true
+  IS_ADMIN=$(printf '%s' "$ADMIN_JSON" | jq -r '.admin // false' 2>/dev/null || echo "false")
+  if [ "$IS_ADMIN" != "true" ]; then
+    echo "publish refused: admin-marked content cannot be published by a non-admin member:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "(--allow-admin is available to organization admins only)" >&2
+    exit 5
+  fi
+  if [ "$ALLOW_ADMIN" -ne 1 ]; then
+    echo "publish refused: this content is admin-marked:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "re-run with --allow-admin to confirm publishing admin-marked content" >&2
+    echo "(this confirmation is separate from normal publication approval)" >&2
+    exit 5
+  fi
+fi
+
 # --- Prepare HTML ---
 TMP_HTML="/tmp/egregore-artifacts/publish-$$.html"
 mkdir -p /tmp/egregore-artifacts
@@ -191,13 +237,20 @@ else
   LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
   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 ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; 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
-    if ! npx -y egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+    # 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

package/runtime/codex/bin/quest.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="$ROOT"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.quest_cli "$@"

package/runtime/codex/bin/question.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Runtime-neutral shell adapter for canonical asynchronous questions.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+exec python3 -m egregore_runtime.question_cli "$@"

package/runtime/codex/bin/research-ingest.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Typed Runtime boundary for approved meeting/interview analysis packages.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+EGREGORE_ROOT="$ROOT" PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+  exec python3 -m egregore_runtime.research_ingest_cli "$@"

package/runtime/codex/bin/restore-owned-skills.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# restore-owned-skills.sh — keep org-owned skills intact through a framework update.
+#
+# Org-owned skills are declared in egregore.json → owned_skills[]. The /update
+# overlay stamps upstream framework paths (including .claude/skills/) over the
+# working tree. This script runs AFTER the overlay and BEFORE the update
+# commit. For every owned skill name:
+#
+#   - upstream does NOT ship that name  → nothing to do (the overlay never
+#     touched it; local edits, committed or not, are left alone)
+#   - upstream DOES ship that name      → the org's committed version wins:
+#     the skill directory is reset to HEAD and the collision is reported so
+#     the org can rename theirs or explicitly adopt upstream's
+#   - collision but no committed org version → upstream's copy stays (there is
+#     nothing to restore); the report says to commit and re-run /update
+#
+# Runtime-neutral: called from every harness's update flow. Idempotent; exits
+# 0 silently when owned_skills is absent or empty.
+#
+# Usage: restore-owned-skills.sh [--upstream-ref <ref>]   (default upstream/main)
+
+set -uo pipefail
+
+UPSTREAM_REF="upstream/main"
+if [ "${1:-}" = "--upstream-ref" ] && [ -n "${2:-}" ]; then
+  UPSTREAM_REF="$2"
+fi
+
+command -v jq >/dev/null 2>&1 || exit 0
+[ -f egregore.json ] || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+OWNED=$(jq -r '.owned_skills // [] | .[]' egregore.json 2>/dev/null)
+[ -n "$OWNED" ] || exit 0
+
+while IFS= read -r name; do
+  [ -n "$name" ] || continue
+  case "$name" in
+    */*|.*|*..*|*' '*)
+      echo "  ⚠ owned_skills: invalid name '$name' — skipped" >&2
+      continue
+      ;;
+  esac
+  SKILL_PATH=".claude/skills/$name"
+
+  # Only a name collision needs work — an org-only skill is never touched by
+  # the overlay, and resetting it here would destroy uncommitted local edits.
+  if ! git ls-tree -d "$UPSTREAM_REF" -- "$SKILL_PATH" 2>/dev/null | grep -q .; then
+    continue
+  fi
+
+  if git cat-file -e "HEAD:$SKILL_PATH" 2>/dev/null; then
+    # Wipe the overlay's copy (index + tree), then restore the org's committed
+    # version. rm+checkout also drops upstream-only files inside the dir.
+    git rm -r --cached --quiet -- "$SKILL_PATH" 2>/dev/null || true
+    rm -rf "$SKILL_PATH"
+    git checkout HEAD -- "$SKILL_PATH" 2>/dev/null || true
+    echo "  ◐ owned skill '$name': upstream ships a skill with this name — kept yours."
+    echo "    Review upstream's version: git diff HEAD $UPSTREAM_REF -- $SKILL_PATH"
+  else
+    echo "  ⚠ owned skill '$name': upstream ships this name and you have no committed version — upstream's copy is in the tree. Commit yours and re-run /update to keep it."
+  fi
+done <<EOF
+$OWNED
+EOF
+
+exit 0