@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/docs/agent-setup.md

@@ -0,0 +1,214 @@
+# Let an agent set up Gallivant
+
+Give the prompt below to your coding agent. It can inspect prerequisites, install
+the CLI, create a private config and validate a first task. You handle account
+login and any required trust prompts. Setup does not need access to every private
+repository, and installing the CLI does not start a paid session.
+
+Start with **Codex or Claude and one repository**. Those are the harnesses supported
+by `gallivant init`. [Hosted Agents API](openai-agents.md) uses an explicit config
+instead; [other harnesses](../README.md#harness-support) have different setup and
+capability boundaries. An installed binary alone does not establish working model
+access or safe unattended operation.
+
+## Prompt to give your agent
+
+```text
+Set up Gallivant on this machine using its current docs:
+https://github.com/uchibeke/gallivant/blob/main/docs/agent-setup.md
+https://github.com/uchibeke/gallivant/blob/main/docs/install.md
+
+Inspect the installed version, operating system, Node architecture, existing
+Gallivant config and target repository before changing anything. Use the actual
+CLI --help and the docs matching the installed version. Prefer an already working
+Codex or Claude setup. Preserve existing credentials, settings, running jobs,
+worktrees and uncommitted changes. Report proposed config changes without secrets.
+
+Install/configure the CLI and run the setup checks. If Gallivant is not yet
+published on npm, use the documented source installation. Do not overwrite an
+existing config, weaken security settings, install global hooks, change repository
+protections, sign into accounts or elevate privileges without the relevant user
+authorization. Never ask me to paste API keys or tokens into this conversation.
+Use the provider's login flow or a private credential file instead.
+
+Ask only for missing decisions: target repository and checkout, approved base
+branch, preferred available harness, first task scope, and allowed spending.
+A setup request alone does not authorize inference, pushes or PR creation.
+Prepare and validate a written brief without starting it unless I have authorized
+the first run. Plain-language task preparation also uses inference.
+
+Finish with a short report: installed version/path, config path, selected harness,
+repository/base, doctor results, reviewer and completion evaluator settings,
+remaining blockers, and the exact command to start the validated first task.
+If I authorized that task, start it once, verify the saved run identity and status,
+and give me its dashboard or SSH-tunnel instructions. Do not claim a running or
+completed task unless observed. Do not merge, publish, deploy or alter accounts.
+```
+
+If the user already provided those decisions and permissions, reuse them. Do not
+ask for the same approval again. This guide does not authorize any particular
+provider, repository, spend or broader machine change by itself.
+
+## 1. Inspect before installing
+
+Use the user's shell and package manager; no path to a particular person's home
+is required. The coordinator supports macOS and Linux with Node 22 or newer.
+Linux needs `ps` from `procps`/`procps-ng`. Harnesses and hosted artifact verification
+have their own sandbox prerequisites; see [installation](install.md).
+
+```sh
+node --version
+node -p 'process.platform + " " + process.arch'
+npm --version
+git --version
+gh --version
+jq --version
+command -v gallivant
+gh auth status
+```
+
+A missing command is a prerequisite to fix, not a reason to disable a guardrail.
+Use the distribution's supported package instructions. Check the chosen harness
+version/login using its CLI; `gallivant doctor` performs Gallivant's compatibility
+and configuration checks after setup. Do not print credential files or tokens.
+
+Inspect the target checkout separately from the Gallivant installation:
+
+```sh
+cd /path/to/target-repository
+git status --short
+git remote -v
+git branch --show-current
+git config --get user.name
+git config --get user.email
+```
+
+Replace the path with the actual authorized checkout. Do not reset, clean,
+automatically commit, or switch a dirty checkout. Confirm which GitHub repository
+and base branch the task should use; the current branch is not necessarily the
+approved PR target. Account login and Git identity belong to the user.
+
+## 2. Install and initialize
+
+Use the [current installation instructions](install.md#1-the-command). Before
+the first npm publication, install from source; `npm install -g @uchibeke/gallivant` is only
+an option after the package is published. Avoid `sudo npm install`; use a
+user-owned Node installation or prefix when global installation is not writable.
+Do not silently replace a different installed version while its daemon is running.
+
+After GitHub and the selected harness are signed in:
+
+```sh
+gallivant --version
+gallivant --help
+gallivant init --harness codex
+gallivant doctor
+```
+
+Use `--harness claude` for Claude. `init` is noninteractive; it creates a config
+only when none exists. It does not log in, install hooks or fix permissions.
+If a config exists, skip `init` and preserve its unrelated keys. The normal path
+is `~/.gallivant/config.json`; use `$GALLIVANT_HOME/config.json` if that variable is
+already set. Keep it private (mode `600`). Choose a worktrees directory outside
+the config home, using `init --worktrees /absolute/path` if needed.
+
+Before a real run, finish the [harness guardrail setup](install.md#6-aport-on-claude-code)
+for the selected harness. Some steps require human interaction: for example,
+Codex's initial `/hooks` trust prompt cannot be automated. Report such a blocker
+instead of changing the enforcement level or bypassing it.
+
+Add the authorized repository to `repos` and its approved base where necessary,
+following [configuration](config.md#the-base-branch). Review the config diff without
+printing credentials. Confirm these decisions before dispatch:
+
+| Decision | What must be established |
+|---|---|
+| Repository access | The run can read/push the intended repository; use a selected-repository token where appropriate. Public-only work does not require private-repository access. |
+| Base protections | Required PR/ruleset protections exist. `doctor` suggests repairs; it does not authorize changing organization policy. |
+| Review | The default Codex GitHub reviewer is installed for this repo, another supported reviewer is configured, or the user explicitly chose `reviewer: null` for CI and trusted human feedback. |
+| Completion evaluator | Default APort hosted confirmation needs network access. A local evaluator is an explicit user choice, not an automatic workaround for a failure. |
+| Cost | Confirm `max_iterations`, provider budget controls and allowed spend. `max_budget_usd` is a native per-run dollar cap for Claude; other local harnesses have no equivalent enforced dollar cap. |
+
+Run `gallivant doctor` again and report every failure. Do not treat “signed in
+(API unchecked)” as proof of inference access. `doctor` without extra flags checks
+configuration, credentials and repository access without launching a model run.
+`doctor --probe` launches a real Claude sandbox test when Claude is configured;
+`doctor --send` sends a real notification. Use those only when authorized.
+
+## 3. Validate a first task without inference
+
+In the target checkout, use a new task name that does not already exist:
+
+```sh
+gallivant new first-docs-task
+# Edit docs/prds/first-docs-task.md to describe the agreed task.
+gallivant ready docs/prds/first-docs-task.md --check
+```
+
+With no `--harness` flag, `new` uses the first configured harness. If several are
+configured, pass `--harness` with the harness agreed during setup.
+
+Fill every required section with repository-specific facts. Pick a small useful
+change, such as documenting existing test commands, with concrete acceptance
+criteria and verification. The template deliberately contains placeholders;
+validation must fail until they are replaced. [The PRD contract](prd.md) lists the
+rules. Expected result: every rule says `ok` and exit status is `0`.
+
+`ready --check` reads and validates locally without loading credentials, starting
+a daemon or invoking a model. This is a useful stopping point when setup is
+approved but implementation is not. Do not mark a failing brief ready manually.
+
+If paid preparation is authorized, [natural-language task intake](tasks.md) can
+write the brief instead. Use `task inspect` and returned revision/question IDs to
+continue that same task; do not resubmit it simply because clarification is needed.
+
+## 4. Start once, when authorized
+
+Record readiness, then dispatch the validated brief against the approved branch:
+
+```sh
+gallivant ready docs/prds/first-docs-task.md
+gallivant start docs/prds/first-docs-task.md --base YOUR_APPROVED_BASE
+gallivant status --json
+```
+
+Replace `YOUR_APPROVED_BASE` with the actual branch. `ready` can contact the
+configured completion evaluator and updates the brief; `start` launches paid work
+and permits repository changes, pushes and PR creation within that task.
+It also starts/reuses the daemon and dashboard, and attempts to open the browser.
+Do not launch a second `up` process.
+
+For a headless machine, use `start ... --no-open`. Reach the loopback dashboard
+through SSH instead of exposing it publicly:
+
+```sh
+# On your own computer; replace user@host with the coordinator's SSH destination.
+ssh -N -L 8791:127.0.0.1:8791 user@host
+```
+
+Then open `http://127.0.0.1:8791` locally. Substitute the reported port if configured
+differently. `--no-server` skips the dashboard while keeping task monitoring.
+Keep the coordinator awake and online; there is no automatic reboot/login service
+installer. Startup is not a system service installation.
+
+Save the reported task/run handle, worktree and status. If startup returns an error,
+inspect `status` and `why HANDLE` before retrying: work may have started before a
+service or browser failed. Diagnose network problems with
+[the bounded network check](network-recovery.md). Send corrections with
+`say HANDLE --note "..."`; use `resume HANDLE` for a stopped execution and
+`recheck HANDLE` for an eligible PR review check. Neither is a blind retry for
+unknown provider state.
+
+`cancel HANDLE` fences further dispatch and requests provider cancellation;
+confirm its status. `down` stops monitoring/dashboard services but **leaves active
+agent processes running**. A ready-for-human result still requires the owner's
+review and merge.
+
+## What setup verification proves
+
+The package's `npm run test:install` smoke test installs the tarball into a
+throwaway directory, uses fixture CLI credentials, initializes a private config,
+loads the packaged PRD template, and checks an offline brief. It does not use a
+real account, invoke a model or certify a provider's current availability.
+A first authorized end-to-end task is still needed to verify the user's actual
+repository permissions, provider entitlement, sandbox, CI and review integration.

package/docs/app.md

@@ -0,0 +1,111 @@
+# The app and the orchestration boundary
+
+Gallivant has a local browser dashboard, a CLI, and a shared task-delivery API.
+They use the same task state and review coordinator. The dashboard shows what is
+running, what needs attention and why; you can send a correction or resume an
+existing run without finding its terminal session.
+
+For a first run, use [installation](install.md) and [natural-language tasks](tasks.md).
+The work can be code, documentation, research or another verifiable repository
+artifact. GitHub pull requests remain the delivery surface; arbitrary browser
+chores, email delivery and deployments are not separate supported task targets.
+
+## Start the dashboard
+
+```sh
+gallivant start
+```
+
+This ensures the daemon and dashboard are running, then opens the browser at
+`http://127.0.0.1:8791`. `gallivant serve` uses the same startup path. Pass
+`--no-open` to keep it in the background, `--no-server` to omit the dashboard,
+or `--no-daemon` when you manage the coordinator separately. See
+[commands](commands.md) for port selection, foreground mode and service ownership.
+The dashboard is a local control surface, not a publicly exposed server.
+
+## Work with an existing run
+
+The dashboard and run sidebar share the CLI's status model. A run page shows
+its current state, stop reason, PR link, session history and streamed logs.
+History can be loaded without redispatching work. Provider capabilities, saved
+execution state and artifact summaries are exposed through the same tracker;
+reading a page does not poll a provider or incur inference.
+
+Run actions have different effects:
+
+| Action | Effect |
+| --- | --- |
+| Recheck PR | Ask the coordinator to refresh GitHub checks/review state and apply its normal readiness rules. |
+| Resume agent | Continue the existing task on its current approved instructions. |
+| Message agent | Send an operator correction to the existing session, including after a PR is ready for review. |
+| Cancel task | Request cancellation through the shared provider-aware control path. |
+
+The message composer is separate from the fixed actions. Normally a message waits
+for active work to settle. Local providers with interrupt support offer an explicit
+interrupt option; hosted providers expose only the controls they implement.
+Requests are queued, and the daemon must be running to apply them. Messages keep
+the brief, permissions and consumed budget; they do not authorize a new scope,
+merge or deployment. Changing the delivery contract requires the explicit
+resnapshot flow. Closed or merged PRs require a new task.
+
+The current dashboard controls existing registered runs. Prepare new work through
+`gallivant task` or `new` → `ready` → `start`. The exported
+[task-delivery package](task-delivery.md) lets an authenticated host provide its own
+intake UI/MCP surface without implementing another runner. That package is not
+evidence that a hosted service or plugin integration is deployed.
+
+## The browser boundary
+
+GET routes read saved state. One `POST /api/run/control` route queues a bounded
+operator request under the shared mutation lock; the daemon performs the action.
+The POST requires a loopback peer, a loopback Host with the actual serving port,
+an exact same-origin header and the server's CSRF token. Remote readers receive
+no control token. There is no arbitrary shell command route.
+
+These checks resist cross-origin requests and DNS rebinding; they are not
+multi-user authentication or isolation from another process running as the same
+OS user. Keep the standalone tracker on loopback. A server mounting the tracker
+owns its authentication and bind address. Do not expose it through an unauthenticated
+proxy. CSP, HTML escaping and text-only log insertion protect rendering of
+repository, reviewer and agent-controlled text.
+
+`mount(ctx, {base})` lets an existing dashboard, including Command Center, delegate
+a path prefix. The tracker provides SSE logs with a bounded initial tail,
+`Last-Event-ID` continuation and explicit history gaps. The CLI, standalone UI and
+mounted UI retain one coordinator and one set of run identities.
+
+## Local and hosted harnesses
+
+Five local CLI adapters and OpenAI Agents API are implemented. Claude, Codex and
+Agents API also have bounded natural-language preparation. Codex Cloud has a
+transport but new dispatch is unavailable until the chosen environment can be
+verified against the intended repository. [Configuration](config.md#execution-providers)
+and the provider guides distinguish implemented capability, account access and
+live qualification.
+
+A hosted harness moves implementation compute off the device; it does not move
+Gallivant's coordinator, GitHub publication or local verification. If this machine
+sleeps, orchestration waits for it to return. Running the coordinator on a Node
+host you operate requires its durable state and appropriate verification isolation.
+Gallivant does not currently sell or provision that host for you.
+
+Provider credentials and models belong to the selected harness/provider setup.
+A subscription, API key or dashboard connection is not automatically usable by a
+different transport. Costs depend on provider pricing, caching, task duration and
+review rounds; Gallivant does not promise that API use is cheaper than a subscription.
+See [execution](execution.md) for cost visibility and limits.
+
+## Product decisions and future work
+
+Gallivant owns the delivery contract, session ownership, retry bounds, review
+feedback and completion evidence. Harnesses own tool execution and context
+management. Adding a provider extends that boundary; it does not add a second
+agent loop. Thin CLI adapters and durable hosted transports share the same review
+state machine even though their execution details differ.
+
+Earlier product exploration proposed a native desktop wrapper, managed hosting,
+per-round harness routing and bundled provider plans. These remain possible
+future directions, not capabilities enabled by this release. A desktop shell
+would add conveniences such as an application icon; the browser dashboard already
+provides run controls. Any future routing must preserve explicit provider consent,
+authority, continuity and budget ownership rather than silently switching a run.

package/docs/architecture.md

@@ -0,0 +1,265 @@
+# Architecture
+
+Gallivant separates task intent, execution and delivery. Natural-language intake
+prepares a canonical brief, or an operator supplies one directly. One coordinator
+starts implementation, watches GitHub reviews/checks, resumes corrections and
+checks completion evidence. Code, documentation and research use the same model
+when their outputs are reviewable repository artifacts. Integration remains a
+human merge decision.
+
+The capability registry includes five local CLI adapters and hosted OpenAI Agents
+API. Codex Cloud is recognized but new dispatch is blocked on environment/repository
+verification. [Execution](execution.md) describes durable transport ownership;
+[preparation](preparation.md) describes the narrower drafting authority. Hosted
+agent compute does not remove the local/Node coordinator or its durable state.
+
+Repository review learning uses one coordinator-owned [learning service](learning.md)
+for CLI and daemon observation, candidate dispositions, signing, transition recovery
+and bounded shared inputs. Its state lives outside checkouts under the operator home;
+coding-review cursors and budgets remain separate. Canonical JSON is authority,
+escaped review text is a view, and only exact enrolled OpenSSH signatures authorize
+transitions. Installed execution isolation remains UNQUALIFIED, so production
+setup/extraction/application refuse activation. The [carried design](https://github.com/uchibeke/gallivant/blob/main/docs/plans/review-feedback-learning.md)
+remains normative; the [qualification record](https://github.com/uchibeke/gallivant/blob/main/docs/audit/learning-qualification.md) lists gaps.
+Shared inputs carry validated task/event paths for scope selection. Explicit fresh
+learning continuity records its intent in the registry and execution boundary,
+retaining task history and cumulative allowance while fencing the old session.
+
+One actor, one file of rules, everything else is plumbing. Plain ESM; one bundled TOML parser handles isolated Codex configuration without inventing another config parser.
+
+```
+bin/gallivant.mjs        CLI: parse args, build the context, call one command
+lib/context.mjs          wires the real dependencies once (config, state, gh, git, notify, log, runner)
+
+lib/tick.mjs             the state machine. Settle runs, fetch, terminal states, events, dispatch, ready, silence.
+lib/chains.mjs           approved linear plans; dispatch after confirmed merges through the same start path
+lib/start_contract.mjs   shared start validation, exact input fingerprints and carried-file preservation
+lib/events.mjs           pure rules: what counts as an event, trust, reviewer verdict, green checks, round counting
+lib/prompt.mjs           start, register and fix prompts; quoting and caps
+lib/harness.mjs          capability registry plus local argv, session, outcome and sign-in adapters
+lib/tasks.mjs            natural-language intake, revisions, validation, readiness and explicit execution consent
+lib/task_delivery.mjs    authenticated host operation boundary; delegates to the same task service
+lib/execution.mjs        durable local/remote dispatch, ownership, observations and recovery
+lib/execution_result.mjs owned hosted artifact verification and coordinator publication
+lib/control.mjs          shared queued recheck, resume, message and cancellation controls
+lib/block.mjs            the PR body block: render, strict parse
+lib/prd.mjs              the contract: frontmatter, sections, rules, criteria, Verify commands, and the comparison of
+                         the daemon's snapshot with the operator's own copy. Takes a Request, not a file
+lib/hash.mjs             one fingerprint spelling: twelve hex characters of a sha1, for the receipt and the contract
+lib/sources/             direct brief-source adapters; PRD files today (intake generates the canonical brief)
+lib/deliverable.mjs      the completion gate: criteria from the PRD, the receipt, the policy's rules and deny codes
+
+lib/public-format.mjs    neutral GitHub names and legacy read aliases
+lib/gh.mjs               daemon GitHub access through gh; public write validation and status-label migration
+lib/git.mjs              per-PRD checkouts (partial clones), the base-branch merge, run environment
+lib/run.mjs              detached runs; liveness checks that the pid still runs the harness, adapted from command-center
+lib/state.mjs            the registry: atomic writes under a lock file, pure ids, handle resolution
+lib/config.mjs           defaults, validation, path expansion
+lib/notify.mjs           ntfy messages and the throttled error class
+lib/probe.mjs            health checks shared by doctor, start and the daemon
+lib/aport.mjs            what APort's installer leaves on disk: the mode file and the audit log, one parser each
+lib/log.mjs, fs.mjs, time.mjs
+
+lib/tracker/stream.mjs   the SSE log tail: bounded first read, resume by last-event-id, follows the log file
+lib/tracker/runs.mjs     the index over ~/.gallivant/runs, and the id checks every route goes through
+lib/tracker/pages.mjs    the pages: escaping, the sidebar and its groups, the run detail pane, the CSP
+lib/tracker/assets.mjs   templates/tracker/{tracker.css,tracker.js}, read once, plus the ?theme value
+
+lib/commands/            start, register, up (daemon + reconcile), status, why, doctor, serve
+test/                    node --test; helpers.mjs holds the fakes
+templates/               passport, Claude sandbox settings, PRD, tracker/{tracker.css,tracker.js}
+```
+
+## Design rules
+
+New intake tasks targeting `delivery_ready` stop automatic observation and fixing
+at the qualified saved handoff. Explicit queued recheck/resume/message controls
+reopen the workflow. `integrated` targets and legacy written-PRD runs retain
+monitoring. `completionStopsAutomation` and the exported `coordinatorEntryActive`
+keep core and host schedulers aligned. The review transitions below apply while
+an entry is monitored; malformed or incomplete delivery proof cannot mark it
+finished or suppress work.
+
+Harness implementation and demonstrated support are separate. The [live support matrix](https://github.com/uchibeke/gallivant/blob/main/docs/audit/harness-live-validation.md)
+records installed versions, provider/model combinations, permission boundaries, budget controls and blocked phases.
+Claude/Codex have existing production evidence; Gemini, OpenCode and Goose currently have blocked or failed coding attempts,
+not successful start/resume proof. Provider subscription eligibility is independent of the harness adapter.
+
+Repeat with `npm run test:live-harnesses -- --live` after the recorded operator remedies. The opt-in
+`test/live-harnesses.mjs` is outside `test/*.test.mjs`; it uses the existing `buildRun`, `runEnv`, `makeRunner`,
+version probe and outcome/session readers. Test-local native model overrides do not add per-task model selection
+to Gallivant. `test/live-support.mjs` verifies model evidence, adapter identity, actual test tool execution, files,
+behavior, commits, upstream and remote HEAD. Calls are sequential, at most 180 seconds per turn and 30 minutes
+per suite, with one start/resume pair and at most one justified targeted retry per combination. Refusals stop
+the affected phase; they are never converted into permission overrides. Ordinary command stderr such as
+`Permission denied`, `Operation not permitted` or `PermissionDenied` is retained for investigation without
+triggering an approval stop. Sandbox classification requires workspace/sandbox context; explicit permission
+requests/rejections and guardrail decisions still stop the turn. Raw streams and exports stay private.
+Recognized unsuccessful native outcomes (such as an aborted OpenCode step) are recorded as
+`native-failure`, not adapter defects. The retry gate checks both saved outcome metadata and the
+current parser's reading of the saved stream; a source change cannot qualify these failures for retry.
+Goose's textual provider-error prefix must start an assistant message/content block. The adapter reads
+across streamed chunks from those boundaries, preserving native failures after earlier output without
+treating error examples embedded in prose or code fences as failed turns. Typed native errors remain failures.
+Named Meta/xAI/Alibaba cases use Goose's native saved providers and OpenCode's separate Console BYOK
+providers; they do not establish Zen/Go subscription access. Exact batch commands and blocked results are
+in the audit. DeepSeek is excluded from new calls and Tencent remains deferred.
+
+Every OpenCode turn pins `--model` to the case's recorded provider/model, including the existing-default
+case. An unknown, incomplete or routing-alias default blocks before fixture creation or launch. Changing
+native defaults afterward cannot change that pinned argument, and exported model evidence must match the
+recorded selection on both turns. Named Console providers keep their exact selectors.
+Goose likewise requires known provider and model selectors before fixture creation or turn reservation;
+both are always passed explicitly. Missing or unparseable settings block without falling back to its
+mutable default. Native environment/settings and the named Meta/xAI/Alibaba selectors remain supported.
+
+Disposable turns clear inherited Git/GitHub/SSH, credential-manager and editor askpass variables, then
+restore `runEnv`'s Git identity and isolated config with terminal credential prompts disabled. Git accepts only
+file transport and its SSH command refuses execution, preventing default SSH identity fallback while keeping
+provider `HOME` intact. Disposable environments override `GH_CONFIG_DIR` with `/dev/null` and disable gh
+prompts: gh fails configuration loading before stored-account, keyring or API lookup. An empty gh config
+directory alone does not prevent keyring fallback. Production `runEnv` keeps its separate gh configuration.
+Child-environment controls do not replace native sandboxing. Short-lived callers use the
+runner's `waitForKill` after requesting a stop so the process-group fallback runs before exit; the live suite
+also waits before metadata export. Signal/watchdog callbacks defer checkpoints to the main async path;
+failed ledger or runner metadata writes still reference and await the kill fallback before surfacing
+the error. A pending kill owns its exit record, so an early leader exit cannot cause another metadata
+write failure before descendants are stopped. An append can
+reuse a version-blocked case after upgrade only if it has no turn, retry reservation or fixture, within the
+original deadline and with the recorded provider/model unchanged.
+
+Runner startup is awaited by initial dispatch, resume/fix dispatch, and the live suite. The runner
+owns its freshly spawned PID until it returns a recorded job; a failed `job.json` or `latest-run`
+write terminates that process group and awaits the existing kill fallback before rejecting. This
+cleanup uses the in-memory job even if disk bookkeeping is missing or truncated. Startup-error
+callbacks cannot repeat failed writes, and the parent's log descriptor closes on every startup path.
+Live turn reservations remain spent when startup bookkeeping fails.
+
+The shared runner pins child `PWD` to its requested working directory. OpenCode 1.18.31 prefers that
+environment variable for its tool directory, so changing `spawn.cwd` alone is insufficient. The live suite
+checks native session directory evidence and stops on a mismatch; start fixtures must have no prewritten
+files or remote commits. See the audit's directory incident and recovery record before repeating a failed case.
+An eligible start retry gets a distinct pristine checkout/remote while retaining the original fixture and
+turn evidence; resume retries still require the last passed checkout and remote state. Retry and time limits
+are unchanged, and no historical failure or exhausted retry is relabeled by these fixes.
+
+Every turn reserves its case, fixture, source, invocation and running record in the atomic ledger before
+launch, including first starts and resumes. The reservation points to the private runner directory even if
+a crash prevents recording the job ID. A running reservation cannot be appended or retried as an unspent
+case; inspect its private runner evidence and resolve any surviving process before scheduling further work.
+The final deadline check includes reservation I/O and releases the reservation only when no launch occurred.
+
+A passing disposable test would still not establish GitHub review/completion behavior. Full support requires
+an authorized PRD through `ready`/`start`, PR creation, review/CI feedback, a same-session pushed fix and the
+completion gate. Keep that lifecycle evidence separate from session fixtures and disposable local Git tests.
+
+- **The daemon owns automatic transitions.** Operator commands record starts, controls and approved plans; the tick settles runs, handles reviews and advances chains. Local completion is observed using recorded process ownership and output; remote completion reconciles the exact saved provider job/session/turn. Durable identities allow a coordinator restart without launching duplicate work.
+- **Rules are pure.** `events.mjs` takes the raw shapes `gh` returns and produces events. Every rule in the PRD has a unit test with no network.
+- **One gate, and the brief is a Request.** `check()` takes a source-neutral Request, `{ id, repo, title, body, harness, status, source: { kind, url, author }, raw }`, plus the parsed fields the rules read. A source under `lib/sources/` reads whatever the operator typed and produces one; the direct source adapter accepts a PRD file. Natural-language intake uses the same canonical representation after bounded preparation and validation, rather than adding another completion gate. Two things follow. A rule that depends on where the brief lives rather than on what it says carries its own scope as data (`kinds: ["prd"]`: `path`, and `sources` because it resolves the files a brief carries against the repository root that path gives it), so a source without a path is not failed for a rule it cannot satisfy. And `repo` is a field the source fills in, not something a command derives: `start` reads `request.repo` and never calls `git.toplevel` itself. Adding a source is an adapter plus somewhere to record its verdict, never a second gate.
+- **Dependencies are injected.** `makeTick` receives `gh`, `git`, `runnerFor`, `notify`, `clock`. The test suite builds fakes in `test/helpers.mjs`; the CLI builds real ones in `context.mjs`.
+- **Per-harness knowledge lives with the adapter.** `harness.mjs` owns each CLI's argv, its session id shape (`isSession`), its sign-in check and the command that fixes a failed one (`signIn.fix`). `HARNESSES` in `config.mjs` derives from the shared execution registry, including remote capabilities. A rule about a harness written anywhere else goes stale the moment an adapter is added: a UUID regex in `block.mjs` was refusing goose's and opencode's real session ids, and `doctor` was telling three harnesses to run `codex login`. Everything that can put a session id into argv goes through `isSession`, the block and `register --session` alike, because `assertSafeArgv` matches flag spellings and cannot judge a value in a position it does not expect.
+- **GitHub is the source of truth for identity; the registry for counters.** Both can be rebuilt: identity from the PR block, counters from the daemon's own marked comments (every round posts one, a reset posts one).
+- **Four cursors, one meaning each, and none of them goes backwards.** Monotonicity is enforced in `advanceCursor`, not asked of each caller: three callers pass a boundary from a different source (the newest event dispatched, the head commit's committer date, a local clock reading) and a candidate before the cursor is refused outright, keys and all. `since`: events at or after it are new. `fixed_sha`: the head the loop last acted on, both the head when the last run started, so a push by a fix run is the head moving, and the head a ready entry was judged on, so a push after that reopens it. `checks_sha`: the head whose failing checks were already dispatched. `receipt_hash`: the completion receipt when the last run started. `since` is inclusive because GitHub stamps events to the second, so two that arrive in the same second share a timestamp; `dispatched` rides alongside it with the ids already handled at exactly that instant, and is cleared the moment the cursor moves to another second.
+- **One run per entry is the lock.** A run root per entry means a second dispatch for the same PR is refused by the runner while the first is alive, and entries never block each other.
+- **Every wait is bounded, and every stop has a reason.** Five steps in the tick decline rather than proceed when one GitHub write will not land, because proceeding would leave a worse state than waiting: the ready-label removal before a dispatch, the same removal before a moved head is judged, the identity block write a start run must land before it can leave `running`, the ready-label write that makes a judged PR say a human may merge it, and the round comment a settled round owes the PR. The fifth declines the rest of its tick rather than the round it announces, because the round is a push that already happened; the other four decline work that has not happened yet. All five are right to wait and none of them may wait forever, so `entry.retry` counts the CONSECUTIVE failures of one named write and the entry stops with `stuck` at five, naming the write and what GitHub said. The count resets the moment that write lands, so an entry whose GitHub came back is never stopped for the ticks it spent failing, and a different write failing starts its own count rather than adding to the old one. One mechanism for all five, and for any sixth: the recurring defect in this codebase is the same invariant enforced on one path and not its sibling, so a second counter would be the next finding. What makes a step belong here is not the write but the shape, so the list is expected to grow: the step declines, the entry stays in a state the next tick re-enters, and nothing else about the entry has changed. Two of the five were added a round after the first three, both found by enumerating the writes rather than by a failure report. Five is a constant with a comment in `tick.mjs` rather than a config key: the only question it answers is "transient or permanent", ten minutes at the default `poll_seconds` outlasts a rate-limit window and falls far short of a revoked token, and `max_iterations` is the wrong knob because it counts rounds that cost money where these cost one API call.
+- **The snapshot is authoritative against the session and disputable by the operator, and those are two different rules.** `start` copies the brief into `~/.gallivant/prds/`, and the files it names in `sources` into `~/.gallivant/prds/<id>.sources/`, and the gate reads only those, which is what stops a session widening its own acceptance criteria. It does not stop the operator editing their own copy, and until the comparison existed nothing noticed: a run finished against criteria nobody was asking for, and the PR arrived satisfying a document that had changed. So the two files are compared, in the contract's own terms and no others (ordered criterion IDs/text, Verify commands, harness, context paths, carried-source paths, and any coordinator delivery ownership contract), and the verdict decides the action. A brief edited outside those fields is followed silently, because an entry stopped for a reworded Problem section is an entry whose operator learns to ignore this. A brief whose contract moved stops with `prd-changed` and the specific difference, because ADDED (valid but incomplete) and REWRITTEN (invalidated) are the same event in two files of text and guessing wrong is expensive in both directions. A brief that no longer passes the contract is `prd-illegal` and never reaches the snapshot, since one `start` would have refused is worse behind the gate than one merely out of date. A brief deleted is `prd-gone`. An entry with no recorded checkout, which is every entry `register` and `reconcile` build, compares to `unknown` and carries on, so recovery from GitHub is not made useless by a tree it was never told about.
+
+  **The verdict is a fingerprint's, and the diff only explains it.** `sameContract` compares `prdFingerprint` over the whole ordered contract; `contractDiff` produces the lines a person reads. Keeping those two jobs apart is the fix for a family of false negative, not tidiness. A diff has to group and set-subtract to be readable, and set arithmetic loses information: a second `- \`npm test\`` in the Verify section leaves every element of both lists present in the other, so the diff is empty while the commands the session must run green have changed. Reordering two criteria is the same shape, and it got its own targeted fix (the criteria are compared as `id: description` pairs, because `criteriaFromPrd` numbers them by position and the receipt on the open pull request attests those numbers, so a swap leaves both ids meaning the other thing and the receipt attesting each criterion with the other's evidence). A targeted fix per shape is a bug per shape nobody has thought of yet, so the verdict asks the one question a hash answers exactly, and a `changed` verdict whose diff came back empty says so in as many words rather than stopping an entry with nothing to show for it.
+
+  One reason this comparison had to fix `parseFrontmatter`'s line endings on the way past: the regex matched `\n` only, so a CRLF copy of a brief parsed as having no frontmatter at all and fell back to the default harness. That was survivable while `ready` was the only reader, with an operator in front of it. It stops being survivable when the brief is compared against a running entry, where a `.gitattributes` change reads as the harness changing and stops a healthy run blaming the wrong thing.
+
+  **Where it runs, and why the daemon reads the operator's tree at all.** Two halves, one implementation in `prd.mjs`. The tick owns automatic completion transitions, so a comparison that lived only in `status` and `why` would be a warning while the daemon finished the work anyway. But it does not run every tick on every entry: `entry.checkout` is a path on the operator's machine, and a stat and a parse per entry per poll for something that changes a handful of times per run buys nothing, while an unmounted volume would read as `gone` and stop healthy entries. So the daemon compares at the one point the contract is USED to certify something, immediately before the completion gate, and everything earlier (a fix round for a review, a round counted for a push) proceeds against the brief the session holds, because a dispatch is not a claim that the brief is satisfied. `status`, `why` and `resume` compare on demand, in the operator's own session where reading their checkout is unremarkable and where they are asking the question. **While a `prd-changed` stop is unresolved the gate judges neither brief**: the snapshot certifies one the operator abandoned, the edited copy certifies criteria the session never saw and never attested, and there is no third brief.
+
+  **A re-snapshot is an explicit act with an audit trail.** `ensurePrdSnapshot` is still the one writer and still refuses to overwrite; what changed is that the refusal is no longer absolute, because a brief the operator has deliberately edited can only become the brief the gate judges by replacing the snapshot. `resolvePrdSnapshot` is the only path to that, reached only through `gallivant resume --resnapshot`, and it warns with the file, who asked and every difference, in the same spirit as the existing line that says the session could have edited the copy it took. `retakePrdSnapshot` shares the writes for the silent case so a third caller cannot invent its own way to put a file in `prds/`. And the fingerprint is `shortHash` in `lib/hash.mjs`, which `receiptHash` now calls too: one spelling of "twelve hex characters of a sha1" rather than two that agree today.
+- **Adapters own the flags.** Local config selects executable/settings paths; remote config selects explicit account, model, environment, network and allowance. Neither is an arbitrary argv escape hatch. CLI adapter changes still pass `assertSafeArgv`, which refuses `--dangerously-*` flags regardless of their source.
+- **Reuse over build.** `gh` for the API, the harness's own resume and no-prompt flags, APort's own installers, ntfy's email header, command-center's runner layout so its log viewer can read a Gallivant run.
+- **One value, resolved in one place.** The base branch is read by three things that must agree: the branch the checkout is cut from, the `gh pr create --base` the session is told to run, and the branch merged in before each round. `resolveBase` in `config.mjs` is the only thing that decides it, from the flag, then the repository's entry in `repos`, then the repository's default branch. Three callers working it out for themselves would agree by luck, and the failure when they stopped agreeing would be a pull request opened against a branch nobody chose.
+- **Automate delivery; humans approve integration.** Chains advance only on a confirmed merge into their approved base. A successful process, `ready-for-human` or `done` is not a dependency signal. The implementation stays a linear queue inside the existing daemon, without automatic merges or stacked branches.
+
+## Chains
+
+`gallivant chain` records an approved linear plan in the same `state.json` as the run registry: ordered task IDs,
+repository and base, input fingerprints, progress and dispatch ownership. The CLI approves the plan; the daemon
+dispatches its milestones through the ordinary start path. Every milestone is a new task in one repository and on
+one base, with the existing contract, credential, harness and completion gates.
+
+A successor waits for fresh GitHub evidence that its predecessor's PR is `MERGED` into the planned base. The base
+used by the new checkout must contain that merge commit before an agent starts. `CLOSED` stops the chain, while an
+ordinary `needs-human` task stays the current milestone and uses existing run recovery. The final merge completes
+the plan. Human review time is an intentional wait, not an iteration to spend or a timeout to work around.
+
+Registration reserves future task IDs. A durable start claim is written under the registry's lock before clone or
+spawn, preventing a CLI start from racing a queued dispatch. The claim is cleared atomically when the run entry is
+recorded. No state lock is held across network calls. On recovery, a recorded run can be reconciled; a start whose
+outcome is ambiguous stops visibly instead of risking duplicate work. `--retry` does not discard that claim.
+
+Queued PRD and source fingerprints cover the bytes handed to the start path. Changed inputs require explicit
+`chain --retry --resnapshot` approval for unstarted tasks; active tasks retain their normal `resume --resnapshot`
+flow. Carried inputs cannot silently replace base files changed since plan approval. Cancellation prevents future
+dispatch without removing or stopping an active task. See [chains](chains.md) for operator commands.
+
+Queued plans cannot be reconstructed from PR metadata: GitHub has no representation of approved work that has not
+started. Existing PR recovery remains unchanged, but preserving `state.json` is necessary to preserve a chain.
+
+## The tick, step by step
+
+For each registry entry that is not `done`:
+
+1. **Settle.** Only the run this entry dispatched (`last.run`) is looked at, ownership first: a live run left behind by a reset or a recovery is ignored rather than waited on and then killed and blamed on the entry. If that run is alive and past `run_timeout_minutes`, kill it and stop with `timeout`. If a run ended and is not yet recorded: for a `running` entry, find the PR on the branch, write the block, enter `pr-open` with the event cursor covering reviews that landed during the start run; or stop with `no-pr`. The block write is a precondition of leaving `running`, not a best-effort extra: it is what recovery rebuilds the entry from once `state.json` is gone, so a failure keeps the entry in `running` with `last.exit` still unrecorded, which is the state the next tick re-enters and retries from. The session is saved on the way out so a retry never mints a second one, and the retry is counted: five consecutive failures of that write stop the entry with `stuck` rather than holding an open PR unwatched in silence, and the stop records the PR number so the message and `gallivant why` can link it. For a `pr-open` entry, the head moving or the receipt changing is a round: bump the iteration, record the run's exit, and note that the round comment is owed. A normal code push moves the feedback cursor to the push. A receipt-only or public-text correction preserves the feedback cursor and its dispatched event ids, so reviews arriving during that run remain eligible for the next dispatch. Its announcement uses the run's start time as a separate deduplication boundary, including the whole start second to match GitHub timestamp precision; markers from earlier seconds cannot discharge the new comment debt. Without a push, the reviewer clock also stays unchanged. Then post the comment, in step 4. A successful run with no head or receipt change returns to watching without charging another round; it does not stop merely for making no push. An unsuccessful run stops with `harness-error`, except for an eligible local transport failure: bounded recovery can resume the same session after a persisted backoff. It reconciles any pushed work first and respects iteration limits, cancellation and queued operator controls. See [network recovery](network-recovery.md) for eligibility, deadlines and retry limits.
+
+   The order there is the point. What happened is a push: a harness run spent money and moved the branch on GitHub, and nothing that fails afterwards can un-spend it. The comment is the announcement of that fact, and `max_iterations` bounds review rounds, so a counter that waits for the announcement is a bound that can be exceeded. The comment used to be the precondition of counting, which meant a refused comment left the push on GitHub, the fix in the branch and the iteration unchanged. So the local write goes first and the GitHub write goes last, which is the same rule the identity block write follows from the other side: order a pair so the irreversible half is last, and here the irreversible half already happened before the settle ran, which leaves the replayable half to a later tick.
+2. **Fetch.** `gh pr view --json` for state, head, checks, issue comments, labels and body; REST for reviews and inline comments since the cursor, asked for from a second before it so the boundary second comes back whatever GitHub's filter does with it.
+3. **Terminal and review state.** Merged or closed is `done`. A legacy `needs-human (draft)` stop returns to the watched state; other stops only retry their pending status labels. Structured recovery metadata migrates before further processing, preserving prose, evidence and task identity. A draft is converted to a regular PR, with a fresh reviewer window and remote confirmation on the next tick. Conversion failures use bounded retries without starting a paid correction. This does not satisfy any completion gate or clear an unrelated stop. Conflicting is `needs-human`. The base branch is then taken from the PR's own `baseRefName` rather than from anything remembered, because GitHub is the only authority on where a pull request is aimed: it is how an entry written before the field existed gets one, and how a PR someone retargeted from `main` to `staging` starts being merged against the branch it now targets.
+4. **The round comment.** Owed by any round the settle counted and could not announce, posted here on the tick that counted it and again on every later tick until it lands. Idempotent against its marker, so a comment that reached GitHub under a failed response is not posted twice. It is a count on the same `entry.retry` as the four declining writes, for the same reason: a token that can push but cannot comment never recovers, and the markers on the PR are what a recovery rebuilds the iteration from, so an entry whose rounds are invisible to a recovery must not be left running in silence. What it declines is the rest of this tick rather than the round, because the comment is also the re-review request: an entry that owes one has asked the reviewer nothing, so its silence must not be judged and a second round must not be charged before the first is announced.
+5. **Events.** The rules in `events.mjs`. Failing checks count against `checks_sha`, so red CI on a head the loop itself pushed is dispatched once; if it stays red on that head after the fix, the entry stops with `checks-red`.
+6. **Dispatch.** Past the cap, stop with `iterations`. Otherwise recreate the checkout if it is gone, merge the base branch into the work branch, build the fix prompt, resume the session (or start one for a registered PR), move the cursor to the newest event and record the ids dispatched at that instant, record the run.
+
+   The merge is where a round of work starts from the current base rather than from wherever the base was when the branch was cut, and it is a merge rather than a rebase for three reasons that all live in this codebase. A rebase of a pushed branch can only move with a force-push, which the rules every session is given forbid. `reviewerVerdict` clears a head only when the commit the reviewer named is that head, so a rewrite makes every prior clearance describe a commit that no longer exists, and the reviewer's inline comments are anchored to those same commits. And step 7 reads a head the loop did not put there as a person's push, so a daemon force-push would look to the daemon itself like a stranger pushing. A merge moves the head forward, keeps every reviewed commit an ancestor, and needs no `--force`. An outstanding review therefore does not hold it up, which is the point: a rebase would have had to wait for the review, and that is a deadlock where the reviewer waits for a fix and the fix waits for the reviewer. The merge commit stays local until the session pushes, so nothing on GitHub moves, the reviewer clock is not reset and the round is still counted from the session's own push. It is recorded the moment it succeeds rather than by the save at the end of this step, because four things after it can return early and a merge nobody recorded is a change to a checkout with nothing to explain it. A conflict is aborted and the entry stops with `base-conflict` naming the base, because a half-merged checkout handed to a session as if it were clean is the worst thing this step could leave, and a conflict does not resolve on its own so retrying every tick would loop forever. Four things that would refuse identically on every poll stop the entry instead of looping: a checkout that cannot be recreated (`no-worktree`, with the cause as the event), a harness that refuses the configured `context_paths` (`context-paths`), no GitHub credential (`no-credential`) and no git identity on the machine (`no-identity`, whose event is the two `git config --global` commands that fix it). None of them resolves on its own, and the entry would otherwise redispatch the same feedback every poll with nothing notified. One invariant orders the rest of this step: **a spawned run must be recorded before anything else can fail.** Everything that can throw, the checkout and the ready-label removal included, happens before the spawn, and the registry write that owns the run comes immediately after it with no `await` in between. A process the registry does not know about is the worst state the dispatch can leave, because the settle step reads it as an unrelated leftover and the feedback that caused it is still new, so the same feedback spawns a second fixer when the first one exits. The label removal is the one write that can therefore hold a dispatch back, and holding it back is bounded: five consecutive failures stop the entry with `stuck`. `gh.removeLabel` throws by default and swallows only gh's own "label not found", which is what makes that bound reachable at all: the lenient behaviour was once the default, one of the two callers omitted the flag, and a GitHub that refused the write resolved as though the label had merely been absent.
+7. **Ready.** First, a head nobody told the loop about. Both watching states go through the same check, in one place: `fixed_sha` follows the head, the reviewer clock resets to the push and the nudge becomes available again, because the reviewer has not seen this commit. A `ready` entry also leaves ready with the label off, since its verdict, its green checks and its accepted receipt all describe a commit that is not the head any more. Handling it for `ready` alone used to leave a `pr-open` entry judging the new head with the old head's age, so the same tick that noticed the push could stop it as `reviewer-silent` on a wait that expired before the commit existed, and the nudge already spent on the old head was never reissued. Then, for a `pr-open` entry: no events, no run, not a draft, every check green (none counts as green), reviewer clear or absent. Then the brief, compared with the operator's own copy: this is the only place the daemon reads their working tree, and it is here because this is where the contract is about to be used to certify something. A contract that moved stops the entry with `prd-changed` and the difference named, before the gate runs and without setting `gate_skipped`, which describes the other thing entirely (a PR that reached READY with the gate unrun, where this entry is not reaching ready at all). An edit outside the contract re-takes the snapshot, notifies nobody and carries on. Then the completion gate (`deliverable.mjs`): the PR body's receipt must attest every acceptance criterion of the PRD with evidence; a deny starts a receipt round. A receipt whose shape is wrong is one of those denies, not an exception. The output scan needs the whole diff, so a diff that cannot be read or reaches the 16 MiB scan cap is no decision at all. Large hosted payloads are sent in overlapping pieces within the API request limit, with full criteria and attestations on each; every piece must allow. Unreadable diffs and unavailable evaluators use the same bounded `entry.retry` mechanism as writes, with the cause visible in `status` and `why`; five consecutive failures stop as `needs-human`, without a fixer run or iteration. The label goes on before the registry says ready, so a label write that fails leaves the entry in `pr-open` to be retried rather than a ready PR carrying no label, and those retries are counted on the same `entry.retry` as every other declining write: a token that cannot write labels at all used to repeat the readiness judgement, the completion gate included, on every poll forever, while `status` said the entry was waiting on a reviewer who had already answered. Only then notify, once.
+8. **Silence.** Reviewer configured and quiet since the last request: nudge once after `rereview_minutes`, stop with `reviewer-silent` after `stall_hours`. Draft conversion in step 3 starts a fresh reviewer window, so time spent as a draft does not count as reviewer silence.
+
+The reviewer clock (`rereview.at`) is when the reviewer was last asked about the current head, and all three of those timers measure from it. Its best available value is the head commit's committer date, which is when the commit was made and not when it arrived on the branch, so it is floored at `rereview_minutes` ago: a commit made on Monday and pushed on Thursday must not stop the PR for a silence the reviewer was never given a chance to break. The rule is `reviewerClock` in `events.mjs`, pure and in one place because the tick is not its only writer: `reconcile` sets the same field on a recovered entry and goes through the same function, so a PR whose last round comment is older than `stall_hours` is not stopped `reviewer-silent` on the first tick after a crash recovery for silence that accrued while no daemon was running to ask.
+
+## The tracker
+
+`gallivant start` and `serve` share service startup: daemon, dashboard and browser,
+with explicit opt-outs. Tracker GET routes read the same saved state as the CLI.
+One protected POST queues Recheck PR, Resume agent, Message agent or Cancel task
+through `requestControl`; only the daemon applies the queued action. The POST
+requires loopback peer and Host/port, exact same-origin and a per-server CSRF
+token, plus the shared mutation lock. Reads never drive provider polling. The
+[app guide](app.md) explains the user controls. These rendering rules still hold:
+
+- **One model, three renderings.** The dashboard, the sidebar and `/api/status` all come from `model(ctx)` in `status.mjs`, the same function the text view uses. A group that appears in one appears in all of them.
+- **An id is validated against the registry, not by pattern.** Entry ids contain slashes, so a query string is accepted only when `state.get(id)` returns an entry; the path is then rebuilt from `idSlug`. Run ids go through `run.mjs`'s `[A-Za-z0-9_-]` check. Nothing from a URL is ever joined to a path directly.
+- **The log is followed as a file.** The stream watches `job.log` with `fs.watch` and a one-second timer underneath, not the child's pipes, so a browser attached after a daemon restart still sees a run this process never spawned. It sends the last 400 lines on connect with a `skipped` count, carries an `id:` on every frame, and honours `last-event-id`, so a reconnect resumes rather than replaying. `res.setTimeout(0)` on the response, the request and the socket keeps Node's five-minute `requestTimeout` from cutting a long fix round. This is ported from command-center, where each of those was a bug first.
+- **The log renderer is command-center's, ported.** `renderLine` and its parse come from that project's `public/logline.js` unchanged apart from an inlined escaper, because a Gallivant run log is harness output and that is the shape the file was written for: an indented `Tool: argument` line, or prose, with URLs inside either. Tool calls get their own column and colour, the closing line is coloured by outcome. Text is escaped before anything is built from it, so only markup the renderer itself wrote is ever inserted. A fix to those regexes belongs in both copies.
+- **Everything interpolated is escaped, and the page runs no inline script.** PR titles, branch names, reasons, run names and log lines come from GitHub or an agent. The CSP is `default-src 'none'; script-src 'self'; style-src 'self'`, and the stylesheet and script are files under `templates/tracker/` served on their own routes, so there is no nonce to thread through a response and no hash to keep in step. Untrusted text is escaped before the bounded Markdown renderer builds markup; status messages and heartbeat text use `textContent`. Raw stderr and fenced code retain their literal characters.
+- **Grouping is a link, not state.** The sidebar groups by entry state or by harness, chosen with `?by=`, so a grouped view is something you can bookmark or frame and there is nothing to keep in sync between the server and the page. Two options and a small switch, not a grouping engine. Collapsed state is the one thing the page keeps, in `localStorage` per view; a filter ignores it and shows every match expanded, which is the detail that makes a search feel right.
+- **The palette can be forced from outside.** Every colour, font and spacing value is a `--gv-*` custom property with a default. A same-origin parent can override them; a cross-origin parent cannot touch this document at all, and CSS custom properties do not change that, so `?theme=dark|light` is the mechanism for that case. It stamps `data-theme` on the root element, because the stylesheet defaults to dark, while `?theme=light` explicitly selects its light palette; an embedding page does not automatically change it.
+
+- **The router is separable from the server.** `handle(ctx, req, res, { base })` is the whole of the routing and `mount(ctx, { base })` wraps it as `{ owns, handle }` for a host server to delegate a prefix to, so the tracker can run standalone on its own port or inside a server somebody else starts. Every URL the pages emit is built from the mount path rather than from the root, and the script reads that path from `<body data-base>` since it is one static file that cannot be told at build time where it lives. A mounted tracker inherits the host's bind address and auth, which is the host's responsibility and not something this module can enforce.
+
+Standalone it binds `127.0.0.1` with no account login. Loopback and the POST checks
+protect the browser boundary; they do not authenticate different local OS users
+or constrain another process running as the operator. The mounting host owns its
+authentication and must not expose an unauthenticated tracker to the network.
+
+## Adding a harness
+
+Register one capability entry in `lib/harness.mjs`; `HARNESSES` derives from that
+registry. A local adapter supplies start/resume argv, environment, session and
+outcome parsing, sign-in/version probes, context support and attach behavior.
+Declare and enforce its minimum version, native permissions and safe argv/env.
+OpenCode is already implemented; unsafe auto-approval flags remain refused.
+
+A remote provider implements the [execution transport contract](execution.md),
+including durable acceptance/recovery, account ownership, bounded observations,
+artifact verification and truthful control/cost capabilities. Preparation is an
+optional separate authority boundary, never inferred from implementation support.
+Add regression/installed fixtures and record actual live qualification separately;
+a successful version probe alone cannot establish unattended support.
+
+## Adding a reviewer
+
+No code. Set `reviewer.login`, `reviewer.rereview_comment` and `reviewer.blocking_pattern` in config.