> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lint AI workflows that run when nobody is watching

> Find the steps in an AI agent workflow that hang, loop forever or fail silently when it runs unattended: run reliant workflow lint, then fix each finding.

A workflow that a trigger starts runs with nobody watching. A command that waits for input, a loop with no exit or a failure that tells no one shows up hours later, if at all. `reliant workflow lint` reads the workflow file and flags those steps before the first firing. This guide lints a nightly workflow with eight kinds of problem, then fixes each one.

Lint is separate from validation. Validation asks whether a workflow can run. Lint asks whether it will still behave when nobody is watching it. [Workflow lint](https://docs.reliantlabs.io/workflows/lint.md) describes every rule. This guide shows the ones an unattended workflow hits most.

## Before you begin

* The `reliant` CLI, v1.21 or later (`reliant version`). Lint needs no account and no network.
* A workflow with `triggers:`. [Run an AI agent on a schedule](https://docs.reliantlabs.io/guides/workflows/run-an-agent-on-a-schedule.md) shows how to write one.

**1. Lint a workflow written without unattended runs in mind**

This workflow updates dependencies every night and has an agent fix whatever breaks. `concurrency: {max_running: 1}` lets only one run at a time, so a stuck run blocks every later night.

```yaml .reliant/workflows/nightly-deps.yaml theme={null}
name: nightly-deps
title: Nightly dependency update
description: Every night, update dependencies and have an agent fix what breaks until the tests pass.

triggers:
  - name: nightly
    schedule:
      cron: ["0 3 * * *"]
      timezone: UTC

concurrency:
  max_running: 1

entry: [update]

nodes:
  - id: update
    type: run
    command: npm update

  - id: attempts
    type: loop
    while: outputs.exit_code != 0
    inline:
      entry: [fix]
      outputs:
        exit_code: "{{nodes.test.exit_code}}"
      nodes:
        - id: fix
          type: workflow
          ref: builtin://agent
          timeout: 45m
          args:
            mode: auto
          thread:
            mode: fork
            inject:
              role: user
              content: Dependencies were updated. Make `npm test` pass.

        - id: test
          type: run
          command: npm test
      edges:
        - from: fix
          default: test

  - id: approve
    type: action
    uses: http/request@1
    connection: reliant-api
    with:
      url: https://api.reliantapi.com/reliant.v1.ApprovalService/Approve
      method: POST
      body: { approval_id: "{{ workflow.id }}" }

edges:
  - from: update
    default: attempts
  - from: attempts
    default: approve
```

```bash terminal theme={null}
reliant workflow lint
```

```text theme={null}
  ✗ nightly-deps.yaml (nightly-deps)
      Lint error: [slot-unbounded-wait] attempts: the loop's while never reads iter.iteration and it has no items, so nothing bounds it; it can hold this workflow's max_running slot forever (add `&& iter.iteration < N` to while)
      Lint error: [slot-unbounded-wait] attempts.fix: the child's loop builtin://agent → agent_loop has no iteration bound, holding this workflow's max_running slot (bound it with iter.iteration in while)
      Lint error: [slot-unbounded-wait] attempts.test: run node has no timeout; a hung command holds this workflow's max_running slot for the 30-day activity default (set timeout: to the longest the command may take)
      Lint error: [slot-unbounded-wait] update: run node has no timeout; ...
      Lint warning: [no-failure-path] the workflow is started by triggers and has no on_failure or finally, so an unattended run that fails reports to nobody ...
      Lint warning: [scenario-none] the workflow has no scenarios, so none of its triggers or endings is tested ...
      Lint warning: [action-error-unread] approve: nothing reads this node's is_error, so a failed call routes like a successful one ...
      Lint warning: [approval-decider] approve: this step calls Reliant's ApprovalService to approve or deny, so the workflow can decide approvals, including its own run's, with the token it holds ...
      Lint warning: [timeout-ignored] attempts.fix: timeout: on a workflow node bounds nothing ...
      Lint warning: [requires-undeclared-tool] attempts.test: the command calls npm, which requires.tools does not list ...
      Lint warning: [requires-undeclared-tool] update: the command calls npm, which requires.tools does not list ...
      Lint warning: [run-exit-code-unread] update: nothing reads this node's exit_code, so a failed command routes like a successful one ...

1 workflow(s): 4 lint error(s), 8 warning(s)
```

Each finding names its rule and the node, and ends with a link to the rule's section of the docs (trimmed here). An error makes the command exit `1`. A warning is printed and the command still exits `0`. `reliant workflow validate` runs the same rules, so the same four errors fail validation too.

**2. Bound every step that can hold the slot**

With `max_running`, anything that can wait without limit is an error ([slot-unbounded-wait](https://docs.reliantlabs.io/workflows/lint.md#slot-unbounded-wait)). Without `concurrency:`, the same file gets warnings instead: `[loop-unbounded] attempts` and `[run-no-timeout]` on `update` and `attempts.test`.

* **Commands:** give each `run` node a `timeout:`, the longest the command may take. Without one, it runs for the 30-day default.
* **The loop:** add `&& iter.iteration < 3` to `while`, so a fix that never works ends after three rounds.
* **The agent:** give it a turn limit. In v1.21.3 `builtin://agent` takes none, so the fixed version below uses `builtin://structured-agent` with `max_turns: 60`, the agent used for structured results in [Write your first multi-agent workflow](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow.md). Later releases accept `max_turns` on `builtin://agent` too: set it there and keep the agent. Left at `0` (no limit), lint names the arg to set, as a warning.

Then delete `timeout: 45m` from `fix`. A workflow node dispatches no activity of its own, so its `timeout:` bounds nothing ([timeout-ignored](https://docs.reliantlabs.io/workflows/lint.md#timeout-ignored)).

**3. Remove the step that approves its own gate**

`approve` calls the approvals API with a saved token, so the workflow could approve requests, including the ones its own run raises. Lint cannot see what the token allows, so it treats any token that can decide approvals as able to ([approval-decider](https://docs.reliantlabs.io/workflows/lint.md#approval-decider)). This workflow has no reason to approve anything, so delete the step.

When approving is the job of a workflow, declare it with `permissions: [approvals:decide]` and allow the finding on that key, with the reason:

```yaml .reliant/workflows/approve-bot.yaml theme={null}
# lint:allow approval-decider — deciding approvals is this workflow's job; its token can decide nothing else
permissions: [approvals:decide]
```

A `lint:allow` with no reason is itself an error: `[lint-allow-invalid] lint:allow approval-decider gives no reason`.

**4. Make every failure reach someone**

* **Read the exit code.** A non-zero exit does not fail a `run` node. Route `update` on `nodes.update.exit_code`, so a failed update goes to a failure ending instead of to the agent.
* **Add `on_failure:`.** A run that fails, or ends at a node with `outcome: failure`, then saves a message that tells someone.
* **Declare the tools.** `requires: {tools: [npm]}` makes a machine without `npm` fail before the first step, not halfway through.
* **Add scenarios** for the trigger and both endings, as in [Test AI agent workflows with scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md).

**5. Verify the workflow is clean**

The fixed workflow:

```yaml .reliant/workflows/nightly-deps.yaml theme={null}
name: nightly-deps
title: Nightly dependency update
description: Every night, update dependencies and have an agent fix what breaks until the tests pass.

triggers:
  - name: nightly
    schedule:
      cron: ["0 3 * * *"]
      timezone: UTC

concurrency:
  max_running: 1

requires:
  tools: [npm]

entry: [update]

nodes:
  - id: update
    type: run
    command: npm update
    timeout: 10m

  - id: attempts
    type: loop
    while: outputs.exit_code != 0 && iter.iteration < 3
    inline:
      entry: [fix]
      outputs:
        exit_code: "{{nodes.test.exit_code}}"
      nodes:
        - id: fix
          type: workflow
          ref: builtin://structured-agent
          args:
            mode: auto
            max_turns: 60
          thread:
            mode: fork
            inject:
              role: user
              content: Dependencies were updated. Make `npm test` pass.

        - id: test
          type: run
          command: npm test
          timeout: 15m
      edges:
        - from: fix
          default: test

  - id: green
    type: save_message
    outcome: success
    args:
      role: assistant
      content: Dependencies updated and the tests pass.

  - id: still_red
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: npm update or npm test still fails. Read the run for the output.

edges:
  - from: update
    cases:
      - to: attempts
        condition: nodes.update.exit_code == 0
    default: still_red
  - from: attempts
    cases:
      - to: green
        condition: nodes.attempts.exit_code == 0
    default: still_red

on_failure:
  entry: [tell]
  nodes:
    - id: tell
      type: save_message
      args:
        role: assistant
        display_style: warning
        content: "nightly-deps failed at {{failure.node_id}}: {{failure.error}}"
```

With two scenarios in `.reliant/workflows/nightly-deps/scenarios/` (the nightly firing ending at `green`, and three red rounds ending at `still_red`):

```bash terminal theme={null}
reliant workflow lint
```

```text theme={null}
  ✓ nightly-deps.yaml (nightly-deps)

1 workflow(s): 0 lint error(s), 0 warning(s)
```

For CI, `reliant workflow lint --json` prints each finding's `rule`, `severity`, `node`, `message`, `fix` and `docs`. To lint and validate in one gate, run `reliant workflow validate --base origin/main`, which also reports trigger changes that would break existing activations.

## What this does not do

* **It does not stop a workflow from running.** Lint never runs when a workflow is saved or started, so a rule added in a later release cannot stop an automation that already fires. Gate your repository on `validate` or `lint` yourself.
* **It reads only the file.** Lint never runs the workflow, and it cannot see what a saved connection or a hosted secret can do. A clean lint does not mean every path works: that is what [scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md) test.
* **It bounds steps, not spend.** `max_turns`, loop bounds and timeouts cap how long each step runs. They do not set a token budget for the run.

## Troubleshooting

> [accordion] \[slot-unbounded-wait] … the child's loop builtin://agent → agent\_loop has no iteration bound
>
> Reliant releases before `builtin://agent` took `max_turns` report the agent this way, as an error whose fix text (editing the loop's `while`) you cannot follow, because the loop is inside the built-in agent. On those, use `builtin://structured-agent` with `max_turns`. On a release whose finding reads "is bounded only by its max\_turns input", set `args.max_turns` on the node. Or, if you have judged that the agent's run is bounded enough, allow the finding on the node with `# lint:allow slot-unbounded-wait — <why>`.

> [accordion] \[lint-allow-invalid] lint:allow … gives no reason
>
> Write the reason after the rule ID: `# lint:allow <rule> — <why it is fine here>`. The rule ID must be one that `reliant workflow lint --rules` lists.

> [accordion] validate lists lint warnings but its summary says Warnings: 0
>
> In reliant v1.21.3 the `Warnings:` count in the `validate` summary does not include lint warnings. Read the `Lint warning:` lines above the summary, or run `reliant workflow lint`, whose last line counts them.

## Next steps

> [card] [Test AI agent workflows with scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md)
>
> Cover every trigger and ending with mocked runs.

> [card] [Run an AI agent on a schedule](https://docs.reliantlabs.io/guides/workflows/run-an-agent-on-a-schedule.md)
>
> Turn the trigger on and watch its firings.

> [card] [Loop an agent until tests pass](https://docs.reliantlabs.io/guides/workflows/run-tests-until-they-pass.md)
>
> A bounded fix-and-test loop, step by step.

> [card] [Workflow lint rules](https://docs.reliantlabs.io/workflows/lint.md)
>
> Every rule, its severity and how to fix it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.