@uchibeke/gallivant 0.2.0 → 0.3.0

package/docs/chains.md

@@ -1,6 +1,6 @@
 # PRD chains
 
-**Gallivant automates delivery; humans approve integration.** A chain starts its next PRD only after GitHub confirms
+**Gallivant automates delivery; humans approve integration.** A chain starts its next PRD only after the Git host confirms
 that the preceding PR was merged into the planned base branch. Gallivant never merges PRs. Passing tests, an accepted
 receipt, `ready-for-human`, and a finished agent session are progress toward that decision; none starts the next task.
 
@@ -38,6 +38,29 @@ the chain; closing any milestone's PR without merging stops it.
 The scope is deliberately linear: one repository, one base, one active milestone per chain. There is no dependency
 graph, stacked-PR mode or automatic merge. Unrelated tasks and other chains can run independently.
 
+## Continue after an existing PR
+
+If the first task already has a registered PR, keep its current run and queue only the new work:
+
+```sh
+gallivant chain launch --after https://github.com/your-org/your-repo/pull/123 docs/prds/launch.md
+# A registered handle also works:
+gallivant chain integration --after your-org/your-repo#123 docs/prds/integration.md docs/prds/next.md
+```
+
+`--after` accepts a PR URL from a supported Git host or a registered run handle. Register the PR first if it is not
+already tracked. At least one **new** ready PRD is required, in the same repository and approved base as the PR.
+The predecessor is a dependency, not a newly started milestone: its session, review policy, counters and any existing
+chain ownership stay unchanged. The usual `say`, `recheck` and `resume` commands still manage that run.
+
+The chain records the exact registered PR, repository, branch and base. It waits for the author process to finish
+and the host to confirm a merge, then checks that merge commit in both the remote base and the successor's clone.
+An open PR marked ready does not release the dependency. A removed or retargeted registration, a closed unmerged PR,
+or missing merge ancestry stops dispatch. Retry and resnapshot cannot replace the predecessor; cancel and create a
+new chain to change it. Progress counts only the newly queued milestones and displays the predecessor separately.
+Keep the predecessor registered until the chain finishes. Run a version supporting `--after` on every coordinator
+using this home; do not downgrade while these chains remain active.
+
 ## Inspect progress
 
 ```sh
@@ -100,3 +123,9 @@ the ordinary review loop. It does not cancel or undo work that has already start
 
 Chain approval and unstarted milestones live in local `state.json`; unlike an open PR's identity, they cannot be
 reconstructed from GitHub. Preserve your Gallivant home when moving the daemon to another machine.
+
+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.

package/docs/codex-cloud.md

@@ -17,6 +17,13 @@ tasks remain available. Its implementation is offline tested; live qualification
 is **unverified**. Local Codex and `openai-agents` retain their existing defaults
 and continuation behavior.
 
+The Git-based Cloud input transport cannot privately deliver new or changed carried
+source files. It refuses before committing or pushing them; use a local harness or
+`openai-agents` for those tasks. Existing repository files with unchanged bytes are
+usable inputs. `publish_files` is only for output documents the operator explicitly
+wants in the PR, never a workaround for publishing private task context. This remains
+a separate limitation from the repository-binding requirement that currently disables dispatch.
+
 ## Trusted worker setup
 
 Use a trusted operator or self-hosted Node 22+ worker with persistent private

package/docs/codex-review.md

@@ -0,0 +1,50 @@
+# Requesting and verifying Codex reviews
+
+A Git push updates the pull-request head and can start CI. It does **not** by
+itself request a new Codex review. In this repository's observed setup, automatic
+review covers a newly opened pull request; a later head needs an explicit
+`@codex review` comment. Security review is a separate request using
+`@codex security review`. A quiet thread after a push is therefore not a clean
+review result.
+
+Gallivant's background review loop posts the configured
+`reviewer.rereview_comment` after a fix run it dispatched. A manual push, a PR
+outside that loop, or a branch reset does not inherit that behavior. Do not infer
+that the daemon requested a review unless its comment is present on the PR.
+
+## Verify a review against the exact head
+
+For every final push:
+
+1. Read the current PR head SHA from GitHub after the push.
+2. Post `@codex review`; also post `@codex security review` when the change
+   affects authorization, parsing, credentials, execution, or other security
+   boundaries.
+3. Wait for a Codex review receipt created after the request. Compare its
+   `commit_id` (and any `Reviewed commit` in the body) with the current GitHub
+   head SHA. For inline findings, compare each comment's `commit_id` too.
+4. Fix each finding or reply with a reproducible test showing why it does not
+   apply. After another push, request and verify both reviews again.
+
+Example read-only checks:
+
+```bash
+git rev-parse HEAD
+gh pr view NUMBER --json headRefOid
+gh api repos/OWNER/REPO/pulls/NUMBER/reviews \
+  --jq '.[] | {commit_id, submitted_at, state, body}'
+gh api repos/OWNER/REPO/pulls/NUMBER/comments \
+  --jq '.[] | {commit_id, created_at, path, line, body}'
+```
+
+An old inline thread can stay visible after later commits, and GitHub can retain
+review records when a branch is reset to a previously seen SHA. Treat a record
+as current only when its commit matches the live head and its timestamp follows
+the current review request. A clean `reviewDecision`, an empty inline-comment
+list, or a successful push is not a substitute for that receipt. A review with
+no findings may have a summary and no inline threads, so verify the review record
+as well as comments.
+
+This procedure reflects the repository's observed Codex integration, not a
+general guarantee about future GitHub or Codex behavior. If the trigger changes,
+update this guide after verifying it with a new exact-head review.

package/docs/commands.md

@@ -9,7 +9,7 @@ Use `gallivant --help` (or `gallivant help`) for the installed CLI's syntax and
 
 | Intent | Command | Notes |
 |---|---|---|
-| Create config | `gallivant init` | Selected Codex or Claude installation; preserves existing config. |
+| Set up the current repository | `gallivant init` | Private config, this repository in `repos`, then the `doctor` report; safe to repeat. |
 | Check setup/connectivity | `gallivant doctor` | `--network` tests DNS/HTTPS; `--probe` is a real Claude run. |
 | Prepare a task | `gallivant task "request"` | Uses inference; implementation requires `--run` authorization. |
 | Inspect/continue a prepared task | `gallivant task list`, `inspect`, `answer`, `resume`, `validate`, `start` | Task IDs and exact revisions; see [task operations](#task-operations). |
@@ -25,6 +25,7 @@ Use `gallivant --help` (or `gallivant help`) for the installed CLI's syntax and
 | Diagnose a stop | `gallivant why HANDLE` | Shows state, failure and pending controls. |
 | Continue stopped execution | `gallivant resume HANDLE` | Preserves the session; explicit changed-brief acceptance uses `--resnapshot`. |
 | Re-evaluate PR gates | `gallivant recheck HANDLE` | No budget reset, no CI rerun, no replacement for execution recovery. |
+| Qualify or change review policy | `gallivant review qualify|status|policy|dispute` | Qualification is separate and may be paid only with `--run`; policy changes preserve the task and session. |
 | Send a correction | `gallivant say HANDLE --note "..."` | Queues same-session delivery; supported local runs can use `--interrupt`. |
 | Stop future dispatch | `gallivant cancel HANDLE` | Requests cancellation; inspect confirmation before assuming the process stopped. |
 | Forget tracking | `gallivant remove HANDLE` | Leaves the PR, branch, labels and checkout in place. |
@@ -46,12 +47,39 @@ select the configured harness in the PRD or task preparation.
 
 ## `gallivant init [--harness codex|claude] [--worktrees <directory>]`
 
-Create a private config from your authenticated GitHub login and the selected
-installed harness (Codex by default). Creates a separate checkouts directory,
-disables optional notifications initially, and prints the packaged template paths.
-Existing configs are refused, never replaced. Does not change credentials, global
-harness settings, reviewer installation or repository rules. Follow `doctor` and
-[installation](install.md) next. `--version` prints the installed package version.
+Set up the Git checkout you run it in. Published form:
+`npx --yes @uchibeke/gallivant init --harness codex`.
+
+Before writing anything it checks, in this order, that the directory is a Git
+checkout whose `origin` is a github.com repository, that `gh` is signed in, that
+the selected harness is installed at a supported version and signed in, and that
+the resolved run credential can push to the repository. A failed check stops the
+command with the exact fix (`gh auth login`, `codex login`, `claude auth login`,
+or the remote or permission to correct) and leaves no state behind.
+Classic credentials also need `public_repo` or `repo` scope; the account's push
+role alone does not grant that scope. If the scope lookup fails, setup asks you
+to retry before writing state. Fine-grained tokens have no OAuth scope header
+and still require the repository permission check.
+
+It then creates a private config from your authenticated GitHub login and the
+selected installed harness (Codex by default for a new config), creates a
+separate checkouts directory, disables optional notifications, records the
+repository in `repos` once, and prints the `doctor` report plus the packaged
+template paths. Its exit status is doctor's: `0` when every check passes, `1`
+while checks remain.
+
+Repeating it is safe. An existing config keeps every key as written; the only
+change is the one `repos` entry for the current repository, never duplicated.
+`--harness` adds a second supported harness without touching the first;
+when both Codex and Claude are configured, pass `--harness` to choose one.
+Concurrent updates use the same mutation lock as other CLI writes; if settings
+change during the prerequisite checks, setup rechecks them before writing.
+`--worktrees` is refused when it differs from the configured directory. `init`
+does not sign in, change credentials, global harness settings, reviewer
+installation or repository rules, and does not start a task. When run through
+`npx` it says that nothing was installed globally and prints both the next `npx`
+command and the optional `npm install -g @uchibeke/gallivant`. See
+[installation](install.md). `--version` prints the installed package version.
 
 ## `gallivant doctor [--send] [--probe]`
 
@@ -88,6 +116,11 @@ Requests can produce code, documentation, research or other repository artifacts
 A natural-language task still becomes an explicit, validated delivery contract;
 it does not require the user to write a PRD first.
 See [task operations](tasks.md) for examples, source delivery and stopping rules.
+`--delivery pull_request` selects the typed delivery profile that alone authorizes
+external actions for new tasks, `--completion-target` sets its completion
+condition, and `--route harness|model` chooses the planner route. The result's
+`review` object is the revision-pinned view an owner approves with `task start
+--run`. See [typed delivery profiles](task-profiles.md).
 
 
 ### Task operations
@@ -115,8 +148,9 @@ Preparation accepts `--repo`, `--base`, repeated `--context` files and `--verify
 commands, and a retry-safe `--request-id`. Answers may also add explicit context
 and verification commands. `--completion-target delivery_ready|integrated` selects
 whether the task tracks readiness or confirmed integration; neither grants merge
-permission. `--run` on initial preparation authorizes dispatch after readiness and
-any required answers. `--no-daemon` leaves monitoring startup to an existing host
+permission. Initial preparation returns the draft or questions for review even
+when `--run` is present; approve the visible revision separately with `task start
+--revision N --run`. `--no-daemon` leaves monitoring startup to an existing host
 or explicit coordinator. See [task operations](tasks.md) for revision conflicts,
 uncertain dispatch, evidence and authorization rules.
 
@@ -161,7 +195,30 @@ Local task submission:
 8. Copies those snapshots into the checkout at their original repository paths, creating directories as needed. The PRD is usually only in your own checkout; this copy lets the session commit it with the implementation. Copies in the session's checkout are writable and are never read back for a decision.
 9. Starts the session detached with the PRD as its prompt, records the session id, and remembers the repo for recovery.
 
-The entry is `running` until the daemon sees the run end. Then either a PR exists on the branch and the entry enters `pr-open`, or it stops with `no-pr`.
+The entry is `running` until the daemon sees the run end. Then either a PR exists on the branch and the entry enters `pr-open`, or a successful worker that did not open one stops with `no-pr`. A failed or incomplete worker without a PR stops with `harness-error`; inspect its run log. Recognized terminal connection failures use the bounded [network recovery](network-recovery.md) path instead.
+
+Workers must collect verification results before returning. Claude launches disable
+native background shell/subagent execution and disallow `Monitor`, which otherwise
+remains available despite that setting. This applies to both new and resumed
+implementation/review runs, without changing the operator's global settings,
+sandbox, APort hooks or task allowances. Temporary development servers may still
+be used within a run, with their tests collected and processes cleaned up before
+returning. Shell checks need explicit timeouts sufficient for the check and within
+the approved limits; a timed-out check is not a pass. Tool-free preparation keeps
+its existing deny-all boundary. These native controls are described in Claude's
+[environment reference](https://code.claude.com/docs/en/env-vars) and
+[Monitor documentation](https://code.claude.com/docs/en/tools-reference#monitor-tool).
+
+A background-task notification's result cannot settle the main task or hide its
+failure. Gallivant owns durable wakeups and review polling. It does not blindly
+restart every `no-pr` or missing-result failure, which could repeat external
+effects or run unchanged blocked work indefinitely. After upgrading, explicitly
+resume an already stopped run once; future launches receive the lifecycle policy.
+An interrupted pre-PR session becomes resumable only after its owned process tree
+has stopped. Late results stay quarantined; the coordinator still discovers any
+PR already opened before delivering the queued correction to the same session.
+An older failed interrupt is repaired to a stopped state, preserving its message
+for an explicit retry instead of replaying that failed request automatically.
 
 It also brings the daemon up in the background if one is not already running, and waits until the daemon reports
 itself before returning. That is not a convenience: `start` opens a session that will open a pull request, and the
@@ -185,11 +242,13 @@ with exit code 1. Retry `gallivant start` without a PRD, not the original submis
 processes continue; restart monitoring with `gallivant start`. Embedded trackers
 are owned by their host and are not stopped by this command.
 
-## `gallivant chain [<name> [<first.md> <next.md> ...]] [--base <branch>]`
+## `gallivant chain [<name> [<first.md> <next.md> ...]] [--base <branch>] [--after <pr-url|handle>]`
 
 Queue at least two ready PRDs in order. All must be new tasks in one checkout of the same repository and on the same
 resolved base. `--base` selects the base for a new chain; otherwise the repository config or default branch applies.
-The daemon starts the first task and starts each successor only after GitHub confirms the preceding PR was merged
+With `--after`, queue one or more new PRDs behind an already registered PR in that same repository and base.
+The existing run is preserved; its exact PR, branch and base are pinned, and its merge must precede all queued tasks.
+The daemon starts the first task and starts each successor only after the Git host confirms the preceding PR was merged
 into that base. The final merge completes the chain. `ready-for-human`, a completed agent process and a local `done`
 entry never satisfy the dependency; closing without merging stops the chain. Gallivant never merges for you.
 
@@ -199,6 +258,7 @@ brings the existing daemon up if needed. Independent runs continue alongside it.
 | Command | Effect |
 |---|---|
 | `gallivant chain launch first.md next.md` | Approve the order and current brief/source fingerprints, then queue dispatch. |
+| `gallivant chain launch --after your-org/repo#123 next.md` | Wait for the registered predecessor's verified merge, then start the new task. |
 | `gallivant chain launch --retry` | Recheck a stopped chain after its cause is resolved. |
 | `gallivant chain launch --retry --resnapshot` | Explicitly accept updated briefs and carried sources for unstarted tasks. |
 | `gallivant chain launch --cancel` | Stop future dispatch; preserve already started work and its review loop. |
@@ -217,8 +277,10 @@ Puts a PR into the loop that Gallivant did not open, or resets one that stopped.
 - A `--worktree` you pass is resolved to an absolute path first, so `.` means the directory you typed it in and not whatever directory the daemon happens to run in later. It is then checked before it is accepted: its `origin` must be the PR's repository and it must already be on the PR's head branch. A path that fails either check is an error, since the harness edits and pushes from that directory. It is never relocated or re-cloned for you, because a resumed session is keyed to the directory it ran in.
 - On an entry that already exists: reason cleared, iteration reset to zero, a marked reset comment posted on the PR (so a count rebuilt from GitHub starts from zero too), cursor set to now, watching again. This is how you restart a `needs-human` PR after you fixed the conflict or answered the question. A fresh registration instead looks at the PR's whole history, so feedback already on it gets addressed.
 - That reset comment is the reset boundary, so posting it is a precondition of the reset and not a best-effort extra. A count rebuilt from GitHub finds its marker and counts only the round comments after it; with the comment missing and `state.json` later lost, recovery reconstructs the rounds this command had just zeroed, and an entry restored at `max_iterations` stops with `iterations` on its next event having done no work in the round. If it cannot be posted, `register` refuses and changes nothing: the entry keeps its iteration, its state and its cursor, and running the same command again once GitHub answers does the whole reset in one go.
-- A reset with a new `--harness` or `--session` makes two durable writes to GitHub, and they are ordered so a failure between them cannot leave GitHub and the registry disagreeing about which harness or session this PR belongs to. The reset comment goes first because it is safely repeatable: a count rebuilt from GitHub takes the LAST reset marker, so a second one counts as one. The identity block goes last, because that write is what a recovery reads the harness and the session out of. So a failed block write leaves a reset comment on the PR, the registry untouched, and both sides still naming the old identity; the same command run again completes the reset.
-- Changing `--harness` without giving a new `--session` drops the inherited session and starts a fresh one on the next fix round. This also applies when both harnesses use UUIDs: a Claude session does not belong to Codex. An explicit `--session` must have the chosen harness's format and is used as supplied.
+- A reset with a new `--harness` or `--session` makes two durable writes to GitHub. The reset comment goes first because it is safely repeatable: a count rebuilt from GitHub takes the LAST reset marker, so a second one counts as one. The identity block goes last, because that write is what a recovery reads the harness and the session out of. If a same-harness block write fails, the registry keeps its prior identity. For a cross-harness reset, the old entry is first fenced against dispatch; if the block write or ledger reservation is ambiguous, the fence remains and rerunning the same `register` command finishes the handoff after inspecting the last run. A failure before the identity write restores the prior entry.
+- Changing `--harness` on an existing entry drops the inherited session and starts a fresh one on the next fix round. This also applies when both harnesses use UUIDs: a Claude session does not belong to Codex. An explicit `--session` can attach only without a harness change, and must have the chosen harness's format.
+
+For a stopped PR whose local provider is exhausted, inspect `gallivant why widget#142` and confirm its last run has settled. Stop the coordinator with `gallivant down`, then run `gallivant register https://github.com/owner/widget/pull/142 --harness codex` and restart it with `gallivant up`. A cross-harness reset requires the coordinator's exclusive lock; it refuses while the daemon is running, so an old-provider dispatch cannot race the reset. The registration does not send a model request. The old execution ledger, result and run log remain under the same run tree. A new ledger is reserved for Codex before the registry changes, and recovery after `state.json` loss selects the latest ledger. A recorded handoff whose ledger is missing refuses dispatch until its matching backup is restored. The first fix prompt tells the new session to read the approved brief, local checkout, unpushed commits, PR and review threads, including after registry recovery. The former Claude conversation cannot be transferred. A reset starts the round count and feedback cursor from now, so earlier review comments do not trigger the new session. Post a **new** trusted PR comment beginning `/fix` with the work to continue; `@codex review` alone requests a reviewer, and `recheck` only reevaluates readiness. Do not repeat a successful `register`: each success posts another reset marker and restarts that cursor and count. A change between local harnesses refuses an unsettled run or any explicit `--session`: an ID's format cannot prove that the new provider owns that conversation. A PR with a saved brief keeps its original snapshot and acceptance criteria; the explicit register command records the new execution route separately from its original `harness:` field.
 
 When the block names a PRD that exists on the PR's branch, the daemon's own snapshot of it is taken, exactly as recovery does, because the completion gate reads that snapshot and nothing else: without it the gate is skipped and the PR can be marked ready with no acceptance criterion evaluated. A snapshot already on disk is kept rather than replaced with the copy the session could have edited, and a PRD the branch does not carry is logged and the PR watched without a gate.
 
@@ -618,3 +680,30 @@ Harnesses still invoke their own GitHub tools directly. A prompt and a later dae
 incorrect draft or branded phrase never appears briefly before correction. This implementation enforces daemon
 writes and readiness, not an exclusive network publication boundary. The encoded recovery record is also not secret:
 it can be decoded to inspect the precise existing branch/session identity.
+
+## Bitbucket setup and PR commands
+
+For an explicitly mapped GitHub review mirror, `npm run promote:bitbucket -- --github-pr URL --bitbucket-repo bitbucket.org/WORKSPACE/REPO --bitbucket-pr N` previews a commit-preserving handoff from a source checkout. It requires exact accepted source readiness, then refreshes the shared review/check policy. Apply requires the inspected plan digest. See [GitHub-to-Bitbucket promotion](bitbucket-promotion.md) for retained post-merge plans, idempotent PR updates and race handling. It never merges or deploys.
+
+Bitbucket Cloud dispatch is available with explicit repository credentials and review policy. Its complete first-party evidence adapter and the shared bounded review service are implemented; the private/public live reviewer matrix and clean Linux installation remain separate qualifications. A prior public disposable run proved PR publication and receipt acceptance in legacy no-reviewer mode only. See the [setup, review and troubleshooting guide](bitbucket-review.md) for prerequisites and limits. Bitbucket-only setup needs no GitHub sign-in; it does not install a pipeline or alter repository settings.
+
+`init` accepts `--host-config <json>` and `--base <branch>`. The installed `task-pr` command supports bound PR create/view/diff/edit/comment operations; `task-review` prepares and publishes independent reviewer results. These commands do not qualify a harness or authorize a model invocation.
+
+For the independent local reviewer, configure `review.mode: "first-party-required"` and `review.route: "codex"`, then run `gallivant review qualify --repo bitbucket.org/workspace/repository --run`. Run the same command without `--run` to inspect its durable result. A new task preflight refuses before author dispatch unless this exact executable/provider fingerprint qualified. To migrate a settled existing task, use `gallivant review policy HANDLE --mode first-party-required --reason "Enable the qualified independent local reviewer"`, then `gallivant recheck HANDLE`. That audited command preserves the task, PRD snapshot, PR and implementation session; editing config alone cannot remove its legacy policy.
+
+Review prompts remain at or below 100,000 bytes. Large changes are divided across at most `review.max_jobs` fresh restricted jobs and the reserved `review.budget_usd`; every path and criterion must be covered. A single large file is sliced or the aggregate stops explicitly as incomplete. Zero CI checks still require `review.zero_checks: true` and are never inferred from reviewer clearance.
+
+The default review allowance is 2,048 jobs and $100 in accounting reservations,
+with 60 minutes per job. Split inspections provide source-grounded reports;
+a separate whole-PR synthesis must clear before readiness. Coding fix rounds
+default to 60 with a $50 per-run allowance. Reviewer jobs and Git commits are
+not coding rounds: the displayed round advances when a corrective coding run
+settles, including a changed completion receipt. Existing task review limits
+remain pinned until an explicit `review policy` command and recheck.
+
+Reviewer qualification can use `review qualify --repo OWNER/REPO --run --wait`
+to keep the launch process alive until settlement. An explicitly inspected,
+owned stopped timeout/provider failure can be retried with `--retry --reason
+"explanation"` on that same command. This preserves its history and reserves a
+new bounded allowance; it never accepts a failed result or bypasses review.
+See [first-party review](first-party-review.md#waiting-for-qualification-and-explicitly-retrying-a-stopped-probe).

package/docs/config.md

@@ -9,19 +9,20 @@ while apply and key setup refuse before activation. Key paths are separate expli
 operator paths, and OpenSSH is pinned outside worker writes. See [learning](learning.md)
 for the CLI, bounds, separate extraction allowance and backup/rotation limitations.
 
-`~/.gallivant/config.json`, mode 600. `gallivant init` creates a local Codex or
-Claude configuration; `gallivant doctor` prints a suggested configuration when
-none exists. Set `GALLIVANT_HOME` to use another directory. Hosted providers need
+`~/.gallivant/config.json`, mode 600. `gallivant init`, run inside a checkout,
+creates a local Codex or Claude configuration, records that repository in `repos`
+and prints the `doctor` report; repeated runs preserve every key you have edited.
+`gallivant doctor` prints a suggested configuration when none exists. Set `GALLIVANT_HOME` to use another directory. Hosted providers need
 explicit configuration; they are not discovered from local executable paths.
 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. |
@@ -40,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
@@ -82,6 +84,12 @@ an awake machine or a continuously running Node host.
 qualify its event stream and unattended permissions; it is not a supported choice.
 Provider/model selection for local harnesses remains in each harness's own
 configuration; Gallivant does not add a general per-task local model router.
+Changing the native model configuration for the same local harness does not
+change Gallivant's recorded harness or session ID. A later `gallivant resume`
+still asks that CLI to resume its exact session, but whether the CLI applies the
+new model to that conversation is native provider behavior, not a Gallivant
+continuity guarantee. Gallivant does not pass a per-run `--model` flag or route
+around an exhausted provider account.
 
 ## The base branch
 
@@ -266,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.
@@ -296,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.
 
@@ -338,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
@@ -412,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`.
 
@@ -427,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/execution.md

@@ -785,7 +785,7 @@ is live or its gates have passed. Check the linked PR and the consumer's current
 release evidence before an installation:
 
 The connected execution successor is
-[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417),
+[`aporthq/agent-passport#417`](https://github.com/aporthq/agent-passport/pull/417) (not publicly readable),
 with canonical PRD `docs/prds/aport-task-delivery-workflow-integration.md` and job
 identity `aporthq/agent-passport/aport-task-delivery-workflow-integration`. It
 preserves the original T0–T9 requirements; the recorded plan requires the actual