create-egregore 0.19.8 → 0.19.11

package/runtime/codex/bin/attendant.sh

@@ -0,0 +1,525 @@
+#!/bin/bash
+# The attendant — Egregore's ambient listener. A per-instance daemon that
+# watches for work Claude Code sessions leave behind when they die without
+# ceremony (terminal closed, laptop shut) and captures it:
+#
+#   ripcord    dead session + no handoff → deterministic auto-handoff to
+#              memory/handoffs/ (kind: ripcord), assembled from the session
+#              transcript + git state. No model, no API calls.
+#   auto-push  dirty/unpushed dev|feature|bugfix branches in this repo's
+#              worktrees, once no session is active → commit + push the
+#              branch. Never merges, never touches develop/main.
+#
+# In-harness hooks (SessionEnd, PreCompact) die with the process; the
+# attendant lives outside it. The signal is Claude Code's own transcript
+# files (~/.claude/projects/<key>/*.jsonl), written continuously regardless
+# of how a session ends: transcript gone stale + work on disk = pull the cord.
+#
+# Usage:
+#   bash bin/attendant.sh ensure   # spawn daemon if not running (fire-and-forget from session-start)
+#   bash bin/attendant.sh run      # daemon loop (foreground)
+#   bash bin/attendant.sh sweep    # single pass (tests, cron)
+#   bash bin/attendant.sh status   # is it alive + last log lines
+#   bash bin/attendant.sh stop     # kill the daemon
+#
+# Env overrides (mainly for tests):
+#   ATTENDANT_STALE_MIN   minutes of transcript silence = dead session (default 12)
+#   ATTENDANT_DRY_RUN=1   log actions, mutate nothing
+#   ATTENDANT_HOME        state dir (default ~/.egregore/attendant)
+#   CLAUDE_PROJECTS_DIR   transcript root (default ~/.claude/projects)
+#   EGREGORE_MEMORY_DIR   memory repo (default <repo>/memory)
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MAIN_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_DIR=$(cd "$WT_GITDIR/../../.." 2>/dev/null && pwd || echo "$SCRIPT_DIR")
+fi
+
+CONFIG="$MAIN_DIR/egregore.json"
+MEMORY_DIR="${EGREGORE_MEMORY_DIR:-$MAIN_DIR/memory}"
+STALE_MIN="${ATTENDANT_STALE_MIN:-12}"
+MAX_AGE_MIN=1440                 # ignore transcripts older than 24h
+RIPCORD_MIN_BYTES=20000          # skip trivial sessions
+DRY_RUN="${ATTENDANT_DRY_RUN:-0}"
+CLAUDE_PROJECTS="${CLAUDE_PROJECTS_DIR:-$HOME/.claude/projects}"
+
+SLUG=$(jq -r '.slug // "egregore"' "$CONFIG" 2>/dev/null || echo "egregore")
+KEY="${SLUG}-$(echo -n "$MAIN_DIR" | cksum | cut -d' ' -f1)"
+STATE_DIR="${ATTENDANT_HOME:-$HOME/.egregore/attendant}"
+PIDFILE="$STATE_DIR/$KEY.pid"
+VERSIONFILE="$STATE_DIR/$KEY.version"
+LOGFILE="$STATE_DIR/$KEY.log"
+JOURNAL="$STATE_DIR/$KEY.journal"
+mkdir -p "$STATE_DIR"
+
+# Munged project key, same rule Claude Code uses for ~/.claude/projects dirs.
+PROJ_KEY=$(echo -n "$MAIN_DIR" | sed 's|[^A-Za-z0-9]|-|g')
+
+log() {
+  echo "$(date '+%Y-%m-%d %H:%M:%S') $*" >> "$LOGFILE"
+  # keep the log bounded
+  if [ "$(wc -c < "$LOGFILE" 2>/dev/null | tr -d ' ')" -gt 1000000 ]; then
+    tail -500 "$LOGFILE" > "$LOGFILE.tmp" && mv "$LOGFILE.tmp" "$LOGFILE"
+  fi
+}
+
+_script_version() {
+  cksum "$MAIN_DIR/bin/attendant.sh" 2>/dev/null | awk '{print $1 ":" $2}'
+}
+
+_enabled() {
+  [ "$(jq -r 'if .features.attendant == false then "false" else "true" end' "$CONFIG" 2>/dev/null)" != "false" ]
+}
+
+_weaver_enabled() {
+  [ "$(jq -r 'if .features.weaver == false then "false" else "true" end' "$CONFIG" 2>/dev/null)" != "false" ]
+}
+
+_trigger_auto_thread() {
+  local reason="$1"
+  local runner="$MAIN_DIR/threads/bin/auto-thread.sh"
+  local dry_arg=""
+  _weaver_enabled || return 0
+  [ -f "$runner" ] || return 0
+  [ "$DRY_RUN" = "1" ] && dry_arg="--dry-run"
+
+  # Projection is downstream of capture. Run it detached so a slow or broken
+  # renderer can never delay ripcord persistence or branch auto-save. The
+  # runner's atomic lock coalesces ripcord + end-of-sweep triggers.
+  (
+    if ! bash "$runner" \
+      --repo-dir "$MAIN_DIR" \
+      --memory-dir "$MEMORY_DIR" \
+      ${dry_arg:+"$dry_arg"}; then
+      log "auto-thread failed ($reason)"
+    fi
+  ) >> "$LOGFILE" 2>&1 &
+}
+
+_author() {
+  local a
+  a=$(jq -r '.github_username // empty' "$MAIN_DIR/.egregore-state.json" 2>/dev/null)
+  [ -z "$a" ] && a=$(git -C "$MAIN_DIR" config user.name 2>/dev/null | tr ' ' '-' | tr '[:upper:]' '[:lower:]')
+  echo "${a:-unknown}"
+}
+
+# --- Session liveness ------------------------------------------------------
+
+_transcript_dirs() {
+  find "$CLAUDE_PROJECTS" -maxdepth 1 -type d -name "${PROJ_KEY}*" 2>/dev/null
+}
+
+_active_session() {
+  local d
+  for d in $(_transcript_dirs); do
+    if [ -n "$(find "$d" -maxdepth 1 -name '*.jsonl' -mmin "-$STALE_MIN" 2>/dev/null | head -1)" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+_stale_transcripts() {
+  local d
+  for d in $(_transcript_dirs); do
+    find "$d" -maxdepth 1 -name '*.jsonl' -mmin "+$STALE_MIN" -mmin "-$MAX_AGE_MIN" -size "+${RIPCORD_MIN_BYTES}c" 2>/dev/null
+  done
+}
+
+# --- Ripcord ---------------------------------------------------------------
+
+_last_prompts() {
+  # Last few human prompts from a transcript, cleaned of harness noise.
+  jq -r 'select(.type=="user") | .message.content
+         | if type=="string" then .
+           else ([.[]? | select(.type?=="text") | .text] | join(" ")) end' "$1" 2>/dev/null \
+    | grep -v -e '^\s*$' -e 'system-reminder' -e '<command-' -e 'tool_use_error' -e '^Caveat:' -e '<task-notification' \
+              -e '<local-command-caveat' -e '</local-command-caveat>' -e '<bash-input>' -e '<bash-stdout>' -e '<bash-stderr>' \
+    | tail -5 | cut -c1-300
+}
+
+_slugify() {
+  printf '%s' "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed 's/<[^>]*>/ /g; s/[`*_#|:;,.!?()[\]{}"'"'"']/ /g; s/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//' \
+    | cut -c1-72 \
+    | sed 's/-$//'
+}
+
+_prompt_topic_slug() {
+  local prompts="$1"
+  local line clean lower slug score best_score=0 best_slug=""
+
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    lower=$(printf '%s' "$line" | tr '[:upper:]' '[:lower:]')
+    case "$lower" in
+      start|*request\ interrupted*|*system-reminder*|*local-command-caveat*|*bash-input*|*bash-stdout*|*bash-stderr*|*tool_use_error*)
+        continue
+        ;;
+    esac
+
+    clean=$(printf '%s' "$line" | sed 's/^>[[:space:]]*//; s/<[^>]*>/ /g; s/[|`*_#]/ /g')
+    slug=$(_slugify "$clean")
+    [ -z "$slug" ] && continue
+    [ "${#slug}" -lt 8 ] && continue
+
+    score=${#slug}
+    case "$slug" in
+      *handoff*|*emissary*|*harvest*|*ssh*|*pr*|*review*|*egregore*|*invite*|*deploy*|*release*)
+        score=$((score + 20))
+        ;;
+    esac
+
+    if [ "$score" -gt "$best_score" ]; then
+      best_score="$score"
+      best_slug="$slug"
+    fi
+  done <<EOF
+$prompts
+EOF
+
+  printf '%s\n' "$best_slug"
+}
+
+_branch_topic_slug() {
+  local gitsum="$1"
+  local author="$2"
+  local branch rest score best_score=0 best_slug=""
+
+  while IFS= read -r branch; do
+    [ -z "$branch" ] && continue
+    case "$branch" in
+      develop|main|master) continue ;;
+      dev/"$author"/*) rest="${branch#dev/$author/}"; score=90 ;;
+      feature/*|bugfix/*|hotfix/*) rest="${branch#*/}"; score=80 ;;
+      dev/*/*) rest="${branch#dev/}"; rest="${rest#*/}"; score=60 ;;
+      */*) rest="${branch#*/}"; score=50 ;;
+      *) rest="$branch"; score=40 ;;
+    esac
+
+    rest=$(_slugify "$rest")
+    [ -z "$rest" ] && continue
+    if [ "$score" -gt "$best_score" ]; then
+      best_score="$score"
+      best_slug="$rest"
+    fi
+  done <<EOF
+$(printf '%s\n' "$gitsum" | awk -F'`' '/^- `/{print $2}')
+EOF
+
+  printf '%s\n' "$best_slug"
+}
+
+_ripcord_topic_slug() {
+  local prompts="$1"
+  local gitsum="$2"
+  local author="$3"
+  local slug
+
+  slug=$(_prompt_topic_slug "$prompts")
+  [ -z "$slug" ] && slug=$(_branch_topic_slug "$gitsum" "$author")
+  [ -z "$slug" ] && slug="session"
+  printf '%s\n' "$slug"
+}
+
+_topic_from_slug() {
+  printf '%s\n' "$1" | tr '-' ' '
+}
+
+_git_summary() {
+  # Branch + dirty/unpushed state for the main checkout and every worktree.
+  local wt branch dirty ahead
+  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)
+    [ -z "$branch" ] && continue
+    dirty=$(git -C "$wt" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    ahead=$(git -C "$wt" rev-list --count '@{u}..HEAD' 2>/dev/null || echo "?")
+    if [ "$dirty" != "0" ] || { [ "$ahead" != "0" ] && [ "$ahead" != "?" ]; }; then
+      echo "- \`$branch\` — $dirty uncommitted, $ahead unpushed ($(basename "$wt"))"
+      git -C "$wt" status --porcelain 2>/dev/null | head -8 | sed 's/^/    /'
+    fi
+  done
+}
+
+_ripcord() {
+  local transcript="$1" base author date_ym date_d slug topic file prompts gitsum
+  base=$(basename "$transcript" .jsonl)
+
+  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
+  # /save skill text mid-way would otherwise false-positive.
+  if tail -c 300000 "$transcript" 2>/dev/null | grep -q -e 'handoff-run.sh' -e 'wraps/'; then
+    echo "ripcord-skip $base (explicit handoff/wrap)" >> "$JOURNAL"
+    return 0
+  fi
+
+  author=$(_author)
+  prompts=$(_last_prompts "$transcript")
+  gitsum=$(_git_summary)
+
+  # Nothing on disk and nothing said — not worth a handoff.
+  if [ -z "$gitsum" ] && [ -z "$prompts" ]; then
+    echo "ripcord-skip $base (no work found)" >> "$JOURNAL"
+    return 0
+  fi
+
+  slug=$(_ripcord_topic_slug "$prompts" "$gitsum" "$author")
+  topic=$(_topic_from_slug "$slug")
+
+  date_ym=$(date '+%Y-%m'); date_d=$(date '+%d')
+  file="$MEMORY_DIR/handoffs/$date_ym/${date_d}-${author}-ripcord-${slug}.md"
+
+  if [ "$DRY_RUN" = "1" ]; then
+    log "DRY ripcord → $file"
+    _trigger_auto_thread "ripcord"
+    return 0
+  fi
+
+  mkdir -p "$(dirname "$file")"
+  {
+    echo "---"
+    echo "date: $(date '+%Y-%m-%d')"
+    echo "author: $author"
+    echo "to: $author"
+    echo "kind: ripcord"
+    echo "status: draft"
+    echo "topic: $topic"
+    echo "---"
+    echo ""
+    echo "# Ripcord: $topic"
+    echo ""
+    echo "Automatic capture — this session ended without an explicit handoff."
+    echo "Assembled by the attendant from the flight recorder (transcript + git state)."
+    echo ""
+    if [ -n "$gitsum" ]; then
+      echo "## Where the work lives"
+      echo ""
+      echo "$gitsum"
+      echo ""
+    fi
+    if [ -n "$prompts" ]; then
+      echo "## Last things the user asked for"
+      echo ""
+      echo "$prompts" | sed 's/^/> /'
+      echo ""
+    fi
+    echo "## Pick it up"
+    echo ""
+    echo "Check out the branch above and run \`/activity\` for surrounding context."
+    echo "Session transcript id: \`$base\` ($(date -r "$transcript" '+%Y-%m-%d %H:%M' 2>/dev/null))"
+  } > "$file"
+
+  # Commit + push memory (retry for concurrent pushers; tolerate no remote).
+  local rel="${file#"$MEMORY_DIR"/}"
+  git -C "$MEMORY_DIR" add "$rel" 2>/dev/null
+  git -C "$MEMORY_DIR" commit -q -m "Ripcord: auto-handoff for $author ($slug)" 2>/dev/null
+  if git -C "$MEMORY_DIR" remote get-url origin >/dev/null 2>&1; then
+    local i
+    for i in 1 2 3; do
+      git -C "$MEMORY_DIR" pull --rebase origin main --quiet 2>/dev/null && \
+        git -C "$MEMORY_DIR" push origin main --quiet 2>/dev/null && break
+      sleep 2
+    done
+  fi
+  bash "$MAIN_DIR/bin/index-handoff.sh" "$rel" >/dev/null 2>&1 || true
+
+  echo "ripcord $base $rel" >> "$JOURNAL"
+  log "ripcord → memory/$rel"
+  _trigger_auto_thread "ripcord"
+}
+
+# --- Auto-push -------------------------------------------------------------
+
+_auto_push() {
+  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)
+    case "$branch" in dev/*|feature/*|bugfix/*) ;; *) continue ;; esac
+    # Mid-rebase/merge — never touch.
+    local gd; gd=$(git -C "$wt" rev-parse --git-dir 2>/dev/null)
+    { [ -d "$gd/rebase-merge" ] || [ -d "$gd/rebase-apply" ] || [ -f "$gd/MERGE_HEAD" ]; } && continue
+
+    dirty=$(git -C "$wt" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    # Only act on work that has itself gone quiet (nothing modified recently).
+    if [ "$dirty" != "0" ]; then
+      local fresh
+      fresh=$(git -C "$wt" status --porcelain 2>/dev/null | sed 's/^...//' | head -50 | while read -r f; do
+        find "$wt/$f" -mmin "-$STALE_MIN" 2>/dev/null | head -1
+      done | head -1)
+      [ -n "$fresh" ] && continue
+      if [ "$DRY_RUN" = "1" ]; then log "DRY auto-commit $branch ($dirty files, $wt)"; else
+        git -C "$wt" add -A 2>/dev/null
+        git -C "$wt" commit -q -m "chore(attendant): ripcord auto-save
+
+Uncommitted work captured after the session went quiet.
+
+Co-Authored-By: Egregore Attendant <noreply@egregore.xyz>" 2>/dev/null
+        log "auto-commit $branch ($dirty files)"
+      fi
+    fi
+
+    upstream=$(git -C "$wt" rev-parse --abbrev-ref '@{u}' 2>/dev/null || true)
+    if [ -z "$upstream" ]; then
+      ahead=$(git -C "$wt" rev-list --count origin/develop..HEAD 2>/dev/null || echo 0)
+    else
+      ahead=$(git -C "$wt" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0)
+    fi
+    if [ "${ahead:-0}" != "0" ]; then
+      if [ "$DRY_RUN" = "1" ]; then log "DRY auto-push $branch ($ahead commits)"; else
+        git -C "$wt" push -u origin "$branch" --quiet 2>/dev/null && log "auto-push $branch ($ahead commits)"
+      fi
+    fi
+  done
+}
+
+# --- Warm: pre-pay the launch path -------------------------------------------
+# Session-start's cost is network: git fetches + the greeting's graph queries.
+# The attendant pays them in the background every WARM_MIN minutes so launch
+# finds fresh refs (git-sync skips its fetch+wait) and a hot graph cache
+# (context.sh reads answers instead of making round-trips). Runs even while
+# sessions are active — fetch and read-only replay are safe mid-work.
+
+WARM_MIN="${ATTENDANT_WARM_MIN:-5}"
+WARM_MARKER="$STATE_DIR/$KEY.warm-ts"
+
+_warm() {
+  local now last
+  now=$(date +%s)
+  last=$(cat "$WARM_MARKER" 2>/dev/null || echo 0)
+  [ $(( now - last )) -lt $(( WARM_MIN * 60 )) ] && return 0
+  [ "$DRY_RUN" = "1" ] && { log "DRY warm"; return 0; }
+
+  git -C "$MAIN_DIR" fetch origin --quiet 2>/dev/null &
+  [ -d "$MEMORY_DIR/.git" ] || [ -f "$MEMORY_DIR/.git" ] && git -C "$MEMORY_DIR" fetch origin --quiet 2>/dev/null &
+  local repo
+  jq -r '(.repos[]? // empty) | if type == "object" then .name else . end' "$CONFIG" 2>/dev/null | while read -r repo; do
+    [ -d "$MAIN_DIR/../$repo/.git" ] && git -C "$MAIN_DIR/../$repo" fetch origin --quiet 2>/dev/null
+  done &
+  wait
+  date +%s > "$WARM_MARKER"
+
+  # Replay graph cache entries touched in the last 24h (connected mode only —
+  # in local mode graph.sh exits instantly and no cache exists).
+  local cache_dir f q p
+  cache_dir="$HOME/.egregore/graph-cache/$(echo -n "$MAIN_DIR" | cksum | cut -d' ' -f1)"
+  if [ -d "$cache_dir" ]; then
+    for f in $(find "$cache_dir" -name '*.json' -mmin -1440 2>/dev/null); do
+      q=$(jq -r '.query // empty' "$f" 2>/dev/null)
+      p=$(jq -c '.params // {}' "$f" 2>/dev/null)
+      [ -n "$q" ] && EGREGORE_GRAPH_CACHE_TTL=1 bash "$MAIN_DIR/bin/graph.sh" query "$q" "$p" >/dev/null 2>&1 || true
+    done
+  fi
+  log "warm: refs fetched, graph cache replayed"
+}
+
+# --- Handoff lifecycle: recurring close / nudge / expiry --------------------
+# Connected-mode only. The job itself filters to lifecycle-v1 handoffs with an
+# explicit intent, so legacy unclassified backfill never runs unattended.
+
+LIFECYCLE_MIN="${ATTENDANT_LIFECYCLE_MIN:-360}"
+LIFECYCLE_MARKER="$STATE_DIR/$KEY.handoff-lifecycle-ts"
+
+_handoff_lifecycle() {
+  local now last mode api_url api_key result
+  [ "$(jq -r '.features.handoff_lifecycle // true' "$CONFIG" 2>/dev/null)" = "true" ] || return 0
+  [ -f "$MAIN_DIR/bin/handoff-lifecycle-job.sh" ] || return 0
+
+  mode=$(jq -r '.mode // "connected"' "$CONFIG" 2>/dev/null)
+  api_url=$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)
+  api_key=$(grep '^EGREGORE_API_KEY=' "$MAIN_DIR/.env" 2>/dev/null | cut -d'=' -f2- || true)
+  [ "$mode" = "connected" ] && [ -n "$api_url" ] && [ -n "$api_key" ] || return 0
+
+  now=$(date +%s)
+  last=$(cat "$LIFECYCLE_MARKER" 2>/dev/null || echo 0)
+  [ $(( now - last )) -lt $(( LIFECYCLE_MIN * 60 )) ] && return 0
+  if [ "$DRY_RUN" = "1" ]; then
+    log "DRY handoff-lifecycle"
+    return 0
+  fi
+
+  if result=$(bash "$MAIN_DIR/bin/handoff-lifecycle-job.sh" run 2>&1); then
+    log "handoff-lifecycle: $(printf '%s' "$result" | jq -c \
+      '{transitions,nudges:(.nudges|length)}' 2>/dev/null || echo success)"
+  else
+    log "handoff-lifecycle failed: $(printf '%s' "$result" | tail -1 | cut -c1-300)"
+  fi
+  date +%s > "$LIFECYCLE_MARKER"
+}
+
+# --- Commands ---------------------------------------------------------------
+
+cmd_sweep() {
+  _enabled || return 0
+  _warm
+  _handoff_lifecycle
+  if _active_session; then
+    log "sweep: session active — standing by"
+    return 0
+  fi
+  local t
+  for t in $(_stale_transcripts); do
+    _ripcord "$t"
+  done
+  _auto_push
+  _trigger_auto_thread "sweep"
+}
+
+cmd_run() {
+  _enabled || exit 0
+  echo $$ > "$PIDFILE"
+  _script_version > "$VERSIONFILE"
+  log "attendant up (pid $$, stale=${STALE_MIN}m, $MAIN_DIR)"
+  while true; do
+    [ -d "$MAIN_DIR" ] || { log "project gone — exiting"; break; }
+    cmd_sweep
+    sleep 60
+  done
+  rm -f "$PIDFILE"
+}
+
+cmd_ensure() {
+  _enabled || exit 0
+  if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE" 2>/dev/null)" 2>/dev/null; then
+    if [ "$(cat "$VERSIONFILE" 2>/dev/null)" = "$(_script_version)" ]; then
+      exit 0
+    fi
+    log "attendant code changed — restarting"
+    kill "$(cat "$PIDFILE")" 2>/dev/null || true
+    rm -f "$PIDFILE"
+  fi
+  nohup bash "$MAIN_DIR/bin/attendant.sh" run >> "$LOGFILE" 2>&1 &
+  disown 2>/dev/null || true
+}
+
+cmd_status() {
+  if [ -f "$PIDFILE" ] && kill -0 "$(cat "$PIDFILE" 2>/dev/null)" 2>/dev/null; then
+    echo "attendant: running (pid $(cat "$PIDFILE"), key $KEY)"
+  else
+    echo "attendant: not running (key $KEY)"
+  fi
+  [ -f "$LOGFILE" ] && tail -5 "$LOGFILE"
+}
+
+cmd_stop() {
+  if [ -f "$PIDFILE" ]; then
+    kill "$(cat "$PIDFILE" 2>/dev/null)" 2>/dev/null
+    rm -f "$PIDFILE" "$VERSIONFILE"
+    echo "attendant: stopped"
+  else
+    echo "attendant: not running"
+  fi
+}
+
+case "${1:-}" in
+  ensure) cmd_ensure ;;
+  run)    cmd_run ;;
+  sweep)  cmd_sweep ;;
+  status) cmd_status ;;
+  stop)   cmd_stop ;;
+  *) echo "usage: bash bin/attendant.sh {ensure|run|sweep|status|stop}" >&2; exit 1 ;;
+esac

package/runtime/codex/bin/capture-reconcile.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -euo pipefail
+
+# Detached reconciliation worker for explicit captures.
+# The foreground path only appends to graph-wal.sh; this worker pays network
+# latency, retries queued writes, and sends completion notifications.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MODE="$(jq -r '.mode // "connected"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo connected)"
+[ "$MODE" = "connected" ] || exit 0
+
+SESSION_ID=""
+AUTHOR=""
+SUMMARY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --session-id) SESSION_ID="${2:-}"; shift 2 ;;
+    --author) AUTHOR="${2:-}"; shift 2 ;;
+    --summary) SUMMARY="${2:-}"; shift 2 ;;
+    *) echo "Unknown reconcile option: $1" >&2; exit 1 ;;
+  esac
+done
+[ -n "$SESSION_ID" ] || exit 0
+
+# Applies Session capture first, then the idempotent handoff transition.
+bash "$SCRIPT_DIR/bin/graph-wal.sh" drain >/dev/null 2>&1 || exit 0
+
+# Claim completion notifications atomically. A stale claim can be retried;
+# successful sends are permanently marked on the IMPLEMENTS relationship.
+# shellcheck disable=SC2016 # $name tokens are Cypher parameters.
+CLAIM_CYPHER='
+  MATCH (impl:Session {id: $sessionId})-[r:IMPLEMENTS]->(ho:Session)-[:BY]->(origin:Person)
+  WHERE ho.handoffStatus = "done"
+    AND r.completionNotifiedAt IS NULL
+    AND (r.completionNotifyClaimedAt IS NULL
+         OR r.completionNotifyClaimedAt < datetime() - duration("PT1H"))
+  SET r.completionNotifyClaimedAt = datetime()
+  RETURN ho.id AS handoffId, ho.topic AS topic,
+         coalesce(origin.github, origin.name) AS recipient'
+PARAMS="$(jq -nc --arg sessionId "$SESSION_ID" '{sessionId:$sessionId}')"
+CLAIMS="$(bash "$SCRIPT_DIR/bin/graph.sh" query "$CLAIM_CYPHER" "$PARAMS" 2>/dev/null || echo '{}')"
+
+printf '%s' "$CLAIMS" | jq -r '.values[]? | @tsv' 2>/dev/null |
+while IFS=$'\t' read -r handoff_id topic recipient; do
+  [ -n "$handoff_id" ] && [ -n "$recipient" ] || continue
+  message="${AUTHOR:-A teammate} completed your handoff '${topic:-$handoff_id}'"
+  [ -n "$SUMMARY" ] && message="${message} — $(printf '%s' "$SUMMARY" | tr '\n' ' ' | cut -c1-180)"
+
+  notify_result="$(bash "$SCRIPT_DIR/bin/notify.sh" send "$recipient" "$message" 2>/dev/null || echo Failed)"
+  if printf '%s' "$notify_result" | grep -qi '^Sent'; then
+    bash "$SCRIPT_DIR/bin/graph.sh" query '
+      MATCH (impl:Session {id: $sessionId})-[r:IMPLEMENTS]->(ho:Session {id: $handoffId})
+      SET r.completionNotifiedAt = datetime(),
+          r.completionNotifyClaimedAt = null
+      RETURN ho.id AS id
+    ' "$(jq -nc --arg sessionId "$SESSION_ID" --arg handoffId "$handoff_id" \
+      '{sessionId:$sessionId,handoffId:$handoffId}')" >/dev/null 2>&1 || true
+  else
+    bash "$SCRIPT_DIR/bin/graph.sh" query '
+      MATCH (impl:Session {id: $sessionId})-[r:IMPLEMENTS]->(ho:Session {id: $handoffId})
+      SET r.completionNotifyClaimedAt = null,
+          r.completionNotifyFailedAt = datetime()
+      RETURN ho.id AS id
+    ' "$(jq -nc --arg sessionId "$SESSION_ID" --arg handoffId "$handoff_id" \
+      '{sessionId:$sessionId,handoffId:$handoffId}')" >/dev/null 2>&1 || true
+  fi
+done