create-egregore 0.19.5 → 0.19.6

package/runtime/pi/bin/notify.sh

@@ -0,0 +1,207 @@
+#!/bin/bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$SCRIPT_DIR/egregore.json"
+
+if [ ! -f "$CONFIG" ]; then
+  echo "Error: egregore.json not found." >&2
+  exit 1
+fi
+
+# --- Mode detection ---
+_MODE=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
+
+# Public relay for local mode group messages.
+# No API key needed — rate-limited, group messages only.
+RELAY_URL="https://egregore-production-55f2.up.railway.app"
+
+# Load specific variables from .env if it exists (safe extraction, no arbitrary code execution)
+if [ -f "$SCRIPT_DIR/.env" ]; then
+  EGREGORE_API_URL="${EGREGORE_API_URL:-$(grep '^EGREGORE_API_URL=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)}"
+  EGREGORE_API_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "$SCRIPT_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)}"
+fi
+
+# Check if API mode or direct mode
+# api_url comes from egregore.json (committed, non-secret)
+# api_key comes from .env only (EGREGORE_API_KEY) — never from egregore.json
+API_URL="${EGREGORE_API_URL:-$(jq -r '.api_url // empty' "$CONFIG")}"
+API_KEY="${EGREGORE_API_KEY:-}"
+
+if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
+  # === API MODE: Call Egregore API gateway ===
+
+  send_to_person() {
+    local name="$1"
+    local message="$2"
+
+    local response
+    response=$(curl -s -X POST "${API_URL}/api/notify/send" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg to "$name" --arg message "$message" \
+        '{to: $to, message: $message}')" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"send","status":"sent"}' 2>/dev/null &
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "unknown error"')
+      if echo "$detail" | grep -qi "forbidden\|can't initiate\|bot was blocked"; then
+        echo "Failed: DM not available. Tell $name to message the Egregore bot first (/start)."
+      else
+        echo "Failed: $detail"
+      fi
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"send","status":"failed"}' 2>/dev/null &
+    fi
+  }
+
+  send_to_group() {
+    local message="$1"
+
+    local response
+    response=$(curl -s -X POST "${API_URL}/api/notify/group" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n --arg message "$message" '{message: $message}')" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"group","status":"sent"}' 2>/dev/null &
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "unknown error"')
+      echo "Failed: $detail"
+      bash "$SCRIPT_DIR/bin/telemetry.sh" emit "notification" \
+        '{"type":"group","status":"failed"}' 2>/dev/null &
+    fi
+  }
+
+  test_connection() {
+    local response
+    response=$(curl -s -X GET "${API_URL}/api/notify/test" \
+      -H "Authorization: Bearer $API_KEY" \
+      --max-time 10)
+
+    if echo "$response" | jq -e '.status == "ok"' >/dev/null 2>&1; then
+      echo "Telegram connected via Egregore API"
+    else
+      echo "Failed to connect" >&2
+      echo "$response" >&2
+      exit 1
+    fi
+  }
+
+elif [ "$_MODE" = "local" ]; then
+  # === LOCAL MODE: Group messages via public relay, DMs not available ===
+  # Telegram config: prefer .egregore-state.json (symlinked across worktrees),
+  # fall back to egregore.json for backward compatibility.
+  STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+
+  _read_telegram_config() {
+    local field="$1"
+    local val
+    val=$(jq -r ".$field // empty" "$STATE_FILE" 2>/dev/null)
+    [ -z "$val" ] && val=$(jq -r ".$field // empty" "$CONFIG" 2>/dev/null)
+    echo "$val"
+  }
+
+  send_to_person() {
+    echo "DMs require managed hosting. Group message sent instead."
+    send_to_group "@${1}: ${2}"
+  }
+
+  send_to_group() {
+    local message="$1"
+    local chat_id
+    chat_id=$(_read_telegram_config telegram_chat_id)
+    local group_link
+    group_link=$(_read_telegram_config telegram_group_link)
+
+    if [ -z "$chat_id" ] && [ -z "$group_link" ]; then
+      echo '{"status":"offline","reason":"no_telegram_group"}'
+      return
+    fi
+
+    local slug
+    slug=$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)
+    local org_name
+    org_name=$(jq -r '.org_name // empty' "$CONFIG" 2>/dev/null)
+
+    local response
+    response=$(curl -s -X POST "${RELAY_URL}/api/notify/relay" \
+      -H "Content-Type: application/json" \
+      -d "$(jq -n \
+        --arg chat_id "$chat_id" \
+        --arg group_link "$group_link" \
+        --arg message "$message" \
+        --arg slug "$slug" \
+        --arg org_name "$org_name" \
+        '{chat_id: $chat_id, group_link: $group_link, message: $message, slug: $slug, org_name: $org_name}')" \
+      --max-time 10 2>/dev/null)
+
+    if echo "$response" | jq -e '.status == "sent"' >/dev/null 2>&1; then
+      echo "Sent"
+    else
+      local detail
+      detail=$(echo "$response" | jq -r '.detail // .status // "relay unavailable"' 2>/dev/null)
+      echo "Failed: $detail"
+    fi
+  }
+
+  test_connection() {
+    local group_link
+    group_link=$(_read_telegram_config telegram_group_link)
+    if [ -n "$group_link" ]; then
+      echo "Telegram group configured (local mode — group messages via relay)"
+    else
+      echo "No Telegram group configured. Run /telegram-connect."
+    fi
+  }
+
+else
+  # === OFFLINE MODE: No API key, not local — skip notifications ===
+  send_to_person() { echo '{"status":"offline","reason":"no_api_key"}'; }
+  send_to_group() { echo '{"status":"offline","reason":"no_api_key"}'; }
+  test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }
+fi
+
+case "${1:-help}" in
+  send)
+    recipient="${2:?Usage: notify.sh send <name> <message>}"
+    message="${3:?Usage: notify.sh send <name> <message>}"
+    result=$(send_to_person "$recipient" "$message")
+    if [[ "$result" == Failed* ]]; then
+      send_to_group "@${recipient}: ${message}"
+      echo "DM failed, sent to group instead. ${result}"
+    else
+      echo "$result"
+    fi
+    ;;
+  group)
+    message="${2:?Usage: notify.sh group <message>}"
+    send_to_group "$message"
+    ;;
+  file)
+    echo "File upload not yet supported via API. Use direct mode." >&2
+    exit 1
+    ;;
+  test)
+    test_connection
+    ;;
+  help|*)
+    echo "Usage: notify.sh <command>"
+    echo ""
+    echo "Commands:"
+    echo "  send <name> <message>   Send DM to a person (auto-fallback to group on failure)"
+    echo "  group <message>         Send to the group chat"
+    echo "  file <path> [caption]   Send a file to the group chat"
+    echo "  test                    Test connection"
+    ;;
+esac

package/runtime/pi/bin/pi-branch-policy.mjs

@@ -0,0 +1,15 @@
+const MUTATING_COMMANDS = /(^|[;&|]\s*)(rm|mv|cp|mkdir|rmdir|touch|chmod|chown|install)\b/;
+const MUTATING_GIT = /(^|[;&|]\s*)git\s+(add|commit|push|merge|rebase|cherry-pick|tag|rm|mv)\b/;
+const MUTATING_PACKAGES = /(^|[;&|]\s*)(npm|pnpm|yarn|bun)\s+(install|add|remove|uninstall|update)\b/;
+
+export function isMutatingBash(command) {
+  if (!command) return false;
+  const meaningfulRedirects = String(command)
+    .replace(/(?:^|\s)\d*>>?\s*\/dev\/null\b/g, " ")
+    .replace(/(?:^|\s)\d*>\s*&\d+\b/g, " ");
+  return MUTATING_COMMANDS.test(command) ||
+    MUTATING_GIT.test(command) ||
+    MUTATING_PACKAGES.test(command) ||
+    /(^|[^<])>>?\s*[^&]/.test(meaningfulRedirects) ||
+    /\bsed\s+[^\n]*\s-i(?:\s|$)/.test(command);
+}

package/runtime/pi/bin/pi-product-workflows.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+
+const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+
+function resultCode(result) {
+  return Number(result?.code ?? result?.status ?? 0);
+}
+
+function commandFailure(label, result) {
+  const detail = String(result?.stderr || result?.stdout || "").replace(ANSI, "").trim();
+  return new Error(detail ? `${label}: ${detail}` : `${label} failed`);
+}
+
+async function checkedExec(pi, command, args, options = {}, label = command) {
+  const result = await pi.exec(command, args, options);
+  if (resultCode(result) !== 0) throw commandFailure(label, result);
+  return String(result.stdout || "");
+}
+
+function readJson(file, fallback = {}) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function cleanArgs(value) {
+  return String(value || "").trim();
+}
+
+function walkMarkdown(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkMarkdown(full, files);
+    else if (entry.isFile() && entry.name.endsWith(".md")) files.push(full);
+  }
+  return files;
+}
+
+function inferArtifactType(file) {
+  const normalized = file.replaceAll("\\", "/");
+  if (normalized.includes("/memory/quests/")) return "quest";
+  if (normalized.includes("/memory/handoffs/")) return "handoff";
+  return "document";
+}
+
+function matchingFiles(root, type, query) {
+  const base = type === "quest"
+    ? join(root, "memory", "quests")
+    : type === "handoff"
+      ? join(root, "memory", "handoffs")
+      : join(root, "memory");
+  const needle = query.toLowerCase().replace(/\.md$/, "");
+  return walkMarkdown(base)
+    .filter((file) => basename(file, ".md").toLowerCase().includes(needle))
+    .sort((a, b) => b.localeCompare(a));
+}
+
+export function parseViewRequest(root, rawArgs) {
+  const raw = cleanArgs(rawArgs);
+  if (!raw) return { kind: "choose" };
+
+  const fast = /(?:^|\s)--(?:fast|floor)(?:\s|$)/.test(raw);
+  const compose = /(?:^|\s)--compose(?:\s|$)/.test(raw);
+  const cleaned = raw.replace(/(?:^|\s)--(?:fast|floor|compose)(?=\s|$)/g, " ").trim();
+  const surface = cleaned.toLowerCase();
+  if (["activity", "board", "network"].includes(surface)) {
+    return { kind: "native", type: surface, source: "", fast: true };
+  }
+
+  const explicit = cleaned.match(/^(quest|handoff|document)\s+(.+)$/i);
+  const type = explicit?.[1]?.toLowerCase();
+  const target = (explicit?.[2] || cleaned).replace(/^@/, "").trim();
+  const direct = resolve(root, target);
+  if (existsSync(direct)) {
+    const inferred = type || inferArtifactType(direct);
+    if (inferred === "document" && (!fast || compose)) {
+      return { kind: "model", reason: "document-composition", raw };
+    }
+    return { kind: "native", type: inferred, source: direct, fast };
+  }
+
+  if (type) {
+    const matches = matchingFiles(root, type, target);
+    if (matches.length === 1 && (type !== "document" || fast)) {
+      return { kind: "native", type, source: matches[0], fast };
+    }
+    if (matches.length > 1) return { kind: "choose-file", type, matches, fast };
+  }
+
+  return { kind: "model", reason: "resolve-or-synthesize", raw };
+}
+
+function rendererCommand(root) {
+  const local = join(root, "packages", "egregore-artifacts", "bin", "cli.js");
+  const react = join(root, "packages", "egregore-artifacts", "node_modules", "react");
+  if (existsSync(local) && existsSync(react)) return { command: "node", prefix: [local] };
+  return { command: "npx", prefix: ["-y", "egregore-artifacts@latest"] };
+}
+
+function artifactPath(output) {
+  const clean = String(output || "").replace(ANSI, "");
+  const matches = clean.match(/(?:\/[^\s'\"]+|[A-Za-z]:\\[^\r\n'\"]+)\.html/g);
+  return matches?.at(-1) || "";
+}
+
+export async function renderView(pi, root, request, signal) {
+  const renderer = rendererCommand(root);
+  const args = [...renderer.prefix, request.type];
+  if (request.source) args.push(request.source);
+  const output = await checkedExec(
+    pi,
+    renderer.command,
+    args,
+    { signal, timeout: 120000 },
+    "Artifact render",
+  );
+  const file = artifactPath(output);
+  let text = "✓ Artifact opened in browser";
+  if (file) text += `\n  File: ${file}`;
+
+  if (request.type === "board") {
+    const config = readJson(join(root, "egregore.json"));
+    if (config.slug && config.mode !== "local" && config.api_url) {
+      text += `\n◆ https://egregore.xyz/view/${config.slug}/board   (stable — refresh for latest)`;
+    }
+  }
+  return { text, file, type: request.type };
+}
+
+export async function renderGreeting(pi, root, signal) {
+  const script = join(root, "bin", "pi-session-start.sh");
+  if (!existsSync(script)) throw new Error("Pi startup renderer is missing");
+  return checkedExec(pi, "bash", [script, "--card"], { signal, timeout: 45000 }, "Egregore startup");
+}
+
+export async function renderActivity(pi, root, signal, options = {}) {
+  if (options.sync !== false) {
+    await checkedExec(
+      pi,
+      "bash",
+      [join(root, "bin", "agent.sh"), "sync"],
+      { signal, timeout: 120000 },
+      "Memory sync",
+    );
+  }
+
+  const state = readJson(join(root, ".egregore-state.json"));
+  let handle = state.github_username || state.name || "";
+  if (!handle) {
+    handle = (await checkedExec(
+      pi,
+      "git",
+      ["-C", root, "config", "user.name"],
+      { signal, timeout: 5000 },
+      "Identity lookup",
+    )).trim();
+  }
+
+  const json = await checkedExec(
+    pi,
+    "bash",
+    [join(root, "bin", "activity-data.sh"), handle],
+    { signal, timeout: 120000 },
+    "Activity refresh",
+  );
+  const temp = mkdtempSync(join(tmpdir(), "egregore-pi-activity-"));
+  const input = join(temp, "activity.json");
+  try {
+    writeFileSync(input, json);
+    return await checkedExec(
+      pi,
+      "node",
+      [join(root, "bin", "codex-skill-render.mjs"), "activity-card", input],
+      { signal, timeout: 10000 },
+      "Activity render",
+    );
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+function section(title, body) {
+  const value = cleanArgs(body) || "- None recorded.";
+  return `## ${title}\n\n${value}`;
+}
+
+export function buildHandoffDocument(params, author, date = new Date().toISOString().slice(0, 10)) {
+  const lines = [
+    `# Handoff: ${cleanArgs(params.topic)}`,
+    "",
+    `**Date**: ${date}`,
+    `**Author**: ${author}`,
+  ];
+  if (cleanArgs(params.recipient)) lines.push(`**To**: ${cleanArgs(params.recipient)}`);
+  lines.push(
+    "",
+    section("Briefing", params.briefing),
+    "",
+    section("Key Decisions", params.key_decisions),
+    "",
+    section("Current State", params.current_state),
+    "",
+    section("Open Threads", params.open_threads),
+    "",
+    section("Next Steps", params.next_steps),
+    "",
+    section("Entry Points", params.entry_points),
+    "",
+  );
+  return lines.join("\n");
+}
+
+export async function createHandoff(pi, root, params, signal) {
+  const state = readJson(join(root, ".egregore-state.json"));
+  const author = state.github_username || state.name || "egregore";
+  const temp = mkdtempSync(join(tmpdir(), "egregore-pi-handoff-"));
+  const body = join(temp, "handoff.md");
+  const recipient = cleanArgs(params.recipient);
+  const runnerArgs = ["--author", author, "--topic", cleanArgs(params.topic)];
+  if (recipient) runnerArgs.push("--recipient", recipient);
+  writeFileSync(body, buildHandoffDocument(params, author));
+
+  try {
+    const shell = 'tmp="$1"; body="$2"; shift 2; TMPDIR="$tmp" bash bin/handoff-run.sh "$@" < "$body"';
+    await checkedExec(
+      pi,
+      "bash",
+      ["-c", shell, "egregore-pi-handoff", temp, body, ...runnerArgs],
+      { signal, timeout: 180000 },
+      "Handoff",
+    );
+    const resultFile = join(temp, "handoff-run-result.json");
+    if (!existsSync(resultFile)) throw new Error("Handoff completed without a result receipt");
+    const result = readJson(resultFile);
+    const card = await checkedExec(
+      pi,
+      "node",
+      [join(root, "bin", "codex-skill-render.mjs"), "handoff-card", resultFile],
+      { signal, timeout: 10000 },
+      "Handoff receipt",
+    );
+    return {
+      text: card.trim(),
+      path: result.file ? `memory/${result.file}` : "",
+      url: result.artifactUrl || "",
+    };
+  } finally {
+    rmSync(temp, { recursive: true, force: true });
+  }
+}
+
+export async function publishScroll(pi, root, params, signal) {
+  const source = resolve(root, String(params.source || "").replace(/^@/, ""));
+  if (!existsSync(source)) throw new Error(`Scroll source not found: ${relative(root, source)}`);
+  const html = readFileSync(source, "utf8");
+  if (/__[A-Z][A-Z0-9_]*__/.test(html)) throw new Error("Scroll still contains unresolved placeholders");
+
+  const config = readJson(join(root, "egregore.json"));
+  let url = "";
+  if (config.mode !== "local" && config.api_url) {
+    const output = await checkedExec(
+      pi,
+      "bash",
+      [
+        join(root, "bin", "publish-artifact.sh"),
+        "document",
+        source,
+        "--raw-html",
+        "--id",
+        cleanArgs(params.slug),
+        "--title",
+        cleanArgs(params.title),
+        "--author",
+        cleanArgs(params.author),
+        "--description",
+        cleanArgs(params.description),
+      ],
+      { signal, timeout: 180000 },
+      "Scroll publish",
+    );
+    url = String(output).match(/https:\/\/[^\s]+/)?.[0] || "";
+    if (!url) throw new Error("Scroll publish did not return a stable URL");
+    const opener = process.platform === "darwin" ? "open" : "xdg-open";
+    await checkedExec(pi, opener, [url], { signal, timeout: 10000 }, "Open scroll");
+  } else {
+    const opener = process.platform === "darwin" ? "open" : "xdg-open";
+    await checkedExec(pi, opener, [source], { signal, timeout: 10000 }, "Open scroll");
+  }
+
+  const version = cleanArgs(params.version) || "v1";
+  const destination = url || source;
+  return {
+    text: `✓ Scroll ${version} opened\n  ${url ? "URL" : "File"}: ${destination}`,
+    path: source,
+    url,
+    version,
+  };
+}
+
+export function workflowPrompt(name, args, extra = "") {
+  const userArgs = cleanArgs(args);
+  return [
+    `Run the Egregore /${name} workflow now.`,
+    `Read .codex/skills/${name}/SKILL.md completely and adapt Codex-specific wording to Pi using .pi/APPEND_SYSTEM.md.`,
+    "Work quietly: do not narrate progress, expose raw command output, or repeat tool results.",
+    "Use the fewest targeted reads and commands that preserve the workflow contract.",
+    userArgs ? `User arguments: ${userArgs}` : "",
+    extra,
+  ].filter(Boolean).join("\n");
+}

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

@@ -0,0 +1,114 @@
+#!/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)}`;
+}
+
+function adapt(sourceSpec) {
+  let text = sourceSpec
+    .replaceAll("Egregore on Codex", "Egregore on Pi")
+    .replaceAll("Codex-native", "Pi-native")
+    .replaceAll("Codex sessions", "Pi sessions")
+    .replaceAll("On Codex", "On Pi")
+    .replaceAll("from Codex", "from Pi")
+    .replaceAll("inside Codex", "inside Pi")
+    .replaceAll("Codex has no", "Pi has no built-in")
+    .replaceAll("normal sandboxed Codex shell", "the Pi shell")
+    .replaceAll("Codex graph network access", "Pi graph network access")
+    .replaceAll("structured Codex question tooling", "Pi UI question tooling")
+    .replaceAll("structured Codex", "structured Pi")
+    .replaceAll("bin/codex-session-start.sh", "bin/pi-session-start.sh")
+    .replaceAll(".codex/hooks/branch-guard.js", ".pi/extensions/egregore.ts")
+    .replaceAll("PreToolUse hook (enabled by the launcher via `--enable hooks`)", "`tool_call` gate (loaded after Pi project trust)")
+    .replaceAll("If this Codex build does not support hooks", "If Pi project resources are disabled")
+    .replaceAll("change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.pi/` anytime")
+    .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 = replaceSection(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.
+
+Invoke commands from user intent — don't wait for the slash. 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.
+
+**Core loop** — \`/activity\` \`/dashboard\` \`/handoff\` \`/wrap\` \`/save\` \`/reflect\` \`/todo\`
+**Knowledge** — \`/search\` \`/deep-reflect\` \`/archive\` \`/note\` \`/add\` \`/meeting\` \`/ingest\` \`/scroll\`
+**Identity** — \`/me\`
+**Coordination** — \`/ask\` \`/quest\` \`/issue\` \`/invite\` \`/delete-user\` \`/announce\`
+**Git** — \`/branch\` \`/commit\` \`/push\` \`/pr\` \`/save\` \`/review-pr\` \`/contribute\`
+**Infra** — \`/setup\` \`/update\` \`/pull\` \`/env\` \`/infra\` \`/sync-repos\` \`/release\` \`/checkup\``);
+
+  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: node 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/pi/bin/pi-session-start.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -o pipefail
+
+# Pi's project extension invokes this during session_start so direct `pi`
+# launches and launcher-managed sessions share the same greeting experience.
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+case "${1:---card}" in
+  --card|card)
+    exec bash "$SCRIPT_DIR/bin/codex-session-start.sh" --card
+    ;;
+  --prompt|prompt)
+    cat <<'EOF'
+You are Pi running inside Egregore. The project extension renders the startup
+card during session_start. Project instructions are in
+.pi/APPEND_SYSTEM.md, Egregore workflows are
+registered as slash commands, and portable skill bodies live in .codex/skills.
+EOF
+    ;;
+  *)
+    echo "usage: bin/pi-session-start.sh [--card|--prompt]" >&2
+    exit 2
+    ;;
+esac