agentleFS
on-keydayon-keyday/agent-harness/.agents/skills/supervising-workers/SKILL.md

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.

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
  1. Distinctive:

    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 …

    line 15
  2. Very specific:

    When you need to delegate work to another agent that you intend to keep talking to, prefer harness-cli session new -d (an interactive …

    line 21
  3. Very specific:

    If a worker session gets canceled (failed, killed, you want a clean restart) and you intend to start another one playing the same role, …

    line 122
  4. Very specific:

    Use the flag, not --agent-arg --continue.

    line 154
  5. Very specific:

    Keep the -d. Opening a session WITHOUT -d hands you its control seat, which needs exec_control over it.

    line 239
  6. Very specific:

    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 …

    line 244
  7. Very specific:

    default (no flag): LONG-POLLS — blocks until the fire, prints {"status":"fired",...} (exit 3 = session ended first).

    line 291
  8. Very specific:

    Every fire, whatever the signal, reports fired_by (the leg that fired) and the lifecycle, program_state and program_kind the session showed …

    line 316
  9. Very specific:

    After verification / probe work, prune the throwaway tasks you spawned so ls stays readable.

    line 456
  10. Very specific:

    --scope bounds the targets: Default subtree = yourself and everything you spawned, transitively.

    line 513
  11. Very specific:

    granter= says who last granted a task's authority: Every ls row ends its authority with granter=<source>@<actor> (<age>) — …

    line 630
  12. Very specific:

    instead of picking one for you — see "A spawn can answer ambiguous_runner" above.

    line 764
  13. Very specific:

    A foreground --oneshot does not queue: When every runner that could take it is full, the open is refused runner_busy.

    line 766
  14. Very specific:

    Prefer this over having the worker paste large files through agentboard messages: file streams the bytes directly and keeps the agentboard …

    line 878

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  • --oneshot runs the agent's print mode (claude -p, codex exec) 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 -d keeps the worker alive between turns, so you can drive it iteratively via agent messages and the user can also intervene at any time (attach with session attach <task-id>, send corrections via the agentboard, etc.).
  • --oneshot still 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 150

A -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> (or session send --resize 40x150 <id> <text> to size and drive in one call). Needs exec_resize on top of exec_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 to exec_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-conversation

Use 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:

LayerFlagWhat it restores
harness task--resume <id>task id, chat topic, worktree branch
agent conversation--resume-conversationthe 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 --agent on a new task. --background implies -d. A profile with no prompt slot in its template (the bash preset) cannot take one: the task ends Failed with prompt_unsupported.
  • What ends it — the first of: the deadline; the end of a turn (--turn-end any|lifecycle|program|quiet|off, default any); the agent waiting on a human for longer than --blocked (default 5m); --queue-timeout while it is still queued; the agent exiting. The end is a cancel, so the status usually reads Succeeded; read the reason in ls: run=bg end=turn_done_program, end=deadline, end=blocked_timeout, … While it runs the row shows run=bg deadline=<time left> until=<clock time>, and while queued wait=all_busy (runners that could take it are full) or wait=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_quiet after the quiet threshold (5m) although it did nothing — the dialog's draw is its only output — and that repeats on every resume. A turn_done_quiet on 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 --prompt and --deadline again.
  • Switch a running session with harness-cli session mode <id> foreground (it then runs until someone ends it) or session mode --deadline 1h <id> background. Either direction needs cancel over 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 below

Busy/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 ls includes last_output_at (unix nanos; 0 = no live session output) and output_idle_ms (server-clock idle age; only meaningful when last_output_at > 0), plus an activity string (busy / idle:Xs) when output has been seen. The top-level ls renders the same as an act=busy / act=idle:Xs badge, and ls --json carries the identical activity / output_idle_ms / last_output_at fields. Every row, of any task kind, also carries the worker's self-reported progress line, progress_at (unix nanos, server clock; 0 = never written) and progress_age_ms — an empty progress with a non-zero progress_at means the line was CLEARED (by the worker or a --clear --task), not that it was never set — plus the live window title; read the title only when live_terminal is 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 N to 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 as agent wait).
    • --topic T: replies armed immediately, with the watcher_id that session await-idle kill takes; 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 own chat.<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: replies armed immediately; on fire the operator gets a notification. For "tell the human when it's done" (they may be away).

--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, an agent=claude without +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> in ls.
  • 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 is global, 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, cancel it first (that needs cancel over it), then prune.
  • After verification / probe work, prune the throwaway tasks you spawned so ls stays 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 prune

Capabilities 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) and delegate-scope (the most scope you may give it) are the operator's to set; the default is delegate=none delegate-scope=subtree, so every child you spawn holds no caps whatever --caps says. Read harness-cli whoami before 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 with caps set <you> --delegate-caps … / --delegate-scope …, so ask, do not retry. A child's own bound (--delegate-caps / --delegate-scope on the spawn) is clamped to yours.
  • Spawn limits bound how many tasks you may create. whoami prints spawn-depth=… max-descendants=… descendants=… room=…; room is 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 a spawn_limit refusal, 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. Holding prune yourself is not a licence: ask the operator and prune only once approved — an unapproved prune can be undone with restore, but it is not the expected path. Never retry the same spawn as is. A child's --spawn-depth is at most yours minus one.
  • Omitted ⇒ none. No --caps flag 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 answers permission denied. Name what it needs — --caps spawn,file_read, or --caps all for everything you may delegate (intersected with your own set and your delegate). 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, spawn and resume. 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.
  • --scope bounds the targets. Default subtree = 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 default delegate-scope (subtree: your own id and your descendants'); under descendants your own id can be handed down only as a view-only id (vis-ids:). The bit that recipe grants must also be in your delegate, 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/subtree sees every task and acts on its own subtree — that is the shape the old info_global capability 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=global is 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, and whoami --json's scope_by_cap states the reach in full either way. board topics, board read and board subscribers are the one thing that stayed a capability, now named board_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 (its chat.<id>, chat.operator, a tree.<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 own chat.<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, needs board_peer, and the bit is scoped like any other: it opens the chat.<id> of the tasks its scope covers, and free-form topics only when that scope is global. A worker's default subtree scope 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 with caps 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 default delegate-scope; but board_peer itself must be in your delegate, or it is dropped. A team channel for you and your workers is tree.<your-full-task-id>.<suffix>, readable and writable by the whole subtree with no bit. The harness-cli skill's references/reach.md has 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 no board_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 unsubscribe undo them. Both need board_member with the worker inside that bit's scope (default subtree: 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's tree.<id>.*, or a free-form topic with a global board_peer; a contact does not count (not_publishable); never chat.* or a tree.<X>.* outside the worker's lineage (not_joinable); a subscribe only to a topic the worker could read itself (not_readable). On tree.<your-full-task-id>.<suffix> your workers can already write; joining them there adds the subscription, the reply default, and — on a topic kept with board 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=descendants is "may drive its workers, may not drive itself". descendants is 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 --json and ls --json carry scope_by_cap, the resolved map, so you never have to work the merge out.
  • You also see your parent, redacted. ls / session ls include 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, agent and the assigned runner come back empty. They were stripped, not absent; do not report "my parent has no prompt". Its caps and created_by ARE 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-run whoami before 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=…) (--json for 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. Its delegate line 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. Its wider than parent: line reads not computed for 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 your ls shows that hold it and the scope it reaches; --cap spawn lists just that bit's holders. Report a grant that outlived its reason to the operator — caps set is theirs.
  • granter= says who last granted a task's authority. Every ls row ends its authority with granter=<source>@<actor> (<age>) — spawn@<creator> for one a task created, operator_caps_set@operator for an operator grant, cascade, resume, or unknown for a task older than the field. A worker holding more than you gave it is usually operator_caps_set: the operator widened it, which is legitimate. @hidden is 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 cancelled
  • new, edit, run, rm need the schedule bit, and edit / run / rm also need the schedule's task in your scope (while it has none, its creator task). ls / show need no bit. new takes --prompt, --deadline, --agent and --repo (or --task T to bind an existing task, not running in foreground), with session new --background's run flags and session 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. Check whoami before promising to create one.
  • A schedule verb also needs the power it exercises. new without --task needs spawn; new --task T and an edit that binds T need resume with T in its scope (resume_exact is not enough); edit / run of an existing schedule need spawn while its task is still to be created and resume over its bound task (an unbound schedule needs neither; an edit that binds a task needs no spawn but resume over the old and the new task). A missing bit is a permission denial naming it; T outside resume's scope is task_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 a TZ= prefix are refused (invalid_cron), as is an expression that matches nothing within five years. Without --tz the 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 --task rebind 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 schedule in a scheduled task's authority (the grant a schedule stores). That refusal compares the caller with the bound task only: a bound task holding schedule and either spawn or resume over a task it can bind can still create a NEW schedule, and a child it spawns with schedule and resume over 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, and pending / lost for 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, or session mode <id> foreground, on a task bound to a schedule needs schedule as well as what it needs today; it unbinds the task, and its firings are skipped_no_task until schedule edit --task <id> binds one. ls shows the binding as schedule=<id8>. A task the schedule CREATED (its first firing) reads from=schedule; a task bound with --task keeps the origin it had, and its firings show as resumed_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>'")
  • --prompt is required; --stream is refused with --oneshot. Without --agent, a runner offering several agents answers ambiguous_runner (exit 3) instead of picking one for you — see "A spawn can answer ambiguous_runner" above.
  • A foreground --oneshot does not queue. When every runner that could take it is full, the open is refused runner_busy. To wait in the queue for a free runner, open it in background — the rules of "Unattended work — --background" apply (--deadline and --agent required):

    TASK_ID=$(harness-cli session new --background --oneshot --repo /path/to/repo --agent claude \
      --deadline 30m --turn-end off --prompt "...")

    --turn-end off leaves the end to the process exit or the deadline. A print-mode agent prints nothing while a long tool call runs, so the default any can end the run on its quiet leg before the answer arrives.

  • A resume reuses nothing: pass --oneshot again with --resume, or the resumed session runs the interactive template. --resume --exact is the exception: it reruns the last run as it was, --oneshot and 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. --pty runs it in a PTY instead, for a program that needs a terminal; it then gets PAGER, GIT_PAGER and SYSTEMD_PAGER set to cat — git log or journalctl would otherwise wait for a key — and a command that reads stdin waits forever: give it < /dev/null. ls marks such a run interactive+oneshot+pty. The converse, session new -d --no-pty, is an interactive session on pipes (interactive+pipe): what you session send reaches 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:

  1. Have the worker reply on the agentboard — the agent send line in the prompt above. Its creator's chat.<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.
  2. While it runs: harness-cli session snapshot <id> (needs exec_view) prints the screen, i.e. the JSON lines as emitted.
  3. After it ended: the agent's transcript holds the whole run, answer included — transcript ls <id> / transcript get <id> <SESSION> <FILE> (needs transcript_read, and the runner online; see "Reading a worker's conversation" below). A bash one-shot has no transcript: open it with --record (needs record_persist) and read it afterwards with harness-cli record get <id> (needs exec_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 tasks

logs 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 outputs

Prefer 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 runsits own process in the worktreetyped into the session's FOREGROUND SHELL
needs a POSIX shell in the foregroundnoyes — times out against a TUI/REPL/claude
stdout vs stderrseparatemerged onto the one PTY stream
exit codethe command's own, and yoursparsed out of the combined output
visible to whoever is watching that sessionnoyes — it lands in their scrollback
capabilityexec_runexec_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 not

Untracked 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 revision

The 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 tar
  • ls lists 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 the created times against when the run started.
  • A row marked shared was recorded in the repo itself — a --no-worktree task, where other tasks' and the operator's sessions also land. It is listed and fetched only if you also hold exec_run on the task.
  • The bytes are not rendered: JSONL for claude, codex and pi, the JSON opencode export writes (its size reads unknown until it is produced), agy's SQLite .db. A <FILE> must be a name ls <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 needs sqlite3 on its PATH.
  • -o FILE is created only once the first byte arrives, so a refused fetch leaves no empty file behind.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.