create-egregore 0.21.6 → 0.22.0

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

@@ -25,6 +25,126 @@ _config_val() {
   fi
 }
 
+# --- Hosted API address -------------------------------------------------------
+# The hosted API moved to api.egregore.xyz after the October 2026 security
+# reset. Its old Railway origin is retired and no longer ours to trust: a token
+# or key sent there could reach whoever holds that address next. Every request
+# that carries a credential resolves its address through _hosted_api_url, so an
+# egregore.json or environment saved before the move never reaches it.
+#
+# The rule is an allowlist, not a normalizer. Only a plain web address is
+# used: http or https, a host of letters, digits, dots, hyphens and
+# underscores, an optional port and a plain path. Every transport reads such
+# an address the same way, so its host is the one the request reaches. A plain
+# address on the retired host becomes the hosted API; any other plain address
+# is kept. Anything else (userinfo, backslashes, percent-encoding, curl glob
+# characters, a query, whitespace inside, non-ASCII) is refused and nothing is
+# sent, because curl, urllib and WHATWG parsers disagree about where it goes.
+# Python: egregore_runtime/hosted_api.py. Node: packages/create-egregore/lib/
+# hosted-api.js and the launcher's inline copy. TypeScript: bin/connector-
+# google/src/hosted-api.ts. bin/tests/fixtures/hosted-api-url-vectors.json
+# holds all of them to one rule and one table.
+EGREGORE_HOSTED_API_ORIGIN="https://api.egregore.xyz"
+EGREGORE_RETIRED_API_ORIGIN="https://egregore-production-55f2.up.railway.app"
+EGREGORE_PLAIN_API_URL='^https?://([A-Za-z0-9._-]+)(:[0-9]{1,5})?(/[A-Za-z0-9._~/-]*)?$'
+EGREGORE_PLAIN_API_TARGET='^https?://([A-Za-z0-9._-]+)(:[0-9]{1,5})?([/?#][!-~]*)?$'
+EGREGORE_REFUSED_API_URL_NOTICE="The hosted services address isn't a plain web address, so nothing was sent. Correct api_url in egregore.json; the hosted address is $EGREGORE_HOSTED_API_ORIGIN."
+
+# _api_url_trim TEXT — TEXT without surrounding ASCII whitespace.
+_api_url_trim() {
+  local LC_ALL=C
+  local text="${1:-}"
+  text="${text#"${text%%[![:space:]]*}"}"
+  text="${text%"${text##*[![:space:]]}"}"
+  printf '%s' "$text"
+}
+
+# _plain_api_url TEXT — succeeds when TEXT is a plain address; sets
+# _PLAIN_API_HOST (the host, compared ignoring case and trailing dots) and
+# _PLAIN_API_PATH. No subshells: this runs on every hosted request.
+_plain_api_url() {
+  local LC_ALL=C
+  local restore_case=0 retired="${EGREGORE_RETIRED_API_ORIGIN#https://}" host
+  _PLAIN_API_HOST=""
+  _PLAIN_API_PATH=""
+  _PLAIN_API_RETIRED=false
+  if shopt -q nocasematch; then shopt -u nocasematch; restore_case=1; fi
+  if ! [[ "${1:-}" =~ $EGREGORE_PLAIN_API_URL ]]; then
+    [ "$restore_case" = 0 ] || shopt -s nocasematch
+    return 1
+  fi
+  host="${BASH_REMATCH[1]}"
+  _PLAIN_API_PATH="${BASH_REMATCH[3]}"
+  while [ "${host%.}" != "$host" ]; do host="${host%.}"; done
+  _PLAIN_API_HOST="$host"
+  shopt -s nocasematch
+  [[ "$host" == "$retired" ]] && _PLAIN_API_RETIRED=true
+  [ "$restore_case" = 1 ] || shopt -u nocasematch
+  return 0
+}
+
+# _retired_api_url URL — succeeds when URL is a plain address on the retired
+# host. Silent; a refused address is not retired.
+_retired_api_url() {
+  local text="${1:-}" LC_ALL=C
+  text="${text#"${text%%[![:space:]]*}"}"
+  text="${text%"${text##*[![:space:]]}"}"
+  _plain_api_url "$text" && [ "$_PLAIN_API_RETIRED" = true ]
+}
+
+# _hosted_api_url URL — the address to send a request to, trailing slashes
+# trimmed. A plain address on the retired host becomes the hosted API with its
+# path kept; any other plain address keeps its text; empty stays empty. Any
+# other address prints nothing, says why once on stderr (EGREGORE_ADDRESS_NOTICE
+# =shown silences it), and fails: callers send nothing, exactly as when no
+# hosted address is set.
+_hosted_api_url() {
+  local url="${1:-}" LC_ALL=C
+  url="${url#"${url%%[![:space:]]*}"}"
+  url="${url%"${url##*[![:space:]]}"}"
+  if [ -z "$url" ]; then
+    printf '\n'
+    return 0
+  fi
+  if ! _plain_api_url "$url"; then
+    [ "${EGREGORE_ADDRESS_NOTICE:-}" = shown ] || printf '%s\n' "$EGREGORE_REFUSED_API_URL_NOTICE" >&2
+    return 1
+  fi
+  [ "$_PLAIN_API_RETIRED" = false ] || url="$EGREGORE_HOSTED_API_ORIGIN$_PLAIN_API_PATH"
+  while [ "${url%/}" != "$url" ]; do url="${url%/}"; done
+  printf '%s\n' "$url"
+}
+
+# _hosted_api_target URL — a full request URL (a path and query after the
+# origin) to send a credential to. Its origin must be plain, so every
+# transport reads the same host; the rest may be any printable ASCII without
+# spaces (curl callers pass --globoff, so glob characters there stay literal).
+# A plain retired origin becomes the hosted API and keeps the rest. Anything
+# else prints nothing, says why on stderr, and fails.
+_hosted_api_target() {
+  local url="${1:-}" LC_ALL=C restore_case=0 rest
+  url="${url#"${url%%[![:space:]]*}"}"
+  url="${url%"${url##*[![:space:]]}"}"
+  if shopt -q nocasematch; then shopt -u nocasematch; restore_case=1; fi
+  if ! [[ "$url" =~ $EGREGORE_PLAIN_API_TARGET ]]; then
+    [ "$restore_case" = 0 ] || shopt -s nocasematch
+    [ "${EGREGORE_ADDRESS_NOTICE:-}" = shown ] || printf '%s\n' "$EGREGORE_REFUSED_API_URL_NOTICE" >&2
+    return 1
+  fi
+  rest="${BASH_REMATCH[3]}"
+  [ "$restore_case" = 0 ] || shopt -s nocasematch
+  if _retired_api_url "${url%"$rest"}"; then
+    url="$EGREGORE_HOSTED_API_ORIGIN$rest"
+  fi
+  printf '%s\n' "$url"
+}
+
+# _config_api_url — egregore.json's api_url, resolved for a request; fails
+# when it is refused.
+_config_api_url() {
+  _hosted_api_url "$(_config_val api_url)"
+}
+
 # Get base branch for a repo. Reads base_branch from egregore.json — top-level
 # for the core egregore repo, per-entry under repos[] for managed repos.
 # Defaults to "develop" for backwards compatibility only when a valid config
@@ -92,12 +212,13 @@ _get_base_branch() {
   echo "$base"
 }
 
+# The Connected test as a jq filter: not explicitly Local, and an api_url saved.
+EGREGORE_CONNECTED_JQ='(.mode // "") != "local" and ((.api_url // "") | length > 0)'
+
 # Detect local vs connected mode
 _detect_mode() {
   local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
-  if [ -f "$config" ] && jq -e \
-    '(.mode // "") != "local" and ((.api_url // "") | length > 0)' \
-    "$config" >/dev/null 2>&1; then
+  if [ -f "$config" ] && jq -e "$EGREGORE_CONNECTED_JQ" "$config" >/dev/null 2>&1; then
     echo "connected"
   else
     echo "local"
@@ -130,3 +251,27 @@ _runtime_mode_badge() {
     echo "◇ LOCAL"
   fi
 }
+
+# Session record policy readers preserve explicit false values. Missing policy
+# is off; missing detail/model inherit the documented defaults.
+_session_records_val() {
+  local key="$1" default="$2" val
+  local config="${CONFIG:-$SCRIPT_DIR/egregore.json}"
+  val=$(jq -r --arg key "$key" '
+    .features.session_records | if type == "object" and has($key)
+    then .[$key] | tostring else empty end
+  ' "$config" 2>/dev/null || true)
+  printf '%s\n' "${val:-$default}"
+}
+
+_session_records_enabled() {
+  [ "$(_session_records_val enabled false)" = "true" ]
+}
+
+_session_records_default_detail() {
+  _session_records_val default_detail outline
+}
+
+_session_records_model() {
+  _session_records_val model haiku
+}

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

@@ -77,7 +77,8 @@ if [ -n "${CTX_SEED_TAR:-}" ] && [ -f "${CTX_SEED_TAR:-}" ]; then
     # (process env → .env → committed api_url).
     _NOW_URL="${EGREGORE_API_URL:-$(grep '^EGREGORE_API_URL=' "${ENV_FILE:-$SCRIPT_DIR/.env}" 2>/dev/null | cut -d'=' -f2- || true)}"
     _NOW_KEY="${EGREGORE_API_KEY:-$(grep '^EGREGORE_API_KEY=' "${ENV_FILE:-$SCRIPT_DIR/.env}" 2>/dev/null | cut -d'=' -f2- || true)}"
-    [ -n "$_NOW_URL" ] || _NOW_URL=$(jq -r '.api_url // empty' "${CONFIG:-$SCRIPT_DIR/egregore.json}" 2>/dev/null)
+    # A fingerprint only: a refused address counts as none, quietly.
+    _NOW_URL="$(_hosted_api_url "${_NOW_URL:-$(jq -r '.api_url // empty' "${CONFIG:-$SCRIPT_DIR/egregore.json}" 2>/dev/null)}" 2>/dev/null)" || _NOW_URL=""
     _NOW_SCOPE=$(echo -n "${_NOW_URL}|${_NOW_KEY}" | cksum | cut -d' ' -f1)
     _SEED_AGE=$(( $(date +%s) - _SEED_TS ))
     if [ -n "$_SEED_AUTHOR" ] && [ "$_SEED_AUTHOR" = "$AUTHOR" ] \
@@ -267,8 +268,11 @@ fi
     done)
     if [ -n "$FP_FILES" ]; then
       FILE_PRESENCE=$(printf '%s\n' "$FP_FILES" | tr '\n' '\0' | xargs -0 awk '
-        function flush() { if (a != "") printf "%s|%s\n", a, d }
-        FNR == 1 { if (NR != 1) flush(); a=""; d="" }
+        function flush() { if (a != "" && !native) printf "%s|%s\n", a, d }
+        FNR == 1 { if (NR != 1) flush(); a=""; d=""; native=0; frontmatter=($0 == "---") }
+        FNR > 1 && /^---[ \t]*$/ { frontmatter=0 }
+        frontmatter && tolower($0) ~ /^[ \t]*["\047]?(producer|producer_principal_id|producer_identity|record_owner_actor_id)["\047]?[ \t]*:/ { native=1 }
+        frontmatter && tolower($0) ~ /^[ \t]*["\047]?subject_kind["\047]?[ \t]*:/ && !/^subject_kind:[ \t]*("human-session"|human-session)[ \t]*$/ { native=1 }
         a == "" && /^\*\*Author\*\*:/ { s = $0; sub(/^\*\*Author\*\*:[ \t]*/, "", s); a = s }
         d == "" && /^\*\*Date\*\*:/   { s = $0; sub(/^\*\*Date\*\*:[ \t]*/, "", s); d = s }
         END { flush() }
@@ -296,8 +300,11 @@ fi
   WORK_MAP="{}"
   if [ -n "$WM_FILES" ]; then
     WORK_MAP=$(printf '%s\n' "$WM_FILES" | tr '\n' '\0' | xargs -0 awk '
-      function flush() { if (a != "" && t != "") printf "%s\t%s\t%s\n", a, d, t }
-      FNR == 1 { if (NR != 1) flush(); a=""; d=""; t="" }
+      function flush() { if (a != "" && t != "" && !native) printf "%s\t%s\t%s\n", a, d, t }
+      FNR == 1 { if (NR != 1) flush(); a=""; d=""; t=""; native=0; frontmatter=($0 == "---") }
+      FNR > 1 && /^---[ \t]*$/ { frontmatter=0 }
+      frontmatter && tolower($0) ~ /^[ \t]*["\047]?(producer|producer_principal_id|producer_identity|record_owner_actor_id)["\047]?[ \t]*:/ { native=1 }
+      frontmatter && tolower($0) ~ /^[ \t]*["\047]?subject_kind["\047]?[ \t]*:/ && !/^subject_kind:[ \t]*("human-session"|human-session)[ \t]*$/ { native=1 }
       a == "" && /^\*\*Author\*\*:/ { s = $0; sub(/^\*\*Author\*\*:[ \t]*/, "", s); a = s }
       d == "" && /^\*\*Date\*\*:/   { s = $0; sub(/^\*\*Date\*\*:[ \t]*/, "", s); d = s }
       t == "" && /^# / {
@@ -385,8 +392,6 @@ fi
 
 # 6. Handoffs addressed to user (background, enriched with author/topic)
 (
-  JSON="[]"
-  RICH="[]"
   if [ -d "$SCRIPT_DIR/memory/handoffs" ]; then
     # One definition everywhere: Egregore Runtime folds canonical lifecycle
     # state for both Local and Connected instances. Graph is an optional
@@ -404,72 +409,38 @@ fi
         [ -n "$_F" ] && [ -f "$_F" ] && printf '%s\n' "$_F"
       done)
     fi
-    # Match github username, display name, github_name first word, and people-file name
-    # Handoff files may use "to: name", "**To**: name", or "To: name"
-    _DISPLAY=$(jq -r '.display_name // empty' "$STATE_FILE" 2>/dev/null)
-    _GH_NAME=$(jq -r '.github_name // empty' "$STATE_FILE" 2>/dev/null)
-    _FIRST_NAME=$(echo "$_GH_NAME" | awk '{print $1}')
-    # Also check people file: memory/people/{author}.md has "# Name" on first line
-    _PEOPLE_NAME=""
-    _PEOPLE_FILE="$SCRIPT_DIR/memory/people/$(echo "$AUTHOR" | tr '[:upper:]' '[:lower:]').md"
-    [ -f "$_PEOPLE_FILE" ] && _PEOPLE_NAME=$(sed -n 's/^# *//p' "$_PEOPLE_FILE" 2>/dev/null | head -1)
-    _GREP_PAT="[Tt]o[*]*: *$AUTHOR\|[Tt]o[*]*:$AUTHOR"
-    for _VARIANT in "$_DISPLAY" "$_FIRST_NAME" "$_PEOPLE_NAME"; do
-      [ -z "$_VARIANT" ] && continue
-      [ "$_VARIANT" = "$AUTHOR" ] && continue
-      # Skip if already in pattern (avoid duplicates)
-      echo "$_GREP_PAT" | grep -qF "$_VARIANT" && continue
-      _GREP_PAT="$_GREP_PAT\|[Tt]o[*]*: *$_VARIANT\|[Tt]o[*]*:$_VARIANT"
-    done
     # Compatibility fallback for an unavailable Runtime. It reads canonical
     # Markdown directly and never calls graph or a control-plane retrieval API.
     if [ -z "$ADDRESSED" ]; then
+      # Match github username, display name, github_name first word, and people-file name
+      # Handoff files may use "to: name", "**To**: name", or "To: name"
+      _DISPLAY=$(jq -r '.display_name // empty' "$STATE_FILE" 2>/dev/null)
+      _GH_NAME=$(jq -r '.github_name // empty' "$STATE_FILE" 2>/dev/null)
+      _FIRST_NAME=$(echo "$_GH_NAME" | awk '{print $1}')
+      # Also check people file: memory/people/{author}.md has "# Name" on first line
+      _PEOPLE_NAME=""
+      _PEOPLE_FILE="$SCRIPT_DIR/memory/people/$(echo "$AUTHOR" | tr '[:upper:]' '[:lower:]').md"
+      [ -f "$_PEOPLE_FILE" ] && _PEOPLE_NAME=$(sed -n 's/^# *//p' "$_PEOPLE_FILE" 2>/dev/null | head -1)
+      _GREP_PAT="[Tt]o[*]*: *$AUTHOR\|[Tt]o[*]*:$AUTHOR"
+      for _VARIANT in "$_DISPLAY" "$_FIRST_NAME" "$_PEOPLE_NAME"; do
+        [ -z "$_VARIANT" ] && continue
+        [ "$_VARIANT" = "$AUTHOR" ] && continue
+        # Skip if already in pattern (avoid duplicates)
+        echo "$_GREP_PAT" | grep -qF "$_VARIANT" && continue
+        _GREP_PAT="$_GREP_PAT\|[Tt]o[*]*: *$_VARIANT\|[Tt]o[*]*:$_VARIANT"
+      done
       ADDRESSED=$(grep -rli "$_GREP_PAT" "$SCRIPT_DIR/memory/handoffs/" 2>/dev/null | sort -r | head -5 || true)
     fi
-    JSON="["
-    RICH="["
-    FIRST=true
-    for AF in $ADDRESSED; do
-      [ -z "$AF" ] && continue
-      AF_NAME=$(basename "$AF" .md)
-      AF_AUTHOR=$(eg_handoff_author "$AF")
-      AF_TOPIC=$(eg_handoff_topic "$AF")
-      AF_DATE=$(eg_handoff_date "$AF")
-      # Extract repo state table if present
-      AF_REPO_STATE="[]"
-      AF_REPO_TABLE=$(awk '/^## Repo State/{found=1; next} found && /^#/{exit} found && /^\|[^-]/ && !/^\| Repo/{print}' "$AF" 2>/dev/null || true)
-      if [ -n "$AF_REPO_TABLE" ]; then
-        AF_REPO_STATE=$(echo "$AF_REPO_TABLE" | while IFS='|' read -r _ R_REPO R_BRANCH R_PR R_BASE _; do
-          R_REPO=$(echo "$R_REPO" | xargs 2>/dev/null || true)
-          R_BRANCH=$(echo "$R_BRANCH" | xargs 2>/dev/null || true)
-          R_PR=$(echo "$R_PR" | xargs 2>/dev/null | sed 's/^#//' | sed 's/—//' || true)
-          R_BASE=$(echo "$R_BASE" | xargs 2>/dev/null || true)
-          [ -z "$R_REPO" ] && continue
-          if [ -n "$R_PR" ] && [ "$R_PR" -eq "$R_PR" ] 2>/dev/null; then
-            printf '{"repo":"%s","branch":"%s","pr":%s,"base":"%s"}\n' "$R_REPO" "$R_BRANCH" "$R_PR" "$R_BASE"
-          else
-            printf '{"repo":"%s","branch":"%s","pr":null,"base":"%s"}\n' "$R_REPO" "$R_BRANCH" "$R_BASE"
-          fi
-        done | jq -sc '.' 2>/dev/null || echo "[]")
-      fi
-      $FIRST || JSON="$JSON,"
-      $FIRST || RICH="$RICH,"
-      JSON="$JSON\"$AF_NAME\""
-      AF_ENTRY=$(jq -cn \
-        --arg name "$AF_NAME" \
-        --arg author "$AF_AUTHOR" \
-        --arg topic "$AF_TOPIC" \
-        --arg date "$AF_DATE" \
-        --argjson repoState "$AF_REPO_STATE" \
-        '{name:$name, author:$author, topic:$topic, date:$date, repoState:$repoState}' 2>/dev/null || echo "{}")
-      RICH="$RICH$AF_ENTRY"
-      FIRST=false
-    done
-    JSON="$JSON]"
-    RICH="$RICH]"
+    # One process reads every addressed handoff for its name, author, topic,
+    # date and Repo State rows with handoff-meta.sh's semantics; a fork per
+    # field made this the gather's slowest job. $ADDRESSED stays unquoted
+    # for the word splitting the per-file loop had.
+    # shellcheck disable=SC2086
+    [ -n "$ADDRESSED" ] && python3 "$SCRIPT_DIR/bin/lib/handoff_meta.py" addressed \
+      "$CTX_DIR/addressed" "$CTX_DIR/addressed_rich" $ADDRESSED 2>/dev/null && exit 0
   fi
-  echo "$JSON" > "$CTX_DIR/addressed"
-  echo "$RICH" > "$CTX_DIR/addressed_rich"
+  echo "[]" > "$CTX_DIR/addressed"
+  echo "[]" > "$CTX_DIR/addressed_rich"
 ) &
 
 # 6.5. Pending questions addressed to user (background)

package/runtime/pi/bin/lib/genui-entry.py

@@ -0,0 +1,36 @@
+"""Run the interface-taste CLI, or name the Runtime update when it cannot run.
+
+This file stays outside egregore_runtime/: /update carries bin/ but never the
+Runtime, so a missing, older or partly updated Runtime fails here, where one
+line can say what to run, instead of in a traceback. That includes the
+package's own initialisation, which runs before any module inside it, and a
+partial update that brought the taste modules without what they call.
+"""
+
+import importlib
+import sys
+
+OUTDATED_RUNTIME = (
+    "genui: this workspace's Egregore Runtime is too old for interface taste; "
+    "to update it, run `egregore`, press s for Settings, then choose Runtime update"
+)
+
+# What taste calls in Runtime modules it does not ship with.
+REQUIRED = (
+    ("egregore_runtime.writeback", "CanonicalArtifactWriteback", "create_file"),
+    ("egregore_runtime.runtime", "EgregoreRuntime", "_writeback"),
+    ("egregore_runtime.runtime", "EgregoreRuntime", "authorize"),
+    ("egregore_runtime.runtime", "EgregoreRuntime", "resolve_actor"),
+)
+
+try:
+    from egregore_runtime.taste_cli import main
+
+    for module, owner, capability in REQUIRED:
+        if not callable(getattr(getattr(importlib.import_module(module), owner), capability, None)):
+            raise AttributeError(f"{owner}.{capability}")
+except (ImportError, SyntaxError, AttributeError):
+    print(OUTDATED_RUNTIME, file=sys.stderr)
+    raise SystemExit(3)
+
+raise SystemExit(main())

package/runtime/pi/bin/lib/git-message.sh

@@ -3,18 +3,37 @@
 # Spec: .claude/context/commit-format.md + .claude/context/pr-format.md.
 #
 # Provides:
+#   egregore_session_id <hub_dir>
+#       Print the calling session's own Egregore session id through
+#       bin/session-id.sh: its harness's native session id mapped at session
+#       start, else the id in <hub_dir>/.egregore-session-id, which names
+#       only the latest session start. Print nothing when neither exists.
 #   egregore_session_trailer <hub_dir>
-#       Print "Egregore-Session: <id>" when <hub_dir>/.egregore-session-id
-#       exists; print nothing otherwise. Never fails.
+#       Print "Egregore-Session: <id>" for that id; print nothing when
+#       there is none. Never fails.
 #   egregore_commit <git_dir> <hub_dir> <message> [git-commit flags…]
-#       git -C <git_dir> commit with the session trailer appended as the
-#       final paragraph (a valid git trailer block) when an id exists.
+#       git -C <git_dir> commit with the session trailer added through
+#       git's own --trailer, so it joins a trailer block the message already
+#       ends with (Co-Authored-By, Refs) instead of opening a paragraph of
+#       its own that would turn those lines back into body text.
 #   egregore_pr_skeleton <what> <why> <verification> <footer>
 #       The one source of the skeleton PR body shape.
 
+_EGREGORE_SESSION_RESOLVER="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)/session-id.sh"
+
+egregore_session_id() {
+  local hub="${1:-.}"
+  if [ -f "$_EGREGORE_SESSION_RESOLVER" ]; then
+    bash "$_EGREGORE_SESSION_RESOLVER" --root "$hub" 2>/dev/null
+  else
+    head -n 1 "$hub/.egregore-session-id" 2>/dev/null
+  fi
+  return 0
+}
+
 egregore_session_trailer() {
   local sid
-  sid="$(cat "${1:-.}/.egregore-session-id" 2>/dev/null || true)"
+  sid="$(egregore_session_id "${1:-.}")"
   [ -n "$sid" ] && printf 'Egregore-Session: %s' "$sid"
   return 0
 }
@@ -25,7 +44,7 @@ egregore_commit() {
   local trailer
   trailer="$(egregore_session_trailer "$hub_dir")"
   if [ -n "$trailer" ]; then
-    git -C "$git_dir" commit -m "$msg" -m "$trailer" "$@"
+    git -C "$git_dir" commit -m "$msg" --trailer "$trailer" "$@"
   else
     git -C "$git_dir" commit -m "$msg" "$@"
   fi

package/runtime/pi/bin/lib/git-sync.sh

@@ -22,6 +22,13 @@
 #          FRAMEWORK_UPDATED, FRAMEWORK_UPDATED_COUNT, FRAMEWORK_UPDATED_FILES,
 #          BASE_BRANCH, BASE_BRANCH_READY
 #
+# EGREGORE_GIT_SYNC_LIVE=1 (a shell variable the refresh pass of
+# bin/session-start.sh sets) means a session is already live in this checkout:
+# fetch and update refs only, and leave every working tree as it is (no
+# fast-forward, autosave, push, branch switch or framework update). The quick
+# pass before it fast-forwarded the base branch and the managed repos on their
+# base branch from the last fetch.
+#
 # Health dimensions are independent. HEALTH_GIT is the project checkout (base
 # branch, worktree, managed repos); HEALTH_MEMORY is the canonical memory
 # repository's synchronization; HEALTH_RETRIEVAL is whether recall can answer.
@@ -300,7 +307,7 @@ setup_develop() {
   if [[ "$CURRENT_BRANCH" != "$BASE_BRANCH" ]]; then
     # Safe to force-update when not checked out
     git branch -f "$BASE_BRANCH" "origin/$BASE_BRANCH" 2>/dev/null || true
-  else
+  elif [ "${EGREGORE_GIT_SYNC_LIVE:-0}" != "1" ]; then
     # On the base branch — try ff merge, fall back to reset only if no unpushed work
     git merge --ff-only "origin/$BASE_BRANCH" --quiet 2>/dev/null || {
       # Only reset if there are no unpushed commits and no dirty tracked work.
@@ -323,7 +330,7 @@ setup_develop() {
   # safe, but autosave commits, branch pushes, and parking the checkout on
   # the base branch mutate a live repo out from under whatever session owns
   # it.
-  if [ "${EGREGORE_GIT_SYNC_READONLY:-0}" = "1" ]; then
+  if [ "${EGREGORE_GIT_SYNC_READONLY:-0}" = "1" ] || [ "${EGREGORE_GIT_SYNC_LIVE:-0}" = "1" ]; then
     ACTION="ready"
     SAVED_BRANCH=""
     return 0
@@ -455,7 +462,8 @@ else
 fi
 
 # Apply a framework update only after setup verified the configured base branch.
-if [ "$IS_WORKTREE" != "true" ] && [ "$BASE_BRANCH_READY" = "true" ]; then
+if [ "$IS_WORKTREE" != "true" ] && [ "$BASE_BRANCH_READY" = "true" ] \
+  && [ "${EGREGORE_GIT_SYNC_LIVE:-0}" != "1" ]; then
   _apply_framework_update 2>/dev/null || true
 fi
 
@@ -563,7 +571,7 @@ for REPO in $MANAGED_REPOS; do
     R_BRANCH=$(git -C "$REPO_DIR" branch --show-current 2>/dev/null || echo "?")
     if [ "$R_BRANCH" != "$REPO_BASE" ]; then
       git -C "$REPO_DIR" branch -f "$REPO_BASE" "origin/$REPO_BASE" --quiet 2>/dev/null || true
-    else
+    elif [ "${EGREGORE_GIT_SYNC_LIVE:-0}" != "1" ]; then
       git -C "$REPO_DIR" merge --ff-only "origin/$REPO_BASE" --quiet 2>/dev/null || true
     fi
   fi