feat(engine): add type: terminate step (#219)

[jrob5756]

Closes #219.

Adds a new type: terminate workflow step that ends the workflow with an explicit status (success | failed) and a structured reason, distinguishable from the default $end path in the CLI exit code, dashboard state, and event logs.

Motivation

Real workflows have multiple legitimate end states beyond "the last agent finished":

• Early success — "the document is already up to date; no work needed"
• Soft abort — "no matching issues found, nothing to do"
• Hard failure with reason — "upstream returned data we cannot process; stop and surface the cause"
• Pre-condition not met — "this PR is from a fork; refusing to run the publish step"

With only $end, all of these collapse into "workflow completed" in CI exit codes, dashboards, and JSONL logs. Downstream tooling cannot distinguish a clean no-op from a real failure. type: terminate makes the distinction explicit.

Shape

agents:
  - name: precheck
    prompt: "Is the input safe to process? Return {safe: bool, reason: string}"
    output:
      safe:   { type: boolean }
      reason: { type: string }
    routes:
      - when: "not precheck.output.safe"
        to: abort_unsafe
      - to: main_pipeline

  - name: abort_unsafe
    type: terminate
    status: failed              # success | failed (required)
    reason: "{{ precheck.output.reason }}"
    output_template:            # optional; replaces workflow-level output:
      aborted: "true"
      stage: precheck
      reason: "{{ precheck.output.reason }}"

  - name: noop_exit
    type: terminate
    status: success
    reason: "Document already up to date; no edits needed."

See examples/terminate.yaml for a complete worked example.

Behaviour

status	CLI exit	Dashboard	Event	Resumable?
success	0	✅	workflow_completed { termination_reason, terminated_by, is_explicit: true, status }	n/a (clean exit)
failed	1	❌	workflow_failed { error_type: "WorkflowTerminated", termination_reason, terminated_by, is_explicit: true, status, output }	No — explicit terminations skip the on-failure checkpoint

• Reaching a terminate step ends the workflow immediately — no routes evaluated after.
• status: failed raises WorkflowTerminated (subclass of ExecutionError); the CLI prints the rendered output JSON to stdout and surfaces the reason banner on stderr, then exits non-zero.
• Sub-workflow boundary: a status: failed terminate inside a child sub-workflow is downgraded at the parent boundary to SubworkflowTerminatedError (also an ExecutionError), preserving the child's rendered terminated_output / terminated_reason / terminated_by as structured attributes. The parent treats it as a normal sub-workflow failure (its own workflow_failed does NOT inherit is_explicit: true). A status: success child terminate returns its rendered output cleanly and the parent continues.
• Restrictions: terminate steps cannot have routes, tools, output, prompt, model, etc.; cannot appear as parallel-group members or as a for_each inline agent (route to one from those groups' routes: instead). Conversely, status / reason / output_template are rejected on every non-terminate step type so authors who forget type: terminate get a clear error rather than silently dropped fields.

Acceptance criteria

• type: terminate accepted with status, reason, optional output_template
• Schema rejects routes / tools / output / forbidden fields on terminate steps
• Reaching a terminate step ends the workflow without evaluating subsequent routes
• CLI exit code matches status: (0 vs non-zero)
• workflow_completed / workflow_failed event includes termination_reason and terminated_by
• Dashboard shows terminate steps distinctly — new TerminateNode component (Octagon icon, status-themed border, sub-label terminate · success / terminate · failed, body shows rendered reason); NodeTooltip shows a green/red Termination row plus the full reason on hover; WorkflowSuccessBanner and WorkflowErrorBanner render "Workflow Terminated" (instead of generic "Completed" / "Failed") with the rendered reason and terminated_by line when is_explicit: true. See commit ec5be86.
• Sub-workflow terminate ends just the sub-workflow; parent continues normally
• Example under examples/terminate.yaml
• Tests for: success termination, failure termination, terminate inside sub-workflow (sequential and for_each-of-workflow paths), terminate routed from a parallel group, terminate routed from for_each

Implementation overview

Layer	What changed
src/conductor/exceptions.py	New WorkflowTerminated(ExecutionError) (carries output, reason, terminated_by, status) and SubworkflowTerminatedError(ExecutionError) (carries terminated_output, terminated_reason, terminated_by)
src/conductor/config/schema.py	Added terminate to AgentDef.type Literal; new status, reason, output_template fields with per-type forbidden-field enforcement (in both directions)
src/conductor/config/validator.py	Forbid terminate inside parallel-group members and for_each inline agents; treat terminate as a sink in routing graph / path enumeration; output-coverage analysis skips terminate paths that supply their own output_template; Jinja2 templates in reason and output_template validated at config-load time
src/conductor/engine/workflow.py	New dispatch branch in _execute_loop (placed before human_gate/script/workflow); dedicated except WorkflowTerminated arm that emits workflow_failed and skips checkpoint save; _run_child_engine() boundary helper used by both sub-workflow paths converts child WorkflowTerminated → SubworkflowTerminatedError; _build_terminate_output() handles the output_template-vs-fallback logic and emits agent_failed on template render errors
src/conductor/cli/app.py + cli/run.py	WorkflowTerminated handlers in both run and resume commands (split stdout JSON / stderr banner / suggestion); resume-instruction suppression for WorkflowTerminated (defense-in-depth)
Docs	docs/workflow-syntax.md Terminate Steps section; examples/README.md Explicit Termination section; plugins/conductor/skills/conductor/{SKILL.md,references/yaml-schema.md,references/authoring.md}; README.md features + examples table; AGENTS.md; CHANGELOG.md
Tests	46 new tests across schema (20), validator (9), engine (14), sub-workflow (4 incl. _with_inputs path), CLI (4), exception (4). Full suite: 2839 passed, 16 skipped.

Review process

This PR went through a comprehensive review pass after the initial implementation, using six specialised reviewer agents (code, tests, comments, silent-failure, type-design, dead-code). The PR-review-polish commit (da82f9b) addresses every critical and important finding before this submission:

• Hardened json.dumps in the CLI handler (default=str + try/except) so a non-serialisable output value cannot crash the CLI and lose the termination reason.
• Introduced SubworkflowTerminatedError so the child's rendered output_template is preserved across the parent boundary as a structured attribute (previously silently dropped).
• Type polish on WorkflowTerminated: dropped the dead status parameter, made terminated_by a property over agent_name (eliminates drift), tightened output: dict → dict[str, Any].
• Reordered check_timeout() before record_execution() in the dispatch branch so a workflow at max_iterations cannot mask explicit termination behind MaxIterationsError.
• Wrapped _build_terminate_output() so a template error emits agent_failed (prevents dashboard "stuck agent" state).
• 15 additional tests for CLI stdout/stderr split, resume failed-terminate parity, terminate as entry-point / routed from parallel-group / routed from for_each, on_complete/on_error hook firing, event ordering, child-output preservation, for_each-of-workflow _with_inputs path, schema cross-product rejection.

Commits

1. 35d010e feat(engine): add type: terminate step
2. da82f9b refactor(terminate): apply PR-review polish
3. edb58ea docs(terminate): document type: terminate across user-facing docs
4. ec5be86 feat(web): render type: terminate steps distinctly in dashboard

Out of scope (suggested follow-ups)

• Discriminated-union step types — AgentDef's single-model-for-all-types pattern is now visibly straining (~140 lines of per-type forbidden-field enforcement); worth tracking but explicitly out of scope here for consistency with existing patterns.
• Broader _print_resume_instructions suppression for all non-resumable ConductorError subclasses (currently only WorkflowTerminated skips the hint).

🤖 Co-authored with Copilot CLI.