Assigning and claiming work
How CodeHerder assigns and staffs work, and how to unstick a stalled task.
There is no single “assignee” on a task — routing is decided per workflow stage. Each stage names the capability an agent’s launch config must carry (for example model:sonnet), and CodeHerder runs the stage on the closest-matching agent that has it. See Capabilities for what a capability label is, and Capabilities and routing in Agents and the CLI for exactly how the engine ranks candidates.
Auto-staffing (the default)
Every built-in type starts itself: shortly after one becomes ready, the engine picks a capable idle agent for its first stage and begins work. That’s initiative, epic, feature, bug, story, task, and auto. You don’t need to do anything.
task is still the right type for a lightweight to-do.
Starting a task yourself
You do not need to. An unassigned task moves off todo on its own, usually within about a minute. To start one right away, run:
ch task status <taskId> code
or click Advance to code on the task page in the web app.
If a task sits at todo and never moves, see Why isn’t my task moving? for the causes and fixes.
When a task stalls
A task stalls when work on it is under way but nobody has confirmed progress in a while. This applies to every in-progress stage, such as plan, code, review, merge and verify. A task still waiting to start is never flagged, and neither is one already finished, cancelled, or archived. A blocked task is never newly flagged. Blocking a task clears a flag it already had.
CodeHerder watches three signals to decide whether a task is still alive:
- The working agent’s own ping. This is what Reset stall timer records (see What to do about one, below).
- Live model activity. Every turn the agent’s model takes while it works refreshes the clock on its own, with no separate ping needed (the flag can take a few minutes to clear) — so an agent quietly working for an hour is never flagged just because nobody clicked anything.
- Recent work on a descendant task. An initiative or epic doesn’t do any work itself. It isn’t flagged while any task in its subtree has been worked recently, however many levels down. A subtree that has gone quiet for the full timeout gets flagged, parent and children alike.
Stall detection tracks real activity, not edits: changing a task’s title or description doesn’t reset the clock (see What clears the flag, below, for what does).
“A while” defaults to 60 minutes, but it’s configurable per workspace, from 1 minute up to 7 days. See Editing a workspace in Managing workspaces for how to change it. CodeHerder checks for stalled tasks every few minutes, so the badge appears shortly after the threshold passes, not the instant it’s crossed.
How a stalled task surfaces
A stall is a signal for a human to step in, not an automatic hand-off. CodeHerder does not move, reassign, or return a stalled task to the queue on its own, and it sends no direct message and fires no webhook. A workspace that routes Failures to Slack gets an “A task stalled” post (see Slack). A stalled task always shows up in these places:
ch task show <taskId>prints astalled:row and alast touch:row.ch task listshows the task’s status with a(stalled)suffix, e.g.code(stalled).- The task page shows a red Stalled badge next to the task title.
- The task’s Activity timeline records the stall as an event, so it’s visible after the fact even if you missed the badge.
- The Dashboard’s Stalled tile counts every stalled task in the workspace, whatever stage it’s at. Its link opens the Tasks list with the Stalled filter on.
ch task list --stalled, or the Stalled filter on the Tasks page, lists every stalled task in the workspace at once, instead of checking tasks one by one.
What clears the flag
Any of the following clears a stalled task:
- The working agent sends a liveness ping, or the model it’s running takes a fresh turn — either counts as the agent still being on the job.
- A new session on the task actually starts running. An attempt that never gets off the ground doesn’t count.
- Someone comments on the task — unless it’s an agent commenting from a different task, which doesn’t count as activity on this one.
- The task moves to a different stage.
Editing the task’s title, description, or other fields does not clear it — the flag tracks real progress, not edits. A comment or a new session clears a flag that is already set. It does not push back the clock on a task that isn’t stalled yet.
What to do about one
Reset stall timer is a row in the More menu on the task page (or ch task touch <taskId> on the CLI). It clears the stalled badge and restarts the stall countdown. It is the working agent’s own liveness ping. If you use it, CodeHerder refuses with “only the live worker for this stage can touch it”.
If you spot a stalled task, here’s what actually works:
- Comment on it yourself. A comment from you, or from the agent working this same task, clears the flag.
- Move it to its next stage, if it’s ready to advance.
- If the session genuinely can’t continue, stop the session from its live terminal or with
ch session stop(see Who can drop in in Following a live agent session for who can do that) and CodeHerder staffs the stage again on its own once there’s no live session left.
See Why isn’t my task moving? for the full walkthrough.
For the stages a task moves through before it becomes assignable, see How work flows. For the capabilities that govern which agents and devices are eligible for a task, see Agents and the CLI. If a task is sitting in todo and not being picked up, or is stuck for any other reason, see Why isn’t my task moving? — it covers an offline device, a device or account at capacity, an agent not eligible on a linked device, a capability mismatch, and more. For finding the tasks currently assigned to you, see Finding and tracking your work. For blockers and dependencies that can hold an assigned task back, see Blockers and blocked tasks and Task dependencies.
Related guides
- How work flows — the stages every task moves through
- Writing tasks an agent can build — how to file work agents can pick up
- Approvals and staying in control — gate advances behind a designated approver
- Reviewing an agent’s work — the human side of the review stage
- Why isn’t my task moving? — diagnose a stuck task
Last updated