Files
archie/proto
sam 7ef58293be feat(harness): serve a daemon-side setup session to the dashboard
The dashboard's setup terminal was a 503: it had a WebSocket route, an
authorizer and an xterm.js surface, but nothing owned a container. The
daemon owns containers, so the session contract lands there and the
dashboard consumes it over a new gRPC contract.

One session concept, two targets. A setup session is addressed by Kit
profile and is ephemeral; a run session (archie-core-qi91) is addressed by
task and attempt and is bounded by the task. This slice serves setup and
answers Unimplemented for run.

The contract, the authorisation, the lifetime and the egress phase are
settled in docs/prds/external-agent-harness.md, "Session contract". The
short version: the daemon serves harness.v1.HarnessService; the dashboard
authorizes the operator as an update on the secret and then dials the
daemon with the harness service token, required even on loopback because a
session is a shell holding an org's credential; the setup container runs
no worker, mounts no worktree, holds a keepalive, and carries an empty
container environment. Install hooks run at the install phase and the
session enters runtime before the shell, so a runtime-phase credential's
token endpoint is the one the proxy intercepts.

Capture is gated by the egress proxy on a granted service, and a setup
session has no task, so the daemon registers a session grant: the
session's proxy token resolves to the org's bindings for the Kit's
declared services. The real token never enters the container: the token
endpoint response is sentinelized and stored as the org's harness secret.

Every teardown path releases the pool slot, revokes the egress session and
the grant, removes the sandbox network, and removes the session's volumes.
The listener requires HARNESS_TOKEN and stops with a 10s grace before
Stop, so an open session cannot hold shutdown to the watchdog leash.
2026-10-09 01:38:41 +11:00
..

Service wire contracts

Each canonical service owns proto/<service>/v1/*.proto in this single Buf module. The service directory matches its registry, DNS and chart name. Breaking changes require a new v2, v3, etc. directory; retain published versions for existing consumers. Buf's FILE rules compare against local main. The first introduction skips that comparison only when main has no Buf config.

Run task proto:install once to install the pinned Buf and Go plugins, with $(go env GOPATH)/bin on PATH. Run task proto:generate after editing a schema. Managed mode sets Go package paths; do not set go_package in the source. Generated grpc-go and protobuf files belong in internal/contracts/<service>/v1/ and must be committed, including formatter output. This directory is generated in full; handwritten adapters belong outside it.

task proto:lint checks lint and compatibility; task proto:check regenerates and rejects differences or untracked generated files. Both run in task check and the deployment quality gate. Normal build and test commands use committed Go files and do not require Buf.

Compatibility smoke verification (2026-09-05): copied the gateway schema and gate script into a temporary Git repository, committed it on main, and ran the lint gate from a linked worktree. The unchanged schema passed. Deleting ChatService.Cancel then failed with Previously present RPC "Cancel" on service "ChatService" was deleted. This exercises the same Git-baseline comparison as the gate without modifying the working schema or real main.