@uchibeke/gallivant 0.2.1 → 0.3.0

package/docs/config.md

@@ -19,10 +19,10 @@ See [installation](install.md) for the first-run sequence.
 | Key | Default | Meaning |
 |---|---|---|
 | `poll_seconds` | 120 | GitHub review and chain-check cadence. Minimum 30. Provider progress and readiness use the separate `execution.progressMs` cadence; the daemon may tick more frequently. |
-| `max_iterations` | 30 | Automatic fix-round allowance per PR. A pushed fix or changed completion receipt consumes a round. At the cap, further automatic work stops with `needs-human`. Explicit operator resumes can exceed the cap; their progress still counts. |
+| `max_iterations` | 60 | Automatic fix-round allowance per PR. A pushed fix or changed completion receipt consumes a round. At the cap, further automatic work stops with `needs-human`. Explicit operator resumes can exceed the cap; their progress still counts. |
 | `checks_grace_minutes` | 5 | A head younger than this with no checks reported is not green yet; GitHub shows an empty check list for the first seconds after a push. A head older than this with no checks at all counts as green. |
 | `run_timeout_minutes` | 720 | Local runs exceeding this time are killed; remote execution uses provider cancellation/reconciliation where supported and preserves unknown ownership. It is a runtime allowance, not a provider billing cap. Overridable per repository; see below and [execution](execution.md). |
-| `max_budget_usd` | 5 | Passed to Claude as `--max-budget-usd` and used in task preparation/authorization accounting. Other local harnesses have no equivalent enforced dollar cap. Hosted dispatch also requires its explicit provider allowance; reservations are not a billing hard cap. |
+| `max_budget_usd` | 50 | Passed to Claude as `--max-budget-usd` and used in task preparation/authorization accounting. Other local harnesses have no equivalent enforced dollar cap. Hosted dispatch also requires its explicit provider allowance; reservations are not a billing hard cap. |
 | `rereview_minutes` | 6 | If the reviewer has not reviewed this long after a request, the request is posted once more. |
 | `stall_hours` | 6 | If the reviewer still has not reviewed, the PR stops with `reviewer-silent`. |
 | `trusted_authors` | required | GitHub logins whose reviews and comments may start a run. Everyone else is ignored. Your own login belongs here. |
@@ -41,9 +41,10 @@ See [installation](install.md) for the first-run sequence.
 | `harness.openai-agents` | absent | Explicit account, organization, project, model, API credential, hosted environment, network policy and allowance. See [Agents setup](openai-agents.md). |
 | `harness.codex-cloud` | absent | Recognized for configuration/recovery, but new dispatch is unavailable. See [Cloud blocker](codex-cloud.md). |
 | `execution` | bounded defaults | Transport/probe deadlines, progress cadence, concurrency, backoff and event limits. See [execution scheduling](execution.md#scheduling-and-limits). |
+| `intake_model` | absent | The explicitly funded planner route for natural-language intake: `{ adapter, model, endpoint, credential_env, budget, timeout_ms }`. The key is read from the named environment variable at call time. Configurable ceilings are 12 calls, 100,000 input and 16,000 output tokens per call and a $10 allowance; configuration can lower them. Timeout defaults to two minutes, configurable up to five. Existing approved route/task budgets remain pinned. See [typed delivery profiles](task-profiles.md#configuring-the-model-route). |
 | `repos` | [] | The repositories Gallivant watches, appended by `start` and `register` and read by `up` to recover from GitHub. Each entry is either `"owner/name"` or an object: `{ "repo": "owner/name", "base": "staging", "run_timeout_minutes": 90 }`. Both object keys are optional. See below. |
 
-The default allows 30 rounds as an upper allowance for unattended review. It is not a target or a promise of completion:
+The default allows 60 rounds as an upper allowance for unattended review. It is not a target or a promise of completion:
 large tasks can exhaust it, while missing external prerequisites cannot be solved by more rounds. Reaching the cap
 requires an operator decision, and it never increases itself.
 Existing explicit `max_iterations` settings keep their value. More rounds allow more time and model spend; they do
@@ -273,6 +274,11 @@ Gallivant was first driven against, and it is only a default:
 - `rereview_comment` is the entire text Gallivant posts to ask for another look. It is posted after every push that came from a fix run, and again as a nudge if the reviewer says nothing for `rereview_minutes`. Gallivant never inspects the string, so a bot mention, a slash command or a plain sentence all work.
 - `blocking_pattern` is a regex tested against each inline comment of the reviewer's newest review since the last request. A match, or a `CHANGES_REQUESTED` state, keeps the PR out of `ready-for-human`.
 
+Pushing a commit does not automatically request Codex review for a manually
+updated PR. Follow [the exact-head review procedure](codex-review.md) after each
+final push; the background loop only posts its configured request after runs it
+dispatches itself.
+
 ### Pointing it at a different reviewer
 
 Nothing beyond these three fields needs to change. Two worked examples.
@@ -303,12 +309,11 @@ account is what distinguishes a review tool from the trusted humans in `trusted_
 dispatches a fix run against rather than waiting on. So a human login in `reviewer.login` never matches, the verdict
 stays `waiting`, and the PR waits out `stall_hours` and then stops with `reviewer-silent` for a person to look at.
 That is a reasonable way to run a repo where a human gates every merge, but it is a wait, not a verdict. If you want
-the human's findings to drive fix rounds instead, put them in `trusted_authors` and set `reviewer` to null.
+the human's findings to drive fix rounds, put them in `trusted_authors`. New tasks without an external actor also need a qualified first-party policy or the explicit legacy no-review exception.
 
 ### No automated reviewer
 
-`"reviewer": null` means there is no review tool: only humans and CI drive the loop, and a PR is ready as soon as
-checks are green. Gallivant asks nobody for a re-review, so there is no nudge and no `reviewer-silent` stop. It still
+`"reviewer": null` means no external review tool is configured. For new tasks, select a qualified first-party route or set `review.legacy_no_review: true` explicitly. Legacy no-review readiness rests on checks and the configured completion gate and is labelled as absence of review, never clearance. No external re-review or nudge is requested. It still
 comments after a push, because the round comment is also how a recovery rebuilds the round count off the PR, but the
 comment says `Pushed a fix.` and mentions no one.
 
@@ -345,7 +350,9 @@ tree. That is the same rule the brief follows: the daemon judges what it recorde
 given by editing a document it was handed. Editing one in your own tree afterwards is reported by `gallivant why` the
 same way an edited brief is, and the list itself is part of the contract, so adding or removing a file is a contract
 change even though no criterion moved. Changes to either the manifest or file bytes block readiness and resume until
-accepted with `resume --resnapshot`; accepted snapshots are also restored when a checkout is recreated.
+accepted with `resume --resnapshot`; accepted snapshots are also restored when a checkout is recreated. Carried inputs
+remain local and untracked unless explicitly requested as output in the approved brief's [`publish_files`](prd.md) list.
+Keep those local copies when removing accidental commits; the task still reads them.
 
 `sources` and `context_paths` answer different questions and neither replaces the other. `sources` puts named files
 INSIDE the checkout, so it works on every harness because it needs no flag at all. `context_paths` grants a session read
@@ -419,14 +426,16 @@ Every run gets the resolved credential as `GH_TOKEN`, the git settings below, an
 
 ### Git settings for a run
 
-No file. Git's own `GIT_CONFIG_COUNT` with numbered `GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n` pairs carries four settings:
+No file. Git's own `GIT_CONFIG_COUNT` with numbered `GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n` pairs carries the following settings:
 
 | Key | Value |
 |---|---|
 | `user.name` | Your Git-configured name, resolved by the coordinator for each run |
 | `user.email` | Your Git-configured email, resolved by the coordinator for each run |
 | `push.default` | `current` |
-| `credential.helper` | a shell snippet that prints `GH_TOKEN` as the password, and prints nothing when there is no `GH_TOKEN` |
+| `credential.helper` | an empty entry resets inherited helpers, followed by a helper that answers only for the bound HTTPS host and repository |
+| `credential.useHttpPath` | `true` |
+| `http.followRedirects` | `false` |
 
 Plus `GIT_CONFIG_NOSYSTEM=1` and `GIT_CONFIG_GLOBAL=/dev/null`.
 
@@ -434,4 +443,20 @@ Nothing in that list is a path outside the worktree, and that is the point. Unti
 
 Both isolating variables are load-bearing, and `GIT_CONFIG_NOSYSTEM` is not decoration. `GIT_CONFIG_GLOBAL` replaces only git's global file; the system one still applies, and on a Mac with the Xcode command line tools `/Library/Developer/CommandLineTools/usr/share/git-core/gitconfig` sets `credential.helper = osxkeychain`. Without `GIT_CONFIG_NOSYSTEM` a run had a path to your keychain whatever else was set. With it, `git config --get-all credential.helper` in a run's environment returns nothing but the snippet above.
 
-What this does not bound, said plainly because it is easy to mistake for new: a run's own `.git/config` is still read, `credential.helper` is multi-valued, and a repo-local helper is consulted before this one. That was equally true when the helper lived in a global file, since local config always won there too. A run owns its worktree, so it can always add a helper. What bounds a run is the token's scope and the branch ruleset, not how the config travels.
+The helper resets repository-local credential helpers and refuses other hosts, repository paths and redirects. Runs clear inherited API tokens and SSH transport settings. A run can read its own environment, so token scope and repository rulesets remain essential. See the [Git host contract](git-hosts.md) for identity, compatibility and provider binding.
+
+## Bitbucket repository policy
+
+Set `reviewer` (or explicit `null`), stable UUID `trusted_authors`, and
+`required_checks` under `git_hosts["bitbucket.org"]`. A host repository entry can
+override these settings, and a `repos` object takes precedence over both.
+GitHub's top-level reviewer defaults are never inherited by Bitbucket.
+See [configuration examples and credential scope](bitbucket-review.md).
+For a deliberate no-reviewer task, set `reviewer: null` and
+`review.legacy_no_review: true` on the repository entry. Readiness then reports
+that no independent review was performed; it still requires configured checks
+and the completion receipt.
+
+## Versioned review policy
+
+`review.mode` selects `external-required`, `first-party-required`, or `both-required` for new tasks. `review.route: "codex"` requires a successful isolated live qualification. `review.specialist` allows at most one of `security` or `regression`. Defaults and bounds, per-repository settings, separate review allowances, explicit zero-check CI policy and the `legacy_no_review` exception are documented in [First-party review](first-party-review.md). A config edit cannot change an existing task policy; use `review policy <handle> --mode <mode> --reason "..."` to revoke readiness and explicitly re-evaluate. `reviewer: null` alone no longer authorizes an unattended new start.

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.