@uchibeke/gallivant 0.2.0 → 0.3.0

package/docs/first-party-review.md

@@ -0,0 +1,266 @@
+# First-party review gate
+
+This is an opt-in model judgement of an immutable task snapshot. It is **not Git-host bot approval**, proof that every defect was found, or authority to merge, deploy, release or advance a chain. Checks, the completion gate, trusted feedback and the existing human merge boundary still apply. The [qualification record](audit/first-party-review.md) currently records an unavailable native boundary and unmeasured live quality; do not change defaults on the strength of deterministic fixtures.
+
+## Select a policy
+
+New tasks snapshot one version-1 policy:
+
+| Mode | Required evidence |
+| --- | --- |
+| `external-required` | Configured external actor's clear verdict for the exact head |
+| `first-party-required` | Coordinator-owned first-party clear for the exact input |
+| `both-required` | Both, without unresolved disagreement |
+
+A configured external reviewer retains `external-required` by default. There is no bot-installation detection. A repository with `reviewer: null` must opt into a qualified route, or explicitly choose the legacy exception below. Missing, slow, failed and rate-limited required reviewers never count as clear and never select another policy.
+
+For new tasks without a remote reviewer, set these keys in the operator configuration:
+
+```json
+{
+  "reviewer": null,
+  "review": {
+    "mode": "first-party-required",
+    "route": "codex",
+    "specialist": null,
+    "timeout_ms": 3600000,
+    "max_jobs": 2048,
+    "retries": 2,
+    "budget_usd": 100,
+    "max_input_bytes": 100000,
+    "zero_checks": false
+  }
+}
+```
+
+`review` can also be set on a `repos` object. Defaults allow 2,048 total reviewer jobs per task, including fresh-head rereviews and final synthesis, a $100 accounting allowance, two known pre-dispatch retries and 60 minutes per job. Each source piece, reduction and whole-PR synthesis has its own deadline; the limit is not a deadline for the entire PR review. Operators can select up to 8,192 jobs, $10,000 and one hour per job; explicit smaller limits remain enforced. Raising defaults does not silently rewrite saved task policies. The external actor remains the configured `reviewer` object and is copied into each task. `specialist` is either `null`, `security`, or `regression`; general correctness always applies. These are short rubrics, with no policy or requirements authority.
+
+`zero_checks: true` is an explicit operator CI policy for a repository with no required checks. An empty Git-host response alone never establishes that policy for new version-1 tasks. Missing CI stops as `missing-ci`; a missing/disabled completion gate stops separately as `completion-gate-skipped`.
+
+Legacy records are snapshotted as version 0 on reconciliation using their last configured external requirement. An absent reviewer is explicitly displayed as **legacy no-review**, never clearance. Existing runs do not inherit new config policy choices. For an intentional new legacy run, set both `reviewer: null` and `review: { "legacy_no_review": true }`. This grants no review evidence. Back up state before upgrading: historical configurations that were never recorded cannot be recovered from PR prose, so restore the original reviewer configuration before the first reconciliation of old records.
+
+## Qualification and diagnostics
+
+The selected Git host must provide the complete review-evidence operation through
+the shared host registry. An unsupported host or missing operation stops
+qualification before native preparation, including when a saved clear exists.
+GitHub retains `owner/repo` identities. Bitbucket uses
+`bitbucket.org/workspace/repository`; its evidence adapter is implemented, but its
+live private/public review matrix remains a separate qualification requirement.
+No other Git host is supported by this review path.
+
+Use the exact executable in `harness.codex.bin`. Only its restricted preparation profile is implemented as a reviewer route; other coding adapters are unqualified. The review service supplies text in a fresh isolated workspace, disables tools, MCP/plugins, hooks, skills, memories, delegation, telemetry and user/project instructions, denies escalation and network access from model tools, and verifies the effective native configuration including managed requirements. Provider authentication is confined to the native inference connection. The coding session and its context mounts are never reused.
+
+```sh
+gallivant review qualify --repo owner/repo
+gallivant review qualify --repo owner/repo --run --wait
+gallivant review qualify --repo bitbucket.org/workspace/repository
+gallivant review qualify --repo bitbucket.org/workspace/repository --run --wait
+gallivant review status <task-handle>
+gallivant doctor
+```
+
+The run page shows a live reviewer activity feed with the current phase, job
+progress, findings count and handoff state. It is separate from the coding
+agent's log and updates while the page is open; it does not expose reviewer
+prompts, raw output or captured source. Its visible history starts when the
+page opens. The entries dashboard's last-activity time tracks a run, review or
+recorded event, rather than routine coordinator writes.
+
+The first command only reads qualification. `--run` explicitly authorizes a separate bounded live challenge. It returns a running record; repeating the command reconciles that same keyed execution. A failed qualification is retained, not silently retried as a new paid session. Repair the observed provider/native-policy failure before requalification; changed native configuration yields a different qualification identity. A credential/configuration/binary change invalidates qualification. Setup diagnostics and start preflight require qualification and recheck the effective native boundary before author launch. A version/sign-in result alone cannot qualify a route.
+
+For recognized ChatGPT OAuth profiles, routine token refresh retains the same
+qualification only when the selected account, owner, issuer, client and subject
+remain consistent across the locally stored ID and access token claims. A
+changed principal or provider invalidates qualification. The provider still
+validates the actual credentials; unknown formats and API keys use the full
+credential digest and fail closed on changes.
+Unrelated absolute project trust records outside the review root do not change
+the review identity. Records covering the review root and all other effective
+configuration and managed policies remain bound.
+
+`npm run test:first-party-review:live` is the opt-in disposable-repository probe. It requires `REVIEW_LIVE=1`, the normal operator configuration, and an explicit review allowance; ordinary tests never call a model. Do not run it to work around an administrator or guardrail refusal.
+
+Codex does not expose a native USD hard cap or reliable cost receipt here. The coordinator reserves `budget_usd / max_jobs` before each review launch and consumes the reservation even when actual cost is unknown. `max_input_bytes` remains a hard per-job prompt cap (at most 100,000 bytes); it is never raised for a large PR. `max_jobs`, the reserved budget and the per-job timeout bound the complete aggregate. Job count, wall time and known pre-dispatch retries are independently bounded. This is an accounting allowance, **not a guaranteed provider billing cap**. Cost qualification and live spend measurement remain outstanding; configure a provider-side limit before relying on a monetary ceiling. Provider failure requires a person; it never spends a coding fix round by itself.
+
+## Evidence, fixes and migration
+
+The GitHub and Bitbucket adapters capture exact head/base/merge-base IDs, a complete diff, full before/after content for added, modified, removed and renamed files, the immutable PRD and every criterion, checks and the full completion receipt. Bitbucket additionally binds the repository UUID and PR number, consumes every diffstat page, compares that inventory to the raw commit comparison, reads source metadata/content at the merge base and head, and rechecks the PR after capture. Oversized evidence, unsupported binaries or submodule content, omitted patches, duplicate or truncated pages, unreadable snapshots and concurrent PR changes produce incomplete review. API credentials stay in the host adapter; reviewer jobs receive neither host nor Git credentials, and redirects outside the bound API repository are refused.
+
+The coordinator requests PNG and JPEG evidence and plans one restricted visual job per changed side alongside text slices. Captures are limited to 32 image sides, 5 MiB per side and 16 MiB total, with dimensions at most 8192 by 8192 and 16 million pixels. Corrupt, unsupported, oversized or incomplete images fail closed. Text qualification alone does not qualify image attachment, model vision or isolation. Each visual job receives a coordinator-created copy, and its exact image identity is checked again at execution; image text and metadata are untrusted data. A [disposable live screenshot review](audit/bitbucket-review-qualification.md#live-image-qualification-and-disposable-review-2026-11-03) reached a clear whole-PR verdict after recovering its owned outputs; the resend PR remains unverified. Preserve screenshots and an incomplete status when qualification or evidence is missing.
+
+The coordinator requests link-object capture from both host adapters. Bounded UTF-8 target bytes are reviewed as untrusted Git object data at each revision; targets are never resolved or followed. Unsupported targets, ambiguous type transitions, incomplete inventories or mismatched hashes and revisions fail closed. Host and reviewer qualification still applies.
+
+Image qualification is recorded independently for the configured executable bytes,
+model and reviewer configuration. `review qualify --repo OWNER/REPO --capability image`
+reads its status; adding `--run` explicitly starts one bounded image challenge and
+consumes the review allowance. The challenge verifies a coordinator-created copy
+at the execution boundary. It is not an end-to-end PR review or host qualification.
+All image sides, text slices and the whole-PR synthesis must complete under the
+same bounded allowance; missing or mismatched results cannot clear the review.
+An image inspection judges its own image, while a text-only requirement may be
+deferred to synthesis. The coordinator records criteria omitted by an image job
+and carries its unresolved concerns through reductions. The final reviewer must
+evaluate those concerns and all criteria against the combined evidence; an
+unresolved need for visual evidence still blocks clearance. A previously owned
+image output rejected solely for local scope can be revalidated against its
+original input and qualification without launching the image job again.
+
+When the full serialized evidence does not fit one job, the shared service creates immutable byte-bounded source and patch slices. Every piece repeats the same task, repository, PR, head, base, merge base, brief, criteria, checks, receipt, policy and aggregate digest. Long single lines and large lockfiles are sliced with absolute line/column offsets rather than omitted. Every changed path and every criterion must appear in the aggregate, every piece must return a valid matching identity, and all pieces must finish before clearance. A finding in any piece, a timeout, malformed output, missing piece, conflicting finding identity, exhausted job/budget bound or unresolved scope blocks readiness. If the configured aggregate cannot hold the evidence, the result says `review-incomplete`/`REVIEW_INCOMPLETE` with the required and configured job counts; it does not review a prefix.
+
+Split review has two stages. Each local inspection judges only supplied slices,
+records concrete defects and supplies bounded, source-quoted observations for
+the final reviewer. Missing other pieces is expected and does not establish a
+missing implementation. Local clear verdicts cannot clear the PR. If every local
+inspection finishes without findings, a separate restricted whole-PR reviewer
+receives the complete criteria, receipt and checks plus reports or validated
+reductions covering every source piece. It
+must resolve cross-file questions and return its own clear verdict. Empty reports,
+unsupported quotes, unresolved scope and oversized synthesis never clear. Each
+observation is verified against its captured source; final findings must also be
+grounded in a supplied report. An incorrect line number is resolved only when the
+exact single-line quote occurs at one unique line in the supplied file, side and
+slice (or, for synthesis, a supplied report). The original and corrected line
+and a quote digest are retained in the review ledger. Ambiguous, absent or
+multiline quotes never gain clearance from this correction.
+When execution sanitization masks a secret-looking value in a quote, the
+coordinator compares it with the same sanitized form of the captured source
+line. The review result retains the masked quote; matching still requires the
+specified file, side and line or a unique source location.
+
+Malformed output or an unverifiable citation receives up to the configured
+`retries` fresh, tools-disabled reviewer attempts, using the same job, spend and
+time limits. Previous attempts stay in the ledger; an ambiguous launch, tool
+attempt or provider failure is never silently retried as a format error. A local
+scope concern is retained in the ledger and carried through any reductions to
+the final whole-PR reviewer; it is never accepted as clearance. Whole-PR
+unresolved scope remains blocking. Older outputs rejected for citation numbering
+or local-slice scope are revalidated once against the exact original input and
+owned execution.
+A confirmed, terminal Codex model-capacity response receives bounded retries
+after one and five minutes, within the same reviewer job and spend allowances.
+The saved evidence and completed pieces are retained. Authentication, quota,
+policy denials, ambiguous ownership and unrecognized provider errors still stop
+for inspection; no model or provider is switched automatically.
+A new protocol identity retains old failed jobs
+for audit without reusing their incomplete verdicts.
+
+A local-scope inspection still requires final synthesis when partitioning happens
+to produce only one piece; only an actual unsplit whole-PR review may clear
+directly. If the combined reports exceed the prompt cap, the same restricted
+review service reduces them in bounded groups over as many levels as needed.
+Each node binds its child reports and a contiguous coverage range to the original
+aggregate. Missing, duplicate or out-of-order coverage is refused, and the root
+must cover every original piece. All original reports and intermediate jobs stay
+in the durable ledger. Each reduction preserves source-grounded observations;
+any concrete finding blocks instead of being summarized away. A reduction's
+local clear verdict never replaces the final whole-PR verdict. Reduction and
+final jobs consume the same task job, spend and timeout allowances, and restart
+reuses their exact saved inputs and executions.
+
+Source capture remains bounded to 16 MiB overall, independently of the higher
+job allowance. The per-job input remains 100,000 bytes; synthesis must fit the
+same bound. These are evidence and context limits, not spending defaults. Explicit
+task/provider authorizations remain pinned. The intake planner has separate,
+explicitly funded settings: up to 12 calls, 100,000 input and 16,000 output
+tokens per call, $10 and a five-minute request timeout. Those higher ceilings
+do not enlarge a saved task's approved allowance.
+
+The model receives this material as untrusted JSON. The final output must cover all criteria, identify the route/head/input digest, leave no unresolved scope, and report either `clear` or actionable findings grounded in captured source or an exact image identity. Local concerns are carried to that final review. Invalid, partial, timed-out, failed or tool-attempting output cannot clear. The coordinator owns the ledger under `reviews/` and the separate execution namespace under `runs/review__...`. Public comments and agent-authored approval text are never an alternative source of internal clearance.
+
+Polling reuses captured source only when the repository, head and base still match, and rechecks the live PR binding before using it. Changed head, base, checks, receipt, policy or brief invalidates the whole aggregate, not only one piece. Piece keys make restart and repeated host pages idempotent; an old-head or partial aggregate cannot clear. A delayed poll accepts a valid result whose recorded execution completion time met the deadline; missing completion times, late results and executions still running past the deadline cannot clear.
+
+The registry caches validated reads only while the underlying file identity and
+timestamps are unchanged. Returned records remain detached, and another
+process's atomic write invalidates the cache. This avoids repeatedly parsing a
+large registry during review polling without changing write ownership or gates.
+Each review advancement also reuses immutable completed jobs from one ledger
+read, while retaining the same policy, input, binding and reviewer checks.
+
+Between host polls, the coordinator advances an already captured review on its
+local progress cadence. It does not refetch the PR for every piece. Terminal
+local results wake the host lane, which must reread the current binding before
+readiness or author dispatch. An explicit recheck or policy change also wakes
+that lane immediately instead of waiting for the old polling deadline.
+
+Findings use the existing fix dispatch and round counter. Their disposition is recorded. A subsequent push needs fresh evidence. Repeated findings on the same input, required-reviewer disagreement and exhausted fix rounds stop for a person. `review dispute <handle> --finding <id> --reason "..."` records a pending dispute and removes readiness; it has no self-accept operation. A person must resolve the defect or deliberately change policy and re-evaluate it.
+
+Findings remain `pending` during confirmed provider-health waits or a busy local runner. `dispatch-intent` is saved immediately before launch and becomes `dispatched` with the accepted run ID. A confirmed unsent refusal returns the findings to pending but still requires the existing explicit resume; an ambiguous launch retains its intent and requires a person before any retry. Waiting alone consumes no fix round.
+
+Historical review records are stored in the private `reviews/history/` directory
+under the Gallivant home. The registry retains compact references and dispatch
+dispositions; `gallivant review status <handle>` verifies and displays the full
+history. Existing inline history migrates on the next registry write. Back up and
+restore the registry and the review directory together. Missing or changed archive
+files are reported as errors rather than treated as review clearance. Migration
+upgrades the registry format: older releases refuse it rather than changing
+references they do not understand. Stop older coordinators before upgrading.
+
+Transient Bitbucket read timeouts, rate limits and server errors during evidence
+capture are retried through the bounded coordinator retry path. Authentication,
+identity, incomplete evidence and uncertain write failures remain blocking; each
+attempt still captures and verifies the current PR before review or readiness.
+
+Changing head, base, checks, receipt or policy invalidates readiness. Configured external findings and trusted human feedback still enter the shared fix path, including feedback arriving after internal clearance on the same head. The external reviewer must answer again when its previously reviewed input changes. The completion gate remains independent of model opinion.
+
+A newly observed head retains the push-based review window, so a timely exact-head approval that arrived between polls still counts. The same rule applies when an author run settles and advances the feedback cursor. Changes to base, receipt or checks on the same head start a new review window when observed and require a later external answer.
+
+Config edits affect future tasks. For a stopped/settled existing task, use:
+
+```sh
+gallivant review policy <handle> --mode both-required --reason "Require both reviews for this task"
+gallivant review policy <handle> --mode first-party-required --reason "Enable the qualified independent local reviewer"
+gallivant recheck <handle>
+gallivant review retry <handle> --reason "Retry the rejected citation with exact single-line source quotes"
+```
+
+`review retry` explicitly authorizes fresh reviewer executions for incomplete
+output whose previous process exited successfully. It retains completed pieces,
+original attempts, reservations and an operator-reason audit. New attempts use
+the same job/spend/timeout limits and strict validation; recheck alone reuses the
+old terminal record. It also accepts a reviewer cancelled by the coordinator
+after a provider error only after confirming its identity, stopped process tree,
+recorded cancellation reason and absence of tool attempts or denials. Ambiguous
+launches, active reviewers, other provider failures, tool/boundary failures and
+unresolved cancellation cannot use this shortcut.
+The normal host lane rechecks the live binding before review can authorize
+readiness. No author session, PR or chain merge gate is reset.
+
+The command first proves that the selected route is qualified, then records the prior policy and reason, revokes readiness, and re-evaluates the current head. For an existing Bitbucket legacy run, this is the only path that removes `legacy_no_review`; direct config edits do not change its snapshot. The original PRD snapshot, task/run identity, PR, checkout and implementation session are retained. A failed preflight changes none of them and starts no paid review. No command here merges or advances a chain before its existing merge gate.
+
+Policy changes and disputes share per-task process exclusion with review decisions,
+including label publication and notification. If a decision is already in flight,
+the command refuses without changing the policy; retry after that operation
+finishes. A failed label removal leaves a durable obligation for later ticks to
+retry, even while the task is stopped. Clearance stays revoked during that wait.
+
+### Waiting for qualification and explicitly retrying a stopped probe
+
+Use `gallivant review qualify --repo OWNER/REPO --run --wait` to keep the CLI
+alive until its bounded challenge settles. This retains the process exit
+callback; a short-lived launcher can otherwise lose the precise exit time and
+later reject an on-time response as a late observed completion. Normal daemon
+review continues to use its existing lifecycle.
+
+Captured local reviews advance alongside provider and Git-host polling. They
+wait for their own task's decision lock, not unrelated provider reconciliation.
+This progress does not clear readiness: the coordinator still fetches the
+current PR head and evaluates the complete review and acceptance gates.
+
+After inspecting a failed qualification, use
+`gallivant review qualify --repo OWNER/REPO --run --wait --retry --reason "explanation"`
+to authorize a fresh bounded attempt. Only a recorded timeout/provider failure
+with matching ownership, confirmed process cessation and no recorded tool
+attempt or policy denial qualifies for this operation. A legacy dispatch-ID
+conflict rejected before launch can also recover after confirming its archived
+process has stopped. Each retry uses a distinct execution identity and preserves earlier attempts and costs,
+reserves another configured qualification allowance, and requires a new native
+challenge to pass. It never turns failed output into clearance. Unknown or
+active processes, missing completion records and boundary failures remain
+blocked. The default without `--wait` still returns the running record promptly.
+
+## Persistence and polling
+
+The coordinator saves changed task and reviewer records immediately. Unchanged progress polls do not rewrite the registry or refresh the task’s change timestamp. Native process liveness and output are still checked each tick; unchanged live execution observations are persisted at most once per minute, and settled executions need no heartbeat. Provider health checks, remote-provider cursors, launch/stop intents, result collection and readiness gates retain their existing persistence and polling.
+
+Historical review evidence is kept in the private, content-addressed archive described above. Reusing an identical archived record verifies the existing file without writing another copy. No review evidence or logs are deleted by these optimizations.

package/docs/git-hosts.md

@@ -0,0 +1,294 @@
+# Git host boundary
+
+For a GitHub review mirror that delivers through Bitbucket, see the [explicit branch promotion workflow](bitbucket-promotion.md). It preserves reviewed commits and uses the existing host/review services.
+
+`github.com` supports task dispatch. Bitbucket's explicit no-reviewer path
+completed live local Codex tasks through PR publication and receipt acceptance
+on disposable public and private repositories, but its coding session could
+read the selected merge-capable token file. General Bitbucket dispatch remains
+unqualified while credential isolation is repaired. Independent Bitbucket
+review and clean Linux installation also remain unvalidated. Other hosts remain
+unsupported. The synthetic adapter in
+`test/git-host.test.mjs` is an offline contract fixture, not a supported host.
+
+`lib/host_definitions.mjs` owns the static host catalogue. `lib/hosts.mjs` binds
+its declarations to Node transport implementations. Portable views and task
+profiles read the same declarations without importing Node or credential code. It is independent of both the harness
+registry and execution transports. Shared code obtains `hostApi(context)` and
+selects a repository for dispatch through `context.hosts.select(...)`. Setup and
+transport tools use `inspect(...)` or `inspectRemote(...)`; these do not qualify
+the host for dispatch. The old `context.gh`
+property is retained as an integration/test compatibility seam. New lifecycle
+code must not use it. GitHub CLI commands, wire normalization, prompt commands,
+learning endpoints and rulesets belong to `lib/gh.mjs`, `lib/hosts/github.mjs`
+and the GitHub diagnostics feature module.
+
+## Identity and compatibility
+
+`repository.mjs` parses HTTPS, HTTP (historical GitHub input, upgraded before use),
+scp-style SSH and `ssh://` input. It rejects ambiguous authorities, ports,
+queries, fragments, encoded path characters, traversal and unsupported schemes.
+It never embeds rejected input in errors. HTTPS userinfo is discarded; it is
+never a credential source. Canonical records contain `host`, `path`,
+`remoteIdentity` (`host/owner/repository`) and `key`.
+
+The historical GitHub key remains `owner/repository`; another qualified host's
+key is `host/owner/repository`. Entry IDs, worktree paths and run folder names
+include that key. Existing GitHub IDs, branch prefixes, cursors, receipt hashes,
+PR metadata and chain ownership tokens are read without rewriting them.
+Review/inline/comment IDs keep their old cursor keys, such as `review:42`.
+A short handle still works when it identifies exactly one entry. Ambiguity
+requires `host/owner/repository#number`. Contradictory saved identities and duplicate
+PR ownership stop with a backup/reconciliation instruction; no automatic
+migration, cursor reset or redispatch repairs them.
+
+## Adapter declaration
+
+Each registry declaration supplies:
+
+| Field | Contract |
+| --- | --- |
+| `host`, `id` | Canonical authority and stable completion-evidence adapter ID |
+| `capabilities` | Required evidence and optional decoration, separately declared |
+| `credential(config, repository)` | Resolve current API/HTTPS authorization for the bound host; never cache at daemon boot |
+| `remote(repository)` | Verified clone URL, protocol, host and repository path |
+| `create(options)` | Repository/API operations with injected transport and credentials |
+| `parsePr(url)`, `prUrl(repository, number)` | Strict PR routing and canonical UI links |
+| `prompts` | Host-specific create, inspect, CI-log and receipt-edit instructions |
+| `dataContract` | `host-records-v1` |
+
+Required capabilities are `pullRequests`, `reviews`, `comments`, `checks`,
+`diff`, `mergeProof` and `recovery`. Missing required capabilities fail closed.
+`labels` is optional: an adapter without labels does not block readiness.
+GitHub retains its existing retry semantics for label writes. Learning and
+ruleset operations are GitHub features, not mandatory adapter methods.
+
+Repository operations cover branch/default-branch and permission reads, exact
+ref/ancestry proof, file reads, PR view/list/diff, review/comment pages, comments,
+body/title/recovery writes, ready-for-review and idempotent publication.
+`fileAtStrict` distinguishes a missing file from inaccessible or incomplete
+content. The shared chain engine requires the exact merge commit to be an
+ancestor of the intended base; a closed PR never authorizes a successor.
+
+First-party review additionally requires `reviewEvidence(repo, pr, head, base,
+maxBytes)`: complete diff and before/after changed-file content, including
+deletions, bound to exact head, base and merge-base IDs. Qualification and
+reconciliation refuse adapters without this operation before launching a
+first-party reviewer or reusing its clearance. External-only and explicit
+no-reviewer policies do not require this method. Evidence reads and policy/dispute label writes
+use the same repository registry and credential binding as other lifecycle
+operations. Review jobs and verdicts remain coordinator-owned.
+
+## Domain records and completeness
+
+Every normalized record carries `source` (host and adapter), `actor` (login and
+bot flag), `eventId`, `headSha`, `createdAt` and `updatedAt`. Unknown optional
+values are explicit nulls. Review/comment records also carry `at`, `reviewId`
+and `replyTo`. Their original numeric `id` remains stable for saved cursors.
+CI records expose `outcome: passed | failed | pending`, name, URL and optional
+run ID. Wire-specific CI classification exists only in the adapter.
+
+PRs retain the established domain field names (`headRefOid`, `headRefName`,
+`baseRefName`, `state`, `mergeCommit`, `mergedAt`, `statusCheckRollup`, body,
+author and URL). These are contract fields, not permission to import a host
+client. The GitHub adapter keeps legacy event aliases for existing consumers;
+the review engine accepts the canonical actor, head and timestamp fields too.
+
+A list is either a complete array or `{ items, complete: true }`. Incomplete
+pages, absent CI, rate limits, authentication failures and unreadable diffs
+throw before a readiness decision. GitHub pagination uses bounded subprocess
+output; PR list/check limits are refused at their cap. Shared retries preserve
+cursors, dispatch ownership and the last known decision. Optional decorations
+never supply review, CI or merge evidence. The shared loop has one reviewer
+verdict and one CI outcome predicate for every qualified host.
+
+## Transport and provider binding
+
+The shared Git layer clones with native `git clone --filter=blob:none`. The
+GitHub policy converts accepted GitHub SSH/HTTP inputs to verified HTTPS; no
+shared Git method constructs a GitHub URL. Existing fetch, base selection,
+operator commit identity, isolated configuration and push behavior remain.
+Origin and push destinations are checked against the repository identity before
+credentialed network operations.
+
+The HTTPS helper reads Git's requested protocol, host and repository path before
+returning the bound token. It resets repository credential helpers, refuses
+redirects and receives secrets only through environment variables. Clone URLs,
+argv, committed files and public diagnostics contain no token. A run clears
+inherited API tokens and SSH channels. Bitbucket supports an explicitly selected
+SSH key for coordinator Git operations; an SSH key alone cannot authorize the PR
+API. The coordinator may clone and push over selected SSH or HTTPS. The coding
+session receives neither the repository API token nor the SSH key. Its bounded
+checkout mailbox requests validated push and PR operations from the coordinator.
+Coordinator Git disables checkout hooks before using a privileged credential.
+Setup never grants a sandbox extra key paths.
+GitHub resolution order remains configured token file, daemon environment,
+then `gh auth token`, with explicit-file failure refusing fallback. Resolution
+happens for each operation so reauthentication works without restarting.
+
+Providers declare `repositoryAccess`: `local-worktree`, `snapshot`, or
+`bound-host` with allowed authorities. The shared pre-dispatch check enforces it
+before clone or paid preparation. A local-worktree provider needs no adapter
+change to use another qualified host. No host-by-harness switch table exists.
+
+## Regression evidence
+
+`test/git-host.test.mjs` exercises canonical identity, saved state, collisions,
+normalized feedback, provider access, native clone, token isolation, failure
+preservation and a synthetic host through readiness and chain merge proof.
+`test/git-host-architecture.test.mjs` rejects direct host CLI/API imports or
+prompt commands and a second host-specific review/CI branch in shared modules.
+The existing review, recovery, receipt, chain and execution suites retain
+coverage for bounded retries and idempotent writes. All these tests are offline
+and make no model calls.
+
+
+## Bitbucket Cloud setup
+
+Configure credentials explicitly in `git_hosts["bitbucket.org"]`. Existing
+`github_token_file` resolution is unchanged and is never tried for Bitbucket.
+No `gh` installation or GitHub sign-in is required for a Bitbucket-only config.
+Use an Atlassian account API token; repository access tokens are not required.
+Request `read:repository:bitbucket`, `write:repository:bitbucket`,
+`read:pullrequest:bitbucket` and `write:pullrequest:bitbucket`, limited to the
+selected workspace where available. Reads do not prove write scopes: diagnostics
+report them as unknown until the corresponding write, which surfaces permission
+errors and never silently switches credentials.
+
+```json
+{
+  "git_hosts": {
+    "bitbucket.org": {
+      "api": {
+        "email": "operator@example.com",
+        "token_file": "~/.config/repository-access/bitbucket-api-token"
+      },
+      "git": { "transport": "https" }
+    }
+  },
+  "repos": [{ "repo": "bitbucket.org/workspace/repository", "base": "release/v2" }]
+}
+```
+
+Keep the existing harness, operator identity, worktrees and other config settings.
+Token files must be private (`chmod 600`). HTTPS Git uses the selected API token
+unless `git.token_file` explicitly selects a separate private token file. Git's
+helper returns the token only for HTTPS on `bitbucket.org` and the exact repository;
+it uses the account-token Git username `x-bitbucket-api-token-auth`. API requests
+use account email plus token over HTTPS to `api.bitbucket.org`, with redirects
+refused. API and Git authorization may differ, but the base commit observed through
+Git must match the API repository and base.
+
+For SSH, use this `git` block instead:
+
+```json
+{
+  "transport": "ssh",
+  "ssh_key": "~/.config/repository-access/bitbucket-key",
+  "known_hosts": "~/.config/repository-access/bitbucket-known-hosts"
+}
+```
+
+Select an unencrypted dedicated key that the coordinator can read, with mode 600.
+No SSH agent or global SSH configuration is used. The dedicated known-hosts file
+must contain only `ssh.bitbucket.org` entries matching Atlassian's published
+SHA256 fingerprints. Get candidate public keys from `https://bitbucket.org/site/ssh`,
+select the `ssh.bitbucket.org` lines and independently check their fingerprints
+against [Atlassian's SSH host-key documentation](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/).
+Do not accept an unverified `ssh-keyscan` result. A host-key rotation stops access
+until the published pins and selected file are reviewed. Strict verification is
+always enabled. Existing `git@bitbucket.org:workspace/repo.git` origins and the
+new `git@ssh.bitbucket.org:workspace/repo.git` origins resolve to one Cloud identity;
+clones use the new endpoint described in [Atlassian's SSH migration notice](https://developer.atlassian.com/cloud/bitbucket/changelog/).
+Self-hosted servers, custom SSH aliases and alternate ports are unsupported.
+
+Run `init` from the checkout to bind the API repository UUID and workspace UUID
+under the host's `repositories` map, or run `doctor` for read-only diagnostics.
+Setup checks repository access, the selected base, effective account push role,
+PR reads, comments when a PR exists, branch restrictions where visible, and native
+Git access to the same base. The account role comes from the
+[authenticated user's repository permissions](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/#api-user-workspaces-workspace-permissions-repositories-get),
+filtered by repository UUID, using repository read scope without workspace-admin access.
+An archive flag, if supplied, is enforced; the Cloud
+repository schema does not currently expose that flag consistently, so absence
+is reported as unknown. A missing API credential reports missing PR/comment
+capability even when an SSH key is configured. A successful transport check is
+followed by an explicit failed dispatch check. No paid model probe is needed for
+this milestone, and `init` does not recommend starting a task on an unqualified host.
+
+API credentials are reread for every operation. A changed email, account UUID on
+successive permission reads, repository UUID,
+workspace UUID, canonical slug or API clone target stops access. Restore the
+previous binding, or inspect the new identity and explicitly edit the binding;
+setup never silently migrates a renamed or transferred repository.
+
+## Bitbucket evidence and publication bounds
+
+`lib/hosts/bitbucket.mjs` owns API shape and pagination differences. PR snapshots
+include source/destination UUIDs, branches and commits, draft state, host state
+(`OPEN`, `MERGED`, `DECLINED` or `SUPERSEDED`), title/description, diff, comments,
+reviewer participants, tasks and statuses tied to the current head. Declined and
+superseded PRs normalize to `CLOSED`, preserving `hostState`. UUID-based actor
+identity avoids nickname ambiguity. These observations do not qualify reviewer
+trust, CI policy, recovery or merge proof for dispatch.
+Build statuses use the [documented commit link](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commit-statuses/#api-repositories-workspace-repo-slug-commit-commit-statuses-get)
+to confirm the queried repository and head; missing or mismatched links stop the snapshot.
+PR list responses omit reviewer and participant collections. Bounded list results
+are expanded through repository-scoped PR detail reads before normalization;
+preflight also reads the selected PR's details before checking comment access.
+Missing or inaccessible detail records stop the operation, and a failed read after
+publication preserves the unresolved write until reconciliation succeeds.
+
+Reads are bounded to 100 pages and 10,000 items per collection, 4 MiB per JSON
+response, a diff smaller than 16 MiB, and 20 seconds per request. Missing fields,
+cycles, changed filters, size inconsistencies, rate limits, foreign pagination,
+redirects and changed PR identity/head during a snapshot produce explicit errors.
+The documented diff redirect is allowed only into the same repository's diff
+endpoint. Failures never become empty reviews or successful checks.
+
+Publication uses the existing public-text validator, exact repository UUIDs and
+source/base names. It checks PRs in all states before every publication, updates one matching open PR,
+and refuses forks, closed predecessors, conflicting bases or duplicate ownership.
+Writes address immutable workspace/repository UUIDs so a concurrent slug change
+cannot redirect a write into a replacement repository. Every write is
+followed by reconciliation, including timeouts after acceptance. An unresolved
+create remains blocked in that adapter instance until a matching PR is observed;
+a restart still reads before any write. Concurrent publication in one instance
+is refused. There is no fork creation, merge, force push or repository-settings API.
+Comments are never automatically retried after an uncertain write.
+
+Offline coverage: `test/bitbucket.test.mjs`, `test/bitbucket-fixture.mjs` and
+`test/host-transport-contract.test.mjs`. The shared contract assertions run against
+both production adapters with injected wire responses. No fixture test calls a
+model or writes to a live repository. Live review-loop qualification remains a
+separate milestone.
+
+API references: [repositories](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/),
+[pull requests](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/),
+and [account-token authentication](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/).
+
+## Review-loop implementation and ship gate
+
+The [Bitbucket review guide](bitbucket-review.md) supersedes transport-only setup
+examples for reviewer/trust/check policy. `init --host-config <json> --base <branch>`
+can bootstrap an empty config, with an explicit reviewer (or `null`) and stable
+trusted UUIDs. The adapter now implements review normalization, required task
+blockers, recovery operations and merge ancestry. The explicit no-reviewer
+dispatch path has [disposable live observations](audit/bitbucket-review-qualification.md),
+but credential isolation failed; independent review and clean Linux installation
+remain unvalidated. Do not enable general dispatch from these observations.
+
+`prView` may include `feedback: { complete: true, headSha, reviews, inline, comments }`.
+The shared loop consumes this one coherent snapshot; adapters without it retain
+the previous collection methods. Strict records declare `headBinding: "exact"`
+and an explicit `verdict`; PR-wide required tasks declare `required: true` and
+`headBinding: "pull-request"`. Stable `sequence` values disambiguate verdicts that
+share a timestamp. `strictIdentity` requests recorded branch/base/head and terminal
+merge checks. These are domain contract fields, not host-name branches in the
+scheduler. GitHub's historical event keys and review interpretation are retained.
+
+A future GitLab adapter must implement the same complete records, explicit policy,
+strict URL/credential binding, publication, file reads, and merge proof. Add its
+static definition/implementation and shared-contract tests, then qualify it live
+with a compatible provider. Until then GitLab and unregistered hosts fail before
+dispatch. Host, harness and inference provider remain separate configuration axes.

package/docs/guardrails.md

@@ -309,3 +309,59 @@ that a tool call was denied. The historical findings are linked below.
 ## Follow-ups filed against APort
 
 The historical [decision record](https://github.com/uchibeke/gallivant/blob/main/docs/audit/DECISIONS.md) lists: multi-file `apply_patch` in the Codex hook, `git push` refspec parsing, control-plane paths blocked by default, a non-interactive local passport install, and a Repository Guard slice that blocks pushes rather than reporting merges.
+
+## Reviewer authority
+
+The opt-in first-party reviewer uses the restricted native preparation boundary in a fresh session with supplied evidence only. Image jobs additionally require their own capability qualification and a verified coordinator-created copy. Its profile denies tools, escalation, delegation and tool network access; setup/start verify effective native policy and require a live qualification record. A private HOME or a prompt alone is not sufficient. The model cannot write task policy, state, files, Git refs, PRs or approvals. The coordinator validates exact-input structured output; public agent text is never an independent host actor. Unknown or partial output fails closed. See [review isolation, evidence and monetary limitations](first-party-review.md) and [unmet live qualification](audit/first-party-review.md). Review grants no merge or deployment authority.
+
+Repository identity, credential transport and PR evidence are defined by the
+[Git host contract](git-hosts.md). GitHub and Bitbucket Cloud can dispatch;
+Bitbucket's live no-reviewer path has been qualified on a disposable public
+repository. Independent Bitbucket review remains unvalidated. Existing IDs and
+chain ownership are retained without a state migration.
+
+## Independent Bitbucket reviewer credentials
+
+Coding sessions receive only their repository-bound coding credential. Reviewer
+credentials belong on an isolated reviewer machine, OS account, or container.
+The independent publisher accepts only the configured stable actor and prepared
+exact head; a successful Pipeline without a posted verdict is silence.
+See [reviewer isolation and publication](bitbucket-review.md#independent-local-codex-reviewer).
+Setup never installs a pipeline, creates a token, or authorizes inference.
+
+## Keep working artifacts out of pull requests
+
+Every local harness receives the same publication policy and generated `commit-msg` hook. The hook examines the
+NUL-delimited staged file list and rejects task scratch directories, conventional work logs, audit/evidence notes,
+and carried task inputs. Removing those files is allowed; preserve any carried files locally because the brief and
+snapshot checks still need them. The hook is refreshed at start and on every resumed/fix run. Hosted file results
+are checked before writing them, and the coordinator checks the complete remote PR diff before expensive first-party review and before readiness, even when the optional output-content scan is disabled. An unreadable or malformed diff is retried and
+never treated as clean. A prohibited file schedules a normal corrective round with its exact path.
+
+Requested audit reports, screenshots and other evidence are still valid deliverables. The operator names exact
+paths in the approved brief's [`publish_files`](prd.md) list. The coordinator uses its saved snapshot, never a
+session-edited whitelist. Before upgrading or restarting the daemon for existing runs, review retained deliverables in reserved directories.
+The operator must name their exact paths in `publish_files` and accept the updated saved brief through the usual
+`resume --resnapshot` flow at a safe resume boundary. Do not edit a running session's snapshot or grandfather all
+existing files. Without those prior approved exceptions, the new guard will request cleanup instead of readiness.
+
+Use a temporary directory outside the repository for scratch files. Runner command/session logs remain in task
+storage; concise verification results belong in the PR receipt. Keep durable release/rollback instructions in the
+project docs without appending a running execution diary. This policy does not inspect arbitrary prose or provide
+an isolation boundary: an agent with Git credentials can bypass local hooks and push, but reserved work-artifact
+paths will not pass the coordinator's readiness check. A clean check is cached only for its exact head, base and approved policy, so review polls do not repeatedly fetch
+the diff. Normal rechecks also inspect legacy ready entries; no PR is automatically rewritten.
+
+First-party reviewers receive carried text inputs from the coordinator's immutable `readSource` snapshots, with
+content digests in their private evidence. They do not fetch those files from remote HEAD or the mutable session
+checkout. These inputs follow the existing capture, per-job input and review-job caps; missing or oversized input
+is reported explicitly, never silently omitted. Keep source context concise: it accompanies each source/visual
+review piece and the final synthesis. The complete brief plus private source context and review metadata must fit the
+configured per-job input cap (at most 100,000 serialized UTF-8 bytes). Larger private sources must be narrowed or
+split into separately approved tasks; do not commit them as a workaround. Required image evidence remains in Git at its approved output paths.
+
+`openai-agents` transports all approved inputs privately with their original hashes, but only explicit output overlays
+are forced into a result. Verification permits private inputs to remain untracked or unstaged only while their bytes
+and modes exactly match the coordinator snapshots. Editing, staging, deleting or substituting them fails publication.
+Codex Cloud's Git-only input transport cannot provide this privacy for new/changed inputs and refuses before commit
+or push; its dispatch is separately unavailable until repository binding is qualified. See [codex-cloud.md](codex-cloud.md).