@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/docs/install.md

@@ -0,0 +1,398 @@
+# Install
+
+Get one repository task from a brief to a reviewed pull request. One command sets
+up a repository; `doctor` tells you what still needs your decision or login; then
+you start a small task. Gallivant keeps the implementation and review loop moving
+and you review and merge.
+
+**Using a coding agent to set this up?** Give it the [agent setup guide](agent-setup.md).
+It includes a copy/paste prompt, the setup checks and the point where a real run starts.
+
+## 1. Prerequisites
+
+Requirements shared by the coordinator: macOS or Linux, Node 22 or newer, Git,
+`gh` signed in, and `jq`. For the recommended local path, use signed-in Codex CLI
+0.160.0+ or Claude Code 2.1.263+ (Codex implementation accepts 0.158.0+, but
+plain-language preparation needs 0.160.0+). Hosted OpenAI Agents execution has a
+separate setup below and needs no local Codex or Claude binary. See the
+[capability matrix](../README.md#harness-support) before choosing another harness.
+
+| Prerequisite | Check | If it fails |
+| --- | --- | --- |
+| Node 22+ | `node --version` | install Node from your package manager or a version manager |
+| Git and jq | `git --version`, `jq --version` | `brew install git jq`, `apt install git jq` or `dnf install git jq` |
+| GitHub CLI signed in | `gh auth status` | `gh auth login` |
+| Codex CLI signed in | `codex login status` | `codex login` |
+| Claude Code signed in | `claude auth status` | `claude auth login` |
+| Git identity | `git config --get user.name`, `git config --get user.email` | `git config --global user.name "..."` and `user.email` |
+
+Each login belongs to that tool's own flow. Nothing in Gallivant asks for a
+password, token or browser cookie, and `init` stops before writing anything when
+`gh` or the selected harness is signed out.
+
+Linux installations need process inspection through `ps` with `lstart`, `command`,
+PID and process-group fields (normally the `procps`/`procps-ng` package). Minimal
+containers may omit it. Keep process inspection available: uncertain ownership
+blocks safe restart rather than allowing overlapping agents. The CI baseline is
+Ubuntu with Node 22/24; other distributions must also satisfy their harness and
+sandbox prerequisites.
+
+For DNS errors or stalled provider calls, see [network diagnosis and recovery](network-recovery.md).
+The diagnostic command works before configuration or login, on Linux and macOS.
+
+## 2. The command
+
+Inside the Git checkout you want Gallivant to work in:
+
+```bash
+cd /path/to/your/repository
+npx --yes @uchibeke/gallivant init --harness codex    # or: --harness claude
+```
+
+This setup flow requires **0.2.1 or newer**. On 2026-10-20, npm's `latest` was
+still 0.2.0: its `init` creates the config only, so repository registration and
+`doctor` must be done separately. A maintainer must [publish 0.2.1](releasing.md)
+before the command above provides the flow below; setup does not publish it.
+
+`npx` downloads the published `@uchibeke/gallivant` package into npm's cache and
+runs its `gallivant` command. Nothing is installed globally, no `gallivant`
+command is added to your PATH, and this repository is not cloned. The command
+ends by saying so and printing both the next `npx` command and the optional
+persistent install:
+
+```bash
+npm install -g @uchibeke/gallivant     # optional; then use plain `gallivant`
+gallivant --version
+```
+
+If the shell cannot find `gallivant` after a global install, the `bin` directory
+under `npm prefix -g` is not on your PATH. Avoid `sudo npm install`; use a
+user-owned Node installation or prefix. The rest of this guide writes
+`gallivant`; with `npx`, read that as `npx --yes @uchibeke/gallivant`.
+
+### What `init` does
+
+1. Refuses to continue, writing nothing, when the directory is not a Git
+   checkout, its `origin` remote is not a github.com repository, `gh` is signed
+   out, the selected harness is missing, too old or signed out, or the resolved
+   run credential cannot see or push to the repository. Each refusal names the
+   command that fixes it. Classic credentials also need `public_repo` or `repo`
+   scope; a failed scope lookup stops setup before writing and asks you to retry.
+2. Creates `~/.gallivant/config.json` (mode 600) with your authenticated GitHub
+   login in `trusted_authors`, the selected installed harness, notifications
+   disabled and a separate `~/.gallivant-worktrees` directory for task checkouts.
+   Use `--worktrees /absolute/path` to put checkouts elsewhere, outside the
+   config home.
+3. Records the repository in `repos` once, by its lowercased `owner/name`.
+4. Prints the `doctor` report and exits with its status: `0` when every check
+   passes, `1` while something still needs you.
+
+Running it again is safe. An existing config keeps every key as written,
+including custom harness binaries, `github_token_file`, `repos` entries with
+their base branches, `notify` and `worktrees`; the only change is the one `repos`
+entry for the current repository, and a repository already listed is not
+duplicated. `--worktrees` is refused when it differs from the configured
+directory, so edit the config to move checkouts. `--harness` adds the named
+harness when it is not configured yet and leaves the others alone.
+If both Codex and Claude are configured, pass `--harness codex` or
+`--harness claude` explicitly. Setup rechecks settings changed by another command
+before writing, so concurrent repository registrations preserve each other's entries.
+
+### What `init` leaves to you
+
+`doctor` reports these with the exact fix. `init` does not perform them:
+
+- **Reviewer.** The default reviewer is the Codex GitHub integration. Enable it
+  on the repository, configure another supported bot, or set `"reviewer": null`
+  to rely on CI and trusted human feedback. Without one of these, the default
+  loop waits for a review that cannot arrive. See [the reviewer key](config.md#the-reviewer-object).
+- **Branch protection.** Section 5 below. `doctor` prints the `gh api` call; you
+  run it.
+- **Harness guardrails.** Sections 7 and 8 below. APort's installer writes the
+  hook, and Codex asks you to trust it interactively.
+- **Credentials and notifications.** Sections 4 and 6 below are optional and
+  need your own token or ntfy topic.
+- **Starting work.** Setup never prepares or starts a task, so it spends nothing
+  on inference. Section 9 covers the first task and what `--run` authorizes.
+
+Global configuration lives in `~/.gallivant/config.json` (or
+`$GALLIVANT_HOME/config.json` when explicitly set). See [config.md](config.md)
+for every key. Task commands still need a target checkout: run inside it, pass
+`--dir` for natural-language tasks, or pass the PRD path for a written brief.
+
+### Install from source
+
+Contributors who want to run the checkout they are editing:
+
+```bash
+git clone https://github.com/uchibeke/gallivant && cd gallivant
+npm ci --ignore-scripts
+npm link
+gallivant --version
+```
+
+The package has locked runtime dependencies; `npm ci` installs them for a source
+checkout. `npm i -g .` copies instead of linking. This is not the path for using
+Gallivant; the published package is.
+
+### Hosted Agents API instead of a local CLI
+
+`init --harness` currently supports only `codex` and `claude`. For a hosted-only
+installation, create the config manually; do not install a local agent just to
+satisfy `init`. Create `~/.gallivant` privately, save the following as
+`~/.gallivant/config.json` with mode `600`, and replace the example account,
+project, model, repository, username and API-key path with your authorized values:
+
+```json
+{
+  "trusted_authors": ["YOUR_GITHUB_LOGIN"],
+  "worktrees": "~/.gallivant-worktrees",
+  "repos": ["YOUR_OWNER/YOUR_REPO"],
+  "harness": {
+    "openai-agents": {
+      "account": "my-service-account",
+      "organization": "org-selected",
+      "project": "proj-selected",
+      "api_key_file": "/absolute/path/to/private/agents-key",
+      "model": "YOUR_AUTHORIZED_MODEL",
+      "environment": "openai_hosted",
+      "container_size": "small",
+      "network": { "access": "disabled" },
+      "allowance": { "remainingUsd": 1, "reservedUsd": 0.2 }
+    }
+  },
+  "notify": null
+}
+```
+
+Keep existing config keys if you are adding this adapter to an existing install.
+The allowance is an illustrative local reservation, not a provider-enforced
+spend cap. API inference and hosted compute use API billing, independently of a
+ChatGPT subscription. Read the [Agents API guide](openai-agents.md) for scoped
+API permissions, packages, restricted networking and cancellation limitations.
+
+Run `gallivant doctor` before starting. Hosted results are verified locally in an
+OS sandbox: macOS needs `sandbox-exec` and Command Line Tools; Linux needs
+`/usr/bin/bwrap` and the supported namespaces. Missing sandbox support blocks
+execution/publication. Read-only account probes do not prove inference entitlement
+or a successful full lifecycle. Local APort hooks are not installed into hosted
+sessions; mandatory local-only policies cause a refusal.
+
+Use `--harness openai-agents` with `gallivant task`, or `harness: openai-agents`
+in your PRD. Keep the coordinator machine awake and online even though the agent
+runs remotely. **Codex Cloud is a different adapter:** its new dispatch is
+currently disabled because repository ownership of the selected environment
+cannot be verified. See [the Cloud gate](codex-cloud.md); local Codex and Claude
+remain available.
+
+## 3. Read the report
+
+`init` ends with the `doctor` report; `gallivant doctor` prints it again at any
+time. Every failing line carries the command or file that fixes it. Work through
+them in order, then rerun `doctor`. `doctor` without flags checks configuration,
+credentials and repository access without launching a model run; `doctor --probe`
+runs a real Claude sandbox test and `doctor --send` sends a real notification,
+so use those only when you mean to.
+
+## 4. GitHub auth
+
+By default Gallivant uses the login you already have, however you set it up. Nothing to configure beyond `gh auth status` passing. There is no file to copy for this: every git setting a run needs, the credential helper included, is passed in the run's environment.
+
+For local CLI runs, the coordinator resolves GitHub credentials before launching
+the harness. Supported sandbox settings restrict native credential-store access,
+so the run receives `GH_TOKEN` and an environment-carried Git helper. Sandbox
+coverage differs by harness; see [guardrails](guardrails.md). The token is not
+placed in command arguments or persisted by Gallivant, but the child process
+can read it. For hosted Agents execution, GitHub credentials stay with the local
+coordinator, which verifies and publishes returned artifacts.
+
+Do not create a separate `~/.gallivant/gitconfig` or override `GIT_CONFIG_GLOBAL`
+for a run. Current versions carry Git configuration in the run environment.
+`doctor` checks that transport with `git ls-remote` in an isolated home;
+a successful read does not by itself prove push permission.
+
+Where the credential comes from, first answer wins:
+
+1. `github_token_file`, if you set one in config.
+2. `GH_TOKEN` or `GITHUB_TOKEN` in the environment the daemon was started in.
+3. `gh auth token`. This is why any login works: `gh` answers from whichever store it used, whether that is a keyring, a secret service, or a plain `hosts.yml` on a machine with neither.
+
+If none of the three answers, `gallivant start` refuses and names all three. It does not start a session that would spend money and then fail to push.
+
+Optional, and recommended once the loop runs on repos that matter: a fine-grained personal access token limited to the participating repos, so an escaped run cannot reach every repository your login can. Create one at GitHub, Settings, Developer settings, Fine-grained tokens, with Contents, Pull requests and Issues read and write, Checks, Actions and Metadata read, and **no Workflows permission**. Save it and point config at it:
+
+```bash
+umask 077
+cat > ~/.gallivant/gh-token
+# Paste the token, then press Ctrl-D. Do not paste it into a shell command.
+# config.json: "github_token_file": "~/.gallivant/gh-token"
+```
+
+With the file set it wins over both of the other two. A missing, unreadable or empty
+file refuses the operation instead of falling back to a wider login. Restore it,
+or explicitly set `github_token_file` to `null` and restart the daemon to choose ambient authentication. `doctor` reports which source a run would use, whether the token is classic or fine-grained, and repository access and protection checks. Its Git credential-transport check uses
+`git ls-remote`; a successful read does not by itself prove push permission.
+
+This installation guide targets github.com repositories. The credential resolver
+recognizes enterprise hosts on an existing checkout, but new-task repository
+resolution and clone URLs currently use github.com. An enterprise login or token
+alone does not establish supported end-to-end operation.
+
+## 5. A ruleset on each repo
+
+The one control that stops a push to the default branch is GitHub's. `doctor` prints the exact `gh api` call for every repo in `repos`; it creates a ruleset that blocks deletion and force pushes on the default branch and requires a pull request, with no bypass actors. Gallivant never merges, so the ruleset costs nothing in the loop.
+
+## 6. Notifications
+
+Optional: create a topic on [ntfy.sh](https://ntfy.sh) or your own server, install the ntfy app, and set
+`"notify": { "ntfy": "https://ntfy.sh/<unguessable-topic>", "email": null }`.
+Set `notify.email` to also get each message by email through ntfy's `Email` header.
+With `"notify": null`, use the dashboard or `status`; there are no push notifications.
+
+```bash
+gallivant doctor --send      # sends one test message
+```
+
+Three kinds of message exist: `ready for a human`, `needs you: <reason>`, and a throttled `gallivant: <error>` when the daemon itself cannot work (gh not authenticated, a harness signed out). Nothing on merge. Nothing per round.
+
+## 7. APort on Claude Code
+
+APort's installer writes a PreToolUse hook with matcher `*` into whichever settings file it is pointed at, and the hook enforces one passport. Gallivant's passport is strict on purpose: writes only under the worktrees directory, control-plane directories blocked. Installed into `~/.claude/settings.json`, that policy would apply to every interactive Claude session you run and block your normal work. So the installer goes into a Gallivant-owned directory, and every run loads it with `--settings` plus `APORT_CLAUDE_CODE_CONFIG_DIR`. Nothing about the sandbox requires this; it is only about keeping Gallivant's policy separate from yours.
+
+If you would rather have one policy everywhere, point `harness.claude.settings` at `~/.claude/settings.json` and install APort there; the sandbox block then applies to your interactive sessions too.
+
+```bash
+APORT_CLAUDE_CODE_CONFIG_DIR=~/.gallivant/claude npx @aporthq/aport-agent-guardrails claude-code
+# choose "Create local passport file"; no hosted account is needed
+# init and doctor print the absolute path to the packaged passport template.
+cp /absolute/path/printed/by/init/passport.gallivant.json ~/.gallivant/claude/aport/passport.json
+# then edit it: replace {{worktrees}} with your worktrees path and {{home}} with your home directory
+```
+
+Merge the sandbox block from the packaged `claude-settings.json` path printed by
+`init` into `~/.gallivant/claude/settings.json` next to the hooks the installer wrote.
+Those absolute template paths work after either source or npm installation.
+Every Claude run loads that file with `--settings` and sets `APORT_CLAUDE_CODE_CONFIG_DIR`, so the hook and the sandbox apply only to Gallivant runs.
+
+On macOS the template enables `sandbox.enableWeakerNetworkIsolation` so `gh` can use Apple's certificate verification service. Without it, a valid GitHub login can fail inside the sandbox with `x509: OSStatus -26276`. This grants access to `com.apple.trustd.agent` and opens a potential exfiltration route through that service; review the [security tradeoff](guardrails.md#claude-on-macos-needs-certificate-verification) before applying it. The setting has no effect on Linux. `doctor` detects the missing setting on macOS and explains the repair; it does not change settings automatically.
+
+Any APort passport option works: a hosted passport created by the installer, an existing hosted `agent_id`, or a local file. With a hosted passport the limits live in the aport.io dashboard, so set `data.file.write` `allowed_paths` there to your worktrees directory and `blocked_paths` to the control-plane directories listed in `templates/passport.gallivant.json`; with a local passport, copy the template. `doctor` reports which mode is in use.
+
+```bash
+gallivant doctor --probe     # a real run: a write inside the checkout succeeds, a write outside is denied
+```
+
+The probe reads the APort audit log to tell apart a hook that never ran from a passport that allowed the write, and prints the fix for each.
+
+## 8. APort on Codex
+
+```bash
+npx @aporthq/aport-agent-guardrails codex --global --enforcement=warn
+codex          # once: run /hooks and trust the APort hook. This step cannot be automated.
+```
+
+APort's Codex hook is beta. Warn mode may downgrade policy denials, but adapter
+failures can still block calls such as unsupported multi-file `apply_patch`;
+check the installed guardrails version's support before unattended use. The
+other controls are `workspace-write`, Codex's automatic approval reviewer for
+Git metadata writes and escalations, the scoped token and the ruleset. Gallivant
+sets the approval mode on start and resume. A denial must be diagnosed, not
+bypassed. See [guardrails.md](guardrails.md#codex-git-writes-need-automatic-approval).
+
+## 9. First task
+
+Before dispatch, confirm the repository, target branch, permitted changes and
+spending limits. The default `max_iterations` is 30 automatic fix rounds;
+`max_budget_usd` defaults to 5 and gives Claude a native per-run dollar cap.
+Other local harnesses do not enforce an equivalent dollar cap. Use your provider's
+spend controls and review [budget semantics](config.md) before unattended work.
+A paid preparation call is different from the local `ready --check` validator.
+
+You can deliver code, documentation, research or content, provided the outcome
+is a repository change with concrete acceptance criteria and checks. You do not
+need to write a PRD by hand.
+
+### From plain language
+
+Inside the target repository:
+
+```sh
+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'
+```
+
+Choose `claude` or `openai-agents` instead when configured. This first command
+uses inference to prepare a brief but does not start implementation. Inspect the
+returned draft and assumptions. If it needs answers, use its printed question
+IDs and `Next` action. Once ready, substitute your returned ID and revision:
+
+```sh
+gallivant task start TASK_ID --revision REVISION --run
+gallivant start
+```
+
+Alternatively, add `--run` to the original `task` request to authorize
+implementation as soon as preparation and any clarifications succeed. The task
+service starts the daemon; `gallivant start` with no path also opens the dashboard.
+Read [task operations](tasks.md) for selected context, revisions, recovery and costs.
+
+### From a written brief
+
+`new` uses the first configured harness. Pass `--harness` with another configured
+harness only when you intend to select it.
+
+```sh
+gallivant new widget-export
+# Fill in docs/prds/widget-export.md, including every required section.
+gallivant ready docs/prds/widget-export.md --check
+gallivant ready docs/prds/widget-export.md
+gallivant start docs/prds/widget-export.md
+gallivant status
+```
+
+`new` writes a complete template. Fill in its Problem, User stories, Acceptance
+criteria, Verify, Where to look and Out of scope sections. Empty section headings
+are not a runnable brief. [The PRD contract](prd.md) explains the rules and
+noncoding verification. `ready --check` is a local, read-only validation;
+`ready` records readiness and updates the file without committing it.
+
+`start` starts the background daemon and dashboard and opens the browser when
+available. Do not run a second `up`. `--no-open` suppresses browser launch;
+`--no-server` starts the task and daemon without the dashboard. `gallivant start`
+with no path starts/reuses the services without submitting a task. `serve` uses
+the same startup; supervisors can use `serve --foreground --no-open --no-daemon`
+for a tracker whose daemon is managed separately. `gallivant down` stops both
+standalone services, preserving active agent processes.
+
+On macOS the daemon starts `caffeinate` for its lifetime to prevent idle sleep.
+Closing a laptop lid, losing network or shutting down still interrupts monitoring.
+There is no automatic login/reboot service installer yet.
+
+### Completion verification
+
+APort readiness/completion verification is separate from harness pre-tool hooks.
+By default, the built-in contract checks are confirmed by APort's hosted endpoint;
+this needs network access and unauthenticated requests have an IP rate limit.
+An installed APort Claude API key is used when available. To deliberately use
+only the local completion evaluator, set `"deliverable": { "evaluator": "local" }`
+in config; the local acceptance criteria and receipt checks still apply. See
+[the completion contract](prd.md#the-completion-receipt) for details.
+
+## Verifying the first real PR
+
+Watch `gallivant status` after the start run ends: the entry moves from `implementing` to `waiting on reviewer` once the PR is open. When the reviewer's review lands, the next tick shows `fixing`, then a round comment appears on the PR, and after the re-review either a `ready for a human` notification arrives or `status` shows why not.
+
+## Where things live
+
+| Path | What |
+|---|---|
+| `~/.gallivant/config.json` | your config, mode 600 |
+| `~/.gallivant/state.json` | the registry; preserve it and its snapshots for exact local recovery |
+| `~/.gallivant/runs/<entry>/<run>/` | `job.json`, redacted `job.log`, private raw `provider.log` for local runs, local `cmd.json` or hosted execution/artifact records |
+| `~/.gallivant/daemon.json` | daemon health, read by `status` |
+| `~/.gallivant/tracker.json`, `tracker.lock`, `tracker.log` | standalone dashboard ownership, port and output |
+| `~/.gallivant/errors.log` | every warning and error |
+| `~/.gallivant/claude/` | Gallivant's Claude settings, APort hook runtime, passport, audit log |
+| `<worktrees>/<repo>/<prd>` | one partial clone per PRD; durable until you delete it |
+
+Override the home directory with `GALLIVANT_HOME` to run a second instance.

package/docs/launch.md

@@ -0,0 +1,45 @@
+# Announcement drafts
+
+Publish these only after [the release checks](releasing.md#verify-before-announcing)
+pass for the version being announced. The package is published as
+`@uchibeke/gallivant`; the setup command to advertise is
+`npx --yes @uchibeke/gallivant init --harness codex` (or `--harness claude`),
+run inside the target checkout. Check that the behavior the README describes is
+in the released version before quoting it. Add a genuine dashboard screenshot or
+recording of a task reaching a reviewed PR. Fixture tests are not live provider
+evidence.
+
+## X
+
+Give an agent a task. Let the review loop run. Go outside.
+
+Gallivant turns requests into reviewed PRs: code, docs or research. Local or
+hosted agents, review/CI fixes, and a dashboard for corrections. You choose
+what merges.
+
+https://github.com/uchibeke/gallivant
+
+## LinkedIn
+
+I built Gallivant to reduce the time spent checking whether an agent has
+finished, collecting review feedback, and sending it back for the next fix.
+
+Start with a plain-language request or a written brief. Gallivant keeps the
+requirements, implementation, tests and PR review together. It watches reviews
+and CI, continues the same session for corrections, and reports when the result
+is ready for you or needs help. A local dashboard lets you follow progress and
+message the agent.
+
+This also works for research, documentation and content delivered as repository
+files. For longer plans, merge one milestone and the next starts from that base.
+You retain the merge decision.
+
+Claude Code and local Codex are the recommended starting points. An explicit
+OpenAI Agents API integration supports hosted preparation and execution with
+separate account, permission and billing requirements. The support table
+separates implemented adapters from live qualification; Codex Cloud dispatch
+remains disabled until its repository binding can be verified.
+
+Gallivant runs on macOS and Linux. Its coordinator still needs to stay online,
+even when the agent runs remotely. Setup, examples and operating boundaries:
+https://github.com/uchibeke/gallivant