create-egregore 0.19.33 → 0.20.1

package/runtime/codex/AGENTS.md

@@ -14,6 +14,12 @@
 > `.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 Prime Agent** (the `prime-agent` harness): **stop here.** Your
+> authoritative Egregore instructions are loaded from
+> `.prime/agent/APPEND_SYSTEM.md`, and your workflows are exposed through the
+> project-local `.prime/agent/` 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
@@ -80,7 +86,7 @@ generated block below. Both paths converge on the same `memory/` files.
 
 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.
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md by `bin/codex-render-spec.mjs`; the per-section manifest is `.codex/spec-manifest.json`. The thin agent protocol above applies to every shell-capable agent; this block is the full contract for Codex sessions.
 
 ---
 
@@ -117,7 +123,7 @@ Egregore's voice is governed by `.claude/rules/voice-bedrock.md` (always loaded)
 
 ## On Launch — MANDATORY FIRST ACTION
 
-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`.
+The `egregore` launcher renders the startup card (identity, momentum, pending work) via `bin/codex-session-start.sh` before Codex starts and installs project skills. Do not rerun or 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. Re-show with `bash bin/codex-session-start.sh --card`.
 
 ---
 
@@ -125,20 +131,11 @@ The `egregore` launcher renders the Egregore startup card (identity, team moment
 
 **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:
 
-The integration branch is `develop` by default. When top-level
-`egregore.json.base_branch` is set, that configured branch replaces
-`develop` as the branch point, rebase target, PR base, and protected
-integration branch.
+The integration branch is `develop` unless top-level `egregore.json.base_branch` sets another; the configured branch is then the branch point, rebase target, PR base, and protected branch everywhere below.
 
 1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
 2. Run `bin/agent.sh branch --topic "<topic>"` — it resolves the configured base and creates a work branch from `origin/{base}` in a task worktree (`dev/{author}/{slug}`, or `feature/{slug}` / `bugfix/{slug}` when the topic reads as a feature or fix). Continue all file work from the printed path.
-3. Give a value-first workspace receipt. Do not lead with Git terminology:
-
-   `Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.`
-
-   Then expose the implementation as secondary detail:
-
-   `Workspace: {branch} (worktree).`
+3. Give a value-first workspace receipt — do not lead with Git terminology: `Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.` Then, as secondary detail: `Workspace: {branch} (worktree).`
 
 **Fallback:** If `bin/agent.sh branch` fails, resolve `{base}` with
 `_get_base_branch`, then use
@@ -148,14 +145,20 @@ integration branch.
 
 ### Starting-work UX contract
 
-Before execution begins, make Egregore's useful structure legible without turning every task start into a tutorial:
+Sequence: **intent → safe workspace → relevant context → consequential assumptions → execution**. Make Egregore's structure legible without turning task starts into a tutorial; keep technical identifiers secondary to user value.
 
-- **Workspace** — use the value-first receipt above for a newly created workspace or topic pivot. If already on the appropriate working branch, do not repeat it.
-- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat and then add one compact result receipt: `↳ Context restored: {decision, handoff, or prior work} · {source/date}`. Never claim context was restored when retrieval found nothing useful.
-- **Assumptions** — surface only consequential assumptions that could change the implementation. Use `Assumption: {assumption} — based on {evidence}.` Add a correction path when cheap; do not narrate obvious operational choices.
-- **Transition** — once workspace, context, and assumptions are settled, state the outcome you are starting toward in one short sentence and begin.
+- **Workspace** — the value-first receipt above, only for a new workspace or topic pivot; do not repeat it on the same branch.
+- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat plus one compact receipt: `↳ Context restored: {decision, handoff, or prior work} · {source/date}`. Never claim context was restored when retrieval found nothing useful.
+- **Assumptions** — surface only consequential ones: `Assumption: {assumption} — based on {evidence}.` Add a correction path when cheap; do not narrate obvious operational choices.
+- **Transition** — state the outcome you are starting toward in one short sentence and begin.
 
-The intended sequence is: **intent → safe workspace → relevant context → consequential assumptions → execution**. Keep technical identifiers available but subordinate them to user value.
+### Returning-work UX contract
+
+When the user continues the current branch's work or asks to resume — sequence: **continuation intent → prior workspace → restored context → open threads → resumed execution**:
+
+- Do not create a new workspace for the same topic. After confirming relevance, say: `I found your previous work on **{topic}** and restored its workspace and context.` Show `Workspace: {branch} (worktree).` secondarily.
+- Retrieve relevant decisions, handoffs, or prior work; keep the Retrieval Beat and `↳ Context restored:` receipt. Never claim context was restored from a branch name alone.
+- Name only unresolved items that could change the next move, state the next outcome briefly, and continue without replaying setup.
 
 ### Handoff claiming
 
@@ -164,7 +167,7 @@ If `addressed_to_user` handoffs exist and the user is picking one up, create the
 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:
+**Auto-checkout repos from handoff**: after claiming, if `addressed_rich` carries a non-empty `repoState`, check out each entry's branch in its managed repo:
 
 ```bash
 PARENT_DIR="$(cd .. && pwd)"
@@ -177,21 +180,19 @@ if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
 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.
+Report `✓ Checked out {branch} in {repo1}, {repo2}`; for a merged-away branch, `◐ {repo}: PR #{N} merged — on {base}`. If `repoState` is absent or empty, skip 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
+**Exceptions** — skip branching when the user explicitly created or named a branch themselves, or the intent continues the current working 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.
+**Topic pivot:** work **unrelated** to the current branch's topic gets a new branch (`bin/agent.sh branch --topic "<new topic>"`). Do NOT mix unrelated work on one branch.
 
 If still on the configured base branch 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`) protects project writes on the configured base branch as well as `develop`/`main`/`master`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
+The `.codex/hooks/branch-guard.js` PreToolUse hook (launcher `--enable hooks`) protects project writes on the configured base plus `develop`/`main`/`master`. Its block message is operational guidance — do not interrupt the user with routine Git choices:
 
-- **Topic is clear** (the user said "fix X", "add Y feature") → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is clear** → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the change is visible — never ask approval for routine branching.
 - **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   ```text
@@ -204,7 +205,7 @@ The `.codex/hooks/branch-guard.js` PreToolUse hook (enabled by the launcher via
   Wait for the reply, then branch.
 - **The user explicitly requested the protected branch** → that request is consent. Record it with `echo '{branch}' > .egregore-branch-consent`, then retry. Never create the marker merely to silence the hook.
 
-Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
+Memory, managed-repo, and runtime-state writes bypass the project guard — if one triggers it, correct the target/context instead of asking for consent.
 
 If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on the configured base, develop, main, or master.
 
@@ -342,7 +343,7 @@ Always use HTTPS for git operations — `github-auth.sh` handles credential stor
 
 ## Loom Routing
 
-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.
+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 — commands run inline. Ignore "Loom routing" preambles in skill specs and skip `bin/loom.sh` calls; `loom/` and `.claude/agents/` are Claude-runtime framework files.
 
 ---
 
@@ -371,6 +372,10 @@ main ← stable (/release)
 
 Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
 
+### Commit format (all harnesses)
+
+Every commit follows `.claude/context/commit-format.md`: subject `type(scope): imperative summary` (≤ 72 chars, aim ≤ 50, lowercase, same grammar and type set as PR titles), body wrapped at 72 explaining what and why — never how, and git trailers on agent-authored commits (`Egregore-Session: <id>` from `.egregore-session-id`, plus the harness `Co-Authored-By` line). Background scripts commit as `chore(<subsystem>): …`, but a commit carrying real work derives its type/scope from the diff — the transport never masks the work. Git-generated messages (merges, reverts, autosquash fixups) keep their native form. Wording for commits and PRs follows `.claude/context/git-language.md`.
+
 ### Managed Repos
 
 Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `$save` scans all managed repos for uncommitted changes.
@@ -387,7 +392,7 @@ Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Ea
 
 ## Command Awareness
 
-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.
+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`, `$scroll`; every other workflow has a generated adapter of the same name. `$save` is the user-facing abstraction for committing, pushing, opening or reusing PRs, and syncing memory — never make users manage git by hand.
 
 Invoke commands from user intent — don't wait for the slash. Each command file has a `## When to invoke` section. Load it for the full spec.
 
@@ -395,7 +400,7 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 **Knowledge** — `$search` `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest` `$scroll` `$mock` `$audit`
 **Identity** — `$me` (view profile or set display name)
 **Coordination** — `$ask` `$quest` `$issue` `$invite` `$delete-user` `$announce`
-**Connectors** — `$notion-connect` (Notion workspace) `$telegram-connect` (Telegram group setup) `$teams-connect` (Microsoft Teams channel setup)
+**Connectors** — `$notion-connect` (Notion workspace) `$telegram-connect` (Telegram group setup) `$teams-connect` (Microsoft Teams channel setup) `$slack-connect` (Slack channel setup)
 **Git** — `$branch` `$commit` `$push` `$pr` `$save` `$review-pr` `$contribute`
 **Spirits** — `$summon` (persistent agent processes)
 **Skills** — `$create-skill` (org-owned skill: scaffold, protect from updates, share)
@@ -411,7 +416,7 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 - Tasks: `$todo` (personal) · `$quest` (team exploration) · `$issue` (something broken)
 - Questions: `$ask [person]` (async) · just ask (agent answers from context)
 - Ingestion: `$ingest <file-or-folder>` (org-scoped corpus intake) · `$ingest meeting` · `$ingest user-interview` · `$ingest google` · ambiguous → ask which type
-- Connectors: `$notion-connect` (Notion workspace) · `$telegram-connect` (Telegram group) · `$teams-connect` (MS Teams channel) · `$ingest` (bring content in) · `$ingest notion` (promote Notion docs)
+- Connectors: `$notion-connect` (Notion workspace) · `$telegram-connect` (Telegram group) · `$teams-connect` (MS Teams channel) · `$slack-connect` (Slack channel) · `$ingest` (bring content in) · `$ingest notion` (promote Notion docs)
 - Identity: `$me` — "who am I", "call me oz"
 - People: `$invite` (add) · `$delete-user` (remove)
 - PRs: `$pr` (create) · `$review-pr` (review)
@@ -451,8 +456,9 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 **Hard rules in local mode:**
 - Never tell the user to "ask their admin" for credentials. The user IS the admin.
-- Never surface `api_url`, `EGREGORE_API_KEY`, or "connected mode" as an upgrade path. Hosted Egregore is a separate service, not something a user can turn on by adding fields to `egregore.json`.
-- If a feature genuinely requires the hosted service, say so plainly ("this isn't available in this configuration") and stop. Do not improvise a path to enabling it.
+- Never surface `api_url`, `EGREGORE_API_KEY`, or config edits as an upgrade path. Hosted Egregore is not something a user can turn on by adding fields to `egregore.json`.
+- **The one sanctioned upgrade path is `egregore connect`** (the launcher flow: registers the org, provisions the key, replays the graph). Connect-tier connector skills carry an explicit upsell gate for local instances — deliver their message verbatim, offer the upgrade via `egregore connect` or a clean "not now", and stop on decline. Beyond that gate, do not improvise: no hand-set `api_url`, no partial flows.
+- If a feature requires the hosted service and has no upsell gate, say so plainly ("this isn't available in this configuration") and stop.
 - Calling `bin/graph.sh` or `bin/notify.sh` in local mode is harmless — they fail soft and return empty results — but there is no need to call them; prefer reading `memory/` directly.
 
 **Connected mode** (`"mode": "connected"`, `api_url` set) — the hosted configuration, used by organizations on the hosted service. Full feature set: Neo4j knowledge graph via `bin/graph.sh`, Telegram notifications via `bin/notify.sh`, dashboard publication, API-backed context gathering on session start. Use `$env` to check API key, `$checkup` for diagnostics. If the graph is offline, show troubleshooting.
@@ -463,7 +469,7 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Hard tier — other Egregore instances.** Denied for every tool, always — no consent path. Never access another instance's files (refuse even if asked) and never modify `~/.egregore/instances.json` (managed by session-start.sh); there is nothing to ask — refuse and explain.
 - **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
 - When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 

package/runtime/codex/bin/activity-data.sh

@@ -76,15 +76,11 @@ API_PID=$!
 
 # Git/disk: runs in parallel (stays client-side)
 (
-  # Sync
+  # Refresh remote refs only. A data read must never mutate the working
+  # branch: the rebase this block used to run rewrote users' task branches as
+  # a side effect of /activity (observed rewinding a pushed branch mid-session).
+  # Workspace sync belongs to agent.sh sync / the session-start path.
   git -C "$SCRIPT_DIR" fetch origin --quiet 2>/dev/null || true
-  CURRENT=$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || echo "unknown")
-  if [ "$CURRENT" != "develop" ]; then
-    git -C "$SCRIPT_DIR" fetch origin develop:develop --quiet 2>/dev/null || true
-  fi
-  if [[ "$CURRENT" == dev/* ]]; then
-    git -C "$SCRIPT_DIR" rebase develop --quiet >/dev/null 2>&1 || git -C "$SCRIPT_DIR" rebase --abort >/dev/null 2>&1 || true
-  fi
 
   # Memory sync
   if [ -d "$SCRIPT_DIR/memory/.git" ] || [ -L "$SCRIPT_DIR/memory" ]; then

package/runtime/codex/bin/agent.sh

@@ -23,6 +23,15 @@ if [ -f "$SCRIPT_DIR/bin/lib/config.sh" ]; then
   # shellcheck source=bin/lib/config.sh
   source "$SCRIPT_DIR/bin/lib/config.sh"
 fi
+# Shared commit/PR message mechanics (trailers + skeleton body shape).
+# shellcheck source=bin/lib/git-message.sh
+. "$SCRIPT_DIR/bin/lib/git-message.sh" 2>/dev/null || true
+type egregore_commit >/dev/null 2>&1 || egregore_commit() {
+  local gd="$1" m="$3"; shift 3; git -C "$gd" commit -m "$m" "$@"
+}
+type egregore_pr_skeleton >/dev/null 2>&1 || egregore_pr_skeleton() {
+  printf '## What\n%s\n\n## Why\n%s\n\n## Verification\n%s\n\n%s\n' "$1" "$2" "$3" "$4"
+}
 
 usage() {
   cat <<'EOF'
@@ -360,8 +369,11 @@ build_pr_body() {
   commits="$(git -C "$SCRIPT_DIR" log --pretty='- %s' "origin/$base..HEAD" 2>/dev/null | head -8)"
   [ -n "$commits" ] || commits="- (commit list unavailable — see the Files tab)"
   stat="$(git -C "$SCRIPT_DIR" diff --shortstat "origin/$base...HEAD" 2>/dev/null | sed 's/^ *//')"
-  printf '## What\n%s\n\n## Why\nShell-agent session save — topic: %s. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description.\n\n## Verification\nNot verified — auto-generated skeleton; review the diff before merging.%s\n\n🤖 Saved via bin/agent.sh\n' \
-    "$commits" "$topic" "${stat:+ ($stat)}"
+  egregore_pr_skeleton \
+    "$commits" \
+    "Shell-agent session save — topic: $topic. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description." \
+    "Not verified — auto-generated skeleton; review the diff before merging.${stat:+ ($stat)}" \
+    "🤖 Saved via bin/agent.sh"
 }
 
 cmd_save() {
@@ -379,7 +391,7 @@ cmd_save() {
   done
 
   [ -n "$topic" ] || topic="portable save"
-  [ -n "$message" ] || message="Save: $topic"
+  [ -n "$message" ] || message="chore(save): $topic"
   base="$(resolve_base_branch)" || die "save stopped before Git changes"
 
   if [ -d "$MEMORY_DIR" ]; then
@@ -392,7 +404,7 @@ cmd_save() {
     branch="$(ensure_working_branch "$topic")"
     git -C "$SCRIPT_DIR" add -A >/dev/null 2>&1 || die "git add failed"
     if ! git -C "$SCRIPT_DIR" diff --cached --quiet 2>/dev/null; then
-      git -C "$SCRIPT_DIR" commit -m "$message" --quiet || die "git commit failed"
+      egregore_commit "$SCRIPT_DIR" "$SCRIPT_DIR" "$message" --quiet || die "git commit failed"
       committed="true"
     fi
   fi
@@ -415,7 +427,7 @@ cmd_save() {
         pr_body="$(cat "$pr_body_file")"
       fi
       [ -n "$pr_body" ] || pr_body="$(build_pr_body "$topic")"
-      pr_url="$(gh pr create --base "$base" --head "$branch" --title "$message" --body "$pr_body" 2>/dev/null || true)"
+      pr_url="$(gh pr create --base "$base" --head "$branch" --title "${message%%$'\n'*}" --body "$pr_body" 2>/dev/null || true)"
     fi
   fi
 

package/runtime/codex/bin/attendant.sh

@@ -99,6 +99,16 @@ _trigger_auto_thread() {
   ) >> "$LOGFILE" 2>&1 &
 }
 
+# Personal off switch for ambient capture. ripcord_enabled=false disables BOTH
+# ripcord notes and auto-push of dirty worktrees — a user who opts out of
+# ambient capture must not find silent commits either. The attendant's other
+# duties (graph cache, context seed, handoff lifecycle) are unaffected.
+# NOTE: jq's `//` treats false as empty (the auto_update:false gotcha), so the
+# test compares the raw value, never `.key // true`.
+_capture_enabled() {
+  [ "$(jq -r '.ripcord_enabled' "$MAIN_DIR/.egregore-state.json" 2>/dev/null)" != "false" ]
+}
+
 _author() {
   local a
   a=$(jq -r '.github_username // empty' "$MAIN_DIR/.egregore-state.json" 2>/dev/null)
@@ -249,6 +259,8 @@ _ripcord() {
   local transcript="$1" base author date_ym date_d slug topic file prompts gitsum
   base=$(basename "$transcript" .jsonl)
 
+  _capture_enabled || return 0
+
   grep -q "$base" "$JOURNAL" 2>/dev/null && return 0
   # Session already ended with ceremony? Then the attendant has no business
   # here. Scan only the tail — a session that merely *read* the /handoff or
@@ -336,6 +348,7 @@ _ripcord() {
 # --- Auto-push -------------------------------------------------------------
 
 _auto_push() {
+  _capture_enabled || return 0
   local wt branch dirty ahead upstream
   git -C "$MAIN_DIR" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2}' | while read -r wt; do
     branch=$(git -C "$wt" branch --show-current 2>/dev/null)

package/runtime/codex/bin/autosave.sh

@@ -28,6 +28,17 @@ set -uo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 STATE_FILE="$SCRIPT_DIR/.egregore-state.json"
 
+# The attendant runs against the MAIN checkout and reads its state file, so
+# ambient-capture settings must be written there — a worktree keeps its own
+# copy, and writing the flag into it would silently do nothing.
+MAIN_STATE_DIR="$SCRIPT_DIR"
+if [ -f "$SCRIPT_DIR/.git" ]; then
+  _WT_GITDIR=$(sed 's/^gitdir: //' "$SCRIPT_DIR/.git" 2>/dev/null || true)
+  [ -n "$_WT_GITDIR" ] && MAIN_STATE_DIR=$(cd "$_WT_GITDIR/../../.." 2>/dev/null && pwd || echo "$SCRIPT_DIR")
+fi
+MAIN_STATE_FILE="$MAIN_STATE_DIR/.egregore-state.json"
+[ -f "$MAIN_STATE_FILE" ] || MAIN_STATE_FILE="$STATE_FILE"
+
 [ -f "$STATE_FILE" ] || echo '{}' > "$STATE_FILE"
 
 # NB: jq's `//` swallows false — status would show "on" for enabled:false.
@@ -42,6 +53,11 @@ set_key() { # key value(json-encoded)
   jq ".$1 = $2" "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
 }
 
+_set_main() { # key value(json-encoded) — writes where the attendant reads
+  jq ".$1 = $2" "$MAIN_STATE_FILE" > "$MAIN_STATE_FILE.tmp" \
+    && mv "$MAIN_STATE_FILE.tmp" "$MAIN_STATE_FILE"
+}
+
 status() {
   local enabled scope publish
   enabled=$(get '.autosave_enabled' 'false')
@@ -50,6 +66,7 @@ status() {
   echo "autosave: $([ "$enabled" = "true" ] && echo on || echo "off (opt-in — 'autosave on' to join the experiment)")"
   echo "scope:    $scope  (all = handoffs + artifacts + docs · handoffs = memory repo only)"
   echo "publish:  $publish  (gate = PRs wait for your merge · auto = merge to develop automatically)"
+  echo "ripcord:  $(jq -r 'if (.ripcord_enabled != null) then (.ripcord_enabled|tostring) else "true" end' "$MAIN_STATE_FILE" 2>/dev/null || echo true)  (crash-recovery notes + branch auto-push when a session dies without /wrap)"
 }
 
 case "${1:-status}" in
@@ -61,6 +78,15 @@ case "${1:-status}" in
       all|handoffs) set_key autosave_scope "\"$2\"" && echo "scope: $2" ;;
       *) echo "usage: autosave.sh scope all|handoffs" >&2; exit 2 ;;
     esac ;;
+  ripcord)
+    # Ambient crash-recovery capture (the attendant): ripcord notes AND
+    # auto-push of dirty task branches. Separate from the autosave
+    # experiment above — this one defaults ON.
+    case "${2:-}" in
+      on)  _set_main ripcord_enabled true  && echo "ripcord: on — dead sessions leave a recovery note" ;;
+      off) _set_main ripcord_enabled false && echo "ripcord: off — no ambient notes, no branch auto-push" ;;
+      *) echo "usage: autosave.sh ripcord on|off" >&2; exit 2 ;;
+    esac ;;
   publish)
     case "${2:-}" in
       gate|auto) set_key autosave_publish "\"$2\"" && echo "publish: $2" ;;
@@ -82,5 +108,5 @@ case "${1:-status}" in
         echo "✗ PR #$n did not merge (conflict with develop?) — it stays open"
       fi
     done ;;
-  *) echo "usage: autosave.sh [status|on|off|scope all|handoffs|publish gate|auto|merge]" >&2; exit 2 ;;
+  *) echo "usage: autosave.sh [status|on|off|scope all|handoffs|publish gate|auto|merge|ripcord on|off]" >&2; exit 2 ;;
 esac

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

@@ -58,6 +58,12 @@ const AGENTS_PREAMBLE = `# Egregore Agent Protocol
 > \`.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 Prime Agent** (the \`prime-agent\` harness): **stop here.** Your
+> authoritative Egregore instructions are loaded from
+> \`.prime/agent/APPEND_SYSTEM.md\`, and your workflows are exposed through the
+> project-local \`.prime/agent/\` 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
@@ -173,26 +179,17 @@ function transformTokens(body) {
 
 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.`;
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md by \`bin/codex-render-spec.mjs\`; the per-section manifest is \`.codex/spec-manifest.json\`. The thin agent protocol above applies to every shell-capable agent; this block is the full 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 ON_LAUNCH_BODY = `The \`egregore\` launcher renders the startup card (identity, momentum, pending work) via \`bin/codex-session-start.sh\` before Codex starts and installs project skills. Do not rerun or 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. Re-show with \`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:
 
-The integration branch is \`develop\` by default. When top-level
-\`egregore.json.base_branch\` is set, that configured branch replaces
-\`develop\` as the branch point, rebase target, PR base, and protected
-integration branch.
+The integration branch is \`develop\` unless top-level \`egregore.json.base_branch\` sets another; the configured branch is then the branch point, rebase target, PR base, and protected branch everywhere below.
 
 1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
 2. Run \`bin/agent.sh branch --topic "<topic>"\` — it resolves the configured base and creates a work branch from \`origin/{base}\` in a task worktree (\`dev/{author}/{slug}\`, or \`feature/{slug}\` / \`bugfix/{slug}\` when the topic reads as a feature or fix). Continue all file work from the printed path.
-3. Give a value-first workspace receipt. Do not lead with Git terminology:
-
-   \`Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.\`
-
-   Then expose the implementation as secondary detail:
-
-   \`Workspace: {branch} (worktree).\`
+3. Give a value-first workspace receipt — do not lead with Git terminology: \`Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.\` Then, as secondary detail: \`Workspace: {branch} (worktree).\`
 
 **Fallback:** If \`bin/agent.sh branch\` fails, resolve \`{base}\` with
 \`_get_base_branch\`, then use
@@ -202,14 +199,20 @@ integration branch.
 
 ### Starting-work UX contract
 
-Before execution begins, make Egregore's useful structure legible without turning every task start into a tutorial:
+Sequence: **intent → safe workspace → relevant context → consequential assumptions → execution**. Make Egregore's structure legible without turning task starts into a tutorial; keep technical identifiers secondary to user value.
+
+- **Workspace** — the value-first receipt above, only for a new workspace or topic pivot; do not repeat it on the same branch.
+- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat plus one compact receipt: \`↳ Context restored: {decision, handoff, or prior work} · {source/date}\`. Never claim context was restored when retrieval found nothing useful.
+- **Assumptions** — surface only consequential ones: \`Assumption: {assumption} — based on {evidence}.\` Add a correction path when cheap; do not narrate obvious operational choices.
+- **Transition** — state the outcome you are starting toward in one short sentence and begin.
+
+### Returning-work UX contract
 
-- **Workspace** — use the value-first receipt above for a newly created workspace or topic pivot. If already on the appropriate working branch, do not repeat it.
-- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat and then add one compact result receipt: \`↳ Context restored: {decision, handoff, or prior work} · {source/date}\`. Never claim context was restored when retrieval found nothing useful.
-- **Assumptions** — surface only consequential assumptions that could change the implementation. Use \`Assumption: {assumption} — based on {evidence}.\` Add a correction path when cheap; do not narrate obvious operational choices.
-- **Transition** — once workspace, context, and assumptions are settled, state the outcome you are starting toward in one short sentence and begin.
+When the user continues the current branch's work or asks to resume — sequence: **continuation intent → prior workspace → restored context → open threads → resumed execution**:
 
-The intended sequence is: **intent → safe workspace → relevant context → consequential assumptions → execution**. Keep technical identifiers available but subordinate them to user value.
+- Do not create a new workspace for the same topic. After confirming relevance, say: \`I found your previous work on **{topic}** and restored its workspace and context.\` Show \`Workspace: {branch} (worktree).\` secondarily.
+- Retrieve relevant decisions, handoffs, or prior work; keep the Retrieval Beat and \`↳ Context restored:\` receipt. Never claim context was restored from a branch name alone.
+- Name only unresolved items that could change the next move, state the next outcome briefly, and continue without replaying setup.
 
 ### Handoff claiming
 
@@ -218,7 +221,7 @@ If \`addressed_to_user\` handoffs exist and the user is picking one up, create t
 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:
+**Auto-checkout repos from handoff**: after claiming, if \`addressed_rich\` carries a non-empty \`repoState\`, check out each entry's branch in its managed repo:
 
 \`\`\`bash
 PARENT_DIR="$(cd .. && pwd)"
@@ -231,21 +234,19 @@ if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
 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.
+Report \`✓ Checked out {branch} in {repo1}, {repo2}\`; for a merged-away branch, \`◐ {repo}: PR #{N} merged — on {base}\`. If \`repoState\` is absent or empty, skip 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
+**Exceptions** — skip branching when the user explicitly created or named a branch themselves, or the intent continues the current working 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.
+**Topic pivot:** work **unrelated** to the current branch's topic gets a new branch (\`bin/agent.sh branch --topic "<new topic>"\`). Do NOT mix unrelated work on one branch.
 
 If still on the configured base branch 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\`) protects project writes on the configured base branch as well as \`develop\`/\`main\`/\`master\`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
+The \`.codex/hooks/branch-guard.js\` PreToolUse hook (launcher \`--enable hooks\`) protects project writes on the configured base plus \`develop\`/\`main\`/\`master\`. Its block message is operational guidance — do not interrupt the user with routine Git choices:
 
-- **Topic is clear** (the user said "fix X", "add Y feature") → run \`bin/agent.sh branch --topic "<topic>"\` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is clear** → run \`bin/agent.sh branch --topic "<topic>"\` automatically, continue in the printed worktree, and say one short sentence so the change is visible — never ask approval for routine branching.
 - **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   \`\`\`text
@@ -258,7 +259,7 @@ The \`.codex/hooks/branch-guard.js\` PreToolUse hook (enabled by the launcher vi
   Wait for the reply, then branch.
 - **The user explicitly requested the protected branch** → that request is consent. Record it with \`echo '{branch}' > .egregore-branch-consent\`, then retry. Never create the marker merely to silence the hook.
 
-Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
+Memory, managed-repo, and runtime-state writes bypass the project guard — if one triggers it, correct the target/context instead of asking for consent.
 
 If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on the configured base, develop, main, or master.
 
@@ -266,7 +267,7 @@ If this Codex build does not support hooks, follow the same discipline as a stan
 
 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 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\`, \`$scroll\`; every other workflow has a generated adapter of the same name. \`$save\` is the user-facing abstraction for committing, pushing, opening or reusing PRs, and syncing memory — never make users manage git by hand.`;
 
 const SOCRATIC_BODY = `**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
 
@@ -274,11 +275,11 @@ Codex has no structured question tool — render each batch as compact numbered
 
 **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 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 — commands run inline. Ignore "Loom routing" preambles in skill specs and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are Claude-runtime framework files.`;
 
 const ISOLATION_BODY = `Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
 
-- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify \`~/.egregore/instances.json\` (managed by session-start.sh). When a request points at another instance's files there is nothing to ask — refuse and explain.
+- **Hard tier — other Egregore instances.** Denied for every tool, always — no consent path. Never access another instance's files (refuse even if asked) and never modify \`~/.egregore/instances.json\` (managed by session-start.sh); there is nothing to ask — refuse and explain.
 - **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (\`~/Downloads\`, \`~/Desktop\`) are readable without consent under the default posture; writes outside the project always need consent. Posture (\`strict | standard | open\`) and extra read roots come from \`egregore.json\` -> \`boundary { posture, read[], locked }\` (org, committed) merged with \`.egregore-boundary.local.json\` (personal, gitignored). \`locked: true\` removes the consent path entirely.
 - When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
 
@@ -321,7 +322,7 @@ const RULES = {
   '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).',
+    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 bash kept verbatim (pure git); surrounding prose compressed 2026-08 for the 32 KiB budget, every rule retained.',
   },
   'Config Files': { action: 'keep', note: 'Kept verbatim — shell facts, runtime-neutral.' },
   'Knowledge Graph': { action: 'keep', note: 'Kept verbatim — bin/graph.sh is runtime-neutral.' },

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

@@ -210,7 +210,9 @@ render_card() {
 
   # Staged auto-saves awaiting the user's merge (the autosave consent gate).
   # Live gh query so the line persists until the PRs actually merge.
-  if command -v gh >/dev/null 2>&1; then
+  # Shown only while the autosave experiment is enabled.
+  autosave_on=$(jq -r '.autosave_enabled // false' "$STATE_FILE" 2>/dev/null)
+  if [ "$autosave_on" = "true" ] && command -v gh >/dev/null 2>&1; then
     gh_self=$(jq -r '.github_username // empty' "$STATE_FILE" 2>/dev/null)
     if [ -n "$gh_self" ]; then
       waiting_as=$(gh pr list --state open --author "$gh_self" --limit 20 \

package/runtime/codex/bin/codex-sync-skills.sh

@@ -101,7 +101,12 @@ skill_description() {
     in_fm && $0 == "---" { exit }
     in_fm && /^description:/ {
       sub(/^description:[[:space:]]*/, "")
-      gsub(/^"|"$/, "")
+      # Block scalars (description: >) keep the text on continuation lines we
+      # do not read. Emit nothing so the caller falls back, which the skill-v1
+      # contract check reports, rather than publishing the indicator itself.
+      if ($0 ~ /^[>|][-+]?[[:space:]]*$/) { exit }
+      if ($0 ~ /^".*"$/) { gsub(/^"|"$/, "") }
+      else if ($0 ~ /^\047.*\047$/) { gsub(/^\047|\047$/, ""); gsub(/\047\047/, "\047") }
       print
       exit
     }

package/runtime/codex/bin/graph-batch.sh

@@ -24,21 +24,40 @@ if [ "$_MODE" = "local" ]; then
   exit 0
 fi
 
-# 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)}"
+# Load specific variables from .env if it exists (safe extraction, no arbitrary code execution).
+# A worktree missing its .env symlink resolves through worktree-links.sh, which
+# self-heals the link and falls back to the main checkout's .env.
+_ENV_FILE="$SCRIPT_DIR/.env"
+if [ ! -f "$_ENV_FILE" ] && [ -f "$SCRIPT_DIR/bin/lib/worktree-links.sh" ]; then
+  # shellcheck source=bin/lib/worktree-links.sh
+  source "$SCRIPT_DIR/bin/lib/worktree-links.sh" 2>/dev/null || true
+  _ENV_FILE="$(egregore_env_file "$SCRIPT_DIR" 2>/dev/null || true)"
+fi
+if [ -n "$_ENV_FILE" ] && [ -f "$_ENV_FILE" ]; then
+  EGREGORE_API_URL="${EGREGORE_API_URL:-$(grep '^EGREGORE_API_URL=' "$_ENV_FILE" 2>/dev/null | cut -d'=' -f2- || true)}"
+  EGREGORE_API_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "$_ENV_FILE" 2>/dev/null | cut -d'=' -f2- || true)}"
 fi
 
 API_URL="${EGREGORE_API_URL:-$(jq -r '.api_url // empty' "$CONFIG")}"
 API_KEY="${EGREGORE_API_KEY:-}"
 
-if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
-  # === OFFLINE MODE: No API key — return empty results (OSS/local) ===
+if [ -z "$API_URL" ]; then
+  # === OFFLINE MODE: no api_url configured (OSS/unconfigured) ===
   echo '{"results":[]}'
   exit 0
 fi
 
+if [ -z "$API_KEY" ]; then
+  # api_url is configured but no key was found — the local-mode gate exited
+  # above, so the org expects a live graph. Faking empty results here hides a
+  # missing .env (e.g. a worktree without its symlink) from every caller.
+  {
+    echo "Error: api_url is configured but EGREGORE_API_KEY is empty (looked in: ${_ENV_FILE:-$SCRIPT_DIR/.env})."
+    echo "  If this is a worktree, its .env symlink may be missing. Run /env to configure."
+  } >&2
+  exit 1
+fi
+
 QUERIES_JSON="${1:?Usage: graph-batch.sh '<json array of queries>'}"
 
 # Wrap the array into the batch request format