fapony 0.2.1 → 0.3.3

package/src/mcp/transport.ts

@@ -1,18 +1,8 @@
 // src/mcp/transport.ts — JSON-RPC dispatch + stdio entry point
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { createInterface } from "node:readline";
-import { mergeBytesByTool, type UsageDetail } from "../session/index.js";
 import { getServerSha } from "./primitives.js";
-import {
-  TOOLS,
-  toolMemAdd,
-  toolMemFind,
-  toolPassiveUsage,
-  toolVerdictSubmit,
-} from "./tools/index.js";
+import { TOOLS, toolMemAdd, toolMemClose, toolMemFind } from "./tools/index.js";
 import { errorResult, type ToolResult } from "./types.js";
 
 // --- Server instructions ---
@@ -27,90 +17,19 @@ import { errorResult, type ToolResult } from "./types.js";
 // Both habits degrade silently — an agent that ignores them still gets
 // correct answers from every tool, just a thinner history.
 
-const SERVER_INSTRUCTIONS = `fapony is a ledger of how work in this project turned out: which model, on which shape of task, produced work that held up. One habit feeds it.
+const SERVER_INSTRUCTIONS = `fapony records decisions, bugs, and notes about this project so the next session (or the next agent) knows what happened and what to watch out for.
 
-When a unit of work is finished, call verdict_submit to grade it — pass-excellent..pass when it holds, fail when the first attempt was wrong, uncertain when you could not verify it (never guess pass). This is a grade on the work, not a confession: grade routinely, including work that went right the first time, because a model's record is only as good as the number of graded units behind it.
+When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session.
 
-worktree must be the absolute path (git rev-parse --show-toplevel): every query scopes by it, so a bare name or none files the verdict where nothing reads it, and nothing errors to say so. Write the note standalone — what the work was and how it held up — it is read months later with no access to this conversation. Never leave a run non-terminal; an open run absorbs later unrelated verdicts for that worktree.
+worktree must be the absolute path (git rev-parse --show-toplevel): every query scopes by it, so a bare name or none files the row where nothing reads it, and nothing errors to say so. Write the note standalone — it is read months later with no access to this conversation.
 
 Skip it and every tool still answers correctly, on a thinner history.`;
 
-// --- Statusline cache ---
-//
-// Written after every MCP tool call. The Claude Code statusline script reads
-// this file (< 1ms, no spawn, no db). Format: single line of text.
-// Only fapony_usage with detail:true produces meaningful data (bytes_by_tool,
-// aggregated across all clients — the bytes live on the claude_code
-// sub-object, never top-level); other tools write a minimal "fapony" marker.
-
-const STATUSLINE_PATH = join(homedir(), ".config", "fapony", "statusline");
-
-function writeStatuslineCache(toolResult: ToolResult): void {
-  try {
-    // Extract bytes_by_tool from fapony_usage detail JSON response.
-    let line = "fapony";
-    if (
-      toolResult &&
-      typeof toolResult === "object" &&
-      "content" in toolResult &&
-      Array.isArray(toolResult.content)
-    ) {
-      for (const c of toolResult.content) {
-        if (
-          c &&
-          typeof c === "object" &&
-          c.type === "text" &&
-          typeof c.text === "string"
-        ) {
-          // Try to extract bytes_by_tool from JSON text response.
-          // Aggregated across all clients: the bytes live on the Claude Code
-          // sub-object (claude_code.detail), never on the top-level detail,
-          // so reading top-level alone would always miss.
-          try {
-            const parsed = JSON.parse(c.text) as {
-              detail?: UsageDetail | null;
-              zcode?: { detail?: UsageDetail | null } | null;
-              claude_code?: { detail?: UsageDetail | null } | null;
-              codex?: { detail?: UsageDetail | null } | null;
-            };
-            const bbt = mergeBytesByTool(
-              parsed?.detail,
-              parsed?.zcode?.detail,
-              parsed?.claude_code?.detail,
-              parsed?.codex?.detail,
-            );
-            const entries = Object.entries(bbt).sort((a, b) => b[1] - a[1]);
-            const total = entries.reduce((s, e) => s + e[1], 0);
-            if (total > 0) {
-              // Format: "84.2k" for total, or "Read 42k · Grep 31k" for top tools.
-              const fmt = (n: number) =>
-                n >= 1024 ? `${(n / 1024).toFixed(1)}k` : `${Math.round(n)}`;
-              if (entries.length <= 3) {
-                line = `fapony ${entries.map((e) => `${e[0]} ${fmt(e[1])}`).join(" · ")}`;
-              } else {
-                line = `fapony ${fmt(total)}`;
-              }
-            }
-          } catch {
-            // Not JSON — that's fine, use default "fapony" marker.
-          }
-          break;
-        }
-      }
-    }
-    const dir = join(homedir(), ".config", "fapony");
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(STATUSLINE_PATH, line, "utf-8");
-  } catch {
-    // Cache write is best-effort — never block MCP on it.
-  }
-}
-
 // --- MCP protocol constants ---
 
 const MCP_PROTOCOL_VERSION = "2025-03-26";
 const SERVER_NAME = "fapony-handcheck";
-const SERVER_VERSION = "0.2.1";
+const SERVER_VERSION = "0.3.0";
 
 // --- JSON-RPC dispatch ---
 
@@ -149,23 +68,18 @@ function dispatchToolCall(params: {
   const args = params.arguments ?? {};
   let result: ToolResult;
   switch (params.name) {
-    case "verdict_submit":
-      result = toolVerdictSubmit(args);
-      break;
-    case "fapony_usage":
-      result = toolPassiveUsage(args);
-      break;
     case "mem_find":
       result = toolMemFind(args);
       break;
     case "mem_add":
       result = toolMemAdd(args);
       break;
+    case "mem_close":
+      result = toolMemClose(args);
+      break;
     default:
       return errorResult(`unknown tool: ${params.name}`);
   }
-  // Write statusline cache after every tool call — best-effort, never blocks.
-  writeStatuslineCache(result);
   return result;
 }
 

package/src/mcp/worktree.ts

@@ -8,7 +8,7 @@ const SENTINEL_MCP_EXTERNAL = "mcp-external";
  * Resolve a worktree argument to an absolute path.
  * - Absolute paths (contain "/") pass through unchanged
  * - Keys are looked up in config.worktrees
- * - "mcp-external" sentinel passes through (set by verdict_submit itself)
+ * - "mcp-external" sentinel passes through (used when no worktree is available)
  * - Throws if key not found in config
  */
 export function resolveWorktreeArg(value: string): string {

package/src/mem/commands/read.ts

@@ -2,13 +2,29 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { doneLines, fmtClose, fmtRow, printOpenRows } from "../render.js";
+import { baselinePath, readEvidenceLintCmd } from "../../lint-baseline.js";
+import { doneLines, fmtClose, fmtRow } from "../render.js";
 import { claimsOf, openRows, staleReport } from "../selectors.js";
 import type { CloseRow, WorkRow } from "../store.js";
-import { allRows, app, memCmd, planDir, rows } from "../store.js";
+import { allRows, app, memCmd, planDir, root, rows } from "../store.js";
 import { planSweepCmd, shippedNotMoved } from "./plan.js";
 import { THRESHOLD } from "./rotate.js";
 
+/** Files changed on this branch vs dev — empty set when dev is missing or diff fails. */
+function getBranchDiffFiles(cwd: string): Set<string> {
+  try {
+    const p = Bun.spawnSync(["git", "diff", "--name-only", "dev...HEAD"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode !== 0) return new Set();
+    return new Set(p.stdout.toString().trim().split("\n").filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
 const rotateLine = (n: number) =>
   n >= THRESHOLD
     ? `\n## 🗜 log ${n} rows (≥ ${THRESHOLD}) — run: ${memCmd} rotate --apply`
@@ -23,26 +39,20 @@ const planSweepLine = () => {
     : "";
 };
 
-export const cmdNow = () => {
-  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
-  const all = rows();
-  console.log(`# ${app} — ${all.length} entries`);
-  printOpenRows(all, { showHold: true });
-  const decisionN = openRows(all).filter((r) => r.kind === "decision").length;
-  const noteN = openRows(all).filter((r) => r.kind === "note").length;
-  console.log(
-    `\n## decision ${decisionN} · note ${noteN} — search: ${memCmd} find <word>`,
-  );
-  const stale = staleReport(all);
-  if (stale.length)
-    console.log(
-      `\n## ⚠ stale (${stale.length})\n` +
-        stale.map((l) => `- ${l}`).join("\n"),
-    );
-  const sweep = planSweepLine();
-  if (sweep) console.log(sweep);
-  const rotate = rotateLine(all.length);
-  if (rotate) console.log(rotate);
+// Row-list caps: no row-list section exceeds 10 (same budget as ## recent,
+// which takes doneLines(all, 10)). Per-row text is cut at a word boundary —
+// a kickoff line points at the row (mem find has the full text), it must not
+// reprint it.
+const BUGS_LIMIT = 10;
+const BRANCH_LIMIT = 10;
+const RECENT_OPEN_LIMIT = 10;
+const RECENT_OPEN_TEXT = 160;
+
+const shortText = (text: string, max = RECENT_OPEN_TEXT): string => {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const lastSpace = cut.lastIndexOf(" ");
+  return `${lastSpace > max / 2 ? cut.slice(0, lastSpace) : cut}…`;
 };
 
 export const cmdDone = () => {
@@ -234,23 +244,194 @@ export const cmdKickoff = (a: string[]) => {
     }
   }
 
-  // --- main output (unchanged behavior) ---
+  // --- suggestions (generated early so the no-args path can print next up
+  //     before the recency tier, keeping it inside the 4KB cap) ---
+
+  type Suggestion = { text: string; run?: string; manual?: boolean };
+  const suggestions: Suggestion[] = [];
+  const GROUP_CAP = 3;
+
+  const truncate = (s: string, n = 80) =>
+    s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
+
+  // group 1 — plans: priority: high first, then the first unchecked chunk
+  const planLines: Suggestion[] = [];
+  if (existsSync(planDir)) {
+    const files = readdirSync(planDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      if (planLines.length >= GROUP_CAP) break;
+      const fullPath = join(planDir, file);
+      if (planFile && fullPath === planFile) continue;
+      if (hasHighPriority(fullPath)) {
+        const title = readPlanTitle(fullPath);
+        planLines.push({
+          text: `${title || file} (${file})`,
+          run: `fapony mem kickoff ${file}`,
+        });
+      }
+    }
+  }
+  if (planLines.length < GROUP_CAP && planCheckboxes.length) {
+    const planName = planFile ? basename(planFile) : "plan";
+    planLines.push({ text: `${planCheckboxes[0]} (${planName})` });
+  }
+  suggestions.push(...planLines);
+
+  // group 2 — open bugs, oldest first
+  const suggClaims = claimsOf(all);
+  const openBugs = openRows(all)
+    .filter((r) => r.kind === "bug" && !suggClaims.has(r.id))
+    .slice(0, GROUP_CAP);
+  for (const b of openBugs) {
+    suggestions.push({
+      text: `bug #${b.id} — ${truncate(b.text)}`,
+      run: `fapony mem close ${b.id} "<msg>"`,
+      manual: true,
+    });
+  }
+
+  // group 3 — the files of the last 3 rows that carried files[]
+  const recentFiles = all
+    .filter(
+      (r): r is WorkRow =>
+        "id" in r && "files" in r && !!(r as WorkRow).files?.length,
+    )
+    .slice(-3)
+    .flatMap((r) => r.files ?? []);
+  const uniqueRecent = [...new Set(recentFiles)].slice(0, GROUP_CAP);
+  if (uniqueRecent.length) {
+    suggestions.push({
+      text: `แตะล่าสุด: ${uniqueRecent.join(", ")}`,
+      run: `fapony review-seed --files ${uniqueRecent.join(",")}`,
+    });
+  }
+
+  // group 4 — the lint baseline
+  try {
+    if (readEvidenceLintCmd(root) && !existsSync(baselinePath(root))) {
+      suggestions.push({
+        text: "lint baseline ยังไม่ capture — แดงที่มีอยู่ก่อนจะถูกนับเป็นของคุณ",
+        run: "fapony lint-baseline --capture",
+      });
+    }
+  } catch {
+    // state dir unreadable — the baseline line is a convenience, never a gate
+  }
+
+  /** Print ## next up and handle --pick. */
+  const printNextUp = () => {
+    if (!suggestions.length) return;
+    console.log(`\n## next up`);
+    for (let i = 0; i < suggestions.length; i++) {
+      console.log(`  [${i + 1}] ${suggestions[i].text}`);
+      if (suggestions[i].run) console.log(`      → ${suggestions[i].run}`);
+    }
+    if (pickIdx !== null) {
+      if (pickIdx > suggestions.length) {
+        console.error(
+          `--pick ${pickIdx}: only ${suggestions.length} suggestion(s) available`,
+        );
+        process.exit(1);
+      }
+      const picked = suggestions[pickIdx - 1];
+      if (!picked.run) {
+        console.error(
+          `--pick ${pickIdx}: "${picked.text}" is context, not a command — nothing to run`,
+        );
+        process.exit(1);
+      }
+      if (picked.manual) {
+        console.error(
+          `--pick ${pickIdx}: the command needs your own message — run it yourself:\n  ${picked.run}`,
+        );
+        process.exit(1);
+      }
+      const cmd = picked.run;
+      console.log(`\n> running: ${cmd}`);
+      const { execSync } = require("node:child_process");
+      try {
+        execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
+      } catch {
+        process.exit(1);
+      }
+    }
+  };
+
+  // --- main output ---
+
+  // Deferred output for the no-args path — recent closes, plan sweep, rotate
+  let kickoffExtras: (() => void) | null = null;
 
   if (!arg && !planFile) {
-    // no args = now + a "recent" section = the last 10 closes
+    // no args = ranked open rows + next up + recent closes
     console.log(`# ${app} — ${all.length} entries`);
-    printOpenRows(all, { showHold: true });
-    console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
-    const stale = staleReport(all);
-    if (stale.length)
-      console.log(
-        `\n## ⚠ stale (${stale.length})\n` +
-          stale.map((l) => `- ${l}`).join("\n"),
-      );
-    const sweep = planSweepLine();
-    if (sweep) console.log(sweep);
-    const rotate = rotateLine(all.length);
-    if (rotate) console.log(rotate);
+
+    const open = openRows(all);
+    const claims = claimsOf(all);
+    const diffFiles = getBranchDiffFiles(root);
+
+    // Tier 1: unclaimed bugs (always first, no matter how old) — capped: a
+    // backlog of unclosable bugs must not push the rest of the ranking out.
+    const bugs = open.filter((r) => r.kind === "bug" && !claims.has(r.id));
+    if (bugs.length) {
+      console.log(`\n## bugs`);
+      for (const r of bugs.slice(0, BUGS_LIMIT)) console.log(fmtRow(r));
+      if (bugs.length > BUGS_LIMIT)
+        console.log(
+          `… +${bugs.length - BUGS_LIMIT} more unclosed bugs — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // next up BEFORE the branch/recency tiers so no row-list section can
+    // push it out — order is by actionability, never by "this tier is short".
+    printNextUp();
+
+    // Tier 2: rows whose files[] overlap with git diff --name-only dev...HEAD
+    // — capped like every other row-list section (≤10 + overflow, pointer
+    // lines via shortText): the branch diff is unbounded and mem clusters on
+    // files every real branch touches, so uncapped this reprints the log.
+    const bugIds = new Set(bugs.map((r) => r.id));
+    const diffMatched = open.filter((r) => {
+      if (bugIds.has(r.id)) return false;
+      if (diffFiles.size === 0) return false;
+      return (r.files ?? []).some((f) => diffFiles.has(f));
+    });
+    if (diffMatched.length) {
+      console.log(`\n## on this branch`);
+      for (const r of diffMatched.slice(0, BRANCH_LIMIT))
+        console.log(fmtRow({ ...r, text: shortText(r.text) }, claims));
+      if (diffMatched.length > BRANCH_LIMIT)
+        console.log(
+          `… +${diffMatched.length - BRANCH_LIMIT} more — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // Tier 3: rest by recency (newest first) — tie-breaker only, capped like
+    // ## recent (doneLines takes 10): decision/note can never close, so an
+    // uncapped tier reprints the whole log. Lines are pointers, not prose —
+    // cut at a word boundary and point at mem find for the rest.
+    const shown = new Set([...bugIds, ...diffMatched.map((r) => r.id)]);
+    const rest = open
+      .filter((r) => !shown.has(r.id))
+      .sort((a, b) => b.ts.localeCompare(a.ts));
+    if (rest.length) {
+      console.log(`\n## recent open`);
+      for (const r of rest.slice(0, RECENT_OPEN_LIMIT))
+        console.log(fmtRow({ ...r, text: shortText(r.text) }, claims));
+      if (rest.length > RECENT_OPEN_LIMIT)
+        console.log(
+          `… +${rest.length - RECENT_OPEN_LIMIT} more — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // recent closes, plan sweep, rotate — after next up
+    kickoffExtras = () => {
+      console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
+      const sweep = planSweepLine();
+      if (sweep) console.log(sweep);
+      const rotate = rotateLine(all.length);
+      if (rotate) console.log(rotate);
+    };
   } else if (resolvedSpec) {
     // spec.md = a brief for that spec
     const open = openRows(all);
@@ -334,115 +515,24 @@ export const cmdKickoff = (a: string[]) => {
           specCloses.map((c) => fmtClose(c, byId)).join("\n"),
       );
     }
+  } else if (planFile) {
+    const title = readPlanTitle(planFile);
+    console.log(`# ${title || basename(planFile)} — plan`);
+    if (planCheckboxes.length) {
+      console.log(
+        `\n## unchecked\n${planCheckboxes.map((c) => `- [ ] ${c}`).join("\n")}`,
+      );
+    } else {
+      console.log(`\n(all chunks checked — ready to ship or archive)`);
+    }
   } else if (arg) {
     console.error(`no id "${arg}" in the log`);
     process.exit(1);
   }
 
-  // --- next up section (chunk 3) ---
-
-  // A suggestion may carry a fully-runnable command. `manual` marks a command
-  // that is a template with a placeholder (bug close) — show it, never auto-run it.
-  type Suggestion = { text: string; run?: string; manual?: boolean };
-  const suggestions: Suggestion[] = [];
-  const GROUP_CAP = 3; // SPEC §3: at most 3 groups, at most 3 lines each
-
-  const truncate = (s: string, n = 80) =>
-    s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
-
-  // group 1 — plans: priority: high first, then the first unchecked chunk
-  const planLines: Suggestion[] = [];
-  if (existsSync(planDir)) {
-    const files = readdirSync(planDir).filter((f) => f.endsWith(".md"));
-    for (const file of files) {
-      if (planLines.length >= GROUP_CAP) break;
-      const fullPath = join(planDir, file);
-      // Skip the plan we already showed
-      if (planFile && fullPath === planFile) continue;
-      if (hasHighPriority(fullPath)) {
-        const title = readPlanTitle(fullPath);
-        planLines.push({
-          text: `${title || file} (${file})`,
-          run: `fapony mem kickoff ${file}`,
-        });
-      }
-    }
-  }
-  // Only the first unchecked chunk (SPEC §3) — the body of the plan is the plan's job.
-  // There is no per-chunk command, so this line is context, not a runnable item.
-  if (planLines.length < GROUP_CAP && planCheckboxes.length) {
-    const planName = planFile ? basename(planFile) : "plan";
-    planLines.push({ text: `${planCheckboxes[0]} (${planName})` });
-  }
-  suggestions.push(...planLines);
-
-  // group 2 — open bugs, oldest first. openRows excludes tombstoned refs; the
-  // old bug filter forgot that and offered already-closed bugs as work.
-  const claims = claimsOf(all);
-  const openBugs = openRows(all)
-    .filter((r) => r.kind === "bug" && !claims.has(r.id))
-    .slice(0, GROUP_CAP);
-  for (const b of openBugs) {
-    suggestions.push({
-      text: `bug #${b.id} — ${truncate(b.text)}`,
-      run: `fapony mem close ${b.id} "<msg>"`,
-      manual: true,
-    });
-  }
-
-  // group 3 — the files of the last 3 rows that carried files[]
-  const recentFiles = all
-    .filter(
-      (r): r is WorkRow =>
-        "id" in r && "files" in r && !!(r as WorkRow).files?.length,
-    )
-    .slice(-3)
-    .flatMap((r) => r.files ?? []);
-  const uniqueRecent = [...new Set(recentFiles)].slice(0, GROUP_CAP);
-  if (uniqueRecent.length) {
-    suggestions.push({
-      text: `แตะล่าสุด: ${uniqueRecent.join(", ")}`,
-      run: `fapony review-seed --files ${uniqueRecent.join(",")}`,
-    });
-  }
+  // For non-no-args paths, print next up at the end
+  if (arg || planFile) printNextUp();
 
-  // Print and optionally execute. Only a suggestion with a complete command is
-  // runnable — a plan item is context, a bug's close is a template needing a message.
-  if (suggestions.length) {
-    console.log(`\n## next up`);
-    for (let i = 0; i < suggestions.length; i++) {
-      console.log(`  [${i + 1}] ${suggestions[i].text}`);
-      if (suggestions[i].run) console.log(`      → ${suggestions[i].run}`);
-    }
-
-    if (pickIdx !== null) {
-      if (pickIdx > suggestions.length) {
-        console.error(
-          `--pick ${pickIdx}: only ${suggestions.length} suggestion(s) available`,
-        );
-        process.exit(1);
-      }
-      const picked = suggestions[pickIdx - 1];
-      if (!picked.run) {
-        console.error(
-          `--pick ${pickIdx}: "${picked.text}" is context, not a command — nothing to run`,
-        );
-        process.exit(1);
-      }
-      if (picked.manual) {
-        console.error(
-          `--pick ${pickIdx}: the command needs your own message — run it yourself:\n  ${picked.run}`,
-        );
-        process.exit(1);
-      }
-      const cmd = picked.run;
-      console.log(`\n> running: ${cmd}`);
-      const { execSync } = require("node:child_process");
-      try {
-        execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
-      } catch {
-        process.exit(1);
-      }
-    }
-  }
+  // Deferred output from no-args path (recent closes, plan sweep, rotate)
+  kickoffExtras?.();
 };

package/src/mem/index.ts

@@ -4,13 +4,7 @@
 // Now an export function called by fapony.ts, not a standalone script.
 
 import { cmdPlanCheck, cmdPlanSweep } from "./commands/plan.js";
-import {
-  cmdDone,
-  cmdFind,
-  cmdKickoff,
-  cmdNow,
-  cmdStale,
-} from "./commands/read.js";
+import { cmdDone, cmdFind, cmdKickoff, cmdStale } from "./commands/read.js";
 import { cmdRotate } from "./commands/rotate.js";
 import { cmdWhere } from "./commands/where.js";
 import {
@@ -30,7 +24,7 @@ subcommands:
   add <kind> "<text>" --files f1,f2 [spec.md]
   close <id> "<msg>"          close a bug
   find "<text>"               substring-search every row
-  now | done | stale          views
+  done | stale              views
   claim <id> | release <id> | synced   bookkeeping
   plan-sweep [<plan.md> [--apply]]     move shipped plans + fix links
   plan-check <plan.md>        validate a plan's frontmatter/sections
@@ -62,9 +56,6 @@ example: fapony mem close mt14 "fixed in a2c6beb"`,
   find: `usage: fapony mem find "<text>"
 substring search over every row's text/spec/ref — all kinds, no default filter
 example: fapony mem find "usage-web"`,
-  now: `usage: fapony mem now
-next + bug + hold still open (decision/note are search-only — use find)
-example: fapony mem now`,
   done: `usage: fapony mem done
 closed rows with their tombstone message
 example: fapony mem done`,
@@ -138,7 +129,7 @@ export async function cmdMem(a: string[], memDir?: string): Promise<void> {
   } else if (cmd === "rotate") {
     cmdRotate(rest);
   } else {
-    // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
-    cmdNow();
+    // bare `fapony mem` → kickoff (ranked session overview)
+    cmdKickoff(rest);
   }
 }

package/src/memory.ts

@@ -218,7 +218,13 @@ function walkUpForMemDir(fromDir: string, acceptEmpty: boolean): string | null {
 export interface MemDirResult {
   dir: string | null;
   step: "flag" | "config" | "walk-up" | "repo-root" | "ambiguous" | "none";
-  /** For step "ambiguous" — the sibling `.fapony/.memory/` dirs that hold logs. */
+  /**
+   * `.fapony/.memory/` dirs under the repo root that hold logs but are not in
+   * scope from `fromDir`. Set for "ambiguous" (two or more, the refusal) and
+   * also for "repo-root"/"none" (one) — a caller that reports "nothing
+   * recorded here" is lying when a single app-scoped log exists one level
+   * down, and the honest line needs the path to say where.
+   */
   candidates?: string[];
 }
 
@@ -320,20 +326,23 @@ function resolveMemDirFrom(
   // Guard (SPEC §1 fail example): nothing at/above cwd holds a log, but the repo
   // has two or more app-scoped ones — refuse instead of silently creating a
   // third log at the root that no app-scoped reader will ever see.
-  if (root) {
-    const candidates = findMemDirsUnder(root);
-    if (candidates.length >= 2) {
-      return { dir: null, step: "ambiguous", candidates };
-    }
+  // One candidate is not ambiguous, so resolution is unchanged — but it still
+  // travels back with the result: out-of-scope is not the same as absent.
+  const candidates = root ? findMemDirsUnder(root) : [];
+  if (candidates.length >= 2) {
+    return { dir: null, step: "ambiguous", candidates };
   }
+  const outOfScope = candidates.length ? { candidates } : {};
 
   // Step 4: <repo root>/.fapony/.memory/ — where a new log is created
   if (root) {
     const rootDir = join(root, DEFAULT_MEM_DIR);
-    if (existsSync(rootDir)) return { dir: rootDir, step: "repo-root" };
+    if (existsSync(rootDir)) {
+      return { dir: rootDir, step: "repo-root", ...outOfScope };
+    }
   }
 
-  return { dir: null, step: "none" };
+  return { dir: null, step: "none", ...outOfScope };
 }
 
 export function resolveMemDir(