faberun 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.20.0",
+  "version": "0.22.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": {
@@ -26,6 +26,7 @@
   "scripts": {
     "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
     "typecheck": "tsc",
+    "check:campaign-brief-render": "node src/report/campaign-brief-html.mjs",
     "test": "node --test --import ./test/scoped-home.mjs --import ./test/git-env.mjs --import ./test/setup.mjs test/*.test.mjs test/*/*.test.mjs",
     "docs": "node src/cli/manual.mjs --write",
     "docs:check": "node src/cli/manual.mjs --check",

package/skills/faberun/references/operations.md

@@ -45,22 +45,22 @@ attempt's sealed sha, the same continuation rule as any other retry.
 One controller drives a run, holding `<run-dir>/controller.lock`: `{pid,
 processStartToken, startedAt, hostname}`. Acquisition is an exclusive create
 with no TTL. A contender treats the lock as stale only once it can prove the
-holder dead — the pid is gone, or its process start token no longer matches
-(pid recycled); anything less is `controller_active` and it exits untouched.
-Takeover renames the lock aside, re-checks the captured record is stale, then
-installs its own; a capture that turns out live is handed back. Worker/judge/
+holder dead — pid gone, or its start token no longer matches (pid recycled);
+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.
-`cancel <run-dir>` signals a live controller first, so its own takeover never
-waits on an expiry.
+`cancel` signals a live controller first, so its takeover never waits.
 
 `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 — it has not proved it needs to be.
+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.
 
 ## Runtime discovery
 

package/src/campaign/brief-cli.mjs

@@ -0,0 +1,174 @@
+/**
+ * `faberun campaign brief generate`: the R7 sharing surface. The campaign CLI
+ * parses argv and dispatches here; every artifact path, the artifact write
+ * order, the stale-HTML cleanup and the renderer failure report live in this
+ * module.
+ *
+ * Generation is deliberately the operator's explicit act. `generate` verifies
+ * the pinned plan, contract and spec through `buildBriefModel`, writes the
+ * Markdown source beside `plan.json`, then asks the optional external renderer
+ * for the portable sibling copy. A successful render and check replaces the
+ * HTML atomically; an absent or failing renderer leaves the Markdown usable,
+ * removes any prior HTML for that phase, and exits with the renderer's named
+ * error. Nothing here writes the spec, the plan, the contract, the
+ * `operator-brief.md` continuity capsule or an external service.
+ *
+ * The usage cutoff is read from recorded evidence -- the newest completed
+ * execution node in this project's pool -- not the wall clock, so regenerating
+ * from the same snapshots produces the same bytes.
+ */
+import { readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { buildBriefModel } from "./campaign-brief.mjs";
+import { resolveCampaign } from "./index.mjs";
+import { readProjectionState } from "./projection.mjs";
+import { renderCampaignBriefMarkdown } from "../report/campaign-brief.mjs";
+import { CampaignBriefRenderError, renderCampaignBriefHtml } from "../report/campaign-brief-html.mjs";
+import { estimateBriefExpense } from "../report/campaign-brief-estimate.mjs";
+import { collectCompletedExecutionNodes } from "../run/usage.mjs";
+import { runsRoot } from "../run/paths.mjs";
+import { writeTextAtomic } from "../run/store.mjs";
+
+const MARKDOWN_FILE = "campaign-brief.md";
+const HTML_FILE = "campaign-brief.md.html";
+// A cutoff far enough ahead that the wide pool carries every recorded node;
+// the pool that feeds the estimate is then filtered to the real 90-day window
+// around the newest recorded completion, not this sentinel.
+const WIDE_WINDOW_DAYS = 36_500;
+const WIDE_CUTOFF = "9999-12-31T23:59:59.999Z";
+
+/** @typedef {import("./campaign-brief.mjs").BriefModel} BriefModel */
+/** @typedef {import("../report/campaign-brief-html.mjs").RenderCampaignBriefHtmlOptions} RenderCampaignBriefHtmlOptions */
+/** @typedef {import("../report/campaign-brief-html.mjs").RenderCampaignBriefHtmlResult} RenderCampaignBriefHtmlResult */
+/** @typedef {import("../run/usage.mjs").CompletedExecutionPool} CompletedExecutionPool */
+
+/**
+ * @typedef {object} BriefGenerateOptions
+ * @property {string} campaignId
+ * @property {unknown} phase
+ * @property {string} [cwd]
+ * @property {string} [runsDir] resolved runs root; defaults to `runsRoot(cwd)`.
+ * @property {string} [mdhtmlBin]
+ * @property {(markdown: string, options: RenderCampaignBriefHtmlOptions) => RenderCampaignBriefHtmlResult} [renderHtml] injectable renderer for tests.
+ * @property {(line: string) => void} [stdout]
+ * @property {(line: string) => void} [stderr]
+ */
+
+/**
+ * @typedef {object} BriefGenerateResult
+ * @property {BriefModel} model
+ * @property {string} markdownPath absolute
+ * @property {string|null} htmlPath absolute when the render succeeded, else null
+ * @property {string|null} code the renderer's named error, or null on success
+ */
+
+/**
+ * Generate the Campaign Brief for one frozen phase plan. The Markdown is
+ * always written before the renderer is asked, and the HTML only survives a
+ * successful build, check, audit and source round-trip. A renderer failure is
+ * reported on stderr with its stable code, the Markdown path is printed, and
+ * any prior HTML for the phase is removed.
+ *
+ * @param {BriefGenerateOptions} options
+ * @returns {BriefGenerateResult}
+ */
+export function generateCampaignBrief(options) {
+  const campaignId = options.campaignId;
+  const cwd = resolve(options.cwd ?? ".");
+  const runsDir = options.runsDir ?? runsRoot(cwd);
+  const { path: campaignPath, campaign } = resolveCampaign(runsDir, campaignId);
+  const phase = requirePhase(options.phase);
+  const planDir = join(campaignPath, "plans", phase);
+  const markdownPath = join(planDir, MARKDOWN_FILE);
+  const htmlPath = join(planDir, HTML_FILE);
+  const stdout = options.stdout ?? ((line) => process.stdout.write(`${line}\n`));
+  const stderr = options.stderr ?? ((line) => process.stderr.write(`${line}\n`));
+
+  const { state, cursor: journalCursor } = readProjectionState(campaignPath, campaign);
+  const pool = collectCompletedExecutionNodes({ runsRoot: runsDir, cutoff: WIDE_CUTOFF, windowDays: WIDE_WINDOW_DAYS });
+  const usageSampleCutoff = newestCompletedAt(pool);
+  const contract = readContractTolerant(join(planDir, "contract.json"));
+  const estimate = contract === null ? undefined : estimateBriefExpense({ contract, cutoff: usageSampleCutoff, pool });
+  const model = buildBriefModel({
+    campaignId,
+    planPath: join(planDir, "plan.json"),
+    cwd,
+    projection: state,
+    journalCursor,
+    usageSampleCutoff,
+    estimate,
+  });
+
+  const markdown = renderCampaignBriefMarkdown(model);
+  writeTextAtomic(markdownPath, markdown);
+
+  const renderHtml = options.renderHtml ?? renderCampaignBriefHtml;
+  try {
+    renderHtml(markdown, { outputPath: htmlPath, title: `Campaign brief — ${campaignId}`, mdhtmlBin: options.mdhtmlBin, cwd });
+  } catch (error) {
+    const code = error instanceof CampaignBriefRenderError ? error.code : "CAMPAIGN_BRIEF_RENDER_FAILED";
+    rmSync(htmlPath, { force: true });
+    stderr(`[fail] ${code} · ${error instanceof Error ? error.message : String(error)}`);
+    stdout(`[brief] markdown · ${markdownPath}`);
+    process.exitCode = 1;
+    return { model, markdownPath, htmlPath: null, code };
+  }
+  stdout(`[brief] markdown · ${markdownPath}`);
+  stdout(`[brief] html · ${htmlPath}`);
+  return { model, markdownPath, htmlPath, code: null };
+}
+
+/**
+ * `--phase` names one directory under `<campaignDir>/plans/`; anything with a
+ * path separator or a dot segment would escape it.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function requirePhase(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError("campaign brief generate requires --phase <phase>");
+  }
+  if (value === "." || value === ".." || value.includes("/") || value.includes("\\")) {
+    throw new TypeError("--phase must be a single path segment");
+  }
+  return value;
+}
+
+/**
+ * The newest completion in the wide pool, as the recorded usage cutoff. A pool
+ * with no readable completion has no cutoff, which the estimate reports as
+ * `insufficient data` rather than inventing one.
+ *
+ * @param {CompletedExecutionPool} pool
+ * @returns {string|null}
+ */
+function newestCompletedAt(pool) {
+  let newest = null;
+  for (const node of pool.nodes) {
+    if (typeof node.completedAt !== "string") continue;
+    const completedMs = Date.parse(node.completedAt);
+    if (!Number.isFinite(completedMs)) continue;
+    if (newest === null || completedMs > newest) newest = completedMs;
+  }
+  return newest === null ? null : new Date(newest).toISOString();
+}
+
+/**
+ * Read the sibling contract the plan froze, tolerating anything unreadable:
+ * `buildBriefModel` owns the refusal and names the exact missing or mismatched
+ * input, so a malformed contract here simply supplies no estimate and lets the
+ * model raise its typed error.
+ *
+ * @param {string} path
+ * @returns {Record<string, any>|null}
+ */
+function readContractTolerant(path) {
+  let value;
+  try {
+    value = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/src/campaign/brief-text.mjs

@@ -0,0 +1,96 @@
+/**
+ * Campaign Brief text parsing and list normalization. Separate from the model
+ * builder because these small Markdown readers are a distinct boundary from
+ * the frozen-plan facts they shape into the brief.
+ */
+
+/** @typedef {{measure: string, target: string, evidence: string}} BriefSuccessCriterion */
+/** @typedef {{risk: string, impact: string, mitigation: string}} BriefRisk */
+
+/**
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function bulletLines(body) {
+  return body
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- "))
+    .map((line) => line.slice(2).trim())
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * @param {string} body
+ * @returns {BriefSuccessCriterion[]}
+ */
+export function successCriteriaRows(body) {
+  const rows = body.split("\n").filter((line) => line.trim().startsWith("|"));
+  if (rows.length < 3) return [];
+  const header = tableCells(rows[0]).map((cell) => cell.toLowerCase());
+  const measureIndex = header.findIndex((cell) => cell.includes("measure"));
+  const targetIndex = header.findIndex((cell) => cell.includes("target"));
+  const evidenceIndex = header.findIndex((cell) => cell.includes("evidence"));
+  return rows.slice(2).map((row) => {
+    const cells = tableCells(row);
+    return {
+      measure: measureIndex >= 0 ? cells[measureIndex] ?? "" : "",
+      target: targetIndex >= 0 ? cells[targetIndex] ?? "" : "",
+      evidence: evidenceIndex >= 0 ? cells[evidenceIndex] ?? "" : "",
+    };
+  }).filter((criterion) => criterion.measure.length > 0 || criterion.target.length > 0);
+}
+
+/**
+ * @param {string} body
+ * @returns {BriefRisk[]}
+ */
+export function riskRows(body) {
+  const rows = body.split("\n").filter((line) => line.trim().startsWith("|"));
+  if (rows.length < 3) return [];
+  const header = tableCells(rows[0]).map((cell) => cell.toLowerCase());
+  const riskIndex = header.findIndex((cell) => cell.includes("risk"));
+  const impactIndex = header.findIndex((cell) => cell.includes("impact"));
+  const mitigationIndex = header.findIndex((cell) => cell.includes("mitigation"));
+  return rows.slice(2).map((row) => {
+    const cells = tableCells(row);
+    return {
+      risk: riskIndex >= 0 ? cells[riskIndex] ?? "" : "",
+      impact: impactIndex >= 0 ? cells[impactIndex] ?? "" : "",
+      mitigation: mitigationIndex >= 0 ? cells[mitigationIndex] ?? "" : "",
+    };
+  }).filter((risk) => risk.risk.length > 0);
+}
+
+/** @param {string} row @returns {string[]} */
+function tableCells(row) {
+  const trimmed = row.trim();
+  const withoutLeading = trimmed.startsWith("|") ? trimmed.slice(1) : trimmed;
+  const withoutTrailing = withoutLeading.endsWith("|") ? withoutLeading.slice(0, -1) : withoutLeading;
+  return withoutTrailing.split("|").map((value) => value.trim());
+}
+
+/** @param {string} text @returns {string|null} */
+export function firstSentence(text) {
+  const collapsed = text.replace(/\s+/gu, " ").trim();
+  if (!collapsed) return null;
+  const match = /^(.*?[.!?])(?:\s|$)/u.exec(collapsed);
+  return (match ? match[1] : collapsed).trim();
+}
+
+/** @param {unknown} value @returns {any[]} */
+export function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+/** @template T @param {T[]} values @returns {T[]} */
+export function unique(values) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}