faberun 0.25.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "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/references/contract.md

@@ -140,8 +140,10 @@ missing something, never repository-wide exploration. Bounded: 32 KiB total,
 4 KiB summary, 32 entries each in `changedFiles`/`verification`/`artifacts`
 (16 in `missingContext`), 2 KiB per entry (16 KiB per artifact). Unknown
 provider-added fields are dropped; missing/malformed canonical fields are
-rejected (`worker-result.mjs`). A discovery node returns `done` with exactly
-one `artifacts` entry: the execution packet for the next node.
+rejected (`worker-result.mjs`). A discovery node without `readFiles` returns
+`done` with one `artifacts` entry, the next node's execution packet; one closed
+to its `readFiles` (every planning stage) delivers through `output`, `artifacts`
+`[]`.
 
 ## Runtimes and routing
 

package/src/contract/task-packet.mjs

@@ -426,8 +426,11 @@ function pathInside(path, root) {
  * @returns {string}
  */
 function renderDiscoveryPrompt(packet, nodeId) {
+  // The closed variant says what settlement accepts (engine/lifecycle.mjs):
+  // only a discovery packet with no read files owes an execution packet in
+  // artifacts[0]; one closed to its read files delivers through `output`.
   const closedContext = packet.readFiles.length
-    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0]."
+    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; deliver your result in `output` and send `artifacts` as []."
     : "This discovery context is read-only and is the one exception to closed inspection: no read files were pre-supplied, so you may inspect the repository read-only only as needed to produce the packet. Do not edit the repository. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0].";
   const lines = [
     `# Node ${nodeId} (discovery)`,

package/src/contract/worker-result.mjs

@@ -25,6 +25,23 @@ const RESULT_LIMITS = Object.freeze({
  */
 export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
 
+/**
+ * A worker result that is well-formed JSON but breaks one of the byte
+ * ceilings above. Typed, not a plain TypeError, so the repair prompt can name
+ * the ceiling that was broken: observed 2026-09-25, a planning draft that
+ * copied its 38 KiB plan into `artifacts[0]` was told twice to drop markdown
+ * fences it never wrote, and repeated the copy.
+ */
+export class WorkerResultSizeError extends TypeError {
+  /** @param {string} field @param {number} limit */
+  constructor(field, limit) {
+    super(`${field} exceeds ${limit} bytes`);
+    this.name = "WorkerResultSizeError";
+    this.field = field;
+    this.limit = limit;
+  }
+}
+
 /** @typedef {"done"|"blocked_context"} WorkerResultStatus */
 
 /**
@@ -37,6 +54,20 @@ export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
  * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[], output?: Record<string, unknown>}} WorkerResult
  */
 
+/**
+ * The repair instruction for an invalid worker result: a broken byte ceiling
+ * is named, since re-emitting the same object without fences cannot fix it.
+ *
+ * @param {unknown} cause
+ * @returns {string}
+ */
+export function invalidResultRepair(cause) {
+  if (cause instanceof WorkerResultSizeError) {
+    return `the result breaks a size ceiling: ${cause.field} exceeds ${cause.limit} bytes. Keep every field within its ceiling; a node that delivers through \`output\` sends \`artifacts\` as [] and never copies \`output\` into \`artifacts\`.`;
+  }
+  return "the entire final message must be exactly the required JSON object: no markdown fences, no prose before or after it. Return it as the only content of the final message.";
+}
+
 /**
  * @param {string} value
  * @returns {WorkerResult}
@@ -45,7 +76,7 @@ export function parseWorkerResult(value) {
   if (typeof value !== "string") throw new TypeError("worker result must be JSON text");
   const maxRawBytes = RESULT_LIMITS.bytes + RESULT_LIMITS.outputBytes;
   if (Buffer.byteLength(value, "utf8") > maxRawBytes) {
-    throw new TypeError(`worker result exceeds ${maxRawBytes} bytes`);
+    throw new WorkerResultSizeError("worker result", maxRawBytes);
   }
   let parsed;
   try {
@@ -100,7 +131,7 @@ export function validateWorkerResult(value) {
   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`);
+      throw new WorkerResultSizeError("worker result.output", RESULT_LIMITS.outputBytes);
     }
     output = /** @type {Record<string, unknown>} */ (record.output);
   }
@@ -115,7 +146,7 @@ export function validateWorkerResult(value) {
   // 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`);
+    throw new WorkerResultSizeError("worker result", RESULT_LIMITS.bytes);
   }
   return output === undefined ? envelope : { ...envelope, output };
 }
@@ -165,6 +196,6 @@ function requireList(value, label, maxItems, itemBytes) {
   if (!Array.isArray(value) || value.length > maxItems) throw new TypeError(`${label} must be an array with at most ${maxItems} items`);
   for (const [index, item] of value.entries()) {
     if (typeof item !== "string") throw new TypeError(`${label}[${index}] must be a string`);
-    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new TypeError(`${label}[${index}] exceeds ${itemBytes} bytes`);
+    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new WorkerResultSizeError(`${label}[${index}]`, itemBytes);
   }
 }

package/src/engine/lifecycle.mjs

@@ -37,7 +37,7 @@ import { getHarness, normalizeProviderAvailability } from "../harnesses/index.mj
 import { availabilityKey, recordRefusal, refusalOfAvailability } from "../run/availability.mjs";
 
 import { acquire as acquireLock } from "../run/lock.mjs";
-import { parseDiscoveryResult } from "../contract/worker-result.mjs";
+import { invalidResultRepair, parseDiscoveryResult } from "../contract/worker-result.mjs";
 import { boundedUtf8, errorCode, errorMessage, excerpt } from "../util.mjs";
 import { readJson, writeJsonAtomic } from "../run/store.mjs";
 import { invocationAlive } from "./process.mjs";
@@ -443,7 +443,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
     // path fails it today.
     if (workerResultError) {
       if (envelope.status === "done") {
-        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(workerResultError), states, campaignPath);
+        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, workerResultError, states, campaignPath);
         continue;
       }
       adoptedWorkerResult = null;
@@ -549,7 +549,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
           }, lock);
           continue;
         }
-        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
+        await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, error, states, campaignPath);
         continue;
       }
       // The artifact demand follows the documented discovery contract, not the
@@ -562,7 +562,7 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
         try {
           parseDiscoveryResult(workerResult, attemptWorkspace(state) ?? contract.cwd);
         } catch (error) {
-          await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
+          await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, error, states, campaignPath);
           continue;
         }
       }
@@ -737,19 +737,21 @@ function applyRoute(contract, runDir, state, lock, { role, error, current, plan,
  * told to return. A second one is evidence about the provider rather than the
  * packet, so the node records a protocol_failure and takes its failover edge —
  * and when no edge remains, it blocks and raises attention rather than filing
- * a quiet exhaustion nobody reads.
+ * a quiet exhaustion nobody reads. The repair names what was wrong
+ * (invalidResultRepair), so a broken byte ceiling is not told about fences.
  *
- * @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {string} message @param {Map<string, NodeSnapshot>} states @param {string} campaignPath
+ * @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {Map<string, Job>|null} running @param {LockHandle} lock @param {unknown} cause @param {Map<string, NodeSnapshot>} states @param {string} campaignPath
  */
-export async function applyInvalidWorkerResult(contract, node, state, runDir, running, lock, message, states, campaignPath) {
+export async function applyInvalidWorkerResult(contract, node, state, runDir, running, lock, cause, states, campaignPath) {
   clearTierExhaustion(state);
+  const message = errorMessage(cause);
   const verdict = /** @type {JudgeVerdict} */ ({
     verdict: "fail",
     maxSeverity: "critical",
     summary: "worker result did not match the structured result protocol",
     findings: [{
       severity: "critical",
-      description: "the entire final message must be exactly the required JSON object: no markdown fences, no prose before or after it. Return it as the only content of the final message.",
+      description: invalidResultRepair(cause),
       evidence: boundedUtf8(message, 4 * 1024),
     }],
   });

package/src/engine/resume.mjs

@@ -284,7 +284,7 @@ export async function resumeRun(runDirPath, options = {}) {
             ? recoverWorkerResult(runDir, state, contract, node)
             : canonicalWorkerResultText(runDir, node.id) ?? recovery.result;
         } catch (error) {
-          await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+          await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
           continue;
         }
         if (recovery.phase === "worker" && workerResult !== null && workerResult !== undefined) {
@@ -301,7 +301,7 @@ export async function resumeRun(runDirPath, options = {}) {
           try {
             parsedWorkerResult = parseWorkerResult(String(extractJson(workerResult) ?? workerResult));
           } catch (error) {
-            await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+            await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
             continue;
           }
           // Same discriminator as lifecycle.mjs: the artifact is owed only by
@@ -311,7 +311,7 @@ export async function resumeRun(runDirPath, options = {}) {
             try {
               parseDiscoveryResult(parsedWorkerResult, attemptWorkspace(state) ?? contract.cwd);
             } catch (error) {
-              await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
+              await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, error, states, campaign.path);
               continue;
             }
           }