create-egregore 0.19.33 → 0.20.1

package/runtime/pi/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/pi/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/pi/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/pi/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/pi/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/pi/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

package/runtime/pi/bin/graph-op.sh

@@ -708,7 +708,8 @@ case "$OP" in
     fi
     bash "$GS" query "
       MATCH (s:Session)-[:HANDED_TO]->(p:Person)
-      WHERE (
+      WHERE NOT coalesce(p.kind, '') IN ['identity_alias']
+        AND (
         toLower(coalesce(p.name, '')) = toLower(\$user)
         OR toLower(coalesce(p.github, '')) = toLower(\$user)
         OR toLower(coalesce(p.githubUsername, '')) = toLower(\$user)
@@ -718,13 +719,13 @@ case "$OP" in
         AND coalesce(s.handoffStatus, 'pending')
             IN ['pending','unread','read','claimed']
       WITH DISTINCT s
-      OPTIONAL MATCH (s)-[:BY]->(author:Person)
-      WITH s, author,
+      WITH s, head([(s)-[:BY]->(author:Person)
+                    WHERE NOT coalesce(author.kind, '') IN ['identity_alias'] | author.name]) AS authorName,
            CASE WHEN s.date IS NULL THEN null
                 ELSE duration.inDays(date(s.date), date()).days END AS ageDays
       RETURN s.id AS id,
              coalesce(s.topic, s.summary, s.branch) AS topic,
-             coalesce(author.name, s.author, 'unknown') AS author,
+             coalesce(authorName, s.author, 'unknown') AS author,
              toString(s.date) AS date,
              coalesce(s.handoffStatus, 'pending') AS status,
              coalesce(s.handoffIntent, 'unclassified') AS intent,

package/runtime/pi/bin/graph.sh

@@ -21,10 +21,18 @@ 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 comes from egregore.json (committed, non-secret)
@@ -168,8 +176,26 @@ if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
     fi
   }
 
+elif [ -n "$API_URL" ]; then
+  # === CONNECTED CONFIG, MISSING KEY ===
+  # api_url is configured, so the org expects a live graph, but no API key was
+  # found. Faking '{"results":[]}' here made a missing credential (e.g. a
+  # worktree without its .env symlink) indistinguishable from an empty graph —
+  # fail loudly instead. `test` keeps its offline JSON contract: dashboards,
+  # render-card, and startup-check consume it.
+  _missing_credentials() {
+    {
+      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
+  }
+  run_query() { _missing_credentials; }
+  get_schema() { _missing_credentials; }
+  test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }
+
 else
-  # === OFFLINE MODE: No API key — return empty results (OSS/local) ===
+  # === OFFLINE MODE: no api_url configured (OSS/unconfigured) ===
   run_query() { echo '{"results":[]}'; }
   get_schema() { echo '{}'; }
   test_connection() { echo '{"status":"offline","reason":"no_api_key"}'; }

package/runtime/pi/bin/handoff-pr-backfill.sh

@@ -77,7 +77,7 @@ if [ -d "$MEMORY_DIR" ]; then
   (
     cd "$MEMORY_DIR" || exit 0
     git add -A >/dev/null 2>&1
-    git commit -m "Backfill PR numbers for handoff: $TOPIC" >/dev/null 2>&1 || exit 0
+    git commit -m "chore(handoff): backfill PR numbers for $TOPIC" >/dev/null 2>&1 || exit 0
     git pull --rebase origin main --quiet >/dev/null 2>&1
     git push origin main --quiet >/dev/null 2>&1
   ) || true

package/runtime/pi/bin/handoff-run.sh

@@ -36,6 +36,11 @@ set -euo pipefail
 #   1 on unrecoverable failure (file write, memory push, bad args).
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# 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" "$@"
+}
 CONFIG="$SCRIPT_DIR/egregore.json"
 
 if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
@@ -326,12 +331,12 @@ PID_ARTIFACTS=$!
     git add "$REL_FILE" handoffs/index.md >/dev/null 2>&1
 
     if [ -n "$RECIPIENT" ]; then
-      MSG_COMMIT="Handoff: ${TOPIC} (to ${RECIPIENT})"
+      MSG_COMMIT="chore(handoff): record ${TOPIC} (to ${RECIPIENT})"
     else
-      MSG_COMMIT="Handoff: ${TOPIC}"
+      MSG_COMMIT="chore(handoff): record ${TOPIC}"
     fi
 
-    git commit -m "$MSG_COMMIT" >/dev/null 2>&1 || true
+    egregore_commit . "$SCRIPT_DIR" "$MSG_COMMIT" >/dev/null 2>&1 || true
 
     STASHED=0
     if [ -n "$(git status --porcelain 2>/dev/null)" ]; then

package/runtime/pi/bin/handoff-save-egregore.sh

@@ -47,19 +47,16 @@ done
 
 case "$KIND" in
   autosave)
-    MSG_PREFIX="Auto-save"
+    MSG_PREFIX="chore(autosave): save"
     PR_WHAT="Save session content captured by the opted-in autosave workflow."
     PR_WHY="This preserves unattended non-coding work without requiring an explicit /save."
     ;;
   *)
-    MSG_PREFIX="Handoff"
+    MSG_PREFIX="chore(handoff): record"
     PR_WHAT="Save core-repository session work captured when the handoff was created."
     PR_WHY="The handoff records shared context immediately; this companion PR keeps the originating checkout's work from remaining only local."
     ;;
 esac
-PR_BODY=$(printf '## What\n\n- %s\n\n## Why\n\n%s Topic: `%s`.\n\n## Verification\n\nNot verified — background %s save; review code or configuration changes before merging.\n\n🤖 Saved via `bin/handoff-save-egregore.sh`\n' \
-  "$PR_WHAT" "$PR_WHY" "$TOPIC" "$KIND")
-
 [ -n "$AUTHOR" ] || { echo "handoff-save-egregore: missing author" >&2; exit 1; }
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
@@ -88,6 +85,21 @@ BASE_REF="origin/$BASE_BRANCH"
 . "$SCRIPT_DIR/bin/lib/git-safe.sh" 2>/dev/null || true
 type git_add_guarded >/dev/null 2>&1 || git_add_guarded() { git add -A 2>/dev/null || true; }
 
+# 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"
+}
+PR_BODY=$(egregore_pr_skeleton \
+  "- $PR_WHAT" \
+  "$PR_WHY Topic: \`$TOPIC\`." \
+  "Not verified — background $KIND save; review code or configuration changes before merging." \
+  "🤖 Saved via \`bin/handoff-save-egregore.sh\`")
+
 # Shared non-coding classifier (auto-merge policy lives in one place).
 # shellcheck source=bin/lib/noncode.sh
 . "$SCRIPT_DIR/bin/lib/noncode.sh" 2>/dev/null || true
@@ -131,7 +143,7 @@ fi
 # --- Commit whatever is uncommitted --------------------------------------
 if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
   git_add_guarded
-  git commit -m "${MSG_PREFIX}: ${TOPIC}" --quiet 2>/dev/null || true
+  egregore_commit . "$REPO_DIR" "${MSG_PREFIX} ${TOPIC}" --quiet 2>/dev/null || true
 fi
 
 # --- Rebase onto the configured base, fall back to merge on conflicts ----
@@ -182,7 +194,7 @@ else
   PR_URL=$(gh pr create \
     --base "$BASE_BRANCH" \
     --head "$CURRENT_BRANCH" \
-    --title "${MSG_PREFIX}: ${TOPIC}" \
+    --title "${MSG_PREFIX} ${TOPIC}" \
     --body "$PR_BODY" \
     2>/dev/null || echo "")
   PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$' || echo "")