nohalt 0.1.0__tar.gz

nohalt-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.nohalt/
+.idea/
+.vscode/
+*.swp
+.DS_Store

nohalt-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 (2026-10-22)
+
+
+### Features
+
+* autonomous agent supervisor for GitHub and GitLab issues ([c401ee5](https://github.com/Seityl/nohalt/commit/c401ee527198bb896cdb92c604b245a6a781e36c))
+
+
+### Bug Fixes
+
+* GitLab dogfood findings -- probe in launch mode, setup failures cost no attempt, drafts marked ready ([b67644d](https://github.com/Seityl/nohalt/commit/b67644d06a61561486ef470de3b0f352f88cf730))
+* **prompt:** read GitHub issues over REST, not gh issue view ([ee0f8b4](https://github.com/Seityl/nohalt/commit/ee0f8b4e0b2c9155701750b461ade1f9e28f8262))
+* **prompt:** verify command works when nohalt is not on PATH ([d462893](https://github.com/Seityl/nohalt/commit/d462893767c03cf7d6ff59045d7e458a7b33e871))
+
+
+### Documentation
+
+* architecture, configuration, stacks, safety and lessons learnt ([51bdd1b](https://github.com/Seityl/nohalt/commit/51bdd1baaa92472b920e909d06b1c845b7641ae0))
+
+## Changelog
+
+All notable changes to this project are documented here. This file is maintained by
+[release-please](https://github.com/googleapis/release-please) from conventional commits.

nohalt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeriel Francis trading as Seityl, and the nohalt contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nohalt-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: nohalt
+Version: 0.1.0
+Summary: Autonomous coding agents that keep going until the forge says done.
+Project-URL: Homepage, https://github.com/Seityl/nohalt
+Project-URL: Issues, https://github.com/Seityl/nohalt/issues
+Project-URL: Changelog, https://github.com/Seityl/nohalt/blob/main/CHANGELOG.md
+Author: Jeriel Francis trading as Seityl
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,autonomous,ci,claude-code,coding-agents,github,opencode,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nohalt
+
+**Autonomous coding agents that keep going until the forge says done.**
+
+[![CI](https://github.com/Seityl/nohalt/actions/workflows/ci.yml/badge.svg)](https://github.com/Seityl/nohalt/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+
+nohalt supervises a fleet of AI coding agents ([opencode](https://opencode.ai), [Claude Code](https://www.claude.com/product/claude-code), or any CLI) working through a queue of GitHub or GitLab issues: one agent per issue, each in its own git worktree, until every issue is **closed** -- not until the agents *say* they are done.
+
+An endpoint that raised `NameError` on every call once shipped with green CI and a confident agent summary, and stayed broken for two months. Agents report success they have not earned. So nohalt believes exactly one thing: the issue's state on the forge, and an issue closes only when a reviewed, green pull request merges.
+
+Everything else in nohalt exists because something went wrong without it, while agents ran unattended through the night on three production projects. Those lessons -- around a hundred of them -- are written up in [**docs/LESSONS.md**](docs/LESSONS.md), and the ones nohalt enforces are pinned by tests.
+
+## What it does
+
+```
+queue.txt ──► scheduler ──► agent in its own worktree ──► PR ──► CI ──► integrator ──► merged ──► issue CLOSED
+ (deps)      slots, memory,     (opencode / claude-code)          │       (direct or         │
+             a model that                │                         │        release train)    └─► pipeline watched;
+             answers                     ▼                         ▼                              red → fix-forward
+                               verify lock: one test env    red / conflicting → handed back      issue, merging stops
+                               per slot, at this commit     to the agent with the failure
+```
+
+- **Dependency-ordered queue.** `14: 13` means #14 waits until #13 is closed. Order is preference; dependencies are law. Edit it while nohalt runs.
+- **GitHub or GitLab.** gitlab.com or self-hosted: merge requests, pipeline jobs as checks, `glab` for agents. Subgroups are fine.
+- **Parallel agents, isolated.** One worktree and branch per issue; guard shims on each agent's `PATH` refuse merging, closing issues, pushing to the base branch, `git stash` (worktrees share one stash stack), and machine-wide `pkill`.
+- **A verification lock.** Agents edit in parallel but verify one at a time per test slot (`nohalt verify <worktree> -- '<cmd>'`), with the environment reset to the commit under test.
+- **Failures classified, not counted blindly.** A model-endpoint outage is not an attempt on the issue. A time limit continues in the same worktree. A hung agent (no output, no command running) is restarted. A red PR goes back to an agent with the failing checks. Only real failures spend attempts; then the issue is labelled for a human and the rest of the queue carries on.
+- **One merger.** Agents never merge. `direct` mode merges green PRs one at a time and stops everything if the pipeline on the base branch goes red; `train` mode batches green PRs into a versioned release branch, resolving bookkeeping conflicts (package.json, migration lists, schema JSON) mechanically and handing real code conflicts back.
+- **Survives itself.** Agents run in their own sessions. Kill or restart the supervisor and it adopts the running agents from their records. `nohalt keepalive` in cron brings it back.
+- **Model routing and a spend guard.** Route by label or title, pin per issue, gate premium models behind approval, fall over to a model that answers, and cap paid-API spend per issue and in total.
+- **Stacks.** A `generic` stack (your own `up`/`reset`/`env` hooks for the test environment) and a `frappe` stack (a pool of agent test sites on a shared bench, worktree-first `PYTHONPATH`, migrate before test, DocType/fixture/patch merge drivers).
+
+## Quick start
+
+```bash
+pip install nohalt          # Python 3.11+, Linux; needs git, plus gh (GitHub) or glab (GitLab)
+cd your-repo
+nohalt init                 # writes nohalt.toml and queue.txt (--stack frappe for Frappe apps)
+$EDITOR nohalt.toml queue.txt
+nohalt doctor --probe       # checks config, forge auth, branch protection, agent binaries, models
+nohalt run --dry-run        # what would launch now, what waits on what
+nohalt run                  # supervise; Ctrl-C leaves agents running, `nohalt run` adopts them again
+nohalt status --watch       # one screen: agents, idle time, attempts, last line of each log
+```
+
+Keep it running without a terminal:
+
+```cron
+*/3 * * * * cd /path/to/your-repo && nohalt keepalive
+```
+
+Control while it runs: `nohalt stop` (between issues), `nohalt stop --now`, `nohalt pause`, `nohalt route <issue> <model>`, `nohalt unblock <issue>`, `nohalt queue --add 42 --after 41`, `nohalt prompt <issue>` (see exactly what an agent will be told).
+
+## Before you run it
+
+nohalt gives AI agents write access to your repository and, if you enable an integrator, lets nohalt merge and deploy. **Read [docs/SAFETY.md](docs/SAFETY.md).** In short: protect the base branch on the forge (the shims are speed bumps, protection is the wall), use a token scoped to the one repository, run agents as a user that cannot reach production, start with `integrate.mode = "none"`, and watch the first few issues end to end.
+
+## Documentation
+
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md) -- every key in `nohalt.toml`
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- the supervisor loop, issue lifecycle, state on disk
+- [docs/STACKS.md](docs/STACKS.md) -- generic and Frappe test environments, writing your own
+- [docs/SAFETY.md](docs/SAFETY.md) -- the threat model and the guardrails
+- [docs/LESSONS.md](docs/LESSONS.md) -- what running agent fleets unattended taught us
+
+## Status
+
+Alpha. The mechanisms come from scripts that ran production agent fleets for weeks; this package is their consolidation into one tested, configurable tool, and it is younger than they are. Before the first release it was run end to end on both forges -- real agents (Claude Code on GitHub, opencode on a self-hosted GitLab), real CI, both `none` and `direct` integration, a supervisor `kill -9` mid-run -- and the bugs those runs found are fixed. Expect rough edges. Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © Jeriel Francis trading as Seityl, and the nohalt contributors.

nohalt-0.1.0/README.md

@@ -0,0 +1,75 @@
+# nohalt
+
+**Autonomous coding agents that keep going until the forge says done.**
+
+[![CI](https://github.com/Seityl/nohalt/actions/workflows/ci.yml/badge.svg)](https://github.com/Seityl/nohalt/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
+
+nohalt supervises a fleet of AI coding agents ([opencode](https://opencode.ai), [Claude Code](https://www.claude.com/product/claude-code), or any CLI) working through a queue of GitHub or GitLab issues: one agent per issue, each in its own git worktree, until every issue is **closed** -- not until the agents *say* they are done.
+
+An endpoint that raised `NameError` on every call once shipped with green CI and a confident agent summary, and stayed broken for two months. Agents report success they have not earned. So nohalt believes exactly one thing: the issue's state on the forge, and an issue closes only when a reviewed, green pull request merges.
+
+Everything else in nohalt exists because something went wrong without it, while agents ran unattended through the night on three production projects. Those lessons -- around a hundred of them -- are written up in [**docs/LESSONS.md**](docs/LESSONS.md), and the ones nohalt enforces are pinned by tests.
+
+## What it does
+
+```
+queue.txt ──► scheduler ──► agent in its own worktree ──► PR ──► CI ──► integrator ──► merged ──► issue CLOSED
+ (deps)      slots, memory,     (opencode / claude-code)          │       (direct or         │
+             a model that                │                         │        release train)    └─► pipeline watched;
+             answers                     ▼                         ▼                              red → fix-forward
+                               verify lock: one test env    red / conflicting → handed back      issue, merging stops
+                               per slot, at this commit     to the agent with the failure
+```
+
+- **Dependency-ordered queue.** `14: 13` means #14 waits until #13 is closed. Order is preference; dependencies are law. Edit it while nohalt runs.
+- **GitHub or GitLab.** gitlab.com or self-hosted: merge requests, pipeline jobs as checks, `glab` for agents. Subgroups are fine.
+- **Parallel agents, isolated.** One worktree and branch per issue; guard shims on each agent's `PATH` refuse merging, closing issues, pushing to the base branch, `git stash` (worktrees share one stash stack), and machine-wide `pkill`.
+- **A verification lock.** Agents edit in parallel but verify one at a time per test slot (`nohalt verify <worktree> -- '<cmd>'`), with the environment reset to the commit under test.
+- **Failures classified, not counted blindly.** A model-endpoint outage is not an attempt on the issue. A time limit continues in the same worktree. A hung agent (no output, no command running) is restarted. A red PR goes back to an agent with the failing checks. Only real failures spend attempts; then the issue is labelled for a human and the rest of the queue carries on.
+- **One merger.** Agents never merge. `direct` mode merges green PRs one at a time and stops everything if the pipeline on the base branch goes red; `train` mode batches green PRs into a versioned release branch, resolving bookkeeping conflicts (package.json, migration lists, schema JSON) mechanically and handing real code conflicts back.
+- **Survives itself.** Agents run in their own sessions. Kill or restart the supervisor and it adopts the running agents from their records. `nohalt keepalive` in cron brings it back.
+- **Model routing and a spend guard.** Route by label or title, pin per issue, gate premium models behind approval, fall over to a model that answers, and cap paid-API spend per issue and in total.
+- **Stacks.** A `generic` stack (your own `up`/`reset`/`env` hooks for the test environment) and a `frappe` stack (a pool of agent test sites on a shared bench, worktree-first `PYTHONPATH`, migrate before test, DocType/fixture/patch merge drivers).
+
+## Quick start
+
+```bash
+pip install nohalt          # Python 3.11+, Linux; needs git, plus gh (GitHub) or glab (GitLab)
+cd your-repo
+nohalt init                 # writes nohalt.toml and queue.txt (--stack frappe for Frappe apps)
+$EDITOR nohalt.toml queue.txt
+nohalt doctor --probe       # checks config, forge auth, branch protection, agent binaries, models
+nohalt run --dry-run        # what would launch now, what waits on what
+nohalt run                  # supervise; Ctrl-C leaves agents running, `nohalt run` adopts them again
+nohalt status --watch       # one screen: agents, idle time, attempts, last line of each log
+```
+
+Keep it running without a terminal:
+
+```cron
+*/3 * * * * cd /path/to/your-repo && nohalt keepalive
+```
+
+Control while it runs: `nohalt stop` (between issues), `nohalt stop --now`, `nohalt pause`, `nohalt route <issue> <model>`, `nohalt unblock <issue>`, `nohalt queue --add 42 --after 41`, `nohalt prompt <issue>` (see exactly what an agent will be told).
+
+## Before you run it
+
+nohalt gives AI agents write access to your repository and, if you enable an integrator, lets nohalt merge and deploy. **Read [docs/SAFETY.md](docs/SAFETY.md).** In short: protect the base branch on the forge (the shims are speed bumps, protection is the wall), use a token scoped to the one repository, run agents as a user that cannot reach production, start with `integrate.mode = "none"`, and watch the first few issues end to end.
+
+## Documentation
+
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md) -- every key in `nohalt.toml`
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- the supervisor loop, issue lifecycle, state on disk
+- [docs/STACKS.md](docs/STACKS.md) -- generic and Frappe test environments, writing your own
+- [docs/SAFETY.md](docs/SAFETY.md) -- the threat model and the guardrails
+- [docs/LESSONS.md](docs/LESSONS.md) -- what running agent fleets unattended taught us
+
+## Status
+
+Alpha. The mechanisms come from scripts that ran production agent fleets for weeks; this package is their consolidation into one tested, configurable tool, and it is younger than they are. Before the first release it was run end to end on both forges -- real agents (Claude Code on GitHub, opencode on a self-hosted GitLab), real CI, both `none` and `direct` integration, a supervisor `kill -9` mid-run -- and the bugs those runs found are fixed. Expect rough edges. Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © Jeriel Francis trading as Seityl, and the nohalt contributors.

nohalt-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,100 @@
+# Architecture
+
+nohalt is one supervisor loop and a set of small, replaceable parts:
+
+```
+src/nohalt/
+  supervisor.py    the loop: reap → watch → integrate → launch → budget
+  queue.py         queue.txt: "<issue>: <deps>"
+  state.py         issue records and control files (JSON, written atomically)
+  worktree.py      one git worktree per issue; rescue before removal
+  models.py        routing, pins, premium gate, probes, fallbacks
+  budget.py        paid-API spend estimate and caps
+  prompt.py        core prompt + stack addendum + project files; strict placeholders
+  verify.py        the verification lock (slot pool) and refused commands
+  forge/           the forge interface; GitHub (gh REST), GitLab (REST v4); a file-backed forge
+  agents/          opencode, claude-code, any command
+  stacks/          generic (shell hooks), frappe (site pool on a shared bench)
+  integrate/       none | direct | train, plus the bookkeeping merge drivers
+  shims/           gh, glab, git, pkill guards put first on every agent's PATH
+  cli.py           the `nohalt` command
+```
+
+## The loop
+
+Every `tick` (default 60 s):
+
+1. **Reap.** For every issue whose agent is running: past its time limit → stop it (`timeout`). No output for `hung_after` and no command of its own running → stop it (`hung`). Exited → *judge* it.
+2. **Watch.** For every issue whose agent finished with a pull request: read the PR's checks on its **current head**. Red → hand back to an agent with the failing checks. Green but unmergeable → hand back to rebase. Green and mergeable → `ready`.
+3. **Integrate.** `direct` or `train` merges `ready` PRs (see below). `none` does nothing: a human merges. Either way, an issue still open after its PR merged is closed by nohalt -- forges act on closing keywords only for the default branch.
+4. **Launch.** Read the queue again (it can be edited live). Walk it in order. For each open issue that is not blocked, not held, has its dependencies closed, and has passed its backoff time, launch an agent if a slot in its model's pool is free, enough memory is available, and the model answers a probe (or a fallback does).
+5. **Budget.** Every few minutes, estimate paid-API spend and move issues over their cap to a fallback model.
+
+The supervisor holds an exclusive lock, so only one runs per state directory. A tick never blocks on long waits: watching a pipeline after a merge, or waiting for a usage limit to reset, is a state that later ticks re-examine.
+
+## Issue lifecycle
+
+```
+            ┌──────────────── handed back (red CI, conflict, PR closed) ─────────────┐
+            ▼                                                                        │
+ queued ──launch──► running ──exit──► judged ──PR open──► waiting_ci ──green──► ready ──merged──► done
+   ▲                  │                 │                                            ▲
+   │                  │ timeout / hung  │ provider error / usage limit (not an attempt)
+   │                  └─────────────────┴─► queued (resume, with backoff)            │
+   │                                    │                                            │
+   │                                    └─ no PR, no close: attempt+1 ─► queued      │
+   │                                                       attempts used ─► blocked  │
+   │                                                                                 │
+   └──── a human removes the blocked label (counters reset)        forge says CLOSED ┘ (at any point)
+```
+
+How an exit is judged, in order:
+
+| Evidence | Verdict | Costs an attempt? |
+|---|---|---|
+| Forge says CLOSED (or the issue no longer exists) | done: worktree rescued and removed, agent data deleted | -- |
+| Forge unreachable | `exited`, judged again next tick | no |
+| Stopped by the budget guard or by `stop --now` | requeued, resumes | no |
+| The agent's output ends on a usage-limit event | requeued after 15 min, the model is not probed for 20 min | no |
+| The agent's output ends on a model-endpoint error | requeued with backoff × n. Blocked after `provider_retries`, with a diagnosis that says it was not the issue's fault | no |
+| Time limit, issue still open | continues in the same worktree, up to `timeout_continues` times | no |
+| Hung | restarted, up to `revive_limit` times | no |
+| A pull request exists | `waiting_ci` | no |
+| None of the above | requeued after `revive_grace` (it may have stopped to ask). Blocked after `max_attempts` | **yes** |
+
+A *resumed* launch continues the agent's previous session in the same worktree with a short "you were stopped, check git status and your PR first" prompt. A *fresh* launch (used after a rebase request, when the world has moved on) starts a new session from the full prompt.
+
+## Integration
+
+**direct.** Takes the first `ready` issue in queue order, checks again that its PR is green on its current head and mergeable, merges it, then watches the pipeline on the base branch's new head (`cd_workflow`, else `ci_workflow`, else the required checks). Nothing else merges until that pipeline is green. If it is red, or times out, nohalt opens a fix-forward issue at the front of the queue, and merging resumes when that issue closes. A `deploy` command, if set, runs after a green pipeline (unless a CD workflow already deploys).
+
+**train.** With no release PR open, every `ready` issue's green PR (priority list first, then queue order, minus held issues and parked SHAs) is merged into `release/auto-<time>` off the base. Conflicts go to the merge drivers by glob (`[integrate.mergers]`). If any file stays in conflict, that PR is left out and handed back to rebase. The batch gets the next free version (from tags, or the version files), an optional regeneration command, and a PR closing every carried issue. On a later tick: green and mergeable → merge, tag, deploy, then the same pipeline gate as `direct` watches the base branch. Red → re-run the failed jobs once (more if the failure was the network). Still red → close the release, park the carried heads until their agents push, and hand each issue back.
+
+## State on disk
+
+```
+<state_dir>/
+  supervisor.lock          one supervisor at a time
+  issues/<n>.json          IssueRecord: status, counters, model, pid, branch, worktree, PR, history
+  pids.json                process start times (a recycled pid is not our agent)
+  pins.json approved.json  model pins and premium approvals
+  probes.json limited.json model probe cache and usage-limit marks
+  spend.json               budget high-water marks
+  integrate.json train.json integrator state that spans ticks
+  status.json              last tick's summary (for `nohalt status`)
+  STOP PAUSE WAKE BATCH_PAUSE DEPLOY_BLOCKED BUDGET_EXHAUSTED   control flags
+  priority hold            one issue per line (train ordering / exclusion)
+  bin/                     guard shims
+  locks/verify-<slot>.lock verification slots
+  agent-data/<n>/          per-agent session data (opencode XDG_DATA_HOME)
+  logs/                    nohalt.log, events.jsonl, issue-<n>.log, guard.log, refused.log, deploy.log
+  work/<n>/                worktrees (unless [project] worktrees is set)
+  work/_release/           the train's integration tree
+```
+
+## Extending
+
+- **A new agent CLI:** implement `launch`, `probe_launch`, `provider_failed` and `usage_limited` (see `agents/opencode.py`), and register it in `agents.get`. Before writing an adapter, try `command:` with `[agents.options.command] argv = [...]`.
+- **A new stack:** subclass `stacks.Stack`. Implement `apply_defaults` (slots, refused commands, merge drivers) and `prepare` (bring the test environment to the worktree's commit inside the lock), and optionally a prompt addendum.
+- **A new forge:** implement the `forge.base.Forge` protocol. Keep to its rule: a failed call raises `ForgeError`. It never returns something that looks like an answer.
+- **A new merge driver:** a function `(repo, path) -> bool` in `integrate/mergers.py`, added to `DRIVERS`, with a test that runs it inside a real conflicted merge.

nohalt-0.1.0/docs/CONFIGURATION.md

@@ -0,0 +1,183 @@
+# Configuration
+
+One `nohalt.toml` per project. `nohalt init [--stack frappe]` writes a starter file, and `nohalt doctor` checks it. nohalt looks for `nohalt.toml` in the current directory and its parents, or takes `--config PATH`. Relative paths are relative to the file.
+
+**Unknown keys are errors.** A typo that silently falls back to a default is how a guard quietly stops guarding.
+
+Durations accept `90`, `"90s"`, `"30m"`, `"4h"` or `"2d"`. Models are always written `<agent>:<model>`: `opencode:anthropic/claude-sonnet-4-5`, `claude-code:sonnet`, `command:anything`.
+
+## [project]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `repo` | -- | `owner/name` on GitHub, `group[/subgroup]/name` on GitLab, or `local:/path/forge.json` for a file-backed forge (rehearsal, tests) |
+| `forge` | `"github"` | `github` or `gitlab` |
+| `forge_url` | `""` | GitLab only: the instance, e.g. `https://gitlab.example.com` (default `$GITLAB_HOST`, else `https://gitlab.com`). Also exported to agents as `GITLAB_HOST` |
+| `token_env` | `"GITLAB_TOKEN"` | GitLab only: the variable holding a token with the `api` scope. If unset, nohalt uses the token `glab` is logged in with |
+| `path` | `"."` | the main clone. Worktrees are cut from it |
+| `base_branch` | `"main"` | branches start here. PRs target it. Agents may never push to it |
+| `remote` | `"origin"` | |
+| `state_dir` | `".nohalt"` | records, logs, locks, shims, agent data |
+| `worktrees` | `<state_dir>/work` | where per-issue worktrees go (keep it out of a Frappe bench's `apps/`) |
+| `shared_paths` | `[]` | untracked directories symlinked from the main clone into each worktree (e.g. `node_modules`) |
+| `branch_prefixes` | `{ bug = "fix" }` | label → branch prefix |
+| `default_prefix` | `"feature"` | branches are `<prefix>/<issue>-<slug>`. An existing branch matching `*/<issue>-*` is reused |
+
+## [queue]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `file` | `"queue.txt"` | `<issue>: <deps…>` per line, `#` comments. Re-read every tick |
+| `blocked_label` | `"nohalt-blocked"` | put on issues that need a human. Remove it to retry, with counters reset |
+| `held_labels` | `["needs-human"]` | issues carrying one of these are never worked |
+| `tick` | `60` | seconds between passes |
+| `poll_when_idle` | `600` | seconds between passes when nothing can move |
+
+## [agents]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `max_parallel` | `2` | agent slots shared by every model not in a `pools` entry. Measure: on a small machine, more is slower |
+| `pools` | `{}` | model prefix → its own cap, e.g. `{ "claude-code:" = 2, "opencode:anthropic/" = 4 }`. Override live with `<state>/caps.json` |
+| `min_free_mb` | `2000` | do not launch below this much available memory |
+| `phase_timeout` | `"4h"` | one agent run |
+| `long_timeout` | `"8h"` | for issues carrying one of `long_labels` |
+| `long_labels` | `[]` | |
+| `max_attempts` | `2` | real attempts (exits with no PR and no close) before blocking |
+| `provider_retries` | `5` | model-endpoint failures per issue before blocking. Never counted as attempts |
+| `provider_backoff` | `"2m"` | multiplied by the retry number |
+| `timeout_continues` | `3` | time limits that continue in the same worktree before counting as an attempt |
+| `hung_after` | `"30m"` | no output and no command running: stop and restart |
+| `revive_limit` | `2` | hung restarts before counting as an attempt |
+| `revive_grace` | `"15m"` | wait before relaunching an agent that stopped without a PR (it may have asked a question) |
+| `ci_rounds` | `3` | red or conflicting PRs handed back before blocking |
+| `log_max_mb` | `20` | per-issue agent logs rotate past this |
+| `title_prefix` | `"nohalt"` | agent session titles: `<prefix> #<issue>` |
+| `copy_files` | `[]` | files copied into each agent's private data dir (e.g. an opencode `auth.json`) |
+| `options` | `{}` | per-adapter options, below |
+
+```toml
+[agents.options.opencode]
+binary = "opencode"
+agent = "build"            # opencode --agent
+extra_args = []
+
+[agents.options.claude-code]
+binary = "claude"
+disallowed_tools = ["Task", "CronCreate", "..."]   # default: sub-agents, schedulers, remote triggers, worktree tools
+mcp = false                # true keeps your MCP servers available to agents
+
+[agents.options.command]   # any CLI: placeholders {model} {prompt} {title} {data_dir}
+argv = ["my-agent", "--model", "{model}", "{prompt}"]
+resume_args = ["--continue"]
+probe_argv = ["my-agent", "--model", "{model}", "--ping"]
+```
+
+## [models]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `default` | `opencode:anthropic/claude-sonnet-4-5` | |
+| `fallbacks` | `[]` | tried in order when an unpinned issue's model does not answer a probe |
+| `premium` | `[]` | models that run only on issues approved with `nohalt route <n> <model> --approve` |
+| `premium_fallback` | `""` | what a non-approved request for a premium model gets (default: `default`) |
+| `probe` | `true` | ask the model for "OK" before launching. A dead endpoint otherwise kills every agent in its first second |
+| `probe_ttl` | `"5m"` | probe results are cached this long |
+| `[[models.route]]` | `[]` | `{ labels = [...], model = "..." }` or `{ title = "regex", model = "..." }`. The first match wins |
+
+Pins (`nohalt route <issue> <model>`) beat rules and are never failed over: a pinned issue waits for its model.
+
+## [budget]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `false` | |
+| `per_issue` | `15.0` | USD. Over it, the issue moves to `fallback_model` |
+| `total` | `100.0` | USD across all paid issues. Once reached, every paid issue moves |
+| `providers` | `["anthropic"]` | model id prefixes that are billed per token |
+| `fallback_model` | `""` | where over-budget issues go. Empty: stop and block them |
+| `rates` | Sonnet list prices | USD per million tokens: `input`, `output`, `cache_read`, `cache_write`. **Calibrate against your console**: estimates are routinely off by a factor until measured |
+
+Spend is estimated from each opencode agent's own session database, keeping the high-water mark per issue (pruning session data never lowers the total).
+
+## [verify]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `slots` | `["default"]` | names, or `{ name, env = {...} }`. One verification per slot at a time |
+| `placeholder` | `""` | a token in agents' commands replaced by the slot's `SITE` (the frappe stack sets it) |
+| `refuse` | `[]` | substrings a verify command may not contain. Refusals are logged |
+| `up` / `reset` / `env` | `""` | shell hooks (generic stack), see [STACKS.md](STACKS.md) |
+| `pythonpath_worktree` | `false` | put the worktree first on `PYTHONPATH` (the frappe stack sets it) |
+| `clean_pycache` | `true` | delete stale bytecode in the worktree before running |
+
+## [integrate]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `mode` | `"none"` | `none` (a human merges), `direct`, `train`. Agents never merge in any mode |
+| `required_checks` | `[]` | check-run names (GitHub) or job names in the newest pipeline (GitLab) that must pass. Empty: every check must pass, and at least one must exist. On GitLab, a job with `allow_failure` never makes a commit red, and a manual job counts as skipped |
+| `merge_method` | `"squash"` | for `direct` (release PRs always merge with a merge commit). On GitLab, `squash` squashes; otherwise the project's merge method applies |
+| `ci_workflow` / `cd_workflow` | `""` | runs watched on the base branch after a merge: GitHub workflow names, or on GitLab a pipeline's `workflow:name` (or `"pipeline"` for any pipeline on the commit) |
+| `cd_timeout` | `"90m"` | a pipeline that does not finish in time counts as red |
+| `base_pipeline_grace` | `"10m"` | if **no** pipeline appears on the base branch's new head within this time, there is nothing to watch, and merging continues. Many integration branches run no CI after a merge |
+| `deploy` | `""` | shell command after a green pipeline (`direct`, when no CD workflow deploys) or a merged release (`train`). A failure writes `DEPLOY_BLOCKED` |
+| `fix_forward` | `true` | a red pipeline opens an issue at the front of the queue and stops merging until it closes |
+| `cancel_superseded` | `false` | cancel queued or running CI for commits no open PR or the base points at |
+| `network_errors` | DNS/reset patterns | failed-log substrings that mark a red as the network's, not the code's |
+| `mergers` | `{}` | glob → driver, see [STACKS.md](STACKS.md#merge-drivers-any-stack) |
+
+```toml
+[integrate.train]
+branch_prefix = "release/"
+version_files = [{ path = "pkg/__init__.py", pattern = '__version__ = "([^"]+)"' }]   # group 1 is replaced
+tag_prefix = "v"
+after_version = "python scripts/regenerate_reference.py"   # run in the release tree after stamping
+red_retries = 1
+batch_pause_file = "BATCH_PAUSE"   # touch <state>/BATCH_PAUSE to hold new batches (expires after 1 h)
+```
+
+`<state>/priority` and `<state>/hold` (one issue per line) put issues first in, or keep them out of, the next batch.
+
+## [stack]
+
+`name = "generic"` or `"frappe"`. Other keys are the stack's options (frappe: `bench`, `app`, `sites`, `full_suite_guard`, `mergers`). See [STACKS.md](STACKS.md).
+
+## [prompt]
+
+| Key | Default | Meaning |
+|---|---|---|
+| `inline_issue` | `false` | put the issue's text and comments in the prompt, so agents don't need a working forge CLI to read it |
+| `template` | `"builtin:core"` | the core prompt: `builtin:<name>` or a file |
+| `extra` | `[]` | your project's own prompt files, appended in order |
+| `vars` | `{}` | extra `{{PLACEHOLDERS}}`. **Never put secrets here**: prompts end up in logs |
+
+Placeholders available: `{{ISSUE}} {{TITLE}} {{REPO}} {{BRANCH}} {{WORKTREE}} {{BASE}} {{VERIFY}}`, `{{SITE}}` when `verify.placeholder` is set, plus `vars`. An undefined placeholder is an error, not an empty string. Run `nohalt prompt <issue>` to see exactly what an agent will be told.
+
+## Example: self-hosted GitLab
+
+Work lands on an integration branch, and humans promote it to the default branch, which deploys. CI on merge requests is a short validation job, and the instance itself doesn't require pipelines to pass.
+
+```toml
+[project]
+repo = "team/app"                       # group[/subgroup]/name
+forge = "gitlab"
+forge_url = "https://gitlab.example.com"
+token_env = "NOHALT_GITLAB_TOKEN"        # a project access token (Developer, api), not a person's token
+base_branch = "develop"                  # NOT the default branch that deploys to production
+
+[queue]
+blocked_label = "blocked"                # reuse the label humans already use
+held_labels = ["in-progress", "Draft"]   # matched case-insensitively
+
+[integrate]
+mode = "direct"
+required_checks = ["validate"]           # nohalt enforces this itself, even if GitLab doesn't
+merge_method = "merge"                   # match the project's merge method
+base_pipeline_grace = "5m"               # develop runs no pipeline after a merge: don't wait for one
+
+[prompt]
+inline_issue = true                      # agents read the issue even if glab can't reach the host
+```
+
+If GitLab is configured to close issues only for merges into the default branch, nohalt closes them itself after a merge into `develop`.