Add human-in-the-loop workflow steps

[DavidWells]

Problem

Some multi-step Agent Runner flows need a deliberate human checkpoint between agent steps. Today each step is effectively modeled as "submit agent work, wait for agent results." That works for fully automated review/synthesis/implementation chains, but it does not model cases where a person should review the previous output, approve or stop, and optionally add extra context before the next agent run starts.

Human-in-the-loop should be a first-class step type rather than a prompt convention. It needs its own wait state, durable artifact, resume behavior, and notification path.

Proposed flow.yml shape

- id: review-plan
  title: Review Documentation Plan
  type: human
  description: Review the synthesized documentation plan before implementation.
  after:
    - synthesize
  waitFor: human-approval
  input:
    - step: synthesize
      results: all
  instructions: |
    Review the plan. Add any constraints, priorities, or exclusions before implementation.
  approval:
    mode: approve-or-edit
    timeout: 7d
    onTimeout: pause

A later agent step should be able to consume the human response like any other prior step result:

- id: implement
  title: Implement Documentation
  prompt: prompts/3_implement-docs.md
  action: comment
  submit: follow-up
  agents: [codex]
  input:
    - step: synthesize
      results: all
    - step: review-plan
      results: human
  waitFor: agent-results

Approval modes

Initial modes could include:

approval:
  mode: approve        # continue or stop

approval:
  mode: approve-or-edit # continue, but allow extra context

approval:
  mode: choose
  options:
    - implement-all
    - implement-p0-only
    - stop

approval:
  mode: checklist
  required:
    - "Scope is correct"
    - "No risky files included"

Human step artifact

A human step should produce a durable result artifact, similar to agent step output:

{
  "stepId": "review-plan",
  "status": "approved",
  "approvedBy": "github-user",
  "approvedAt": "2026-05-21T12:34:56Z",
  "comment": "Only implement README and ARCHITECTURE.md. Skip CONTRIBUTING.md.",
  "selectedOption": "implement-p0-only"
}

This artifact should be available to later prompts through normal step input formatting and persisted under .nax/workflows/... with the rest of the workflow state.

Action surfaces

Possible places where the human can act:

• GitHub issue comment with commands:
  • /nax approve
  • /nax approve Only fix README
  • /nax stop
  • /nax choose implement-p0-only
• GitHub issue labels:
  • add nax:waiting-human while paused
  • remove it after approval/stop
• GitHub Actions job summary:
  • show "waiting for human"
  • link to the approval issue/comment
  • show the exact command(s) accepted
• Local Netlify API run:
  • print the approval URL/path
  • persist workflow as paused
• nax resume:
  • detects paused human step
  • prompts locally for approval/context
  • records the human artifact and resumes downstream steps

Notification channels

Separate where the human acts from how they are notified.

Possible notification config:

notify:
  onWait:
    github:
      assign: ["octocat"]
      labels: ["nax:waiting-human"]
      mention: ["@octocat"]
    webhook:
      urlEnv: NAX_NOTIFY_WEBHOOK_URL

Potential channels:

• GitHub mention in the waiting comment
• GitHub issue assignment
• GitHub label/project board status
• Slack/Discord/webhook later via a generic notify block
• Existing macOS desktop notification for local runs
• Email only if there is already a Netlify notification service to use

Suggested v1 scope

1. Add type: human and waitFor: human-approval to flow normalization.
2. For GitHub transport, post a waiting comment and pause the workflow.
3. For local/Netlify API transport, persist paused state and let nax resume collect approval/context.
4. Store human output as a durable workflow artifact.
5. Let later steps consume human output with input: [{ step: ..., results: human }].
6. Add basic GitHub labels/assignment/mentions for notification.

Design constraint

Paused human steps must be resumable and auditable. They should not rely on terminal scrollback or memory of what happened in a previous run.