@forwardimpact/libwiki 0.2.11 → 0.2.12

package/src/commands/fix.js

@@ -1,7 +1,6 @@
-import fsAsync from "node:fs/promises";
 import path from "node:path";
 import { Writable } from "node:stream";
-import { Finder, emitFindingsText, runRules } from "@forwardimpact/libutil";
+import { emitFindingsText, runRules } from "@forwardimpact/libutil";
 import {
   createAgentRunner,
   composeProfilePrompt,
@@ -9,56 +8,136 @@ import {
 } from "@forwardimpact/libeval";
 import { RULES } from "../audit/rules.js";
 import { buildContext, resolveScope } from "../audit/scopes.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-/** Run the wiki audit and auto-fix findings via a Haiku-powered AgentRunner. */
-export async function runFixCommand(values, _args, _cli) {
-  const finder = new Finder(fsAsync, { debug() {} }, process);
-  const projectRoot = finder.findProjectRoot(process.cwd());
-  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
-  const today = values.today || new Date().toISOString().slice(0, 10);
+// The agent edits, we re-audit, and resume on whatever still fails. Cap the
+// rounds so a finding the agent cannot resolve (e.g. a budget needing
+// `fit-wiki rotate`, which it has no Bash to run) fails loudly, not forever.
+const MAX_ROUNDS = 3;
 
-  const ctx = buildContext({ wikiRoot, today });
-  const findings = runRules(RULES, ctx, { resolveScope });
+/**
+ * Every rule governing a scope with an open finding, as `id — hint` lines.
+ * Handing the agent the full contract for the files it edits — not just the
+ * failing rules — stops it fixing one finding by breaking another (dropping
+ * the `**Last run**:` line, appending a section after `## Open Blockers`, …).
+ */
+function invariantContract(findings) {
+  const scopes = new Set(
+    findings.map((f) => RULES.find((r) => r.id === f.id)?.scope),
+  );
+  return RULES.filter((r) => scopes.has(r.scope) && r.hint).map(
+    (r) => `- ${r.id} — ${r.hint}`,
+  );
+}
 
-  if (findings.length === 0) {
-    process.stdout.write("nothing to fix\n");
-    return;
+/**
+ * The opening task: the findings, the invariant contract, and the two things
+ * the rule hints don't cover — where trimmed history goes, and to prefer a
+ * single Write.
+ */
+function composeTask(findings, wikiRoot, projectRoot) {
+  return [
+    `Fix these wiki audit findings by editing files under ${wikiRoot}.`,
+    ``,
+    emitFindingsText(findings, { cwd: projectRoot }),
+    ``,
+    `All of these invariants must hold when you finish — never fix one finding`,
+    `by breaking another:`,
+    ...invariantContract(findings),
+    ``,
+    `Move history out of an over-budget summary into the agent's weekly-log`,
+    `file (wiki/<agent>-YYYY-Www.md), never a new summary section. Prefer a`,
+    `single Write over many Edits.`,
+  ].join("\n");
+}
+
+/** The resume task: the findings that survived the last edit. */
+function composeFollowup(findings, projectRoot) {
+  return [
+    `The wiki still fails the audit. Remaining findings:`,
+    ``,
+    emitFindingsText(findings, { cwd: projectRoot }),
+    ``,
+    `Fix every one without breaking any invariant listed earlier.`,
+  ].join("\n");
+}
+
+/**
+ * Surface a round's agent error, if any. Returns true when it is fatal: a
+ * missing sessionId means the process never started (e.g. the SDK refused
+ * bypass-permissions as root), so there is nothing to resume. A turn-limit or
+ * transient error keeps its session and may have made partial progress, so it
+ * is noted but not fatal — the re-audit decides.
+ */
+function isFatalError(result, round, err) {
+  if (!result.error) return false;
+  if (!result.sessionId) {
+    err(`fit-wiki fix: agent run failed: ${result.error.message}\n`);
+    return true;
   }
+  err(`fit-wiki fix: round ${round} agent error: ${result.error.message}\n`);
+  return false;
+}
 
-  const auditText = emitFindingsText(findings, { cwd: projectRoot });
-  const redactor = createRedactor();
-  const devNull = new Writable({
-    write(_c, _e, cb) {
-      cb();
-    },
-  });
+/** Run the wiki audit and auto-fix findings via a Haiku-powered AgentRunner. */
+export async function runFixCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const projectRoot = resolveProjectRoot(runtime);
+  const wikiRoot = ctx.options["wiki-root"] || path.join(projectRoot, "wiki");
+  const today = ctx.options.today || currentDayIso(runtime);
+  const out = (s) => runtime.proc.stdout.write(s);
+  const err = (s) => runtime.proc.stderr.write(s);
 
-  const systemPrompt = composeProfilePrompt("technical-writer", {
-    profilesDir: path.resolve(projectRoot, ".claude/agents"),
-  });
+  // The agent's edits change the result, so re-read and re-audit each round.
+  const audit = () =>
+    runRules(RULES, buildContext({ wikiRoot, today, fs: runtime.fsSync }), {
+      resolveScope,
+    });
 
-  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+  let findings = audit();
+  if (findings.length === 0) {
+    out("nothing to fix\n");
+    return { ok: true };
+  }
 
+  const query =
+    ctx.deps.query ?? (await import("@anthropic-ai/claude-agent-sdk")).query;
   const runner = createAgentRunner({
     cwd: projectRoot,
     query,
-    output: devNull,
+    output: new Writable({ write: (_c, _e, cb) => cb() }),
     model: "claude-haiku-4-5-20251001",
-    maxTurns: 15,
+    maxTurns: 30,
     allowedTools: ["Read", "Write", "Edit"],
     settingSources: ["project"],
-    systemPrompt,
-    redactor,
+    systemPrompt: composeProfilePrompt("technical-writer", {
+      profilesDir: path.resolve(projectRoot, ".claude/agents"),
+    }),
+    redactor: createRedactor(),
   });
 
-  const task = [
-    `Fix these wiki audit findings.`,
-    `The wiki root is ${wikiRoot}.`,
-    ``,
-    auditText,
-  ].join("\n");
+  // The audit is the verdict, not the agent's self-report: run, re-audit, and
+  // resume the session on whatever still fails until clean or out of rounds.
+  // Resuming also extends the turn budget for a trim too large for one round.
+  let task = composeTask(findings, wikiRoot, projectRoot);
+  for (let round = 0; round < MAX_ROUNDS; round++) {
+    const result =
+      round === 0 ? await runner.run(task) : await runner.resume(task);
+    if (result.text) out(result.text + "\n");
+    if (isFatalError(result, round, err)) return { ok: false, code: 1 };
+
+    findings = audit();
+    if (findings.length === 0) {
+      out("fixed: wiki audit is clean\n");
+      return { ok: true, code: 0 };
+    }
+    task = composeFollowup(findings, projectRoot);
+  }
 
-  const result = await runner.run(task);
-  if (result.text) process.stdout.write(result.text + "\n");
-  process.exit(result.success ? 0 : 1);
+  err(
+    `fit-wiki fix: ${findings.length} finding(s) remain after ${MAX_ROUNDS} round(s):\n` +
+      emitFindingsText(findings, { cwd: projectRoot }),
+  );
+  return { ok: false, code: 1 };
 }

package/src/commands/inbox.js

@@ -1,26 +1,20 @@
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import fsAsync from "node:fs/promises";
 import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
 import {
   MEMO_INBOX_MARKER,
   PRIORITY_INDEX_HEADING,
   PRIORITY_INDEX_TABLE_HEADER,
 } from "../constants.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
-function projectRoot() {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, process);
-  return finder.findProjectRoot(process.cwd());
-}
-
-function paths(values) {
-  const root = projectRoot();
-  const wikiRoot = values["wiki-root"] || path.join(root, "wiki");
-  const agent = values.agent || process.env.LIBEVAL_AGENT_PROFILE;
+function paths(runtime, options) {
+  const wikiRoot = resolveWikiRoot(runtime, options);
+  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    process.stderr.write("inbox requires --agent or LIBEVAL_AGENT_PROFILE\n");
-    process.exit(2);
+    runtime.proc.stderr.write(
+      "inbox requires --agent or LIBEVAL_AGENT_PROFILE\n",
+    );
+    return { error: { ok: false, code: 2 } };
   }
   return {
     summaryPath: path.join(wikiRoot, `${agent}.md`),
@@ -53,33 +47,39 @@ function removeBulletAt(lines, idx) {
   return lines;
 }
 
-function listCmd(values) {
-  const { summaryPath } = paths(values);
-  if (!existsSync(summaryPath)) {
-    process.stdout.write(JSON.stringify({ bullets: [] }) + "\n");
-    return;
+function listCmd(runtime, options) {
+  const p = paths(runtime, options);
+  if (p.error) return p.error;
+  const { summaryPath } = p;
+  if (!runtime.fsSync.existsSync(summaryPath)) {
+    runtime.proc.stdout.write(JSON.stringify({ bullets: [] }) + "\n");
+    return { ok: true };
   }
-  const text = readFileSync(summaryPath, "utf-8");
+  const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { bullets } = readInboxBullets(text);
-  process.stdout.write(JSON.stringify({ bullets }, null, 2) + "\n");
+  runtime.proc.stdout.write(JSON.stringify({ bullets }, null, 2) + "\n");
+  return { ok: true };
 }
 
-function ackOrDropCmd(values, _kind) {
-  const { summaryPath } = paths(values);
-  const idx = Number.parseInt(values.index ?? "", 10);
+function ackOrDropCmd(runtime, options) {
+  const p = paths(runtime, options);
+  if (p.error) return p.error;
+  const { summaryPath } = p;
+  const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    process.stderr.write("inbox requires --index <n>\n");
-    process.exit(2);
+    runtime.proc.stderr.write("inbox requires --index <n>\n");
+    return { ok: false, code: 2 };
   }
-  const text = readFileSync(summaryPath, "utf-8");
+  const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bulletIdxs } = readInboxBullets(text);
   if (idx >= bulletIdxs.length) {
-    process.stderr.write(`no bullet at index ${idx}\n`);
-    process.exit(2);
+    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    return { ok: false, code: 2 };
   }
   removeBulletAt(lines, bulletIdxs[idx]);
-  writeFileSync(summaryPath, lines.join("\n"));
-  process.stdout.write(`removed inbox bullet ${idx}\n`);
+  runtime.fsSync.writeFileSync(summaryPath, lines.join("\n"));
+  runtime.proc.stdout.write(`removed inbox bullet ${idx}\n`);
+  return { ok: true };
 }
 
 function appendPriorityRow(memoryText, { item, agents, owner, status, added }) {
@@ -128,28 +128,30 @@ function appendPriorityRow(memoryText, { item, agents, owner, status, added }) {
   return lines.join("\n");
 }
 
-function promoteCmd(values) {
-  const { summaryPath, memoryPath, agent } = paths(values);
-  const idx = Number.parseInt(values.index ?? "", 10);
+function promoteCmd(runtime, options) {
+  const p = paths(runtime, options);
+  if (p.error) return p.error;
+  const { summaryPath, memoryPath, agent } = p;
+  const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    process.stderr.write("inbox promote requires --index <n>\n");
-    process.exit(2);
+    runtime.proc.stderr.write("inbox promote requires --index <n>\n");
+    return { ok: false, code: 2 };
   }
-  const text = readFileSync(summaryPath, "utf-8");
+  const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bullets, bulletIdxs } = readInboxBullets(text);
   if (idx >= bullets.length) {
-    process.stderr.write(`no bullet at index ${idx}\n`);
-    process.exit(2);
+    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    return { ok: false, code: 2 };
   }
   const bulletText = bullets[idx].replace(/^[-*]\s+/, "");
   removeBulletAt(lines, bulletIdxs[idx]);
-  writeFileSync(summaryPath, lines.join("\n"));
+  runtime.fsSync.writeFileSync(summaryPath, lines.join("\n"));
 
-  const memText = existsSync(memoryPath)
-    ? readFileSync(memoryPath, "utf-8")
+  const memText = runtime.fsSync.existsSync(memoryPath)
+    ? runtime.fsSync.readFileSync(memoryPath, "utf-8")
     : "";
-  const today = values.today || new Date().toISOString().slice(0, 10);
-  const owner = values.owner || agent;
+  const today = options.today || currentDayIso(runtime);
+  const owner = options.owner || agent;
   const promoted = appendPriorityRow(memText, {
     item: bulletText,
     agents: agent,
@@ -157,24 +159,29 @@ function promoteCmd(values) {
     status: "active",
     added: today,
   });
-  writeFileSync(memoryPath, promoted);
-  process.stdout.write(`promoted inbox bullet ${idx} to priorities\n`);
+  runtime.fsSync.writeFileSync(memoryPath, promoted);
+  runtime.proc.stdout.write(`promoted inbox bullet ${idx} to priorities\n`);
+  return { ok: true };
 }
 
 const SUBS = {
   list: listCmd,
-  ack: (v) => ackOrDropCmd(v, "ack"),
-  drop: (v) => ackOrDropCmd(v, "drop"),
+  ack: ackOrDropCmd,
+  drop: ackOrDropCmd,
   promote: promoteCmd,
 };
 
 /** Dispatch `inbox {list|ack|promote|drop}` to the matching sub-handler. */
-export function runInboxCommand(values, args, cli) {
-  const sub = args[0];
+export function runInboxCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const sub = ctx.args.subcommand;
   const handler = SUBS[sub];
   if (!handler) {
-    cli.usageError("inbox requires subcommand: list | ack | promote | drop");
-    process.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "inbox requires subcommand: list | ack | promote | drop",
+    };
   }
-  handler(values);
+  return handler(runtime, ctx.options);
 }

package/src/commands/init.js

@@ -1,12 +1,6 @@
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import path from "node:path";
-import fsAsync from "node:fs/promises";
-import { Finder } from "@forwardimpact/libutil";
-import { createScriptConfig } from "@forwardimpact/libconfig";
-import { WikiRepo } from "../wiki-repo.js";
 import { listSkills } from "../skill-roster.js";
-import { createDefaultIo } from "../io.js";
+import { resolveProjectRoot, resolveWikiRoot } from "../util/wiki-dir.js";
 import {
   ACTIVE_CLAIMS_HEADING,
   ACTIVE_CLAIMS_TABLE_HEADER,
@@ -14,22 +8,21 @@ import {
 } from "../constants.js";
 
 /** Resolve the wiki clone URL. Honors the FIT_WIKI_URL env var as an explicit override (for sandboxed environments where `origin` is rewritten to a local proxy that does not serve wiki repos); otherwise derives the URL by appending `.wiki.git` to the parent repo's `origin` remote. */
-export function deriveWikiUrl(parentDir, env = process.env) {
+export async function deriveWikiUrl(gitClient, parentDir, env) {
   if (env.FIT_WIKI_URL) return env.FIT_WIKI_URL;
-
-  const r = spawnSync("git", ["-C", parentDir, "remote", "get-url", "origin"], {
-    encoding: "utf-8",
-    stdio: "pipe",
-  });
-  if (r.status !== 0) return null;
-  const origin = r.stdout.trim();
-  const base = origin.replace(/\.git$/, "");
-  return base + ".wiki.git";
+  try {
+    const origin = await gitClient.remoteGetUrl("origin", { cwd: parentDir });
+    if (!origin) return null;
+    const base = origin.replace(/\.git$/, "");
+    return base + ".wiki.git";
+  } catch {
+    return null;
+  }
 }
 
-function scaffoldActiveClaims(memoryPath) {
-  if (!existsSync(memoryPath)) return false;
-  const text = readFileSync(memoryPath, "utf-8");
+function scaffoldActiveClaims(runtime, memoryPath) {
+  if (!runtime.fsSync.existsSync(memoryPath)) return false;
+  const text = runtime.fsSync.readFileSync(memoryPath, "utf-8");
   if (new RegExp(`^${ACTIVE_CLAIMS_HEADING}$`, "m").test(text)) return false;
 
   const block = [
@@ -48,65 +41,66 @@ function scaffoldActiveClaims(memoryPath) {
   const lines = text.split("\n");
   const storyboardIdx = lines.findIndex((l) => l.trim() === "## Storyboard");
   if (storyboardIdx === -1) {
-    writeFileSync(memoryPath, text.replace(/\n*$/, "") + "\n" + block + "\n");
+    runtime.fsSync.writeFileSync(
+      memoryPath,
+      text.replace(/\n*$/, "") + "\n" + block + "\n",
+    );
     return true;
   }
   lines.splice(storyboardIdx, 0, ...block.split("\n"), "");
-  writeFileSync(memoryPath, lines.join("\n"));
+  runtime.fsSync.writeFileSync(memoryPath, lines.join("\n"));
   return true;
 }
 
-async function maybeCloneWiki(projectRoot, wikiDir, io) {
-  const wikiUrl = deriveWikiUrl(projectRoot, io.env);
+async function maybeCloneWiki(wikiSync, gitClient, projectRoot, runtime) {
+  const wikiUrl = await deriveWikiUrl(gitClient, projectRoot, runtime.proc.env);
   if (!wikiUrl) {
-    io.stderr("init: could not determine wiki URL from origin remote\n");
+    runtime.proc.stderr.write(
+      "init: could not determine wiki URL from origin remote\n",
+    );
     return;
   }
-  const config = await createScriptConfig("wiki");
-  const repo = new WikiRepo({
-    wikiDir,
-    parentDir: projectRoot,
-    resolveToken: () => config.ghToken(),
-  });
-  const cloneResult = repo.ensureCloned(wikiUrl);
+  const cloneResult = await wikiSync.ensureCloned(wikiUrl);
   if (cloneResult.cloned) {
-    repo.inheritIdentity();
+    await wikiSync.inheritIdentity();
   } else {
-    io.stderr("init: could not clone wiki, continuing with local-only steps\n");
+    runtime.proc.stderr.write(
+      "init: could not clone wiki, continuing with local-only steps\n",
+    );
   }
 }
 
 /** Clone the wiki if not already present, scaffold Active Claims in MEMORY.md, and create per-skill metric directories. */
-export async function runInitCommand(
-  values,
-  _args,
-  _cli,
-  io = createDefaultIo(),
-) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
-  const projectRoot = finder.findProjectRoot(io.cwd());
+export async function runInitCommand(ctx) {
+  const { runtime, wikiSync, gitClient } = ctx.deps;
+  const options = ctx.options;
+  const projectRoot = resolveProjectRoot(runtime);
 
-  const wikiDir = path.resolve(projectRoot, values["wiki-root"] ?? "wiki");
+  const wikiDir = resolveWikiRoot(runtime, options);
   const skillsDir = path.resolve(
     projectRoot,
-    values["skills-dir"] ?? path.join(".claude", "skills"),
+    options["skills-dir"] ?? path.join(".claude", "skills"),
   );
 
-  await maybeCloneWiki(projectRoot, wikiDir, io);
+  await maybeCloneWiki(wikiSync, gitClient, projectRoot, runtime);
 
-  if (existsSync(skillsDir)) {
-    for (const slug of listSkills({ skillsDir })) {
-      mkdirSync(path.join(wikiDir, "metrics", slug), { recursive: true });
+  if (runtime.fsSync.existsSync(skillsDir)) {
+    for (const slug of listSkills({ skillsDir }, runtime.fsSync)) {
+      runtime.fsSync.mkdirSync(path.join(wikiDir, "metrics", slug), {
+        recursive: true,
+      });
     }
   }
 
-  if (existsSync(wikiDir)) {
+  if (runtime.fsSync.existsSync(wikiDir)) {
     const memoryPath = path.join(wikiDir, "MEMORY.md");
-    if (scaffoldActiveClaims(memoryPath)) {
-      io.stdout(`init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`);
+    if (scaffoldActiveClaims(runtime, memoryPath)) {
+      runtime.proc.stdout.write(
+        `init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`,
+      );
     }
   }
 
-  io.stdout(`init: wiki ready at ${wikiDir}\n`);
+  runtime.proc.stdout.write(`init: wiki ready at ${wikiDir}\n`);
+  return { ok: true };
 }

package/src/commands/log.js

@@ -1,31 +1,22 @@
-import { existsSync, readFileSync } from "node:fs";
-import fsAsync from "node:fs/promises";
-import path from "node:path";
-import { Finder } from "@forwardimpact/libutil";
 import {
   weeklyLogPath,
   rotateIfOverBudget,
   appendEntry,
 } from "../weekly-log.js";
 import { DECISION_HEADING } from "../constants.js";
-import { createDefaultIo } from "../io.js";
+import { currentDayIso } from "../util/clock.js";
+import { resolveWikiRoot } from "../util/wiki-dir.js";
 
-function projectRootForCommand(io) {
-  const logger = { debug() {} };
-  const finder = new Finder(fsAsync, logger, { cwd: io.cwd });
-  return finder.findProjectRoot(io.cwd());
-}
-
-function commonContext(values, io) {
-  const agent = values.agent || io.env.LIBEVAL_AGENT_PROFILE;
+function commonContext(runtime, options) {
+  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
   if (!agent) {
-    io.stderr("log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n");
-    io.exit(2);
-    return null;
+    runtime.proc.stderr.write(
+      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n",
+    );
+    return { error: { ok: false, code: 2 } };
   }
-  const projectRoot = projectRootForCommand(io);
-  const wikiRoot = values["wiki-root"] || path.join(projectRoot, "wiki");
-  const today = values.today || io.today();
+  const wikiRoot = resolveWikiRoot(runtime, options);
+  const today = options.today || currentDayIso(runtime);
   return { agent, wikiRoot, today };
 }
 
@@ -39,14 +30,14 @@ function lastDateHeading(text) {
   return last;
 }
 
-function runDecision(values, io) {
-  const ctx = commonContext(values, io);
-  if (!ctx) return;
+function runDecision(runtime, options) {
+  const ctx = commonContext(runtime, options);
+  if (ctx.error) return ctx.error;
   const { agent, wikiRoot, today } = ctx;
-  const surveyed = values.surveyed || "—";
-  const chosen = values.chosen || "—";
-  const rationale = values.rationale || "—";
-  const alternatives = values.alternatives || "—";
+  const surveyed = options.surveyed || "—";
+  const chosen = options.chosen || "—";
+  const rationale = options.rationale || "—";
+  const alternatives = options.alternatives || "—";
   const body = [
     `## ${today}`,
     "",
@@ -62,55 +53,70 @@ function runDecision(values, io) {
     "",
   ].join("\n");
   const lineCount = body.split("\n").length;
-  rotateIfOverBudget(wikiRoot, agent, today, lineCount);
+  rotateIfOverBudget(wikiRoot, agent, today, lineCount, {}, runtime.fsSync);
   const target = weeklyLogPath(wikiRoot, agent, today);
-  appendEntry(target, body, agent, today);
-  io.stdout(`logged decision to ${target}\n`);
+  appendEntry(target, body, agent, today, runtime.fsSync);
+  runtime.proc.stdout.write(`logged decision to ${target}\n`);
+  return { ok: true };
 }
 
-function runNote(values, io) {
-  const ctx = commonContext(values, io);
-  if (!ctx) return;
+function runNote(runtime, options) {
+  const ctx = commonContext(runtime, options);
+  if (ctx.error) return ctx.error;
   const { agent, wikiRoot, today } = ctx;
-  if (!values.field || !values.body) {
-    io.stderr("log note requires --field and --body\n");
-    io.exit(2);
-    return;
+  if (!options.field || !options.body) {
+    runtime.proc.stderr.write("log note requires --field and --body\n");
+    return { ok: false, code: 2 };
   }
-  const fieldBlock = `### ${values.field}\n\n${values.body}\n`;
+  const fieldBlock = `### ${options.field}\n\n${options.body}\n`;
   // Conservative line budget: assume we'll prepend a date heading.
   const withHeading = `## ${today}\n\n${fieldBlock}`;
-  rotateIfOverBudget(wikiRoot, agent, today, withHeading.split("\n").length);
+  rotateIfOverBudget(
+    wikiRoot,
+    agent,
+    today,
+    withHeading.split("\n").length,
+    {},
+    runtime.fsSync,
+  );
   const target = weeklyLogPath(wikiRoot, agent, today);
   // Append under the open entry if the file's last `## YYYY-MM-DD` is today;
   // otherwise open a new entry by prepending a date heading.
-  const existing = existsSync(target) ? readFileSync(target, "utf-8") : "";
+  const existing = runtime.fsSync.existsSync(target)
+    ? runtime.fsSync.readFileSync(target, "utf-8")
+    : "";
   const body = lastDateHeading(existing) === today ? fieldBlock : withHeading;
-  appendEntry(target, body, agent, today);
-  io.stdout(`logged note to ${target}\n`);
+  appendEntry(target, body, agent, today, runtime.fsSync);
+  runtime.proc.stdout.write(`logged note to ${target}\n`);
+  return { ok: true };
 }
 
-function runDone(values, io) {
-  const ctx = commonContext(values, io);
-  if (!ctx) return;
+function runDone(runtime, options) {
+  const ctx = commonContext(runtime, options);
+  if (ctx.error) return ctx.error;
   const { agent, wikiRoot, today } = ctx;
   const body = `### Closed\n\nRun closed ${today}.\n`;
   const lineCount = body.split("\n").length;
-  rotateIfOverBudget(wikiRoot, agent, today, lineCount);
+  rotateIfOverBudget(wikiRoot, agent, today, lineCount, {}, runtime.fsSync);
   const target = weeklyLogPath(wikiRoot, agent, today);
-  appendEntry(target, body, agent, today);
-  io.stdout(`closed entry in ${target}\n`);
+  appendEntry(target, body, agent, today, runtime.fsSync);
+  runtime.proc.stdout.write(`closed entry in ${target}\n`);
+  return { ok: true };
 }
 
 const SUBS = { decision: runDecision, note: runNote, done: runDone };
 
 /** Dispatch `log {decision|note|done}` to the matching sub-handler. */
-export function runLogCommand(values, args, cli, io = createDefaultIo()) {
-  const sub = args[0];
+export function runLogCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const sub = ctx.args.subcommand;
   const handler = SUBS[sub];
   if (!handler) {
-    cli.usageError("log requires subcommand: decision | note | done");
-    return io.exit(2);
+    return {
+      ok: false,
+      code: 2,
+      error: "log requires subcommand: decision | note | done",
+    };
   }
-  handler(values, io);
+  return handler(runtime, ctx.options);
 }