Add a human decision stage that pauses a run for an operator's choice

A new registered stage type `human` (internal/stage/human.go) has no model,
agent, tools or configs: its required `prompt` block carries the operator
instructions and its non-error edges are the selectable options. It parses,
validates, renders, exports and imports like every other type (no parser
special-case, no config keys).

At runtime the runner parks the run instead of executing: the step and the run
persist `waiting` with self-contained {prompt, options} evidence, and the run
returns without starting later stages, capturing file diffs, scanning artifacts,
holding a goroutine/timer or applying a stage timeout. The wait is durable: a
restart leaves the waiting rows untouched (RecoverRuns excludes them) and a
rebuilt runtime over the same database still accepts the decision.

`pipelines decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]` and
the TUI `c` picker resolve the decision from the pinned graph in one store
transaction, record the choice and feedback as the step's evidence and resume
along edges[KEY]. An unknown option is refused with the valid list, a stage that
is not waiting is refused, and a repeated decision for an already-decided visit
does not double-apply. Cancel and retry keep working while waiting and after a
decision; a human stage is never killed by a stage timeout or max_visits, and a
`notify` policy can fire an `on=waiting` event.

Docs: the authoring skill references (format.md, operations.md), docs/cli.md and
README describe the stage, the command and the TUI picker. Tests cover stage
validation, the parsing round-trip, the store transitions, a websocket wait/decide
integration, cancel/retry, waiting notifications and a persistence-layer rebuild
(second Open + newRunner over one database, no process restart).
This commit is contained in:
2026-10-16 16:47:28 +01:00
parent 1b4674d22c
commit a6aff47117
32 changed files with 1782 additions and 87 deletions
+36
View File
@@ -35,6 +35,7 @@ type App struct {
type options struct {
harness string
url, name, prompt, title, template, workspace, paths, key, opencode, model string
option, feedback string
output string
conflict string
all bool
@@ -107,6 +108,9 @@ func (a App) flags(command string) (*flag.FlagSet, *options) {
f.DurationVar(&o.waitTimeout, "wait-timeout", 0, "Client limit for --wait (0 waits until the run ends); independent of --timeout")
case "cancel", "draft-delete":
f.BoolVar(&o.yes, "yes", false, "Confirm this action without an interactive prompt")
case "decide":
f.StringVar(&o.option, "option", "", "Option key to choose among the waiting stage's edges (required)")
f.StringVar(&o.feedback, "feedback", "", "Optional free-text feedback recorded with the decision")
case "debug":
f.StringVar(&o.harness, "harness", "", "Debugging harness: configured opencode/pi, or nvim")
f.BoolVar(&o.yes, "yes", false, "Approve opening a debugging session without prompting")
@@ -778,6 +782,38 @@ func (a App) Run(ctx context.Context, args []string) error {
return a.finishRun(ctx, r, o, call)
}
return a.output(r.RunDetail)
case "decide":
if len(pos) < 1 || len(pos) > 2 {
return fmt.Errorf("decide requires a run ID and an optional stage key")
}
id, err := strconv.ParseInt(pos[0], 10, 64)
if err != nil || id <= 0 {
return fmt.Errorf("run ID must be positive")
}
option := strings.TrimSpace(o.option)
if option == "" {
return fmt.Errorf("decide requires --option KEY")
}
stageKey := ""
if len(pos) == 2 {
stageKey = pos[1]
}
r, err := call(protocol.Message{Type: protocol.DecideRun, RunID: id, Stage: stageKey, Option: option, Feedback: o.feedback})
if err != nil {
return err
}
if r.RunDetail == nil {
return fmt.Errorf("server did not return run detail")
}
if o.json {
return a.output(r.RunDetail)
}
line := fmt.Sprintf("Decided run #%d: %s · %s", r.RunDetail.ID, option, r.RunDetail.Status)
if feedback := strings.TrimSpace(o.feedback); feedback != "" {
line += " · feedback: " + feedback
}
_, err = fmt.Fprintln(a.Out, line)
return err
case "title":
if len(pos) != 2 {
return fmt.Errorf("title requires a run ID and a title")
+2
View File
@@ -20,6 +20,7 @@ var usage = map[string]string{
"runs": "runs [--pipeline NAME] [--json]",
"inspect": "inspect <run-id> [--json]",
"cancel": "cancel <run-id> [--json]",
"decide": "decide <run-id> [stage] --option KEY [--feedback TEXT] [--json]",
"retry": "retry <run-id> [--json [--wait [--wait-timeout DURATION]]]",
"title": "title <run-id> \"<title>\" [--json]",
"debug": "debug <run-id> [--json | --no-open]",
@@ -44,6 +45,7 @@ var notes = map[string]string{
"run": "Runs in your current directory after action confirmation (--yes skips it). Select a pipeline and compose a multiline task with Ctrl+S. Stage tools are enabled automatically; no file list or typed RUN confirmation. Cancellation does not undo edits. --title sets an explicit run title; without it the title is derived from the prompt. In JSON mode --wait polls until terminal; --wait-timeout bounds only the client wait after admission and is independent of per-request --timeout. A reached wait limit leaves the run active: inspect read-only with `inspect <run-id> --json`, or reattach with --wait reusing the original --request-key (never an automatic replay or cancel).",
"retry": "Start a new attempt of a failed run with the same initial input, directory, pipeline version, and edit scope. Original history is retained. Already-completed side effects are not undone. --wait/--wait-timeout behave as for run: a reached wait limit leaves the new run active; inspect read-only with `inspect <run-id> --json`, or reattach with --wait and the original --request-key instead of starting a duplicate retry.",
"title": "Rename a run's operator-facing title after the fact without touching its input, steps or execution. The title is collapsed to a single bounded line and recorded as explicitly set. `pipelines runs` and `pipelines inspect` then show it.",
"decide": "Choose an option for a run waiting on a human stage. The run must be `waiting`; the option must be one of that stage's non-error edges. The stage is inferred from the run's current stage unless named. The choice and optional --feedback are recorded as the step's evidence (visible in inspect and the TUI) and the run resumes along the chosen edge. An unknown option is refused with the valid list; a repeated decision for an already-decided visit does not double-apply. Works across a server restart because the wait is persisted.",
"debug": "Open a fresh configured harness conversation to investigate a run using inspect/show/runs CLI queries. --harness opencode|pi|nvim chooses another configured harness or read-only nvim packet. Does not resume implementation or retry. --json returns the prompt without launching anything.",
"rpc": "Accepts a JSON protocol envelope; '-' reads stdin. Every TUI server operation is available here too. Mutating commands are not dry runs.",
}
+85
View File
@@ -0,0 +1,85 @@
package cli_test
import (
"context"
"encoding/json"
"strconv"
"strings"
"testing"
"git.a-wan.net/alan/pipelines/internal/protocol"
)
const cliHumanSource = "# stage gate\n\n```output\nDecision evidence.\n```\n\n```prompt\nApprove the release.\n```\n\n```edges\ngo -> #success\nhalt -> #failure\nerror -> #failure\n```\n\n```configs\ntype=human\n```\n\n"
func TestCLIDecideWaitingHumanRun(t *testing.T) {
run, store, _ := setup(t)
ctx := context.Background()
if _, err := store.Submit(ctx, "human-ws", cliHumanSource); err != nil {
t.Fatal(err)
}
output, err := run("run", "human-ws", "ship it", "--json", "--yes")
if err != nil {
t.Fatal(err)
}
var started protocol.Message
if err := json.Unmarshal([]byte(output), &started); err != nil || started.RunDetail == nil {
t.Fatalf("run did not return detail: %v %s", err, output)
}
runID := started.RunDetail.ID
waitFor := func(status string) protocol.RunDetail {
t.Helper()
for i := 0; i < 100; i++ {
text, err := run("inspect", strconv.FormatInt(runID, 10), "--json")
if err != nil {
t.Fatal(err)
}
var detail protocol.RunDetail
if err := json.Unmarshal([]byte(text), &detail); err != nil {
t.Fatal(err)
}
if detail.Status == status {
return detail
}
}
t.Fatalf("run never reached %s", status)
return protocol.RunDetail{}
}
waiting := waitFor(protocol.RunStatusWaiting)
if len(waiting.Steps) != 1 || waiting.Steps[0].Status != protocol.StepStatusWaiting {
t.Fatalf("waiting step not visible: %+v", waiting.Steps)
}
if prompt := protocol.WaitingPrompt(waiting.Steps[0].Output); !strings.Contains(prompt, "Approve the release") {
t.Fatalf("waiting prompt not visible: %+v", waiting.Steps[0].Output)
}
if _, err := run("decide", strconv.FormatInt(runID, 10)); err == nil || !strings.Contains(err.Error(), "--option") {
t.Fatalf("missing --option was accepted: %v", err)
}
if _, err := run("decide", strconv.FormatInt(runID, 10), "--option", "launch"); err == nil || !strings.Contains(err.Error(), "valid options") {
t.Fatalf("unknown option was accepted: %v", err)
}
output, err = run("decide", strconv.FormatInt(runID, 10), "gate", "--option", "go", "--feedback", "approved", "--json")
if err != nil {
t.Fatal(err)
}
var decided protocol.RunDetail
if err := json.Unmarshal([]byte(output), &decided); err != nil {
t.Fatal(err)
}
final := waitFor("succeeded")
gate := final.Steps[0]
if gate.Outcome != "go" || gate.Target != protocol.SuccessEnd || gate.Output["feedback"] != "approved" || gate.Diagnostic != "" {
t.Fatalf("decision evidence not recorded: %+v", gate)
}
if gate.Verdict == nil || gate.Verdict.Option != "go → success" || gate.Verdict.Reason != "approved" {
t.Fatalf("derived verdict missing the decision: %+v", gate.Verdict)
}
if _, err := run("help", "decide"); err != nil {
t.Fatal(err)
}
}
+1
View File
@@ -26,6 +26,7 @@ EXECUTE
runs List audited runs; --pipeline filters results
inspect <run-id> Inspect stages, outputs, errors and status
cancel <run-id> Cancel a run; changes are NOT rolled back
decide <run-id> [stage] Choose an option for a run waiting on a person
retry <run-id> Restart a failed run with its original input and directory
title <run-id> "<title>" Rename a run after the fact; input/steps unchanged
debug <run-id> Investigate a run with a configured harness or nvim