faberun 0.8.0 → 0.9.0

package/package.json

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

@@ -32,6 +32,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 +107,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" },
+  },
 };
 
 /**
@@ -421,6 +432,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();
 }

package/src/contract/task-packet.mjs

@@ -432,7 +432,7 @@ function renderDiscoveryPrompt(packet, nodeId) {
     ...bulletOrNone(packet.nonGoals),
     "",
     "## Required output",
-    'Return exactly one worker-result JSON object, with no markdown or prose. Set status to "done", missingContext to [], and artifacts to an array containing exactly one JSON-stringified execution task packet with every required taskPacket field. The packet readFiles and writeFiles must be non-empty and scoped to this repository.',
+    'Return exactly one worker-result JSON object, with no markdown or prose. Set status to "done", missingContext to [], and artifacts to an array containing exactly one JSON-stringified execution task packet with every required taskPacket field. The packet readFiles and writeFiles must be non-empty and scoped to this repository. Put structured findings meant to inform that packet in `output` (a JSON object, at most 65536 bytes); prose belongs in `summary`.',
     "",
     "## Verification",
     VERIFICATION_PARAGRAPH,

package/src/contract/worker-result.mjs

@@ -1,6 +1,6 @@
 import { Buffer } from "node:buffer";
 import { validateTaskPacket } from "./task-packet.mjs";
-import { requireText } from "./assert.mjs";
+import { assertObject, requireText } from "./assert.mjs";
 
 const RESULT_LIMITS = Object.freeze({
   bytes: 32 * 1024,
@@ -9,6 +9,10 @@ const RESULT_LIMITS = Object.freeze({
   itemBytes: 2 * 1024,
   artifactBytes: 16 * 1024,
   missingContextItems: 16,
+  // A discovery worker's structured findings are the deliverable, not
+  // incidental prose, so `output` gets its own ceiling outside the 32 KiB
+  // envelope instead of competing with summary/verification for it.
+  outputBytes: 64 * 1024,
 });
 
 /**
@@ -26,9 +30,11 @@ export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
 /**
  * The worker-result protocol: exactly one JSON object returned as the only
  * content of the final worker message. `blocked_context` requires at least one
- * missingContext entry; `done` requires none.
+ * missingContext entry; `done` requires none. `output` is optional and carries
+ * a discovery node's structured findings; an execution result must not
+ * declare it (enforced where the node's mode is known, not here).
  *
- * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[]}} WorkerResult
+ * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[], output?: Record<string, unknown>}} WorkerResult
  */
 
 /**
@@ -37,8 +43,9 @@ export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
  */
 export function parseWorkerResult(value) {
   if (typeof value !== "string") throw new TypeError("worker result must be JSON text");
-  if (Buffer.byteLength(value, "utf8") > RESULT_LIMITS.bytes) {
-    throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
+  const maxRawBytes = RESULT_LIMITS.bytes + RESULT_LIMITS.outputBytes;
+  if (Buffer.byteLength(value, "utf8") > maxRawBytes) {
+    throw new TypeError(`worker result exceeds ${maxRawBytes} bytes`);
   }
   let parsed;
   try {
@@ -86,17 +93,42 @@ export function validateWorkerResult(value) {
   if (record.status === "done" && missingContext.length > 0) {
     throw new TypeError("worker result.missingContext must be empty for done");
   }
-  const normalized = {
+  // `output` is accepted on any result here: the schema does not know which
+  // node mode produced it. Refusing it for execution results happens exactly
+  // once, at the ingestion point that does know the mode (resolveWorkerResult).
+  let output;
+  if (Object.hasOwn(record, "output") && record.output !== undefined) {
+    assertObject(record.output, "worker result.output");
+    if (Buffer.byteLength(JSON.stringify(record.output), "utf8") > RESULT_LIMITS.outputBytes) {
+      throw new TypeError(`worker result.output exceeds ${RESULT_LIMITS.outputBytes} bytes`);
+    }
+    output = /** @type {Record<string, unknown>} */ (record.output);
+  }
+  const envelope = {
     status: /** @type {WorkerResultStatus} */ (record.status),
     summary: /** @type {string} */ (record.summary),
     verification: [.../** @type {string[]} */ (record.verification)],
     artifacts: [.../** @type {string[]} */ (record.artifacts)],
     missingContext: [...missingContext],
   };
-  if (Buffer.byteLength(JSON.stringify(normalized), "utf8") > RESULT_LIMITS.bytes) {
+  // `output` is bounded on its own above and kept outside this envelope cap:
+  // it is a discovery node's deliverable, not incidental prose competing with
+  // summary/verification for the same 32 KiB budget.
+  if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > RESULT_LIMITS.bytes) {
     throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
   }
-  return normalized;
+  return output === undefined ? envelope : { ...envelope, output };
+}
+
+/**
+ * A discovery node's structured findings, or null when the result carries
+ * none. The one accessor for `output` so callers never read the raw field.
+ *
+ * @param {WorkerResult} result
+ * @returns {Record<string, unknown>|null}
+ */
+export function discoveryOutput(result) {
+  return result.output ?? null;
 }
 
 /**

package/src/engine/lifecycle.mjs

@@ -54,6 +54,7 @@ import { appendUsageRecord, invocationCost, invocationUsage, recordInvocationUsa
 import { attemptWorkspace } from "../repo/worktree.mjs";
 import { executeControllerVerification } from "./verify.mjs";
 import {
+  ExecutionOutputNotAllowedError,
   materializeAttemptResult,
   readWorkerResultFile,
   resolveWorkerResult,
@@ -528,6 +529,16 @@ export async function finalizeClosedJobs(contract, runDir, states, running, lock
       try {
         workerResult = resolveWorkerResult(runDir, job.node, envelope.result);
       } catch (error) {
+        // A definitive protocol violation, not a malformed result: an
+        // execution node has no legitimate way to earn the repair path here.
+        if (error instanceof ExecutionOutputNotAllowedError) {
+          clearTierExhaustion(state);
+          transition(runDir, state, "failed", {
+            phase: "worker",
+            error: { code: "execution_output_not_allowed", message: errorMessage(error) },
+          }, lock);
+          continue;
+        }
         if (job.resultMaterialization) {
           clearTierExhaustion(state);
           transition(runDir, state, "failed", {

package/src/engine/result-file.mjs

@@ -19,10 +19,18 @@ import { extractJson } from "../harnesses/protocol.mjs";
 import { invocationResult } from "./process.mjs";
 import { join } from "node:path";
 import { parseJudge } from "./prompts.mjs";
-import { parseWorkerResult } from "../contract/worker-result.mjs";
+import { discoveryOutput, parseWorkerResult } from "../contract/worker-result.mjs";
 import { readJson, writeJsonAtomic, writeTextAtomic } from "../run/store.mjs";
 import { routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
 
+/**
+ * Thrown by `resolveWorkerResult` when an execution result declares `output`.
+ * A distinct type, not a plain TypeError: this is a definitive protocol
+ * violation the engine can fail terminally on sight, not a malformed result
+ * worth the generic invalid-result repair attempt.
+ */
+export class ExecutionOutputNotAllowedError extends TypeError {}
+
 /** @typedef {import("./lifecycle.mjs").Invocation} Invocation */
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -115,6 +123,10 @@ export function isResultMaterializationInvocation(invocation) {
   }
 }
 /**
+ * The single ingestion point that knows the node's mode, so it is the one
+ * place `output` is refused for an execution result: the schema itself
+ * accepts the field on any result, mode-blind.
+ *
  * @param {string} runDir
  * @param {ValidatedNode} node
  * @param {unknown} providerResult
@@ -122,9 +134,11 @@ export function isResultMaterializationInvocation(invocation) {
  */
 export function resolveWorkerResult(runDir, node, providerResult) {
   const fromFile = readWorkerResultFile(runDir, node.id);
-  if (fromFile) return fromFile;
-  const result = parseWorkerResult(String(extractJson(providerResult) ?? providerResult ?? ""));
-  persistWorkerResultFile(runDir, node.id, result);
+  const result = fromFile ?? parseWorkerResult(String(extractJson(providerResult) ?? providerResult ?? ""));
+  if (node.taskPacket.mode === "execution" && discoveryOutput(result) !== null) {
+    throw new ExecutionOutputNotAllowedError("worker result.output is only allowed for a discovery node, not execution");
+  }
+  if (!fromFile) persistWorkerResultFile(runDir, node.id, result);
   return result;
 }
 /**

package/src/harnesses/protocol.mjs

@@ -5,6 +5,8 @@ import { finite } from "../util.mjs";
  * `zcode.mjs`, `replay.mjs` and `exec-jsonl.mjs` itself all depend on it.
  */
 
+/** @typedef {{remaining: number|null, limit: number|null, resetsAt: string|null, window: string|null}} ClaudeAllowance */
+
 /**
  * Parse newline-delimited JSON without accepting provider prose.
  *
@@ -75,33 +77,110 @@ function withStartupReason(message, options = {}) {
   return reason ? `${message}: ${boundedMessage(reason, 512)}` : message;
 }
 
+/**
+ * Claude's account-wide rate-limit signal, reported on its own `rate_limit_event`
+ * stream line, never on the terminal `result` event. Measured 2026-09-17
+ * against `claude -p 'Reply with exactly OK and use no tools.' --output-format
+ * stream-json --verbose`, cost `total_cost_usd: 0.27848` for that one probe
+ * (opus-tier default model, most of it `cache_creation_input_tokens` for this
+ * project's session context -- a probe against a smaller/cheaper model would
+ * cost far less, but the seat sampled is whichever model the operator's own
+ * session already has configured, so this is the honest per-probe figure for
+ * that seat). No `rate_limits` or `rate_limit_status` field appears anywhere
+ * in the stream. The measured line, verbatim:
+ * `{"type":"rate_limit_event","rate_limit_info":{"status":"allowed_warning",
+ * "resetsAt":1789837200,"rateLimitType":"seven_day","utilization":0.77,
+ * "isUsingOverage":false,"surpassedThreshold":0.75,"unifiedWindows":
+ * {"five_hour":{"utilization":0.1,"resetsAt":1789663200},"seven_day":
+ * {"utilization":0.77,"resetsAt":1789837200}}}}`. `utilization` is a 0..1
+ * fraction of the window named by `rateLimitType`, confirmed (not merely
+ * assumed) by `surpassedThreshold: 0.75` sitting just below the measured
+ * `0.77` at `status: "allowed_warning"` -- a 0-100 percentage scale would put
+ * 0.77 nowhere near a 75-scaled threshold. This is a different field, on a
+ * different scale, from the `used_percentage` (0-100) the statusline
+ * integration already reads off `rate_limits.five_hour` (see
+ * `integrations/claude-code/statusline.sh`); the two must not be confused.
+ * `remaining` here is the fraction left (`1 - utilization`) and `limit` is
+ * the fixed ceiling `1` -- a coarse proxy, declared as such. A `utilization`
+ * outside `[0, 1]` is treated as no signal (null) rather than silently
+ * clamped, so a future scale change on the stream fails visibly instead of
+ * pinning every sample to 0.
+ *
+ * `unifiedWindows` carries every window's own utilization side by side
+ * (`five_hour: 0.1` next to `seven_day: 0.77` in the measured line above): the
+ * top-level `utilization` is only ever the figure for the window `rateLimitType`
+ * names, so a sample must read the named window out of `unifiedWindows` (falling
+ * back to the top-level field only when `unifiedWindows` carries no entry for
+ * it) and record which window that was. Two samples of different windows are
+ * not comparable -- a `five_hour` utilization minus a `seven_day` one is not a
+ * delta -- so the window travels with the sample for `allowanceDelta` to pin.
+ *
+ * @param {Record<string, unknown>[]} events
+ * @returns {ClaudeAllowance}
+ */
+function extractClaudeAllowance(events) {
+  const event = events.findLast((candidate) => candidate.type === "rate_limit_event");
+  const info = event?.rate_limit_info;
+  const record = info && typeof info === "object" && !Array.isArray(info) ? /** @type {Record<string, unknown>} */ (info) : null;
+  const window = record && typeof record.rateLimitType === "string" ? record.rateLimitType : null;
+  const unifiedWindows = record?.unifiedWindows && typeof record.unifiedWindows === "object" && !Array.isArray(record.unifiedWindows)
+    ? /** @type {Record<string, unknown>} */ (record.unifiedWindows)
+    : null;
+  const namedWindowEntry = window && unifiedWindows?.[window] && typeof unifiedWindows[window] === "object" && !Array.isArray(unifiedWindows[window])
+    ? /** @type {Record<string, unknown>} */ (unifiedWindows[window])
+    : null;
+  const rawUtilization = finite(namedWindowEntry ? namedWindowEntry.utilization : record?.utilization);
+  const utilization = rawUtilization !== null && rawUtilization >= 0 && rawUtilization <= 1 ? rawUtilization : null;
+  const resetsAtSeconds = finite(namedWindowEntry ? namedWindowEntry.resetsAt : record?.resetsAt);
+  return {
+    remaining: utilization === null ? null : 1 - utilization,
+    limit: utilization === null ? null : 1,
+    resetsAt: resetsAtSeconds === null ? null : new Date(resetsAtSeconds * 1000).toISOString(),
+    window,
+  };
+}
+
+/** The claude allowance shape with every member null: no signal was read. */
+const NULL_CLAUDE_ALLOWANCE = { remaining: null, limit: null, resetsAt: null, window: null };
+
 /**
  * @param {string} stdout
  * @param {number|null} exitCode
  * @param {string|null} signal
  * @param {import("./index.mjs").NormalizeOptions} [options]
- * @returns {import("./index.mjs").ProviderEnvelope}
+ * @returns {import("./index.mjs").ProviderEnvelope & {allowance: ClaudeAllowance}}
  */
 export function normalizeClaudeResult(stdout, exitCode, signal, options = {}) {
-  if (signal) return failed("canceled", `provider ended after ${signal}`, "canceled");
+  // The signal check must stay the first statement, byte-identical to before
+  // the allowance signal existed: `parseJsonLines` throws on any unparseable
+  // line past the first, and a killed process routinely leaves a truncated
+  // *later* line (the bounded-tail tolerance only covers the first). Parsing
+  // stdout before checking `signal` would turn a clean cancellation into a
+  // thrown error, which callers (`src/run/usage.mjs`, `src/engine/process.mjs`)
+  // catch into `invalid_output` or `null`, losing the envelope entirely.
+  if (signal) return { ...failed("canceled", `provider ended after ${signal}`, "canceled"), allowance: NULL_CLAUDE_ALLOWANCE };
   const events = parseJsonLines(stdout, "claude");
+  const allowance = extractClaudeAllowance(events);
   const resultEvent = events.findLast((event) => event.type === "result");
-  if (!resultEvent) return failed("incomplete_stream", withStartupReason("Claude emitted no result event", options));
+  if (!resultEvent) return { ...failed("incomplete_stream", withStartupReason("Claude emitted no result event", options)), allowance };
   const result = typeof resultEvent.result === "string" ? resultEvent.result : null;
   // A provider-reported quota stop is exhaustion: the declared failover edge
   // must fire instead of settling the node as an ordinary provider failure.
   const quotaText = claudeQuotaText(resultEvent, events);
   if (quotaText) {
-    return failed(
-      "quota_exhausted",
-      boundedMessage(quotaText, 512),
-      "exhausted",
-      typeof resultEvent.session_id === "string" ? resultEvent.session_id : null,
-      canonicalUsage(resultEvent.usage),
-    );
+    return {
+      ...failed(
+        "quota_exhausted",
+        boundedMessage(quotaText, 512),
+        "exhausted",
+        typeof resultEvent.session_id === "string" ? resultEvent.session_id : null,
+        canonicalUsage(resultEvent.usage),
+      ),
+      allowance,
+    };
   }
   if (resultEvent.is_error || exitCode !== 0) {
-    return failed("provider_error", result ?? `Claude exited with code ${exitCode}`);
+    return { ...failed("provider_error", result ?? `Claude exited with code ${exitCode}`), allowance };
   }
   return {
     status: result?.trim() ? "done" : "no-op",
@@ -110,6 +189,7 @@ export function normalizeClaudeResult(stdout, exitCode, signal, options = {}) {
     usage: canonicalUsage(resultEvent.usage),
     costUsd: finite(resultEvent.total_cost_usd),
     error: null,
+    allowance,
   };
 }