faberun 0.27.0 → 0.29.0

package/README.md

@@ -108,8 +108,9 @@ 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
+detached, state is persisted under the project's runs directory in
+`$FABERUN_HOME` (default `~/.faberun`), `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.
 
@@ -218,6 +219,11 @@ An installed copy updates itself from the newest GitHub release:
 faberun update
 ```
 
+To leave cleanly, `faberun uninstall --dry-run` lists what the install wrote
+outside a repository — registered skills, status-line and hook entries, and
+`$FABERUN_HOME` — and `faberun uninstall` removes it after confirming, refusing
+while a campaign's ledger is not preserved at its repository unless `--force`.
+
 ## Quickstart
 
 The full walkthrough, from a fresh machine to a first verified node, is in
@@ -226,7 +232,7 @@ The full walkthrough, from a fresh machine to a first verified node, is in
 | 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. |
+| 2 | `faberun init` | Prepares a repository: confirms a git work tree, ignores the legacy in-tree runs directory, 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.27.0",
+  "version": "0.29.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/skills/faberun/SKILL.md

@@ -16,11 +16,11 @@ Read [rules](references/rules.md) first.
 | Dispatch a node | [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) |
+| Install, set up, update, uninstall | [operations](references/operations.md) |
+| Doctor --env | [local-env](references/local-env.md) |
 
-Watchdog re-invocations:
+Watchdog:
 
-    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

@@ -187,17 +187,15 @@ 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. Each adapter
-also declares `signalsProcesses` (`true`, `false`, or `null` when unmeasured):
+`permissionExecution`: `claude` `bypassPermissions` (default `acceptEdits`),
+`zcode` `yolo` (also default), `dsh` both its default `workspace-write` and
+`danger-full-access`; every `codex` sandbox mode executes, and
+`agy`/`exec-jsonl`/`replay` expose no denying mode. Each adapter
+also declares `signalsProcesses` (`true`, `false`, or unmeasured `null`):
 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.
+`true`. Judge modes are excluded: they review captured results.
 
 - `claude`: `permissionMode` (a node that runs commands needs
   `bypassPermissions`, or the worker can only return `blocked_context`).
@@ -237,7 +235,9 @@ are excluded because judges review captured results.
   (`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_PERMISSION_MODE`, default `workspace-write`: a toolchain cache outside
+  the worktree gets `ReadOnlyFileSystem`, so compiling needs
+  `danger-full-access`. 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

package/skills/faberun/references/local-env.md

@@ -0,0 +1,11 @@
+# Local environment
+
+A worker or judge process gets only the environment it is allowed — the base
+set (`PATH`, `HOME`, `USER`, `SHELL`, `LANG`, `LC_*`, `TERM`, `TMPDIR`, `TZ`,
+plus the Windows names), the names a harness adapter declares, its runtimes'
+`env_key` names and any `envPassthrough` — while this phase's
+definition-of-done commands and `finalVerification` keep today's environment.
+
+`faberun doctor --env [<contract.json>]` lists, per runtime, the names that
+would pass and the names excluded, never the values; a credential-shaped
+exclusion is marked retained.

package/skills/faberun/references/operations.md

@@ -9,17 +9,11 @@ source `gitHead`. Every worker attempt gets a linked worktree at
 `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.
+the home of run/control artifacts.
 
 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.
+attempt from that sha (`worktree.previousAttempt`).
 
 ## Integration transaction
 
@@ -36,9 +30,8 @@ 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.
+unfinished transaction and complete it idempotently; a re-dispatch follows the
+same continuation rule as any other retry.
 
 ## Controller lock and takeover
 
@@ -50,17 +43,16 @@ otherwise it exits `controller_active`, untouched. Takeover renames the lock
 aside and re-checks it is stale before installing its own. 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.
+`SIGKILL`) every invocation recorded for a `running` node —
+unless still inside its deadline, when it is adopted and its result read.
 `cancel` signals a live controller first, so its takeover never waits.
+`resume --reauthor <node-id>` re-widens a refused packet under a hard round
+budget.
 
-`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. A detached controller outlives its launcher,
-not the session scope (cgroup) holding it: run long work under `tmux`,
-`systemd-run` or the seat.
+`supervise <run-dir> [--detach] [--interval <sec>]` is the watchdog;
+it holds no lock and writes no state. A detached controller outlives its
+launcher, not the session scope (cgroup) holding it: run long work under
+`tmux`, `systemd-run` or the seat.
 
 ## Runtime discovery
 
@@ -101,7 +93,7 @@ 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:
+Writes shell out to the runner CLI:
 `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:
@@ -110,7 +102,7 @@ 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 one
-message from persisted state, in the operator's own language (detected from
+message from persisted state, in the operator's language (from
 the campaign goal, journal notes and node objectives, or `FABERUN_NOTIFY_LANG`;
 English otherwise). Only `run.terminal`, `attention` and `advisory` leave by
 default -- a phase settling and a person being needed -- while a node settling
@@ -118,31 +110,31 @@ gets a `filtered` receipt; `FABERUN_NOTIFY_EVENTS` widens or narrows the list:
 line one is the outcome (`✅ <node> · done in 8m · $0.09`, `🏁 run 15 · <name>
 · 2/2 done`, or `👀 <node> needs you · <error>`), then asked / done / proof
 for a node, what every node delivered for a run, or why / asked / do for
-attention, then a progress bar, a rule and the `🐦 faberun` signature with
-campaign percent, cost and elapsed; an `⬆️` line names a newer release when
+attention, then a progress bar, a rule and the `🐦 faberun` signature (campaign
+percent, cost, elapsed); an `⬆️` line names a newer release when
 the cached update check has one. ≤2 KiB. It delivers that
-same text to every bound transport at once, appending one receipt
-(`delivered`, `failed`, `no_transport`, one entry per transport) to
+text to every bound transport at once, appending one receipt
+(`delivered`, `failed`, `no_transport`, per transport) to
 `<run-dir>/notify.jsonl`. Delivery is lossy: **exactly one attempt**, no retry,
 no backoff. `FABERUN_NOTIFY_BIN` names an executable called with the event as
 JSON on stdin (`os-macos` selects the bundled `osascript` adapter); it pushes to
 a person, `canWake: false`. `FABERUN_NOTIFY_SESSION` wakes harness sessions,
 `canWake: true`: `auto` is the Claude Code inbox and Codex thread the
 environment names; `claude:<socket>` adds another session's inbox, so the
-operator's own interactive session hears a run a background session launched
-(`echo $CLAUDE_CODE_MESSAGING_SOCKET` in that session gives the path). A seat
-window sets `auto`; nothing else does, so a test suite never wakes a session.
+operator's own session hears a background run
+(`echo $CLAUDE_CODE_MESSAGING_SOCKET` in that session gives the path). Only a seat
+window sets `auto`, so a test suite never wakes a session.
 **On an inbound `🐦 faberun` message**: repeat it to the operator verbatim,
-then one line on what you do next -- the message exists to inform the person,
-not you, and it reaches them only through your reply; `👀`, act on the `do`
+then one line on what you do next -- it informs the person, not
+you, and reaches them only through your reply; `👀`, act on the `do`
 command it names. 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 both variables are empty, and `--wake` names what will wake.
+launch warn when both are empty, and `--wake` names what will wake.
 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.
+`dedupeKey` 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.
@@ -207,3 +199,4 @@ binary is absent, and only reattaching is lost.
 `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.
+`faberun uninstall [--dry-run]` removes what faberun wrote outside a target repository and `$FABERUN_HOME`; an unpreserved ledger refuses unless `--force`.

package/src/campaign/brief.mjs

@@ -17,12 +17,13 @@ import { boundedText, compactCost, compactTokens, finite, readJsonTolerant } fro
 import { join } from "node:path";
 import { readCampaign } from "./record.mjs";
 import { readProjectionState } from "./projection.mjs";
+import { listNodeSnapshots, nodeSnapshotPath } from "../run/node-store.mjs";
 import { writeTextAtomic } from "../run/store.mjs";
 
 /** @typedef {import("./index.mjs").Campaign} Campaign */
 /** @typedef {import("./index.mjs").JournalEntry} JournalEntry */
 /** @typedef {import("./index.mjs").Projection} Projection */
-/** @typedef {{id: string, exists: boolean, summary: string, controller: string, phase: string|null, done: number, total: number, costUsd: number|null, inputTokens: number|null, outputTokens: number|null, attention: {id: string, status: string, note: string}[]}} BriefRun */
+/** @typedef {{id: string, exists: boolean, summary: string, controller: string, phase: string|null, judgeIndependence?: string|null, done: number, total: number, costUsd: number|null, inputTokens: number|null, outputTokens: number|null, attention: {id: string, status: string, note: string}[]}} BriefRun */
 /** @typedef {{campaign: Campaign, updatedAt: string, phase: string|null, checkpoints: {done: number, total: number}, runs: BriefRun[], openQuestions: JournalEntry[], transitions: JournalEntry[], budget: {costUsd: number|null, inputTokens: number|null, outputTokens: number|null}, notes: JournalEntry[], commands: string[]}} Brief */
 /** @typedef {{limit: number, used: number, lines: string[]}} BriefBudget */
 
@@ -75,9 +76,11 @@ export function materializeBrief(campaignPath, brief) {
 }
 
 /**
- * Read the campaign's live projection and each linked run's `status.json`, then
+ * Read the campaign's live projection, each linked run's `status.json` and the
+ * effective judge-independence mode recorded on that run's node snapshots, then
  * materialize the brief. `heartbeat.json` does not exist in this tree -- the
- * projection and per-run status are the durable sources.
+ * projection, the per-run status and the persisted node snapshots are the
+ * durable sources.
  *
  * @param {string} campaignPath
  * @param {string} runsDir
@@ -95,16 +98,42 @@ export function renderBrief(campaignPath, runsDir) {
  * @returns {BriefRun[]}
  */
 function readRunBriefs(runsDir, runIds) {
-  return runIds.map((runId) => runBrief(runId, readJsonTolerant(join(runsDir, runId, "status.json"))));
+  return runIds.map((runId) => {
+    const runDir = join(runsDir, runId);
+    return runBrief(runId, readJsonTolerant(join(runDir, "status.json")), recordedJudgeIndependence(runDir));
+  });
+}
+
+/**
+ * The effective judge-independence mode the launch recorded on this run's node
+ * snapshots (`routing.assignments.judgeIndependence`). The launch composes one
+ * mode per contract, so the first node that recorded one answers for the run;
+ * reading it here keeps the brief from re-deriving the mode from the contract,
+ * which cannot see a machine-config opt-in. A run with no persisted node or no
+ * recorded mode has no recorded opt-in (the cross-vendor default).
+ *
+ * @param {string} runDir
+ * @returns {string|null}
+ */
+export function recordedJudgeIndependence(runDir) {
+  for (const name of [...listNodeSnapshots(runDir)].sort()) {
+    const snapshot = readJsonTolerant(nodeSnapshotPath(runDir, name.slice(0, -".json".length)));
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)) continue;
+    const routing = /** @type {Record<string, any>} */ (snapshot).routing;
+    const mode = routing && typeof routing === "object" ? routing.assignments?.judgeIndependence : undefined;
+    if (typeof mode === "string" && mode) return mode;
+  }
+  return null;
 }
 
 /**
  * @param {string} runId
  * @param {unknown} status
+ * @param {string|null} [judgeIndependence] the mode the launch recorded on the run snapshot
  * @returns {BriefRun}
  */
-function runBrief(runId, status) {
-  if (!status || typeof status !== "object" || Array.isArray(status)) return missingRunBrief(runId);
+function runBrief(runId, status, judgeIndependence = null) {
+  if (!status || typeof status !== "object" || Array.isArray(status)) return missingRunBrief(runId, judgeIndependence);
   const record = /** @type {Record<string, any>} */ (status);
   const nodes = Array.isArray(record.nodes) ? record.nodes : [];
   const usage = record.usage && typeof record.usage === "object" ? /** @type {Record<string, unknown>} */ (record.usage) : {};
@@ -122,6 +151,7 @@ function runBrief(runId, status) {
     summary: typeof record.summary === "string" ? record.summary : "",
     controller: typeof record.controller?.state === "string" ? record.controller.state : "none",
     phase,
+    judgeIndependence,
     done: nodes.filter((node) => node.status === "done" || node.status === "no-op").length,
     total: nodes.length,
     costUsd: finite(usage.costUsd),
@@ -139,10 +169,11 @@ function runBrief(runId, status) {
 
 /**
  * @param {string} runId
+ * @param {string|null} [judgeIndependence]
  * @returns {BriefRun}
  */
-function missingRunBrief(runId) {
-  return { id: runId, exists: false, summary: "no status.json yet", controller: "none", phase: null, done: 0, total: 0, costUsd: null, inputTokens: null, outputTokens: null, attention: [] };
+function missingRunBrief(runId, judgeIndependence = null) {
+  return { id: runId, exists: false, summary: "no status.json yet", controller: "none", phase: null, judgeIndependence, done: 0, total: 0, costUsd: null, inputTokens: null, outputTokens: null, attention: [] };
 }
 
 /**
@@ -367,7 +398,8 @@ function runLine(run, cap, idCap) {
   const hidden = run.attention.length - ATTENTION_LINE_LIMIT;
   if (hidden > 0) attention.push(`${hidden} more`);
   const detail = attention.length ? ` · ${attention.join("; ")}` : "";
-  return `- ${id}: ${boundedText(run.summary, cap)} · checkpoints ${run.done}/${run.total} · controller ${boundedText(run.controller, cap)}${detail}`;
+  const independence = run.judgeIndependence ? ` · judge independence ${boundedText(run.judgeIndependence, cap)}` : "";
+  return `- ${id}: ${boundedText(run.summary, cap)} · checkpoints ${run.done}/${run.total} · controller ${boundedText(run.controller, cap)}${independence}${detail}`;
 }
 
 /**

package/src/campaign/campaign-brief.mjs

@@ -51,7 +51,7 @@ import { projectCampaignDecisions } from "./projection.mjs";
 /** @typedef {{risk: string, impact: string, mitigation: string}} BriefRisk */
 /** @typedef {{intent: string|null, expectedOutcome: string|null, successCriteria: BriefSuccessCriterion[], humanFacts: string[], calculatedFacts: string[], gaps: string[]}} BriefOpening */
 /** @typedef {{human: string[], delegated: string[], journal: ProjectedDecision[], risks: BriefRisk[], evals: string[], gaps: string[]}} BriefDecisions */
-/** @typedef {{campaign: string, specBaseline: string|null, specDigest: string, specPath: string, targetGitHead: string|null, planPath: string, planDigest: string, contractDigest: string, journalCursor: number, usageSampleCutoff: string|null}} BriefIdentity */
+/** @typedef {{campaign: string, specBaseline: string|null, specDigest: string, specPath: string, targetGitHead: string|null, planPath: string, planDigest: string, contractDigest: string, judgeIndependence?: string|null, journalCursor: number, usageSampleCutoff: string|null}} BriefIdentity */
 /** @typedef {{identity: BriefIdentity, opening: BriefOpening, coverage: BriefCoverage, graph: BriefGraph, decisions: BriefDecisions, estimate: BriefEstimate, decisionState: BriefDecisionState}} BriefModel */
 
 /**
@@ -71,6 +71,7 @@ import { projectCampaignDecisions } from "./projection.mjs";
  * @property {string|null} [usageSampleCutoff]
  * @property {Projection} [projection]
  * @property {BriefEstimateInput} [estimate]
+ * @property {string|null} [effectiveJudgeIndependence] the mode the launch recorded on the run snapshot; `undefined` falls back to the contract's own declaration.
  */
 
 const SAMPLE_FLOOR = 5;
@@ -152,7 +153,19 @@ export function buildBriefModel(options) {
   const contractNodes = asArray(contract.nodes);
   const declarations = normalizeDeclarations(plan.phases);
   const coverage = buildCoverage(parsedSpec, declarations, contractNodes, specPath, planPath);
-  const graph = buildGraph(contract, contractNodes);
+  // R36: the effective judge-independence mode the launch recorded on the run
+  // snapshot wins over the contract's own declaration, which never sees the
+  // machine config's opt-in. With no recorded value the contract remains the
+  // only source, exactly as before.
+  const judgeIndependence = options.effectiveJudgeIndependence === "same-vendor"
+    ? "same-vendor"
+    : options.effectiveJudgeIndependence !== undefined
+      ? null
+      : contract.judgeIndependence === "same-vendor" ? "same-vendor" : null;
+  const graphContract = { ...contract };
+  if (judgeIndependence === "same-vendor") graphContract.judgeIndependence = "same-vendor";
+  else delete graphContract.judgeIndependence;
+  const graph = buildGraph(graphContract, contractNodes);
   const journalDecisions = options.projection ? projectCampaignDecisions(options.projection) : [];
   // R16: an operator step the frozen plan carries as an explicit stop
   // (`plan.humanSteps`, `src/plan/human-step.mjs`) is a human decision the
@@ -170,6 +183,7 @@ export function buildBriefModel(options) {
     contractDigest: expectedContractDigest,
     specPath,
     specBaseline: typeof parsedSpec.frontMatter?.baseline === "string" ? parsedSpec.frontMatter.baseline : null,
+    judgeIndependence,
     journalCursor: options.journalCursor ?? 0,
     usageSampleCutoff: options.usageSampleCutoff ?? null,
   });
@@ -576,7 +590,7 @@ function buildOpening(parsedSpec, coverage, graph, estimate, decisions) {
 }
 
 /**
- * @param {{campaign: string, plan: AnyRecord, planPath: string, planDigest: string, contractDigest: string, specPath: string, specBaseline: string|null, journalCursor: number, usageSampleCutoff: string|null}} input
+ * @param {{campaign: string, plan: AnyRecord, planPath: string, planDigest: string, contractDigest: string, specPath: string, specBaseline: string|null, judgeIndependence: string|null, journalCursor: number, usageSampleCutoff: string|null}} input
  * @returns {BriefIdentity}
  */
 function buildIdentity(input) {
@@ -590,6 +604,7 @@ function buildIdentity(input) {
     planPath: input.planPath,
     planDigest: input.planDigest,
     contractDigest: input.contractDigest,
+    judgeIndependence: input.judgeIndependence,
     journalCursor: input.journalCursor,
     usageSampleCutoff: input.usageSampleCutoff,
   };

package/src/campaign/index.mjs

@@ -18,7 +18,7 @@ import { readProjectionState } from "./projection.mjs";
 import { handoffFromState, materializeHandoff } from "./handoff.mjs";
 import { preserveCampaignLedger, reledgerCampaignLedger } from "./ledger.mjs";
 
-export { preserveCampaignLedger, reledgerCampaignLedger } from "./ledger.mjs";
+export { markCampaignLedgerPreserved, preserveCampaignLedger, reledgerCampaignLedger, unpreservedLedgerCampaigns } from "./ledger.mjs";
 
 /** @typedef {Record<string, unknown>} JsonObject */
 /** @typedef {{path: string, digest: string}} CampaignContract */
@@ -27,7 +27,7 @@ export { preserveCampaignLedger, reledgerCampaignLedger } from "./ledger.mjs";
 /** @typedef {{runId: string, node: string, passed: boolean|null, verdict: string|null}} RequirementNodeEvidence */
 /** @typedef {{requirementId: string, status: "covered"|"open", nodes: RequirementNodeEvidence[]}} RequirementClosure */
 /** @typedef {{oldPath: string, newPath: string, runIds: string[], at: string}} ContractReplacement */
-/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], replacements?: ContractReplacement[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
+/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], replacements?: ContractReplacement[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, requirements?: RequirementClosure[], ledgerPreserved?: boolean, createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
 /** @typedef {{type: string, eventId: string, at: string, sessionId?: string, text?: string, tool?: string, transcript?: string|null, transcriptUnavailable?: boolean, format?: string|null, cursor?: string|null, decisionId?: string, supersedes?: string, runId?: string, questionId?: string, campaignId?: string, nodeId?: string|null, phase?: string, checkpointsDone?: number, checkpointsTotal?: number, runtime?: string|null, state?: string, lastProgressAt?: string, attention?: string|null}} JournalEntry */
 /** @typedef {{updatedAt: string|null, decisions: Record<string, JournalEntry>, questions: Record<string, JournalEntry>, constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], sessions: JournalEntry[], next: JournalEntry|null, evicted: Record<string, number>}} Projection */
 /** @typedef {{cursor: number, byte: number, size: number, projection: Projection}} ProjectionRecord */
@@ -130,10 +130,10 @@ export function resolveCampaign(runsDir, campaignId) {
 
 /**
  * @param {string} campaignPath
- * @param {{at?: string, eventId?: string}} options
+ * @param {{at?: string, eventId?: string, ledgerInRepo?: boolean}} options
  * @returns {{path: string, campaign: Campaign, ledgerFiles: string[], ledgerSkipped: {runId: string, source: string}[], worktrees: {removed: number, archived: string[]}}}
  */
-export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID() } = {}) {
+export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID(), ledgerInRepo = true } = {}) {
   requireTimestamp(at, "at");
   const campaign = readCampaign(campaignPath);
   if (campaign.status === "closed") throw new Error(`campaign already closed: ${campaign.id}`);
@@ -154,23 +154,36 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
   // Preserve after the closed record exists: the ledger is the recomputable
   // closed record, including requirements used by the north-star projector.
-  const ledger = preserveCampaignLedger(campaignPath, campaignRepoRoot(campaignPath));
+  //
+  // A plain close keeps the evidence beside the campaign in the operator home.
+  // The versioned copy under docs/ is opt-in with --ledger-in-repo, so closing
+  // a campaign against a repository the operator does not own leaves the tree
+  // untouched. The library default stays the versioned copy: existing callers
+  // and already-committed ledgers keep their location, and the CLI is what
+  // defaults to the home.
+  const repoRoot = campaignRepoRoot(campaignPath);
+  const ledger = preserveCampaignLedger(campaignPath, repoRoot, ledgerInRepo ? undefined : join(campaignPath, "ledger"));
+  // A versioned preservation marks the record inside `preserveCampaignLedger`;
+  // re-reading returns the record the caller can read, marker included.
+  const persisted = readCampaign(campaignPath);
   // A closed campaign resumes nothing, so the attempt worktrees its runs left
   // go now, each archived under a ref first (releaseRunWorktrees).
   const runsDir = resolve(campaignPath, "..", "..");
   const worktrees = { removed: 0, archived: /** @type {string[]} */ ([]) };
   for (const runId of campaign.linkedRunIds) {
-    const released = releaseRunWorktrees(campaignRepoRoot(campaignPath), join(runsDir, runId), runId);
+    const released = releaseRunWorktrees(repoRoot, join(runsDir, runId), runId);
     worktrees.removed += released.removed;
     worktrees.archived.push(...released.archived);
   }
-  return { path: campaignPath, campaign: closed, ledgerFiles: ledger.written, ledgerSkipped: ledger.skipped, worktrees };
+  return { path: campaignPath, campaign: persisted, ledgerFiles: ledger.written, ledgerSkipped: ledger.skipped, worktrees };
 }
 
 /**
  * Complete the versioned evidence ledger of a closed campaign. Unlike close,
- * this operation never updates the campaign record or journal: it only adds
- * surviving run sources beneath the repository's ledger directory.
+ * this operation does not otherwise update the campaign record or journal: it
+ * adds surviving run sources beneath the repository's ledger directory and
+ * marks the record's `ledgerPreserved`, the one state the durable copy makes
+ * true.
  *
  * @param {string} campaignPath
  * @returns {import("./ledger.mjs").LedgerReledger & {ledgerDir: string}}

package/src/campaign/ledger.mjs

@@ -6,7 +6,8 @@ import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync,
 import { dirname, join, resolve } from "node:path";
 
 import { readMetricNodeSnapshots } from "./metrics-command.mjs";
-import { CAMPAIGN_FILE, JOURNAL_FILE, LEDGER_SOURCE_MANIFEST_FILE } from "./layout.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+import { CAMPAIGN_FILE, JOURNAL_FILE, LEDGER_SOURCE_MANIFEST_FILE, campaignsDir } from "./layout.mjs";
 import { readCampaign } from "./record.mjs";
 
 /** @typedef {{runId: string, source: string}} LedgerSkip */
@@ -27,19 +28,74 @@ export const EVENT_PROJECTION_FIELDS = Object.freeze([
 /** Fields consumed by `projectMetrics`; notification messages and transport details never cross the ledger boundary. */
 export const NOTIFY_PROJECTION_FIELDS = Object.freeze(["at", "dedupeKey", "attempt", "status"]);
 
+/**
+ * Mark a campaign's record as having its ledger preserved at the durable,
+ * versioned location under its registered repository. A record that never
+ * carried the marker reads as not preserved (`readCampaign`), so removal
+ * refuses until this runs. Idempotent: an already marked record is returned
+ * untouched, which keeps a repeated reledger byte-stable.
+ *
+ * @param {string} campaignPath
+ * @returns {import("./index.mjs").Campaign}
+ */
+export function markCampaignLedgerPreserved(campaignPath) {
+  const campaign = readCampaign(campaignPath);
+  if (campaign.ledgerPreserved) return campaign;
+  const marked = { ...campaign, ledgerPreserved: true };
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), marked);
+  return marked;
+}
+
+/**
+ * The ids of the campaigns under `runsDir` whose ledger is not preserved at
+ * its durable, versioned repository location, sorted. A record written before
+ * the marker existed and a record that cannot be read both report as
+ * unpreserved: a removal that keeps evidence must refuse on the default and
+ * cannot let an unreadable record prove its evidence safe.
+ *
+ * @param {string} runsDir
+ * @returns {string[]}
+ */
+export function unpreservedLedgerCampaigns(runsDir) {
+  const root = campaignsDir(runsDir);
+  if (!existsSync(root)) return [];
+  /** @type {string[]} */
+  const unpreserved = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const campaignPath = join(root, entry.name);
+    if (!existsSync(join(campaignPath, CAMPAIGN_FILE))) continue;
+    try {
+      if (readCampaign(campaignPath).ledgerPreserved !== true) unpreserved.push(entry.name);
+    } catch {
+      unpreserved.push(entry.name);
+    }
+  }
+  return unpreserved.sort();
+}
+
 /**
  * Copy a campaign's projector sources into its versioned ledger. Missing run
  * sources are reported so a pruned run cannot make the close fail or look
  * complete by accident. Repeated calls overwrite the same paths.
  *
+ * `ledgerDir` is the exact destination. It defaults to the versioned ledger
+ * under `repoRoot/docs/campaigns/<id>/ledger`; `closeCampaign` passes the
+ * campaign directory in the operator home instead when `--ledger-in-repo` was
+ * not given, so the target repository is not dirtied by a plain close. A
+ * versioned write marks the campaign record's `ledgerPreserved`; a home write
+ * does not, because it does not survive an uninstall.
+ *
  * @param {string} campaignPath
  * @param {string} repoRoot
+ * @param {string|undefined} [ledgerDir]
  * @returns {LedgerPreservation}
  */
-export function preserveCampaignLedger(campaignPath, repoRoot) {
+export function preserveCampaignLedger(campaignPath, repoRoot, ledgerDir = undefined) {
   const campaign = readCampaign(campaignPath);
   const runsDir = resolve(campaignPath, "..", "..");
-  const ledgerDir = join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
+  const versioned = ledgerDir === undefined;
+  ledgerDir ??= join(repoRoot, "docs", "campaigns", campaign.id, "ledger");
   mkdirSync(ledgerDir, { recursive: true });
   /** @type {string[]} */
   const written = [];
@@ -96,6 +152,13 @@ export function preserveCampaignLedger(campaignPath, repoRoot) {
   const manifest = join(ledgerDir, LEDGER_SOURCE_MANIFEST_FILE);
   writeFileSync(manifest, `${JSON.stringify({ schemaVersion: 1, absent: [...absent].sort(), preserved: [...preserved].sort() })}\n`);
   written.push(manifest);
+  // The ledger exists, so a versioned preservation now marks the record. The
+  // already-copied campaign.json is refreshed afterwards so the durable copy
+  // carries the marker too; `written` keeps its original position and length.
+  if (versioned) {
+    markCampaignLedgerPreserved(campaignPath);
+    copyFileSync(join(campaignPath, CAMPAIGN_FILE), join(ledgerDir, CAMPAIGN_FILE));
+  }
   return { written, skipped };
 }
 
@@ -103,7 +166,9 @@ export function preserveCampaignLedger(campaignPath, repoRoot) {
  * Complete an already closed ledger from the run files still in the operator
  * home. A destination is replaced only when the source strictly extends its
  * bytes; this keeps a ledger's evidence stable when a run was rewritten or
- * truncated after close. Missing run sources are reported as gone.
+ * truncated after close. Missing run sources are reported as gone. The write
+ * is always versioned, so it marks the campaign record's `ledgerPreserved`
+ * and refreshes the ledger's copy of the record.
  *
  * @param {string} campaignPath
  * @param {string} repoRoot
@@ -164,6 +229,9 @@ export function reledgerCampaignLedger(campaignPath, repoRoot) {
       if (copyIfStrictExtension(source, destination)) copied.push({ runId: campaign.id, source: `proposals/${relative}` });
     }
   }
+  // The ledger is durable now, so mark the campaign record before refreshing
+  // the ledger's own copy of it when that copy is not already a closed record.
+  markCampaignLedgerPreserved(campaignPath);
   const ledgerCampaign = join(ledgerDir, CAMPAIGN_FILE);
   if (existsSync(ledgerCampaign)) {
     const existing = readJsonObject(ledgerCampaign);