Steering a live run
A parallel run can take an hour. You don't have to stop it to change it. forge control changes a live plan's settings and steers its scheduler, and forge-ui's buttons call the very same commands.
Change a setting
forge control show "$PLAN" # every setting, override, pin and recent change forge control set "$PLAN" max-parallel 2 # tasks at once forge control set "$PLAN" qa-threshold P1 --task tooling # looser bar for one task forge control set "$PLAN" retry-budget 3 # automatic retries forge control pin "$PLAN" token-model sol:high:codex # the model its next full retry uses, once
Settings take effect at the scheduler's next pass. Every change, from the terminal or the page, is logged in control.log with who asked.
Steer the scheduler
| Command | What happens |
|---|---|
drain | Start nothing new. Running tasks finish, then the run waits. |
resume | End the drain; eligible tasks start again. |
stop | Finish what runs, start nothing, end the run. |
stop --now | Interrupt running tasks too, like Ctrl-C. Their partial work is kept. |
retry TASK | Queue a retry of a stopped or failed task, optionally --dwarf on another model. |
add TASK | Queue a row you appended to tasks.tsv, with its prompt. |
accept TASK | Accept a failed task with --reason and --approved; the tasks waiting on it start. |
forge control drain "$PLAN" forge control retry "$PLAN" docs --dwarf opus:high forge control accept "$PLAN" tooling --reason "the P2 is a test-only nit" --approved
A retry or add only queues a request; the scheduler applies or refuses it and logs the outcome under the same request id.
When a task keeps failing
forge's retry policy can stop a task as NEEDS_DECISION with a suggestion, such as splitting it. Decide with more attempts, a different threshold or another model, each with a reason:
forge control retry "$PLAN" parser --decide retry=2 --dwarf sol:xhigh --reason "bigger model, two more tries" --approved
Several stopped tasks at once
retry --no-dispatch records the decision for each stopped task and carries its findings forward without starting anything, so one run then dispatches them all side by side.
Answering questions while it runs
With brief mode on, answer each task's questions while earlier waves work; see Questions before a task.
A task that asked you something mid-run waits as NEEDS_INPUT. Answer it with forge control retry "$PLAN" TASK --answer "…", or from forge-ui's task panel; when no run is live, forge prepares the retry for the next run.
Carrying on from another session
A run outlives the agent session that started it. forge handoff tells the next session, in any CLI, what the run is doing and what it needs: its tasks, what waits on a person, the latest changes, and the next commands.
forge handoff # the newest open run here forge handoff note "$PLAN" "release after integrate" forge handoff resume "$PLAN" --harness codex # follow or restart it
Resume never starts a second scheduler: when the run is live it follows it. When the run stopped, it saves the work of any task left running, resets it without counting the attempt twice, and restarts the run in the background with the choices you made at launch. A session already driving the run holds it for 12 hours; taking over takes --take-over, and that's logged.
Planned An investigation into steering a running dwarf live from forge-ui (#134).
Full reference Every flag and edge case: docs/decomposed-runs.md