How Work Happens in Agent Studio
This is the work model: how an intention becomes a task, how a task moves through a fixed pipeline, how the result is proven with evidence, and how work that arrives from outside the runner is reconciled honestly. It is a mechanical story, not a marketing one.
Work moves through application-owned lanes from 0-backlog to 7-archive. Auto-review reissues, accepts or escalates; a human always confirms completion. Every task carries a git-backed evidence record, out-of-band results are a first-class ingest, and orchestrator chats are context-bound sessions.
The Task Pipeline
Work moves through a fixed, application-owned lane sequence. A task is a folder on disk, and the board is those same lanes rendered. Agents never move themselves between lanes — the platform owns every transition. The live CLI process state, not the lane, tells you whether something is running right now.
The board turns agent work into a reviewable flow: Backlog, Active, and Done & Decide with run and review state on every card.
Application owns transitions
Selecting the next task, moving lanes and starting or stopping runs are platform actions, never agent actions.
One worktree per run
Every coding run, including resume and reissue, is worktree-isolated so the main checkout stays untouched.
Lane is not liveness
A 3-progress card may have no live process; the CLI run state is the truth about what is executing now.
- 0-backlog: untriaged work. New and auto-created tasks land here for a human to shape before anything runs.
- 1-preparation: intake. The task is scoped, its predicted file scope and exclusivity are assessed, and the prompt contract is injected before pickup.
- 2-ready: queued for execution. A ready card can still be held back while its declared waits-on dependencies are unfulfilled.
- 3-progress: a coding-agent CLI runs in its own git worktree. A card can sit here without a live process after a stop, crash or restart, so the CLI state is the real signal.
- 4-auto-review: the automated review phase, labelled Post Processing in the UI. Only a successful run reaches it, and the orchestrator decides what happens next.
- 5-human-review: the human gets the final say. Escalated and parked cards collect here, including the 5e-escalated sub-lane.
- 6-completed: accepted work. The user always confirms this move, and the platform pushes completed work per project settings.
- 7-archive: closed history that stays queryable through the API.
Run protocol
Claim. Run. Deliver.
One ordered attempt, from fenced pickup to reviewable evidence.- 01
run/claimedClaim
The Runner asks for ready work. The Task Server grants a time-bound lease with a fencing token.
- from
- agent-runner
- owns
- task server
- 02
run/startedRun
The selected coding-agent CLI works inside its task branch and isolated worktree.
- scope
- task/<id>
- proof
- checks + diff
- 03
run/deliveredDeliver
The Runner returns the verdict and durable evidence. The Task Server routes the result to review.
- payload
- status + evidence
- next
- review decision
task WEB-12lease f_18verdict → evidence → reviewAuto-Review and Reissue Gates
Only successful CLI runs move from 3-progress to 4-auto-review. There the orchestrator runs a review-decision pass over the result and the selected review aspects, then makes one of three calls instead of silently accepting the run.
Review Loop
Reissue
Bounded automatic rework with feedback when the result misses the bar.
Accept-as-done
Clean runs move up to human review, not straight to completed.
Escalate
Inconclusive or blocked runs are parked for a human with a recorded category.
- Reissue: send the task back to 3-progress with concrete feedback when the work or its evidence is not good enough yet.
- Accept-as-done: forward to 5-human-review. The orchestrator never moves a task straight from auto-review to completed.
- Escalate: also forward to 5-human-review, with a recorded reason when the run was inconclusive, environmental or blocked.
- The evidence gate reissues otherwise-good work when required proof such as tests or screenshots is missing, so "it says it is done" is not enough.
- The reissue budget is counted per attempt chain, not per lifetime, so a human reopening a card starts a fresh budget instead of instantly re-escalating.
- A run that committed real work but exited without a clean sentinel (committed-partial) is routed to review for a human, never auto-reissued into a loop.
Human Review Has the Final Say
The move from 5-human-review to 6-completed is always a human confirmation. Auto-review can prepare a decision, but a person accepts, rejects, reissues or splits the result. That is where product taste and architecture judgement stay.
Quality-gate task detail from a pinned DEMO-9 task.
- Accepting is the only path into 6-completed. Integration is a separate fact: a finished run may already be on develop while its evidence is still under review.
- The reviewer reads the diff, the protocol and the recorded evidence instead of reconstructing the run from terminal scrollback.
- Escalated cards arrive with a category — inconclusive-with-results, environmental, cli-launch-failed and similar — so the reviewer knows why the system stopped.
- When results are present but no clean verdict exists, the card states that partial work is in results/ and asks the reviewer to inspect before deciding.
- A rejected or incomplete result becomes a reissue or a precise follow-up task, not a lost run.
Release the Stream, Freeze Stable Points
Agent Studio uses the transparent watering-can model: finished task revisions join develop early, then a manual release promotes that coherent Git graph to main. The release view says exactly what comes along — including work still in review — so one developer can move a green integration stream without staging release theatre. Main keeps moving; stability begins only when a checked main SHA receives an explicit stable tag.
- Integration and acceptance are separate facts: a card can already be on develop while its evidence is still in Auto Review, Human Review or Escalated.
- Before confirmation, the release dialog recalculates the exact Git range and groups accepted, still-in-review, escalated and unattributed work without changing any card lane.
- In practice, the operator loop promotes develop to main several times a day when the gates are green; main is the continuous released line, not a claim that every revision is a stable version.
- A stable tag freezes one exact main SHA together with its checks, evidence, actor and rollback predecessor.
- Merge-only-after-acceptance is deliberately not recommended here: it would turn human review into an integration queue, leave dependent work on stale bases and reveal coupling later.
Release the stream. Freeze what is stable.
The release step promotes one coherent Git graph and makes its review state visible. A stable tag is a later, deliberate decision.
- 01Task cards
task/*Bounded work carries its diff, checks and review evidence.
- 02Integration stream
developFinished run revisions join one shared graph, even while evidence is still in review.
- 03Release merge
develop → mainThe dialog shows accepted, unreviewed, escalated and unattributed work before confirmation.
- 04Released line
mainGreen promotions keep the released line moving; main alone is not a stable claim.
- 05Stable freeze
stable/<date>A checked main SHA becomes a named freeze point with durable evidence.
The Evidence Model
Agent output does not vanish into a transcript. Every task carries a git-backed evidence record so a reviewer, and any future agent, can inspect what happened and why it was accepted.
The evidence record of one task: its task branch, the single commit, the two changed files, and the develop and main promotions still pending.
Git-backed
Diffs, results and snapshots are committed so evidence survives beyond one machine.
Visual proof
Source-labelled screenshots sit with the task and catch UI drift.
Readable protocol
status.md, summaries and the timeline explain the run without scrollback.
- Git-backed results: the run is committed on its task/<id> branch and the workspace snapshot, including the results/ folder, is committed, so deliverables are durable rather than only local.
- Screenshots: visual proof lives under results/, labelled by source (real backend versus mocked) and indexed as review evidence beside the implementation.
- Summaries: status.md is the generated review protocol with a single Result line, a small model writes the run summary, and the unified timeline.jsonl ledger records every pre, core and post step.
- The protocol view renders a verdict chain — run, gate, review aspects, lane decision — so a reviewer can see why the head state is what it is.
- The worktree safety invariant means a run can end with work uncommitted: preserving it on the task branch is the platform’s job, not the agent’s.
Work That Arrives From Outside the Runner
Not every task is finished by a local runner run. An operator can do the work by hand or in the orchestrator chat, an external agent or a remote host can produce the result, or a run can die with its deliverables already on disk. Agent Studio treats that as a first-class ingest, not a manual folder edit, so the card’s story stays honest.
Activity across projects: a queryable ledger of signals, decisions, and actions with per-project and event-class filters.
First-class ingest
External results get provenance, a summary and a timeline row, not a silent lane drag.
Canonical narrative
results/deliverables.md records what was delivered and where, with a provenance block.
Honest card
The badge and external actor tell the board the work came from outside the runner.
- A single reconciliation call, POST /api/tasks/{id}/external-completion, takes a required summary plus optional deliverables, a source and a target lane that defaults to 5-human-review.
- It writes results/deliverables.md as the canonical narrative, overwrites the stale status.md, records provenance on task.json and terminalizes the lifecycle so the card stops looking stuck.
- The completion is attributed to an external actor with its own timeline row and filter chip, distinct from agent, orchestrator and system activity.
- An "extern erledigt" badge marks the card so work done outside the runner reads as intentionally finished, not abandoned.
- The lane move is the last step, after the evidence is reconciled. Moving the card is a consequence of the ingest, never a substitute for it.
Execution Can Run Elsewhere
Where a task runs is separate from where it is managed. The whole pipeline — CLI runs, per-task worktrees, verification and quota probes — has been proven end to end on a plain Linux host, and multi-machine execution is designed around one authoritative Task Server with fenced run leases.
The board turns agent work into a reviewable flow: Backlog, Active, and Done & Decide with run and review state on every card.
- The full path, security model and honest constraints live in the Remote Execution section on the Product page, which this page links to rather than repeating.
- Each run stays worktree-isolated, so parallel slots and remote hosts never share a working tree.
- Multi-system execution uses transactional run leases with fencing tokens, so a woken-up stale runner cannot overwrite a task another runner has taken over.
- Task code travels through origin, not the task store: a runner fetches the recorded refs and rebuilds its worktree, so a crash can hand off from the pushed task/<id> branch.
Context-Bound Orchestrator Chats
The orchestrator is not one global history of everything that ever happened. Navigating to a task gives you an orchestrator that carries that task’s context and keeps its own persistent history; the global and per-project views are just other contexts. Many such sessions run in parallel and are switchable at a glance.
Orchestrator and Task Chat
One session per place
Global, project and task contexts each keep their own persistent chat history.
Park and resume
Sessions park when idle and resume through the CLI’s native session id, with no full replay.
Bounded processes
A small active-process cap keeps thirty parked chats from becoming thirty running CLIs.
- A context key is canonical — global, project:<PROJ-ID> or task:<PROJ-ID>/<TASK-KEY> — and each key has exactly one session with append-only history.
- Context is automatic: it derives from where you are, so task-context sessions archive together with their task and its git-backed evidence trail.
- A session, meaning history plus a CLI resume token, is cheap and persistent; an active process, meaning a running CLI turn, is expensive and exists only while a turn is processed.
- An active-process cap, defaulting to a few slots, means extra turn requests queue visibly instead of forking dozens of CLIs. Thirty parked sessions cost only disk.
- Per-context token usage is shown per session, so the switcher can surface the cost of each conversation.