@pmelab/gtd 7.1.1 → 7.3.0

package/docs/cli.md

@@ -30,6 +30,12 @@ Commands:
                    the commit the process started from, keeping everything it
                    produced as uncommitted changes. A no-op when no process is
                    underway
+  restore          Hard-reset HEAD back to the pre-squash tip retained by the
+                   last squash/abandon (refs/worktree/gtd/history), undoing a
+                   squash or bringing back an abandoned process's turns.
+                   Refuses on a dirty working tree, when there is no retained
+                   history, or when HEAD has advanced past the squash with
+                   commits that would be lost
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   status           Print the resolved rest's state/actor and which declared
@@ -295,6 +301,47 @@ hash HEAD now points at:
 
 The no-op reports `{"state": "idle", "abandoned": false}` and still exits 0.
 
+## `gtd restore [--json]`
+
+Undoes the last squash or `gtd abandon` by hard-resetting HEAD back to the
+pre-squash tip that either one retains, before acting, on the per-worktree
+`refs/worktree/gtd/history` ref
+([STATES.md §8](../STATES.md#8-the-squash-lifecycle)):
+
+```
+restored the retained history — HEAD is back at 1a2b3c4 ("gtd(agent): drafting
+→ working"), resting at "await-review". Resume with the loop, or `git reset`
+to any earlier turn to restart from there.
+```
+
+Refuses on a dirty working tree — commit, stash, or discard your changes first.
+Refuses when there is no retained history to restore (nothing has been squashed
+or abandoned yet, or a previous `restore` already consumed it). Refuses when
+HEAD has advanced past the retained tip with commits that would be discarded by
+resetting:
+
+```
+gtd restore: HEAD has advanced past the squash — restoring would discard
+commits built on top of it — HEAD 4d5e6f7 is ahead of the retained tip
+1a2b3c4.
+```
+
+Takes no positional argument (extra arguments are a usage error).
+
+`--json` emits `{state, restored, to, from}` — `state` is the resolved rest
+after the reset, `restored` always `true` (a refusal exits non-zero instead),
+`to` the full hash HEAD was reset to, and `from` the state the machine rested at
+before the reset:
+
+```json
+{
+  "state": "await-review",
+  "restored": true,
+  "to": "1a2b3c4…",
+  "from": "idle"
+}
+```
+
 ## `gtd next [--json]`
 
 Pure emitter of the resolved rest's rendered content — it **never mutates** the
@@ -496,9 +543,17 @@ cleanly.
 ## `gtd visualize [--port=<n>] [--no-open] [--json]`
 
 Serve an interactive diagram of the ACTIVE workflow on a local web server: the
-main flow as a graph (one box per sub-machine), and a click-through inspector
-with each state's actor, content kind, model/memory, steering file+mode, retry,
-flags, and outgoing/incoming edges. This is the replacement for the removed
+main flow as a graph (each sub-machine invocation collapsed into a single opaque
+black-box node — click it to jump to that sub-machine's own diagram, rendered
+separately below with its true member states/shapes/colours and a muted ghost
+node for any edge leaving the group; every diagram supports scroll-to-zoom,
+drag-to-pan, and a corner `+`/`−`/fit control cluster), a click-through
+inspector with each state's actor, content kind, its own raw
+prompt/message/script text, model/memory, steering file+mode, retry, flags, and
+outgoing/incoming edges, and — read ONCE at page load, never polled — a "Current
+state" panel showing where the active process rests, its pending changes, and
+which `on` pattern (or retry redirect) currently leads where, with the resting
+node highlighted in the diagrams. This is the replacement for the removed
 `gtd mermaid` — a live viewer instead of a static diagram dump.
 
 ```
@@ -506,25 +561,34 @@ $ gtd visualize
 gtd visualize running at http://127.0.0.1:53017 — Ctrl-C to stop
 ```
 
-The server serves two routes: `/` (the self-contained HTML page) and
-`/workflow.json` (the model the page renders). It runs until interrupted
+The server serves three routes: `/` (the self-contained HTML page),
+`/workflow.json` (the model the page renders), and `/state.json` (the current
+process's resting state, or `{}` when there isn't one — not a repo, no commits,
+or an older server; the browser tolerates either). It runs until interrupted
 (Ctrl-C), then closes cleanly. Options (orthogonal, `gtd visualize` only):
 
 - `--port=<n>` (or `--port <n>`) — serve on a specific port (0–65535); the
   default is a free ephemeral port, printed on start.
 - `--no-open` — do not open the default browser (the URL is always printed).
 - `--json` — print the workflow model to stdout and exit WITHOUT starting a
-  server. The model is `{ states, initial, groups, vars }`; each state carries
-  its `actor`/`kind`/`model`/`memory`/`file`/`mode`/`retry`/`flags`, its `on`
-  edges, its computed `incoming` edges, and its sub-machine `group`. `groups`
-  lists each sub-machine invocation and the concrete states it produced.
+  server (unchanged shape — live state is a server-only concern). The model is
+  `{ states, initial, groups, vars }`; each state carries its
+  `actor`/`kind`/`content`/`model`/`memory`/`file`/`mode`/`retry`/`flags`
+  (`content` is the state's own raw script/prompt/message text, omitted for a
+  commit state), its `on` edges, its computed `incoming` edges, and its
+  sub-machine `group`. `groups` lists each sub-machine invocation and the
+  concrete states it produced.
 
 Dispatched before the repository-root guard and the config-reading path's review
 window — it reads the active workflow (the built-in default when none is
-configured) but touches no git/HEAD/review-window state. The diagram is rendered
-with Mermaid loaded from a CDN, so the graph needs network access the first time
-a browser loads the page; the inspector works offline regardless. Rejects
-unknown options and unexpected positional arguments.
+configured) but touches no git/HEAD/review-window state ITSELF; the
+`/state.json` route best-effort reads git state per request instead (any failure
+— not a repo, no commits — serves `{}`), preferring the review checkout window's
+saved head over HEAD so a request landing mid-window still reports the state the
+process actually rests at. The diagram is rendered with Mermaid loaded from a
+CDN, so the graph needs network access the first time a browser loads the page;
+the inspector and current-state panel work offline regardless. Rejects unknown
+options and unexpected positional arguments.
 
 ## Error envelope
 

package/docs/configuration.md

@@ -261,6 +261,38 @@ value) only when the resolved state declares one — **omitted entirely**, never
 `null`, when unset. Plain `gtd status` prints a `Memory:` line (right after
 `Model:`, when present).
 
+### `label:` — the opaque display name, template-rendered
+
+A state may declare `label: <string>` — an OPAQUE display name gtd never
+interprets; it is only passed through so a driver/viewer can show something
+friendlier than the raw state name. Unset means the state has no display name.
+Forbidden on a commit state (never at rest, emits nothing):
+
+```yaml
+workflow:
+  states:
+    working:
+      actor: agent
+      label: Implement the feature
+      prompt: do the thing
+      on:
+        "* **": done
+```
+
+Like `model`/`memory`, `label:` is rendered as an Eta template through the exact
+same context as the state's content — a plain string with no Eta tags
+(`Implement the feature` above) passes through unchanged, but
+`label: "<%= it.vars.stateLabel %>"` resolves against the merged `it.vars` (see
+["Variables"](#variables)). A render failure behaves exactly like a content
+render failure at the same call site: `gtd next`/`gtd status` error out, nothing
+committed.
+
+`gtd next --json` and `gtd status --json` include a `"label"` key (the RENDERED
+value) only when the resolved state declares one — it is **omitted entirely**,
+never emitted as `null`, when unset. A driver/viewer choosing to fall back to
+the raw state name when `label` is absent is that consumer's own fallback, not
+something gtd itself does.
+
 ### `file:`/`mode:` — the steering-file association
 
 A state may additionally declare `file:` — an Eta template naming THE steering

package/docs/loop.md

@@ -18,13 +18,18 @@ DRIVER runs the emitted `content` and then steps that state's own actor.
 A loop is a simple cycle:
 
 1. Run `gtd next --json` — see [`cli.md`](cli.md#gtd-next---json) for the exact
-   `{state, actor, kind, content, model?, memory?}` field shape. `kind` is the
-   dispatch key: `"message"` → halt (a human rest); `"script"` → execute
+   `{state, actor, kind, content, model?, memory?, label?}` field shape. `kind`
+   is the dispatch key: `"message"` → halt (a human rest); `"script"` → execute
    `content` verbatim (ignoring its exit code), then `gtd step <actor>` to
    capture the outcome; `"prompt"` → feed `content` to the agent, then
    `gtd step <actor>` yourself once it's done acting. The optional `model` is an
    opaque string the workflow author chose, which you map onto your own
-   harness's model selection if you use one.
+   harness's model selection if you use one. The optional `label` is a
+   human-readable display name for the resolved state, present only when that
+   state declares `label:` in the workflow; when it's absent, a driver that
+   wants to show something falls back to `state` itself (that fallback lives in
+   the driver, not gtd core — see `bin/gtd-loop`'s
+   `label="$(jq -r '.label // .state' <<<"$next_json")"`).
 2. Repeat until a `"message"` rest halts the loop, or a zero-commit script step
    at idle settles it (the green terminal signal).
 
@@ -162,3 +167,35 @@ example, to drive a different agent CLI:
 ```bash
 GTD_LOOP_AGENT_CMD='my-agent-cli --prompt "$GTD_LOOP_PROMPT"' gtd-loop
 ```
+
+## Herdr integration (optional)
+
+`bin/gtd-loop` optionally reports its lifecycle to [Herdr](https://herdr.dev) (a
+terminal multiplexer for coding agents) via a `herdr` CLI binary, entirely at
+the driver's edge — gtd core never talks to Herdr. Every call is best-effort
+(guarded, output discarded, `|| true`), so a missing/failing `herdr` binary
+never blocks, slows, or fails the loop.
+
+The reporting is a no-op unless all three guard conditions hold: `HERDR_ENV=1`,
+a non-empty `$HERDR_PANE_ID`, and `herdr` on `$PATH`. When they do, `gtd-loop`
+makes three kinds of calls:
+
+- `herdr pane report-agent --source herdr:gtd --agent gtd --state <state> --message <label> "$HERDR_PANE_ID"`
+- `herdr pane release-agent --source herdr:gtd --agent gtd "$HERDR_PANE_ID"`
+- `herdr notification show <title> --body <label> --sound request`
+
+mapped onto the loop's states like this:
+
+| Loop moment                                                                          | Call(s)                                                                  |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| Top of every non-`"message"` iteration                                               | `report-agent --state working`                                           |
+| Right before halting at a `"message"` (human) gate                                   | `report-agent --state blocked` + `notification show`                     |
+| Right before a clean settle (a script rest, zero new commits)                        | `report-agent --state idle` + `release-agent`                            |
+| Any non-zero exit (stall guard, validate-cap, `gtd next` failure, unhandled failure) | `report-agent --state blocked` + `notification show`, via an `EXIT` trap |
+
+`working`/`blocked` reports use the resolved rest's `label` (falling back to
+`state`, per the field above); the trap falls back to `$GTD_LAST_LABEL`, the
+label tracked from the last completed iteration, when it fires outside the
+normal per-iteration flow. `report-agent` claims display authority for the
+`herdr:gtd` source, so `working` is re-reported every lap rather than once, to
+stay fresh against Herdr's own heuristic detection of the inner agent process.

package/package.json

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