supervising-workers
Skill2 starsChanged 2 days agoMITView on GitHub
Use when acting on ANOTHER agent's task from inside a runner-spawned task — spawning / driving / killing worker sessions, one-shot sessions (`session new --oneshot`) and getting their answer back, `watch`, attenuating a child's capabilities with `--caps`, moving files in or out of a worker's worktree, running a command in one with `exec`, or reading a worker's diff or its agent transcripts. Peer-to-peer messaging, replying and subscriptions live in the `harness-cli` skill instead.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-tourSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- session-debuggingSkill
- codebase-tourSkill
- dummy-harnessSkill
- harness-cli-from-a-toolSkill
- harness-cliSkill
- implementation-pitfallsSkill
- independent-reviewSkill
- landing-to-mainSkill
- memory-maintenanceSkill
- running-parallel-workersSkill
- session-debuggingSkill
- supervising-workersSkill
- surface-parity-checklistSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 1 is distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Read that skill first regardless: the trust model, the "you may not be the first process on this task" caveat, and the async-by-default …
- Very specific: line 21
When you need to delegate work to another agent that you intend to keep talking to, prefer harness-cli session new -d (an interactive …
- Very specific: line 122
If a worker session gets canceled (failed, killed, you want a clean restart) and you intend to start another one playing the same role, …
- Very specific: line 154
Use the flag, not --agent-arg --continue.
- Very specific: line 239
Keep the -d. Opening a session WITHOUT -d hands you its control seat, which needs exec_control over it.
- Very specific: line 244
Reuse > re-spawn, and never hand-type the id: When you mean the *same role*, resume the existing task instead of spawning a fresh one — it …
- Very specific: line 291
default (no flag): LONG-POLLS — blocks until the fire, prints {"status":"fired",...} (exit 3 = session ended first).
- Very specific: line 316
Every fire, whatever the signal, reports fired_by (the leg that fired) and the lifecycle, program_state and program_kind the session showed …
- Very specific: line 456
After verification / probe work, prune the throwaway tasks you spawned so ls stays readable.
- Very specific: line 513
--scopebounds the targets: Default subtree = yourself and everything you spawned, transitively. - Very specific: line 630
granter=says who last granted a task's authority: Every ls row ends its authority with granter=<source>@<actor> (<age>) — … - Very specific: line 764
instead of picking one for you — see "A spawn can answer ambiguous_runner" above.
- Very specific: line 766
A foreground
--oneshotdoes not queue: When every runner that could take it is full, the open is refused runner_busy. - Very specific: line 878
Prefer this over having the worker paste large files through agentboard messages: file streams the bytes directly and keeps the agentboard …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
supervising-workers (another agent's task, end to end)
Everything here is about a task acting on ANOTHER task, across its whole
lifetime: creating it, bounding what it may do, steering and watching it,
inspecting what it produced, and tearing it down. If you only need
to talk to a peer that already exists, you want the harness-cli skill —
sending, replying with --in-reply-to, subscriptions and the handshake
conventions are all there.
Read that skill first regardless: the trust model, the "you may not be the first process on this task" caveat, and the async-by-default rule apply to everything below.
Spawning a worker agent
When you need to delegate work to another agent that you intend to keep
talking to, prefer harness-cli session new -d (an interactive session)
over a one-shot (session new -d --oneshot).
# Spawn a detached interactive PTY agent on a specific repo. Prints the
# new task id on stdout; the agent stays alive in the background.
TASK_ID=$(harness-cli session new -d --repo /path/to/repo)
# Reach it on the agentboard. The agent's inbound channel is
# chat.<first-8-chars-of-TASK_ID> — same convention this skill uses for
# every agent's "naming inbound channels" rule.
SHORT_ID=${TASK_ID:0:8}
harness-cli agent send --topic "chat.$SHORT_ID" --data "$(cat <<'JSON'
{
"kind": "hello",
"from": "<your role>",
"message": "..."
}
JSON
)"Why interactive sessions over --oneshot:
--oneshotruns the agent's print mode (claude-p, codexexec) on the prompt you supplied: it answers once and exits, and the session ends with it. Once it is running, neither you nor the user can step in to adjust direction, answer a clarifying question, or feed it new context — an agentboard message cannot start a second turn. That makes it a bad fit for any collaborative workflow.session new -dkeeps the worker alive between turns, so you can drive it iteratively via agent messages and the user can also intervene at any time (attach withsession attach <task-id>, send corrections via the agentboard, etc.).--oneshotstill has a place for genuinely narrow tasks ("give me a one-line summary of X") where mid-task intervention is not needed — but treat it as the exception. "One-shot sessions" below covers how to get its answer back.
Use auto mode for complex delegated work
For any non-trivial worker — anything that will require multiple tool
calls, file edits, or long autonomous stretches — start the worker in
auto permission mode by forwarding the flag through --agent-arg:
harness-cli session new -d --repo /path/to/repo \
--agent-arg --permission-mode --agent-arg auto--permission-mode auto is Claude's flag, and --agent-arg forwards it
verbatim to whatever binary the profile runs. Check the profile's agent= in
ls: a worker on another agent CLI needs that runtime's own equivalent, passed
the same way.
Without this the worker spawns in the default permission mode and will
stall on every permission prompt — and since the worker is detached, no
TTY is attached to answer them. Auto mode lets the worker proceed
through routine tool calls on its own while still respecting harder
safety boundaries (it is not the same as bypassPermissions). Use it
as the default for delegated work; reserve narrower modes for cases
where you have an explicit reason.
The session's PTY size
harness-cli session new -d --repo /path/to/repo --rows 40 --cols 150A -d (or --background) open is sized 40x120 unless you pass --rows and
--cols; --rows 0 --cols 0 sends no size, and the session then has no size
at all until a client attaches. The size belongs to the CONTROL attach
whenever someone holds it. Two ways to set one without taking it over:
- size it here, at open — always available to the spawner;
- later, with
harness-cli session resize --size 40x150 <id>(orsession send --resize 40x150 <id> <text>to size and drive in one call). Needsexec_resizeon top ofexec_view, and applies only while no control client is attached — the unattended worker you spawned with-d, which is the case that used to have no answer at all. The capability is orthogonal toexec_view/exec_cowrite: ask for it explicitly, it is not implied by being allowed to type. The command exits 3 when the size did not take, so do not assume it worked.
Without either, session exec <id> 'stty rows 40 cols 150' still works when the
foreground is a POSIX shell — but not when it is the full-screen TUI whose size
you were trying to fix. Both flags are required together (one alone is ignored).
And stty does not tell the SERVER, so a session sized only that way
renders PARTIAL under snapshot — which reads as a broken program rather than
an unset size. If you intend to READ the screen, size it with session resize
/ send --resize. The mechanism and the measurement are in session-debugging
under session resize; they are not repeated here.
It matters when the worker's agent draws a full-screen TUI and you opened it at
0x0: codex then paints literally nothing, so snapshot returns a blank screen
and the worker looks hung when it is merely undrawn.
Reuse the same task id with --resume
If a worker session gets canceled (failed, killed, you want a clean restart)
and you intend to start another one playing the same role, pass
--resume <task-id> so the new session keeps the same task id:
harness-cli session new -d --repo /path/to/repo --resume "$TASK_ID"Resuming needs the resume capability, not spawn: spawn creates tasks
and nothing else, and resume re-queues an existing one without creating any.
A supervisor that restarts its own workers needs both.
Same task id means the same chat.<short-id> inbound topic, so:
- Other agents that handshook with the previous session can keep talking to the new one; there is nothing to re-discover.
- The worktree branch
harness/<task-id>is reused, so any commits the previous session made are still reachable.
But --resume alone only restores the harness-level identity — same
task id, same topic, same worktree. The new session still boots a fresh
agent process with no memory of the previous conversation. To also resume
the agent's own conversation (so the worker remembers what it was doing),
add --resume-conversation:
harness-cli session new -d --repo /path/to/repo \
--resume "$TASK_ID" \
--agent-arg --permission-mode --agent-arg auto \
--resume-conversationUse the flag, not --agent-arg --continue. --continue is Claude's
syntax; the flag makes the RUNNER pick the resume form of whichever agent
profile the task runs under (exec resume --last for Codex, --continue
for Claude, whatever --agent-resume-*-argv was configured). Injecting
--continue by hand works on Claude and breaks everywhere else.
Three layers move independently, and only two of them are yours to choose:
| Layer | Flag | What it restores |
| harness task | --resume <id> | task id, chat topic, worktree branch |
| agent conversation | --resume-conversation | the agent's own session memory, in its own syntax |
| OS process | — | nothing. Always new, with a new auth ticket and possibly a different runner |
You almost always want both flags for a "pick up where it left off"
restart. Use --resume alone when you specifically want a clean agent
mind on the same identity (e.g. the previous run got stuck in a confused
state and you want a fresh start without losing the chat topic).
The third row is why a resumed worker cannot be assumed to still hold what the previous run set up — see "You may not be the first process on this task" above, which is the same fact seen from inside the resumed session.
Without --resume you get a fresh task id and the peers' link to the
previous identity is dead — they will need a new hello round.
Bringing back a session exactly as it was — --exact
You drive a session you did not create — a bash session the operator opened
and gave you exec_cowrite on — and a stray exit ends it. Bring it back
with the settings it was recorded with:
harness-cli session new --resume "$TASK_ID" --exact -d
harness-cli session send -enter "$TASK_ID" 'echo back'--exact takes the task's recorded agent, args, kind, caps and scope, and the
last run's prompt and --oneshot (that prompt is sent again), so it needs only
resume_exact (which resume implies), and it refuses every setting flag
beside it — --agent, --agent-arg, --caps, --scope, --scope-for,
--delegate-caps, --delegate-scope, --prompt and --oneshot. Leave --repo and --runner off: the server
reopens it on the runner it last ran on. --resume-conversation still works,
and so do -d, the size and --pty / --no-pty (without either it takes the
last run's PTY choice).
Unattended work — --background
A background session is a detached session that nobody has to watch: it waits in the queue for a free runner instead of being refused, starts the agent with a prompt, and ends itself.
TASK_ID=$(harness-cli session new --background --repo /path/to/repo --agent claude \
--deadline 30m --prompt "Triage the new issues and report on chat.<your-short-id>")- Required:
--prompt(at most 16384 bytes),--deadline, and--agenton a new task.--backgroundimplies-d. A profile with no prompt slot in its template (thebashpreset) cannot take one: the task endsFailedwithprompt_unsupported. - What ends it — the first of: the deadline; the end of a turn
(
--turn-end any|lifecycle|program|quiet|off, defaultany); the agent waiting on a human for longer than--blocked(default 5m);--queue-timeoutwhile it is still queued; the agent exiting. The end is a cancel, so the status usually readsSucceeded; read the reason inls:run=bg end=turn_done_program,end=deadline,end=blocked_timeout, … While it runs the row showsrun=bg deadline=<time left> until=<clock time>, and while queuedwait=all_busy(runners that could take it are full) orwait=no_candidate(none could). - A directory its agent has never trusted stops the run at the trust
dialog, with the prompt unprocessed. The harness does not answer it: the
operator attaches and answers once, and the agent remembers the directory.
Until then a claude or codex run ends
turn_done_quietafter the quiet threshold (5m) although it did nothing — the dialog's draw is its only output — and that repeats on every resume. Aturn_done_quieton a task's first run in a new directory means "look at it", not "done". - A resume reuses nothing but the agent and the run mode. Resuming a
background task is a background resume unless you pass
--foreground, and it needs--promptand--deadlineagain. - Switch a running session with
harness-cli session mode <id> foreground(it then runs until someone ends it) orsession mode --deadline 1h <id> background. Either direction needscancelover the task, and a task may not switch its own run mode in either direction.
Keep the -d. Opening a session WITHOUT -d hands you its control seat,
which needs exec_control over it; a refusal reads detach_required or names
exec_control. After a -d open you drive it with whatever your exec_* caps
allow, exactly as before it ended.
Reuse > re-spawn, and never hand-type the id. When you mean the same
role, resume the existing task instead of spawning a fresh one — it keeps
the chat topic and worktree (above) and avoids littering ls with dead
identities. Always take the task id from the spawn command's stdout or from
ls and keep it in a variable (TASK_ID=$(harness-cli session new -d …));
do not transcribe a 32-hex id by hand — a mistyped/merged id silently
targets the wrong task or none. When a peer sends you an id, reconcile it
against ls before acting on it.
Listing and killing your sessions
harness-cli session ls # JSON Lines: detachable interactive sessions only. Each row shares the `ls --json` task vocabulary (id, status, kind, repo, from, agent, caps, created_by, prompt, exit_code, created_at/started_at/ended_at, last_output_at, output_idle_ms, progress, progress_at, progress_age_ms, live_terminal, title, authority_source, authority_actor, authority_actor_hidden, authority_at, authority_age_ms, delegate_caps, delegate_scope) plus session-only is_attached + ring_buffer_bytes; it differs from `ls --json` ONLY by the interactive filter
harness-cli session kill <id> # terminate one (alias of `cancel`)
harness-cli session snapshot <id> # PRINT the current screen as text (non-TTY; safe for you)
harness-cli session send -enter <id> "…" # inject input + Enter (non-TTY co-write); flags BEFORE the id
harness-cli session exec <id> <cmd>... # RUN one shell cmd, wait, return combined output + exit code (POSIX-shell foreground)
harness-cli session await-idle --topic chat.<your-short-id> <id> # one-shot "tell me when its turn ends" (--signal picks how: below)
harness-cli session await-idle ls # the watchers you have armed
harness-cli session await-idle kill <watcher-id> # disarm one
harness-cli await-progress --since <progress_at> --topic chat.<your-short-id> <id> # one-shot "tell me its next stage" (any task kind)
harness-cli session attach <id> # HUMAN ONLY (needs a real TTY) — see belowBusy/idle detection — stop polling snapshots
An interactive session's PTY output is byte-quiescent exactly when the foreground program is waiting for input: an in-flight agent turn repaints its spinner ~every 100ms, an idle prompt emits nothing at all. Two surfaces:
- Pull:
session lsincludeslast_output_at(unix nanos; 0 = no live session output) andoutput_idle_ms(server-clock idle age; only meaningful whenlast_output_at > 0), plus anactivitystring (busy/idle:Xs) when output has been seen. The top-levellsrenders the same as anact=busy/act=idle:Xsbadge, andls --jsoncarries the identicalactivity/output_idle_ms/last_output_atfields. Every row, of any task kind, also carries the worker's self-reportedprogressline,progress_at(unix nanos, server clock; 0 = never written) andprogress_age_ms— an emptyprogresswith a non-zeroprogress_atmeans the line was CLEARED (by the worker or a--clear --task), not that it was never set — plus the live windowtitle; read the title only whenlive_terminalis true; false means no live terminal session. - Push (one-shot):
session await-idle <id>fires ONCE as soon as the session is quiescent for the threshold (default 2500ms;--threshold-ms Nto override), then disarms itself. It is level-triggered, not edge-triggered: a session already idle when you arm fires immediately, and worst-case fire latency otherwise is threshold + the 500ms watch tick. Sinks:- default (no flag): LONG-POLLS — blocks until the fire, prints
{"status":"fired",...}(exit 3 = session ended first). Fine for shell scripts; never use this blocking form from an agent turn (same rule asagent wait). --topic T: repliesarmedimmediately, with thewatcher_idthatsession await-idle killtakes; on fire the server publishes{"kind":"session_idle","task":"<32-hex>","last_output_at_unix_ms":N,"status":"fired"|"session_stopped","signal":…,"fired_by":…,"lifecycle":…,"program_state":…,"program_kind":…}to T. THE agent pattern: arm with your ownchat.<short-id>, end the turn, and the fire wakes you via the inbox hook — replaces snapshot polling when babysitting a worker session, but NOT a reply you already asked for (below).--notify: repliesarmedimmediately; on fire the operator gets a notification. For "tell the human when it's done" (they may be away).
- default (no flag): LONG-POLLS — blocks until the fire, prints
--signal picks what idle means. quiet (the default) is the byte
quiescence above. lifecycle fires when the agent hooks' state (ls
lifecycle=) leaves working; program when the program's own OSC 7501
report (ls program=) does; any on whichever of the three comes first.
The two state signals fire within ~0.5s of the turn ending instead of
threshold + tick. They count a state only if it came after the session's last
input AND a working followed that input — so arming right after session
send waits for the turn you started, not the previous one — or, when the
input started nothing (text without Enter), once the session has been quiet
for the threshold.
Every fire, whatever the signal, reports fired_by (the leg that fired) and
the lifecycle, program_state and program_kind the session showed — wire
words, "" when never reported. So a state-signal fire already tells you
which "waiting for input" it found: lifecycle=waiting or
program_state=blocked with program_kind=permission|question is a prompt
waiting on a human; idle / done is a finished turn.
A source that never reports leaves a lifecycle / program watcher armed
until the session ends: an agent without the harness hooks, or any program on
a Windows runner (no OSC 7501 there). Nothing refuses the arm. Use any when
unsure, and session await-idle ls / kill for one left waiting.
A quiet fire alone cannot tell them apart — turn finished, permission
prompt, or a menu all look the same at the byte level; read the reported
states, or snapshot once after the fire (that needs exec_view). Arming the watcher itself needs
no capability at all — it reports last_output_at, which ls already gives
you — except --notify, which needs notify because it reaches the operator's
egress, and --topic on a topic outside your board reach, which needs
board_peer because the fire publishes there in your name. Your own
chat.<short-id> is always in reach.
Do not arm it for a peer you asked to report back. A skill-aware claude
worker runs agent send during its turn, so its reply reaches you while the
PTY is still emitting; the idle fire lands ~3s later and adds nothing the
reply did not say. Two wakes for one event, the second one strictly weaker.
The state signals are worse here, not better: the agentboard wake is typed
into the PTY by the runner, not through the server, so it does not count as
input, and a lifecycle / program watcher armed right after agent send
can fire at once on the previous turn's state. If you armed one anyway and the
reply arrived first, harness-cli session await-idle kill <watcher_id>
disarms it — nothing is published for a killed watcher. session await-idle ls
shows what you have armed (yours only; the operator sees everyone's). A
redundant fire costs one extra wake, so this is tidiness, not damage control.
Arm it when no reply is coming:
- the peer has no agentboard path —
agent=bash, anagent=claudewithout+skills, or any non-claude peer that must poll its own inbox; - you drove the session by keystrokes (
session send) rather than by message — a/clear, a permission answer, a menu selection. No reply exists there; quiescence, or for an agent that reports them the state signals, is the completion edge; --notify, to tell the human.
await-idle is the completion signal for the keyboard channel. The agentboard
channel already has one: the reply.
Waiting for a worker's next stage — await-progress. Idle says the PTY
went quiet, not that the worker moved on. A worker that writes harness-cli
progress (the harness-cli skill) gives you a stage edge instead, on any task
kind. Take the baseline from ls --json, then arm:
AT=$(harness-cli ls --json | jq -r --arg id "$TASK_ID" '.tasks[] | select(.id==$id) | .progress_at')
harness-cli await-progress --since "$AT" --topic chat.<your-short-id> "$TASK_ID"It fires once on the next write, set or clear — at once if the worker has
written since $AT, so a write landing between your ls and the arm is not
missed (omit --since to wait for the first write after arming). The --topic
fire publishes
{"kind":"task_progress","task":"<32-hex>","progress":"<text>","progress_at_unix_ms":N,"status":"fired"|"task_ended"}.
Sinks and gates are await-idle's: the default long-polls and prints one
{"status","progress","progress_at","watcher_id"} object (exit 0 fired, 3
task_ended, 4 cancelled) — scripts only, never from an agent turn;
--notify needs notify; --topic needs board reach to that topic. The
target must be a task you can see. await-progress ls / await-progress kill
<id> share one registry with session await-idle, so either kill disarms
either kind of watcher.
A worker's line outlives its stage — it survives a resume, the end of the task
and a deliberate server restart (a crash loses it). To empty a stale one
yourself, harness-cli progress --clear --task "$TASK_ID": it needs cancel
with that task in cancel's scope (out of scope reads not_found, no cancel
is a permission denial) and behaves like the worker's own --clear — a fresh
progress_at, so armed await-progress watchers fire. Setting text is the
worker's alone.
Reading / driving a session as the agent (you have no TTY). session attach
runs RemoteShell, which flips the local terminal into raw mode and splices it
to the remote PTY — it needs a real interactive TTY, which the human operator has
(TUI / WebUI) but you do not. Your tools are the non-TTY trio above —
snapshot (read the screen), send (inject keystrokes), exec (run one shell
command synchronously) — authenticated by your task ticket, no operator PSK.
They do not share one capability: snapshot is a view attach (exec_view),
send/exec are cowrite attaches (exec_cowrite). The caps imply downward,
so exec_cowrite covers all three. The full playbook lives in the
session-debugging skill (harness-cli skill session-debugging, or open
.claude/skills/session-debugging/SKILL.md /
.agents/skills/session-debugging/SKILL.md): tool choice (exec only fits a
POSIX-shell foreground), the send → snapshot drive loop, screen-reading flags
(--style/--color/--raw), and the footguns (flags go BEFORE <id> for
send/exec; a bare exit typed via exec kills the session; exec on a
TUI/REPL/claude foreground times out by design).
These suit terminal-level work (shells, TUIs, REPLs, or watching a screen). To coordinate a claude worker (hand it tasks / corrections), still prefer agentboard messages — the worker's claude reads its inbox; you don't need to puppeteer its keyboard. (The human may also attach in parallel; that's expected.)
session ls lists only detachable interactive sessions (a --oneshot session
is one); the top-level ls shows every task, including event-stream sessions
and oneshot-kind tasks left from before submit was retired.
A spawn can answer ambiguous_runner. session new does, with exit
status 3, whenever more than one (runner, agent)
choice matches: several runners serve the repo, or one runner offers several
agents and you passed no --agent. stderr then lists one line per runner, with
the flags that pin it:
ambiguous runner: 2 runners match this repo; re-run with the flags shown:
host1 [1/8] /path/to/repo --runner <32-hex id> --agent <claude|codex>
host1 [0/8] /path/to/repo --runner <32-hex id> --agent <claude>Re-run with one line's --runner and one of its --agent names. Pass
--agent up front when you know which agent you want; it avoids the round trip.
--host <name> / --ip <addr> also pin, but two runners on one host share a
hostname, which is why the table gives --runner.
Pruning tasks you spawned
harness-cli prune asks the server to forget tasks (they vanish from ls).
The server now bounds this to your scope — an id outside it is counted as
missing, and the age sweep only reaches tasks you can see — so the rules below
are about not destroying your OWN work, not about staying out of other
people's:
- Prune only terminal tasks (Succeeded / Failed / Cancelled) that you
spawned —
by=<your-short-id>inls. harness-cli prune <id>...forgets the listed terminal tasks. With no ids it forgets every terminal task older than--before(default 168h) within your scope. If your scope isglobal, that is still everyone's tasks: do not run the bare/age form.- A non-terminal task (Queued / Running / Detached / Held) is never
forgotten, whoever asks: its record is what lets anyone cancel, list or bound
it, and its agent would keep running without one. Prune skips it and counts
it as active. To clear one,
cancelit first (that needscancelover it), then prune. - After verification / probe work, prune the throwaway tasks you spawned so
lsstays readable.
Pipe ids straight from output; never hand-type a 32-hex id:
# forget the terminal tasks you spawned under a given repo
harness-cli ls | sed -n '/^TASKS/,$p' | grep "$REPO" \
| grep -wE 'Failed|Cancelled|Succeeded' | grep "by=$MY_SHORT" \
| awk '{print $1}' | xargs -r harness-cli pruneCapabilities and scope (--caps / --scope)
session new accepts both. --caps names the
verbs; --scope names which tasks those verbs may be pointed at. A cap
without a scope is not "may cancel" — it is "may cancel anything on the
server", which is why both exist. harness-cli caps lists the capability names
and the scope forms (--json for the machine-readable form).
- Attenuating, never amplifying. A child receives
creator_caps ∩ delegate_caps ∩ requested— you can only grant a subset of what you yourself hold AND may delegate, and caps are monotonically non-increasing down a spawn chain. - By default you may delegate no bits. Your
delegate(the caps you may put into a child's) anddelegate-scope(the most scope you may give it) are the operator's to set; the default isdelegate=none delegate-scope=subtree, so every child you spawn holds no caps whatever--capssays. Readharness-cli whoamibefore promising a worker a bit. A bit you hold but may not delegate is DROPPED silently, like one you do not hold; an id refused as "outside what you may delegate (see whoami: delegate-scope)" is outside your bound, not your own scope — the operator widens it withcaps set <you> --delegate-caps … / --delegate-scope …, so ask, do not retry. A child's own bound (--delegate-caps/--delegate-scopeon the spawn) is clamped to yours. - Spawn limits bound how many tasks you may create.
whoamiprintsspawn-depth=… max-descendants=… descendants=… room=…;roomis how many more you may create now, under every limited ancestor. Check it before promising to start workers. Every task you create counts until it is pruned: ending or cancelling a worker frees no place. On aspawn_limitrefusal, in this order: resume a worker you already have (session new -d --resume <id>, which creates nothing); if none can serve, ask the operator to prune or to raise the limit. Holdingpruneyourself is not a licence: ask the operator and prune only once approved — an unapproved prune can be undone withrestore, but it is not the expected path. Never retry the same spawn as is. A child's--spawn-depthis at most yours minus one. - Omitted ⇒ none. No
--capsflag means the child gets NOTHING: it is a data-plane-only worker (agentboard within its base set + its own ls) and every control-plane verb answerspermission denied. Name what it needs —--caps spawn,file_read, or--caps allfor everything you may delegate (intersected with your own set and yourdelegate). A worker you expect to spawn, resume or supervise its own children, attach to a PTY, move files, or notify the operator will NOT be able to until you say so — and spawning and resuming are two grants,spawnandresume. Forgot at spawn time?caps set <id> --caps …fixes it on the live task without a restart. - Operator = full set. A task launched directly by the human operator (no
principal task) is the trusted root and holds
all. --scopebounds the targets. Defaultsubtree= yourself and everything you spawned, transitively.none= yourself only.global= every task on the server, the explicit opt-out.ids:<id>[,<id>]= yourself plus exactly those tasks;subtree+ids:<id>= both. Every request naming a task — cancel, attach, file pull/push, git, await-idle, port forwards, and resume — is checked against it, and a task outside your scope answers no such task, the same as one that does not exist. Do not read that as a bug; read it as "not yours".- Scope attenuates like caps. A child's base is clamped to yours
(
none < subtree < global), and every id you name must already be inside your own set at spawn time. An id that is not is an error, not a silent drop. You may name your own id, which is how you hand a child access to yourself — under the defaultdelegate-scope(subtree: your own id and your descendants'); underdescendantsyour own id can be handed down only as a view-only id (vis-ids:). The bit that recipe grants must also be in yourdelegate, or it is dropped. - Visibility is an axis of the scope, not a cap. A scope is written
[<visibility>/]<action>; omitting the visibility half makes it follow the action half.--scope global/subtreesees every task and acts on its own subtree — that is the shape the oldinfo_globalcapability produced. It widens LOOKING only: you can see a task and still be refused when you try to cancel it. The reverse — acting wider than you can see — is allowed, deliberately:--scope none --scope-for exec_view=globalis a worker that can enumerate nothing and look at any task whose id it is handed over the agentboard. Task ids are 128 random bits, so a wide action rank buys no discovery, andwhoami --json'sscope_by_capstates the reach in full either way.board topics,board readandboard subscribersare the one thing that stayed a capability, now namedboard_observe: the board is keyed by topic, which the task hierarchy does not contain, so no task scope can bound it. It is NOT needed to send, to read your own inbox, or to read a group topic; it IS needed to read another task's direct messages (itschat.<id>,chat.operator, atree.<id>the reader is not in) by any agent verb. - Board reach follows the spawn tree. With no bits, a worker publishes to
its own
chat.<id>, yours (its creator's), its own children's,chat.operator, and to anyone who messaged it first (on its ownchat.<id>, or in reply to it — not posters it merely read on a group topic). Messaging a sibling or any other peer it has no thread with, or a free-form topic, needsboard_peer, and the bit is scoped like any other: it opens thechat.<id>of the tasks its scope covers, and free-form topics only when that scope is global. A worker's defaultsubtreescope therefore does NOT reach its siblings — they are yours, not its. Name them:--caps …,board_peer --scope-for board_peer=ids:<sibling>(each id must be inside your own scope, as for any grant), at spawn or later withcaps set— which rewrites the whole scope, so it also needs--scope <base>and any other override the worker should keep. The worker's siblings are your own children, so their ids are inside the defaultdelegate-scope; butboard_peeritself must be in yourdelegate, or it is dropped. A team channel for you and your workers istree.<your-full-task-id>.<suffix>, readable and writable by the whole subtree with no bit. Theharness-cliskill'sreferences/reach.mdhas the full rule. - Putting workers on a topic —
board join/board subscribe. To gather workers on one discussion,harness-cli board join <worker> <topic>makes each a member: subscribed, allowed to publish there with noboard_peer, and replies to its posts stay on the topic.board subscribe <worker> <topic>only subscribes — the shape for a broadcast request whose answers go to each poster privately.board leave/board unsubscribeundo them. Both needboard_memberwith the worker inside that bit's scope (defaultsubtree: your workers), and are bounded so you hand out nothing you lack: never yourself as the target (not_found); a join only to a topic YOU may publish to on your own reach — your lineage'stree.<id>.*, or a free-form topic with a globalboard_peer; a contact does not count (not_publishable); neverchat.*or atree.<X>.*outside the worker's lineage (not_joinable); a subscribe only to a topic the worker could read itself (not_readable). Ontree.<your-full-task-id>.<suffix>your workers can already write; joining them there adds the subscription, the reply default, and — on a topic kept withboard retain— a subscription that survives a server restart. - One capability can be narrowed below the others.
--scope-for CAPS=SCOPE(repeatable, capability lists must not overlap) gives named bits their own target set:--scope-for exec_cowrite,file_write=descendantsis "may drive its workers, may not drive itself".descendantsis the subtree without self. An override never GRANTS a verb — one naming a bit you do not hold sits inert until something grants it.whoami --jsonandls --jsoncarryscope_by_cap, the resolved map, so you never have to work the merge out. - You also see your parent, redacted.
ls/session lsinclude one row for your direct creator so you can tell whether the task driving you is still running / idle. That row is deliberately sparse —repo,prompt,worktree,agentand the assigned runner come back empty. They were stripped, not absent; do not report "my parent has no prompt". Itscapsandcreated_byARE real. One hop only: your grandparent is not listed, and a verb aimed at your parent (session snapshot,transcript ls, …) still answers not-found unless your scope names it. - The operator can change your caps or scope while you run.
harness-cli caps set <id>is operator-only and takes effect on your very next request, with nothing restarted. If a call that worked a minute ago starts answering no such task or permission denied, re-runwhoamibefore assuming a bug — and if the change narrowed you, your open attaches and transfers were closed with it. - Check your own caps with
harness-cli whoami. It prints THIS connection's own principal task id and the exact capability set and scope the server enforces for you, and your delegation bound (delegate=… delegate-scope=…) (--jsonfor the machine-readable form). No cap is required — it is self-introspection, not a peek at another task's record. Use it when unsure whether a denied RPC is a missing cap vs. a real error. - See what a worker could reach before you spawn it:
harness-cli caps reach <your-id>. Per bit you exercise, the tasks you act on (act) and only see (see +N); a child you spawn reaches at most that, per bit. Itsdelegateline is what a spawn by you would actually be allowed: the caps a child can receive (caps=) and the ids you may write into its scope, as action ids and (see +N) as view-only ids — computed as the server checks the spawn.caps reach <worker-id>afterwards shows what the worker holds. Itswider than parent:line readsnot computedfor you: your listing has gaps, and only an operator's comparison is trustworthy. - Try the spawn before you send it:
harness-cli caps what-if <your-id> --spawn --caps … --scope …. It applies the server's spawn rules to your listing and sends nothing: the child (new) with the caps and scope it would actually get — a bit you may not delegate already shows as missing — and per bit which of your ancestors' reach gains it. A spawn the server would refuse prints the refusal it would give (… is outside what you may delegate), so fix the flags before spawning rather than after a denial. The report starts(over your listing only)for you, since your listing has gaps. - See what you handed out with
harness-cli caps audit. One line per capability, strongest first, listing the tasks yourlsshows that hold it and the scope it reaches;--cap spawnlists just that bit's holders. Report a grant that outlived its reason to the operator —caps setis theirs. granter=says who last granted a task's authority. Everylsrow ends its authority withgranter=<source>@<actor> (<age>)—spawn@<creator>for one a task created,operator_caps_set@operatorfor an operator grant,cascade,resume, orunknownfor a task older than the field. A worker holding more than you gave it is usuallyoperator_caps_set: the operator widened it, which is legitimate.@hiddenis an actor you cannot see.
Granular names: spawn, resume_exact, resume, cancel, exec_view, exec_cowrite,
exec_control, exec_resize, exec_run, exec_tap, file_read, file_write,
forward_local, forward_remote, forward_link, forward_tap, notify, prune,
runner_admin, board_observe, board_purge, board_send, board_peer, board_persist, board_member,
record_persist, record_delete, transcript_read, schedule — plus the aliases none / all. harness-cli caps
prints the authoritative list with a line each; this one can fall behind it.
schedule creates, edits, runs and deletes a server-kept cron schedule and
unbinds a task from one (next section).
record_persist keeps a session's PTY record (switches recording on, opens a
session with --record, keeps a record longer) and record_delete removes one
(record rm, record off, a shorter retention); reading a record is
exec_view. transcript_read reads the agents' own transcripts of a task's
working directory (transcript ls / get, below). exec_view does not imply
it: a transcript holds what never reached a screen — the files the agent read,
its subagents, every past run.
spawn creates a task and nothing else. resume re-queues a finished one under
its own id, free to change its prompt, agent, args, caps and scope; it implies
resume_exact, which allows only --exact (above). Neither implies spawn,
nor spawn either of them. A resumed task keeps its recorded caps unless
--caps re-grants them. Opening a session without -d takes its control
seat, so it also needs exec_control — whether the session is new or resumed.
forward_tap reads the PAYLOAD crossing a port forward (forward tap) —
cleartext, so routinely Authorization headers and credentials. Holding a
forward is a different power from reading what goes through it, so
forward_local does not imply it and neither does forward_remote; the byte
COUNTS on forward ls need neither. forward_link puts a network interface
at each end of a forward (forward --ip): a port forward names one target, a
link names none, so every service bound to all addresses on either host becomes
reachable from the other. Neither port-forward bit implies it, and it implies
neither. exec_tap reads the payload crossing an
exec (exec tap) — its stdin as well as its output; exec_run does not imply
it, and the byte counts on exec ls need neither. exec_resize and exec_run sit BESIDE
the three attach caps rather than inside their ranking — resizing is availability and running a command in the
worktree touches no session at all, so neither is implied by being allowed to
type. The three attach caps are ranked and checked with implication:
exec_view reads a session, exec_cowrite also types into one, exec_control
also takes it over from whoever is driving. Grant a worker you only want to
WATCH exec_view; grant one you need to DRIVE exec_cowrite. exec_control
is for taking a terminal away from someone, which is rarely what you want. When you spawn a worker you
intend to keep driving, grant the narrowest set that lets it finish, and widen
only if it hits a capability-denied error.
Recurring runs — harness-cli schedule
A schedule is a server-kept cron entry: at the times its expression names, in a stated zone, the server starts a background run of the schedule's task (the first firing creates the task, every later one resumes it). Use it for work that should start by itself and end by itself, not for a worker you will drive.
harness-cli schedule new --cron '0 9 * * mon-fri' --tz Asia/Tokyo \
--repo /path/to/repo --agent claude --deadline 30m \
--prompt "Triage the new issues and report on chat.<your-short-id>"
harness-cli schedule ls [--json] # needs no bit, only reach
harness-cli schedule show <schedule-id> # definition, history, wait statistics
harness-cli schedule edit --cron '*/30 * * * *' <schedule-id>
harness-cli schedule run <schedule-id> # fire now (history: run_now)
harness-cli schedule rm <schedule-id> # the task stays; a run is not cancellednew,edit,run,rmneed theschedulebit, andedit/run/rmalso need the schedule's task in your scope (while it has none, its creator task).ls/showneed no bit.newtakes--prompt,--deadline,--agentand--repo(or--task Tto bind an existing task, not running in foreground), withsession new --background's run flags andsession new's--caps/--scope/--scope-for/--delegate-*. The stored authority is bounded by yours; an edit recomputes it with the editor as granter, so editing a schedule never leaves it wider than you. Checkwhoamibefore promising to create one.- A schedule verb also needs the power it exercises.
newwithout--taskneedsspawn;new --task Tand an edit that binds T needresumewith T in its scope (resume_exactis not enough);edit/runof an existing schedule needspawnwhile its task is still to be created andresumeover its bound task (an unbound schedule needs neither; an edit that binds a task needs nospawnbutresumeover the old and the new task). A missing bit is a permission denial naming it; T outsideresume's scope istask_not_reachable. Firings check nothing. - The expression is five cron fields in the schedule's zone, or
@hourly/@daily/@weekly/@monthly/@yearly; an interval is a step (*/30 * * * *).@every,?,L,W,#and aTZ=prefix are refused (invalid_cron), as is an expression that matches nothing within five years. Without--tzthe server's zone is used, and a server that cannot name it refuses the create and asks for--tz. - A schedule's own task cannot act on its schedule.
edit,run,rm, a--taskrebind and unbinding it are refused for the bound task whatever it holds, because a scheduled run reads untrusted text (issues, pull requests) and an instruction injected into it must not outlive the run by rewriting the prompt, the times or the binding. Do not read the refusal (self_refused) as a missing bit; the operator or another task changes it. - Do not grant
schedulein a scheduled task's authority (the grant a schedule stores). That refusal compares the caller with the bound task only: a bound task holdingscheduleand eitherspawnorresumeover a task it can bind can still create a NEW schedule, and a child it spawns withscheduleandresumeover its parent can edit the parent's schedule — so an injected instruction could outlive the run. - Every due firing leaves a history entry (
schedule show, last 50):fired,run_now,skipped_busy(the previous run is still queued or running),skipped_no_task,skipped_task_gone,skipped_refused(with the reason),resumed_by,unbound, andpending/lostfor a firing a server crash interrupted. A firing runs at most once, and one missed while the server was down runs once when it comes back. - Taking a scheduled task away needs the bit too. A resume that asks for
--foreground, orsession mode <id> foreground, on a task bound to a schedule needsscheduleas well as what it needs today; it unbinds the task, and its firings areskipped_no_taskuntilschedule edit --task <id>binds one.lsshows the binding asschedule=<id8>. A task the schedule CREATED (its first firing) readsfrom=schedule; a task bound with--taskkeeps the origin it had, and its firings show asresumed_by=schedule.
One-shot sessions & monitoring (session new --oneshot, watch)
session new --oneshot is the fire-and-forget counterpart to session new -d:
the session runs the agent's one-shot (print-mode) argv on your prompt — claude
-p … --output-format stream-json, codex exec --json, the bash profile
bash -c <prompt> — and ends when the process exits; the task's exit code is
the process's. There is no way to step in mid-run (see "Why interactive
sessions over --oneshot" above). Prefer session new -d for anything
collaborative; reach for --oneshot only for genuinely narrow, no-intervention
jobs.
TASK_ID=$(harness-cli session new -d --oneshot --repo /path/to/repo --agent claude \
--prompt "one-line job ... When done, send your answer with: harness-cli agent send --topic chat.<your-short-id> --data '<answer>'")--promptis required;--streamis refused with--oneshot. Without--agent, a runner offering several agents answersambiguous_runner(exit 3) instead of picking one for you — see "A spawn can answerambiguous_runner" above.A foreground
--oneshotdoes not queue. When every runner that could take it is full, the open is refusedrunner_busy. To wait in the queue for a free runner, open it in background — the rules of "Unattended work —--background" apply (--deadlineand--agentrequired):TASK_ID=$(harness-cli session new --background --oneshot --repo /path/to/repo --agent claude \ --deadline 30m --turn-end off --prompt "...")--turn-end offleaves the end to the process exit or the deadline. A print-mode agent prints nothing while a long tool call runs, so the defaultanycan end the run on its quiet leg before the answer arrives.- A resume reuses nothing: pass
--oneshotagain with--resume, or the resumed session runs the interactive template.--resume --exactis the exception: it reruns the last run as it was,--oneshotand prompt included. - The child has no PTY by default: its stdin is
/dev/null, so a command that reads stdin ends at once instead of waiting, and its output reaches the session byte for byte.--ptyruns it in a PTY instead, for a program that needs a terminal; it then getsPAGER,GIT_PAGERandSYSTEMD_PAGERset tocat—git logorjournalctlwould otherwise wait for a key — and a command that reads stdin waits forever: give it< /dev/null.lsmarks such a runinteractive+oneshot+pty. The converse,session new -d --no-pty, is an interactive session on pipes (interactive+pipe): what yousession sendreaches its stdin, and nothing echoes it.
Getting a one-shot's answer back
The session shows the agent's raw output — for claude and codex the JSON event stream, not converted — and ends with the process. There is no task log: the server keeps nothing of a one-shot's output unless it was recorded. So decide where the answer goes before you open it:
- Have the worker reply on the agentboard — the
agent sendline in the prompt above. Its creator'schat.<id>is in a worker's default board reach, so this needs no capability, and the reply wakes you through the inbox hook like any peer's. This is the convention; use it first. The worker gets exactly one turn — it can send, but no message can wake it into a second one — so ask everything in the prompt. - While it runs:
harness-cli session snapshot <id>(needsexec_view) prints the screen, i.e. the JSON lines as emitted. - After it ended: the agent's transcript holds the whole run, answer
included —
transcript ls <id>/transcript get <id> <SESSION> <FILE>(needstranscript_read, and the runner online; see "Reading a worker's conversation" below). Abashone-shot has no transcript: open it with--record(needsrecord_persist) and read it afterwards withharness-cli record get <id>(needsexec_view).
ls shows the status and, once it ended, the exit code (exit_code in ls
--json). For a worker that cannot reply (--agent bash),
session await-idle --topic chat.<your-short-id> <id> fires once when the
session ends ("status":"session_stopped") or goes quiet, whichever comes
first; read ls after the fire.
Monitoring and ending tasks
harness-cli watch # stream status events (queued, assigned, started, ended, …) for the tasks your `ls` shows; runners only if it lists them
harness-cli cancel <TASK_ID> # cancel a queued/running task
harness-cli prune [--before DUR] [TASK_ID ...] # ask the server to forget terminal taskslogs is retired with the task log (it prints a one-line pointer to the verbs
above). session attach is a human/PTY tool, not for you — see "Listing and
killing your sessions" above.
cancel <id> and session kill <id> (its alias) route a CancelTask to the
assigned runner, which
hangs up the agent (SIGHUP, then SIGTERM, then SIGKILL within about 2 s) so it
can stop the tool processes it started — a session with no PTY, which has no
terminal to hang up, gets SIGTERM to its process group and SIGKILL 2 s later,
as a stream session does; what an agent deliberately detached into
a session of its own (setsid) is left running. Cancel is
idempotent and skips already-terminal tasks. (prune / prune-local are
post-hoc cleanup of terminal tasks — server-side forget and local worktree
removal respectively — and are kind-agnostic.)
Moving files in / out of a worker's worktree
harness-cli file reads and writes files inside a task's worktree — the
per-task harness/<task-id> checkout the runner created for it, not arbitrary
host paths. Use it to seed a worker you spawned with input files, or to collect
its artifacts. WORKTREE_REL_* paths are POSIX and relative to the worktree
root.
# List one directory (default: worktree root).
harness-cli file ls <TASK_ID> [WORKTREE_REL_DIR]
# Copy a local file INTO the worktree (-r: directory tree).
# Default is O_EXCL — refuses to overwrite; -f permits replacement.
harness-cli file push [-r] [-f] <TASK_ID> <LOCAL_SRC> <WORKTREE_REL_DST>
# Copy a worktree file OUT to a local path (-r: directory tree).
# Default refuses to overwrite the local target; -f permits replacement.
harness-cli file pull [-r] [-f] <TASK_ID> <WORKTREE_REL_SRC> <LOCAL_DST>
# Remove a file. -r targets a directory (dir_delete); -r -f removes a
# non-empty directory (RemoveAll). Without -r a directory is refused.
harness-cli file delete [-r] [-f] <TASK_ID> <WORKTREE_REL_PATH><TASK_ID> is the 32-hex id from session new (the same id behind
the chat.<short-id> topic). Typical seed → run → collect flow with a worker:
TASK_ID=$(harness-cli session new -d --repo /path/to/repo)
harness-cli file push "$TASK_ID" ./spec.md docs/spec.md # hand it inputs
# ... drive it via the agentboard; let it work ...
harness-cli file pull "$TASK_ID" out/report.md ./report.md # collect outputsPrefer this over having the worker paste large files through agentboard
messages: file streams the bytes directly and keeps the agentboard for
coordination, not bulk transfer.
Running a command in a worker's worktree — harness-cli exec
harness-cli exec runs ONE command in a task's worktree as its own
process. It needs exec_run.
This is the verb for "build it and tell me if it passes". It is not
session exec, and the difference decides which one you want:
exec <id> -- <cmd> | session exec <id> <cmd> | |
| where it runs | its own process in the worktree | typed into the session's FOREGROUND SHELL |
| needs a POSIX shell in the foreground | no | yes — times out against a TUI/REPL/claude |
| stdout vs stderr | separate | merged onto the one PTY stream |
| exit code | the command's own, and yours | parsed out of the combined output |
| visible to whoever is watching that session | no | yes — it lands in their scrollback |
| capability | exec_run | exec_cowrite |
# Words after -- are the argv, verbatim. Nothing re-splits them, so an
# argument containing a space stays one argument.
harness-cli exec <TASK_ID> -- make test
harness-cli exec <TASK_ID> -- git status
harness-cli exec <TASK_ID> -- sh -c 'go build ./... 2>&1 | head -40'
# Redirect the two streams independently — the reason this verb exists.
harness-cli exec <TASK_ID> -- make test >out.txt 2>err.txt
# What is running right now, and how to stop one.
harness-cli exec ls [-task <TASK_ID>] [--json]
harness-cli exec kill <EXEC_ID>
# What is crossing one, live: stdin, stdout, stderr. Needs exec_tap.
harness-cli exec tap <EXEC_ID> [--chan stdin|stdout|stderr] [--text|--raw|--json]exec ls prints a second line per exec — io=pipe|pty stdin=… stdout=…
stderr=… last=… taps=N — so whether bytes are moving at all is visible without
a tap. A tap sees only what crosses after it opens, and taps=N tells everyone
it is open.
io=pty is an exec running under a terminal — exec -t, or ssh -t through
the gateway. Its stdout and stderr are one stream, so its stderr=0 says
nothing about errors. -t needs a real terminal on stdin, which you do not
have; it is the operator's.
The exit code is the command's own, so if harness-cli exec "$TASK_ID" -- make
test; then … works. A command that never started — missing binary, no
worktree, killed — exits 125 with the reason on stderr; 125 rather than 127
because there is no shell here to have that convention.
The target is the worktree, not the task's status. A worker that ended with
uncommitted work keeps its tree, so git status and make test still run in
it, which is exactly when you want them. A worker that ended clean had its tree
removed and is refused.
It is synchronous and dies with you. There is no detached form — that is
what spawning a task is for. Do not use it to babysit something long: your turn
ends, the exec is killed. Every client can see it in exec ls while it runs,
and each task's row carries execs=N.
Reading a worker's diff — harness-cli git
harness-cli git reads a task's git state without attaching to its shell, so
you can review what a worker changed while it is still running. It is
read-only: there is no commit, add, checkout or stash. It needs file_read.
# The task's commits.
harness-cli git log <TASK_ID> [--max N] [-- <PATH>]
# The diff. Revisions are counted the way git counts them:
# no revision -> the unstaged change
# one -> that revision against the working tree
# two -> commit against commit
# --staged puts the index on the right-hand side instead.
harness-cli git diff <TASK_ID> [--staged] [<BASE>] [<TARGET>] [-- <PATH>]
# One commit and its diff.
harness-cli git show <TASK_ID> [<REV>] [-- <PATH>]
# Uncommitted and untracked paths, as `git status --porcelain`.
harness-cli git status <TASK_ID> [-- <PATH>]Two things worth knowing before you read the output:
A worker that has committed shows nothing under a plain diff. That is
git, not a gap. Read log first, then name a baseline:
harness-cli git log "$TASK_ID" # find where it started
harness-cli git diff "$TASK_ID" <that-sha> # everything since, committed or notUntracked files appear in no diff. status is where a brand-new file
shows up, as a ?? entry; read its contents with file pull.
While the task is live the query runs in its worktree, so uncommitted and
untracked state is visible. After it ends the worktree is gone and the query
runs against the retained harness/<task-id> branch — committed work only,
and status is then empty because there is no working tree left to be dirty.
HEAD still means the task's own tip in that case, not the repository's
checkout. The runner that ran the task must still be online.
One file, whole — git file <TASK_ID>
A diff shows the lines that changed; this shows the file they changed.
harness-cli git file <TASK_ID> <PATH> # the file on disk
harness-cli git file <TASK_ID> --staged <PATH> # the staged blob
harness-cli git file <TASK_ID> --rev <REV> <PATH> # the blob at a revisionThe path is relative to whichever repository the query is rooted in, so
--subrepo composes and a path lifted straight out of a diff header works
unchanged — after -- as well as as a positional.
In the TUI's git modal, o toggles between the diff and the whole file
(scroll with space/f and b, or d/u for half a page — the arrow keys drive the
row picker); in the
WebUI, a file header inside a diff is clickable. Either way the side matches the
diff you were reading: the working tree for a worktree diff, the staged blob for
a staged one, that commit for a commit-to-commit diff or a shown commit.
Repositories inside the repository
A plain nested repo — a directory with its own .git that the outer repo
only ever sees as one ?? nested/ entry — is invisible to every query above.
--untracked-files=all does not descend into one, and it appears in no diff
because it is untracked. Run the query inside it instead:
harness-cli git subrepos <TASK_ID> # what is nested in there
harness-cli git log <TASK_ID> --subrepo pkg/inner # its own history
harness-cli git diff <TASK_ID> --subrepo pkg/inner # its own changes--subrepo works on log, diff, show and status, and composes with
-- <PATH>: --subrepo chooses WHICH repository, -- <PATH> filters within
it. A path that is not a repository root is refused rather than silently
answering about the enclosing one.
Submodules show up in subrepos too, so the same route gives you a
submodule's full history. For a single combined diff instead, --submodule
on diff / show inlines the submodule's own file-level changes under its
gitlink entry. It is off by default because that output is no longer an
applyable patch.
A nested repo lives inside the task's worktree, so once the worktree is gone
--subrepo answers no_source — the retained harness/<task-id> branch is
in the outer repository and says nothing about it.
Reading a worker's conversation — harness-cli transcript
The diff shows what a worker changed; its agent's transcript shows how it got
there — its tool calls and their results, its subagents, every earlier run —
as the agent stored it on the runner host. The runner reads it on demand, so
the task's runner must be online (otherwise runner_offline); nothing is
copied to the server. It needs transcript_read with the task in that bit's
scope.
harness-cli transcript ls "$TASK_ID" # agent, session, created/updated, size
harness-cli transcript ls "$TASK_ID" <SESSION> # the files that session is made of
harness-cli transcript get "$TASK_ID" <SESSION> <FILE> > f.jsonl # one file, as stored
harness-cli transcript get -o s.tar "$TASK_ID" <SESSION> # the whole session, as a tarlslists the sessions every agent recorded in the task's working directory, so a worker resumed under another agent lists both. To find one run's session, read thecreatedtimes against when the run started.- A row marked
sharedwas recorded in the repo itself — a--no-worktreetask, where other tasks' and the operator's sessions also land. It is listed and fetched only if you also holdexec_runon the task. - The bytes are not rendered: JSONL for claude, codex and pi, the JSON
opencode exportwrites (its size readsunknownuntil it is produced), agy's SQLite.db. A<FILE>must be a namels <SESSION>printed. - A store the runner could not read is named on a
note:line, not passed off as an empty list — for agy, the runner host needssqlite3on its PATH. -o FILEis created only once the first byte arrives, so a refused fetch leaves no empty file behind.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

