@uchibeke/gallivant 0.2.1 → 0.3.0

package/docs/bitbucket-review.md

@@ -0,0 +1,330 @@
+# Bitbucket Cloud review setup and qualification
+
+Bitbucket Cloud dispatch and complete first-party evidence capture are implemented.
+The independent local review route is still **live-unqualified** until the public
+and private disposable repository matrix records a genuine blocking verdict,
+same-session correction and fresh exact-head clearance. Earlier disposable runs
+proved regular PR publication and receipt acceptance with **no reviewer
+configured**; they are not review evidence. The private coding session could also
+read the coordinator's merge-capable API-token file by path, so that historical
+coding-credential hold remains separate from reviewer credential isolation. Do
+not migrate an existing legacy run or start unattended work on the strength of
+offline fixtures. See the [qualification record](audit/bitbucket-review-qualification.md).
+
+## First setup, including a checkout with no existing configuration
+
+Use Node 22 or later, Git, and an explicitly selected installed local Codex or
+Claude executable. Bitbucket setup does not require `gh` or GitHub sign-in.
+Version/sign-in diagnostics do not prove model access. Existing GitHub defaults
+and runs retain their previous review semantics.
+
+1. Obtain an Atlassian **account API token** scoped to the intended workspace,
+   with `read:repository:bitbucket`, `write:repository:bitbucket`,
+   `read:pullrequest:bitbucket`, and `write:pullrequest:bitbucket`. Save it in a
+   private file (`chmod 600`). Supply the account email separately. An account
+   API token can be used with a free-plan repository; this does not require a
+   workspace/repository access-token subscription or Agentic Pipelines.
+2. For HTTPS Git, the coordinator uses the selected token as
+   `x-bitbucket-api-token-auth`; the API uses account email/token Basic auth.
+   For SSH Git, keep the API token and select the explicit SSH key/verified
+   known-hosts file described in [Git host setup](git-hosts.md). SSH authentication
+   alone cannot read or write PRs. The coding session receives neither token nor
+   SSH key through environment variables: its bounded PR mailbox asks the
+   coordinator to push and publish. A same-user coding process can still read
+   the configured private files unless a separate boundary denies those reads.
+   HTTPS and Cloud SSH checkout origins identify
+   the same repository; self-hosted servers and SSH aliases remain unsupported.
+3. Write a host settings file outside the coding checkout. Example:
+
+```json
+{
+  "api": {
+    "email": "operator@example.com",
+    "token_file": "~/.config/repository-access/bitbucket-api-token"
+  },
+  "git": { "transport": "https" },
+  "trusted_authors": ["{11111111-1111-1111-1111-111111111111}"],
+  "reviewer": null,
+  "required_checks": ["Tests"]
+}
+```
+
+Replace the example UUID with the operator's stable Bitbucket UUID, not a nickname.
+Select `reviewer: null` deliberately; the local first-party path needs no separate
+Bitbucket reviewer account. After `init`, configure the repository entry for a
+new reviewed run:
+
+```json
+{
+  "repo": "bitbucket.org/workspace/repository",
+  "reviewer": null,
+  "review": {
+    "mode": "first-party-required",
+    "route": "codex",
+    "max_input_bytes": 100000,
+    "max_jobs": 2048,
+    "budget_usd": 100,
+    "zero_checks": false
+  }
+}
+```
+
+Keep `review.legacy_no_review: true` only for a deliberately unreviewed legacy
+run while live qualification is unavailable. That mode still enforces configured
+CI, trusted commands, unresolved required feedback and the completion receipt,
+but its readiness record says `none`; it is never independently reviewed. The
+example check name must exactly match the repository's build status name. An
+empty `required_checks` list does not waive CI for a version-1 policy: a repository
+with no checks must explicitly set `review.zero_checks: true`. Missing/partial
+responses, rate limits, outages and pending checks never pass.
+
+From the intended checkout:
+
+```sh
+gallivant init --harness codex --host-config /absolute/path/bitbucket-host.json --base release/v2
+gallivant doctor
+```
+
+`--host-config` imports settings for the verified checkout's host. It creates a
+new config, or accepts unchanged settings while preserving UUID bindings added
+by setup. JSON member order does not matter; changed or omitted policy and
+conflicting identity bindings are refused. `--base` is validated and saved on the repository entry.
+`init` binds repository/workspace UUIDs, reads the selected base and account push
+role, and verifies Git's base SHA against the API. `doctor` distinguishes unknown
+write scopes from observed read access. Only an actual write can prove Git push,
+PR creation and comment write permission. Setup never installs a pipeline,
+creates a credential, changes repository protection, or makes a paid model call.
+It reports dispatch availability separately from transport access.
+
+Host settings live under `git_hosts["bitbucket.org"]`. `repositories["workspace/repo"]`
+may override `api`, `git`, `reviewer`, `trusted_authors`, and `required_checks`,
+alongside the UUID binding. Each override replaces that setting, not another
+host's credentials. A `repos` object may override reviewer/trust/check policy;
+precedence is repository entry, host repository binding, host settings. Historical
+top-level reviewer/trust defaults apply only to GitHub. Reviewer objects for
+Bitbucket must supply every required field; the GitHub mention is rejected.
+
+## Independent local Codex reviewer
+
+The host adapter binds the repository UUID, PR number, full head and base object
+IDs, and merge base. It paginates `diffstat/<head>..<base>?topic=true`, compares
+that changed-path inventory to the complete raw comparison, and reads regular
+UTF-8 source at the merge base and head through `src/{commit}/{path}`. Added,
+modified, removed and renamed files all carry before/after text as applicable.
+Unsupported binary, subrepository, missing-patch, duplicate, truncated, stale,
+rate-limited, redirected and oversized evidence is refused. The coordinator
+captures bounded symlink target data as untrusted Git objects without following
+the link. Unsupported targets or ambiguous type transitions block review.
+The PR binding is read again after capture. The API token stays behind the host boundary and is not
+part of the reviewer prompt or environment.
+
+The coordinator requests bounded PNG and JPEG sides at the exact revisions and
+requires a separate image-capability qualification before launching visual jobs.
+It combines their validated reports with text review and whole-PR synthesis.
+The image qualification does not itself qualify the host or complete a PR review;
+the [disposable live screenshot review](audit/bitbucket-review-qualification.md#live-image-qualification-and-disposable-review-2026-11-03)
+reached a clear verdict after its owned outputs were recovered; the resend PR
+has not been rechecked. Preserve the original files and incomplete state when any
+capability or evidence is unavailable.
+
+Qualify the exact configured executable/provider route only after authorizing its
+separate paid challenge:
+
+```sh
+gallivant review qualify --repo bitbucket.org/workspace/repository
+gallivant review qualify --repo bitbucket.org/workspace/repository --run --wait
+gallivant review qualify --repo bitbucket.org/workspace/repository
+```
+
+The first and last commands are read-only. `--run` starts at most the one durable
+qualification job for that fingerprint; CLI version and sign-in checks alone do
+not prove selected-model access. Start refuses before author dispatch if the route
+cannot qualify.
+
+Qualification fingerprints use the adapter's selected provider environment,
+configuration, credentials and executable. Parent-agent session and tool-call
+IDs do not invalidate an existing qualification. The private Codex profile drops
+the desktop-only `daybreak` flag for CLI compatibility; strict inspection of
+effective permissions and managed policy remains required.
+
+For a settled existing run that still has the explicit legacy snapshot, use the
+audited transition and then recheck the same PR:
+
+```sh
+gallivant review policy HANDLE --mode first-party-required \
+  --reason "Enable the qualified independent local reviewer"
+gallivant recheck HANDLE
+```
+
+This is the only path that removes the saved legacy policy. It retains the task
+identity, original PRD snapshot, PR, checkout and implementation session. A
+failed route preflight changes nothing and launches no review. Do not edit an
+active WebBabyShower brief or local policy as an implementation test.
+
+Each reviewer job is a fresh restricted Codex execution with no implementation
+session, context mounts, tools, network, host/Git credential or publication
+authority. The 100,000-byte input cap applies to every job. Large evidence is
+split into immutable source/patch slices, including a single large lockfile or
+line; every slice repeats the aggregate identities and all acceptance criteria.
+Clearance requires every piece to complete and match. `max_jobs`, `budget_usd`
+and per-job timeout bound the aggregate. If the full change does not fit those
+bounds, the run stops with `review-incomplete`; no path or suffix is omitted.
+
+## External Bitbucket reviewer account
+
+This is an alternative external-review setup, not required by the local path.
+Use a separate Bitbucket account for the automated reviewer. Configure its stable
+UUID, never its display name, nickname, the coding account, or a Pipeline label:
+
+```json
+{
+  "reviewer": {
+    "actor_id": "{22222222-2222-2222-2222-222222222222}",
+    "rereview_comment": "Review the current commit and post a work-review verdict.",
+    "blocking_pattern": "\\bP[01]\\b"
+  }
+}
+```
+
+This fragment belongs in the coding coordinator's host/repository policy. The
+reviewer token does **not** belong there. On a separate operator-controlled
+reviewer machine, OS account, or isolated container, store another private config
+with the same policy and the **reviewer** account email/token in `api`. Its token
+needs repository read and PR read/write. The coding agent must have no filesystem,
+environment, secret-store or container access to that credential. A private file
+in a directory readable by the coding identity is not isolation. The review model
+needs only the prepared input and a read-only checkout, never publication secrets.
+Codex requires its own supported sign-in or provider credentials and actual model
+access; CLI installation/sign-in alone cannot qualify it.
+
+The installed `task-review` tool separates preparation and publication from
+inference. It never invokes a model, changes model/provider settings, or posts a
+review request. These review transport steps are covered by offline tests; the
+intervening Codex execution and end-to-end publication are still unqualified:
+
+```sh
+task-review prepare --config /private/reviewer-config.json \
+  --url https://bitbucket.org/workspace/repo/pull-requests/7 > review-input.json
+```
+
+In the isolated reviewer checkout, use the operator-selected Codex executable
+under the existing read-only review permissions to inspect the input's exact
+head and diff. Follow `review-input.json.instructions`. Save its actual response
+as `review-result.json`, containing only this JSON shape:
+
+```json
+{
+  "head_sha": "0123456789012345678901234567890123456789",
+  "verdict": "blocking",
+  "summary": "Concrete findings from reviewing this exact commit."
+}
+```
+
+A successful model execution is not a verdict. Outside the model process, publish
+its response with the separate reviewer credential:
+
+```sh
+task-review publish --config /private/reviewer-config.json \
+  --url https://bitbucket.org/workspace/repo/pull-requests/7 \
+  --input review-input.json --result review-result.json
+```
+
+Publication verifies the authenticated actor differs from the coding author and
+matches `reviewer.actor_id`. It rechecks repository UUIDs, PR number, branches,
+base, full head SHA and diff hash against the prepared input. An explicit retry
+reuses an identical verdict only while it remains the reviewer's latest decision.
+A superseded match causes a new publication, so blocking/clear/blocking decisions
+take effect even on the same head. Uncertain comment writes are not silently
+retried. Keep the real model transcript/run ID with qualification
+artifacts: a manually authored fixture result cannot prove a Codex review.
+An ordinary Pipeline can orchestrate these steps when an operator explicitly
+installs it, enables Pipelines, and configures provider and reviewer secrets in an
+isolated trusted job. Do not expose those secrets to arbitrary PR code or the
+coding step. No paid Agentic Pipelines capability is assumed or installed.
+
+The posted comment contains a `work-review` fenced JSON block. Only the configured
+actor and a complete exact current SHA can clear readiness. Abbreviations, old-head
+approvals, prose claiming a successful Pipeline, or a run with no posted verdict
+are silence. Native Bitbucket approvals do not identify a reviewed commit and
+cannot clear an automated-review gate. Native change requests and unresolved tasks
+remain blockers until their authors remove/resolve them, including after one fix
+round has consumed their events.
+
+Trusted humans can post `/fix ...`. Inline findings use a verified code link to
+the full source SHA or a standalone `Reviewed commit: <40-character-sha>` line.
+Unknown inline heads stop readiness with the source link rather than silently
+approving or dispatching a guessed head. A command explicitly naming an older head
+is ignored. Replies authored by the coding account do not become new fix requests.
+
+## Session PR operations and recovery
+
+`task-pr` is the bounded PR CLI used by Bitbucket start/fix/resume prompts. In a
+task session it writes a bounded request to the checkout's mailbox; the daemon
+verifies the saved repository, branch, base and PR identity, then uses its own
+Git and API credentials. `push`, `create`, `edit` and `comment` push committed
+HEAD through the coordinator before publication. `view` and `diff` are read
+operations. The agent receives no Git or PR token and no SSH key in its
+environment. Its observed ability to read the token file remains a dispatch
+blocker. The
+coordinator disables checkout hooks when running Git, so an agent-written
+pre-push hook cannot run with coordinator authority. The mailbox has no merge,
+deployment or repository-settings operation. Direct `task-pr` use outside an
+agent session still requires an explicitly bound API credential.
+The PR CLI created and reconciled a disposable private PR, read its exact head,
+posted a comment and updated its body. A separate live public task also used it
+to open and update a regular PR. See the [qualification record](audit/bitbucket-review-qualification.md).
+
+After the credential boundary is qualified, local PRD commands use the verified
+checkout, and `register` uses the exact PR
+URL. Host-qualified state/worktree keys
+prevent a same-named GitHub repository controlling a Bitbucket PR. Base overrides
+flow through clone, PR publication and later base updates. Use `gallivant doctor`
+to confirm access and policy before `gallivant start <prd> --base <branch>`.
+Hosted providers with a GitHub-bound environment are incompatible. A snapshot
+provider must pass the same publication and qualification checks as a local one.
+
+Bitbucket snapshots supply one coherent set of paginated comments, participants,
+required tasks and statuses for the head. The shared event cursor, bounded fix
+round, session continuation, completion gate and chain engine consume those
+records. Unreadable snapshots preserve cursors. A changed PR branch/base or a
+replacement repository stops with `pr-identity`. Declined/superseded PRs cannot
+become done. A merged PR must match the recorded head and its merge commit must
+be an ancestor of the intended base before completion or chain advancement.
+No command merges the PR, force-pushes, deploys or alters protections.
+
+## Troubleshooting
+
+- `NO_CREDENTIAL`: select the account email and private API-token file under the
+  correct host/repository. An SSH key, GitHub token or token file without an email
+  is insufficient. Restore scopes before retrying; do not broaden another host.
+- `reviewer.actor_id` / explicit reviewer errors: use the actual UUID and producer
+  configuration, or explicitly choose no-reviewer mode. Do not use `@codex review`.
+- `BB_INCOMPLETE`, `BB_STALE`, HTTP 429/5xx: restore API access or wait for the read
+  retry. Never clear a cursor or turn missing evidence into an empty collection.
+- `REVIEW_UNQUALIFIED`: confirm the exact `harness.codex.bin`, selected model and
+  provider access, then explicitly run `review qualify --repo ... --run`. Do not
+  substitute `--version`, sign-in status or an offline fixture.
+- `review-incomplete` / `REVIEW_INCOMPLETE`: inspect the named missing identity,
+  path, patch or required job count. For a large complete text change, raise
+  `max_jobs` and `budget_usd` only within an operator-approved bound, then select
+  the new policy explicitly. Unsupported binary, subrepository, malformed link, rate-limited,
+  redirected or stale evidence must be corrected; increasing a byte cap is not a
+  workaround.
+- Screenshot evidence: check `review qualify --repo ... --capability image` for
+  the exact route. Repair the reported native or provider issue before a separately
+  authorized `--run`; do not repeat an unchanged failed launch. PNG/JPEG limits
+  and all image sides still apply. Unsupported formats remain incomplete.
+- `pr-identity`: inspect source/base/repository/head and restore the recorded
+  identity. A decline or unproven merge needs operator reconciliation, not a new
+  paid run or an automatic chain advance.
+- Access probe fails: check the selected coordinator SSH key or HTTPS token and
+  the account API token for PR operations. The coding session receives neither.
+  Re-run `doctor`, then resume the existing task rather than starting a duplicate.
+- PR mailbox timeout: confirm the daemon is running and can read the selected
+  repository; retry the same `task-pr` operation. Do not give the coding session
+  a token to work around the mailbox.
+
+API semantics are based on Atlassian's [PR APIs](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/),
+[commit ancestry API](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-commits/),
+[source metadata](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-source/),
+and [account API-token guidance](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/).

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

@@ -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. |
@@ -115,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
@@ -142,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.
 
@@ -188,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
@@ -212,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.
 
@@ -226,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. |
@@ -647,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).