# Chat persistence: attach to the operator's own OpenCode by pairing, and fall back honestly ## What this item changed Brokered chat could already be pointed at an operator-supplied OpenCode endpoint (`-opencode-endpoint` / `PIPELINES_OPENCODE_ENDPOINT`), but pointing it at the operator's running V2 service failed closed: the V2 API authenticates every request with HTTP Basic auth (fixed user `opencode` plus a password), the broker had no credential, so the health probe answered 401, startup logged `OpenCode chat unavailable: OpenCode endpoint … is unreachable or is not an OpenCode service`, and chat was disabled entirely. Established from the installed binary (`opencode v2.0.20`), not from docs: - `opencode --help` lists `api`, `pair`, `serve`, `service`, `auth`; `pair` is "Print one-time links to connect a browser or app". - `GET /api/info` unauthenticated → `401`, `www-authenticate: Basic realm="Secure Area"`. - Basic auth user `opencode` with the password from `~/.local/state/opencode/service.json` (`opencode service start` writes it, mode 0600) → `200`. - `POST /api/pair` (authenticated) → `{"code":"…","expires_in":300}`; `GET /auth/connect/{code}` (unauthenticated, single use) → `{"token":"…"}`. The returned token is then accepted as the Basic password with user `opencode`; it is not a bearer token, a cookie or an api-key header. Changes: - `internal/opencode/pair.go` (new): `PairEndpoint` performs the pair exchange (`POST /api/pair` then `GET /auth/connect/{code}`) over the shared `nativeRequest` transport, so it keeps the same auth, bounds and JSON checks; `ReadServiceCredential` reads the operator's local service password (private file rule); `OpenEndpointAttached` resolves the credential in precedence order — explicit password file, a paired token stored by an earlier run, then a fresh pairing bootstrapped by the local service credential — stores the token in an owner-only file and re-pairs once when a stored token is refused (401). The paired token is written 0600 through a temp file and rename and is never logged. - `internal/opencode/endpoint.go`: `OpenEndpoint` now wraps `probeEndpoint`, which returns the connection even on failure; `Connection.unauthorized` (set by the request paths on HTTP 401, cleared per probe) lets the attach tell an authentication refusal from any other refusal. - `cmd/pipelines-server/main.go`: the endpoint attach uses `OpenEndpointAttached` with the paired-credential file beside the pipeline database (`/opencode-endpoint.json`). An endpoint that cannot be attached logs a line naming it and **falls back to the server's own OpenCode instance** instead of leaving chat refused. - `internal/protocol/status.go`, `internal/server/websocket.go`: `get_status` gains an `opencode` object (`health` = `endpoint` | `fallback` | `spawned` | `unavailable`, plus the endpoint `url`), the honest status evidence for the fallback. `Options.OpenCodeStatus` carries it; no credential is ever placed there. - Tests: `internal/opencode/pair_test.go`, `internal/protocol/status_test.go`, a `TestStatusReportsOpenCodeAttachment` case in `internal/server/status_test.go`. ## Verification (17 Oct 2026) Scratch server only, deployed server untouched; `go build ./... && go vet ./...` and `gofmt -l .` clean; `go test ./internal/... ./cmd/...` green. Live check with `-addr 127.0.0.1:` and `-db /pipelines.db`, `PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:49374`: - `get_status` → `{"opencode":{"health":"endpoint","url":"http://127.0.0.1:49374"}}`; `/opencode-endpoint.json` written mode `-rw-------`. - `chat_sessions` (empty registry) → 0 sessions; `chat_adopt ses_eb3c685f0ffe…` (an operator session) → recorded; `chat_create ` → a new operator session; `chat_sessions` → both. - `chat_prompt` on the created session → `turn completed: 4 frame(s), 1 text frame(s)`; `chat_messages` → 2 turns. - **Restart**: stopped the scratch server (SIGTERM), started it again on the same database. `get_status` → `endpoint`; `chat_sessions` → the same 2 sessions; `chat_messages` → the same 2 turns; the paired-credential file's mtime and size were unchanged, so the stored token was reused, not re-paired. - Fallback: `PIPELINES_OPENCODE_ENDPOINT=http://127.0.0.1:1` → log `OpenCode endpoint http://127.0.0.1:1 could not be attached (…); falling back to the server's own OpenCode instance`, and `get_status` → `{"opencode":{"health":"fallback","url":"http://127.0.0.1:1"}}` with chat still served by the spawned instance. Not verified: whether the V2 service rotates/invalidates paired tokens across a restart of **the service itself** (the operator's service was never restarted); whether a containerised/remote Pipelines server can reach the local `service.json` bootstrap (it cannot, so it would need the password-file path). ## Shared documents this change makes stale The note is written here rather than edited in place; the `docs-fold` writer should update these when it next folds notes. - `docs/cli.md:354` — the `### Choosing the endpoint` section says a failure "disable[s] chat … never a silent fallback". It should now say: the broker authenticates to a V2 endpoint by pairing (`POST /api/pair` then `GET /auth/connect/{code}`) using the operator's local OpenCode service credential as bootstrap, stores the paired token owner-only (`opencode-endpoint.json` beside the database), reuses it across restarts and re-pairs once when it is refused; an explicit `PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE` still wins; and an endpoint that cannot be attached logs the reason and **falls back to the server's own OpenCode instance** rather than disabling chat. - `docs/cli.md` — the `get_status`/`status` description should document the new `opencode` object (`health` = `endpoint`|`fallback`|`spawned`|`unavailable`, `url`), which is where an unattachable endpoint is reported. - `internal/author/skill/references/operations.md:289` — the endpoint paragraph repeats the same "clear refusal and no fallback" wording and the password-file/username-only credential story; update it for pairing, the stored paired token and the honest fallback, and add the `opencode` status field. Add a dated evidence bullet naming the new tests and the restart check. ## Not stale - `internal/author/install.go`'s managed file inventory: no reference file is added. - `internal/installation/service.go`: no new environment variable, so the autostart variable list and the credential-file handling are unchanged. - `internal/server/AGENTS.md` already points at `cmd/pipelines-server/main.go` for the endpoint choice and at `internal/server/chat_*.go`; no new area-map entry is needed.