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.
8.1 KiB
Harnesses and runner-owned control
Configure two independent model defaults:
./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.