create-egregore 0.21.6 → 0.22.0

package/runtime/pi/bin/reflexes/README.md

@@ -0,0 +1,61 @@
+# Reflexes
+
+A reflex is a probe with a tier. The probe states a fact about yesterday; the
+tier says how far the egregore may go on its own: say it (show), end the line
+with the command to run (propose), or do it and leave a receipt (act). The
+startup card is where the probes speak, on every harness. The act tier never
+prints from here; it lives in the path it governs, such as the merge gate in
+the save path.
+
+## A probe
+
+One file in this directory: a `.sh` or `.py` file, or any executable. The
+runner (`bin/reflexes.sh`, `bin/lib/reflexes.py`) runs them in name order,
+one at a time, and prints each line a probe writes to stdout with the card's
+sigil in front. A probe prints nothing when there is nothing to say, one line
+for a fact, two at most. Lines are cut at 160 characters.
+
+The runner never fails the card. A probe that exits non-zero, prints nothing,
+or runs past one second is silent; the runner stops launching probes once
+three seconds have passed in total. `bash bin/reflexes.sh --debug` names
+every silent probe and the reason.
+
+Sessions started minutes apart print the same card, so the runner keeps the
+last card for each harness in `.egregore/runtime/reflexes/` and prints it
+again, for up to ten minutes, while what the probes read is unchanged: the
+probe and `bin/lib` files, everything under `memory/sessions` (records and
+ledgers), the features in `egregore.json`, the person's names and records
+switch in the state file, the local date and nightly's cache (`cache_key` in
+`bin/lib/reflexes.py`). Anything else, such as the memory lookups the
+retrieval line counts, can be up to ten minutes old on the card. `--debug`, a
+sandbox marker, or a run in which a probe ran past its budget or never
+started skips the cache.
+
+Every probe gets, on top of the caller's environment:
+
+- `EGREGORE_ROOT` the project root
+- `EGREGORE_MEMORY` the memory directory, which may not exist
+- `EGREGORE_STATE` the per-instance state file (`.egregore-state.json`)
+- `EGREGORE_AUTHOR` the person's GitHub username, when known
+- `EGREGORE_HARNESS` `claude`, `codex`, `pi` or `prime`
+
+A probe reads records, state and local files; it never reaches the network
+without a cache and a budget, never writes outside `tmp/` (beyond one file
+created and removed to test a directory, as `20-sandbox.sh` does), and never
+prints anything a record would withhold.
+
+## Adding one
+
+Add a file here with a two-digit prefix for order (`20-nightly.sh`), make it
+print its line only when its predicate holds, and give it a case in
+`tests/test-reflexes.sh` or a test of its own. A probe that reads a file the
+cache key does not cover shows its change up to ten minutes late; add the
+file to `cache_key` when that matters. The runtime bundle ships this
+directory whole (`BIN_DIRS` in the bundle builder), so a tracked probe needs
+no allowlist entry. An organisation adds its own probes the same way.
+
+## Wording
+
+A show line states the fact: `3 open items are older than three days and
+have no owner`. A propose line ends with the command: `... · /records file
+a1b2c3`. No exclamation marks, no advice, no explanation of the mechanism.

package/runtime/pi/bin/reflexes.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# The reflexes: one runner, a directory of probes. See bin/reflexes/README.md.
+# Prints the probes' lines for the startup card; never fails the card.
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)" || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+exec python3 "$SCRIPT_DIR/bin/lib/reflexes.py" --root "$SCRIPT_DIR" "$@"

package/runtime/pi/bin/runtime-identity.sh

@@ -14,6 +14,8 @@ ROOT="${EGREGORE_INSTANCE_ROOT:-$RUNTIME_ROOT}"
 ROOT="$(cd "$ROOT" && pwd)"
 CONFIG="$ROOT/egregore.json"
 STATE="$ROOT/.egregore-state.json"
+# shellcheck source=bin/lib/config.sh
+source "$RUNTIME_ROOT/bin/lib/config.sh"
 
 resolved() {
   [ -f "$CONFIG" ] && [ -f "$STATE" ] || return 1
@@ -26,6 +28,114 @@ resolved() {
   ' "$STATE" >/dev/null 2>&1
 }
 
+# The saved address is resolved: an egregore.json saved before the October
+# 2026 move still names the retired origin, which never receives a token.
+connected_config() {
+  api_url="$(_config_api_url)" || api_url=""
+  slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
+  api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  [ -n "$api_url" ] && [ -n "$slug" ]
+}
+
+# The greeting's one note about the organization key (bin/lib/health-footer.sh
+# renders it): "renewed" shows once; "needs_sign_in" shows until renewal works.
+key_notice_state() {
+  jq -r '.hosted_key_notice.state // empty' "$STATE" 2>/dev/null || true
+}
+
+key_notice() {
+  local file tmp
+  [ -f "$STATE" ] || return 0
+  # A worktree links the checkout's state file: rename onto its target.
+  file="$(realpath "$STATE" 2>/dev/null)" || file="$STATE"
+  tmp="$(mktemp "$file.XXXXXX" 2>/dev/null)" || return 0
+  if [ "$1" = clear ]; then
+    jq 'if .hosted_key_notice.state == "needs_sign_in" then del(.hosted_key_notice) else . end' \
+      "$file" >"$tmp" 2>/dev/null
+  else
+    jq --arg state "$1" --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+      '.hosted_key_notice = {state: $state, at: $at}' "$file" >"$tmp" 2>/dev/null
+  fi && [ -s "$tmp" ] && mv "$tmp" "$file" || rm -f "$tmp"
+}
+
+# One authenticated status read; sets status_code and status_body.
+probe_status() {
+  local response=""
+  status_code=""
+  status_body=""
+  [ -n "$api_key" ] || return 0
+  response="$(curl -s "$api_url/api/org/status" \
+    -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
+    -w '\n%{http_code}' 2>/dev/null || true)"
+  status_code="${response##*$'\n'}"
+  status_body="${response%$'\n'*}"
+}
+
+status_ok() {
+  [ "$status_code" = 200 ] && printf '%s' "$status_body" | jq -e --arg slug "$slug" '
+    (.org_id | type == "string" and length > 0) and .slug == $slug
+  ' >/dev/null 2>&1
+}
+
+rejection_code() {
+  [ "$status_code" = 401 ] || return 0
+  printf '%s' "$status_body" | jq -r '.code // empty' 2>/dev/null || true
+}
+
+# Recover the configured org's key only through the membership-verifying
+# endpoint, which renews a key retired in the October 2026 security reset.
+# A historic path/namespace collision could also leave this checkout with
+# another Egregore's key. Install it atomically, then verify it. No
+# credential bytes are printed. $1 is the API's code for the rejected key.
+recover_key() {
+  local rejected="${1:-}" github_token encoded_slug response code recovered renewed previous_key
+  github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  if [ -z "$github_token" ]; then
+    [ "$rejected" != key_retired ] || key_notice needs_sign_in
+    return 1
+  fi
+  encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
+  response="$(curl -s "$api_url/api/org/$encoded_slug/key" \
+    -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
+    -w '\n%{http_code}' 2>/dev/null || true)"
+  code="${response##*$'\n'}"
+  recovered="${response%$'\n'*}"
+  if [ "$code" = 401 ]; then
+    # The GitHub sign-in was rejected; a fresh one renews the key.
+    [ "$rejected" != key_retired ] || key_notice needs_sign_in
+    return 1
+  fi
+  [ "$code" = 200 ] || return 1
+  # The key itself must name this org (ek_<slug>_<secret>), not just the reply.
+  printf '%s' "$recovered" | jq -e --arg slug "$slug" '
+    (.api_key | type == "string" and startswith("ek_" + $slug + "_")
+      and length > ($slug | length) + 4)
+    and .org_slug == $slug
+  ' >/dev/null 2>&1 || return 1
+  renewed="$(printf '%s' "$recovered" | jq -r '.renewed == true' 2>/dev/null || echo false)"
+  # Prove the candidate works before it replaces the saved key.
+  previous_key="$api_key"
+  api_key="$(printf '%s' "$recovered" | jq -r '.api_key')"
+  probe_status
+  if ! status_ok; then
+    api_key="$previous_key"
+    return 1
+  fi
+  if ! printf '%s' "$recovered" | \
+    EGREGORE_ROOT="$ROOT" \
+    PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null; then
+    api_key="$previous_key"
+    return 1
+  fi
+  api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2- || true)"
+  if [ "$rejected" = key_retired ] || [ "$renewed" = true ]; then
+    key_notice renewed
+  else
+    key_notice clear
+  fi
+}
+
 case "${1:-ensure}" in
   status)
     if resolved; then
@@ -35,56 +145,44 @@ case "${1:-ensure}" in
     printf '{"status":"unresolved"}\n'
     exit 1
     ;;
+  recover)
+    # A hosted request just rejected the organization key ($2 is the API's
+    # code). Once a fresh sign-in is known to be needed, only session start
+    # retries, so the notice and the retry stay one per session.
+    [ "$(key_notice_state)" != needs_sign_in ] || exit 1
+    connected_config || exit 1
+    recover_key "${2:-}"
+    ;;
   ensure)
-    resolved && exit 0
+    if resolved; then
+      # Healthy starts stop here, with no network call. After a recorded
+      # need for a fresh sign-in, retry so the greeting shows the outcome.
+      [ "$(key_notice_state)" = needs_sign_in ] || exit 0
+      connected_config || exit 0
+      probe_status
+      if status_ok; then
+        key_notice clear
+      else
+        recover_key "$(rejection_code)" || true
+      fi
+      exit 0
+    fi
     mode="$(jq -r 'if (.mode // "local") == "connected" or (.api_url // "") != "" then "connected" else "local" end' "$CONFIG" 2>/dev/null || echo local)"
     if [ "$mode" = "local" ]; then
       EGREGORE_ROOT="$ROOT" \
         PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
         python3 -m egregore_runtime.identity_cli initialize-local >/dev/null
     else
-      api_url="$(jq -r '.api_url // empty' "$CONFIG" 2>/dev/null)"
-      slug="$(jq -r '.slug // empty' "$CONFIG" 2>/dev/null)"
-      api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-      [ -n "$api_url" ] && [ -n "$slug" ] || exit 1
+      connected_config || exit 1
       # Identity repair selects already-existing account and membership
-      # records, then adopts their opaque IDs locally. If a stale credential
-      # belongs to another org, recover only the configured org's existing key
-      # through verified GitHub membership. No control-plane records are made.
-      control_plane=""
-      if [ -n "$api_key" ]; then
-        control_plane="$(curl -sf "$api_url/api/org/status" \
-          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-          2>/dev/null || true)"
-      fi
-      if ! printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
-        (.org_id | type == "string" and length > 0) and .slug == $slug
-      ' >/dev/null 2>&1; then
-        # A historic path/namespace collision could leave this checkout with
-        # another Egregore's API key. Recover the configured org's existing key
-        # only through the membership-verifying endpoint, install it atomically,
-        # and retry. No credential bytes are printed.
-        github_token="$(grep '^GITHUB_TOKEN=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-        [ -n "$github_token" ] || exit 1
-        encoded_slug="$(printf '%s' "$slug" | jq -sRr @uri)"
-        recovered="$(curl -sf "$api_url/api/org/$encoded_slug/key" \
-          -H "Authorization: Bearer $github_token" --connect-timeout 2 --max-time 12 \
-          2>/dev/null || true)"
-        printf '%s' "$recovered" | jq -e --arg slug "$slug" '
-          (.api_key | type == "string" and length > 0) and .org_slug == $slug
-        ' >/dev/null 2>&1 || exit 1
-        printf '%s' "$recovered" | \
-          EGREGORE_ROOT="$ROOT" \
-          PYTHONSAFEPATH=1 PYTHONPATH="$RUNTIME_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-          python3 -m egregore_runtime.identity_cli install-connected-key >/dev/null
-        api_key="$(grep '^EGREGORE_API_KEY=' "$ROOT/.env" 2>/dev/null | cut -d= -f2-)"
-        control_plane="$(curl -sf "$api_url/api/org/status" \
-          -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
-          2>/dev/null || true)"
-        printf '%s' "$control_plane" | jq -e --arg slug "$slug" '
-          (.org_id | type == "string" and length > 0) and .slug == $slug
-        ' >/dev/null 2>&1 || exit 1
+      # records, then adopts their opaque IDs locally. A rejected key is
+      # recovered for the configured org only, through verified GitHub
+      # membership. No control-plane records are made.
+      probe_status
+      if ! status_ok; then
+        recover_key "$(rejection_code)" || exit 1
       fi
+      control_plane="$status_body"
       roster="$(curl -sf "$api_url/api/org/$slug/members?include_removed=true" \
         -H "Authorization: Bearer $api_key" --connect-timeout 2 --max-time 4 \
         2>/dev/null || true)"
@@ -102,7 +200,7 @@ case "${1:-ensure}" in
     resolved
     ;;
   *)
-    echo 'usage: bash bin/runtime-identity.sh {ensure|status}' >&2
+    echo 'usage: bash bin/runtime-identity.sh {ensure|status|recover [code]}' >&2
     exit 2
     ;;
 esac

package/runtime/pi/bin/screenshot.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Render an HTML file or a URL to a PNG with headless Chrome.
+#   bin/screenshot.sh <file.html|url> <out.png> [width] [height]   (1440 x 2400)
+# Chrome: $EGREGORE_CHROME when set, with no fallback when it is wrong; else
+# the macOS Google Chrome app; else google-chrome or chromium on PATH. An
+# aborted render (no file, or zero bytes) is retried once; each try is capped
+# at 30 s. Prints "<out>: <bytes> bytes"; a failure prints one line naming the
+# cause and exits non-zero.
+# Headless Chrome enforces a minimum window width near 500 px, so phone checks
+# use 600. Heights above about 5400 px yield no file. Run one headless Chrome
+# at a time. Chrome dies at launch under the Codex sandbox, so in a minion run
+# the driver renders (.claude/skills/minion/SKILL.md, LAND).
+set -u
+
+die() { printf 'screenshot: %s\n' "$1" >&2; exit "${2:-1}"; }
+whole() { for n in "$@"; do case $n in '' | 0* | *[!0-9]*) return 1 ;; esac; done; }
+
+[ $# -ge 2 ] && [ $# -le 4 ] || die "usage: bin/screenshot.sh <file.html|url> <out.png> [width] [height]" 2
+input=$1 out=$2 width=${3:-1440} height=${4:-2400}
+whole "$width" "$height" || die "width and height must be whole pixels, got $width x $height" 2
+
+if [[ $input =~ ^[A-Za-z][A-Za-z0-9+.-]*:// ]] || [[ $input == data:* ]] || [[ $input == about:* ]]; then
+  url=$input
+else
+  [ -f "$input" ] && [ -r "$input" ] || die "input file missing: $input"
+  case $input in */*) dir=${input%/*} ;; *) dir=. ;; esac
+  dir=$(cd -- "${dir:-/}" && pwd -P) || die "input file missing: $input"
+  url=file://
+  # Percent-encode every byte outside the unreserved set, so a space, "#", "?",
+  # "%", a control character or a non-UTF-8 name reaches Chrome intact.
+  # shellcheck disable=SC2046 # the words are od's hex pairs; splitting them is the point
+  for byte in $(printf '%s' "${dir%/}/${input##*/}" | od -An -v -tx1); do
+    case $byte in
+      2[d-f] | 3[0-9] | 4[1-9a-f] | 5[0-9a] | 5f | 6[1-9a-f] | 7[0-9a] | 7e)
+        printf -v char '%b' "\\x$byte"; url+=$char ;;
+      *) url+=%$byte ;;
+    esac
+  done
+fi
+
+case $out in */*) outdir=${out%/*} ;; *) outdir=. ;; esac
+[ -d "${outdir:-/}" ] && [ -w "${outdir:-/}" ] || die "output directory missing or not writable: ${outdir:-/}"
+[ ! -d "$out" ] || die "output path is a directory: $out"
+
+if [ -n "${EGREGORE_CHROME:-}" ]; then
+  chrome=$EGREGORE_CHROME
+  [ -f "$chrome" ] && [ -x "$chrome" ] || die "no Chrome found: EGREGORE_CHROME=$chrome is not an executable file"
+else
+  chrome="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+  [ -x "$chrome" ] || chrome=$(command -v google-chrome || command -v chromium) \
+    || die "no Chrome found: set EGREGORE_CHROME, or install Google Chrome or Chromium"
+fi
+
+pid=
+trap '[ -z "$pid" ] || kill "$pid" 2>/dev/null' EXIT
+trap 'exit 130' INT TERM HUP
+
+render() { # one try; true when Chrome left a non-empty file at $out
+  rm -f -- "$out"; timed_out=0 ticks=0
+  "$chrome" --headless=new --disable-gpu --hide-scrollbars --window-size="$width,$height" \
+    --virtual-time-budget=4000 --screenshot="$out" "$url" >/dev/null 2>&1 &
+  pid=$!
+  while kill -0 "$pid" 2>/dev/null; do
+    [ "$ticks" -lt 150 ] || { kill -9 "$pid" 2>/dev/null; timed_out=1; break; }
+    sleep 0.2; ticks=$((ticks + 1))
+  done
+  wait "$pid" 2>/dev/null; pid=
+  [ -f "$out" ] && [ -s "$out" ]
+}
+
+if ! render && ! render; then
+  cause="no file at $out"
+  [ "$timed_out" = 0 ] || cause="the last try timed out after 30 s"
+  [ "$height" -le 5400 ] || cause="$cause; heights above about 5400 px yield no file"
+  die "render aborted twice ($cause)"
+fi
+printf '%s: %s bytes\n' "$out" "$(wc -c < "$out" | tr -d ' ')"

package/runtime/pi/bin/scroll.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 export EGREGORE_ROOT="$ROOT"
-export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(bash "$ROOT/bin/session-id.sh" --root "$ROOT" 2>/dev/null || cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
 export PYTHONSAFEPATH=1 PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
 
 exec python3 -m egregore_runtime.scroll_cli "$@"

package/runtime/pi/bin/search.sh

@@ -10,6 +10,7 @@
 #   bash bin/search.sh start
 #   bash bin/search.sh stop
 #   bash bin/search.sh open memory/path/to/source.md
+#   bash bin/search.sh mind publish
 #
 # The shell owns the established user-facing output. Retrieval infrastructure
 # is isolated behind the Egregore Retriever adapter.
@@ -47,6 +48,28 @@ _elapsed_s() {
   awk -v ms="$(( $(_now_ms) - $1 ))" 'BEGIN { printf "%.1f", ms / 1000 }'
 }
 
+# Run a Runtime operation as an OpenTelemetry span when the harness traces
+# this process (it exports TRACEPARENT). Untraced calls take the plain path.
+# Usage: _traced <span-name> <original-args-array-name> <command...>
+_traced() {
+  local name="$1" argv_ref="$2[@]"; shift 2
+  if [ -z "${TRACEPARENT:-}" ]; then "$@"; return $?; fi
+  local start out rc results degraded stale
+  start=$(_now_ms)
+  out=$(mktemp "${TMPDIR:-/tmp}/egregore-span.XXXXXX")
+  "$@" | tee "$out"
+  rc=${PIPESTATUS[0]}
+  results=$(grep -cE '^[0-9]+\. ' "$out" 2>/dev/null)
+  degraded=false; grep -q 'Search degraded' "$out" 2>/dev/null && degraded=true
+  stale=$(sed -nE 's/^Note: ([0-9]+) eligible document.*/\1/p' "$out" 2>/dev/null | head -1)
+  rm -f "$out"
+  ( python3 "$SCRIPT_DIR/bin/lib/otel_span.py" --name "$name" --start-ms "$start" \
+      --end-ms "$(_now_ms)" --rc "$rc" --attr "egregore.search.results=${results:-0}" \
+      --attr "egregore.search.degraded=$degraded" --attr "egregore.search.stale_documents=${stale:-}" \
+      --argv -- ${!argv_ref+"${!argv_ref}"} >/dev/null 2>&1 & ) 2>/dev/null
+  return "$rc"
+}
+
 _result_paths() {
   local line path canonical_prefix
   canonical_prefix="**file:** \`memory/"
@@ -71,7 +94,7 @@ _result_paths() {
 # calls there. The dormant graph configuration is preserved untouched for
 # rollback only.
 _upgrade_instance_key() {
-  # Mirrors egregore_runtime.upgrade.instance_key: stable org identity
+  # Mirrors egregore_runtime.installation.installation_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)
@@ -371,11 +394,12 @@ case "${1:-}" in
     for arg in "$@"; do
       if [ "$arg" = --context-packet ]; then FIND_ARGS+=(--private-result); else FIND_ARGS+=("$arg"); fi
     done
-    _runtime find "${FIND_ARGS[@]}"
+    _traced egregore.search.find FIND_ARGS _runtime find "${FIND_ARGS[@]}"
     ;;
   investigate) shift; cmd_investigate "$@" ;;
   start) shift; _runtime start "$@" ;;
   stop) shift; _runtime stop "$@" ;;
+  mind) shift; _runtime mind "$@" ;;
   open)
     shift
     OPEN_PACKET=0; OPEN_PATHS=()
@@ -393,19 +417,21 @@ case "${1:-}" in
     [ "$OPEN_PACKET" = 1 ] && OPEN_BINDING+=(--private-result)
     # Older Bash treats an empty array as unset under nounset. Optional flags
     # must expand to zero arguments without requiring an explicit episode ID.
-    _runtime open ${OPEN_PATHS[@]+"${OPEN_PATHS[@]}"} ${OPEN_BINDING[@]+"${OPEN_BINDING[@]}"}
+    OPEN_ARGS=(${OPEN_PATHS[@]+"${OPEN_PATHS[@]}"} ${OPEN_BINDING[@]+"${OPEN_BINDING[@]}"})
+    _traced egregore.search.open OPEN_ARGS _runtime open ${OPEN_ARGS[@]+"${OPEN_ARGS[@]}"}
     ;;
   help|-h|--help)
     cat <<'USAGE'
-usage: bash bin/search.sh {find|investigate|query|handoffs|reindex|install|start|stop|status|readiness|open}
+usage: bash bin/search.sh {find|investigate|query|handoffs|reindex|install|start|stop|status|readiness|open|mind}
   find "terms" [--kind keyword|semantic|hybrid|filename|literal|dates] [--recent-days N]
   open memory/path.md [memory/other.md ...] [--offset N] [--length N]
   handoffs --mine --status open --order newest --limit 1 --open
   handoffs [--addressed-to NAME|--sent|--sent-by NAME] [--status STATUS] [--order newest|oldest] [--limit N] [--json]
+  mind publish
 USAGE
     ;;
   *)
-    echo "usage: bash bin/search.sh {find|investigate|query|handoffs|reindex|install|start|stop|status|readiness|open}" >&2
+    echo "usage: bash bin/search.sh {find|investigate|query|handoffs|reindex|install|start|stop|status|readiness|open|mind}" >&2
     exit 1
     ;;
 esac

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

@@ -133,9 +133,12 @@ if git -C "$DIR/memory" rev-parse --git-dir >/dev/null 2>&1; then
   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
+      if git -C "$DIR/memory" pull --rebase origin main --quiet 2>/dev/null; then
+        if bash "$SCRIPT_ROOT/bin/memory-push.sh" --repository "$DIR/memory" --branch main >/dev/null 2>&1; then
+          break
+        else
+          case "$?" in 75) ;; *) break ;; esac
+        fi
       fi
       sleep 1
     done

package/runtime/pi/bin/session-id.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# session-id.sh — the calling harness session's own Egregore session id.
+#
+# Every session start mints an Egregore session id and writes it to the
+# checkout's .egregore-session-id, which each worktree links to. With several
+# sessions open on one machine, the latest start owns that file, so a commit
+# that reads it can carry another session's Egregore-Session trailer. This
+# script keeps one small map file per harness session and resolves the
+# caller's own id from the native session id its harness exports.
+#
+#   session-id.sh [--root DIR]
+#       Print the caller's Egregore session id; print nothing and exit 1
+#       when there is none. A native id in the environment whose map was
+#       recorded for DIR's repository wins; otherwise DIR/.egregore-session-id.
+#   session-id.sh record <harness> <native-id> <egregore-id> [--root DIR]
+#       Map a starting session (bin/lib/identity.sh), replacing an old map.
+#   session-id.sh bind <harness> <native-id> [--root DIR]
+#       Map a session first seen after its start (a Codex thread, at its
+#       first prompt) to the id it resolves to now. A map this repository
+#       can use is kept; one recorded for a moved checkout is replaced.
+#
+# Native ids, in order: EGREGORE_NATIVE_SESSION_ID under
+# EGREGORE_NATIVE_HARNESS (Claude, Pi and Prime tool commands), then
+# CLAUDE_CODE_SESSION_ID, then CODEX_THREAD_ID. A Codex worker started from a
+# Claude or Pi shell inherits that shell's ids and so resolves to the session
+# that started it.
+#
+# Map files: ~/.egregore/sessions/<harness>-<native-id>.id, two lines: the
+# Egregore id and the repository's physical git common dir, so a map never
+# applies to another repository (a test fixture, another instance). Names are
+# checked, never rewritten. Each record prunes maps unused for 30 days; every
+# resolve and bind that uses a map marks it used.
+set -u
+export LC_ALL=C
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MAP_DIR=""
+[ -z "${HOME:-}" ] || MAP_DIR="$HOME/.egregore/sessions"
+SCOPE=""
+
+usage() {
+  awk 'NR == 1 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' "$0"
+}
+
+valid_harness() {
+  case "$1" in ''|*[!a-z0-9]*) return 1 ;; esac
+  [ "${#1}" -le 16 ]
+}
+
+valid_native() {
+  case "$1" in ''|.*|*[!A-Za-z0-9._-]*) return 1 ;; esac
+  [ "${#1}" -le 128 ]
+}
+
+valid_session() {
+  case "$1" in ''|*[[:cntrl:]]*) return 1 ;; esac
+  [ "${#1}" -le 200 ]
+}
+
+# The repository's git common dir, physical, so worktrees and every spelling
+# of one checkout agree.
+scope_of() {
+  local dir
+  dir="$(git -C "$1" rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$dir" in /*) ;; *) dir="$1/$dir" ;; esac
+  (cd "$dir" 2>/dev/null && pwd -P)
+}
+
+# Print a map's Egregore id when the map belongs to this repository, and mark
+# it used so the age prune spares a session that is still working.
+lookup() {
+  local harness="$1" native="$2" file id="" scope=""
+  [ -n "$MAP_DIR" ] && valid_harness "$harness" && valid_native "$native" || return 1
+  file="$MAP_DIR/$harness-$native.id"
+  [ -f "$file" ] || return 1
+  { IFS= read -r id; IFS= read -r scope; } < "$file" 2>/dev/null
+  valid_session "$id" && [ -n "$scope" ] || return 1
+  [ -n "$SCOPE" ] || SCOPE="$(scope_of "$ROOT_DIR")" || return 1
+  [ "$scope" = "$SCOPE" ] || return 1
+  touch -c "$file" 2>/dev/null   # -c: a map pruned meanwhile stays gone, never empty
+  printf '%s\n' "$id"
+}
+
+resolve() {
+  local id=""
+  if [ -n "${EGREGORE_NATIVE_SESSION_ID:-}" ] && [ -n "${EGREGORE_NATIVE_HARNESS:-}" ]; then
+    if lookup "$EGREGORE_NATIVE_HARNESS" "$EGREGORE_NATIVE_SESSION_ID"; then return 0; fi
+  fi
+  if [ -n "${CLAUDE_CODE_SESSION_ID:-}" ]; then
+    if lookup claude "$CLAUDE_CODE_SESSION_ID"; then return 0; fi
+  fi
+  if [ -n "${CODEX_THREAD_ID:-}" ]; then
+    if lookup codex "$CODEX_THREAD_ID"; then return 0; fi
+  fi
+  [ -f "$ROOT_DIR/.egregore-session-id" ] || return 1
+  IFS= read -r id < "$ROOT_DIR/.egregore-session-id" 2>/dev/null
+  valid_session "$id" || return 1
+  printf '%s\n' "$id"
+}
+
+record() {
+  local harness="$1" native="$2" id="$3" scope tmp
+  [ -n "$MAP_DIR" ] && valid_harness "$harness" && valid_native "$native" && valid_session "$id" || return 1
+  scope="$(scope_of "$ROOT_DIR")" && [ -n "$scope" ] || return 1
+  mkdir -p "$MAP_DIR" 2>/dev/null || return 1
+  tmp="$MAP_DIR/.$harness-$native.$$"
+  printf '%s\n%s\n' "$id" "$scope" > "$tmp" 2>/dev/null \
+    && mv -f "$tmp" "$MAP_DIR/$harness-$native.id" 2>/dev/null || { rm -f "$tmp"; return 1; }
+  find "$MAP_DIR" -maxdepth 1 -type f \( -name '*.id' -o -name '.*' \) -mtime +30 \
+    -exec rm -f {} + 2>/dev/null
+  return 0
+}
+
+bind() {
+  local harness="$1" native="$2" id
+  [ -n "$MAP_DIR" ] && valid_harness "$harness" && valid_native "$native" || return 1
+  # A map this repository can use is kept; one recorded for a checkout that
+  # has since moved is replaced rather than left unusable.
+  lookup "$harness" "$native" >/dev/null && return 0
+  id="$(resolve)" || return 1
+  record "$harness" "$native" "$id"
+}
+
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)
+      [ -n "${2:-}" ] || { echo "session-id.sh: --root needs a directory" >&2; exit 2; }
+      ROOT_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+set -- ${ARGS[@]+"${ARGS[@]}"}
+
+case "${1:-resolve}" in
+  resolve)
+    [ $# -le 1 ] || { usage >&2; exit 2; }
+    resolve ;;
+  record)
+    [ $# -eq 4 ] || { usage >&2; exit 2; }
+    record "$2" "$3" "$4" ;;
+  bind)
+    [ $# -eq 3 ] || { usage >&2; exit 2; }
+    bind "$2" "$3" ;;
+  *) usage >&2; exit 2 ;;
+esac

package/runtime/pi/bin/session-log.sh

@@ -21,6 +21,25 @@ INPUT=$(cat /dev/stdin 2>/dev/null || echo "{}")
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)
 TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || true)
 
+# Route known native transcript locations before reading their contents.
+RUNTIME=$(printf '%s' "$INPUT" | jq -r '.runtime // empty' 2>/dev/null || true)
+RECORD_TRANSCRIPT=false
+if [ -n "${HOME:-}" ]; then
+  if [[ "$TRANSCRIPT_PATH" == "$HOME/.claude/projects/"* ]] && \
+      printf '%s' "$INPUT" | jq -e 'has("hook_event_name")' >/dev/null 2>&1; then
+    RECORD_TRANSCRIPT=true
+  elif { [ "$RUNTIME" = pi ] && [[ "$TRANSCRIPT_PATH" == "$HOME/.pi/agent/sessions/"* ]]; } || \
+       { [ "$RUNTIME" = prime ] && [[ "$TRANSCRIPT_PATH" == "$HOME/.prime/agent/sessions/"* ]]; }; then
+    RECORD_TRANSCRIPT=true
+  fi
+fi
+if [ "$RECORD_TRANSCRIPT" = true ]; then
+  source "$SCRIPT_DIR/bin/lib/config.sh"
+  if _session_records_enabled; then
+    exec bash "$SCRIPT_DIR/bin/session-record.sh" --mode end <<< "$INPUT"
+  fi
+fi
+
 if [ -z "$SESSION_ID" ]; then
   exit 0
 fi