feat(terminals): terminal-driver axis v1 → peek/poke on tmux/herdr/plain

.github/errexit-status-reads-baseline

@@ -0,0 +1 @@
+1

.github/workflows/tests.yml

@@ -1075,6 +1075,24 @@ jobs:
       - name: No new assertion that cannot fail
         run: .github/scripts/check-enforced-assertions.sh
 
+  errexit-status-reads:
+    name: errexit status reads
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Unconditional for the same reason as `enforced-assertions` above: a job
+    # that skips on some diffs is a required context that can sit pending. It
+    # is a static read of `scripts/**/*.sh`.
+    steps:
+      - uses: actions/checkout@v4
+
+      # Ubuntu's bash is 5.x, and one of the three shapes this looks for is
+      # fatal ONLY on bash 3.2 (macOS /bin/bash). That is why the check is
+      # static: running it under one interpreter would miss the shape that
+      # kills the other. The behaviour was measured on both (see the header);
+      # what runs here is the count.
+      - name: No status read that errexit already decided
+        run: .github/scripts/check-errexit-status-reads.sh
+
   private-names:
     name: internal names
     runs-on: ubuntu-latest

scripts/actas-claim.sh

@@ -36,6 +36,18 @@ source "$SCRIPT_DIR/lib/actas-lock.sh"
 source "$SCRIPT_DIR/lib/resolve-project.sh"
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/lib/role-session.sh"  # role->session record (#339)
+# Terminal registry, for naming this pane after the claim (v1 scope, item 4). The
+# errexit lift is not decoration: on bash 3.2 a failure inside a sourced file
+# fires THIS script's `set -e`, so `. x || true` would take the script down
+# instead of the guard arm. Naming must never be able to fail a claim.
+_agmsg_tr_rc=0; _agmsg_tr_e=0
+case $- in *e*) _agmsg_tr_e=1 ;; esac
+set +e
+# shellcheck disable=SC1091
+[ -r "$SCRIPT_DIR/lib/terminal-registry.sh" ] && . "$SCRIPT_DIR/lib/terminal-registry.sh"
+_agmsg_tr_rc=$?
+[ "$_agmsg_tr_e" = 1 ] && set -e
+[ "$_agmsg_tr_rc" -eq 0 ] || echo "agmsg: terminal registry unavailable; this pane will not be named" >&2
 
 # Resolve the session's real project root (see #92) before any lookup, so an
 # actas issued from a subdir/worktree claims against the registered project
@@ -97,6 +109,33 @@ while IFS= read -r team; do
   agmsg_role_session_record "$team" "$NAME" "$BARE_SID" "$PROJECT_PHYS" "$TYPE" || true
 done <<< "$TEAMS"
 
+# Name this pane for the role just claimed, so peek/poke can reach a session a
+# human started by hand — not only one `spawn` placed. `|| true` twice over: the
+# claim is what the caller is waiting on, and naming must not be able to fail it
+# or delay its status line. A terminal that cannot name says so on stderr once.
+#
+# BARE_SID, not $SESSION_ID. In THIS script $SESSION_ID has been overwritten with
+# the normalized composite "<sid>.<pid>" (above), a token that exists only inside
+# agmsg; in session-start.sh the identically named variable holds the BARE sid the
+# CLI handed the hook, and it passes that. What a terminal knows is the bare one —
+# herdr stores exactly it in agent_session.value — so handing over the composite
+# asks a question no terminal can answer. It comes back as "cannot identify this
+# pane", which reads as a resolution problem and is an identifier mismatch, and
+# the `|| true` below means the claim still reports success while the pane goes
+# unnamed and unaddressable. watch.sh does the same lookup and was corrected the
+# same way (watch.sh:271); this was the remaining site.
+#
+# Once per claimed team, mirroring the role-session loop above: each (team, role)
+# gets its own record, because that pair is what peek/poke resolve by. The
+# VISIBLE pane name is whichever team comes last — panes have one name and a role
+# in two teams is one pane. Stable, since the order is $TEAMS'.
+if declare -F agmsg_terminal_name_self_safe >/dev/null 2>&1; then
+  while IFS= read -r team; do
+    [ -z "$team" ] && continue
+    agmsg_terminal_name_self_safe "$BARE_SID" "$team" "$NAME" "$PROJECT_PHYS" "$TYPE" record || true
+  done <<< "$TEAMS"
+fi
+
 # Start the engine for each claimed team, if one is not already up (#774).
 #
 # The second of the two trigger points. `actas` is where a session takes on a

scripts/delivery.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 #
 # Usage:
 #   delivery.sh set <mode> <type> <project_path>
-#   delivery.sh status [<type> <project_path>]
+#   delivery.sh status [<type> <project_path> [<session_id>]]
 #   delivery.sh stop
 #   delivery.sh restart [<project_path> <type>]
 #
@@ -72,6 +72,8 @@ RUN_DIR="$SKILL_DIR/run"
 # command; see lib/shquote.sh for why naive `'$var'` is not enough.
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/lib/shquote.sh"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/terminal-registry.sh"
 _agmsg_shq() { agmsg_shq "$1"; }
 
 # True (0) iff <cli>'s reported version is >= <min>, compared as MAJOR.MINOR.PATCH.
@@ -718,9 +720,60 @@ do_set() {
   esac
 }
 
+# Report which terminal this session resolves to, as three distinguishable
+# answers rather than one hopeful line:
+#
+#   terminal: herdr (pane w1:p1)              resolved, and nameable/peekable
+#   terminal: herdr (cannot identify ...)     under it, but this pane is unknown
+#   terminal: unknown                         the resolver answered for nothing
+#
+# The middle one is the one worth printing separately: it is the state where
+# `name` and `peek` will fail while everything else looks fine, and a status
+# that folded it into either neighbour would be the reason nobody could tell.
+#
+# The session id is optional because delivery.sh is type-generic and each CLI
+# names its own session differently. Without one, PLACEMENT still answers
+# ("which terminal am I under") — that needs no self-id — and the pane is
+# reported as not asked for, not as absent.
+print_terminal_status() {
+  local sid="${1:-}" line name id errf reason
+
+  if [ -z "$sid" ]; then
+    if name="$(agmsg_terminal_resolve_placement "" 2>/dev/null)"; then
+      echo "terminal: $name (pane not resolved — no session id given)"
+    else
+      echo "terminal: unknown"
+    fi
+    return 0
+  fi
+
+  errf="$(mktemp "${TMPDIR:-/tmp}/agmsg-status.XXXXXX")" || errf=/dev/null
+  # resolve_name is fail-closed: present-but-unidentifiable is a non-zero with
+  # the driver's reason on stderr. Keep that reason — it is the whole content
+  # of the middle state.
+  line="$(agmsg_terminal_resolve_name "$sid" 2>"$errf")" || line=""
+  if [ -n "$line" ]; then
+    name="${line%%	*}"
+    id="${line#*	}"
+    echo "terminal: $name (pane $id)"
+  else
+    reason=""
+    if [ "$errf" != /dev/null ] && [ -f "$errf" ]; then
+      reason="$(cat "$errf" 2>/dev/null || true)"
+    fi
+    if name="$(agmsg_terminal_resolve_placement "$sid" 2>/dev/null)"; then
+      echo "terminal: $name (${reason:-cannot identify this pane})"
+    else
+      echo "terminal: unknown${reason:+ ($reason)}"
+    fi
+  fi
+  [ "$errf" = /dev/null ] || rm -f "$errf"
+}
+
 do_status() {
   local TYPE="${1:-}"
   local PROJECT="${2:-}"
+  local SESSION_ID="${3:-}"
 
   # Mode is derived from the project's settings.local.json — there's no
   # global mode value. When called without <type> <project>, we can't infer
@@ -734,6 +787,8 @@ do_status() {
   fi
 
   agmsg_delivery_runtime_status "$TYPE" "$PROJECT"
+
+  print_terminal_status "$SESSION_ID"
 }
 
 kill_all_watchers() {

scripts/despawn.sh

@@ -12,23 +12,31 @@ set -euo pipefail
 #
 # Default (graceful): send a `ctrl:despawn` control message to <name>. The
 # member's watcher (watch.sh) sees it, drops its own role (releasing the actas
-# lock) and closes its own tmux pane — ending its CLI. We block until the lock
-# is released, up to --timeout (default 30s); on timeout the member didn't
-# respond (dead watcher, or a codex member with no Monitor) — re-run with
-# --force.
+# lock) and folds its OWN pane through the terminal driver named by its placement
+# record — so tmux AND herdr members fold themselves (a plain/OS-terminal member
+# has no addressable pane, so it drops its role and its window is closed by hand).
+# We block until the lock is released, up to --timeout; on timeout the member
+# didn't respond (dead watcher, or a monitor=no member with no watcher) — re-run
+# with --force. A `free` lock with a placement record is NOT proof the member is
+# gone (a monitor=no type never holds one): that reports `needs-force` and KEEPS
+# the record, rather than a false `ok` (#625).
 #
-# --force: skip the message and tear the member down from here using the
-# placement recorded at spawn time — kill its tmux pane/window and drop its
-# registration. For when the member's watcher can't respond.
+# --force: skip the message and tear the member down from here through the
+# terminal driver named by the placement record. The teardown must be CONFIRMED
+# (the ref resolves to a terminal, the driver loads, and terminal_despawn exits 0)
+# BEFORE the record / registration / lock are dropped — an unconfirmed teardown
+# keeps all three and reports `status=error`, so the record (the only retry
+# authority) is never deleted out from under a pane that is still alive (#625, the
+# --force side). For when the member's watcher can't respond.
 #
-# See #109. Graceful teardown's full pane-close is tmux-only (the member needs a
-# tmux pane to close); an OS-terminal member drops its role but its window must
-# be closed by hand.
+# See #109.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"  # actas-lock.sh requires SKILL_DIR
 # shellcheck disable=SC1091
 source "$SCRIPT_DIR/lib/actas-lock.sh"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/terminal-registry.sh"  # kill via the terminal driver
 
 die() { echo "despawn: $*" >&2; exit 1; }
 
@@ -50,33 +58,39 @@ case "$TIMEOUT" in ''|*[!0-9]*) die "--timeout must be a whole number of seconds
 
 SPAWN_REC="$(agmsg_spawn_path "$TEAM" "$NAME")"
 
-# Kill the recorded tmux target. ids are self-describing: %N pane, @N window.
+# Tear down the recorded placement through the terminal-driver registry, and PROVE
+# it (co1, full-head review). The record ref is <terminal>:<id> or a legacy bare
+# %N/@N; an unknown/corrupt ref does NOT resolve (agmsg_terminal_ref_terminal fails
+# closed). The teardown counts as confirmed only if the ref resolved, the driver
+# loaded, AND terminal_despawn exited 0 — a driver reporting runtime_error/13 (a real
+# possibility for tmux and herdr) means the pane may STILL be alive, and the caller
+# must keep the record rather than delete the one retry authority. Returns 0 on a
+# confirmed teardown, non-zero otherwise (no side effects here beyond the kill call).
 kill_recorded_placement() {
   [ -f "$SPAWN_REC" ] || return 1
-  local id _proj _type
+  local id _proj _type _term _bare
   IFS=$'\t' read -r id _proj _type < "$SPAWN_REC"
   [ -n "$id" ] || return 1
-  case "$id" in
-    herdr:*)
-      command -v herdr >/dev/null 2>&1 && herdr pane close "${id#herdr:}" 2>/dev/null || true
-      ;;
-    *)
-      if command -v tmux >/dev/null 2>&1; then
-        case "$id" in
-          %*) tmux kill-pane   -t "$id" 2>/dev/null || true ;;
-          @*) tmux kill-window -t "$id" 2>/dev/null || true ;;
-        esac
-      fi
-      ;;
-  esac
-  printf '%s\t%s\t%s' "$id" "$_proj" "$_type"   # echo back for the caller
+  _term="$(agmsg_terminal_ref_terminal "$id")" || return 1   # unknown/corrupt ref
+  _bare="$(agmsg_terminal_ref_id "$id")"
+  agmsg_terminal_load "$_term" 2>/dev/null || return 1       # driver would not load
+  terminal_despawn "$_bare" >/dev/null 2>&1 || return 1      # terminal did not confirm
+  return 0
 }
 
 if [ "$FORCE" = "1" ]; then
   [ -f "$SPAWN_REC" ] || die "no placement record for '$TEAM/$NAME' — nothing to force (was it launched via 'spawn'? graceful despawn does not need this)"
   IFS=$'\t' read -r _id _proj _type < "$SPAWN_REC"
-  kill_recorded_placement >/dev/null
-  # Drop the member's registration, and release its (now-stale) lock.
+  if ! kill_recorded_placement; then
+    # Teardown NOT confirmed. Keep the record (the only retry authority), the
+    # registration and the lock, and say so — never claim a forced teardown that did
+    # not happen (the #625 shape, on the --force side).
+    echo "despawn: could not confirm '$NAME' was torn down via its placement record ($_id) — the terminal driver did not report the pane closed (unknown/corrupt ref, the driver would not load, or the terminal returned an error). The record is KEPT so you can retry; check the pane manually." >&2
+    echo "status=error name=$NAME team=$TEAM note=force-teardown-unconfirmed"
+    exit 1
+  fi
+  # Confirmed torn down: NOW drop the registration, release the (stale) lock, and
+  # delete the record.
   if [ -n "${_proj:-}" ] && [ -n "${_type:-}" ]; then
     "$SCRIPT_DIR/reset.sh" "$_proj" "$_type" "$NAME" >/dev/null 2>&1 || true
   fi
@@ -91,8 +105,21 @@ fi
 state="$(actas_lock_state "$TEAM" "$NAME" "" 2>/dev/null || echo free)"
 case "$state" in
   free)
-    echo "despawn: '$NAME' holds no live actas lock — nothing to confirm a teardown against (a codex member has no watcher; a tmux member may already be gone). If a window remains, use --force." >&2
-    rm -f "$SPAWN_REC" 2>/dev/null || true
+    # #625: a free actas lock does NOT prove the member is gone. A monitor=no type
+    # (cursor, codex) never runs a watcher and so NEVER holds a lock; a member whose
+    # watcher merely died reads identically. So split on the placement record — the
+    # positive evidence that something was spawned and may still be running.
+    if [ -f "$SPAWN_REC" ]; then
+      # A pane/process was placed and is likely still there. Do NOT delete the record
+      # (--force reads exactly this — deleting it here is what made the advised
+      # recovery impossible), and do NOT report a teardown we did not perform.
+      echo "despawn: '$NAME' holds no live actas lock, but a placement record remains — graceful despawn cannot confirm a teardown (a monitor=no member such as cursor/codex never holds a lock; a watcher may have died). Retry with --force to tear it down via the record, which is kept intact." >&2
+      echo "status=needs-force name=$NAME team=$TEAM note=no-live-lock-recorded"
+      exit 1
+    fi
+    # No placement record: nothing was spawned here to tear down (a hand-joined
+    # member, or one already gone). The free lock is all there is to act on.
+    echo "despawn: '$NAME' holds no live actas lock and has no placement record — nothing to tear down here (if a window remains, it was not launched via spawn; close it directly)." >&2
     echo "status=ok name=$NAME team=$TEAM note=no-live-lock"
     exit 0
     ;;