faberun 0.3.0

package/skills/faberun/references/contract.md

@@ -0,0 +1,380 @@
+# Contract reference
+
+Node.js 22+, plain ESM `.mjs`; TypeScript is development-only (`npm run
+typecheck`). Schema version is `3`.
+
+## Shape
+
+```json
+{
+  "schemaVersion": 3,
+  "contractVersion": "0.3.0",
+  "id": "feature-42",
+  "campaignId": "feature-42",
+  "goal": "Deliver feature 42 with tests",
+  "cwd": "../target-repo",
+  "maxParallel": 1,
+  "stallTimeoutSec": 300,
+  "timeoutSec": 2400,
+  "runtimeDefaults": { "worker": "flash", "judge": "sol" },
+  "runtimes": {
+    "flash": { "harness": "dsh", "model": "deepseek-flash", "reasoning": "high",
+      "vendor": "deepseek", "sandbox": "danger-full-access",
+      "config": { "provider": "deepseek-official", "api_key.env_key": "DEEPSEEK_API_KEY" } },
+    "luna": { "harness": "codex", "model": "gpt-5.6-luna", "reasoning": "xhigh" },
+    "sol": { "harness": "codex", "model": "gpt-5.6-sol", "reasoning": "xhigh", "vendor": "openai-sol" },
+    "opus": { "harness": "claude", "model": "opus", "permissionMode": "acceptEdits" },
+    "zcode-flash": { "harness": "zcode", "model": "glm-5.3-flash", "vendor": "zhipu-flash", "permissionMode": "edit" },
+    "zcode-pro": { "harness": "zcode", "model": "glm-5.3", "vendor": "zhipu-pro", "permissionMode": "plan" },
+    "agy-flash": { "harness": "agy", "model": "gemini-3.8-flash-low" }
+  },
+  "nodes": [
+    {
+      "id": "implementation", "type": "backend", "phase": "implementation",
+      "taskPacketFile": "packets/implementation.json", "dependsOn": [], "timeoutSec": 2400,
+      "definitionOfDone": [
+        { "id": "behavior-implemented", "text": "The requested behavior is implemented",
+          "proof": { "kind": "command", "ref": "npm test" } },
+        { "id": "diff-scoped", "text": "No unrelated files changed",
+          "proof": { "kind": "path", "ref": "src/feature-42.ts" } },
+        { "id": "design-honored", "text": "The change honors the stated design decisions", "judgment": true }
+      ],
+      "gate": { "failOn": ["major", "critical"], "maxRevisions": 1 }
+    }
+  ]
+}
+```
+
+Every `definitionOfDone` item declares `id`, `text`, and how it is proven:
+`proof.kind` `command` (re-runs the command, capped at `min(timeoutSec, 120s)`)
+or `path` (a file must exist), or `judgment: true` for the judge. `proof: {
+kind: "verification", ref: <index> }` reuses a `verification` entry's already
+recorded result by position instead of re-running it — never by comparing argv
+strings, since a joined argv loses shell semantics. A schema-1 string item is
+rejected. There is no spend ceiling in the schema: no `maxInputTokens`,
+`maxCostUsd`, or `usagePolicy`. `timeoutSec` and `stallTimeoutSec` bound an
+attempt; a spent allowance is handled by runtime re-tiering (below). `usage.jsonl` records
+tokens and cost per invocation for **reporting only** — no control path reads
+it.
+
+## Task packets
+
+```json
+{
+  "mode": "execution",
+  "objective": "One concrete outcome",
+  "instructions": ["Exact behavior to implement"],
+  "readFiles": ["src/feature.ts"],
+  "writeFiles": ["src/feature.ts"],
+  "symbols": ["runContract"],
+  "decisions": ["Decision already made; do not reopen"],
+  "nonGoals": ["Explicitly excluded work"],
+  "verification": [{ "argv": ["node", "--test", "test/feature.test.mjs"] }]
+}
+```
+
+`mode` is `execution`, `discovery`, or `autonomous`. `objective`,
+`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
+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
+exception to closed scope — otherwise it is closed to the listed files. Each
+`verification` entry is `{argv, cwd?, timeoutSec? (default 120, max 600),
+repeat? (default 1, max 8), env?}` — at most 32 commands, 64 argv items, 32
+KiB argv bytes per command. `env` declares variable *names* only; values
+never travel in the packet. `prompt`/`promptFile` are
+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
+advisory, not a gate: a completed attempt whose worker result and
+verification both pass keeps unexpected writes as a `scopeFindings` entry and
+still reaches `done`; only a failed verification turns the unexpected paths
+into part of the failure. Redirect a toolchain's cache/build output under
+`.runs/` (git-ignored, outside the snapshot).
+The workspace snapshot skips `.runs`, `.git`, `node_modules`, `.claude`,
+`.codex` at the repository root.
+
+The stored `contract.json` inlines every packet (dropping `taskPacketFile`
+and the generated prompt) and carries a `packetHash` the runner validates on
+load, so a run directory is a self-contained resumable record.
+
+## Worker results
+
+```json
+{
+  "status": "done",
+  "summary": "Implemented the described behavior",
+  "changedFiles": ["src/feature.ts"],
+  "verification": ["node --test test/feature.test.mjs"],
+  "artifacts": [],
+  "missingContext": []
+}
+```
+
+`status` is `done` (empty `missingContext`) or `blocked_context` (at least one
+`missingContext` entry) — the only response when the closed context is
+missing something, never repository-wide exploration. Bounded: 32 KiB total,
+4 KiB summary, 32 entries each in `changedFiles`/`verification`/`artifacts`
+(16 in `missingContext`), 2 KiB per entry (16 KiB per artifact). Unknown
+provider-added fields are dropped; missing/malformed canonical fields are
+rejected (`worker-result.mjs`). A discovery node returns `done` with exactly
+one `artifacts` entry: the execution packet for the next node.
+
+## Runtimes and routing
+
+Resolve a worker as `nodes[].runtime`, then `runtimeDefaults.worker`; a judge
+as `nodes[].gate.runtime`, then `runtimeDefaults.judge`. When `runtimes` and
+`runtimeDefaults` are both omitted, the factory composes them from the
+discovery catalogue (`DISCOVERY_RUNTIME_DEFINITIONS`: `dsh-deepseek`,
+`zcode-glm`, `agy-gemini` at tier 1, `codex-gpt` and `claude-sonnet` at tier 2;
+available when the binary answers and every `config["*.env_key"]` it names is
+set): the cheapest available runtime executes, the strongest runtime of a
+*different vendor* judges, persisted in `routing.assignments`; no admissible
+cross-vendor judge fails by name (`runtime_assignment_judge_unavailable`).
+
+`harness` names the adapter that runs the turn (`claude`, `codex`, `agy`,
+`dsh`, `zcode`, `exec-jsonl`, `replay`) and `model` what it asks; the two
+vary independently — DeepSeek answers through `dsh`, GLM through `zcode`. Name
+a runtime id `<harness>-<model>` so a recorded run says which harness produced
+it; ids take letters, numbers, dot, underscore, dash only. Vendor is resolved (`resolveVendor` in `harnesses/index.mjs`), not the
+harness name: an explicit `vendor`, else a provider-config override (a codex
+runtime with `config.model_provider: "deepseek"` is vendor `deepseek`), else
+the harness default (`claude`→anthropic, `codex`→openai, `agy`→google,
+`zcode`→zhipu); `dsh`/`replay`/`exec-jsonl` have no default and must declare
+`vendor`. Validation rejects a gate-enabled node whose worker and judge
+resolve to the same vendor, and does the same for every runtime in the
+worker's declared fallback chain (rejecting a cycle in that chain outright)
+— all statically knowable from the contract alone. The symmetric case, a
+judge fallback landing on the vendor of the worker runtime that actually ran,
+cannot be checked statically (it depends on which worker runtime ran this
+attempt) and is instead refused at execution; see Failover below. Two models of one family (a GLM 5.3-flash worker judged by GLM 5.3) pair only by
+declaring distinct `vendor` strings — a claim about review independence.
+
+An optional `runtimes[<id>].pricing` object declares `inputPerMTok`,
+`cachedInputPerMTok`, and `outputPerMTok` (each finite and >= 0, at
+least one required, unknown keys rejected) and prices that runtime's canonical
+counters when the harness reports no cost; a missing counter stays `unknown`,
+never zero.
+
+Non-empty `taskPacket.verification` is rejected when the resolved worker or a
+worker fallback cannot execute commands. Adapters declare
+`permissionExecution`: `claude` only `bypassPermissions` (default
+`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
+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
+  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
+  never used because it also disables the tool-policy hook.
+- `codex`: `sandbox` (`read-only`, `workspace-write` default,
+  `danger-full-access`); arbitrary `config` entries serialize as `-c
+  key=value`; disables browser/computer-use/app/sub-agent tooling and MCP by
+  default (`CODEX_PREAMBLE_OVERRIDES`). Executable override: `executable` or
+  `FABERUN_CODEX_BIN`. A profile name never selects a custom provider:
+  Codex accepts unknown profiles silently.
+- `zcode`: the GLM route — Z.ai's own harness CLI, driven headlessly
+  (`zcode --prompt --json`; `executable` / `FABERUN_ZCODE_BIN` override).
+  Model and endpoint travel
+  as `ZCODE_MODEL` (`config.provider`/model, default `glm`/model; a `[1m]` model
+  suffix is stripped — the provider reports the context window itself) and
+  `ZCODE_BASE_URL` (default the Z.ai Anthropic-compatible endpoint); the token
+  rides the provider-derived `${PROVIDER}_API_KEY` variable built from
+  `config["auth_token.env_key"]` (default `ZAI_API_KEY`). `permissionMode`
+  maps to `--mode` (`build`/`edit`/`plan`/`yolo`; default `yolo` — a judge
+  runtime declares `plan`). No schema flag and no tool policy, and the CLI's
+  `--settings`/hooks surface stays unwired:
+  `structuredOutput`/`toolPolicy` are `false`, judges arbitrate through the
+  prompt-embedded schema, and a `toolPolicy` requirement rejects the runtime.
+  Continuation resumes `sess_…` ids. Mid-run metering reads zero; usage
+  settles from the terminal result.
+- `agy`: the installed `agy` CLI (or `FABERUN_AGY_BIN`); optional
+  `printTimeout`; omit `reasoning` for models without `--effort`.
+- `dsh`: the DeepSeek Harness through the shipped `sdk` JSON-RPC client;
+  `headless` drops usage. Normalization assumes streamed `inputTokens` excludes
+  `cacheReadTokens`; `usage.jsonl` records it unchanged as uncached input.
+  `config.provider` is required (`deepseek-official`); `model` and `reasoning`
+  pass through verbatim. Its catalogue is the one `models` prints
+  (`deepseek-flash` is the default); unknown ids fail in the harness.
+  Authentication stays in `DEEPSEEK_API_KEY`;
+  `config["api_key.env_key"]` only names it for `preflight`. `sandbox` maps to
+  `DSH_PERMISSION_MODE`, default `workspace-write` (above). Every attempt loads
+  `dsh/closed-packet.patch.yml`; `config.patch` stacks one layer. Executable
+  override: `executable` or `FABERUN_DSH_BIN`. No default vendor,
+  continuation (`session/resume` is ACP-only), or native schema flag; the judge
+  schema travels in the prompt.
+- `exec-jsonl`: generic harness for a JSONL-protocol executable — one
+  `run.request` on stdin, `run.started`/`message`/`run.completed`/
+  `run.failed` on stdout. Set `executable` (or
+  `FABERUN_EXEC_JSONL_BIN`), `args`, `versionArgs` when `--version` is
+  unsupported.
+- `replay`: stands in for any provider in tests — recorded, already-normalized
+  envelopes, zero model calls. `config["replay.recording"]` names a JSONL
+  recording consumed strictly in order via a `.cursor` sidecar; each consumed
+  line appends one record to `<recording>.invocations.jsonl`. A missing line
+  emits `replay_exhausted` (exit 1); a path escape in `files` emits
+  `replay_path_escape` (exit 2) and writes nothing.
+
+Continuation is capability-gated (`codex`, `claude`, `zcode`, `agy`,
+`exec-jsonl`, `replay` all declare it) and requires an exact fingerprint of
+the runtime definition; a runtime change, a failover hop, or an adapter
+without the capability starts a fresh session carrying prior structured
+summaries forward, never a continuation ID.
+
+### Failover
+
+`runtimes[<id>].fallback` names at most one other runtime id — the single hop
+a role takes on provider exhaustion at execution time; a self-loop is
+rejected outright. Runtimes can chain (a fallback whose fallback names a third,
+and so on); validation walks that chain for a gated worker and rejects a cycle,
+but does not walk a chain no gated worker reaches, or a judge's. `tier` groups runtimes
+for composed re-tiering (cheaper tiers first); `costRank` breaks ties. A
+worker fallback is taken unconditionally once reachable and unattempted this
+revision. A judge fallback is admissible only when it differs in vendor from
+the worker runtime that actually ran the attempt; a same-vendor fallback is
+refused and the node parks `attention` with
+`judge_fallback_vendor_conflict`. Either role exhausting its one-hop budget
+without an admissible target ends `exhausted` (worker) or `attention` (judge)
+with `runtime_tier_exhausted`, preserving any announced `exhaustedUntil`.
+Budget, scope, permission, and authority failures never trigger failover.
+
+When an exhaustion envelope announces `resetAt` strictly after now and
+strictly before the node's own deadline, the controller waits for it on the
+same runtime instead of taking an edge; a reset outside that window, or none
+announced, takes the declared/synthesized edge. A wait is not a hop and does
+not consume the failover budget.
+
+`doctor --discover [--json]` normalizes each harness's exhaustion signal into
+`{available, exhaustedUntil, reason}` (missing CLI → `not_found`; auth
+failure has no reset; a quota response keeps its reset, including Z.ai code
+1310).
+
+## Graph and states
+
+`dependsOn` forms a DAG; a node starts once every dependency is `done`, and a
+failed terminal dependency makes it `blocked`. Terminal states: `done`,
+`no-op`, `blocked`, `failed`, `exhausted`, `stalled`, `canceled` — every node
+ends in exactly one. `stallTimeoutSec` bounds silence on stdout/stderr, but
+only for a harness declaring `streamsOutput` (true for `codex`, `claude`,
+`agy`, `dsh`; false for `zcode`, which dumps its turn at exit);
+others fall back to `timeoutSec` alone.
+`timeoutSec` (default 2400s) caps one invocation and may be overridden per
+node; a node is bounded by `(1 + maxRevisions) × 2 × timeoutSec`. Both clocks
+are monotonic and pause with host suspend. `maxParallel` above 1 dispatches
+every dependency-ready node concurrently, each into its own attempt
+worktree; integration stays serialized. Nodes of one phase need no edge
+between them: a continuation a live invocation already claims is never
+offered to a second node, so one session runs one turn.
+
+## Gates
+
+`gate: false` skips review (`none`). A gate object accepts `runtime`
+(judge override), `review` (`none`/`advisory`/`blocking`, default
+`advisory`), `failOn` (default `["critical"]`), `maxRevisions` (default 1).
+`advisory` records the verdict, findings and `maxSeverity` and still settles
+`done` on deterministic verification alone — it never consumes a revision or
+re-dispatches. `blocking` re-dispatches within `maxRevisions` when findings
+reach `failOn`. Validation requires `critical` whenever `major` is in
+`failOn`, and `major` in `failOn` for a `blocking` gate: `["critical"]` alone
+passes every major finding, which is close to no gate.
+
+The revision budget counts gate rejections, not worker starts; a resume or a
+crash-restart never consumes one (tracked separately as `attempt` vs.
+`revisions`). Deterministic `verification` commands run once by default
+before any judge and the judge reviews the recorded results, never
+re-running them (`repeat` opts into re-running a flaky check). A judge
+output is `pass` only with empty `findings` and `maxSeverity: none`; for
+Codex judges, normalization selects the last parseable JSON agent message.
+Zero or multiple verdict-shaped messages, a dead judge, or a wall-clock kill
+is a review-protocol defect, not a verdict — one bounded re-ask; if that
+also fails, advisory review completes `done` with `gate.verdict:
+invalid_judge_output`, while blocking review marks the node `blocked` with
+`judge_unavailable`, preserving the worker result and verification for
+`resume` to re-judge. There is no first-class `stopped` state: model a
+falsification gate as a node whose Definition of Done requires a durable
+stop artifact and a fail-closed check, and do not schedule descendants after
+it is accepted.
+
+## Run artifacts
+
+Under `<cwd>/.runs/<id>/`:
+
+```text
+contract.json  run.json  status.json  findings.json
+nodes/<id>.json
+logs/<id>.<attempt>.<worker|judge>[.r<n>].jsonl / .err
+operations/<invocationId>.intent.json / .settlement.json
+usage.jsonl  integration.jsonl  events.jsonl  notify.jsonl  STATUS.md
+```
+
+`operations/` holds the exact-once intent/settlement record for every
+provider invocation, written before dispatch and merged idempotently after:
+`settled` means a known harness outcome; `unknown_effect` means the request
+may have run without proof and is not permission to retry. Replay of an
+unknown-effect window needs `replayPolicy: "safe"` (default) plus a clean
+persisted scope across the window and passing verification; otherwise it
+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
+[operations.md](operations.md) for worktrees, integration, `status.json`,
+notify, the controller lock, and campaigns.
+
+## Resume
+
+`resume <run-dir>` continues an interrupted run in place: same run, same
+node, attempt plus one, packet frozen. It adopts completed work first — a
+worker log proving the turn finished recovers an orphaned provider process,
+and a node `blocked` with `judge_unavailable` is re-judged from the
+preserved result, never re-dispatched to a worker. Only then does it
+re-dispatch ordinary failures (`failed`, `stalled`, `canceled`,
+wall-clock-`exhausted`, `blocked`/`dependency_failed`) as attempt plus one,
+with a bounded `## Previous attempt` section (prior error, judge/scope
+findings, failing commands) appended to the regenerated prompt.
+`resume --node <id>` limits the retry to that node and its dependents.
+
+`resume --answer <node-id>=<path>` records an operator's answer for a node
+`blocked` with `context_missing`, then re-dispatches it and its dependants,
+narrowed exactly like `--node`. The file is read once, relative to the
+shell's own cwd rather than the contract's, refused above 8 KiB, and
+persisted as an `operator-answer` execution override (`kind`, `at`, `reason`,
+a bounded `text`) — the authored packet and `packetHash` untouched, and a
+repeated answer appends rather than merges. A malformed value, an unknown
+node, an unreadable or oversized file, or a node not blocked on missing
+context each refuse with their own message. The answer is text only, never
+written into the attempt worktree.
+
+`unknown_effect_reconciled` is re-dispatched only with an explicit
+`--reconcile <node-id>`. Resume accepts a current `HEAD` that is a
+descendant of the recorded `gitHead` (workers and the orchestrator commit
+between attempts) and records the new head; a non-descendant is refused. A
+`dirtyTreeFingerprint` mismatch is a status warning, not a refusal.
+
+## Environment doctor, cancel, JSON status
+
+`doctor [<contract.json>] [--cwd <dir>] [--json]` is mutation-free: checks
+`cwd` is a git work tree, `.runs/` is ignored, `node`/`npm` are on `PATH`,
+and — with a contract — every routed harness exists and probes cleanly.
+`cancel <run-dir>` signals the controller (`SIGTERM` then `SIGKILL` after
+2s), takes over its now-stale lock, terminates every recorded invocation,
+and marks the run terminal; it cannot act on a lock held by its own process.
+`status --json`/`report --json <run-dir>` emit stable `schemaVersion: 1`
+payloads for streaming monitors instead of `STATUS.md`.

package/skills/faberun/references/engineering.md

@@ -0,0 +1,29 @@
+# Verification and tools
+
+The session itself runs only these; everything else runs detached.
+
+| You want | Run |
+| --- | --- |
+| Probe runtimes and host before spending tokens | `preflight <contract.json>`, `doctor [--cwd <dir>]` |
+| Choose runtime and model, and see the effort each accepts | `models [--probe] [--json]` |
+| Prove each verification command fits its own `timeoutSec` | `preflight <contract.json> --time-verification` |
+| Pull unseen campaign events | `campaign sync <id> --cwd <repo> --session-id <s>` |
+| Advance that cursor past an event | `campaign ack <id> --cwd <repo> --session-id <s> --event-id <e>` |
+| Wake only on actionable change, poll every 30s | `campaign watch <id> --cwd <repo> --wake` |
+| Read the campaign indicators | `metrics <campaign-id> [--cwd <dir>] [--json]` |
+| Ask one question about many large files | `bulk-read --question <text> --paths <a,b,c>` -- bullets only, corpora under 1500 lines are refused |
+
+**Foreground children.** Worker prompts run builds, watchers, and servers in
+the foreground; only the runner is detached. Keep output bounded
+(`| tail -n 200`). Never instruct a worker to run a command slower than its
+own tool's foreground timeout, including the full test suite — that is what
+`taskPacket.verification` is for, run by the controller after the worker
+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`.
+
+Keep secrets in env vars; contracts carry variable names only. Claude
+`bypassPermissions` only in a repository-scoped, recoverable environment;
+otherwise `acceptEdits`, letting denials become `blocked`.

package/skills/faberun/references/handoffs.md

@@ -0,0 +1,26 @@
+# Handoffs: capsule, brief, settlement
+
+**Campaign first.** Establish or discover the durable campaign before
+launching work; stop instead of guessing when several are active. Attach this
+session, read `HANDOFF.md`, and record every material intent, decision, and
+open question as a campaign event — handoff state, not documentation.
+
+**Closed packets.** Each node lists exact `readFiles`, `writeFiles`, and
+`verification`. Workers and judges inspect only those paths and return the
+structured `blocked_context` result instead of exploring.
+
+**A packet is an instruction and a detector, not a sandbox.** Only a `claude`
+worker is stopped mechanically, and only on `Write`/`Edit`/`NotebookEdit`: a
+write through `Bash` is never inspected, and no other harness is prevented at
+all. Everything else is caught after the attempt by the scope comparison in
+`engine/scope.mjs`, which is advisory when verification passes. Scope keeps an
+honest worker inside its lane and records what left it. It does not contain an
+adversarial one, so give a worker no credential or write access you would not
+give the packet's whole repository.
+
+**Settlement.** Store raw worker output under `.runs/`; bring only status and
+actionable verdicts into the session.
+
+The packet shape and the worker-result object live in
+[contract.md](contract.md); the `HANDOFF.md` capsule and the campaign journal
+live in [operations.md](operations.md).

package/skills/faberun/references/operations.md

@@ -0,0 +1,184 @@
+# Faberun operations
+
+## Attempt worktrees
+
+An execution repository is a git work tree with at least one commit. A run
+creates the integration head `refs/faberun/<run-id>/run` at the recorded
+source `gitHead`. Every worker attempt gets a linked worktree at
+`.runs/worktrees/<run-id>/<node-id>.<attempt>` on branch
+`faberun/<run-id>/<node-id>/<attempt>`, cut from that ref; the node snapshot records
+`worktree.path`, `.branch`, `.baseSha` and the sealed `.commit`. Provider,
+scope, verification and judge processes all use that path; `contract.cwd` stays
+the home of run/control artifacts. An installed root `node_modules` is
+symlinked into every attempt worktree, never copied.
+
+A retried attempt never discards the previous one's edits: the controller seals
+the previous worktree first and, when that seal has a diff, cuts the next
+attempt from that sha (`worktree.previousAttempt`); an empty seal falls back to
+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.
+
+## Integration transaction
+
+The controller serializes integration. It seals uncommitted attempt edits with a
+commit naming the run/node/attempt (`empty: true` in the journal when there is
+no diff), appends a `prepared` record to `integration.jsonl` (node, attempt,
+attempt sha, previous run-ref tip, candidate sha, verification evidence) before
+creating anything, and builds the candidate — fast-forward or merge — on
+`refs/faberun/<run-id>/candidate` / `.runs/worktrees/<run-id>/.candidate`,
+where node `verification` runs once. A pass advances the run ref with a
+conditional `update-ref` and writes the node `done` with `integratedHead`. A
+failed candidate removes the candidate ref/worktree, leaves the run ref
+untouched, and keeps the attempt worktree. A conflict marks the node `attention`
+with the conflicting paths and cleans the scratch worktree.
+
+Resume replays `integration.jsonl`, never ancestry, to identify the one
+unfinished transaction and complete it idempotently. A resume that re-dispatches
+a failed/stalled/exhausted/canceled node cuts the next attempt from the previous
+attempt's sealed sha, the same continuation rule as any other retry.
+
+## Controller lock and takeover
+
+One controller drives a run, holding `<run-dir>/controller.lock`: `{pid,
+processStartToken, startedAt, hostname}`. Acquisition is an exclusive create
+with no TTL. A contender treats the lock as stale only once it can prove the
+holder dead — the pid is gone, or its process start token no longer matches
+(pid recycled); anything less is `controller_active` and it exits untouched.
+Takeover renames the lock aside, re-checks the captured record is stale, then
+installs its own; a capture that turns out live is handed back. Worker/judge/
+verification children run detached in their own process group, so before
+dispatching new work `resume`'s recovery pass terminates (`SIGTERM` then
+`SIGKILL`, same as `cancel`) every invocation recorded for a `running` node —
+unless it is still inside its deadline, when it is adopted and its result read.
+`cancel <run-dir>` signals a live controller first, so its own takeover never
+waits on an expiry.
+
+`supervise <run-dir> [--detach] [--interval <sec>]` is the watchdog above that.
+It holds no lock and writes no state: every interval (default 30s) it launches
+`resume --detach` when a node is unfinished and no controller is live, exits 0
+once all are terminal, and stops after three failed launches. An empty run
+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,
+otherwise the node parks `attention` with `runtime_tier_exhausted`. Failover
+rules: [contract.md](contract.md).
+
+## Status
+
+`<run-dir>/status.json` (`status --json`'s payload: identifiers, `goal`, `usage`,
+`controller` state, `summary`, and one `nodes[]` entry per node — id, status,
+phase, runtime, attempt, revisions, cost, verdict, note, `errorCode`,
+`blockedBy`) and `.runs/status.json` (a ≤1 KiB pointer: run and campaign id,
+`state`, checkpoints, `activeNode`, `costUsd`, `needsYou`, `attention`,
+`generatedAt`) are written atomically every controller tick and at run terminal.
+`status <run-dir>` renders Needs you, Now, Nodes and Cost;
+`integrations/claude-code/statusline.sh` reads the pointer for an ambient prompt
+segment. `next [--cwd <dir>] [--json]` prints one line per active campaign
+naming the most urgent action and its command; read-only, no lock, writes
+nothing.
+
+## Dashboard
+
+`node src/web/server.mjs [--port 4173] [--cwd <repo>]` serves a read-only,
+SSE-refreshed page on `127.0.0.1:4173` over `status.json`, node JSON,
+`events.jsonl`, `usage.jsonl`, `notify.jsonl` and `HANDOFF.md`. Sections:
+campaign picker; **Now**; **Needs you** (each attention item with its resolving
+command); **Runs**; **Run drawer** on row click with per-node log, verification,
+diff, findings and prompt tabs; **Handoff**. The snapshot is bounded to 200 KiB,
+shrinking the drawer's tails, prompt, then handoff.
+
+## Remote API
+
+The same server exposes the phone surface under `/api/*`, behind the
+same token and bind. Reads: `GET /api/campaigns`, `/api/campaigns/<id>`,
+`…/brief`, `/api/seats`, and `…/events?after=<cursor>` (one bounded page, ≤32 KiB
+and ≤100 entries, so a client starting at zero never drags the whole journal).
+Writes shell out to the runner CLI and touch no state themselves:
+`POST …/decisions/<id>` → `campaign resolve`; `…/note` → `campaign note`;
+`…/pause` and `…/resume` → `cancel` / `resume --detach`; `/api/seats/<id>/switch`
+→ `seat switch`. No replan, contract, routing or gate route exists on purpose:
+the contract is frozen with a digest, and the phone's middle ground is a note.
+
+## Notify
+
+On `node.terminal`, `run.terminal` and `attention` the controller renders a
+one-line message from counters and identifiers only (node id, run id, state,
+attempt, error code, done/total — never model text), calls the executable named
+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`.
+`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.
+No transport is a default: `doctor`, `preflight` and the foreground launch warn
+when the variable is empty, and `--wake` reports no adapter can wake a session.
+Campaign-level lines are queued in `.runs/inbox.jsonl`, the managed block's
+append-only record — one object per line `{schemaVersion, eventId, at, type,
+campaignId, runId, nodeId, status, errorCode, dedupeKey, summary}`, deduped on
+`dedupeKey` (first write wins) with one `O_APPEND` write per line.
+`campaign watch --wake --detach` queues there and delivers through
+`<campaign-dir>/notify.jsonl`; a durable `watch.lock` plus the inbox dedupe keep
+two detached watchers from double-sending across a restart.
+
+## Campaigns
+
+Every contract requires `campaignId`; campaign state lives at
+`.runs/campaigns/<campaign-id>/` (`campaign.json`, `journal.jsonl`,
+`HANDOFF.md`) and can link multiple runs.
+
+```bash
+node src/cli.mjs 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>
+  watch --wake [--detach] | show | close  ·  list (no id)
+```
+
+`sync` is the user-pull read: campaign header, the newest linked run's
+`status.json` summary, and unseen journal events (≤8000 bytes) after the
+session cursor, without moving it. `ack` is the only cursor writer, keyed by the
+journal's own event id. `watch --wake [--detach]` polls every linked run's
+`status.json` every 30s and prints one line per actionable change (terminal run,
+attention node, stale controller lock, twenty idle minutes), exiting once the
+campaign is closed. `close` refuses until a `retrospective` note exists; a
+closed campaign stays inspectable but rejects further writes. The managed block
+at the bottom of the target repo's `AGENTS.md` mirrors active state and names a
+parked run's nodes, error codes and `resume` command.
+
+`HANDOFF.md` is an atomic ≤16 KiB projection of recent intents, decisions,
+constraints, outcomes, next action and open questions, refreshed at
+initialization, registration, transitions and terminal completion;
+`journal.jsonl` is the append-only, fsynced narrative.
+
+## Operator seat
+
+The seat is one tmux session, `faberun-seat`, with one window per open
+campaign. It hosts the operator's interactive harness and never drives a run:
+state writes stay with the controller, and a dead pane cannot touch `.runs/`.
+The harness registry (`src/seat/harnesses.mjs`) declares five entries — `claude`,
+`codex`, `zcode`, `dsh`, `agy` — each with interactive argv, an environment
+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>]
+```
+
+`attach` prints the command to paste rather than running `tmux attach`, which
+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.

package/skills/faberun/references/rules.md

@@ -0,0 +1,35 @@
+# Load-bearing rules
+
+**One contract per approved plan step.** Inspect the repository once, then
+author every node of the step with its `dependsOn` edges in a single turn.
+Serial micro-contracts keep the expensive control session alive for the whole
+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.
+
+**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
+context. Check status once per invocation, report one line, end the turn.
+Interrupt the user only for `blocked`, `failed`, `exhausted`, `stalled`, or
+completion.
+
+**No spend ceiling.** `timeoutSec` and `stallTimeoutSec` bound an attempt;
+there is no `maxInputTokens`, `maxCostUsd`, or `usagePolicy`. A spent provider
+allowance is handled by runtime re-tiering and discovery
+([contract.md](contract.md)), never a ceiling the operator had to guess. Usage
+is recorded per attempt in `usage.jsonl` for reporting only.
+
+**Gates.** The judge reviews captured results instead of re-running them.
+Default `failOn` to `critical`, set `maxRevisions` explicitly, keep judge and
+worker runtimes different. After two rejections or an exhaustion, create one
+targeted fix node from the verbatim finding — never copy the graph.
+
+Express model choice only in `runtimes`, `runtimeDefaults`, or an explicit
+node override — never as model-specific branches in prose. Resolution order
+and the single-hop fallback edge: [contract.md](contract.md).
+
+Stop and ask before destructive production, data, merge, deployment, or
+credential operations, even if a worker proposes them.