e70c94e8dd
Cut the review loop's repeat cost and make a blocked stage actionable, at the
definition level only, with the runner's existing visit counting and caps.
The published maintenance, quick and focused pipelines gain a reviewer
`advisory -> next stage` edge for non-blocking notes, so an advisory-only review
continues the run instead of buying another implementer visit; `rejected ->
implementer` and its unchanged {"max_visits":3,"on":["rejected"]} limit keep a
must-fix finding looping and still terminate. The implementer gains
blocked_retryable -> implementer with {"max_visits":5,"on":["blocked_retryable"]}
for a transient environment/tooling/device problem a fresh attempt could
survive, while blocked -> #failure stays terminal. The cap is at least the
reviewer's rejection budget so the implementer's own pre-execution cap cannot
preempt the reviewer's rejected control.
No production Go code changed. New tests in internal/server/review_contract_test.go
cover advisory-only never revisiting the implementer, must-fix still looping to
the reviewer limit, the implementer cap not preempting the reviewer, retryable
blocks bounded then failing closed, a retry that recovers, and a terminal block
failing immediately; concurrency/control/human tests share the new submitRunner
and startRun seams.
Documentation checked: internal/author/skill/references/control.md and
docs/harnesses-and-control.md carry the new edges and the visit-cap rule;
no packaged template defines these pipelines (they are published immutable
versions), and docs/model-results.md needs no change because the {outcome,output}
result contract is unchanged. README and other shared docs deliberately untouched.
Verified: go build ./... and go test -count=1 ./... pass.
Residual limitation: the must-fix-vs-advisory split is carried by the prompt
contract, not a machine-readable marker, because the recorded findings have none;
a model that still returns rejected for advisory-only notes would still buy a
visit. All 18 recorded implementer blocked runs classify terminal, so the
blocked_retryable edge recovers 0 of them.
129 lines
8.1 KiB
Markdown
129 lines
8.1 KiB
Markdown
# Harnesses and runner-owned control
|
|
|
|
Configure two independent model defaults:
|
|
|
|
```sh
|
|
./install --docker --harness pi # Docker setup without OpenCode login
|
|
./install --opencode --default
|
|
./install --pi
|
|
pipelines harness
|
|
pipelines harness default pi
|
|
pipelines new --harness pi
|
|
pipelines debug 12 --harness nvim
|
|
```
|
|
|
|
Setup uses a styled onboarding wizard that shows authentication and model steps
|
|
and fuzzy-searchable catalogs; the live picker renders each numbered step with
|
|
its title and purpose (no duplicated numbered prose is printed outside it). It
|
|
preserves existing credentials and does not perform inference. The interactive
|
|
harness model is chosen first (`Step 1 of 2`) and the new-pipeline-stage model
|
|
second (`Step 2 of 2`), in two separate pickers with the saved value preselected
|
|
and marked `(current)`; typing filters, arrow keys or Tab navigate, Enter
|
|
confirms, and Esc cancels without changing anything. Pi signs in through
|
|
`/login` in a fresh, no-context, extension-free, no-prompt-templates, no-tools
|
|
session launched with `--tui-mode regular` so the handoff stays visible above
|
|
Pi's interface instead of the default fullscreen clear (there is no standalone
|
|
`pi auth login`); the handoff names `/login`, the authentication-method step
|
|
("Sign in with an API key" for provider API credentials; account and Radius stay
|
|
the user's choice), finishing provider sign-in and exiting Pi with
|
|
`ctrl+c`/`ctrl+d` to return to model configuration. Existing credentials stay in
|
|
the Docker volume and are reused by exiting when no new sign-in is needed;
|
|
completing a sign-in can update the credentials stored in the volume.
|
|
Canceling or failing either picker leaves saved preferences unchanged.
|
|
On existing Docker setups, the reconfiguration commands
|
|
resolve and verify the current OpenCode V2/Pi releases, then operate inside the
|
|
container without restarting it. A rebuild is required only when the verified
|
|
release image identity (versions/digest) differs from the resolved releases; a
|
|
model/login-only change does not rebuild. A full `./install --docker` always
|
|
invokes the Docker build for a dirty source and relies on layer caching. Harness
|
|
installation stays Docker-only: the default native setup only detects an existing
|
|
host OpenCode/Pi and never installs, upgrades or downloads them, and
|
|
reconfiguration never falls back to host harness execution.
|
|
Container credentials and accounts are separate from host credentials and are
|
|
reused on reinstall/reconfigure.
|
|
Profiles live in XDG config home's `pipelines/harnesses.json` and record their
|
|
launch mode: a host profile launches the executable directly, while a
|
|
Docker-linked profile records the checkout directory and launches through
|
|
`docker compose exec`. `harness setup <opencode|pi> --host` configures (or
|
|
converts) a host profile and clears any Docker link; without `--host`,
|
|
reconfiguring a Docker-linked profile re-verifies that the recorded directory
|
|
still has `compose.yaml` and fails naming it instead of saving a link that cannot
|
|
launch. Setup's summary and `harness list` report the resulting mode (and, for
|
|
Docker, the directory) so a profile never silently stays Docker-linked. The
|
|
native installer writes host profiles for the harnesses it detects and clears a
|
|
stale Docker link rather than leaving the config Docker-linked.
|
|
Defaults affect only new drafts/starters, not existing immutable versions.
|
|
OpenCode uses `mini --model` to avoid changing unrelated host/project defaults.
|
|
Pi stage execution requires its profile on the server; interactive host and
|
|
execution-server credentials/settings remain separate.
|
|
The shared authoring/debug CLI prefix is Docker-aware: a loopback logical
|
|
`--url` is mapped to this Compose service only when a single bounded
|
|
`docker compose port` probe returns a `host:port` binding covering the requested
|
|
loopback address and port. Remote DNS names (including names such as
|
|
`127.remote.example` that merely begin with `127.`), malformed or non-matching
|
|
bindings, unmatched loopback endpoints and loopback `wss` endpoints fail safely
|
|
instead of being silently redirected or downgraded to plaintext. `provider-check`
|
|
on a Docker-linked profile runs in-container and preserves the caller's output
|
|
mode (`--json` only when requested) with exact stdout/exit propagation.
|
|
|
|
Put `harness=pi` in a model stage's configs to select Pi. nvim edits definitions
|
|
or displays debug evidence; it does not execute model stages.
|
|
|
|
For bounded review loops, add a fenced `limits` JSON object to the reviewer:
|
|
`{"max_visits":3,"on":["rejected"]}`. Its ordinary edges can be
|
|
`approved -> #success`, `rejected -> implement`, and `error -> #failure`.
|
|
On the third rejection the server terminates at failure regardless of model
|
|
counters. Approval on that visit can still succeed. Limits never enter prompts.
|
|
|
|
A reviewer that must separate a blocking defect from advisory notes declares both
|
|
edges: `rejected -> implement` (kept, with the `limits` above) is reserved for a
|
|
must-fix finding that names a concrete location, evidence and remedy, and
|
|
`advisory -> <next stage>` carries non-blocking duplication, performance or style
|
|
notes. An advisory outcome continues the run and never buys another implementer
|
|
visit. An implementer that can tell a transient environment, tooling or device
|
|
problem from an acceptance criterion that genuinely cannot be met declares a
|
|
bounded self-edge: `blocked_retryable -> implementer`, while `blocked -> #failure`
|
|
stays terminal. `max_visits` caps every visit of that stage, including re-entries
|
|
from the reviewer's `rejected` edge, so an implementer that is also the rejection
|
|
target needs a cap at least as large as the reviewer's budget; the published
|
|
maintenance, quick and focused pipelines use
|
|
`{"max_visits":5,"on":["blocked_retryable"]}`. A smaller implementer cap stops the
|
|
loop on the implementer's pre-execution limit before the reviewer's own cap can
|
|
fire, which silently makes the reviewer's `rejected` control unreachable. The runner
|
|
already counts the visits and stops at the cap, so neither loop needs new server
|
|
code and no model counts visits.
|
|
|
|
Add a fenced `memory` map such as
|
|
`{"task":"input.prompt","checks":"planner.checks"}` to select reviewer
|
|
input without previous verdicts. Implementers can select
|
|
`{"task":"input.prompt","plan":"planner.plan","feedback":"review.findings?"}`.
|
|
`?` means omit if unavailable. A memory block replaces the previous-stage input;
|
|
without it, existing previous-output handoffs are unchanged. Latest completed
|
|
outputs are shared only within this run. Read provenance and routing overrides
|
|
are retained in SQLite and exposed in run inspection/metadata.
|
|
|
|
These controls enforce counts/field selection, not semantic independence or every
|
|
prose guideline. AI-assisted guidelines validation is not implemented.
|
|
|
|
Verification: `go test` uses controlled RPC fixtures for Pi stage accounting,
|
|
results and timeout cleanup; `node --test scripts/test_pi_policy.mjs` exercises
|
|
policy gates. `python3 scripts/check-pi-rpc.py` checks installed Pi metadata RPC,
|
|
policy loading and idle lease cleanup without inference, also checked in an
|
|
isolated built Docker image non-root with networking disabled. Real-provider Pi
|
|
stage execution is now covered for the dated 2026-10-11 final install: run17 ran
|
|
both the OpenCode and Pi real stages on the installed runtime and each returned the
|
|
exact `pipelines-docker-verified` marker (see the dated install receipt in
|
|
`docs/installation-verification.md`). Active lease-expiry recovery, web tool
|
|
delivery and fresh interactive Docker Pi sign-in remain not tested. An additional
|
|
opt-in integration command,
|
|
`PIPELINES_PI_LOCAL=1 go test ./internal/stage -run TestPiInstalledLocalIntegration`,
|
|
exercised installed Pi with scripted loopback responses: actual permitted/denied
|
|
writes, budget exhaustion and active-shell cancellation without a delayed write.
|
|
It also covers isolated deny-all syntax repair and cumulative usage.
|
|
These are not real-provider results. Pi syntax-only formatting repair uses a separate deny-all
|
|
session, retains ownership and shares the budget; value changes are rejected
|
|
locally. Permission gates are not an OS sandbox.
|
|
|
|
Detailed packaged guidance: `internal/author/skill/references/control.md` and
|
|
`internal/author/skill/references/harnesses.md`.
|