karajan-code 3.5.1 → 3.7.0

package/packages/ai-trash/src/index.js

@@ -0,0 +1,14 @@
+// @karajan/ai-trash — public entry (skeleton).
+// Real surface (snapshot, restore, list, manifest) lands in KJC-TSK-0388
+// commits 2-6 and KJC-TSK-0389 (git ops). For now we expose a single
+// `version` export so consumers / tests can confirm the package loads.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+
+export const version = pkg.version;
+export const name = pkg.name;

package/packages/ai-trash/src/install.js

@@ -0,0 +1,52 @@
+// Claude Code settings patcher (KJC-TSK-0390 commit 3). Idempotently
+// adds a PreToolUse hook entry that pipes Bash commands through
+// `kj-trash hook`. Preserves any unrelated keys and existing hooks so
+// the user's other settings are untouched.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+export const HOOK_COMMAND = "kj-trash hook";
+const MATCHER = "Bash";
+
+async function readSettings(path) {
+  try {
+    return JSON.parse(await fs.readFile(path, "utf8"));
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+function hasHookCommand(matcherEntry, command) {
+  return (matcherEntry.hooks ?? []).some((h) => h.type === "command" && h.command === command);
+}
+
+export function patchSettings(settings, command = HOOK_COMMAND, matcher = MATCHER) {
+  const next = { ...settings };
+  next.hooks = { ...(next.hooks ?? {}) };
+  const preToolUse = Array.isArray(next.hooks.PreToolUse) ? next.hooks.PreToolUse.slice() : [];
+  let entry = preToolUse.find((e) => e.matcher === matcher);
+  let mutated = false;
+  if (!entry) {
+    entry = { matcher, hooks: [{ type: "command", command }] };
+    preToolUse.push(entry);
+    mutated = true;
+  } else if (!hasHookCommand(entry, command)) {
+    entry.hooks = [...(entry.hooks ?? []), { type: "command", command }];
+    mutated = true;
+  }
+  next.hooks.PreToolUse = preToolUse;
+  return { settings: next, mutated };
+}
+
+export async function installClaudeCodeHook({ path = DEFAULT_SETTINGS_PATH, command = HOOK_COMMAND } = {}) {
+  const settings = await readSettings(path);
+  const { settings: next, mutated } = patchSettings(settings, command);
+  if (!mutated) return { path, mutated: false };
+  await fs.mkdir(dirname(path), { recursive: true });
+  await fs.writeFile(path, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8" });
+  return { path, mutated: true };
+}

package/packages/ai-trash/src/logger.js

@@ -0,0 +1,60 @@
+// Append-only JSONL audit log for the trash store. Events are written one
+// JSON object per line so the file can be `tail -f`-d and parsed
+// line-by-line without holding the whole log in memory.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { lockdownFile } from "./permissions.js";
+
+const HOME = homedir();
+
+function redactPath(p) {
+  if (typeof p !== "string" || !p) return p;
+  if (p === HOME) return "~";
+  if (p.startsWith(`${HOME}/`)) return `~/${p.slice(HOME.length + 1)}`;
+  return p;
+}
+
+function redactPayload(payload) {
+  if (!payload || typeof payload !== "object") return payload;
+  const out = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (typeof v === "string" && (k.includes("Path") || k === "cwd")) {
+      out[k] = redactPath(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function appendLogEntry(rootDir, event, payload = {}) {
+  if (!event) throw new Error("ai-trash: log event required");
+  const file = join(rootDir, "log.jsonl");
+  const line =
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      event,
+      ...redactPayload(payload),
+    }) + "\n";
+  await fs.mkdir(rootDir, { recursive: true });
+  await fs.appendFile(file, line, { encoding: "utf8", mode: 0o600 });
+  await lockdownFile(file);
+}
+
+export async function readLog(rootDir) {
+  const file = join(rootDir, "log.jsonl");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export { redactPath };

package/packages/ai-trash/src/manifest.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { ulid } from "./ulid.js";
+
+export const SCHEMA_VERSION = 1;
+
+export async function loadManifest(rootDir) {
+  const file = join(rootDir, "manifest.json");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== SCHEMA_VERSION) {
+      throw new Error(`ai-trash: unsupported manifest schemaVersion ${parsed?.schemaVersion}`);
+    }
+    if (!Array.isArray(parsed.entries)) parsed.entries = [];
+    return parsed;
+  } catch (err) {
+    if (err.code === "ENOENT") return { schemaVersion: SCHEMA_VERSION, entries: [] };
+    throw err;
+  }
+}
+
+export async function saveManifest(rootDir, manifest) {
+  const file = join(rootDir, "manifest.json");
+  await fs.mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(manifest, null, 2), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.rename(tmp, file);
+}
+
+export function addEntry(manifest, partial) {
+  if (!partial?.sourcePath) throw new Error("ai-trash: sourcePath required");
+  if (typeof partial.sizeBytes !== "number" || partial.sizeBytes < 0) {
+    throw new Error("ai-trash: sizeBytes must be a non-negative number");
+  }
+  const now = Date.now();
+  const entry = {
+    id: ulid(now),
+    createdAt: now,
+    sourcePath: partial.sourcePath,
+    snapshotPath: partial.snapshotPath ?? null,
+    sizeBytes: partial.sizeBytes,
+    command: partial.command ?? null,
+    origin: partial.origin ?? "unknown",
+  };
+  manifest.entries.push(entry);
+  return entry;
+}
+
+export function listEntries(manifest) {
+  return [...manifest.entries].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function removeEntry(manifest, id) {
+  const idx = manifest.entries.findIndex((e) => e.id === id);
+  if (idx < 0) return null;
+  return manifest.entries.splice(idx, 1)[0];
+}
+
+export function expireBefore(manifest, cutoffMs) {
+  const expired = [];
+  manifest.entries = manifest.entries.filter((e) => {
+    if (e.createdAt < cutoffMs) {
+      expired.push(e);
+      return false;
+    }
+    return true;
+  });
+  return expired;
+}
+
+export function enforceLruQuota(manifest, maxBytes) {
+  if (typeof maxBytes !== "number" || maxBytes < 0) {
+    throw new Error("ai-trash: maxBytes must be a non-negative number");
+  }
+  const sorted = listEntries(manifest);
+  const total = sorted.reduce((sum, e) => sum + e.sizeBytes, 0);
+  const evicted = [];
+  let running = total;
+  for (const entry of sorted) {
+    if (running <= maxBytes) break;
+    evicted.push(entry);
+    running -= entry.sizeBytes;
+  }
+  const evictedIds = new Set(evicted.map((e) => e.id));
+  manifest.entries = manifest.entries.filter((e) => !evictedIds.has(e.id));
+  return evicted;
+}

package/packages/ai-trash/src/permissions.js

@@ -0,0 +1,26 @@
+import { promises as fs } from "node:fs";
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+export async function ensureSecureDir(path) {
+  await fs.mkdir(path, { recursive: true, mode: DIR_MODE });
+  await fs.chmod(path, DIR_MODE);
+}
+
+export async function lockdownFile(path) {
+  await fs.chmod(path, FILE_MODE);
+}
+
+export async function assertOwnedByCurrentUser(path) {
+  if (process.platform === "win32") return;
+  const stats = await fs.stat(path);
+  if (typeof process.getuid !== "function") return;
+  if (stats.uid !== process.getuid()) {
+    throw new Error(
+      `ai-trash: ${path} is owned by uid ${stats.uid}, expected ${process.getuid()}`
+    );
+  }
+}
+
+export { DIR_MODE, FILE_MODE };

package/packages/ai-trash/src/snapshot.js

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import { basename, join } from "node:path";
+import { ulid } from "./ulid.js";
+import { ensureSecureDir, lockdownFile } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+async function statOrNull(path) {
+  try {
+    return await fs.lstat(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function snapshotFile(rootDir, sourcePath, options = {}) {
+  const stat = await statOrNull(sourcePath);
+  if (!stat) throw new Error(`ai-trash: source not found: ${sourcePath}`);
+  if (stat.isDirectory()) {
+    throw new Error("ai-trash: directory snapshots not implemented in MVP");
+  }
+  const id = ulid();
+  const storeDir = join(rootDir, "store", id);
+  await ensureSecureDir(storeDir);
+  const snapshotPath = join(storeDir, basename(sourcePath));
+  await fs.copyFile(sourcePath, snapshotPath);
+  await lockdownFile(snapshotPath);
+  const entry = {
+    id,
+    createdAt: Date.now(),
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+    command: options.command ?? null,
+    origin: options.origin ?? "unknown",
+  };
+  await appendLogEntry(rootDir, "snapshot.create", {
+    id,
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+  });
+  return entry;
+}
+
+export async function restoreSnapshot(rootDir, entry, targetPath) {
+  const target = targetPath ?? entry.sourcePath;
+  const exists = await statOrNull(target);
+  if (exists) throw new Error(`ai-trash: refusing to overwrite ${target}`);
+  await fs.mkdir(join(target, ".."), { recursive: true });
+  await fs.copyFile(entry.snapshotPath, target);
+  await appendLogEntry(rootDir, "snapshot.restore", {
+    id: entry.id,
+    snapshotPath: entry.snapshotPath,
+    targetPath: target,
+  });
+  return target;
+}
+
+export async function purgeSnapshot(rootDir, entry) {
+  await fs.rm(join(rootDir, "store", entry.id), { recursive: true, force: true });
+  await appendLogEntry(rootDir, "snapshot.purge", {
+    id: entry.id,
+    sizeBytes: entry.sizeBytes,
+  });
+}

package/packages/ai-trash/src/ulid.js

@@ -0,0 +1,66 @@
+// Tiny ULID generator (Crockford base32, 26 chars, monotonic within ms).
+// We keep this self-contained to avoid pulling a runtime dep into the
+// safety-net package — fewer transitive deps = fewer supply-chain surfaces
+// that an attacker could pivot through to reach the trash store.
+
+import { randomBytes } from "node:crypto";
+
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+let lastMs = 0;
+let lastRandom = new Uint8Array(10);
+
+function encodeTime(ms) {
+  let out = "";
+  for (let i = 9; i >= 0; i--) {
+    out = ENCODING[ms % 32] + out;
+    ms = Math.floor(ms / 32);
+  }
+  return out;
+}
+
+function encodeRandom(bytes) {
+  let out = "";
+  for (let i = 0; i < 16; i++) {
+    const byteIndex = Math.floor((i * 5) / 8);
+    const bitOffset = (i * 5) % 8;
+    const hi = bytes[byteIndex] ?? 0;
+    const lo = bytes[byteIndex + 1] ?? 0;
+    const value = ((hi << 8) | lo) >> (11 - bitOffset);
+    out += ENCODING[value & 31];
+  }
+  return out;
+}
+
+function bumpRandom(buf) {
+  for (let i = buf.length - 1; i >= 0; i--) {
+    if (buf[i] === 0xff) {
+      buf[i] = 0;
+      continue;
+    }
+    buf[i] += 1;
+    return buf;
+  }
+  throw new Error("ulid: random overflow within the same millisecond");
+}
+
+export function ulid(nowMs = Date.now()) {
+  if (nowMs === lastMs) {
+    lastRandom = bumpRandom(lastRandom);
+  } else {
+    lastMs = nowMs;
+    lastRandom = new Uint8Array(randomBytes(10));
+  }
+  return encodeTime(nowMs) + encodeRandom(lastRandom);
+}
+
+export function decodeTimeFromUlid(id) {
+  const slice = id.slice(0, 10);
+  let ms = 0;
+  for (const ch of slice) {
+    const v = ENCODING.indexOf(ch);
+    if (v < 0) throw new Error(`ulid: invalid char ${ch}`);
+    ms = ms * 32 + v;
+  }
+  return ms;
+}

package/packages/hu-board/src/db.js

@@ -361,6 +361,17 @@ export function getDb() {
   return db;
 }
 
+/**
+ * Lazily initialise the DB if it isn't open yet (KJC-BUG-0090). The cost
+ * writers run from `kj run`/`kj autorun` paths that may never start the board
+ * (which is what normally calls initDb), so cost writes failed with
+ * "Database not initialized". This makes those writers self-sufficient.
+ */
+export function ensureDb() {
+  if (!db) initDb();
+  return db;
+}
+
 /**
  * Inserts or updates a project record.
  * @param {{ id: string, name?: string, first_seen?: string, last_activity?: string, total_stories?: number }} project

package/scripts/verify-pack.mjs

@@ -18,7 +18,7 @@
  * this from prepublishOnly does not recurse.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -101,6 +101,19 @@ try {
   }
   console.log("verify-pack: sqlite-vec + @karajan/core resolve ✓");
 
+  // 4. kj-trash (ai-trash safety binary) must ship + link onto PATH and boot
+  // without a module-resolution crash. It was silently absent from the tarball
+  // until KJC-BUG-0089 — every npm user got "kj-trash not found".
+  const trashBin = path.join(tmpDir, "node_modules", ".bin", "kj-trash");
+  if (!fs.existsSync(trashBin)) fail(`kj-trash binary missing after install: ${trashBin}`);
+  const trash = spawnSync(trashBin, ["--help"], { encoding: "utf8", env: childEnv });
+  // The CLI exits 2 on --help (usage); only a real crash (module not found, or
+  // an unexpected non-0/2 exit) is a failure.
+  if (![0, 2].includes(trash.status) || /ERR_MODULE_NOT_FOUND|Cannot find/.test(trash.stderr || "")) {
+    fail("`kj-trash --help` crashed on a clean install", trash.stderr || `exit ${trash.status}`);
+  }
+  console.log("verify-pack: kj-trash ships + boots ✓");
+
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });

package/src/autonomy/arbiter-role.js

@@ -0,0 +1,71 @@
+/**
+ * ArbiterRole — the autonomous decision authority that resolves agent conflicts
+ * by picking the least-bad verdict (KJC-TSK-0573, épica KJC-PCS-0062).
+ *
+ * Extends AgentRole (so it inherits Brain recovery / standby) following the
+ * TriageRole pattern: a cheap decisor model emits a closed-set verdict, and any
+ * parse failure degrades to BLOCK_AND_CONTINUE — the pipeline never crashes and
+ * never blocks on the Arbiter.
+ */
+
+import { AgentRole } from "../roles/agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { buildArbiterPrompt, VERDICTS } from "../prompts/arbiter.js";
+
+const CONSERVATIVE = "BLOCK_AND_CONTINUE";
+const VERDICT_SET = new Set(VERDICTS);
+
+function clampConfidence(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+}
+
+export class ArbiterRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "arbiter" });
+  }
+
+  async buildPrompt(input) {
+    return { prompt: buildArbiterPrompt(input) };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const verdict = VERDICT_SET.has(parsed?.verdict) ? parsed.verdict : CONSERVATIVE;
+    return {
+      verdict,
+      confidence: clampConfidence(parsed?.confidence),
+      rationale: String(parsed?.rationale || "").trim() || "no rationale",
+      defect: parsed?.defect ? String(parsed.defect).trim() : null,
+      directive: parsed?.directive ? String(parsed.directive).trim() : null,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    return `Arbiter: ${VERDICT_SET.has(parsed?.verdict) ? parsed.verdict : CONSERVATIVE}`;
+  }
+
+  // Never crash on garbage: degrade to the conservative verdict so the pipeline
+  // moves on instead of aborting (ok:true keeps the run alive).
+  handleParseNull(agentResult, provider) {
+    return this.degraded(agentResult, provider, "unstructured output");
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degraded(agentResult, provider, err?.message || "parse error");
+  }
+
+  degraded(agentResult, provider, why) {
+    this.logger?.warn?.(`[arbiter] ${why} → ${CONSERVATIVE} (conservative)`);
+    return {
+      ok: true,
+      result: { verdict: CONSERVATIVE, confidence: 0, rationale: `degraded: ${why}`, defect: null, directive: null, provider },
+      summary: `Arbiter: ${CONSERVATIVE} (degraded)`,
+      usage: agentResult.usage,
+    };
+  }
+}

package/src/autonomy/arbiter.js

@@ -0,0 +1,22 @@
+/**
+ * createArbiter — adapt ArbiterRole to the function the decision-resolver
+ * injects (KJC-TSK-0573). The resolver calls `arbiter(req)` and expects
+ * `{ choice, rationale, ... }`; here `choice` is the Arbiter's verdict, which
+ * the resolver then validates against the caller's options (AUTO-A).
+ */
+
+import { ArbiterRole } from "./arbiter-role.js";
+
+export function createArbiter({ config = {}, logger = console, createAgentFn = null } = {}) {
+  return async function arbiter(req) {
+    const role = new ArbiterRole({ config, logger, createAgentFn });
+    const { result } = await role.execute(req);
+    return {
+      choice: result.verdict,
+      rationale: result.rationale,
+      confidence: result.confidence,
+      defect: result.defect,
+      directive: result.directive,
+    };
+  };
+}

package/src/autonomy/decider.js

@@ -0,0 +1,18 @@
+/**
+ * buildDecider — wire the active autonomy level to a ready decision resolver
+ * (KJC-TSK-0572, design in docs/specs/autonomous-delivery.md §5).
+ *
+ * interactive → the human `ask`; assisted/autonomous → the Arbiter (AUTO-B).
+ * Consumers (spec-review, reviewer, checkpoint…) call `resolve(...)` instead of
+ * prompting directly, so the autonomy level decides who answers in one place.
+ */
+
+import { createDecisionResolver } from "./decision-resolver.js";
+import { resolveAutonomy } from "./policy.js";
+import { createArbiter } from "./arbiter.js";
+
+export function buildDecider({ config = {}, flags = {}, ask = null, env = process.env, logger = console, createAgentFn = null } = {}) {
+  const autonomy = resolveAutonomy({ config, flags, env });
+  const arbiter = autonomy === "interactive" ? null : createArbiter({ config, logger, createAgentFn });
+  return { autonomy, resolve: createDecisionResolver({ autonomy, ask, arbiter, logger }) };
+}

package/src/autonomy/decision-resolver.js

@@ -0,0 +1,58 @@
+/**
+ * autonomy/decision-resolver — the single choke point for every pipeline
+ * question (KJC-TSK-0572, design in docs/specs/autonomous-delivery.md §5).
+ *
+ * Today the "ask a human" logic is scattered (spec-review, checkpoint,
+ * reviewer, board-bridge). This unifies it: callers ask `resolveDecision`
+ * instead of prompting directly, and the autonomy level decides who answers —
+ * the human (`ask`) or the Arbiter (`arbiter`, injected by AUTO-B).
+ *
+ * INVARIANT: in `autonomous` mode the resolver NEVER returns a null choice and
+ * NEVER blocks — if the Arbiter can't decide it degrades to the option flagged
+ * `conservative` (or the first option). Decisions are always traced.
+ */
+
+import { RISK, usesArbiter } from "./policy.js";
+
+/** Pick the safe fallback: the option flagged conservative, else the first. */
+function conservativeOf(options) {
+  return options.find((o) => o.conservative) ?? options[0] ?? null;
+}
+
+function decision(choice, rationale, source) {
+  return { choice: choice ?? null, rationale, source };
+}
+
+/**
+ * Build a resolver bound to an autonomy level and its two answer sources.
+ *
+ * @param {object} opts
+ * @param {string} opts.autonomy - interactive | assisted | autonomous
+ * @param {(question: string, context?: object) => Promise<string|null>} [opts.ask] - human prompt
+ * @param {(input: object) => Promise<{choice: string, rationale?: string}>} [opts.arbiter] - AUTO-B
+ * @returns {(req: object) => Promise<{choice, rationale, source}>}
+ */
+export function createDecisionResolver({ autonomy = "interactive", ask = null, arbiter = null, logger = console } = {}) {
+  return async function resolveDecision({ question, options = [], context = null, risk = RISK.LOW } = {}) {
+    const fallback = conservativeOf(options);
+
+    // Human path: interactive, or assisted with a high-risk decision.
+    if (!usesArbiter(autonomy, risk)) {
+      const answer = ask ? await ask(question, context) : null;
+      return decision(answer, "human", "human");
+    }
+
+    // Arbiter path: must always yield a valid choice, never block.
+    if (!arbiter) return decision(fallback?.value, "no arbiter available → conservative", "fallback");
+    let verdict;
+    try {
+      verdict = await arbiter({ question, options, context, risk });
+    } catch (err) {
+      logger.warn?.(`decision-resolver: arbiter failed (${err.message}) → conservative`);
+      return decision(fallback?.value, "arbiter error → conservative", "fallback");
+    }
+    const valid = verdict && options.some((o) => o.value === verdict.choice);
+    if (!valid) return decision(fallback?.value, "arbiter gave no valid choice → conservative", "fallback");
+    return decision(verdict.choice, verdict.rationale ?? "arbiter", "arbiter");
+  };
+}

package/src/autonomy/outcome-report.js

@@ -0,0 +1,55 @@
+/**
+ * outcome-report — the auditable "meets the ask, with known defects" report
+ * for an autonomous run (KJC-TSK-0577, design in docs/specs/autonomous-delivery.md §10).
+ *
+ * Pure: builds a serializable outcome from the run results + Arbiter decisions,
+ * and renders it as lines (or the structure is emitted as --json). The point is
+ * that an imperfect-but-delivered result is explicit and auditable: which HUs
+ * met the ask, what the Arbiter decided, and what debt remains.
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.planRef]
+ * @param {boolean} opts.delivered - the run met the minimum ask
+ * @param {Array<{id, title?, met: boolean, note?}>} [opts.hus]
+ * @param {Array<{verdict, rationale, hu?, defect?}>} [opts.decisions] - Arbiter log
+ */
+export function buildOutcome({ planRef = null, delivered = false, hus = [], decisions = [] } = {}) {
+  const met = hus.filter((h) => h.met).length;
+  const residualDefects = [
+    ...hus.filter((h) => !h.met).map((h) => ({ hu: h.id, detail: h.note || "acceptance criteria not fully met" })),
+    ...decisions.filter((d) => d.defect).map((d) => ({ hu: d.hu ?? null, detail: d.defect })),
+  ];
+  return {
+    verdict: delivered ? "DELIVERED" : "INCOMPLETE",
+    planRef,
+    hus: { total: hus.length, met, unmet: hus.length - met },
+    decisions,
+    residualDefects,
+  };
+}
+
+/** Render an outcome (from buildOutcome) as human-readable lines. */
+export function formatOutcomeReport(outcome) {
+  const lines = [
+    `kj autorun — outcome: ${outcome.verdict}`,
+    `  plan: ${outcome.planRef ?? "?"}`,
+    `  HUs:  ${outcome.hus.met}/${outcome.hus.total} met the ask`,
+  ];
+  if (outcome.decisions?.length) {
+    lines.push("  Decisions (Arbiter — least-bad calls):");
+    for (const d of outcome.decisions) {
+      lines.push(`    • ${d.verdict}${d.hu ? ` [${d.hu}]` : ""} — ${d.rationale}`);
+    }
+  }
+  if (outcome.residualDefects?.length) {
+    lines.push("  Known defects (delivered with debt):");
+    for (const def of outcome.residualDefects) {
+      lines.push(`    • ${def.hu ? `[${def.hu}] ` : ""}${def.detail}`);
+    }
+  } else {
+    lines.push("  No residual defects recorded.");
+  }
+  return lines;
+}