Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions crates/core/src/agents/helpers.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
//! Helpers an agent runs inside its own work (Codex's sub-agents, Claude Code's background agents). A helper's turn
//! ending is not the agent's: Codex reports it like any turn end, with the helper's own thread, whose saved
//! conversation names the thread that started it. And while a helper the agent started is still at work, the agent's
//! own turn ending is not the end of its work: the helper's answer starts the agent again.
//! Helpers an agent runs inside its own work (Codex's sub-agents, Claude Code's background agents and the commands it
//! runs in the background). A helper's turn ending is not the agent's: Codex reports it like any turn end, with the
//! helper's own thread, whose saved conversation names the thread that started it. And while a helper the agent started
//! is still at work, the agent's own turn ending is not the end of its work: the helper's answer starts the agent again.
use super::adapter::transcript;
use super::read_turn::{head_of, read_turn, tail_lines, when, Turn, TAIL};
use crate::json::*;
Expand Down Expand Up @@ -53,15 +53,24 @@ fn word_after(line: &str, key: &str) -> Vec<String> {
/// `<task-notification>` comes back. One that comes back while the agent's turn is still going is no message of its own:
/// it is written as a queued command (`queue-operation`, then an `attachment` taken into the running turn), as seen on
/// HSW-218 (Claude Code 2.1.300, 2026-10-15), where the board waited for a helper back for half an hour.
/// A command it runs in the background (a Bash with `run_in_background`, or one moved there when its timeout ran out)
/// is at work the same way, from the result that names it (`backgroundTaskId`) until its `<task-notification>`
/// (completed, failed or killed), or until TaskStop's result: a stopped one gets no notification (Claude Code 2.1.308 to
/// 2.1.322). Before, a turn that ended while one ran was taken for the end, and the check and the review ran while it
/// still did (upstream Shepherdr SHEP-148).
fn claude_running(file: &Path, since: i64) -> usize {
let mut live: Vec<(String, i64)> = vec![];
let mut known: Vec<String> = vec![];
for (l, e) in lines_with(file, &["Async agent launched", "<task-notification>", "\"SendMessage\""]) {
for (l, e) in lines_with(file, &["Async agent launched", "<task-notification>", "\"SendMessage\"", "backgroundTaskId", "Successfully stopped task"]) {
let at = when(e.at("timestamp"));
if e.s("type") == "user" && l.contains("Async agent launched") {
for id in word_after(&l, "agentId: ") { live.retain(|(x, _)| *x != id); live.push((id.clone(), at)); known.push(id); }
} else if ["user", "attachment", "queue-operation"].contains(&e.s("type")) && l.contains("<task-notification>") {
for id in word_after(&l, "<task-id>") { live.retain(|(x, _)| *x != id); }
} else if e.s("type") == "user" && !e.b("isSidechain") {
let r = e.at("toolUseResult");
if let Some(id) = shell_started(&e) { live.retain(|(x, _)| *x != id); live.push((id, at)); }
else if r.b("task_id") && r.s("message").to_lowercase().contains("stopped") { let id = r.t("task_id"); live.retain(|(x, _)| *x != id); }
} else if e.s("type") == "assistant" {
for c in e.at("message").arr("content") {
let to = c.at("input").t("to");
Expand All @@ -71,6 +80,10 @@ fn claude_running(file: &Path, since: i64) -> usize {
}
live.iter().filter(|(id, at)| *at >= since && !claude_back(file, id, *at)).count()
}
/// The id of a command Claude Code moved to the background: its result's `backgroundTaskId` (in every one recorded,
/// 2.1.308 to 2.1.322). Never the words of the result: a foreground command's own output may begin with them, and no
/// notification would ever end a command it never started.
fn shell_started(e: &Value) -> Option<String> { Some(e.at("toolUseResult").t("backgroundTaskId")).filter(|id| !id.is_empty()) }
/// A Claude Code helper's own conversation (`<conversation>/subagents/agent-<id>.jsonl`) ends in its finished reply,
/// written since it was last started: it is back, whatever the agent's own file shows of its notification.
fn claude_back(file: &Path, id: &str, at: i64) -> bool {
Expand Down
7 changes: 7 additions & 0 deletions docs/how-work-gets-done.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,13 @@ When the agent's turn ends, the board:
still going. (The same holds for a working agent and its task.) A helper is back when its answer is in the
conversation (a message of its own, or a queued one taken into a turn still going), or its own saved conversation
ends in its finished reply.
- A command Claude Code runs in the background (a Bash with `run_in_background`, or one moved there when its
timeout ran out) counts the same way: a turn that ends while one runs is not the end. It has ended when its
notification is in the conversation (completed, failed or killed) or the agent stopped it (TaskStop). Its end
starts the agent again, and that turn's end is the one that counts. So the check, the review and the "ready"
alert start once, after the command, not while it runs. Meanwhile the row says `Finishing`. A command that never
ends (a server left running) holds it there: the agents are told to stop theirs before they finish, and `Ctrl+L`
takes the work as it is.
- A reviewer whose turn its provider cut off is retried by the board ([a turn cut off by the provider](provider-errors.md)).
- It starts with your own hooks off, and is not started at all when its program says it is signed out here
([the reviewer's own start-up screens](#the-reviewers-own-start-up-screens)).
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ Find what its row says:
| `queued after HSW-12` | it waits for other tasks to be done ([one task after another](after.md)) | wait, or `herdr-projects delegate <id> --now` |
| `Has not started yet: pressing enter again` | the task's text sits in the agent's box | wait a moment: the board presses enter again |
| `Not started: its instructions sit unsent in its box` | the text never went in | `Ctrl+L` (retry), or go into the agent and press enter ([handing over](handing-over.md)) |
| `Finishing` for a long time, with the agent at rest | the board missed the end of its turn | `Ctrl+L`, or `herdr-projects finish <id>` |
| `Finishing` for a long time, with the agent at rest | a command the agent runs in the background (Claude Code) has not ended, and the task waits for it ([how work gets done](how-work-gets-done.md)); or the board missed the end of its turn | wait for the command, or have the agent stop it; `Ctrl+L`, or `herdr-projects finish <id>`, takes the work as it is |
| `Stopped without a summary` | the agent stopped and the board cannot tell if it finished | `Ctrl+R` tells it to go on; `Ctrl+L` takes the work as it is |
| `Agent's connection dropped, trying again in 2m` | the provider cut the turn off | nothing: the board retries by itself ([a turn cut off by the provider](provider-errors.md)) |
| `Agent stopped` | an error waiting cannot fix: a usage limit, a refusal | read the reason in the panel; reply, or `Ctrl+R` |
Expand Down
4 changes: 4 additions & 0 deletions tests/fixtures/endings/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,5 +22,9 @@ the API's documented 529 and 429 texts; the two `-finished-made` files are an or
- `claude-helper-back-mid-turn-made` (tests/finish_missed.rs): a helper whose answer comes back while the agent's turn
is still going, in the shape recorded on HSW-218 (Claude Code 2.1.300): its `<task-notification>` is only a
`queue-operation` and an `attachment` (a queued command taken into the running turn), never a message of its own.
- `claude-shell-running-made`, `claude-shell-back-made` (tests/helpers/shells.rs): a turn that ends while a command it
started in the background still runs, and the turn the command's end starts, in the shape recorded from Claude Code
2.1.314 (a Bash result with `backgroundTaskId`, then its `<task-notification>` queued and taken as a message), with
folder names cut.
- `claude-idle-compaction` (tests/turns/ended_late.rs): recorded on 2026-10-24 (Claude Code 2.1.312), summary and file
names cut: what Claude Code writes when it compacts a session left idle an hour after its turn ended, with no prompt.
4 changes: 4 additions & 0 deletions tests/fixtures/endings/claude-shell-back-made.jsonl
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{"type": "queue-operation", "operation": "enqueue", "sessionId": "made", "content": "<task-notification>\n<task-id>bk3m9x2qa</task-id>\n<tool-use-id>toolu_made_s1</tool-use-id>\n<output-file>/private/tmp/claude-501/made/tasks/bk3m9x2qa.output</output-file>\n<status>completed</status>\n<summary>Background command \"Run the full check\" completed (exit code 0)</summary>\n</task-notification>"}
{"type": "queue-operation", "operation": "dequeue", "sessionId": "made"}
{"type": "user", "uuid": "made-s4", "isSidechain": false, "message": {"role": "user", "content": "<task-notification>\n<task-id>bk3m9x2qa</task-id>\n<tool-use-id>toolu_made_s1</tool-use-id>\n<output-file>/private/tmp/claude-501/made/tasks/bk3m9x2qa.output</output-file>\n<status>completed</status>\n<summary>Background command \"Run the full check\" completed (exit code 0)</summary>\n</task-notification>"}, "origin": {"kind": "task-notification", "producer": "session-task"}, "promptSource": "system", "turnOrigin": "task_notification"}
{"type": "assistant", "uuid": "made-s5", "message": {"id": "msg_made_s5", "role": "assistant", "content": [{"type": "text", "text": "The full check passed. Done."}], "stop_reason": "end_turn"}}
3 changes: 3 additions & 0 deletions tests/fixtures/endings/claude-shell-running-made.jsonl
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{"type": "assistant", "uuid": "made-s1", "message": {"id": "msg_made_s1", "role": "assistant", "content": [{"type": "tool_use", "id": "toolu_made_s1", "name": "Bash", "input": {"command": "npm run check -- --all", "description": "Run the full check", "run_in_background": true}}], "stop_reason": "tool_use"}}
{"type": "user", "uuid": "made-s2", "isSidechain": false, "message": {"role": "user", "content": [{"tool_use_id": "toolu_made_s1", "type": "tool_result", "content": "Command running in background with ID: bk3m9x2qa. Output is being written to: /private/tmp/claude-501/made/tasks/bk3m9x2qa.output. You will be notified when it completes — do not poll that file or sleep while waiting."}]}, "toolUseResult": {"stdout": "", "stderr": "", "interrupted": false, "isImage": false, "noOutputExpected": false, "backgroundTaskId": "bk3m9x2qa"}}
{"type": "assistant", "uuid": "made-s3", "message": {"id": "msg_made_s3", "role": "assistant", "content": [{"type": "text", "text": "Committed. The full check runs in the background; I finish once it has passed."}], "stop_reason": "end_turn"}}
12 changes: 8 additions & 4 deletions tests/helpers.rs
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
//! Helpers an agent runs inside its own work (Codex's sub-agents, Claude Code's background agents): a helper's turn
//! ending is not the review's or the task's end, a turn that ends while a helper is still at work is waited past, and
//! a reviewer that really ended without a verdict is started once more by itself. Seen on HP-1 (2026-10-15): a Codex
//! reviewer's helper `/root/check_plans` finished, and the board failed the review for want of a verdict.
//! Helpers an agent runs inside its own work (Codex's sub-agents, Claude Code's background agents and commands): a
//! helper's turn ending is not the review's or the task's end, a turn that ends while a helper is still at work is
//! waited past, and a reviewer that really ended without a verdict is started once more by itself. Seen on HP-1
//! (2026-10-15): a Codex reviewer's helper `/root/check_plans` finished, and the board failed the review for want of a
//! verdict.
use crate::common;
use common::*;
use serde_json::{json, Value};
use sw::json::*;
use sw::store::reviews::{review_history, review_round};

/// A command Claude Code runs in the background, at work until it ends (upstream SHEP-148).
mod shells;

fn work() -> Value { json!({ "files": { "f.txt": "v1\n" }, "commit": "v1", "note": "Did v1." }) }
fn verdict() -> Value { json!({ "meets": true, "findings": [], "text": "Looks right." }) }
fn reviewer_starts(w: &World) -> usize { calls(w).iter().filter(|c| regex::Regex::new(r"^agent start \S+-r ").unwrap().is_match(c)).count() }
Expand Down
Loading
Loading