create-egregore 0.19.3 → 0.19.6

package/runtime/pi/bin/codex-install-skills.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Make Egregore's project-local Codex skills available without duplicating
+# them in CODEX_HOME.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCE_DIR="$SCRIPT_DIR/.codex/skills"
+HOOKS_FILE="$SCRIPT_DIR/.codex/hooks.json"
+HOOKS_DIR="$SCRIPT_DIR/.codex/hooks"
+CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
+TARGET_DIR="$CODEX_HOME_DIR/skills"
+
+[ -d "$SOURCE_DIR" ] || exit 0
+
+# Current Codex discovers project skills via .agents/skills (and follows
+# symlinks). The repo commits .agents/skills -> ../.codex/skills; repair it
+# here for checkouts that lost the symlink (zip downloads, some Windows
+# clones). Never clobber a real directory the user created.
+AGENTS_DIR="$SCRIPT_DIR/.agents"
+AGENTS_LINK="$AGENTS_DIR/skills"
+if [ ! -e "$AGENTS_LINK" ] && [ ! -L "$AGENTS_LINK" ]; then
+  mkdir -p "$AGENTS_DIR"
+  ln -s ../.codex/skills "$AGENTS_LINK" 2>/dev/null || true
+fi
+
+is_egregore_skill() {
+  local file="$1"
+  [ -f "$file" ] || return 1
+  grep -q 'Egregore' "$file" 2>/dev/null || return 1
+  grep -Eq 'bin/agent\.sh|bin/activity-data\.sh|bin/codex-skill-render\.mjs|Native Codex|generated-by: bin/codex-sync-skills\.sh|\.claude/skills' "$file" 2>/dev/null
+}
+
+installed=0
+for skill_dir in "$SOURCE_DIR"/*; do
+  [ -d "$skill_dir" ] || continue
+  [ -f "$skill_dir/SKILL.md" ] || continue
+  installed=$((installed + 1))
+done
+
+# Current Codex loads project-local .codex/skills from --cd. Older Egregore
+# builds copied the same skills globally, which makes Codex show duplicates.
+# Default to local-only and remove legacy global copies that are recognizably
+# Egregore-managed. Set EGREGORE_CODEX_INSTALL_GLOBAL=1 for older Codex builds.
+if [ "${EGREGORE_CODEX_INSTALL_GLOBAL:-0}" != "1" ]; then
+  removed=0
+  if [ -d "$TARGET_DIR" ]; then
+    for skill_dir in "$SOURCE_DIR"/*; do
+      [ -d "$skill_dir" ] || continue
+      [ -f "$skill_dir/SKILL.md" ] || continue
+      name="$(basename "$skill_dir")"
+      target="$TARGET_DIR/$name/SKILL.md"
+      if cmp -s "$skill_dir/SKILL.md" "$target" 2>/dev/null || is_egregore_skill "$target"; then
+        rm -rf "$TARGET_DIR/$name"
+        removed=$((removed + 1))
+      fi
+    done
+  fi
+  hooks_ready=0
+  if [ -f "$HOOKS_FILE" ] && [ -d "$HOOKS_DIR" ]; then
+    hooks_ready=1
+  fi
+  echo "codex project skills ready: $installed (removed global duplicates: $removed; hooks ready: $hooks_ready)"
+  exit 0
+fi
+
+mkdir -p "$TARGET_DIR"
+
+copied=0
+for skill_dir in "$SOURCE_DIR"/*; do
+  [ -d "$skill_dir" ] || continue
+  [ -f "$skill_dir/SKILL.md" ] || continue
+  name="$(basename "$skill_dir")"
+  mkdir -p "$TARGET_DIR/$name"
+  cp -R "$skill_dir/." "$TARGET_DIR/$name/"
+  copied=$((copied + 1))
+done
+
+echo "codex global skills installed: $copied"

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

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+// Derive the Codex-native Egregore behavioral spec from CLAUDE.md.
+//
+// CLAUDE.md is the single source of truth for egregore behavior. Codex does
+// not read CLAUDE.md — it reads AGENTS.md (root, concatenated, 32 KiB cap).
+// This script renders CLAUDE.md into a generated block inside AGENTS.md the
+// same way bin/codex-sync-skills.sh derives skills: deterministic transform,
+// explicit per-section adaptation, manifest of what was adapted or dropped.
+//
+//   node bin/codex-render-spec.mjs            # render AGENTS.md + manifest
+//   node bin/codex-render-spec.mjs --check    # exit 1 if rendered output is stale
+//
+// Adaptation rules (the DECIDED option-b translations):
+//   EnterWorktree            -> bin/agent.sh branch / git checkout fallback
+//   AskUserQuestion          -> numbered options in plain text
+//   hook-dependent behavior  -> .codex/hooks equivalent where it exists,
+//                               stated as an instruction where it doesn't
+//   Claude-only mechanics    -> dropped explicitly (recorded in the manifest)
+//   /command tokens          -> $skill tokens when a Codex skill of that name exists
+//
+// Manifest: .codex/spec-manifest.json — one entry per CLAUDE.md section with
+// action (keep|replace), the source section hash, and a note explaining the
+// translation. `replace` sections embed hand-authored Codex-native bodies;
+// when the source section changes, the recorded hash goes stale and --check
+// fails, forcing a review of the translation.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CLAUDE_MD = path.join(ROOT, 'CLAUDE.md');
+const AGENTS_MD = path.join(ROOT, 'AGENTS.md');
+const MANIFEST = path.join(ROOT, '.codex', 'spec-manifest.json');
+
+const BEGIN = '<!-- BEGIN GENERATED EGREGORE CODEX SPEC — derived from CLAUDE.md by bin/codex-render-spec.mjs; do not edit by hand -->';
+const END = '<!-- END GENERATED EGREGORE CODEX SPEC -->';
+
+// Hand-authored top of AGENTS.md, owned by this script so it can never be lost
+// on regeneration. Opens with the runtime-precedence guard: Claude Code reads
+// CLAUDE.md (and now loads root AGENTS.md automatically), so the first thing it
+// must see here is an instruction to defer. Codex / shell-only agents read past
+// the guard into the thin protocol and the generated spec below.
+const AGENTS_PREAMBLE = `# Egregore Agent Protocol
+
+> **Runtime precedence — read this first.**
+>
+> **If you are Claude Code** (or any agent that loads \`.claude/\`): **stop here.**
+> Your authoritative instructions are \`CLAUDE.md\` and \`.claude/\`. Follow the
+> SessionStart greeting and the branch-on-first-message rule there. Do **not**
+> follow the startup steps below and do **not** use \`bin/agent.sh\` for work an
+> Egregore skill already covers. This file exists only for runtimes that cannot
+> read \`CLAUDE.md\`.
+>
+> **If you are Pi** (the \`pi\` coding-agent harness): **stop here.** Your
+> authoritative Egregore instructions are loaded from
+> \`.pi/APPEND_SYSTEM.md\`, and your workflows are exposed through the
+> project-local \`.pi/\` runtime. Do not follow the Codex-specific block below.
+>
+> **If you are Codex or another shell-only agent:** this file is yours — continue.
+
+Egregore is no longer only a Claude Code workspace. Claude Code remains the
+first-class integrated runtime through \`.claude/\` and \`CLAUDE.md\`; any other
+agent that can run shell commands in this checkout participates through the
+portable memory protocol below.
+
+## Startup
+
+1. Read \`egregore.json\` for the instance name, GitHub owner, and managed repos.
+2. Run \`bin/agent.sh sync\` to pull the latest shared memory.
+3. Read \`memory/people/\` to learn collaborator handles.
+4. Run \`bin/agent.sh activity --for <your-handle>\` to inspect handoffs and
+   pending questions addressed to you.
+
+## Communication
+
+Use the runtime-neutral bridge instead of Claude Code slash commands:
+
+\`\`\`bash
+bin/agent.sh branch --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh wrap --from alice --topic "auth review" \\
+  --summary "Implemented the OAuth callback parser and documented follow-ups." \\
+  --body "Open threads: review error cases and browser redirects."
+
+bin/agent.sh handoff --from alice --to bob --topic "auth review" \\
+  --body "Implemented the OAuth callback parser. Bob should review error cases."
+
+bin/agent.sh ask --from bob --to alice --topic "auth review" \\
+  --question "Should invalid state redirect to login or return 400?"
+
+bin/agent.sh answer --from alice \\
+  --question memory/knowledge/questions/2026-04-26-bob-to-alice-auth-review.md \\
+  --body "Return 400 in the API path; redirect only in browser routes."
+\`\`\`
+
+Each command writes to the existing Git-backed \`memory/\` repository and pushes
+when the memory repo has an \`origin\` remote. Agents that cannot run shell may
+write the same markdown files directly, following \`docs/AGENT-PROTOCOL.md\`.
+
+## Handoffs vs Emissaries
+
+\`bin/agent.sh handoff\` is the runtime-neutral path for internal team
+session-handoffs: it writes to \`memory/handoffs/\`, updates the index, and uses
+the same \`bin/handoff-run.sh\` machinery as Claude Code's \`/handoff\`.
+
+Portable external capsules are **emissaries**, not team handoffs. Claude Code
+routes those through \`/emissary\`; non-Claude agents should use the
+\`egregore-emissary\` CLI/skill when it is installed. Do not use the deprecated
+\`egregore-handoff\` CLI for Egregore project \`/handoff\` work.
+
+## Compatibility
+
+Claude Code users continue using \`/handoff\`, \`/activity\`, \`/ask\`, \`/save\`, and
+other skills — driven by \`CLAUDE.md\`, not this file. Non-Claude agents use
+\`bin/agent.sh\` and the file protocol, with the full Codex behavioral spec in the
+generated block below. Both paths converge on the same \`memory/\` files.`;
+
+function sha(text) {
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 12);
+}
+
+// ── fence-aware section splitter ────────────────────────────────────────
+// Splits markdown into the intro (before the first H2) and one chunk per H2.
+// `## ` lines inside ``` fences do not start sections.
+function splitSections(markdown) {
+  const lines = markdown.split('\n');
+  const sections = [];
+  let current = { heading: '(intro)', body: [] };
+  let inFence = false;
+  for (const line of lines) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && /^## /.test(line)) {
+      sections.push(current);
+      current = { heading: line.replace(/^## /, '').trim(), body: [] };
+      continue;
+    }
+    current.body.push(line);
+  }
+  sections.push(current);
+  return sections.map((s) => ({ heading: s.heading, body: s.body.join('\n').replace(/^\n+/, '').replace(/\n+$/, '') }));
+}
+
+// ── /command -> $skill token transform (outside code fences) ────────────
+// Deterministic: every backticked /token becomes a $skill token except a
+// static denylist of Claude Code harness features that are not Egregore
+// skills on any runtime. Consulting the local .codex/skills directory here
+// would make the rendered output depend on which instance ran the render
+// (public checkouts carry fewer skills than the source repo).
+const NON_SKILL_TOKENS = new Set(['loop', 'fast', 'config', 'clear', 'help']);
+
+function transformTokens(body) {
+  const lines = body.split('\n');
+  let inFence = false;
+  const out = lines.map((line) => {
+    if (/^```/.test(line.trim())) {
+      inFence = !inFence;
+      return line;
+    }
+    if (inFence) return line;
+    return line.replace(/`\/([a-z][a-z0-9-]*)((?: [^`]*)?)`/g, (match, name, args) =>
+      NON_SKILL_TOKENS.has(name) ? match : `\`$${name}${args}\``
+    );
+  });
+  return out.join('\n');
+}
+
+// ── hand-authored Codex-native section bodies ────────────────────────────
+// Each is the option-b translation of the matching CLAUDE.md section. The
+// manifest records the source hash so drift is caught by --check.
+
+const INTRO_BODY = `You are a collaborator inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md (the source of truth for egregore behavior) by \`bin/codex-render-spec.mjs\`. The per-section adaptation manifest is \`.codex/spec-manifest.json\`. The thin agent protocol above this block applies to every shell-capable agent; this block is the full behavioral contract for Codex sessions.`;
+
+const ON_LAUNCH_BODY = `The \`egregore\` launcher renders the Egregore startup card (identity, team momentum, and pending work) via \`bin/codex-session-start.sh\` before Codex starts, and installs project skills. 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, run \`bash bin/codex-session-start.sh --card\`.`;
+
+const AFTER_GREETING_BODY = `**Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
+
+1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
+2. Run \`bin/agent.sh branch --topic "<topic>"\` — it creates a work branch from \`origin/develop\` in a task worktree (\`dev/{author}/{slug}\`, or \`feature/{slug}\` / \`bugfix/{slug}\` when the topic reads as a feature or fix) and prints the worktree path. Continue all file work from that printed path.
+3. Confirm: \`On {branch} (worktree).\`
+
+**Fallback:** If \`bin/agent.sh branch\` fails, use \`git checkout -b dev/{author}/{slug} origin/develop\`.
+
+4. Update graph (fire-and-forget): \`bash bin/graph-op.sh set-topic "$(cat .egregore-session-id 2>/dev/null)" "topic from slug" "dev/author/slug" 2>/dev/null &\`
+
+### Handoff claiming
+
+If \`addressed_to_user\` handoffs exist and the user is picking one up, create the IMPLEMENTS link after branch creation:
+\`\`\`bash
+bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
+\`\`\`
+
+**Auto-checkout repos from handoff**: After claiming, check the \`addressed_rich\` context for \`repoState\`. If the handoff includes repo state (non-empty \`repoState\` array), check out the handoff's branches in each managed repo:
+
+\`\`\`bash
+PARENT_DIR="$(cd .. && pwd)"
+# For each entry in repoState:
+REPO_DIR="$PARENT_DIR/$REPO_NAME"
+if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
+  git -C "$REPO_DIR" fetch origin "$BRANCH" --quiet 2>/dev/null
+  git -C "$REPO_DIR" checkout "$BRANCH" 2>/dev/null || \\
+    git -C "$REPO_DIR" checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null
+fi
+\`\`\`
+
+Report results: \`✓ Checked out {branch} in {repo1}, {repo2}\`. If a branch no longer exists (PR was merged): \`◐ {repo}: PR #{N} merged — on {base}\`. If \`repoState\` is absent or empty, skip auto-checkout silently.
+
+**Exceptions** — skip branching when:
+- The user explicitly created or named a branch themselves
+- Already on a working branch AND the user's intent continues the current branch's topic
+
+**Topic pivot while on a working branch:** If the user describes work **unrelated** to the current branch's topic, treat it as a new topic and create a new branch (\`bin/agent.sh branch --topic "<new topic>"\`). Do NOT mix unrelated work on one branch.
+
+If on develop after two messages, create a branch immediately from whatever context you have.
+
+### Branch-guard protocol
+
+The \`.codex/hooks/branch-guard.js\` PreToolUse hook (enabled by the launcher via \`--enable hooks\`) denies writes, patches, and commits on \`develop\`/\`main\`/\`master\`. When it fires, choose between two paths based on how clear the topic is:
+
+- **Topic is obvious from the last turn** (user said "fix X", "add Y feature") → auto-branch silently with \`bin/agent.sh branch --topic "<topic>"\` (or the git checkout fallback), then continue. Say one sentence ("Creating \`dev/{author}/{slug}\`.") so the user isn't confused about why a new branch appeared.
+- **Topic is ambiguous** (open-ended exploration, user didn't specify what we're building yet) → ask **before** branching, in plain text with numbered options (Codex has no structured question tool):
+
+  \`\`\`text
+  Need a working branch first. Topic?
+    1. <suggested slug from context>
+    2. <alternative slug>
+    3. Other: (name it)
+  \`\`\`
+
+  Wait for the reply, then branch.
+
+If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on develop/main/master.
+
+### Onboarding exception
+
+If the startup card output contains \`onboarding_needed\`, invoke the \`$onboarding\` skill instead of greeting.`;
+
+const COMMAND_AWARENESS_PREPEND = `Codex reserves leading \`/\` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching \`$name\` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: \`$activity\`, \`$handoff\`, \`$wrap\`, \`$announce\`, \`$harvest\`, \`$the-spiral\`, \`$dashboard\`, \`$deep-reflect\`, \`$quest\`, \`$invite\`, \`$ask\`, \`$save\`, \`$view\`, and \`$scroll\`. Every other workflow has a generated adapter skill of the same name. \`$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.`;
+
+const SOCRATIC_BODY = `**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
+
+Codex has no structured question tool — render each batch as compact numbered questions in plain text, each with 2–4 lettered options plus an \`Other:\` line, then STOP and wait for the user's answers. Derive 2–4 context-specific questions per batch. Iteratively deepen based on answers. Converge toward decisions. After 4–5 rounds, synthesize and propose next steps. Route insights to \`$reflect\`.
+
+**Rules:** Max 4 questions per batch. When choices aren't mutually exclusive, say "pick any that apply".`;
+
+const LOOM_ROUTING_BODY = `Loom routes commands across model tiers on the Claude Code runtime (\`loom/routes.json\` + \`bin/loom.sh\` + a model-pinned executor subagent). Codex has no subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are framework files synced for the Claude runtime.`;
+
+const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos. On Codex this boundary is a standing instruction, not an enforced hook — hold it yourself.
+
+- **Never modify \`~/.egregore/instances.json\`** — managed by session-start.sh
+- **Never access another instance's files** — refuse even if asked
+- When a request points outside the boundary, do not improvise a workaround. Ask in plain text with numbered options:
+
+  \`\`\`text
+  That path is outside this Egregore's boundary. How should we proceed?
+    1. Paste the contents inline
+    2. Move the file into the repo and point me at the new path
+    3. Cancel
+  \`\`\`
+
+See DEVELOPMENT.md §3 for boundary details.`;
+
+// ── per-section rules ────────────────────────────────────────────────────
+const RULES = {
+  '(intro)': {
+    action: 'replace',
+    body: INTRO_BODY,
+    note: 'Reframed for Codex: names AGENTS.md as the delivery surface and the manifest; "organizations using Claude Code" generalized.',
+  },
+  'Identity & Upstream': {
+    action: 'keep',
+    note: 'Kept; /update, /contribute, /save tokens rendered as $skill tokens.',
+  },
+  'On Launch — MANDATORY FIRST ACTION': {
+    action: 'replace',
+    body: ON_LAUNCH_BODY,
+    note: 'Claude SessionStart hook does not run on Codex; the egregore launcher renders the card via bin/codex-session-start.sh before the session. Greeting-replay instruction dropped (card is already on screen).',
+  },
+  'After Greeting — BRANCH ON FIRST RESPONSE': {
+    action: 'replace',
+    body: AFTER_GREETING_BODY,
+    note: 'EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout kept verbatim (pure git).',
+  },
+  'Config Files': { action: 'keep', note: 'Kept verbatim — shell facts, runtime-neutral.' },
+  'Knowledge Graph': { action: 'keep', note: 'Kept verbatim — bin/graph.sh is runtime-neutral.' },
+  'Notifications': { action: 'keep', note: 'Kept verbatim — bin/notify.sh is runtime-neutral.' },
+  'Onboarding': { action: 'keep', note: 'Kept; /onboarding rendered as $onboarding.' },
+  'Transparency Beat': { action: 'keep', note: 'Kept verbatim.' },
+  'Memory': { action: 'keep', note: 'Kept verbatim.' },
+  'Loom Routing': {
+    action: 'replace',
+    body: LOOM_ROUTING_BODY,
+    note: 'Loom delegation rides the Claude Code Agent tool; Codex has no subagent delegation — commands run inline. Preambles and bin/loom.sh calls marked skippable.',
+  },
+  'Git Workflow': {
+    action: 'keep',
+    note: 'Kept; slash tokens rendered as $skill tokens. Branch diagram unchanged (code fence).',
+  },
+  'Working Conventions': { action: 'keep', note: 'Kept verbatim.' },
+  'Command Awareness': {
+    action: 'keep',
+    prepend: COMMAND_AWARENESS_PREPEND,
+    note: 'Prepended the Codex command surface (skill tokens, native vs adapter split, $save abstraction); disambiguation map kept with /x -> $x token rendering. Tokens with no Codex skill (e.g. /loop, a Claude Code harness feature) are left as-is.',
+  },
+  'Socratic Questioning (MANDATORY)': {
+    action: 'replace',
+    body: SOCRATIC_BODY,
+    note: 'AskUserQuestion -> numbered plain-text question batches with explicit stop-and-wait; multiSelect -> "pick any that apply".',
+  },
+  'Telemetry': { action: 'keep', note: 'Kept verbatim — bin/telemetry.sh is runtime-neutral.' },
+  'Mode': { action: 'keep', note: 'Kept; /env and /checkup rendered as $skill tokens.' },
+  'Environment Isolation': {
+    action: 'replace',
+    body: ISOLATION_BODY,
+    note: 'boundary-check is a Claude PreToolUse hook with no .codex equivalent — behavior stated as a standing instruction; AskUserQuestion remediation -> numbered options.',
+  },
+};
+
+// ── render ───────────────────────────────────────────────────────────────
+function render() {
+  const claudeMd = fs.readFileSync(CLAUDE_MD, 'utf-8');
+  const sections = splitSections(claudeMd);
+
+  const manifest = [];
+  const parts = [];
+
+  for (const section of sections) {
+    const rule = RULES[section.heading];
+    if (!rule) {
+      console.error(`codex-render-spec: no rule for CLAUDE.md section "${section.heading}" — add one to RULES in bin/codex-render-spec.mjs`);
+      process.exit(1);
+    }
+    const sourceHash = sha(section.body);
+    manifest.push({ section: section.heading, action: rule.action, sourceHash, note: rule.note });
+
+    const heading = section.heading === '(intro)' ? '## Egregore on Codex' : `## ${section.heading}`;
+    let body;
+    if (rule.action === 'replace') {
+      body = rule.body;
+    } else {
+      body = transformTokens(section.body);
+      if (rule.prepend) body = `${rule.prepend}\n\n${body}`;
+    }
+    parts.push(`${heading}\n\n${body}`);
+  }
+
+  for (const heading of Object.keys(RULES)) {
+    if (!sections.some((s) => s.heading === heading)) {
+      console.error(`codex-render-spec: RULES contains "${heading}" but CLAUDE.md has no such section — remove or update the rule`);
+      process.exit(1);
+    }
+  }
+
+  const block = `${BEGIN}\n\n${parts.join('\n\n---\n\n')}\n\n${END}`;
+  return { block, manifest };
+}
+
+// AGENTS.md is fully owned by this script: the guard preamble plus the generated
+// spec block. Reconstructing it deterministically (rather than splicing into the
+// existing file) guarantees the runtime-precedence guard is always present and
+// correct — it cannot be stripped by an upstream sync or a hand edit.
+function assembleAgentsMd(block) {
+  return `${AGENTS_PREAMBLE.trim()}\n\n${block}\n`;
+}
+
+const check = process.argv.includes('--check');
+const { block, manifest } = render();
+const manifestJson = `${JSON.stringify({ generatedBy: 'bin/codex-render-spec.mjs', source: 'CLAUDE.md', sections: manifest }, null, 2)}\n`;
+
+const currentAgents = fs.existsSync(AGENTS_MD) ? fs.readFileSync(AGENTS_MD, 'utf-8') : '';
+const nextAgents = assembleAgentsMd(block);
+
+const CODEX_DOC_BUDGET = 32 * 1024;
+if (Buffer.byteLength(nextAgents, 'utf-8') > CODEX_DOC_BUDGET) {
+  console.error(`codex-render-spec: AGENTS.md would be ${Buffer.byteLength(nextAgents, 'utf-8')} bytes — over Codex's ${CODEX_DOC_BUDGET}-byte project-doc budget. Trim CLAUDE.md or tighten translations.`);
+  process.exit(1);
+}
+
+if (check) {
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, 'utf-8') : '';
+  const stale = nextAgents !== currentAgents || manifestJson !== currentManifest;
+  if (stale) {
+    console.error('codex spec out of date — run: node bin/codex-render-spec.mjs');
+    process.exit(1);
+  }
+  console.log('codex spec up to date');
+} else {
+  fs.writeFileSync(AGENTS_MD, nextAgents);
+  fs.writeFileSync(MANIFEST, manifestJson);
+  console.log(`codex spec rendered: AGENTS.md (${Buffer.byteLength(nextAgents, 'utf-8')} bytes), .codex/spec-manifest.json (${manifest.length} sections)`);
+}

package/runtime/pi/bin/codex-session-start.sh

@@ -0,0 +1,188 @@
+#!/bin/bash
+set -o pipefail
+
+# Codex does not run Claude Code SessionStart hooks. This is the runtime-neutral
+# startup card: it reuses the same identity, git sync, and context-gathering
+# libraries as Claude's SessionStart, then renders a terminal greeting before
+# Codex itself starts.
+
+FRAMEWORK_VERSION="6"
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$SCRIPT_DIR" || exit 1
+
+IS_WORKTREE="false"
+MAIN_PROJECT_DIR="$SCRIPT_DIR"
+if [ -f "$SCRIPT_DIR/.git" ]; then
+  IS_WORKTREE="true"
+  WT_GITDIR=$(sed 's/^gitdir: //' "$SCRIPT_DIR/.git" 2>/dev/null)
+  MAIN_PROJECT_DIR=$(cd "$WT_GITDIR/../../.." 2>/dev/null && pwd)
+fi
+
+# Clear any branch-guard consent from a previous session — consent to write on
+# a protected branch is asked fresh each session (see AGENTS.md branch-guard protocol).
+rm -f "$SCRIPT_DIR/.egregore-branch-consent" "$MAIN_PROJECT_DIR/.egregore-branch-consent" 2>/dev/null
+
+if [ -f "$SCRIPT_DIR/bin/lib/worktree-links.sh" ]; then
+  source "$SCRIPT_DIR/bin/lib/worktree-links.sh" >/dev/null 2>/dev/null || true
+  egregore_link_shared_state "$SCRIPT_DIR" "$MAIN_PROJECT_DIR" >/dev/null 2>/dev/null || true
+fi
+
+HEALTH_GITHUB="skip"
+HEALTH_GIT="skip"
+HEALTH_APIKEY="skip"
+HEALTH_GRAPH="skip"
+HEALTH_TELEGRAM="skip"
+
+STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
+ENV_FILE="$SCRIPT_DIR/.env"
+CONFIG="$SCRIPT_DIR/egregore.json"
+DATE=$(date +%Y-%m-%d)
+
+source "$SCRIPT_DIR/bin/lib/config.sh"
+source "$SCRIPT_DIR/bin/lib/hash.sh"
+source "$SCRIPT_DIR/bin/lib/time.sh"
+source "$SCRIPT_DIR/bin/lib/identity.sh" >/dev/null 2>/dev/null
+
+LOCAL_MODE="false"
+[ "$(_detect_mode)" = "local" ] && LOCAL_MODE="true"
+
+if [ "$LOCAL_MODE" != "true" ]; then
+  if [ -f "$ENV_FILE" ] && grep -q '^EGREGORE_API_KEY=.' "$ENV_FILE" 2>/dev/null; then
+    HEALTH_APIKEY="ok"
+  else
+    HEALTH_APIKEY="fail"
+  fi
+fi
+
+source "$SCRIPT_DIR/bin/lib/git-sync.sh" >/dev/null 2>/dev/null
+source "$SCRIPT_DIR/bin/lib/context.sh" >/dev/null 2>/dev/null
+source "$SCRIPT_DIR/bin/lib/metrics.sh" >/dev/null 2>/dev/null
+trap 'rm -rf "${CTX_DIR:-}"' EXIT
+
+read_json() {
+  local file="$1"
+  local expr="$2"
+  local fallback="${3:-}"
+  if [ -f "$file" ] && command -v jq >/dev/null 2>&1; then
+    jq -r "$expr // empty" "$file" 2>/dev/null | head -1
+  else
+    printf '%s\n' "$fallback"
+  fi
+}
+
+ORG_NAME="$(read_json "$CONFIG" '.org_name' '')"
+[ -z "$ORG_NAME" ] && ORG_NAME="$(read_json "$CONFIG" '.slug' 'Egregore')"
+GITHUB_ORG="$(read_json "$CONFIG" '.github_org' '')"
+REPO_NAME="$(read_json "$CONFIG" '.repo_name' 'egregore')"
+SLUG="$(read_json "$CONFIG" '.slug' '')"
+DISPLAY_NAME="$(read_json "$STATE_FILE" '.display_name' '')"
+[ -z "$DISPLAY_NAME" ] && DISPLAY_NAME="${DISPLAY_NAME_STATE:-$AUTHOR}"
+ONBOARDING_COMPLETE="$(read_json "$STATE_FILE" '.onboarding_complete' '')"
+[ -z "$ONBOARDING_COMPLETE" ] && ONBOARDING_COMPLETE="unknown"
+
+ADDRESSED_RICH="$(cat "$CTX_DIR/addressed_rich" 2>/dev/null || echo "[]")"
+PENDING_Q="$(cat "$CTX_DIR/pending_questions" 2>/dev/null || echo "[]")"
+ADDRESSED_COUNT="$(echo "$ADDRESSED_RICH" | jq 'length' 2>/dev/null || echo "0")"
+PENDING_Q_COUNT="$(echo "$PENDING_Q" | jq 'length' 2>/dev/null || echo "0")"
+
+render_pending_line() {
+  if [ "$PENDING_Q_COUNT" -gt 0 ] 2>/dev/null; then
+    local senders noun
+    senders="$(echo "$PENDING_Q" | jq -r '[.[].from] | unique | join(", ")' 2>/dev/null)"
+    [ "$PENDING_Q_COUNT" = "1" ] && noun="question" || noun="questions"
+    if [ -n "$senders" ]; then
+      printf '  ◐ %s pending %s from %s - bin/agent.sh answer\n' "$PENDING_Q_COUNT" "$noun" "$senders"
+    else
+      printf '  ◐ %s pending %s - bin/agent.sh answer\n' "$PENDING_Q_COUNT" "$noun"
+    fi
+  elif [ "$ADDRESSED_COUNT" -gt 0 ] 2>/dev/null; then
+    printf '  ◇ %s handoffs for %s - bin/agent.sh activity --for %s\n' "$ADDRESSED_COUNT" "$AUTHOR" "$AUTHOR"
+  fi
+}
+
+banner() {
+  cat <<'EOF'
+
+  ███████╗ ██████╗ ██████╗ ███████╗ ██████╗  ██████╗ ██████╗ ███████╗
+  ██╔════╝██╔════╝ ██╔══██╗██╔════╝██╔════╝ ██╔═══██╗██╔══██╗██╔════╝
+  █████╗  ██║  ███╗██████╔╝█████╗  ██║  ███╗██║   ██║██████╔╝█████╗
+  ██╔══╝  ██║   ██║██╔══██╗██╔══╝  ██║   ██║██║   ██║██╔══██╗██╔══╝
+  ███████╗╚██████╔╝██║  ██║███████╗╚██████╔╝╚██████╔╝██║  ██║███████╗
+  ╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚══════╝
+
+EOF
+}
+
+render_card() {
+  local separator identity_left identity_right line_width pad footer_left footer_right board_url has_failure failed_services
+  separator="  ..................................................................."
+  identity_left="  ${GITHUB_ORG:-$ORG_NAME}/${REPO_NAME}"
+  identity_right="${DISPLAY_NAME} · ${BRANCH:-?}"
+  line_width=67
+  pad=$((line_width - ${#identity_left} - ${#identity_right}))
+  [ "$pad" -lt 1 ] && pad=1
+
+  banner
+  printf '%s%*s%s\n' "$identity_left" "$pad" "" "$identity_right"
+  printf '%s\n' "$separator"
+  SEPARATOR="$separator" LINE_WIDTH=$line_width _render_momentum_board
+  render_pending_line
+  printf '%s\n' "$separator"
+
+  has_failure="false"
+  failed_services=""
+  for pair in "github:$HEALTH_GITHUB" "git:$HEALTH_GIT" "api-key:$HEALTH_APIKEY" "graph:$HEALTH_GRAPH" "telegram:$HEALTH_TELEGRAM"; do
+    svc="${pair%%:*}"
+    svc_status="${pair#*:}"
+    if [ "$svc_status" = "fail" ]; then
+      has_failure="true"
+      failed_services="${failed_services} ${svc} ✗"
+    fi
+  done
+
+  if [ "$has_failure" = "true" ]; then
+    printf '  ⚠%s\n' "$failed_services"
+  else
+    footer_left="  ✓ ready"
+    if [ "${MEMORY_SYNCED:-false}" = "true" ]; then
+      footer_right="◆ memory synced"
+    else
+      footer_right="◆ memory not synced"
+    fi
+    pad=$((line_width - ${#footer_left} - ${#footer_right}))
+    [ "$pad" -lt 1 ] && pad=1
+    printf '%s%*s%s\n' "$footer_left" "$pad" "" "$footer_right"
+  fi
+
+  if [ -n "$SLUG" ]; then
+    board_url="https://egregore.xyz/view/${SLUG}/board"
+    printf '  ◆ %s\n' "$board_url"
+  fi
+  printf '\nWhat are you working on?\n'
+}
+
+case "${1:---card}" in
+  --card|card)
+    render_card
+    ;;
+  --prompt|prompt)
+    cat <<EOF
+You are Codex running inside Egregore for ${ORG_NAME} as ${AUTHOR}.
+The launcher already rendered the Egregore startup card using the shared identity, git-sync, graph, and filesystem context pipeline.
+This session is Trusted Codex: full shell/network access is enabled and approval prompts are disabled by the launcher.
+Do not rerun startup checks or narrate startup unless the user asks.
+Follow AGENTS.md before code changes.
+After the user names what they are working on, use bin/agent.sh branch --topic "<work topic>" if you are not already in an appropriate task worktree, then continue file work from the printed worktree path.
+Use bin/agent.sh to update shared activity: handoff, ask, and answer write to memory/ and push when possible.
+Use bin/agent.sh handoff for internal team session-handoffs. Portable external capsules are emissaries; use egregore-emissary when installed, not the deprecated egregore-handoff CLI.
+Codex reserves leading slash commands for built-ins, so custom Egregore /activity-style commands will not reach the agent. Egregore native Codex skills are: \$activity, \$handoff, \$wrap, \$announce, \$harvest, \$the-spiral, \$dashboard, \$deep-reflect, \$quest, \$invite, \$ask, \$save, \$view, and \$scroll. Natural-language requests such as "show activity", "make a handoff", or "render this as a scroll" work too. Remaining mirrored workflows are adapter skills for long-tail coverage.
+\$save is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory; do not make users manage the git workflow by hand.
+Egregore Codex workflows are skill invocations, not Claude Code slash commands. Do not rely on Claude Code-only command machinery.
+If onboarding_complete is false, use the memory protocol directly and make sure memory/people/${AUTHOR}.md exists before the first handoff.
+EOF
+    ;;
+  *)
+    echo "usage: bin/codex-session-start.sh [--card|--prompt]" >&2
+    exit 2
+    ;;
+esac