faberun 0.8.0 → 0.10.0

package/README.md

@@ -2,7 +2,9 @@
 
 <h1 align="center">faberun</h1>
 
-<p align="center">From intent to running software.</p>
+<p align="center"><strong>From intent to running software.</strong></p>
+
+<p align="center">Graph engineering for coding agents.</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>
@@ -10,21 +12,162 @@
   <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 a graph-engineering runtime for building software with coding agents.
+It sits above the models and the harnesses and turns an implementation plan into
+a durable graph of tasks, dependencies, workers, proofs, reviews, retries and
+integration gates.
+
+Harnesses are execution environments: Claude Code, Codex, the Gemini, DeepSeek
+and GLM shells, and a generic `exec-jsonl` door for whatever comes next. Models
+are the engines inside them. Faberun owns the graph, the state and the
+definition of done around both.
+
+The goal is not to make a group of agents talk to each other. It is to use the
+right model for each kind of work, keep the process independent of any single
+model or harness, and require evidence before software counts as done.
+
+## Why Faberun
+
+Coding agents are already very good at changing repositories. The remaining
+problem is everything around that execution.
+
+A frontier model earns its cost when it reasons about architecture, challenges a
+design, writes a specification or reviews a difficult decision. The same model
+is usually unnecessary for a small, well-defined implementation task a much
+cheaper one performs well. Without an orchestration layer, though, the model
+driving the current session becomes the model doing everything.
+
+Faberun separates those concerns. One campaign can use a frontier model to
+reason about the problem and author a plan, a second strong model to attack that
+plan, lower-cost models to execute well-defined implementation nodes, a model
+from another vendor to judge the work that genuinely needs judgment, and plain
+deterministic commands wherever no model is needed at all. The expensive
+intelligence goes where it matters, and the rest becomes an execution problem.
+
+It also takes the campaign out of the lifetime of one chat. The work has durable
+state on disk, so Claude Code can start a campaign and Codex, DeepSeek, GLM or
+any other adapted harness can continue it later without reconstructing the
+process from a conversation history.
+
+## Graph engineering
 
-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.
+Faberun treats development as an executable graph rather than a long
+conversation.
 
-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.
+```text
+intent
+  └─ campaign
+       └─ contract
+            ├─ node A ── proof ── review ──┐
+            ├─ node B ── proof ── review ──┼── integration ── promotion
+            └─ node C ── proof ── review ──┘
+```
+
+A campaign carries the durable intent. A contract turns part of that intent into
+a schema-versioned DAG. Each node carries a closed packet: what the worker may
+read, what it may change, what done means, and how that claim has to be proven.
+The graph decides what can run, what must wait, what may retry, what needs a
+human and what is allowed to advance. The models are replaceable participants
+inside it. The graph remains.
+
+## What is different
+
+### Use the right model for the job
+
+A runtime is one harness running one model. Workers, judges and planning
+sessions need not share a provider or a capability tier, so high-cost reasoning
+and low-cost execution live in the same campaign instead of one model owning the
+whole process. Changing providers is a routing decision, not a rewrite of the
+workflow.
+
+### Proof before opinion
+
+A worker saying "done" is not evidence that it is. Every definition-of-done item
+declares how it can be proven: a command that must succeed, a path that must
+exist, or — only when the criterion cannot be mechanised — the judgment of a
+judge. Mechanical verification always runs first, and a node whose proofs are
+all mechanical settles without spending a token on review. A gate may also
+declare `skipWhen`, so a change that is green and small enough skips the judge
+by policy rather than by accident.
+
+### Independent review
+
+When judgment is required, the worker does not grade itself. Validation refuses
+a gated node whose worker and judge resolve to the same vendor. The judge reads
+the recorded result and its evidence, never the reasoning that produced it, and
+never re-runs the work. The point is not to make two agents agree; it is to keep
+implementation and acceptance as separate responsibilities.
+
+### Isolated execution
+
+Each attempt runs in its own git worktree, so independent nodes run at the same
+time without sharing a mutable working tree, and accepted work reaches the
+repository through controlled refs instead of being copied into the operator's
+checkout. The operator keeps working while the campaign runs.
+
+### Durable campaigns
+
+A run is not tied to the terminal that launched it. The controller runs
+detached, state is persisted under `.runs/`, `supervise` resumes a controller
+that died, and a campaign carries its intent across many runs and sessions. If a
+provider goes down or a harness session ends, the work does not have to be
+re-authored.
+
+### Safe integration
+
+Passing a worker's own checks is not the end of the process. An accepted attempt
+is sealed, integrated onto the run ref and verified again in the candidate
+state, and the phase-terminal node runs the contract's final verification. If
+combining individually valid changes breaks the system, the campaign does not
+promote them.
+
+### Measurable model economics
+
+Every invocation records its usage, routing and outcome, and a closed campaign
+keeps that ledger in its own record under `docs/campaigns/<id>/ledger/`. It makes
+questions like these measurable instead of anecdotal: which model handles this
+class of task reliably, where a frontier model is actually worth its price,
+which nodes close mechanically with no judge at all, how many revisions a worker
+needs before acceptance, what one closed checkpoint costs, and how often a
+fallback saves a campaign. The objective is not to spend less. It is to know
+where expensive intelligence creates value.
+
+## Campaigns, not synthetic teams
+
+Faberun does not model an agent process as a human organisation. It needs no "AI
+architect", "AI developer", "AI QA engineer" and "AI product manager" merely
+because human teams carry those titles: models are general enough that those
+boundaries are mostly artificial. The roles it does define are the ones that
+stay useful for agents.
+
+| role | responsibility |
+| --- | --- |
+| worker | produces a result inside its packet. |
+| judge | decides independently whether a result that needs judgment satisfies its contract. |
+| controller | advances the graph deterministically. |
+| operator | supplies the intent and intervenes when a decision genuinely needs a human. |
+
+Everything else belongs in the contract.
+
+## From spec to contract
+
+Planning is part of the product, and it is adversarial on purpose. `faberun spec
+validate` checks a specification's front matter, its `R<n>` requirements and the
+proof each one declares, and invokes no model to do it. `faberun plan` then runs
+the debate in budgeted, isolated runs: an author drafts, a reviewer from another
+vendor attacks the draft holding only the spec, the repository facts and the
+plan under review, and a revision round follows while a critical finding
+remains. A converged draft is sized, routed and frozen into a contract. Freezing
+never launches, and a plan that never converges ends `contested`, with its open
+findings recorded as a campaign question instead of a contract.
+
+None of it is mandatory. The traceability rules are advisory unless you ask for
+`--strict-traceability`, a document with no front matter validates as `legacy`
+rather than being rejected, and you can skip planning altogether and author the
+contract by hand. What Faberun needs is the executable part of the plan:
+objective, nodes, dependencies, read and write scope, definitions of done,
+verification, runtime policy and integration behaviour. Your specification
+process stays yours.
 
 ## Install
 
@@ -92,29 +235,35 @@ 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.
+names. Faberun then judges the result in stages, and a free slot dispatches the
+next node while another one is still being verified.
 
 ```text
-intent
-  └─ contract: validate · preflight
-       └─ controller
-            ├─ worker attempt in an attempt worktree
-            │     └─ deterministic verification · cross-vendor judge
-            └─ integration ref · promotion · landing branch
+packet
+  └─ worker attempt in its own worktree
+       └─ mechanical proof ── failure ─→ retry · route · attention
+            └─ judge, when required ── rejection ─→ revision
+                 └─ seal ─→ integration ref ─→ candidate verification
+                      └─ promotion onto the campaign's landing branch
 ```
 
-The vocabulary is in [Concepts](docs/CONCEPTS.md), and the layers, process
-model and gates are in [Architecture](docs/ARCHITECTURE.md).
+A judge reviews recorded evidence rather than re-running arbitrary work. A
+passing attempt is sealed and integrated onto the run ref, a campaign promotes
+each finished 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.
 
-## Harnesses
+The vocabulary is in [Concepts](docs/CONCEPTS.md), and the layers, process model
+and gates are in [Architecture](docs/ARCHITECTURE.md).
 
-A runtime is one harness running one model. Any runtime can be a worker, and a
-judge of another vendor reviews what it produced.
+## Harnesses and models
+
+Faberun keeps three things apart. A **model** is the reasoning engine, a
+**harness** is the environment that gives a model access to code and tools, and
+a **runtime** is one configured harness-and-model pair Faberun can dispatch. Any
+runtime can act as a worker or as a judge, according to the contract and the
+routing policy.
 
 | Harness | Default vendor | Example model |
 | --- | --- | --- |
@@ -126,6 +275,19 @@ judge of another vendor reviews what it produced.
 | `exec-jsonl` | declared per runtime | the model its command names |
 | `replay` | declared per runtime | the recorded model |
 
+Harness and model support are adapter concerns. The orchestration above them
+depends on no single vendor.
+
+## Philosophy
+
+Software should be built, not merely generated. Generating plausible code is
+becoming cheap; the valuable part is the system around the generation —
+preserving intent, decomposing work, choosing the appropriate intelligence,
+isolating effects, proving outcomes, recovering from failure, and recording why a
+change was accepted. A craftsman does not depend on one hammer, and Faberun does
+not depend on one model. Models change, harnesses change, providers change. The
+intent, the graph, the evidence and the finished work remain.
+
 ## Documentation
 
 - [Documentation map](docs/README.md): every document and the question it answers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.8.0",
+  "version": "0.10.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": {

package/src/campaign/chain.mjs

@@ -290,6 +290,25 @@ export function validateContractAgainstRef(raw, contractPath, context = {}) {
   }
 }
 
+/**
+ * Validate a contract for a launch, the one path the CLI's `run` command and
+ * the scheduler's own re-validation both go through: against `baseRef` when
+ * one is given, the checkout otherwise. `repo` defaults to the contract's own
+ * `cwd` when the caller does not know a better one (the campaign chain always
+ * passes its own), since a contract's `cwd` is always inside the repo it
+ * names.
+ *
+ * @param {Record<string, unknown>} raw
+ * @param {string} contractPath
+ * @param {{repo?: string, baseRef?: string}} [context]
+ * @returns {ValidatedContract}
+ */
+export function validateContractForLaunch(raw, contractPath, context = {}) {
+  if (!context.baseRef) return validateContract(raw, contractPath);
+  const repo = context.repo ?? resolve(dirname(contractPath), typeof raw.cwd === "string" ? raw.cwd : ".");
+  return validateContractAgainstRef(raw, contractPath, { repo, baseRef: context.baseRef });
+}
+
 /**
  * Reduce a run's progress to the one decision the chain makes. An in-flight run
  * is `unfinished` even though `reduceRunOutcome` already names its running nodes

package/src/campaign/journal.mjs

@@ -11,6 +11,7 @@ import { JOURNAL_FILE, JOURNAL_TEXT_BYTES, JOURNAL_WATCH_CURSOR_DIR, JOURNAL_WAT
 import { boundedText, collapseLines } from "../util.mjs";
 import { campaignIdOf } from "./record.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname, isAbsolute, join } from "node:path";
 import { requireText, requireTimestamp } from "../contract/assert.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
@@ -34,6 +35,7 @@ const JOURNAL_TYPES = new Set([
   "question.resolved",
   "retrospective",
   "liveness",
+  "seat.allowance",
 ]);
 const SESSION_REQUIRED_TYPES = new Set([
   "session.attached",
@@ -63,7 +65,9 @@ const ENTRY_SHAPES = {
   "question.resolved": ["at", "type", "eventId", "sessionId", "questionId", "text"],
   retrospective: ["at", "type", "eventId", "sessionId", "text"],
   liveness: ["at", "type", "eventId", "campaignId", "runId", "nodeId", "phase", "checkpointsDone", "checkpointsTotal", "runtime", "state", "lastProgressAt", "attention"],
+  "seat.allowance": ["at", "type", "eventId", "sample", "harness", "remaining", "limit", "resetsAt", "delta", "window"],
 };
+const SEAT_ALLOWANCE_SAMPLES = new Set(["start", "freeze"]);
 /**
  * Fields a liveness fact carried before the budget ceiling was removed. A
  * historical journal (like the live campaign's own) still has lines shaped
@@ -272,6 +276,7 @@ export function validateJournalEntry(entry) {
   // rejects an unexpected key; no deeper shape validation is needed for a type
   // nothing produces.
   if (type === "liveness") return;
+  if (type === "seat.allowance") return validateSeatAllowanceEntry(record);
   if (type === "session.attached") return validateSessionEntry(record);
   if (type === "run.registered") {
     requireText(record.runId, "entry.runId");
@@ -293,6 +298,49 @@ export function validateJournalEntry(entry) {
   }
   if (type === "outcome" && record.runId !== undefined) requireText(record.runId, "entry.runId");
 }
+/**
+ * @param {JsonObject} entry
+ */
+function validateSeatAllowanceEntry(entry) {
+  if (!SEAT_ALLOWANCE_SAMPLES.has(/** @type {string} */ (entry.sample))) {
+    throw new TypeError("seat.allowance sample must be start or freeze");
+  }
+  if (entry.harness !== null && typeof entry.harness !== "string") {
+    throw new TypeError("seat.allowance harness must be null or a string");
+  }
+  for (const field of ["remaining", "limit", "delta"]) {
+    if (entry[field] !== null && typeof entry[field] !== "number") {
+      throw new TypeError(`seat.allowance ${field} must be null or a number`);
+    }
+  }
+  if (entry.resetsAt !== null && typeof entry.resetsAt !== "string") {
+    throw new TypeError("seat.allowance resetsAt must be null or a string");
+  }
+  // Optional: a historical entry, and every call site not yet updated to
+  // sample it, carries no window at all.
+  if (entry.window !== undefined && entry.window !== null && typeof entry.window !== "string") {
+    throw new TypeError("seat.allowance window must be null or a string");
+  }
+}
+/**
+ * The one writer of `seat.allowance`: `campaign init` calls it for the
+ * `start` sample, `plan freeze` for the `freeze` sample. Kept as a single
+ * function, rather than two call sites building the literal themselves, so
+ * the field-ownership ratchet does not grow by one for every field this event
+ * carries.
+ *
+ * @param {string} campaignPath
+ * @param {{sample: "start"|"freeze", harness: string|null, remaining: number|null, limit: number|null, resetsAt: string|null, delta: number|null, window?: string|null}} allowance
+ * @returns {{entry: JournalEntry, deduplicated: boolean}}
+ */
+export function appendSeatAllowanceEvent(campaignPath, allowance) {
+  return appendJournal(campaignPath, {
+    type: "seat.allowance",
+    eventId: randomUUID(),
+    at: new Date().toISOString(),
+    ...allowance,
+  });
+}
 /**
  * @param {JsonObject} entry
  */

package/src/cli/brand.mjs

@@ -197,6 +197,7 @@ export function renderUsage() {
     "contract validate <contract.json>",
     "spec validate <file> [--strict-traceability] [--json]",
     "spec scaffold <path> [--id <id>]",
+    "plan <spec.md> --campaign <id> [--phase <phase>] [--review-rounds <n>] [--approve-below standard|high|none] [--runtime-defaults worker=<id>,judge=<id>] [--detach] [--json]",
     "metrics <campaign-id> [--cwd <dir>] [--json]",
     "campaign <init|watch|attach|note|resolve|close|supervise|show|list|sync|ack> ...",
     "seat <start|attach|status|stop> [<campaign-id>] [--cwd <dir>] ...",

package/src/cli/campaign.mjs

@@ -12,12 +12,14 @@ import {
 } from "../campaign/index.mjs";
 import { lockStale, pidAlive, processStartToken, readLock } from "../run/lock.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
-import { acknowledgeJournalEvent, appendJournal, readJournal, watchJournal } from "../campaign/journal.mjs";
+import { acknowledgeJournalEvent, appendJournal, appendSeatAllowanceEvent, readJournal, watchJournal } from "../campaign/journal.mjs";
 import { driveCampaignChain } from "../campaign/chain.mjs";
 import { unparkCampaign } from "../campaign/unpark.mjs";
 import { readCampaign } from "../campaign/record.mjs";
 import { notifyQueueFor } from "../engine/notify-queue.mjs";
 import { appendInbox, readInbox, wakeCapabilityNotice } from "../notify/index.mjs";
+import { allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
+import { detectOperatorHarness } from "../seat/harnesses.mjs";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
 import { errorCode, readJsonTolerant } from "../util.mjs";
 
@@ -326,12 +328,23 @@ function watchLockStale(occupant) {
  * @param {string} campaignId
  * @param {CliValues} values
  */
-function init(campaignId, values) {
+async function init(campaignId, values) {
   const cwd = resolve(values.cwd ?? ".");
   const runsDir = join(cwd, ".runs");
   const goal = textValue(values.goal, "--goal");
   const contracts = contractManifest(values.contract);
   const created = initializeCampaign(runsDir, { campaignId, goal, contracts, landBranch: values.landBranch });
+  // The operator's own seat: whichever harness this CLI is running inside
+  // (env-marker detection, see seat/harnesses.mjs), the only harness whose
+  // allowance is meaningful at a point before any node runtime exists.
+  const harness = detectOperatorHarness();
+  const allowance = await sampleAllowance({ harness });
+  appendSeatAllowanceEvent(created.path, {
+    sample: "start",
+    harness,
+    delta: null,
+    ...allowanceEventFields(allowance),
+  });
   renderHandoff(created.path, runsDir);
   process.stdout.write(`[campaign] ${campaignId} initialized · ${created.path} · landBranch ${created.campaign.landBranch} · ${created.campaign.contracts.length} contract(s)\n`);
   if (syncAgentSignal(runsDir)) process.stdout.write(`[campaign] AGENTS.md signal updated\n`);

package/src/cli/plan.mjs

@@ -0,0 +1,142 @@
+/**
+ * `plan` argv: run the planning pipeline as successive ordinary runs (draft,
+ * review, revise up to a round budget) and freeze the result, or park it
+ * contested. This file only owns the wire — `src/plan/pipeline.mjs` owns the
+ * sequencing and every decision the pipeline makes.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
+import { classifyRunProgress } from "../campaign/chain.mjs";
+import { runProgress } from "../engine/supervise.mjs";
+import { DISCOVERY_RUNTIME_DEFINITIONS } from "../engine/runtime-discovery.mjs";
+import { validateRuntime } from "../contract/runtime.mjs";
+import { delay } from "../util.mjs";
+import { runPlanningPipeline } from "../plan/pipeline.mjs";
+
+/** How often a foreground `plan` polls a launched stage's run directory. */
+const DEFAULT_POLL_MS = 1_000;
+
+/**
+ * `--runtime-defaults worker=<id>,judge=<id>`, either key optional, comma
+ * separated. Absent entirely, the pipeline falls through to plain
+ * availability discovery for every node.
+ *
+ * @param {string|undefined} value
+ * @returns {{worker?: string, judge?: string}}
+ */
+export function parseRuntimeDefaults(value) {
+  /** @type {{worker?: string, judge?: string}} */
+  const result = {};
+  if (value === undefined) return result;
+  for (const pair of value.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) throw new Error(`--runtime-defaults entries must be worker=<id> or judge=<id>: ${pair}`);
+    const role = pair.slice(0, eq).trim();
+    const id = pair.slice(eq + 1).trim();
+    if (role !== "worker" && role !== "judge") throw new Error(`--runtime-defaults role must be worker or judge: ${role}`);
+    if (!id) throw new Error(`--runtime-defaults ${role} needs a runtime id`);
+    result[role] = id;
+  }
+  return result;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+function reviewRoundsOf(value) {
+  if (value === undefined) return 2;
+  const rounds = Number(value);
+  if (!Number.isInteger(rounds) || rounds < 1) throw new Error(`--review-rounds must be a positive integer: ${String(value)}`);
+  return rounds;
+}
+
+/**
+ * A `--runtimes <path>` catalogue: a JSON object in the same shape a
+ * contract's own `runtimes` field takes, validated entry-by-entry with the
+ * same validator `validateContract` uses, so a malformed catalogue is
+ * rejected before any planning stage launches rather than surfacing as an
+ * opaque failure deep inside the pipeline.
+ *
+ * @param {string} path
+ * @returns {Record<string, import("../contract/index.mjs").ValidatedRuntime>}
+ */
+export function loadRuntimesCatalogue(path) {
+  const resolved = resolve(path);
+  /** @type {unknown} */
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(resolved, "utf8"));
+  } catch (error) {
+    throw new Error(`--runtimes ${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`--runtimes ${path} must be a JSON object`);
+  /** @type {Record<string, import("../contract/index.mjs").ValidatedRuntime>} */
+  const runtimes = {};
+  for (const [id, runtime] of Object.entries(raw)) runtimes[id] = validateRuntime(id, runtime);
+  return runtimes;
+}
+
+/**
+ * @param {string} target
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, detach?: boolean, json?: boolean}} values
+ * @returns {Promise<void>}
+ */
+export async function planCli(target, values) {
+  const specPath = resolve(target);
+  if (typeof values.campaign !== "string" || !values.campaign) throw new Error("plan requires --campaign <id>");
+  const campaignId = values.campaign;
+  const phase = typeof values.phase === "string" && values.phase ? values.phase : "default";
+  const reviewRounds = reviewRoundsOf(values["review-rounds"]);
+  const approveBelow = /** @type {"standard"|"high"|"none"|undefined} */ (values["approve-below"]);
+  const runtimeDefaults = parseRuntimeDefaults(values["runtime-defaults"]);
+  const runtimes = typeof values.runtimes === "string" && values.runtimes
+    ? loadRuntimesCatalogue(values.runtimes)
+    : DISCOVERY_RUNTIME_DEFINITIONS;
+
+  if (values.detach === true) {
+    const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
+    if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);
+    if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
+    if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
+    const child = detachArgv(argv);
+    if (child.pid === undefined) throw new Error("detached plan has no pid");
+    process.stdout.write(`[plan] detached · pid ${child.pid} · ${specPath}\n`);
+    return;
+  }
+
+  const result = await runPlanningPipeline({
+    specPath,
+    campaignId,
+    phase,
+    reviewRounds,
+    approveBelow,
+    runtimeDefaults,
+    runtimes,
+    launch: async (contractPath, contract) => {
+      const child = detachSelf("run", contractPath);
+      if (child.pid === undefined) throw new Error("detached planning run has no pid");
+      await waitForBootstrap(join(contract.cwd, ".runs", contract.id), child.pid, child);
+    },
+    wait: async (runDir) => {
+      for (;;) {
+        const progress = runProgress(runDir);
+        const classification = classifyRunProgress(progress);
+        if (classification !== "unfinished" && classification !== "waiting") return progress;
+        await delay(DEFAULT_POLL_MS);
+      }
+    },
+  });
+
+  if (values.json === true) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (result.status === "contested") {
+    process.stdout.write(`[plan] ${campaignId} phase ${phase} contested after ${result.round} round(s) · ${result.findings.length} finding(s) · ${result.planPath}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`[plan] ${campaignId} phase ${phase} frozen · approved ${result.approved} · ${result.contractPath}\n`);
+}

package/src/cli.mjs

@@ -24,6 +24,7 @@ import {
   validBootstrapNonce,
 } from "./run/lock.mjs";
 import { renderRunHandoff } from "./campaign/index.mjs";
+import { validateContractForLaunch } from "./campaign/chain.mjs";
 import { campaignCli } from "./cli/campaign.mjs";
 import { seatCli } from "./cli/seat.mjs";
 import { initCommand } from "./cli/init.mjs";
@@ -32,6 +33,7 @@ import { skillsCli } from "./cli/skills.mjs";
 import { updateCommand } from "./cli/update.mjs";
 import { contractCli, validateContractFile } from "./cli/contract.mjs";
 import { specCli } from "./cli/spec.mjs";
+import { planCli } from "./cli/plan.mjs";
 import { METRICS_OPTIONS, renderCampaignMetrics } from "./campaign/metrics.mjs";
 import { runContract } from "./engine/scheduler.mjs";
 import { resumeRun } from "./engine/resume.mjs";
@@ -106,6 +108,16 @@ export const COMMAND_OPTIONS = {
   setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
+  plan: {
+    campaign: { type: "string" },
+    phase: { type: "string" },
+    "review-rounds": { type: "string" },
+    "approve-below": { type: "string" },
+    "runtime-defaults": { type: "string" },
+    runtimes: { type: "string" },
+    detach: { type: "boolean" },
+    json: { type: "boolean" },
+  },
 };
 
 /**
@@ -280,9 +292,9 @@ async function main(argv) {
   if (command === "run") {
     warnIfNoTransport();
     const absolute = resolve(target);
-    const contract = validateContract(JSON.parse(readFileSync(absolute, "utf8")), absolute);
-    const runDir = join(contract.cwd, ".runs", contract.id);
     const baseRef = typeof values["base-ref"] === "string" && values["base-ref"] ? values["base-ref"] : undefined;
+    const contract = validateContractForLaunch(JSON.parse(readFileSync(absolute, "utf8")), absolute, { baseRef });
+    const runDir = join(contract.cwd, ".runs", contract.id);
     setLaunchBaseRef(baseRef);
     // The base is what every worktree is cut from; a dirty tree only blocks
     // when the cwd HEAD *is* that base. A `--base-ref` elsewhere leaves the
@@ -303,7 +315,7 @@ async function main(argv) {
       return;
     }
     for (const warning of [...contract.warnings, ...reusedDoneWarnings(contract)]) process.stdout.write(`${advisoryToken()} ${warning}\n`);
-    const result = await runContract(target, { detachedBootstrap: hasDetachedBootstrapNonce() });
+    const result = await runContract(target, { detachedBootstrap: hasDetachedBootstrapNonce(), baseRef });
     if (!result.ok) process.exitCode = 1;
     return;
   }
@@ -421,6 +433,10 @@ async function main(argv) {
   }
   if (command === "metrics") { process.stdout.write(renderCampaignMetrics(target, values)); return; }
   if (command === "findings") { process.stdout.write(renderFindings(resolve(target))); return; }
+  if (command === "plan") {
+    await planCli(target, /** @type {Parameters<typeof planCli>[1]} */ (values));
+    return;
+  }
   if (command === "validate") { validateContractFile(resolve(target)); return; }
   usage();
 }