dotmd-cli 0.60.0 → 0.62.0

package/src/baton.mjs

@@ -0,0 +1,231 @@
+import { readFileSync, fstatSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, warn, currentSessionId } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { readJournalEntries } from './journal.mjs';
+import { runNew, readBodyInput } from './new.mjs';
+import { runSet } from './lifecycle.mjs';
+import { green, dim } from './color.mjs';
+
+// `dotmd baton` is the one-command handoff: save the resume prompt AND release
+// the plan in a single atomic-ish verb. It exists because the three-step skill
+// version ("save prompt, pick a status, commit") kept expanding in practice —
+// sessions turned closeout into repo triage, forgot the prompt body, or got
+// tangled in what to commit. Baton does exactly one plan, one prompt, one
+// status flip, and then *tells* the agent the exact commit command.
+
+// Does a journal argv doc reference point at this index doc? References come
+// from `use <x>` / `set in-session <x>` invocations, so they may be a repo
+// path, a bare basename, or a slug without .md.
+function matchesDocRef(doc, ref) {
+  if (typeof ref !== 'string' || !ref) return false;
+  const cleaned = ref.replace(/^\.\//, '');
+  if (doc.path === cleaned) return true;
+  const base = path.basename(doc.path, '.md');
+  if (cleaned === base || cleaned === `${base}.md`) return true;
+  return doc.path.endsWith(`/${cleaned}`) || doc.path.endsWith(`/${cleaned}.md`);
+}
+
+// Resolve which in-session plan belongs to THIS session. There is no checkout
+// or lock — in-session is just frontmatter — so ownership is reconstructed
+// from the per-repo journal: the last `use <plan>` / `set in-session <plan>`
+// this sid ran whose target is still in-session. Falls back to "the only
+// in-session plan" when the journal can't answer (disabled, or another tool
+// flipped the status). Returns { plan, via, inSession }; plan is null when
+// there's no defensible answer (caller decides how to ask).
+export function findOwnedPlan(config, index = null) {
+  const idx = index ?? buildIndex(config);
+  const inSession = idx.docs.filter(d => d.type === 'plan' && d.status === 'in-session');
+  if (inSession.length === 0) return { plan: null, via: null, inSession };
+
+  const sid = currentSessionId();
+  let entries = [];
+  try { entries = readJournalEntries(config); } catch { entries = []; }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e?.sid !== sid || !Array.isArray(e.argv) || (e.exit ?? 0) !== 0) continue;
+    const a = e.argv;
+    let ref = null;
+    if (a[0] === 'use') ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-'));
+    else if (a[0] === 'set' && a[1] === 'in-session') ref = a.slice(2).find(x => typeof x === 'string' && !x.startsWith('-'));
+    else if (a[0] === 'status' && a.includes('in-session')) ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-') && x !== 'in-session');
+    if (!ref) continue;
+    const doc = inSession.find(d => matchesDocRef(d, ref));
+    if (doc) return { plan: doc, via: 'journal', inSession };
+  }
+
+  if (inSession.length === 1) return { plan: inSession[0], via: 'single-in-session', inSession };
+  return { plan: null, via: null, inSession };
+}
+
+const BODY_USAGE = `dotmd baton needs the resume draft as its body. Write 10–20 lines first — the next concrete decision plus any gotchas, NOT a recap of the plan — then:
+  dotmd baton @/tmp/draft.md             # body from file (preferred)
+  cat /tmp/draft.md | dotmd baton        # body from stdin
+  dotmd baton --message "..."            # one-liner
+No plan in-session? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`;
+
+// Is this positional a filesystem reference (must resolve, typos die) or a
+// bare word (may be a plan slug, may be a brand-new handoff name)?
+function looksLikePath(arg) {
+  return arg.includes('/') || arg.endsWith('.md');
+}
+
+export async function runBaton(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  let status = 'active';
+  let statusFlag = false;
+  let note = null;
+  let bodyFlag = null;
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--status' && argv[i + 1]) { status = argv[++i]; statusFlag = true; continue; }
+    if (a === '--note' && argv[i + 1]) { note = argv[++i]; continue; }
+    if ((a === '--body' || a === '--message') && argv[i + 1]) { bodyFlag = argv[++i]; continue; }
+    if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
+    die(`Unknown flag for \`dotmd baton\`: ${a}`);
+  }
+
+  let planArg = null;
+  let bodyArg = null;
+  for (const p of positionals) {
+    if (p === '-' || p.startsWith('@')) { bodyArg = p; continue; }
+    if (!planArg) { planArg = p; continue; }
+    if (bodyArg === null) bodyArg = p; // trailing inline body
+  }
+
+  // Body FIRST — it's the common failure (`new prompt` without a body was the
+  // top real-world baton error), and nothing must mutate before it's secured.
+  let body = null;
+  if (bodyFlag !== null) body = bodyFlag;
+  else if (bodyArg !== null) body = readBodyInput(bodyArg);
+  else {
+    // Auto-consume piped/redirected stdin, same probe as `dotmd new`.
+    try {
+      const stat = fstatSync(0);
+      if (stat.isFIFO() || stat.isFile() || stat.isSocket()) {
+        const piped = readFileSync(0, 'utf8');
+        if (piped.length > 0) body = piped;
+      }
+    } catch { /* stdin not introspectable */ }
+  }
+  if (!body || !body.trim()) die(BODY_USAGE);
+
+  // Resolve what's being handed off. Two modes:
+  //   plan mode — a plan is released alongside the prompt (one status flip).
+  //   slug mode — no plan involved: "save a resume prompt for what I'm doing
+  //   right now". The hallmark use ("update the docs and save a resume prompt
+  //   for this") must work mid-anything, claimed plan or not — baton does
+  //   nothing but save the prompt in this mode.
+  let planPath = null;
+  let promptSlug = null;
+  if (planArg) {
+    if (looksLikePath(planArg)) {
+      planPath = resolveDocArg(planArg, config); // typos die loudly — a mistyped path must not silently become a prompt name
+    } else {
+      // Bare word: a plan slug if it resolves to a plan, else a handoff name.
+      const resolved = resolveDocArg(planArg, config, { dieOnMiss: false });
+      let resolvedType = null;
+      if (resolved) {
+        try {
+          const { frontmatter: fmProbe } = extractFrontmatter(readFileSync(resolved, 'utf8'));
+          resolvedType = fmProbe ? asString(parseSimpleFrontmatter(fmProbe).type) : null;
+        } catch { resolvedType = null; }
+      }
+      if (resolved && resolvedType === 'plan') planPath = resolved;
+      else promptSlug = planArg;
+    }
+  } else {
+    const owned = findOwnedPlan(config);
+    if (owned.plan) {
+      planPath = path.resolve(config.repoRoot, owned.plan.path);
+      if (owned.via === 'single-in-session') {
+        process.stderr.write(dim(`Handing off the only in-session plan: ${owned.plan.path}\n`));
+      }
+    } else if (owned.inSession.length > 1) {
+      die(`Multiple plans are in-session and the journal can't tell which is this session's — pass yours explicitly:\n${owned.inSession.map(d => '  dotmd baton ' + d.path + ' @/tmp/draft.md').join('\n')}\nNot about a plan? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`);
+    } else {
+      die(`No in-session plan, so baton needs a name for the resume prompt:\n  dotmd baton <slug> @/tmp/draft.md      # saves resume-<slug>, touches nothing else\nHanding off a specific plan? dotmd baton <plan-file> @/tmp/draft.md`);
+    }
+  }
+
+  let repoPath = null;
+  let oldStatus = null;
+  if (planPath) {
+    repoPath = toRepoPath(planPath, config.repoRoot);
+    const raw = readFileSync(planPath, 'utf8');
+    const { frontmatter: fmRaw } = extractFrontmatter(raw);
+    if (!fmRaw) {
+      die(`${repoPath} has no frontmatter block — baton can't flip its status.\nFix the doc first (\`dotmd bulk-tag ${repoPath} --type plan --status in-session\`), or save the prompt without a status flip: dotmd baton ${path.basename(planPath, '.md')} @/tmp/draft.md`);
+    }
+    const fm = parseSimpleFrontmatter(fmRaw);
+    const docType = asString(fm.type);
+    oldStatus = asString(fm.status) ?? 'unset';
+    if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
+
+    // Validate the target status BEFORE creating the prompt so a bad --status
+    // doesn't leave a half-done handoff.
+    const validStatuses = config.typeStatuses?.get(docType ?? 'plan') ?? config.validStatuses;
+    if (validStatuses && validStatuses.size > 0 && !validStatuses.has(status)) {
+      die(`Invalid status \`${status}\` for type \`${docType ?? 'plan'}\`\nValid: ${[...validStatuses].join(', ')}`);
+    }
+  } else {
+    if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
+    if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
+  }
+
+  // 1. Save the resume prompt. Collision-safe: resume-<slug>, then -2, -3, …
+  // (a pending resume-<slug> from an earlier handoff must never block this one,
+  // and bodies are not mergeable).
+  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
+  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  let createdSlug = null;
+  for (let n = 1; n <= 9 && !createdSlug; n++) {
+    const slug = n === 1 ? slugBase : `${slugBase}-${n}`;
+    try {
+      await runNew(['prompt', slug, '--body', body], config, { dryRun });
+      createdSlug = slug;
+    } catch (err) {
+      if (!/File already exists/.test(String(err?.message))) throw err;
+    }
+  }
+  if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
+
+  // 2. Release the plan — exactly one status flip. Skipped entirely in slug
+  // mode: with no plan involved there is nothing to release.
+  let archiveResult = null;
+  let statusChanged = false;
+  if (planPath) {
+    if (oldStatus === status) {
+      process.stderr.write(dim(`Plan already ${status}: ${repoPath} (no status change)\n`));
+    } else {
+      const setArgs = [status, planPath];
+      if (note) setArgs.push('--note', note);
+      archiveResult = await runSet(setArgs, config, { dryRun });
+      statusChanged = true;
+    }
+  }
+
+  // 3. Tell the agent exactly what to commit — and what NOT to. The prompt is
+  // session-local (often gitignored); only the plan's frontmatter change is
+  // repo state.
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stderr.write(`\n${prefix}${green('✓ Baton passed')}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  if (statusChanged) {
+    const newRepoPath = archiveResult?.newRepoPath ?? null;
+    const pathspec = newRepoPath && newRepoPath !== repoPath ? `${repoPath} ${newRepoPath}` : repoPath;
+    let gitignored = false;
+    try {
+      const { isGitIgnored } = await import('./git.mjs');
+      gitignored = isGitIgnored(planPath, config.repoRoot);
+    } catch { /* not a git repo — fall through to the hint */ }
+    if (gitignored) {
+      process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
+    } else {
+      process.stderr.write(`${prefix}Commit the plan's status change (keep the prompt OUT of the pathspec — it's session-local):\n`);
+      process.stderr.write(`${prefix}  git commit -m "baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}" -- ${pathspec}\n`);
+    }
+  }
+}

package/src/commands.mjs

@@ -4,10 +4,10 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist', 'runlists',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
   'guard', 'misuse', 'update',
-  'ship', 'self-check',
+  'ship', 'self-check', 'baton',
 ];

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query', 'grep',
-  'plans', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'runlist', 'runlists', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 

package/src/doctor.mjs

@@ -155,6 +155,30 @@ function findDeprecatedCommandMentions(config) {
   return matches;
 }
 
+// Workflow-drift checks: configurations and docs that make the agent-facing
+// verbs (`use`, `set`, `baton`) blow up at the worst moment — mid-handoff.
+// Both failure modes came from real sessions: a repo whose plan vocab dropped
+// `in-session` (every `dotmd use` died), and a repo full of docs without
+// frontmatter blocks (every `dotmd set` died during closeout).
+function findWorkflowDrift(config) {
+  const docsWithoutFrontmatter = [];
+  for (const filePath of collectDocFiles(config)) {
+    let raw = '';
+    try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+    if (!raw.startsWith('---\n')) docsWithoutFrontmatter.push(toRepoPath(filePath, config.repoRoot));
+  }
+
+  const planStatusGaps = [];
+  const planStatuses = config.typeStatuses?.get('plan');
+  if (planStatuses && planStatuses.size > 0) {
+    for (const required of ['in-session', 'active']) {
+      if (!planStatuses.has(required)) planStatusGaps.push(required);
+    }
+  }
+
+  return { docsWithoutFrontmatter, planStatusGaps };
+}
+
 function runDoctorProject(config, { json = false } = {}) {
   const cliPackage = readJsonIfPresent(new URL('../package.json', import.meta.url));
   const repoPackage = readJsonIfPresent(path.join(config.repoRoot, 'package.json'));
@@ -165,11 +189,14 @@ function runDoctorProject(config, { json = false } = {}) {
     ?? null;
   const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
   const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
+  const { docsWithoutFrontmatter, planStatusGaps } = findWorkflowDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
     packageDependency: depVersion,
     claudeCommandWarnings,
     deprecatedCommandMentions,
+    docsWithoutFrontmatter,
+    planStatusGaps,
   };
 
   if (json) {
@@ -187,6 +214,17 @@ function runDoctorProject(config, { json = false } = {}) {
   } else {
     process.stdout.write('- docs mentioning deprecated commands: 0\n');
   }
+  if (docsWithoutFrontmatter.length) {
+    process.stdout.write(yellow(`- docs without a frontmatter block: ${docsWithoutFrontmatter.length} — every status verb (\`set\`, \`archive\`, \`baton\`) dies on these. Fix: dotmd bulk-tag <file> --type <type> --status <status>`) + '\n');
+    for (const file of docsWithoutFrontmatter.slice(0, 10)) process.stdout.write(`  - ${file}\n`);
+  } else {
+    process.stdout.write('- docs without a frontmatter block: 0\n');
+  }
+  if (planStatusGaps.length) {
+    process.stdout.write(yellow(`- plan status vocab missing: ${planStatusGaps.join(', ')} — \`dotmd use\` and \`dotmd baton\` depend on these; add them to types.plan.statuses in dotmd.config.mjs`) + '\n');
+  } else {
+    process.stdout.write('- plan status vocab: ok\n');
+  }
   return result;
 }
 

package/src/guard.mjs

@@ -58,6 +58,45 @@ function shellTokens(command) {
   return command.split(/\s+/).map(t => t.replace(/^['"]|['"]$/g, '')).filter(Boolean);
 }
 
+// Drop heredoc bodies, keeping the command line that opens them. Heredoc
+// bodies are document content — resume-prompt drafts routinely mention
+// `docs/prompts/…` paths and even describe the guard's own rules, and none of
+// that is the *command* doing anything.
+function stripHeredocBodies(command) {
+  if (typeof command !== 'string' || !command.includes('<<')) return command;
+  const lines = command.split('\n');
+  const out = [];
+  let marker = null;
+  for (const line of lines) {
+    if (marker !== null) {
+      if (line.trim() === marker) marker = null;
+      continue;
+    }
+    out.push(line);
+    const m = line.match(/<<-?\s*(['"]?)(\w+)\1/);
+    if (m) marker = m[2];
+  }
+  return out.join('\n');
+}
+
+// Split a compound command into independently-evaluated segments. Each side of
+// a pipe / && / || / ; / newline runs its own program, so a rule should only
+// fire on the segment whose program actually touches the prompt — `dotmd check
+// docs/prompts/x.md; git commit -- docs/plans/y.md` commits no prompt.
+function shellSegments(command) {
+  return stripHeredocBodies(command)
+    .split(/\|\|?|&&|;|\n/)
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+// Blank out quoted strings that contain whitespace — prose, not paths. A
+// commit message like `-m "handoff saved to docs/prompts/x.md"` only *mentions*
+// a prompt; `git add "docs/prompts/foo.md"` (no inner whitespace) survives.
+function stripProseStrings(s) {
+  return s.replace(/"([^"]*)"|'([^']*)'/g, (m, d, q) => (/\s/.test(d ?? q ?? '') ? '""' : m));
+}
+
 // Decision level for the status-edit rules. Hand-editing `status:` has no
 // legitimate variant — `dotmd set` is a complete substitute — so it denies by
 // default. `guard: { deny: false }` in config drops it back to warn-only.
@@ -87,48 +126,57 @@ const STREAM_EDITOR_INPLACE = [
 ];
 
 function evalBash(command, config, isIgnored) {
-  const tokens = shellTokens(command);
-  const promptTokens = tokens.filter(isPromptPath);
+  const segments = shellSegments(command);
 
-  // Rule A — committing/adding a gitignored prompt. The exact failure the guard
-  // exists for: an agent reflexively `git add`s a session-local prompt that
-  // lives under a gitignored path, and the commit dies confusingly.
-  if (/\bgit\s+(add|commit|stage)\b/.test(command) && promptTokens.length) {
-    const ignored = promptTokens.filter(p => isIgnored(p));
-    const targets = ignored.length ? ignored : promptTokens;
-    const ignoredNote = ignored.length
-      ? ` ${ignored.join(', ')} is gitignored — it cannot be committed.`
-      : '';
-    return {
-      decision: 'deny',
-      rule: 'commit-prompt',
-      detail: command,
-      reason:
-        `Saved prompts (${targets.join(', ')}) are session-local dotmd artifacts, not source to commit.${ignoredNote} ` +
-        `Don't git add/commit them. The next session consumes a prompt with \`dotmd use <file>\` (or \`dotmd use\` for the oldest pending), which prints the body and archives it atomically.`,
-    };
-  }
+  for (const seg of segments) {
+    const segTokens = shellTokens(stripProseStrings(seg));
+    if (!segTokens.length) continue;
+    const cmd0 = path.basename(segTokens[0]);
+    const promptTokens = segTokens.filter(isPromptPath);
+
+    // Rule A — committing/adding a gitignored prompt. The exact failure the
+    // guard exists for: an agent reflexively `git add`s a session-local prompt
+    // that lives under a gitignored path, and the commit dies confusingly.
+    // Scoped to the git segment's own arguments: a prompt path in a sibling
+    // segment (`dotmd check docs/prompts/x.md; git commit …`) or inside a
+    // quoted commit message is a mention, not a commit.
+    if (cmd0 === 'git' && /^(add|commit|stage)$/.test(segTokens[1] ?? '') && promptTokens.length) {
+      const ignored = promptTokens.filter(p => isIgnored(p));
+      const targets = ignored.length ? ignored : promptTokens;
+      const ignoredNote = ignored.length
+        ? ` ${ignored.join(', ')} is gitignored — it cannot be committed.`
+        : '';
+      return {
+        decision: 'deny',
+        rule: 'commit-prompt',
+        detail: command,
+        reason:
+          `Saved prompts (${targets.join(', ')}) are session-local dotmd artifacts, not source to commit.${ignoredNote} ` +
+          `Don't git add/commit them — commit your other changes without the prompt in the pathspec. ` +
+          `The next session consumes a prompt with \`dotmd use <file>\` (or \`dotmd use\` for the oldest pending), which prints the body and archives it atomically.`,
+      };
+    }
 
-  // Rule B — reading a prompt through the shell instead of consuming it.
-  if (tokens.length) {
-    const cmd0 = path.basename(tokens[0]);
+    // Rule B — reading a prompt through the shell instead of consuming it.
     if (SHELL_READERS.has(cmd0) && promptTokens.length) {
       return {
         decision: 'warn',
         rule: 'cat-prompt',
         detail: command,
         reason:
-          `${promptTokens.join(', ')} is a saved dotmd prompt. Don't \`${cmd0}\` it — run \`dotmd use ${promptTokens[0]}\` ` +
-          `to print the body and archive it in one atomic step (prevents the same prompt being consumed twice). Use \`dotmd use\` with no arg for the oldest pending prompt.`,
+          `${promptTokens.join(', ')} is a saved dotmd prompt. To start work from it, run \`dotmd use ${promptTokens[0]}\` — ` +
+          `it prints the body and archives the prompt in one atomic step (prevents double-consumption). ` +
+          `Just peeking or triaging (not consuming)? \`dotmd prompts show ${promptTokens[0]}\` reads it without archiving. Don't \`${cmd0}\` it directly.`,
       };
     }
   }
 
   // Rule C — in-place stream-editing `status:` in a managed doc. Same wrong-move
-  // as the Edit-tool rule, reached via the shell.
-  const beforeHeredoc = command.split(/<<-?\s*['"]?\w/)[0];
-  if (/status/.test(beforeHeredoc) && STREAM_EDITOR_INPLACE.some(re => re.test(beforeHeredoc))) {
-    const managed = shellTokens(beforeHeredoc).filter(t => isManagedDoc(t, config));
+  // as the Edit-tool rule, reached via the shell. Heredoc bodies are document
+  // content (often prose *describing* these rules), not commands.
+  const stripped = stripHeredocBodies(command);
+  if (/status/.test(stripped) && STREAM_EDITOR_INPLACE.some(re => re.test(stripped))) {
+    const managed = shellTokens(stripped).filter(t => isManagedDoc(t, config));
     if (managed.length) {
       return editStatusResult(managed[0], config, command);
     }
@@ -144,7 +192,8 @@ function evalRead(filePath) {
     rule: 'read-prompt',
     detail: filePath,
     reason:
-      `${filePath} is a saved dotmd prompt. Prefer \`dotmd use ${filePath}\` over reading it directly — it prints the body and archives the prompt atomically so it can't be double-consumed.`,
+      `${filePath} is a saved dotmd prompt. To start work from it, run \`dotmd use ${filePath}\` — it prints the body and archives the prompt atomically so it can't be double-consumed. ` +
+      `Just peeking or triaging (not consuming)? \`dotmd prompts show ${filePath}\` reads it without archiving.`,
   };
 }
 
@@ -205,8 +254,11 @@ function readStdin() {
       process.stdin.on('data', (c) => { data += c; });
       process.stdin.on('end', () => resolve(data));
       process.stdin.on('error', () => resolve(data));
-      // Don't hang the tool dispatch if stdin never closes.
-      setTimeout(() => resolve(data), 2000);
+      // Don't hang the tool dispatch if stdin never closes. unref() so the
+      // timer can't hold the event loop open — without it every guard
+      // invocation lingered the full 2s AFTER answering, which added ~2s of
+      // dead latency to every guarded tool call in every session.
+      setTimeout(() => resolve(data), 2000).unref();
     } catch {
       resolve(data);
     }

package/src/health.mjs

@@ -1,13 +1,32 @@
 import path from 'node:path';
 import { buildIndex } from './index.mjs';
 import { bold, dim, green, yellow, red } from './color.mjs';
+import { buildCoordinationIndex, hubLabel } from './runlist.mjs';
+import { isArchivedPath } from './util.mjs';
 
 export function runHealth(argv, config) {
   const json = argv.includes('--json');
   const index = buildIndex(config);
 
   // Only plans (type: plan or untyped docs in plans root)
-  const plans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  const allPlans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  // Coordination hubs (prose-first runlists) are navigation maps, not execution
+  // units — they carry no checklist and skew active-plan aging — so lift the
+  // LIVE ones out of the pipeline + active set into a dedicated Runlists tally,
+  // mirroring `dotmd plans` / `dotmd runlists`. Archived hubs stay in `plans` so
+  // the archived/velocity counts are unchanged. No coordination hubs → `plans`
+  // equals the full set and every count below is identical to before.
+  const coordination = buildCoordinationIndex(index, config);
+  const closedStatuses = new Set([
+    ...(config.lifecycle?.archiveStatuses ?? []),
+    ...(config.lifecycle?.terminalStatuses ?? []),
+  ]);
+  const isLiveHub = (d) => coordination.has(d.path) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
+  const runlistHubs = allPlans.filter(isLiveHub)
+    // Most stale first — health is an aging lens, and it matches `dotmd runlists`'
+    // default. Unknown-age hubs sort last so they never top the list.
+    .sort((a, b) => (b.daysSinceUpdate ?? -1) - (a.daysSinceUpdate ?? -1));
+  const plans = allPlans.filter(d => !isLiveHub(d));
   const now = Date.now();
 
   // Status distribution
@@ -68,24 +87,51 @@ export function runHealth(argv, config) {
       ready: { count: readyPlans.length },
       planned: { count: plannedPlans.length },
       recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
+      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0 })) },
     }, null, 2) + '\n');
     return;
   }
 
   process.stdout.write(bold('Plan Health') + '\n\n');
 
-  // Pipeline
+  // Pipeline — ordered by the configured status vocab, then any present-but-
+  // unconfigured statuses (custom ones a repo defines, by count). Deriving from
+  // the live status set means in-session/partial/awaiting/etc. all show, and a
+  // dead status never leaves an empty row — unlike the old hand-kept list that
+  // drifted out of sync with the vocabulary.
   process.stdout.write(bold('Pipeline:') + '\n');
-  const pipeline = ['active', 'paused', 'ready', 'planned', 'blocked', 'scoping', 'archived'];
-  for (const s of pipeline) {
-    const count = byStatus[s] || 0;
-    if (count > 0) {
-      const bar = '█'.repeat(Math.min(count, 40));
-      process.stdout.write(`  ${s.padEnd(10)} ${String(count).padStart(4)}  ${dim(bar)}\n`);
-    }
+  const statusOrder = config.statusOrder ?? [];
+  const present = Object.keys(byStatus).filter(s => byStatus[s] > 0);
+  const ordered = [
+    ...statusOrder.filter(s => present.includes(s)),
+    ...present.filter(s => !statusOrder.includes(s)).sort((a, b) => byStatus[b] - byStatus[a]),
+  ];
+  const pad = Math.max(10, ...ordered.map(s => s.length));
+  for (const s of ordered) {
+    const count = byStatus[s];
+    const bar = '█'.repeat(Math.min(count, 40));
+    process.stdout.write(`  ${s.padEnd(pad)} ${String(count).padStart(4)}  ${dim(bar)}\n`);
   }
   process.stdout.write('\n');
 
+  // Runlists (coordination hubs) — held out of the leaf-plan pipeline above and
+  // surfaced as their own tally so they don't inflate the active count. Newest
+  // first, mirroring `dotmd runlists`; capped with a "more" footer.
+  if (runlistHubs.length > 0) {
+    process.stdout.write(`${bold('Runlists:')} ${runlistHubs.length}  ${dim('· dotmd runlists')}\n`);
+    for (const doc of runlistHubs.slice(0, 8)) {
+      const slug = hubLabel(doc).padEnd(28);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
+      const rel = coordination.get(doc.path)?.childCount;
+      const relStr = rel ? `  ${dim(`${rel} related`)}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}\n`);
+    }
+    if (runlistHubs.length > 8) {
+      process.stdout.write(`  ${dim(`...and ${runlistHubs.length - 8} more`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
   // Active plan health
   if (activePlans.length > 0) {
     process.stdout.write(bold('Active plans:') + '\n');