CodeHerderSearch⌘KRequest access →

Why isn't my task moving?

A diagnostic guide for a task that looks stuck, and how to unstick it.

When a task sits in the same status longer than expected, start here. Most causes leave a visible signal — the quickest first step is always to read what the task is actually showing you:

ch task show <taskId>

The output shows the current status (with a pointer to ch task blockers when it’s blocked), a next stages row, an advance to <stage> row naming what’s missing for the next move, any pending-approval banner, a start refusal row when CodeHerder is declining to start a session, whether the task is stalled, and the last touch time. Match what you see to one of the causes below. For a quick read of who must act next, see Who acts next.

Start with the advance row

Before working through the causes below, check the advance to <stage> row ch task show <taskId> prints. It’s the fastest way to learn whether a task can move on, and what’s missing when it can’t:

advance to review:  blocked — artifact: required field is empty

The web app’s task page shows the same verdict below the stage breadcrumb, as an Advance to <stage> button or, in its place, a line naming what’s outstanding.

Act on what the row names:

  • A field name and reason (like artifact: required field is empty above): fill that field. See A required field is missing at the current stage, below.
  • An outstanding checklist: tick the remaining acceptance-criteria items, or move an item to a later stage. A person uses ch task acceptance stage. An agent uses ch task acceptance defer with a reason. See Write acceptance criteria.
  • A verification: record a result for it. See Verification keeps failing, below.
  • A sentence about a dependency, unfinished child tasks, or a change-shape limit: see the matching cause below.
  • pending — …: the next stage has an entry condition that isn’t met yet, such as a merge reference that isn’t recorded. The sentence names it.

A row like this is never a stuck task — it’s an unmet requirement, and it already names which one. If ch task show prints no advance to row at all, the task has no next stage right now (terminal, or its pipeline ends here) — expected, not a symptom; look at the causes below instead.

What the row doesn’t cover

not blocked means the task meets the requirements for its next move — it doesn’t mean the task is about to move. The row reports requirement checks only, the ones in Before a task moves on in How work flows.

So a task can read not blocked and still go nowhere: a waiting approval, no available device, a signed-out host CLI, a stalled assignee, a spend cap, the reject-loop cap — none show up in the row. Each has its own section below.

The fastest way to find which one applies: let the activity feed name it directly — see Let the activity feed name the cause, next.

Let the activity feed name the cause

If the advance row says nothing is outstanding and the task still isn’t moving, don’t stop there. The activity feed usually names the cause in a plain sentence:

ch activity task <taskId> --type task.staffing_skipped,task.start_refused

The WHY column carries that sentence for a staffing-skip or start-refusal row. It’s empty when no reason was recorded, and shows the raw value when your ch doesn’t yet know the reason. The --type filter cuts the per-turn cost rows this feed otherwise mixes in. See Activity feeds for the full column reference. ch task show also keeps the latest refusal in its start refusal row.

In the web app, the task page’s Activity section shows the same sentence as a row’s detail. A staffing-skip sentence is on the curated story. A start-refusal sentence needs the All events toggle in the section’s header. The CLI shows both with no toggle, so check it, or flip the toggle, before assuming nothing was recorded.

What each sentence means

Find the opening words of the sentence you see, then read the section in the last column.

The feed says What it means Read
The account is already running its maximum concurrent sessions Your plan’s session limit is full Account is at its concurrent-session limit
This task already has a live session A session is already working the task A session is already live for this task
This task’s workflow has auto-staffing turned off at its entry stage Nothing starts an unassigned task by itself Auto-staffing is off at the entry stage
This task’s saved stage isn’t in its workflow The task sits at a stage its workflow doesn’t have A task at a stage its workflow doesn’t have
This task’s dependencies have not finished yet An upstream task is still open Unresolved dependency
This task’s merge stage waits for its stacked upstream task to merge A stacked dependent waits for its upstream’s merge Stacked dependencies
This task has an active blocker A blocker is still open Blocked
This task waits for its open child tasks The task waits for its children. The count shows how many are open A task waiting on its children
This task’s current stage does not run an agent The stage has no agent attached Current stage doesn’t run an agent
No launch config in this workspace can handle this task No launch config carries the capabilities the task needs Capability mismatch
The chosen device is offline The device isn’t connected Device is Offline
The chosen device is already running its maximum sessions The device is full Device at capacity
Every capable device holds its maximum sandboxes Every capable device has no free worktree slot Device at capacity
No device in this workspace can host this task right now No device passes the placement checks Agent not eligible on any linked device
Every credential on the capable devices is exhausted or at its cap Every AI credential on the capable devices is spent or capped Claude usage or spend limit exhausted and AI credentials on a device
No capable device has an enabled, accepted credential for this harness No device has a usable AI credential for the agent’s harness AI credentials on a device and Coding agent not signed in
The AI provider for this task’s route is failing or rate-limited The provider has an outage or is limiting requests AI provider outages
Every capable device runs a ch too old for this stage’s setup script The device needs a newer ch Updating the CLI and the server
Every capable device refuses this task because agents there can read its git credentials The device isn’t set up for agent isolation Isolating agent runs on a device
No capable device has a git credential for a repo this task lists A device has no minter or token for the repo Git credentials on a device
Every capable device refuses this task because its repo commits harness config that runs commands The repo commits hooks, plugins or helper commands that the device does not trust Repo config not trusted and the guide
This task is in a backoff window after a prior failure CodeHerder is waiting before it retries In a backoff window after a recent failure
The last agent found nothing to do and released The task waits for new input Waiting for new input
The chosen agent has reached its daily spend cap The agent’s daily cap is spent Agent daily spend cap
This task’s spend cap, a parent task’s subtree spend cap or its workspace’s spend cap is reached A cost cap stopped the task, or refused its start Spend cap reached
New agent spawns are paused for this account or the whole instance Someone paused new sessions Spawning is paused
All child tasks finished, but this task’s stage runs no agent Nothing can review the children at this stage A task waiting on its children
All child tasks finished An older event: the retired join sweep closed the parent. Nothing moves a parent now No action
A child task didn’t finish An older event: the retired join sweep blocked the parent. That blocker stays until a human resolves it A task waiting on its children

These sentences describe a read that failed for this sweep only: a count, a workflow, the launch configs, the task row, or a session create that didn’t take. They also include “The dependency check failed this attempt”. They retry on their own. Act only if one keeps recurring for the same task.

1. Waiting on an approval

Signal: ch task show <taskId> shows a ⏸ pending advance → <stage> banner. The task’s status has not changed, but an advance request is waiting.

What happened: CodeHerder tried to advance the task and hit an approval gate — a rule requiring a designated member to sign off first. The request is recorded but held until an eligible approver acts. This only happens on a stage CodeHerder can leave automatically — for the built-in feature, bug, and story types, that’s the todo stage a task starts at.

What to do: If you are an eligible approver, approve it:

ch task approve <taskId>

To see all pending advances waiting on you across the workspace:

ch task list --awaiting-approval

If you are not the right approver, share the task with whoever is. If the work shouldn’t start yet, reject it instead:

ch task reject <taskId>

For how approval gates are configured and all the approval actions, see Approvals and staying in control.

2. Blocked

A task moves to the blocked status several ways, including someone filing an explicit blocker, an agent posting a question it couldn’t answer alone, the task hitting the automatic reject-loop cap, or its spend reaching a cost cap — see How a task gets a blocker for the full list. An unmet dependency works differently and does not change the task’s status — see Unresolved dependency below. An agent that finds nothing to do twice in a row also leaves an “Awaiting input” blocker — see Waiting for new input.

Filed blocker

Signal: ch task show <taskId> shows status blocked (with a pointer to ch task blockers).

What to do: List the active blockers, then check the RELEASES-AT column — a blocker with a release time clears itself once that time passes, so there’s nothing to do but wait. For a plain blocker, resolve it by hand:

ch task blockers <taskId> --active
ch task unblock <blockerId>

Pass the blocker ID (from the blockers list), not the task ID. Resolving the last active blocker returns the task automatically to the stage it was at.

A blocker that waits on a merge request clears itself when the request merges, closes, fails its pipeline or has a conflict. See Blockers that wait on a merge request.

ch task unblock refuses a blocker that waits on a network access request, an agent question or an unfinished upstream task. Answer the question, decide the request, or remove the dependency instead. See Blockers that clear through their request, question or dependency.

If it stays at blocked anyway, move it back manually — ch task show <taskId>’s next stages row names the stage:

ch task status <taskId> <stage>

For the full blocker lifecycle, see Blockers and blocked tasks.

Agent question

Signal: The task is blocked with a reason that shows the agent’s question, shown as an open card on the Dashboard and on the task’s own page.

What to do: Answer it from wherever you’re looking at it — see When an agent needs your input for the full list. Submitting clears the blocker and resumes the task automatically; nothing to unblock by hand.

Unresolved dependency

Signal: The task sits at todo and never advances, even though nothing else looks wrong — its status is not blocked. On the web app, the task’s page shows a Waiting on dependencies box and a Waiting on N badge by the title. From the CLI, ch task blockers <taskId> --active shows a blocker whose reason starts with unmet dependency:; that blocker, not the status, is holding it back. Check upstream tasks:

ch task deps <taskId>

The Tasks page’s Graph view lays out the whole upstream chain at once.

What to do: Every dependency must release before this task can advance — planning stages included. By default a dependency releases when its upstream finishes. ch task deps <taskId> shows each release condition. If an upstream is still in progress, no action is needed: once every dependency releases, the blocker clears automatically. If an upstream won’t finish on its own, cancelling it (with a reason) or removing the dependency edge both clear the way, since cancelling counts as finishing. Cancel this task too if it no longer makes sense without that result.

The same rule applies when you reopen a finished task. ch task reopen <taskId> code --reason "..." is refused with “task has unmet upstream dependencies; it will proceed automatically once they land” while an upstream is open. Reopen at todo, or wait for the upstream. See Reopening a cancelled or completed task.

See Task dependencies and Blockers and blocked tasks. The advance to <stage> row above already names an unmet dependency.

Reject-loop cap reached

Signal: The task was sent back into code from review, verify, or merge enough times to hit the round cap on one of those routes. The engine moves it to blocked automatically and posts a blocker note explaining what happened.

What to do: A human needs to review this. Read the blocker note with ch task blockers <taskId> (ch task show <taskId> only points at that command), then fix the blocker and resume the task at the stage that fits, or cancel it:

ch task status <taskId> <stage>           # resume
ch task status <taskId> cancelled --reason "Superseded by …"  # cancel

For how the reject-loop cap works and how to change it per workflow, see How work flows.

Verification keeps failing

Signal: The task leaves code, reaches review or verify, then returns to code on its own — possibly more than once — with no manual send-back.

What happened: the stage’s agent recorded a fail for a required verification, so CodeHerder routed the task back to code for another build attempt — the same reject loop as above, just triggered by a recorded result rather than a human reviewer. See the Stage verifications section of How work flows. If a task is simply sitting with no pass recorded yet, rather than bouncing, the advance to <stage> row in Start with the advance row above names the missing verification.

What to do: Usually nothing — the workflow is self-correcting. Read the hand-off comment on the task to see what failed:

ch task show <taskId>

To see exactly which check failed, list every verification result recorded for the task:

ch task verifications <taskId>

The output lists stage, check, status, build attempt, and any recorded detail, most recent first. <status> is one of pass, fail, error, or skipped. Omit <taskId> and it defaults to CH_TASK_ID.

Each return to code this way escalates to a more capable model for the next attempt — see Automatic model escalation on rework in How work flows. If it keeps bouncing, it eventually hits the round cap and moves to blocked — follow Reject-loop cap reached above.

A result is refused

Signal: ch task verify is refused with a message that a required verification pass may not come from the party it checks, and the advance to <stage> row still names the verification.

What happened: CodeHerder keeps the checker apart from the author on one kind of check. It refuses a required pass on the verify goal gate from an author, unless that member worked the verify stage itself. A test, lint, or typecheck check has no such rule. See Who can record a pass in How work flows.

What to do: Pick the case that fits:

  • For the verify goal gate, have a person or agent who did not build the change record the pass. For example, a workspace member who did not work on the task runs ch task verify <taskId> goal_gate pass.

The refusal message may suggest --execute. That helps only when the check’s stage declares a command. The built-in goal gate declares none.

Spend cap reached

Signal: ch task blockers <taskId> --active shows a blocker whose reason starts with cost budget exceeded (task) or cost budget exceeded (workspace).

What happened: Either the task’s own spend, or its workspace’s, reached a cost cap, so CodeHerder stopped its active sessions and moved it to blocked. If the task isn’t blocked yet but won’t start, it shows a Start refused badge. Its reason reads “This task’s spend cap, a parent task’s subtree spend cap or its workspace’s spend cap is reached”. Those sessions end Released, not failed — see Sandbox state vs. a run’s outcome.

Workspace daily or monthly cap: These caps don’t block the task. The task keeps its status and shows a Start refused badge. ch task show <taskId> prints a start refusal row saying the workspace’s daily or monthly spend cap is reached. CodeHerder refuses new spawns in the workspace until the next UTC day or month, or until an admin raises or clears the cap with ch workspace edit. There is no blocker to resolve. Sessions already running continue.

Subtree spend cap: A cap on a parent task counts the whole branch. When it is spent, no task in the branch starts a new session. The task keeps its status and shows a Start refused badge. ch task show <taskId> prints a start refusal row that names the parent task and the amount spent against its cap. There is no blocker to resolve, and running sessions continue. An admin raises or clears the cap with ch task edit <parentTaskId> --subtree-budget <amount> or --clear-subtree-budget, and held tasks start on the next scheduler pass. See Capping a parent task and its subtasks.

What to do: For a blocker, read the word in parentheses before raising anything — it names which cap applied; raising the wrong one leaves the task blocked. See Reading the blocker in Spend limits. Once raised or cleared, resolve the blocker:

ch task blockers <taskId> --active
ch task unblock <blockerId>

3. Stalled assignee

Signal: ch task show <taskId> shows a stalled: row and a last touch: row.

What happened: Whoever — or whatever — is working the current stage has shown no sign of life for long enough that CodeHerder flagged it as stalled. Signs of life are the agent’s own ping, live model activity, and recent work on a descendant task. The stage is still being worked; it’s just not progressing.

Looking across the whole workspace? Run ch task list --stalled, or turn on the Stalled filter on the Tasks page.

What to do: Reset stall timer (in the task page More menu, or ch task touch) is the working agent’s own ping. If you use it, CodeHerder refuses with “only the live worker for this stage can touch it”. Instead:

  • Comment on the task — posting is itself confirmed activity and clears the flag right away.
  • Move it to its next stage, if it’s ready to advance.

How long a task can sit untouched before it’s flagged is a per-workspace setting (60 minutes by default) — see Editing a workspace in Managing workspaces. For the full stall flow, see Assigning and claiming work.

4. No agent or device available to staff the task

An eligible, ready task can still sit in todo if the staffing prerequisites are not met. Check the following. To spot a coverage gap for your whole workspace before it strands the next task, see Staffing coverage.

Account is at its concurrent-session limit

Signal: The activity feed’s cause names the account as already at its session limit.

What happened: Your plan caps how many agent sessions run across the whole account at once, regardless of how many devices you have free.

What to do: ch workspace plan shows the concurrent agents line against the limit. Wait for a slot to free, or raise the plan’s concurrency limit — see Plans and limits. This differs from Device at capacity, below, which caps one device, not the account.

A session is already live for this task

Signal: The activity feed’s cause names an already-live session for this task.

What happened: Only one session runs a task at a time. CodeHerder re-checks this on every staffing sweep, so seeing it once for a task that’s genuinely being worked is expected, not a symptom.

What to do: Open the task’s Sessions view to confirm a session is running. If the task also looks stalled (see Stalled assignee above) and you’re confident the session is dead, stop it directly (only a person can), then a fresh one can start:

ch session stop <sessionId>

Check the session’s Progress row first; see Is this session making progress?. If the session may hold unpushed work, add --preserve so the device saves it first; see Stop and keep the work.

No repository resolves to build in

Signal: The task’s status is blocked, and ch task blockers <taskId> shows a note naming one or more candidate repositories.

What happened: CodeHerder resolves what a task builds in automatically — the task’s own attached repo set first, then a workspace default, then the one active repository across the workspace and its parent groups — and blocks the task right away when none of those resolve. This most often happens when a workspace has more than one active repository and neither a task-level repo set nor a workspace default names the one to use; the blocker note lists every repo it found in play. See Tasks that span several repositories and Which repositories a task builds in in Connecting repositories for the full resolution order.

What to do: Either attach a repo set to the task —

ch task repos create <taskId> <repo>

— or set a default for the workspace so future tasks resolve without you having to name one each time:

ch workspace edit <workspace> --default-repo <name|id>

This also works if the repository is inherited from a parent group. If you’d rather not set a default, keep exactly one active repository across the workspace and its parent groups, and archive the rest with ch repo archive <name>. Take care with a repo that belongs to a parent group: archiving it removes it from every workspace under that group. Set a workspace default instead when the extra repo is inherited.

A task blocked here has no repo attached, so either fix works: a new default or an attached repo applies the next time CodeHerder starts a session for the task. A task that already got a repo when it was created keeps that repo. A later change to the default doesn’t move it.

A similar note appears when a repository has been archived: the task’s set, or the workspace default, names a repo that’s no longer active, and CodeHerder won’t start a session for the task. The note names the repo. Bring it back with ch repo restore <name>, remove it from the task with ch task repos delete <taskId> <repo>, or change the workspace default with ch workspace edit <workspace> --default-repo <name|id> (or --clear-default-repo).

A related problem lands a task in the same blocked state: two attached repos would need the same folder name inside the sandbox, so CodeHerder refuses to provision either one. Detach one with ch task repos delete <taskId> <repo>.

A repo that fails to clone is different, not an immediate block — the sandbox fails to provision, the failure shows in the task’s Sessions view, and CodeHerder retries automatically before giving up. In a multi-repo set, the whole sandbox fails to provision and the failure names the culprit repo; a sibling that had already cloned is reused, not re-cloned. Fix whatever the clone error names — usually credentials or a URL, see Git access to clone the repository in Connecting repositories — and the next retry picks it up.

Device is Offline

Signal: The task is unassigned and waiting; your devices are Offline.

ch device list

What to do: Start or restart ch device-server on the machine — the device comes Online as soon as it connects. No device registered yet? See How do I add a device?. Or set up a MicroVM runner so CodeHerder launches one on its own next time.

Agent not eligible on any linked device

Signal: The device is Online but not picking up work for this agent.

An agent is eligible on any device linked to its workspace (or an ancestor group) whose capabilities the device covers — no separate assignment step. Check what the engine sees:

ch task placement <taskId> --agent <agentId>
ch agent placement <agentId>   # the agent alone, regardless of task

Either lists every candidate device and, for each ineligible one, the exact refusal reason. It names an unhealthy device as device_unhealthy; see Unhealthy device and The Placement report.

Secret reference unacknowledged or unresolvable

Signal: The device is Online and the agent is eligible on it, but a session for this agent still won’t start. The task shows that the agent failed to start, and the reason mentions a secret reference or a secret variable the device owner hasn’t acknowledged, a secret variable whose device consent has expired, or a secret reference that couldn’t be resolved on the device.

What happened: This is the same acknowledgement gate for two things. A launch config’s device-side credential (an @secret:<key> value) must be explicitly acknowledged by the device or a workspace owner, with the value actually stored there. A secret variable at group, workspace, device, or agent scope needs the same acknowledgement, even though it isn’t an @secret: reference. Either one missing refuses the session to start — including after adding a new key to an already-acknowledged config. Consent for secret variables also expires, by default 90 days after the last key was added with ch device secrets set. An uppercase secret in scope needs this consent even when a Credential ref binds it.

What to do: Add every referenced key to the device’s acknowledged-secrets list, @secret: or secret-variable alike:

ch device secrets set <deviceId> --add <key>

--add adds a key without replacing the list, and it renews expired consent; ch device secrets list <deviceId> shows the expiry. Only the device’s owner or a workspace owner can run it. If the failure says a reference couldn’t be resolved instead, it won’t name the key — check which @secret:<key> references the launch config uses and confirm each is stored on that device. See Secrets on a device and Variables.

Device at capacity

Signal: The device is Online and eligible agents exist for it, but the device is fully busy.

Check the Capacity panel under Set up → Devices → [the device] for its Session limit — see Concurrency and capacity. At the limit, new tasks queue and start as a running session finishes; raise the limit in the same panel for more parallel work.

If the device stays full with nothing seeming to run, some worktree slots may be left over from ended sessions. Expand the row and check Worktree slots in the Health snapshot — if it reports reclaimable slots, force an immediate clean-up:

ch device reclaim <deviceId>

See Reclaiming stuck worktree slots in Managing your devices for the full picture, including who can run it and what to check before you do.

Unhealthy device

Signal: The device is Online and has free slots, but a task still does not start. In Set up → Devices, the device row shows an amber Not staffable badge next to the health badge. (A device that is only Unhealthy can still take work that doesn’t need the failing check; see Coding agent not signed in.) If a session was attempted and failed, a task comment says the device is unhealthy and names the failing check.

What happened: CodeHerder runs readiness checks on every device. When a blocking check covers the whole device, CodeHerder holds all new sessions there. Common causes: an unwritable session-root directory, critically low disk space, or a git host the device can’t reach. Some checks cover only one coding CLI or one repository. A signed-out CLI or a repository’s failing git credentials holds only the work that needs it, so the device shows Unhealthy without Not staffable. For a signed-out CLI, see Coding agent not signed in below.

What to do:

  1. In Set up → Devices, click the device row to expand it.
  2. The Health snapshot panel lists every failing check with a summary and remediation tip. If you only see a notice, ask the device’s owner or an admin to read it — see Who sees host details.
  3. Fix it on the device — for example, free disk space, or, for a git-credential failure, add a git token for the repository (see Git credentials on a device) or re-run gh auth setup-git.
  4. The device re-checks within roughly five minutes, or immediately on restarting ch device-server. Once it passes, the Not staffable badge disappears.

For every readiness check, see Device health and readiness checks in Managing your devices.

Coding agent not signed in

Signal: The device is Online but a task that needs that CLI won’t start. In Set up → Devices, the device row shows an Unhealthy badge. It does not show Not staffable, because other work can still land there. Expanding the row, the Health snapshot panel shows the Harness auth check failing. If a session was attempted anyway, it dies at startup unable to reach a model.

What happened: A coding CLI can be installed on a device but not signed in to its AI provider — installing it only satisfies the Harness ready check. A separate Harness auth check tests each installed CLI, and blocks work that needs a CLI that is signed out. This is the most common cause of an unhealthy device right after you register it. Only work that needs that CLI on that device is held.

What to do:

  1. On the device, sign in with that harness’s own login command — claude login, codex login, cursor-agent login (or set CURSOR_API_KEY), or opencode auth login, matching the CLI the agent’s config uses. Pi has no login command: it signs in via a provider API key (for example ANTHROPIC_API_KEY) in the device’s environment, or a credential file already signed in elsewhere. mini-swe-agent has no login command either: it reads provider keys from a file named by CH_MINI_API_KEY_FILE on the device. See Choosing the coding-agent CLI your agents run.
    • If the failing harness is installed for reasons unrelated to CodeHerder, exclude it instead of signing in: restart ch device-server with --harness-exclude <name> (or CH_DS_HARNESS_EXCLUDE=<name>). It then no longer counts against Harness ready or Harness auth — but keep at least one harness on the device, or Harness ready fails instead.
  2. The device re-checks automatically within roughly five minutes, or immediately if you restart ch device-server.
  3. Once the check passes, the Unhealthy badge clears and the engine resumes placing work that needs that CLI on the device.

For the full readiness-check reference, see Device health and readiness checks in Managing your devices.

Device is drained (paused)

Signal: The device is Online, healthy, and not at capacity, but tasks still are not placed there. ch device list shows drained in the STATE column, or ch device show <deviceId> prints drained: yes (since <when>).

What happened: Someone paused the device — Disable in the web app or ch device disable <deviceId> — to stop new work landing there without interrupting running sessions. Online state and health badge don’t change; only new placement is skipped. If ch device list shows excluded here instead, a workspace turned the device off for itself. See Turning a device off for one workspace.

What to do: Resume placement:

ch device enable <deviceId>

Or click Enable on the device’s row in Set up → Devices. Placement resumes immediately.

For the full pause/resume workflow, see Pausing a device in Managing your devices.

Claude usage or spend limit exhausted

Signal: The device is Online, healthy, not at capacity, and has an eligible agent — yet tasks still do not start. In Set up → Devices, the device carries a Claude exhausted badge next to its health badge (or Claude subscription exhausted on its detail page). ch device show <deviceId> prints the same thing as a staffing row.

What happened: CodeHerder monitors each device’s Claude usage — a subscription plan’s usage pools, or an enterprise/organization credential’s spend caps. When a meter reaches 100% before it resets, the engine stops routing new tasks there to avoid stranding sessions on a credential that will reject them. Running sessions aren’t interrupted, and the device’s Online/healthy status doesn’t change — its health checks don’t reflect this.

What to do: No manual action is required. Once the reset time shown on the meter passes, the engine resumes placing tasks automatically. The resets in text shows how long to wait.

If a second device with headroom is registered, CodeHerder already tries it — no action needed. Otherwise, the fix is a second Online, healthy device with a capable agent, or simply waiting for the window to roll over.

For the full explanation — why the pause is device-wide, why switching launch configs on the same device doesn’t help, and how failover across devices actually works — see AI usage limits.

Repo config not trusted

Signal: The task shows a Start refused badge. The reason is “Every capable device refuses this task because its repo commits harness config that runs commands”. ch task show <taskId> shows it in the start refusal row.

What it means: The repo commits hooks, helper commands, plugins or MCP servers. A device does not trust those files by default. CodeHerder skips each refusing device for this task for 24 hours.

What to do: Remove the config from the repo, or ask the device operator to trust the repo, a plugin marketplace or the whole device. Then restart the device. See When a task says “Repo config not trusted” for the files, the three settings and how to retry.

In a backoff window after a recent failure

Signal: The activity feed’s cause names a backoff window after a prior failure.

What happened: After a session fails to start, CodeHerder waits out a short backoff window instead of retrying in a tight loop.

What to do: Nothing — it retries automatically once the window ends. If it keeps re-entering backoff, check the task’s Sessions view for what the failed attempt reported and follow the matching cause on this page.

Waiting for new input

Signal: The activity feed says the last agent found nothing to do and released. After a second release in a row, the task shows status blocked and its blocker reason starts with “Awaiting input:”.

What happened: An agent looked at the task, found no work it could do, and ended its session. CodeHerder waits a short while, then starts one more session. If that agent also finds nothing and no new input arrived in between, CodeHerder blocks the task. The blocker reads “Awaiting input:” followed by the agent’s note about what it needs. If the agent left no note, the reason says it released twice with nothing to do.

What to do: Read the blocker reason with ch task blockers <taskId>. The agent’s note usually says what is missing. Then give the task new input. These wake it:

  • A comment from a person. An agent’s comment doesn’t count.
  • A person’s answer to an agent question.
  • Another blocker on the task being resolved.
  • A dependency or a child task finishing.
  • A person editing the task or one of its fields.
  • Git activity on the task’s own pull or merge request: its head CI finishing, or a new comment or review.

A task in the short wait wakes at once. A task with the “Awaiting input” blocker wakes when CodeHerder next checks, about every five minutes. The blocker then clears, the task returns to its stage, and one session starts.

You can also resolve the blocker by hand. Use Resolve in the web app, or ch task unblock <blockerId> with the blocker ID from ch task blockers <taskId>. If the agent was right and the work is done, move the task on with ch task status <taskId> <stage>.

Agent daily spend cap

Signal: The activity feed says the chosen agent has reached its daily spend cap.

What happened: One agent’s spend in this workspace reached the account’s daily cap. That agent starts no new work until the UTC day rolls over or the cap is raised. Other agents are unaffected.

What to do: Wait for the reset, raise the cap, or let a different agent take the task. See Spend limits.

Spawning is paused

Signal: The activity feed says new agent spawns are paused for the account or the whole instance.

What happened: Someone paused new sessions, for example while they contain an incident. Running sessions and queued tasks wait.

What to do: Nothing on the task. It starts once the pause lifts. Ask your account owner or instance operator who paused it and why.

Capability mismatch

Signal: The device is Online and has free slots, but the task still does not start.

See Capabilities for what a capability label is and the different rules for each place it appears.

There are three distinct causes that produce this signal:

No agent’s launch config covers what the stage requires. Workflow stages declare capabilities a launch config must carry — for example, a planning stage may require model:opus. Set these with --cap in ch agent config edit, or --config-cap at agent-creation time (see Creating a runnable agent in one call). If no launch config in your workspace carries the needed capability, the stage is unstaffable.

The web app surfaces this as a Capability gap callout at the top of Set up → Agents, naming what’s missing:

ch agent config edit <agentId> --cap <existing-cap> --cap <missing-cap>

--cap replaces the whole capability list, so name every existing one plus the missing one. config edit leaves other fields — command, args, environment — as they are. For a brand-new agent, create it and its launch config together: ch agent create --harness <h> --config-cap <capability>. See Agents and the CLI.

The task’s own required capabilities are no longer covered. A task can carry its own --cap requirements, combined with each stage’s as the task moves through the workflow — see Capabilities. Creating or editing a task checks every stage against your enabled launch configs. A task that passed can still stall if someone later edits, disables or archives a launch config, or if you created the task before any launch config existed. A device capability set with --device-cap has no such check: a typo is accepted, and then no device fits. Run ch task placement <taskId> to see which device capability is missing.

This shows a Start refused badge (task list and detail) and a Start refusal row naming the reason; ch task show <taskId> and --json’s startRefusal carry the same. Fix with ch task edit <taskId> --cap <label>... or --clear-caps.

The agent needs tooling the device lacks. An agent can require host tools — the AI coding binary or the git-host CLI (gh/glab) — which devices detect automatically. Install the missing tool; the device picks it up on its next connection. See Managing your devices.

No device can run the tools. The stage’s declared tools or system packages can’t be built on any capable device. This case has no Start refused badge. Instead, the task gets a blocker that starts with “No device can run this stage’s tools” and names the tool and platform, or the failed build. The blocker clears by itself once a device can run the tools. See Giving stages the tools they need.

Current stage doesn’t run an agent

Signal: The activity feed says the current stage does not run an agent. ch task show <taskId> shows the same sentence in its start refusal row.

What happened: A pipeline’s start and end stages, like todo and done, are bridge stages that never run an agent by design. See Staffing coverage. An epic or initiative at in_progress also runs no agent while its children work, which needs no action. On a story, feature, bug, or task build stage, this usually means the workflow has no real agent stage attached there.

What to do: For a bridge or container stage, do nothing. Otherwise the workflow’s stage list needs a real agent stage there. See How work flows.

A task at a stage its workflow doesn’t have

Signal: The activity feed says the task’s saved stage isn’t in its workflow. No session ever starts, there’s no blocker, and nothing waits on you.

What happened: The task sits at a stage its workflow doesn’t declare, so nothing can staff it. Two causes are common. A workflow edit removed the stage while the task was there. Or a story, feature, bug, or task was left at in_progress, which CodeHerder now refuses for those types. in_progress is the holding stage for an initiative or epic, and these four pipelines never had it.

What to do: Reopen the task at a stage you want:

ch task reopen <taskId> code --reason "picking this back up"

Only a person can run this. In the web app, open the task and use the item under its More menu, which reads Send back on an active task. Run ch task show <taskId> and read its reopen targets row for the stages you can pick. If the workflow itself lost the stage, restore the stage in the workflow instead. See Reopening a cancelled or completed task in Editing and cancelling tasks.

5. Stuck at code or merge — host-CLI not authenticated

Signal: The task is stuck at the code or merge stage. Looking at the task’s Sessions view shows a failed session with an error about the git-host CLI (gh or glab) not being found or not authenticated.

What happened: A stage that runs directly on the device, without its own container, opens and lands pull requests through the git-host CLI installed on the device. If it’s missing or its token expired, whichever stage runs first — code opening the request, or merge landing it — fails and posts the error as a task comment.

What to do: On the device that ran the failed session, confirm which CLI is involved and its current state:

ch githost auth-check

The command detects the host from the repository’s origin remote and prints a clear result — ✓ when authenticated, ✗ when not. For a specific repository, supply its remote URL:

ch githost auth-check --remote https://github.com/acme/my-app

Note: ch githost auth-check supports github.com and gitlab.com only. If your repository is on Bitbucket or a self-hosted instance, the command does not apply — check the host CLI’s own auth status directly.

If the check fails, follow the printed remediation:

  • GitHub: gh auth login on the device.
  • GitLab: glab auth login on the device.

Once the CLI is authenticated, move the task back to the failed stage:

ch task status <taskId> code    # if it failed at code
ch task status <taskId> merge   # if it failed at merge

The engine staffs the task to the next available session. For the full device requirements — git credentials and host-CLI setup — see Connecting repositories and Git credentials on a device.

6. Auto-staffing is off at the entry stage

Signal: The task sits at its workflow’s very first stage, untouched, and the activity feed says the task’s workflow has auto-staffing turned off at its entry stage.

A task can wait there because auto-staffing is off for it. One setting controls it, auto_staff_unassigned. The built-in initiative, epic, feature, bug, story, task and auto types all have it on, so this section mostly applies to a workflow your workspace wrote itself, or to a task with its own workflow override. Start by reading what applies to this task:

ch workflow show <taskId>

That prints the workflow this task actually runs on. Look for auto_staff_unassigned:

  • true — auto-staffing is on for this task. Check the other causes on this page instead.
  • Absent, or null — auto-staffing is off (a missing key and null mean the same thing). Keep reading.

When it’s off, the setting comes from the task’s own workflow override if it has one, or its type’s shared settings otherwise. Read the type’s shared settings next — --json is required, since the plain-text output omits this setting. --type narrows the JSON to that one type:

ch workspace workflow show --type <type> --json | jq -r '.data[].schema.auto_staff_unassigned'

Without jq, read auto_staff_unassigned inside the schema object of that output. A missing key means off.

Compare the two readings:

  • Both are absent or null — the type itself doesn’t auto-staff. See Auto-staffing is off for the whole type, below.
  • The type reads true, but the task reads absent or null — this task carries its own workflow override. See A task held back by its own workflow override, below.

Auto-staffing is off for the whole type

Signal: Both readings above are absent or null.

What happened: This type’s entry stage leaves newly created, unassigned tasks alone, often on purpose, so a person triages or assigns each one first. A built-in type reads its current built-in setting, which is on. Only a workflow your workspace wrote for that type, or a task’s own override, can turn it off.

What to do: Move the task on by hand:

ch task status <taskId> <stage>

To change it for future tasks of this type, a workspace admin or owner sets auto_staff_unassigned to true at the top level of the type’s composition document and writes it back:

ch workspace workflow composition <type> > <type>.json
# add "auto_staff_unassigned": true next to "key" and "label"
ch workspace workflow edit <type> --from-file <type>.json

See Assigning and claiming work.

A task held back by its own workflow override

Signal: The type reads true, but the task reads absent or null.

What happened: A task can carry its own workflow override — a private copy that keeps the auto-staffing setting as it stood when made, and doesn’t follow later changes to the type. An override made while the type was off keeps this task off even after someone turns the type back on.

What to do: Move the task on by hand with ch task status <taskId> <stage>, or clear the override so the task follows its type again:

ch workflow override clear <taskId>

Clearing it reverts the task to the type’s current settings. Workspace admins and owners can run it. If the task sits at a stage the type’s workflow doesn’t have, the command stops and tells you to re-run it with --migrate <oldStage>=<newStage>. See Assigning and claiming work.

7. A task waiting on its children

Signal: One of these:

  • ch task show <taskId> shows a start refusal that reads Waits for <N> open child tasks.
  • The task is an epic or initiative at in_progress.
  • The feed says “Waiting for child tasks”.

What happened: Every task with children follows one rule. It waits while a child is open. When the last child finishes, an agent starts in the task’s current stage. For a container, that stage is in_progress. There, the agent reviews the child outcomes and closes the container. See Waiting for child tasks to finish.

What to do: Check the state of the child tasks:

ch task children <taskId>

Progress the children through their own workflows. An agent starts on the parent by itself once they are all finished. If you try to close the parent by hand before then, CodeHerder refuses and names how many children are still open.

If every child is finished and the task still does not start, read ch task show <taskId>. The start refusal names the cause. A stage that runs no agent shows Finished children, stage runs no agent. Move the task to a stage that runs an agent.

To stop a task from waiting, finish or cancel its open children, or move it to another stage yourself.

A cancelled or archived child does not hold the parent back. A child that ends at a failed end stage also ends the wait. The agent that starts on the parent sees the failure in its brief.

An older sweep blocked a parent when a child failed. The feed shows that event as “A child task didn’t finish”. Nothing clears that blocker now. Review the children, then resolve it yourself with ch task blockers <taskId> --active and ch task unblock <blockerId>. An agent then starts in the parent’s current stage.

For the container lifecycle and the planning stage that precedes in_progress, see How work flows and Core concepts. The advance to <stage> row in Start with the advance row above names the open child count too, once the container is otherwise ready to close.

8. Refused by a change-shape limit

Signal: Advancing the task fails with an error naming a counter and a threshold, for example advancing out of stage "code" is blocked by its change-shape gate: max_files_changed is 34, exceeding the threshold of 20.

What happened: The stage you’re leaving has an optional limit on how big or spread out the task’s change can be, and the task’s recorded change shape exceeds it. This only happens on a stage where someone has deliberately set such a limit — most workspaces never see this message at all.

What to do: Either split the change into smaller tasks so each one fits under the limit, or — if the limit is too tight for this kind of work — raise or remove it on that stage. See Change shape for what the counters measure and how to adjust the limit. The advance to <stage> row in Start with the advance row above shows this same refusal before you even attempt the move.

9. A required field is missing at the current stage

Signal: Advancing the task fails with an error listing one or more field keys as still needed, the task page shows a note naming which required fields are missing instead of an Advance to <stage> button, or ch task show <taskId>’s advance to <stage> row names the field.

What happened: Every stage has a gate — a check that its required fields are filled — and one is still empty. On the built-in story/feature workflow this most often means the task is at plan: it can’t leave until both acceptance and plan are set, from different sources. You write acceptance when filing the task — see Write acceptance criteria — and the planning agent reads it, then writes plan in return.

What to do: Run ch task fields <taskId> to see exactly what this task’s type requires and which fields are still unset:

ch task fields <taskId>

If acceptance is what’s missing, you need to write it yourself — no agent will:

ch task edit <taskId> --acceptance-file criteria.md

If plan is what’s missing and the planning agent is still working, give the session time to finish — it doesn’t appear until the agent saves it. If the field is genuinely stuck empty, fill it yourself:

ch task edit <taskId> --plan-file plan.md

See Planning stages and stage gates in How work flows for the full gate table, and Writing tasks an agent can build for what each field holds.

An agent was refused a checklist change

Signal: An agent’s edit to the acceptance criteria fails with agent callers may not ... — ask a human.

What happened: An agent may only defer an item forward, with a reason. It may not move an item by editing the whole list, delete an unticked item, change an item that has a deferral history, or tick a deferred item early.

What to do: Decide what the item needs, then run ch task acceptance stage <taskId> <n> <stage> yourself. A person can move an item in any direction. See Move an item to another stage.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close