@pmelab/gtd 8.1.0 → 8.2.0

package/README.md

@@ -285,20 +285,106 @@ re-launching it — its opening move captures whatever you left, so you never ru
 
 Anything richer at that boundary — opening your editor, desktop notifications,
 terminal-multiplexer status — is the job of an outer wrapper around `gtd`, not
-of the loop itself. Pass `--once` to restrict a run to exactly one beat — one
-human-gate capture, one check, or one agent turn — instead of driving all the
-way to idle.
+of the loop itself; see
+[Terminal-multiplexer status: a herdr wrapper](#terminal-multiplexer-status-a-herdr-wrapper)
+below for a worked example. Pass `--once` to restrict a run to exactly one beat
+— one human-gate capture, one check, or one agent turn — instead of driving all
+the way to idle.
 
 Bare `gtd` prints one line per event — colored and emoji on a real terminal,
 plain ASCII under `NO_COLOR` or when piped — and redirects the noisier
 agent/check/step subprocess output to a per-repo/per-worktree log file (its path
-is the run's first output line, ready to `tail -f`).
+is the run's first output line, ready to `tail -f`). Any execution that FAILS
+also replays its last 20 lines of output inline on stderr, on top of the log
+still holding the complete record: an agent turn that fails stops the loop (it
+would fail identically next lap), while a check script that exits non-zero is
+reported as a warning and the loop carries on, because the outcome lives in the
+tree, not in the script's exit code.
 
 A workflow state can declare an optional `label:` — a human-readable display
 name surfaced in `gtd next --json`/`gtd status`. The driver uses it for its
 per-beat progress lines; an outer wrapper (a terminal multiplexer, a notifier)
 can use it the same way.
 
+### Terminal-multiplexer status: a herdr wrapper
+
+[herdr](https://herdr.dev) shows a per-pane status in its sidebar. This wrapper
+reports `gtd`'s own lifecycle to that status without any herdr-specific
+knowledge in `gtd` itself: `working` while the loop drives, `blocked` when it
+comes to rest on a human (a gate, a stall, a non-zero exit), and `idle`
+(rendered as "done" once the pane's tab is unfocused) when a run ends without
+anything owed. It needs nothing from `gtd` beyond `gtd next --json`'s `.actor`
+field, which the loop's driver already reads at every beat.
+
+Save this as `~/.local/bin/gtdh`, `chmod +x` it, and run `gtdh` in place of
+`gtd` — it's a plain bash file, so it works from fish or any other shell, and it
+forwards every argument (`gtdh --once`, `gtdh status`, ...).
+
+```bash
+#!/usr/bin/env bash
+# Report gtd's own lifecycle to the herdr pane it runs in: working while the
+# loop drives, blocked when it rests on you, idle (shown as "done") otherwise.
+# Needs nothing from gtd but `gtd next --json`. Outside herdr it is a plain
+# passthrough. Requires `jq` — so does gtd's own loop driver.
+set -uo pipefail
+
+pane="${HERDR_PANE_ID:-}"
+
+# `--agent gtd` is deliberate: herdr only lets screen detection (or a visible
+# approval prompt) override a reported state when the reported label names a
+# KNOWN agent. "gtd" names none, so the loop's `claude -p` turns can never move
+# this pane's status.
+report() { # report <state>
+  [ -n "$pane" ] || return 0
+  herdr pane report-agent "$pane" \
+    --source custom:gtd --agent gtd --state "$1" >/dev/null 2>&1 || true
+}
+
+report working
+trap 'report blocked; exit 130' INT TERM
+
+# HERDR_PANE_ID is unset for the loop: herdr's Claude Code hook needs it, and
+# without it no `claude -p` turn reports a claude SESSION identity for this
+# pane. That is load-bearing, not cosmetic — a pane that owns one rejects every
+# later state report, so the report below would be dropped.
+env -u HERDR_PANE_ID gtd "$@"
+rc=$?
+
+# Whose turn is it now? `gtd next --json` is mutation-free. A human actor means
+# gtd is waiting on you; anything else means the run ended with nothing owed.
+actor="$(gtd next --json 2>/dev/null | jq -r '.actor // ""' 2>/dev/null || true)"
+
+if [ "$rc" -ne 0 ] || [ -z "$actor" ] || [ "$actor" = human ]; then
+  report blocked
+else
+  report idle
+fi
+
+exit $rc
+```
+
+A few things to know before relying on it:
+
+- **Give `gtd` its own pane.** Run an interactive `claude` (or any agent whose
+  herdr integration reports session identity) in the same pane and that pane
+  owns a `herdr:claude` session until the process exits; while it does, the
+  wrapper's reports are silently ignored and the sidebar stops tracking `gtd`.
+- **`blocked` covers the resting `idle` state too** — gtd's own `idle` is a
+  human gate (it waits for you to write a steering file), so a finished cycle
+  reads as "your turn", which is what it is.
+- The status **persists after the wrapper exits** — that's the point: the
+  sidebar keeps showing which worktree is waiting on you. Hand the pane back to
+  ordinary detection with
+  `herdr pane release-agent "$HERDR_PANE_ID" --source custom:gtd --agent gtd`.
+- A non-zero exit (a stall, a refusal, an error) reports `blocked`: herdr has no
+  failure state, and those all need a human.
+- Ctrl-C reports `blocked` rather than leaving a stale `working`.
+
+Optionally,
+`herdr pane report-metadata "$HERDR_PANE_ID" --source custom:gtd-display --token summary=<text>`
+sets a value renderable as `$summary` in an Agent sidebar row, if you want more
+than the state itself.
+
 ## Configuration
 
 gtd reads an optional `.gtdrc` config file via
@@ -483,9 +569,11 @@ compiler's job at load time.
 per `review`-mode chunk that still has an unchecked hunk (an outline of the
 packages left to review) plus check/uncheck actions over those chunks,
 go-to-definition from a `review`-mode hunk line into the file it points at (at
-its `#line`), symbols over a `qa`-mode file's open questions, diagnostics for
-both (live as you edit), and a `gtd.openSteeringFile` command that jumps to the
-current state's steering file.
+its `#line`), symbols over a `qa`-mode file's open questions plus "pick this
+option"/"uncheck this option" code actions on each option — offered anywhere on
+the option's list item, including any wrapped continuation lines, not just its
+own `- [ ]` line — diagnostics for both (live as you edit), and a
+`gtd.openSteeringFile` command that jumps to the current state's steering file.
 
 It is config-driven via each state's `file:`/`mode:`, and falls back to basename
 dispatch (`REVIEW.md` → `review`) with no config in sight. `qa` and `review` are

package/bin/gtd

@@ -44,12 +44,12 @@ 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_ELLIPSIS="…"
+  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_ELLIPSIS="..."
+  M_FIX="[fix]"; M_COMMIT="[commit]"; M_SETTLE="[done]"; M_ERROR="[err]"; M_WARN="[warn]"; M_ELLIPSIS="..."
 fi
 
 # emit_file_rows <files> — render a commit's changed files as dim, indented
@@ -114,8 +114,10 @@ emit_error() {
 }
 
 # emit_log_pointer — the "see the log" line printed right after every
-# emit_error call, to stderr: suppression must never hide a failure, so every
-# error points at where the redirected subprocess output actually went.
+# 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
@@ -124,6 +126,58 @@ emit_log_pointer() {
   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"
+}
+
+# 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
@@ -375,9 +429,10 @@ fi
 
 while true; do
   if ! next_json="$(run_gtd next --json 2>&1)"; then
-    echo "gtd-loop: could not determine the next step:" >&2
-    echo "$next_json" >&2
-    echo "Run \`gtd status\` to inspect the repo." >&2
+    emit_error "could not determine the next step:
+$next_json
+Run \`gtd status\` to inspect the repo."
+    emit_log_pointer
     exit 1
   fi
 
@@ -394,17 +449,29 @@ while true; do
     # (or an outer wrapper) edits and re-launches; the opening move above
     # captures what they left.
     emit_gate "$state" "$label"
-    run_gtd next
+    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 is deliberately
-    # ignored (`|| true` under `set -e`) — the script encodes its outcome in
-    # the tree, and `gtd step` captures whatever it left there via the state's
-    # own `on` patterns. Its own output goes to the log, not the terminal.
-    bash -c "$content" >>"$GTD_LOOP_LOG" 2>&1 || true
+    # 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 step "$actor" 2>&1)"; then
       printf '%s\n' "$step_out" >>"$GTD_LOOP_LOG"
       emit_error "$step_out"
@@ -478,24 +545,42 @@ $next_out"
   # 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"
-  run_agent_turn "$content" "$resume"
+  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
 
   fix_attempt=0
   while ! validate_out="$(run_gtd validate 2>&1)"; do
     fix_attempt=$((fix_attempt + 1))
     if ((fix_attempt > 3)); then
+      printf '%s\n' "$validate_out" >>"$GTD_LOOP_LOG"
       emit_error "'$state' still fails \`gtd validate\` 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
-    emit_action "$M_FIX" "attempt $fix_attempt"
-    run_agent_turn "$content"$'\n\n'"Your last turn does not pass \`gtd validate\`. Fix these format violations, then finish:"$'\n'"$validate_out" "$fix_resume"
+    turn_offset="$(log_offset)"
+    agent_status=0
+    run_agent_turn "$content"$'\n\n'"Your last turn does not pass \`gtd validate\`. 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 step "$actor" 2>&1)"; then

package/dist/gtd.bundle.mjs

@@ -204397,11 +204397,28 @@ const splitQuestionBlocks = (lines, start) => {
 /** A markdown task-list checkbox line: `- [ ]` / `- [x]` / `* [X]`, optional leading indent, optional trailing text. */
 const CHECKBOX_RE = /^\s*[-*]\s*\[([ xX])\]\s?(.*)$/;
 /**
+* The body index of the last line belonging to the list item that starts at
+* `index`: the run of following lines that are neither blank nor a checkbox of
+* their own (see the span rule in the module doc). Indentation is NOT
+* required — an unindented lazy wrap is as much part of the item as an
+* indented one.
+*/
+const itemEndIndex = (body, index) => {
+	let end = index;
+	for (let i = index + 1; i < body.length; i += 1) {
+		const line = body[i];
+		if (line.trim().length === 0 || CHECKBOX_RE.test(line)) break;
+		end = i;
+	}
+	return end;
+};
+/**
 * Extracts the checkbox options from a question block's body, in document
 * order. The LAST option is the free-text slot (`freeText: true`); its text is
 * normalized to `""` when it still carries the unfilled `FREE_TEXT_PLACEHOLDER`.
 * `bodyStart` is the absolute 0-based line index of `body[0]` (the line right
-* after the `###` heading), so each option carries its true source line.
+* after the `###` heading), so each option carries its true source line and
+* span (`itemEndIndex`).
 */
 const parseOptions = (body, bodyStart) => {
 	const raw = [];
@@ -204411,7 +204428,8 @@ const parseOptions = (body, bodyStart) => {
 		raw.push({
 			checked: match[1] !== " ",
 			text: match[2].trim(),
-			sourceLine: bodyStart + i
+			sourceLine: bodyStart + i,
+			bodyIndex: i
 		});
 	});
 	const lastIndex = raw.length - 1;
@@ -204422,7 +204440,8 @@ const parseOptions = (body, bodyStart) => {
 			checked: option.checked,
 			text: normalized,
 			freeText,
-			sourceLine: option.sourceLine
+			sourceLine: option.sourceLine,
+			endLine: bodyStart + itemEndIndex(body, option.bodyIndex)
 		};
 	});
 };
@@ -204704,7 +204723,7 @@ const questionSymbols = (content) => {
 		const children = question.options.map((option) => ({
 			name: `${option.checked ? "[x]" : "[ ]"} ${option.text || "your answer"}`,
 			kind: import_main.SymbolKind.Boolean,
-			range: lineRange(lines, option.sourceLine),
+			range: spanRange(lines, option.sourceLine, option.endLine),
 			selectionRange: lineRange(lines, option.sourceLine)
 		}));
 		return {
@@ -204886,11 +204905,12 @@ const optionCodeAction = (uri, content, question, option) => {
 	};
 };
 /**
-* Code actions for a `qa`-mode file: on an open question's option line, "pick
-* this option" (radio semantics — check it and uncheck every sibling in the
-* same question, so exactly one stays ticked) or "uncheck this option" when it
-* is already the chosen one. No action off an option line, or on an
-* answered-section (prose) question.
+* Code actions for a `qa`-mode file: anywhere on an open question's option's
+* list item — its `- [ ]` line or any of its wrapped continuation lines (see
+* `QuestionOption.endLine`) — "pick this option" (radio semantics — check it
+* and uncheck every sibling in the same question, so exactly one stays
+* ticked) or "uncheck this option" when it is already the chosen one. No
+* action off an option's span, or on an answered-section (prose) question.
 */
 const questionCodeActions = (uri, content, range) => {
 	const { questions } = parseOpenQuestions(content);
@@ -204898,7 +204918,7 @@ const questionCodeActions = (uri, content, range) => {
 	const actions = [];
 	for (const question of questions) {
 		if (question.status !== "open") continue;
-		const option = question.options.find((o) => o.sourceLine === cursorLine);
+		const option = question.options.find((o) => cursorLine >= o.sourceLine && cursorLine <= o.endLine);
 		if (!option) continue;
 		const action = optionCodeAction(uri, content, question, option);
 		if (action) actions.push(action);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {