# UltraPi operations

UltraPi is loaded by the Pi Coding Agent from `src/index.ts`. Root orchestration has one entry point: `ultra_dispatch`. Start with the [README](../README.md), then use [Usage](./USAGE.md) for installation/commands and [Configuration](./CONFIGURATION.md) for modes, policies, and immutable config versions.

## Profiles

Run `node --import tsx src/install.ts` from this directory after upgrades; an interactive terminal asks for weekly/daily credit budgets and the default per-task policy. For automation, pass `--weekly-credit-budget <n> --daily-credit-budget <n> --per-task-policy economy|balanced|quality|max`. It creates isolated `~/.pi-private` and `~/.pi-free` directories plus `~/.local/bin/pi-private` and `~/.local/bin/pi-free`. `pi-private` is the documented/default UltraPi profile; `pi-free` is explicit and fail-closed when its roster is incomplete. They intentionally do not share authentication; log in to each profile separately.

Run work with `/ultra <task>`. Auto mode requires a valid `ultrapi-profile.json` marker in the selected agent directory; use the matching launcher or an explicit non-auto mode for an unmarked profile. Use `/ultra-config budget <weekly> [daily]` before `mode=auto`, or `/ultra-config budget acknowledge` for an explicitly acknowledged one-task run. `/ultra-config doctor` shows the actual agent directory/profile, model availability, MCP presence, storage health, and compatibility pins.

## Commands

`/ultra <task>` is the only task command. Status, mode, policy, budget, runs, stop, steer, recovery, feedback, export, config, and doctor live under `/ultra-config` so normal runs stay quiet.

An executable `acceptanceCommand` makes UltraPi's verifier authoritative. It runs without a shell through the guarded argv executor; unsupported or unsafe commands are blocked rather than retried.

Before writing any export, use `/ultra-config export preview [YYYY-Www]`. The report/export command asks for confirmation, but previewing is the right operational check for a shareable artifact.

## Watching a run

While a run is live, a terminal session shows a panel above the editor with the named steps of the run, which one is in progress and who owns it, the delegated agents still working under it, and provider health:

```
UltraPi · swarm · 3bf1fcf9
✔ Validate the request and the checkout  root
✔ Select the smallest safe topology      root
▸ Gather bounded evidence                scout  2/6
  Apply the scoped change                writer
  Run the declared acceptance check      root
  Settle the run                         root
    flow        scout  openai-codex/gpt-5.6-luna  0.32 cr  active
    invariants  scout  openai-codex/gpt-5.6-luna  0.19 cr  active
degraded · 2 parallel · 429×2 · est. $0.25
```

The step names come from the run's ledger, which plans them per topology at dispatch. Pi caps a widget at ten lines, so the panel budgets its own: step rows always fit, and agent rows take the space that is left, with a count of any that did not.

Every session also keeps one line in the status bar — topology and state, checklist position, live agent count, model, health, spend — and that is the only surface outside a terminal.

Both are best-effort by construction. A host with no widget or status bar, a controller that is not ready, a renderer that rejects the content: all are swallowed and the run continues. A display that can end the run it reports on would be worse than no display.

`/ultra-config status --live` prints the same information on demand, in any mode.