No way to end a run early and successfully — every early exit is a failure

[khaliqgant]

Problem

A workflow cannot say "there is nothing to do here, stop, and that is fine." Every early exit is a step failure that fails the whole run.

Verified with a minimal workflow:

steps:
  - name: skipper
    type: deterministic
    command: "sh -c 'echo skipping; exit 78'"
  - name: after
    type: deterministic
    command: "echo AFTER_RAN"
    dependsOn: [skipper]
errorHandling:
  strategy: fail-fast

✗ skipper — FAILED: Command failed with exit code 78
○ after — skipped
[workflow] FAILED: Step "skipper" failed

There is also no conditional-step mechanism to route around it — the schema has no condition, when, skipIf, onlyIf, or if on any step type (checked all seven: WorkflowStep, AgentWorkflowStep, DeterministicWorkflowStep, WorktreeWorkflowStep, IntegrationWorkflowStep, WaitForWorkflowStep, CustomWorkflowStep).

Why it matters

"Nothing to do" is not an exception in a scheduled pipeline — it is the common case. Three examples from one real customer workflow, all of which are correct outcomes:

• the brand is switched off behind a rollout flag
• a circuit breaker has auto-disabled the brand after repeated failures
• hourly cron, a manual trigger and a task redelivery raced for the same tick, and this one lost the claim

At ~3,000 brands ticking hourly, the third alone means a large and constant stream of runs that are supposed to stop early. Today every one of them is recorded as a failed run.

That inverts the signal. A dashboard that is permanently red teaches operators to stop reading it, and then a genuine failure is indistinguishable from the background. This customer's previous engine died silently for weeks for exactly that reason, so it is the specific failure mode the design is trying to avoid.

Current workaround, and why it is unsatisfying

The gate has to move outside the workflow: the caller runs a check first and only triggers a run for work that should proceed.

if node bin/check-breakers.mjs; then
  relayflows run workflows/autopilot-tick.yaml
fi   # exit 78 -> skip quietly, trigger nothing

This works and is arguably better architecture for a brand-level flag. It does not help the in-run cases. Losing a claim race can only be discovered inside the run — by then the workflow has started, and its only ways to stop are "fail" or "run the remaining steps anyway", which for agent steps means paying for model calls that should not happen.

Suggestions

Either would solve it; the first is smaller.

1. A terminal-success exit. A reserved exit code, or a sentinel a step can emit, meaning end this run here, mark it succeeded, skip the rest. Downstream steps report skipped, the run reports completed.
2. Conditional steps. A condition/when on a step, evaluated against prior step output, so a workflow can branch around work it does not need to do.

A distinct terminal state (completed_early / no_op) rather than plain completed would be even better — it keeps "ran and did work" separable from "correctly did nothing" without either being an error.

[khaliqgant]

Design proposal (requesting approval before implementation)

I propose Option 1: an explicit terminal-success exit, scoped to deterministic steps.

Public surface

steps:
  - name: claim-work
    type: deterministic
    command: node bin/claim-work.mjs
    terminalSuccessExitCodes: [78]

  - name: do-work
    type: agent
    agent: worker
    task: Do the claimed work
    dependsOn: [claim-work]

terminalSuccessExitCodes would also be available on reusable custom deterministic step definitions and in the TypeScript builder's deterministic-step options. It is an opt-in list so no exit code gains new meaning globally.

Exact semantics

• A deterministic step carrying terminalSuccessExitCodes is a scheduler barrier: once it is ready, the runner evaluates it before launching other ready steps in that DAG wave. This makes a root gate reliable rather than allowing expensive sibling work to race the gate.
• If the command exits with a listed code:
  • the triggering step is recorded as completed, with its output/exit evidence retained and a new completion reason identifying the early exit;
  • every step that has not started is recorded as skipped with a reason naming the terminal step;
  • no retries or repair-agent work are triggered for the listed code;
  • the run is recorded as the distinct terminal status completed_early, never plain completed;
  • a distinct run:completed-early event is emitted, and the CLI prints “completed early” and exits 0.
• An exit code not in the list follows today's behavior exactly. With the default failOnError: true, it fails the step/run and downstream steps are skipped.
• If already-running work reports a genuine failure, failure wins; the terminal-success signal must not mask it.
• If a terminal-capable step exits normally without a listed code, scheduling resumes normally. Including 0 in the list is allowed but must be explicit.
• If verification is configured on the terminal step, verification still runs; a failed verification remains a real failure rather than being hidden by the exit-code classification.

Status/reporting model

• Run status union adds completed_early.
• Trigger step remains completed but carries a dedicated completion reason such as completed_early_exit, so the exact gate and exit evidence remain discoverable.
• Not-started steps are skipped, not failed, and summaries/dashboard output label the overall run COMPLETED EARLY.
• Cloud polling and all terminal-status checks must recognize completed_early as terminal while preserving it as a separate value.

Compatibility / what could break

There is no behavior change for existing workflows: absent terminalSuccessExitCodes, exit 78 and every other non-zero exit keep their current meaning. No existing exit code is reserved or reinterpreted.

The additive status/event surface can still affect consumers that use exhaustive switches, strict runtime validators, database enum/check constraints, or assume the only successful terminal status is completed. Those consumers will need to recognize completed_early; the CLI will treat it as a successful process outcome (exit 0) while still displaying the distinct status. I will call this out prominently in the PR and release notes.

Test-first plan

Before implementation I will add the issue's minimal reproduction with terminalSuccessExitCodes: [78] and assert:

1. it fails against current code;
2. after the fix, the gate is completed, remaining steps are skipped/not invoked, and the run is completed_early;
3. an unlisted non-zero exit still yields a failed step/run;
4. without the opt-in field, exit 78 still fails exactly as it does in v1.0.7;
5. CLI/event reporting preserves the early-completion distinction.

Please approve this surface/semantics or request changes. I will not change code until there is explicit human approval.