CodeHerderSearch⌘KRequest access →

Blockers and blocked tasks

What a blocker is, how a task gets one, which ones clear themselves, how to answer one that asks you to choose, and how to file, view, and resolve one.

A blocker is a record on a task explaining why it’s stuck. It’s usually one of three things: a hand-off a person needs to make, an automatic note that the task is waiting on another task, or a wait for a pull request to merge. A few automatic merge-wait notes fit neither kind — see Notes that don’t change the task’s status. A person-facing blocker moves the task to the reserved blocked status; an automatic dependency note doesn’t — the task stays where it was, just held out of the staffing queue until the wait is over. A person-facing blocker can also carry a release time, so it clears itself once that time passes. A task can carry more than one blocker at once.

This page covers both kinds: how each one ends up on a task, where you’ll actually meet one, and how to file, inspect, and resolve one.

What a blocker is

A blocker records who filed it (a person, an agent, or CodeHerder itself), when, and a reason. Only CodeHerder’s own dependency note links a task.

How a task gets a blocker

These move the task’s status to blocked — it drops out of its current stage until every one of them is resolved:

  • Someone files a blocker. A person or an agent records that the task is stuck on something external — optionally with a future release time, covered in Blockers that release themselves below. See Filing a blocker yourself for how.
  • An agent waits for egress approval. After a destination was denied, an agent can block its task on one or more of its network access requests. The blocker reads “Waiting for network access approval” with each destination. It clears once every request is decided or has expired, and the task resumes. You can’t resolve it by hand while a request is still pending. See Network access approvals.
  • A stage meets a harness’s managed-settings approval dialog. Claude Code asks a person to approve the settings your organization serves, and a stage has no person at the terminal. The blocker reads “Waiting for a workspace admin to approve the org’s Claude settings”. Every task that meets the same settings waits on ONE shared request. One decision by a workspace owner or admin clears every waiting task. Decide it under Admin → Integrations → Claude, or with ch managed-settings. See Approving your organization’s Claude settings.
  • An agent asks a question it can’t answer alone. The blocker’s reason shows the question until you answer it — from the Dashboard, the task itself, or wherever else you happen to meet the agent. Only an answer clears it. See When an agent needs your input.
  • An agent refuses its own stage. An agent can decide mid-session that its work isn’t ready to go forward and end its own turn — see refuse in Sessions from the command line. That blocks the task immediately, with the agent’s own reason (if it gave one) and a link back to the session. It only takes hold if the task is still at the stage that session was running — one that’s already moved on isn’t affected.
  • A send-back edge into code hit its round cap — review → code, verify → code, or merge → code. See How work flows for how the round cap works and how to change it.
  • The task’s spend reached a cost cap. See Spend limits.
  • Sessions kept failing to make progress on the selected device — failing to start, ending again and again without moving the task forward, or an agent that keeps refusing. CodeHerder parks the task once it’s tried enough times, and the blocker note names which limit was hit. See Why isn’t my task moving? for the device-health causes this usually traces back to.
  • An agent releases twice in a row with nothing to do. The blocker reads “Awaiting input:” followed by the agent’s note. It clears once new input arrives. See Waiting for new input.
  • Someone moved the task to blocked by hand — from the web app’s status dropdown, or ch task status <taskId> blocked. CodeHerder files a note recording which stage the task was at.
  • A sandbox holds a clone of a repo that isn’t on your workspace’s repo list. The task’s sandbox has a clone of a remote that isn’t registered in the workspace, or is archived. CodeHerder blocks the task, and the note names the remote. Either register the repo or remove the clone, then resolve the blocker.
  • An agent waits for a pull or merge request to merge. The blocker reads “Waiting for a merge request to merge” and clears itself when a request it names merges, closes, fails its pipeline, has a conflict, gets approved or passes its pipeline. See Blockers that wait on a merge request.
  • A merge couldn’t land and needed something no agent can grant — most often a required human approval on the merge request. The merge agent files this itself rather than leaving the task stuck at merge. See How work flows for the other ways a stuck merge gets resolved.

Whichever of these moves a task to blocked, CodeHerder also stops any session still running on that task.

A dependency note works differently: the task’s status doesn’t change — it stays wherever it was, normally todo — but CodeHerder still holds it out of the staffing queue until the upstream task finishes. See Which blockers need you below for what, if anything, you need to do about one of these.

Filing a blocker yourself on a task that has already reached done, cancelled, or archived is rejected outright — a finished task can’t be paused.

Notes that don’t change the task’s status

This is different from a blocker that waits on a merge request, which does move the task to blocked. A workflow stage built to wait for an external merge request can carry its own automatic note alongside the task’s regular blockers, without ever moving the task to blocked. It shows up in three cases: the merge request was closed without merging, CodeHerder couldn’t check the merge’s status, or the wait ran past its own limit. It clears itself once the merge lands, the merge request reopens, or status checks start working again — nothing to do by hand. None of CodeHerder’s built-in task types have a stage like this; you’d only meet one on a workflow customized to add it. See Integrations for how CodeHerder reads a merge request’s status from GitHub or GitLab.

Which blockers need you

Reading a blocker tells you whether it clears itself or needs you to act.

Clears on its own:

  • A dependency note, as soon as the named upstream task finishes or you remove that dependency — see below.
  • A blocker from an agent question, the moment you answer it — see When an agent needs your input.
  • A blocker filed with a release time, once that time passes — see Blockers that release themselves.
  • A blocker that waits on a merge request, when a request it names needs action or all have merged — see Blockers that wait on a merge request.
  • An “Awaiting input” blocker, once a person comments or answers, or other new input arrives (CodeHerder checks about every five minutes). You can also resolve it by hand — see Waiting for new input.
  • A park for sessions failing to start on one device, as soon as that device recovers — see Automatic recovery below.
  • A merge-wait note, once the merge lands or its status can be read again — see Notes that don’t change the task’s status above.
  • A park for repeated session failures, once, after a person comments on the task or answers one of its agent questions — see One retry after you comment below.

Clears only through what it waits on: a blocker for a network access request, a managed-settings approval request, an agent question or an unfinished upstream task. You can’t resolve these by hand. See Blockers that clear through their request, question or dependency below.

Needs you to resolve by hand: a reject-loop round cap, a spend cap, a join failure, an agent’s refusal, a manual block, an unlisted repo clone, a plain blocker filed with no release time, and a park with no retries left. Resolve any of these as described in Resolving a blocker below.

A dependency note clears as soon as the dependency on the named upstream releases. By default that is when the upstream finishes, including one that’s cancelled or archived instead of completed: the note still clears, and CodeHerder separately tells you the upstream’s work never landed (see When an upstream is cancelled or archived). There’s nothing for you to do here.

The note also clears if you remove the dependency (ch task undepend, or Remove in the web app). If the task still has another unfinished upstream, CodeHerder files a new note that names that one.

One more thing worth knowing if you’re actively building on a task: adding a dependency to a task that’s already underway pulls it back. CodeHerder retires its live session, discards that session’s in-progress work, and reverts the task to its starting stage so the dependency gate can govern when it’s allowed to proceed again. This reset is intended: the task restarts from current main with a fresh plan once the dependency releases. Add dependencies before work starts where you can, and see Task dependencies for the full dependency model.

Automatic recovery

When sessions keep failing to start on one device, CodeHerder clears the resulting blocker as soon as that device is healthy again. If nothing else holds the task, it goes back to its stage within a few minutes. This covers start failures only; a park for sessions that ended without moving the task forward stays until you resolve it. A workspace owner or admin can also clear a start-failure park without waiting for the device to recover, and so can the device’s own owner as long as they still hold admin rank in the workspace: ch device clear-provision-breaker <device>. The task again returns to its stage within a few minutes. See Managing your devices for what makes a device healthy.

One retry after you comment

After CodeHerder parks a task for repeated session failures, a comment from a person on the task gives it one automatic retry — so does a person answering one of its open agent questions. An agent’s own comment doesn’t count. CodeHerder checks for this roughly every five minutes, and the retry spends from the same budget rather than resetting it, so a task that fails again afterwards can park again sooner. This doesn’t apply to the reject-loop round cap — that one always needs a person to resolve it by hand.

Where you meet a blocker

On the task itself: a Waiting on dependencies box appears at the top of the task’s page while the task has unfinished upstream tasks. It lists each upstream with its title (a link) and current status. An upstream in a workspace you can’t see shows as “a task in another workspace”. Under the list, it says “This task starts automatically when they finish.” The box goes away once the last upstream finishes. The same wait also shows as a Waiting on N badge by the task’s title. Hover over the badge, or tab to it, to see which upstreams it counts. The badge also appears on task rows on the Me page and on the member, agent and session pages.

While the box is showing, the red banner doesn’t repeat the dependency note. A Blocked banner appears whenever a person-facing blocker is open. Its title reads “Blocked — an agent is waiting on a human”. Below it, a line says where the blocker came from — who raised it, and during which stage’s session, if it came from one. With more than one blocker open, the banner also shows the count and a link down to the full list.

For a plain blocker, the banner offers Resolve right there. For a question, the banner shows an Answer the question link. For a network access request, it shows “Needs a network access decision”. For an upstream task, it shows “Clears when the upstream task finishes”. Those two lines link to the Active blockers list, where the real actions are (see Blockers that clear through their request, question or dependency). You can also scroll down to the Active blockers section for the full list and the filing form. A task that has ever carried a blocker also keeps a separate Resolved blockers section below it, once at least one has been cleared.

The Blockers page lists blockers across the workspace. My work lists the blockers that ask you to choose, across your workspaces. See the sections below.

Blockers that ask you to choose

Some blockers carry an ask. An ask tells a person what happened and what CodeHerder needs from them. It offers one to four options. Each option says what happens when you pick it. An agent writes the ask when it files a blocker. CodeHerder writes one itself for the parks listed below.

A blocker with no ask is a note. It stays on the task page and the Blockers page. It never reaches Needs you in My work.

What the card shows

In Needs you, an ask appears as a card with:

  • what happened, in plain words
  • the one thing CodeHerder needs from you
  • one button for each option, with the consequence under the button
  • for an option that needs a step outside CodeHerder, a Do this first line and a Done, resume button
  • for an option that sends a reply, a box to write your answer

Where to answer

In the web app, open My work and find the row in Needs you. Select Act, then press an option’s button. The row covers your own work: tasks you filed, tasks under them, and tasks you watch. An admin can select Show team to see more. See My work.

From the CLI, read the ask first, then choose an option:

ch task blockers <taskId> --json
ch task blockers choose <taskId> <blockerId> --option 1
ch task blockers choose <taskId> <blockerId> --option 0 --text "Use the staging key"

The --json output shows the ask and its options. On the CLI, options count from 0. --text takes your reply. --text-file <path> reads it from a file. Only a person can choose an option. An agent or session that tries gets a refusal.

What each option does

The option What happens
Resume CodeHerder resolves the blocker.
Done, resume (a step outside CodeHerder) You do the step first. Then CodeHerder resolves the blocker.
Answer You must give a reply. CodeHerder posts it as a comment on the task and resolves the blocker.
Cancel CodeHerder resolves the blocker and cancels the task. The same rules apply as when you cancel the task yourself.
Move to a stage CodeHerder resolves the blocker and moves the task to that stage. It refuses while another blocker is open on the task.

After a resume, an answer or a step you did outside CodeHerder, the task goes back to the stage it was blocked from once no blocker is open. If a rule refuses a move to a stage, the blocker stays resolved. The task waits at the stage it was blocked from.

CodeHerder refuses a choice in these cases:

  • The blocker is already resolved.
  • The blocker has no ask.
  • The option number doesn’t exist.
  • An answer option has no text.
  • The task has another open blocker, and the option moves it to a stage.

A plain Resolve (or ch task unblock <blockerId>) still works on a blocker that has an ask. It clears the blocker without running an option. Use an option when you want the consequence it names.

Parks that carry an ask

CodeHerder writes an ask for these parks:

  • The task spent its budget, or a stage ran several times without moving forward.
  • A merge request closed without a merge, or CodeHerder can’t read its status, or the wait for the merge ran long.
  • A stage used its send-back rounds, and the merge request still needs work.
  • A merge-hold stage found a conflict, but the workflow has no stage that can write code. See Converge a merge request before merge.
  • No device can run the tools a stage needs, or the stage needs an isolated device and none exists.
  • A sandbox holds a clone of a repo that isn’t on your workspace’s repo list.
  • A parent and child task wait on each other.
  • A plan downgrade stopped the task.

Cancel the task is always the last option. Some options have a name such as Try the stage again or Send it back once more.

For a park that comes back while its cause stays (for example no device can run the stage), choosing Done, resume clears the blocker now. CodeHerder checks again on its next pass. It files the blocker again if the problem is still there.

Adding an ask to a blocker

You or an agent can file a blocker with an ask. Write the ask as a JSON file and pass it with --ask-file:

ch task block <taskId> --reason "Needs the vendor contract" --ask-file ask.json

For the file format and how to write a good ask, see Asking a human.

To add an ask to an open note that has none, use:

ch task blockers ask <taskId> <blockerId> --ask-file ask.json

The blocker keeps its age and its author. CodeHerder refuses this on a blocker that waits on a network access request, a merge request, a managed-settings approval, a question or an upstream task. It also refuses a closed blocker, and one that already has an ask.

Blockers that clear through their request, question or dependency

Four kinds of blocker wait on something that has its own answer. Only that answer clears them. A merge-request blocker isn’t one of them: it clears itself, and you can also resolve it by hand.

The blocker waits on What clears it
A network access request A workspace admin allows or denies the request. In the web app, the task’s Active blockers list shows Allow and Deny buttons for an admin. A member who can’t decide sees “Needs a workspace admin to allow” the destination and an Ask admins button. See Network access approvals.
A managed-settings request A human workspace owner or admin approves or rejects the request, or chooses Try again once the device is fixed. See Approving your organization’s Claude settings.
An agent question An answer to the question. The Active blockers list links to it as Answer the question. From the CLI, use ch task questions answer <taskId> --from-file <file>. See When an agent needs your input.
Another task The upstream task finishes, or you remove the dependency. In the web app, click Remove dependency. From the CLI, run ch task undepend <taskId> <upstreamTaskId>.

ch task unblock and the web app’s Resolve button refuse these blockers, for every member, including admins and owners. The message names the way out, for example “Remove the dependency (ch task undepend …) or finish or cancel task …”. Moving the task out of blocked by hand is refused too, as long as one of these blockers is open. Cancelling the task still works, and it closes every blocker.

Blockers that wait on a merge request

When a task can’t go on until someone merges a pull or merge request, it can wait on that request. The task moves to blocked. When the request needs action, or merges, the blocker clears itself and the task goes on. The agent’s next brief says why. After a failed pipeline or a conflict, the agent fixes the request and blocks on it again. An agent usually files this blocker, most often in the merge stage when a person has to press the merge button. You can file it too, from the CLI:

ch task block <taskId> --on-merge-request https://github.com/acme/shop/pull/42

The reason is optional. It defaults to “Waiting for a merge request to merge”. Give more than one request as a comma-separated list, or repeat the flag. A call takes up to 20 requests. The URL must be a GitHub or GitLab pull or merge request.

CodeHerder refuses the blocker in these cases:

  • The request isn’t recorded. It must be recorded on a task in your workspace. The message names the fix: ch task merge-requests create <taskId> <url>. A pull request link that an agent writes into a task’s artifact field is recorded for you. See Waiting for a person to merge.
  • The request is already merged or closed. There’s nothing left to wait for.
  • The request belongs to a parent or other ancestor of the task. A task can’t wait on its own ancestor, because the parent holds its start until the task ends. Detach the task, or file the work as a sibling that depends on the parent.
  • You also ask for network access approval. A blocker waits on network access requests or on merge requests, not both.
  • An agent files a free-text blocker that names an open pull request of its own task. For example, the reason says “waiting for review of #42”. CodeHerder refuses it and gives the --on-merge-request command to use instead. A person’s free-text blocker is not checked.
  • The task runs in local mode. Nothing reads a request’s state there, so the wait would never end. See Local tasks.

Run the command again on the same task to add more requests. They join the open merge-request blocker. CodeHerder doesn’t file a second one.

The blocker clears when any request you named needs action, or when all of them have merged. A request needs action in these cases:

  • Closed without a merge.
  • Its pipeline failed. A required job that failed while the pipeline still runs counts too. The agent can act before the pipeline ends.
  • It has a conflict that CodeHerder saw after you filed the blocker.
  • It was approved. A reviewer approved it after you filed the blocker, or your git host reports it ready to merge. The head pipeline must not be running. This happens once for each head commit.
  • Its pipeline passed. This happens once for each pipeline run.
  • The merge queue removed it. Your git host’s merge queue took the request out without merging it, after you filed the blocker. On GitHub, this is the merge queue. On GitLab, auto-merge was cancelled. CodeHerder waits two minutes first. The agent then checks the failed run. For a flaky or infrastructure failure it queues the request again. For a real defect it fixes the request or sends the task back to code. A task parked from an externally_merged stage does not queue it again. It asks a person.
  • A reviewer commented. This is for a task parked from a merge stage that a person or an outside process merges (externally_merged). Such a task ignores the approved and pipeline-passed wakes. A new comment or review on the request, after you filed the blocker, wakes it instead. A bot you set to drop does not count, a bot you set to collapse does, and an approval never does. CodeHerder waits until the newest comment is 90 seconds old, so one review is one wake. The agent’s next brief lists the comments. The agent acts on them as its stage instructions direct.

If one request merges and the others stay open, the blocker keeps waiting. The agent’s next brief lists each request that settled and why. CodeHerder resolves the blocker as soon as it records the change. A periodic check catches any change it missed. It shows no person as the resolver. If nothing else holds the task, it goes back to the stage it was blocked from. The agent in that stage then decides what to do next. CodeHerder learns a request’s state from your git host connection, so this works only where CodeHerder can read your requests. See Integrations.

This blocker is not one of the three that clear only through their request, question or dependency. If you merge outside the flow, or the wait no longer matters, resolve it by hand as described in Resolving a blocker.

In the web app, the task’s blocked banner and Active blockers list show one line for each request. An open one reads “Waiting for merge request: !42 Add checkout” with the state Open. A settled one reads “Merge request: !42 Add checkout” with Merged or Closed without merging. The title links to the request on your git host. The web filing form has no control for this blocker. File it from the CLI.

Blockers that release themselves

Any blocker you file can carry a release time — a future instant after which CodeHerder resolves it for you. It’s useful for a cool-down period, a wait on a vendor maintenance window, or simply “don’t touch this again until Monday” — anything where you already know when the hold should end, so there’s no reason to make anyone come back and clear it by hand.

Web app: the filing form has an optional Auto-release at field — a date and time picker, read in your own time zone.

CLI: add --until or --for to ch task block, mutually exclusive:

ch task block <taskId> --reason "Waiting out the maintenance window" --until 2026-09-01T09:00:00Z
ch task block <taskId> --reason "Cooling down before retry" --for 24h

--until takes a full timestamp, or a bare date (2026-09-01) — a bare date resolves to midnight UTC, so if you mean a specific time of day in your own zone, spell out the full timestamp instead. --for takes a duration counted from now, for example 30m or 24h. There’s no day unit, so write a week as 168h, not 7d. Either way, the release time has to be in the future; CodeHerder rejects the blocker outright if it isn’t.

A wait for a scheduled time uses --until <RFC3339> or --for <duration>. An agent’s reason that names a clock time or a duration (for example “Resume at 01:15Z” or “in 30m”) is refused without one. A human filer is not checked. Pass --no-time to file the blocker untimed on purpose.

Use a timer only for a re-check you can do alone: a CI run, a deploy, an observation window you can read. Never use a timer to poll a person. When a person must act, file an ask with --ask-file. A timed note with an ask still shows in the person’s Needs you, with its release time.

When the release time arrives, CodeHerder resolves the blocker for you — it’s checked roughly every five minutes, not to the second. If the blocker had moved the task to blocked and nothing else is holding it, the task returns to its stage automatically, the same as resolving it by hand would. An auto-released blocker shows no one as the resolver, since you didn’t act on it — just the time it cleared.

Filing a blocker with a release time doesn’t stop you from resolving it early — see Resolving a blocker below. There’s no way to change a release time once it’s set; resolve the blocker and file a new one with the time you actually want.

The Blockers page

The Blockers link stays in the sidebar at all times, with a pulsing red badge showing a count — the badge is absent when that count is zero. The count is scoped to blockers that need a person: it doesn’t include unmet-dependency notes, so a task quietly waiting on an upstream never turns it red.

Above the list, a Show control has two toggles: Active hides already-resolved blockers, and is on by default; Unmet dependencies brings dependency notes into view, and is off by default. Together, the page opens showing only unresolved, person-facing blockers. A search box next to the toggles matches on the reason text, the task’s title, or who filed it. Scroll down and the list keeps loading more.

A third toggle, Stale, narrows the list to open blockers that have sat for more than 7 days with no ask. It leaves out blockers that wait on a dependency, a network access request, a merge request, a settings approval or a question. It also leaves out blockers with a release time. These are notes nobody can act on from Needs you, so they can sit unnoticed.

Once you move off that default view (you type a search, turn Active off, or turn on Unmet dependencies or Stale), a Showing N of M count and a Clear filters button appear. Clear filters returns you to the default view.

Click Task, Filed by, or Filed to sort by that column; unsorted, the list reads newest first. When more rows are still to load, a note reads “Sorted within N loaded blockers”: a sort orders only the rows already loaded. Each row shows:

  • Task — the affected task; click the row to open it.
  • Reason — the blocker’s reason. For a dependency note this reads as “Waiting on” the upstream task’s own title, linked straight to it; for anything else it’s the free-text reason. A line underneath can show the release time, only while the blocker is still open.
  • Filed by — who or what filed it.
  • Filed — when it was filed.

A row whose own task has since been cancelled carries a Task cancelled badge; a dependency row carries an Unmet dependency badge; a row that matches the Stale filter carries a Stale badge. An action column offers Resolve on an active plain blocker. A blocker that waits on a network access request shows “Needs a network access decision”. One that waits on a question shows an Answer the question link. A dependency shows “Clears when the upstream task finishes”. A resolved row instead shows when it was cleared, and by whom — except one that released itself automatically, which shows only the time, since nobody acted on it.

Your personal My work view lists the blockers that carry an ask in its Needs you section — see Blockers that ask you to choose. A blocker with no ask doesn’t appear there. It covers the tasks you filed or watch, across your workspaces — see My work.

Filing a blocker yourself

Web app: open the task, find the Active blockers section, and click File blocker to open the filing form. Alongside the reason, it has an optional Auto-release at field — see Blockers that release themselves above.

CLI:

ch task block <taskId> --reason "Waiting for the vendor API contract" [--until <timestamp>|--for <duration>]

--reason also accepts --reason-file <path> (or --from-file <path>) or a piped-in body for longer notes. Filing a blocker moves the task straight to blocked from whatever active stage it was in.

A parent task with open children is not a reason to block. When its agent runs ch task status to finish it, the task waits for its children. When the last child finishes, an agent starts in the task’s current stage. See Waiting for child tasks to finish.

There is one rule about waiting. To wait on another task, add a dependency. It releases itself when the upstream is done, or earlier if you pick another release condition. A started task returns to To do and restarts from current main with a fresh plan. To wait on anything else, such as a person, a release or access, file a blocker with a resume condition. Add --for or --until for a bounded wait. A blocker never links a task. To wait on a task:

ch task depends-on <taskId> <upstreamTaskId>

See Task dependencies for the full dependency model.

Viewing a task’s blockers

ch task blockers <taskId>                              # every blocker on the task, active and resolved
ch task blockers <taskId> --active                     # only unresolved blockers
ch task blockers <taskId> --limit N --cursor <token>   # default 200, max 500

The table lists STATE, ID, FILED-BY, BLOCKED-ON, RELEASES-AT, and REASON — in that order. BLOCKED-ON names the upstream task of a dependency note, or - for any other blocker. RELEASES-AT shows the release time for a blocker that has one, in your own time zone, and - for one that doesn’t. REASON truncates long text. For a merge-request blocker it ends with each request’s state, such as [!42 open] — for the full reason, read the task’s detail page in the web app, or add --json to the command above. For an automatic dependency note, the CLI’s REASON column shows CodeHerder’s own internal tracking text rather than a friendly sentence; BLOCKED-ON already names the upstream task directly, so read that column instead. See Paging through long lists.

Resolving a blocker

Pass the blocker’s own ID from the list above — not the task ID:

ch task unblock <blockerId>

Any workspace member can resolve a plain blocker by hand at any time — that is, any blocker except the three kinds in Blockers that clear through their request, question or dependency. That includes one with a release time still ahead of it, resolving it early rather than waiting for that time to pass. Resolving one already resolved is refused, not a no-op — check ch task blockers <taskId> if you’re not sure it’s still open. For a blocker that moved the task to blocked (see How a task gets a blocker above), resolving the last active one automatically returns the task to the stage it was at when it was blocked, and work resumes with no further action. If CodeHerder can’t determine that stage, the task stays at blocked — move it forward yourself:

ch task status <taskId> <stage>

Moving a task out of blocked by hand this way resolves every plain blocker still open on it, not just the one you had in mind — useful if you know the underlying problem is fixed and don’t want to track each one down individually. If the task still has an open blocker that waits on a network access request, a question or an upstream task, the move is refused. Moving the task to cancelled is the exception: it closes every blocker, and any open question with it.

A question blocker never closes unanswered. Answer the question instead — see When an agent needs your input.

A dependency note doesn’t return a task from blocked, since the task’s status never changed in the first place — see Which blockers need you above for what actually has to happen before the task can proceed.

ch task block, ch task blockers, and ch task unblock above are frozen aliases for the nested ch task blockers child collection (create/list/resolve) — see Managing a record’s child collections.

When the pull requests merge while a task is blocked

A person can merge a task’s pull request on the git host while the task is still blocked, for example after the reject-loop cap. CodeHerder does not move the task. Once the task’s own pull requests have merged, the task shows a merged-while-blocked flag. The flag appears on the task page, in the task’s merge requests and on your blocker lists. CodeHerder records a task.merged_while_blocked event once for each block. Webhooks and session subscriptions can receive it. Watchers get no DM for it.

The flag has three states. The web app and the CLI word them differently:

State Web app CLI (ch task show) What you can do
All merged All pull and merge requests merged while blocked All PRs merged while blocked, followed by the ch task status commands to run next Move the task yourself.
Still waiting Own pull and merge requests merged; still waiting on another merge request Own PRs merged; waiting on each open request, for example !42: open, pipeline running Nothing. The task stays blocked until that request settles.
Resolving All pull and merge requests merged; the merge wait is resolving All PRs merged; the merge wait is resolving Nothing. The task returns to its stage when the merge wait resolves.

Only the first state offers a move. In the web app, use Unblock to the next stage to continue, for example to verify the work. Use Mark done to close the task. From the command line, ch task show prints both commands.

The other two states come from a merge-request blocker. While another request it names is still open, the task shows “still waiting”. Once every request it names has merged or closed, the task shows “resolving” until CodeHerder resolves the blocker. Then the task goes back to its stage by itself. If something else holds the task, the flag moves to “all merged” and you decide what happens next.

Who gets notified

When a blocker moves a task to blocked, CodeHerder messages the task’s owner — unless the owner is the one who filed it. It also messages anyone watching the task for status changes. Mentioning someone in a blocker’s reason (@name) notifies them too, the same as an @-mention anywhere else on a task. See Watching tasks and notifications for what a watcher actually receives and how to change it.

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