Pi Web UI Internal API Orchestration

Pi Web UI is a browser interface and backend sitting in front of several agent runtimes. The part that matters here is that it exposes a local-only Internal API over a Unix socket, which turns it into an orchestration control plane you can drive from anywhere on the machine — a different repo, a terminal, a script, a voice assistant — without being inside the web UI at all. Sessions you create land in the same registry the browser uses, so the operator can open them later.

When to use

Also: score or classify batch items on a model, hand a job to another model, start something and check back later, transfer context between sessions, adopt a session as a child, automate Pi Web UI without the browser, and manage children as a parent orchestrator (Unix-socket orchestration, session fan-out, runtime comparison, watch-wake).

Which skill do you want?

The two Pi Web UI skills split on one question: are you using Pi Web UI, or testing it?

That distinction decides the safety posture, so get it right before your first call. Using production here is correct and expected — these sessions are meant to be visible in the operator's Web UI. What is never acceptable is validating a code change against production, or stopping, restarting, redeploying, or reconfiguring the service that hosts your orchestration on your own initiative — the one exception is a programme whose operator authorised a restart, run by the parent under the protocol in references/orchestrator-governance.md. If the task is "does my change work?", stop and read the live-validation docs.

How to read this skill

This is a reference, not a tutorial — read only what the current job needs, not everything. The usual path: Connect → Golden rule → Choosing the route once, then straight to the numbered step you're on.

This file holds the workflow and the rules that keep you out of trouble. Tier 1 — the only must-read: references/parent-card.md (one page: the rules that bit, copy-paste sequences per harness, on-wake triage, routing). Read it before you dispatch anything and again after every compaction. Also read references/routing.md before choosing a model, and mandate the agent-os-child skill in every child prompt (§3; you do not follow it, you mandate it). Everything else is reference: open a file only when the card or a numbered step points there.

Where things are in this file:

Contract version. Every feature note below names the Internal API contract version that introduced it. An additive minor release keeps existing shapes; if /capabilities reports a different minor than your client's snapshot expects, read the contract's exception table first — pi-orch also warns SNAPSHOT_STALE.

Fields and endpoints here are the working subset; the pi-web-ui repo's docs/INTERNAL-API.md and docs/INTERNAL-API-CONTRACT.md are the authoritative full reference — open them when a shape below doesn't answer your question.

Connect from anywhere

Preferred: the pi-orch client (public: https://github.com/valtterimelkko/pi-orch; pi-orch on PATH is the bin of that repo). It builds every request against a drift-guarded contract snapshot, sends X-Parent-Session for you when it knows your session id, and uses documented exit codes. Its wait blocks in the server's long poll and never polls. Programmes dispatch through it, not through hand-written curl scripts. Read references/pi-orch.md before your first call: verbs, goal budget, retention ids, waiting patterns, route caps, exit codes.

SID=$(pi-orch spawn --runtime pi --cwd /work/dir --model-selector <live-selector> \
      --thinking low --owner <you> --ttl 3600 --id-only)    # + --goal-objective "…" --goal-budget-tokens N for a goal child
RID=$(pi-orch prompt "$SID" --message "…" --id-only)        # detached, idempotency key built in
pi-orch wait "$SID" --run-id "$RID" --deadline 1800 --json      # in-turn wait only; an idle parent registers a watch and ends the turn (§4)
pi-orch result "$RID" --json                                    # final text + parsed completion block
pi-orch verify "$SID" --run-id "$RID" --since <base> [--rerun "npm test"] --json   # check the block's claims
pi-orch status --parent <you> --json; pi-orch cleanup "$SID" --lease <id> --owner <you>

Rules worth carrying: a goal child that may run long needs --goal-budget-tokens (the 5,000,000 default pauses it mid-run) and a single-line objective; a Claude Code parent names its children orch-<programme>-<parentShort8>-<lane> because it has no managed parent identity; exit 3 is a deadline (re-wait, never re-dispatch), 18 means reconcile with status before any re-spawn, 25 means the route cap refused the spawn (nothing was created); the completion block is a claim, so run verify before accepting it. Per-route caps: spread a large wave across routes rather than queueing it on one (one provider route stops completing above roughly five to eight concurrent children).

Fallback: raw requests. Use them for anything the client does not cover (adoption, transfers, diagnostics), or when pi-orch is unavailable. Nothing here assumes a working directory. The socket and token are absolute paths, overridable by environment variable so the same snippet works in any harness:

SOCKET="${PI_WEB_UI_SOCKET:-$HOME/.pi-web-ui/internal-api.sock}"
TOKEN_PATH="${PI_WEB_UI_TOKEN_PATH:-$HOME/.pi-web-ui/internal-api-token}"
TOKEN="$(cat "$TOKEN_PATH")"
API_BASE="${PI_WEB_UI_API_BASE:-http://localhost/api/v1}"
SELF_ID="${PI_WEB_UI_SESSION_ID:-${PI_SESSION_ID:-}}"   # your own internal id, when you are a managed session

api() {
  curl --silent --show-error --unix-socket "$SOCKET" \
    -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    ${SELF_ID:+-H "X-Parent-Session: $SELF_ID"} \
    "$@"
}

When you run inside a Pi Web UI-managed session, PI_WEB_UI_SESSION_ID (contract 1.47.0; Pi also keeps PI_SESSION_ID) is set automatically, and the runtime also exposes PI_WEB_UI_SESSION_ORIGIN and PI_WEB_UI_PARENT_SESSION_ID (OpenCode and the Claude channel backend get none). From a bare CLI there is no internal id: leave SELF_ID empty and omit the header rather than inventing one. It is optional identification, not auth.

Parent linkage (contract 1.34.0): the X-Parent-Session header links the calls you make to your session, so linkage events (child_dispatched, child_turn_ended, watch_registered, watch_fired) are published to your session's event stream and are watchable like any other event. Linked children persist parentSessionId; GET /sessions/:id gains an additive children list. Unresolvable values are ignored — and a native Claude Code parent is not a Pi Web UI session, so its X-Parent-Session does not link. From a native Claude parent, put $CLAUDE_CODE_SESSION_ID in the child directive as the parent session ID (§3), and record the family in whatever coordination surface you use, so peers can see which dispatch a child belongs to. A session that already exists — created earlier without linkage, or a native CLI session on disk — can be linked under you after the fact instead of re-created; see §8 and references/adoption.md.

Confirm Pi Web UI is actually present before planning anything:

ls -l "$SOCKET" "$TOKEN_PATH"

Auth is Authorization: Bearer <token> over the socket. This is a trusted same-host surface, not an RBAC boundary: any token holder can inspect and control every session. So be explicit with the operator about target, runtime, model, thinking level, session count, retention, and likely side effects before acting, and never delete, abort, transfer, or repurpose sessions your orchestration does not own.

The repository also ships an experimental seven-tool stdio MCP adapter, but it is retained and disabled. Do not try to route through it; use the socket.

Golden rule: discover first, every time

Ask the server what exists right now. Machines differ, backends change, and model lists are live.

GET $API_BASE/capabilities
GET $API_BASE/capacity
GET $API_BASE/models

• /capabilities — verify contract.name is pi-web-ui-internal-api and check contract.majorVersion. Capability-gate optional features rather than assuming them. The runtime feature flags are per-runtime, nested under runtimes.<runtime> (not top-level): read supportsFollowUp, followUpSemantics, supportsSteer, supportsSteerWhileBusy, supportsThinkingLevel, supportsApprovals, supportsInteractiveQuestions, supportsReplayHistory from the entry of the specific runtime you plan to use.
• /capacity — a preflight, not a reservation. Prompt admission is rechecked at dispatch and can still return 429 ADMISSION_CAPACITY_EXHAUSTED for slot/runtime limits, or 503 for resource pressure, with Retry-After. Resource refusals include heap_pressure and event_loop_lag (1.49.0; /capacity shows heap and eventLoopLag), and 503 SERVER_DRAINING while a deploy drains (1.51.0). Treat any 429/503 with Retry-After as "wait and retry" (a drain ends in a restart: re-check /capabilities afterwards), and never read the wire contract's code list as closed. An event_loop_lag refusal usually means the host is overloaded (another agent's build or benchmark), not that your request is wrong: pi-orch waits out Retry-After for you; raw callers must too. Heavy work of your own belongs under nice and capped CPU and memory (systemd-run --scope -p CPUQuota=… -p MemoryMax=… -- nice -n 10 <cmd>; some systemd-run versions reject -p Nice=10, so put nice inside the scope), so it cannot starve the server's single event loop. Read actual tasks, reservations and the limiting reason—not just the nominal turn ceiling. Admission permits are not a complete count of browser/native work or autonomous goal continuations; separate request receipts can also refer to one executing turn.
• /models — choose exactly one live-advertised entry. Read its id, provider, thinkingLevels, and for Claude profiles backend and claudeModel. A missing field is unknown, not permission to fill it in from memory. Profile ids are opaque strings; since contract 1.25.0 both /models profile entries and /capabilities.claudeProfiles carry the same underlying alias in claudeModel / model. After creating a session with an explicit model, trust only the create response's resolvedModel / modelBinding fields (contract ≥ 1.25.0) or a follow-up /info read-back — never assume the echo means the binding happened.
• Watch mutation capability — features.watchGenerationPreconditions, when present with the documented field names, enables opaque-generation conditional register/delete. Use observed tokens and exact ownership; absence means legacy non-CAS semantics, not permission to claim atomic deletion. See walk-away.md.
• Provider quota — /capacity is Pi Web UI's local admission capacity and /sessions/usage is our own recorded consumption; neither is the provider's remaining subscription quota. Check that before choosing a route: read each provider's remaining quota in its own dashboard or CLI (a zero-model-token, read-only check), including per-provider windows, resets, shared pools and any peak-window flag. That check is your authoritative pre-dispatch evidence.

Read enabled as well as available. Since contract 1.15.0 they mean different things: enabled: false is an operator-disabled runtime, which is not the same as uninstalled or unhealthy. Treat disabled as unavailable and never silently substitute another runtime.

There are five runtime families, not four: pi, claude, opencode, antigravity, and the feature-gated commandcode. Don't hard-code the old four-runtime assumption.

Pi provider policy — on contract 1.16.0+, capabilities.features.piProviderPolicy.blockedProviders lists Pi providers barred from automation to prevent accidental metered spend. The shipped default is empty: the direct openai provider and the full OpenRouter gateway catalogue are both served through /models and selectable like any other provider (check blockedProviders for the effective per-deployment list — operators can re-block exact provider ids via INTERNAL_API_BLOCKED_PI_PROVIDERS, and a non-empty deployment rejects blocked providers with 403 PROVIDER_NOT_ALLOWED). Don't guess around an omitted model on deployments that do omit them. Being served is not being authorised: pay-as-you-go providers (direct Google API, OpenRouter, a direct anthropic API key, a native DeepSeek API, plain openai) need the operator's direct authorisation before any use — see references/routing.md. A subscription-backed provider is distinct from a metered direct provider and is never covered by this policy.

If a model you expect is missing, refresh the catalogue rather than improvising: POST $API_BASE/models/refresh with {"runtime":"pi"} (refreshes the OpenRouter catalogue and returns an ids diff) or the default/"opencode" mode (warms the models.dev cache and recycles the idle backend). It returns public ids and metadata only, never credentials.

Never use a remembered model list, a family-name match, a coarse reasoning flag, a stale contract version, or a guessed fallback. If the exact combination you need is absent, stop and report why.

Choosing the child path

Internal API first for every child size: it keeps routing and quota control. Use the harness's own subagents (Agent tool) or a Claude Code cloud child only when the Internal API is unavailable or the operator asks.

• Agent-tool isolation:"worktree" can lose its context (every Bash refused): create the worktree yourself and tell the child to cd into it, using absolute paths.
• Cloud children bill credits your provider dashboards do not show. A clean finish emits nothing watchable, so give each lane a branch, end every child turn with a pushed commit whose subject starts QUESTION|BLOCKED|HANDBACK, run a capped git ls-remote watcher as a background task in the dispatch turn (Bash timeout 7,200,000 ms; the 30 min default kills it) and arm a ≤ 60 min wake_deadline that checks get_session.
• If the Internal API persistently refuses admission (e.g. event_loop_lag), retry briefly, then use an Agent-tool child on a capable model as the fallback for the same bounded task — provided the operator has allowed that path.

Choosing the route

Treat a dispatch route as the complete tuple:

runtime + selector/id + provider + profile/backend/Claude-model (when used)
        + advertised thinking or discovered native effort + invocation role

Names are not selectors. Immediately before real dispatch, get one fresh /models response, filter the named runtime list, and select exactly one entry satisfying every predicate; use its returned selector (since contract 1.26.0 every entry carries one — the exact string POST /sessions accepts, so copy it rather than constructing provider/id yourself). Zero matches, multiple matches, a missing required field, or an absent required level is a refusal — never a reason to take the first similar entry or another backend. Keep the matched metadata with the dispatch record.

→ references/routing-rationale.md explains why a route table is shaped as it is (why a list price is the wrong yardstick, what to check before changing a row); read it before changing any route.

→ references/routing.md carries the method: choosing from live metadata, checking provider headroom, the three work classes (Class 1 routine children on cheap, high-quota models; Class 2 more demanding work; Class 3 the most demanding), the PAYG rule (metered providers only with the operator's direct authorisation), the reviewer-from-a-different-family rule, per-route concurrency caps, hard exclusions and route-discipline rules. Read it before choosing a model — the exclusions and quota lanes are the kind of thing that looks harmless to guess at and is not.

Planning a multi-phase programme

Most runs are one wave — dispatch, watch, fan in, done — and §1–§9 below cover that. When the work is a programme (a sequence of dependent improvements over multiple waves, often in shared repos alongside other active agents), plan the organisation before the first dispatch. Parents fail at the joins between waves, not inside them. Three rules carry the shape:

• Write the programme into three durable artefacts that survive parent compaction and restarts: a stable strategy document (scope, waves, ownership, gates; operator-gated status header PLANNING ONLY → READY → EXECUTING; amendments recorded in place; records scope, not completion), a mutable live checkpoint re-read before acting (per-child status, receipts, wake-delivery ids, next sequence, honest counters), and a per-child brief + evidence directory (bounded outcome, owned paths, handback format with a FROZEN marker).
• Brief every child with a bounded, self-contained packet: frozen success criteria, bounded files, exact test commands and guardrails, rather than dumping repo context. A child that already holds its context should not re-query or loop.
• Give every concurrent child an isolated git worktree with disjoint owned paths; the child states those paths (and what it leaves to others) in its hand-back, or in whatever coordination surface your setup provides (§3b).
• Derive waves from the sequence, not from available children: a parent-owned bootstrap wave first when the supervision machinery itself is suspect; parallel children only on disjoint owned paths; later phases gated on earlier interface stability or another lineage's work landing (postpone the seam, don't block); a fresh read-only reviewer child after each lane (§3c), not only at the end, and a named reviewer live re-run lane before the wave closes; code/test/deployment reported separately. Declare dependencies by what a step needs (interface, data, deploy order), and put a design gate in the brief of any behaviour-critical lane.
• Acceptance is a verdict, not a receipt: the parent independently re-runs verifiers and writes its own probes; every defect returns with RED evidence as one bounded correction brief; accepted phases freeze.

→ references/multi-phase.md has the full pattern: the programme trigger table, the three artefacts in detail, wave derivation, ownership contracts for concurrent writers, correction cycles, and cross-wave supervision; references/programme-kit.md has the templates and runbooks to copy. Read it before dispatching the first child of anything longer than one wave.

The orchestration loop

1. Create sessions

POST /sessions for one child, POST /sessions/batch for several. For anything long-lived, ask for retention atomically at creation so a failure can't leave an orphan:

{
  "runtime": "claude",
  "model": "profile:<discovery-resolved-id>",   // SDK profiles only, see below
  "thinkingLevel": "max",
  "cwd": "/approved/working/directory",
  "retention": { "mode": "durable", "ttlSeconds": 3600, "ownerId": "<retention-id>" }
}

Claude on the Internal API is SDK-only (contract 1.46.0): /models?runtime=claude lists only SDK profiles, and a create or prompt through any other Claude backend fails 403 CLAUDE_BACKEND_NOT_ALLOWED (features.claudeBackendPolicy in /capabilities; it also covers watch wake, goal dispatch and batch). Take the exact profile:<id> from the live /models entry and do not construct one.

Prefer a single create when atomic retention matters — batch creation does not guarantee leases. Record at minimum the canonical sessionId, the exact route tuple, the invocation role, your ownerId, the returned retention.leaseId, and your own orchestration id. Since contract 1.34.0 the create response echoes parentSessionId when you identified yourself via X-Parent-Session, and GET /sessions/:id lists linked children. Since 1.54.0 every create also records parentSource (header | body | bash | peer): without the header the server resolves the calling session from socket peer credentials, fails closed (no link) on any ambiguity, and costs a slower create, so still send X-Parent-Session whenever you have an id. GET /sessions?parent=<id> lists a parent's children (404 for an unknown parent). There is still no orchestrationId, so keep your own tree record too.

Create into a directory that exists (1.53.0): every create checks the effective cwd (exists, is a directory, writable) and refuses 400 PREFLIGHT_FAILED with a failures[] list before any model token is spent, so make the child's worktree first. Add "preflight": {"paths": [...], "tools": [...]} (absolute paths, bare tool names; also accepted on POST /sessions/:id/prompt) for the files and tools the brief depends on: a bad workspace then fails in one cheap round trip instead of many children discovering it mid-task. Batch create answers 200 with per-entry PREFLIGHT_FAILED. Treat it as fix-then-resend, never blind retry.

The create response's model echo is not proof of binding. Verify the effective, provider-qualified model via /info (and for Pi, the last model_change entry on disk) before spending a long run — a silent rebind to a much costlier model has happened with a correct-looking echo. → references/sessions.md (Model binding) has the verification reads, the Claude-profile rules, and the observed failure shape.

Bindings are durable (contract 1.33.0) — the run receipt is authoritative. After dispatch read servedModel and modelRebound on the receipt; a binding that cannot be applied fails loudly (MODEL_NOT_APPLIED / PROVIDER_NOT_ALLOWED). Never re-verify by hand-scraping child session files during a run (references/sessions.md).

2. Prepare, if needed

Model, thinking-level and effort switches, and retention leases, go through POST /sessions/:id/control (set_model, set_thinking_level, set_effort, acquire/renew/release_retention). Thinking levels are capability-gated; for Pi the response level is the effective read-back after SDK clamping, not an echo. set_effort is the Command Code axis — idle-only, next-turn, never changes thinkingLevel (models with no adjustable effort take no effort request). For Claude, pick the backend/provider profile at session creation rather than switching later; backend comparisons are cleaner as one session per profile.

→ references/sessions.md (Control actions) has the exact action payloads.

3. Dispatch

POST /sessions/:id/prompt, POST /sessions/batch/prompt.

Modes — this is how you redirect a child that's already working, and it's easy to miss:

Every successful response and receipt carries dispatchMode, the operation actually performed, alongside the requested mode. requireActiveTurn: true turns idle promotion into 409 SESSION_NOT_STREAMING everywhere. Capability-gate the differences with followUpSemantics and supportsSteerWhileBusy — steering is a Pi capability and, since contract 1.29.0, a Claude SDK-backend capability (runtimes.claude.supportsSteer).

A busy steer is not admission-checked (it joins an existing turn), so steering a busy parent works even when every slot is full; new turns can still get 429/503 with Retry-After — detail in references/sessions.md (Dispatch modes and admission).

Persist the returned runId before doing more work.

For anything that may outlive your connection, use detached dispatch. An attached tasks/full stream disconnect cancels its run; use verbosity=answers with detach:true for disconnect-safe execution. A separate /events observer does not own the execution. Repaired SSE helpers close slow/oversized responses at their buffer limit, so streaming is not a substitute for durable receipts:

POST /sessions/:id/prompt  {"message":"…","verbosity":"answers","detach":true}   → 202 + runId
GET  /runs/:runId

Large or slow fan-outs should prefer detached individual prompts, because batch/prompt holds answer bodies until its response completes.

Mandatory child skill requirement. The agent-os-child skill is **not injected into API-created sessions by any harness; only your prompt delivers it. Every child prompt, for implementers, researchers and reviewers alike, must carry this directive. Without it a worker drifts into narrative, omits command exit statuses, ignores exclusions and self-signs-off:

"You are dispatched as an Agent OS child worker. You MUST load and strictly follow the agent-os-child skill. Your session ID is <sessionId>. Your parent session ID is <parentSessionId>. Work strictly inside execution worktree <cwd>. Owned paths: <paths>. Negative exclusions: <paths>. Hand-back directory: <dir>. Success criteria are frozen. Announce your task once before editing files (a one-line note in the hand-back directory), and leave a closing note when you finish. <Push / do not push.> Hand back by ending your turn only when your own commands have finished; never wait or poll."

The directive pi-orch lane run sends adds "declare presence on the board" clauses for the author's coordination layer. If you have no such layer, drop those clauses or leave them in: the child skill tells a child without a board to write the note file instead.

Put the directive in the prompt itself, not only in a brief file it points to, and restate it inside a goal objective ("follow agent-os-child; mark the goal achieved and end") — goal-engine dispatches that dropped it produced most of the unmandated children in an audit of real child sessions. The rest of a good brief (each item traces to a recurring failure in that audit):

• Its own worktree for every concurrent child — never two children in one main checkout.
• Push stance. Say whether the child may push. Lane branches are often never pushed (children commit only; the parent merges) — state the rule anyway.
• The long commands and how to run them (foreground with a timeout), and that a child must not end its turn while its own job runs — or must start the message NOT FINISHED:.
• The RED method: test first; no git stash (its stack is shared across worktrees).
• Restarts stay with you: never delegate a restart of the service that hosts the child.
• Read-only roles: say "no edits, no stash, no extra turns" (lookups are fine); add "no lookups" only for a genuine fresh-reader or blind test.
• A budget for research children (time or tool calls), a checkpoint cadence and a hand-back milestone — unbounded research children ran for thousands of tool calls.

• An end-of-task report block (contract 1.58.0), so the server captures the child's claims (§6). pi-orch appends it for you (for a goal child also the Status: marker and field-shape instructions); paste it by hand only for raw dispatch, verbatim inside this four-backtick fence (a cheap fast model followed it 16 times out of 16 in live trials):

  END-OF-TASK REPORT (required): the LAST thing in your final answer must be exactly this kind of fenced block (info string `completion`, JSON body):
  
  ```completion
  {"schema":"pi-completion/v1","status":"done","summary":"<one line>","commands":[{"command":"<a command you ran>","exitCode":0}],"filesChanged":["<path>"]}
  ```
  
  Fill in the real values; add "tests", "commits", "openIssues" or "blockedReason" fields only if they apply. Do not end your turn with only a tool call: after your final tool call, always write a short final answer that ends with the report block. Nothing after the closing fence.

• Live proofs in the child's own disposable server copy only the credential of the approved route into the isolated agent directory, count models.json entries that carry apiKey as credential copies and delete every copy afterwards, name the child route explicitly in any inner brief, and assert the served model by script. A parent holding a full credential copy can silently pick a different model for its children.
• Host rules the brief must carry (binding wording in programme-kit.md, common brief): disposable servers started with the inherited production placement or tool-root variables removed (env -u <VAR> …); heavy commands in a systemd-run --scope with a hard MemoryMax; changed-file lint against the lane base; never touch the main checkout. The child-side form is agent-os-child §3 and §7.
• Templates for all of this: references/programme-kit.md.

For a read-only reviewer, replace the owned-paths, exclusions and push sentences with "You are a read-only reviewer: do not edit, commit, stash or push, and leave the tree untouched; numbered answer and correction files amend the brief", and add the verdict format (§3c), to be returned in the review file and the final message. Your own prompt already carries the identity and scope context, so the brief need not restate it.

3b. Task announcement: parent vs child

If you run a coordination layer (a shared task board, a sibling-agent registry, a worktree claim file), the child announces what it touches and the parent defines the boundaries and lineage:

• The child announces what it owns, once, before editing, and says what it leaves to others; on finishing or blocking it leaves a closing note before handing back. If the layer has a command for this, pass the child its sessionId from POST /sessions so the announcement merges onto the existing linkage. Where the layer distinguishes an "exclude" list, note that it is information for peers, not a keep-out zone.
• The parent defines the worktree, owned paths, exclusions and frozen criteria in the brief; records the dispatch lineage itself; and closes the record of a child that crashed, timed out or aborted without a closing note.
• No coordination layer? Then this section is one line of the brief: "say what you own before you start, and tell me when you stop." Nothing else changes.

3c. Reviewer child: a fresh, independent read-only session

After an implementer hands back, and before you accept or merge, dispatch a fresh session to review the change. Fresh context is the point: the implementer's history, and yours, are polluted by the path taken, while a new session sees only the diff, the brief and the evidence. Run one per lane and again after each correction; it is not only a last wave.

• Route (a role, not a model): one of your recommended worker models, on a different model family from the implementer, at the highest thinking level its live route advertises, never a metered provider without direct authorisation, respecting disabled or suspended backends — rules in references/routing.md (Use an independent reviewer). Check provider headroom first and confirm fallbackApplied:false on create.
• Create with cwd = the implementer's worktree and durable retention (ttlSeconds sized for the wait, ownerId:"orch-<prog>-<parentShort8>-<lane>-reviewer"), dispatch detached, watch agent_end with max_wakes headroom (each auto-compaction also fires an agent_end).
• Read-only is enforced by the brief only. Check git status is clean afterwards.
• The verdict is evidence, not sign-off. You still re-run gates and adjudicate; a defect goes back to the same implementer as a bounded correction, and the same reviewer closes the previous findings.

Proportionality. A finding must be able to change the decision; if it cannot, verify, record the limitation and accept. Use a capability-strong reviewer for safety-critical code (cheap reviewers have missed a HIGH confirm-gate gap that a stronger reviewer caught). A quick "ACCEPT, no findings" from a cheap reviewer is a weak signal, not sign-off. Time-box reviews. Never shortcut production safety checks.

Cap: one full review, one closure round on the same reviewer, then a final parent-verified correction (no round 3). Brief contents, the verdict format, the closure loop and the compaction gotchas are in references/multi-phase.md (Review wave). For several parallel critiques of one draft, use references/patterns.md (Reviewer fan-out) instead.

4. Set a long task and walk away

Four pieces combine into "dispatch and check back later": retention keeps the session alive, detached dispatch starts the turn and returns, watch-wake prompts you when the child finishes, and notifications ping the human.

Who are you? Decide this BEFORE any detached dispatch. Only a managed session (one Pi Web UI created) can be an onFire target. A bare CLI process cannot be prompted by the server: a server-side onFire armed for it — by you, a script, curl or a repo dispatcher helper — sits undelivered while you idle. Observed: a parent audited its script-armed watch as active, asserted it would auto-resume, and slept until a human noticed. A server-side watch existing is not a wake being deliverable. Before ending your turn, name the exact tool call that delivers each wake into this session.

The rules worth carrying in your head:

• Watch the child, wake the parent. Register the watch on the child with an onFire action targeting your own session, then return your turn. Never watch yourself — an idle session emits no events.
• Command-shaped work is not child work. Long shell jobs (test suites, builds, watchers, validation scripts) run natively where the harness provides a background command (a background-shell extension, or the harness's own run_in_background mechanism): launch, end your turn, and the completion wake carries the exit code and output tail — no child session, no watch, no tokens while waiting. That is for you, the parent: a child that ends its turn on its own background job wakes you with a false hand-back, which is why children run long commands in the foreground (agent-os-child §2). Reserve child dispatch and watch-wake for work that needs another model context; cross-runtime waiting rules are unchanged.
• Bare-CLI parent ⇒ local delivery is mandatory (table above), then one appropriate backstop per long-horizon-waiting-strategies before idling: the loaded wake_deadline on a healthy host, an independent fallback when the host/tool itself is suspect. Repo scripts that arm their own server-side watches serve audit/durability — they do not count toward your wake.
• event_type: agent_end is the default condition. One wake per child turn, and it also fires when the child stops early to ask, which is exactly when you should look.
• Parallel children are supported. Wake budgets are per watch record, so N children give N independent budgets with no cross-child suppression.
• Two fan-in rules (contract 1.32.0+): one watch per session (re-registering explicitly returns replaced:true and starts a new ledger), and only one steer may be pending per target. Use mode:'steer' for a busy Pi/Claude SDK parent and reconcile every child on any wake; additional concurrent steers are recorded as steer_pending suppression. Transient delivery failures do not consume budget and get one bounded retry.
• Never poll in-turn. Holding your turn open to watch a child is the failure this whole section exists to remove. That includes a foreground pi-orch wait: it is for scripts and in-turn waits; an idle parent registers a watch and ends its turn (references/pi-orch.md, Waiting).
• 202 is queue acceptance, not delivery. Never report "notified" from it.

→ references/walk-away.md has the full detail: retention modes and lease ownership, the watch-wake payload and its cross-runtime matrix, the fan-in best-practice list, bare-CLI wake paths, every condition type with what it actually promises, and the notification edges. Read it before your first detached dispatch.

4b. Goal-driven children (contract 1.27.0)

A goal is a durable objective that survives compaction on every supported runtime — the strongest primitive for long-horizon children, and protection against ambient traffic that sounds like a session ending (a plain-prompt probe child once stopped mid-task to obey an automated end-of-session summary request). Arm one for work that must outlive a context window or must not be derailed; use a plain prompt for bounded single-turn tasks. Write the aim, not the method: what must be true, the evidence that settles it, where the record lives, the invariants. Arm via POST|GET /api/v1/sessions/:id/goal or atomically at create; watch terminal goal_end (filter a reused session's old-goal clear by the exact new objective), not per-run agent_end. A start receipt is not completion. The objective must be a single line (the API rejects newlines), and a goal that may run long needs an explicit token budget (budgetTokens; pi-orch --goal-budget-tokens): the 5,000,000 default pauses it mid-run — measured programme lanes needed tens of millions.

→ references/goals.md — the API, per-runtime honesty matrix, read-back discipline. Read it before arming a goal.

4c. Pausing YOUR OWN goal to supervise a child (Pi coding agent only)

Keep the parent goal running while independent work remains. Before idling: arm the watch and backstop, goal pause (reason "supervising <child>"), end the turn. Never end with Status: NEEDS_USER_INPUT for supervision (the wake would auto-resume the goal), and resume only when fully settled (no re-dispatch, questions or child watches outstanding). Verify the goal engine version you rely on is actually loaded.

→ references/goals.md (Part 2) — full lifecycle and trigger table. Read it before dispatching a child under an active goal.

5. When a child asks a question

A child that stops to ask is otherwise a dead end. Read pending requests with GET /sessions/:id/approvals/pending and answer via POST /sessions/:id/approvals/:requestId/respond — structured answers keyed by the exact question text, cancelled: true to dismiss. Never fabricate an answer on the operator's behalf, and never treat an accepted HTTP response as resolved work.

→ references/sessions.md has the exact request/response shapes, error codes, and the permission-request form. Open it before answering a child.

6. Monitor, and know what counts as evidence

/events is supervision, not durable completion evidence. For detached or disconnect-prone work, the receipt is the truth.

• A /wait timeout means "still running", not "failed". Re-wait; never restart, re-dispatch or alert on one.
• Before reporting a blocker, rule out your own harness — over-strict route assertions, parsers that reject valid JSON wrapped in prose, schemas stricter than the one you asked for. A false blocker costs the operator more than a slow run.
• A blank transcript projection is not proof there was no answer. Compare the full projection, receipt evidence, history and diagnostics first.
• Terminal codes that are not child failures to retry as-is.
  • NEVER_STARTED (1.57.0): an accepted, dispatched run showed no runtime activity inside the start window (default 120 s). The watch fires with runNeverStarted: true. The dispatch never ran: re-dispatch once, then look at the session. Turns started by an extension or the browser (goal continuations, watch-wake deadlines) have no receipt, so this does not cover them; keep goal_end watches plus a backstop.
  • RUN_TRANSPORT_LOST (1.57.0): a synchronous dispatch's receipt went terminal but its response chain never returned. The outcome is in the receipt; read it and do not re-dispatch blindly.
  • RUN_BUDGET_EXCEEDED: the run hit a per-run cap. The caps are streamed tool arguments (64 KiB per call, 256 KiB per run), 1,000,000 output tokens, and 4 MiB of streamed output. The run_budget_exceeded / tool_args_budget_exceeded event names which cap. Split the task, or ask for files instead of inline output.
  • interrupted with SERVER_RESTART: a deploy cut the run off. The watch fires with interruptedByRestart: true, and receipt-less goal or extension turns carry runId: "busy-<sessionId>" (1.52.0). On contract ≥ 1.60.0 a Pi goal child cut off by a RESTART interruption does not need you: the server continues it once at boot — a goal_state with status: "running" + top-level autoContinued: true, progress, never a goal_end — and only a stop it could NOT continue surfaces as goal_state paused + pausedReason: "interrupted" with the cause — exactly one of: restart_interruption/rehydrate_pause that could not be continued, second_transient, continue_failed, unsupported_runtime (non-Pi goals, boot sweep only). A provider-aborted goal is NOT continued: it ends exactly as it did before 1.60.0 (a failed goal_end) and needs you as it always did. Resume a visible stop (POST /goal {"action":"resume"}) or re-dispatch; every non-Pi goal still needs the old resume-or-re-dispatch move. On older servers, resume or re-dispatch after the restart, as before. Watch forms: dataMatch {"autoContinued": true} sees continues; dataMatch {"status":"paused","pausedReason":"interrupted"} sees stops (both plus your objective filter); pi-orch wait already registers the continue condition, counts continues into autoContinues and settles a visible stop as exit 5 with the cause and a note.

Completion blocks (1.58.0). A child that ends its final answer with a pi-completion/v1 block (see §3's brief list) gets it parsed server-side. The receipt carries completion (or completionError with a typed code and field path) and completionDelimiter. GET /sessions/:id carries latestCompletion, which also covers goal children whose final turns have no receipt. The block is the child's claim, not proof: run pi-orch verify (or check commits and files yourself) before accepting it. A contradicted verdict is a correction item, not a retry.

→ references/evidence.md has the five-step evidence ladder, the receipt.outputEvidence dispositions, transcript scope semantics (including the scope=screen trap), what receipt terminality does and does not prove, and the Claude channel /events caveat. Read it before declaring anything complete.

7. Find and identify sessions

GET $API_BASE/sessions            # list: sessionId, runtime, model, status, cwd, messageCount, lastActivity
GET $API_BASE/sessions/:id        # detail
GET $API_BASE/sessions/:id/info   # enriched runtime/session metadata

Listing is the natural first move when you arrive cold and need to know what is already running. The list returns the full persistent registry — including long-dead sessions — ordered newest-first by lastActivity; liveness comes from busy/lastActivity, never from mere presence.

→ references/sessions.md has server-side filters (contract 1.30.0), the native-CLI session scan, and the identifier-forms warning (internal id vs sessionPath vs runtime-native id — resolve first, never guess).

8. Adopt existing sessions as children (contract 1.40.0)

Adoption links an already-existing session under you after the fact, with the same linkage and fan-out as create-time children. A registered session: POST /sessions/:id/adopt (or control action adopt). A native CLI session never registered: discover with GET /sessions/native, then POST /sessions/adopt-native and use the returned internal sessionId. Adoption is display-only metadata — it never moves transcripts or changes ownership — and adopted children are full supervision targets.

Operator gate — never skip. If the session was initiated or used in a CLI tool (claude, cmdc, agy, opencode, pi), ask the operator and wait for explicit confirmation that they have exited that CLI before adopting or dispatching. Your dispatches resume the same native artefact in the server's subprocess; a still-open CLI is a second live writer (Claude refuses --resume with Session ID already in use, and concurrent writers diverge the transcript).

→ references/adoption.md — discovery recipes, payloads, responses, errors, ownership/fencing, post-adoption wiring, worked example. Read it before your first adoption.

9. Transfer, aggregate, clean up

• POST /sessions/:id/transfer moves visible context into a target session you own — cleaner than inventing your own handoff framing. It is a handoff, not shared memory; track the target id and send a follow-up instruction after.
• POST /sessions/usage aggregates token/cost across the batch. Keep the session/run mapping so cost stays attributable.
• After positive quiescence, release_retention only the exact lease you own (payload key retentionLeaseId). Then POST /sessions/:id/abort if work must stop, and DELETE /sessions/:id for disposable sessions you created.
• DELETE of a Pi session runs its extensions' session_shutdown (reason quit, bounded 5 s): the child's background-shell processes (dev servers, watchers) and goal/watch timers end with it, and the call can take up to 5 s longer. Collect anything a child's background task produced before deleting it.
• If release or deletion is unconfirmed, preserve that uncertainty in the handoff. Never blanket-unpin, broad-kill processes, or delete an operator-owned session.

10. Orchestrator governance

For the parent only (children follow agent-os-child). The full playbook, with the decision boundaries, restart protocol and notification standards, is references/orchestrator-governance.md; the rules to carry:

• Decide and fix autonomously within scope. Diagnose defects, design fixes, write briefs and dispatch small-to-medium corrections without asking; keep the operator informed at milestones. Escalate only what the governance file lists (destructive or irreversible steps, external submissions, production restarts and deploys unless the programme's authority already covers them, locked-decision pivots, quota exhaustion, unadjudicable ambiguity).
• One writer per working tree. Concurrent children in one repository each get an isolated git worktree with disjoint owned paths; where a worktree is impractical, queue the second child until the first has committed. Cross-repository parallelism is safe.
• Sequence gating is yours, not the operator's. When an earlier lane lands and the tree is clear, un-gate the queued lane at once; never ask "may I start phase X?".
• Production restarts of the service that hosts your orchestration: only with the operator's authority for the programme, only by the parent (never from inside a child it hosts), and through the deployment's drain-then-restart procedure. Pi Web UI ships production:drain-restart under a production lock; adapt it to your deployment.
  • On contract ≥ 1.52.0 the drain waits for every busy session, goal continuations and browser turns included.
  • On contract ≥ 1.60.0 a Pi goal child the restart still cuts off continues once on its own at boot; you resume only the stops it reports as paused/interrupted.
  • On an older server, pause goal-armed children first: its drain cannot see their turns.
  • Afterwards verify /capabilities and reconcile every child and watch (references/orchestrator-governance.md §3).
• On every wake, check every child, not only the one named in the wake.
• Flatten child chains: adopt or re-parent finished sub-workers under your own record.
• Mandate agent-os-child in every dispatch (§3) and require child-side task announcement with owned paths.
• Verify every fix a child claims against the diff, not its report. Children have claimed fixes they never made and root causes that were wrong; a correction brief should demand a file:line list per claimed fix and a test on the real code path, and the parent checks both (details in the governance file §8).
• Contain your own proofs. Any memory or isolation experiment runs under its own hard memory cap, inside a subtree you created and verified, with self-capped allocations: an escaped proof once grew without bound and the host OOM killer took the service down.
• Run the CI's gate list, not a subset, before merging or deploying — including changed-source ratchets against an explicit base (npm run lint:ratchet -- --base <lane base or previous master> in a repo that has one; the default base sees nothing on a merge commit). Local lint passing while CI's ratchet fails is a real gap.
• Notify at milestones through your own notification path — a short milestone, question, blocked or done message, never as a running commentary — and check that it was delivered.

Current limitations

• Parent linkage and child surfacing exist from contract 1.34.0 (automatic lineage and ?parent= since 1.54.0), but there is no general orchestration job registry. Keep the programme checkpoint and exact session/run/watch/lease mapping; linkage is not execution or completion proof.
• Run receipts are dispatch-scoped; there is no general job queue or scheduler.
• /approvals/pending is backend-specific; runtimes without a synchronous pending surface return an empty list.
• Command Code exposes only its attested shadow profile through the Internal API. Browser-contained Command Code sessions are deliberately invisible to Internal API session, diagnostic, notification, receipt, and transfer routes.

Related

• Pi Web UI live-validation documentation — proving a Pi Web UI or runtime change works, short-horizon or long-horizon, always on a disposable server. Use it instead of this skill whenever the question is "does my change work?".
• long-horizon-waiting-strategies — going idle safely during long waits: the pre-idle checklist, harness-specific wake and backstop mechanics (Pi, Claude Code, Antigravity, Command Code), and the supervision and liveness rules.
• agent-os-child — the skill every child must follow; you mandate it (§3).
• secret-scanning — the credential-scanning companion for work that produces artefacts, evidence bundles or repositories.
• In the Pi Web UI repo when present: docs/INTERNAL-API-QUICKSTART.md, docs/INTERNAL-API.md, docs/INTERNAL-API-ORCHESTRATION.md, docs/INTERNAL-API-RECIPES.md, docs/INTERNAL-API-CONTRACT.md, docs/NOTIFICATIONS.md, docs/SHARP-EDGES.md, docs/DURABILITY-MATRIX.md, docs/TROUBLESHOOTING.md, docs/CLAUDE-BACKENDS.md.

If the repo is not checked out, this skill plus live /capabilities is enough.

Part of the Pi Web UI orchestration set

• Pi Web UI — https://github.com/valtterimelkko/pi-web-ui (docs: docs/ORCHESTRATION-OVERVIEW.md, docs/INTERNAL-API-ORCHESTRATION.md).
• pi-orch — https://github.com/valtterimelkko/pi-orch, the parent client whose bin is pi-orch on ${PATH}.
• The pack — https://github.com/valtterimelkko/agent-workflow-skills/blob/main/packs/pi-web-ui-orchestration-pack/README.md.
• The watch-wake companion — companions/watch-wake/ in this repository: the Pi extension and the Claude Code mod that wake an idle parent, plus the model-free wake deadlines.
• Sibling skills in this repository: ../agent-os-child/, ../long-horizon-waiting-strategies/, ../secret-scanning/.