dotmd-cli 0.79.1 → 0.81.0

package/README.md

@@ -54,9 +54,10 @@ shell, and runlist reads it as a per-session identity automatically.
 /plugin install dotmd@dotmd
 ```
 
-The plugin provides SessionStart and SubagentStart orientation, a PreToolUse
-guard, the canonical workflow skill, and `/plans`, `/docs`, `/prompts`, and
-`/baton` commands.
+The plugin provides SessionStart and SubagentStart orientation, a
+UserPromptSubmit hint that gives the exact `runlist baton` form when you ask for
+a handoff, a PreToolUse guard, the canonical workflow skill, and `/plans`,
+`/docs`, `/prompts`, and `/baton` commands.
 
 ### OpenCode Plugin
 

package/bin/dotmd.mjs

@@ -109,8 +109,9 @@ Common commands:
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
   use [<file-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
-  baton [<plan>|<slug>] <@<file>|-> Save a resume prompt (+ release the plan, if one is in-session)
                         (no file: consume oldest pending prompt)
+  baton [<plan>|<slug>] @<draft-file>
+                        Save a resume prompt (+ release the plan, if one is in-session)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
 More help:
@@ -229,7 +230,7 @@ View & Query:
   grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
-  baton [<plan>|<slug>] <@<file>|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
+  baton [<plan>|<slug>] @<draft>     Save a resume prompt; releases the plan + prints the commit when one is in-session
   prompts [list|show|archive|new] Prompt admin (list / peek / archive / save). Use \`runlist use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -917,49 +918,53 @@ Use --dry-run (-n) to preview without writing.`,
 
   new: `runlist new <type> <name> [body] — create a new document
 
-Types and their default destinations:
-  plan        docs/plans/<slug>.md     (build-up template: Problem → Phases → Closeout)
-  doc         docs/<slug>.md           (build-up lite: Overview → Version History → Related)
-  prompt      docs/prompts/<slug>.md   (saved prompt to seed a future session — body required)
-
-\`<type>\` can be omitted; defaults to \`doc\`.
-\`<name>\` is slugified for the filename.
-
-Body input (all built-in types — required for prompt, optional for plan/doc):
-  piped stdin            Auto-consumed when stdin is piped/redirected (no flag needed)
-  @path                  Read body from a file
-  -                      Explicit stdin marker (equivalent to piped stdin)
-  --body "<text>"        Explicit inline body (alias: --message)
-  <text>                 Inline body as 3rd positional
-
-Tip for agents: prefer piped stdin or \`@path\` for multi-line bodies. Inline
-bodies put the entire content on the bash command line, which (a) breaks
-under shell quoting for backticks/dollar-signs and (b) trips PreToolUse hooks
-that scan command strings for forbidden literals (destructive-git patterns,
-etc.). \`cat /tmp/foo.md | runlist new …\` and \`@/tmp/foo.md\` both sidestep both.
-
-For plan/doc, a single-section body lands under the type's first scaffolded
-section (e.g. \`## Problem\` for plans). If the body already authors
-\`## Section\` headings start-to-finish, the scaffold short-circuits and only
-the title + your body is emitted — no duplicated empty outline below
-(since 0.36.1).
+Usage (write the draft to a file first):
+  runlist new plan <slug> @/tmp/draft.md     # plan from a draft
+  runlist new doc <slug> @/tmp/draft.md      # reference doc from a draft
+  runlist new prompt <slug> @/tmp/draft.md   # saved prompt (body required)
+  runlist new plan <slug>                    # empty scaffold to fill in
+
+What the draft does:
+  - Draft with its own \`## \` headings → it IS the body. Only a \`# Title\` is
+    added if missing; the template's outline is not appended. This holds for a
+    repo's own plan/doc template too.
+  - Draft with no \`## \` headings → lands in the template's first section
+    (\`## Problem\` for plans).
+  - Draft opening with a \`---\` frontmatter block → those keys replace the
+    scaffold's (status, surfaces, modules, current_state, next_step, …), so no
+    frontmatter edit is needed afterwards. \`type:\` is fixed by <type>.
+  To change status later, use \`runlist set <status> <file>\`.
+
+The repo's own types, starting statuses and folders are listed at the end of
+this help when it runs inside a runlist repo.
+
+Body input (required for prompt, optional for plan/doc):
+  @path                  Read body from a file (preferred)
+  -                      Read stdin explicitly (heredoc: \`runlist new … - <<'EOF'\`)
+  piped stdin            Read when something is piped or redirected in
+  --body "<text>"        Inline body (alias: --message), one-liners only
+  <text>                 Inline body as 3rd positional, one-liners only
+
+Inline bodies put the whole content on the command line, which breaks on
+backticks and dollar signs and trips hooks that scan commands; use @path.
+
+\`<type>\` can be omitted; defaults to \`doc\`. \`<name>\` is slugified for the
+filename; a name with a \`/\` is read relative to the repo (or to --root).
 
 Examples:
-  runlist new plan auth-revamp
+  runlist new plan auth-revamp @/tmp/auth-revamp.md
   runlist new prompt resume-foo @/tmp/draft.md
-  cat /tmp/draft.md | runlist new prompt resume-foo
-  runlist new prompt resume-foo <<'EOF'
-  multi-line
-  prompt body
-  EOF
-  runlist new prompt cleanup-tomorrow "look at remaining lint warnings"
-  runlist new plan full-spec <<'EOF'
+  runlist new plan full-spec - <<'EOF'
+  ---
+  status: planned
+  next_step: Phase 1, extract the token store.
+  ---
   ## Problem
   …
   ## Phases
   …
   EOF
-  runlist new plan auth-revamp "Investigation findings before scoping…"
+  runlist new prompt cleanup-tomorrow "look at remaining lint warnings"
 
 Scaffolding runlists (plans only):
   --runlist <a,b,c>    Create a sprint runlist hub plus one child plan per slug.
@@ -1182,31 +1187,15 @@ Examples:
 
   baton: `runlist baton — save a resume prompt for whatever you're doing (and release the plan, if there is one)
 
-The "save a resume prompt" verb. Works mid-anything:
-
-Plan mode (a plan is in-session, or you pass one):
-  The following publish in one atomic cooperating transaction:
-  1. A resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …),
-     stamped with a plan: link so consuming it re-claims the plan (see \`runlist
-     use\`). The prompt is session-local — the next session's hud surfaces it;
-     never paste resume text into chat.
-  2. Releases the plan: one status flip, in-session → active by default
-     (--status to override, --note to record why in ## Version History).
-  3. Defers the shared generated index and prints exact repository-only commit
-     guidance. Prompt and ownership records stay session-local and OUT of the
-     pathspec.
-  Which plan? Pass it explicitly, or baton resolves exactly one plan owned by
-  this authoritative session. Journal entries and global in-session counts never
-  grant ownership. A live pickup-hook delivery lease blocks release and force
-  takeover; hooks are at-least-once and deduplicate the stable operationId.
+Usage (write the resume to a file first, then pick the form that matches):
+  runlist baton @/tmp/draft.md               # a plan is in-session: save resume-<plan-slug>, release the plan
+  runlist baton <plan-file> @/tmp/draft.md   # hand off a named plan
+  runlist baton <slug> @/tmp/draft.md        # no plan: save resume-<slug>, change nothing else
+  The resume can also come from stdin (\`-\`, or a pipe) or --message "..." for one-liners.
+  Baton prints the prompt name it saved and, in plan mode, the git commit to run.
 
-Slug mode (no plan involved — "save a resume prompt for this"):
-  runlist baton <slug> @/tmp/draft.md   →  saves resume-<slug>, touches NOTHING
-  else: no status changes, no commit, no plan required. Reference any relevant
-  plans/docs inside the draft body.
-
-Usage:
-  runlist baton [<plan-file> | <slug>] [@<draft-file> | - | --message "..."]
+The resume (10–20 lines): the next concrete decision plus any gotchas, and the
+paths of the plans/docs it concerns — not a recap of the plan body.
 
 Options:
   --status <s>           Target status for the plan (default: active; plan mode only)
@@ -1217,14 +1206,34 @@ Options:
   --dry-run, -n          Preview without writing
 
 Examples:
-  runlist baton @/tmp/draft.md                       # owned plan, body from file
-  runlist baton checkout-fixes @/tmp/draft.md        # no plan: just save resume-checkout-fixes
-  cat /tmp/draft.md | runlist baton                  # body from stdin
-  runlist baton docs/plans/auth.md @/tmp/draft.md    # explicit plan
+  runlist baton @/tmp/draft.md
+  runlist baton checkout-fixes @/tmp/draft.md
+  runlist baton docs/plans/auth.md @/tmp/draft.md
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
+  cat /tmp/draft.md | runlist baton
+
+Plan mode (a plan is in-session, or you pass one) publishes in one atomic
+cooperating transaction:
+  1. A resume prompt named resume-<plan-slug>, stamped with a plan: link so
+     consuming it re-claims the plan (see \`runlist use\`). The prompt is
+     session-local — the next session's hud surfaces it; never paste resume text
+     into chat.
+  2. Releases the plan: one status flip, in-session → active by default.
+  3. Defers the shared generated index and prints exact repository-only commit
+     guidance. Prompt and ownership records stay session-local and OUT of the
+     pathspec.
+  Which plan? Pass it explicitly, or baton resolves exactly one plan owned by
+  this authoritative session. Journal entries and global in-session counts never
+  grant ownership. A live pickup-hook delivery lease blocks release and force
+  takeover; hooks are at-least-once and deduplicate the stable operationId.
+
+Slug mode (no plan involved) saves resume-<slug> and touches nothing else: no
+status change, no commit. A bare word that names a plan is treated as that plan.
 
-Write the draft FIRST (10–20 lines): the next concrete decision plus any
-gotchas — not a recap of the plan body.`,
+Baton saves nothing while a handoff for the same work is pending (resume-<name>,
+or a pending prompt linked to the plan): consume or archive it, then re-run.
+With no @file, \`-\` or --message, baton reads stdin only when something is piped
+in; an open pipe that sends nothing is given up on after a moment.`,
 
   stale: `runlist stale — list stale documents
 
@@ -1600,6 +1609,17 @@ async function main() {
   if (args.includes('--help') || args.includes('-h')) {
     requireCommandPolicy(command, dispatchPolicy);
     process.stdout.write(`${HELP[command] ?? commandUsage(command)}\n`);
+    if (command === 'new') {
+      // Best effort: outside a runlist repo, or with a broken config, the
+      // static help above is the whole answer.
+      try {
+        const repoConfig = await resolveConfig(process.cwd(), explicitConfig);
+        if (repoConfig?.configFound !== false) {
+          const { newHelpForRepo } = await import('../src/new.mjs');
+          process.stdout.write(`\n${newHelpForRepo(repoConfig)}\n`);
+        }
+      } catch { /* static help already printed */ }
+    }
     return;
   }
 
@@ -1619,6 +1639,9 @@ async function main() {
       process.stdout.write('{}\n');
       return;
     }
+    // A prompt hook runs on every user message; a broken config must not
+    // turn each one into an error.
+    if (command === 'hud' && restArgs.includes('--prompt-submit')) return;
     throw err;
   }
   _resolvedConfig = config;
@@ -1820,6 +1843,12 @@ async function main() {
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
   // Lifecycle commands
+  if (command === 'hud' && restArgs.includes('--prompt-submit')) {
+    const { runPromptSubmitHud } = await import('../src/hud.mjs');
+    const { readHookStdin } = await import('../src/guard.mjs');
+    await runPromptSubmitHud(config, { readStdin: readHookStdin });
+    return;
+  }
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config, { dryRun }); return; }
   if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config, { dryRun }); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.79.1",
+  "version": "0.81.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/baton.mjs

@@ -30,8 +30,13 @@ export function findOwnedPlan(config, index = null) {
 // resume itself: the session that did the work is the only one that knows the
 // next decision, and a prompt assembled from frontmatter reads like a handoff
 // while carrying nothing the plan doesn't already say.
+// The three forms are listed because this is the message a bare `runlist baton`
+// prints, and an agent unsure of the shape should be able to act on it without
+// a trip through --help.
 const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
-  runlist baton [<plan-or-slug>] @/tmp/draft.md`;
+  runlist baton @/tmp/draft.md               # hand off the plan this session owns
+  runlist baton <plan-file> @/tmp/draft.md   # hand off a named plan
+  runlist baton <slug> @/tmp/draft.md        # no plan: save resume-<slug>, change nothing else`;
 
 // A handoff that lands beside a pending one leaves two prompts for the same
 // work, and the next session picks whichever sorts first. Baton used to step to
@@ -156,6 +161,7 @@ export async function runBaton(argv, config, opts = {}) {
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
+  let planGuard = null;
   if (planPath) {
     planPath = authorizeManagedSource(planPath, config, { kind: 'Baton plan source' }).path;
     repoPath = toRepoPath(planPath, config.repoRoot);
@@ -178,7 +184,29 @@ export async function runBaton(argv, config, opts = {}) {
     if (status === 'in-session') {
       die('`runlist baton --status in-session` contradicts baton release semantics. Choose active/paused/awaiting/partial/blocked.');
     }
-    assertPlanMutationAuthorized(repoPath, config, { sessionId: authoritativeSessionId(), force });
+    const sessionId = authoritativeSessionId();
+    const ownership = assertPlanMutationAuthorized(repoPath, config, { sessionId, force });
+    const ownedHere = ownership?.state === 'owned' && ownership.sessionId === sessionId;
+    // Baton's release only means something when there is a claim to release. A
+    // plan that is neither in-session nor owned here carries a status someone
+    // chose on purpose (`awaiting`, `blocked`, a repo's own `awaiting-testing`),
+    // and flipping it to the default `active` as a side effect of saving a
+    // prompt overwrites that reason — silently, since baton's headline is the
+    // prompt it saved. That is not hypothetical: a prompt-refresh pass named a
+    // plan slug, got a status flip it never asked for, and had to notice and
+    // undo it. So the prompt still lands with its `plan:` link, and the plan's
+    // status stays put unless the caller states the transition with --status.
+    const currentStatus = asString(fm.status);
+    if (!statusFlag && oldStatus !== 'in-session' && !ownedHere) {
+      if (!currentStatus || (validStatuses?.size > 0 && !validStatuses.has(currentStatus))) {
+        die(`${repoPath} is not in-session and its status (\`${oldStatus}\`) is not one baton can leave in place.\n`
+          + `Say what it should become: runlist baton ${repoPath} @<draft-file> --status <status>\n`
+          + `Or save the prompt without touching the plan: runlist baton ${path.basename(planPath, '.md')} @<draft-file>`);
+      }
+      status = currentStatus;
+      planGuard = { path: planPath, expectedContent: raw };
+      if (note) warn('--note ignored — the plan\'s status is unchanged, so there is no transition to record.');
+    }
     // Before the plan-completion step: a refusal must leave nothing changed.
     refuseIfPending();
     ownershipPath = readPlanOwnership(repoPath, config)?.recordPath ?? null;
@@ -216,7 +244,7 @@ export async function runBaton(argv, config, opts = {}) {
     const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
     const setArgs = [status, planPath];
     if (force) setArgs.push('--force');
-    if (note) setArgs.push('--note', note);
+    if (note && !planGuard) setArgs.push('--note', note);
     try {
       if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
       archiveResult = await runSet(setArgs, config, {
@@ -224,6 +252,7 @@ export async function runBaton(argv, config, opts = {}) {
         viaBaton: true,
         testHooks: opts.testHooks,
         creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
+        guards: planGuard && !dryRun ? [planGuard] : [],
         deferIndex: true,
       });
     } catch (err) {
@@ -292,6 +321,10 @@ export async function runBaton(argv, config, opts = {}) {
     return operationResult;
   }
   process.stderr.write(`\n${prefix}${green('✓ Baton passed')}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  if (planGuard) {
+    process.stderr.write(dim(`${repoPath} left at \`${oldStatus}\` — it was not in-session, so there was no claim to release.\n`));
+    process.stderr.write(dim(`Meant to change it? runlist set <status> ${repoPath}\n`));
+  }
   if (statusChanged) {
     const pathspec = operationResult.repositoryFiles.join(' ');
     let gitignored = false;

package/src/commands.mjs

@@ -64,7 +64,7 @@ const definitions = [
   command('briefing', none, 'read', [form('', { options: [flag('--json')] })]),
   command('context', none, 'read', [form('', { options: [flag('--json'), flag('--compact'), flag('--summarize'), value('--model')] })]),
   command('agent-context', none, 'read', [form('', { options: [flag('--json')] })]),
-  command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent')] })]),
+  command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent'), flag('--prompt-submit')] })]),
   command('focus', none, 'read', [form('[status]', { args: positionals(0, 1), options: [flag('--json')] })]),
   command('query', none, 'read', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
   command('grep', none, 'read', [form('<term> [terms...]', { args: positionals(1, Infinity), options: QUERY_OPTIONS })]),

package/src/git.mjs

@@ -122,8 +122,7 @@ export function getGitLastModifiedBatch(repoRoot, relPaths, options = {}) {
   assertSafeGitPaths(paths);
   if (paths.length === 0) return { dates: new Map(), commits: new Map(), history: new Map(), complete: true, reason: null };
   // Full-tree callers can supply a small set of configured root pathspecs for
-  // diff extraction. Revision selection still uses the exact requested paths,
-  // so excluded or unrelated documents cannot consume the commit bound.
+  // diff extraction.
   const scanPaths = options.pathspecs?.length ? [...new Set(options.pathspecs)] : paths;
   assertSafeGitPaths(scanPaths);
   const expectedPaths = new Set(paths);
@@ -133,10 +132,23 @@ export function getGitLastModifiedBatch(repoRoot, relPaths, options = {}) {
   const commitsByPath = new Map();
   const history = new Map();
   let reason = null;
+  // Revision selection uses the root pathspecs when the caller supplied them,
+  // not the full requested list: Git matches every pathspec against every
+  // commit's diff, so a full-tree scan of a ~5k-doc corpus spent ~14s here
+  // walking history 5k pathspecs at a time (the same walk costs ~0.25s against
+  // one root). The window can only widen, never narrow, per requested path —
+  // every requested path lives under a root, so a commit touching one matches
+  // the root too, and the window stays a newest-first prefix of history. What
+  // it costs is depth: commits touching only non-requested docs now consume the
+  // bound, so a path whose latest commit falls outside the window resolves to
+  // no date at all rather than to a stale one. That case is already accounted
+  // for below — an unresolved TRACKED path keeps `commit-limit`, which callers
+  // surface as "Git metadata is incomplete".
+  const revisionPathspecs = scanPaths.length < paths.length ? scanPaths : paths;
   const revisions = spawnSync('git', ['rev-list', '--stdin', `--max-count=${maxCommits + 1}`, revision], {
     cwd: repoRoot,
     encoding: 'utf8',
-    input: `--\n${paths.map(literalGitPathspec).join('\n')}\n`,
+    input: `--\n${revisionPathspecs.map(literalGitPathspec).join('\n')}\n`,
     maxBuffer,
   });
   if (revisions.error?.code === 'ENOBUFS') {

package/src/guard.mjs

@@ -365,7 +365,7 @@ export function evaluateGuard(payload, config, deps = {}) {
   return null;
 }
 
-function readStdin() {
+export function readHookStdin() {
   return new Promise((resolve) => {
     let data = '';
     try {
@@ -404,7 +404,7 @@ function emit(result) {
 export async function runGuard(argv, config, opts = {}) {
   let payload = {};
   try {
-    const raw = await readStdin();
+    const raw = await readHookStdin();
     if (raw && raw.trim()) payload = JSON.parse(raw);
   } catch {
     payload = {};

package/src/hud.mjs

@@ -1,12 +1,15 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { currentSessionId, isArchivedPath, relTime } from './util.mjs';
+import { asString, currentSessionId, isArchivedPath, relTime, toRepoPath } from './util.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { promptDirectory } from './new.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
 import { findOwnedPlan } from './baton.mjs';
+import { listOwnedPlans } from './pickup.mjs';
 import { actionablePromptStatuses, comparePromptDocs, resolveStatusMetadata } from './status-metadata.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
@@ -48,6 +51,41 @@ export function detectVersionDrift(env = process.env) {
 // status surfaced too, without needing a code change.
 // Returns repo paths, oldest-created first — the same order no-arg `dotmd use`
 // consumes them, so prompts[0] is always "the one you'd pick up next".
+// The same answer from the prompt directory alone, reading frontmatter only.
+// The full index read every body in the repo; at ~5k docs that took 10s and the
+// SessionStart hook's 5s timeout killed hud before it printed anything.
+export function findActionablePromptsInPromptDir(config) {
+  const actionable = actionablePromptStatuses(config);
+  const dir = promptDirectory(config);
+  if (!existsSync(dir)) return [];
+  const docs = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const abs = path.join(entry.parentPath ?? entry.path, entry.name);
+    const repoPath = toRepoPath(abs, config.repoRoot);
+    if (isArchivedPath(repoPath, config)) continue;
+    let fm;
+    try { fm = parseSimpleFrontmatter(extractFrontmatter(readFileSync(abs, 'utf8')).frontmatter ?? ''); }
+    catch { continue; }
+    const status = asString(fm.status);
+    if (asString(fm.type) !== 'prompt' || !actionable.has(status)) continue;
+    docs.push({ path: repoPath, status, created: asString(fm.created) || null, updated: asString(fm.updated) || null });
+  }
+  return docs.sort(comparePromptDocs).map(doc => doc.path);
+}
+
+// Text-mode hud: pending prompts and this session's plan, without the index.
+export function buildHudFast(config) {
+  let prompts = [];
+  let owned = null;
+  try { prompts = findActionablePromptsInPromptDir(config); } catch { /* hud must not fail */ }
+  try {
+    const records = listOwnedPlans(config);
+    if (!records.diagnostics?.length && records.length === 1) owned = { path: records[0].plan, title: null, via: 'ownership' };
+  } catch { /* hud must not fail */ }
+  return { owned, prompts, misuseRecap: buildMisuseRecap(config) };
+}
+
 function findActionablePrompts(config, index) {
   const actionable = actionablePromptStatuses(config);
   return index.docs
@@ -266,6 +304,47 @@ export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
 // the zero-false-positive signal for "this is a dotmd repo." A bare docs/ dir is
 // deliberately NOT enough — too many repos have one. In a non-dotmd repo the hook
 // then contributes nothing to the session: no primer, no index build, no heal.
+// UserPromptSubmit: when the user asks for a baton, tell the session the exact
+// form for its situation before it goes looking. Sessions ran `baton --help`
+// before nearly every baton even with the form in CLAUDE.md, because the right
+// form depends on whether this session owns a plan, which only runlist knows.
+const HANDOFF_ASK = /\bbaton\b|\bhand[\s-]?off\b|\bresume[\s-]prompt\b|\bsave (?:a |the )?resume\b|\bpick (?:it|this|that) (?:back )?up (?:next time|later|tomorrow)\b/i;
+
+export function isHandoffAsk(prompt) {
+  return typeof prompt === 'string' && HANDOFF_ASK.test(prompt);
+}
+
+export function buildHandoffContext(config) {
+  // Ownership records name their plans and are checked against those files
+  // alone; building the index here cost 9s in a repo of ~5k docs, past the
+  // hook's timeout.
+  let ownedPaths = [];
+  try {
+    const records = listOwnedPlans(config);
+    if (!records.diagnostics?.length) ownedPaths = records.map(record => record.plan);
+  } catch { /* fall through to the no-plan form */ }
+  const draft = 'Write the resume first (the next concrete decision, any gotchas, the plan/doc paths it concerns; not a recap) to a file in your scratchpad.';
+  const tail = 'Baton prints the prompt name it saved; tell the user that name. No `--help` needed.';
+  if (ownedPaths.length === 1) {
+    return `[runlist] Baton: this session owns ${ownedPaths[0]}. ${draft} Then run \`runlist baton @<file>\`: it saves the prompt, releases the plan to active (\`--status paused|awaiting|partial|blocked\` and \`--note "why"\` if that fits better), and prints the commit to run. ${tail}`;
+  }
+  if (ownedPaths.length > 1) {
+    return `[runlist] Baton: this session owns ${ownedPaths.length} plans (${ownedPaths.join(', ')}), so name the one to hand off. ${draft} Then run \`runlist baton <plan-file> @<file>\`. ${tail}`;
+  }
+  return `[runlist] Baton: this session owns no plan. ${draft} Then run \`runlist baton <slug> @<file>\` (saves resume-<slug>, changes nothing else), or \`runlist baton <plan-file> @<file>\` to hand off a plan by path. ${tail}`;
+}
+
+export async function runPromptSubmitHud(config, { readStdin } = {}) {
+  if (!isDotmdRepo(config)) return;
+  let prompt = '';
+  try {
+    const raw = await readStdin();
+    if (raw && raw.trim()) prompt = JSON.parse(raw).prompt ?? '';
+  } catch { return; }
+  if (!isHandoffAsk(prompt)) return;
+  process.stdout.write(buildHandoffContext(config) + '\n');
+}
+
 function isDotmdRepo(config) {
   return Boolean(config?.configFound);
 }
@@ -291,13 +370,14 @@ export function runHud(argv, config) {
   // the session. Skip the index build, slash-heal, primer, and drift line.
   if (!dotmdRepo && !json) return;
 
-  const hud = buildHud(config);
-
   if (json) {
+    const hud = buildHud(config);
     process.stdout.write(JSON.stringify({ ...hud, drift: drift ?? null }, null, 2) + '\n');
     return;
   }
 
+  const hud = buildHudFast(config);
+
   // SessionStart contract: the command primer, plus ONLY signals that carry a
   // direct instruction for this session. Passive state (error counts,
   // slash-command refresh notices, previous-self / fleet / recent-rejections)
@@ -313,7 +393,7 @@ export function runHud(argv, config) {
   //     Global in-session counts never provide a fallback.
   // The misuse recap stays for the same reason: a repeat-offense rule means
   // the primer alone isn't landing, so name the habit to break.
-  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@<file>|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<plan-or-slug>] @<draft-file> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
   process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
   if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[runlist] in-session (yours): ${hud.owned.path} — continue it; hand off with \`runlist baton @/tmp/draft.md\` before stopping.`) + '\n');

package/src/lifecycle.mjs

@@ -417,7 +417,15 @@ export async function runStatus(argv, config, opts = {}) {
 
   if (oldStatus === newStatus) {
     if (!dryRun && (opts.additionalUpdates?.length || opts.creations?.length)) {
-      mutateFileSet({ updates: opts.additionalUpdates ?? [], creations: opts.creations ?? [] }, {
+      // Guards belong here as much as on the mutating paths below: a caller that
+      // asked for the status it already has (baton's prompt-only handoff) decided
+      // that from this file's status and then writes only its creations, so the
+      // read and the write need something holding the gap.
+      mutateFileSet({
+        updates: opts.additionalUpdates ?? [],
+        creations: opts.creations ?? [],
+        guards: opts.guards ?? [],
+      }, {
         repoRoot: config.repoRoot,
         testHooks: opts.testHooks,
       });

package/src/new.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -348,13 +349,43 @@ export function readBodyInput(source) {
   return source;
 }
 
+// An agent's shell can hand a command a pipe that is open and never written or
+// closed (Claude Code does for chained and backgrounded commands), so a plain
+// blocking read of an implicit pipe hangs until the tool times out: a bare
+// `runlist baton` sat there for two minutes in the platform transcripts. A
+// child reads the pipe instead and gives up when the first byte doesn't arrive
+// within the window; once data starts it waits for EOF, so a slow producer that
+// has begun writing is never cut off.
+export const PIPED_STDIN_IDLE_MS = 1500;
+const STDIN_SILENT_EXIT = 3;
+const PIPE_READER = `let d='',got=false;` +
+  `const t=setTimeout(()=>{if(!got)process.exit(${STDIN_SILENT_EXIT})},Number(process.argv[1]));` +
+  `process.stdin.setEncoding('utf8');` +
+  `process.stdin.on('data',c=>{got=true;d+=c});` +
+  `process.stdin.on('end',()=>{clearTimeout(t);process.stdout.write(d)});`;
+
+function readPipeUnlessSilent() {
+  const r = spawnSync(process.execPath, ['-e', PIPE_READER, String(PIPED_STDIN_IDLE_MS)], {
+    stdio: [0, 'pipe', 'ignore'],
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (r.status !== 0) return null;
+  return r.stdout;
+}
+
 export function readPipedBodyInput() {
   try {
     const stat = fstatSync(0);
+    if (stat.isFile()) {
+      const redirected = readFileSync(0, 'utf8');
+      return redirected.length > 0 ? redirected : null;
+    }
     const isWindowsPipe = process.platform === 'win32' && !process.stdin.isTTY;
-    if (stat.isFIFO() || stat.isFile() || stat.isSocket() || isWindowsPipe) {
-      const piped = readFileSync(0, 'utf8');
-      return piped.length > 0 ? piped : null;
+    if (stat.isFIFO() || stat.isSocket() || isWindowsPipe) {
+      const piped = readPipeUnlessSilent();
+      return piped ? piped : null;
     }
   } catch { /* stdin not introspectable */ }
   return null;
@@ -368,6 +399,18 @@ export function titleize(s) {
   return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+// Where saved prompts are written: the prompt template's targetRoot when a
+// root matches it, else the primary root plus the template's `dir`.
+export function promptDirectory(config, template = resolveTemplate('prompt', config)) {
+  let targetRoot = config.docsRoot;
+  let routed = false;
+  if (template.targetRoot) {
+    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
+    if (match) { targetRoot = match; routed = true; }
+  }
+  return template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
+}
+
 export function preparePromptDocument(name, bodyInput, config, { plan = null, dryRun = false } = {}) {
   const template = resolveTemplate('prompt', config);
   const typeStatuses = config.typeStatuses?.get('prompt');
@@ -377,14 +420,7 @@ export function preparePromptDocument(name, bodyInput, config, { plan = null, dr
   if (!bodyInput?.trim()) die('`prompt` template requires a body.');
   const slug = slugify(path.basename(name, '.md'));
   const title = titleize(path.basename(name, '.md'));
-  let targetRoot = config.docsRoot;
-  let routed = false;
-  if (template.targetRoot) {
-    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
-    if (match) { targetRoot = match; routed = true; }
-  }
-  const baseDir = template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
-  const filePath = path.join(baseDir, `${slug}.md`);
+  const filePath = path.join(promptDirectory(config, template), `${slug}.md`);
   authorizeManagedDestination(filePath, config, { kind: 'Baton prompt destination' });
   if (dryRun) return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content: null };
 
@@ -989,7 +1025,13 @@ export async function runNew(argv, config, opts = {}) {
     if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
     let body;
     const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
-    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
+    // A repo that overrides the plan or doc template keeps the built-in promise
+    // that an authored body replaces the outline. Without this, the override's
+    // body fn dropped the draft into its first slot and appended its own
+    // sections after it, so a draft opening `## Problem` came out with two, and
+    // sessions trimmed the tail by hand. Other custom types render as written.
+    const overridesShortcutType = template._overridesBuiltin && (typeName === 'plan' || typeName === 'doc');
+    const authored = variantBody || overridesShortcutType ? fullBodyShortcut(docTitle, bodyInput) : null;
     if (authored !== null) body = authored;
     else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
     else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
@@ -1074,6 +1116,40 @@ export async function runNew(argv, config, opts = {}) {
   };
 }
 
+// The part of `new --help` only the repo can answer: which types exist here,
+// what status each starts at, which statuses are valid, and where each lands.
+// Sessions otherwise read the config file to find out.
+export function newHelpForRepo(config) {
+  // Only types with a template: a status-only type can't be created by `new`.
+  const types = new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(config.raw?.templates ?? {})]);
+  const rows = [];
+  const width = Math.max(...[...types].map(t => t.length));
+  for (const typeName of types) {
+    const template = resolveTemplate(typeName, config);
+    if (!template) continue;
+    const statuses = [...(config.typeStatuses?.get(typeName) ?? [])];
+    const tmplDefault = typeof template === 'object' ? template.defaultStatus : null;
+    const start = tmplDefault && (!statuses.length || statuses.includes(tmplDefault)) ? tmplDefault : (statuses[0] ?? tmplDefault ?? 'active');
+    const roots = config.docsRoots ?? [config.docsRoot];
+    // Mirrors runNew: a matching targetRoot wins, else the catch-all root plus
+    // the template's `dir`.
+    const typeRoot = typeof template === 'object' && template.targetRoot
+      ? roots.find(r => r.endsWith(template.targetRoot) || path.basename(r) === template.targetRoot)
+      : null;
+    const dest = typeRoot ?? (typeof template === 'object' && template.dir
+      ? path.join(catchAllRoot(config), template.dir)
+      : catchAllRoot(config));
+    const where = toRepoPath(dest, config.repoRoot) + '/';
+    const custom = Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName) ? ' (this repo\'s template)' : '';
+    rows.push(`  ${typeName.padEnd(width)} → ${where}<slug>.md, starts ${start}${custom}`);
+    if (statuses.length) rows.push(`  ${''.padEnd(width)}   statuses: ${statuses.join(', ')}`);
+  }
+  const roots = (config.docsRoots ?? [config.docsRoot]).map(r => path.basename(r));
+  return `This repo:
+${rows.join('\n')}
+  roots (for --root): ${roots.join(', ')}`;
+}
+
 function resolveTemplate(name, config) {
   const configTemplates = config.raw?.templates ?? {};
   const override = configTemplates[name];

package/src/prompts.mjs

@@ -56,7 +56,13 @@ export async function runPrompts(argv, config, opts = {}) {
 }
 
 function runPromptsList(argv, config, opts = {}) {
-  const index = buildIndex(config);
+  // Listing prompts renders slug / status / updated / target — nothing any
+  // validating pass produces, and `runQuery` never reads warnings either. A
+  // full `buildIndex` here parsed every body in the repo through the ref,
+  // git-staleness and hub passes (~25s on a 5k-doc corpus) to print ten lines,
+  // and then `pendingPromptsOldestFirst` scanned the tree a second time. One
+  // fast index, shared, on the same terms hud reads on.
+  const index = buildIndex(config, { fast: true, invokeHooks: false });
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
@@ -87,7 +93,7 @@ function runPromptsList(argv, config, opts = {}) {
 }
 
 function renderPromptQueueList(index, config) {
-  const queue = pendingPromptsOldestFirst(config);
+  const queue = pendingPromptsOldestFirst(config, index);
   const queuedPaths = new Set(queue.map(q => q.doc.path));
   const others = index.docs
     .filter(d => d.type === 'prompt' && !queuedPaths.has(d.path) && !isArchivedPath(d.path, config) && d.status !== 'archived')
@@ -175,8 +181,12 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
   }
 }
 
-export function pendingPromptsOldestFirst(config) {
-  const index = buildIndex(config, { fast: true, invokeHooks: false });
+// `index` lets a caller that already has a fast index (the prompt listings)
+// share it rather than re-walking the tree. It must be a full index of the
+// repo: the filter below narrows it, so a pre-filtered one would drop prompts
+// from the queue.
+export function pendingPromptsOldestFirst(config, index = null) {
+  index = index ?? buildIndex(config, { fast: true, invokeHooks: false });
   const actionable = actionablePromptStatuses(config);
   const prompts = index.docs.filter(d =>
     d.type === 'prompt'

package/src/util.mjs

@@ -221,6 +221,48 @@ export function levenshtein(a, b) {
   return matrix[b.length][a.length];
 }
 
+// Edit distance, but only as far as the caller cares. Returns the distance when
+// it is <= limit and null when it provably exceeds it. The suggester asks
+// "within 3 edits?" of every candidate in the index, and the full matrix
+// computes an exact answer it then throws away: ~900 cells and two allocations
+// per pair, several hundred thousand pairs per unresolved reference on a large
+// corpus. Only cells within `limit` of the diagonal can hold a value <= limit,
+// so this walks that band in two flat rows and abandons a row whose cheapest
+// cell is already past the limit. Distances <= limit are identical to
+// `levenshtein`'s — test/util.test.mjs checks that against it directly.
+export function levenshteinWithin(a, b, limit) {
+  if (Math.abs(a.length - b.length) > limit) return null;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const over = limit + 1;
+  let prev = new Int32Array(a.length + 2).fill(over);
+  let cur = new Int32Array(a.length + 2).fill(over);
+  for (let j = 0; j <= Math.min(a.length, limit); j++) prev[j] = j;
+  for (let i = 1; i <= b.length; i++) {
+    const lo = Math.max(1, i - limit);
+    const hi = Math.min(a.length, i + limit);
+    // Reset the cells this row will write plus the two the next row reads as
+    // band neighbours, so nothing stale survives the row swap.
+    cur.fill(over, Math.max(0, lo - 1), hi + 2);
+    cur[0] = i <= limit ? i : over;
+    let rowMin = over;
+    for (let j = lo; j <= hi; j++) {
+      const substitution = prev[j - 1] + (b.charCodeAt(i - 1) === a.charCodeAt(j - 1) ? 0 : 1);
+      const deletion = prev[j] + 1;
+      const insertion = cur[j - 1] + 1;
+      let best = substitution < deletion ? substitution : deletion;
+      if (insertion < best) best = insertion;
+      if (best > limit) best = over;
+      cur[j] = best;
+      if (best < rowMin) rowMin = best;
+    }
+    if (rowMin > limit) return null;
+    const swap = prev; prev = cur; cur = swap;
+  }
+  const distance = prev[a.length];
+  return distance <= limit ? distance : null;
+}
+
 // Top-N candidates from a list, ranked for "did you mean" hints. Substring
 // match wins (cheap and intent-revealing for typos that share a prefix or
 // stem); Levenshtein distance ≤3 catches transpositions and small edits.
@@ -246,8 +288,12 @@ export function suggestCandidates(query, candidates, max = 3) {
       if (!cand || scored.has(cand)) continue;
       const candLower = String(cand).toLowerCase();
       if (candLower === lower) continue;
-      const dist = levenshtein(lower, candLower);
-      if (dist <= 3) scored.set(cand, 1000 + dist);
+      // The candidate list here is every basename AND every repo path in the
+      // index, so on a large corpus this loop ran hundreds of thousands of
+      // distance computations per unresolved reference. Only "within 3 edits"
+      // matters, so it asks for exactly that.
+      const dist = levenshteinWithin(lower, candLower, 3);
+      if (dist !== null) scored.set(cand, 1000 + dist);
     }
   }
 

package/src/validate.mjs

@@ -338,14 +338,25 @@ function candidatePathsForType(docs, type) {
 // can't see siblings). Filters candidates by ref-field type when the field
 // name implies one (e.g. `related_plans` → plans only).
 export function enrichRefErrorSuggestions(docs, config) {
+  // One candidate list per inferred type, not per broken ref. The list is a
+  // filter plus a ~2-per-doc Set build over the whole index, and it does not
+  // depend on the entry — rebuilding it for each entry made this pass quadratic
+  // in (docs × broken refs), which on a 4.8k-doc corpus with a couple hundred
+  // unresolved refs was ~9s of every `check`, `briefing` and `plans` run.
+  const candidateCache = new Map();
+  const candidatesFor = (type) => {
+    const key = type ?? '';
+    if (!candidateCache.has(key)) candidateCache.set(key, candidatePathsForType(docs, type));
+    return candidateCache.get(key);
+  };
+
   const enrich = (entry) => {
     if (!entry?.meta || !['ref-resolution', 'body-link-resolution'].includes(entry.meta.kind)) return;
     if (entry.meta.kind === 'body-link-resolution'
       && (entry.meta.targetKind !== 'document' || entry.meta.reason !== 'missing')) return;
     if (entry._suggested) return;
     const inferred = inferRefFieldType(entry.meta.field);
-    const candidates = candidatePathsForType(docs, inferred);
-    const suggestions = suggestCandidates(path.basename(entry.meta.relPath), candidates);
+    const suggestions = suggestCandidates(path.basename(entry.meta.relPath), candidatesFor(inferred));
     entry._suggested = true;
     if (suggestions.length === 0) return;
     entry.message = `${entry.message} Did you mean: ${suggestions.join(', ')}?`;