Files
pipelines/docs/harnesses-and-control.md
T
alan 914345cb31 Move harness profiles between host and Docker and stop silent draft retargeting
Native installs left Docker-era harness profiles in harnesses.json, so every
authoring launch failed trying to reach a Docker service, and a retained draft
bound to the old Docker server was silently projected onto the configured one.

- harness: add Profile.Mode and VerifyDockerLink as the single mode/verification
  helpers. `harness setup --host` configures or converts a host profile and
  clears docker_directory; reconfiguring a Docker-linked profile re-verifies the
  recorded directory still owns compose.yaml and fails naming it instead of
  saving a link that cannot launch. Setup's summary and `harness list` (via the
  new List/ListView shape) report the resulting mode and, for Docker, the
  directory, without changing the stored Config schema.
- setup-native.py: after build/install-skill it writes host (no docker_directory)
  profiles for the detected harnesses, defaulting to the detected OpenCode profile
  rather than a stale pi default, taking models from --model or the existing valid
  profile and never inventing one; it clears a stale Docker link and preserves
  unrelated keys/profiles. Detection-only: no harness install, upgrade or download.
- draft: add Draft.Resolve, the shared mismatch helper, which projects a draft
  onto the configured server and returns a dual-URL notice. CLI validate/submit
  and the TUI draft browser use it so a foreign draft is never silently
  retargeted; the TUI pre-wraps the notice to the panel width.
- Tests cover the Docker->host and host->host transitions, the missing-directory
  failure, installer write/migration (Python), and the CLI/TUI notice, using the
  real config file path in a temp dir.
- Update help text, README, docs and the packaged authoring skill reference to
  describe host as the default and the Docker-linked case.
2026-10-15 19:53:10 +01:00

6.8 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.

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.