create-egregore 0.19.3 → 0.19.6

package/runtime/codex/bin/agent.sh

@@ -28,6 +28,8 @@ Runtime-neutral commands:
   protocol                         Print the portable agent protocol
   sync                             Pull latest shared memory
   activity [--for <person>]        Show recent handoffs and questions
+  search "query" [-n N] [--fast|--semantic]
+                                   Hybrid recall over shared memory (qmd)
   people                           List known people from memory/people
   branch --topic TEXT              Create or reuse a task branch/worktree
   save [--message TEXT]            Commit and push current repo + memory changes
@@ -165,8 +167,9 @@ Egregore portable agent protocol
 4. Use `bin/agent.sh handoff` to leave structured context for another agent.
 5. Use `bin/agent.sh ask` and `bin/agent.sh answer` for asynchronous questions.
 6. Run `bin/agent.sh activity --for <person>` to see pending work.
-7. Run `bin/agent.sh branch --topic "<what you are working on>"` before code changes when you need a task branch/worktree.
-8. Run `bin/agent.sh save` and `bin/agent.sh wrap` for portable save/wrap flows.
+7. Run `bin/agent.sh search "<query>"` to recall shared memory (decisions, handoffs, knowledge) before answering questions about past work.
+8. Run `bin/agent.sh branch --topic "<what you are working on>"` before code changes when you need a task branch/worktree.
+9. Run `bin/agent.sh save` and `bin/agent.sh wrap` for portable save/wrap flows.
 
 This protocol is runtime-neutral. Claude Code may still use .claude hooks and
 skills, while Codex or another agent can call this script directly.
@@ -653,11 +656,16 @@ cmd_answer() {
   echo "answered: memory/$rel"
 }
 
+cmd_search() {
+  bash "$SCRIPT_DIR/bin/search.sh" query "$@"
+}
+
 case "${1:-}" in
   --help|-h|help|"") usage ;;
   protocol) shift; cmd_protocol "$@" ;;
   sync) shift; cmd_sync "$@" ;;
   activity) shift; cmd_activity "$@" ;;
+  search) shift; cmd_search "$@" ;;
   people) shift; cmd_people "$@" ;;
   branch) shift; cmd_branch "$@" ;;
   save) shift; cmd_save "$@" ;;

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

@@ -71,7 +71,7 @@ for skill_dir in "$SOURCE_DIR"/*; do
   [ -f "$skill_dir/SKILL.md" ] || continue
   name="$(basename "$skill_dir")"
   mkdir -p "$TARGET_DIR/$name"
-  cp "$skill_dir/SKILL.md" "$TARGET_DIR/$name/SKILL.md"
+  cp -R "$skill_dir/." "$TARGET_DIR/$name/"
   copied=$((copied + 1))
 done
 

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

@@ -53,6 +53,11 @@ const AGENTS_PREAMBLE = `# Egregore Agent Protocol
 > Egregore skill already covers. This file exists only for runtimes that cannot
 > read \`CLAUDE.md\`.
 >
+> **If you are Pi** (the \`pi\` coding-agent harness): **stop here.** Your
+> authoritative Egregore instructions are loaded from
+> \`.pi/APPEND_SYSTEM.md\`, and your workflows are exposed through the
+> project-local \`.pi/\` runtime. Do not follow the Codex-specific block below.
+>
 > **If you are Codex or another shell-only agent:** this file is yours — continue.
 
 Egregore is no longer only a Claude Code workspace. Claude Code remains the
@@ -73,6 +78,12 @@ portable memory protocol below.
 Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 \`\`\`bash
+bin/agent.sh branch --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh wrap --from alice --topic "auth review" \\
+  --summary "Implemented the OAuth callback parser and documented follow-ups." \\
+  --body "Open threads: review error cases and browser redirects."
+
 bin/agent.sh handoff --from alice --to bob --topic "auth review" \\
   --body "Implemented the OAuth callback parser. Bob should review error cases."
 
@@ -88,6 +99,17 @@ Each command writes to the existing Git-backed \`memory/\` repository and pushes
 when the memory repo has an \`origin\` remote. Agents that cannot run shell may
 write the same markdown files directly, following \`docs/AGENT-PROTOCOL.md\`.
 
+## Handoffs vs Emissaries
+
+\`bin/agent.sh handoff\` is the runtime-neutral path for internal team
+session-handoffs: it writes to \`memory/handoffs/\`, updates the index, and uses
+the same \`bin/handoff-run.sh\` machinery as Claude Code's \`/handoff\`.
+
+Portable external capsules are **emissaries**, not team handoffs. Claude Code
+routes those through \`/emissary\`; non-Claude agents should use the
+\`egregore-emissary\` CLI/skill when it is installed. Do not use the deprecated
+\`egregore-handoff\` CLI for Egregore project \`/handoff\` work.
+
 ## Compatibility
 
 Claude Code users continue using \`/handoff\`, \`/activity\`, \`/ask\`, \`/save\`, and
@@ -152,7 +174,7 @@ const INTRO_BODY = `You are a collaborator inside Egregore — a shared intellig
 
 This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md (the source of truth for egregore behavior) by \`bin/codex-render-spec.mjs\`. The per-section adaptation manifest is \`.codex/spec-manifest.json\`. The thin agent protocol above this block applies to every shell-capable agent; this block is the full behavioral contract for Codex sessions.`;
 
-const ON_LAUNCH_BODY = `The \`egregore\` launcher renders the Egregore startup card (identity, handoffs, team activity) 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 Egregore startup card (identity, team momentum, and pending work) via \`bin/codex-session-start.sh\` before Codex starts, and installs project skills. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card, run \`bash bin/codex-session-start.sh --card\`.`;
 
 const AFTER_GREETING_BODY = `**Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
 
@@ -216,7 +238,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\`. 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\`, and \`$scroll\`. Every other workflow has a generated adapter skill of the same name. \`$save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.`;
 
 const SOCRATIC_BODY = `**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
 

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

@@ -6,7 +6,7 @@ set -o pipefail
 # libraries as Claude's SessionStart, then renders a terminal greeting before
 # Codex itself starts.
 
-FRAMEWORK_VERSION="3"
+FRAMEWORK_VERSION="6"
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$SCRIPT_DIR" || exit 1
 
@@ -56,6 +56,7 @@ fi
 
 source "$SCRIPT_DIR/bin/lib/git-sync.sh" >/dev/null 2>/dev/null
 source "$SCRIPT_DIR/bin/lib/context.sh" >/dev/null 2>/dev/null
+source "$SCRIPT_DIR/bin/lib/metrics.sh" >/dev/null 2>/dev/null
 trap 'rm -rf "${CTX_DIR:-}"' EXIT
 
 read_json() {
@@ -69,23 +70,6 @@ read_json() {
   fi
 }
 
-shorten() {
-  local value="$1"
-  local max="$2"
-  if command -v jq >/dev/null 2>&1; then
-    jq -nr --arg value "$value" --argjson max "$max" '
-      $value
-      | if length > $max then .[0:($max - 3)] + "..." else . end
-    '
-    return
-  fi
-  if [ "${#value}" -gt "$max" ]; then
-    printf '%s...\n' "${value:0:$((max - 3))}"
-  else
-    printf '%s\n' "$value"
-  fi
-}
-
 ORG_NAME="$(read_json "$CONFIG" '.org_name' '')"
 [ -z "$ORG_NAME" ] && ORG_NAME="$(read_json "$CONFIG" '.slug' 'Egregore')"
 GITHUB_ORG="$(read_json "$CONFIG" '.github_org' '')"
@@ -96,14 +80,12 @@ DISPLAY_NAME="$(read_json "$STATE_FILE" '.display_name' '')"
 ONBOARDING_COMPLETE="$(read_json "$STATE_FILE" '.onboarding_complete' '')"
 [ -z "$ONBOARDING_COMPLETE" ] && ONBOARDING_COMPLETE="unknown"
 
-TEAM_DATA="$(cat "$CTX_DIR/team" 2>/dev/null || echo "[]")"
 ADDRESSED_RICH="$(cat "$CTX_DIR/addressed_rich" 2>/dev/null || echo "[]")"
 PENDING_Q="$(cat "$CTX_DIR/pending_questions" 2>/dev/null || echo "[]")"
-LAST_ACTIVITY="$(cat "$CTX_DIR/activity" 2>/dev/null || true)"
 ADDRESSED_COUNT="$(echo "$ADDRESSED_RICH" | jq 'length' 2>/dev/null || echo "0")"
 PENDING_Q_COUNT="$(echo "$PENDING_Q" | jq 'length' 2>/dev/null || echo "0")"
 
-render_for_you_summary() {
+render_pending_line() {
   if [ "$PENDING_Q_COUNT" -gt 0 ] 2>/dev/null; then
     local senders noun
     senders="$(echo "$PENDING_Q" | jq -r '[.[].from] | unique | join(", ")' 2>/dev/null)"
@@ -115,41 +97,9 @@ render_for_you_summary() {
     fi
   elif [ "$ADDRESSED_COUNT" -gt 0 ] 2>/dev/null; then
     printf '  ◇ %s handoffs for %s - bin/agent.sh activity --for %s\n' "$ADDRESSED_COUNT" "$AUTHOR" "$AUTHOR"
-  else
-    printf '  ◇ nothing pending for %s\n' "$AUTHOR"
-  fi
-}
-
-render_handoff_rows() {
-  if [ "$ADDRESSED_COUNT" -gt 0 ] 2>/dev/null; then
-    echo "$ADDRESSED_RICH" | jq -r '.[] | [.author, .date, .topic] | @tsv' 2>/dev/null | head -4 | while IFS=$'\t' read -r author date topic; do
-      [ -z "$author" ] && continue
-      printf '  ○ %-10s%-12s%s\n' "$(shorten "$author" 9)" "$date" "$(shorten "$topic" 40)"
-    done
-  elif [ -n "$LAST_ACTIVITY" ]; then
-    local last_when last_msg
-    last_when="$(printf '%s\n' "$LAST_ACTIVITY" | cut -d'|' -f1 | sed 's/ hours\{0,1\} ago/h ago/; s/ days\{0,1\} ago/d ago/; s/ minutes\{0,1\} ago/m ago/')"
-    last_msg="$(printf '%s\n' "$LAST_ACTIVITY" | cut -d'|' -f2-)"
-    printf '  ◇ %-10s%-12s%s\n' "you" "$last_when" "$(shorten "$last_msg" 40)"
   fi
 }
 
-render_team_rows() {
-  local now_render online_threshold
-  now_render=$(date +%s)
-  online_threshold=7200
-  echo "$TEAM_DATA" | jq -r '.[] | [.name, .last_seen_sort, .last_seen, (.branches | join(", "))] | @tsv' 2>/dev/null | head -4 | while IFS=$'\t' read -r name epoch seen branches; do
-    [ -z "$name" ] && continue
-    local dot
-    if [ "$epoch" -gt 0 ] 2>/dev/null && [ $((now_render - epoch)) -lt "$online_threshold" ] 2>/dev/null; then
-      dot="●"
-    else
-      dot="○"
-    fi
-    printf '  %s %-10s%-12s%s\n' "$dot" "$(shorten "$name" 9)" "$seen" "$(shorten "$branches" 40)"
-  done
-}
-
 banner() {
   cat <<'EOF'
 
@@ -175,12 +125,8 @@ render_card() {
   banner
   printf '%s%*s%s\n' "$identity_left" "$pad" "" "$identity_right"
   printf '%s\n' "$separator"
-  printf '  ◦ for you\n'
-  render_for_you_summary
-  render_handoff_rows
-  printf '\n'
-  printf '  ◦ around\n'
-  render_team_rows
+  SEPARATOR="$separator" LINE_WIDTH=$line_width _render_momentum_board
+  render_pending_line
   printf '%s\n' "$separator"
 
   has_failure="false"
@@ -229,7 +175,7 @@ Follow AGENTS.md before code changes.
 After the user names what they are working on, use bin/agent.sh branch --topic "<work topic>" if you are not already in an appropriate task worktree, then continue file work from the printed worktree path.
 Use bin/agent.sh to update shared activity: handoff, ask, and answer write to memory/ and push when possible.
 Use bin/agent.sh handoff for internal team session-handoffs. Portable external capsules are emissaries; use egregore-emissary when installed, not the deprecated egregore-handoff CLI.
-Codex reserves leading slash commands for built-ins, so custom Egregore /activity-style commands will not reach the agent. Egregore native Codex skills are: \$activity, \$handoff, \$wrap, \$announce, \$harvest, \$the-spiral, \$dashboard, \$deep-reflect, \$quest, \$invite, \$ask, and \$save. Natural-language requests such as "show activity" or "make a handoff" work too. Remaining mirrored workflows are adapter skills for long-tail coverage.
+Codex reserves leading slash commands for built-ins, so custom Egregore /activity-style commands will not reach the agent. Egregore native Codex skills are: \$activity, \$handoff, \$wrap, \$announce, \$harvest, \$the-spiral, \$dashboard, \$deep-reflect, \$quest, \$invite, \$ask, \$save, \$view, and \$scroll. Natural-language requests such as "show activity", "make a handoff", or "render this as a scroll" work too. Remaining mirrored workflows are adapter skills for long-tail coverage.
 \$save is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory; do not make users manage the git workflow by hand.
 Egregore Codex workflows are skill invocations, not Claude Code slash commands. Do not rely on Claude Code-only command machinery.
 If onboarding_complete is false, use the memory protocol directly and make sure memory/people/${AUTHOR}.md exists before the first handoff.

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

@@ -72,9 +72,10 @@ function truncate(value, max) {
 }
 
 function padLine(left, right = '') {
-  const l = truncate(left, WIDTH - 4);
-  const r = truncate(right, WIDTH - 4);
-  const space = Math.max(1, WIDTH - 4 - l.length - r.length);
+  const inner = WIDTH - 4;
+  const r = right ? truncate(right, Math.min(18, inner - 1)) : '';
+  const l = truncate(left, inner - (r ? r.length + 1 : 0));
+  const space = Math.max(0, inner - l.length - r.length);
   return `│ ${l}${' '.repeat(space)}${r} │`;
 }
 
@@ -143,13 +144,14 @@ function renderActivity(data) {
   const org = data.org || data.organization || 'Egregore';
   const date = data.date || '';
   const me = data.me?.github || data.me?.name || data.github_username || '';
-  const handoffs = firstArray(data, ['handoffs', 'pending_handoffs', 'me.handoffs', 'addressed_handoffs']);
+  const handoffs = firstArray(data, ['handoffs_to_me', 'handoffs', 'pending_handoffs', 'me.handoffs', 'addressed_handoffs']);
   const questions = firstArray(data, ['questions', 'pending_questions', 'me.questions']);
   const prs = asArray(data.prs);
   const mine = firstArray(data, ['local_sessions.my_sessions', 'my_sessions', 'sessions']);
   const team = firstArray(data, ['local_sessions.team_sessions', 'team_sessions', 'team.sessions']);
 
-  const lines = [topRule(), padLine('ACTIVITY', [org, me, date].filter(Boolean).join(' · ')), rule()];
+  const brand = `${truncate(org, 20).toUpperCase()} EGREGORE ✦ ACTIVITY DASHBOARD`;
+  const lines = [topRule(), padLine(brand), padLine([me, date].filter(Boolean).join(' · ')), rule()];
   if (graph.status !== 'connected') {
     lines.push(padLine(`graph: ${graph.status}`, graph.reason));
     lines.push(rule());
@@ -159,12 +161,18 @@ function renderActivity(data) {
   if (questions.length === 0 && handoffs.length === 0) {
     lines.push(padLine('nothing pending'));
   } else {
-    questions.slice(0, 4).forEach((q) => {
-      lines.push(padLine(`? ${valueOf(q, ['from', 'author', 'asker'], 'someone')}: ${valueOf(q, ['topic', 'title', 'question'], 'question')}`));
-    });
-    handoffs.slice(0, 4).forEach((h) => {
-      lines.push(padLine(`> ${valueOf(h, ['author', 'from'], 'someone')}: ${valueOf(h, ['topic', 'title'], 'handoff')}`));
-    });
+    if (questions.length > 0) {
+      lines.push(padLine('QUESTIONS'));
+      questions.slice(0, 4).forEach((q) => {
+        lines.push(padLine(`● ${valueOf(q, ['from', 'author', 'asker'], 'someone')}: ${valueOf(q, ['topic', 'title', 'question'], 'question')}`));
+      });
+    }
+    if (handoffs.length > 0) {
+      lines.push(padLine('HANDOFFS'));
+      handoffs.slice(0, 4).forEach((h) => {
+        lines.push(padLine(`○ ${valueOf(h, ['author', 'from'], 'someone')}: ${valueOf(h, ['topic', 'title'], 'handoff')}`));
+      });
+    }
   }
 
   lines.push(rule());
@@ -284,7 +292,7 @@ function renderHandoff(data) {
     data.notifyStatus ? `notify=${data.notifyStatus}` : '',
   ].filter(Boolean).join(' · ');
 
-  const lines = [topRule(), padLine('HANDOFF', data.author || ''), rule()];
+  const lines = [topRule(), padLine('⇌ HANDOFF', data.author || ''), rule()];
   lines.push(padLine(`Topic: ${data.topic || '(untitled)'}`));
   if (data.recipient) lines.push(padLine(`To: ${data.recipient}`));
   if (file) lines.push(padLine(`Path: ${file}`));

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

@@ -19,6 +19,9 @@ NATIVE_SKILLS=(
   invite
   ask
   save
+  search
+  view
+  scroll
 )
 
 STRUCTURED_UX_SKILLS=(
@@ -54,6 +57,7 @@ STRUCTURED_UX_SKILLS=(
   emissary
   launch-site
   view
+  scroll
   visual-explain
   tui-design
 )

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

@@ -19,8 +19,11 @@ set -euo pipefail
 #                               remove-name to keep-name, stores remove-name as alias
 #   create-harvest <id> <topic> <intent> <initiator>
 #                               Create a Harvest node and link to initiator (WAL-backed)
-#   create-harvest-session <harvest-id> <session-id> <person-name>
-#                               Create a HarvestSession linked to a Harvest and Person
+#   create-harvest-session <harvest-id> <session-id> <person-name> [status]
+#                               Create a HarvestSession linked to a Harvest and Person.
+#                               status defaults to 'active' (back-compat). Valid values:
+#                               pending | active | answered | complete | incorporated.
+#                               Async respondents should be created with 'pending'.
 #   record-harvest-turn <session-id> <turn> <question> <intent> [answer] [eval]
 #                               Record a question-answer turn in a HarvestSession
 #   complete-harvest <harvest-id> <artifact-path>
@@ -42,6 +45,7 @@ if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   echo "  merge-person <keep> <rm> Merge two Person nodes"
   echo "  claim-handoff <sid> <ho> Link implementing session to handoff"
   echo "  create-pr <sid> <num> <repo> <author> [title]"
+  echo "  register-artifact <id> <url> <title> <type> <author> <topics> <excerpt>"
   echo "  create-harvest / complete-harvest / record-harvest-turn"
   echo "  wal-status               Show WAL pending count"
   exit 0
@@ -202,6 +206,39 @@ case "$OP" in
     bash "$GS" query "$CYPHER" "$PARAMS"
     ;;
 
+  register-artifact)
+    # Index a published (hosted) artifact as an Artifact node so the finder can
+    # retrieve it from the graph in connected mode — by content (title/topics/
+    # excerpt CONTAINS) and by relationship (who made it, which quest). The node
+    # id is the registry FILENAME STEM (date-author-slug), matching sync-graph.sh
+    # so a later /save sync upserts the same node instead of duplicating it.
+    # args: <id> <url> <title> <type> <author-handle> <topics-csv> <excerpt>
+    A_ID="${1:?missing id}"
+    A_URL="${2:?missing url}"
+    A_TITLE="${3:-}"
+    A_TYPE="${4:-artifact}"
+    A_AUTHOR="$(printf '%s' "${5:-}" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')"
+    A_TOPICS_JSON="$(printf '%s' "${6:-}" | jq -Rc 'split(",") | map(gsub("^\\s+|\\s+$";"")) | map(select(length > 0))' 2>/dev/null || echo '[]')"
+    A_EXCERPT="$(printf '%s' "${7:-}" | tr '\n' ' ' | cut -c1-2000)"
+    CYPHER="
+      MERGE (a:Artifact {id: \$id})
+      ON CREATE SET a.created = datetime()
+      SET a.title = \$title, a.type = \$type, a.url = \$url,
+          a.topics = \$topics, a.excerpt = \$excerpt, a.published = true
+      WITH a
+      OPTIONAL MATCH (p:Person)
+        WHERE \$author <> '' AND (toLower(p.name) = \$author OR p.github = \$author)
+      FOREACH (_ IN CASE WHEN p IS NOT NULL THEN [1] ELSE [] END |
+        MERGE (a)-[:CONTRIBUTED_BY]->(p))
+      RETURN a.id AS id
+    "
+    PARAMS="$(jq -n --arg id "$A_ID" --arg url "$A_URL" --arg title "$A_TITLE" --arg type "$A_TYPE" \
+      --arg author "$A_AUTHOR" --argjson topics "$A_TOPICS_JSON" --arg excerpt "$A_EXCERPT" \
+      '{id: $id, url: $url, title: $title, type: $type, author: $author, topics: $topics, excerpt: $excerpt}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
   check-implements)
     SID="${1:?missing session-id}"
     bash "$GS" query "
@@ -305,16 +342,30 @@ case "$OP" in
     HID="${1:?missing harvest-id}"
     HSID="${2:?missing session-id}"
     PERSON="${3:?missing person-name}"
-    bash "$GS" query "
+    STATUS="${4:-active}"
+    case "$STATUS" in
+      pending|active|answered|complete|incorporated) ;;
+      *) jq -n --arg s "$STATUS" '{error:("invalid status: "+$s),valid:["pending","active","answered","complete","incorporated"]}' >&2; exit 2 ;;
+    esac
+    CYPHER="
       MATCH (h:Harvest {id: \$hid})
       MERGE (hs:HarvestSession {id: \$hsid})
-      ON CREATE SET hs.status = 'active', hs.created = datetime()
+      ON CREATE SET hs.status = \$status, hs.created = datetime()
       MERGE (h)-[:HAS_SESSION]->(hs)
       WITH hs
       MATCH (p:Person) WHERE toLower(p.name) = toLower(\$person) OR p.github = \$person
       MERGE (hs)-[:WITH]->(p)
       RETURN hs.id AS id, hs.status AS status
-    " "$(jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" '{hid: $hid, hsid: $hsid, person: $person}')"
+    "
+    PARAMS="$(jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" --arg status "$STATUS" '{hid: $hid, hsid: $hsid, person: $person, status: $status}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    OUT="$(bash "$GS" query "$CYPHER" "$PARAMS")"
+    if [ "$(echo "$OUT" | jq -r '.results | length' 2>/dev/null)" = "0" ]; then
+      jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" \
+        '{error:"create-harvest-session: harvest or person not found",hid:$hid,hsid:$hsid,person:$person}' >&2
+      exit 3
+    fi
+    echo "$OUT"
     ;;
 
   record-harvest-turn)

package/runtime/codex/bin/graph.sh

@@ -42,6 +42,22 @@ _millis() {
   fi
 }
 
+# --- Optional read-through cache (opt-in via EGREGORE_GRAPH_CACHE_TTL) ---
+# Read-only queries can be served from a local cache that bin/attendant.sh
+# keeps warm in the background, so callers on the launch path (session-start
+# greeting) pay zero network round-trips when warm. TTL in seconds; unset/0
+# disables. Mutating queries are never cached.
+_CACHE_TTL="${EGREGORE_GRAPH_CACHE_TTL:-0}"
+_CACHE_DIR="$HOME/.egregore/graph-cache/$(echo -n "$SCRIPT_DIR" | cksum | cut -d' ' -f1)"
+
+_cache_key() {
+  echo -n "$1|${2:-}" | cksum | cut -d' ' -f1
+}
+
+_is_read_query() {
+  ! echo "$1" | grep -qiE '\b(MERGE|CREATE|SET|DELETE|DETACH|REMOVE)\b'
+}
+
 if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
   # === API MODE: Call Egregore API gateway ===
 
@@ -54,6 +70,19 @@ if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
       params="{}"
     fi
 
+    local cache_file=""
+    if [ "$_CACHE_TTL" != "0" ] && _is_read_query "$cypher"; then
+      cache_file="$_CACHE_DIR/$(_cache_key "$cypher" "$params").json"
+      if [ -f "$cache_file" ]; then
+        local now cts
+        now=$(date +%s)
+        cts=$(jq -r '.ts // 0' "$cache_file" 2>/dev/null || echo 0)
+        if [ $(( now - cts )) -lt "$_CACHE_TTL" ]; then
+          jq -c '.result' "$cache_file" 2>/dev/null && return 0
+        fi
+      fi
+    fi
+
     local body
     body=$(jq -n --arg stmt "$cypher" --argjson params "$params" \
       '{statement: $stmt, parameters: $params}')
@@ -86,6 +115,13 @@ if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "graph_query" \
       "$(jq -n --argjson latency "$latency_ms" '{latency_ms: $latency}')" 2>/dev/null &
 
+    # Store for the attendant to keep warm (query+params travel with the result)
+    if [ -n "$cache_file" ]; then
+      mkdir -p "$_CACHE_DIR" 2>/dev/null
+      jq -n --arg q "$cypher" --argjson p "$params" --argjson ts "$(date +%s)" --argjson r "$response" \
+        '{query: $q, params: $p, ts: $ts, result: $r}' > "$cache_file" 2>/dev/null || true
+    fi
+
     echo "$response"
   }