kew run

Pick the next ready issue and dispatch the configured runner to implement it.

Usage: kew run [OPTIONS] [ACTION] [TARGET_RUN_ID]

Options:
  --loop          Continuous mode until queue empty
  --dry-run       Preview issue selection without running
  --show-prompt   Print the generated prompt and exit
  --issue INT     Force a specific issue number
  --workers INT   Number of parallel workers (overrides config)
  --force         Bypass budget checks
  --model TEXT    Override model for this dispatch
  --approve       Approve this dispatch past the approval gate (requires --issue)

Examples:

# Single dispatch (pick next ready issue)
kew run

# Preview what would be picked
kew run --dry-run

# Continuous mode (processes queue, exits after 3 empty checks)
kew run --loop

# Force a specific issue
kew run --issue 42

# Inspect the prompt that would be sent to the configured runner
kew run --dry-run --show-prompt --issue 42

# Parallel dispatch with 3 workers
kew run --loop --workers 3

# Release an issue held by the approval gate
kew run --issue 42 --approve

# Repair a run left awaiting host publication
kew run finalize <run-id>

Note: run --loop is continuous dispatch (drains the ready queue). It is unrelated to kew dispatch <issue> --loop, which supervises a single issue as a first-class, verified loop. See kew dispatch.

Exit status

Code	Meaning
0	An issue was dispatched (or the loop drained the queue cleanly).
1	The dispatch itself failed.
2	The ready queue was empty — nothing to dispatch.
3	A GitHub query failed (e.g. an expired token or network outage). The queue state is unknown — this is deliberately distinct from 2 so an overnight --loop that dies on a gh failure never looks like a clean, empty-queue drain.

--approve

Approve this dispatch past the approval gate (requires --issue, not valid with --loop). Use it to release an issue held with the needs-approval label. Logged as approval_granted. Without [approval] configured the flag is an accepted no-op.

finalize <run-id>

Use kew run finalize <run-id> only for residue that is still recorded as awaiting_publication after publication was completed out of band. The command atomically marks the run successful and terminals its unclaimed preserved-work continuation, then records the operator intent in the chained audit ledger. It refuses missing runs and every run state other than awaiting_publication.

Normal recovery does not require this command: each epic-driver tick discovers an open or merged PR from the preserved branch, reconciles the run, and closes the Linear item after an externally merged PR. The repair verb is the explicit escape hatch for older or otherwise unreconciled rows.

Exit status for this action differs from the dispatch table above: 0 on success, 2 for an unknown run, a run in any state other than awaiting_publication, or invalid usage (a missing run id, or dispatch options passed alongside finalize), and 1 when the run state changed underneath the command before the finalization could commit.