trantor 0.18.9 → 0.18.11

package/bin/crew.sh

@@ -3,6 +3,8 @@
 # session's teardown can't nuke out from under ANOTHER session's crew.
 #
 #   bin/crew.sh up codex glm kimi deepseek   # bring up THIS project's crew (tmux panes, or Terminal windows)
+#   bin/crew.sh open [<project>]              # host the operator's claude as the `orchestrator · <project>`
+#                                             #   pane in herdr (reattaches; never stacks a second one)
 #   bin/crew.sh down                          # tear down ONLY THIS PROJECT's crew (scoped, prints what it kills)
 #   bin/crew.sh down codex                    # tear down ONE seat
 #   bin/crew.sh down --all --yes              # tear down EVERY project's crew (global; --yes required)
@@ -46,11 +48,21 @@ HAVE_TMUX=0; command -v tmux >/dev/null 2>&1 && HAVE_TMUX=1
 # Events) — NOT the control socket — so it needs NO socket password (the socket denies external processes
 # by default; AppleScript bypasses that, exactly like we already script Terminal.app).
 HAVE_CMUX=0; [ -d "/Applications/cmux.app" ] && HAVE_CMUX=1
+# PRESENCE vs PREFERENCE: HAVE_* answer "which mux do NEW crews get" and are stomped by CREW_MUX and
+# the herdr auto-preference below. *_PRESENT answer "is this mux on the machine at all" and are what
+# PRUNE keys on — a row is validated by ITS OWN kind's liveness, never by which mux new crews prefer.
+# Conflating them let a dead cmux row survive prune the moment herdr became the preferred default.
+CMUX_PRESENT=$HAVE_CMUX
+HERDR_PRESENT=0; command -v herdr >/dev/null 2>&1 && HERDR_PRESENT=1
 # herdr (https://herdr.dev — a server-held terminal runtime: panes live in its background server, so a
-# crew survives the launcher exiting) is OPT-IN ONLY, never auto-detected — a machine with herdr
-# installed keeps its default cmux→tmux→terminal dispatch untouched. CREW_MUX=herdr is the explicit
-# switch; opting in without the binary is a HARD ERROR, because a silent fallback would defeat the ask.
+# crew survives the launcher exiting) is the PREFERRED mux when its binary is installed: it is the
+# only backend the desktop app's Workspace pane can render, so an auto-detected herdr means every
+# `trantor up` on every project shows up live in the app with no flag. (It was opt-in for exactly one
+# wave; the first thing the operator noticed was that other projects' crews stayed invisible.)
+# CREW_MUX=cmux|tmux|terminal still forces the old dispatch; CREW_MUX=herdr without the binary stays
+# a HARD ERROR, because an explicit ask must never silently fall back.
 HAVE_HERDR=0
+[ -z "${CREW_MUX:-}" ] && command -v herdr >/dev/null 2>&1 && { HAVE_HERDR=1; HAVE_CMUX=0; HAVE_TMUX=0; }
 # explicit override (user preference or tests): CREW_MUX=cmux|tmux|terminal|herdr forces the grouping UI.
 case "${CREW_MUX:-}" in
   cmux)     HAVE_CMUX=1; HAVE_TMUX=0 ;;
@@ -100,7 +112,7 @@ _cmux() { CMUX_QUIET=1 "$CMUX_BIN" "$@"; }            # quiet CLI wrapper (suppr
 _CMUX_OK=""                                          # cached: does the control socket accept us (allowAll)?
 _cmux_ok() {
   [ -n "$_CMUX_OK" ] && { [ "$_CMUX_OK" = "1" ] && return 0 || return 1; }
-  if [ "$HAVE_CMUX" = "1" ] && _cmux ping >/dev/null 2>&1; then _CMUX_OK=1; return 0; fi
+  if [ "$CMUX_PRESENT" = "1" ] && _cmux ping >/dev/null 2>&1; then _CMUX_OK=1; return 0; fi
   _CMUX_OK=0; return 1
 }
 # resolve a freshly-created workspace REF (workspace:N) → its stable UUID (survives index shifts).
@@ -170,6 +182,103 @@ console.log("\u0001"+a.map(x=>x.label||x.name||x.custom_title||"").filter(Boolea
 # Teardown works regardless of CREW_MUX: you must never need to remember the flag to tear a crew down.
 _herdr_close_ws()   { [ "$DRY" = "1" ] && { echo "[dry] herdr workspace close $1"; return 0; }; _herdr workspace close "$1" >/dev/null 2>&1; }
 _herdr_close_pane() { [ "$DRY" = "1" ] && { echo "[dry] herdr pane close $1";    return 0; }; _herdr pane close    "$1" >/dev/null 2>&1; }
+# Tell herdr a pane hosts an agent. WITHOUT this the pane is just a shell to herdr, `herdr agent
+# attach` answers agent_not_found, and the app's terminal shows that error instead of the seat —
+# observed 2026-08-27 on every seat while the orchestrator (claude, which herdr detects on its own)
+# streamed fine. NOTE the argument order: the pane id must come FIRST, before the flags.
+# ── orchestrator continuity ────────────────────────────────────────────────────────────────────
+# herdr keeps the PANE alive across an app quit, and launchd keeps its server alive across a
+# reboot. Neither preserves the CONVERSATION: a pty that dies comes back empty, because the
+# transcript was never a property of the terminal. That part is ours.
+#
+# So the project gets ONE claude session id, chosen by us and remembered. First open starts claude
+# under it; every later open resumes it. Discovering the id afterwards would be guesswork, and
+# `--continue` would grab whatever ran last in this directory, which may be a different window.
+_orch_sid() {   # $1=project → the project's session uuid, minting one on first use
+  local f="${STATE%/*}/orch-sessions.txt" p sid
+  if [ -f "$f" ]; then
+    while IFS="$(printf '\t')" read -r p sid; do
+      [ "$p" = "$1" ] && [ -n "$sid" ] && { printf '%s' "$sid"; return 0; }
+    done < "$f"
+  fi
+  sid="$(uuidgen 2>/dev/null | tr 'A-Z' 'a-z')"
+  [ -n "$sid" ] || return 1
+  [ "$DRY" = "1" ] || { mkdir -p "${f%/*}"; printf '%s\t%s\n' "$1" "$sid" >> "$f"; }
+  printf '%s' "$sid"
+}
+
+# claude writes each conversation to ~/.claude/projects/<slug>/<session-id>.jsonl, where the slug
+# is the working directory with every / and . turned into -.
+_orch_transcript() { printf '%s' "$HOME/.claude/projects/$(printf '%s' "$1" | tr '/.' '--')/$2.jsonl"; }
+
+# A herdr server started from inside a Claude Code session hands its whole environment to every
+# pane it later spawns, and those markers are session-scoped, not machine-scoped. The damage is
+# quiet and total: claude sees CLAUDE_CODE_CHILD_SESSION, decides it is a sub-session and TURNS
+# TRANSCRIPT SAVING OFF — so --resume would have nothing to resume and the persistence above would
+# be theatre. CLAUDE_CODE_MESSAGING_SOCKET/TOKEN are worse: they point the new session at the
+# ORIGINATING session's socket, which is how a fresh pane ends up claiming another session's baton.
+#
+# Feature flags the operator actually set (AGENT_TEAMS, FORK_SUBAGENT, EFFORT) are deliberately
+# left alone. Only identity is stripped.
+ORCH_STRIP="CLAUDECODE CLAUDE_CODE_ENTRYPOINT CLAUDE_CODE_SESSION_ID CLAUDE_CODE_CHILD_SESSION CLAUDE_CODE_BRIDGE_SESSION_ID CLAUDE_CODE_MESSAGING_SOCKET CLAUDE_CODE_MESSAGING_TOKEN CLAUDE_CODE_EXECPATH CLAUDE_PID"
+# TRANTOR_ORCH marks the pane's claude as THE orchestrator pane for $PROJ: the sessionstart hook
+# uses it to claim a held orchestrator baton immediately and to record its own session id in
+# orch-sessions.txt (project-matched on the hook side, so a child claude elsewhere can't inherit it).
+_orch_env() { local v out="env"; for v in $ORCH_STRIP; do out="$out -u $v"; done; printf '%s TRANTOR_ORCH=%s' "$out" "$PROJ"; }
+
+# The HARNESS dial (trantor autonomy). "bypass" is what the operator means by letting the agent
+# just work; "prompt" is the default because a fresh install must never silently skip a permission
+# the operator has not chosen to skip. Read per open, so changing it in the app takes effect the
+# next time the session is started rather than needing a reinstall.
+_orch_flags() {
+  local mode
+  mode="$(node "$(dirname "$0")/autonomy.mjs" get harness --project "$PROJ" 2>/dev/null)"
+  [ "$mode" = "bypass" ] && printf ' --dangerously-skip-permissions'
+}
+
+# Resume when the conversation already exists on disk; otherwise start it under the id we picked so
+# the NEXT open can resume it.
+_orch_cmd() {   # $1=dir $2=sid
+  if [ -f "$(_orch_transcript "$1" "$2")" ]; then printf '%s claude%s --resume %s' "$(_orch_env)" "$(_orch_flags)" "$2"
+  else printf '%s claude%s --session-id %s' "$(_orch_env)" "$(_orch_flags)" "$2"; fi
+}
+
+# A recorded thread that HANDED OFF has ended: resuming it replays a dead conversation while the
+# handoff waits for a successor (the 2026-08-27 seam — "Trantor resumes the wrong thread"). When the
+# newest unconsumed handoff for the project was written BY the recorded session, open must start a
+# FRESH id instead; the sessionstart hook then claims the baton and records the fresh id in
+# orch-sessions.txt (single writer for the map: the hook + adopt — this function writes nothing).
+_orch_takeover_sid() {   # $1=project $2=recorded-sid → prints the sid open should use
+  local fresh
+  if node -e '
+const fs=require("fs"),path=require("path"),os=require("os");
+const dir=path.join(process.env.AGENT_BUS_DIR||process.env.RELAY_DATA_DIR||path.join(os.homedir(),".agent-bus"),"handoffs");
+const [proj,sid]=process.argv.slice(1);
+try{
+  const re=new RegExp("^"+proj.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")+"-(\\d+)\\.json$");
+  const files=fs.readdirSync(dir).map(f=>{const m=re.exec(f);return m?{f,s:Number(m[1])}:null}).filter(Boolean).sort((a,b)=>b.s-a.s);
+  for(const {f} of files){
+    const r=JSON.parse(fs.readFileSync(path.join(dir,f),"utf8"));
+    if(r.consumed) continue;
+    process.exit(r.session_id&&r.session_id===sid?0:1);   // newest UNCONSUMED decides
+  }
+}catch(e){}
+process.exit(1);' "$1" "$2" 2>/dev/null; then
+    fresh="$(uuidgen 2>/dev/null | tr 'A-Z' 'a-z')"
+    [ -n "$fresh" ] && { echo "— recorded session $2 handed off: starting fresh as $fresh to claim it —" >&2; printf '%s' "$fresh"; return 0; }
+  fi
+  printf '%s' "$2"
+}
+
+# Does herdr see a LIVE agent in this pane? A pane answering `rename` only proves the pane exists;
+# the process inside it can be long gone, and reattaching to a dead shell shows the operator an
+# empty terminal that never fills.
+_herdr_pane_has_agent() { _herdr agent list 2>/dev/null | grep -q "\"pane_id\":\"$1\""; }
+
+_herdr_report_agent() {   # $1=pane $2=agent-label
+  [ "$DRY" = "1" ] && { echo "[dry] herdr pane report-agent $1 --source crew --agent $2 --state working"; return 0; }
+  _herdr pane report-agent "$1" --source crew --agent "$2" --state working >/dev/null 2>&1
+}
 
 # ── herdr spawn: ONE workspace `trantor:$PROJ`, one named pane per seat ─────────────────────────────
 # Topology = workspace create (its root pane runs seat 1) + pane split for the rest, same ceil(√N) grid
@@ -267,6 +376,9 @@ spawn_herdr() {   # $@ = specs
         [ -n "$surf" ] && { _herdr pane rename "$surf" "$AGENT · $PROJ" >/dev/null 2>&1; _herdr pane run "$surf" "$cmd" >/dev/null 2>&1; }
       fi
     fi
+    # Every path, dry included: herdr must know this pane hosts an agent or `agent attach` — which
+    # is how the app streams it — answers agent_not_found and the seat renders as an error.
+    [ -n "$surf" ] && _herdr_report_agent "$surf" "$AGENT"
     surfs+=("$surf")
     record_state "$PROJ" "herdr" "$AGENT" "$surf"
     echo "  → $AGENT seat in herdr workspace ($PROJ)"
@@ -328,7 +440,7 @@ down() {
 
   # collect the rows in scope + build a human kill-list. `scoped` entries are joined with '|' (NOT a tab):
   # tab is IFS whitespace, so re-splitting a tab-joined string would collapse an empty leading PROJECT.
-  local scoped=() line killlist="" seentmux=""
+  local scoped=() line killlist="" seentmux="" orch_scopes=""
   while IFS= read -r line; do
     [ -n "$line" ] || continue
     _parse_row "$line"                                       # → RP RK RA RH
@@ -336,14 +448,19 @@ down() {
     # SKIPPED by a scoped down — we can't prove they're ours, and killing another project's crew is the exact
     # bug we're fixing. `trantor down --all` reaches them; otherwise they self-heal via prune_dead_state.
     if [ "$WANT_ALL" != "1" ] && [ "$RP" != "$PROJ" ]; then continue; fi
+    # a project hosting the orchestrator pane degrades to PER-SEAT teardown: its workspace must survive
+    # (the orch pane lives inside it — closing the workspace closes the terminal the operator is typing
+    # in, from inside that terminal), so only the seat panes are closed.
+    [ "$RK" = "orch" ] && case ";$orch_scopes;" in *";$RP;"*) : ;; *) orch_scopes="$orch_scopes;$RP;" ;; esac
     if [ "${#AGENTS[@]}" -gt 0 ]; then                       # agent filter (if specific seats named)
       local match=0 want; for want in "${AGENTS[@]}"; do [ "$RA" = "$want" ] && match=1; done
       [ "$match" = "1" ] || continue
     fi
     scoped+=("$RP|$RK|$RA|$RH")
-    case "$RK" in attach|cmuxws|herdrws) continue ;; esac       # infra rows (attach/cmux/herdr workspace) — not seats
+    case "$RK" in attach|cmuxws|herdrws|orch) continue ;; esac # infra rows (attach/cmux/herdr workspace/orch) — not seats; `orch` is SPARED entirely
     killlist="$killlist  • ${RP:-<legacy>} · $RA ($RK)"$'\n'
   done < "$STATE"
+  _has_orch() { case "$orch_scopes" in *";$1;"*) return 0 ;; esac; return 1; }
 
   if [ "${#scoped[@]}" -eq 0 ]; then echo "nothing to tear down for $SCOPE_DESC"; return 0; fi
   echo "— tearing down ($SCOPE_DESC):"; printf '%s' "$killlist"
@@ -357,10 +474,10 @@ down() {
   for s in "${scoped[@]}"; do
     IFS='|' read -r P2 K2 A2 H2 <<< "$s"
     case "$K2" in
-      cmuxws) [ "${#AGENTS[@]}" -gt 0 ] || _cmux_close_tab "$H2" ;;   # whole workspace (no specific seats)
-      cmux)   [ "${#AGENTS[@]}" -gt 0 ] && _cmux_close_term "$H2" ;;  # a single seat's pane
-      herdrws) [ "${#AGENTS[@]}" -gt 0 ] || _herdr_close_ws "$H2" ;;  # whole workspace (no specific seats)
-      herdr)   [ "${#AGENTS[@]}" -gt 0 ] && _herdr_close_pane "$H2" ;;# a single seat's pane
+      cmuxws) { [ "${#AGENTS[@]}" -gt 0 ] || _has_orch "$P2"; } || _cmux_close_tab "$H2" ;;   # whole workspace (unless seats are named or an orch pane lives in it)
+      cmux)   { [ "${#AGENTS[@]}" -gt 0 ] || _has_orch "$P2"; } && _cmux_close_term "$H2" ;;  # a single seat's pane
+      herdrws) { [ "${#AGENTS[@]}" -gt 0 ] || _has_orch "$P2"; } || _herdr_close_ws "$H2" ;;  # whole workspace (unless seats are named or an orch pane lives in it)
+      herdr)   { [ "${#AGENTS[@]}" -gt 0 ] || _has_orch "$P2"; } && _herdr_close_pane "$H2" ;;# a single seat's pane
       tmux)
         if [ "${#AGENTS[@]}" -gt 0 ]; then run "tmux kill-pane -t '$H2' 2>/dev/null"      # per-seat
         else
@@ -372,7 +489,8 @@ down() {
     case "$K2" in cmuxws|attach|herdrws) : ;; *) _kill_seat_procs "$P2" "$A2" ;; esac
   done
 
-  # rewrite STATE minus the rows we tore down (leaves OTHER projects' rows intact)
+  # rewrite STATE minus the rows we tore down (leaves OTHER projects' rows intact). An orch-hosting
+  # project's workspace rows survive too — the workspace is still needed by the spared orch pane.
   if [ "$DRY" != "1" ]; then
     local tmp="$STATE.tmp"; : > "$tmp"
     while IFS= read -r line; do
@@ -380,6 +498,10 @@ down() {
       _parse_row "$line"
       local drop=0
       for s in "${scoped[@]}"; do [ "$s" = "$RP|$RK|$RA|$RH" ] && drop=1; done
+      # `orch` itself is spared alongside the workspace that hosts it: down never closes the
+      # orchestrator pane, so dropping its row would orphan a live pane and let the next `open`
+      # stack a second orchestrator on top of it.
+      [ "$drop" = "1" ] && _has_orch "$RP" && case "$RK" in herdrws|cmuxws|orch) drop=0 ;; esac
       [ "$drop" = "1" ] || printf '%s\t%s\t%s\t%s\n' "$RP" "$RK" "$RA" "$RH" >> "$tmp"
     done < "$STATE"
     mv "$tmp" "$STATE"
@@ -388,7 +510,7 @@ down() {
   echo "— crew torn down ($SCOPE_DESC)"
 }
 [ "$CMD" = "down" ] && { down "$@"; exit $?; }
-case "$CMD" in up|swap|prune) ;; *) echo "usage: crew.sh up <agent...> | crew.sh swap <old> <new[:provider[/model]]> | crew.sh down [<agent>...] [--all --yes] | crew.sh prune"; exit 1 ;; esac
+case "$CMD" in up|open|swap|prune) ;; *) echo "usage: crew.sh up <agent...> | crew.sh open [<project>] | crew.sh swap <old> <new[:provider[/model]]> | crew.sh down [<agent>...] [--all --yes] | crew.sh prune"; exit 1 ;; esac
 
 # self-heal: drop STATE rows whose Terminal window is already gone (dead crews from past sessions), so the
 # file doesn't accumulate ghosts across ups. tmux rows are validated by their session existing; cmux rows
@@ -409,10 +531,11 @@ prune_dead_state() {
     CLIVE="$(printf '%s' "$pair" | sed -n 1p)"
     CLIVE_NAMES="$(printf '%s' "$pair" | sed -n 2p)"
   fi
-  # herdr liveness is queried ONLY under the explicit opt-in (CREW_MUX=herdr): a default run never
-  # invokes herdr at all. Same keep-when-unprovable doctrine as cmux — no answer ⇒ rows are KEPT.
+  # herdr liveness is queried whenever the BINARY is present (herdr rows deserve validation no
+  # matter which mux new crews prefer). Same keep-when-unprovable doctrine as cmux — no answer,
+  # or no binary at all ⇒ rows are KEPT.
   local HLIVE="" HLIVE_NAMES=""
-  if [ "$HAVE_HERDR" = "1" ]; then
+  if [ "$HERDR_PRESENT" = "1" ]; then
     local hpair
     hpair="$(_herdr_ws_live)"
     HLIVE="$(printf '%s' "$hpair" | sed -n 1p)"
@@ -435,9 +558,9 @@ prune_dead_state() {
       if [ -n "$CLIVE" ]; then case "$CLIVE_NAMES" in *$'\x01'"trantor:$RP"$'\x01'*) : ;; *) alive=0 ;; esac; fi
     elif [ "$RK" = "herdrws" ]; then
       if [ -n "$HLIVE" ]; then case " $HLIVE " in *" $RH "*) : ;; *) alive=0 ;; esac; fi
-    elif [ "$RK" = "herdr" ]; then
-      # seat row lives exactly as long as its project still has a live crew workspace — validated at
-      # WORKSPACE granularity, never per pane (the cmux 0.17.61 lesson generalized)
+    elif [ "$RK" = "herdr" ] || [ "$RK" = "orch" ]; then
+      # seat + orchestrator rows live exactly as long as their project still has a live crew workspace
+      # — validated at WORKSPACE granularity, never per pane (the cmux 0.17.61 lesson generalized)
       if [ -n "$HLIVE" ]; then case "$HLIVE_NAMES" in *$'\x01'"trantor:$RP"$'\x01'*) : ;; *) alive=0 ;; esac; fi
     fi
     [ "$alive" = "1" ] && printf '%s\t%s\t%s\t%s\n' "$RP" "$RK" "$RA" "$RH" >> "$tmp"
@@ -447,6 +570,123 @@ prune_dead_state() {
 # `crew.sh prune` — run the self-heal on demand (ops: clean ghost rows without spawning anything).
 [ "$CMD" = "prune" ] && { prune_dead_state; echo "— pruned dead crew rows ($STATE) —"; exit 0; }
 
+# ── open: host the OPERATOR's session as the `orchestrator · <project>` pane (card #5396) ────────────
+# The session a developer actually works in used to be an unowned Terminal window — invisible to the
+# app, and killed by any whole-project `down` that closed the workspace under it. `trantor open`
+# hosts it as a herdr pane in the SAME `trantor:<project>` workspace the crew uses (herdr keeps the
+# pane alive server-side; Terminal attaches to the SAME session), and prints the pane TARGET on
+# stdout as ONE line:   herdr:<workspace_id>/<pane_id>   (human chatter goes to stderr, so the
+# target is capturable). REATTACH, NEVER STACK: a second open finds the tracked `orch` row alive and
+# reprints the target — two orchestrator claude processes on one project would fight over one bus
+# identity (the duplicated-runner lesson, crew.sh edition). The liveness probe is an idempotent
+# rename to the pane's own title: no per-pane list API is trusted (the 0.17.61 workspace-granularity
+# lesson), and a closed pane can never pass it. `down` SPARES `orch` rows for the same reason.
+usage_open() {
+  cat <<EOF
+usage: trantor open [<project>]
+  host THIS project's orchestrator session as a herdr pane in workspace trantor:<project>
+  (creating the workspace if needed) and print its TARGET on stdout. A second open REATTACHES:
+  it prints the existing target and exits 0 without spawning a second orchestrator.
+EOF
+}
+open_orchestrator() {
+  local a
+  for a in "$@"; do case "$a" in
+    --help|-h) usage_open; return 0 ;;
+    --*) echo "trantor open: unknown flag '$a'"; usage_open; return 1 ;;
+    *) PROJ="$a" ;;
+  esac; done
+  command -v herdr >/dev/null 2>&1 || { echo "trantor open needs herdr (the pane host) — install: curl -fsSL https://herdr.dev/install.sh | sh"; exit 1; }
+  local wsid="" orch="" live_ids="" live_names="" pair="" line fresh=0
+  local sid; sid="$(_orch_sid "$PROJ")" || { echo "trantor open: could not mint a session id (uuidgen missing?)" >&2; exit 1; }
+  sid="$(_orch_takeover_sid "$PROJ" "$sid")"
+  if [ "$DRY" != "1" ]; then
+    pair="$(_herdr_ws_live)"
+    live_ids="$(printf '%s' "$pair" | sed -n 1p)"
+    live_names="$(printf '%s' "$pair" | sed -n 2p)"
+  fi
+  if [ -f "$STATE" ]; then
+    while IFS= read -r line; do
+      [ -n "$line" ] || continue
+      _parse_row "$line"
+      [ "$RP" = "$PROJ" ] || continue
+      case "$RK" in
+        herdrws)
+          # a tracked workspace is only usable while LIVE (label match); a provably dead row is dropped.
+          # No live answer ⇒ kept (the keep-when-unprovable doctrine shared with prune).
+          if [ "$DRY" != "1" ] && [ -n "$live_ids" ]; then
+            case " $live_ids " in *" $RH "*) wsid="$RH" ;; *) _state_drop "$PROJ" "herdrws" "" "$RH" ;; esac
+          else wsid="$RH"; fi ;;
+        orch) orch="$RH" ;;
+      esac
+    done < "$STATE"
+  fi
+  # REATTACH, never stack: a tracked orch pane that still answers is reused as-is.
+  if [ -n "$orch" ]; then
+    if [ "$DRY" = "1" ]; then
+      echo "herdr:${wsid:-%DRYWS}/$orch"
+      return 0
+    fi
+    if _herdr pane rename "$orch" "orchestrator · $PROJ" >/dev/null 2>&1; then
+      if _herdr_pane_has_agent "$orch"; then
+        echo "herdr:${wsid:-?}/$orch"
+        echo "— orchestrator already hosted: reattached to herdr:${wsid:-?}/$orch —" >&2
+        return 0
+      fi
+      # The pane outlived its claude (a crash, or a reboot that took the process but not the row).
+      # Restart the CONVERSATION in the same pane rather than handing back an empty terminal.
+      _herdr pane run "$orch" "$(_orch_cmd "$DIR" "$sid")" >/dev/null 2>&1
+      _herdr_report_agent "$orch" "claude"
+      echo "herdr:${wsid:-?}/$orch"
+      echo "— orchestrator pane was empty: resumed session $sid in herdr:${wsid:-?}/$orch —" >&2
+      return 0
+    fi
+    _state_drop "$PROJ" "orch" "" ""; orch=""     # stale row → healed by the create path below
+  fi
+  # No usable workspace yet: adopt an untracked LIVE crew workspace before creating a second one
+  # (spawn_herdr's adopt-else-create doctrine — open must not stack trantor:<project> workspaces).
+  if [ -z "$wsid" ]; then
+    if [ "$DRY" = "1" ]; then
+      wsid="%DRYWS"
+      echo "[dry] herdr: workspace create (cwd $DIR) --label 'trantor:$PROJ'" >&2
+    else
+      local found=""
+      case "$live_names" in
+        *$'\x01'"trantor:$PROJ"$'\x01'*)
+          found="$(_herdr workspace list 2>/dev/null | WSNAME="trantor:$PROJ" node -e 'let d="";process.stdin.on("data",c=>d+=c).on("end",()=>{try{const o=JSON.parse(d.slice(d.search(/[\[{]/)));const a=Array.isArray(o)?o:(o.workspaces||((o.result||{}).workspaces)||[]);console.log(a.filter(x=>x.label===process.env.WSNAME||x.name===process.env.WSNAME||x.custom_title===process.env.WSNAME).map(x=>x.workspace_id||x.id||"").filter(Boolean)[0]||"")}catch(e){}})')"
+          [ -n "$found" ] && echo "— adopting existing crew workspace for $PROJ ($found) —" >&2 ;;
+      esac
+      if [ -n "$found" ]; then wsid="$found"
+      else
+        pair="$(_herdr_ws_create "$DIR" "trantor:$PROJ")"
+        wsid="${pair%%$'\t'*}"; fresh=1
+      fi
+      [ -n "$wsid" ] || { echo "trantor open: herdr workspace create failed" >&2; exit 1; }
+    fi
+    record_state "$PROJ" "herdrws" "__ws__" "$wsid"
+  fi
+  # Host the pane: a JUST-created workspace's root pane IS the orchestrator pane (claude rides it);
+  # an existing workspace gets a split — the crew's seats tile off it on the next `up`, never
+  # replacing it (spawn_herdr's REUSE mode splits seats off their own old pane / the previous one).
+  if [ "$DRY" = "1" ]; then
+    orch="%DRYORCH"
+    echo "[dry] herdr: ${fresh:+root pane + }pane rename $orch 'orchestrator · $PROJ' + run '$(_orch_cmd "$DIR" "$sid")'" >&2
+  else
+    if [ "$fresh" = "1" ]; then orch="${pair##*$'\t'}"
+    else orch="$(_herdr_split "" right)"; fi
+    [ -n "$orch" ] || { echo "trantor open: could not create the orchestrator pane" >&2; exit 1; }
+    _herdr pane rename "$orch" "orchestrator · $PROJ" >/dev/null 2>&1
+    _herdr pane run "$orch" "$(_orch_cmd "$DIR" "$sid")" >/dev/null 2>&1
+    _herdr_report_agent "$orch" "claude"
+  fi
+  _state_drop "$PROJ" "orch" "" ""                 # replace-never-stack: exactly one orch row per project
+  record_state "$PROJ" "orch" "__orch__" "$orch"
+  echo "herdr:$wsid/$orch"
+  echo "— orchestrator pane hosted: herdr:$wsid/$orch (claude in $DIR). 'trantor down' spares it. —" >&2
+  return 0
+}
+[ "$CMD" = "open" ] && { open_orchestrator "$@"; exit $?; }
+
 # --task/--difficulty drive LAZY live-model selection for provider-only specs (agent:provider).
 TASK="code"; DIFF="medium"; _ARGS=()
 while [ $# -gt 0 ]; do

package/bin/herdr-agent.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Keep herdr's server alive across a reboot.
+//
+// herdr already holds every pane in a background server, so quitting the app or closing a Terminal
+// window never costs you a session. A REBOOT does: the server dies with everything else, and
+// nothing brings it back, so the next `trantor open` finds no workspace and starts over. That was
+// the missing half of "it survives restarts" (card #5401).
+//
+// This is only the SERVER's lifetime. The conversation inside a pane is a separate problem, solved
+// in crew.sh: the project keeps one claude session id and `open` resumes it.
+import { existsSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+const LABEL = "com.trantor.herdr";
+const PLIST = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+const LOG = "/tmp/trantor-herdr-server.log";
+const D = "\x1b[2m", R = "\x1b[0m";
+
+function herdrBin() {
+  // launchd runs with a minimal PATH, so the absolute path has to be baked in at install time.
+  for (const p of [join(homedir(), ".local/bin/herdr"), "/opt/homebrew/bin/herdr", "/usr/local/bin/herdr"]) {
+    if (existsSync(p)) return p;
+  }
+  try {
+    const found = execFileSync("/usr/bin/which", ["herdr"], { encoding: "utf8" }).trim();
+    if (found) return found;
+  } catch { /* not on PATH either */ }
+  return "";
+}
+
+const plistBody = (bin) => `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>-lc</string>
+    <!-- Idempotent on purpose. A second herdr server against a live one prints "already running"
+         and exits 1, so a plain KeepAlive would respawn it every 10s forever. Bail out cleanly
+         instead, and only exec when nothing is holding the socket. -->
+    <string>${bin} status 2>/dev/null | grep -q 'status: running' &amp;&amp; exit 0; exec ${bin} server</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <!-- Restart a server that DIED, never one that stopped cleanly (herdr server stop) or one that
+       bailed because another was already up. -->
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>StandardOutPath</key><string>${LOG}</string>
+  <key>StandardErrorPath</key><string>${LOG}</string>
+</dict>
+</plist>
+`;
+
+const cmd = process.argv[2] || "status";
+const uid = process.getuid();
+
+if (cmd === "install") {
+  const bin = herdrBin();
+  if (!bin) {
+    console.error("herdr is not installed — get it first: curl -fsSL https://herdr.dev/install.sh | sh");
+    process.exit(1);
+  }
+  mkdirSync(dirname(PLIST), { recursive: true });
+  writeFileSync(PLIST, plistBody(bin));
+  // bootout first so a re-install replaces rather than stacks
+  try { execFileSync("/bin/launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" }); } catch { /* not loaded */ }
+  try {
+    execFileSync("/bin/launchctl", ["bootstrap", `gui/${uid}`, PLIST], { stdio: "ignore" });
+  } catch (e) {
+    console.error(`wrote ${PLIST} but launchctl bootstrap failed: ${e?.message || e}`);
+    process.exit(1);
+  }
+  console.log(`herdr's server now starts at login (${bin} server)`);
+  console.log(`${D}plist: ${PLIST}   log: ${LOG}${R}`);
+} else if (cmd === "remove") {
+  try { execFileSync("/bin/launchctl", ["bootout", `gui/${uid}/${LABEL}`], { stdio: "ignore" }); } catch { /* not loaded */ }
+  if (existsSync(PLIST)) { unlinkSync(PLIST); console.log("removed the herdr login agent"); }
+  else console.log("no herdr login agent installed");
+} else if (cmd === "status") {
+  const installed = existsSync(PLIST);
+  let loaded = false;
+  try {
+    loaded = execFileSync("/bin/launchctl", ["list"], { encoding: "utf8" }).split("\n").some(l => l.includes(LABEL));
+  } catch { /* launchctl unavailable */ }
+  let running = false;
+  try { running = /status:\s*running/.test(execFileSync(herdrBin() || "herdr", ["status"], { encoding: "utf8" })); } catch { /* server down */ }
+  console.log(`login agent: ${installed ? "installed" : "not installed"}${installed ? ` (${loaded ? "loaded" : "NOT loaded"})` : ""}`);
+  console.log(`herdr server: ${running ? "running" : "not running"}`);
+  if (!installed) console.log(`${D}install it so panes survive a reboot: trantor herdr install${R}`);
+} else {
+  console.log("usage: trantor herdr install | remove | status");
+  process.exit(1);
+}

package/bin/integrate.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// `trantor integrate` — collect the crew's work, prove it, ship it.
+//
+// The steps are the ones the orchestrator already performs by hand. The dials decide how far it is
+// allowed to go on its own, and every stop says which dial stopped it, so "why didn't it push"
+// always has an answer.
+import { resolveProject } from "../lib/project.mjs";
+import { resolveAutonomy } from "../lib/autonomy.mjs";
+import { seatWorktrees, commitSeatWork, seatAhead, mergeSeat, verify, git } from "../lib/integrate.mjs";
+
+const D = "\x1b[2m", B = "\x1b[1m", G = "\x1b[32m", Y = "\x1b[33m", RED = "\x1b[31m", R = "\x1b[0m";
+const args = process.argv.slice(2);
+const dry = args.includes("--dry-run");
+const repo = process.cwd();
+const project = resolveProject(repo);
+const a = resolveAutonomy(project);
+
+console.log(`${B}integrate${R} · ${project}   ${D}commit=${a.commit ? "on" : "off"} push=${a.push ? "on" : "off"} deploy=${a.deploy ? "on" : "off"}${R}`);
+
+const base = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]);
+const seats = seatWorktrees(project);
+if (!seats.length) {
+  console.log(`${D}no seat worktrees for ${project} — nothing to integrate${R}`);
+  process.exit(0);
+}
+
+// 1. Each seat's uncommitted work becomes a commit AUTHORED TO THAT SEAT, so git blame stays a
+//    truthful answer to "who wrote this" once integration stops being manual.
+let blocked = false;
+for (const w of seats) {
+  const dirty = git(w.dir, ["status", "--porcelain"]);
+  if (!dirty) { console.log(`  ${D}${w.agent}: clean${R}`); continue; }
+  if (!a.commit) {
+    console.log(`  ${Y}${w.agent}: has uncommitted work, and commit is off${R} ${D}(trantor autonomy set commit on)${R}`);
+    blocked = true;
+    continue;
+  }
+  if (dry) { console.log(`  ${D}[dry] would commit ${dirty.split("\n").length} file(s) as ${w.agent}${R}`); continue; }
+  const r = commitSeatWork(w);
+  console.log(`  ${G}${w.agent}: committed ${r.sha}${R}`);
+}
+
+// 2. Merge what each seat is ahead by. A conflict stops the pass: two seats on the same lines is
+//    the collision the overseer exists to surface, not something to resolve silently.
+const merged = [];
+for (const w of seats) {
+  const { branch, ahead } = seatAhead(w, base);
+  if (!ahead) continue;
+  if (dry) { console.log(`  ${D}[dry] would merge ${branch} (${ahead} commit(s))${R}`); merged.push(branch); continue; }
+  const m = mergeSeat(repo, branch);
+  if (m.conflict) {
+    console.log(`  ${RED}${branch}: CONFLICT — left untouched${R}\n${D}${m.detail}${R}`);
+    blocked = true;
+    continue;
+  }
+  if (m.merged) { console.log(`  ${G}merged ${branch} (${ahead} commit(s))${R}`); merged.push(branch); }
+}
+
+if (blocked) {
+  console.log(`\n${Y}stopping here — resolve the above before anything ships${R}`);
+  process.exit(1);
+}
+if (!merged.length && !dry) {
+  console.log(`${D}nothing new to integrate${R}`);
+  process.exit(0);
+}
+
+// 3. Proof. This gate ignores the dial on purpose: unverified work does not leave the machine,
+//    whatever the operator turned on.
+if (dry) { console.log(`${D}[dry] would verify, then push=${a.push}${R}`); process.exit(0); }
+console.log(`\n${D}verifying…${R}`);
+const v = verify(repo);
+if (!v.ok) {
+  console.log(`${RED}verify FAILED (${v.cmd}) — not pushing${R}\n${D}${v.tail}${R}`);
+  process.exit(1);
+}
+console.log(`${G}verified (${v.cmd})${R}`);
+
+// 4. Ship.
+if (!a.push) {
+  console.log(`${D}push is off — integrated and verified locally (trantor autonomy set push on)${R}`);
+  process.exit(0);
+}
+git(repo, ["push"]);
+console.log(`${G}pushed ${base}${R}`);
+if (a.deploy) console.log(`${D}deploy is on, but this project has no deploy step wired here yet${R}`);

package/bin/seat-why.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// trantor seat-why <agent> [--json] — explain why a crew seat is (not) working, straight from
+// local ~/.agent-bus evidence. No hub needed; works even when the whole fleet is down.
+import { seatWhy } from "../lib/seat-why.mjs";
+import { resolveProject } from "../lib/project.mjs";
+
+const args = process.argv.slice(2);
+const agent = args.find(a => !a.startsWith("--"));
+const asJson = args.includes("--json");
+const projIdx = args.indexOf("--project");
+const project = projIdx !== -1 && args[projIdx + 1]
+  ? args[projIdx + 1]
+  : process.env.RELAY_PROJECT || resolveProject(process.cwd());
+
+if (!agent) {
+  console.error("usage: trantor seat-why <agent> [--json] [--project <name>]");
+  process.exit(2);
+}
+
+const out = await seatWhy(project, agent);
+if (asJson) {
+  console.log(JSON.stringify({ agent, project, ...out }, null, 2));
+} else {
+  console.log(`seat ${agent}:${project} -> ${out.state}`);
+  console.log(`why:    ${out.why}`);
+  console.log(`advice: ${out.advice}`);
+}

package/hooks/lib/handoff.mjs

@@ -433,7 +433,9 @@ export function maybeSpawn(projectDir, conf = readConfig()) {
 }
 
 // The self-announcing fresh session command (single-quoted so it survives osascript→shell un-escaped).
-export const RECAP_CMD = "claude 'Recap the handoff you just took over — what was the previous session doing, and where do we continue? Then wait for me.'";
+// The recap must be READABLE: on 2026-08-27 a takeover session answered with three consecutive
+// 4-5k-character status dumps and the operator abandoned the app. Brevity is part of the prompt.
+export const RECAP_CMD = "claude 'Recap the handoff you just took over — task, state, next step — in at most 3 sentences. Then wait for me. Keep all replies short by default: no status tables, no headers, no walls of text unless I explicitly ask for detail.'";
 
 // Spawn a fresh self-announcing session WITHOUT the dialog (manual handoff — the user already decided).
 // ONE suppression check for every path that can open a terminal window. There were two names for