Merge main; align lint and skill practices with essential memory/history and the four graded examples

This commit is contained in:
2026-11-04 13:08:47 +00:00
217 changed files with 8560 additions and 1937 deletions
+78 -28
View File
@@ -71,8 +71,9 @@ token-reporting stage reported one, and the summed cost, plus counts of stages
that did or did not report a cost. A stage whose provider reported no cost is
counted as cost-unknown and never contributes a fabricated or zero cost, and no
cost/token count is inferred from output length or transcript text. The totals are
the sum of the per-run totals `inspect` shows. `pipelines stats --json` exposes
these aggregates.
the sum of the per-run totals `inspect` shows. Only usage rows whose recorded
step still exists are counted, so rows orphaned by an old history wipe are ignored
(not deleted). `pipelines stats --json` exposes these aggregates.
Use `:status` on any TUI page to open server and ntfy information. Scroll with
arrows or `j/k`, PgUp/PgDn; `r` refreshes and Esc closes without changing the page.
@@ -152,7 +153,7 @@ pipelines edit # fuzzy pipeline selection
pipelines edit "bug fix" # ask the harness what to change
pipelines edit "bug fix" "Add a review step"
pipelines new "release notes" "Summarize changes and notify my phone"
pipelines new "Add a feature" --template task
pipelines new "Add a feature" --template feedback-loop
```
`new` opens the configured harness (Pi or OpenCode; host by default, or
@@ -213,27 +214,21 @@ is not ownership (the kernel lock is). This is a local-filesystem lock, not a
distributed lease; hard-link database aliases and filesystems without reliable
advisory locking are unsupported.
Use `:templates` for four simple, manual-only starters: task, review, research,
and plan/implement/review. **Submit template** (`s` or Enter) asks for a
Use `:templates` for the four manual-only examples, read in order: one stage,
two stages, a feedback loop and a human decision (`examples/README.md`). A
brand-new database already holds them as ordinary pipelines; the server seeds
them once and never again, so removing them or upgrading never brings them back.
**Submit template** (`s` or Enter) asks for a
name without opening an editor. Enter saves a retained draft, then a separate
confirmation publishes it as a new pipeline. Esc before naming creates nothing;
Esc at publication keeps the draft. **Customize** (`e`) opens the editor picker
instead. Both paths inherit the configured default model and preserve existing
pipelines/history. The research starter requires configured web search support.
Starter stages use goal-appropriate tools: the task worker and the three-stage
implementer edit and run checks, the task, planner and review stages may
search/fetch official sources only when external knowledge is genuinely needed,
the three-stage implementer has no web tools and follows the planner's research,
the standalone review stage never edits or runs commands and says so explicitly,
and the three-stage reviewer independently inspects the real changes and receives
the planner-owned acceptance checks rather than the implementer's summary,
approving only when the applicable acceptance checks were independently observed
passing and no unresolved substantive issue remains. The task and three-stage
templates end in a committer stage that stages the runner's captured changed paths
and commits locally without ever pushing; a genuine operator gate is a `type=human`
decision stage, never a model stage pretending to approve. Editing a bundled
template source changes no installed or published definition; a starter becomes an
immutable version only after explicit authoring and publication.
pipelines/history. Only the stages that make the requested change (`implement`,
`act`) may edit; the others read, and the loop's reviewer also runs read-only
checks. No example commits, pushes or deploys. A genuine operator gate is a
`type=human` decision stage, never a model stage pretending to approve. Editing a
bundled template source changes no installed or published definition; a template
becomes an immutable version only after explicit authoring and publication.
Home's `n` / `:new` and **Customize** (`e`) on a template first ask how to author the new
pipeline: **nvim** opens a retained Markdown draft file, or a configured harness
@@ -284,6 +279,19 @@ pipelines validate /path/to/pipeline-123.md --json
pipelines submit /path/to/pipeline-123.md --json
```
`validate` and `submit` apply the authoring lint to new drafts (stored versions
keep loading and running unchanged). Errors reject the draft and are listed
together, one `stage KEY: RULE: message` per line: a stage that can modify the
workspace without a `checks` block (`none: <reason>` or, on a `delivery=true`
stage, the commands), a prompt naming an undeclared outcome ("report skipped"),
a "the server lands it" claim with no `delivery=true` stage, a loop edge without
`limits`, and a check guard that passes without running (`|| true`,
`[ ! -x tool ] || ...`). Warnings print as `warning: ...` on stderr (the
`warnings` array with `--json`) and do not block: runner boilerplate in a prompt,
a prompt over 2000 bytes, an instruction to read the full history every visit,
and back-quoted non-outcome words after return/report. The skill's
`references/practices.md` explains each rule.
`--json` never opens an editor or picker; provide a name explicitly. It returns
draft metadata including `path`, `name`, `server`, `create_only`, and `base_version`.
`--no-open` prints the path and review commands. `$PIPELINES_DRAFT_DIR` overrides
@@ -349,8 +357,23 @@ Every run summary (`list_runs` rows, `get_run`, subscribe snapshots and terminal
with turn documents and session exports, server-created Pi session directories,
plus an estimate of its database rows). It is cached in `pipeline_runs.size_bytes`,
invalidated by triggers when the run changes, measured on completion, and
backfilled in the background; 0 means not measured yet. `delete_runs` removes
finished runs to free space:
backfilled in the background; 0 means not measured yet.
`list_runs` rows (and `get_run`) also carry `usage`, the run's totalled reported
model usage, in the same shape as the run detail's total: `tokens_total`,
`stages` and `tokens_known_stages` (the total is partial when fewer stages
reported tokens than recorded usage), the `tokens_in`/`tokens_out` split with
`split_known`, the `tokens_reasoning`/`cache_read`/`cache_write` components with
`cache_known` (true only when every token-reporting stage recorded them;
`tokens_total` includes cache reads, which dominate for a caching harness), and
`cost_usd` with `cost_known_stages`/`cost_unknown_stages`. The list computes it
with one grouped SQL aggregate per batch of 100 runs over the stored per-stage
usage rows joined to their recorded steps, never a step load or transcript parse.
It is omitted for a run with no recorded model usage; an older server omits it on
every row, and clients then show nothing. Subscribe snapshots and `run_event`
frames do not carry it, so a running run's total refreshes with the next list.
`delete_runs` removes finished runs to free space:
```json
{"type":"delete_runs","id":"1","run_ids":[12,13,99]}
@@ -461,6 +484,20 @@ sessions pipeline runs create. The protocol types are:
for the run that owns them. The list is fail-closed: with no registry and no
store it returns an empty list, never the endpoint's whole session list. A
session is never marked `busy`: any number of clients may watch and write one.
Each row carries `activity` (`turn_running`, `background_tasks`, `seq`): the
server's live view of the session. An older server omits it.
- `chat_activity` is pushed to every open connection, not only the chat's
watchers, when a session's turn starts or ends or its count of running
background tasks changes (shells, background commands, Claude Code background
Bash and subagents, Codex command executions). The body is `chat_activity`
(`session_id`, `turn_running`, `background_tasks`, `seq`). It is sent on those
transitions only, never per output chunk. `seq` increases with every change
and keeps increasing across a restart, so a client keeps the snapshot (list
row or push) with the larger `seq`. Background tasks are counted only while
the server observes the session: after a chat's last viewer leaves, the
server keeps observing it while its tasks run (bounded like an unattended
turn: at most 16 such chats and 6 hours). Once released it reports none
rather than a stale count.
- `chat_subscribe` attaches a connection to one session's shared live stream (body
`session_id`) and replays the session's still-pending approval requests, so every
client that watches a session sees every frame any client's turn produces — the
@@ -627,8 +664,12 @@ per-step `provider`/`model`, and the run's graph shows the effective pair). Each
model step also records the usage the harness reported, carried from the same
accounting the stage already used for its budget: `usage.tokens_total`, the
`tokens_in`/`tokens_out` split when the harness reported it (`split_known`),
`cost_usd` when reported, and the explicit `tokens_known`/`cost_known`/
`split_known` markers. The run detail totals those stages as `usage`, so a
`cost_usd` when reported, the `tokens_reasoning`/`cache_read`/`cache_write`
components when the harness reported the component split (`cache_known`; rows
recorded before these were kept lack it, so their cache share is unknown), and
the explicit `tokens_known`/`cost_known`/`split_known` markers. Some subscription
providers report `cost_known` with no positive `cost_usd`; clients show that cost
as not reported, never as $0. The run detail totals those stages as `usage`, so a
mixed-model run shows each stage's model, tokens and cost and the run total. A
stage whose provider reported no cost shows its tokens with `cost_known: false`
(never a fabricated or zero cost), and a harness that reports only a total (Pi)
@@ -637,6 +678,13 @@ total as input tokens. The
CLI is the deliverable; a TUI picker for choosing overrides is a documented
follow-up, not half-built.
The run detail (`inspect <id> --json`, `get_run`) also carries an additive
top-level `warnings` string list, derived at read time from the steps; `inspect`
repeats each entry on stderr as `warning: ...`. Today it names every visit whose
retained file-change capture was `partial` or `unavailable`, because such a
capture is not a complete workspace diff and disables the server skip fallback
(see [stage-file-diffs.md](stage-file-diffs.md)). Older peers ignore the field.
On either the runs list or run inspector, press `P` (or use `:pipeline`) to open
the selected run's exact pipeline version. Navigation does not cancel the run.
@@ -754,6 +802,7 @@ files as that step's artifacts:
```
<artifacts>/<run>/stages/01-implementer/input.md
<artifacts>/<run>/stages/01-implementer/memory.md
<artifacts>/<run>/stages/01-implementer/history.md
<artifacts>/<run>/stages/01-implementer/output.md
<artifacts>/<run>/stages/01-implementer/private/
<artifacts>/<run>/public/
@@ -761,10 +810,11 @@ files as that step's artifacts:
`input.md` is the run prompt on the first visit; later visits carry the run
prompt under `# Run task` followed by the previous visit's output body (without
its outcome section) under `# Previous turn output`. `memory.md` is the accumulated markdown of completed turns plus the
files each turn added to the shared `public/` directory. A text-only stage (an
explicit empty `tools` block) receives both files' contents in its prompt
instead, because it has no file-reading tool. The model returns the complete
its outcome section) under `# Previous turn output`. `memory.md` is the capped (4 KB) essential memory inlined in every prompt: task,
previous stage's `# handoff`, outcome ledger and changed files. `history.md` is
the accumulated markdown of completed turns plus the files each turn added to
the shared `public/` directory, read on demand. A stage without `read` also
receives `input.md` in its prompt (capped), because it has no file-reading tool. The model returns the complete
`output.md` markdown; only its `# outcome` section is interpreted by the server.
Everything else is free-form and preserved under the step's `markdown` output.
`private/` belongs to its own visit, while `public/` is shared by every stage in