persistent-state: documented cursor reference ${steps.<id>.outputs.value} does not resolve

[yohamta0]

Summary

writing-workflows/persistent-state.md tells readers to consume a stored value with ${steps.<id>.outputs.value}. That reference does not resolve — it is passed through to the step as a literal string.

The Quick Example is the pattern most people will copy, and it does not work as written.

Where

• The Quick Example, which pipes ${steps.load_cursor.outputs.value} into CURSOR_JSON
• The sentence that follows it: "state.get publishes JSON, so later steps can reference the top-level value as ${steps.load_cursor.outputs.value} and decode nested fields in the consuming command."

Reproduction

steps:
  - id: seed
    action: state.set
    with:
      key: probe/cursor
      value:
        updated_since: "2026-07-01T00:00:00Z"

  - id: load
    action: state.get
    output: CURSOR
    with:
      key: probe/cursor
      default:
        updated_since: "never"
    depends: seed

  - id: show
    env:
      - VIA_REF: ${steps.load.outputs.value}
    run: |
      echo "ENVVAR_CURSOR=[$CURSOR]"
      echo "VIA_REF=[$VIA_REF]"
    depends: load

Output:

ENVVAR_CURSOR=[{"operation":"get","scope":"dag","namespace":"state-probe","key":"probe/cursor","found":true,"version":1,"hash":"...","value":{"updated_since":"2026-07-01T00:00:00Z"}}]
VIA_REF=[${steps.load.outputs.value}]

dagu validate reports it too:

${steps.load_cursor.outputs.value} was left unchanged because the referenced output name is not declared ... reason=unknown_output_name

So the tooling is correct and the documentation contradicts it.

Why it matters

The failure is quiet. A workflow that follows the documented pattern feeds jq the literal text ${steps.load_cursor.outputs.value}, so the parsed cursor is empty or an error string. The subsequent state.set still runs on success, so the workflow keeps reporting success while syncing the wrong window on every run. Cursor and checkpoint workflows are exactly the case this page exists to support.

What actually works

state.get writes a JSON envelope to stdout and publishes no declared output named value. Capture stdout with output: and read through the .value key:

  - id: load_cursor
    action: state.get
    output: CURSOR
    with:
      key: cursors/feed
      default:
        last_id: 0

  - id: fetch
    run: |
      last_id="$(printf '%s\n' "$CURSOR" | jq -r .value.last_id)"
      ./fetch-feed --after "$last_id" > result.json
    depends: load_cursor

Verified end to end: a two-run cycle reads the default on the first run and the value written by the previous run on the second.

Suggested fix

Update the Quick Example and the sentence after it to the output: plus .value form, and state that the step's stdout is an envelope rather than the bare stored value. If ${steps.<id>.outputs.value} is intended to work, this is a code bug rather than a docs bug.