git:20261003.dc0d872 to git:20261028.e62486e

- description: "Drive real agent work through Pi Web UI's local Internal API from any directory or harness: run a task on several models and compare, spin up child or sub-agent sessions, split work across runtimes, score or classify batch items with one model, hand a job to another model, start something and check back later, get woken when a child finishes or a condition fires, answer a child agent's question, monitor or clean up running sessions, transfer context between sessions, adopt an existing session as a child, or automate Pi Web UI without the browser. Use it as a parent orchestrator or multi-agent orchestrator managing children, or when the user mentions the Internal API, Unix-socket orchestration, session fan-out, session adoption, runtime comparison, watch-wake, or dispatching by voice. Every child you dispatch must be told to follow the `orchestrated-child-worker` skill, and the waiting discipline is in `long-horizon-waiting-strategies`: use all three together. To prove a change to Pi Web UI itself works, use the Pi Web UI repository's live-validation docs instead."

- ## Which job do you want?

- The two Pi Web UI jobs split on one question: **are you *using* Pi Web UI, or

- | You are… | Approach | Default target |

- | Proving a change to Pi Web UI or a runtime actually works | the repository's live-validation docs | a **disposable** server, always |

- reconfiguring the Pi Web UI service on your own initiative — the one exception is a

- programme whose owner 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.

- This file holds the workflow and the rules that keep you out of trouble. The

- reference files hold the field-level detail, organised in three reading tiers:

- must-read on every run, must-read when the situation matches, and optional.

- **Tier 1 is not advisory** — skipping it before dispatching is the most common

- way an orchestration run goes wrong (stale model lists, wrong routes,

- exhausted provider quota). Tier 2 rows are mandatory *within* their stated

- situation and skippable outside it. Tier 3 is genuinely optional.

-

- **Tier 1 — Must read, every orchestration run (before you dispatch anything):**

-

- | Must-read | Why |

- |---|---|

- | `long-horizon-waiting-strategies` skill (separate skill) | roughly all Internal API orchestration is long-horizon: the pre-idle checklist, backstop selection, supervision and liveness rules. Read it before your first idle window |

- | `orchestrated-child-worker` skill (separate skill) — **you do not follow it, you mandate it** | every child prompt must carry the child directive in §3, for implementers, researchers and reviewers alike. Nothing injects it automatically |

- | *Golden rule* section (above), including the **provider quota check** | live capability/capacity/model discovery, plus provider headroom — `/capacity` and `/sessions/usage` are **not** provider quota, and subscription peak windows change the right route |

- | `references/routing.md` | **model routing principles — mandatory**: choosing an exact live selector, checking provider quota, reviewer families, and the rules that no longer hold |

-

- **Tier 2 — Must read when the situation matches:**

-

- | Reference | Mandatory when… | What it holds |

- |---|---|---|

- | `references/pi-orch.md` | **before your first `pi-orch` call in a run**, and before dispatching a programme through it | verbs and flags, goal budget, owner-id convention, `status --owner`, idle vs in-turn waiting, route caps, exit codes |

- | `references/adoption.md` | **before adopting any session as a child** — registered or native CLI; includes the operator's CLI-exit confirmation gate | discovery, payloads, responses, errors, post-adoption supervision wiring, worked example |

- | `references/claude-code-orchestrator.md` | **MANDATORY when orchestrating from Claude Code** (interactive `claude` CLI, `claude -p`, or a managed Claude session) | Internal API side for Claude parents: which-Claude wake route, dispatch-and-idle with a watch-wake mod, fan-in, `onFire` for managed Claude, Claude-parent routing notes. Wake mechanics, backstops and zero-token discipline: `long-horizon-waiting-strategies/references/claude-code-watch-wake-and-background-watcher.md` |

- | `references/antigravity-orchestrator.md` | **MANDATORY when orchestrating from Antigravity CLI / IDE** | Zero-token reactive waiting protocol, persistent wait-watch helper, no-in-turn-polling invariant, milestone notification standards, post-compaction checkpoint anchor |

- | `references/orchestrator-governance.md` | **when running several children** — competing priorities, production restarts, or defect handling | autonomous boundaries, defect design & dispatch, single-writer repository staging, restart protocol & recovery, check-in discipline, notifications |

- | `references/multi-phase.md` | **before the first child of a multi-wave programme** — dependent phases, shared repositories, concurrent writers, or another agent lineage owning overlapping scope | programme artefacts, wave derivation and dependency kinds, interim waves, design gates, the reviewer child, ownership contracts, correction cycles |

- | `references/programme-kit.md` | **with `multi-phase.md`, when you write the programme's files** | copyable templates (checkpoint, common and lane briefs, correction brief), parent verification checklist, worktree and shared-dependency rules, merge order, deploy and restart runbook, close-out |

- | `references/walk-away.md` | **before your first detached dispatch** | retention, the watch-wake payload, fan-in under parallelism, every condition type, notification edges, bare-CLI wake paths |

- | `references/goals.md` | **before arming a goal** on a child, or dispatching while your own session runs under a goal; also high-value for complex or longer child tasks | goal API, per-runtime honesty matrix, read-back discipline, parent-goal parking |

- | `references/evidence.md` | **before declaring a child complete** | the evidence ladder, receipt dispositions, transcript scope traps, the Claude `/events` caveat |

- | `references/sessions.md` | binding a model to a session, answering a child's question or permission request, or finding/identifying sessions | control payloads, model-binding verification, request/response shapes, identifier forms |

-

- **Tier 3 — Optional reads:**

- | `references/patterns.md` | designing a fan-out or batch job, or reporting a run to the operator — background reference, not required |

- | Several children, restarts, defects, notifications | §10 → `references/orchestrator-governance.md` |

- **Contract versions.** Feature notes below name the Internal API contract version

- that introduced them (for example 1.49.0 for the heap and lag refusals). The

- Pi Web UI repository'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. A deployment can declare a

- stability window in which the contract takes bug fixes only; `/capabilities`

- reports the served version, and a client such as `pi-orch` warns when its bundled

- snapshot is stale.

- **Preferred: the `pi-orch` client** (https://github.com/valtterimelkko/pi-orch —

- a thin parent client with no runtime dependencies beyond Node). 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, owner ids, waiting patterns, route caps, exit codes.

- pi-orch wait "$SID" --run-id "$RID" --deadline 1800 --json # in-turn wait only; an idle parent registers a watch and ends its turn (§4)

- pi-orch result "$RID" --json # final text + parsed completion block

- 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 lineage;

- 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. Spread a large

- wave across routes rather than queueing it on one.

- (adoption, transfers, diagnostics, goal pause and resume), or when `pi-orch` is

- `children` list. Unresolvable values are ignored. A session that already

- for you; raw callers must too. Heavy work of your own belongs under `nice` and a capped

- scope, so it cannot starve the server's single event loop: on systemd,

- `systemd-run --scope -p CPUQuota=… -p MemoryMax=… -- nice -n 10 <cmd>` (put `nice`

- inside the scope; `-p Nice=10` is rejected by `systemd-run`).

- remaining subscription quota. Check that before choosing a route: read the

- read-only check), including per-provider windows, resets, shared pools, and any

- peak-window flag. This is the authoritative, zero-token pre-dispatch check.

- **Provider policy** — on contract 1.16.0+,

- barred from automation to prevent accidental metered spend. Operators can 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 (metered API keys, gateway catalogues)

- need the operator's direct authorisation before any use — see

- `references/routing.md`. Subscription-backed providers are distinct from metered

- direct providers and are never covered by this policy.

- Names are **not** selectors. Immediately before real dispatch, get one fresh

- **→ `references/routing.md`** carries the general principles: choosing from live

- metadata, checking provider headroom before dispatch, using a different model

- family for reviewers, asserting the served model, and the hard exclusions

- (metered providers without authorisation, disabled or suspended backends). Read

- it before choosing a model.

- ownership, gates; owner-gated status header `PLANNING ONLY` → `READY` →

- the child announces its owned paths (and what it leaves to others) in its

- coordination directory (§3b).

- not only at the end, and a named **reviewer live re-run lane** before the wave closes;

- code/test/deployment reported separately. Declare

- "retention": { "mode": "durable", "ttlSeconds": 3600, "ownerId": "<unique-owner>" }

- | `prompt` | start a new turn | `409 SESSION_BUSY` if busy. From 1.45.0: a swallowed prompt (extension input-hook swallow / fence) fails fast as `PROMPT_NOT_EXECUTED` after a 2 s grace; a session whose lease a **live foreign runtime** holds refuses up front as `409 SESSION_OWNED_BY_OTHER_RUNTIME` (`ownerPid`/`ownerMode`, no run created); a dead owner is auto-recovered (dispose→rehydrate, pins kept) before dispatch | `409 SESSION_BUSY` if running | `409 SESSION_BUSY` if running |

- attached owner `tasks`/`full` stream disconnect *cancels* its run; use

- A separate `/events` observer is not the execution owner. Repaired SSE helpers

- **Mandatory child skill requirement.** The `orchestrated-child-worker` 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 orchestrated child worker. You MUST load and strictly follow the `orchestrated-child-worker` skill. Your session ID is `<sessionId>`. Work strictly inside execution worktree `<cwd>`. Owned paths: `<paths>`. Negative exclusions: `<paths>`. Hand-back directory: `<dir>`. Success criteria are frozen. Announce your task (a one-line note in the hand-back directory) before editing files, and leave a 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."

- goal-engine dispatches that dropped it produced most of the unmandated children in an

- audit of 241 child sessions. The rest of a good brief (each item traces to a

- - **Read-only roles**: say "no edits, no stash, no capture"; add "no lookups" only for a genuine fresh-reader or blind test.

- four-backtick fence:

-

- **Completion-block shape** (learned from a live proof where two blocks were rejected or mis-verified): `commands` entries are `{command, exitCode}` objects; `commits` entries are `{sha, repo, subject?}` (sha is 7–64 hex chars; `repo` is an absolute path); `filesChanged` entries are paths **relative to a claimed repo** — coordination or hand-back files outside the work tree are not part of the claim and should be omitted. A malformed block is still parsed to a typed `completionError` (`fieldPath` names the first bad field), so a rejected block costs one reporting follow-up, not a re-run.

- 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 with 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 without the inherited production placement or

- tool-root variables; 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 `orchestrated-child-worker` §3 and §7.

- 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. The harness already delivers the identity packet and scope warnings to the child, so the brief need not restate them.

- ### 3b. Task announcement ownership: parent vs child

- **The child owns runtime presence; the parent defines boundaries and lineage.**

- - **The child announces**, from inside its worktree, with owned paths and, optionally, what it leaves to others:

- a one-line note in the coordination directory (for example `00-declared.md`).

- Where the parent's environment provides a shared task surface, use it as well.

- On finishing or blocking the child adds a closing note before handing back.

- - **The parent:**

- 1. Defines the worktree, owned paths, exclusions and frozen criteria in the brief, mandating the child skill.

- 2. Passes the child its `sessionId` (from `POST /sessions`).

- 3. Records its own dispatch lineage for the child where its environment supports it

- (the `X-Parent-Session` header / `parentSessionId` is the API-level link).

- 4. Closes its record of the child if it crashed, timed out or aborted without a closing note.

- - **Route (a role, not a model):** one of the recommended worker models, on a **different model family from the implementer**, at the highest thinking level it advertises, never a metered provider without direct authorisation, respecting disabled/suspended backends — rules in `references/routing.md` *Reviewer route*. Check provider quota first and confirm `fallbackApplied:false` on create.

- - **Create** with `cwd` = the implementer's worktree and durable retention (`ttlSeconds` sized for the wait, `ownerId:"<prog>-<lane>-reviewer"`; a Claude Code parent uses the `orch-<prog>-<parentShort8>-<lane>-reviewer` convention, `references/pi-orch.md`), dispatch detached, watch `agent_end` with `max_wakes` headroom (each auto-compaction also fires an `agent_end`).

- or a repo dispatcher helper — sits undelivered while you idle. 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.

- builds, watchers, validation scripts) run natively in a harness that provides

- background commands (a background-shell extension or the harness's

- `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 (`orchestrated-child-worker` §2). Reserve child dispatch and watch-wake for work that

- (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

- 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

- obey an automated capture request). Arm one for work that must outlive a context window or

- token budget (`budgetTokens`; `pi-orch --goal-budget-tokens`): the 5,000,000 default pauses

- it mid-run.

- with a needs-user-input marker for supervision (the wake would auto-resume the goal), and

- `verify --since <ref>` requires each claimed commit to be an **ancestor of `<ref>`**:

- pass the branch head you inspected (the ref that must contain the work), never the

- pre-work baseline — the check is inverted from the natural reading of "since".

- > is a second live owner (Claude refuses `--resume` with `Session ID already in use`, and

- bounded 5 s; contract 1.5x): the child's background 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.

- - **Sequence gating is yours, not the owner's.** When an earlier lane lands and the tree

- owner's authority for the programme, only by the parent (never from inside a child it

- - **Flatten child chains**: re-parent finished sub-workers under your own record.

- - **Mandate the child skill** in every dispatch (§3) and require child-side

- - **Notify at milestones** through your own notification path — a short milestone /

- question / blocked / done message, never a running commentary.

- - **pi-orch** — the thin parent client: https://github.com/valtterimelkko/pi-orch.

- - **Pi Web UI** — https://github.com/valtterimelkko/pi-web-ui. When the repo is

- checked out, the canonical docs are `docs/INTERNAL-API.md`,

- `docs/INTERNAL-API-ORCHESTRATION.md`, `docs/INTERNAL-API-CONTRACT.md`,

- `docs/LIVE-VALIDATION.md`, `docs/TROUBLESHOOTING.md`;