@forwardimpact/libwiki 0.2.24 → 0.2.26

package/src/commands/claim.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { addDays } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   appendClaim,
   removeClaim,
@@ -7,7 +8,25 @@ import {
   filterExpired,
 } from "../active-claims.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
+import { refusalEnvelope } from "../secret-gate.js";
+import { AncestryRefusal } from "../wiki-sync.js";
+
+/** Non-zero envelope returned when the ancestry guard refused publication. */
+const NOT_PUBLISHED = {
+  ok: false,
+  code: 1,
+};
+
+/** Build the not-published refusal message for the given guard refusal. */
+function notPublishedMessage(err) {
+  return (
+    `${err.message}\n` +
+    "The row was written to MEMORY.md but is NOT published — it remains an " +
+    "uncommitted working-tree change.\n"
+  );
+}
 
 function readMemory(runtime, memPath) {
   if (!runtime.fsSync.existsSync(memPath)) return "";
@@ -18,17 +37,72 @@ function memoryPath(runtime, options) {
   return path.join(resolveWikiRoot(runtime, options), "MEMORY.md");
 }
 
-async function pushWiki(wikiSync, runtime, message) {
-  if (!wikiSync) return;
+/**
+ * Push the claim/release MEMORY.md change through the secret-gated push path
+ * and translate the result into a command envelope. A secret block fails the
+ * command closed (`{ ok: false, code: 1 }`) and names the finding or the
+ * scanner absence on stderr — distinct from a *network* push failure, which
+ * still degrades to "saved locally" and succeeds (`{ ok: true }`).
+ *
+ * The `reapply` closure re-derives this row against the fresh tip if the
+ * landing contends, so a parallel writer's row is never erased. An
+ * ancestry-guard refusal ({@link AncestryRefusal}) is rethrown so the caller's
+ * `pushRowOrRefuse` can map it to the not-published non-zero envelope; every
+ * other throw is a network/credential failure that degrades to "saved locally".
+ *
+ * @param {object} wikiSync - The WikiSync collaborator (may be absent in tests).
+ * @param {object} runtime - The runtime bag (for stdout/stderr).
+ * @param {string} message - The commit message.
+ * @param {(freshText: string) => string | null} [reapply] - Re-derives the row
+ *   against the fresh tip when the landing contends.
+ * @returns {Promise<{ok: boolean, code?: number}>}
+ */
+async function pushWiki(wikiSync, runtime, message, reapply) {
+  if (!wikiSync) return { ok: true };
+  let result;
   try {
     await wikiSync.inheritIdentity();
     // claim/release contract is a 1-line MEMORY.md change; the pathspec keeps
-    // foreign uncommitted files from parallel writers out of the commit.
-    const result = await wikiSync.commitAndPush(message, ["MEMORY.md"]);
-    if (result.pushed)
-      runtime.proc.stdout.write("push: committed and pushed\n");
+    // foreign uncommitted files from parallel writers out of the commit. The
+    // `reapply` closure re-derives this row against the fresh tip if the landing
+    // contends, so a parallel writer's row is never erased.
+    result = await wikiSync.commitAndPush(message, ["MEMORY.md"], { reapply });
+  } catch (err) {
+    // An ancestry-guard refusal pierces the saved-locally degradation: it must
+    // reach a non-zero exit so the session stops rather than scroll past. Every
+    // other failure is a network/credential failure: preserve fire-and-forget
+    // "saved locally" — the change is on disk and the command still succeeds.
+    if (err instanceof AncestryRefusal) throw err;
+    createLogger("wiki", runtime).warn(
+      "claim",
+      `push failed (saved locally): ${err.message}`,
+    );
+    return { ok: true };
+  }
+  const refusal = refusalEnvelope(runtime, result);
+  if (refusal) return refusal;
+  if (result.pushed) runtime.proc.stdout.write("push: committed and pushed\n");
+  return { ok: true };
+}
+
+/**
+ * Push a written claim/release row, mapping an ancestry-guard refusal to the
+ * not-published non-zero envelope and any other outcome to `{ ok: true }`. The
+ * row is already written to MEMORY.md; on refusal it stays as an uncommitted
+ * working-tree change. The `reapply` closure re-derives the same row against
+ * the fresh tip when the landing contends.
+ */
+async function pushRowOrRefuse(wikiSync, runtime, message, reapply) {
+  try {
+    // Propagate pushWiki's envelope so a secret-gate refusal ({ ok: false })
+    // fails the command closed; a clean push returns { ok: true }.
+    return await pushWiki(wikiSync, runtime, message, reapply);
   } catch (err) {
-    runtime.proc.stderr.write(`push failed (saved locally): ${err.message}\n`);
+    if (err instanceof AncestryRefusal) {
+      runtime.proc.stderr.write(notPublishedMessage(err));
+      return NOT_PUBLISHED;
+    }
+    throw err;
   }
 }
 
@@ -36,14 +110,13 @@ async function pushWiki(wikiSync, runtime, message) {
 export async function runClaimCommand(ctx) {
   const { runtime, wikiSync } = ctx.deps;
   const options = ctx.options;
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    return {
-      ok: false,
-      code: 2,
-      error: "claim requires --agent or LIBEVAL_AGENT_PROFILE",
-    };
-  }
+  const resolved = requireAgentFlag(options, {
+    command: "claim",
+    example:
+      "fit-wiki claim --agent staff-engineer --target spec-NNNN --branch claude/...",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
   if (!options.target || !options.branch) {
     return {
       ok: false,
@@ -55,24 +128,35 @@ export async function runClaimCommand(ctx) {
   const expires = options["expires-at"] || addDays(today, 7);
   const memPath = memoryPath(runtime, options);
   const text = readMemory(runtime, memPath);
-  const result = appendClaim(text, {
+  const claim = {
     agent,
     target: options.target,
     branch: options.branch,
     pr: options.pr || null,
     claimed_at: today,
     expires_at: expires,
-  });
+  };
+  const result = appendClaim(text, claim);
   if (!result.inserted) {
-    runtime.proc.stderr.write(
-      `claim already exists for ${agent}/${options.target}\n`,
+    createLogger("wiki", runtime).warn(
+      "claim",
+      `claim already exists for ${agent}/${options.target}`,
     );
     return { ok: false, code: 2 };
   }
   runtime.fsSync.writeFileSync(memPath, result.text);
   runtime.proc.stdout.write(`claimed ${options.target} (expires ${expires})\n`);
-  await pushWiki(wikiSync, runtime, `wiki: claim ${options.target}`);
-  return { ok: true };
+  // Re-apply the same append against the fresh tip if the landing contends.
+  const reapply = (fresh) => {
+    const r = appendClaim(fresh, claim);
+    return r.inserted ? r.text : null;
+  };
+  return pushRowOrRefuse(
+    wikiSync,
+    runtime,
+    `wiki: claim ${options.target}`,
+    reapply,
+  );
 }
 
 /** Remove a claim row. `--expired` cleans every row past expires_at. */
@@ -97,18 +181,35 @@ export async function runReleaseCommand(ctx) {
     }
     runtime.fsSync.writeFileSync(memPath, current);
     runtime.proc.stdout.write(`released ${count} expired claim(s)\n`);
-    await pushWiki(wikiSync, runtime, "wiki: release expired claims");
-    return { ok: true };
-  }
-
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    return {
-      ok: false,
-      code: 2,
-      error: "release requires --agent or --expired",
+    // Re-derive expiry against the fresh tip so a renewal landed since the stale
+    // read survives; only still-expired rows are removed.
+    const reapply = (fresh) => {
+      const freshExpired = filterExpired(parseClaims(fresh), today).expired;
+      let next = fresh;
+      let anyRemoved = false;
+      for (const c of freshExpired) {
+        const r = removeClaim(next, { agent: c.agent, target: c.target });
+        if (r.removed) {
+          next = r.text;
+          anyRemoved = true;
+        }
+      }
+      return anyRemoved ? next : null;
     };
+    return pushRowOrRefuse(
+      wikiSync,
+      runtime,
+      "wiki: release expired claims",
+      reapply,
+    );
   }
+
+  const resolved = requireAgentFlag(options, {
+    command: "release",
+    example: "fit-wiki release --agent staff-engineer --target spec-NNNN",
+  });
+  if (!resolved.ok) return resolved;
+  const agent = resolved.agent;
   if (!options.target) {
     return {
       ok: false,
@@ -122,9 +223,19 @@ export async function runReleaseCommand(ctx) {
     runtime.proc.stdout.write(
       `no matching claim for ${agent}/${options.target}\n`,
     );
-  } else {
-    runtime.proc.stdout.write(`released ${options.target}\n`);
-    await pushWiki(wikiSync, runtime, `wiki: release ${options.target}`);
+    return { ok: true };
   }
-  return { ok: true };
+  runtime.proc.stdout.write(`released ${options.target}\n`);
+  // Re-apply the same removal against the fresh tip if the landing contends;
+  // re-removing an absent row is a no-op, so a re-release never resurrects it.
+  const reapply = (fresh) => {
+    const r = removeClaim(fresh, { agent, target: options.target });
+    return r.removed ? r.text : null;
+  };
+  return pushRowOrRefuse(
+    wikiSync,
+    runtime,
+    `wiki: release ${options.target}`,
+    reapply,
+  );
 }

package/src/commands/fix.js

@@ -16,6 +16,7 @@ import {
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 import { FAST_MODEL } from "@forwardimpact/libutil/models";
+import { createLogger } from "@forwardimpact/libtelemetry";
 
 // Pipeline: audit → deterministic rotation (the one fix needing a file seal the
 // agent can't do) → re-audit → Haiku agent on the prose-judgment residual →
@@ -37,14 +38,18 @@ function classOf(finding) {
  * 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`, …).
+ *
+ * Only static-string hints are listed: a function hint is a per-finding
+ * resolved command (a `rotate` remediation the agent never performs), not a
+ * file invariant, so listing it would leak its source text into the prompt.
  */
 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}`,
-  );
+  return RULES.filter(
+    (r) => scopes.has(r.scope) && typeof r.hint === "string",
+  ).map((r) => `- ${r.id} — ${r.hint}`);
 }
 
 /**
@@ -105,7 +110,7 @@ function sealMainLog(agent, { wikiRoot, today, projectRoot, fs, out, err }) {
       wikiRoot,
       agent,
       today,
-      0,
+      { lines: 0, words: 0 },
       { force: true },
       fs,
     );
@@ -276,11 +281,16 @@ export async function runFixCommand(ctx) {
   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 logger = createLogger("wiki", runtime);
+  const err = (s) => logger.warn("fix", String(s).replace(/\n+$/, ""));
 
   // The agent's edits change the result, so re-read and re-audit each round.
   const audit = () =>
-    runRules(RULES, buildContext({ wikiRoot, today, fs }), { resolveScope });
+    runRules(
+      RULES,
+      buildContext({ wikiRoot, today, fs, subprocess: runtime.subprocess }),
+      { resolveScope },
+    );
   // The agent only ever gets prose-judgment (`agent`-class) findings. A
   // `rotate` finding that survived the pre-pass (e.g. a prior-week log) is
   // unfixable by the agent — and trimming append-only history to satisfy a

package/src/commands/inbox.js

@@ -1,21 +1,22 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   MEMO_INBOX_MARKER,
   PRIORITY_INDEX_HEADING,
   PRIORITY_INDEX_TABLE_HEADER,
 } from "../constants.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 function paths(runtime, options) {
   const wikiRoot = resolveWikiRoot(runtime, options);
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    runtime.proc.stderr.write(
-      "inbox requires --agent or LIBEVAL_AGENT_PROFILE\n",
-    );
-    return { error: { ok: false, code: 2 } };
-  }
+  const resolved = requireAgentFlag(options, {
+    command: "inbox",
+    example: "fit-wiki inbox list --agent staff-engineer",
+  });
+  if (!resolved.ok) return { error: resolved };
+  const agent = resolved.agent;
   return {
     summaryPath: path.join(wikiRoot, `${agent}.md`),
     memoryPath: path.join(wikiRoot, "MEMORY.md"),
@@ -67,13 +68,13 @@ function ackOrDropCmd(runtime, options) {
   const { summaryPath } = p;
   const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    runtime.proc.stderr.write("inbox requires --index <n>\n");
+    createLogger("wiki", runtime).warn("inbox", "inbox requires --index <n>");
     return { ok: false, code: 2 };
   }
   const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bulletIdxs } = readInboxBullets(text);
   if (idx >= bulletIdxs.length) {
-    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    createLogger("wiki", runtime).warn("inbox", `no bullet at index ${idx}`);
     return { ok: false, code: 2 };
   }
   removeBulletAt(lines, bulletIdxs[idx]);
@@ -134,13 +135,16 @@ function promoteCmd(runtime, options) {
   const { summaryPath, memoryPath, agent } = p;
   const idx = Number.parseInt(options.index ?? "", 10);
   if (!Number.isInteger(idx) || idx < 0) {
-    runtime.proc.stderr.write("inbox promote requires --index <n>\n");
+    createLogger("wiki", runtime).warn(
+      "inbox",
+      "inbox promote requires --index <n>",
+    );
     return { ok: false, code: 2 };
   }
   const text = runtime.fsSync.readFileSync(summaryPath, "utf-8");
   const { lines, bullets, bulletIdxs } = readInboxBullets(text);
   if (idx >= bullets.length) {
-    runtime.proc.stderr.write(`no bullet at index ${idx}\n`);
+    createLogger("wiki", runtime).warn("inbox", `no bullet at index ${idx}`);
     return { ok: false, code: 2 };
   }
   const bulletText = bullets[idx].replace(/^[-*]\s+/, "");

package/src/commands/init.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import { ensureMetricsCsvMergeAttribute } from "../gitattributes.js";
 import { listSkills } from "../skill-roster.js";
 import { resolveProjectRoot, resolveWikiRoot } from "../util/wiki-dir.js";
 import {
@@ -53,19 +55,19 @@ function scaffoldActiveClaims(runtime, memoryPath) {
 }
 
 async function maybeCloneWiki(wikiSync, gitClient, projectRoot, runtime) {
+  const logger = createLogger("wiki", runtime);
   const wikiUrl = await deriveWikiUrl(gitClient, projectRoot, runtime.proc.env);
   if (!wikiUrl) {
-    runtime.proc.stderr.write(
-      "init: could not determine wiki URL from origin remote\n",
-    );
+    logger.warn("init", "could not determine wiki URL from origin remote");
     return;
   }
   const cloneResult = await wikiSync.ensureCloned(wikiUrl);
   if (cloneResult.cloned) {
     await wikiSync.inheritIdentity();
   } else {
-    runtime.proc.stderr.write(
-      "init: could not clone wiki, continuing with local-only steps\n",
+    logger.warn(
+      "init",
+      "could not clone wiki, continuing with local-only steps",
     );
   }
 }
@@ -99,6 +101,11 @@ export async function runInitCommand(ctx) {
         `init: scaffolded ${ACTIVE_CLAIMS_HEADING} in ${memoryPath}\n`,
       );
     }
+    if (ensureMetricsCsvMergeAttribute(wikiDir, runtime.fsSync).changed) {
+      runtime.proc.stdout.write(
+        "init: declared metrics-CSV union merge in .gitattributes\n",
+      );
+    }
   }
 
   runtime.proc.stdout.write(`init: wiki ready at ${wikiDir}\n`);

package/src/commands/log.js

@@ -1,29 +1,36 @@
+import { createLogger } from "@forwardimpact/libtelemetry";
 import {
   weeklyLogPath,
   rotateIfOverBudget,
   appendEntry,
 } from "../weekly-log.js";
-import { DECISION_HEADING } from "../constants.js";
+import {
+  DECISION_HEADING,
+  WEEKLY_LOG_LINE_BUDGET,
+  WEEKLY_LOG_SEAM_RE,
+  WEEKLY_LOG_WORD_BUDGET,
+} from "../constants.js";
+import { countLines, countWords } from "../budget.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveWikiRoot } from "../util/wiki-dir.js";
 
 function commonContext(runtime, options) {
-  const agent = options.agent || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
-  if (!agent) {
-    runtime.proc.stderr.write(
-      "log requires --agent <name> or LIBEVAL_AGENT_PROFILE env var\n",
-    );
-    return { error: { ok: false, code: 2 } };
-  }
+  const resolved = requireAgentFlag(options, {
+    command: "log",
+    example:
+      'fit-wiki log decision --agent staff-engineer --chosen "..." --rationale "..."',
+  });
+  if (!resolved.ok) return { error: resolved };
   const wikiRoot = resolveWikiRoot(runtime, options);
   const today = options.today || currentDayIso(runtime);
-  return { agent, wikiRoot, today };
+  return { agent: resolved.agent, wikiRoot, today };
 }
 
 function lastDateHeading(text) {
   // Match `## YYYY-MM-DD` at the start of a line, optionally followed by
   // suffix text (e.g. `## 2026-05-19 (third activation)`).
-  const re = /^## (\d{4}-\d{2}-\d{2})/gm;
+  const re = new RegExp(WEEKLY_LOG_SEAM_RE.source, "gm");
   let last = null;
   let match;
   while ((match = re.exec(text)) !== null) last = match[1];
@@ -38,28 +45,50 @@ function lastDateHeading(text) {
  * thrown fs error is reported and swallowed: the writer rolled back, so the
  * (intact) current file still receives the new entry.
  */
-function rotateBeforeAppend(wikiRoot, agent, today, appendLines, runtime) {
+function rotateBeforeAppend(wikiRoot, agent, today, body, runtime) {
   try {
+    const delta = { lines: countLines(body), words: countWords(body) };
     const res = rotateIfOverBudget(
       wikiRoot,
       agent,
       today,
-      appendLines,
+      delta,
       {},
       runtime.fsSync,
     );
     if (res.status === "incomplete") {
-      runtime.proc.stderr.write(
-        `note: day-section ${res.residue.section} alone exceeds the budget ` +
+      createLogger("wiki", runtime).warn(
+        "log",
+        `day-section ${res.residue.section} alone exceeds the budget ` +
           `(${res.residue.lines} lines, ${res.residue.words} words); ` +
-          `sealed as ${res.residue.path} for manual recovery\n`,
+          `sealed as ${res.residue.path} for manual recovery`,
       );
     }
   } catch (e) {
-    runtime.proc.stderr.write(`note: rotation failed: ${e.message}\n`);
+    createLogger("wiki", runtime).warn("log", `rotation failed: ${e.message}`);
   }
 }
 
+/**
+ * Report the just-written weekly log's budget state — value, cap, and remaining
+ * headroom for both the line and word budget — so a writer sees the ceiling
+ * before composing the next entry rather than discovering it via a red gate.
+ * Runs after every successful append, on the rotated and non-rotated path alike.
+ */
+function reportBudget(target, runtime) {
+  const text = runtime.fsSync.existsSync(target)
+    ? runtime.fsSync.readFileSync(target, "utf-8")
+    : "";
+  const lines = countLines(text);
+  const words = countWords(text);
+  runtime.proc.stdout.write(
+    `weekly log budget: ${lines}/${WEEKLY_LOG_LINE_BUDGET} lines ` +
+      `(${WEEKLY_LOG_LINE_BUDGET - lines} remaining), ` +
+      `${words}/${WEEKLY_LOG_WORD_BUDGET} words ` +
+      `(${WEEKLY_LOG_WORD_BUDGET - words} remaining)\n`,
+  );
+}
+
 function runDecision(runtime, options) {
   const ctx = commonContext(runtime, options);
   if (ctx.error) return ctx.error;
@@ -82,11 +111,11 @@ function runDecision(runtime, options) {
     `**Rationale:** ${rationale}`,
     "",
   ].join("\n");
-  const lineCount = body.split("\n").length;
-  rotateBeforeAppend(wikiRoot, agent, today, lineCount, runtime);
+  rotateBeforeAppend(wikiRoot, agent, today, body, runtime);
   const target = weeklyLogPath(wikiRoot, agent, today);
   appendEntry(target, body, agent, today, runtime.fsSync);
   runtime.proc.stdout.write(`logged decision to ${target}\n`);
+  reportBudget(target, runtime);
   return { ok: true };
 }
 
@@ -95,19 +124,17 @@ function runNote(runtime, options) {
   if (ctx.error) return ctx.error;
   const { agent, wikiRoot, today } = ctx;
   if (!options.field || !options.body) {
-    runtime.proc.stderr.write("log note requires --field and --body\n");
+    createLogger("wiki", runtime).warn(
+      "log",
+      "log note requires --field and --body",
+    );
     return { ok: false, code: 2 };
   }
   const fieldBlock = `### ${options.field}\n\n${options.body}\n`;
-  // Conservative line budget: assume we'll prepend a date heading.
+  // Conservative budget: assume we'll prepend a date heading. Rotate on the
+  // larger `withHeading` body so the word/line projection never under-counts.
   const withHeading = `## ${today}\n\n${fieldBlock}`;
-  rotateBeforeAppend(
-    wikiRoot,
-    agent,
-    today,
-    withHeading.split("\n").length,
-    runtime,
-  );
+  rotateBeforeAppend(wikiRoot, agent, today, withHeading, runtime);
   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.
@@ -117,6 +144,7 @@ function runNote(runtime, options) {
   const body = lastDateHeading(existing) === today ? fieldBlock : withHeading;
   appendEntry(target, body, agent, today, runtime.fsSync);
   runtime.proc.stdout.write(`logged note to ${target}\n`);
+  reportBudget(target, runtime);
   return { ok: true };
 }
 
@@ -125,11 +153,11 @@ function runDone(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;
-  rotateBeforeAppend(wikiRoot, agent, today, lineCount, runtime);
+  rotateBeforeAppend(wikiRoot, agent, today, body, runtime);
   const target = weeklyLogPath(wikiRoot, agent, today);
   appendEntry(target, body, agent, today, runtime.fsSync);
   runtime.proc.stdout.write(`closed entry in ${target}\n`);
+  reportBudget(target, runtime);
   return { ok: true };
 }
 

package/src/commands/memo.js

@@ -1,8 +1,10 @@
 import path from "node:path";
+import { createLogger } from "@forwardimpact/libtelemetry";
 import { writeMemo } from "../memo-writer.js";
 import { listAgents } from "../agent-roster.js";
 import { BROADCAST_TARGET } from "../constants.js";
 import { currentDayIso } from "../util/clock.js";
+import { requireAgentFlag } from "../util/agent-flag.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
 function writeAndCheck(runtime, summaryPath, sender, message, today) {
@@ -11,8 +13,9 @@ function writeAndCheck(runtime, summaryPath, sender, message, today) {
     runtime.fsSync,
   );
   if (!result.written) {
-    runtime.proc.stderr.write(
-      `summary lacks memo:inbox marker: ${result.path}\n`,
+    createLogger("wiki", runtime).warn(
+      "memo",
+      `summary lacks memo:inbox marker: ${result.path}`,
     );
     return { ok: false, code: 2 };
   }
@@ -61,19 +64,19 @@ function writeBroadcast(
   return { ok: true };
 }
 
-/** Write a memo to a target agent's summary file (or broadcast to all except the sender); sender is --from or LIBEVAL_AGENT_PROFILE env var. */
+/** Write a memo to a target agent's summary file (or broadcast to all except the sender); the sender is the required --from flag. */
 export function runMemoCommand(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;
-  const sender = options.from || runtime.proc.env.LIBEVAL_AGENT_PROFILE;
+  const resolved = requireAgentFlag(options, {
+    command: "memo",
+    flag: "--from",
+    example:
+      'fit-wiki memo --from staff-engineer --to security-engineer --message "..."',
+  });
+  if (!resolved.ok) return resolved;
+  const sender = resolved.agent;
 
-  if (!sender) {
-    return {
-      ok: false,
-      code: 2,
-      error: "memo requires --from <sender> or LIBEVAL_AGENT_PROFILE env var",
-    };
-  }
   if (!options.to) {
     return { ok: false, code: 2, error: "memo requires --to <target|all>" };
   }