@pmelab/gtd 8.6.0 → 9.1.0

package/bin/gtd

@@ -1,878 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# This file is the single published `bin` entry: `bin/gtd`. Before anything
-# else, it dispatches on $1:
-#   - `--once` (bare, or immediately after `loop`) -> stripped here; restricts
-#     the loop to exactly one beat (one human-gate capture, one script
-#     check+step, or one agent prompt+step) before exiting. Dispatch then
-#     continues on the remaining arguments as if it had never been given.
-#   - no arguments, or exactly `loop` with no further arguments -> fall through
-#     into the loop body below (the loop protocol comment further down).
-#   - `loop` with an unrecognised extra argument -> usage error, exit 2.
-#   - anything else -> a WRITE subcommand (`step`, the `--entry` forms,
-#     `abandon`, `restore` — see `is_write_command`) routes through
-#     `run_gtd_command`, which actually performs the bundle's emitted
-#     `required`/`optional` scripts (the bundle itself only ever PRINTS them
-#     now); everything else (`status`, `next`, `validate`, `visualize`, `lsp`,
-#     `check`, `init`) hands off straight to the bundle via `run_gtd`,
-#     forwarding all arguments unchanged (e.g. `bin/gtd status`).
-# The loop's whole job is to drive the process until it rests at a
-# NON-AUTONOMOUS state (a human gate) or settles. Everything beyond that —
-# editors, desktop notifications, terminal-multiplexer status — is an OUTER
-# wrapper's responsibility, deliberately not this script's.
-# `run_gtd` is the ONE place that knows how to invoke "the bundle": by default
-# it resolves `dist/gtd.bundle.mjs` relative to this script's own location
-# (not cwd), but `GTD_BIN` (a dev/test override for the whole invocation
-# command, e.g. `GTD_BIN="node $PWD/dev/run.mjs"`) takes precedence when set.
-# Every call the loop body makes below goes through `run_gtd` too, so the loop
-# always drives the exact same build/source it was launched from — no
-# dependence on a `gtd` binary being on PATH.
-# Follow symlinks first: npm's global install exposes this script as a
-# symlink in the node prefix's bin/, and dist/ only exists next to the REAL
-# script inside the package.
-SCRIPT_SOURCE="${BASH_SOURCE[0]}"
-while [[ -L "$SCRIPT_SOURCE" ]]; do
-  SCRIPT_DIR="$(cd -- "$(dirname -- "$SCRIPT_SOURCE")" &>/dev/null && pwd)"
-  SCRIPT_SOURCE="$(readlink "$SCRIPT_SOURCE")"
-  [[ "$SCRIPT_SOURCE" != /* ]] && SCRIPT_SOURCE="$SCRIPT_DIR/$SCRIPT_SOURCE"
-done
-SCRIPT_DIR="$(cd -- "$(dirname -- "$SCRIPT_SOURCE")" &>/dev/null && pwd)"
-
-run_gtd() {
-  if [[ -n "${GTD_BIN:-}" ]]; then
-    eval "$GTD_BIN" '"$@"'
-  else
-    node "$SCRIPT_DIR/../dist/gtd.bundle.mjs" "$@"
-  fi
-}
-
-# ── Rendering primitives (capability detection, palette/markers, emitters) ──
-# `FANCY=1` only when stdout (fd 1) is a real terminal AND `NO_COLOR` is unset
-# — any pipe/redirect/non-tty stdout, or `NO_COLOR` set to any value, gives
-# plain ASCII with no escape codes, per the NO_COLOR convention
-# (https://no-color.org).
-if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then FANCY=1; else FANCY=0; fi
-
-if [[ "$FANCY" == 1 ]]; then
-  C_RESET=$'\e[0m'; C_BOLD=$'\e[1m'; C_DIM=$'\e[2m'
-  C_CYAN=$'\e[36m'; C_GREEN=$'\e[32m'; C_YELLOW=$'\e[33m'; C_RED=$'\e[31m'
-  M_TRANS="➡️"; M_AGENT="🤖"; M_CHECK="🔧"; M_HUMAN="✍️"
-  M_FIX="🔁"; M_COMMIT="✅"; M_SETTLE="🎉"; M_ERROR="❌"; M_WARN="⚠️"; M_ELLIPSIS="…"
-else
-  C_RESET=""; C_BOLD=""; C_DIM=""
-  C_CYAN=""; C_GREEN=""; C_YELLOW=""; C_RED=""
-  M_TRANS="->"; M_AGENT="[agent]"; M_CHECK="[check]"; M_HUMAN="[you]"
-  M_FIX="[fix]"; M_COMMIT="[commit]"; M_SETTLE="[done]"; M_ERROR="[err]"; M_WARN="[warn]"; M_ELLIPSIS="..."
-fi
-
-# `jq` used to be a loop-only dependency (the loop's own `next --json`
-# parsing); now every write subcommand's `--json` response (parsed by
-# `run_gtd_command`, below) carries the `required`/`optional` scripts this
-# script must execute for ANY invocation, not just `loop`. Checked once, up
-# front, before any dispatch below ever reaches for `jq` — a plain
-# `echo`/`exit` rather than `emit_error` since that helper (and the
-# fancy/plain markers it relies on) isn't the point; keeping the check
-# dependency-free is.
-if ! command -v jq >/dev/null 2>&1; then
-  echo "gtd: jq is required (used to parse the bundle's --json output) — install it and retry" >&2
-  exit 1
-fi
-
-# emit_file_rows <files> — render a commit's changed files as dim, indented
-# rows BELOW the transition/commit line: at most 3, then a "… (N more)" row
-# when there are more. <files> is a newline-separated list (git diff-tree
-# --name-only output); empty input prints nothing.
-emit_file_rows() {
-  local files="$1" f shown=0 total=0
-  [[ -z "$files" ]] && return 0
-  while IFS= read -r f; do [[ -n "$f" ]] && total=$((total + 1)); done <<<"$files"
-  while IFS= read -r f; do
-    [[ -z "$f" ]] && continue
-    if ((shown >= 3)); then
-      printf '   %s%s (%d more)%s\n' "$C_DIM" "$M_ELLIPSIS" "$((total - 3))" "$C_RESET"
-      break
-    fi
-    printf '   %s%s%s\n' "$C_DIM" "$f" "$C_RESET"
-    shown=$((shown + 1))
-  done <<<"$files"
-}
-
-# emit_transition <from> <to> <files> — a captured state-to-state move. The
-# "→" separator is literal (not FANCY-dependent) — the same separator the
-# engine's commit grammar itself uses, per the package spec.
-emit_transition() {
-  local from="$1" to="$2" files="$3"
-  printf '%s %s%s → %s%s\n' \
-    "$M_TRANS" "$C_BOLD$C_CYAN" "$from" "$to" "$C_RESET"
-  emit_file_rows "$files"
-}
-
-# emit_action <marker> <label> — the heartbeat printed before a turn runs.
-emit_action() {
-  local marker="$1" label="$2"
-  printf '%s %s%s\n' "$marker" "$label" "$C_RESET"
-}
-
-# emit_commit <subject> <files> — a non-transition capture (a bare-subject
-# self-loop, or the squash's agent-authored final commit).
-emit_commit() {
-  local subject="$1" files="$2"
-  printf '%s %s%s%s\n' "$M_COMMIT" "$C_GREEN" "$subject" "$C_RESET"
-  emit_file_rows "$files"
-}
-
-# emit_gate <state> <message> — the human-instruction line at a message rest.
-emit_gate() {
-  local message="$2"
-  printf '%s  %s%s%s\n' "$M_HUMAN" "$C_BOLD$C_YELLOW" "$message" "$C_RESET"
-}
-
-# emit_settled <state> — the terminal "nothing left to do" signal.
-emit_settled() {
-  printf '%s %ssettled — nothing left to do%s\n' "$M_SETTLE" "$C_GREEN" "$C_RESET"
-}
-
-# emit_error <message> — refusals/stalls/failures, to stderr; <message> may be
-# multi-line and is passed through verbatim.
-emit_error() {
-  local message="$1"
-  printf '%s %s%s%s\n' "$M_ERROR" "$C_RED" "$message" "$C_RESET" >&2
-}
-
-# emit_log_pointer — the "see the log" line printed right after every
-# emit_error call, to stderr: it names the log as the OVERFLOW channel — the
-# failing execution's own output is already replayed inline (see emit_block/
-# emit_output_since below); the log is where the rest of it, and the full
-# run's other output, lives.
-emit_log_pointer() {
-  if [[ "$FANCY" == 1 ]]; then
-    printf '%s📄 see %s%s\n' "$C_DIM" "$GTD_LOOP_LOG" "$C_RESET" >&2
-  else
-    printf '%ssee %s%s\n' "$C_DIM" "$GTD_LOOP_LOG" "$C_RESET" >&2
-  fi
-}
-
-# Suppressed subprocess output goes to $GTD_LOOP_LOG in full, but a FAILING
-# execution also replays inline: mark the log's size before the call, print
-# what was appended since. Bounded to the last $ERR_TAIL_LINES lines — the log
-# holds the rest, and the overflow row says where.
-ERR_TAIL_LINES=20
-
-# log_offset — the log's current size in bytes (0 when it doesn't exist yet).
-log_offset() {
-  local n=0
-  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then n="$(wc -c <"$GTD_LOOP_LOG")"; fi
-  printf '%s' "${n// /}"
-}
-
-# emit_block <text> — replay captured subprocess output to stderr, dim and
-# indented like emit_file_rows, capped at the LAST $ERR_TAIL_LINES lines with
-# an overflow row naming the log. Empty <text> prints nothing. CSI escapes are
-# stripped under FANCY=0 (the plain-ASCII promise), using a sed form (\e, not
-# \x1b) that both BSD and GNU sed accept.
-emit_block() {
-  local text="$1" total overflow
-  [[ -z "$text" ]] && return 0
-  if [[ "$FANCY" == 0 ]]; then
-    text="$(sed $'s/\e\\[[0-9;]*[a-zA-Z]//g' <<<"$text")"
-  fi
-  total="$(wc -l <<<"$text")"
-  total="${total// /}"
-  if ((total > ERR_TAIL_LINES)); then
-    overflow=$((total - ERR_TAIL_LINES))
-    printf '   %s%s (%d earlier lines in %s)%s\n' "$C_DIM" "$M_ELLIPSIS" "$overflow" "$GTD_LOOP_LOG" "$C_RESET" >&2
-    text="$(tail -n "$ERR_TAIL_LINES" <<<"$text")"
-  fi
-  while IFS= read -r line; do
-    printf '   %s%s%s\n' "$C_DIM" "$line" "$C_RESET" >&2
-  done <<<"$text"
-}
-
-# emit_output_since <offset> — emit_block over the log bytes appended since
-# <offset>.
-emit_output_since() {
-  local offset="$1" bytes=""
-  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then
-    bytes="$(tail -c "+$((offset + 1))" "$GTD_LOOP_LOG" 2>/dev/null || true)"
-  fi
-  emit_block "$bytes"
-}
-
-# A resume that failed because the session it names no longer exists — claude
-# prints "No conversation found with session ID: <uuid>". Loose on purpose: any
-# adapter whose CLI says something session-shaped gets the same recovery
-# instead of stopping the loop.
-SESSION_GONE_RE='no conversation found with session id|no such session|session (id )?[^ ]*( was)? not found|session [^ ]* does not exist'
-
-# session_gone_since <offset> — true when the log bytes appended since <offset>
-# carry the missing-session signature above. Blind (returns false) when no log
-# is configured, so recovery is best-effort, never a hard dependency.
-session_gone_since() {
-  local offset="$1" bytes=""
-  if [[ -n "${GTD_LOOP_LOG:-}" && -f "$GTD_LOOP_LOG" ]]; then
-    bytes="$(tail -c "+$((offset + 1))" "$GTD_LOOP_LOG" 2>/dev/null || true)"
-  fi
-  [[ -n "$bytes" ]] && grep -qiE "$SESSION_GONE_RE" <<<"$bytes"
-}
-
-# emit_warn <message> — a surfaced but NON-fatal failure (a check script that
-# exited non-zero).
-emit_warn() {
-  printf '%s %s%s%s\n' "$M_WARN" "$C_YELLOW" "$1" "$C_RESET" >&2
-}
-
-# ── Git-derivation helpers (parse_subject, report_commits) ──────────────────
-
-# parse_subject <subject> — sets S_ACTOR / S_FROM / S_TO / S_KIND. Patterns are
-# held in variables (rather than inlined) so bash's [[ =~ ]] doesn't need the
-# literal parens/spaces quoted inline.
-parse_subject() {
-  local subject="$1"
-  local transition_re='^gtd\(([^)]+)\): (.+) → (.+)$'
-  local capture_re='^gtd\(([^)]+)\): (.+)$'
-  S_ACTOR="" S_FROM="" S_TO="" S_KIND=""
-  if [[ "$subject" =~ $transition_re ]]; then
-    S_KIND=transition
-    S_ACTOR="${BASH_REMATCH[1]}"
-    S_FROM="${BASH_REMATCH[2]}"
-    S_TO="${BASH_REMATCH[3]}"
-  elif [[ "$subject" =~ $capture_re ]]; then
-    S_KIND=capture
-    S_ACTOR="${BASH_REMATCH[1]}"
-    S_TO="${BASH_REMATCH[2]}"
-  else
-    S_KIND=squash
-    S_TO="$subject"
-  fi
-}
-
-# report_commits — walks "$reported_head"..HEAD in order, emitting a
-# transition/commit line per new commit, and advances $reported_head to HEAD
-# when it reported at least one; returns non-zero (having emitted nothing,
-# and leaving $reported_head unchanged) when there were no new commits. Global
-# rather than per-beat so the review checkout window's HEAD rewinds between
-# beats never cause an already-reported commit to replay. $reported_head ==
-# "none" (the repo had no commits at all when it was last captured) can't
-# form a "none"..HEAD range — `git rev-list` would fail resolving "none" as a
-# revision — so that case walks the whole history from the root instead.
-report_commits() {
-  local sha subject files reported=0
-  local range
-  if [[ "$reported_head" == none ]]; then
-    range="HEAD"
-  else
-    range="$reported_head..HEAD"
-  fi
-  while IFS= read -r sha; do
-    [[ -z "$sha" ]] && continue
-    reported=1
-    subject="$(git log -1 --format=%s "$sha")"
-    files="$(git diff-tree --no-commit-id --name-only -r "$sha")"
-    parse_subject "$subject"
-    case "$S_KIND" in
-      transition) emit_transition "$S_FROM" "$S_TO" "$files" ;;
-      capture | squash) emit_commit "$subject" "$files" ;;
-    esac
-  done < <(git rev-list --reverse "$range")
-  if [[ "$reported" == 1 ]]; then
-    reported_head="$(git rev-parse HEAD)"
-  fi
-  [[ "$reported" == 1 ]]
-}
-
-# ── Write-command execution (is_write_command, run_gtd_command) ────────────
-# The bundle no longer performs a WRITE subcommand's git effect itself: its
-# `--json` response for `step`/the `--entry` forms/`abandon`/`restore` now
-# carries `required` (a bash script that performs the command's whole
-# effect — commit/reset/etc, including any review-window close/open
-# management) and `optional` (presentation-only, e.g. re-opening the review
-# checkout window — safe to skip), alongside whichever keys that command's
-# JSON always carried. This script is the ONE driver for every invocation
-# (not just the loop's), so it — not the bundle — must run those scripts.
-
-# is_write_command <token> — true for exactly the tokens whose command
-# mutates the repo: `step` (with or without `--entry` trailing), `abandon`,
-# `restore`, and the bare `--entry` short form (`gtd --entry <state>`, where
-# `--entry` itself is $1 since there is no subcommand token in front of it).
-# Everything else (next/status/validate/visualize/lsp/check/init, or an
-# unrecognised token) is read-only or has its own arity/usage errors and is
-# left to the existing plain `run_gtd "$@"` forwarding.
-# `--entry` takes both spellings (`--entry <state>` and `--entry=<state>`), so
-# the bare short form has to be recognised either way.
-is_write_command() {
-  case "${1:-}" in
-    step | abandon | restore | --entry | --entry=*) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-# run_gtd_command <subcommand-and-args...> — the ONE execution path for every
-# write subcommand, used both by the direct dispatch below and by the loop
-# body's own step calls (so there is one execution path rather than two, not
-# a loop-only one and a separate direct one). Fetches the bundle's `--json`
-# response for "$@" (forcing --json on regardless of whether the caller's own
-# arguments already carry it — repeating `--json` is harmless, see
-# `Cli.ts`'s arity-0 flag handling), runs `.required` via `bash -c` (aborting
-# — returning its exit code — before `.optional` ever runs, mirroring `set
-# -e`), then `.optional` via `bash -c` (a non-zero exit there is only ever a
-# warning: it is presentation-only, e.g. re-opening the review checkout
-# window, per its own "safe to skip" billing). On success it prints, on
-# stdout, the plain human-facing line in TODAY's exact wording — the same
-# text `runStepCommand`/`runEntryCommand`/`runAbandonCommand`/
-# `runRestoreCommand` printed themselves before this rewrite moved the git
-# write into `required`. A direct caller lets that line stream straight to
-# the terminal; the loop instead captures it (`$(... 2>&1)`, the file's
-# established idiom) and logs it, since its own on-screen presentation is
-# `report_commits`. `abandon`/`restore` have no `subject` in their JSON (never
-# did — the original handlers computed it from git AFTER writing), so this
-# recomputes it from HEAD after `.required` has run; every other field used
-# below (`state`, `from`, `head`, `to`) is one of the contract's own preserved
-# "existing keys". On failure (the JSON fetch itself — a refusal/usage error —
-# or `.required`), the combined fetch output is sent to stderr and the
-# function returns non-zero; a failing `.required`'s own output streams
-# (or is captured by the caller) exactly as it happened, unredirected here.
-run_gtd_command() {
-  local subcmd="${1:-}" json_out required optional opt_status
-  local state subject head to from
-
-  if ! json_out="$(run_gtd "$@" --json 2>&1)"; then
-    printf '%s' "$json_out" >&2
-    return 1
-  fi
-
-  # `// empty` guards a command whose JSON doesn't (yet, or ever) carry these
-  # keys for a given branch — e.g. `gtd abandon`'s "nothing to abandon" no-op
-  # reply has neither key at all — so a missing/null field reads as "" (jq's
-  # own `null` stringifies to the 4-character text "null" otherwise, which
-  # would misread as a non-empty script).
-  required="$(jq -r '.required // empty' <<<"$json_out")"
-  optional="$(jq -r '.optional // empty' <<<"$json_out")"
-
-  if [[ -n "$required" ]]; then
-    bash -c "$required" || return $?
-  fi
-
-  if [[ -n "$optional" ]]; then
-    opt_status=0
-    bash -c "$optional" || opt_status=$?
-    if ((opt_status != 0)); then
-      emit_warn "the presentation-only follow-up after '$subcmd' failed (exit $opt_status) — continuing"
-    fi
-  fi
-
-  case "$subcmd" in
-    abandon)
-      if [[ -z "$required" ]]; then
-        state="$(jq -r '.state' <<<"$json_out")"
-        printf 'no gtd process is underway (resting at "%s") — nothing to abandon\n' "$state"
-      else
-        from="$(jq -r '.from' <<<"$json_out")"
-        state="$(jq -r '.state' <<<"$json_out")"
-        head="$(jq -r '.head' <<<"$json_out")"
-        subject="$(git log -1 --format=%s HEAD)"
-        printf 'abandoned the process resting at "%s" — HEAD is back at %s ("%s"), resting at "%s".\n' \
-          "$from" "${head:0:7}" "$subject" "$state"
-        printf 'Everything the process produced is kept as uncommitted changes (`git status`); discard them with `git checkout -- . && git clean -fd .gtd` for a clean tree.\n'
-      fi
-      ;;
-    restore)
-      to="$(jq -r '.to' <<<"$json_out")"
-      state="$(jq -r '.state' <<<"$json_out")"
-      subject="$(git log -1 --format=%s HEAD)"
-      printf 'restored the retained history — HEAD is back at %s ("%s"), resting at "%s". Resume with the loop, or `git reset` to any earlier turn to restart from there.\n' \
-        "${to:0:7}" "$subject" "$state"
-      ;;
-    *)
-      # `step` (subject nullable — a no-op prints "nothing to do") and the
-      # `--entry` forms (subject never null — always "committed: ...") share
-      # this one branch: the null-check alone tells them apart.
-      subject="$(jq -r '.subject' <<<"$json_out")"
-      if [[ -n "$subject" && "$subject" != "null" ]]; then
-        printf 'committed: %s\n' "$subject"
-      else
-        state="$(jq -r '.state' <<<"$json_out")"
-        printf 'nothing to do at "%s"\n' "$state"
-      fi
-      ;;
-  esac
-}
-
-# ── Log file (resolve_log_path) ─────────────────────────────────────────────
-
-# worktree_git_dir — the git dir of the working tree gtd is operating in,
-# derived purely from the cwd. GIT_DIR/GIT_WORK_TREE are scrubbed for this one
-# call so an inherited GIT_DIR (e.g. leaked from a parent git process, a hook,
-# or another worktree's shell) can never point our per-worktree state at a
-# DIFFERENT worktree — that would let two concurrently looping worktrees
-# collide on one log/memory file. A linked worktree's git-dir is its own
-# private .git/worktrees/<name>, so this is per-repository AND per-worktree.
-worktree_git_dir() {
-  env -u GIT_DIR -u GIT_WORK_TREE -u GIT_COMMON_DIR -u GIT_INDEX_FILE \
-    git rev-parse --git-dir
-}
-
-# resolve_log_path — echoes the loop's logfile path: $GTD_LOOP_LOG verbatim if
-# set, else "$(worktree_git_dir)/gtd-loop.log".
-resolve_log_path() {
-  if [[ -n "${GTD_LOOP_LOG:-}" ]]; then
-    echo "$GTD_LOOP_LOG"
-  else
-    echo "$(worktree_git_dir)/gtd-loop.log"
-  fi
-}
-
-# --once governs only the loop driver, recognised in exactly two positions —
-# bare (`gtd --once`) or immediately after `loop` (`gtd loop --once`) — at
-# most once. When recognised it is stripped here before anything below looks
-# at "$@", so the bundle's own unknown-option guard never sees it; anything
-# else (an unknown flag, a duplicate --once, or --once mixed with a real
-# subcommand) is left untouched and falls through to the existing dispatch
-# below, which forwards a non-flag first argument to the bundle (whose own
-# unknown-option guard rejects it) or rejects a `loop` invocation carrying an
-# unrecognised extra argument.
-once_mode=0
-
-if [[ "${1:-}" == "loop" ]]; then
-  loop_form=1
-  loop_flag_args=("${@:2}")
-else
-  loop_form=0
-  loop_flag_args=("$@")
-fi
-
-valid_combo=1
-n_once=0
-for a in ${loop_flag_args[@]+"${loop_flag_args[@]}"}; do
-  case "$a" in
-  --once) n_once=$((n_once + 1)) ;;
-  *) valid_combo=0 ;;
-  esac
-done
-((n_once > 1)) && valid_combo=0
-
-if [[ "$valid_combo" == 1 && "$n_once" == 1 ]]; then
-  once_mode=1
-  if [[ "$loop_form" == 1 ]]; then
-    set -- loop
-  else
-    set --
-  fi
-fi
-
-if [[ $# -gt 0 && "$1" != "loop" ]]; then
-  if is_write_command "${1:-}"; then
-    run_gtd_command "$@"
-    exit $?
-  fi
-  run_gtd "$@"
-  exit $?
-fi
-if [[ "${1:-}" == "loop" && $# -gt 1 ]]; then
-  echo "gtd: 'loop' takes no arguments" >&2
-  exit 2
-fi
-# otherwise ($# -eq 0, or exactly "loop" with no further args, --once already
-# stripped above): fall through into the loop body below.
-
-# Drives the v3 pattern-machine loop: each iteration asks
-# `gtd next --json` who's up and what they should do, dispatching on `kind`:
-#   - "message" (a human rest)  -> the non-autonomous halt: print the gate and
-#     exit 0. Acting on it (opening an editor, notifying, whatever) is an
-#     outer wrapper's job; this loop only ever drives the AUTONOMOUS states.
-#   - "script"  (a check rest) -> execute `content` (the emitted wrapper
-#     script) verbatim via bash — exit code deliberately ignored, the outcome
-#     lives in the tree — then `gtd step <actor>` to capture it; zero new
-#     commits = green with nothing owed (the terminal signal at idle).
-#   - "prompt"  (an agent rest) -> feed `content` to the agent, run the
-#     self-validation gate (`gtd validate`, re-prompting on findings — see the
-#     gate's own comment below), then `gtd step <actor>` ourselves — the
-#     harness owns ending the turn, not the prompt text.
-# `.model` (optional, opaque) is exported as $GTD_LOOP_MODEL for the agent
-# adapter invoked at a "prompt" rest; the default adapter appends `--model
-# "$GTD_LOOP_MODEL"` only when it's non-empty.
-#
-# `.memory` (optional, opaque) is the agent-memory scope label. gtd never interprets it; the driver does:
-# consecutive "prompt" turns emitting the SAME label continue ONE agent
-# session (so the agent still remembers its previous turn), and a changed
-# label — or the first turn, or an unset label — starts fresh. That is what
-# lets a loop retain memory within itself (grilling ↔ answer, fixing ↔
-# checking) and clear it at a phase boundary. The previous prompt turn's scope
-# and its agent session id are persisted in the git dir (NOT the working tree,
-# so `gtd status` and the pending diff never see them), so retention survives
-# across restarts — a grilling loop that halts at its human gate every lap
-# still resumes one planning session. The scope, session id, and a
-# resume-or-fresh flag are exported as $GTD_LOOP_MEMORY / $GTD_LOOP_SESSION_ID
-# / $GTD_LOOP_MEMORY_RESUME; the default adapter turns them into
-# `--resume`/`--session-id`. An adapter that ignores them keeps working. A
-# remembered session that has since vanished (the retention window elapsed, a
-# wiped `~/.claude/projects`, a machine change) degrades to a fresh session
-# with a warning rather than failing the turn — see run_agent_turn's own
-# comment.
-
-# new_session_id — mints an opaque session id for a fresh memory scope
-# (uuidgen, falling back to the kernel's random uuid, or empty when neither is
-# available — the default adapter then omits --session-id entirely).
-new_session_id() {
-  uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid 2>/dev/null || echo ""
-}
-
-# scope_of <key> — the scope part of a "<scope>#<hash>" memory key: everything
-# before the first "#". Used to decide which existing table row a fresh entry
-# into a scope displaces (see write_scope_session).
-scope_of() {
-  printf '%s' "${1%%#*}"
-}
-
-# lookup_scope_session <key> — print the session id remembered for EXACTLY
-# this key (a row whose first field string-equals it), or fail with no output
-# if no row matches (a lookup miss -> the caller starts fresh). $memory_marker
-# absent counts as no rows at all.
-lookup_scope_session() {
-  local key="$1" row_key row_sid
-  [[ -f "$memory_marker" ]] || return 1
-  while read -r row_key row_sid; do
-    if [[ "$row_key" == "$key" ]]; then
-      printf '%s' "$row_sid"
-      return 0
-    fi
-  done <"$memory_marker"
-  return 1
-}
-
-# write_scope_session <key> <session_id> — replace the ONE row for this key's
-# SCOPE (scope_of) with a fresh row for <key>, leaving every OTHER scope's row
-# in the table untouched. A scope has at most one live conversation at any
-# moment, so an existing row for this scope is dead the instant a new entry
-# into it begins — this is the entire pruning story, no process concept
-# needed (see the module's own memory-scope doc comment below). The table is
-# rewritten via a sibling temp file + rename, so a crash mid-write never
-# leaves a half-written table.
-write_scope_session() {
-  local key="$1" session_id="$2" scope tmp row_key row_sid
-  scope="$(scope_of "$key")"
-  tmp="$(mktemp "${memory_marker}.XXXXXX")"
-  if [[ -f "$memory_marker" ]]; then
-    while read -r row_key row_sid; do
-      [[ "$(scope_of "$row_key")" == "$scope" ]] && continue
-      printf '%s %s\n' "$row_key" "$row_sid" >>"$tmp"
-    done <"$memory_marker"
-  fi
-  printf '%s %s\n' "$key" "$session_id" >>"$tmp"
-  mv "$tmp" "$memory_marker"
-}
-
-prev_state=""
-prev_content=""
-prev_head=""
-# Where each scope's remembered agent session is persisted across iterations
-# and across restarts, as a TABLE — one "<key> <session_id>" row per scope
-# (keys contain no whitespace, so plain field-splitting is safe) — never a
-# single last-label value: with machine-scoped memory, a scope's key can
-# legitimately reappear AFTER the loop has run turns in a completely
-# different (or nested) scope — e.g. build.fix -> into a nested health-gate
-# child's own agent turn -> back to build.fix, still the same builder
-# conversation. "The last label" can't represent that; a table where each
-# scope owns exactly one row can. In the git dir, never the work tree.
-memory_marker="$(worktree_git_dir 2>/dev/null || echo .git)/gtd-loop-memory"
-
-# Truncated once here (not every iteration), so the file always reflects the
-# current run but survives after the loop exits.
-log_path="$(resolve_log_path)"
-: >"$log_path"
-export GTD_LOOP_LOG="$log_path"
-if [[ "$FANCY" == 1 ]]; then
-  printf '%s📄 log: %s  (tail -f to follow)%s\n' "$C_DIM" "$log_path" "$C_RESET"
-else
-  printf '%slog: %s  (tail -f to follow)%s\n' "$C_DIM" "$log_path" "$C_RESET"
-fi
-
-# Swappable agent adapter: GTD_LOOP_AGENT_CMD lets any coding agent CLI stand
-# in for the default, receiving the prompt via $GTD_LOOP_PROMPT, the state's
-# opaque model hint (if any) via $GTD_LOOP_MODEL, and the memory scope via
-# $GTD_LOOP_MEMORY / $GTD_LOOP_SESSION_ID / $GTD_LOOP_MEMORY_RESUME ("1" when
-# this turn should continue the prior session). An adapter that ignores any of
-# these keeps working — they're exported alongside $GTD_LOOP_PROMPT, never
-# required. The default adapter maps the memory signal onto claude's own
-# session flags: --resume to continue the scope's session, --session-id to pin
-# a fresh one so the next same-scope turn can resume it. $1 is the prompt, $2
-# the resume flag; the memory scope ($memory/$session_id) is read from the
-# enclosing iteration, so a same-turn re-prompt (the validate gate) resumes the
-# same session.
-invoke_agent() {
-  local prompt="$1" do_resume="$2" cmd="${GTD_LOOP_AGENT_CMD:-}"
-  if [[ -z "$cmd" ]]; then
-    cmd='claude -p "$GTD_LOOP_PROMPT"'
-    [[ -n "$model" ]] && cmd="$cmd"' --model "$GTD_LOOP_MODEL"'
-    if [[ "$do_resume" == "1" ]]; then
-      cmd="$cmd"' --resume "$GTD_LOOP_SESSION_ID"'
-    elif [[ -n "$session_id" ]]; then
-      cmd="$cmd"' --session-id "$GTD_LOOP_SESSION_ID"'
-    fi
-    cmd="$cmd"' --dangerously-skip-permissions'
-  fi
-  GTD_LOOP_PROMPT="$prompt" GTD_LOOP_MODEL="$model" GTD_LOOP_MEMORY="$memory" \
-    GTD_LOOP_SESSION_ID="$session_id" GTD_LOOP_MEMORY_RESUME="$do_resume" bash -c "$cmd" \
-    >>"${GTD_LOOP_LOG:-/dev/null}" 2>&1
-}
-
-# run_agent_turn <prompt> <resume> — invoke_agent, with one recovery: a
-# resumed turn (do_resume == 1) that fails AND whose output carries the
-# missing-session signature (session_gone_since) means the CURRENT scope's
-# remembered session no longer exists on disk. Rather than failing the turn
-# (and every turn after it, since the dead id would just be resumed again),
-# mint a fresh session and rewrite ONLY this scope's row in $memory_marker
-# (write_scope_session — every other scope's row survives untouched) — the
-# self-healing part, so a later launch doesn't repeat this — and retry the
-# SAME prompt once with resume off. $resume and $session_id are the enclosing
-# iteration's globals; recovery rewrites them too, so a later validate-gate
-# re-prompt in the same turn resumes the newly pinned session. Blind to the
-# failure mode when session_gone_since can't tell (no log configured): a
-# genuine agent failure then correctly propagates.
-run_agent_turn() {
-  local prompt="$1" do_resume="$2" offset status=0
-  offset="$(log_offset)"
-  invoke_agent "$prompt" "$do_resume" && return 0
-  status=$?
-  if [[ "$do_resume" == "1" ]] && session_gone_since "$offset"; then
-    emit_warn "the remembered agent session for '$memory' is gone — continuing in a fresh session (this turn starts without its previous context)"
-    session_id="$(new_session_id)"
-    resume=0
-    write_scope_session "$memory" "$session_id"
-    invoke_agent "$prompt" 0
-    return $?
-  fi
-  return $status
-}
-
-# The furthest commit already reported to the terminal by report_commits (see
-# its own comment) — a global high-water mark rather than a per-beat
-# head_before, so a review checkout window's HEAD rewind between beats never
-# causes an already-printed transition to replay.
-reported_head="$(git rev-parse --verify --quiet HEAD || echo none)"
-
-# Opening move: capture the human's pending edit so gtd-loop is the ONLY command
-# a human runs. A human acts at a gate by editing files (a plan answer, a review
-# tick, a code fix) and re-launching the loop — they should never have to run
-# `gtd step human` by hand first. So before driving, if the machine currently
-# rests at a human gate, step the human once to commit whatever they left, then
-# fall into the loop below from the resulting state.
-#
-# We peek with the pure, mutation-free `gtd next --json` and step ONLY when it
-# reports a human rest (`kind == "message"`): at an agent/check rest
-# `gtd step human` would refuse out-of-turn (non-zero, aborting under `set -e`),
-# and a mid-process restart must simply resume driving, not fail. A clean gate is
-# a harmless no-op; a genuine refusal there (a malformed steering file, or an
-# edit no `on` pattern accepts) is surfaced and stops the loop rather than being
-# driven past. --once treats a captured commit here as the run's one beat and
-# exits; a clean/no-op gate captures nothing, so it isn't a beat — it falls
-# into the loop below exactly as it would without --once.
-if ! peek_json="$(run_gtd next --json 2>&1)"; then
-  emit_error "could not determine the next step:
-$peek_json
-Run \`gtd status\` to inspect the repo."
-  emit_log_pointer
-  exit 1
-fi
-peek_kind="$(jq -r .kind <<<"$peek_json")"
-if [[ "$peek_kind" == "message" ]]; then
-  opening_head_before="$(git rev-parse --verify --quiet HEAD || echo none)"
-  if ! step_out="$(run_gtd_command step human 2>&1)"; then
-    emit_error "could not capture your changes at the human gate:
-$step_out
-Fix the reported issue and re-run gtd-loop."
-    emit_log_pointer
-    exit 1
-  fi
-  # This branch reports nothing — advance the marker past whatever was just
-  # (silently) captured so the first loop-body beat below doesn't newly
-  # print it.
-  reported_head="$(git rev-parse --verify --quiet HEAD || echo none)"
-  if [[ "$once_mode" == 1 && "$opening_head_before" != "$reported_head" ]]; then
-    exit 0
-  fi
-fi
-
-while true; do
-  if ! next_json="$(run_gtd next --json 2>&1)"; then
-    emit_error "could not determine the next step:
-$next_json
-Run \`gtd status\` to inspect the repo."
-    emit_log_pointer
-    exit 1
-  fi
-
-  state="$(jq -r .state <<<"$next_json")"
-  actor="$(jq -r .actor <<<"$next_json")"
-  kind="$(jq -r .kind <<<"$next_json")"
-  content="$(jq -r .content <<<"$next_json")"
-  model="$(jq -r '.model // empty' <<<"$next_json")"
-  memory="$(jq -r '.memory // empty' <<<"$next_json")"
-  label="$(jq -r '.label // .state' <<<"$next_json")"
-
-  if [[ "$kind" == "message" ]]; then
-    # The non-autonomous halt: print the gate, hand off, exit 0. The human
-    # (or an outer wrapper) edits and re-launches; the opening move above
-    # captures what they left.
-    emit_gate "$state" "$label"
-    if ! gate_out="$(run_gtd next 2>&1)"; then
-      emit_error "$gate_out"
-      emit_log_pointer
-      exit 1
-    fi
-    printf '%s\n' "$gate_out"
-    exit 0
-  fi
-
-  if [[ "$kind" == "script" ]]; then
-    emit_action "$M_CHECK" "$label"
-    # Execute the emitted wrapper verbatim; its exit code decides nothing
-    # (the script encodes its outcome in the tree, and `gtd step` captures
-    # whatever it left there via the state's own `on` patterns) but a non-zero
-    # exit is surfaced as a warning — its own output goes to the log, and to
-    # the terminal too when it exits non-zero.
-    script_offset="$(log_offset)"
-    script_status=0
-    bash -c "$content" >>"$GTD_LOOP_LOG" 2>&1 || script_status=$?
-    if ((script_status != 0)); then
-      emit_warn "the check script at '$state' exited $script_status — continuing; the outcome is whatever it left in the tree:"
-      emit_output_since "$script_offset"
-    fi
-    if ! step_out="$(run_gtd_command step "$actor" 2>&1)"; then
-      printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
-      emit_error "$step_out"
-      emit_log_pointer
-      exit 1
-    fi
-    printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
-    if ! report_commits; then
-      emit_settled "$state"
-      exit 0
-    fi
-    prev_state=""
-    prev_content=""
-    if [[ "$once_mode" == 1 ]]; then
-      exit 0
-    fi
-    continue
-  fi
-
-  # kind == "prompt": stall detection — the same
-  # agent-owned state and content repeating, WITH NO COMMIT authored since the
-  # last time we saw this beat, means the last dispatch made no progress; stop
-  # rather than spin on it. The HEAD check is what distinguishes a genuine
-  # stall from a return lap back into the same state (e.g. checking ->
-  # fixing): a static prompt looks identical to last time, but a commit
-  # landed in between, so HEAD has moved and this isn't a stall.
-  cur_head="$(git rev-parse --verify --quiet HEAD || echo none)"
-  if [[ "$state" == "$prev_state" && "$content" == "$prev_content" && "$cur_head" == "$prev_head" ]]; then
-    next_out="$(run_gtd next 2>&1)" || true
-    emit_error "no progress at '$state' — the agent's last turn changed nothing. Stopping to avoid spinning.
-$next_out"
-    emit_log_pointer
-    exit 1
-  fi
-  prev_state="$state"
-  prev_content="$content"
-  prev_head="$cur_head"
-
-  # Agent-memory scope: look this turn's `memory` key up in the per-scope
-  # table (lookup_scope_session — exact string equality against a row's full
-  # key, "<scope>#<hash>", not just its scope part). A hit -> resume that
-  # session; a miss -> start fresh with a new session id, then write ONLY this
-  # key's scope's row (write_scope_session), leaving every other scope's row
-  # untouched — a scope can legitimately go quiet and reappear later (see the
-  # $memory_marker declaration's own comment) without losing its place. An
-  # absent/empty key carries no constraint (harness default) and leaves the
-  # table completely untouched — it may hold live sessions for OTHER scopes
-  # this turn knows nothing about, so it's neither read nor written here.
-  resume=0
-  session_id=""
-  if [[ -n "$memory" ]]; then
-    if found_session_id="$(lookup_scope_session "$memory")"; then
-      resume=1
-      session_id="$found_session_id"
-    else
-      session_id="$(new_session_id)"
-    fi
-    write_scope_session "$memory" "$session_id"
-  fi
-
-  # Run the agent turn (see run_agent_turn's own comment for the adapter
-  # contract). Then the self-validation gate: a producing state may declare a
-  # `file:`/`mode:` pair (e.g. the default workflow's grilling/reviewing),
-  # making its output's format checkable. `gtd validate --json` always exits
-  # 0 now — it hands back the SCRIPT that formats/checks the file (`.script`,
-  # empty when the resolved rest has nothing to validate) rather than running
-  # it itself, so this driver runs that script after EVERY agent turn and
-  # re-prompts the SAME agent session on ITS non-zero exit (up to a cap)
-  # before stepping — the plain-`gtd next` self-validation instruction's
-  # driver-side equivalent, so the next rest is only ever handed a
-  # well-formed file. gtd itself never validates at step time — this is the
-  # loop's job.
-  emit_action "$M_AGENT" "$label"
-  turn_offset="$(log_offset)"
-  agent_status=0
-  run_agent_turn "$content" "$resume" || agent_status=$?
-  if ((agent_status != 0)); then
-    emit_error "the agent turn at '$state' failed (exit $agent_status):"
-    emit_output_since "$turn_offset"
-    emit_log_pointer
-    exit 1
-  fi
-
-  if ! validate_json="$(run_gtd validate --json 2>&1)"; then
-    emit_error "could not resolve the validation script at '$state':
-$validate_json
-Stopping rather than stepping with a possibly-malformed steering file."
-    emit_log_pointer
-    exit 1
-  fi
-  validate_script="$(jq -r '.script' <<<"$validate_json")"
-
-  fix_attempt=0
-  while [[ -n "$validate_script" ]]; do
-    validate_status=0
-    validate_out="$(bash -c "$validate_script" 2>&1)" || validate_status=$?
-    ((validate_status == 0)) && break
-    fix_attempt=$((fix_attempt + 1))
-    if ((fix_attempt > 3)); then
-      printf '%s\n' "$validate_out" >>"$GTD_LOOP_LOG"
-      emit_error "'$state' still fails its own validation script after 3 fix attempts:
-$validate_out
-Stopping rather than stepping with a malformed steering file."
-      emit_log_pointer
-      exit 1
-    fi
-    printf '%s\n' "$validate_out" >>"$GTD_LOOP_LOG"
-    emit_action "$M_FIX" "attempt $fix_attempt"
-    # Resume the same session when there is one (the agent just wrote the file);
-    # otherwise a fresh invocation still gets the findings via the prompt.
-    fix_resume=0
-    [[ -n "$session_id" ]] && fix_resume=1
-    turn_offset="$(log_offset)"
-    agent_status=0
-    run_agent_turn "$content"$'\n\n'"Your last turn does not pass its own validation script. Fix these format violations, then finish:"$'\n'"$validate_out" "$fix_resume" || agent_status=$?
-    if ((agent_status != 0)); then
-      emit_error "the agent's fix attempt $fix_attempt at '$state' failed (exit $agent_status):"
-      emit_output_since "$turn_offset"
-      emit_log_pointer
-      exit 1
-    fi
-  done
-
-  if ! step_out="$(run_gtd_command step "$actor" 2>&1)"; then
-    printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
-    emit_error "$step_out"
-    emit_log_pointer
-    exit 1
-  fi
-  printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
-  # A no-op step (nothing matched a declared pattern on a clean tree) reports
-  # zero commits here — report_commits returns non-zero, and that's fine: the
-  # NEXT iteration's stall check is what catches unchanged state/content.
-  report_commits || true
-  if [[ "$once_mode" == 1 ]]; then
-    exit 0
-  fi
-done