faberun 0.7.0 → 0.9.0

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,
   };
 }
 

package/src/plan/freeze.mjs

@@ -0,0 +1,101 @@
+/**
+ * Freezing a plan: the boundary between a session's draft and a contract the
+ * engine can execute. `freezePlan` writes the plan's nodes as a validated
+ * contract.json, plus a plan.json carrying that contract's digest and the
+ * full provenance of how it was produced — the two files travel together so
+ * a later launch and this record agree on exactly what was reviewed.
+ * `verifyFrozenPlan` is the one check that the pair still agree.
+ *
+ * Nothing here invokes a model or the engine; it only writes and hashes
+ * bytes, so freezing a plan can never be mistaken for starting a run.
+ */
+import { mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, contractDigest, validateContract } from "../contract/index.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+
+/** @typedef {{runtimeId: string, model: string}} PlanParticipant */
+/** @typedef {{id: string, severity: "minor"|"major"|"critical", nodeId?: string, text: string}} PlanFinding */
+/** @typedef {{targetGitHead: string|null, planner: PlanParticipant, reviewer: PlanParticipant, sizing: unknown, findings: PlanFinding[]}} PlanProvenanceInput */
+/** @typedef {PlanProvenanceInput & {packageVersion: string, schemaVersion: number, contractVersion: string}} PlanProvenance */
+/** @typedef {{formatVersion: number, contractDigest: string, provenance: PlanProvenance}} FrozenPlan */
+/** @typedef {{ok: boolean, digest: string, expectedDigest: string}} FrozenPlanVerdict */
+
+const PLAN_FORMAT_VERSION = 1;
+
+/** @returns {string} the installed package's own version, read once per call so a freeze always names the toolchain that produced it */
+function packageVersion() {
+  const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+  return JSON.parse(readFileSync(packageJsonPath, "utf8")).version;
+}
+
+/**
+ * Validate `plan` as a contract and, only once it is valid, write it and a
+ * sibling plan.json naming its digest and provenance. `plan` supplies
+ * `schemaVersion`/`contractVersion` itself; when it does not, this fills in
+ * the runner's own current values.
+ *
+ * contract.json is written before validation runs, because a packet may
+ * declare `readFiles: ["contract.json"]` — an execution packet's own file,
+ * self-referenced the same way every fixture in this codebase already does.
+ * A validation failure removes that file again, so a caller never observes a
+ * contract.json that failed its own check.
+ *
+ * @param {JsonObject} plan
+ * @param {{outDir: string, provenance: PlanProvenanceInput}} options
+ * @returns {FrozenPlan}
+ */
+export function freezePlan(plan, { outDir, provenance }) {
+  mkdirSync(outDir, { recursive: true });
+  const contractPath = join(outDir, "contract.json");
+  const raw = /** @type {JsonObject} */ ({
+    schemaVersion: PROTOCOL_SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    ...plan,
+  });
+  writeJsonAtomic(contractPath, raw);
+  try {
+    validateContract(raw, contractPath);
+  } catch (error) {
+    rmSync(contractPath, { force: true });
+    throw error;
+  }
+  const frozen = /** @type {FrozenPlan} */ ({
+    formatVersion: PLAN_FORMAT_VERSION,
+    contractDigest: contractDigest(raw),
+    provenance: {
+      packageVersion: packageVersion(),
+      schemaVersion: /** @type {number} */ (raw.schemaVersion),
+      contractVersion: /** @type {string} */ (raw.contractVersion),
+      targetGitHead: provenance.targetGitHead,
+      planner: provenance.planner,
+      reviewer: provenance.reviewer,
+      sizing: provenance.sizing,
+      findings: provenance.findings,
+    },
+  });
+  // Atomic: the pipeline rewrites this file with its status straight after, and a
+  // reader polling for the frozen plan must never see a torn or half-written one
+  // (measured 2026-09-17: eval case D25 read a statusless plan.json on a slow runner).
+  writeJsonAtomic(join(outDir, "plan.json"), frozen);
+  return frozen;
+}
+
+/**
+ * Recompute contract.json's digest from the bytes on disk and compare it
+ * with the digest plan.json recorded at freeze time. A single byte changed
+ * in either file — the contract re-authored after review, or the plan
+ * record itself tampered with — is a mismatch.
+ *
+ * @param {string} outDir
+ * @returns {FrozenPlanVerdict}
+ */
+export function verifyFrozenPlan(outDir) {
+  const raw = JSON.parse(readFileSync(join(outDir, "contract.json"), "utf8"));
+  const plan = JSON.parse(readFileSync(join(outDir, "plan.json"), "utf8"));
+  const digest = contractDigest(raw);
+  return { ok: digest === plan.contractDigest, digest, expectedDigest: plan.contractDigest };
+}