create-egregore 0.19.3 → 0.19.6

package/runtime/pi/bin/lib/dashboard-artifact.sh

@@ -0,0 +1,142 @@
+# shellcheck shell=bash
+# dashboard-artifact.sh — Generate a session dashboard artifact with a shareable URL
+#
+# Runs after context.sh (all $CTX_DIR/* files populated), before greeting.sh.
+# Compiles gathered context into a markdown document, generates HTML via
+# egregore-artifacts, publishes it, and exports DASHBOARD_URL for greeting.sh.
+#
+# Inputs:  SCRIPT_DIR, CTX_DIR, AUTHOR, GREETING_NAME, LOCAL_MODE,
+#          EGREGORE_SESSION_ID, FIRST_SESSION
+# Outputs: DASHBOARD_URL (exported for greeting.sh)
+
+DASHBOARD_URL=""
+
+# Skip conditions: first session, onboarding incomplete, no session ID
+if [ "${FIRST_SESSION:-false}" = "true" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+if [ -z "${EGREGORE_SESSION_ID:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# --- Read gathered context ---
+_DB_ADDRESSED=$(cat "$CTX_DIR/addressed_rich" 2>/dev/null || echo "[]")
+_DB_ADDR_COUNT=$(echo "$_DB_ADDRESSED" | jq 'length' 2>/dev/null || echo "0")
+_DB_QUESTS=$(cat "$CTX_DIR/quests" 2>/dev/null || echo "[]")
+_DB_QUEST_COUNT=$(echo "$_DB_QUESTS" | jq 'length' 2>/dev/null || echo "0")
+_DB_TEAM=$(cat "$CTX_DIR/team" 2>/dev/null || echo "[]")
+_DB_TEAM_COUNT=$(echo "$_DB_TEAM" | jq 'length' 2>/dev/null || echo "0")
+_DB_LIFECYCLE=$(cat "$CTX_DIR/lifecycle" 2>/dev/null || echo '{}')
+_DB_MERGED_COUNT=$(echo "$_DB_LIFECYCLE" | jq '.merged_prs.values // [] | length' 2>/dev/null || echo "0")
+_DB_IMPL_COUNT=$(echo "$_DB_LIFECYCLE" | jq '.implemented_handoffs.values // [] | length' 2>/dev/null || echo "0")
+_DB_PULSE=$(cat "$CTX_DIR/pulse_brief" 2>/dev/null || echo '{}')
+_DB_PULSE_BRIEF=$(echo "$_DB_PULSE" | jq -r '.brief // empty' 2>/dev/null || true)
+
+# Skip if all context is empty — nothing worth showing
+_DB_HAS_CONTENT="false"
+if [ "$_DB_ADDR_COUNT" -gt 0 ] 2>/dev/null; then _DB_HAS_CONTENT="true"; fi
+if [ "$_DB_QUEST_COUNT" -gt 0 ] 2>/dev/null; then _DB_HAS_CONTENT="true"; fi
+if [ "$_DB_TEAM_COUNT" -gt 0 ] 2>/dev/null; then _DB_HAS_CONTENT="true"; fi
+if [ "$_DB_MERGED_COUNT" -gt 0 ] 2>/dev/null; then _DB_HAS_CONTENT="true"; fi
+if [ "$_DB_IMPL_COUNT" -gt 0 ] 2>/dev/null; then _DB_HAS_CONTENT="true"; fi
+
+if [ "$_DB_HAS_CONTENT" = "false" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# --- Compile markdown ---
+_DB_DATE=$(date +%Y-%m-%d)
+_DB_ORG=$(jq -r '.org_name // "Egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo "Egregore")
+_DB_MD="/tmp/egregore-dashboard-${EGREGORE_SESSION_ID}.md"
+mkdir -p /tmp
+
+{
+  printf '# Session Dashboard — %s\n\n' "$_DB_ORG"
+
+  # --- Pulse Brief (first — sets the tone) ---
+  if [ -n "$_DB_PULSE_BRIEF" ]; then
+    printf '## Pulse\n\n'
+    printf '✦ %s\n\n' "$_DB_PULSE_BRIEF"
+  fi
+
+  # --- Handoffs & Asks (dense format matching terminal TUI) ---
+  if [ "$_DB_ADDR_COUNT" -gt 0 ] 2>/dev/null; then
+    printf '## Handoffs & Asks\n\n'
+    _DB_NOW_SEC=$(date +%s)
+    echo "$_DB_ADDRESSED" | jq -r '.[] | "\(.author // "unknown")\t\(.topic // "Untitled")\t\(.date // "--")"' 2>/dev/null | while IFS=$'\t' read -r _HF_AUTHOR _HF_TOPIC _HF_DATE; do
+      [ -z "$_HF_AUTHOR" ] && continue
+      # Compute relative time
+      _HF_DATE_ONLY="${_HF_DATE%%T*}"
+      _HF_EPOCH=$(date -j -f "%Y-%m-%d" "$_HF_DATE_ONLY" +%s 2>/dev/null || \
+                  date -d "$_HF_DATE_ONLY" +%s 2>/dev/null || echo "0")
+      _HF_DAYS=$(( (_DB_NOW_SEC - _HF_EPOCH) / 86400 ))
+      if [ "$_HF_DAYS" -le 0 ] 2>/dev/null; then _HF_AGO="today"
+      elif [ "$_HF_DAYS" -eq 1 ] 2>/dev/null; then _HF_AGO="yesterday"
+      else _HF_AGO="${_HF_DAYS}d ago"
+      fi
+      _HF_NAME_LC=$(printf '%s' "$_HF_AUTHOR" | awk '{print tolower($1)}')
+      printf '● %s → you: %s (%s)\n\n' "$_HF_NAME_LC" "$_HF_TOPIC" "$_HF_AGO"
+    done
+  fi
+
+  # --- Team Activity (right after handoffs, recent only) ---
+  if [ "$_DB_TEAM_COUNT" -gt 0 ] 2>/dev/null; then
+    _DB_NOW=$(date +%s)
+    _DB_RECENCY=$((7 * 86400))
+    _DB_TEAM_FILTERED=$(echo "$_DB_TEAM" | jq --argjson now "$_DB_NOW" --argjson window "$_DB_RECENCY" \
+      '[.[] | select(.last_seen_sort > 0 and ($now - .last_seen_sort) < $window)]' 2>/dev/null || echo "[]")
+    _DB_TEAM_FCOUNT=$(echo "$_DB_TEAM_FILTERED" | jq 'length' 2>/dev/null || echo "0")
+    if [ "$_DB_TEAM_FCOUNT" -gt 0 ] 2>/dev/null; then
+      printf '## Team Activity\n\n'
+      printf '| Name | Last Seen | Working On |\n'
+      printf '|------|-----------|------------|\n'
+      echo "$_DB_TEAM_FILTERED" | jq -r '.[] | ((.working_on // "")) as $w | (.branches // []) as $b | "| \(.name) | \(.last_seen) | \(if $w != "" then $w else ($b | join(", ")) end) |"' 2>/dev/null || true
+      printf '\n'
+    fi
+  fi
+
+  # --- What Changed ---
+  if [ "$_DB_MERGED_COUNT" -gt 0 ] 2>/dev/null || [ "$_DB_IMPL_COUNT" -gt 0 ] 2>/dev/null; then
+    printf '## What Changed\n\n'
+    if [ "$_DB_MERGED_COUNT" -gt 0 ] 2>/dev/null; then
+      echo "$_DB_LIFECYCLE" | jq -r '.merged_prs.values[]? | "- ✓ PR #\(.[0]) \(.[2] // .[1] // "")"' 2>/dev/null || true
+    fi
+    if [ "$_DB_IMPL_COUNT" -gt 0 ] 2>/dev/null; then
+      echo "$_DB_LIFECYCLE" | jq -r '.implemented_handoffs.values[]? | "- ✓ \(.[1] // "someone") worked on: \(.[0] // "handoff")"' 2>/dev/null || true
+    fi
+    printf '\n'
+  fi
+
+  # --- Active Quests (bottom — reference, exclude meta entries) ---
+  if [ "$_DB_QUEST_COUNT" -gt 0 ] 2>/dev/null; then
+    _DB_QUESTS_FILTERED=$(echo "$_DB_QUESTS" | jq '[.[] | select(. != "_template" and . != "index")][:10]' 2>/dev/null || echo "[]")
+    _DB_QF_COUNT=$(echo "$_DB_QUESTS_FILTERED" | jq 'length' 2>/dev/null || echo "0")
+    if [ "$_DB_QF_COUNT" -gt 0 ] 2>/dev/null; then
+      printf '## Active Quests\n\n'
+      echo "$_DB_QUESTS_FILTERED" | jq -r '.[] | "- \(.)"' 2>/dev/null || true
+      printf '\n'
+    fi
+  fi
+
+} > "$_DB_MD" 2>/dev/null
+
+# --- Publish markdown → HTML → hosted URL ---
+# publish-artifact.sh handles HTML generation internally (npx egregore-artifacts)
+# then uploads. Don't pre-generate HTML — that causes double-wrapping.
+# https:// URLs are universally cmd+clickable across all terminal emulators.
+# publish-artifact.sh may output npx progress lines before the URL — extract just the URL
+_DB_PUBLISH_OUT=$(bash "$SCRIPT_DIR/bin/publish-artifact.sh" document "$_DB_MD" \
+  --title "Session Dashboard" \
+  --author "${GREETING_NAME:-$AUTHOR}" 2>/dev/null || true)
+DASHBOARD_URL=$(echo "$_DB_PUBLISH_OUT" | grep -o 'https://[^ ]*' | tail -1)
+
+# Fallback: generate HTML locally and use file:// URL (offline, no API key, etc.)
+if [ -z "$DASHBOARD_URL" ]; then
+  _DB_HTML="/tmp/egregore-artifacts/dashboard-${EGREGORE_SESSION_ID}.html"
+  mkdir -p /tmp/egregore-artifacts
+  if npx egregore-artifacts@latest document "$_DB_MD" --output "$_DB_HTML" --no-open >/dev/null 2>&1 && [ -f "$_DB_HTML" ]; then
+    DASHBOARD_URL="file://${_DB_HTML}"
+  fi
+fi
+
+rm -f "$_DB_MD"

package/runtime/pi/bin/lib/ensure-develop.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# ensure-develop.sh — Ensure a repository has a develop branch.
+#
+# Usage:
+#   bash bin/lib/ensure-develop.sh <repo-path>
+#   bash bin/lib/ensure-develop.sh <repo-path> --report
+#
+# Behavior:
+#   1. Detects the repo's default branch (main, master, or HEAD)
+#   2. Checks if develop exists locally and/or on origin
+#   3. If missing, creates develop from the default branch and pushes it
+#
+# Flags:
+#   --report   Print a JSON report of the repo's branching model instead of
+#              creating develop. Used by create-egregore to analyze existing repos.
+#
+# Exit codes:
+#   0 — develop exists (already existed or was just created)
+#   1 — could not create develop (no default branch, not a git repo, push failed)
+#
+# Output (on success, without --report):
+#   created:<default_branch>   — develop was created from <default_branch>
+#   exists                     — develop already existed
+#
+# Output (with --report):
+#   JSON object with branching analysis
+
+set -o pipefail
+
+REPO_PATH="${1:-.}"
+FLAG="${2:-}"
+
+if [ ! -d "$REPO_PATH/.git" ] && [ ! -f "$REPO_PATH/.git" ]; then
+  echo "error:not_a_git_repo" >&2
+  exit 1
+fi
+
+# ── Detect default branch ──────────────────────────────────────────
+# Priority: what origin/HEAD points to > main > master > first branch found
+detect_default_branch() {
+  local repo="$1"
+
+  # 1. Check origin/HEAD (set by GitHub on clone)
+  local origin_head
+  origin_head=$(git -C "$repo" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+  if [ -n "$origin_head" ] && git -C "$repo" show-ref --verify --quiet "refs/remotes/origin/$origin_head" 2>/dev/null; then
+    echo "$origin_head"
+    return 0
+  fi
+
+  # 2. Check common names on remote
+  for branch in main master; do
+    if git -C "$repo" show-ref --verify --quiet "refs/remotes/origin/$branch" 2>/dev/null; then
+      echo "$branch"
+      return 0
+    fi
+  done
+
+  # 3. Check local branches (repo might not have a remote yet)
+  for branch in main master; do
+    if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
+      echo "$branch"
+      return 0
+    fi
+  done
+
+  # 4. Fall back to whatever HEAD points to
+  local head_branch
+  head_branch=$(git -C "$repo" branch --show-current 2>/dev/null)
+  if [ -n "$head_branch" ] && [ "$head_branch" != "develop" ]; then
+    echo "$head_branch"
+    return 0
+  fi
+
+  return 1
+}
+
+# ── Report mode ─────────────────────────────────────────────────────
+if [ "$FLAG" = "--report" ]; then
+  default_branch=$(detect_default_branch "$REPO_PATH" 2>/dev/null || echo "")
+  has_develop_local="false"
+  has_develop_remote="false"
+  git -C "$REPO_PATH" show-ref --verify --quiet refs/heads/develop 2>/dev/null && has_develop_local="true"
+  git -C "$REPO_PATH" show-ref --verify --quiet refs/remotes/origin/develop 2>/dev/null && has_develop_remote="true"
+
+  # Count remote branches (excluding HEAD)
+  branch_count=$(git -C "$REPO_PATH" branch -r 2>/dev/null | grep -cv 'HEAD' 2>/dev/null || echo "0")
+  [ -z "$branch_count" ] && branch_count=0
+
+  # List remote branch names (excluding origin/HEAD, max 20)
+  _branch_list=$(git -C "$REPO_PATH" branch -r --format='%(refname:short)' 2>/dev/null \
+    | grep -v 'origin/HEAD' \
+    | sed 's|^origin/||' \
+    | head -20)
+  if [ -n "$_branch_list" ]; then
+    branches=$(echo "$_branch_list" | jq -R . | jq -s .)
+  else
+    branches="[]"
+  fi
+
+  # Detect active contributors from branch names (dev/author/... pattern)
+  _contrib_list=$(git -C "$REPO_PATH" branch -r --format='%(refname:short)' 2>/dev/null \
+    | grep -E '^origin/dev/' \
+    | sed 's|^origin/dev/||; s|/.*||' \
+    | sort -u)
+  if [ -n "$_contrib_list" ]; then
+    contributors=$(echo "$_contrib_list" | jq -R . | jq -s .)
+  else
+    contributors="[]"
+  fi
+
+  jq -n \
+    --arg default_branch "$default_branch" \
+    --argjson has_develop_local "$has_develop_local" \
+    --argjson has_develop_remote "$has_develop_remote" \
+    --argjson branch_count "$branch_count" \
+    --argjson branches "$branches" \
+    --argjson contributors "$contributors" \
+    '{
+      default_branch: $default_branch,
+      has_develop_local: $has_develop_local,
+      has_develop_remote: $has_develop_remote,
+      branch_count: $branch_count,
+      branches: $branches,
+      contributors: $contributors,
+      needs_develop: (($has_develop_remote | not) and ($has_develop_local | not))
+    }'
+  exit 0
+fi
+
+# ── Ensure develop exists ──────────────────────────────────────────
+
+# Already exists on remote?
+if git -C "$REPO_PATH" show-ref --verify --quiet refs/remotes/origin/develop 2>/dev/null; then
+  # Ensure local tracking branch exists too
+  if ! git -C "$REPO_PATH" show-ref --verify --quiet refs/heads/develop 2>/dev/null; then
+    git -C "$REPO_PATH" branch develop origin/develop --quiet 2>/dev/null || true
+  fi
+  echo "exists"
+  exit 0
+fi
+
+# Already exists locally but not on remote? Push it.
+if git -C "$REPO_PATH" show-ref --verify --quiet refs/heads/develop 2>/dev/null; then
+  if git -C "$REPO_PATH" push -u origin develop --quiet 2>/dev/null; then
+    echo "exists"
+    exit 0
+  fi
+  # Push failed but local exists — still usable
+  echo "exists:local_only"
+  exit 0
+fi
+
+# Need to create develop from default branch
+DEFAULT_BRANCH=$(detect_default_branch "$REPO_PATH")
+if [ -z "$DEFAULT_BRANCH" ]; then
+  echo "error:no_default_branch" >&2
+  exit 1
+fi
+
+# Create develop from the default branch
+# Prefer remote ref if available (more up-to-date after fetch)
+if git -C "$REPO_PATH" show-ref --verify --quiet "refs/remotes/origin/$DEFAULT_BRANCH" 2>/dev/null; then
+  git -C "$REPO_PATH" branch develop "origin/$DEFAULT_BRANCH" --quiet 2>/dev/null
+else
+  git -C "$REPO_PATH" branch develop "$DEFAULT_BRANCH" --quiet 2>/dev/null
+fi
+
+if [ $? -ne 0 ]; then
+  echo "error:branch_create_failed" >&2
+  exit 1
+fi
+
+# Push to remote
+if git -C "$REPO_PATH" push -u origin develop --quiet 2>/dev/null; then
+  echo "created:$DEFAULT_BRANCH"
+  exit 0
+else
+  # Push failed — develop exists locally but not on remote
+  # This is still usable; session-start.sh will retry the push
+  echo "created:$DEFAULT_BRANCH:local_only"
+  exit 0
+fi

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

@@ -0,0 +1,288 @@
+# shellcheck shell=bash
+# git-sync.sh — Git synchronization for session-start.sh
+#
+# Handles all git operations during session startup:
+#   - Pull rebase configuration
+#   - Parallel fetches (origin, upstream, memory, managed repos)
+#   - Worktree orphan cleanup
+#   - Git health check
+#   - Develop branch setup + sync
+#   - Memory sync
+#   - Managed repos sync
+#
+# Inputs:  SCRIPT_DIR, IS_WORKTREE, MAIN_PROJECT_DIR, STATE_FILE, ENV_FILE,
+#          HEALTH_GIT, MANAGED_REPOS (not yet set — read from config here)
+# Outputs: HEALTH_GIT, DEVELOP_SYNCED, COMMITS_AHEAD, ACTION, SAVED_BRANCH,
+#          BRANCH, MEMORY_SYNCED, REPOS_STATUS, MANAGED_REPOS, CURRENT_BRANCH,
+#          FRAMEWORK_UPDATED
+
+FRAMEWORK_UPDATED="false"
+
+# --- Ensure pull.rebase is set (prevents "divergent branches" errors) ---
+git config pull.rebase true 2>/dev/null || true
+
+# --- Fetch all remotes in parallel ---
+# Set git transfer timeout so hangs don't block startup indefinitely.
+export GIT_HTTP_LOW_SPEED_LIMIT=1000  # abort if <1KB/s
+export GIT_HTTP_LOW_SPEED_TIME=10     # for 10 seconds
+
+# Attendant fast path: the ambient daemon (bin/attendant.sh) fetches origin,
+# memory, and managed repos every few minutes. If its warm marker is fresh,
+# refs are already up to date — skip the network fetches and launch on local
+# ops only. Upstream fetch (framework update check) is not covered by the
+# attendant and stays unconditional below.
+_REFS_FRESH="false"
+_ATT_SLUG=$(jq -r '.slug // "egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || echo "egregore")
+_ATT_MARKER="$HOME/.egregore/attendant/${_ATT_SLUG}-$(echo -n "$SCRIPT_DIR" | cksum | cut -d' ' -f1).warm-ts"
+if [ -f "$_ATT_MARKER" ]; then
+  _ATT_AGE=$(( $(date +%s) - $(cat "$_ATT_MARKER" 2>/dev/null || echo 0) ))
+  [ "$_ATT_AGE" -lt 360 ] && _REFS_FRESH="true"
+fi
+
+[ "$_REFS_FRESH" != "true" ] && git fetch origin --quiet 2>/dev/null &
+
+# Fetch upstream framework (for update check — non-blocking)
+# Default: official egregore-core repo. Set upstream_url in egregore.json to override,
+# or set it to "none" to disable (e.g., in the dev repo where this IS the source).
+_UPSTREAM_URL=$(jq -r '.upstream_url // empty' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+[ -z "$_UPSTREAM_URL" ] && _UPSTREAM_URL="https://github.com/egregore-labs/egregore.git"
+if [ "$_UPSTREAM_URL" != "none" ]; then
+  git remote add upstream "$_UPSTREAM_URL" 2>/dev/null || true
+  git fetch upstream main --quiet 2>/dev/null &
+fi
+
+# Sync memory in parallel (symlink or direct directory — both valid)
+MEMORY_SYNCED="false"
+if [ -d "$SCRIPT_DIR/memory/.git" ] && [ "$_REFS_FRESH" != "true" ]; then
+  git -C "$SCRIPT_DIR/memory" fetch origin --quiet 2>/dev/null &
+fi
+
+# Fetch managed repos in parallel
+MANAGED_REPOS=$(jq -r '(.repos[]? // empty) | if type == "object" then .name else . end' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+if [ "$_REFS_FRESH" != "true" ]; then
+  for REPO in $MANAGED_REPOS; do
+    if [ -d "$SCRIPT_DIR/../$REPO/.git" ]; then
+      git -C "$SCRIPT_DIR/../$REPO" fetch origin --quiet 2>/dev/null &
+    fi
+  done
+fi
+
+# Wait for all fetches
+wait 2>/dev/null || true
+
+# --- Auto-update framework from upstream (deferred) ---
+# Moved AFTER setup_develop() so framework commits land on develop, not on
+# working branches. See _apply_framework_update() below.
+_AUTO_UPDATE=$(jq -r '.auto_update // true' "$SCRIPT_DIR/egregore.json" 2>/dev/null)
+
+_apply_framework_update() {
+  # Applies framework paths from upstream to the CURRENT branch (must be develop).
+  # Disable with "auto_update": false in egregore.json.
+  # Dev repos (upstream_url: "none") skip this entirely.
+  if [ "$_UPSTREAM_URL" = "none" ] || [ "$_AUTO_UPDATE" = "false" ]; then
+    return 0
+  fi
+  if ! git show-ref --verify --quiet refs/remotes/upstream/main 2>/dev/null; then
+    return 0
+  fi
+  # Apply upstream changes — checkout is idempotent, skip diff check
+  # (git diff with variable path lists breaks in zsh — no word-splitting)
+  for _p in bin/ .claude/commands/ .claude/skills/ .claude/hooks/ .claude/context/ .claude/agents/ loom/ CLAUDE.md skills/; do
+    git checkout upstream/main -- "$_p" 2>/dev/null || true
+  done
+  # Only commit if there are actual changes
+  if [ -n "$(git status --porcelain bin/ .claude/ loom/ CLAUDE.md skills/ 2>/dev/null | head -1)" ]; then
+    git add bin/ .claude/ loom/ CLAUDE.md skills/ 2>/dev/null
+    EGREGORE_FRAMEWORK_UPDATE=1 git commit -m "Auto-update Egregore framework" --quiet 2>/dev/null || true
+    FRAMEWORK_UPDATED="true"
+  fi
+}
+
+# --- Worktree prune (just clean git's internal list, don't delete anything) ---
+git worktree prune 2>/dev/null || true
+
+# --- Git health check ---
+if git show-ref --verify --quiet refs/remotes/origin/develop 2>/dev/null; then
+  HEALTH_GIT="ok"
+else
+  HEALTH_GIT="fail"
+fi
+
+# --- Guarded staging -------------------------------------------------------
+# git_add_guarded() lives in the shared lib so the /handoff auto-save uses the
+# exact same logic. Fallback to plain `git add -A` if the lib can't be sourced,
+# so an unattended auto-save never silently no-ops.
+# shellcheck source=bin/lib/git-safe.sh
+. "$SCRIPT_DIR/bin/lib/git-safe.sh" 2>/dev/null || true
+if ! type git_add_guarded >/dev/null 2>&1; then
+  git_add_guarded() { git add -A 2>/dev/null || true; }
+fi
+
+# --- Setup develop (wrapped — failures set HEALTH_GIT but don't crash) ---
+setup_develop() {
+  # Ensure develop branch exists locally
+  if ! git show-ref --verify --quiet refs/heads/develop 2>/dev/null; then
+    if git show-ref --verify --quiet refs/remotes/origin/develop 2>/dev/null; then
+      git checkout -b develop origin/develop --quiet 2>/dev/null
+    else
+      # No develop on remote either — create from main
+      git checkout -b develop --quiet 2>/dev/null
+      git push -u origin develop --quiet 2>/dev/null
+    fi
+  fi
+
+  # Sync develop (without checkout — safe for concurrent sessions)
+  CURRENT_BRANCH=$(git branch --show-current)
+
+  # Update local develop ref from remote without switching branches
+  # Use fetch + force-update to handle divergence (e.g., from auto-update commits)
+  git fetch origin develop --quiet 2>/dev/null || true
+  if [[ "$CURRENT_BRANCH" != "develop" ]]; then
+    # Safe to force-update when not checked out
+    git branch -f develop origin/develop 2>/dev/null || true
+  else
+    # On develop — try ff merge, fall back to reset only if no unpushed work
+    git merge --ff-only origin/develop --quiet 2>/dev/null || {
+      # Only reset if there are no unpushed commits on develop
+      LOCAL_AHEAD=$(git rev-list origin/develop..develop --count 2>/dev/null || echo "0")
+      if [ "$LOCAL_AHEAD" = "0" ]; then
+        git reset --hard origin/develop --quiet 2>/dev/null || true
+      fi
+    }
+  fi
+  DEVELOP_SYNCED="true"
+
+  # Count commits on develop ahead of main
+  COMMITS_AHEAD=0
+  if git show-ref --verify --quiet refs/remotes/origin/main 2>/dev/null; then
+    COMMITS_AHEAD=$(git rev-list origin/main..develop --count 2>/dev/null || echo "0")
+  fi
+
+  # Always start from develop
+  # Every session begins on develop. Claude creates a fresh topic branch
+  # (dev/{author}/{topic-slug}) when the user says what they're working on.
+  # If we're on a working branch with uncommitted work, save it first.
+  ACTION="ready"
+  SAVED_BRANCH=""
+
+  if [[ "$CURRENT_BRANCH" != "develop" ]]; then
+    # Check for uncommitted work (staged + unstaged + untracked in tracked dirs)
+    if [ -n "$(git status --porcelain 2>/dev/null | head -1)" ]; then
+      # Save uncommitted work so nothing is lost (guarded: never auto-commit
+      # stray submodule pointers from sibling repos in the checkout)
+      git_add_guarded
+      git commit -m "Auto-save: uncommitted work from $CURRENT_BRANCH" --quiet 2>/dev/null || true
+      SAVED_BRANCH="$CURRENT_BRANCH"
+    fi
+
+    # Push the branch if it has unpushed commits (so work is never only local)
+    if [[ "$CURRENT_BRANCH" == dev/* ]] || [[ "$CURRENT_BRANCH" == feature/* ]] || [[ "$CURRENT_BRANCH" == bugfix/* ]]; then
+      LOCAL_HEAD=$(git rev-parse HEAD 2>/dev/null || echo "")
+      REMOTE_HEAD=$(git rev-parse "origin/$CURRENT_BRANCH" 2>/dev/null || echo "none")
+      if [ "$LOCAL_HEAD" != "$REMOTE_HEAD" ]; then
+        git push origin "$CURRENT_BRANCH" --quiet 2>/dev/null || true
+      fi
+    fi
+
+    # Switch to develop (already updated by fetch origin develop:develop above)
+    git checkout develop --quiet 2>/dev/null || true
+  else
+    # Already on develop — fetch couldn't update it (checked-out branch), so pull
+    git merge --ff-only origin/develop --quiet 2>/dev/null || true
+  fi
+
+  BRANCH="develop"
+}
+
+# Initialize defaults used by setup_develop
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+DEVELOP_SYNCED="false"
+COMMITS_AHEAD=0
+ACTION="ready"
+SAVED_BRANCH=""
+BRANCH="${CURRENT_BRANCH:-develop}"
+
+if [ "$IS_WORKTREE" = "true" ]; then
+  # Inside a worktree — skip develop checkout and framework update.
+  # Worktrees are isolated working copies; framework updates belong on develop.
+  BRANCH=$(git branch --show-current 2>/dev/null || echo "?")
+  DEVELOP_SYNCED="true"
+
+  # --- Worktree branch health check ---
+  # Detect if the branch was already merged into develop (e.g., PR merged
+  # but worktree not cleaned up). This prevents working on a stale branch
+  # whose commits are already in develop.
+  WORKTREE_STALE="false"
+  if [ "$BRANCH" != "?" ] && [ "$BRANCH" != "develop" ] && [ "$BRANCH" != "main" ]; then
+    # Check if remote branch still exists
+    if ! git ls-remote --heads origin "$BRANCH" 2>/dev/null | grep -q "$BRANCH"; then
+      # Remote branch gone — check if it was merged into develop
+      if git branch -r --merged origin/develop 2>/dev/null | grep -q "origin/$BRANCH" 2>/dev/null || \
+         git merge-base --is-ancestor HEAD origin/develop 2>/dev/null; then
+        WORKTREE_STALE="merged"
+      else
+        WORKTREE_STALE="remote_deleted"
+      fi
+    fi
+  fi
+
+  if [ "$WORKTREE_STALE" = "merged" ]; then
+    echo ""
+    echo "WARNING: Branch '$BRANCH' was already merged into develop."
+    echo "This worktree is stale — your work here is already in develop."
+    echo "Start a new session in the main project to get a fresh branch."
+    echo ""
+    HEALTH_GIT="fail"
+  elif [ "$WORKTREE_STALE" = "remote_deleted" ]; then
+    echo ""
+    echo "WARNING: Remote branch '$BRANCH' was deleted but NOT merged into develop."
+    echo "This worktree may contain unique local commits. Check before discarding:"
+    echo "  git log origin/develop..HEAD --oneline"
+    echo ""
+  fi
+
+  # Use main project's .env and state if ours are missing
+  if [ ! -f "$SCRIPT_DIR/.env" ] && [ -f "$MAIN_PROJECT_DIR/.env" ]; then
+    export ENV_FILE="$MAIN_PROJECT_DIR/.env"
+  fi
+elif ! setup_develop 2>/dev/null; then
+  HEALTH_GIT="fail"
+fi
+
+# Apply framework update now — we're on develop (or worktree skipped above)
+if [ "$IS_WORKTREE" != "true" ]; then
+  _apply_framework_update 2>/dev/null || true
+fi
+
+# --- Sync memory (symlink or direct directory — both valid) ---
+if [ -d "$SCRIPT_DIR/memory/.git" ]; then
+  MEM_LOCAL=$(git -C "$SCRIPT_DIR/memory" rev-parse HEAD 2>/dev/null || echo "")
+  MEM_REMOTE=$(git -C "$SCRIPT_DIR/memory" rev-parse origin/main 2>/dev/null || echo "")
+  if [ -n "$MEM_LOCAL" ] && [ -n "$MEM_REMOTE" ] && [ "$MEM_LOCAL" != "$MEM_REMOTE" ]; then
+    git -C "$SCRIPT_DIR/memory" pull origin main --quiet 2>/dev/null || true
+  fi
+  MEMORY_SYNCED="true"
+fi
+
+# --- Sync managed repos ---
+REPOS_STATUS=""
+for REPO in $MANAGED_REPOS; do
+  REPO_DIR="$SCRIPT_DIR/../$REPO"
+  if [ -d "$REPO_DIR/.git" ]; then
+    # Resolve base branch for this repo (from egregore.json or auto-detect)
+    REPO_BASE=$(_get_base_branch "$REPO")
+    # Sync base branch with remote (if not checked out)
+    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
+      git -C "$REPO_DIR" merge --ff-only "origin/$REPO_BASE" --quiet 2>/dev/null || true
+    fi
+    # Collect status
+    R_DIRTY=""
+    if [ -n "$(git -C "$REPO_DIR" status --porcelain 2>/dev/null | head -1)" ]; then
+      R_DIRTY=" *"
+    fi
+    REPOS_STATUS="${REPOS_STATUS}  ◇ ${REPO}: ${R_BRANCH}${R_DIRTY}\n"
+  fi
+done