orbit.sh

#!/usr/bin/env bash
set -euo pipefail

ORBIT_VERSION="0.2.0"
ORBIT_ROOT="${ORBIT_ROOT:-}"
ORBIT_DEFAULT_BRANCH_PREFIX="ws"
ORBIT_CMD="${0##*/}"

# --- Messages (all decorative output goes to stderr) ---

# new: editor prompts (before creation)
ORBIT_NEW_PROMPTS=(
  "What's the mission?"
  "Plot your course."
  "Set your heading."
  "Name your target."
  "Where to, pilot?"
  "Log your objective."
)

# new: farewells (after creation)
# shellcheck disable=SC2034
ORBIT_NEW_FAREWELLS=(
  "Godspeed."
  "Ad astra."
  "Go for orbit."
  "Fly true."
  "All systems nominal."
  "Good hunting."
)

# goal: editor prompts (before update)
ORBIT_GOAL_PROMPTS=(
  "Revise the mission."
  "Adjust your heading."
  "Recalculate trajectory."
  "Update the briefing."
  "New orders, pilot."
  "Amend the flight plan."
)

# goal: farewells (after update)
# shellcheck disable=SC2034
ORBIT_GOAL_FAREWELLS=(
  "Target locked."
  "Course corrected."
  "New heading confirmed."
  "Objective updated."
  "Coordinates set."
  "Recalibrating..."
)

# goal: farewells (after clear)
# shellcheck disable=SC2034
ORBIT_GOAL_CLEAR_FAREWELLS=(
  "Target disengaged."
  "Drifting free."
  "Off the grid."
  "Signal lost. Standing by."
)

# done: farewells (after marking done)
# shellcheck disable=SC2034
ORBIT_DONE_FAREWELLS=(
  "Mission complete."
  "Orbit achieved."
  "Touchdown confirmed."
  "Splashdown."
  "Payload delivered."
  "That's one for the books."
)

orbit_random_msg() {
  local _arr_name=$1
  eval "local _len=\${#${_arr_name}[@]}"
  # shellcheck disable=SC2154
  local idx=$(( RANDOM % _len ))
  eval "local _msg=\${${_arr_name}[$idx]}"
  # shellcheck disable=SC2154
  printf '\n%s\n' "$_msg" >&2
}

# --- Utilities ---

orbit_usage() {
  cat <<EOF
Usage:
  $ORBIT_CMD clone <url> [--push <fork-url>] [--name <repo>] [--branch <branch>]
  $ORBIT_CMD repos
  $ORBIT_CMD info <repo>
  $ORBIT_CMD memo [<repo>] [--refresh|--scaffold]
  $ORBIT_CMD new "<goal>" [--name <name>] [--no-goal] [--exec "<cmd>"]
  $ORBIT_CMD add <repo> [--ref <tag/branch>] [-s|--silent]
  $ORBIT_CMD switch [-c] [repo] <name>
  $ORBIT_CMD sync [repo...] [--force] [--branch <branch>]
  $ORBIT_CMD done [--pr <url>...] [--json]
  $ORBIT_CMD status [workspace] [--json]
  $ORBIT_CMD goal ["text"] [--clear]
  $ORBIT_CMD jot [<repo>] ["text"] [--pop] [--json]
  $ORBIT_CMD prune [workspace] [--older <dur>] [--dry-run] [--force]
  $ORBIT_CMD config [<key> [<value> | --unset]]
  $ORBIT_CMD context [<key>] [--startup|--prime|--reignite] [--json]
  $ORBIT_CMD doctor
  $ORBIT_CMD completion <zsh|bash>
  $ORBIT_CMD version

  Options: --json for machine-readable output (repos, status, info, done, context, jot --pop)

Config keys (project-level, via '$ORBIT_CMD config <key> <value>'):
  agent.recommend       Launch command recommended after 'new' (e.g. 'claude "orbit start"')
  branch.prefix         Scoped-mode tracking branch prefix (default: ws)
  memo.minLines         Memo card soft lower bound / thin floor (default: 4)
  memo.maxLines         Memo card hard upper bound / compress + README-fallback cap (default: 16)
  jot.bufferSize        Jot entries per repo before aggregation is nudged (default: memo.minLines = 4)
  explore.paths         Cold-start memo exploration scope: comma-delimited <path>:<depth>
                        list, e.g. '.:1,src:1,docs:2' (default: .:1)

Environment:
  ORBIT_ROOT             Explicit project root (default: discover from CWD)
EOF
}

orbit_fail() {
  printf 'orbit: %s\n' "$*" >&2
  return 1
}

# orbit_plural <count> <singular> <plural> — human-facing counts read wrong
# with a bare "s" ("1 repos"); branch→branches style plurals need both forms.
orbit_plural() {
  if [ "$1" = "1" ]; then
    printf '%s' "$2"
  else
    printf '%s' "$3"
  fi
}

# One path segment, legal inside a git refname, and not something that reads as
# an option on a command line. git check-ref-format is the authority on the
# rest (rejects '.'-leading, '..', spaces, control chars).
orbit_valid_branch_prefix() {
  case "$1" in
    ''|*/*|-*) return 1 ;;
  esac
  git check-ref-format "refs/heads/$1/w/n" >/dev/null 2>&1
}

# List pool repos holding local branches under <prefix>/, as "repo (n)" pairs.
# Returns 1 when there are none.
orbit_branches_under_prefix() {
  local root="$1" prefix="$2" repo_dir count total=0 hits=""
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir" ] || continue
    count=$(git -C "$repo_dir" for-each-ref --format='%(refname:short)' "refs/heads/$prefix/" 2>/dev/null | grep -c . || true)
    [ "${count:-0}" -gt 0 ] || continue
    hits="$hits $(basename "$repo_dir") ($count)"
    total=$((total + count))
  done
  [ "$total" -gt 0 ] || return 1
  printf '%s\n' "${hits# }"
}

# The tracking-branch prefix is a durable project property, not per-invocation
# state: it is baked into every branch name orbit creates AND it is the selector
# prune uses to decide which branches are orbit's to delete. Those two moments
# must agree — if they can disagree, branches leak (created under one prefix,
# looked for under another) or, worse, prune claims branches it never created.
# So it lives in project config, written deliberately and persisting across
# sessions, rather than in an environment variable any single call can flip.
orbit_require_prefix() {
  local prefix="" root
  if root=$(orbit_find_root 2>/dev/null); then
    prefix=$(git config --file "$root/.repos/.orbit" --get branch.prefix 2>/dev/null || true)
  fi
  [ -n "$prefix" ] || prefix="$ORBIT_DEFAULT_BRANCH_PREFIX"
  orbit_valid_branch_prefix "$prefix" || { orbit_fail "invalid branch.prefix in project config: $prefix"; return 1; }
  printf '%s\n' "$prefix"
}

orbit_find_root() {
  if [ -n "$ORBIT_ROOT" ]; then
    [ -d "$ORBIT_ROOT/.repos" ] || return 1
    printf '%s\n' "$ORBIT_ROOT"
    return 0
  fi
  local dir
  dir="$(pwd)"
  while [ "$dir" != "/" ]; do
    if [ -d "$dir/.repos" ]; then
      printf '%s\n' "$dir"
      return 0
    fi
    dir=$(dirname "$dir")
  done
  return 1
}

orbit_require_root() {
  local root
  root=$(orbit_find_root) || { orbit_fail "not in an orbit project (no .repos/ found); use 'orbit clone' or 'orbit new' to start"; return 1; }
  printf '%s\n' "$root"
}

# Pool infrastructure marker. .repos/ is orbit's pool, not an agent API surface:
# it lives outside the workspace sandbox and all access goes through orbit
# commands. This README is a passive warning that surfaces if an agent ever
# lists .repos/ directly. Idempotent — written once, never overwritten.
orbit_write_pool_readme() {
  local repos_dir="$1"
  [ -f "$repos_dir/README.md" ] && return 0
  cat > "$repos_dir/README.md" <<'EOF'
# .repos/ — orbit pool infrastructure (do not access directly)

This directory is orbit's repo pool. It is internal infrastructure, not an API
surface. Do not read, edit, or run git inside `.repos/` directly.

All pool access goes through orbit commands:

- `orbit repos` / `orbit info <repo>` — list and inspect pool repos
- `orbit add <repo>` — bring a repo into your workspace as a worktree
- `orbit sync <repo>` — update a pool repo from its upstream
- `orbit memo <repo>` — read/write a repo's memo card

Work happens in workspace worktrees created by `orbit add`, never here.
EOF
}

orbit_ensure_init() {
  local root
  if root=$(orbit_find_root); then
    mkdir -p "$root/.repos"
    [ -f "$root/.repos/.orbit" ] || touch "$root/.repos/.orbit"
    orbit_write_pool_readme "$root/.repos"
    printf '%s\n' "$root"
    return 0
  fi
  root="$(pwd)"
  mkdir -p "$root/.repos"
  touch "$root/.repos/.orbit"
  orbit_write_pool_readme "$root/.repos"
  printf '%s\n' "$root"
}

orbit_repo_basename() {
  local remote name
  remote="$1"
  name="${remote%/}"
  name="${name##*/}"
  name="${name##*:}"
  name="${name%.git}"
  [ -n "$name" ] || orbit_fail "cannot derive repo name from: $remote"
  printf '%s\n' "$name"
}

orbit_default_branch() {
  local repo="$1" head branch
  head=$(git -C "$repo" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null || true)
  # Trust the local pointer only if it actually resolves — guards a dangling
  # origin/HEAD left behind by a deleted default branch.
  if [ -n "$head" ] && git -C "$repo" rev-parse --verify --quiet "$head" >/dev/null 2>&1; then
    printf '%s\n' "${head#refs/remotes/origin/}"
    return 0
  fi
  if git -C "$repo" rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
    printf 'main\n'
    return 0
  fi
  if git -C "$repo" rev-parse --verify --quiet origin/master >/dev/null 2>&1; then
    printf 'master\n'
    return 0
  fi
  # Fallback: ask the remote directly. Handles a non-standard default branch
  # (e.g. develop/trunk) when origin/HEAD is missing — as after a single-branch
  # clone. Persist the answer so the fast local path works next time.
  branch=$(git -C "$repo" ls-remote --symref origin HEAD 2>/dev/null \
    | awk '/^ref:/ {sub("refs/heads/", "", $2); print $2; exit}')
  if [ -n "$branch" ]; then
    git -C "$repo" remote set-head origin --auto >/dev/null 2>&1 || true
    printf '%s\n' "$branch"
    return 0
  fi
  orbit_fail "cannot determine default branch for $repo
  the remote has no detectable default branch — it is likely empty (no commits/branches pushed yet) or missing origin/HEAD.
  fix: push an initial commit to the remote, then run 'orbit sync'."
}

orbit_git_supports_orphan_worktree() {
  local ver
  ver=$(git --version | awk '{print $3}')
  [ "$(printf '%s\n' "2.42" "$ver" | sort -V | head -n1)" = "2.42" ]
}

orbit_reserved_workspace() {
  case "$1" in
    ''|.|..|.repos|.git|*/*) return 0 ;;
    .*) return 0 ;;
    *) return 1 ;;
  esac
}

# Print the name of the workspace containing the given path, nothing if none.
# "Looks like a workspace" = a non-reserved direct child of the project root;
# any depth below it counts (workspaces host repos and nested dirs). Detection
# is purely structural — it does NOT require a .orbit marker: workspace metadata
# is disposable (Principle 3), so a lost or absent .orbit must never quietly
# disable a destructive-op guard. orbit_reserved_workspace already excludes
# .repos/.git and every dotdir, so the pool index cannot be mistaken for one.
orbit_ws_containing_dir() {
  local root="$1" path="$2" root_phys path_phys rel first
  root_phys=$(cd "$root" 2>/dev/null && pwd -P) || return 1
  [ -d "$path" ] || return 1
  path_phys=$(cd "$path" 2>/dev/null && pwd -P) || return 1
  case "$path_phys" in
    "$root_phys") return 1 ;;
    "$root_phys"/*) ;;
    *) return 1 ;;
  esac
  rel="${path_phys#"$root_phys/"}"
  first="${rel%%/*}"
  orbit_reserved_workspace "$first" && return 1
  printf '%s\n' "$first"
}

orbit_tracking_branch() {
  local prefix ws name
  prefix=$(orbit_require_prefix) || return 1
  ws="$1"; name="$2"
  printf '%s/%s/%s\n' "$prefix" "$ws" "$name"
}

orbit_branch_is_checked_out_elsewhere() {
  local repo="$1" branch="$2"
  git -C "$repo" worktree list --porcelain | grep -Fqx "branch refs/heads/$branch"
}

orbit_set_upstream() {
  local path="$1" local_branch="$2" upstream_branch="$3"
  git -C "$path" config "branch.$local_branch.remote" origin
  git -C "$path" config "branch.$local_branch.merge" "refs/heads/$upstream_branch"
}

orbit_remote_branch_exists() {
  local repo="$1" branch="$2"
  git -C "$repo" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1
}

# Fetch an existing remote branch's tracking ref with an explicit colon
# refspec: layout-independent — it works under the wildcard map, under a
# single-branch default entry, and under any user-narrowed layout, and it
# never touches config.
# Always fetch, even when origin/<branch> exists locally: the remote branch
# may have advanced or been force-pushed after it was fetched, and checking
# out the stale ref silently builds on abandoned history. Degrade when
# offline: use the local ref with a warning; fail only when there is
# nothing to fall back on.
orbit_ensure_remote_branch() {
  local repo="$1" branch="$2"
  if ! git -C "$repo" fetch origin "+refs/heads/$branch:refs/remotes/origin/$branch" 2>/dev/null; then
    if git -C "$repo" rev-parse --verify --quiet "refs/remotes/origin/$branch" >/dev/null 2>&1; then
      printf 'orbit: cannot fetch origin/%s, using possibly-stale local ref\n' "$branch" >&2
    else
      orbit_fail "cannot fetch origin/$branch"
    fi
  fi
}

# Read one of the managed-config switches (project config, following the
# branch.prefix convention): always (default) = the key is orbit-maintained
# at every touchpoint; once = written once at clone, then the value is the
# user's; never = never written, never corrected. Unrecognized values read as
# always.
orbit_managed_config_mode() {
  local root="$1" key="$2" v
  v=$(git config --file "$root/.repos/.orbit" --get "$key" 2>/dev/null || true)
  case "$v" in once|never) printf '%s' "$v" ;; *) printf 'always' ;; esac
}

# Config maintenance — one predicate per managed key, no remote comparison,
# no per-branch bookkeeping. The rule (spec-worktree → Git Dependency
# Closure): a config key orbit depends on is either managed here or
# explicitly declared premise-only.
#   git.fetchAllBranches = always: remote.origin.fetch is exactly the full wildcard
#     (the on-disk form of `git remote set-branches origin "*"`); exact
#     entries, scoped wildcards, and emptied configs all converge to it.
#   git.fetchPrune = always: fetch.prune=true is set.
#   git.pushUpstreamByDefault = always: push.default=upstream is set — scoped local
#     names (ws/<ws>/<name>) differ from remote names, so git's default
#     "simple" would refuse a bare `git push`.
# once/never pools are user territory — untouched, unreported.
# dry_run=1 prints would-lines on stdout (prune's pool-maintenance plan);
# real runs report each actual change on stderr, one line per key, each
# carrying its escape-hatch command.
orbit_maintain_pool_config() {
  local repo="$1" root="$2" dry_run="${3:-0}"
  local name wildcard='+refs/heads/*:refs/remotes/origin/*'
  name=$(basename "$repo")
  if [ "$(orbit_managed_config_mode "$root" git.fetchAllBranches)" = "always" ]; then
    local line count=0 exact=1
    while IFS= read -r line; do
      [ -n "$line" ] || continue
      count=$((count + 1))
      [ "$line" = "$wildcard" ] || exact=0
    done < <(git -C "$repo" config --get-all remote.origin.fetch 2>/dev/null || true)
    if [ "$count" -ne 1 ] || [ "$exact" -ne 1 ]; then
      if [ "$dry_run" = "1" ]; then
        printf 'would converge fetch config: git remote set-branches origin "*"\n'
      else
        git -C "$repo" config --replace-all remote.origin.fetch "$wildcard"
        printf 'orbit: %s: fetch config converged: git remote set-branches origin "*" (stop converging and re-apply yours: orbit config git.fetchAllBranches once)\n' "$name" >&2
      fi
    fi
  fi
  if [ "$(orbit_managed_config_mode "$root" git.fetchPrune)" = "always" ]; then
    if [ "$(git -C "$repo" config --type=bool --get fetch.prune 2>/dev/null || true)" != "true" ]; then
      if [ "$dry_run" = "1" ]; then
        printf 'would converge fetch config: git config fetch.prune true\n'
      else
        git -C "$repo" config fetch.prune true
        printf 'orbit: %s: fetch config converged: git config fetch.prune true (stop converging and re-apply yours: orbit config git.fetchPrune once)\n' "$name" >&2
      fi
    fi
  fi
  if [ "$(orbit_managed_config_mode "$root" git.pushUpstreamByDefault)" = "always" ]; then
    if [ "$(git -C "$repo" config --get push.default 2>/dev/null || true)" != "upstream" ]; then
      if [ "$dry_run" = "1" ]; then
        printf 'would converge push routing: git config push.default upstream\n'
      else
        git -C "$repo" config push.default upstream
        printf 'orbit: %s: push routing converged: git config push.default upstream (stop converging and re-apply yours: orbit config git.pushUpstreamByDefault once)\n' "$name" >&2
      fi
    fi
  fi
}

# The touchpoint fetch discipline (sync / prune):
# fetch the default branch plus every remote branch a local branch tracks
# (branch.*.merge, deduped — several local branches can share one upstream),
# one explicit refspec per fetch, never a bare fetch: under the wildcard map
# a bare fetch pulls every branch's objects (defeating the single-branch
# clone's economy), and a batch of refspecs dies atomically on the first dead
# branch. Each fetch stands alone: git's fatal is swallowed (this path must
# never leak the "couldn't find remote ref" this model exists to eliminate);
# when anything failed, one closing `git remote prune origin` converges the
# refs of remote-deleted branches — online it cleans, offline it fails and
# deletes nothing. The prune runs only while the full wildcard is in place
# (shape judgment, not mode forking: a narrowed clone/off layout is the
# user's territory). The default branch is the one loud failure: if it does
# not fetch while the remote answers, the remote may have lost its default
# branch — a repo-level event, reported. Returns non-zero iff the default
# branch would not fetch (sync treats this as fetch failure; prune ignores
# it).
orbit_touchpoint_fetch() {
  local repo="$1" default_br lb merge b failed=0 default_failed=0
  default_br=$(orbit_default_branch "$repo" 2>/dev/null || true)
  local seen=" " branches=""
  if [ -n "$default_br" ]; then
    branches="$default_br
"
    seen=" $default_br "
  fi
  while IFS= read -r lb; do
    [ -n "$lb" ] || continue
    [ "$(git -C "$repo" config --get "branch.$lb.remote" 2>/dev/null)" = "origin" ] || continue
    merge=$(git -C "$repo" config --get "branch.$lb.merge" 2>/dev/null) || continue
    case "$merge" in
      refs/heads/*) b="${merge#refs/heads/}" ;;
      *) continue ;;
    esac
    case "$seen" in *" $b "*) continue ;; esac
    seen="$seen$b "
    branches="$branches$b
"
  done < <(git -C "$repo" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null || true)

  while IFS= read -r b; do
    [ -n "$b" ] || continue
    if ! GIT_TERMINAL_PROMPT=0 git -C "$repo" fetch origin "+refs/heads/$b:refs/remotes/origin/$b" >/dev/null 2>&1; then
      failed=1
      [ "$b" = "$default_br" ] && default_failed=1
    fi
  done < <(printf '%s' "$branches")

  if [ "$failed" = "1" ]; then
    if git -C "$repo" config --get-all remote.origin.fetch 2>/dev/null | grep -Fqx '+refs/heads/*:refs/remotes/origin/*'; then
      GIT_TERMINAL_PROMPT=0 git -C "$repo" remote prune origin >/dev/null 2>&1 || true
    fi
    if [ "$default_failed" = "1" ]; then
      # Probe once to tell "remote lost its default branch" (repo-level news,
      # reported) from "offline" (routine, silent): 0 = branch exists yet the
      # fetch failed, 2 = branch gone from a reachable remote — both report.
      local rc=0
      GIT_TERMINAL_PROMPT=0 git -C "$repo" ls-remote --exit-code --heads origin "$default_br" >/dev/null 2>&1 || rc=$?
      case "$rc" in
        0|2)
          printf 'orbit: %s: WARNING: cannot fetch default branch origin/%s though the remote answers — the remote may have lost its default branch\n' \
            "$(basename "$repo")" "$default_br" >&2 ;;
      esac
    fi
  fi
  [ "$default_failed" = "0" ]
}

# --- CWD Inference ---

# A repo name is a pool directory basename, never a path. Callers build
# destructive targets by concatenation ($root/.repos/$name), so a traversing
# name ('../<ws>/<repo>') would point the pool operation at a workspace
# worktree instead — check the argument, not just whether the path it lands on
# happens to exist.
# The charset is GitHub's own ([A-Za-z0-9._-]): slashes and spaces are not
# legal remote repo names either. Two GitHub-legal shapes stay rejected on
# purpose: a leading '.' (pool loops glob .repos/*/, which skips hidden dirs)
# and a leading '-' (indistinguishable from an option flag in any argv slot).
orbit_valid_repo_name() {
  local name="$1"
  case "$name" in
    ''|.*|-*) return 1 ;;
    *[!A-Za-z0-9._-]*) return 1 ;;
  esac
  return 0
}

orbit_require_repo_name() {
  orbit_valid_repo_name "$1" || orbit_fail "invalid repo name: $1 (expected a pool repo basename: [A-Za-z0-9._-], no leading '.' or '-')"
}

orbit_infer_workspace() {
  local root="$1" cwd rel first
  # Physical paths on both sides: a cwd reached through a symlink (macOS
  # /tmp -> /private/tmp) shares no prefix with the logical root, and every
  # command that infers its workspace would refuse to work there. This is also
  # what keeps inference and the root-only guards answering the same question
  # the same way.
  cwd=$(pwd -P)
  root=$(cd "$root" 2>/dev/null && pwd -P) || root="$1"
  case "$cwd" in
    "$root") orbit_fail "cannot infer workspace from project root; cd into a workspace first"; return 1 ;;
    "$root"/*) ;;
    *) orbit_fail "CWD is not under project root"; return 1 ;;
  esac
  rel="${cwd#"$root/"}"
  first="${rel%%/*}"
  if orbit_reserved_workspace "$first"; then
    orbit_fail "cannot infer workspace: '$first' is reserved"
    return 1
  fi
  printf '%s\n' "$first"
}

# True when the CWD is inside some workspace (the project root itself and
# reserved dirs are not). Delegates to orbit_ws_containing_dir so the cwd guard
# and the ancestry guard answer "what counts as a workspace" with one rule.
# The comparison is on physical paths, because a cwd reached through a symlink
# (macOS /tmp -> /private/tmp) fails a logical prefix match, and an isolation
# guard that silently does not fire is the bug class this whole family of checks
# exists to prevent — which is also why an unreadable cwd answers "inside":
# a deleted working directory cannot be proven to be outside a workspace, and
# guessing "outside" is exactly the silent non-firing to avoid. The refusal that
# follows names the project root, which is the fix for a deleted cwd anyway.
orbit_cwd_inside_workspace() {
  local cwd
  cwd=$(pwd -P 2>/dev/null) || return 0
  orbit_ws_containing_dir "$1" "$cwd" >/dev/null
}

orbit_infer_repo() {
  local root="$1" ws="$2" cwd rel repo_name ws_dir
  # Physical on both sides, same reason as orbit_infer_workspace.
  cwd=$(pwd -P)
  ws_dir=$(cd "$root/$ws" 2>/dev/null && pwd -P) || ws_dir="$root/$ws"
  case "$cwd" in
    "$ws_dir") return 1 ;;
    "$ws_dir"/*) ;;
    *) return 1 ;;
  esac
  rel="${cwd#"$ws_dir/"}"
  repo_name="${rel%%/*}"
  if [ -d "$root/$ws/$repo_name/.git" ] || [ -f "$root/$ws/$repo_name/.git" ]; then
    printf '%s\n' "$repo_name"
    return 0
  fi
  return 1
}

# --- Process Ancestry ---

# Ancestor cwds are a property of this process, not of any candidate: collect
# them once per run. Re-walking per candidate costs a ps + lsof round-trip per
# ancestor on macOS, which scales with the number of workspaces for no gain.
ORBIT_ANCESTRY_CACHED=0
ORBIT_ANCESTOR_CWDS=""

# Print the cwd of a process; nothing if unreadable (exited, permissions).
# On hosts with neither /proc nor lsof this prints nothing for every pid and
# session detection degrades to the root-level guard — orbit doctor warns.
# `|| true` keeps the function safe under set -e in any calling context.
orbit_process_cwd() {
  local pid="$1"
  if [ -d "/proc/$pid" ]; then
    readlink "/proc/$pid/cwd" 2>/dev/null || true
  elif command -v lsof >/dev/null 2>&1; then
    lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | awk '/^n\//{print substr($0,2); exit}' || true
  fi
}

# Print a process's parent pid. Prefers /proc (no external command, and works
# where busybox ps lacks -o); falls back to ps. In /proc/<pid>/stat the comm
# field can itself contain spaces and parens, so fields are read after the last
# ')': state, then ppid.
orbit_process_ppid() {
  local pid="$1" stat rest
  if [ -r "/proc/$pid/stat" ]; then
    stat=$(cat "/proc/$pid/stat" 2>/dev/null) || stat=""
    if [ -n "$stat" ]; then
      rest=${stat##*') '}
      # shellcheck disable=SC2086  # deliberate word split into positionals
      set -- $rest
      [ "$#" -ge 2 ] && { printf '%s\n' "$2"; return 0; }
    fi
  fi
  ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ' || true
}

# Walk the ppid chain once and cache every readable ancestor cwd.
# Announces its own blind spot: if not a single ancestor cwd could be read, the
# guard cannot see anything, and a guard that silently does nothing is how the
# original incident happened. The check is on the *result*, not on which
# facility is present — a host can have /proc yet no usable ps, and vice versa.
orbit_collect_ancestor_cwds() {
  [ "$ORBIT_ANCESTRY_CACHED" = "1" ] && return 0
  ORBIT_ANCESTRY_CACHED=1
  local pid cwd depth=0
  pid=$(orbit_process_ppid $$)
  # Cap the walk at 32 ancestors: deep enough for any realistic shell/agent
  # stack, and bounds the loop should ps ever report a cyclic ppid chain.
  # Ancestors beyond the cap are (deliberately) not checked.
  while [ "$depth" -lt 32 ]; do
    case "$pid" in ''|*[!0-9]*|0|1) break ;; esac
    cwd=$(orbit_process_cwd "$pid")
    if [ -n "$cwd" ]; then
      ORBIT_ANCESTOR_CWDS="$ORBIT_ANCESTOR_CWDS$cwd
"
    fi
    pid=$(orbit_process_ppid "$pid")
    depth=$((depth + 1))
  done
  if [ -z "$ORBIT_ANCESTOR_CWDS" ]; then
    printf 'orbit: cannot read process ancestry on this host: the initiation guard is inactive\n' >&2
  fi
}

# Return 0 if any ancestor process has its cwd inside $1.
# The invoking shell's cwd is agent-controllable (cd), so "is this session
# rooted in <dir>" must be checked on the process tree — a shell can cd out,
# but the session's ancestor chain keeps its launch cwd. Positive match only:
# unreadable cwds are skipped and the walk continues.
orbit_session_workspace() {
  local root="$1" cwd ws
  # orbit_ws_containing_dir physical-normalizes each ancestor cwd itself
  # (lsof//proc report resolved paths).
  orbit_collect_ancestor_cwds
  [ -n "$ORBIT_ANCESTOR_CWDS" ] || return 1
  while IFS= read -r cwd; do
    [ -n "$cwd" ] || continue
    if ws=$(orbit_ws_containing_dir "$root" "$cwd"); then
      printf '%s\n' "$ws"
      return 0
    fi
  done <<EOF
$ORBIT_ANCESTOR_CWDS
EOF
  return 1
}

# Shared guard for destructive root-scoped operations (prune, sync --force /
# --branch). One rule: the invocation must come from a process tree standing
# entirely outside every workspace.
#   $1 root  $2 subcommand name (replay prefix)  $3 display name (message
#   prefix, may name flags)  $4+ original args (for the cd replay)
# Refuses (orbit_fail + return 1) when blocked; returns 0 when it may proceed.
# Every failure path returns explicitly rather than leaning on the caller's
# set -e, so the guard stays correct even if a future caller invokes it in a
# condition context (which would disable set -e for its whole body).
orbit_require_root_scope() {
  local root="$1" subcmd="$2" display="$3"
  shift 3
  local ws_hit

  # Walk the ancestry HERE, in this shell. orbit_session_workspace is called in
  # a command substitution below, and a subshell's assignments never reach the
  # caller — reading ORBIT_ANCESTOR_CWDS after it would always see the empty
  # initial value and mistake a readable ancestry for a blind one. Collecting
  # first also lets the subshell inherit the cache: one walk, one blind-spot
  # warning.
  orbit_collect_ancestor_cwds

  # Primary, target-independent guard: any ancestor process rooted inside any
  # workspace aborts the whole invocation. A parent's cwd can't be cd'd away,
  # so there is no remedy to offer — state the fact and stop.
  if ws_hit=$(orbit_session_workspace "$root"); then
    orbit_fail "$display should not be initiated from inside workspace $ws_hit"
    return 1
  fi

  # Fallback guard: orbit's own cwd is misplaced into a workspace.
  if orbit_cwd_inside_workspace "$root"; then
    # Replay the intended command ONLY when the ancestry actually ran and came
    # back clean (ORBIT_ANCESTOR_CWDS populated above). When it was blind (no
    # readable ancestor cwd), we cannot vouch the session isn't rooted in a
    # workspace, so handing back a ready-to-run `cd <root> && orbit ...` could
    # walk the operator straight into deleting the live workspace they are in
    # — give the fact only.
    if [ -z "$ORBIT_ANCESTOR_CWDS" ]; then
      orbit_fail "$display must be run from the project root"
      return 1
    fi
    local replay="" arg
    for arg in "$@"; do replay="$replay $(printf '%q' "$arg")"; done
    orbit_fail "$display must be run from the project root — cd $(printf '%q' "$root") && orbit $subcmd$replay"
    return 1
  fi

  return 0
}

orbit_ensure_workspace_orbit() {
  local ws_dir="$1"
  local orbit_file="$ws_dir/.orbit"
  if [ ! -f "$orbit_file" ]; then
    local now
    now=$(date +%s)
    git config --file "$orbit_file" workspace.created "$now"
  fi
}

# Memo card line bounds (project config on .repos/.orbit; not shell env — memo
# is project-level state). minLines = soft lower bound (gap/thin floor): below
# it a card isn't real yet. maxLines = hard upper bound (compress/curate ceiling
# + README-fallback cap): above it, curate instead of appending.
orbit_memo_min() {
  local root="$1" v
  v=$(git config --file "$root/.repos/.orbit" --get memo.minLines 2>/dev/null || true)
  case "$v" in ''|*[!0-9]*) v=4 ;; esac
  printf '%s' "$v"
}
orbit_memo_max() {
  local root="$1" v
  v=$(git config --file "$root/.repos/.orbit" --get memo.maxLines 2>/dev/null || true)
  case "$v" in ''|*[!0-9]*) v=16 ;; esac
  printf '%s' "$v"
}

# Over-budget threshold = maxLines + minLines. A card past the hard ceiling
# by more than the min-floor buffer is genuinely bloated; best-effort curation
# that lands slightly over the ceiling stays under this line and is left alone.
orbit_memo_overlong_threshold() {
  local root="$1"
  printf '%s' "$(( $(orbit_memo_max "$root") + $(orbit_memo_min "$root") ))"
}

# A memo is "thin" (missing or low-quality) if the file is absent or has fewer
# than memo.minLines non-blank lines. Conservative on purpose: only flags
# genuinely empty/stub cards that still need a real pull-decision card written.
orbit_memo_is_thin() {
  local md_file="$1" root="$2"
  [ -f "$md_file" ] || return 0
  local n min
  n=$(grep -c '[^[:space:]]' "$md_file" 2>/dev/null || echo 0)
  min=$(orbit_memo_min "$root")
  [ "$n" -lt "$min" ]
}

# Cold-start exploration scope for writing a memo card: a comma-delimited list
# of <path>:<depth> entries (project config; default the repo root at depth 1).
# One global knob, consumed only at first `orbit add` of a repo; afterward the
# jot -> incremental-memo pipeline maintains the card. Doc-format agnostic —
# orbit attaches no meaning to what lives at the paths.
orbit_explore_paths() {
  local root="$1" v
  v=$(git config --file "$root/.repos/.orbit" --get explore.paths 2>/dev/null || true)
  [ -n "$v" ] || v=".:1"
  printf '%s' "$v"
}

# Render the stored path:depth list as human text so a reader need not know the
# convention: ".:1,src:2" -> ". (depth 1), src (depth 2)".
orbit_explore_paths_human() {
  local raw out="" entry path depth
  raw=$(orbit_explore_paths "$1")
  local oldifs="$IFS"; IFS=,
  for entry in $raw; do
    IFS="$oldifs"
    path="${entry%%:*}"; depth="${entry##*:}"
    [ -n "$out" ] && out="$out, "
    out="$out$path (depth $depth)"
    IFS=,
  done
  IFS="$oldifs"
  printf '%s' "$out"
}

# Jot aggregation buffer (project config on .repos/.orbit): a repo that has
# accumulated enough jots to fill a minimum memo should aggregate them into the
# card. Defaults to memo.minLines; follows it unless explicitly set.
orbit_jot_buffer_size() {
  local root="$1" v
  v=$(git config --file "$root/.repos/.orbit" --get jot.bufferSize 2>/dev/null || true)
  case "$v" in ''|*[!0-9]*) v=$(orbit_memo_min "$root") ;; esac
  printf '%s' "$v"
}

# Jot warn level for a count given the buffer size: building | overflow | none.
# Silent at or below bufferSize/2; building up to bufferSize; overflow past it.
orbit_jot_level() {
  local count="$1" buf="$2"
  local half=$(( buf / 2 ))
  if [ "$count" -gt "$buf" ]; then printf 'overflow'
  elif [ "$count" -gt "$half" ]; then printf 'building'; fi
}

# Memo state for context/status purposes: thin | ok | over.
# thin = missing or fewer than memo.minLines non-blank lines (no real card yet);
# over = more than maxLines+minLines non-blank lines (over budget, curate once).
orbit_memo_state() {
  local md_file="$1" root="$2" n min over_t
  [ -f "$md_file" ] || { printf 'thin'; return; }
  n=$(grep -c '[^[:space:]]' "$md_file" 2>/dev/null || echo 0)
  min=$(orbit_memo_min "$root")
  over_t=$(orbit_memo_overlong_threshold "$root")
  if [ "$n" -lt "$min" ]; then printf 'thin'
  elif [ "$n" -gt "$over_t" ]; then printf 'over'
  else printf 'ok'; fi
}

# Print the worktree's upstream tracking state: "untracked" when the branch
# has no upstream config or its tracking ref is not materialized yet (a
# branch that was never pushed — cruise block surfaces this so the agent
# knows), a number when behind, or empty when tracked and up-to-date.
# Uses local refs only — never fetches.
orbit_repo_upstream_behind() {
  local wt_dir="$1" upstream behind
  # See orbit_status: a failing rev-parse can still print '@{upstream}' —
  # gate on the exit code, not on the captured text.
  if ! upstream=$(git -C "$wt_dir" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null); then
    upstream=""
  fi
  if [ -z "$upstream" ]; then
    printf 'untracked'
    return 0
  fi
  behind=$(git -C "$wt_dir" rev-list --count "HEAD..${upstream}" 2>/dev/null || echo 0)
  [ "$behind" = "0" ] && behind=""
  printf '%s' "$behind"
}

# Per-repo status for a workspace, one line per worktree repo (unfiltered):
#   <name>|<jot_count>|<jot_level>|<behind>|<memo_state>|<branch>|<is_scoped>
# jot_level: building|overflow (empty when count <= bufferSize/2);
# behind: commits behind the worktree branch's @{upstream}, "untracked" when
# no upstream (raw-mode), or empty when tracked and up-to-date;
# memo_state: ok|thin|over (see orbit_memo_state);
# branch: the worktree's current branch name (for the untracked hint);
# is_scoped: 1 when branch name starts with ws/<workspace>/ (scoped mode),
# 0 otherwise (raw mode — recommend orbit switch -c to convert).
# Shared by `orbit context` (cruise/reignite blocks) and `orbit done`.
orbit_collect_repo_status() {
  local root="$1" ws_dir="$2"
  local orbit_file="$ws_dir/.orbit"
  local buf
  buf=$(orbit_jot_buffer_size "$root")
  local ws_name
  ws_name=$(basename "$ws_dir")
  local d name branch count level behind mstate is_scoped
  for d in "$ws_dir"/*/; do
    [ -d "$d" ] || continue
    [ -d "$d/.git" ] || [ -f "$d/.git" ] || continue
    name=$(basename "$d")
    branch=$(git -C "$d" branch --show-current 2>/dev/null || echo "detached")
    case "$branch" in
      ws/"$ws_name"/*) is_scoped=1 ;;
      *) is_scoped=0 ;;
    esac
    count=$(git config --file "$orbit_file" --get-all "jot.$name.entry" 2>/dev/null | grep -c . || true)
    [ -n "$count" ] || count=0
    level=$(orbit_jot_level "$count" "$buf")
    behind=$(orbit_repo_upstream_behind "$d")
    mstate=$(orbit_memo_state "$root/.repos/.$name.md" "$root")
    printf '%s|%s|%s|%s|%s|%s|%s\n' "$name" "$count" "$level" "$behind" "$mstate" "$branch" "$is_scoped"
  done
}

# --- Brief Extraction ---

orbit_brief_extract() {
  local file="$1"
  [ -e "$file" ] || [ "$file" = "/dev/stdin" ] || return 1
  local line found=""
  # State for multi-line constructs common in GitHub READMEs:
  #   in_fence   — the opening fence marker (``` or ~~~), empty when outside
  #   in_comment — inside a multi-line <!-- --> comment
  #   in_tag     — inside a multi-line HTML tag (<img ...\n src="..."\n width="50%">)
  #   html_stack — open non-void HTML blocks (<p align="center"> … </p>)
  #   html_lines — lines spent inside html_stack; an unclosed block is common
  #     in hand-written README HTML, so after a budget we drop the stack and
  #     resume normal scanning instead of swallowing the rest of the file
  local in_fence="" in_comment=0 in_tag=0 html_stack="" html_lines=0
  while IFS= read -r line || [ -n "$line" ]; do
    line="${line#"${line%%[![:space:]]*}"}"

    if [ "$in_comment" = "1" ]; then
      case "$line" in *'-->'*) in_comment=0 ;; esac
      continue
    fi
    if [ "$in_tag" = "1" ]; then
      case "$line" in *'>'*) in_tag=0 ;; esac
      continue
    fi
    case "$line" in
      '```'*|'~~~'*)
        # Typed fences: only the same fence type closes the block, so a ~~~
        # line inside a ``` fence (or vice versa) is content, not a toggle.
        if [ -n "$in_fence" ]; then
          case "$line" in "$in_fence"*) in_fence="" ;; esac
        else
          in_fence="${line:0:3}"
        fi
        continue ;;
    esac
    [ -n "$in_fence" ] && continue
    if [ -n "$html_stack" ]; then
      html_lines=$((html_lines + 1))
      if [ "$html_lines" -gt 50 ]; then
        html_stack="" html_lines=0
      else
        local top="${html_stack##* }"
        case "$line" in
          '</'"$top"'>'*)
            html_stack="${html_stack% *}"
            [ -z "$html_stack" ] && html_lines=0 ;;
        esac
        continue
      fi
    fi

    case "$line" in
      ''|'#'*) continue ;;
      '['*|'!['*) continue ;;        # badges, link-only/nav lines
      '* '*|'- '*|[0-9]*'. '*) continue ;;
      '---'*|'***'*|'==='*) continue ;;
      '<!--'*)
        case "$line" in *'-->'*) ;; *) in_comment=1 ;; esac
        continue ;;
    esac
    case "$line" in
      '<'[a-zA-Z]*)
        # no '>' on the line → multi-line tag, skip until it closes
        case "$line" in *'>'*) ;; *) in_tag=1; continue ;; esac
        local tag
        tag="${line#<}"
        tag="${tag%% *}"
        tag="${tag%%>*}"
        case "$tag" in
          # void elements never open a block
          img|br|hr|source|input|meta|link|area|base|col|embed|track|wbr) ;;
          *)
            # inline-closed (<h2>Text</h2>) or self-closing (<br/>) don't open
            case "$line" in
              *'/>'*|*'</'"$tag"'>'*) ;;
              *) html_stack="$html_stack $tag" ;;
            esac ;;
        esac
        continue ;;
      '</'[a-zA-Z]*) continue ;;
    esac

    line="${line#> }"
    if [ ${#line} -gt 120 ]; then
      line="${line:0:120}"
      line="${line% *}"
    fi
    printf '%s\n' "$line"
    found=1
    break
  done < "$file"
  [ -n "$found" ]
}

# Resolve a pool repo's display brief via the shared fallback model
# (docs/spec-metadata.md "Fallback Rules"): index cache → memo file → README.
# README/memo fallbacks are display-only and never written back to the index.
# Prints two lines: the resolved brief (possibly empty) and the source tag
# (index|memo|readme|none). Presentation is the caller's job — `orbit repos`
# renders steering notes on stderr (human terminal), while the
# `orbit context --startup` prime roster inlines them as stdout sections
# (hook injection only carries stdout).
orbit_pool_brief() {
  local root="$1" index="$2" name="$3" repo_dir="$4"
  local brief
  brief=$(git config --file "$index" --get "repos.$name.brief" 2>/dev/null || true)
  if [ -n "$brief" ]; then
    printf '%s\nindex\n' "$brief"
    return 0
  fi

  local md_file="$root/.repos/.$name.md"
  if [ -f "$md_file" ]; then
    brief=$(orbit_brief_extract "$md_file" || true)
    if [ -n "$brief" ]; then
      printf '%s\nmemo\n' "$brief"
      return 0
    fi
  fi

  local readme="" f
  for f in "$repo_dir/README.md" "$repo_dir/README" "$repo_dir/readme.md"; do
    if [ -f "$f" ]; then readme="$f"; break; fi
  done
  if [ -n "$readme" ]; then
    brief=$(orbit_brief_extract "$readme" || true)
    if [ -n "$brief" ]; then
      printf '%s\nreadme\n' "$brief"
      return 0
    fi
  fi

  printf '\nnone\n'
}

# --- Staleness Check ---

orbit_staleness_check() {
  local repo_name="$1" root="$2"
  local index="$root/.repos/.orbit"
  local repo_dir="$root/.repos/$repo_name"
  [ -f "$index" ] || return 0
  local stored current
  stored=$(git config --file "$index" --get "repos.$repo_name.head" 2>/dev/null || true)
  [ -n "$stored" ] || return 0
  [ -f "$root/.repos/.$repo_name.md" ] || return 0
  current=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null || true)
  [ -n "$current" ] || return 0
  if [ "$stored" != "$current" ]; then
    local distance
    distance=$(git -C "$repo_dir" rev-list "$stored".."$current" --count 2>/dev/null || echo "?")
    printf 'orbit: %s memo is %s commits behind HEAD: skim the changes, then update memo %s, or run memo %s --refresh if structure is unchanged\n' \
      "$repo_name" "$distance" "$repo_name" "$repo_name" >&2
  fi
}

orbit_upstream_check() {
  local repo_name="$1" root="$2"
  local repo_dir="$root/.repos/$repo_name"
  local branch
  branch=$(orbit_default_branch "$repo_dir" 2>/dev/null) || return 0
  local local_head remote_head
  local_head=$(git -C "$repo_dir" rev-parse "refs/heads/$branch" 2>/dev/null) || return 0
  remote_head=$(git -C "$repo_dir" rev-parse "refs/remotes/origin/$branch" 2>/dev/null) || return 0
  if [ "$local_head" != "$remote_head" ]; then
    local distance
    distance=$(git -C "$repo_dir" rev-list "$local_head".."$remote_head" --count 2>/dev/null || echo "?")
    printf 'orbit: %s has %s new commits on origin/%s: run sync %s before you add or rely on it\n' \
      "$repo_name" "$distance" "$branch" "$repo_name" >&2
  fi
}

# --- JSON Output ---

orbit_json_escape() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\"/\\\"}"
  s="${s//$'\n'/\\n}"
  s="${s//$'\t'/\\t}"
  s="${s//$'\r'/\\r}"
  s="${s//$'\x08'/\\b}"
  s="${s//$'\x0c'/\\f}"
  s=$(printf '%s' "$s" | tr -d '\001-\007\013\016-\037')
  printf '%s' "$s"
}

orbit_json_kv() {
  local key="$1" value="$2"
  printf '"%s":"%s"' "$key" "$(orbit_json_escape "$value")"
}

orbit_json_kv_raw() {
  # For values that are already valid JSON (numbers, booleans, arrays, objects)
  local key="$1" value="$2"
  printf '"%s":%s' "$key" "$value"
}

# --- Commands ---

orbit_clone() {
  [ "$#" -ge 1 ] || orbit_fail "usage: orbit clone <url> [--push <fork-url>] [--name <repo>] [--branch <branch>]"

  local remote="$1" repo_name="" branch="" push_url=""
  shift

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --name) [ "$#" -ge 2 ] || orbit_fail "--name requires a value"; repo_name="$2"; shift 2 ;;
      --branch) [ "$#" -ge 2 ] || orbit_fail "--branch requires a value"; branch="$2"; shift 2 ;;
      --push) [ "$#" -ge 2 ] || orbit_fail "--push requires a value"; push_url="$2"; shift 2 ;;
      *) orbit_fail "unknown option: $1" ;;
    esac
  done

  local root
  root=$(orbit_ensure_init)

  if [ -z "$repo_name" ]; then
    repo_name=$(orbit_repo_basename "$remote") || return 1
    # A URL basename outside the name contract (e.g. an org's .github repo) is
    # not a dead end — the repo just needs a pool identity picked by hand.
    orbit_valid_repo_name "$repo_name" || orbit_fail "cannot use URL basename as repo name: $repo_name (pick a pool name with --name)"
  fi
  orbit_require_repo_name "$repo_name"

  local dst="$root/.repos/$repo_name"
  [ ! -e "$dst" ] || orbit_fail "repo already exists: $repo_name"

  if [ -n "$branch" ]; then
    git clone --single-branch --branch "$branch" "$remote" "$dst"
  else
    git clone --single-branch "$remote" "$dst"
  fi

  # Converge the fresh pool's fetch config to the two managed keys — the
  # birth baseline: the full wildcard mapping (the on-disk form of
  # `git remote set-branches origin "*"`, written directly because the
  # porcelain refuses a config with no existing entry — an empty-remote
  # clone has none) plus fetch.prune=true (tracking refs self-clean).
  # once/never modes: written here only (once) or never (never); the default
  # always mode re-asserts them at every touchpoint.
  if [ "$(orbit_managed_config_mode "$root" git.fetchAllBranches)" != "never" ]; then
    git -C "$dst" config --replace-all remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
  fi
  if [ "$(orbit_managed_config_mode "$root" git.fetchPrune)" != "never" ]; then
    git -C "$dst" config fetch.prune true
  fi
  if [ "$(orbit_managed_config_mode "$root" git.pushUpstreamByDefault)" != "never" ]; then
    git -C "$dst" config push.default upstream
  fi

  if [ -n "$push_url" ]; then
    git -C "$dst" remote set-url --push origin "$push_url"
  fi

  local index="$root/.repos/.orbit"

  local url head
  url=$(git -C "$dst" remote get-url origin)
  head=$(git -C "$dst" rev-parse HEAD 2>/dev/null) || head="-"
  git config --file "$index" "repos.$repo_name.url" "$url"
  git config --file "$index" "repos.$repo_name.head" "$head"

  local cloned_branch
  cloned_branch=$(git -C "$dst" symbolic-ref --short HEAD 2>/dev/null || echo "unknown")
  printf 'cloned %s (default branch: %s)\n' "$repo_name" "$cloned_branch"
  printf 'next: orbit new "<goal>", then orbit add %s\n' "$repo_name"
}

orbit_new() {
  local goal="" name="" exec_cmd="" no_goal=false

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --name) [ "$#" -ge 2 ] || orbit_fail "--name requires a value"; name="$2"; shift 2 ;;
      --exec) [ "$#" -ge 2 ] || orbit_fail "--exec requires a value"; exec_cmd="$2"; shift 2 ;;
      --no-goal) no_goal=true; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *)
        if [ -z "$goal" ]; then
          goal="$1"
        else
          orbit_fail "unexpected argument: $1"
        fi
        shift
        ;;
    esac
  done

  if [ "$no_goal" = true ]; then
    [ -z "$goal" ] || orbit_fail "--no-goal cannot be combined with a goal argument"
  elif [ -z "$goal" ]; then
    local use_editor=false
    if [ -n "${ORBIT_EDITOR:-}" ]; then
      use_editor=true
    elif [ -t 0 ]; then
      use_editor=true
    fi

    if [ "$use_editor" = true ]; then
      local tmpf
      tmpf=$(mktemp "${TMPDIR:-/tmp}/orbit-goal-XXXXXX")
      local pidx=$(( RANDOM % ${#ORBIT_NEW_PROMPTS[@]} ))
      printf '\n# %s\n# Lines starting with # are ignored. Empty goal aborts.\n' "${ORBIT_NEW_PROMPTS[$pidx]}" > "$tmpf"
      local editor="${ORBIT_EDITOR:-${VISUAL:-${EDITOR:-vi}}}"
      "$editor" "$tmpf" </dev/tty >/dev/tty 2>/dev/null || "$editor" "$tmpf"
      goal=$(awk '/^#/{next} {lines[++n]=$0} END{s=1;e=n; while(s<=e && lines[s]=="")s++; while(e>=s && lines[e]=="")e--; for(i=s;i<=e;i++)print lines[i]}' "$tmpf")
      rm -f "$tmpf"
    else
      goal=$(cat)
    fi
    [ -n "$goal" ] || orbit_fail "aborting: empty goal"
  fi

  local root
  root=$(orbit_ensure_init)

  if [ -z "$name" ]; then
    local max=0 n
    for d in "$root"/task-*/ ; do
      [ -d "$d" ] || continue
      n="${d%/}"
      n="${n##*task-}"
      if [[ "$n" =~ ^[0-9]+$ ]] && [ "$n" -gt "$max" ]; then
        max="$n"
      fi
    done
    name=$(printf 'task-%02d' $((max + 1)))
  fi

  if orbit_reserved_workspace "$name"; then
    orbit_fail "invalid workspace name: $name"
  fi

  # Workspace name must be valid for scoped-mode branch names (ws/<workspace>/<name>).
  # git branch ref rules: no space, ~, ^, :, ?, *, [, \; no leading/trailing dot or slash;
  # no consecutive dots or slashes; no control chars; length limit (leave room for
  # ws/<workspace>/ prefix + branch name, keep total < 255).
  if [ "${#name}" -gt 50 ]; then
    orbit_fail "workspace name too long (${#name} chars, max 50): $name"
  fi
  case "$name" in
    *[[:space:]~^:?*[\\]* | .* | */* | *..* )
      orbit_fail "invalid workspace name (git branch ref rules): $name" ;;
  esac

  local ws_dir="$root/$name"
  [ ! -e "$ws_dir" ] || orbit_fail "workspace already exists: $name"

  mkdir -p "$ws_dir"
  local now
  now=$(date +%s)
  if [ -n "$goal" ]; then
    git config --file "$ws_dir/.orbit" workspace.goal "$goal"
  fi
  git config --file "$ws_dir/.orbit" workspace.created "$now"

  local cd_target
  if [ "$PWD" = "$root" ]; then
    cd_target="$name"
  else
    cd_target="$ws_dir"
  fi

  printf 'created workspace: %s\n' "$name"
  if [ -n "$goal" ]; then
    printf '\n  "%s"\n' "$goal"
  fi

  if [ -n "$exec_cmd" ]; then
    orbit_random_msg ORBIT_NEW_FAREWELLS
    (cd "$ws_dir" && sh -c "$exec_cmd")
  else
    local agent_exec
    agent_exec=$(git config --file "$root/.repos/.orbit" --get agent.recommend 2>/dev/null || true)
    if [ -n "$agent_exec" ]; then
      printf '\nget started:\n'
      printf '\n  cd %s && %s\n' "$cd_target" "$agent_exec"
    else
      printf '\nenter workspace:\n'
      printf '\n  cd %s\n' "$cd_target"
    fi
    orbit_random_msg ORBIT_NEW_FAREWELLS
  fi
}

orbit_add() {
  local repo_name="" target_ref="" silent=0

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --ref)
        [ "$#" -ge 2 ] || orbit_fail "usage: orbit add <repo> [--ref <tag/branch>] [-s|--silent]"
        target_ref="$2"; shift 2 ;;
      -s|--silent)
        silent=1; shift ;;
      -*)
        orbit_fail "usage: orbit add <repo> [--ref <tag/branch>] [-s|--silent]" ;;
      *)
        [ -z "$repo_name" ] || orbit_fail "usage: orbit add <repo> [--ref <tag/branch>] [-s|--silent]"
        repo_name="$1"; shift ;;
    esac
  done
  [ -n "$repo_name" ] || orbit_fail "usage: orbit add <repo> [--ref <tag/branch>] [-s|--silent]"
  orbit_require_repo_name "$repo_name"

  local root
  root=$(orbit_require_root) || return 1

  local ws
  ws=$(orbit_infer_workspace "$root") || return 1

  local ws_status
  ws_status=$(git config --file "$root/$ws/.orbit" --get workspace.status 2>/dev/null || true)
  if [ "$ws_status" = "done" ]; then
    printf 'orbit: workspace %s is marked done and prune-eligible: reactivate it with goal "<text>" before resuming work\n' "$ws" >&2
  fi

  local repo_dir="$root/.repos/$repo_name"
  [ -d "$repo_dir" ] || orbit_fail "repo not in pool: $repo_name (use 'orbit clone' first)"

  local ws_dir="$root/$ws"
  local dst="$ws_dir/$repo_name"
  [ ! -e "$dst" ] || orbit_fail "worktree already exists: $ws/$repo_name"

  # Empty-repo bootstrap: no commits yet → create an orphan-branch worktree
  # so the user can author the first commit.
  if [ -z "$target_ref" ] && ! git -C "$repo_dir" rev-parse --verify --quiet HEAD >/dev/null 2>&1; then
    orbit_git_supports_orphan_worktree || orbit_fail "$repo_name is an empty repo; bootstrapping the first commit needs git >= 2.42 (you have $(git --version | awk '{print $3}')). Upgrade git, or push an initial commit to the remote first."
    local empty_default empty_branch
    empty_default=$(git -C "$repo_dir" symbolic-ref --short HEAD 2>/dev/null || echo main)
    empty_branch=$(orbit_tracking_branch "$ws" "$empty_default") || return 1
    git -C "$repo_dir" worktree add --orphan -b "$empty_branch" "$dst"
    orbit_set_upstream "$dst" "$empty_branch" "$empty_default"
    orbit_ensure_workspace_orbit "$ws_dir"
    printf 'added %s → %s/%s (branch: %s, EMPTY repo — author the first commit here, then: git push)\n' \
      "$repo_name" "$ws" "$repo_name" "$empty_branch"
    return 0
  fi

  local default_branch
  default_branch=$(orbit_default_branch "$repo_dir") || return 1

  local checkout_target local_branch
  if [ -n "$target_ref" ]; then
    # --ref mode: fetch specified ref
    git -C "$repo_dir" fetch origin "$target_ref" 2>/dev/null || orbit_fail "$repo_name: cannot fetch ref: $target_ref"
    checkout_target="FETCH_HEAD"
  else
    # Default mode: checkout default branch
    orbit_ensure_remote_branch "$repo_dir" "$default_branch"
    checkout_target="origin/$default_branch"
  fi

  local_branch=$(orbit_tracking_branch "$ws" "$default_branch") || return 1

  if git -C "$repo_dir" rev-parse --verify --quiet "refs/heads/$local_branch" >/dev/null 2>&1; then
    if orbit_branch_is_checked_out_elsewhere "$repo_dir" "$local_branch"; then
      orbit_fail "branch already checked out: $local_branch"
    fi
    git -C "$repo_dir" worktree add "$dst" "$local_branch"
    [ -z "$target_ref" ] || git -C "$dst" reset --hard "$checkout_target" 2>/dev/null
  else
    git -C "$repo_dir" worktree add -b "$local_branch" "$dst" "$checkout_target"
  fi

  # Set upstream for status/ahead-behind visibility; push safety is handled by skill conventions
  orbit_set_upstream "$dst" "$local_branch" "$default_branch"

  orbit_ensure_workspace_orbit "$ws_dir"

  printf 'added %s → %s/%s (branch: %s, upstream: origin/%s)\n' "$repo_name" "$ws" "$repo_name" "$local_branch" "$default_branch"

  local explore_paths
  explore_paths=$(orbit_explore_paths_human "$root")

  # Surface the memo so agents that skipped `orbit info` still get repo context.
  # A well-behaved agent that already ran `orbit info` passes -s to suppress this.
  if [ "$silent" -eq 0 ]; then
    local md_file="$root/.repos/.$repo_name.md"
    if [ -f "$md_file" ]; then
      printf -- '--- memo: %s (pass -s to suppress) ---\n' "$repo_name" >&2
      cat "$md_file" >&2
      # Thin card: nudge a proper exploration at this high-attention moment.
      # This stderr is the explore.paths carrier (bounded cold-start scope).
      if orbit_memo_is_thin "$md_file" "$root"; then
        printf 'orbit: memo for %s is thin: explore %s and expand it into a pull-decision card (roles + how to use) with memo %s before done (pass -s to suppress)\n' \
          "$repo_name" "$explore_paths" "$repo_name" >&2
      fi
    else
      printf 'orbit: no memo for %s: explore %s and write a pull-decision card (roles + how to use), then write it with memo %s before done (pass -s to suppress)\n' "$repo_name" "$explore_paths" "$repo_name" >&2
    fi
  fi
}

orbit_switch() {
  local create_mode=0 args=()

  while [ "$#" -gt 0 ]; do
    case "$1" in
      -c) create_mode=1; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *) args+=("$1"); shift ;;
    esac
  done

  [ "${#args[@]}" -ge 1 ] || orbit_fail "usage: orbit switch [-c] [repo] <name>"

  local root ws repo_name branch_name
  root=$(orbit_require_root) || return 1
  ws=$(orbit_infer_workspace "$root") || return 1

  if [ "${#args[@]}" -eq 2 ]; then
    repo_name="${args[0]}"
    branch_name="${args[1]}"
  elif [ "${#args[@]}" -eq 1 ]; then
    branch_name="${args[0]}"
    repo_name=$(orbit_infer_repo "$root" "$ws") || orbit_fail "multiple repos in workspace, specify which one: orbit switch [-c] <repo> <name>"
  else
    orbit_fail "usage: orbit switch [-c] [repo] <name>"
  fi

  local repo_dir="$root/.repos/$repo_name"
  [ -d "$repo_dir" ] || orbit_fail "repo not in pool: $repo_name"

  local wt_path="$root/$ws/$repo_name"
  [ -d "$wt_path" ] || orbit_fail "repo not in workspace: $ws/$repo_name (use 'orbit add' first)"

  local local_branch
  local_branch=$(orbit_tracking_branch "$ws" "$branch_name") || return 1

  if [ "$create_mode" -eq 1 ]; then
    # No pre-creation remote check — git switch -c doesn't check remote either.
    # Push conflict is handled by git when it happens.
    local current
    current=$(git -C "$wt_path" branch --show-current)
    if [ "$current" = "$local_branch" ]; then
      printf 'already on %s\n' "$local_branch"
      return 0
    fi
    git -C "$wt_path" checkout -b "$local_branch"
    orbit_set_upstream "$wt_path" "$local_branch" "$branch_name"
    # No fetch-refspec registration: under the wildcard map the first push
    # materializes origin/<branch> on the spot, and @{u} resolution reads the
    # map, not any per-branch entry.
    printf '%s: created %s (upstream: origin/%s)\n' "$repo_name" "$local_branch" "$branch_name"

    # Post-creation conflict check: remote already has <name> with different
    # commits → push will conflict. Exempt when transferring a raw-mode branch
    # (current branch name = <name> and no upstream — agent already knows).
    local remote_head local_head current_branch current_upstream
    remote_head=$(git ls-remote --heads origin "$branch_name" 2>/dev/null | awk '{print $1}')
    if [ -n "$remote_head" ]; then
      local_head=$(git -C "$wt_path" rev-parse "refs/heads/$local_branch" 2>/dev/null || true)
      current_branch=$(git -C "$wt_path" branch --show-current 2>/dev/null || true)
      current_upstream=$(git -C "$wt_path" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)
      if [ -n "$local_head" ] && [ "$remote_head" != "$local_head" ] && \
         { [ "$current_branch" != "$branch_name" ] || [ -n "$current_upstream" ]; }; then
        printf 'orbit: note: remote already has %s with different commits — push will conflict\n' "$branch_name" >&2
      fi
    fi
  else
    if git -C "$repo_dir" rev-parse --verify --quiet "refs/heads/$local_branch" >/dev/null 2>&1; then
      if orbit_branch_is_checked_out_elsewhere "$repo_dir" "$local_branch"; then
        orbit_fail "branch checked out in another worktree: $local_branch"
      fi
      git -C "$wt_path" checkout "$local_branch"
      printf '%s: switched to %s\n' "$repo_name" "$local_branch"
    elif orbit_remote_branch_exists "$repo_dir" "$branch_name"; then
      orbit_ensure_remote_branch "$repo_dir" "$branch_name"
      git -C "$wt_path" checkout -b "$local_branch" "origin/$branch_name"
      orbit_set_upstream "$wt_path" "$local_branch" "$branch_name"
      printf '%s: created %s (upstream: origin/%s)\n' "$repo_name" "$local_branch" "$branch_name"
    else
      orbit_fail "branch not found on remote: origin/$branch_name (use -c to create)"
    fi
  fi
}

orbit_sync_one() {
  local repo_name="$1" root="$2" force="$3" new_branch="$4" ws="${5:-}"
  if ! orbit_valid_repo_name "$repo_name"; then
    printf "orbit: invalid repo name: %s (expected a pool repo basename: [A-Za-z0-9._-], no leading '.' or '-')\n" "$repo_name" >&2
    return 1
  fi
  local repo_dir="$root/.repos/$repo_name"
  [ -d "$repo_dir" ] || { printf 'orbit: %s: repo not in pool, skipping\n' "$repo_name" >&2; return 1; }

  local branch
  branch=$(orbit_default_branch "$repo_dir" 2>/dev/null) || { printf 'orbit: %s: cannot determine default branch (remote is empty or missing origin/HEAD; push an initial commit first)\n' "$repo_name" >&2; return 1; }

  if [ -n "$new_branch" ]; then
    orbit_maintain_pool_config "$repo_dir" "$root" 0
    # No config writes for the switch itself: the wildcard map already covers
    # any new default branch. Fetch the tracking ref explicitly, check it
    # out, move origin/HEAD.
    if ! git -C "$repo_dir" fetch origin "+refs/heads/$new_branch:refs/remotes/origin/$new_branch" 2>/dev/null; then
      printf 'orbit: %s: cannot fetch branch: %s\n' "$repo_name" "$new_branch" >&2
      return 1
    fi
    if git -C "$repo_dir" rev-parse --verify --quiet "refs/heads/$new_branch" >/dev/null 2>&1; then
      git -C "$repo_dir" checkout "$new_branch" 2>/dev/null
    else
      git -C "$repo_dir" checkout -b "$new_branch" "origin/$new_branch" 2>/dev/null
    fi
    git -C "$repo_dir" symbolic-ref refs/remotes/origin/HEAD "refs/remotes/origin/$new_branch" 2>/dev/null || true
    if [ "$force" -eq 1 ]; then
      git -C "$repo_dir" reset --hard "origin/$new_branch" 2>/dev/null
    fi
    if [ -f "$root/.repos/.$repo_name.md" ]; then
      printf 'orbit: %s: memo may not apply to new branch %s\n' "$repo_name" "$new_branch" >&2
    fi
    printf 'pool: switched %s to branch %s\n' "$repo_name" "$new_branch"
    return 0
  fi

  # Config maintenance, then the touchpoint fetch discipline: named branches
  # only (default + tracked, deduped), never a bare fetch — under the
  # wildcard map a bare fetch would pull every branch's objects.
  orbit_maintain_pool_config "$repo_dir" "$root" 0
  if ! orbit_touchpoint_fetch "$repo_dir"; then
    printf 'orbit: %s: fetch failed\n' "$repo_name" >&2
    return 1
  fi

  local head_before
  head_before=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null || true)

  if [ "$force" -eq 1 ]; then
    git -C "$repo_dir" reset --hard "origin/$branch" 2>/dev/null
    printf '%s: reset to origin/%s\n' "$repo_name" "$branch"
  else
    if ! git -C "$repo_dir" merge --ff-only "origin/$branch" 2>/dev/null; then
      printf 'orbit: %s: fast-forward failed (local diverged from upstream), use --force to reset the pool checkout (worktrees are untouched)\n' "$repo_name" >&2
      return 1
    fi
    local head_after
    head_after=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null || true)
    if [ "$head_before" = "$head_after" ]; then
      printf '%s: already up to date\n' "$repo_name"
    else
      local n_commits
      n_commits=$(git -C "$repo_dir" rev-list --count "${head_before}..${head_after}" 2>/dev/null || echo '?')
      printf '%s: fast-forwarded %s %s → origin/%s\n' "$repo_name" "$n_commits" "$(orbit_plural "$n_commits" commit commits)" "$branch"
    fi
  fi

  # sync updates the pool repo only. If this workspace has a worktree of this repo
  # tracking the same remote branch we just advanced, it is now behind — hint the pull.
  if [ -n "$ws" ]; then
    local wt="$root/$ws/$repo_name"
    if [ -e "$wt/.git" ]; then
      local wt_up
      wt_up=$(git -C "$wt" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null || true)
      if [ "$wt_up" = "origin/$branch" ]; then
        printf 'orbit: %s pool advanced but your worktree (tracking origin/%s) is untouched by sync: pull it with git if you want the new commits\n' "$repo_name" "$branch" >&2
      fi
    fi
  fi
}

orbit_sync() {
  local force=0 new_branch="" repos=()
  local orig_args=("$@")

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --force) force=1; shift ;;
      --branch)
        [ "$#" -ge 2 ] || orbit_fail "--branch requires a value"
        new_branch="$2"; shift 2 ;;
      -*) orbit_fail "unknown option: $1" ;;
      *) repos+=("$1"); shift ;;
    esac
  done

  local root
  root=$(orbit_require_root) || return 1

  # Destructive pool operations are root-scoped. --force discards the pool's
  # local commits; --branch re-points the pool's checked-out branch and its
  # origin/HEAD. Neither destroys anything the calling workspace owns — which
  # is precisely why the call must come from the scope that does own the
  # pool. Bare sync (ff-only) cannot lose data and stays callable from
  # anywhere.
  if [ "$force" -eq 1 ] || [ -n "$new_branch" ]; then
    local scoped_flags=""
    [ "$force" -eq 1 ] && scoped_flags="--force"
    if [ -n "$new_branch" ]; then
      [ -n "$scoped_flags" ] && scoped_flags="$scoped_flags/"
      scoped_flags="$scoped_flags--branch"
    fi
    orbit_require_root_scope "$root" "sync" "sync $scoped_flags" ${orig_args[@]+"${orig_args[@]}"}
  fi

  local ws_ctx=""
  ws_ctx=$(orbit_infer_workspace "$root" 2>/dev/null) || ws_ctx=""
  if [ "${#repos[@]}" -eq 0 ]; then
    local ws repo_name
    if ws=$(orbit_infer_workspace "$root" 2>/dev/null); then
      if repo_name=$(orbit_infer_repo "$root" "$ws" 2>/dev/null); then
        repos+=("$repo_name")
      else
        for d in "$root/$ws"/*/; do
          [ -d "$d" ] || continue
          local name
          name=$(basename "$d")
          if [ -d "$d/.git" ] || [ -f "$d/.git" ]; then
            repos+=("$name")
          fi
        done
      fi
    else
      for d in "$root/.repos"/*/; do
        [ -d "$d" ] || continue
        repos+=("$(basename "$d")")
      done
    fi
  fi

  [ "${#repos[@]}" -gt 0 ] || orbit_fail "no repos to sync"

  local n_ok=0 failed_names=""
  for repo_name in "${repos[@]}"; do
    if orbit_sync_one "$repo_name" "$root" "$force" "$new_branch" "$ws_ctx"; then
      n_ok=$((n_ok + 1))
    else
      failed_names="$failed_names $repo_name"
    fi
  done

  local n_failed=$(( ${#repos[@]} - n_ok ))
  if [ "${#repos[@]}" -gt 1 ]; then
    if [ "$n_failed" -gt 0 ]; then
      printf 'sync complete: %d ok, %d failed (%s)\n' "$n_ok" "$n_failed" "${failed_names# }"
    else
      printf 'sync complete: %d ok, 0 failed\n' "$n_ok"
    fi
  fi

  [ "$n_failed" -eq 0 ]
}

orbit_status() {
  local root ws json_mode=0

  root=$(orbit_require_root) || return 1

  local args=()
  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json_mode=1; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *) args+=("$1"); shift ;;
    esac
  done

  if [ "${#args[@]}" -eq 1 ]; then
    ws="${args[0]}"
  elif [ "${#args[@]}" -eq 0 ]; then
    ws=$(orbit_infer_workspace "$root") || return 1
  else
    orbit_fail "usage: orbit status [--json] [workspace]"
  fi

  local ws_dir="$root/$ws"
  [ -d "$ws_dir" ] || orbit_fail "workspace not found: $ws"

  orbit_ensure_workspace_orbit "$ws_dir"

  local goal
  goal=$(git config --file "$ws_dir/.orbit" --get workspace.goal 2>/dev/null || true)

  local status_val
  status_val=$(git config --file "$ws_dir/.orbit" --get workspace.status 2>/dev/null || true)
  [ -n "$status_val" ] || status_val="active"

  local d name branch upstream ahead behind dirty is_scoped
  local repo_entries=()
  for d in "$ws_dir"/*/; do
    [ -d "$d" ] || continue
    [ -d "$d/.git" ] || [ -f "$d/.git" ] || continue
    name=$(basename "$d")
    branch=$(git -C "$d" branch --show-current 2>/dev/null || echo "detached")
    case "$branch" in
      ws/"$ws"/*) is_scoped=1 ;;
      *) is_scoped=0 ;;
    esac
    # Upstream config may exist while its remote-tracking ref was never
    # materialized (single-branch pool): rev-parse then prints the literal
    # '@{upstream}' AND fails — treat that as untracked, never as in-sync.
    upstream=$(git -C "$d" rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' 2>/dev/null) || upstream='-'
    if [ "$upstream" = '-' ]; then
      ahead='0'; behind='0'
    else
      ahead=$(git -C "$d" rev-list --count "${upstream}..HEAD" 2>/dev/null || echo '0')
      behind=$(git -C "$d" rev-list --count "HEAD..${upstream}" 2>/dev/null || echo '0')
    fi
    dirty=$(git -C "$d" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
    repo_entries+=("$name|$branch|$ahead|$behind|$dirty|$is_scoped|$upstream")
  done

  if [ "$json_mode" -eq 1 ]; then
    local out="{"
    out+="$(orbit_json_kv workspace "$ws"),"
    out+="$(orbit_json_kv goal "$goal"),"
    out+="$(orbit_json_kv status "$status_val"),"
    out+='"worktrees":['
    local first=1
    for entry in "${repo_entries[@]+${repo_entries[@]}}"; do
      IFS='|' read -r name branch ahead behind dirty is_scoped upstream <<< "$entry"
      local dirty_bool="false"
      [ "$dirty" = "0" ] || dirty_bool="true"
      [ "$first" -eq 1 ] || out+=','
      first=0
      out+='{'
      out+="$(orbit_json_kv name "$name"),"
      out+="$(orbit_json_kv branch "$branch"),"
      out+="$(orbit_json_kv_raw ahead "$ahead"),"
      out+="$(orbit_json_kv_raw behind "$behind"),"
      out+="$(orbit_json_kv_raw dirty "$dirty_bool"),"
      out+="$(orbit_json_kv_raw scoped "$is_scoped")"
      out+='}'
    done
    out+=']}'
    printf '%s\n' "$out"
    return 0
  fi

  printf '=== workspace: %s (%s) ===\n' "$ws" "$status_val"
  if [ -n "$goal" ]; then
    printf 'goal: %s\n' "$goal"
  fi
  printf '\n'

  if [ "${#repo_entries[@]}" -eq 0 ]; then
    printf '(no repos yet — orbit add <repo>)\n'
    return 0
  fi

  local name_w=0
  for entry in "${repo_entries[@]}"; do
    IFS='|' read -r name _ <<< "$entry"
    [ "${#name}" -gt "$name_w" ] && name_w=${#name}
  done

  for entry in "${repo_entries[@]}"; do
    IFS='|' read -r name branch ahead behind dirty is_scoped upstream <<< "$entry"
    local display_branch="$branch" raw_mark=""
    case "$branch" in
      ws/"$ws"/*) display_branch="${branch#ws/"$ws"/}" ;;
    esac
    [ "$is_scoped" = "0" ] && raw_mark=" raw"
    if [ "$upstream" = '-' ]; then
      # Never fabricate +0/-0 for an untracked branch — that reads as "in sync"
      printf '  %-*s %-28s %-15s -   -  dirty:%s%s\n' "$name_w" "$name" "$display_branch" "(no upstream)" "$dirty" "$raw_mark"
    elif [ "$ahead" = "0" ] && [ "$behind" = "0" ] && [ "$dirty" = "0" ]; then
      printf '  %-*s %-28s %-15s clean\n' "$name_w" "$name" "$display_branch" "$upstream"
    else
      local counters=""
      [ "$ahead" != "0" ] && counters="+$ahead"
      if [ "$behind" != "0" ]; then
        [ -n "$counters" ] && counters="$counters "
        counters="$counters-$behind"
      fi
      if [ "$dirty" != "0" ]; then
        [ -n "$counters" ] && counters="$counters  "
        counters="${counters}dirty:$dirty"
      fi
      printf '  %-*s %-28s %-15s %s%s\n' "$name_w" "$name" "$display_branch" "$upstream" "$counters" "$raw_mark"
    fi
  done

  # Steering parity with context/done (spec-warnings steering registry):
  # raw-mode branches get the conversion pointer on stderr; the stdout table
  # keeps only the ' raw' mark.
  for entry in "${repo_entries[@]}"; do
    IFS='|' read -r name branch ahead behind dirty is_scoped upstream <<< "$entry"
    [ "$is_scoped" = "0" ] || continue
    printf 'orbit: %s: raw mode branch — run: orbit switch -c %s (convert to scoped)\n' "$name" "$branch" >&2
  done
}

orbit_goal() {
  local root ws goal=""

  root=$(orbit_require_root) || return 1
  ws=$(orbit_infer_workspace "$root") || return 1

  local ws_dir="$root/$ws"
  local orbit_file="$ws_dir/.orbit"

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --clear)
        [ "$#" -le 1 ] || orbit_fail "unexpected argument after --clear: $2"
        if [ -f "$orbit_file" ]; then
          git config --file "$orbit_file" --unset workspace.goal 2>/dev/null || true
        fi
        printf 'goal cleared\n'
        orbit_random_msg ORBIT_GOAL_CLEAR_FAREWELLS
        return 0
        ;;
      -*) orbit_fail "unknown option: $1" ;;
      *)
        if [ -z "$goal" ]; then
          goal="$1"
        else
          orbit_fail "unexpected argument: $1"
        fi
        ;;
    esac
    shift
  done

  if [ -z "$goal" ]; then
    local use_editor=false
    if [ -n "${ORBIT_EDITOR:-}" ]; then
      use_editor=true
    elif [ -t 0 ]; then
      use_editor=true
    fi

    if [ "$use_editor" = true ]; then
      local current_goal
      current_goal=$(git config --file "$orbit_file" --get workspace.goal 2>/dev/null || true)
      local tmpf
      tmpf=$(mktemp "${TMPDIR:-/tmp}/orbit-goal-XXXXXX")
      local pidx=$(( RANDOM % ${#ORBIT_GOAL_PROMPTS[@]} ))
      if [ -n "$current_goal" ]; then
        printf '%s\n' "$current_goal" > "$tmpf"
        printf '\n# %s\n# Lines starting with # are ignored. Empty goal keeps current.\n' "${ORBIT_GOAL_PROMPTS[$pidx]}" >> "$tmpf"
      else
        printf '\n# %s\n# Lines starting with # are ignored. Empty goal aborts.\n' "${ORBIT_GOAL_PROMPTS[$pidx]}" > "$tmpf"
      fi
      local editor="${ORBIT_EDITOR:-${VISUAL:-${EDITOR:-vi}}}"
      "$editor" "$tmpf" </dev/tty >/dev/tty 2>/dev/null || "$editor" "$tmpf"
      goal=$(awk '/^#/{next} {lines[++n]=$0} END{s=1;e=n; while(s<=e && lines[s]=="")s++; while(e>=s && lines[e]=="")e--; for(i=s;i<=e;i++)print lines[i]}' "$tmpf")
      rm -f "$tmpf"
      if [ -z "$goal" ]; then
        if [ -n "$current_goal" ]; then
          return 0
        fi
        orbit_fail "aborting: empty goal"
      fi
    else
      goal=$(cat)
    fi
  fi
  [ -n "$goal" ] || orbit_fail "aborting: empty goal"

  orbit_ensure_workspace_orbit "$ws_dir"

  # Setting a goal signals new work: reactivate a done workspace so it leaves
  # prune eligibility, and clear the previous cycle's completion record.
  local prev_status
  prev_status=$(git config --file "$orbit_file" --get workspace.status 2>/dev/null || true)
  if [ "$prev_status" = "done" ]; then
    git config --file "$orbit_file" --unset workspace.status 2>/dev/null || true
    git config --file "$orbit_file" --unset workspace.done-at 2>/dev/null || true
    git config --file "$orbit_file" --unset workspace.done-date 2>/dev/null || true
    git config --file "$orbit_file" --remove-section pr 2>/dev/null || true
  fi

  git config --file "$orbit_file" workspace.goal "$goal"
  printf 'goal set: %s\n' "$goal"
  if [ "$prev_status" = "done" ]; then
    printf 'orbit: workspace reactivated (was done; cleared completion record and PR history)\n' >&2
  fi
  orbit_random_msg ORBIT_GOAL_FAREWELLS
}

orbit_jot() {
  local root ws repo_name="" text="" pop=false json_mode=0

  root=$(orbit_require_root) || return 1
  ws=$(orbit_infer_workspace "$root") || return 1

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --pop) pop=true; shift ;;
      --json) json_mode=1; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *)
        if [ -z "$repo_name" ]; then
          # Only a plain pool-repo name can name a repo here; a path-like
          # argument is treated as jot text, never resolved as a worktree.
          if orbit_valid_repo_name "$1" && { [ -d "$root/$ws/$1/.git" ] || [ -f "$root/$ws/$1/.git" ]; }; then
            repo_name="$1"
          else
            if [ -n "$text" ]; then
              orbit_fail "unexpected argument: $1"
            fi
            text="$1"
          fi
        elif [ -z "$text" ]; then
          text="$1"
        else
          orbit_fail "unexpected argument: $1"
        fi
        shift
        ;;
    esac
  done

  if [ -z "$repo_name" ]; then
    repo_name=$(orbit_infer_repo "$root" "$ws" 2>/dev/null) || orbit_fail "cannot infer repo from CWD, specify repo name"
  fi

  local ws_dir="$root/$ws"
  local orbit_file="$ws_dir/.orbit"
  orbit_ensure_workspace_orbit "$ws_dir"

  if [ "$pop" = true ]; then
    if [ "$json_mode" -eq 1 ]; then
      local entries=()
      while IFS= read -r line; do
        [ -n "$line" ] || continue
        entries+=("$line")
      done < <(git config --file "$orbit_file" --get-all "jot.$repo_name.entry" 2>/dev/null || true)
      git config --file "$orbit_file" --unset-all "jot.$repo_name.entry" 2>/dev/null || true
      local out
      out="{$(orbit_json_kv repo "$repo_name"),\"entries\":["
      local first=1
      for e in "${entries[@]+${entries[@]}}"; do
        [ "$first" -eq 1 ] || out+=','
        first=0
        out+="\"$(orbit_json_escape "$e")\""
      done
      out+="],$(orbit_json_kv_raw count "${#entries[@]}")}"
      printf '%s\n' "$out"
    else
      git config --file "$orbit_file" --get-all "jot.$repo_name.entry" 2>/dev/null || true
      git config --file "$orbit_file" --unset-all "jot.$repo_name.entry" 2>/dev/null || true
    fi
    return 0
  fi

  if [ -z "$text" ]; then
    local use_editor=false
    if [ -n "${ORBIT_EDITOR:-}" ]; then
      use_editor=true
    elif [ -t 0 ]; then
      use_editor=true
    fi

    if [ "$use_editor" = true ]; then
      local tmpf
      tmpf=$(mktemp "${TMPDIR:-/tmp}/orbit-jot-XXXXXX")
      printf '\n# Jot a note for %s. Lines starting with # are ignored. Empty aborts.\n' "$repo_name" > "$tmpf"
      local editor="${ORBIT_EDITOR:-${VISUAL:-${EDITOR:-vi}}}"
      "$editor" "$tmpf" </dev/tty >/dev/tty 2>/dev/null || "$editor" "$tmpf"
      text=$(awk '/^#/{next} {lines[++n]=$0} END{s=1;e=n; while(s<=e && lines[s]=="")s++; while(e>=s && lines[e]=="")e--; for(i=s;i<=e;i++)print lines[i]}' "$tmpf")
      rm -f "$tmpf"
    else
      text=$(cat)
    fi
  fi

  [ -n "$text" ] || orbit_fail "aborting: empty jot"

  # Subsection form ([jot "<repo>"] entry), matching repos.<name>.url: a plain
  # jot.<repo> key cannot hold every contract-legal repo name (my_repo, 2048 —
  # git-config key segments reject '_' and leading digits), a subsection can.
  git config --file "$orbit_file" --add "jot.$repo_name.entry" "$text"

  local count buf half
  count=$(git config --file "$orbit_file" --get-all "jot.$repo_name.entry" 2>/dev/null | grep -c . || true)
  buf=$(orbit_jot_buffer_size "$root")
  half=$(( buf / 2 ))
  if [ "$count" -gt "$buf" ]; then
    printf 'orbit: %s has %s jots (overflow): jot %s --pop, then merge into memo\n' \
      "$repo_name" "$count" "$repo_name" >&2
  elif [ "$count" -gt "$half" ]; then
    printf 'orbit: %s has %s jots (building)\n' "$repo_name" "$count" >&2
  fi
}

orbit_done() {
  local root ws pr_urls=() json_mode=0

  root=$(orbit_require_root) || return 1
  ws=$(orbit_infer_workspace "$root") || return 1

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json_mode=1; shift ;;
      --pr) [ "$#" -ge 2 ] || orbit_fail "--pr requires a URL"; pr_urls+=("$2"); shift 2 ;;
      *) orbit_fail "unknown argument: $1" ;;
    esac
  done

  local ws_dir="$root/$ws"
  local orbit_file="$ws_dir/.orbit"

  orbit_ensure_workspace_orbit "$ws_dir"

  # Per-repo wrap-up gate (advisory, never blocks done): for each repo surface
  # what remains — one issue per line, with the literal command to close it.
  # Keywords (pop + merge / explore + write / curate once) are quoted verbatim
  # by skills/orbit/SKILL.md and skills/CONSTRAINTS.md: keep them intact.
  local budget_hint=0 any_warn=0
  local rs_name rs_count rs_mstate rs_branch rs_scoped
  while IFS='|' read -r rs_name rs_count _ _ rs_mstate rs_branch rs_scoped; do
    [ -n "$rs_name" ] || continue
    if [ "$rs_count" -gt 0 ]; then
      printf 'orbit: %s: %s jots remain — run: orbit jot %s --pop, then merge into memo (pop + merge)\n' \
        "$rs_name" "$rs_count" "$rs_name" >&2
      budget_hint=1 any_warn=1
    fi
    if [ "$rs_mstate" = "thin" ] && [ "$rs_count" -eq 0 ]; then
      printf 'orbit: %s: memo thin, no capture this session — explore + write\n' "$rs_name" >&2
      any_warn=1
    fi
    if [ "$rs_mstate" = "over" ]; then
      printf 'orbit: %s: memo over budget — curate once\n' "$rs_name" >&2
      budget_hint=1 any_warn=1
    fi
    if [ "$rs_scoped" = "0" ]; then
      printf 'orbit: %s: raw mode branch — run: orbit switch -c %s (convert to scoped)\n' \
        "$rs_name" "$rs_branch" >&2
      any_warn=1
    fi
  done < <(orbit_collect_repo_status "$root" "$ws_dir")

  if [ "$budget_hint" -eq 1 ]; then
    printf 'orbit: card budget is %s~%s lines: curate the memo to roles + how to use, don'\''t just append\n' \
      "$(orbit_memo_min "$root")" "$(orbit_memo_max "$root")" >&2
  fi

  # Any per-repo debt above means session knowledge is still outside the memo.
  # done ends the session; working memory and the jot queue do not survive it.
  if [ "$any_warn" -eq 1 ]; then
    printf 'orbit: only memo survives done\n' >&2
  fi

  local now now_date
  now=$(date +%s)
  now_date=$(date -r "$now" +%Y-%m-%d 2>/dev/null || date -d "@$now" +%Y-%m-%d 2>/dev/null || date +%Y-%m-%d)

  git config --file "$orbit_file" workspace.status "done"
  git config --file "$orbit_file" workspace.done-at "$now"
  git config --file "$orbit_file" workspace.done-date "$now_date"

  if [ "${#pr_urls[@]}" -gt 0 ]; then
    for url in "${pr_urls[@]}"; do
      git config --file "$orbit_file" --add pr.url "$url"
    done
  fi

  if [ "$json_mode" -eq 1 ]; then
    local all_pr_urls=()
    while IFS= read -r url; do
      [ -n "$url" ] || continue
      all_pr_urls+=("$url")
    done < <(git config --file "$orbit_file" --get-all pr.url 2>/dev/null || true)

    local out="{"
    out+="$(orbit_json_kv workspace "$ws"),"
    out+="$(orbit_json_kv status "done"),"
    out+="$(orbit_json_kv_raw doneAt "$now"),"
    out+='"prs":['
    local first=1
    for url in "${all_pr_urls[@]+${all_pr_urls[@]}}"; do
      [ "$first" -eq 1 ] || out+=','
      first=0
      out+="\"$(orbit_json_escape "$url")\""
    done
    out+=']}'
    printf '%s\n' "$out"
    return 0
  fi

  printf 'workspace %s marked done\n' "$ws"
  if [ "${#pr_urls[@]}" -gt 0 ]; then
    printf '  pr: %s\n' "${pr_urls[@]}"
  fi
  orbit_random_msg ORBIT_DONE_FAREWELLS
}

orbit_repos() {
  local json_mode=0 urls_mode=0

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json_mode=1; shift ;;
      --urls) urls_mode=1; shift ;;
      *) orbit_fail "usage: orbit repos [--json] [--urls]" ;;
    esac
  done

  local root
  root=$(orbit_require_root) || return 1

  local index="$root/.repos/.orbit"
  local has_repos=0

  # Mark repos already present in the current workspace (if any)
  local cur_ws=""
  cur_ws=$(orbit_infer_workspace "$root" 2>/dev/null) || cur_ws=""

  local names=() urls=() briefs=() heads=() stales=() completes=() memo_states=() in_ws_marks=()
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir" ] || continue
    local name url brief head idx_url idx_brief idx_head
    name=$(basename "$repo_dir")
    has_repos=1

    idx_url=$(git config --file "$index" --get "repos.$name.url" 2>/dev/null || true)
    idx_brief=$(git config --file "$index" --get "repos.$name.brief" 2>/dev/null || true)
    idx_head=$(git config --file "$index" --get "repos.$name.head" 2>/dev/null || true)

    url="$idx_url"
    if [ -z "$url" ]; then
      url=$(git -C "$repo_dir" remote get-url origin 2>/dev/null || echo "-")
    fi

    # repos only needs the brief text; the source tag drives no rendering here
    IFS= read -r brief <<< "$(orbit_pool_brief "$root" "$index" "$name" "$repo_dir")"
    [ -n "$brief" ] || brief="-"

    head="$idx_head"
    if [ -z "$head" ]; then
      head=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null) || head="-"
    fi

    local incomplete_flag=false
    if [ ! -f "$root/.repos/.$name.md" ] || [ -z "$idx_url" ] || [ -z "$idx_brief" ] || [ -z "$idx_head" ]; then
      incomplete_flag=true
    fi

    local memo_behind=0
    local current_head
    current_head=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null || true)
    if [ -n "$idx_head" ] && [ -n "$current_head" ] && [ "$idx_head" != "$current_head" ] && [ -f "$root/.repos/.$name.md" ]; then
      memo_behind=$(git -C "$repo_dir" rev-list "$idx_head".."$current_head" --count 2>/dev/null || echo 0)
    fi

    # Human table carries memo state as a column (was: unsilenceable stderr spray)
    local memo_state
    if [ ! -f "$root/.repos/.$name.md" ]; then
      memo_state="none"
    elif [ "$memo_behind" != "0" ]; then
      memo_state="stale $memo_behind"
    else
      memo_state="ok"
    fi

    local in_ws=""
    if [ -n "$cur_ws" ] && { [ -d "$root/$cur_ws/$name/.git" ] || [ -f "$root/$cur_ws/$name/.git" ]; }; then
      in_ws="*"
    fi

    names+=("$name")
    urls+=("$url")
    briefs+=("$brief")
    heads+=("$head")
    stales+=("$memo_behind")
    completes+=("$incomplete_flag")
    memo_states+=("$memo_state")
    in_ws_marks+=("$in_ws")
  done

  if [ "$has_repos" -eq 0 ]; then
    if [ "$json_mode" -eq 1 ]; then
      printf '[]\n'
    else
      printf '(no repos in pool)\n'
    fi
    return 0
  fi

  if [ "$json_mode" -eq 1 ]; then
    local out='['
    local first=1 i
    for i in "${!names[@]}"; do
      [ "$first" -eq 1 ] || out+=','
      first=0
      out+='{'
      out+="$(orbit_json_kv name "${names[$i]}"),"
      out+="$(orbit_json_kv url "${urls[$i]}"),"
      out+="$(orbit_json_kv brief "${briefs[$i]}"),"
      out+="$(orbit_json_kv head "${heads[$i]}"),"
      out+="$(orbit_json_kv_raw incomplete "${completes[$i]}"),"
      out+="$(orbit_json_kv_raw memoBehind "${stales[$i]}")"
      out+='}'
    done
    out+=']'
    printf '%s\n' "$out"
    return 0
  fi

  local name_w=4
  for i in "${!names[@]}"; do
    [ "${#names[$i]}" -gt "$name_w" ] && name_w=${#names[$i]}
  done

  if [ "$urls_mode" -eq 1 ]; then
    printf '%-*s  %-5s %-9s %-40s %s\n' "$name_w" "NAME" "ADDED" "MEMO" "URL" "BRIEF"
    local i
    for i in "${!names[@]}"; do
      printf '%-*s  %-5s %-9s %-40.40s %s\n' "$name_w" "${names[$i]}" "${in_ws_marks[$i]}" "${memo_states[$i]}" "${urls[$i]}" "${briefs[$i]}"
    done
  else
    printf '%-*s  %-5s %-9s %s\n' "$name_w" "NAME" "ADDED" "MEMO" "BRIEF"
    local i
    for i in "${!names[@]}"; do
      printf '%-*s  %-5s %-9s %s\n' "$name_w" "${names[$i]}" "${in_ws_marks[$i]}" "${memo_states[$i]}" "${briefs[$i]}"
    done
  fi
}

orbit_info() {
  local json_mode=0 repo_name=""

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json_mode=1; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *)
        if [ -z "$repo_name" ]; then
          repo_name="$1"
        else
          orbit_fail "unexpected argument: $1"
        fi
        shift
        ;;
    esac
  done

  [ -n "$repo_name" ] || orbit_fail "usage: orbit info [--json] <repo>"
  orbit_require_repo_name "$repo_name"

  local root
  root=$(orbit_require_root) || return 1

  local repo_dir="$root/.repos/$repo_name"
  [ -d "$repo_dir" ] || orbit_fail "repo not in pool: $repo_name"

  local default_branch
  default_branch=$(orbit_default_branch "$repo_dir" 2>/dev/null) || true
  if [ -n "$default_branch" ]; then
    # Config maintenance only — info is a screening command and stays purely
    # local (zero network, like `orbit repos` and the cruise block). The
    # staleness checks below read last-fetched refs, refreshed by the
    # fetching touchpoints (sync / prune) or the user's own fetch/pull.
    orbit_maintain_pool_config "$repo_dir" "$root" 0
  fi

  orbit_upstream_check "$repo_name" "$root"
  orbit_staleness_check "$repo_name" "$root"

  local content=""
  local md_file="$root/.repos/.$repo_name.md"
  if [ -f "$md_file" ]; then
    content=$(cat "$md_file")
  else
    local readme=""
    for f in "$repo_dir/README.md" "$repo_dir/README" "$repo_dir/readme.md"; do
      if [ -f "$f" ]; then readme="$f"; break; fi
    done

    if [ -n "$readme" ]; then
      local max total
      max=$(orbit_memo_max "$root")
      total=$(grep -c '' "$readme" 2>/dev/null || echo 0)
      content=$(head -n "$max" "$readme")
      if [ "$total" -gt "$max" ]; then
        printf 'orbit: %s has no memo; showing first %s of %s README lines\n' "$repo_name" "$max" "$total" >&2
      else
        printf 'orbit: %s has no memo, showing README\n' "$repo_name" >&2
      fi
    else
      printf 'orbit: %s has no memo\n' "$repo_name" >&2
      content="(no memo available)"
    fi
  fi

  if [ "$json_mode" -eq 1 ]; then
    local remote_ahead=0 memo_behind=0
    if [ -n "$default_branch" ]; then
      local local_head remote_head
      local_head=$(git -C "$repo_dir" rev-parse "refs/heads/$default_branch" 2>/dev/null) || true
      remote_head=$(git -C "$repo_dir" rev-parse "refs/remotes/origin/$default_branch" 2>/dev/null) || true
      if [ -n "$local_head" ] && [ -n "$remote_head" ] && [ "$local_head" != "$remote_head" ]; then
        remote_ahead=$(git -C "$repo_dir" rev-list "$local_head".."$remote_head" --count 2>/dev/null || echo 0)
      fi
    fi
    local index="$root/.repos/.orbit"
    local stored
    stored=$(git config --file "$index" --get "repos.$repo_name.head" 2>/dev/null || true)
    if [ -n "$stored" ] && [ -f "$md_file" ]; then
      local current_head
      current_head=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null || true)
      if [ -n "$current_head" ] && [ "$stored" != "$current_head" ]; then
        memo_behind=$(git -C "$repo_dir" rev-list "$stored".."$current_head" --count 2>/dev/null || echo 0)
      fi
    fi
    local out="{"
    out+="$(orbit_json_kv repo "$repo_name"),"
    out+="$(orbit_json_kv content "$content"),"
    out+="$(orbit_json_kv_raw remoteAhead "$remote_ahead"),"
    out+="$(orbit_json_kv_raw memoBehind "$memo_behind")"
    out+='}'
    printf '%s\n' "$out"
    return 0
  fi

  printf '%s\n' "$content"
}

orbit_memo_scaffold() {
  local repo_name="$1" root="$2"
  local repo_dir="$root/.repos/$repo_name"

  [ -d "$repo_dir" ] || orbit_fail "repo not in pool: $repo_name"

  cat <<EOF
# ${repo_name}

TODO — one sentence, ≤ 120 chars, what this repo is

## When to add (roles)
- TODO — a reason a workspace would pull this repo in (list every role; a repo may fill many)

## How to use
- \`TODO\` — MVP/VIP file or dir path + why it matters + when to reach for it (list as many as needed; e.g. CLI entry, core package)
EOF
}

orbit_memo() {
  if [ "$#" -eq 0 ]; then
    orbit_memo_refresh_all
    return 0
  fi

  local repo_name="$1"; shift
  local refresh_only=0 scaffold_mode=0

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --refresh)  refresh_only=1; shift ;;
      --scaffold) scaffold_mode=1; shift ;;
      *) orbit_fail "unknown option: $1" ;;
    esac
  done

  local root
  root=$(orbit_require_root) || return 1
  orbit_require_repo_name "$repo_name"
  local repo_dir="$root/.repos/$repo_name"
  [ -d "$repo_dir" ] || orbit_fail "repo not in pool: $repo_name"

  if [ "$scaffold_mode" -eq 1 ]; then
    orbit_memo_scaffold "$repo_name" "$root"
    return 0
  fi

  if [ "$refresh_only" -eq 1 ]; then
    orbit_memo_refresh_one "$repo_name" "$root"
    return 0
  fi

  local md_file="$root/.repos/.$repo_name.md"
  local content
  content=$(cat)
  [ -n "$content" ] || orbit_fail "empty input; pipe markdown content to 'orbit memo $repo_name'"

  local brief
  brief=$(printf '%s\n' "$content" | orbit_brief_extract /dev/stdin) || orbit_fail "cannot extract brief from input (need a valid text paragraph after title)"

  printf '%s\n' "$content" > "$md_file"

  local index="$root/.repos/.orbit"
  local url head
  url=$(git -C "$repo_dir" remote get-url origin 2>/dev/null || echo "-")
  head=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null) || head="-"
  git config --file "$index" "repos.$repo_name.url" "$url"
  git config --file "$index" "repos.$repo_name.brief" "$brief"
  git config --file "$index" "repos.$repo_name.head" "$head"

  # Over-budget advisory: one-shot stderr when this write left the card well
  # past the ceiling (maxLines + minLines buffer, so best-effort curation that
  # lands slightly over the ceiling is left alone). No loop: the same state
  # resurfaces via per-repo status (context/done), computed inline each time.
  local ws
  if ws=$(orbit_infer_workspace "$root" 2>/dev/null) && [ -n "$ws" ]; then
    local n threshold
    n=$(grep -c '[^[:space:]]' "$md_file" 2>/dev/null || echo 0)
    threshold=$(orbit_memo_overlong_threshold "$root")
    if [ "$n" -gt "$threshold" ]; then
      printf 'orbit: %s memo is over budget (%s lines): curate the card back to %s~%s lines, don'\''t just append\n' \
        "$repo_name" "$n" "$(orbit_memo_min "$root")" "$(orbit_memo_max "$root")" >&2
    fi
  fi

  printf 'wrote memo for %s (brief: %s)\n' "$repo_name" "$brief"
}

orbit_memo_refresh_one() {
  local repo_name="$1" root="$2"
  local repo_dir="$root/.repos/$repo_name"
  local index="$root/.repos/.orbit"
  local md_file="$root/.repos/.$repo_name.md"

  local url head brief=""
  url=$(git -C "$repo_dir" remote get-url origin 2>/dev/null || echo "-")
  head=$(git -C "$repo_dir" rev-parse HEAD 2>/dev/null) || head="-"

  if [ -f "$md_file" ]; then
    brief=$(orbit_brief_extract "$md_file" || true)
  fi

  git config --file "$index" "repos.$repo_name.url" "$url"
  git config --file "$index" "repos.$repo_name.head" "$head"
  if [ -n "$brief" ]; then
    git config --file "$index" "repos.$repo_name.brief" "$brief"
  else
    git config --file "$index" --unset "repos.$repo_name.brief" 2>/dev/null || true
  fi

  printf 'refreshed index: %s\n' "$repo_name"
}

orbit_memo_refresh_all() {
  local root
  root=$(orbit_require_root) || return 1

  local n_refreshed=0
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir" ] || continue
    local name
    name=$(basename "$repo_dir")
    orbit_memo_refresh_one "$name" "$root"
    n_refreshed=$((n_refreshed + 1))
  done
  printf 'refreshed index: %d %s\n' "$n_refreshed" "$(orbit_plural "$n_refreshed" repo repos)"
}

# --- Prune ---

orbit_parse_duration() {
  local input="$1"
  local num unit
  num="${input%[dwmy]}"
  unit="${input##*[0-9]}"
  [[ "$num" =~ ^[0-9]+$ ]] || return 1
  case "$unit" in
    d) printf '%s\n' "$(( num * 86400 ))" ;;
    w) printf '%s\n' "$(( num * 604800 ))" ;;
    m) printf '%s\n' "$(( num * 2592000 ))" ;;
    y) printf '%s\n' "$(( num * 31536000 ))" ;;
    *) return 1 ;;
  esac
}

# --- Layer-1 PR evidence -------------------------------------------------
# Run-scoped cache, reset by orbit_prune. ORBIT_PR_URLS holds the recorded
# pr.url list; each URL is queried once (network-bound) and cached as a
# `url\x1fstate\x1fheadRefName\x1fheadRefOid` line. A gh failure caches an
# empty state — a failed call never answers, and never fires twice.
# ORBIT_PR_GH_BAD=1 disables the layer for the rest of the run after one
# warning (gh absent, or one call failing).
ORBIT_PR_URLS="" ORBIT_PR_CACHE="" ORBIT_PR_GH_BAD=""

# Normalize a repo or PR URL to its host/org/name triple, lowercased —
# scheme, user, `.git` suffix and a trailing /pull/<n> all wash out, so an
# SSH origin and an HTTPS PR URL for the same repo compare equal.
orbit_repo_url_triple() {
  local u="$1"
  u="${u%/}"; u="${u%.git}"
  case "$u" in *"/pull/"*) u="${u%%/pull/*}" ;; esac
  u="${u#*://}"                # strip scheme://
  u="${u#*@}"                  # strip userinfo (scp git@ and https user@ alike)
  u="${u/://}"                 # scp-like host:path -> host/path
  printf '%s\n' "$(printf '%s' "$u" | tr '[:upper:]' '[:lower:]')"
}

# Query gh for one URL, cached per run. Set-global style (not stdout
# capture): ORBIT_PR_STATE / ORBIT_PR_HEAD / ORBIT_PR_OID — $() subshells
# would lose the cache write. Returns 1 when gh cannot answer; the FIRST
# failure (gh absent, or any call erroring) warns once and disables layer 1
# for the rest of the run.
orbit_pr_fetch() {
  local url="$1" line u
  ORBIT_PR_STATE="" ORBIT_PR_HEAD="" ORBIT_PR_OID=""
  while IFS= read -r line; do
    [ -n "$line" ] || continue
    u="${line%%$'\x1f'*}"
    if [ "$u" = "$url" ]; then
      line="${line#*$'\x1f'}"
      ORBIT_PR_STATE="${line%%$'\x1f'*}"
      line="${line#*$'\x1f'}"
      ORBIT_PR_HEAD="${line%%$'\x1f'*}"
      ORBIT_PR_OID="${line#*$'\x1f'}"
      [ -n "$ORBIT_PR_STATE" ]
      return
    fi
  done <<EOF
$ORBIT_PR_CACHE
EOF
  [ "$ORBIT_PR_GH_BAD" = "1" ] && return 1
  if ! command -v gh >/dev/null 2>&1; then
    printf 'orbit: PR evidence recorded but gh unavailable — falling back to git merged checks\n' >&2
    ORBIT_PR_GH_BAD=1
    return 1
  fi
  local json
  if ! json=$(gh pr view "$url" --json state,headRefName,headRefOid 2>/dev/null); then
    printf 'orbit: PR evidence recorded but gh unavailable — falling back to git merged checks\n' >&2
    ORBIT_PR_GH_BAD=1
    ORBIT_PR_CACHE="${ORBIT_PR_CACHE}${url}"$'\x1f\x1f\x1f'$'\n'
    return 1
  fi
  ORBIT_PR_STATE=$(printf '%s' "$json" | grep -o '"state"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
  ORBIT_PR_HEAD=$(printf '%s' "$json" | grep -o '"headRefName"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
  ORBIT_PR_OID=$(printf '%s' "$json" | grep -o '"headRefOid"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
  ORBIT_PR_CACHE="${ORBIT_PR_CACHE}${url}"$'\x1f'"${ORBIT_PR_STATE}"$'\x1f'"${ORBIT_PR_HEAD}"$'\x1f'"${ORBIT_PR_OID}"$'\n'
  [ -n "$ORBIT_PR_STATE" ]
}

# Layer 1 per branch: a recorded PR covers THIS branch — repo-matched (URL
# triple vs the pool repo's origin), the branch's RECORDED upstream mapping
# (branch.<name>.merge, what orbit_set_upstream writes) equals the PR's
# headRefName (multi-segment names like feat/login survive — a last-segment
# match would never fire for them), gh reports it merged, and the local tip
# is contained in the PR head (local objects only — a head the pool never
# fetched cannot answer, and the branch falls through).
orbit_pr_covers_branch() {
  local main_repo="$1" branch="$2" url triple head_name
  head_name=$(git -C "$main_repo" config --get "branch.$branch.merge" 2>/dev/null || true)
  head_name="${head_name#refs/heads/}"
  [ -n "$head_name" ] || return 1
  triple=$(orbit_repo_url_triple "$(git -C "$main_repo" config --get remote.origin.url 2>/dev/null || true)")
  [ -n "$triple" ] || return 1
  while IFS= read -r url; do
    [ -n "$url" ] || continue
    [ "$(orbit_repo_url_triple "$url")" = "$triple" ] || continue
    orbit_pr_fetch "$url" || continue
    [ "$ORBIT_PR_STATE" = "MERGED" ] || continue
    [ "$ORBIT_PR_HEAD" = "$head_name" ] || continue
    [ -n "$ORBIT_PR_OID" ] || continue
    git -C "$main_repo" merge-base --is-ancestor "$branch" "$ORBIT_PR_OID" 2>/dev/null || continue
    return 0
  done <<EOF
$ORBIT_PR_URLS
EOF
  return 1
}

# True when <branch>'s content is provably contained in <upstream>'s tree —
# the signature of a squash/rebase merge, which rewrites SHAs and therefore
# defeats the ancestor check. Prints "tree" when `git merge-tree
# --write-tree` answered (clean merge, either direction — definitive), and
# "cherry" when merge-tree could not answer (git < 2.38, or a conflicting
# merge) but every commit is patch-equivalent upstream. merge-tree writes a
# few tree objects to the ODB (invisible git-internal cache, also under
# --dry-run).
orbit_branch_content_upstream() {
  local main_repo="$1" branch="$2" upstream="$3" merged_tree
  if merged_tree=$(git -C "$main_repo" merge-tree --write-tree "$upstream" "$branch" 2>/dev/null); then
    [ "$merged_tree" = "$(git -C "$main_repo" rev-parse "$upstream^{tree}" 2>/dev/null)" ] || return 1
    printf 'tree\n'
    return 0
  fi
  # An unresolvable upstream — or any cherry failure — is "cannot tell", not
  # "content upstream": an empty '+' set would otherwise invert into a false
  # positive, and the hint hands out branch -D verbatim. Capture first and
  # match without a pipe (a pipe can SIGPIPE the producer under pipefail).
  local cherry_out
  cherry_out=$(git -C "$main_repo" cherry "$upstream" "$branch" 2>/dev/null) || return 1
  printf 'cherry\n'
  ! grep -q '^+' <<< "$cherry_out"
}

# Delete a branch, passing git's native error through on failure. git refuses
# when the branch is checked out — including STALE registrations left by
# worktrees removed without `git worktree remove` (dir gone, admin entry
# stays, refusal persists). Those are cleaned (`worktree remove --force` on
# the dead path) and the delete retried once; a live checkout keeps refusing.
# LC_ALL=C: the stale-registration retry parses git's error text, and a
# localized message would silently disable the retry.
orbit_branch_delete() {
  local repo="$1" branch="$2" flag="$3" allow_merged_retry="${4:-0}" del_err wt_path
  if del_err=$(LC_ALL=C git -C "$repo" branch "$flag" "$branch" 2>&1 >/dev/null); then
    return 0
  fi
  # A stale worktree registration (dir gone, admin entry left) keeps refusing
  # deletion forever — clean it and retry. A live checkout keeps refusing.
  wt_path=$(printf '%s\n' "$del_err" | sed -n "s/.*used by worktree at '\(.*\)'.*/\1/p" | head -1)
  if [ -n "$wt_path" ] && [ ! -e "$wt_path" ]; then
    git -C "$repo" worktree remove --force "$wt_path" >/dev/null 2>&1 || true
    if del_err=$(LC_ALL=C git -C "$repo" branch "$flag" "$branch" 2>&1 >/dev/null); then
      return 0
    fi
  fi
  # `-d` measures mergedness against the LOCAL default checkout, which lags
  # origin/<default> after a fetch. Callers who already proved the content is
  # upstream (layer-2 / PR-merged) treat that refusal as retryable with -D.
  if [ "$allow_merged_retry" = "1" ]; then
    case "$del_err" in
      *"not fully merged"*)
        if del_err=$(LC_ALL=C git -C "$repo" branch -D "$branch" 2>&1 >/dev/null); then
          return 0
        fi
        ;;
    esac
  fi
  printf 'orbit: %s\n' "$(printf '%s\n' "$del_err" | head -1)" >&2
  return 1
}

# Pure verdict for one branch: which layer fires, with which delete flag. No
# mutation, no report rendering — the result lands in ORBIT_VERDICT /
# ORBIT_V_FLAG / ORBIT_V_RETRY / ORBIT_V_LABEL / ORBIT_V_NOTE. Set-global
# style (not stdout capture) so the layer-1 PR cache survives the call —
# $() and <(...) subshells would lose it. Layer 1 (recorded PR covers this
# branch) reads the run-scoped ORBIT_PR_URLS — a ghost has no recorded
# URLs, so it never fires for ghosts. Execution and rendering live in
# orbit_branch_protection_delete.
orbit_branch_verdict() {
  local main_repo="$1" branch="$2" force_flag="$3"
  ORBIT_VERDICT="" ORBIT_V_FLAG="" ORBIT_V_RETRY=0 ORBIT_V_LABEL="" ORBIT_V_NOTE=""

  if [ "$force_flag" = "1" ]; then
    ORBIT_VERDICT=delete ORBIT_V_FLAG=-D ORBIT_V_LABEL=force
    return 0
  fi

  # Layer 1: a recorded, repo-matched, merged PR whose head covers the tip.
  if [ -n "$ORBIT_PR_URLS" ] && orbit_pr_covers_branch "$main_repo" "$branch"; then
    ORBIT_VERDICT=delete ORBIT_V_FLAG=-D ORBIT_V_LABEL="PR merged"
    return 0
  fi

  # Layer 2: merged into origin/<default-branch>
  local default_branch
  default_branch=$(orbit_default_branch "$main_repo" 2>/dev/null || true)
  if [ -n "$default_branch" ] && git -C "$main_repo" merge-base --is-ancestor "$branch" "origin/$default_branch" 2>/dev/null; then
    ORBIT_VERDICT=delete ORBIT_V_FLAG=-d ORBIT_V_RETRY=1 ORBIT_V_LABEL=merged
    return 0
  fi

  # Layer 3: content proven upstream — the squash/rebase case, where layer 2
  # can never fire. A definitive tree-level answer (merge-tree clean) is a
  # delete verdict; only when merge-tree cannot answer does the branch stay,
  # and a cherry-positive demotes to a report hint on the keep line.
  local evidence=""
  if [ -n "$default_branch" ]; then
    if evidence=$(orbit_branch_content_upstream "$main_repo" "$branch" "origin/$default_branch"); then
      if [ "$evidence" = "tree" ]; then
        ORBIT_VERDICT=delete ORBIT_V_FLAG=-D ORBIT_V_LABEL="content upstream"
        return 0
      fi
      ORBIT_V_NOTE=" (content reads as already upstream — squash/rebase merge? clean up: git -C \".repos/$(basename "$main_repo")\" branch -D $(printf '%q' "$branch"))"
    else
      ORBIT_V_NOTE=" — review: git -C \".repos/$(basename "$main_repo")\" log $(printf '%q' "origin/$default_branch..$branch")"
    fi
  fi
  ORBIT_VERDICT=keep
}

orbit_branch_protection_delete() {
  local main_repo="$1" branch="$2" force_flag="$3" dry_run_flag="$4" quiet_keep="${5:-0}"
  # Returns 0 if the branch was (or would be) deleted, 1 if skipped.
  # quiet_keep=1 (ghost groups): a real-run keep is reported by the caller in
  # the group's stdout block — the stderr diagnostic would just duplicate it.
  orbit_branch_verdict "$main_repo" "$branch" "$force_flag"

  if [ "$ORBIT_VERDICT" = "keep" ]; then
    if [ "$dry_run_flag" = "1" ]; then
      printf '    would keep unmerged branch: %s%s\n' "$branch" "$ORBIT_V_NOTE"
    elif [ "$quiet_keep" = "0" ]; then
      printf 'orbit: keeping unmerged branch: %s%s\n' "$branch" "$ORBIT_V_NOTE" >&2
    fi
    return 1
  fi

  if [ "$dry_run_flag" = "1" ]; then
    if [ "$ORBIT_V_LABEL" = "force" ]; then
      printf '    would force-delete branch: %s\n' "$branch"
    else
      printf '    would delete branch (%s): %s\n' "$ORBIT_V_LABEL" "$branch"
    fi
    return 0
  fi

  # The report owns the deletion line (git's own chatter is suppressed), so it
  # carries the one informative piece of git's line: the commit — the recovery
  # handle (the branch's own reflog dies with it; the SHA is what remains).
  # Resolve before the delete; omit the suffix if unresolvable.
  local sha=""
  sha=$(git -C "$main_repo" rev-parse --short "$branch" 2>/dev/null || true)
  [ -n "$sha" ] && sha=" (was $sha)"
  if orbit_branch_delete "$main_repo" "$branch" "$ORBIT_V_FLAG" "$ORBIT_V_RETRY"; then
    printf '    deleted branch (%s): %s%s\n' "$ORBIT_V_LABEL" "$branch" "$sha"
    return 0
  fi
  return 1
}

# --- Residue: ghost workspaces and untraceable branches ---
# Candidates derive only from the structural truth sources (git refs +
# filesystem), never from disposable metadata: a ghost workspace is named by
# its scoped branches (<prefix>/<ws>/…), a raw branch's traceability by
# refs/remotes and the worktree list.

# for-each-ref wrapper for residue scans: a git error (corrupt repo) warns
# instead of reading as "no branches" — a blind scan must never pass as empty.
orbit_for_each_ref() {
  local out
  if ! out=$(git -C "$1" for-each-ref --format='%(refname:short)' "$2" 2>/dev/null); then
    printf 'orbit: %s: cannot scan branches — residue check skipped for this repo\n' "$(basename "$1")" >&2
    return 0
  fi
  printf '%s\n' "$out"
}

# Print names of workspaces whose directory is gone but which still have
# scoped branches in some pool repo ("ghosts"). Caller dedups (sort -u).
orbit_prune_ghost_workspaces() {
  local root="$1" prefix repo_dir br ws
  prefix=$(orbit_require_prefix) || return 1
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir/.git" ] || continue
    while IFS= read -r br; do
      [ -n "$br" ] || continue
      case "$br" in "$prefix"/*/*) ;; *) continue ;; esac   # full shape only; a single-segment name is raw residue
      ws="${br#"$prefix"/}"
      ws="${ws%%/*}"
      [ -n "$ws" ] || continue
      orbit_reserved_workspace "$ws" && continue
      [ -d "$root/$ws" ] || printf '%s\n' "$ws"
    done < <(orbit_for_each_ref "$repo_dir" "refs/heads/$prefix/")
  done
}

# Process one ghost workspace: every scoped branch through the git verdict
# layers (2 and 3 — a ghost carries no recorded PRs, so layer 1 never fires),
# per-item: merged → deleted, unmerged → kept and reported, --force → force
# deleted. The group is a reconciliation report, not a refusal: kept lines
# are stdout report content in both modes, adjacent to the deletion lines.
# Kept branches feed the closing block via ORBIT_KEPT_WS. Returns 0 when any
# branch was found.
orbit_prune_ghost_group() {
  local root="$1" ws="$2" force="$3" dry_run="$4" targeted="$5"
  local prefix repo_dir repo_name branch found=0 g_del=0 g_keep=0 conv_out=""
  prefix=$(orbit_require_prefix) || return 1
  # A ghost carries no recorded PRs (its .orbit died with the directory) —
  # layer 1 never fires here, whatever a live candidate left in the variable.
  ORBIT_PR_URLS=""
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir/.git" ] || continue
    repo_name=$(basename "$repo_dir")
    local branches=()
    while IFS= read -r branch; do
      [ -n "$branch" ] && branches+=("$branch")
    done < <(orbit_for_each_ref "$repo_dir" "refs/heads/$prefix/$ws/")
    [ "${#branches[@]}" -gt 0 ] || continue
    if [ "$found" = "0" ]; then
      if [ "$dry_run" = "1" ]; then printf 'would prune: %s (residue)\n' "$ws"
      else printf 'pruning: %s (residue)\n' "$ws"; fi
      found=1
    fi
    local repo_out="" bline
    for branch in "${branches[@]}"; do
      if bline=$(orbit_branch_protection_delete "$repo_dir" "$branch" "$force" "$dry_run" 1); then
        g_del=$((g_del + 1))
        repo_out="$repo_out$bline
"
      else
        # Distinguish a verdict-keep from a deletion FAILURE (git refused —
        # its own first line already went to stderr): re-run the pure verdict
        # in this shell and classify. A failure is a step failure — it
        # latches the run's exit code, prints no "kept" line, and never feeds
        # the closing block (its --force suggestion would just fail again).
        if [ "$dry_run" = "0" ]; then
          orbit_branch_verdict "$repo_dir" "$branch" "$force"
        fi
        if [ "$dry_run" = "1" ] || [ "$ORBIT_VERDICT" = "keep" ]; then
          g_keep=$((g_keep + 1))
          # A ghost's kept line is report content in BOTH modes.
          if [ "$dry_run" = "1" ]; then
            repo_out="$repo_out$bline
"
          else
            repo_out="$repo_out    kept branch (unmerged): $branch$ORBIT_V_NOTE
"
          fi
          # Newline-separated list + literal match: workspace names can contain
          # glob characters — a space-joined list would word-split AND pathname-
          # expand at the project root, retargeting the closing block's
          # suggestion at a DIFFERENT workspace.
          if ! printf '%s\n' "$ORBIT_KEPT_WS" | grep -Fxq -- "$ws"; then
            ORBIT_KEPT_WS="${ORBIT_KEPT_WS:+$ORBIT_KEPT_WS
}$ws"
          fi
        else
          ORBIT_PRUNE_FAILED=1
        fi
      fi
    done
    [ -n "$repo_out" ] && printf '  %s:\n%s' "$repo_name" "$repo_out"
    # Config maintenance + the fetch discipline run here only for a TARGETED
    # run — on enumeration the closing sweep covers every pool. Maintenance
    # would-lines report under the pool-maintenance section, never inside the
    # workspace block: pool accounts are not the workspace's cleanup.
    # Real-run convergence reports on stderr.
    if [ "$targeted" = "1" ]; then
      local g_rlines="" g_r g_bk
      while IFS= read -r g_r; do
        if [ -n "$g_r" ]; then g_rlines="$g_rlines    $g_r
"; fi
      done < <(orbit_maintain_pool_config "$repo_dir" "$root" "$dry_run")
      if [ "$dry_run" = "0" ]; then
        orbit_touchpoint_fetch "$repo_dir" || true
        if g_bk=$(orbit_prune_repo_maintenance "$repo_dir" "$dry_run"); then
          g_rlines="$g_rlines    $g_bk
"
        fi
      fi
      [ -n "$g_rlines" ] && conv_out="$conv_out  $repo_name:
$g_rlines"
    fi
  done
  if [ "$found" = "1" ] && [ "$dry_run" = "0" ]; then
    printf 'pruned: %s (residue) (%d %s deleted, %d kept)\n' \
      "$ws" "$g_del" "$(orbit_plural "$g_del" branch branches)" "$g_keep"
  fi
  # Pool accounts get their own section, after the workspace report closes.
  [ -n "$conv_out" ] && printf 'pool maintenance:\n%s' "$conv_out"
  [ "$found" = "1" ]
}

# Report branches that cannot be traced to anything: not scoped-shaped, no
# remote copy (no origin/<name>), not checked out in any worktree. These are
# never deleted by orbit — collected here (grouped by repo, in pool order) and
# rendered by the closing block, for the human operator to dispose of.
# Sets ORBIT_RAW_COUNT and fills ORBIT_RAW_ENTRIES / ORBIT_RAW_DELETES.
orbit_prune_raw_residue() {
  local root="$1" dry_run="$2"
  local prefix repo_dir repo_name branch default_branch
  prefix=$(orbit_require_prefix) || return 1
  for repo_dir in "$root/.repos"/*/; do
    [ -d "$repo_dir/.git" ] || continue
    repo_name=$(basename "$repo_dir")
    local checked_out=" " wt_line
    while IFS= read -r wt_line; do
      case "$wt_line" in
        branch\ refs/heads/*) checked_out="$checked_out${wt_line#branch refs/heads/} " ;;
      esac
    done < <(git -C "$repo_dir" worktree list --porcelain 2>/dev/null || true)
    default_branch=$(orbit_default_branch "$repo_dir" 2>/dev/null || true)
    local repo_group=""
    while IFS= read -r branch; do
      [ -n "$branch" ] || continue
      case "$branch" in "$prefix/"*/*) continue ;; esac        # scoped → residue path
      case "$checked_out" in *" $branch "*) continue ;; esac   # live in a worktree
      # Remote copy = traceable: same-name ref, or a configured upstream under
      # another name. Read branch.<name>.merge directly and map by convention
      # (refs/heads/X → refs/remotes/<remote>/X) rather than @{upstream}
      # resolution — the convention works under any fetch-refspec layout,
      # including user-narrowed ones (git.fetchAllBranches=once/never pools).
      git -C "$repo_dir" rev-parse --verify --quiet "origin/$branch" >/dev/null 2>&1 && continue
      local merge_ref remote_short
      merge_ref=$(git -C "$repo_dir" config --get "branch.$branch.merge" 2>/dev/null || true)
      if [ -n "$merge_ref" ]; then
        remote_short="${merge_ref#refs/heads/}"
        git -C "$repo_dir" rev-parse --verify --quiet "origin/$remote_short" >/dev/null 2>&1 && continue
      fi
      local status_word="unknown" review=""
      if [ -n "$default_branch" ]; then
        status_word="unmerged"
        if git -C "$repo_dir" merge-base --is-ancestor "$branch" "origin/$default_branch" 2>/dev/null; then
          status_word="merged"
        else
          review=" — review: git -C \".repos/$repo_name\" log $(printf '%q' "origin/$default_branch..$branch")"
        fi
      fi
      repo_group="$repo_group    $branch ($status_word)$review
"
      # Ref names may carry shell metacharacters (`;` `&&` `$()` …) — the
      # operator copy-pastes this, so quote it the way the replay does.
      ORBIT_RAW_DELETES="$ORBIT_RAW_DELETES  git -C \".repos/$repo_name\" branch -D $(printf '%q' "$branch")
"
      ORBIT_RAW_COUNT=$((ORBIT_RAW_COUNT + 1))
    done < <(orbit_for_each_ref "$repo_dir" refs/heads/)
    if [ -n "$repo_group" ]; then
      ORBIT_RAW_ENTRIES="$ORBIT_RAW_ENTRIES  $repo_name:
$repo_group"
    fi
  done
  [ "$ORBIT_RAW_COUNT" -gt 0 ]
}

# Maintenance self-heal for one pool repo, both kinds of registration whose
# subject no longer exists:
#   - stale worktree registrations — the path is GONE (a registration whose
#     path still exists is a damaged worktree: validation's job, never
#     auto-repaired — the registration is the only evidence of that state)
#   - orphan branch.<name>.* config sections whose branch no longer exists
#     (existence ≠ having a ref: an UNBORN branch — e.g. an empty repo's
#     orphan worktree — is alive while checked out in a NON-pool worktree,
#     ref or no ref; and the pool HEAD's target branch is always alive,
#     possibly unborn — its config is first-push routing, not residue)
# Neither touches an object or a file with content, so no --force. Prints one
# summary line when it repaired anything. --dry-run evaluates and stays
# silent (the line's exact counts add no plan value over the dry-run's other
# output).
orbit_prune_repo_maintenance() {
  local repo="$1" dry_run="$2" n_reg=0 n_cfg=0 line wt_path br
  # Porcelain prints PHYSICAL paths (macOS /var → /private/var); a logical
  # $repo would never match the pool's own worktree line (physical-vs-logical
  # mismatch lesson from the prune cwd-protection pitfall). Keep the logical
  # basename for display: callers print group headers from the un-resolved
  # path — a symlinked pool dir must not rename the line under its header.
  local display
  display=$(basename "$repo")
  repo=$(cd "$repo" 2>/dev/null && pwd -P) || return 1
  if [ "$dry_run" = "0" ]; then
    local porcelain checked_out=" " pool_wt=0 head_br
    # The pool HEAD's target branch is always protected below, ref or no ref:
    # its branch.<name>.* section is live first-push routing (e.g. an empty
    # repo's clone-written default), never residue. In non-empty repos this is
    # invisible — the ref check already keeps it. Premise: the pool's HEAD is
    # a symref. No orbit command ever detaches it (sync only fetches;
    # add/switch only touch worktrees) — if a future command detaches the pool
    # HEAD, this exemption silently no-ops (head_br comes out empty).
    head_br=$(git -C "$repo" symbolic-ref --short -q HEAD 2>/dev/null || true)
    porcelain=$(git -C "$repo" worktree list --porcelain 2>/dev/null || true)
    while IFS= read -r line; do
      case "$line" in
        worktree\ *)
          wt_path="${line#worktree }"
          pool_wt=0
          # The pool's own checkout is never stale, whatever the registry says.
          if [ "$wt_path" = "$repo" ]; then pool_wt=1; continue; fi
          [ -e "$wt_path" ] && continue
          if git -C "$repo" worktree remove --force "$wt_path" >/dev/null 2>&1; then
            n_reg=$((n_reg + 1))
          fi
          ;;
        branch\ refs/heads/*)
          # Porcelain groups the branch line under its worktree: the pool's own
          # checkout is infrastructure, not a user worktree — its (possibly
          # unborn) branch must not shield clone-written config residue.
          [ "$pool_wt" = "1" ] && continue
          checked_out="$checked_out${line#branch refs/heads/} " ;;
      esac
    done <<EOF
$porcelain
EOF
    while IFS= read -r line; do
      [ -n "$line" ] || continue
      # branch.<name>.<key>: the KEY is the last segment — strip it only.
      # Truncating at the first dot would orphan "feat.v2" forever.
      br="${line#branch.}"; br="${br%.*}"
      git -C "$repo" rev-parse --verify --quiet "refs/heads/$br" >/dev/null 2>&1 && continue
      # A branch checked out in a worktree is alive even without a ref (unborn)
      # — its upstream config is push routing in use, not an orphan.
      case "$checked_out" in *" $br "*) continue ;; esac
      # The pool HEAD's target branch (possibly unborn) — live first-push
      # routing, protected whether or not the repo is empty.
      [ -n "$head_br" ] && [ "$br" = "$head_br" ] && continue
      if git -C "$repo" config --remove-section "branch.$br" 2>/dev/null; then
        n_cfg=$((n_cfg + 1))
      fi
    done < <(git -C "$repo" config --get-regexp '^branch\..*\.' 2>/dev/null | cut -d' ' -f1 | sort -u || true)
  fi
  if [ "$n_reg" -gt 0 ] || [ "$n_cfg" -gt 0 ]; then
    printf '%s: pruned %d stale worktree registration(s), %d orphan branch config section(s)\n' \
      "$display" "$n_reg" "$n_cfg"
    return 0
  fi
  return 1
}

orbit_prune() {
  local older="" dry_run=0 force=0 target_ws=""
  local orig_args=("$@")

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --older) [ "$#" -ge 2 ] || orbit_fail "--older requires a duration"; older="$2"; shift 2 ;;
      --dry-run) dry_run=1; shift ;;
      --force) force=1; shift ;;
      -*) orbit_fail "unknown option: $1" ;;
      *) [ -z "$target_ws" ] || orbit_fail "unexpected argument: $1"; target_ws="$1"; shift ;;
    esac
  done

  local root
  root=$(orbit_require_root) || return 1

  # Prune is a root-level destructive operation: target-independent guard,
  # shared with the other root-scoped commands (see orbit_require_root_scope).
  orbit_require_root_scope "$root" "prune" "prune" ${orig_args[@]+"${orig_args[@]}"}

  local older_seconds=0
  if [ -n "$older" ]; then
    older_seconds=$(orbit_parse_duration "$older") || orbit_fail "invalid duration: $older"
  fi

  local now
  now=$(date +%s)

  # Run-scoped state: closing-block collectors, the layer-1 PR evidence cache
  # (each URL is one network call, queried once), and the failure latch (a
  # step that FAILED exits non-zero; a validation refusal does not).
  ORBIT_KEPT_WS="" ORBIT_RAW_COUNT=0 ORBIT_RAW_ENTRIES="" ORBIT_RAW_DELETES=""
  ORBIT_PR_URLS="" ORBIT_PR_CACHE="" ORBIT_PR_GH_BAD="" ORBIT_PRUNE_FAILED=""
  local had_failure=0 trash_entries=0

  # Opening sweep: whatever the trash holds is past the commit point —
  # definitionally garbage, resumed with no validation and no --force. This
  # also guarantees a later rename never collides with a same-named leftover.
  # --dry-run touches nothing and reports the sweep as a would-line.
  local trash="$root/.prune-trash"
  if [ -d "$trash" ]; then
    local t tname t_err t_cleared=0
    for t in "$trash"/*/; do
      [ -d "$t" ] || continue
      trash_entries=$((trash_entries + 1))
      if [ "$dry_run" = "0" ]; then
        if t_err=$(rm -rf "$t" 2>&1); then
          t_cleared=$((t_cleared + 1))
        else
          tname=$(basename "$t")
          printf 'orbit: %s: trash removal incomplete (%s) — left in .prune-trash, resumed on the next run\n' "$tname" "$t_err" >&2
          had_failure=1
        fi
      fi
    done
    if [ "$dry_run" = "1" ]; then
      [ "$trash_entries" -gt 0 ] && printf 'would clear %d interrupted deletion(s)\n' "$trash_entries"
    elif [ "$t_cleared" -gt 0 ]; then
      printf 'orbit: .prune-trash: cleared %d interrupted deletion(s)\n' "$t_cleared" >&2
    fi
  fi

  # Collect candidate workspaces
  local candidates=()
  for ws_dir in "$root"/*/; do
    [ -d "$ws_dir" ] || continue
    local ws_name
    ws_name=$(basename "$ws_dir")
    orbit_reserved_workspace "$ws_name" && continue

    # If specific workspace given, filter
    if [ -n "$target_ws" ] && [ "$ws_name" != "$target_ws" ]; then
      continue
    fi

    local orbit_file="$ws_dir/.orbit"
    local status_val
    status_val=$(git config --file "$orbit_file" --get workspace.status 2>/dev/null || true)
    [ "$status_val" = "done" ] || continue

    # --older check
    if [ "$older_seconds" -gt 0 ]; then
      local done_at
      done_at=$(git config --file "$orbit_file" --get workspace.done-at 2>/dev/null || true)
      if [ -z "$done_at" ]; then
        done_at=$(git config --file "$orbit_file" --get workspace.created 2>/dev/null || true)
      fi
      if [ -z "$done_at" ]; then
        done_at=$(stat -f %m "$ws_dir" 2>/dev/null || stat -c %Y "$ws_dir" 2>/dev/null || echo "$now")
      fi
      local age=$(( now - done_at ))
      [ "$age" -gt "$older_seconds" ] || continue
    fi

    candidates+=("$ws_name")
  done

  # Ghost workspaces: scoped branches whose workspace directory is already
  # reclaimed. A targeted run looks only at its own workspace's branches —
  # no global ghost scan, no raw report; enumeration scans everything.
  local ghost_ws=()
  if [ -n "$target_ws" ]; then
    # Same structural filter the enumeration path applies via
    # orbit_prune_ghost_workspaces: a reserved or slash-bearing name is not a
    # workspace, and "<ws>/<sub>" must not become a ref-pattern into a live one.
    orbit_reserved_workspace "$target_ws" \
      && orbit_fail "no such workspace: $target_ws"
    if [ ! -d "$root/$target_ws" ]; then
      local tg_prefix tg_repo tg_refs
      tg_prefix=$(orbit_require_prefix) || return 1
      for tg_repo in "$root/.repos"/*/; do
        [ -d "$tg_repo/.git" ] || continue
        # Capture, then test: piping for-each-ref into `grep -q` SIGPIPEs the
        # producer under pipefail once the ref list outgrows the pipe buffer,
        # and the ghost is missed exactly when the residue pile is biggest.
        if ! tg_refs=$(git -C "$tg_repo" for-each-ref --count=1 --format='%(refname:short)' \
          "refs/heads/$tg_prefix/$target_ws/" 2>/dev/null); then
          printf 'orbit: %s: cannot scan branches — residue check skipped for this repo\n' "$(basename "$tg_repo")" >&2
          continue
        fi
        if [ -n "$tg_refs" ]; then
          ghost_ws+=("$target_ws")
          break
        fi
      done
    fi
  else
    while IFS= read -r g; do [ -n "$g" ] && ghost_ws+=("$g"); done \
      < <(orbit_prune_ghost_workspaces "$root" | sort -u)
  fi

  # Targeted refusal: three distinct facts, none naming a way forward — the
  # second is a recorded intent (never overridden), the third a lost cache
  # (rebuilt by `orbit done` inside the directory).
  if [ -n "$target_ws" ] && [ "${#candidates[@]}" -eq 0 ]; then
    local targeted_ghost=0 g
    for g in ${ghost_ws[@]+"${ghost_ws[@]}"}; do
      [ "$g" = "$target_ws" ] && targeted_ghost=1
    done
    if [ "$targeted_ghost" = "0" ]; then
      if [ -d "$root/$target_ws" ]; then
        local t_status="" t_rc=0
        if [ -f "$root/$target_ws/.orbit" ]; then
          # rc 1 = no status key (a recorded non-done intent); rc >1 = the
          # file itself is unreadable to git-config (a lost cache).
          t_status=$(git config --file "$root/$target_ws/.orbit" --get workspace.status 2>/dev/null) || t_rc=$?
        fi
        if [ ! -f "$root/$target_ws/.orbit" ] || [ "$t_rc" -gt 1 ]; then
          orbit_fail "$target_ws exists but workspace metadata is missing or unreadable"
        fi
        if [ "$t_status" = "done" ] && [ "$older_seconds" -gt 0 ]; then
          # done but filtered out by --older alone — state the age fact
          orbit_fail "$target_ws is marked done but not older than $older"
        fi
        orbit_fail "$target_ws exists but is not marked done"
      fi
      orbit_fail "no such workspace: $target_ws"
    fi
  fi

  for ws in ${candidates[@]+"${candidates[@]}"}; do
    local ws_dir="$root/$ws"
    local orbit_file="$ws_dir/.orbit"

    # Layer-1 evidence for this candidate: the recorded PR URLs. Newline-
    # joined and read with while-read — .orbit is agent-writable input, and
    # an unquoted `for url in $list` would pathname-expand glob characters
    # in a URL against the current directory.
    ORBIT_PR_URLS=""
    local url
    while IFS= read -r url; do
      [ -n "$url" ] || continue
      ORBIT_PR_URLS="$ORBIT_PR_URLS$url"$'\n'
    done < <(git config --file "$orbit_file" --get-all pr.url 2>/dev/null || true)

    # Workspace top-level enumeration: pool-backed worktrees (a .git *file*
    # with a pool counterpart) vs foreign repos (a .git *directory* — an
    # independent clone even when it sits under a pool repo's name; its
    # objects live in its own .git, so the removal below destroys history
    # that exists nowhere else). The scan is deliberately top-level: guard
    # scope is the workspace's direct children (see spec-lifecycle).
    local ws_repo_dirs=() foreign_repos=()
    for repo_dir in "$ws_dir"/*/; do
      [ -d "$repo_dir" ] || continue
      [ -d "$repo_dir/.git" ] || [ -f "$repo_dir/.git" ] || continue
      local repo_name
      repo_name=$(basename "$repo_dir")
      if [ -f "$repo_dir/.git" ] && [ -d "$root/.repos/$repo_name" ]; then
        ws_repo_dirs+=("$repo_dir")
      else
        foreign_repos+=("$repo_name")
      fi
    done

    # Branch collection is pool-driven: the union of refs/heads/<prefix>/<ws>/*
    # across pool repos, independent of which worktree directories still
    # exist (deriving the pool from the worktree path would drop branches
    # from collection after an interruption between D1 and D2 — manufacturing
    # a ghost). Entries are "<pool>\x1f<branch>" lines. A scan FAILURE is
    # fail-closed here: the live path must never read "cannot read" as "no
    # branches" — that is how all-or-nothing's premise (a complete branch
    # set) stays enforced.
    local ws_prefix
    ws_prefix=$(orbit_require_prefix) || return 1
    local br_entries="" pool_dir b scan_out scan_failed_repos=()
    for pool_dir in "$root/.repos"/*/; do
      [ -d "$pool_dir/.git" ] || continue
      if ! scan_out=$(git -C "$pool_dir" for-each-ref --format='%(refname:short)' "refs/heads/$ws_prefix/$ws/" 2>/dev/null); then
        scan_failed_repos+=("$(basename "$pool_dir")")
        continue
      fi
      while IFS= read -r b; do
        [ -n "$b" ] || continue
        br_entries="$br_entries${pool_dir%/}"$'\x1f'"$b"$'\n'
      done <<< "$scan_out"
    done

    # --- Validation: a pure function of structural evidence --------------
    # Every guard that reads workspace-side evidence fails closed on absence.
    # The data guards run in BOTH modes — --force releases them, but only
    # after announcing what it discards.
    local skip_reasons="" kept_lines="" blocked=0
    local dirty_repos=() damaged_repos=() jotted_repos=()

    # Uncommitted changes: worktree removal nukes working-tree state
    # outright, so an unreadable `git status` counts as dirty — "cannot
    # tell" is never "clean".
    for repo_dir in ${ws_repo_dirs[@]+"${ws_repo_dirs[@]}"}; do
      local st_out st_rc=0
      st_out=$(git -C "$repo_dir" status --porcelain 2>/dev/null) || st_rc=$?
      if [ "$st_rc" -ne 0 ] || [ -n "$st_out" ]; then
        dirty_repos+=("$(basename "$repo_dir")")
      fi
    done

    # Damaged worktrees: the pool still registers a direct child as a
    # worktree, but its gitdir pointer is unusable — every "is this a git
    # repo" test fails on it, so the dirty guard would never see it. The
    # registration names the path; prune does not repair it (a worktree
    # orbit cannot read is one it must not delete). git reports physical
    # paths, so the comparison is done on the physical workspace path.
    local wt_line wt_path wt_name ws_dir_phys
    ws_dir_phys=$(cd "$ws_dir" 2>/dev/null && pwd -P || printf '%s' "$ws_dir")
    local damaged_pairs=""
    for pool_dir in "$root/.repos"/*/; do
      [ -d "$pool_dir/.git" ] || continue
      while IFS= read -r wt_line; do
        case "$wt_line" in
          worktree\ *)
            wt_path="${wt_line#worktree }"
            case "$wt_path" in
              "$ws_dir_phys"/*)
                wt_name="${wt_path#"$ws_dir_phys"/}"
                case "$wt_name" in */*) continue ;; esac   # direct children only
                # path gone = stale registration (maintenance's job, below);
                # damaged = the path EXISTS but its gitdir pointer is dead
                [ -e "$wt_path" ] || continue
                if ! git -C "$wt_path" rev-parse --git-dir >/dev/null 2>&1; then
                  damaged_repos+=("$(basename "$pool_dir")")
                  damaged_pairs="$damaged_pairs$(basename "$pool_dir")"$'\x1f'"$wt_path"$'\n'
                fi
                ;;
            esac
            ;;
        esac
      done < <(git -C "$pool_dir" worktree list --porcelain 2>/dev/null || true)
    done

    # Unmerged jots: they live in the workspace .orbit, which the removal
    # takes with it. done only warns once; this is the last checkpoint.
    local jot_repo jot_count
    while IFS= read -r jot_repo; do
      [ -n "$jot_repo" ] || continue
      jot_count=$(git config --file "$orbit_file" --get-all "jot.$jot_repo.entry" 2>/dev/null | grep -c . || true)
      [ "${jot_count:-0}" -gt 0 ] || continue
      jotted_repos+=("$jot_repo ($jot_count)")
    done < <(git config --file "$orbit_file" --name-only --get-regexp '^jot\..*\.entry$' 2>/dev/null | sed 's/^jot\.//; s/\.entry$//' | sort -u || true)

    [ "${#dirty_repos[@]}" -gt 0 ] && skip_reasons="uncommitted changes in: ${dirty_repos[*]}"
    if [ "${#foreign_repos[@]}" -gt 0 ]; then
      [ -n "$skip_reasons" ] && skip_reasons="$skip_reasons; "
      skip_reasons="${skip_reasons}git repos not from the pool: ${foreign_repos[*]}"
    fi
    if [ "${#jotted_repos[@]}" -gt 0 ]; then
      [ -n "$skip_reasons" ] && skip_reasons="$skip_reasons; "
      skip_reasons="${skip_reasons}unmerged jots in: ${jotted_repos[*]}"
    fi
    local dmg
    for dmg in ${damaged_repos[@]+"${damaged_repos[@]}"}; do
      [ -n "$skip_reasons" ] && skip_reasons="$skip_reasons; "
      skip_reasons="${skip_reasons}damaged worktree in $dmg (gitdir pointer unusable, pool registration intact) — content may be un-persisted"
    done

    # A scan failure blocks in BOTH modes, ahead of everything else:
    # --force accepts consequences, it cannot supply the branch set git
    # failed to enumerate — and the verdicts below would run on a partial
    # set. Same exit class as a validation refusal (nothing was attempted).
    # Never feeds the closing block: its --force suggestion cannot help here.
    if [ "${#scan_failed_repos[@]}" -gt 0 ]; then
      if [ "$dry_run" = "1" ]; then
        printf 'would skip: %s (cannot scan branches in: %s)\n' "$ws" "${scan_failed_repos[*]}"
      else
        printf 'orbit: skipping %s: cannot scan branches in: %s\n' "$ws" "${scan_failed_repos[*]}" >&2
      fi
      continue
    fi

    if [ "$force" = "1" ] && [ "$dry_run" = "0" ]; then
      # The two steps with no recovery path are announced before the act —
      # statements of consequence, not ways around a refusal.
      [ "${#dirty_repos[@]}" -gt 0 ] && \
        printf 'orbit: %s: --force discards un-persisted work in %s — this cannot be undone\n' "$ws" "${dirty_repos[*]}" >&2
      for dmg in ${damaged_repos[@]+"${damaged_repos[@]}"}; do
        printf 'orbit: %s: --force removes %s whose state cannot be read — content may be un-persisted, this cannot be undone\n' "$ws" "$dmg" >&2
      done
    elif [ "$force" = "0" ]; then
      # Branch verdicts: the whole set is verdicted before any mutation, and
      # a kept branch blocks the workspace exactly like a data-guard reason.
      # Skipped entirely when a data guard already blocks — a refused
      # workspace must not pay for layer-1 network calls. Direct calls (no
      # subshell) so the PR-evidence cache persists.
      local be_line be_pool be_branch
      if [ -z "$skip_reasons" ]; then
        while IFS= read -r be_line; do
          [ -n "$be_line" ] || continue
          be_pool="${be_line%%$'\x1f'*}"; be_branch="${be_line#*$'\x1f'}"
          orbit_branch_verdict "$be_pool" "$be_branch" 0
          if [ "$ORBIT_VERDICT" = "keep" ]; then
            kept_lines="${kept_lines}keeping unmerged branch: $be_branch$ORBIT_V_NOTE
"
          fi
        done <<EOF
$br_entries
EOF
      fi
    fi
    if [ "$force" = "0" ] && { [ -n "$skip_reasons" ] || [ -n "$kept_lines" ]; }; then blocked=1; fi

    # All-or-nothing: any blocker means zero mutation, all reasons reported
    # together — one skip line joins the data-guard reasons, each kept branch
    # adds its own review/hint line. Workspaces block independently.
    if [ "$blocked" = "1" ]; then
      if ! printf '%s\n' "$ORBIT_KEPT_WS" | grep -Fxq -- "$ws"; then
        ORBIT_KEPT_WS="${ORBIT_KEPT_WS:+$ORBIT_KEPT_WS
}$ws"
      fi
      if [ "$dry_run" = "1" ]; then
        [ -n "$skip_reasons" ] && printf 'would skip: %s (%s)\n' "$ws" "$skip_reasons"
        printf '%s' "$kept_lines"
      else
        [ -n "$skip_reasons" ] && printf 'orbit: skipping %s: %s\n' "$ws" "$skip_reasons" >&2
        printf '%s' "$kept_lines" | sed 's/^/orbit: /' >&2
      fi
      continue
    fi

    local n_deleted=0 n_worktrees=0 d_failed=0

    if [ "$dry_run" = "1" ]; then
      printf 'would prune: %s (%d %s)\n' "$ws" "${#ws_repo_dirs[@]}" "$(orbit_plural "${#ws_repo_dirs[@]}" worktree worktrees)"
    else
      printf 'pruning: %s (%d %s)\n' "$ws" "${#ws_repo_dirs[@]}" "$(orbit_plural "${#ws_repo_dirs[@]}" worktree worktrees)"
    fi

    if [ "${#ws_repo_dirs[@]}" -eq 0 ]; then
      printf '  (no worktrees)\n'
    fi

    # D1, damaged worktrees under --force, FIRST: git cannot remove a
    # worktree whose gitdir is unreadable ("validation failed" even with
    # -f -f), so a garbage/truncated pointer sitting in ws_repo_dirs would
    # die in the ordinary loop below. `worktree repair` re-links the .git
    # pointer (best-effort), then the ordinary remove works. Still failing →
    # the whole workspace is kept.
    local wt_err="" dmg_done_paths=""
    if [ "$force" = "1" ] && [ "$dry_run" = "0" ] && [ -n "$damaged_pairs" ]; then
      local dp_line dp_pool dp_path
      while IFS= read -r dp_line; do
        [ -n "$dp_line" ] || continue
        dp_pool="${dp_line%%$'\x1f'*}"; dp_path="${dp_line#*$'\x1f'}"
        git -C "$root/.repos/$dp_pool" worktree repair "$dp_path" >/dev/null 2>&1 || true
        if ! wt_err=$(git -C "$root/.repos/$dp_pool" worktree remove --force "$dp_path" 2>&1 >/dev/null); then
          printf 'orbit: skipping %s: worktree removal failed in %s (%s) — workspace kept\n' "$ws" "$dp_pool" "$(printf '%s\n' "$wt_err" | head -1)" >&2
          d_failed=1 had_failure=1
          break
        fi
        dmg_done_paths="$dmg_done_paths$dp_path"$'\n'
        n_worktrees=$((n_worktrees + 1))
      done <<EOF
$damaged_pairs
EOF
      [ "$d_failed" = "1" ] && continue
    fi

    # D1: worktree remove (E3+E4 go together). "Not a working tree" (never
    # registered) leaves nothing git-side, and the removal below is the
    # complete cleanup. Any OTHER failure (locked, IO) means git still
    # tracks this directory — deleting it would leave a registration pointing
    # at a vanished path, and every later deletion of that branch would
    # refuse ("used by worktree at <gone path>") — so the whole workspace is
    # kept. Directory removal runs only when git has no stake in the outcome.
    for repo_dir in ${ws_repo_dirs[@]+"${ws_repo_dirs[@]}"}; do
      local repo_name
      repo_name=$(basename "$repo_dir")
      local main_repo="$root/.repos/$repo_name"
      if [ "$dry_run" = "0" ]; then
        # damaged worktrees were removed above (their directory went with
        # the registration) — never re-attempt them here. The damaged list
        # holds physical paths (git porcelain), so compare on the physical
        # workspace path.
        if printf '%s\n' "$dmg_done_paths" | grep -Fxq -- "$ws_dir_phys/$repo_name"; then
          continue
        fi
        if ! wt_err=$(git -C "$main_repo" worktree remove "$repo_dir" --force 2>&1 >/dev/null); then
          case "$wt_err" in
            *"is not a working tree"*)
              printf 'orbit: %s: worktree not registered to the pool repo; left to directory removal\n' "$repo_name" >&2
              continue
              ;;
            *)
              printf 'orbit: skipping %s: worktree removal failed in %s (%s) — workspace kept\n' "$ws" "$repo_name" "$(printf '%s\n' "$wt_err" | head -1)" >&2
              d_failed=1 had_failure=1
              break
              ;;
          esac
        fi
      fi
      n_worktrees=$((n_worktrees + 1))
    done
    [ "$d_failed" = "1" ] && continue

    # D2: branch delete (E5; git drops E6 along with the branch). The set is
    # the pool-driven collection from validation — grouped by repo for the
    # report. A git refusal keeps the whole workspace (no rename); branches
    # already deleted stay deleted and the next run resumes.
    local repo_out="" cur_repo="" bline
    while IFS= read -r be_line; do
      [ -n "$be_line" ] || continue
      be_pool="${be_line%%$'\x1f'*}"; be_branch="${be_line#*$'\x1f'}"
      if [ "$(basename "$be_pool")" != "$cur_repo" ]; then
        [ -n "$repo_out" ] && printf '  %s:\n%s' "$cur_repo" "$repo_out"
        repo_out=""
        cur_repo="$(basename "$be_pool")"
      fi
      if bline=$(orbit_branch_protection_delete "$be_pool" "$be_branch" "$force" "$dry_run"); then
        n_deleted=$((n_deleted + 1))
        repo_out="$repo_out$bline
"
      else
        # git's refusal (its own first line) already went to stderr. A dry-run
        # never gets here: validation already blocked the workspace.
        d_failed=1
        [ "$dry_run" = "0" ] && had_failure=1
        break
      fi
    done <<EOF
$br_entries
EOF
    [ -n "$repo_out" ] && printf '  %s:\n%s' "$cur_repo" "$repo_out"
    [ "$d_failed" = "1" ] && continue

    # D3: convergence — maintenance self-heal, fetch-config maintenance, and
    # naming branches shaped like this workspace's but outside the configured
    # prefix (raw-mode, or born under another prefix — not orbit's to delete;
    # the branch names in git are the recoverable record). Involved repos =
    # pool worktrees in the directory + branch-holding pools. (No fetch here:
    # this workspace's pools get theirs at the targeted ghost pass or the
    # closing sweep.)
    local involved=" " inv_pool inv_list="" rlines rline lb
    for repo_dir in ${ws_repo_dirs[@]+"${ws_repo_dirs[@]}"}; do
      inv_list="$inv_list$root/.repos/$(basename "$repo_dir")"$'\n'
    done
    while IFS= read -r be_line; do
      if [ -n "$be_line" ]; then inv_list="$inv_list${be_line%%$'\x1f'*}"$'\n'; fi
    done <<EOF
$br_entries
EOF
    while IFS= read -r inv_pool; do
      [ -n "$inv_pool" ] || continue
      [ -d "$inv_pool/.git" ] || continue
      case "$involved" in *" $inv_pool "*) continue ;; esac
      involved="$involved$inv_pool "
      rlines=""
      while IFS= read -r rline; do
        if [ -n "$rline" ]; then rlines="$rlines    $rline
"; fi
      done < <(orbit_maintain_pool_config "$inv_pool" "$root" "$dry_run")
      if rline=$(orbit_prune_repo_maintenance "$inv_pool" "$dry_run"); then
        rlines="$rlines    $rline
"
      fi
      local left_behind=()
      while IFS= read -r lb; do
        [ -n "$lb" ] || continue
        case "$lb" in
          "$ws_prefix/$ws/"*) continue ;;
          */"$ws"/*) left_behind+=("$lb") ;;
        esac
      done < <(git -C "$inv_pool" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null || true)
      if [ "${#left_behind[@]}" -gt 0 ]; then
        if [ "$dry_run" = "1" ]; then
          rlines="$rlines    would leave branch outside branch.prefix: ${left_behind[*]}
"
        else
          printf 'orbit: %s: left branch outside branch.prefix: %s\n' "$(basename "$inv_pool")" "${left_behind[*]}" >&2
        fi
      fi
      [ -n "$rlines" ] && printf '  %s:\n%s' "$(basename "$inv_pool")" "$rlines"
      true
    done <<EOF
$inv_list
EOF

    # D4a: the atomic rename into the trash — the only directory-level commit
    # point (a mount-point workspace fails here with EXDEV and stays in
    # place). The entry name carries the pid so it can never collide with a
    # leftover the opening sweep failed to clear (a plain <ws> name would
    # otherwise NEST inside it). D4b: unordered deletion; a failure is
    # reported, exits non-zero, and is resumed by the next run's sweep.
    if [ "$dry_run" = "1" ]; then
      printf 'would remove workspace directory (via .prune-trash)\n'
    else
      [ -d "$trash" ] || mkdir -p "$trash"
      local mv_err rm_err trash_name="$ws.$$"
      if ! mv_err=$(mv "$ws_dir" "$trash/$trash_name" 2>&1); then
        printf 'orbit: skipping %s: rename to .prune-trash failed (%s) — workspace kept\n' "$ws" "$mv_err" >&2
        had_failure=1
        continue
      fi
      if ! rm_err=$(rm -rf "${trash:?}/${trash_name:?}" 2>&1); then
        printf 'orbit: %s: trash removal incomplete (%s) — left in .prune-trash, resumed on the next run\n' "$ws" "$rm_err" >&2
        had_failure=1
        continue
      fi
      printf 'pruned: %s (%d %s removed, %d %s deleted)\n' \
        "$ws" "$n_worktrees" "$(orbit_plural "$n_worktrees" worktree worktrees)" \
        "$n_deleted" "$(orbit_plural "$n_deleted" branch branches)"
    fi
  done

  # Ghost residue: scoped branches whose workspace directory is gone. Same
  # pipeline in dir-absent form; a targeted run only touches its ghost.
  for g in ${ghost_ws[@]+"${ghost_ws[@]}"}; do
    if [ -n "$target_ws" ] && [ "$g" != "$target_ws" ]; then continue; fi
    # `|| true`: enumeration and this scan share the shape predicate, so an
    # empty group can only mean the branch vanished mid-run — never abort.
    if [ -n "$target_ws" ]; then
      orbit_prune_ghost_group "$root" "$g" "$force" "$dry_run" 1 || true
    else
      orbit_prune_ghost_group "$root" "$g" "$force" "$dry_run" 0 || true
    fi
  done

  # Untraceable raw branches + pool maintenance: enumeration only (a targeted
  # run is focused). The fetch discipline runs FIRST so the residue scan
  # reads refs already converged by this touchpoint (tracked-but-gone refs
  # cleaned by the conditional `git remote prune origin`); config maintenance
  # runs on every prune path — a run with no live candidate still converges a
  # non-standard pool. The sweep prints under its OWN section header:
  # same-indentation repo groups would otherwise read as belonging to the
  # last workspace block.
  if [ -z "$target_ws" ]; then
    local bk_pool bk_line bk_out bk_r bk_header=0
    for bk_pool in "$root/.repos"/*/; do
      [ -d "$bk_pool/.git" ] || continue
      bk_out=""
      while IFS= read -r bk_r; do
        if [ -n "$bk_r" ]; then bk_out="$bk_out    $bk_r
"; fi
      done < <(orbit_maintain_pool_config "${bk_pool%/}" "$root" "$dry_run")
      if [ "$dry_run" = "0" ]; then
        orbit_touchpoint_fetch "${bk_pool%/}" || true
      fi
      if bk_line=$(orbit_prune_repo_maintenance "${bk_pool%/}" "$dry_run"); then
        bk_out="$bk_out    $bk_line
"
      fi
      if [ -n "$bk_out" ]; then
        if [ "$bk_header" = "0" ]; then printf 'pool maintenance:\n'; bk_header=1; fi
        printf '  %s:\n%s' "$(basename "$bk_pool")" "$bk_out"
      fi
    done
    orbit_prune_raw_residue "$root" "$dry_run" || true
  fi

  # Closing block, ordered: kept-workspace summary → raw report (grouped by
  # repo) → ONE confirm-useless caveat → force-delete suggestions, scoped
  # (orbit prune <ws> --force) before raw (native branch -D). The `orbit:`
  # prefix marks the diagnostics channel — real run only; in dry-run the
  # whole block is report content on stdout, unprefixed.
  if [ -n "$ORBIT_KEPT_WS" ] || [ "$ORBIT_RAW_COUNT" -gt 0 ]; then
    local pfx="orbit: "
    [ "$dry_run" = "1" ] && pfx=""
    {
      if [ -n "$ORBIT_KEPT_WS" ]; then
        local ws_display="" w
        while IFS= read -r w; do
          [ -n "$w" ] || continue
          ws_display="${ws_display:+$ws_display, }$w"
        done <<EOF
$ORBIT_KEPT_WS
EOF
        if [ "$dry_run" = "1" ]; then
          printf 'would keep workspaces: %s\n' "$ws_display"
        else
          printf 'orbit: workspaces kept: %s\n' "$ws_display"
        fi
      fi
      if [ "$ORBIT_RAW_COUNT" -gt 0 ]; then
        printf '%suntraceable branches (raw, no remote, no workspace) — human disposal:\n' "$pfx"
        printf '%s' "$ORBIT_RAW_ENTRIES"
      fi
      printf '%safter confirming the content is no longer needed (nothing un-persisted would be lost), force-delete:\n' "$pfx"
      while IFS= read -r g; do
        [ -n "$g" ] || continue
        printf '  orbit prune %q --force\n' "$g"
      done <<EOF
$ORBIT_KEPT_WS
EOF
      printf '%s' "$ORBIT_RAW_DELETES"
    } | { if [ "$dry_run" = "1" ]; then cat; else cat >&2; fi }
  fi

  if [ "${#candidates[@]}" -eq 0 ] && [ "${#ghost_ws[@]}" -eq 0 ] && [ "$ORBIT_RAW_COUNT" -eq 0 ] && [ "$trash_entries" -eq 0 ]; then
    printf 'nothing to prune\n'
  fi

  # Closing self-clean: succeeds only when empty, so it is self-guarding; a
  # failure is silent (a failed deletion was already reported at its step).
  rmdir "$trash" 2>/dev/null || true

  # Exit status: a validation refusal is expected operation (exit 0); a step
  # that FAILED — worktree removal, branch deletion (live or ghost), rename,
  # trash removal — exits non-zero.
  if [ "$had_failure" = "1" ] || [ "$ORBIT_PRUNE_FAILED" = "1" ]; then return 1; fi
  return 0
}

# --- Doctor ---

orbit_doctor() {
  local all_ok=1

  printf 'Orbit Environment Diagnostics\n'
  printf '================================\n'
  printf 'orbit %s\n\n' "$ORBIT_VERSION"

  # 1. git version check (≥ 2.20)
  if command -v git >/dev/null 2>&1; then
    local git_ver
    git_ver=$(git --version | awk '{print $3}')
    if [ "$(printf '%s\n' "2.20" "$git_ver" | sort -V | head -n1)" = "2.20" ]; then
      printf '[OK]   git %s\n' "$git_ver"
    else
      printf '[FAIL] git %s (need >= 2.20)\n' "$git_ver"
      all_ok=0
    fi
  else
    printf '[FAIL] git not found\n'
    all_ok=0
  fi

  if command -v git >/dev/null 2>&1 && ! orbit_git_supports_orphan_worktree; then
    printf '[WARN] git %s: upgrade to >= 2.42 (empty-repo bootstrap (orbit add --orphan) needs >= 2.42)\n' "$git_ver"
  fi

  # 2. bash version check (≥ 3.2)
  if [ "${BASH_VERSINFO[0]}" -gt 3 ] || { [ "${BASH_VERSINFO[0]}" -eq 3 ] && [ "${BASH_VERSINFO[1]}" -ge 2 ]; }; then
    printf '[OK]   bash %s\n' "$BASH_VERSION"
  else
    printf '[FAIL] bash %s (need >= 3.2)\n' "$BASH_VERSION"
    all_ok=0
  fi

  # 3. Optional tools
  if command -v jq >/dev/null 2>&1; then
    printf '[OK]   jq (optional)\n'
  else
    printf '[WARN] jq not found (optional, improves JSON handling)\n'
  fi

  if command -v gh >/dev/null 2>&1; then
    printf '[OK]   gh (optional)\n'
  else
    printf '[WARN] gh not found (optional, enables PR-aware prune)\n'
  fi

  # Prune's session-rooted guard is best-effort: it reads ancestor cwds via
  # /proc (Linux) or lsof (macOS). Without either, only the root-level guard
  # applies — surface that instead of failing silently open.
  if [ -d "/proc/$$" ] || command -v lsof >/dev/null 2>&1; then
    printf '[OK]   process ancestry (/proc or lsof; prune initiation guard)\n'
  else
    printf '[WARN] no /proc and no lsof: prune cannot detect sessions rooted in a workspace (root-level guard still applies)\n'
  fi

  # 4. Project structure (if in orbit project)
  local root
  if root=$(orbit_find_root 2>/dev/null); then
    printf '\nProject: %s\n' "$root"
    if [ -d "$root/.repos" ]; then
      printf '[OK]   .repos/ exists\n'
      if [ -f "$root/.repos/.orbit" ]; then
        printf '[OK]   .repos/.orbit index\n'
      else
        printf '[WARN] .repos/.orbit not found (created on first clone)\n'
      fi
      local repo_count=0
      for d in "$root/.repos"/*/; do
        [ -d "$d" ] && repo_count=$((repo_count + 1))
      done
      printf '[INFO] repos in pool: %d\n' "$repo_count"
      local ws_count=0
      for d in "$root"/*/; do
        [ -d "$d" ] || continue
        local dirname
        dirname=$(basename "$d")
        orbit_reserved_workspace "$dirname" && continue
        ws_count=$((ws_count + 1))
      done
      printf '[INFO] workspaces: %d\n' "$ws_count"
    else
      printf '[WARN] .repos/ not found (run orbit clone to start)\n'
    fi
  else
    printf '\n[INFO] not in orbit project\n'
  fi

  printf '\n'
  if [ "$all_ok" -eq 1 ]; then
    printf 'All critical checks passed.\n'
  else
    # the verdict belongs to the report — keep it on stdout with the rest
    printf 'Some critical checks failed.\n'
    return 1
  fi
}

# --- Config ---

orbit_config() {
  local root
  root=$(orbit_require_root) || return 1
  local orbit_file="$root/.repos/.orbit"

  if [ "$#" -eq 0 ]; then
    # git config --list lowercases keys; restore the documented camelCase forms
    git config --file "$orbit_file" --list 2>/dev/null | grep -v '^repos\.' | \
      sed -e 's/^memo\.minlines=/memo.minLines=/' \
          -e 's/^memo\.maxlines=/memo.maxLines=/' \
          -e 's/^jot\.buffersize=/jot.bufferSize=/' \
          -e 's/^git\.fetchallbranches=/git.fetchAllBranches=/' \
          -e 's/^git\.fetchprune=/git.fetchPrune=/' \
          -e 's/^git\.pushupstreambydefault=/git.pushUpstreamByDefault=/' || true
    return 0
  fi

  local key="$1"
  if [ "$#" -eq 1 ]; then
    local val
    if val=$(git config --file "$orbit_file" --get "$key" 2>/dev/null); then
      printf '%s\n' "$val"
    else
      printf '(unset)\n' >&2
      return 1
    fi
    return 0
  fi

  [ "$#" -le 2 ] || orbit_fail "usage: orbit config <key> [<value> | --unset]"
  local value="$2"

  # git config key names are case-insensitive (subsections aside), so every
  # key-identity check below compares the lowercased form — a differently-cased
  # spelling of a guarded key must not slip past its guard.
  local key_lc
  key_lc=$(printf '%s' "$key" | tr '[:upper:]' '[:lower:]')

  # repos.* is the pool index orbit maintains, not project configuration. It is
  # rebuildable (Principle 3), but relying on that to excuse hand-editing means
  # the safety of this command rests on another principle rather than on itself.
  case "$key_lc" in
    repos.*) orbit_fail "repos.* is pool index data, not project config; refresh it with memo <repo> --refresh" ;;
  esac

  # branch.prefix is embedded in every branch orbit has already created and is
  # what prune matches on to find them again. A bad value would persist, and a
  # changed one would orphan the existing branches — validate on write, and
  # refuse to move it while any branch still carries the current one.
  if [ "$key_lc" = "branch.prefix" ]; then
    local target="$value" current existing
    [ "$value" = "--unset" ] && target="$ORBIT_DEFAULT_BRANCH_PREFIX"
    if ! orbit_valid_branch_prefix "$target"; then
      orbit_fail "invalid branch.prefix: $target (one path segment, valid in a git refname)"
      return 1
    fi
    current=$(orbit_require_prefix) || return 1
    if [ "$target" != "$current" ] && existing=$(orbit_branches_under_prefix "$root" "$current"); then
      orbit_fail "branch.prefix is part of existing branch names under '$current/': $existing"
      return 1
    fi
  fi

  # The managed-config switches accept exactly three modes; anything else
  # would silently read as the default (always) while looking like a choice.
  case "$key_lc" in
    git.fetchallbranches|git.fetchprune|git.pushupstreambydefault)
      if [ "$value" != "--unset" ]; then
        case "$value" in
          always|once|never) ;;
          *) orbit_fail "invalid $key: $value (expected always, once, or never)" ;;
        esac
      fi ;;
  esac

  if [ "$value" = "--unset" ]; then
    git config --file "$orbit_file" --unset "$key" 2>/dev/null || true
    printf 'unset: %s\n' "$key"
  else
    git config --file "$orbit_file" "$key" "$value"
    printf 'set: %s = %s\n' "$key" "$value"
  fi
}

# --- Context ---

# `orbit context` is the model-facing context aggregation command — its stdout
# is a readable markdown block for agents/humans, not machine data (the machine
# channel is --json). Three purpose-scoped entries:
#   --startup   session-start block; routes to prime (empty) / reignite (repos)
#   (bare)      cruise block: cheap durables + conditional per-repo status
#   <key>       single-value query: workspace|path|goal|state
# --prime / --reignite are explicit routing targets for humans and debugging;
# the skill exposes only --startup and the bare form. Fails fast outside a
# workspace (hooks treat failure as no-op).
orbit_context() {
  local json_mode=0 startup_mode=0 prime_mode=0 reignite_mode=0 query_key=""

  while [ "$#" -gt 0 ]; do
    case "$1" in
      --json) json_mode=1; shift ;;
      --startup) startup_mode=1; shift ;;
      --prime) prime_mode=1; shift ;;
      --reignite) reignite_mode=1; shift ;;
      -*) orbit_fail "usage: orbit context [<key>] [--startup|--prime|--reignite] [--json]" ;;
      *)
        if [ -z "$query_key" ]; then
          query_key="$1"
        else
          orbit_fail "usage: orbit context [<key>] [--startup|--prime|--reignite] [--json]"
        fi
        shift
        ;;
    esac
  done

  local mode_count=$(( startup_mode + prime_mode + reignite_mode ))
  [ "$mode_count" -le 1 ] || orbit_fail "--startup, --prime and --reignite are mutually exclusive"
  if [ -n "$query_key" ] && [ "$mode_count" -gt 0 ]; then
    orbit_fail "a key cannot be combined with --startup/--prime/--reignite"
  fi

  local root
  root=$(orbit_require_root) || return 1

  local ws
  ws=$(orbit_infer_workspace "$root") || return 1

  local ws_dir="$root/$ws"

  orbit_ensure_workspace_orbit "$ws_dir"

  if [ -n "$query_key" ]; then
    case "$query_key" in
      workspace) printf '%s\n' "$ws" ;;
      path)      printf '%s\n' "$ws_dir" ;;
      goal)      printf '%s\n' "$(git config --file "$ws_dir/.orbit" --get workspace.goal 2>/dev/null || true)" ;;
      state)     local s; s=$(git config --file "$ws_dir/.orbit" --get workspace.status 2>/dev/null || true); printf '%s\n' "${s:-active}" ;;
      *)         orbit_fail "unknown key: $query_key (available: workspace, path, goal, state)" ;;
    esac
    return 0
  fi

  local goal state_val
  goal=$(git config --file "$ws_dir/.orbit" --get workspace.goal 2>/dev/null || true)
  state_val=$(git config --file "$ws_dir/.orbit" --get workspace.status 2>/dev/null || true)
  [ -n "$state_val" ] || state_val="active"

  local index="$root/.repos/.orbit"

  # --startup routes on worktree presence: empty -> prime, populated -> reignite.
  if [ "$startup_mode" -eq 1 ]; then
    prime_mode=1
    local d
    for d in "$ws_dir"/*/; do
      [ -d "$d" ] || continue
      if [ -d "$d/.git" ] || [ -f "$d/.git" ]; then
        prime_mode=0
        reignite_mode=1
        break
      fi
    done
  fi

  if [ "$prime_mode" -eq 1 ]; then
    orbit_context_prime "$root" "$ws" "$ws_dir" "$goal" "$state_val" "$index" "$json_mode"
    return 0
  fi

  if [ "$reignite_mode" -eq 1 ]; then
    orbit_context_reignite "$root" "$ws" "$ws_dir" "$goal" "$state_val" "$index" "$json_mode"
    return 0
  fi

  # --- bare: cruise block (compact/resume recovery) ---
  # Cheap durables (path/goal/state — compaction may have wiped them) plus
  # conditional per-repo status (only repos with something pending). No memos,
  # no roster, no fetch — heavy durables live in --startup.
  local n c l b m br sc
  if [ "$json_mode" -eq 1 ]; then
    local out='{' first=1
    out+="$(orbit_json_kv workspace "$ws"),"
    out+="$(orbit_json_kv path "$ws_dir"),"
    out+="$(orbit_json_kv goal "$goal"),"
    out+="$(orbit_json_kv state "$state_val"),"
    out+='"mode":"cruise","worktrees":['
    while IFS='|' read -r n c l b m br sc; do
      [ -n "$n" ] || continue
      [ "$c" -gt 0 ] || [ -n "$b" ] || [ "$m" != "ok" ] || [ "$sc" = "0" ] || continue
      [ "$first" -eq 1 ] || out+=','
      first=0
      out+='{'
      out+="$(orbit_json_kv name "$n"),"
      out+="$(orbit_json_kv_raw jots "$c"),"
      out+="$(orbit_json_kv jotLevel "$l"),"
      out+="$(orbit_json_kv behind "$b"),"
      out+="$(orbit_json_kv memoState "$m"),"
      out+="$(orbit_json_kv branch "$br"),"
      out+="$(orbit_json_kv_raw scoped "$sc")"
      out+='}'
    done < <(orbit_collect_repo_status "$root" "$ws_dir")
    out+=']}'
    printf '%s\n' "$out"
    return 0
  fi

  printf 'path: %s\n' "$ws_dir"
  [ -n "$goal" ] && printf 'goal: %s\n' "$goal"
  printf 'state: %s\n' "$state_val"
  if [ "$state_val" = "done" ]; then
    printf '\n[!] this workspace is marked DONE — ask the user before continuing (reopen / prune / start elsewhere)\n'
  fi

  local first_line=1 parts
  while IFS='|' read -r n c l b m br sc; do
    [ -n "$n" ] || continue
    [ "$c" -gt 0 ] || [ -n "$b" ] || [ "$m" != "ok" ] || [ "$sc" = "0" ] || continue
    [ "$first_line" -eq 1 ] && { printf '\n'; first_line=0; }
    parts=""
    if [ "$c" -gt 0 ]; then
      if [ -n "$l" ]; then parts="$c jots ($l)"; else parts="$c jots"; fi
    fi
    if [ "$b" = "untracked" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}no upstream (fetch origin $br to track)"
    elif [ -n "$b" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}${b} behind upstream"
    fi
    if [ "$m" != "ok" ]; then
      [ -n "$parts" ] && parts="$parts | "
      if [ "$m" = "over" ]; then parts="${parts}memo over budget"; else parts="${parts}memo thin"; fi
    fi
    if [ "$sc" = "0" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}raw mode branch (orbit switch -c $br to convert to scoped)"
    fi
    printf 'repo %s: %s\n' "$n" "$parts"
  done < <(orbit_collect_repo_status "$root" "$ws_dir")
}

# prime: cold start with an empty workspace — orientation block: durables plus
# the pool roster (the "add menu"). No per-repo status (no worktrees), no memos.
orbit_context_prime() {
  local root="$1" ws="$2" ws_dir="$3" goal="$4" state_val="$5" index="$6" json_mode="$7"

  local pool_names=() pool_briefs=() pool_urls=() pool_srcs=() pool_nomemo=() pool_desync=()
  local pd pname pbrief psrc purl
  for pd in "$root/.repos"/*/; do
    [ -d "$pd" ] || continue
    pname=$(basename "$pd")
    { IFS= read -r pbrief; IFS= read -r psrc || true; } <<< "$(orbit_pool_brief "$root" "$index" "$pname" "$pd")"
    if [ -z "$pbrief" ] && [ "$json_mode" -eq 0 ]; then
      pbrief="-"
    fi
    purl=$(git config --file "$index" --get "repos.$pname.url" 2>/dev/null || true)
    if [ -z "$purl" ]; then
      purl=$(git -C "$pd" remote get-url origin 2>/dev/null || true)
    fi
    pool_names+=("$pname")
    pool_briefs+=("$pbrief")
    pool_urls+=("$purl")
    pool_srcs+=("$psrc")
    case "$psrc" in
      readme|none) pool_nomemo+=("$pname") ;;
      memo)        pool_desync+=("$pname") ;;
    esac
  done

  if [ "$json_mode" -eq 1 ]; then
    local out='{' first=1 p
    out+="$(orbit_json_kv workspace "$ws"),"
    out+="$(orbit_json_kv path "$ws_dir"),"
    out+="$(orbit_json_kv goal "$goal"),"
    out+="$(orbit_json_kv state "$state_val"),"
    out+='"mode":"prime","repos":['
    for p in "${!pool_names[@]}"; do
      [ "$first" -eq 1 ] || out+=','
      first=0
      out+='{'
      out+="$(orbit_json_kv name "${pool_names[$p]}"),"
      out+="$(orbit_json_kv url "${pool_urls[$p]}"),"
      out+="$(orbit_json_kv brief "${pool_briefs[$p]}")"
      out+='}'
    done
    out+=']}'
    printf '%s\n' "$out"
    return 0
  fi

  printf 'path: %s\n' "$ws_dir"
  [ -n "$goal" ] && printf 'goal: %s\n' "$goal"
  printf 'state: %s\n' "$state_val"
  if [ "$state_val" = "done" ]; then
    printf '[!] this workspace is marked DONE — ask the user before continuing (reopen / prune / start elsewhere)\n'
  fi
  printf '\n'
  if [ "${#pool_names[@]}" -eq 0 ]; then
    printf 'pool is empty — clone a repo into the pool first: orbit clone <url>\n'
  else
    printf 'available in pool (orbit add <repo> to pull source; orbit info <repo> for detail):\n'
    local i name_w=0
    for i in "${!pool_names[@]}"; do
      [ "${#pool_names[$i]}" -gt "$name_w" ] && name_w=${#pool_names[$i]}
    done
    for i in "${!pool_names[@]}"; do
      # Fallback briefs (README extract / none) are uncurated — append the
      # remote URL as the authoritative identity hint. Curated memo/index
      # briefs stay lean.
      case "${pool_srcs[$i]}" in
        readme|none)
          if [ -n "${pool_urls[$i]}" ]; then
            printf '  %-*s %s (%s)\n' "$name_w" "${pool_names[$i]}" "${pool_briefs[$i]}" "${pool_urls[$i]}"
          else
            printf '  %-*s %s\n' "$name_w" "${pool_names[$i]}" "${pool_briefs[$i]}"
          fi
          ;;
        *)
          printf '  %-*s %s\n' "$name_w" "${pool_names[$i]}" "${pool_briefs[$i]}"
          ;;
      esac
    done
    # Steering is inlined as stdout sections — hook injection carries only
    # stdout, so notes emitted on stderr would never reach the agent
    # (docs/spec-metadata.md "Fallback Rules").
    if [ "${#pool_nomemo[@]}" -gt 0 ]; then
      printf '\nno memo (write the card via orbit memo <repo>; a README-derived brief above is a display fallback, not a memo):\n'
      printf '  %s\n' "${pool_nomemo[@]}"
    fi
    if [ "${#pool_desync[@]}" -gt 0 ]; then
      printf '\nindex out of sync (repair via orbit memo <repo> --refresh):\n'
      printf '  %s\n' "${pool_desync[@]}"
    fi
  fi
}

# reignite: session (re)start with worktrees present — rebuilds what the ignite
# phase had read: each repo's memo card + two-layer staleness (memoBehind +
# remoteAhead; read from last-fetched refs — the startup hook is the session's
# main path and never fetches; without an async daemon, auto-fetch here would
# tax every session start for an advisory hint, and sync stays on-demand),
# conditional per-repo status, and small jot queues inlined. No roster, no source.
orbit_context_reignite() {
  local root="$1" ws="$2" ws_dir="$3" goal="$4" state_val="$5" index="$6" json_mode="$7"
  local buf
  buf=$(orbit_jot_buffer_size "$root")

  local d name branch md_file default_branch stored current local_head remote_head
  local memo_behind remote_ahead count level upstream behind mstate staleness parts jline

  if [ "$json_mode" -eq 1 ]; then
    local out='{' first=1
    out+="$(orbit_json_kv workspace "$ws"),"
    out+="$(orbit_json_kv path "$ws_dir"),"
    out+="$(orbit_json_kv goal "$goal"),"
    out+="$(orbit_json_kv state "$state_val"),"
    out+='"mode":"reignite","worktrees":['
    for d in "$ws_dir"/*/; do
      [ -d "$d" ] || continue
      [ -d "$d/.git" ] || [ -f "$d/.git" ] || continue
      name=$(basename "$d")
      branch=$(git -C "$d" branch --show-current 2>/dev/null || echo "detached")
      default_branch=$(orbit_default_branch "$root/.repos/$name" 2>/dev/null || true)
      memo_behind=0 remote_ahead=0
      if [ -n "$default_branch" ]; then
        # Config maintenance only — the startup hook is the session's main
        # path and stays purely local (zero network). remoteAhead below reads
        # last-fetched refs, refreshed by sync / prune or the user's own
        # fetch/pull.
        orbit_maintain_pool_config "$root/.repos/$name" "$root" 0
        local_head=$(git -C "$root/.repos/$name" rev-parse "refs/heads/$default_branch" 2>/dev/null || true)
        remote_head=$(git -C "$root/.repos/$name" rev-parse "refs/remotes/origin/$default_branch" 2>/dev/null || true)
        if [ -n "$local_head" ] && [ -n "$remote_head" ] && [ "$local_head" != "$remote_head" ]; then
          remote_ahead=$(git -C "$root/.repos/$name" rev-list "$local_head".."$remote_head" --count 2>/dev/null || echo 0)
        fi
      fi
      md_file="$root/.repos/.$name.md"
      stored=$(git config --file "$index" --get "repos.$name.head" 2>/dev/null || true)
      if [ -n "$stored" ] && [ -f "$md_file" ]; then
        current=$(git -C "$root/.repos/$name" rev-parse HEAD 2>/dev/null || true)
        if [ -n "$current" ] && [ "$stored" != "$current" ]; then
          memo_behind=$(git -C "$root/.repos/$name" rev-list "$stored".."$current" --count 2>/dev/null || echo 0)
        fi
      fi
      count=$(git config --file "$ws_dir/.orbit" --get-all "jot.$name.entry" 2>/dev/null | grep -c . || true)
      [ -n "$count" ] || count=0
      level=$(orbit_jot_level "$count" "$buf")
      behind=$(orbit_repo_upstream_behind "$d")
      mstate=$(orbit_memo_state "$md_file" "$root")

      [ "$first" -eq 1 ] || out+=','
      first=0
      out+='{'
      out+="$(orbit_json_kv name "$name"),"
      out+="$(orbit_json_kv branch "$branch"),"
      out+="$(orbit_json_kv_raw memoBehind "$memo_behind"),"
      out+="$(orbit_json_kv_raw remoteAhead "$remote_ahead"),"
      out+="$(orbit_json_kv_raw jots "$count"),"
      out+="$(orbit_json_kv jotLevel "$level"),"
      out+="$(orbit_json_kv behind "$behind"),"
      out+="$(orbit_json_kv memoState "$mstate"),"
      out+='"jotEntries":['
      local ef=1
      while IFS= read -r jline; do
        [ -n "$jline" ] || continue
        [ "$ef" -eq 1 ] || out+=','
        ef=0
        out+="\"$(orbit_json_escape "$jline")\""
      done < <(git config --file "$ws_dir/.orbit" --get-all "jot.$name.entry" 2>/dev/null || true)
      out+='],'
      if [ -f "$md_file" ]; then
        out+="$(orbit_json_kv memo "$(cat "$md_file")")"
      else
        out+="$(orbit_json_kv memo "")"
      fi
      out+='}'
    done
    out+=']}'
    printf '%s\n' "$out"
    return 0
  fi

  printf 'path: %s\n' "$ws_dir"
  [ -n "$goal" ] && printf 'goal: %s\n' "$goal"
  printf 'state: %s\n\n' "$state_val"
  if [ "$state_val" = "done" ]; then
    printf '[!] this workspace is marked DONE — ask the user before continuing (reopen / prune / start elsewhere)\n\n'
  fi

  for d in "$ws_dir"/*/; do
    [ -d "$d" ] || continue
    [ -d "$d/.git" ] || [ -f "$d/.git" ] || continue
    name=$(basename "$d")
    branch=$(git -C "$d" branch --show-current 2>/dev/null || echo "detached")

    # Two-layer staleness (purely local, last-fetched refs; no sync).
    default_branch=$(orbit_default_branch "$root/.repos/$name" 2>/dev/null || true)
    memo_behind=0 remote_ahead=0
    if [ -n "$default_branch" ]; then
      orbit_maintain_pool_config "$root/.repos/$name" "$root" 0
      local_head=$(git -C "$root/.repos/$name" rev-parse "refs/heads/$default_branch" 2>/dev/null || true)
      remote_head=$(git -C "$root/.repos/$name" rev-parse "refs/remotes/origin/$default_branch" 2>/dev/null || true)
      if [ -n "$local_head" ] && [ -n "$remote_head" ] && [ "$local_head" != "$remote_head" ]; then
        remote_ahead=$(git -C "$root/.repos/$name" rev-list "$local_head".."$remote_head" --count 2>/dev/null || echo 0)
      fi
    fi
    md_file="$root/.repos/.$name.md"
    stored=$(git config --file "$index" --get "repos.$name.head" 2>/dev/null || true)
    if [ -n "$stored" ] && [ -f "$md_file" ]; then
      current=$(git -C "$root/.repos/$name" rev-parse HEAD 2>/dev/null || true)
      if [ -n "$current" ] && [ "$stored" != "$current" ]; then
        memo_behind=$(git -C "$root/.repos/$name" rev-list "$stored".."$current" --count 2>/dev/null || echo 0)
      fi
    fi

    count=$(git config --file "$ws_dir/.orbit" --get-all "jot.$name.entry" 2>/dev/null | grep -c . || true)
    [ -n "$count" ] || count=0
    level=$(orbit_jot_level "$count" "$buf")
    behind=$(orbit_repo_upstream_behind "$d")
    mstate=$(orbit_memo_state "$md_file" "$root")
    local is_scoped
    case "$branch" in
      ws/"$ws"/*) is_scoped=1 ;;
      *) is_scoped=0 ;;
    esac

    printf -- '--- %s (branch: %s) ---\n' "$name" "$branch"
    staleness=""
    [ "$memo_behind" != "0" ] && staleness="memo is $memo_behind commits behind HEAD"
    if [ "$remote_ahead" != "0" ]; then
      [ -n "$staleness" ] && staleness="$staleness | "
      staleness="${staleness}${remote_ahead} new commits on origin/$default_branch"
    fi
    [ -n "$staleness" ] && printf 'staleness: %s\n' "$staleness"
    parts=""
    if [ "$count" -gt 0 ]; then
      if [ -n "$level" ]; then parts="$count jots ($level)"; else parts="$count jots"; fi
    fi
    if [ "$behind" = "untracked" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}no upstream (fetch origin $branch to track)"
    elif [ -n "$behind" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}${behind} behind upstream"
    fi
    if [ "$mstate" != "ok" ]; then
      [ -n "$parts" ] && parts="$parts | "
      if [ "$mstate" = "over" ]; then parts="${parts}memo over budget"; else parts="${parts}memo thin"; fi
    fi
    if [ "$is_scoped" = "0" ]; then
      [ -n "$parts" ] && parts="$parts | "
      parts="${parts}raw mode branch (orbit switch -c $branch to convert to scoped)"
    fi
    [ -n "$parts" ] && printf 'status: %s\n' "$parts"
    if [ "$count" -gt 0 ]; then
      if [ "$count" -le "$buf" ]; then
        printf 'jots (pop with: orbit jot %s --pop):\n' "$name"
        while IFS= read -r jline; do
          [ -n "$jline" ] || continue
          printf '  - %s\n' "$jline"
        done < <(git config --file "$ws_dir/.orbit" --get-all "jot.$name.entry" 2>/dev/null || true)
      else
        printf 'jots: %s entries queued — pop to view: orbit jot %s --pop\n' "$count" "$name"
      fi
    fi
    printf '\n'
    if [ -f "$md_file" ]; then
      printf '%s\n\n' "$(cat "$md_file")"
    else
      printf '(no memo yet — explore and write one with: orbit memo %s)\n\n' "$name"
    fi
  done
}

# --- Completion ---

orbit_completion_zsh() {
  cat <<'ZSH_EOF'
#compdef orbit
#
# Zsh completion for orbit — Git-native multi-repo workspace manager

_orbit_find_root() {
  local dir="$PWD"
  if [[ -n "${ORBIT_ROOT:-}" ]] && [[ -d "$ORBIT_ROOT/.repos" ]]; then
    printf '%s' "$ORBIT_ROOT"
    return
  fi
  while [[ "$dir" != "/" ]]; do
    if [[ -d "$dir/.repos" ]]; then
      printf '%s' "$dir"
      return
    fi
    dir="${dir:h}"
  done
}

_orbit_repos() {
  local root
  root=$(_orbit_find_root)
  [[ -z "$root" ]] && return
  local repos_dir="$root/.repos"
  [[ -d "$repos_dir" ]] || return
  local -a repos
  repos=("$repos_dir"/*(N/:t))
  repos=(${repos:#.*})
  compadd -a repos
}

_orbit_workspaces() {
  local root
  root=$(_orbit_find_root)
  [[ -z "$root" ]] && return
  local -a workspaces
  workspaces=("$root"/*(N/:t))
  workspaces=(${workspaces:#.repos})
  workspaces=(${workspaces:#.*})
  compadd -a workspaces
}

_orbit() {
  local -a commands
  commands=(
    'clone:Clone a repo into the source pool'
    'new:Create a new workspace'
    'add:Add a repo to current workspace'
    'switch:Switch to or create a branch'
    'sync:Sync pool repos with upstream'
    'status:Show workspace status'
    'goal:Read or set workspace goal'
    'jot:Record a discovery for later memo merge'
    'done:Mark workspace as done'
    'repos:List repos in pool'
    'info:Show repo memo'
    'memo:Write or refresh repo memos'
    'prune:Clean up done workspaces'
    'context:Show workspace context for agents'
    'config:Read or set project configuration'
    'doctor:Check environment health'
    'completion:Generate shell completion script'
    'version:Show orbit version'
  )

  _arguments -C \
    '1:command:->command' \
    '*::arg:->args'

  case "$state" in
    command)
      _describe -t commands 'orbit command' commands
      ;;
    args)
      case "$words[1]" in
        clone)
          _arguments \
            '--push[Enable push access]' \
            '--name[Set repo name]:name:' \
            '--branch[Specify branch]:branch:'
          ;;
        new)
          _arguments \
            '--name[Set workspace name]:name:' \
            '--no-goal[Create without a goal]' \
            '--exec[Execute command after creation]:command:'
          ;;
        add)
          _arguments \
            '--ref[Checkout specific ref]:ref:' \
            '(-s --silent)'{-s,--silent}'[Suppress the memo echo]' \
            '*:repo:_orbit_repos'
          ;;
        switch)
          _arguments \
            '-c[Create new branch]' \
            '*:repo:_orbit_repos'
          ;;
        sync)
          _arguments \
            '--force[Reset pool checkout to upstream, discarding local commits (project root only)]' \
            '--branch[Switch pool tracking branch (project root only)]:branch:' \
            '*:repo:_orbit_repos'
          ;;
        status)
          _arguments \
            '--json[Output as JSON]' \
            '*:workspace:_orbit_workspaces'
          ;;
        goal)
          _arguments \
            '--clear[Clear the workspace goal]'
          ;;
        jot)
          _arguments \
            '--pop[Pop all entries and clear]' \
            '--json[Output as JSON]' \
            '*:repo:_orbit_repos'
          ;;
        done)
          _arguments \
            '--pr[Include PR info]' \
            '--json[Output as JSON]'
          ;;
        repos)
          _arguments \
            '--json[Output as JSON]'
          ;;
        info)
          _arguments \
            '--json[Output as JSON]' \
            '*:repo:_orbit_repos'
          ;;
        memo)
          _arguments \
            '--refresh[Refresh memo index]' \
            '--scaffold[Generate scaffold to stdout]' \
            '*:repo:_orbit_repos'
          ;;
        context)
          _arguments \
            '1:key:(workspace path goal state)' \
            '--startup[Session-start block (routes prime/reignite)]' \
            '--prime[Cold-start block: durables + pool roster]' \
            '--reignite[Restart block: memos + per-repo status]' \
            '--json[Output as JSON]'
          ;;
        config)
          _arguments \
            '1:key:(agent.recommend branch.prefix explore.paths git.fetchAllBranches git.fetchPrune git.pushUpstreamByDefault jot.bufferSize memo.minLines memo.maxLines)' \
            '2:value:'
          ;;
        completion)
          _arguments \
            '1:shell:(zsh bash)'
          ;;
        prune)
          _arguments \
            '--older[Filter by age]:days:' \
            '--dry-run[Show what would be pruned]' \
            '--force[Destroy uncommitted changes and unmerged branches]' \
            '*:workspace:_orbit_workspaces'
          ;;
      esac
      ;;
  esac
}

_orbit "$@"
ZSH_EOF
}

orbit_completion_bash() {
  cat <<'BASH_EOF'
# Bash completion for orbit — Git-native multi-repo workspace manager

_orbit_find_root() {
  local dir="$PWD"
  if [ -n "${ORBIT_ROOT:-}" ] && [ -d "$ORBIT_ROOT/.repos" ]; then
    printf '%s' "$ORBIT_ROOT"
    return
  fi
  while [ "$dir" != "/" ]; do
    if [ -d "$dir/.repos" ]; then
      printf '%s' "$dir"
      return
    fi
    dir=$(dirname "$dir")
  done
}

_orbit_repo_names() {
  local root
  root=$(_orbit_find_root)
  [ -z "$root" ] && return
  local repos_dir="$root/.repos"
  [ -d "$repos_dir" ] || return
  local entry
  for entry in "$repos_dir"/*/; do
    [ -d "$entry" ] || continue
    entry="${entry%/}"
    entry="${entry##*/}"
    case "$entry" in
      .*) ;;
      *) printf '%s\n' "$entry" ;;
    esac
  done
}

_orbit_workspace_names() {
  local root
  root=$(_orbit_find_root)
  [ -z "$root" ] && return
  local entry
  for entry in "$root"/*/; do
    [ -d "$entry" ] || continue
    entry="${entry%/}"
    entry="${entry##*/}"
    case "$entry" in
      .repos|.*) ;;
      *) printf '%s\n' "$entry" ;;
    esac
  done
}

_orbit_completions() {
  local cur prev cmd
  cur="${COMP_WORDS[COMP_CWORD]}"
  prev="${COMP_WORDS[COMP_CWORD-1]}"

  local i cmd=""
  for ((i=1; i < COMP_CWORD; i++)); do
    case "${COMP_WORDS[i]}" in
      -*) ;;
      *) cmd="${COMP_WORDS[i]}"; break ;;
    esac
  done

  if [ -z "$cmd" ]; then
    COMPREPLY=($(compgen -W "clone new add switch sync status goal jot done repos info memo prune context config doctor completion version" -- "$cur"))
    return
  fi

  case "$cmd" in
    clone)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--push --name --branch" -- "$cur"))
      fi
      ;;
    new)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--name --no-goal --exec" -- "$cur"))
      fi
      ;;
    add)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--ref -s --silent" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    switch)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "-c" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    sync)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--force --branch" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    status)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--json" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_workspace_names)" -- "$cur"))
      fi
      ;;
    goal)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--clear" -- "$cur"))
      fi
      ;;
    jot)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--pop --json" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    done)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--pr --json" -- "$cur"))
      fi
      ;;
    repos)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--json" -- "$cur"))
      fi
      ;;
    info)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--json" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    memo)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--refresh --scaffold" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_repo_names)" -- "$cur"))
      fi
      ;;
    context)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--startup --prime --reignite --json" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "workspace path goal state" -- "$cur"))
      fi
      ;;
    config)
      if [[ "$cur" == --* ]]; then
        COMPREPLY=($(compgen -W "--unset" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "agent.recommend branch.prefix explore.paths git.fetchAllBranches git.fetchPrune git.pushUpstreamByDefault jot.bufferSize memo.minLines memo.maxLines" -- "$cur"))
      fi
      ;;
    completion)
      COMPREPLY=($(compgen -W "zsh bash" -- "$cur"))
      ;;
    prune)
      if [[ "$cur" == -* ]]; then
        COMPREPLY=($(compgen -W "--older --dry-run --force" -- "$cur"))
      else
        COMPREPLY=($(compgen -W "$(_orbit_workspace_names)" -- "$cur"))
      fi
      ;;
  esac
}

complete -F _orbit_completions orbit
BASH_EOF
}

orbit_completion() {
  local shell="${1:-}"
  case "$shell" in
    zsh)  orbit_completion_zsh ;;
    bash) orbit_completion_bash ;;
    *)    orbit_fail "usage: $ORBIT_CMD completion <zsh|bash>" ;;
  esac
}

# --- Dispatch ---

orbit() {
  local cmd="${1:-}"
  if [ "$#" -gt 0 ]; then shift; fi

  case "$cmd" in
    clone)      orbit_clone "$@" ;;
    new)        orbit_new "$@" ;;
    add)        orbit_add "$@" ;;
    switch)     orbit_switch "$@" ;;
    sync)       orbit_sync "$@" ;;
    status)     orbit_status "$@" ;;
    goal)       orbit_goal "$@" ;;
    jot)        orbit_jot "$@" ;;
    done)       orbit_done "$@" ;;
    repos)      orbit_repos "$@" ;;
    info)       orbit_info "$@" ;;
    memo)       orbit_memo "$@" ;;
    prune)      orbit_prune "$@" ;;
    config)     orbit_config "$@" ;;
    context)    orbit_context "$@" ;;
    doctor)     orbit_doctor "$@" ;;
    completion) orbit_completion "$@" ;;
    version|-v|--version) printf '%s\n' "$ORBIT_VERSION" ;;
    -h|--help|help|'') orbit_usage ;;
    *) orbit_fail "unknown command: $cmd" ;;
  esac
}

orbit "$@"