robisie 0.1.0 → 0.1.1

package/helpers/client-spawn.sh

@@ -0,0 +1,825 @@
+#!/usr/bin/env bash
+# ROB_113 T1 — explicitly spawn one client-mode builder in a new terminal.
+# Credentials cross the terminal boundary only through the environment (or,
+# for the osascript fallback, a private one-shot FIFO). They never enter argv.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SESSION_RUNNER="$SCRIPT_DIR/client-spawn-session.sh"
+OWNER_PREFIX="robisie-client-spawn-v1"
+OWNER_VALUE=""
+RECLAIM_CLAIM_DIR=""
+RECLAIM_CLAIM_ALT_DIR=""
+RECLAIM_CLAIM_TOKEN=""
+TERMINAL_PROCESS_PID=""
+TERMINAL_IS_FOREGROUND=0
+
+usage() {
+  echo "usage: client-spawn.sh <card-ref> [--dry-run]" >&2
+}
+
+die() {
+  local code="$1"
+  shift
+  echo "client-spawn: $*" >&2
+  exit "$code"
+}
+
+is_nonnegative_number() {
+  [[ "$1" =~ ^[0-9]+([.][0-9]+)?$ ]]
+}
+
+is_positive_integer() {
+  [[ "$1" =~ ^[1-9][0-9]*$ ]]
+}
+
+render_command() {
+  local rendered="" arg quoted
+  for arg in "$@"; do
+    printf -v quoted '%q' "$arg"
+    [[ -n "$rendered" ]] && rendered+=" "
+    rendered+="$quoted"
+  done
+  printf '%s' "$rendered"
+}
+
+sha256_text() {
+  local value="$1" digest=""
+  if command -v sha256sum >/dev/null 2>&1; then
+    digest="$(printf '%s' "$value" | sha256sum)"
+  elif command -v shasum >/dev/null 2>&1; then
+    digest="$(printf '%s' "$value" | shasum -a 256)"
+  else
+    return 1
+  fi
+  digest="${digest%% *}"
+  [[ "$digest" =~ ^[0-9a-f]{64}$ ]] || return 1
+  printf '%s' "$digest"
+}
+
+path_mode_octal() {
+  local path="$1" value=""
+  if value="$(stat -f '%Lp' "$path" 2>/dev/null)" && [[ "$value" =~ ^[0-9]+$ ]]; then
+    printf '%s' "$value"
+    return 0
+  fi
+  value="$(stat -c '%a' "$path" 2>/dev/null)" || return 1
+  [[ "$value" =~ ^[0-9]+$ ]] || return 1
+  printf '%s' "$value"
+}
+
+find_terminal() {
+  local name="$1" found=""
+
+  if [[ -n "${ROBISIE_SPAWN_TERMINAL_PATH:-}" ]]; then
+    found="$(PATH="$ROBISIE_SPAWN_TERMINAL_PATH" command -v "$name" 2>/dev/null || true)"
+  elif [[ "$PLATFORM" == "darwin" && "$name" == "open" && -x /usr/bin/open ]]; then
+    found="/usr/bin/open"
+  else
+    found="$(command -v "$name" 2>/dev/null || true)"
+  fi
+
+  [[ -n "$found" ]] || return 1
+  printf '%s' "$found"
+}
+
+build_terminal_command() {
+  local bin=""
+  BACKEND=""
+  CMD=()
+  TERMINAL_IS_FOREGROUND=0
+
+  case "$PLATFORM" in
+    darwin)
+      if bin="$(find_terminal open)"; then
+        BACKEND="open"
+        CMD=("$bin" -n -a Terminal "$LAUNCH_FILE")
+      elif bin="$(find_terminal osascript)"; then
+        BACKEND="osascript"
+        CMD=(
+          "$bin"
+          -e 'on run argv'
+          -e 'set launchPath to item 1 of argv'
+          -e 'tell application "Terminal"'
+          -e 'activate'
+          -e 'do script "/bin/bash " & quoted form of launchPath'
+          -e 'end tell'
+          -e 'end run'
+          "$LAUNCH_FILE"
+        )
+      else
+        die 3 "no supported terminal for darwin (tried: open, osascript)"
+      fi
+      ;;
+    linux)
+      if bin="$(find_terminal gnome-terminal)"; then
+        BACKEND="gnome-terminal"
+        CMD=("$bin" --window -- "$LAUNCH_FILE")
+      elif bin="$(find_terminal xterm)"; then
+        BACKEND="xterm"
+        TERMINAL_IS_FOREGROUND=1
+        CMD=("$bin" -T Robisie -e "$LAUNCH_FILE")
+      elif bin="$(find_terminal alacritty)"; then
+        BACKEND="alacritty"
+        TERMINAL_IS_FOREGROUND=1
+        CMD=("$bin" --title Robisie --command "$LAUNCH_FILE")
+      else
+        die 3 "no supported terminal for linux (tried: gnome-terminal, xterm, alacritty)"
+      fi
+      ;;
+    windows)
+      if bin="$(find_terminal wt.exe)" || bin="$(find_terminal wt)"; then
+        BACKEND="wt"
+        CMD=("$bin" -w new nt --inheritEnvironment bash "$LAUNCH_FILE")
+      elif bin="$(find_terminal cmd.exe)"; then
+        BACKEND="start"
+        CMD=("$bin" /d /v:off /s /c 'set "BASH_ENV=%ROBISIE_BOOTSTRAP_CMD%" && start "" bash -c :')
+      elif bin="$(find_terminal powershell.exe)" || bin="$(find_terminal pwsh.exe)"; then
+        BACKEND="powershell"
+        CMD=(
+          "$bin" -NoLogo -NoProfile -NonInteractive -Command
+          "\$env:BASH_ENV=\$env:ROBISIE_BOOTSTRAP_CMD; Start-Process -FilePath 'bash' -ArgumentList @('-c', ':')"
+        )
+      else
+        die 3 "no supported terminal for windows (tried: wt, start, PowerShell)"
+      fi
+      ;;
+    *)
+      die 2 "unsupported platform: $PLATFORM"
+      ;;
+  esac
+}
+
+pid_file_is_alive() {
+  local file="$1" pid=""
+  [[ -f "$file" ]] || return 1
+  IFS= read -r pid < "$file" || return 1
+  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+path_mtime_epoch() {
+  local path="$1" value=""
+  if value="$(stat -f '%m' "$path" 2>/dev/null)" && [[ "$value" =~ ^[0-9]+$ ]]; then
+    printf '%s' "$value"
+    return 0
+  fi
+  value="$(stat -c '%Y' "$path" 2>/dev/null)" || return 1
+  [[ "$value" =~ ^[0-9]+$ ]] || return 1
+  printf '%s' "$value"
+}
+
+read_state_owner() {
+  local dir="$1" marker=""
+  [[ -f "$dir/.owner" ]] || return 1
+  IFS= read -r marker < "$dir/.owner" || return 1
+  [[ "$marker" =~ ^robisie-client-spawn-v1:[[:alnum:]._-]+$ ]] || return 1
+  printf '%s' "$marker"
+}
+
+state_artifact_path() {
+  local dir="$1" owner="$2" artifact="$3" generation
+  generation="${owner#*:}"
+  [[ -n "$generation" && "$generation" != "$owner" ]] || return 1
+  case "$artifact" in
+    runner-claim) printf '%s/runner.claim.%s' "$dir" "$generation" ;;
+    runner-pid) printf '%s/runner.%s.pid' "$dir" "$generation" ;;
+    agent-pid) printf '%s/agent.%s.pid' "$dir" "$generation" ;;
+    ready) printf '%s/ready.%s' "$dir" "$generation" ;;
+    failed) printf '%s/failed.%s' "$dir" "$generation" ;;
+    token-fifo) printf '%s/token.%s.fifo' "$dir" "$generation" ;;
+    token-writer-pid) printf '%s/token-writer.%s.pid' "$dir" "$generation" ;;
+    *) return 1 ;;
+  esac
+}
+
+owned_state_dir() {
+  local dir="$1" expected="${2:-}" marker=""
+  case "$dir" in
+    "$STATE_ROOT"/*.lock|"$STATE_ROOT"/*.lock.stale.*) ;;
+    *) return 1 ;;
+  esac
+  marker="$(read_state_owner "$dir")" || return 1
+  [[ -z "$expected" || "$marker" == "$expected" ]]
+}
+
+cleanup_owned_state() {
+  local dir="$1" expected="$2"
+  [[ -n "$expected" ]] || return 1
+  owned_state_dir "$dir" "$expected" || return 1
+  rm -rf -- "$dir"
+}
+
+existing_state_is_active() {
+  local created="" now age owner agent_pid runner_pid failed
+
+  owner="$(read_state_owner "$STATE_DIR")" || return 1
+  agent_pid="$(state_artifact_path "$STATE_DIR" "$owner" agent-pid)" || return 1
+  runner_pid="$(state_artifact_path "$STATE_DIR" "$owner" runner-pid)" || return 1
+  failed="$(state_artifact_path "$STATE_DIR" "$owner" failed)" || return 1
+
+  if pid_file_is_alive "$agent_pid" || pid_file_is_alive "$runner_pid"; then
+    return 0
+  fi
+
+  [[ -f "$failed" ]] && return 1
+  if [[ -f "$STATE_DIR/created-at" ]]; then
+    IFS= read -r created < "$STATE_DIR/created-at" || return 1
+    [[ "$created" =~ ^[0-9]+$ ]] || return 1
+  else
+    # A second launcher can observe the directory between atomic mkdir and
+    # the created-at write. Use the owner marker's mtime for that tiny window
+    # instead of reclaiming a lock that is still being initialized.
+    created="$(path_mtime_epoch "$STATE_DIR/.owner" || true)"
+    [[ "$created" =~ ^[0-9]+$ ]] || return 0
+  fi
+  now="$(date +%s)"
+  age=$((now - created))
+  [[ "$age" -ge 0 && "$age" -lt "$STALE_SEC" ]]
+}
+
+initialize_card_lock() {
+  local created_now
+  mkdir "$STATE_DIR" 2>/dev/null || return 1
+  created_now="$(date +%s)"
+  if {
+    printf '%s\n' "$OWNER_VALUE" > "$STATE_DIR/.owner" &&
+    printf '%s\n' "$created_now" > "$STATE_DIR/created-at"
+  }; then
+    return 0
+  fi
+
+  rm -f "$STATE_DIR/.owner" "$STATE_DIR/created-at" 2>/dev/null || true
+  rmdir "$STATE_DIR" 2>/dev/null || true
+  return 2
+}
+
+release_reclaim_claim() {
+  local claim_dir="$1" claim_token="$2" recorded=""
+  [[ -f "$claim_dir/claimant" ]] || return 1
+  IFS= read -r recorded < "$claim_dir/claimant" || return 1
+  [[ "$recorded" == "$claim_token" ]] || return 1
+  rm -f "$claim_dir/claimant" "$claim_dir/pid" "$claim_dir/created-at" || return 1
+  rmdir "$claim_dir"
+}
+
+clear_reclaim_claim_tracking() {
+  RECLAIM_CLAIM_DIR=""
+  RECLAIM_CLAIM_ALT_DIR=""
+  RECLAIM_CLAIM_TOKEN=""
+}
+
+# Invoked indirectly by the EXIT trap installed before argument parsing.
+# shellcheck disable=SC2329
+cleanup_reclaim_claim_on_exit() {
+  if [[ -n "$RECLAIM_CLAIM_TOKEN" ]]; then
+    [[ -z "$RECLAIM_CLAIM_DIR" ]] || release_reclaim_claim "$RECLAIM_CLAIM_DIR" "$RECLAIM_CLAIM_TOKEN" 2>/dev/null || true
+    [[ -z "$RECLAIM_CLAIM_ALT_DIR" ]] || release_reclaim_claim "$RECLAIM_CLAIM_ALT_DIR" "$RECLAIM_CLAIM_TOKEN" 2>/dev/null || true
+  fi
+}
+
+reclaim_claim_is_abandoned() {
+  local claim_dir="$1" expected_owner="$2" current_owner="" claimant_pid="" created="" now age
+  [[ -d "$claim_dir" ]] || return 1
+  current_owner="$(read_state_owner "$STATE_DIR" || true)"
+  [[ "$current_owner" == "$expected_owner" ]] || return 1
+
+  if [[ -f "$claim_dir/pid" ]]; then
+    IFS= read -r claimant_pid < "$claim_dir/pid" || claimant_pid=""
+    if [[ "$claimant_pid" =~ ^[0-9]+$ ]]; then
+      kill -0 "$claimant_pid" 2>/dev/null && return 1
+      return 0
+    fi
+  fi
+
+  if [[ -f "$claim_dir/created-at" ]]; then
+    IFS= read -r created < "$claim_dir/created-at" || created=""
+  else
+    created="$(path_mtime_epoch "$claim_dir" || true)"
+  fi
+  [[ "$created" =~ ^[0-9]+$ ]] || return 1
+  now="$(date +%s)"
+  age=$((now - created))
+  [[ "$age" -ge 2 ]]
+}
+
+remove_abandoned_reclaim_claim() {
+  local claim_dir="$1" expected_owner="$2" current_owner=""
+  reclaim_claim_is_abandoned "$claim_dir" "$expected_owner" || return 1
+  current_owner="$(read_state_owner "$STATE_DIR" || true)"
+  [[ "$current_owner" == "$expected_owner" ]] || return 1
+  rm -f "$claim_dir/claimant" "$claim_dir/pid" "$claim_dir/created-at" || return 1
+  rmdir "$claim_dir"
+}
+
+acquire_card_lock() {
+  local stale_dir stale_owner moved_owner moved_claim init_rc candidate_owner generation
+  local claim_dir claim_token current_owner claim_deadline
+  claim_deadline=$((SECONDS + 5))
+
+  while true; do
+    if initialize_card_lock; then
+      return 0
+    else
+      init_rc=$?
+    fi
+    [[ "$init_rc" -eq 1 ]] || die 4 "cannot initialize card lock"
+
+    [[ -d "$STATE_DIR" ]] || {
+      [[ "$SECONDS" -lt "$claim_deadline" ]] || die 4 "cannot create card lock: $STATE_DIR"
+      sleep "$POLL_INTERVAL_SEC"
+      continue
+    }
+    if ! owned_state_dir "$STATE_DIR"; then
+      # Another launcher can be between its atomic mkdir and the first complete
+      # owner/created-at writes. Wait only for that incomplete shape; a fully
+      # formed foreign marker still fails closed immediately.
+      if [[ "$SECONDS" -lt "$claim_deadline" ]] && { [[ ! -s "$STATE_DIR/.owner" ]] || [[ ! -f "$STATE_DIR/created-at" ]]; }; then
+        sleep "$POLL_INTERVAL_SEC"
+        continue
+      fi
+      die 4 "refusing unowned state collision for card=$CARD_REF"
+    fi
+
+    if existing_state_is_active; then
+      echo "ALREADY_RUNNING card=$CARD_REF"
+      exit 0
+    fi
+
+    candidate_owner="$(read_state_owner "$STATE_DIR")" || die 4 "cannot read stale state owner for card=$CARD_REF"
+    generation="${candidate_owner#*:}"
+    claim_dir="$STATE_DIR/reclaim.claim.$generation"
+    claim_token="$$-$RANDOM-$(date +%s)"
+
+    if ! mkdir "$claim_dir" 2>/dev/null; then
+      if remove_abandoned_reclaim_claim "$claim_dir" "$candidate_owner" 2>/dev/null; then
+        continue
+      fi
+      [[ "$SECONDS" -lt "$claim_deadline" ]] || die 4 "stale reclaim is busy for card=$CARD_REF"
+      sleep "$POLL_INTERVAL_SEC"
+      continue
+    fi
+    if ! {
+      printf '%s\n' "$claim_token" > "$claim_dir/claimant" &&
+      printf '%s\n' "$$" > "$claim_dir/pid" &&
+      printf '%s\n' "$(date +%s)" > "$claim_dir/created-at"
+    }; then
+      rm -f "$claim_dir/claimant" "$claim_dir/pid" "$claim_dir/created-at" 2>/dev/null || true
+      rmdir "$claim_dir" 2>/dev/null || true
+      die 4 "cannot initialize stale reclaim claim for card=$CARD_REF"
+    fi
+    RECLAIM_CLAIM_DIR="$claim_dir"
+    RECLAIM_CLAIM_ALT_DIR=""
+    RECLAIM_CLAIM_TOKEN="$claim_token"
+
+    current_owner="$(read_state_owner "$STATE_DIR" || true)"
+    if [[ "$current_owner" != "$candidate_owner" ]]; then
+      release_reclaim_claim "$claim_dir" "$claim_token" || true
+      clear_reclaim_claim_tracking
+      [[ "$SECONDS" -lt "$claim_deadline" ]] || die 4 "state generation changed during stale reclaim for card=$CARD_REF"
+      sleep "$POLL_INTERVAL_SEC"
+      continue
+    fi
+
+    if existing_state_is_active; then
+      release_reclaim_claim "$claim_dir" "$claim_token" || die 4 "cannot release reclaim claim for active card=$CARD_REF"
+      clear_reclaim_claim_tracking
+      echo "ALREADY_RUNNING card=$CARD_REF"
+      exit 0
+    fi
+
+    stale_owner="$candidate_owner"
+    stale_dir="$STATE_DIR.stale.$$-$RANDOM"
+    RECLAIM_CLAIM_ALT_DIR="$stale_dir/reclaim.claim.$generation"
+    if ! mv "$STATE_DIR" "$stale_dir" 2>/dev/null; then
+      release_reclaim_claim "$claim_dir" "$claim_token" 2>/dev/null || true
+      clear_reclaim_claim_tracking
+      [[ "$SECONDS" -lt "$claim_deadline" ]] || die 4 "could not reclaim stale card lock for card=$CARD_REF"
+      sleep "$POLL_INTERVAL_SEC"
+      continue
+    fi
+    RECLAIM_CLAIM_DIR="$RECLAIM_CLAIM_ALT_DIR"
+    RECLAIM_CLAIM_ALT_DIR=""
+
+    moved_owner="$(read_state_owner "$stale_dir" || true)"
+    if [[ "$moved_owner" != "$stale_owner" ]]; then
+      moved_claim="$stale_dir/reclaim.claim.$generation"
+      release_reclaim_claim "$moved_claim" "$claim_token" 2>/dev/null || true
+      clear_reclaim_claim_tracking
+      if [[ ! -e "$STATE_DIR" ]]; then
+        mv "$stale_dir" "$STATE_DIR" 2>/dev/null || true
+      fi
+      die 4 "state generation changed while moving stale lock for card=$CARD_REF"
+    fi
+
+    cleanup_owned_state "$stale_dir" "$stale_owner" || die 4 "could not remove stale owned state for card=$CARD_REF"
+    clear_reclaim_claim_tracking
+
+    if initialize_card_lock; then
+      return 0
+    else
+      init_rc=$?
+    fi
+    [[ "$init_rc" -eq 1 ]] || die 4 "cannot initialize reclaimed card lock"
+    if [[ -d "$STATE_DIR" ]] && owned_state_dir "$STATE_DIR" && existing_state_is_active; then
+      echo "ALREADY_RUNNING card=$CARD_REF"
+      exit 0
+    fi
+    [[ "$SECONDS" -lt "$claim_deadline" ]] || die 4 "card lock raced during reclaim for card=$CARD_REF"
+    sleep "$POLL_INTERVAL_SEC"
+  done
+}
+
+write_owned_line() {
+  local path="$1" value="$2"
+  owned_state_dir "$STATE_DIR" "$OWNER_VALUE" || return 1
+  printf '%s\n' "$value" > "$path"
+}
+
+write_spawn_state() {
+  local runner_q state_q owner_q card_q
+  printf -v runner_q '%q' "$SESSION_RUNNER"
+  printf -v state_q '%q' "$STATE_DIR"
+  printf -v owner_q '%q' "$OWNER_VALUE"
+  printf -v card_q '%q' "$CARD_REF"
+
+  if ! {
+    write_owned_line "$STATE_DIR/card-ref" "$CARD_REF" &&
+    write_owned_line "$STATE_DIR/project-context" "$PROJECT_CONTEXT" &&
+    write_owned_line "$STATE_DIR/agent-command" "$AGENT_COMMAND" &&
+    write_owned_line "$STATE_DIR/boot-grace" "$BOOT_GRACE_SEC" &&
+    write_owned_line "$STATE_DIR/transcript-path" "${ROBISIE_SPAWN_TRANSCRIPT:-}" &&
+    owned_state_dir "$STATE_DIR" "$OWNER_VALUE" &&
+    {
+      printf '%s\n' '#!/usr/bin/env bash'
+      printf '%s\n' 'unset BASH_ENV'
+      printf 'exec /bin/bash %s %s %s %s\n' "$runner_q" "$state_q" "$owner_q" "$card_q"
+    } > "$LAUNCH_FILE" &&
+    owned_state_dir "$STATE_DIR" "$OWNER_VALUE" &&
+    chmod 700 "$LAUNCH_FILE"
+  }; then
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+    die 4 "failed to write spawn state"
+  fi
+}
+
+stop_token_writer() {
+  if [[ -n "${TOKEN_WRITER_PID:-}" ]]; then
+    if kill -0 "$TOKEN_WRITER_PID" 2>/dev/null; then
+      kill "$TOKEN_WRITER_PID" 2>/dev/null || true
+    fi
+    wait "$TOKEN_WRITER_PID" 2>/dev/null || true
+    TOKEN_WRITER_PID=""
+  fi
+  if [[ -n "${TOKEN_WRITER_PID_FILE:-}" ]] && owned_state_dir "${STATE_DIR:-}" "$OWNER_VALUE"; then
+    rm -f "$TOKEN_WRITER_PID_FILE" 2>/dev/null || true
+  fi
+}
+
+# Invoked from the EXIT-trap call graph below.
+# shellcheck disable=SC2329
+wait_for_token_writer_delivery() {
+  local rounds=0 writer_rc=0
+  [[ -n "${TOKEN_WRITER_PID:-}" ]] || return 0
+  while kill -0 "$TOKEN_WRITER_PID" 2>/dev/null && [[ "$rounds" -lt 100 ]]; do
+    sleep 0.05
+    rounds=$((rounds + 1))
+  done
+  kill -0 "$TOKEN_WRITER_PID" 2>/dev/null && return 1
+  if wait "$TOKEN_WRITER_PID" 2>/dev/null; then writer_rc=0; else writer_rc=$?; fi
+  TOKEN_WRITER_PID=""
+  if [[ -n "${TOKEN_WRITER_PID_FILE:-}" ]] && owned_state_dir "${STATE_DIR:-}" "$OWNER_VALUE"; then
+    rm -f "$TOKEN_WRITER_PID_FILE" 2>/dev/null || true
+  fi
+  [[ "$writer_rc" -eq 0 ]]
+}
+
+# Invoked from the EXIT-trap call graph below.
+# shellcheck disable=SC2329
+abort_token_handoff() {
+  local rounds=0 runner_pid=""
+  stop_token_writer
+  if [[ -n "${TOKEN_FIFO:-}" ]] && owned_state_dir "${STATE_DIR:-}" "$OWNER_VALUE"; then
+    rm -f "$TOKEN_FIFO" 2>/dev/null || true
+  fi
+  while [[ "$rounds" -lt 100 ]]; do
+    if [[ -n "${RUNNER_PID_FILE:-}" ]] && pid_file_is_alive "$RUNNER_PID_FILE"; then
+      :
+    elif [[ "$rounds" -lt 20 && -n "${RUNNER_CLAIM:-}" && -d "$RUNNER_CLAIM" && ! -f "${RUNNER_PID_FILE:-}" ]]; then
+      : # Claim-to-PID initialization window.
+    else
+      break
+    fi
+    sleep 0.05
+    rounds=$((rounds + 1))
+  done
+  if [[ -n "${RUNNER_PID_FILE:-}" ]] && pid_file_is_alive "$RUNNER_PID_FILE"; then
+    IFS= read -r runner_pid < "$RUNNER_PID_FILE" || runner_pid=""
+    [[ "$runner_pid" =~ ^[0-9]+$ ]] && kill -TERM "$runner_pid" 2>/dev/null || true
+    sleep 0.1
+  fi
+  if [[ -n "${STATE_DIR:-}" && -n "$OWNER_VALUE" ]] &&
+    ! pid_file_is_alive "${RUNNER_PID_FILE:-}" &&
+    ! pid_file_is_alive "${AGENT_PID_FILE:-}"; then
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" 2>/dev/null || true
+  fi
+}
+
+stop_terminal_process() {
+  if [[ -n "$TERMINAL_PROCESS_PID" ]] && kill -0 "$TERMINAL_PROCESS_PID" 2>/dev/null; then
+    kill "$TERMINAL_PROCESS_PID" 2>/dev/null || true
+    wait "$TERMINAL_PROCESS_PID" 2>/dev/null || true
+  fi
+  TERMINAL_PROCESS_PID=""
+}
+
+# Invoked from the signal-handler call graph below.
+# shellcheck disable=SC2329
+current_generation_has_runner() {
+  [[ -n "${RUNNER_CLAIM:-}" && -d "$RUNNER_CLAIM" ]] ||
+    { [[ -n "${RUNNER_PID_FILE:-}" ]] && pid_file_is_alive "$RUNNER_PID_FILE"; } ||
+    { [[ -n "${AGENT_PID_FILE:-}" ]] && pid_file_is_alive "$AGENT_PID_FILE"; }
+}
+
+# Invoked indirectly by INT/TERM traps installed below.
+# shellcheck disable=SC2329
+handle_signal() {
+  local code="$1"
+  if ! current_generation_has_runner; then
+    stop_token_writer
+    stop_terminal_process
+    if [[ -n "${STATE_DIR:-}" && -n "$OWNER_VALUE" ]]; then
+      cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" 2>/dev/null || true
+    fi
+  fi
+  exit "$code"
+}
+
+# Invoked indirectly by the EXIT trap installed below.
+# shellcheck disable=SC2329
+cleanup_on_exit() {
+  if [[ -n "${TOKEN_WRITER_PID:-}" ]]; then
+    if current_generation_has_runner; then
+      wait_for_token_writer_delivery || abort_token_handoff
+    else
+      abort_token_handoff
+      if [[ -n "${STATE_DIR:-}" && -n "$OWNER_VALUE" ]]; then
+        cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" 2>/dev/null || true
+      fi
+    fi
+  fi
+  cleanup_reclaim_claim_on_exit
+}
+
+trap cleanup_on_exit EXIT
+trap 'handle_signal 130' INT
+trap 'handle_signal 143' TERM
+trap 'handle_signal 129' HUP
+trap 'handle_signal 131' QUIT
+
+CARD_REF=""
+DRY_RUN=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --*)
+      usage
+      die 2 "unknown option: $1"
+      ;;
+    *)
+      [[ -z "$CARD_REF" ]] || {
+        usage
+        die 2 "exactly one card-ref is required"
+      }
+      CARD_REF="$1"
+      shift
+      ;;
+  esac
+done
+
+[[ -n "$CARD_REF" ]] || {
+  usage
+  die 2 "card-ref is required"
+}
+[[ "$CARD_REF" =~ ^[[:alnum:]][[:alnum:].:_-]{0,127}$ ]] || die 2 "invalid card-ref: use 1-128 alphanumeric/._:- characters"
+CARD_DIGEST="$(sha256_text "$CARD_REF")" || die 2 "sha256sum or shasum is required to derive a portable card lock"
+STATE_KEY="card-$CARD_DIGEST"
+
+PROJECT_CONTEXT="${ROBISIE_PROJECT_CONTEXT:-$PWD}"
+[[ "$PROJECT_CONTEXT" != *$'\n'* && -d "$PROJECT_CONTEXT" ]] || die 2 "ROBISIE_PROJECT_CONTEXT must be an existing single-line directory"
+if [[ "$PROJECT_CONTEXT" != /* ]]; then
+  PROJECT_CONTEXT="$PWD/$PROJECT_CONTEXT"
+fi
+
+AGENT_COMMAND="${ROBISIE_AGENT_COMMAND:-claude --agent manager-builder}"
+[[ -n "$AGENT_COMMAND" && "$AGENT_COMMAND" != *$'\n'* ]] || die 2 "ROBISIE_AGENT_COMMAND must be a non-empty single line"
+
+BOOT_TIMEOUT_SEC="${ROBISIE_SPAWN_BOOT_TIMEOUT_SEC:-20}"
+BOOT_GRACE_SEC="${ROBISIE_SPAWN_BOOT_GRACE_SEC:-1}"
+POLL_INTERVAL_SEC="${ROBISIE_SPAWN_POLL_INTERVAL_SEC:-0.25}"
+MAX_ATTEMPTS="${ROBISIE_SPAWN_MAX_ATTEMPTS:-3}"
+BACKOFF_SEC="${ROBISIE_SPAWN_BACKOFF_SEC:-1}"
+STALE_SEC="${ROBISIE_SPAWN_STALE_SEC:-60}"
+is_positive_integer "$BOOT_TIMEOUT_SEC" || die 2 "ROBISIE_SPAWN_BOOT_TIMEOUT_SEC must be a positive integer"
+is_nonnegative_number "$BOOT_GRACE_SEC" || die 2 "ROBISIE_SPAWN_BOOT_GRACE_SEC must be non-negative"
+is_nonnegative_number "$POLL_INTERVAL_SEC" || die 2 "ROBISIE_SPAWN_POLL_INTERVAL_SEC must be non-negative"
+is_positive_integer "$MAX_ATTEMPTS" || die 2 "ROBISIE_SPAWN_MAX_ATTEMPTS must be a positive integer"
+is_nonnegative_number "$BACKOFF_SEC" || die 2 "ROBISIE_SPAWN_BACKOFF_SEC must be non-negative"
+is_positive_integer "$STALE_SEC" || die 2 "ROBISIE_SPAWN_STALE_SEC must be a positive integer"
+
+PLATFORM="${ROBISIE_SPAWN_PLATFORM:-}"
+if [[ -z "$PLATFORM" ]]; then
+  case "$(uname -s 2>/dev/null || true)" in
+    Darwin) PLATFORM="darwin" ;;
+    Linux) PLATFORM="linux" ;;
+    MINGW*|MSYS*|CYGWIN*) PLATFORM="windows" ;;
+    *) die 2 "unsupported platform: $(uname -s 2>/dev/null || echo unknown)" ;;
+  esac
+fi
+case "$PLATFORM" in darwin|linux|windows) ;; *) die 2 "unsupported platform: $PLATFORM" ;; esac
+
+if [[ "$PLATFORM" == "windows" && -z "${ROBISIE_SPAWN_STATE_ROOT:-}" ]]; then
+  WINDOWS_USER_STATE_BASE="${LOCALAPPDATA:-${USERPROFILE:-}}"
+  [[ -n "$WINDOWS_USER_STATE_BASE" ]] || die 2 "LOCALAPPDATA or USERPROFILE is required for private Windows state"
+  command -v cygpath >/dev/null 2>&1 || die 2 "cygpath is required for private Windows state"
+  DEFAULT_STATE_BASE="$(cygpath -u "$WINDOWS_USER_STATE_BASE")/Robisie"
+  STATE_ROOT="$DEFAULT_STATE_BASE/client-spawn"
+else
+  DEFAULT_STATE_BASE="${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}"
+  STATE_ROOT="${ROBISIE_SPAWN_STATE_ROOT:-$DEFAULT_STATE_BASE/robisie-client-spawn-${UID:-$(id -u)}}"
+fi
+[[ -n "$STATE_ROOT" && "$STATE_ROOT" == /* && "$STATE_ROOT" != *$'\n'* ]] || die 2 "ROBISIE_SPAWN_STATE_ROOT must be an absolute single-line path"
+STATE_DIR="$STATE_ROOT/$STATE_KEY.lock"
+LAUNCH_FILE="$STATE_DIR/launch.command"
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  build_terminal_command
+  echo "DRY-RUN platform=$PLATFORM backend=$BACKEND"
+  echo "ENV ROBISIE_CARD_REF=$CARD_REF ROBISIE_KEY=<redacted> ROBISIE_PROJECT_CONTEXT=$PROJECT_CONTEXT"
+  echo "COMMAND $(render_command "${CMD[@]}")"
+  exit 0
+fi
+
+[[ -n "${ROBISIE_KEY:-}" ]] || die 2 "ROBISIE_KEY is required for a real spawn"
+[[ -x "$SESSION_RUNNER" ]] || die 4 "session runner is missing or not executable: $SESSION_RUNNER"
+if [[ "$PLATFORM" == "windows" && -n "${ROBISIE_SPAWN_STATE_ROOT:-}" ]]; then
+  die 2 "real Windows spawn requires the per-user LOCALAPPDATA state root"
+fi
+
+umask 077
+if [[ -L "$STATE_ROOT" || ( -e "$STATE_ROOT" && ! -d "$STATE_ROOT" ) ]]; then
+  die 4 "private state root must be a regular directory, not a symlink: $STATE_ROOT"
+fi
+mkdir -p "$STATE_ROOT" || die 4 "cannot create state root: $STATE_ROOT"
+if [[ -L "$STATE_ROOT" || ! -d "$STATE_ROOT" || ! -O "$STATE_ROOT" ]]; then
+  die 4 "private state root must be owned by the current user: $STATE_ROOT"
+fi
+chmod 700 "$STATE_ROOT" || die 4 "cannot secure private state root: $STATE_ROOT"
+if [[ "$PLATFORM" != "windows" ]]; then
+  [[ "$(path_mode_octal "$STATE_ROOT" || true)" == "700" ]] || die 4 "private state root permissions must be 700: $STATE_ROOT"
+fi
+STATE_ROOT="$(cd "$STATE_ROOT" && pwd -P)"
+[[ -d "$STATE_ROOT" && -O "$STATE_ROOT" ]] || die 4 "private state root ownership changed during setup"
+STATE_DIR="$STATE_ROOT/$STATE_KEY.lock"
+LAUNCH_FILE="$STATE_DIR/launch.command"
+
+if [[ -d "$STATE_DIR" ]] && owned_state_dir "$STATE_DIR" && existing_state_is_active; then
+  echo "ALREADY_RUNNING card=$CARD_REF"
+  exit 0
+fi
+
+build_terminal_command
+OWNER_VALUE="$OWNER_PREFIX:$(date +%s)-$$-$RANDOM"
+RUNNER_CLAIM="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" runner-claim)"
+RUNNER_PID_FILE="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" runner-pid)"
+AGENT_PID_FILE="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" agent-pid)"
+READY_FILE="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" ready)"
+FAILED_FILE="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" failed)"
+TOKEN_FIFO="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" token-fifo)"
+TOKEN_WRITER_PID_FILE="$(state_artifact_path "$STATE_DIR" "$OWNER_VALUE" token-writer-pid)"
+acquire_card_lock
+write_spawn_state
+
+export ROBISIE_BOOTSTRAP_CMD="$LAUNCH_FILE"
+TOKEN_WRITER_PID=""
+if [[ "$BACKEND" == "osascript" ]]; then
+  if ! owned_state_dir "$STATE_DIR" "$OWNER_VALUE" || ! mkfifo "$TOKEN_FIFO"; then
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+    die 4 "cannot create private credential FIFO"
+  fi
+  if ! owned_state_dir "$STATE_DIR" "$OWNER_VALUE" || ! chmod 600 "$TOKEN_FIFO"; then
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+    die 4 "cannot secure private credential FIFO"
+  fi
+  (printf '%s\n' "$ROBISIE_KEY" > "$TOKEN_FIFO") &
+  TOKEN_WRITER_PID=$!
+  if ! write_owned_line "$TOKEN_WRITER_PID_FILE" "$TOKEN_WRITER_PID"; then
+    stop_token_writer
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+    die 4 "cannot record credential writer pid"
+  fi
+fi
+
+attempt=1
+launched=0
+last_rc=0
+boot_deadline=$((SECONDS + BOOT_TIMEOUT_SEC))
+while [[ "$attempt" -le "$MAX_ATTEMPTS" ]]; do
+  if [[ "$TERMINAL_IS_FOREGROUND" -eq 1 ]]; then
+    "${CMD[@]}" &
+    TERMINAL_PROCESS_PID=$!
+    while [[ "$SECONDS" -lt "$boot_deadline" ]]; do
+      if owned_state_dir "$STATE_DIR" "$OWNER_VALUE" && { [[ -d "$RUNNER_CLAIM" ]] || pid_file_is_alive "$RUNNER_PID_FILE"; }; then
+        launched=1
+        break
+      fi
+      kill -0 "$TERMINAL_PROCESS_PID" 2>/dev/null || break
+      sleep "$POLL_INTERVAL_SEC"
+    done
+    if [[ "$launched" -eq 1 ]]; then
+      break
+    fi
+    if kill -0 "$TERMINAL_PROCESS_PID" 2>/dev/null; then
+      # A foreground emulator that remains alive owns the window; the common
+      # readiness deadline below will report a bounded boot timeout.
+      launched=1
+      break
+    fi
+    if wait "$TERMINAL_PROCESS_PID"; then last_rc=0; else last_rc=$?; fi
+    TERMINAL_PROCESS_PID=""
+  elif "${CMD[@]}"; then
+    launched=1
+    break
+  else
+    last_rc=$?
+  fi
+
+  if owned_state_dir "$STATE_DIR" "$OWNER_VALUE" && { [[ -d "$RUNNER_CLAIM" ]] || pid_file_is_alive "$RUNNER_PID_FILE"; }; then
+    launched=1
+    break
+  fi
+
+  if [[ "$attempt" -lt "$MAX_ATTEMPTS" ]]; then
+    sleep "$BACKOFF_SEC"
+  fi
+  attempt=$((attempt + 1))
+done
+
+if [[ "$launched" -ne 1 ]]; then
+  stop_token_writer
+  stop_terminal_process
+  cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+  die 4 "terminal launch failed after $MAX_ATTEMPTS attempt(s) (last exit $last_rc)"
+fi
+
+deadline="$boot_deadline"
+while [[ "$SECONDS" -lt "$deadline" ]]; do
+  if ! owned_state_dir "$STATE_DIR" "$OWNER_VALUE"; then
+    stop_token_writer
+    stop_terminal_process
+    die 4 "spawn state generation changed before readiness"
+  fi
+
+  if [[ -f "$READY_FILE" ]]; then
+    stop_token_writer
+    echo "SPAWNED card=$CARD_REF platform=$PLATFORM backend=$BACKEND"
+    exit 0
+  fi
+
+  if [[ -f "$FAILED_FILE" ]]; then
+    reason="agent exited before readiness"
+    IFS= read -r reason < "$FAILED_FILE" || true
+    stop_token_writer
+    stop_terminal_process
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+    die 4 "$reason"
+  fi
+
+  sleep "$POLL_INTERVAL_SEC"
+done
+
+if [[ -n "${TOKEN_WRITER_PID:-}" ]]; then
+  if pid_file_is_alive "$AGENT_PID_FILE"; then
+    wait_for_token_writer_delivery || abort_token_handoff
+  elif kill -0 "$TOKEN_WRITER_PID" 2>/dev/null; then
+    abort_token_handoff
+  else
+    wait_for_token_writer_delivery || abort_token_handoff
+  fi
+fi
+if owned_state_dir "$STATE_DIR" "$OWNER_VALUE"; then
+  if pid_file_is_alive "$AGENT_PID_FILE" || pid_file_is_alive "$RUNNER_PID_FILE" || [[ -d "$RUNNER_CLAIM" ]]; then
+    : # Preserve the live generation; a later invocation must remain a no-op.
+  else
+    stop_terminal_process
+    cleanup_owned_state "$STATE_DIR" "$OWNER_VALUE" || true
+  fi
+fi
+die 4 "boot timeout after ${BOOT_TIMEOUT_SEC}s"