faberun 0.3.0 → 0.7.0

package/README.md

@@ -1,131 +1,183 @@
-# skills
+<p align="center"><img src="assets/faberun-icon.png" width="160" alt="The hornero on its clay nest, the Faberun mark"></p>
 
-Personal catalog of reusable agent skills, installable into any repository
-with a single command.
+<h1 align="center">faberun</h1>
 
-All skills live under [`skills/`](skills/). Each skill is one folder
-with a `SKILL.md`; scripts, references, and templates live inside the skill so
-it stays a single copyable unit.
+<p align="center">From intent to running software.</p>
+
+<p align="center">
+  <a href="https://github.com/feliperun/faberun/actions/workflows/ci.yml"><img src="https://github.com/feliperun/faberun/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/feliperun/faberun/releases/latest"><img src="https://img.shields.io/github/v/release/feliperun/faberun" alt="Latest release"></a>
+  <a href="https://www.npmjs.com/package/faberun"><img src="https://img.shields.io/npm/v/faberun" alt="npm version"></a>
+</p>
+
+Faberun is a development orchestration system that turns intent into verified
+software. It manages the process around software creation: plans, tasks,
+dependencies, execution, validation, evidence, retries and progress toward a
+defined outcome. It is not another coding agent, and it does not generate code
+without a definition of done.
+
+Faberun is model- and harness-agnostic. Claude Code, Codex, OpenCode and
+whatever comes next are workers; Claude, GPT, Gemini, DeepSeek, GLM and other
+models are engines; Faberun sits above them. It keeps the intent, coordinates
+the work, tracks what was actually completed, validates the result and decides
+what should happen next.
+
+Software should be built, not merely generated. A craftsman does not depend on
+one hammer, so Faberun does not depend on one model or one agent: tools,
+models and harnesses can change, and the work remains.
 
 ## Install
 
+The installer resolves the newest release, checks the requirements and runs
+`faberun setup`:
+
 ```bash
-npx github:feliperun/faberun             # every `mine` skill → .claude/skills/ of the current repo
-npx github:feliperun/faberun faberun # one named skill
-npx github:feliperun/faberun list        # show the catalog
-npx github:feliperun/faberun --global    # install into ~/.claude/skills/ instead
-npx github:feliperun/faberun --force     # replace skills that already exist
+curl -fsSL https://raw.githubusercontent.com/feliperun/faberun/main/install.sh | sh
 ```
 
-`npx` needs the repository to be reachable (public, or private with git
-credentials). Without npx, copy or symlink a skill folder into
-`~/.claude/skills/` or `.claude/skills/`:
+`faberun setup` runs at the end of the installer and registers the `faberun`
+skill for the harnesses it finds (Claude Code, Codex and the shared
+`~/.agents/skills`, plus any measured convention); `faberun skills register`
+redoes it.
+
+It needs Node 22 or newer, git, and one harness CLI on `PATH`. The npm and
+source installs need Node and git alone.
+
+From the npm registry:
 
 ```bash
-cp -r skills/faberun ~/.claude/skills/faberun
-ln -s "$(pwd)/skills/init-agentkit" ~/.claude/skills/init-agentkit
+npm install -g faberun
 ```
 
-## Skills
+Or run the package without installing it:
 
-### faberun
+```bash
+npx faberun --help
+```
 
-Executes large implementation plans as observable multi-model DAGs outside the
-orchestrator's context: declarative routing (Claude or Codex workers, including
-DeepSeek through Codex custom providers), closed task packets, structured
-cross-model quality gates, bounded revisions, campaign journaling with
-`HANDOFF.md`, and a built-in `supervise` watchdog that keeps resuming a dead
-controller until the run is terminal — from any host scheduler (launchd, cron,
-CI, or another agent), with no dependency on the orchestrator's runtime.
+From a checkout, as a contributor:
 
-Release 1 makes a long campaign cheap to watch and cheap to finish. Liveness is
-rendered ambiently from a bounded heartbeat at zero token cost, and the control
-session pulls campaign events on its own cursor instead of being woken by
-progress. Every Definition of Done item now declares how it is proven, so a
-mechanically provable node spends no judge at all, while contract-level
-`finalVerification` keeps a phase from closing on partial proof. An interrupted
-run is continued in place by `resume`, never re-authored, and the factory rides
-out provider exhaustion, quota resets, dead leases, and flaky networks
-deterministically. `metrics` reports effectiveness and efficiency of a
-campaign together, from what the runs recorded. Detail:
-[references/release-1.md](skills/faberun/references/release-1.md).
+```bash
+git clone https://github.com/feliperun/faberun.git
+cd faberun
+node src/cli.mjs --help
+```
 
-Quickstart, in the repository that will receive the implementation:
+An installed copy updates itself from the newest GitHub release:
 
 ```bash
-FABERUN=/path/to/faberun/src/cli.mjs
-TARGET=/path/to/target-repository
+faberun update
+```
 
-rg -qxF '.runs/' "$TARGET/.gitignore" || printf '\n.runs/\n' >> "$TARGET/.gitignore"
-node "$FABERUN" campaign init feature-42 --cwd "$TARGET" --goal "Deliver feature 42"
-node "$FABERUN" campaign attach feature-42 --cwd "$TARGET" --tool codex --session-id <session-id> --no-transcript
+## Quickstart
+
+The full walkthrough, from a fresh machine to a first verified node, is in
+[Getting started](docs/GETTING-STARTED.md).
+
+| Step | Command | What it does |
+| --- | --- | --- |
+| 1 | `faberun setup` | Onboards the machine: checks node and git, discovers the harnesses, and writes the default worker and judge. |
+| 2 | `faberun init` | Prepares a repository: confirms a git work tree, ignores `.runs/`, and installs the `faberun` skill. |
+| 3 | `faberun campaign init <id> --goal "..."` | Opens the durable campaign that carries the intent across runs. |
+| 4 | write a contract | Fixes `contract.json`: the node DAG, each packet's read and write scope, and each definition of done. |
+| 5 | `faberun validate contract.json` | Parses the contract and prints the report the authoring turn reads. |
+| 6 | `faberun preflight contract.json` | Checks the host, the runtime binaries and their credentials without dispatching a worker. |
+| 7 | `faberun run --detach contract.json` | Starts the run in its own process and returns with the run directory. |
+| 8 | `faberun status <run-dir>` / `faberun next` | Renders one run, or names the most urgent action across the active campaigns. |
+| 9 | `faberun supervise --detach <run-dir>` | Watches the run and resumes it when the controller dies. |
+
+## How it works
+
+The operator writes the intent into a campaign and an authored contract, a
+schema-versioned DAG whose nodes each carry a closed task packet. The controller
+schedules every dependency-ready node and dispatches its packet to a worker
+inside an attempt worktree, where the worker sees only the files the packet
+names. The controller then runs the deterministic verification once, and a
+judge from a different vendor reviews the recorded result without re-running it.
+A passing attempt is sealed and integrated onto the run ref, a campaign promotes
+each run onto its landing branch, and the orchestrator lands that branch.
+Campaigns, handoffs and the `supervise` watchdog carry the work across sessions,
+so an interrupted run is continued in place instead of being re-authored.
+
+```text
+intent
+  └─ contract: validate · preflight
+       └─ controller
+            ├─ worker attempt in an attempt worktree
+            │     └─ deterministic verification · cross-vendor judge
+            └─ integration ref · promotion · landing branch
 ```
 
-Inspect the target once, write the contract and its task packets, then:
+The vocabulary is in [Concepts](docs/CONCEPTS.md), and the layers, process
+model and gates are in [Architecture](docs/ARCHITECTURE.md).
+
+## Harnesses
+
+A runtime is one harness running one model. Any runtime can be a worker, and a
+judge of another vendor reviews what it produced.
+
+| Harness | Default vendor | Example model |
+| --- | --- | --- |
+| `claude` | Anthropic | `claude-sonnet` |
+| `codex` | OpenAI | `codex-gpt` |
+| `agy` | Google | `agy-gemini` |
+| `dsh` | declared per runtime; DeepSeek in the discovery entry | `dsh-deepseek` |
+| `zcode` | Zhipu | `zcode-glm` |
+| `exec-jsonl` | declared per runtime | the model its command names |
+| `replay` | declared per runtime | the recorded model |
+
+## Documentation
+
+- [Documentation map](docs/README.md): every document and the question it answers.
+- [Vision](docs/VISION.md): why Faberun exists and what it refuses to become.
+- [Concepts](docs/CONCEPTS.md): each term, where it lives, and its invariant.
+- [Getting started](docs/GETTING-STARTED.md): install to a first verified node.
+- [Commands](docs/COMMANDS.md): every verb's synopsis, flags, exit codes and one example.
+- [Architecture](docs/ARCHITECTURE.md): the layers, the process model and the quality gates.
+- [Decisions](docs/adr/README.md): the active ADRs and the format they use.
+- [Design system](DESIGN.md): the identity, the palette and the documentation grammar.
+- [History](docs/history/README.md): the dated records and the path mapping from before the move.
+- [Agent playbook](AGENTS.md): the contributor and agent rules for this repository.
+
+## Development
+
+- `npm run check` runs `node --check` over every `.mjs` under `bin/`, `src/`,
+  `test/`, `evals/` and `.claude/hooks/`.
+- `npm run typecheck` runs `tsc` over the whole tree in `checkJs` mode and must
+  be clean.
+- `npm test` runs the test suite.
+- `node evals/run.mjs --class deterministic --assert-no-model` runs every
+  deterministic case with zero model calls.
+- `node evals/run.mjs --class deterministic --verify-discriminating` requires
+  each case's declared mutation to make the case fail.
+
+[AGENTS.md](AGENTS.md) is the playbook. The skills shipped in `skills/` are
+[faberun](skills/faberun/SKILL.md), for orchestrating agents, and
+[init-agentkit](skills/init-agentkit/SKILL.md), an optional kit that bootstraps
+`AGENTS.md`, `docs/`, ADRs and githooks into another repository. Install either
+into a repository with:
 
 ```bash
-node "$FABERUN" validate contract.json
-node "$FABERUN" preflight contract.json
-node "$FABERUN" run --detach contract.json
-node "$FABERUN" supervise --detach "$TARGET/.runs/<run-id>"   # unattended resume
+faberun skills install faberun
+faberun skills install init-agentkit
 ```
 
-| Goal | Command |
-| --- | --- |
-| Find the active campaign | `campaign list --cwd <repo>` |
-| Pull unseen campaign events | `campaign sync <id> --cwd <repo> --session-id <s>` |
-| Advance the session cursor | `campaign ack <id> --cwd <repo> --session-id <s> --event-id <e>` |
-| Validate a contract | `validate <contract.json>` |
-| Check credentials, models, binaries | `preflight <contract.json>` / `doctor [--cwd <dir>]` |
-| Start without blocking the session | `run --detach <contract.json>` |
-| Read current state | `status <run-dir>` / `status --json <run-dir>` |
-| Name the next action per campaign | `next [--cwd <dir>] [--json]` |
-| View attempts and tokens | `report <run-dir>` |
-| Read what a stopped node needs: gate findings and blocking questions | `findings <run-dir>` |
-| Read the campaign indicators | `metrics <campaign-id> --cwd <repo>` |
-| Stop a run and terminate its providers | `cancel <run-dir>` |
-| Resume an interrupted run | `resume --detach <run-dir>` |
-| Keep finishing a run whose controller died | `supervise --detach <run-dir> [--interval 30]` |
-
-Operational detail: [SKILL.md](skills/faberun/SKILL.md) and the
-[contract reference](skills/faberun/references/contract.md).
-
-### init-agentkit
-
-Bootstraps the agent kit into a repository: canonical `AGENTS.md` with
-`CLAUDE.md`/`GEMINI.md`/`CURSOR.md`/`AGENT.md` symlinks, base docs (VISION,
-ARCHITECTURE, ABSTRACTIONS, GETTING-STARTED), ADRs with template and index, the
-Sentrux structural quality gate, a `create-adr` slash command, and githooks.
-Always ask which compatibility rule applies before running it — see
-[SKILL.md](skills/init-agentkit/SKILL.md).
-
-### Session continuity
-
-Long sessions stay cheap across usage-limit resets: a curated handoff is saved
-to `.claude/session-handoff.md` while the session is warm, and this
-repository's [SessionStart hook](.claude/hooks/session-start.mjs) injects a
-fresh handoff into every new session automatically. The save/resume protocol
-lives inside faberun as
-[references/session-memory.md](skills/faberun/references/session-memory.md).
-
-## Development
+`faberun skills install` copies a skill into a repository; `faberun skills
+register` links the `faberun` skill into every installed harness's own skills
+directory instead, so the harness has it in every repository.
 
-- Node.js 22 or newer; the runtime is plain ESM `.mjs` with no runtime
-  dependencies. TypeScript is a development-only check (`checkJs`/`noEmit`).
-- `npm run check` — syntax; `npm run typecheck` — static types; `npm test` — the suite.
-- The skills of this repository stay active inside it through symlinks in
-  `.claude/skills/`.
-- [AGENTS.md](AGENTS.md) is the canonical guidance; the other agent files are
-  symlinks to it — never edit them.
+Never run `npm install` inside an attempt worktree: husky's `prepare` script
+dirties the ignore snapshot the controller compares against.
 
-## Inspiration
+## History
 
-The memory-layer split (session handoff / campaign handoff / standing memory)
-draws on [ai-memory](https://github.com/akitaonrails/ai-memory) by Akita on
-Rails. Most other patterns here — compile-not-retrieve summaries,
-start-of-session handoff injection, cross-harness workstreams — converged
-independently.
+Faberun began as an internal orchestration tool under an earlier name, and this
+repository began as a personal library of agent skills. Neither record is
+rewritten: the dated history is under `docs/history/`, and the campaign specs
+and journals are under `docs/campaigns/`. The
+[documentation map](docs/README.md) and the
+[history index](docs/history/README.md) point to both.
 
-## License
+## Licence
 
 [MIT](LICENSE).

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "faberun",
-  "version": "0.3.0",
+  "version": "0.7.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {
     "faberun": "bin/faberun.mjs"
   },
-  "repository": "github:feliperun/faberun",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feliperun/faberun.git"
+  },
   "homepage": "https://github.com/feliperun/faberun",
   "files": [
     "bin",
@@ -14,6 +17,9 @@
     "skills",
     "integrations"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -21,6 +27,8 @@
     "check": "for f in bin/*.mjs .claude/hooks/*.mjs src/*.mjs src/*/*.mjs src/*/*/*.mjs evals/*.mjs test/*.mjs test/*/*.mjs; do node --check \"$f\" || exit 1; done",
     "typecheck": "tsc",
     "test": "node --test test/*.test.mjs test/*/*.test.mjs",
+    "docs": "node src/cli/manual.mjs --write",
+    "docs:check": "node src/cli/manual.mjs --check",
     "prepare": "husky"
   },
   "devDependencies": {

package/skills/faberun/SKILL.md

@@ -11,14 +11,15 @@ Read [rules](references/rules.md) first.
 | Action | Read |
 | --- | --- |
 | Author a contract (fallback) | [contract](references/contract.md), [engineering](references/engineering.md) |
-| Launch, resume, integrate | [workflow](references/workflow.md), [operations](references/operations.md) |
+| Launch and resume | [workflow](references/workflow.md), [operations](references/operations.md) |
 | Dispatch a node | [handoffs](references/handoffs.md) |
-| Supervise, answer attention | [operations](references/operations.md), [handoffs](references/handoffs.md) |
-| Verify, judge, settle | [engineering](references/engineering.md), [handoffs](references/handoffs.md) |
+| Supervise, answer | [operations](references/operations.md), [handoffs](references/handoffs.md) |
+| Verify, judge | [engineering](references/engineering.md) |
+| Install, set up, update | [operations](references/operations.md) |
 
 Watchdog re-invocations:
 
-    node src/cli.mjs supervise <run-dir>
-    node src/cli.mjs supervise campaign <id> [--allow-main]
+    faberun supervise <run-dir>
+    faberun supervise campaign <id> [--allow-main]
 
 launchd: `StartInterval 300`; `launchctl load -w ~/Library/LaunchAgents/faberun.plist`.

package/skills/faberun/references/contract.md

@@ -57,6 +57,15 @@ attempt; a spent allowance is handled by runtime re-tiering (below). `usage.json
 tokens and cost per invocation for **reporting only** — no control path reads
 it.
 
+At the contract level, `sharedVerification` is the same command schema as
+`finalVerification`, appended to every node's attempt and integration-candidate
+verification after the packet's own commands and before `finalVerification`,
+which only the phase-terminal node carries. Declare it for the fast repository
+ratchets (source shape, field ownership, brand, docs diet): a node whose write
+set breaks a rule then fails on its own attempt instead of on the
+phase-terminal node's full suite. Both sets count in the node budget and in
+`preflight --time-verification`.
+
 ## Task packets
 
 ```json
@@ -77,10 +86,10 @@ it.
 `instructions`, and `verification` are required and non-empty. An execution
 packet requires non-empty `readFiles` and `writeFiles`; read paths are
 relative to `cwd`, cannot escape it, and must exist at validation time —
-except contract loading defers a missing `readFiles` entry a transitive
-dependency declares in its `writeFiles`, or that sits under one of that
-dependency's directory-shaped `writeRoots` entries (a file-shaped entry
-authorizes only that exact path); every other caller still rejects the
+except contract loading defers a missing `readFiles` or `scopeAcknowledged`
+entry a transitive dependency declares in its `writeFiles`, or that sits under
+its directory-shaped `writeRoots` entries (a file-shaped entry authorizes only
+that exact path); every other caller still rejects the
 missing read. A
 discovery packet has empty `writeFiles`; with an empty `readFiles` it may
 read the repository read-only to produce an execution packet — the one
@@ -93,8 +102,6 @@ rejected; a node has `taskPacket` or `taskPacketFile`, never both. Measure a
 candidate command's real duration before naming it in `verification` or a
 worker instruction — `preflight <contract.json> --time-verification` runs each
 declared command once and fails the contract when it cannot fit that timeout.
-A suite past 600s never fits: target what the change touches and run the whole
-suite out of band.
 
 An `autonomous` packet declares `writeRoots` instead of `writeFiles`:
 whole-repo read, write bounded to the listed files/directories. Scope is
@@ -174,12 +181,17 @@ worker fallback cannot execute commands. Adapters declare
 `acceptEdits`), `zcode` only `yolo` (also default), `dsh` both its default
 `workspace-write` (measured: executes and writes inside the worktree) and
 `danger-full-access` (only for effects outside it); every `codex` sandbox mode
-executes, and `agy`/`exec-jsonl`/`replay` expose no denying mode. Judge modes
+executes, and `agy`/`exec-jsonl`/`replay` expose no denying mode. Each adapter
+also declares `signalsProcesses` (`true`, `false`, or `null` when unmeasured):
+a worker whose adapter declares `false` gets a `## Sandbox` prompt warning not
+to run tests that start and terminate child processes, and
+`requiredCapabilities.signalsProcesses: true` admits only an adapter declaring
+`true`. Judge modes
 are excluded because judges review captured results.
 
-- `claude`: `permissionMode` (default `acceptEdits`; a node that runs
-  commands needs `bypassPermissions`, since headless `acceptEdits` denies
-  execution and the worker can only return `blocked_context`). Executable
+- `claude`: `permissionMode` (a node that runs commands needs
+  `bypassPermissions`, or the worker can only return `blocked_context`).
+  Executable
   override: `executable` or `FABERUN_CLAUDE_BIN`. It disables slash
   commands, MCP, and settings files on every invocation and restricts tools to
   `runtime.tools` (default `Read, Edit, Write, Bash, Glob, Grep`); `--bare` is
@@ -334,7 +346,7 @@ settles `reconciled` and blocks the node with `unknown_effect_reconciled` — a
 durable manual-stop attention boundary. All writes happen under the
 controller lock. `usage.jsonl` is one line per invocation: tokens by kind
 (uncached input, cache read, output), `costUsd` with provenance (`priced`, else
-`provider`, else `unknown`), timestamps — reporting only. See
+`provider`, else `unknown`), timestamps. See
 [operations.md](operations.md) for worktrees, integration, `status.json`,
 notify, the controller lock, and campaigns.
 

package/skills/faberun/references/engineering.md

@@ -22,7 +22,9 @@ declares done. Measure a verification command's real duration before setting
 its `timeoutSec`; a suite can silently outgrow the 600s per-entry cap as it
 grows, and a worker forced to wait past its own timeout backgrounds the
 command and returns prose instead of a result — a protocol failure, not a
-`done`.
+`done`. A harness whose adapter declares `signalsProcesses: false` never
+runs a test that terminates processes; the controller's verification is the
+proof.
 
 Keep secrets in env vars; contracts carry variable names only. Claude
 `bypassPermissions` only in a repository-scoped, recoverable environment;

package/skills/faberun/references/operations.md

@@ -19,7 +19,7 @@ the run ref tip.
 
 `contract.maxParallel` bounds concurrent nodes; each tick dispatches every
 `pending` node whose dependencies are `done`, up to the free slots, each into
-its own worktree. Integration stays serialized.
+its own worktree.
 
 ## Integration transaction
 
@@ -65,10 +65,9 @@ directory is never resumed — it has not proved it needs to be.
 ## Runtime discovery
 
 `doctor --discover [--json]` performs mutation-free harness discovery,
-reporting `{available, exhaustedUntil, reason}` per runtime (missing CLI →
-`not_found`; auth failure has no reset; quota keeps its reset, including Z.ai
-code 1310). Omitted `runtimes`/`runtimeDefaults` are composed once and persisted
-in `routing.assignments`; exhaustion re-tiers within the current tier only,
+reporting `{available, exhaustedUntil, reason}` per runtime. Omitted
+`runtimes`/`runtimeDefaults` are composed once and persisted in
+`routing.assignments`; exhaustion re-tiers within the current tier only,
 otherwise the node parks `attention` with `runtime_tier_exhausted`. Failover
 rules: [contract.md](contract.md).
 
@@ -116,8 +115,7 @@ attempt, error code, done/total — never model text), calls the executable name
 by `FABERUN_NOTIFY_BIN` with that event as JSON on stdin, and appends a
 timestamped receipt (`delivered`, `failed`, `no_transport`) to
 `<run-dir>/notify.jsonl`. Delivery is lossy: **exactly one attempt**, no retry,
-no backoff; `FABERUN_NOTIFY_BACKOFF_MS` appears nowhere in `src`. Unset,
-nothing is spawned and the receipt is `no_transport`.
+no backoff. Unset, nothing is spawned and the receipt is `no_transport`.
 `FABERUN_NOTIFY_BIN=os-macos` selects the bundled `osascript` adapter
 (`canWake: false`); any other value is an executable path. A resume never
 re-sends a notification already recorded for the same node, attempt and outcome.
@@ -138,7 +136,7 @@ Every contract requires `campaignId`; campaign state lives at
 `HANDOFF.md`) and can link multiple runs.
 
 ```bash
-node src/cli.mjs campaign <op> <id> [--cwd <dir>] …flags
+faberun campaign <op> <id> [--cwd <dir>] …flags
   init --goal "Goal" | attach --tool codex --session-id <s> --transcript <path> --format jsonl
   note --session-id <s> --kind <intent|decision|supersede|constraint|outcome|next|open-question|retrospective> --text <t>
   resolve --session-id <s> --question-id <q> --text <a> | sync --session-id <s> | ack --session-id <s> --event-id <e>
@@ -171,10 +169,10 @@ The harness registry (`src/seat/harnesses.mjs`) declares five entries — `claud
 marker, and `canRenderAmbient` (claude only).
 
 ```bash
-node src/cli.mjs seat start <campaign-id> --cwd <dir> [--harness <name>]
-node src/cli.mjs seat attach [<campaign-id>] [--cwd <dir>] [--ssh <host>]
-node src/cli.mjs seat status [--json] [--cwd <dir>]
-node src/cli.mjs seat stop [<campaign-id>] [--cwd <dir>]
+faberun seat start <campaign-id> --cwd <dir> [--harness <name>]
+faberun seat attach [<campaign-id>] [--cwd <dir>] [--ssh <host>]
+faberun seat status [--json] [--cwd <dir>]
+faberun seat stop [<campaign-id>] [--cwd <dir>]
 ```
 
 `attach` prints the command to paste rather than running `tmux attach`, which
@@ -182,3 +180,12 @@ would nest sessions; `--ssh <host>` prints the remote `ssh -t` line. `status
 --json` lists each window's campaign, harness and ambient capability. tmux is
 optional: every `seat` function returns an explicit unavailable result when the
 binary is absent, and only reattaching is lost.
+
+## Install, set up, update
+
+`faberun setup` writes the user runtime config that composition honours when a contract omits runtimes.
+`faberun init` prepares a target repository (`.runs` ignored, skill installed, agent kit optional and always asked).
+`faberun update --check` reads the release channel and writes the cache the banner shows; `faberun update` switches versions only after the new one proves itself.
+`faberun skills install [name]` installs the shipped skills.
+`faberun skills register [--harness a,b] [--copy] [--force]` links the faberun skill into each installed harness's skills directory.
+`faberun campaign unpark <id> [--force]` clears a parked campaign once its run is no longer parked so `supervise campaign` can continue.

package/skills/faberun/references/rules.md

@@ -8,7 +8,9 @@ physical runtime. Use `mode: "discovery"` only when no packet is possible.
 **Prove mechanically.** Every Definition of Done item is an object declaring
 its own proof: a verification `command`, a workspace `path`, or `judgment`.
 Proofs gate before any judge runs, so a fully mechanical node costs no judge.
-Contract-level `finalVerification` runs on the phase-terminal node.
+Contract-level `finalVerification` runs on the phase-terminal node;
+`sharedVerification` runs on every node, so a ratchet-breaking write set
+fails on its own attempt.
 
 **Never wait inside a turn.** No `sleep`/`while` loops, no repeated `status`
 calls, no watched background jobs — every tool call re-sends the whole session

package/src/campaign/chain.mjs

@@ -36,6 +36,7 @@ import { assertContractManifestIntact, parkCampaign, promoteRunInCampaign } from
 import { readCampaign } from "./record.mjs";
 import { validateContract } from "../contract/index.mjs";
 import { defaultControllerIdentity, storedContractDigest, verifyControllerIdentity } from "../engine/run-identity.mjs";
+import { refuseSelfSignal } from "../engine/process-identity.mjs";
 import { HEARTBEAT_INTERVAL_MS, createHeartbeat, groupAlive, heartbeatBreach, readHeartbeat, runProgress, waitForGroupGone } from "../engine/supervise.mjs";
 import { pidAlive, processStartToken } from "../run/lock.mjs";
 import { delay, errorCode, errorMessage } from "../util.mjs";
@@ -147,10 +148,12 @@ function groupKill(pid, signal) {
 /**
  * Terminate the coordinator's process group, bounded: `SIGTERM`, then `SIGKILL`
  * after the named grace. The takeover writes its own lock only once the group
- * is gone, so two coordinators never overlap.
+ * is gone, so two coordinators never overlap. A lock naming this process or its
+ * parent is refused before any signal: that group is the caller's own, so the
+ * refusal is recorded and the takeover leaves it alone.
  *
  * @param {string} campaignPath
- * @param {{lock?: Record<string, unknown>|null, kill?: (pid: number, signal: string) => void, alive?: (pid: number) => boolean, sleep?: (ms: number) => Promise<void>, now?: () => number, graceMs?: number, killGraceMs?: number}} [options]
+ * @param {{lock?: Record<string, unknown>|null, kill?: (pid: number, signal: string) => void, alive?: (pid: number) => boolean, sleep?: (ms: number) => Promise<void>, now?: () => number, graceMs?: number, killGraceMs?: number, append?: (event: Record<string, unknown>) => void}} [options]
  * @returns {Promise<boolean>}
  */
 export async function terminateCoordinatorGroup(campaignPath, options = {}) {
@@ -158,6 +161,7 @@ export async function terminateCoordinatorGroup(campaignPath, options = {}) {
   if (!lock || /** @type {{invalid?: true}} */ (lock).invalid) return false;
   const record = /** @type {Record<string, unknown>} */ (lock);
   const pid = /** @type {number} */ (record.pid);
+  if (refuseSelfSignal(pid, options.append)) return false;
   const kill = options.kill ?? groupKill;
   const alive = options.alive ?? ((target) => pidAlive(target) || groupAlive(target));
   const sleep = options.sleep ?? delay;

package/src/campaign/index.mjs

@@ -110,7 +110,7 @@ export function resolveCampaign(runsDir, campaignId) {
     if (campaigns.length) {
       throw new Error(`no active campaign under ${campaignsDir(runsDir)}; all campaigns are closed`);
     }
-    throw new Error(`no campaign found under ${campaignsDir(runsDir)}; initialize one with: runner.mjs campaign init`);
+    throw new Error(`no campaign found under ${campaignsDir(runsDir)}; initialize one with: faberun campaign init`);
   }
   if (active.length > 1) {
     const ids = active.map((entry) => entry.campaign.id).join(", ");
@@ -237,6 +237,21 @@ export function parkCampaign(campaignPath, attention) {
   return parked;
 }
 
+/**
+ * A promotion record is only worth keeping when it actually moved the land
+ * branch. `promoteRun`'s `already_promoted` result reports the branch's
+ * *current* head, which may have advanced past this run since it last landed
+ * (another run promoted in between, or a coordinator restart is replaying the
+ * same call); recording it would add a second entry for a run that never
+ * moved anything.
+ *
+ * @param {import("../repo/integrate.mjs").PromoteRecord} record
+ * @returns {boolean}
+ */
+export function promotionMovedBranch(record) {
+  return record.status === "promoted";
+}
+
 /**
  * Promote a run onto the campaign's landing branch and record it. The branch
  * name comes from the campaign record, never from the caller, so a campaign
@@ -257,6 +272,7 @@ export function promoteRunInCampaign({ campaignPath, repo, runId, runHead, baseS
     finalVerificationPassed,
     allowMain,
     onPromoted: (record) => {
+      if (!promotionMovedBranch(record)) return;
       recordPromotion(campaignPath, {
         runId: record.runId,
         ...(contractPath === undefined ? {} : { contractPath }),

package/src/campaign/metrics.mjs

@@ -23,7 +23,7 @@
  * 1 only when a whole run had to be re-authored after a failure that
  * `resume` could not repair.
  *
- * The second half of this module is the `runner.mjs metrics` command: reading
+ * The second half of this module is the `faberun metrics` command: reading
  * a campaign's linked runs and parsing the command's flags live here, while
  * `metrics-report.mjs` decides how the projection is printed.
  */
@@ -397,7 +397,7 @@ function orderOf(entry) {
   return Number.isFinite(entry.atMs) ? entry.atMs : 0;
 }
 
-/** Flags of `runner.mjs metrics`, declared here so the router only names them. */
+/** Flags of `faberun metrics`, declared here so the router only names them. */
 /** @type {import("node:util").ParseArgsOptionsConfig} */
 export const METRICS_OPTIONS = { cwd: { type: "string" }, json: { type: "boolean" } };
 
@@ -479,7 +479,7 @@ function readRunNodes(runDir) {
 }
 
 /**
- * `runner.mjs metrics <campaign-id> [--cwd <dir>] [--json]`: project the
+ * `faberun metrics <campaign-id> [--cwd <dir>] [--json]`: project the
  * campaign's recorded artefacts and return what the command prints. Reading
  * only, and never a write: a report of a closed campaign must not touch it.
  *

package/src/cli/brand.mjs

@@ -188,7 +188,7 @@ export function renderUsage() {
     "<status|report> <run-dir> [--json]",
     "findings <run-dir>",
     "doctor [<contract.json>] [--cwd <dir>] [--discover] [--json]",
-    "setup [--yes] [--harnesses <a,b>] [--worker <id>] [--judge <id>] [--json]",
+    "setup [--yes] [--no-skill] [--harnesses <a,b>] [--worker <id>] [--judge <id>] [--json]",
     "init [--cwd <dir>] [--yes] [--no-skill] [--agentkit] [--greenfield|--stable] [--json]",
     "update [--check] [--json]",
     "models [--probe] [--json]",
@@ -200,6 +200,7 @@ export function renderUsage() {
     "seat <start|attach|status|stop> [<campaign-id>] [--cwd <dir>] ...",
     "skills list",
     "skills install [<name>...] [--target <dir>] [--global] [--force]",
+    "skills register [--harness <a,b>] [--copy] [--force] [--json]",
   ];
   return `${groups.map((group) => `usage: faberun ${group}`).join("\n")}\n`;
 }

package/src/cli/campaign.mjs

@@ -728,3 +728,5 @@ function usage() {
   );
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;

package/src/cli/contract.mjs

@@ -65,3 +65,5 @@ function usage() {
   process.stderr.write("usage: faberun contract validate <contract.json>\n");
   process.exitCode = 2;
 }
+
+export default OPERATION_OPTIONS;