faberun 0.19.3 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.19.3",
+  "version": "0.20.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/engine/dispatch.mjs

@@ -34,7 +34,7 @@ import { invocationCost, invocationUsage } from "../run/usage.mjs";
 import { logPaths, startProcess } from "./process.mjs";
 import { readBoundedTail } from "./transcript.mjs";
 import { mkdirSync, statSync } from "node:fs";
-import { READ_BYTE_LIMIT, READ_LINE_LIMIT, normalizeProviderResult } from "../harnesses/index.mjs";
+import { READ_BYTE_LIMIT, READ_LINE_LIMIT, harnessCapabilities, normalizeProviderResult } from "../harnesses/index.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
 import { routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
@@ -153,12 +153,19 @@ function workerToolPolicy(runtime, node, workspace) {
  * @returns {import("../harnesses/index.mjs").CommandOptions}
  */
 function invocationCommandOptions(contract, node, state, runtime, phasePlan, runDir, lock, extra = {}) {
+  // A harness that streams its stdout proves liveness through the event
+  // monitor; a buffered one (zcode's `--json` writes only at exit) has one
+  // live surface left, its own log stream, and the adapter decides whether
+  // this dir means anything to it. Streaming harnesses get none: their log
+  // dir would be dead weight the engine never watches.
+  const streaming = harnessCapabilities(runtime).streamsOutput === true;
   return {
     ...extra,
     continuationId: runtime.capabilities.continuation === true ? phasePlan.continuationId : null,
     // The attempt's request ceiling. An adapter that can enforce it natively
     // takes it as a flag; the monitor enforces it for every streaming harness.
     maxTurns: node.maxTurns ?? contract.maxTurns,
+    logDir: streaming ? null : join(runDir, "logs", `${node.id}.${state.attempt}.provider`),
   };
 }
 /**

package/src/engine/process.mjs

@@ -7,7 +7,7 @@
  * a judge decides, or when a run is done. That separation is the point: a stuck
  * provider is killed by the same code whatever it was asked to do.
  */
-import { boundedRegion, monitorInvocation } from "./transcript.mjs";
+import { boundedRegion, latestLogWriteMs, monitorInvocation } from "./transcript.mjs";
 import { closeSync, existsSync, fsyncSync, openSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { errorCode, errorMessage } from "../util.mjs";
@@ -36,7 +36,7 @@ import { killTarget } from "../host/platform.mjs";
 /** @typedef {{prompt: string|null, stdout: string, stderr: string}} PathSet */
 /** @typedef {{id: string, pid: number, processGroupId: number|null, processStartToken: string|null, harness: string, runtimeId: string|null, runtimeFingerprint?: string, revision?: number, phase: string, promptPath: string|null, stdoutPath: string, stderrPath: string, startedAt: string, deadlineAt: string|null, updatedAt: string, closedAt: string|null, exitCode: number|null, signal: string|null, status: "active"|"closed"|"terminated", executable: string, snapshotPath?: string, usage?: Usage, usageEstimated?: boolean, costUsd?: number|null, costProvenance?: "priced", runId?: string, campaignId?: string, nodeId?: string, attempt?: number, workspace?: string, worktreeBranch?: string|null, worktreeBaseSha?: string|null, planPhase?: string, role?: "worker"|"judge", model?: string, reasoning?: string|null, sandbox?: string|null, continuationId?: string|null, continuationMode?: "fresh"|"reuse"|"rotate", session?: import("../harnesses/session-metrics.mjs").SessionLedger|null}} Invocation */
 /** @typedef {{pid: number|null, processGroupId?: number|null, processStartToken?: string|null}} InvocationProbe */
-/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
+/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, logDir?: string|null, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, lastLogWriteMs?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
 /** @typedef {{graceMs?: number, killGraceMs?: number, escalate?: boolean, runDir?: string, kill?: (pid: number, signal: string|number) => unknown, child?: ChildProcess|null}} TerminateOptions */
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -48,6 +48,16 @@ const GATE_PATH = join(HERE, "gate.mjs");
  */
 export function startProcess({ contract, node, state, runtime, prompt, paths, phase, workspace = contract.cwd, commandOptions = {}, onInvocation, onInvocationUpdate, onProgress }) {
   const command = providerCommand(runtime, prompt, commandOptions);
+  // The engine offers a log dir to every non-streaming harness; only an
+  // adapter that wants one creates it (zcode does, inside `command()` above,
+  // which has already run). Taking the offer is therefore observable, and the
+  // stall detector must key on the adapter's answer rather than on the
+  // engine's offer: `exec-jsonl` and `replay` are non-streaming too, declare
+  // no `stallTimeoutSec`, and were deliberately not stall-tracked at all. A
+  // path they never write to would otherwise have made them tracked against a
+  // log that stays empty forever -- measured 2026-09-22 against the contract
+  // default of 300s, a healthy exec-jsonl worker was killed as stalled.
+  const logDir = commandOptions.logDir && existsSync(commandOptions.logDir) ? commandOptions.logDir : null;
   if (paths.prompt) writeFileSync(paths.prompt, prompt, { flag: "wx", mode: 0o600 });
   const gateConfigPath = `${paths.prompt}.gate.json`;
   const gateReleasePath = `${paths.prompt}.gate.release`;
@@ -125,6 +135,7 @@ export function startProcess({ contract, node, state, runtime, prompt, paths, ph
     terminating: null,
     gateConfigPath,
     gateReleasePath,
+    logDir,
     onInvocationUpdate,
     onProgress,
   };
@@ -433,11 +444,13 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
     // calling tools is alive even when it writes no workspace file, and a
     // buffered harness (zcode's `--json`) writes its whole transcript only at
     // exit, so its mtime proves nothing. A harness that never streams is
-    // stall-tracked only when its runtime declares its own threshold; otherwise
-    // the wall clock above is the only budget it is held to.
+    // stall-tracked through its provider log dir when its adapter keeps one
+    // (zcode points the CLI's `ZCODE_LOG_DIR` at it), through a runtime that
+    // declares its own threshold, or by neither — the wall clock above is
+    // then the only budget it is held to.
     const streaming = harnessCapabilities(job.runtime).streamsOutput;
     const declaredStall = typeof (/** @type {{stallTimeoutSec?: unknown}} */ (job.runtime)?.stallTimeoutSec) === "number";
-    if (!streaming && !declaredStall) continue;
+    if (!streaming && !declaredStall && !job.logDir) continue;
     const stallTimeoutSec = stallTimeoutSecFor(job.runtime, contract);
     if (streaming) {
       const monitored = monitorInvocation(job);
@@ -499,9 +512,24 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
         await onTimeout(job, "exhausted", limit);
         continue;
       }
-    } else if (job.observedOnce !== true) {
-      job.progressTicks = now;
-      job.lastOutputAt = Date.now();
+    } else {
+      // The buffered-harness liveness signal: the CLI's log stream appending
+      // inside the attempt's log dir. An mtime that advances past the newest
+      // one this loop has seen is a write, and a write is progress — the same
+      // lower-bound discipline as the polling fixtures: it can only delay a
+      // stall verdict, never prove speed.
+      if (job.logDir) {
+        const written = latestLogWriteMs(job.logDir);
+        if (written > (job.lastLogWriteMs ?? 0)) {
+          job.lastLogWriteMs = written;
+          job.progressTicks = now;
+          job.lastOutputAt = Date.now();
+        }
+      }
+      if (job.observedOnce !== true) {
+        job.progressTicks = now;
+        job.lastOutputAt = Date.now();
+      }
     }
     job.observedOnce = true;
     if (elapsedSeconds(job.progressTicks, now) < stallTimeoutSec) continue;

package/src/engine/transcript.mjs

@@ -6,10 +6,11 @@
  * because reading the log never touches the process, and because process.mjs
  * crossed the 800-line ceiling carrying both jobs.
  */
-import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
 import { Buffer } from "node:buffer";
 import { SessionMetricsParser } from "../harnesses/session-metrics.mjs";
 import { errorCode } from "../util.mjs";
+import { join } from "node:path";
 
 /** @typedef {import("./process.mjs").Job} Job */
 
@@ -143,3 +144,44 @@ function dropPartialLogLine(value) {
   const newline = String(value).indexOf("\n");
   return newline < 0 ? "" : String(value).slice(newline + 1);
 }
+
+/**
+ * Newest write inside the attempt's provider log dir, 0 when nothing is there
+ * yet. The CLI lays its session logs out as files (it may nest a directory),
+ * so the scan walks three levels and reads only mtimes — never contents,
+ * which is the monitor's job for streaming harnesses and nobody else's.
+ * Every stat failure is an ordinary not-yet: a dir with nothing readable in
+ * it proves no liveness, which is exactly the right answer.
+ *
+ * Cheap enough to run on every tick: measured 2026-09-22 on macOS, a dir of
+ * 250 files across two levels scans in 0.80 ms, against the 1000 ms default
+ * `pollIntervalMs` — so the cost is under a tenth of a percent of one job's
+ * poll, and the scan reads no bytes.
+ *
+ * @param {string} dir
+ * @param {number} [depth]
+ * @returns {number}
+ */
+export function latestLogWriteMs(dir, depth = 0) {
+  let newest = 0;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (depth < 3) newest = Math.max(newest, latestLogWriteMs(path, depth + 1));
+      continue;
+    }
+    try {
+      newest = Math.max(newest, statSync(path).mtimeMs);
+    } catch {
+      // Raced a rotation or a permission change: this entry proves nothing,
+      // the rest of the scan still does.
+    }
+  }
+  return newest;
+}

package/src/harnesses/index.mjs

@@ -95,7 +95,7 @@ export const READ_LINE_LIMIT = 1500;
  */
 export const READ_BYTE_LIMIT = 32 * 1024;
 
-/** @typedef {{schema?: object, schemaPath?: string, continuationId?: string|null, toolPolicy?: ToolPolicy, env?: Record<string, string>, maxTurns?: number}} CommandOptions */
+/** @typedef {{schema?: object, schemaPath?: string, continuationId?: string|null, toolPolicy?: ToolPolicy, env?: Record<string, string>, maxTurns?: number, logDir?: string|null}} CommandOptions */
 
 /** @typedef {{preferStructured?: boolean, exitCode?: number|null, signal?: string|null, stderr?: string}} NormalizeOptions */
 

package/src/harnesses/zcode/index.mjs

@@ -1,4 +1,4 @@
-import { accessSync, chmodSync, constants, existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { normalizeZcodeResult, parseVersion } from "../protocol.mjs";
@@ -20,6 +20,20 @@ const ZCODE_MACOS_BUNDLE = Object.freeze({
   cli: "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
 });
 
+/**
+ * Linux install layouts: an Electron `.deb`/`.rpm` unpacks the app under
+ * `/opt/<App>` (some packagers use `/usr/lib/<app>`) with the same
+ * `resources/` shape the macOS bundle has. None of these is documented by the
+ * vendor — `docs/harnesses/zcode-cli.md` records only the macOS layout — so the
+ * list is a probe, and `FABERUN_ZCODE_APP_DIR` names an install this list
+ * does not know.
+ */
+const ZCODE_LINUX_BUNDLES = Object.freeze([
+  { electron: "/opt/ZCode/zcode", cli: "/opt/ZCode/resources/glm/zcode.cjs" },
+  { electron: "/opt/zcode/zcode", cli: "/opt/zcode/resources/glm/zcode.cjs" },
+  { electron: "/usr/lib/zcode/zcode", cli: "/usr/lib/zcode/resources/glm/zcode.cjs" },
+]);
+
 /** Provider id in the ZCODE_MODEL target; it also derives the auth env var name. */
 const ZCODE_DEFAULT_PROVIDER = "glm";
 
@@ -68,7 +82,9 @@ export const zcodeHarness = {
     // once at exit: a live worker node was killed at 420s stall_timeout with
     // its stdout/stderr at zero bytes, while a completed 1m26s invocation's
     // log held its full 26 lines only once the process exited. Stall
-    // detection must not watch this harness's stdout/stderr mtime.
+    // detection must not watch this harness's stdout/stderr mtime. Liveness
+    // comes from the CLI's own log stream instead — see `command()`'s
+    // ZCODE_LOG_DIR wiring, which the engine's stall clock watches.
     streamsOutput: false,
     // Unmeasured: no run has proven whether zcode's sandbox can signal child
     // processes or read the process table.
@@ -134,6 +150,19 @@ export const zcodeHarness = {
     // resolves (e.g. GLM_API_KEY); an unresolved token is omitted, not blanked.
     const apiKeyVar = providerApiKeyVar(provider);
     if (token !== null && apiKeyVar !== null) env[apiKeyVar] = token;
+    // The one live surface a buffered harness has: the CLI's own log stream.
+    // `--json` writes stdout only at exit, but `ZCODE_LOG_DIR` in `json`
+    // format receives session events as they happen, so the engine's stall
+    // clock can watch the log dir instead of holding the attempt to the wall
+    // clock alone. The engine supplies one dir per attempt (see
+    // `invocationCommandOptions`); the adapter creates it and points the CLI
+    // at it, and console logging stays off so stderr stays a pure error path.
+    if (options.logDir) {
+      mkdirSync(options.logDir, { recursive: true });
+      env.ZCODE_LOG_DIR = options.logDir;
+      env.ZCODE_LOG_FORMAT = "json";
+      env.ZCODE_LOG_CONSOLE = "false";
+    }
     return { executable: this.executable(runtime), args, promptTransport: "argv", input: null, env };
   },
 
@@ -187,8 +216,8 @@ export function ensureZcodeAvailable(options = {}) {
     const env = options.env ?? process.env;
     const pathDirs = options.pathDirs ?? (env.PATH ?? "").split(delimiter).filter(Boolean);
     if (resolvesOnPath(pathDirs, ZCODE_BIN_NAME)) return;
-    const bundle = options.bundle ?? ZCODE_MACOS_BUNDLE;
-    if (!existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
+    const bundle = options.bundle ?? zcodeBundle(env);
+    if (!bundle || !existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
     const body = zcodeShim(bundle);
     for (const dir of shimDirs(options.home ?? homedir())) {
       if (!pathDirs.includes(dir)) continue;
@@ -200,6 +229,22 @@ export function ensureZcodeAvailable(options = {}) {
   }
 }
 
+/**
+ * The bundle this host has, if any: an explicit `FABERUN_ZCODE_APP_DIR`
+ * override, the macOS app path on darwin, or the first probed Linux layout
+ * whose two paths both exist. A host with none gets null — the same "not
+ * installed" answer every probe below returns.
+ *
+ * @param {Record<string, string|undefined>} env
+ * @returns {{electron: string, cli: string}|null}
+ */
+function zcodeBundle(env) {
+  const appDir = env.FABERUN_ZCODE_APP_DIR;
+  if (appDir) return { electron: join(appDir, "zcode"), cli: join(appDir, "resources", "glm", "zcode.cjs") };
+  if (process.platform === "darwin") return ZCODE_MACOS_BUNDLE;
+  return ZCODE_LINUX_BUNDLES.find((bundle) => existsSync(bundle.electron) && existsSync(bundle.cli)) ?? null;
+}
+
 /**
  * The shim body. It runs the bundle through the app's own Electron binary as
  * node because the CLI mis-handles its response path under a system node