create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/bin/search.sh

@@ -0,0 +1,318 @@
+#!/usr/bin/env bash
+# Compatibility shell for Egregore's Local Retriever.
+# Usage:
+#   bash bin/search.sh query "text" [-n N] [--fast|--semantic] [--recent-days N] [--min-evidence N] [--compact] [--context-packet] [--enrich] [--all] [--new-search]
+#   bash bin/search.sh reindex [--embed]
+#   bash bin/search.sh install
+#   bash bin/search.sh status
+#   bash bin/search.sh start
+#   bash bin/search.sh stop
+#   bash bin/search.sh open memory/path/to/source.md
+#
+# The shell owns the established user-facing output. Retrieval infrastructure
+# is isolated behind the Egregore Retriever adapter.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MEM_PATH="$(readlink -f "$SCRIPT_DIR/memory" 2>/dev/null || true)"
+
+_runtime() {
+  EGREGORE_ROOT="$SCRIPT_DIR" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.harness_cli "$@"
+}
+
+# Explicit index provisioning/rebuild remains a maintenance compatibility
+# surface. Normal harness query/open/lifecycle traffic never enters this
+# implementation-specific bridge.
+_maintenance_runtime() {
+  EGREGORE_ROOT="$SCRIPT_DIR" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.adapters.qmd_cli "$@"
+}
+
+_result_paths() {
+  local line path canonical_prefix
+  canonical_prefix="**file:** \`memory/"
+  while IFS= read -r line || [ -n "$line" ]; do
+    path=""
+    if [[ "$line" == *"$canonical_prefix"* ]]; then
+      path="${line#*"$canonical_prefix"}"
+    fi
+    path="${path%%\`*}"
+    case "$path" in
+      *.md*) printf '%s\n' "${path%%.md*}.md" ;;
+    esac
+  done | sort -u
+}
+
+# Legacy explicit graph annotation remains available while the graph is moved
+# behind its projection boundary. It is intentionally never selected by the
+# default Local retrieval path.
+#
+# An instance whose Runtime MVP upgrade has been activated retrieves through
+# Runtime/QMD exclusively: even the explicit --enrich flag makes zero graph
+# calls there. The dormant graph configuration is preserved untouched for
+# rollback only.
+_upgrade_instance_key() {
+  # Mirrors egregore_runtime.upgrade.instance_key: stable org identity
+  # composed with the main installation path. No org_id → fail closed.
+  local org main gitdir
+  org=$(jq -r '.org_id // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+  [ -n "$org" ] || return 1
+  main="$SCRIPT_DIR"
+  if [ -f "$SCRIPT_DIR/.git" ]; then
+    gitdir=$(sed -n 's/^gitdir: //p' "$SCRIPT_DIR/.git" 2>/dev/null)
+    case "$gitdir" in
+      */.git/worktrees/*) main="${gitdir%/.git/worktrees/*}" ;;
+    esac
+  fi
+  main=$(cd "$main" 2>/dev/null && pwd -P) || return 1
+  printf '%s|%s' "$org" "$main" | shasum -a 256 2>/dev/null | cut -c1-16
+}
+
+_upgraded_runtime_active() {
+  local key record
+  key=$(_upgrade_instance_key) || return 1
+  [ -n "$key" ] || return 1
+  record="${EGREGORE_UPGRADE_ROOT:-$HOME/.egregore/runtime/upgrade}/${key}/active.json"
+  [ -f "$record" ] || return 1
+  [ "$(jq -r '.retrieval // empty' "$record" 2>/dev/null)" = "runtime-qmd" ]
+}
+
+_enrich() {
+  local results paths params out
+  results=$(cat)
+  echo "$results"
+  if _upgraded_runtime_active; then
+    echo "↳ graph retrieval: not used by this Runtime version"
+    return 0
+  fi
+  paths=$(printf '%s\n' "$results" | _result_paths)
+  [ -z "$paths" ] && return 0
+  params=$(printf '%s\n' "$paths" | jq -R . | jq -sc '{paths: .}')
+  out=$(bash "$SCRIPT_DIR/bin/graph.sh" query "UNWIND \$paths AS fp
+    OPTIONAL MATCH (s:Session {filePath: fp})
+    OPTIONAL MATCH (a:Artifact {filePath: fp})
+    WITH fp, s, a WHERE s IS NOT NULL OR a IS NOT NULL
+    RETURN fp,
+      CASE WHEN s IS NOT NULL THEN coalesce(s.handoffStatus, s.status) ELSE null END AS sessionStatus,
+      s.handedTo AS handedTo, a.type AS artifactType,
+      CASE WHEN a IS NOT NULL THEN [q IN [(a)-[:PART_OF]->(qq:Quest) | qq.id] | q][0] ELSE null END AS quest" \
+    "$params" 2>/dev/null)
+  echo "$out" | jq -r '.values[]? | @tsv' 2>/dev/null | while IFS=$'\t' read -r fp sstat sto atype quest; do
+    local ann=""
+    [ -n "$sstat" ] && [ "$sstat" != "null" ] && ann="status: $sstat"
+    [ -n "$sto" ] && [ "$sto" != "null" ] && ann="$ann${ann:+ · }to: $sto"
+    [ -n "$atype" ] && [ "$atype" != "null" ] && ann="$ann${ann:+ · }artifact: $atype"
+    [ -n "$quest" ] && [ "$quest" != "null" ] && ann="$ann${ann:+ · }quest: $quest"
+    [ -n "$ann" ] && echo "↳ graph · $fp — $ann"
+  done
+}
+
+_banner_and_emit() {
+  local label="$1" t0="$2" emit="$3" out="$4" hide_results="${5:-0}"
+  local hits dur product surface plural="" gap actual required
+  if [[ "$out" == EGREGORE_OBSERVE_CONTEXT_REUSED* ]]; then
+    printf '⌕ Egregore · using context already compiled for this prompt · 0s\n\n'
+    [ "$hide_results" = 1 ] || printf '%s\n' "$out" | tail -n +2
+    return 0
+  fi
+  gap=$(printf '%s\n' "$out" | head -n 1)
+  if [[ "$gap" == EGREGORE_EVIDENCE_GAP* ]]; then
+    actual="${gap#*actual=}"
+    actual="${actual%% *}"
+    required="${gap#*required=}"
+    required="${required%% *}"
+    dur=$(( $(date +%s) - t0 ))
+    printf '⌕ Egregore · searching your organization’s memory · %s · evidence gap · %s/%s sources · %ss\n\n' \
+      "$label" "$actual" "$required" "$dur"
+    [ "$hide_results" = 1 ] || printf '%s\n' "$out" | tail -n +2
+    return 0
+  fi
+  hits=$(printf '%s\n' "$out" | _result_paths | wc -l | tr -d ' ')
+  dur=$(( $(date +%s) - t0 ))
+  product="Egregore"
+  surface="searching your organization’s memory"
+  if [ "$emit" = "_enrich" ] && [ "$hits" -gt 0 ]; then
+    product="Egregore Connect"
+    surface="${surface} and relationships"
+  fi
+  [ "$hits" != "1" ] && plural="s"
+  local line="⌕ ${product} · ${surface} · ${label} · ${hits} hit${plural} · ${dur}s"
+  if [ -t 1 ]; then
+    printf '\033[1;38;5;30m%s\033[0m\n\n' "$line"
+  else
+    printf '%s\n\n' "$line"
+  fi
+  [ "$hide_results" = 1 ] || printf '%s\n' "$out" | "$emit"
+}
+
+_context_packet_path() {
+  local session context_dir
+  # Same precedence as the Python runtime's session identity: an explicit
+  # EGREGORE_SESSION_ID wins, the session file is the fallback.
+  session="${EGREGORE_SESSION_ID:-}"
+  [ -n "$session" ] || session=$(cat "$SCRIPT_DIR/.egregore-session-id" 2>/dev/null || true)
+  session=$(printf '%s' "$session" | tr -cd 'A-Za-z0-9_.-')
+  [ -n "$session" ] || return 1
+  context_dir="${TMPDIR:-/tmp}/egregore-retrieval-context"
+  mkdir -p "$context_dir" 2>/dev/null || return 1
+  chmod 700 "$context_dir" 2>/dev/null || true
+  printf '%s/%s.context\n' "$context_dir" "$session"
+}
+
+cmd_query() {
+  local mode="lex+vec" label="hybrid" n=6 enrich=0 all=0 new_search=0 recent_days="" min_evidence=1 compact=0 context_packet=0
+  local -a words=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --fast) mode="lex"; label="keyword" ;;
+      --semantic) mode="vec"; label="semantic" ;;
+      --enrich) enrich=1 ;;
+      --no-enrich) enrich=0 ;;
+      --all) all=1 ;;
+      --new-search) new_search=1 ;;
+      --recent-days)
+        [ $# -ge 2 ] || { echo "search: --recent-days requires a positive integer" >&2; return 1; }
+        recent_days="$2"
+        shift
+        ;;
+      --min-evidence)
+        [ $# -ge 2 ] || { echo "search: --min-evidence requires a positive integer" >&2; return 1; }
+        min_evidence="$2"
+        shift
+        ;;
+      --compact) compact=1 ;;
+      --context-packet) context_packet=1 ;;
+      -n)
+        [ $# -ge 2 ] || { echo "search: -n requires a positive integer" >&2; return 1; }
+        n="$2"
+        shift
+        ;;
+      *) words+=("$1") ;;
+    esac
+    shift
+  done
+  local q="${words[*]}"
+  if [ -z "$q" ]; then
+    echo "usage: bash bin/search.sh query \"text\" [-n N] [--fast|--semantic] [--recent-days N] [--min-evidence N] [--compact] [--context-packet] [--all] [--new-search]" >&2
+    return 1
+  fi
+  [[ "$n" =~ ^[1-9][0-9]*$ ]] || { echo "search: -n requires a positive integer" >&2; return 1; }
+  [ -z "$recent_days" ] || [[ "$recent_days" =~ ^[1-9][0-9]*$ ]] || {
+    echo "search: --recent-days requires a positive integer" >&2
+    return 1
+  }
+  [[ "$min_evidence" =~ ^[1-9][0-9]*$ ]] || {
+    echo "search: --min-evidence requires a positive integer" >&2
+    return 1
+  }
+  [ "$all" = 1 ] && n=10000
+
+  local -a args=(query --task "$q" --mode "$mode" --limit "$n")
+  [ "$new_search" = 1 ] && args+=(--new-search)
+  [ -n "$recent_days" ] && args+=(--recent-days "$recent_days")
+  args+=(--min-evidence "$min_evidence")
+  [ "$compact" = 1 ] && args+=(--compact)
+  case "$mode" in
+    lex) args+=(--lex "$q") ;;
+    vec) args+=(--vec "$q") ;;
+    lex+vec) args+=(--lex "$q" --vec "$q") ;;
+  esac
+
+  local t0 out emit="cat" query_rc
+  t0=$(date +%s)
+  out=$(_runtime "${args[@]}" 2>&1)
+  query_rc=$?
+  if [ "$query_rc" -ne 0 ]; then
+    {
+      echo "⚠ Egregore Runtime retrieval failed."
+      printf '%s\n' "$out" | tail -3 | sed 's/^/  /'
+      echo "This is a Runtime failure — do not fall back to manual scanning (rg/grep/ls over memory), a global qmd, npx, or graph."
+      echo "Diagnose with: bash bin/search.sh readiness · report with /issue · stop here."
+    } >&2
+    return "$query_rc"
+  fi
+  [ "$enrich" = 1 ] && emit="_enrich"
+  if [ "$context_packet" = 1 ]; then
+    local packet
+    packet=$(_context_packet_path) || {
+      echo "search: context packet requires an active Egregore session" >&2
+      return 1
+    }
+    umask 077
+    printf '%s\n' "$out" > "$packet"
+    _banner_and_emit "$label" "$t0" "$emit" "$out" 1
+  else
+    _banner_and_emit "$label" "$t0" "$emit" "$out"
+  fi
+}
+
+cmd_reindex() {
+  local -a args=(update)
+  [ "${1:-}" = "--embed" ] && args+=(--embed)
+  _maintenance_runtime "${args[@]}"
+}
+
+cmd_status() {
+  _runtime status
+  echo ""
+  echo "canonical memory: $MEM_PATH"
+}
+
+case "${1:-}" in
+  query) shift; cmd_query "$@" ;;
+  reindex) shift; cmd_reindex "$@" ;;
+  install) shift; _maintenance_runtime install "$@" ;;
+  status) shift; cmd_status ;;
+  readiness) shift; _runtime readiness "$@" ;;
+  handoffs)
+    shift
+    if ! _runtime handoffs "$@"; then
+      {
+        echo "⚠ Egregore Runtime lifecycle lookup failed."
+        echo "This is a Runtime failure — do not fall back to manual scanning (ls/rg/grep over memory), a semantic re-query, or graph."
+        echo "Diagnose with: bash bin/search.sh readiness · report with /issue · stop here."
+      } >&2
+      exit 1
+    fi
+    ;;
+  start) shift; _runtime start "$@" ;;
+  stop) shift; _runtime stop "$@" ;;
+  open)
+    shift
+    OPEN_PACKET=0; OPEN_PATH=""
+    for _arg in "$@"; do
+      case "$_arg" in
+        --context-packet) OPEN_PACKET=1 ;;
+        *) OPEN_PATH="$_arg" ;;
+      esac
+    done
+    if [ "$OPEN_PACKET" = 1 ]; then
+      # Claude: full documents attach privately through the PostToolUse
+      # packet instead of splashing raw markdown into the transcript —
+      # the same contract query --context-packet already follows.
+      packet=$(_context_packet_path) || {
+        echo "search: context packet requires an active Egregore session" >&2
+        exit 1
+      }
+      umask 077
+      if _runtime open "$OPEN_PATH" > "$packet" 2>"$packet.err"; then
+        rm -f "$packet.err"
+        echo "↳ opened $OPEN_PATH · content attached privately"
+      else
+        cat "$packet.err" >&2 2>/dev/null
+        rm -f "$packet" "$packet.err"
+        exit 1
+      fi
+    else
+      _runtime open "$OPEN_PATH"
+    fi
+    ;;
+  *)
+    echo "usage: bash bin/search.sh {query|reindex|install|start|stop|status|readiness|open}" >&2
+    exit 1
+    ;;
+esac

package/runtime/claude/bin/session-autosave.sh

@@ -0,0 +1,220 @@
+#!/usr/bin/env bash
+# session-autosave.sh — save non-coding session work without an explicit /save.
+#
+# Terminal-close is the design constraint: no single "session end" event is
+# reliable (people just close the window), so durability comes from three
+# overlapping triggers:
+#   - Stop hook, debounced (Claude Code): saves DURING the session, after a
+#     turn completes — a killed terminal loses at most the debounce window.
+#   - Session-start sweep (--sweep, all runtimes): the next launch on this
+#     machine rescues leftovers in the main checkout and lingering worktrees.
+#   - SessionEnd hook / agent.sh wrap (Codex, Pi): immediate save on clean exit.
+#
+# Gate: acts ONLY when every pending change — uncommitted files AND commits
+# ahead of origin/develop — is non-coding per bin/lib/noncode.sh. Any code in
+# the pending set → exit silently; code always goes through explicit /save and
+# review. Never auto-commits half-finished code.
+#
+# When the gate passes, delegates commit→push→PR→auto-merge to
+# handoff-save-egregore.sh (--kind autosave), and pushes the memory repo.
+#
+# Usage:
+#   session-autosave.sh [--dir <repo-dir>] [--author <name>]
+#                       [--debounce <sec>] [--min-idle <sec>] [--sweep]
+#   --debounce  skip if this dir was autosaved less than <sec> ago (Stop hook)
+#   --min-idle  skip if any dirty file was modified less than <sec> ago
+#               (don't commit prose someone is actively typing)
+#   --sweep     iterate main checkout + .claude/worktrees/* (session start)
+#   (Hook invocations pass nothing; stdin JSON supplies cwd.)
+
+set -uo pipefail
+
+# shellcheck source=bin/lib/git-message.sh
+. "$(cd "$(dirname "$0")" && pwd)/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" "$@"
+}
+
+DIR=""
+AUTHOR=""
+DEBOUNCE=0
+MIN_IDLE=0
+SWEEP=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) DIR="${2:-}"; shift 2 ;;
+    --author) AUTHOR="${2:-}"; shift 2 ;;
+    --debounce) DEBOUNCE="${2:-0}"; shift 2 ;;
+    --min-idle) MIN_IDLE="${2:-0}"; shift 2 ;;
+    --sweep) SWEEP=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+SCRIPT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# --- Sweep mode: rescue abandoned checkouts, then exit -------------------
+if [ "$SWEEP" = "1" ]; then
+  # Let session-start's own git syncs settle before touching the checkout.
+  sleep 15
+  for d in "$SCRIPT_ROOT" "$SCRIPT_ROOT"/.claude/worktrees/*/; do
+    d="${d%/}"
+    [ -d "$d" ] || continue
+    # min-idle protects live sessions in other terminals: never commit files
+    # someone touched in the last 10 minutes. debounce dedupes concurrent
+    # session launches sweeping the same dirs.
+    bash "$0" --dir "$d" --min-idle 600 --debounce 120 >/dev/null 2>&1 || true
+  done
+  exit 0
+fi
+
+# Hook invocations deliver JSON on stdin (cwd = where the session worked).
+if [ -z "$DIR" ] && [ ! -t 0 ]; then
+  HOOK_INPUT=$(cat 2>/dev/null || true)
+  DIR=$(echo "$HOOK_INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+fi
+
+[ -n "$DIR" ] && [ -d "$DIR" ] || DIR="$SCRIPT_ROOT"
+cd "$DIR" 2>/dev/null || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+# --- Debounce (per-dir stamp) --------------------------------------------
+# NB: `cmd | cut || fallback` doesn't work — cut succeeds on empty input, so
+# the fallback never fires and every dir collapses to one stamp (macOS has
+# md5, not md5sum). Group the hash commands, then cut.
+DIR_HASH=$( { md5sum <<<"$DIR" 2>/dev/null || md5 -q -s "$DIR" 2>/dev/null || echo default; } | cut -c1-8 )
+STAMP="/tmp/.egregore-autosave-${DIR_HASH}"
+if [ "$DEBOUNCE" -gt 0 ] && [ -f "$STAMP" ]; then
+  if stat -c %Y "$STAMP" >/dev/null 2>&1; then
+    LAST=$(stat -c %Y "$STAMP")
+  else
+    LAST=$(stat -f %m "$STAMP" 2>/dev/null || echo 0)
+  fi
+  case "$LAST" in ""|*[!0-9]*) LAST=0 ;; esac
+  [ $(( $(date +%s) - LAST )) -lt "$DEBOUNCE" ] && exit 0
+fi
+touch "$STAMP" 2>/dev/null || true
+
+# shellcheck source=bin/lib/noncode.sh
+. "$SCRIPT_ROOT/bin/lib/noncode.sh" 2>/dev/null || exit 0
+
+# --- Per-user consent settings (bin/autosave.sh / the /autosave skill) ----
+# enabled=false  → fully off, nothing captured ambiently
+# scope=handoffs → memory repo only; the core repo is never touched ambiently
+# publish=gate   → PR is opened but NEVER merged without the user's word
+# NB: jq's `//` swallows false (falsy) — `.k // empty` on k:false yields the
+# default, silently re-enabling autosave. Test key presence instead (this is
+# the same trap that broke auto_update:false).
+_as_conf() { # key default
+  local v
+  v=$(jq -r "if (.$1 != null) then (.$1|tostring) else empty end" "$DIR/.egregore-state.json" 2>/dev/null)
+  [ -n "$v" ] || v=$(jq -r "if (.$1 != null) then (.$1|tostring) else empty end" "$SCRIPT_ROOT/.egregore-state.json" 2>/dev/null)
+  [ -n "$v" ] && echo "$v" || echo "$2"
+}
+# Autosave is an opt-in experiment: enabled defaults to FALSE. Nothing is
+# captured ambiently until the user runs `/autosave on` (or autosave.sh on).
+AS_ENABLED=$(_as_conf autosave_enabled false)
+AS_SCOPE=$(_as_conf autosave_scope all)
+AS_PUBLISH=$(_as_conf autosave_publish gate)
+[ "$AS_ENABLED" = "true" ] || exit 0
+
+if [ -z "$AUTHOR" ]; then
+  AUTHOR=$(jq -r '.github_username // .name // empty' "$DIR/.egregore-state.json" 2>/dev/null || true)
+  [ -n "$AUTHOR" ] || AUTHOR=$(jq -r '.github_username // .name // empty' "$SCRIPT_ROOT/.egregore-state.json" 2>/dev/null || true)
+  [ -n "$AUTHOR" ] || AUTHOR=$(git config user.name 2>/dev/null | tr '[:upper:] ' '[:lower:]-' || true)
+  [ -n "$AUTHOR" ] || AUTHOR="egregore"
+fi
+
+# --- Memory repo: markdown by definition, push straight to main ----------
+if git -C "$DIR/memory" rev-parse --git-dir >/dev/null 2>&1; then
+  if [ -n "$(git -C "$DIR/memory" status --porcelain 2>/dev/null)" ]; then
+    git -C "$DIR/memory" add -A >/dev/null 2>&1 || true
+    egregore_commit "$DIR/memory" "$DIR" "chore(autosave): save session work" --quiet 2>/dev/null || true
+  fi
+  if [ -n "$(git -C "$DIR/memory" log origin/main..HEAD --oneline 2>/dev/null)" ]; then
+    for _try in 1 2 3; do
+      if git -C "$DIR/memory" pull --rebase origin main --quiet 2>/dev/null \
+         && git -C "$DIR/memory" push origin main --quiet 2>/dev/null; then
+        break
+      fi
+      sleep 1
+    done
+  fi
+fi
+
+# scope=handoffs: memory (above) is the handoff channel; stop before the
+# core repo — it is never captured ambiently under this scope.
+[ "$AS_SCOPE" = "handoffs" ] && exit 0
+
+# --- Core repo gate: everything pending must be non-coding ---------------
+# -uall expands untracked dirs to individual files: a collapsed "docs/" entry
+# would defeat both the classifier (code nested under a content dir) and the
+# idle guard (directory mtime, not file mtime).
+DIRTY_PATHS=$(git status --porcelain -uall 2>/dev/null | cut -c4- | sed 's/.* -> //' | sed '/^$/d')
+PENDING=$(
+  {
+    printf '%s\n' "$DIRTY_PATHS"
+    git diff origin/develop...HEAD --name-only 2>/dev/null
+  } | sed '/^$/d'
+)
+[ -n "$PENDING" ] || exit 0
+
+BLOCKER=$(printf '%s\n' "$PENDING" | noncode_filter)
+if [ -n "$BLOCKER" ]; then
+  # Code in the pending set — leave it for an explicit /save + review.
+  exit 0
+fi
+
+# --- Idle guard: don't commit files someone is actively editing ----------
+if [ "$MIN_IDLE" -gt 0 ] && [ -n "$DIRTY_PATHS" ]; then
+  NOW=$(date +%s)
+  while IFS= read -r f; do
+    [ -e "$f" ] || continue
+    M=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    [ $(( NOW - M )) -lt "$MIN_IDLE" ] && exit 0
+  done <<< "$DIRTY_PATHS"
+fi
+
+ORIG_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+bash "$SCRIPT_ROOT/bin/handoff-save-egregore.sh" "$AUTHOR" \
+  "session content $(date +%Y-%m-%d)" --kind autosave --repo-dir "$DIR" \
+  --branch-suffix "$DIR_HASH" --publish "$AS_PUBLISH" \
+  >/dev/null 2>&1 || true
+
+# Tell the user what just happened. Under the Stop hook this line surfaces in
+# the Claude Code UI; sweep/SessionEnd invocations discard stdout (their trail
+# is the ledger, reported by the next greeting).
+LEDGER="${EGREGORE_AUTOSAVE_LOG:-$HOME/.egregore/autosave.log}"
+LAST=$(grep -F "|autosave|$DIR|" "$LEDGER" 2>/dev/null | tail -1 || true)
+if [ -n "$LAST" ]; then
+  TS=$(echo "$LAST" | cut -d'|' -f1)
+  PR=$(echo "$LAST" | cut -d'|' -f5)
+  RESULT=$(echo "$LAST" | cut -d'|' -f6)
+  NF=$(echo "$LAST" | cut -d'|' -f7)
+  NOW_EPOCH=$(date +%s)
+  TS_EPOCH=$(date -u -j -f %Y-%m-%dT%H:%M:%SZ "$TS" +%s 2>/dev/null || date -u -d "$TS" +%s 2>/dev/null || echo 0)
+  if [ $(( NOW_EPOCH - TS_EPOCH )) -lt 120 ]; then
+    case "$RESULT" in
+      merged) echo "⟲ auto-saved: $NF non-coding file(s) → develop (PR #$PR merged)" ;;
+      staged) echo "⟲ auto-saved: $NF non-coding file(s) → PR #$PR — yours to merge (say \"merge my auto-saves\" or /autosave)" ;;
+      open)   echo "⟲ auto-saved: $NF non-coding file(s) → PR #$PR (merge pending)" ;;
+      *)      echo "⟲ auto-saved: $NF non-coding file(s) → branch pushed (PR pending)" ;;
+    esac
+  fi
+fi
+
+# The helper branches off protected branches before committing. If this
+# checkout was on develop/main (e.g. the main checkout during a sweep),
+# restore it so the next session doesn't land on a stray autosave branch.
+case "$ORIG_BRANCH" in
+  develop|main|master)
+    CUR=$(git branch --show-current 2>/dev/null || echo "")
+    if [ "$CUR" != "$ORIG_BRANCH" ]; then
+      git checkout "$ORIG_BRANCH" --quiet 2>/dev/null || true
+      git pull --ff-only origin "$ORIG_BRANCH" --quiet 2>/dev/null || true
+    fi
+    ;;
+esac
+
+exit 0