@uchibeke/gallivant 0.2.0 → 0.2.1

package/README.md

@@ -2,86 +2,102 @@
 
 **Give an agent a task. Let the review loop run. Go outside.**
 
-Gallivant turns repository tasks into reviewed pull requests. It starts an agent,
-watches CI and reviewer feedback, and continues the same session to fix issues.
-You can follow progress and send corrections from a local dashboard. **You decide
-what gets merged.**
-
-Use it for code, documentation, research or content that belongs in a GitHub
-repository. Start with a plain-language request or a written brief.
+Gallivant turns a repository task into a reviewed pull request. It runs a coding
+agent in a separate checkout, opens the PR, watches CI and reviewer feedback, and
+continues the same session until the PR is ready for you. You decide what merges.
 
 ```text
 Your task → agent works → PR → review + CI → fixes → ready for you
                                  ↑___________|
 ```
 
-## Install
-
-You need **macOS or Linux, Node 22+, Git, GitHub CLI and jq**. For your first run,
-use signed-in **Codex CLI 0.160.0+** or **Claude Code 2.1.263+**. Provider usage is
-billed to your own account. [Full prerequisites](docs/install.md).
+## Set up in one command
 
-Check the [registry version](https://www.npmjs.com/package/@uchibeke/gallivant). Once a
-version is available, install it with `npm install -g @uchibeke/gallivant`. If the package
-is not published yet, install from source:
+Run this inside the Git checkout you want to work in:
 
 ```sh
-git clone https://github.com/uchibeke/gallivant.git
-cd gallivant
-npm ci --ignore-scripts
-npm link
-gallivant --version
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-[Release status and checks](docs/releasing.md).
+The setup flow below requires **0.2.1 or newer**. At verification on 2026-10-20,
+npm's `latest` was still 0.2.0, whose `init` only creates the config. A maintainer
+must [publish 0.2.1](docs/releasing.md) before this command provides repository
+registration, repeat safety and the diagnostic report described below.
 
-## Set up
+`init` writes a private config at `~/.gallivant/config.json`, records this
+repository, creates a separate directory for task checkouts, and ends with the
+same report as `gallivant doctor`: one line per check and the exact fix for each
+failing one. Run it again in another repository to add that repository; nothing
+else in the config changes.
 
-```sh
-gh auth status
-codex login status                    # use Claude sign-in if you choose Claude
-gallivant init --harness codex         # or --harness claude
-gallivant doctor
-```
+Before you run it you need:
 
-`init` creates local configuration and a separate task-checkout directory. It
-preserves existing config, credentials and global agent settings. Follow the
-fixes from `doctor`; [setup instructions](docs/install.md) cover authentication,
-harness permissions and repository protection.
+| Prerequisite | Check | If it fails |
+| --- | --- | --- |
+| macOS or Linux, Node 22+, Git, jq | `node --version`, `git --version`, `jq --version` | install from your package manager |
+| GitHub CLI signed in | `gh auth status` | `gh auth login` |
+| Codex CLI 0.160.0+ signed in | `codex login status` | `codex login` |
+| or Claude Code 2.1.263+ signed in | `claude auth status` | `claude auth login` |
 
-Enable the Codex GitHub review integration on the target repository, or choose
-another reviewer. If you want CI and trusted human feedback without a review bot,
-explicitly configure `"reviewer": null`. The default waits for Codex review.
+A signed-out `gh` or harness stops `init` before it writes anything, and the
+message repeats the login command above. `init` never asks for passwords, tokens
+or browser cookies; sign in with each tool's own flow. Inference is billed to
+your own provider account.
 
-**Prefer an agent to handle setup?** Give it the
-[setup-agent instructions](docs/agent-setup.md). They cover inspection, installation,
-configuration, verification and the points where your input is required.
+`npx` downloads and runs the package on demand. Nothing is installed globally
+and no `gallivant` command is added to your PATH. If you want one:
 
-## Run your first task
+```sh
+npm install -g @uchibeke/gallivant
+```
 
-Inside a repository you can push to. This example uses Codex; if you configured
-Claude, replace `--harness codex` with `--harness claude` before running it:
+The rest of this page writes `gallivant`. With `npx`, read that as
+`npx --yes @uchibeke/gallivant`. Contributors who want to run from a source
+checkout: see [installing from source](docs/install.md#install-from-source).
+
+## Finish what setup cannot do for you
+
+`doctor` names these. `init` does not do them, because each needs a decision
+from you or an account with a third party.
+
+- **Reviewer.** The default loop waits for the Codex GitHub review integration
+  (`chatgpt-codex-connector[bot]`). Enable it on the repository, configure
+  another reviewer, or set `"reviewer": null` in the config to rely on CI and
+  trusted human feedback. Without one of these, the first PR waits for a review
+  that never arrives. See [the reviewer key](docs/config.md#the-reviewer-object).
+- **Branch protection.** `doctor` prints the `gh api` call that creates a
+  ruleset blocking direct and force pushes to the default branch. Run it
+  yourself. Setup never changes repository settings.
+- **Harness guardrails.** The APort hook for Claude or Codex is installed by its
+  own `npx @aporthq/aport-agent-guardrails` command, and Codex asks you to trust
+  the hook inside its own interface. Setup does not install hooks.
+  [Guardrails](docs/guardrails.md) explains what each control covers.
+- **Spend.** Defaults are 30 fix rounds per PR and a 5 USD per-run cap that
+  only Claude enforces natively. Review [limits](docs/config.md) before
+  unattended work.
+
+## Run a first task
 
 ```sh
-cd /path/to/your/repository
 gallivant task "Document how to run the existing tests in CONTRIBUTING.md. Use the commands already defined in the repository. Change documentation only." \
   --harness codex --verify 'git diff --check' --run
 gallivant start
 ```
 
-`task` prepares a brief and asks for missing information. `--run` authorizes
-implementation when that brief is ready, including after clarification. Omit it
-to inspect the draft first. Follow the printed `Next` action using your task's ID
-and revision. Preparation also uses inference.
-
-`gallivant start` opens **http://127.0.0.1:8791** and ensures the daemon is running.
-Without a PRD path, it does not submit another task. Closing the browser does not
-stop the work.
-
-With the default configuration, **ready** means the configured checks, reviewer
-and acceptance gate passed. Inspect status for skipped-gate warnings, review the
-PR and merge when you choose. Missing access, evidence or exhausted limits produce
-an inspectable stop instead.
+What happens: `task` uses your harness to prepare a brief, which is a paid
+inference call, and may ask you questions. `--run` authorizes implementation
+once the brief is ready; omit it to read the draft first and follow the printed
+`Next` action. The agent then works in a clone under `~/.gallivant-worktrees`,
+pushes a branch, opens a PR against the default branch, and the daemon watches CI
+and the reviewer, sending each round of feedback back to the same session.
+`gallivant start` opens the dashboard at **http://127.0.0.1:8791** and keeps
+the daemon running; closing the browser does not stop the work.
+
+Expected outcome: a PR with a small CONTRIBUTING.md change and a completion
+receipt in its body, and `gallivant status` showing the entry as **ready** once
+checks, reviewer and the acceptance gate pass. You review and merge. Missing
+access, failing checks or an exhausted round allowance produce an inspectable
+stop instead; `gallivant why <handle>` explains it.
 
 ### Bring a written brief
 
@@ -96,6 +112,20 @@ gallivant start docs/prds/add-csv-export.md
 You do not have to write a PRD yourself. Both entry points use a validated brief
 and the same review loop. [Writing briefs](docs/prd.md) · [Task commands](docs/tasks.md).
 
+## How the review loop runs
+
+1. The agent implements the brief, runs the brief's verification commands and
+   opens the PR.
+2. Each tick (every two minutes by default) the daemon reads CI and reviewer
+   state. A blocking review or a failing check starts a fix round in the same
+   agent session, and the fix is pushed to the same PR.
+3. Rounds stop at `max_iterations` (30 by default), when the reviewer stays
+   silent for `stall_hours`, or when a run exceeds its timeout. Every stop is
+   recorded with a reason you can read with `gallivant why`.
+4. **Ready** means the configured checks, reviewer and acceptance gate passed.
+   Nothing merges automatically. Natural-language tasks stop at a review
+   handoff by default; choose `integrated` to keep watching until you merge.
+
 ## While it works
 
 | What you need | Action |
@@ -128,6 +158,9 @@ base. You can plan longer work while retaining the merge decision.
 
 ## Harness support
 
+`init --harness` accepts `codex` and `claude`. Other adapters are configured by
+hand in `config.json`; see [configuration](docs/config.md#execution-providers).
+
 | Harness (`harness` key) | Runs on | Prepare requests | Implementation status |
 | --- | --- | --- | --- |
 | Claude Code (`claude`) | Your host | Yes | Recommended; live usage evidence |
@@ -194,6 +227,11 @@ for the installed version's flags.
 [Commands](docs/commands.md) · [Configuration](docs/config.md) ·
 [Dashboard](docs/app.md) · [All guides](docs/README.md)
 
+**Asking a coding agent to set this up?** Give it the
+[setup-agent instructions](docs/agent-setup.md). They cover inspection, the
+`npx` command, the points where your login or decision is required, and what a
+setup run may not do on its own.
+
 Embedding the same workflow in another application? See
 [task delivery](docs/task-delivery.md). Installing this CLI does not deploy a
 hosted service or publish a chat plugin.

package/bin/gallivant.mjs

@@ -15,7 +15,7 @@ import { newPrd } from "../lib/commands/new.mjs";
 import { resume } from "../lib/commands/resume.mjs";
 import { startServices } from "../lib/commands/start_services.mjs";
 import { trackerPort, stopTracker } from "../lib/tracker_process.mjs";
-import { init } from "../lib/commands/init.mjs";
+import { init, renderInit } from "../lib/commands/init.mjs";
 import { VERSION } from "../lib/fs.mjs";
 import { hasConfig } from "../lib/config.mjs";
 import { resolveHandle } from "../lib/state.mjs";
@@ -29,7 +29,8 @@ import { safeDisplay } from "../lib/learning_data.mjs";
 const HELP = `gallivant: give an agent a task, let the review loop run, go outside.
 
   gallivant init [--harness codex|claude] [--worktrees <directory>]
-                                         create a private config; never overwrite settings or sign in for you
+                                         set up the repository you are in: private config, this repo in repos,
+                                         then doctor's report. Safe to repeat; never signs in or overwrites settings
   gallivant --version                    print the installed version
   gallivant doctor [--send] [--probe]   install checklist and health probe
   gallivant doctor --network <https-origin> [--json]   bounded DNS/HTTPS diagnosis
@@ -111,9 +112,12 @@ async function dispatch(argv) {
   if (values.version) { console.log(VERSION); return 0; }
   if (values.help || !cmd || cmd === "help") { console.log(HELP); return 0; }
   if (cmd === "init") {
+    if (arg) throw new Error("init takes no positional argument; run it from inside the target checkout");
     const r = await init({ harness: values.harness, worktrees: values.worktrees });
-    console.log(`Created ${r.file}\nHarness: ${r.harness}\nWorktrees: ${r.config.worktrees}\n\nNext: gallivant doctor\nComplete the harness guardrail and repository setup before starting work:\n  https://github.com/uchibeke/gallivant/blob/main/docs/install.md\nPackaged templates:\n  ${r.templates.passport}\n  ${r.templates.sandbox}`);
-    return 0;
+    const report = renderDoctor(r.doctor);
+    console.log(renderInit(r, report));
+    // Doctor's exit code, so a script or an agent reading only the status knows whether setup still has open items.
+    return report.exitCode;
   }
   if (values.foreground && cmd !== "serve") throw new Error("--foreground is available only with serve");
   if (values.foreground && values["no-server"]) throw new Error("--foreground cannot be combined with --no-server");

package/docs/README.md

@@ -1,7 +1,9 @@
 # Documentation
 
-Start with [installation and your first run](install.md), then choose how to
-describe the work. [Natural-language tasks](tasks.md) prepare a reviewable brief
+Start with [installation and your first run](install.md): inside the target
+checkout, `npx --yes @uchibeke/gallivant init --harness codex` (or
+`--harness claude`) writes the config, records the repository and prints the
+setup report. Then choose how to describe the work. [Natural-language tasks](tasks.md) prepare a reviewable brief
 from your request; [hand-authored PRDs](prd.md) let you write that brief directly.
 Both use the same validation, execution, GitHub review and completion workflow.
 Code, research and documentation can all be delivered as verifiable repository

package/docs/agent-setup.md

@@ -1,9 +1,10 @@
 # Let an agent set up Gallivant
 
-Give the prompt below to your coding agent. It can inspect prerequisites, install
-the CLI, create a private config and validate a first task. You handle account
-login and any required trust prompts. Setup does not need access to every private
-repository, and installing the CLI does not start a paid session.
+Give the prompt below to your coding agent. It can inspect prerequisites, run
+the published setup command, read the resulting report and validate a first task.
+You handle account login and any required trust prompts. Setup does not need
+access to every private repository, and running the setup command does not start
+a paid session.
 
 Start with **Codex or Claude and one repository**. Those are the harnesses supported
 by `gallivant init`. [Hosted Agents API](openai-agents.md) uses an explicit config
@@ -24,12 +25,15 @@ CLI --help and the docs matching the installed version. Prefer an already workin
 Codex or Claude setup. Preserve existing credentials, settings, running jobs,
 worktrees and uncommitted changes. Report proposed config changes without secrets.
 
-Install/configure the CLI and run the setup checks. If Gallivant is not yet
-published on npm, use the documented source installation. Do not overwrite an
-existing config, weaken security settings, install global hooks, change repository
-protections, sign into accounts or elevate privileges without the relevant user
-authorization. Never ask me to paste API keys or tokens into this conversation.
-Use the provider's login flow or a private credential file instead.
+From inside the target checkout, run the published setup command:
+npx --yes @uchibeke/gallivant init --harness codex (or --harness claude), then
+read its report. Do not clone the Gallivant repository or install it globally
+unless I ask. If the command stops because gh or the harness is signed out, tell
+me the exact login command it printed and wait; do not sign in for me. Do not
+overwrite an existing config, weaken security settings, install hooks, change
+repository protections or elevate privileges without my authorization. Never ask
+me to paste API keys or tokens into this conversation. Use the provider's login
+flow or a private credential file instead.
 
 Ask only for missing decisions: target repository and checkout, approved base
 branch, preferred available harness, first task scope, and allowed spending.
@@ -88,38 +92,45 @@ automatically commit, or switch a dirty checkout. Confirm which GitHub repositor
 and base branch the task should use; the current branch is not necessarily the
 approved PR target. Account login and Git identity belong to the user.
 
-## 2. Install and initialize
+## 2. Run the setup command
 
-Use the [current installation instructions](install.md#1-the-command). Before
-the first npm publication, install from source; `npm install -g @uchibeke/gallivant` is only
-an option after the package is published. Avoid `sudo npm install`; use a
-user-owned Node installation or prefix when global installation is not writable.
-Do not silently replace a different installed version while its daemon is running.
-
-After GitHub and the selected harness are signed in:
+Use the [current installation instructions](install.md#2-the-command). After
+GitHub and the selected harness are signed in, from inside the target checkout:
 
 ```sh
-gallivant --version
-gallivant --help
-gallivant init --harness codex
-gallivant doctor
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
 ```
 
-Use `--harness claude` for Claude. `init` is noninteractive; it creates a config
-only when none exists. It does not log in, install hooks or fix permissions.
-If a config exists, skip `init` and preserve its unrelated keys. The normal path
-is `~/.gallivant/config.json`; use `$GALLIVANT_HOME/config.json` if that variable is
-already set. Keep it private (mode `600`). Choose a worktrees directory outside
-the config home, using `init --worktrees /absolute/path` if needed.
-
-Before a real run, finish the [harness guardrail setup](install.md#6-aport-on-claude-code)
+`npx` runs the published package on demand; it installs nothing globally and
+does not clone this repository. `init` is noninteractive. It refuses, writing
+nothing, when the directory is not a GitHub checkout, `gh` or the harness is
+signed out, or the login cannot push to the repository; report the printed
+command to the user instead of working around it. Otherwise it creates
+`~/.gallivant/config.json` (mode 600) when none exists, records the current
+repository in `repos` once, creates the worktrees directory and prints the
+`doctor` report. Exit status `1` means checks remain, not that setup failed.
+
+With an existing config, `init` keeps every key as written and adds only the
+current repository. Do not edit unrelated keys. The normal path is
+`~/.gallivant/config.json`; use `$GALLIVANT_HOME/config.json` if that variable is
+already set. Pass `--worktrees /absolute/path` only on first creation; later
+runs refuse a different directory.
+
+If the user prefers a persistent command, `npm install -g @uchibeke/gallivant`
+is the documented option; ask before installing globally. Avoid `sudo npm
+install`; use a user-owned Node installation or prefix. Do not silently replace
+a different installed version while its daemon is running.
+
+Before a real run, finish the [harness guardrail setup](install.md#7-aport-on-claude-code)
 for the selected harness. Some steps require human interaction: for example,
 Codex's initial `/hooks` trust prompt cannot be automated. Report such a blocker
 instead of changing the enforcement level or bypassing it.
 
-Add the authorized repository to `repos` and its approved base where necessary,
-following [configuration](config.md#the-base-branch). Review the config diff without
-printing credentials. Confirm these decisions before dispatch:
+`init` records the repository without a base branch; its pull requests target
+the default branch unless the user chooses otherwise with `start --base` or a
+`{ "repo", "base" }` entry, following [configuration](config.md#the-base-branch).
+Review the config diff without printing credentials. Confirm these decisions
+before dispatch:
 
 | Decision | What must be established |
 |---|---|
@@ -129,8 +140,9 @@ printing credentials. Confirm these decisions before dispatch:
 | Completion evaluator | Default APort hosted confirmation needs network access. A local evaluator is an explicit user choice, not an automatic workaround for a failure. |
 | Cost | Confirm `max_iterations`, provider budget controls and allowed spend. `max_budget_usd` is a native per-run dollar cap for Claude; other local harnesses have no equivalent enforced dollar cap. |
 
-Run `gallivant doctor` again and report every failure. Do not treat “signed in
-(API unchecked)” as proof of inference access. `doctor` without extra flags checks
+Run `gallivant doctor` (or `npx --yes @uchibeke/gallivant doctor`) again and
+report every failure. Do not treat “signed in (API unchecked)” as proof of
+inference access. `doctor` without extra flags checks
 configuration, credentials and repository access without launching a model run.
 `doctor --probe` launches a real Claude sandbox test when Claude is configured;
 `doctor --send` sends a real notification. Use those only when authorized.
@@ -206,9 +218,11 @@ review and merge.
 
 ## What setup verification proves
 
-The package's `npm run test:install` smoke test installs the tarball into a
-throwaway directory, uses fixture CLI credentials, initializes a private config,
-loads the packaged PRD template, and checks an offline brief. It does not use a
-real account, invoke a model or certify a provider's current availability.
-A first authorized end-to-end task is still needed to verify the user's actual
-repository permissions, provider entitlement, sandbox, CI and review integration.
+The package's `npm run test:install` check packs the tarball and runs the
+README's `npx` setup command against it from a disposable repository, with
+fixture `gh` and `codex` commands and a throwaway home. It proves which binary
+ran, the config and directory permissions, repository registration, repeat
+safety and the printed next steps. It does not use a real account, invoke a
+model or certify a provider's current availability. A first authorized
+end-to-end task is still needed to verify the user's actual repository
+permissions, provider entitlement, sandbox, CI and review integration.

package/docs/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). |
@@ -46,12 +46,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]`
 
@@ -217,8 +244,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.
 

package/docs/config.md

@@ -9,9 +9,10 @@ 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.
 
@@ -82,6 +83,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
 

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