create-egregore 0.19.3 → 0.19.6

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

@@ -0,0 +1,136 @@
+#!/bin/bash
+# handoff-save-egregore.sh — background save+auto-merge for the core repo after a handoff.
+#
+# /handoff renders its card first, then fires this detached. The user never waits on git.
+#
+# Behavior:
+#   - If nothing to save (clean working tree + up-to-date with origin) → exit silently.
+#   - If on develop/main/master → create dev/{author}/handoff-{YYYY-MM-DD} branch from origin/develop.
+#   - Commit all changes, rebase onto origin/develop, push.
+#   - If push succeeds: create PR to develop (or reuse existing), then:
+#     - Markdown-only diff → `gh pr merge --auto --merge` (auto-merges when checks pass).
+#     - Code/config present → leave PR open for review (no auto-merge).
+#
+# Usage:
+#   handoff-save-egregore.sh <author> <topic> [--repo-dir <path>]
+#
+# --repo-dir overrides the default working directory (normally the script's
+# own repo root, resolved from $0). Tests and sandbox runs MUST pass it;
+# without it, the script operates on the real repo regardless of caller cwd.
+#
+# Detached usage (the skill calls it this way):
+#   ( bash bin/handoff-save-egregore.sh "$AUTHOR" "$TOPIC" >/dev/null 2>&1 & ) >/dev/null 2>&1
+#
+# Exit 0 on any non-fatal outcome. The caller never reads stdout/stderr — all status
+# lives in the PR itself and in `git log`.
+
+set -uo pipefail
+
+AUTHOR="${1:-}"
+TOPIC="${2:-session work}"
+shift 2 2>/dev/null || true
+
+REPO_DIR=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo-dir) REPO_DIR="${2:-}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+[ -n "$AUTHOR" ] || { echo "handoff-save-egregore: missing author" >&2; exit 1; }
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# If --repo-dir wasn't given, default to the script's own repo root.
+[ -z "$REPO_DIR" ] && REPO_DIR="$SCRIPT_DIR"
+cd "$REPO_DIR" || exit 1
+
+# Shared safe-staging guard — never auto-commit stray sibling-repo gitlinks.
+# shellcheck source=bin/lib/git-safe.sh
+. "$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; }
+
+# --- Early exit if nothing to do -----------------------------------------
+DIRTY=0
+[ -n "$(git status --porcelain 2>/dev/null)" ] && DIRTY=1
+
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+AHEAD=0
+if [ -n "$CURRENT_BRANCH" ]; then
+  # Count commits ahead of origin/develop on the current branch (works from any
+  # dev/* branch or from develop itself).
+  AHEAD=$(git rev-list --count "origin/develop..HEAD" 2>/dev/null || echo 0)
+fi
+
+if [ "$DIRTY" = "0" ] && [ "$AHEAD" = "0" ]; then
+  exit 0
+fi
+
+# --- Protect the protected branches: create a working branch if needed --
+case "$CURRENT_BRANCH" in
+  develop|main|master|"")
+    SLUG_DATE=$(date +%Y-%m-%d)
+    NEW_BRANCH="dev/${AUTHOR}/handoff-${SLUG_DATE}"
+    git fetch origin develop --quiet 2>/dev/null || true
+    git checkout -b "$NEW_BRANCH" origin/develop --quiet 2>/dev/null || \
+      git checkout "$NEW_BRANCH" --quiet 2>/dev/null || exit 0
+    CURRENT_BRANCH="$NEW_BRANCH"
+    ;;
+esac
+
+# --- Commit whatever is uncommitted --------------------------------------
+if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
+  git_add_guarded
+  git commit -m "Handoff: ${TOPIC}" --quiet 2>/dev/null || true
+fi
+
+# --- Rebase onto develop, fall back to merge if rebase conflicts ---------
+git fetch origin develop --quiet 2>/dev/null || true
+if ! git rebase origin/develop --quiet 2>/dev/null; then
+  git rebase --abort 2>/dev/null || true
+  if ! git merge origin/develop --quiet -m "Sync with develop" 2>/dev/null; then
+    # Conflicts we can't auto-resolve. Leave the branch as-is; the user will see it
+    # next session or when they run /save explicitly.
+    git merge --abort 2>/dev/null || true
+    exit 0
+  fi
+fi
+
+# --- Push ---------------------------------------------------------------
+if ! git push -u origin "$CURRENT_BRANCH" --quiet 2>/dev/null; then
+  # Push failed (network, auth). Commits are safe locally.
+  exit 0
+fi
+
+# --- PR: reuse open PR on this branch, or create one --------------------
+command -v gh >/dev/null 2>&1 || exit 0
+
+PR_NUMBER=""
+EXISTING=$(gh pr list --head "$CURRENT_BRANCH" --state open --json number,baseRefName --jq '.[0]' 2>/dev/null)
+EXISTING_NUMBER=$(echo "$EXISTING" | jq -r '.number // empty' 2>/dev/null)
+EXISTING_BASE=$(echo "$EXISTING" | jq -r '.baseRefName // empty' 2>/dev/null)
+
+if [ -n "$EXISTING_NUMBER" ]; then
+  PR_NUMBER="$EXISTING_NUMBER"
+  if [ "$EXISTING_BASE" != "develop" ]; then
+    gh pr edit "$PR_NUMBER" --base develop >/dev/null 2>&1 || true
+  fi
+else
+  PR_URL=$(gh pr create \
+    --base develop \
+    --head "$CURRENT_BRANCH" \
+    --title "Handoff: ${TOPIC}" \
+    --body "Auto-created by /handoff. Session work for: ${TOPIC}" \
+    2>/dev/null || echo "")
+  PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$' || echo "")
+fi
+
+[ -n "$PR_NUMBER" ] || exit 0
+
+# --- Auto-merge iff markdown-only ---------------------------------------
+NON_MD=$(git diff origin/develop --name-only 2>/dev/null | grep -v '\.md$' | head -1 || echo "")
+if [ -z "$NON_MD" ]; then
+  gh pr merge "$PR_NUMBER" --auto --merge >/dev/null 2>&1 || true
+fi
+
+exit 0

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

@@ -0,0 +1,312 @@
+#!/bin/bash
+set -euo pipefail
+
+# Index a single handoff file into the Neo4j graph.
+# Usage: bash bin/index-handoff.sh <file-path>
+# Returns: {"sessionId":"...","resolved":N} or {"error":"..."}
+#
+# The file-path should be relative to memory/ (e.g. handoffs/2026-02/14-oz-topic.md)
+# or an absolute/relative path that contains "handoffs/" somewhere in it.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  echo "Usage: index-handoff.sh <handoff-file-path>"
+  echo ""
+  echo "Index a single handoff file into the Neo4j graph."
+  echo "Parses metadata (author, date, topic, recipients) from"
+  echo "markdown headers or YAML front matter, creates Session"
+  echo "and relationship nodes, and auto-resolves old handoffs."
+  echo ""
+  echo "Returns: {\"sessionId\":\"...\",\"resolved\":N}"
+  exit 0
+fi
+
+# --- Local mode gate: bail immediately ---
+_MODE=$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+if [ "$_MODE" = "local" ]; then
+  echo '{"sessionId":"","resolved":0,"mode":"local"}'
+  exit 0
+fi
+
+# --- Validate input ---
+FILE_ARG="${1:?Usage: index-handoff.sh <handoff-file-path>}"
+
+# Resolve to absolute path if needed
+if [[ "$FILE_ARG" = /* ]]; then
+  FILE_PATH="$FILE_ARG"
+elif [[ "$FILE_ARG" = memory/* ]]; then
+  FILE_PATH="$SCRIPT_DIR/$FILE_ARG"
+else
+  FILE_PATH="$SCRIPT_DIR/memory/$FILE_ARG"
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  echo '{"error":"File not found: '"$FILE_ARG"'"}'
+  exit 1
+fi
+
+# --- Derive filePath (relative to memory/) and sessionId ---
+REL_PATH="${FILE_PATH##*/memory/}"
+if [[ "$REL_PATH" = "$FILE_PATH" ]]; then
+  REL_PATH="handoffs/${FILE_PATH##*handoffs/}"
+fi
+
+FILENAME="$(basename "$FILE_PATH" .md)"
+DIR_MONTH="$(basename "$(dirname "$FILE_PATH")")"
+
+# sessionId = YYYY-MM-DD-author-topic
+# If file is in a YYYY-MM subdirectory, derive from dir + filename
+# If file is in root handoffs/ (no month subdir), extract date from filename
+if [[ "$DIR_MONTH" =~ ^[0-9]{4}-[0-9]{2}$ ]]; then
+  DAY="${FILENAME%%-*}"
+  REST="${FILENAME#*-}"
+  SESSION_ID="${DIR_MONTH}-${DAY}-${REST}"
+else
+  # Filename starts with YYYY-MM-DD — use it directly
+  SESSION_ID="$FILENAME"
+  DAY="$(echo "$FILENAME" | grep -oE '^[0-9]{4}-[0-9]{2}-[0-9]{2}' || true)"
+  REST="${FILENAME#*-*-*-}"
+  DIR_MONTH="$(echo "$DAY" | grep -oE '^[0-9]{4}-[0-9]{2}' || true)"
+fi
+
+# --- Parse handoff metadata from markdown ---
+CONTENT="$(cat "$FILE_PATH")"
+
+# Helper: extract from markdown headers, handles both **Key**: Value and **Key:** Value
+md_extract() {
+  echo "$CONTENT" | grep -m1 "$1" 2>/dev/null | sed "$2" || true
+}
+
+# Helper: extract markdown field by name (handles **Key**: and **Key:** patterns)
+md_field() {
+  local key="$1"
+  local val
+  # Try **Key**: Value (colon outside bold)
+  val="$(echo "$CONTENT" | grep -m1 "^\*\*${key}\*\*:" 2>/dev/null | sed "s/\*\*${key}\*\*:[[:space:]]*//" | tr -d '\n' || true)"
+  # Try **Key:** Value (colon inside bold)
+  if [ -z "$val" ]; then
+    val="$(echo "$CONTENT" | grep -m1 "^\*\*${key}:\*\*" 2>/dev/null | sed "s/\*\*${key}:\*\*[[:space:]]*//" | tr -d '\n' || true)"
+  fi
+  echo "$val"
+}
+
+# Helper: extract from YAML front matter (key: value between --- delimiters)
+yaml_extract() {
+  local key="$1"
+  sed -n '/^---$/,/^---$/p' "$FILE_PATH" 2>/dev/null | grep -m1 "^${key}:" 2>/dev/null | sed "s/^${key}:[[:space:]]*//" | sed 's/^"//' | sed 's/"$//' | xargs 2>/dev/null || true
+}
+
+# H1 topic (always from markdown body, not front matter)
+TOPIC="$(md_extract '^# ' 's/^# //; s/^Handoff: //')"
+# Also check YAML front matter topic
+[ -z "$TOPIC" ] && TOPIC="$(yaml_extract 'topic')"
+[ -z "$TOPIC" ] && TOPIC="$REST"
+
+# Date: try markdown header, then YAML
+DATE="$(md_field 'Date')"
+[ -z "$DATE" ] && DATE="$(yaml_extract 'date')"
+[ -z "$DATE" ] && DATE="${DIR_MONTH}-${DAY}"
+
+# Author: try markdown header (Author or From), then YAML (author or from)
+AUTHOR="$(md_field 'Author')"
+[ -z "$AUTHOR" ] && AUTHOR="$(md_field 'From')"
+[ -z "$AUTHOR" ] && AUTHOR="$(yaml_extract 'author')"
+[ -z "$AUTHOR" ] && AUTHOR="$(yaml_extract 'from')"
+# Strip " → recipient" if present (e.g. "cem → oz" → "cem")
+AUTHOR_HANDLE="$(echo "$AUTHOR" | sed 's/[[:space:]]*→.*//' | awk '{print tolower($1)}')"
+[ -z "$AUTHOR_HANDLE" ] && AUTHOR_HANDLE="unknown"
+
+# Recipients: try markdown header (To or For), then YAML (to or for)
+RECIPIENTS_RAW="$(md_field 'To')"
+[ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(md_field 'For')"
+[ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'to')"
+[ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'for')"
+# Also extract from "From: author → recipient" pattern
+if [ -z "$RECIPIENTS_RAW" ] && echo "$AUTHOR" | grep -q '→' 2>/dev/null; then
+  RECIPIENTS_RAW="$(echo "$AUTHOR" | sed 's/.*→[[:space:]]*//')"
+fi
+
+# Project: try markdown header, then YAML
+PROJECT="$(md_field 'Project')"
+[ -z "$PROJECT" ] && PROJECT="$(yaml_extract 'project')"
+
+# Handoff kind: used by readers to distinguish automatic captures from manual handoffs.
+KIND="$(md_field 'Kind')"
+[ -z "$KIND" ] && KIND="$(yaml_extract 'kind')"
+
+# Summary: 5-level precedence chain
+# 1. Frontmatter summary field
+SUMMARY="$(yaml_extract 'summary')"
+# 2. First non-empty paragraph after ## Briefing
+[ -z "$SUMMARY" ] && SUMMARY="$(echo "$CONTENT" | awk '/^## Briefing/{found=1; next} found && /^#/{exit} found && /^[^#]/ && !/^[[:space:]]*$/{print; exit}' || true)"
+# 3. First non-empty paragraph after ## Session Summary (legacy)
+[ -z "$SUMMARY" ] && SUMMARY="$(echo "$CONTENT" | awk '/^## Session Summary/{found=1; next} found && /^#/{exit} found && /^[^#]/ && !/^[[:space:]]*$/{print; exit}' || true)"
+# 4. First non-heading, non-metadata, non-empty line in body
+[ -z "$SUMMARY" ] && SUMMARY="$(echo "$CONTENT" | awk '!/^[[:space:]]*$/ && !/^#/ && !/^\*\*/ && !/^---/ && !/^\|/ && !/^- /{print; exit}' || true)"
+# 5. Topic fallback
+[ -z "$SUMMARY" ] && SUMMARY="$TOPIC"
+
+# Repo State: parse markdown table after "## Repo State"
+# Extracts repo, branch, PR number, and base branch from each table row
+REPO_STATE_JSON="[]"
+REPO_TABLE=$(echo "$CONTENT" | awk '/^## Repo State/{found=1; next} found && /^#/{exit} found && /^\|[^-]/ && !/^\| Repo/{print}' || true)
+if [ -n "$REPO_TABLE" ]; then
+  REPO_STATE_JSON=$(echo "$REPO_TABLE" | while IFS='|' read -r _ R_REPO R_BRANCH R_PR R_BASE _; do
+    R_REPO=$(echo "$R_REPO" | xargs 2>/dev/null || true)
+    R_BRANCH=$(echo "$R_BRANCH" | xargs 2>/dev/null || true)
+    R_PR=$(echo "$R_PR" | xargs 2>/dev/null | sed 's/^#//' | sed 's/—//' || true)
+    R_BASE=$(echo "$R_BASE" | xargs 2>/dev/null || true)
+    [ -z "$R_REPO" ] && continue
+    if [ -n "$R_PR" ] && [ "$R_PR" -eq "$R_PR" ] 2>/dev/null; then
+      jq -n --arg repo "$R_REPO" --arg branch "$R_BRANCH" --argjson pr "$R_PR" --arg base "$R_BASE" \
+        '{repo:$repo, branch:$branch, pr:$pr, base:$base}'
+    else
+      jq -n --arg repo "$R_REPO" --arg branch "$R_BRANCH" --arg base "$R_BASE" \
+        '{repo:$repo, branch:$branch, pr:null, base:$base}'
+    fi
+  done | jq -s '.' 2>/dev/null || echo "[]")
+fi
+
+# --- Build Cypher queries ---
+
+# Q1: MERGE Session + relationships
+HANDED_TO_CYPHER=""
+_RECIP_ARGS=()
+if [ -n "$RECIPIENTS_RAW" ]; then
+  IFS=',' read -ra RECIPS <<< "$RECIPIENTS_RAW"
+  for i in "${!RECIPS[@]}"; do
+    R="$(echo "${RECIPS[$i]}" | xargs | tr '[:upper:]' '[:lower:]')"
+    [ -z "$R" ] && continue
+    HANDED_TO_CYPHER="${HANDED_TO_CYPHER}
+WITH s
+OPTIONAL MATCH (r${i}:Person) WHERE toLower(r${i}.name) = \$recipient${i} OR r${i}.github = \$recipient${i} OR toLower(r${i}.fullName) = \$recipient${i}
+FOREACH (_ IN CASE WHEN r${i} IS NOT NULL THEN [1] ELSE [] END |
+  MERGE (s)-[:HANDED_TO]->(r${i})
+)"
+    _RECIP_ARGS+=("--arg" "recipient${i}" "$R")
+  done
+fi
+
+PROJECT_CYPHER=""
+_PROJECT_ARGS=()
+if [ -n "$PROJECT" ]; then
+  PROJECT_CYPHER="
+WITH s
+OPTIONAL MATCH (proj:Project) WHERE toLower(proj.name) = toLower(\$project)
+FOREACH (_ IN CASE WHEN proj IS NOT NULL THEN [1] ELSE [] END |
+  MERGE (s)-[:ABOUT]->(proj)
+)"
+  _PROJECT_ARGS=("--arg" "project" "$PROJECT")
+fi
+
+Q1_CYPHER="MATCH (p:Person) WHERE toLower(p.name) = \$author OR p.github = \$author OR toLower(p.fullName) = \$author OR \$author IN [x IN coalesce(p.previousNames, []) | toLower(x)]
+MERGE (s:Session {id: \$sessionId})
+ON CREATE SET s.date = date(\$date), s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.author = \$author, s.handoffKind = CASE WHEN \$kind = '' THEN null ELSE \$kind END, s.handoffStatus = 'pending', s.repoState = \$repoState, s.startedAt = datetime(\$date + 'T00:00:00Z')
+ON MATCH SET s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.author = \$author, s.handoffKind = CASE WHEN \$kind = '' THEN null ELSE \$kind END, s.repoState = \$repoState
+WITH s, p
+MERGE (s)-[:BY]->(p)${PROJECT_CYPHER}${HANDED_TO_CYPHER}
+RETURN s.id AS sessionId"
+
+Q1_PARAMS=$(jq -n \
+  --arg sessionId "$SESSION_ID" \
+  --arg author "$AUTHOR_HANDLE" \
+  --arg date "$DATE" \
+  --arg topic "$TOPIC" \
+  --arg summary "$SUMMARY" \
+  --arg filePath "$REL_PATH" \
+  --arg kind "$KIND" \
+  --arg repoState "$REPO_STATE_JSON" \
+  "${_PROJECT_ARGS[@]:+${_PROJECT_ARGS[@]}}" \
+  "${_RECIP_ARGS[@]:+${_RECIP_ARGS[@]}}" \
+  '$ARGS.named')
+
+# Q2: Auto-resolve old read handoffs from this author
+Q2_CYPHER="MATCH (s:Session)-[:HANDED_TO]->(p:Person) WHERE (toLower(p.name) = \$author OR p.github = \$author OR toLower(p.fullName) = \$author) AND s.handoffStatus = 'read' AND s.id <> \$sessionId
+WITH s, p, coalesce(s.handoffReadDate, s.date) AS sinceDate
+MATCH (later:Session)-[:BY]->(p)
+WHERE later.date > sinceDate
+WITH s, count(later) AS laterSessions WHERE laterSessions > 0
+SET s.handoffStatus = 'done'
+RETURN count(s) AS resolved"
+
+Q2_PARAMS=$(jq -n --arg author "$AUTHOR_HANDLE" --arg sessionId "$SESSION_ID" \
+  '{author: $author, sessionId: $sessionId}')
+
+# Q3: Capture the handoff's knowledge-graph neighborhood for artifact rendering.
+# Only the "graph-only" relations — things not already visible in the markdown
+# header. Author/recipients/project live in the metadata row above the graph,
+# so including them would be noise.
+Q3_CYPHER="MATCH (s:Session {id: \$sessionId})
+OPTIONAL MATCH (s)-[:IMPLEMENTS]->(prior:Session)
+OPTIONAL MATCH (prior)-[:BY]->(priorAuthor:Person)
+OPTIONAL MATCH (later:Session)-[:IMPLEMENTS]->(s)
+OPTIONAL MATCH (later)-[:BY]->(laterAuthor:Person)
+OPTIONAL MATCH (s)-[:CONTINUES]->(cont:Session)
+OPTIONAL MATCH (cont)-[:BY]->(contAuthor:Person)
+OPTIONAL MATCH (s)-[:ADVANCED|INVOLVES]->(quest:Quest)
+OPTIONAL MATCH (s)-[:HAS_ACTIVITY]->(art:Artifact)
+OPTIONAL MATCH (s)-[:PRODUCED]->(pr:PR)
+RETURN
+  collect(DISTINCT {id: prior.id, topic: prior.topic, author: priorAuthor.name}) AS implementsHandoff,
+  collect(DISTINCT {id: later.id, topic: later.topic, author: laterAuthor.name}) AS implementedBy,
+  collect(DISTINCT {id: cont.id, topic: cont.topic, author: contAuthor.name}) AS continues,
+  collect(DISTINCT {id: quest.id, title: quest.title}) AS quests,
+  collect(DISTINCT {id: art.id, title: art.title, type: art.type, path: art.path}) AS artifacts,
+  collect(DISTINCT {id: pr.id, number: pr.number, title: pr.title, repo: pr.repo}) AS prs"
+
+Q3_PARAMS=$(jq -n --arg sessionId "$SESSION_ID" '{sessionId: $sessionId}')
+
+# --- Build batch request ---
+BATCH_JSON=$(jq -n \
+  --arg q1 "$Q1_CYPHER" \
+  --argjson p1 "$Q1_PARAMS" \
+  --arg q2 "$Q2_CYPHER" \
+  --argjson p2 "$Q2_PARAMS" \
+  --arg q3 "$Q3_CYPHER" \
+  --argjson p3 "$Q3_PARAMS" \
+  '[{statement: $q1, parameters: $p1}, {statement: $q2, parameters: $p2}, {statement: $q3, parameters: $p3}]')
+
+# --- Execute ---
+RESPONSE=$(bash "$SCRIPT_DIR/bin/graph-batch.sh" "$BATCH_JSON" 2>/dev/null) || {
+  echo '{"error":"graph-batch.sh failed"}'
+  exit 1
+}
+
+# --- Mark auto-captured personal Session as handed_off ---
+PROJ_HASH=$(echo -n "$SCRIPT_DIR" | md5 2>/dev/null || echo -n "$SCRIPT_DIR" | md5sum 2>/dev/null | cut -d' ' -f1)
+CURRENT_SID=$(cat "$HOME/.egregore/session-${PROJ_HASH}.id" 2>/dev/null || echo "")
+if [ -n "$CURRENT_SID" ]; then
+  bash "$SCRIPT_DIR/bin/graph.sh" query \
+    "MATCH (s:Session {id: \$sid}) SET s.status = 'handed_off' RETURN s.id" \
+    "$(jq -n --arg sid "$CURRENT_SID" '{sid: $sid}')" >/dev/null 2>&1 || true
+fi
+
+# --- Parse response ---
+RESOLVED=$(echo "$RESPONSE" | jq -r '.results[1].values[0][0] // 0' 2>/dev/null || echo "0")
+
+# Parse Q3 neighborhood into a subgraph object. Collect() entries that didn't
+# match anything come back as {name: null, ...} — filter those out.
+EMPTY_SG='{"implementsHandoff":[],"implementedBy":[],"continues":[],"quests":[],"artifacts":[],"prs":[]}'
+SUBGRAPH_JSON=$(echo "$RESPONSE" | jq -c '
+  (.results[2] // null) as $r
+  | if $r == null or (($r.values // []) | length) == 0 then
+      {implementsHandoff:[], implementedBy:[], continues:[], quests:[], artifacts:[], prs:[]}
+    else
+      ($r.fields // []) as $f
+      | ($r.values[0] // []) as $v
+      | reduce range(0; ($f | length)) as $i ({}; .[$f[$i]] = $v[$i])
+      | {
+          implementsHandoff: ((.implementsHandoff // []) | map(select(.id != null))),
+          implementedBy:     ((.implementedBy // []) | map(select(.id != null))),
+          continues:         ((.continues // []) | map(select(.id != null))),
+          quests:            ((.quests // []) | map(select(.id != null))),
+          artifacts:         ((.artifacts // []) | map(select(.id != null or .path != null))),
+          prs:               ((.prs // []) | map(select(.number != null or .id != null)))
+        }
+    end
+' 2>/dev/null || echo "$EMPTY_SG")
+[ -z "$SUBGRAPH_JSON" ] && SUBGRAPH_JSON="$EMPTY_SG"
+
+jq -n --arg sessionId "$SESSION_ID" --argjson resolved "$RESOLVED" --argjson subgraph "$SUBGRAPH_JSON" \
+  '{sessionId: $sessionId, resolved: $resolved, subgraph: $subgraph}'

package/runtime/pi/bin/lib/artifact-id.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# artifact-id.sh — Deterministic artifact IDs for memory files.
+#
+# Emits `{prefix}-{12 hex}` where prefix is derived from the file extension
+# (m = .md, h = .html) and the hex is the first 12 chars of sha256(canonical_path).
+#
+# Kept in parity with packages/egregore-artifacts/lib/artifact-id.js — both MUST
+# produce identical output for the same input. Any change here requires an
+# equivalent change there (and a passing parity test in test/artifact-id.test.js).
+
+_artifact_id_sha256() {
+  local input="$1"
+  printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -d' ' -f1 \
+    || printf '%s' "$input" | sha256sum 2>/dev/null | cut -d' ' -f1
+}
+
+# artifact_id_from_path <path>
+# Returns the deterministic artifact id for a repo-relative memory path, or
+# empty (exit 1) if the extension is unsupported.
+artifact_id_from_path() {
+  local raw="$1"
+  [ -n "$raw" ] || return 1
+
+  local canonical
+  canonical="${raw#./}"
+  canonical="$(printf '%s' "$canonical" | sed 's|/\{2,\}|/|g')"
+
+  # Extension match is case-insensitive to keep parity with the JS renderer
+  # (`extension()` in artifact-id.js lowercases before lookup). The canonical
+  # path itself is hashed verbatim — only the extension lookup is case-folded.
+  local ext_lower
+  ext_lower="$(printf '%s' "${canonical##*.}" | tr '[:upper:]' '[:lower:]')"
+
+  local prefix=""
+  case "$ext_lower" in
+    md) prefix="m" ;;
+    html) prefix="h" ;;
+    *) return 1 ;;
+  esac
+
+  local hash
+  hash="$(_artifact_id_sha256 "$canonical")"
+  [ -n "$hash" ] || return 1
+
+  printf '%s-%s' "$prefix" "${hash:0:12}"
+}

package/runtime/pi/bin/lib/config.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Shared config helpers — sourced by session-start.sh and other scripts.
+# Expects SCRIPT_DIR to be set by the caller.
+
+# Load specific variables from .env (safe extraction, no code execution)
+_load_env_var() {
+  local var_name="$1"
+  local env_file="${ENV_FILE:-$SCRIPT_DIR/.env}"
+  if [ -f "$env_file" ]; then
+    grep "^${var_name}=" "$env_file" 2>/dev/null | cut -d'=' -f2- || true
+  fi
+}
+
+# Read a value from egregore.json
+_config_val() {
+  local key="$1"
+  local default="${2:-}"
+  local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
+  if [ -f "$config" ]; then
+    local val
+    val=$(jq -r ".${key} // empty" "$config" 2>/dev/null || true)
+    echo "${val:-$default}"
+  else
+    echo "$default"
+  fi
+}
+
+# Get base branch for a repo. Reads base_branch from egregore.json repos[] config.
+# Defaults to "develop" for backwards compatibility (existing egregores use develop).
+# Only returns something other than "develop" when base_branch is explicitly set
+# (e.g., for teams who added existing repos with a different default branch).
+# Usage: _get_base_branch "repo-name"   (omit for core repo)
+_get_base_branch() {
+  local repo_name="${1:-}"
+  local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
+
+  # Core egregore repo — always develop
+  if [ -z "$repo_name" ]; then
+    echo "develop"
+    return
+  fi
+
+  # Managed repo — check egregore.json for explicit base_branch
+  if [ -f "$config" ]; then
+    local base
+    base=$(jq -r --arg name "$repo_name" \
+      '(.repos[]? // empty) | select((if type == "object" then .name else . end) == $name) | if type == "object" then .base_branch // empty else empty end' \
+      "$config" 2>/dev/null || true)
+    if [ -n "$base" ]; then
+      echo "$base"
+      return
+    fi
+  fi
+
+  # No explicit config — default to develop (backwards compatible)
+  echo "develop"
+}
+
+# Detect local vs connected mode
+_detect_mode() {
+  local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
+  local mode
+  mode=$(jq -r '.mode // empty' "$config" 2>/dev/null || true)
+  local api_url
+  api_url=$(jq -r '.api_url // empty' "$config" 2>/dev/null || true)
+  if [ "$mode" = "local" ] || [ -z "$api_url" ]; then
+    echo "local"
+  else
+    echo "connected"
+  fi
+}