dotmd-cli 0.70.4 → 0.71.1

package/bin/dotmd.mjs

@@ -109,7 +109,7 @@ 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>] <@draft|-> Save a resume prompt (+ release the plan, if one is in-session)
+  baton [<plan>|<slug>] <@<file>|-> Save a resume prompt (+ release the plan, if one is in-session)
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -180,7 +180,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>] <@draft|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
+  baton [<plan>|<slug>] <@<file>|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
   prompts [list|show|archive|new|hold] Prompt admin (list / peek / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -201,6 +201,7 @@ Analyze:
 
 Validate & Fix:
   doctor [--apply]                  Auto-fix everything: refs, lint, long fields, dates, index (preview by default)
+  doctor --transactions             Report/clear wedged mutation transactions (run this if mutations refuse repo-wide)
   self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
@@ -711,6 +712,16 @@ Modes:
                          (F4). Use --apply (alias --yes) to actually write;
                          explicit --dry-run still wins over --apply if both
                          are passed (safety prevails).
+  --transactions         Report pending mutation transactions. A transaction
+                         abandoned mid-flight can reach \`failed-manual\`, and
+                         recovery sweeps the whole repo on every mutation —
+                         so ONE wedged transaction makes \`set\`, \`archive\`,
+                         \`use\`, \`baton\`, and \`rename\` refuse repo-wide,
+                         naming a file the failing command never touched.
+                         Run this first when that happens. Add --apply to
+                         clear the transactions whose files already agree on
+                         one generation (no document content is touched);
+                         the rest are reported for manual review.
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -1038,6 +1049,9 @@ Examples:
   dotmd prompt list                    # singular alias for \`dotmd prompts list\`
 
   dotmd prompts show resume-foo        # peek without consuming (triage)
+  dotmd prompts show --all             # peek the WHOLE pending queue in one call
+  dotmd prompts show --all --limit 10  # ...capped
+  dotmd prompts show a b c             # peek several by name
   dotmd prompts next --dry-run         # preview without consuming
   dotmd prompts archive old-thing
   dotmd prompts new my-prompt "Body text here"`,
@@ -1068,7 +1082,7 @@ Slug mode (no plan involved — "save a resume prompt for this"):
   plans/docs inside the draft body.
 
 Usage:
-  dotmd baton [<plan-file> | <slug>] [@draft.md | - | --message "..."]
+  dotmd baton [<plan-file> | <slug>] [@<draft-file> | - | --message "..."]
 
 Options:
   --status <s>           Target status for the plan (default: active; plan mode only)

package/package.json

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

package/src/atomic-mutation.mjs

@@ -194,7 +194,10 @@ function transactionRepairMessage(manifestPath, manifest, reason) {
     manifest.gitIndex?.prepared?.tempPath,
     ...(manifest.gitIndex?.retainedPaths ?? []),
   ].filter(Boolean);
-  return `${reason}\nTransaction recovery refused to guess. Manifest: ${manifestPath}\nInspect the canonical files and recovery artifacts, then restore one complete generation and remove the manifest:\n${artifacts.map(item => `  ${item}`).join('\n') || '  (no content artifacts)'}`;
+  return `${reason}\nTransaction recovery refused to guess. Manifest: ${manifestPath}\n` +
+    `Start with \`dotmd doctor --transactions\` — it reports this transaction's state and resolves it when the canonical files agree on one generation.\n` +
+    `If it reports the generations as ambiguous, inspect the canonical files and recovery artifacts, then restore one complete generation and remove the manifest:\n` +
+    `${artifacts.map(item => `  ${item}`).join('\n') || '  (no content artifacts)'}`;
 }
 
 function assertString(value, label, { nullable = false } = {}) {
@@ -445,8 +448,19 @@ export function recoverAbandonedTransactions(repoRoot, options = {}) {
       throw new MutationConflictError(transactionRepairMessage(manifestPath, manifest, 'Canonical generations are ambiguous.'));
     }
     const rollForward = states.every(state => state === 'new');
+    // Lock acquisition is the one step here that fails for a reason that is not
+    // evidence of damage: another process holds these paths, almost always
+    // because it is recovering this same abandoned transaction. Nothing inside
+    // the callback acquires a lock, so a MutationLockError always means the
+    // callback never ran and no generation was touched — the manifest is exactly
+    // as it was. Marking it failed-manual on that (see the catch below, which
+    // is otherwise correct to retain evidence) turned transient contention into
+    // a permanent repo-wide brick: every later mutation hit the failed-manual
+    // check above and refused, for a transaction unrelated to it.
+    let locked = false;
     try {
       withPathLocks(manifest.participants.map(item => item.path), { repoRoot, ...options }, () => {
+        locked = true;
         const lockedStates = manifest.participants.map(participantState);
         if (lockedStates.includes('unknown')) {
           throw new MutationConflictError(transactionRepairMessage(manifestPath, manifest, 'Canonical generations changed while recovery acquired locks.'));
@@ -538,6 +552,13 @@ export function recoverAbandonedTransactions(repoRoot, options = {}) {
         retainedGitPaths,
       });
     } catch (err) {
+      if (!locked && err instanceof MutationLockError) {
+        // Whoever holds the lock finishes (or re-abandons) this transaction;
+        // either way it stays recoverable. The caller's own withPathLocks still
+        // guards the paths it actually mutates, so proceeding is safe.
+        recovered.push({ id: manifest.id, result: 'deferred-locked' });
+        continue;
+      }
       try {
         manifest.phase = 'failed-manual';
         manifest.result = 'failed-manual';
@@ -550,6 +571,87 @@ export function recoverAbandonedTransactions(repoRoot, options = {}) {
   return recovered;
 }
 
+// Report on every transaction manifest without mutating anything, so a wedged
+// repo can be diagnosed. `recoverAbandonedTransactions` deliberately refuses to
+// guess and throws; that left no way to even SEE the state short of reading
+// JSON by hand, and a single failed-manual manifest blocks every mutation in
+// the repo. Never throws for a manifest it cannot parse — an unreadable one is
+// itself the finding.
+export function inspectTransactions(repoRoot, options = {}) {
+  const root = transactionRoot(repoRoot, options);
+  if (!existsSync(root)) return [];
+  const report = [];
+  for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      report.push({ id: entry.name, readable: false, reason: 'Unsafe entry in transaction root', resolvable: false });
+      continue;
+    }
+    const directory = path.join(root, entry.name);
+    const manifestPath = path.join(directory, 'manifest.json');
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); }
+    catch (err) {
+      report.push({ id: entry.name, directory, manifestPath, readable: false, reason: err?.code === 'ENOENT' ? 'No manifest' : `Unreadable manifest: ${err.message}`, resolvable: false });
+      continue;
+    }
+    try { validateManifest(manifest, manifestPath, directory, repoRoot, options); }
+    catch (err) {
+      report.push({ id: entry.name, directory, manifestPath, readable: false, reason: err.message, resolvable: false });
+      continue;
+    }
+    const participants = manifest.participants.map(item => ({ path: item.path, state: participantState(item) }));
+    const states = new Set(participants.map(item => item.state));
+    const retainedGitPaths = (manifest.gitIndex?.retainedPaths ?? []).filter(item => existsSync(item));
+    const retainedDirectories = manifest.createdDirectories.filter(item => existsSync(item.path)).map(item => item.path);
+    // Safe to clear only when the filesystem already shows one uniform
+    // generation: that IS the atomicity the transaction existed to guarantee,
+    // so the manifest is bookkeeping for work that is fully done or fully
+    // undone. Anything mixed, unknown, or with retained artifacts stays put.
+    const uniform = states.size === 1 && (states.has('old') || states.has('new'));
+    report.push({
+      id: manifest.id,
+      directory,
+      manifestPath,
+      readable: true,
+      status: manifest.status,
+      phase: manifest.phase,
+      result: manifest.result,
+      operation: manifest.operation,
+      createdAt: manifest.createdAt,
+      ownerLiveness: processOwnerLiveness(manifest.owner),
+      participants,
+      generation: uniform ? [...states][0] : null,
+      retainedGitPaths,
+      retainedDirectories,
+      resolvable: uniform && retainedGitPaths.length === 0 && retainedDirectories.length === 0,
+      reason: uniform
+        ? (retainedGitPaths.length || retainedDirectories.length ? 'Retained artifacts need manual review' : null)
+        : 'Canonical files do not agree on one generation',
+    });
+  }
+  return report;
+}
+
+// Clear the manifests inspectTransactions marked resolvable. Touches no
+// canonical file — those already agree on one generation; this only removes the
+// bookkeeping that is wedging later mutations.
+export function resolveTransactions(repoRoot, options = {}) {
+  const cleared = [];
+  for (const item of inspectTransactions(repoRoot, options)) {
+    if (!item.resolvable) continue;
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(item.manifestPath, 'utf8')); } catch { continue; }
+    withPathLocks(manifest.participants.map(entry => entry.path), { repoRoot, ...options }, () => {
+      // Re-check under the lock: nothing may have moved since inspection.
+      const states = new Set(manifest.participants.map(participantState));
+      if (states.size !== 1 || !(states.has('old') || states.has('new'))) return;
+      cleanupTransactionDirectory(item.directory, manifest, options);
+      cleared.push({ id: item.id, generation: [...states][0] });
+    });
+  }
+  return cleared;
+}
+
 function ensureDirectoryDurable(directory, options, phase) {
   if (existsSync(directory)) return false;
   const parent = path.dirname(directory);

package/src/commands.mjs

@@ -94,7 +94,7 @@ const definitions = [
     form('list', { subcommands: ['list', 'status'], options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
     form('next', { subcommands: ['next'] }),
     form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force')] }),
-    form('show [file]', { subcommands: ['show', 'peek'], args: positionals(0, 1), options: [flag('--json')] }),
+    form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
@@ -102,7 +102,7 @@ const definitions = [
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@draft|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
@@ -133,7 +133,7 @@ const definitions = [
   command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files')] })]),
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--json'), flag('--include-archived')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),

package/src/doctor.mjs

@@ -14,6 +14,7 @@ import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
 import { normalizeEol } from './frontmatter.mjs';
 import { toRepoPath } from './util.mjs';
+import { inspectTransactions, resolveTransactions } from './atomic-mutation.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
 // MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
@@ -44,6 +45,65 @@ const CUE_LABELS = {
   blocked: '"hardware", "vendor", "third-party", "rollout"',
 };
 
+// A wedged repo reports here. One failed-manual manifest makes every `set`,
+// `archive`, `use`, `baton`, and `rename` in the repo refuse — and the error
+// names a file the command never touched, because recovery sweeps the whole
+// transaction root. This is the only surface that can see and clear that state.
+function runDoctorTransactions(argv, config, opts = {}) {
+  const json = argv.includes('--json');
+  // The dispatcher strips --apply/--yes and folds them into opts.dryRun, which
+  // for doctor already means "preview unless the user asked to write".
+  const apply = !opts.dryRun;
+  const report = inspectTransactions(config.repoRoot);
+
+  const cleared = apply ? resolveTransactions(config.repoRoot) : [];
+  const clearedIds = new Set(cleared.map(item => item.id));
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ transactions: report, cleared }, null, 2) + '\n');
+    return;
+  }
+
+  if (report.length === 0) {
+    process.stdout.write(green('✓') + ' No pending transactions — nothing is wedging mutations.\n');
+    return;
+  }
+
+  process.stdout.write(bold(`Transactions (${report.length})\n`));
+  for (const item of report) {
+    if (!item.readable) {
+      process.stdout.write(`  ${yellow('?')} ${item.id} — ${item.reason}\n`);
+      continue;
+    }
+    const blocking = item.status === 'failed-manual';
+    const mark = clearedIds.has(item.id) ? green('✓') : blocking ? yellow('!') : dim('·');
+    const note = clearedIds.has(item.id)
+      ? 'cleared'
+      : item.resolvable ? 'resolvable' : (item.reason ?? item.status);
+    process.stdout.write(`  ${mark} ${item.id} [${item.status}] ${item.operation} — owner ${item.ownerLiveness}, ${note}\n`);
+    for (const participant of item.participants) {
+      process.stdout.write(dim(`      ${participant.state.padEnd(9)} ${toRepoPath(participant.path, config.repoRoot)}\n`));
+    }
+    for (const retained of item.retainedGitPaths) {
+      process.stdout.write(dim(`      retained  ${retained}\n`));
+    }
+  }
+
+  const resolvable = report.filter(item => item.resolvable && !clearedIds.has(item.id));
+  if (cleared.length) {
+    process.stdout.write(green(`\n✓ Cleared ${cleared.length} transaction${cleared.length === 1 ? '' : 's'} whose files already agreed on one generation.\n`));
+  }
+  if (resolvable.length) {
+    process.stdout.write(`\n${resolvable.length} resolvable — the canonical files already agree on one generation.\n`);
+    process.stdout.write(dim('Run `dotmd doctor --transactions --apply` to clear them (no document content is touched).\n'));
+  }
+  const stuck = report.filter(item => !item.resolvable && !clearedIds.has(item.id) && (item.status === 'failed-manual' || !item.readable));
+  if (stuck.length) {
+    process.stdout.write(yellow(`\n${stuck.length} need manual review — generations disagree, so clearing them could lose work.\n`));
+    process.stdout.write(dim('Inspect the participant paths above against the artifacts in each transaction directory.\n'));
+  }
+}
+
 export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
@@ -65,6 +125,10 @@ export function runDoctor(argv, config, opts = {}) {
     runFrontmatterFix(config, opts);
     return;
   }
+  if (argv.includes('--transactions')) {
+    runDoctorTransactions(argv, config, opts);
+    return;
+  }
 
   const { dryRun, testHooks } = opts;
   // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run

package/src/guard.mjs

@@ -305,7 +305,8 @@ function evalRead(filePath, config) {
     detail: filePath,
     reason:
       `${filePath} is a saved dotmd prompt. To start work from it, run \`dotmd use ${filePath}\` — it commits archive/claim before at-most-once body output so it can't be double-consumed. ` +
-      `Just peeking or triaging (not consuming)? \`dotmd prompts show ${filePath}\` reads it without archiving.`,
+      `Just peeking or triaging (not consuming)? \`dotmd prompts show ${filePath}\` reads it without archiving. ` +
+      `Surveying the whole queue? \`dotmd prompts show --all\` peeks every pending prompt in one call — don't Read them file by file.`,
   };
 }
 

package/src/hud.mjs

@@ -326,7 +326,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('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@draft|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  process.stdout.write(dim('dotmd: 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(buildPlanStatusPrimer(config)) + '\n');
   if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[dotmd] in-session (yours): ${hud.owned.path} — continue it; hand off with \`dotmd baton @/tmp/draft.md\` before stopping.`) + '\n');

package/src/lifecycle.mjs

@@ -1036,7 +1036,10 @@ export async function runSet(argv, config, opts = {}) {
       warn('partial usually references the successor plan tracking the tail — add a link to the body, or rerun with --note "tail tracked in <plan>".');
     }
     if (batonNudge) {
-      warn(`wrapping up? leave a baton so the next session picks up cleanly — \`dotmd baton ${path.basename(filePath, '.md')} @draft\` saves a resume prompt (no copy-paste into chat).`);
+      // `@<draft-file>` stays an obvious metavariable: the old `@draft` read as
+      // a runnable path and got copied verbatim into failing batons. If it is
+      // copied anyway, readBodyInput recognizes the <…> form and says so.
+      warn(`wrapping up? leave a baton so the next session picks up cleanly — write your resume notes to a file, then \`dotmd baton ${path.basename(filePath, '.md')} @<draft-file>\` saves a resume prompt (no copy-paste into chat).`);
     }
   }
   return result;

package/src/new.mjs

@@ -271,13 +271,37 @@ function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
   return fm;
 }
 
+// Metavariables that ship in help text, `dotmd baton`'s signature, and the
+// wrap-up nudge. Agents copy them verbatim, and the bare `Body file not found:
+// draft` that resulted read like a missing file rather than an unsubstituted
+// placeholder — so the retry was usually another guess at the path. Only
+// consulted after existsSync fails, so a real file by any of these names wins.
+const BODY_PLACEHOLDER_NAMES = new Set([
+  'draft', 'draft.md', '/tmp/draft.md', 'tmp/draft.md',
+  '/tmp/baton.md', '/tmp/my-draft.md',
+  'path', 'file', 'body', 'FILE', 'PATH', 'BODY',
+]);
+
+function isBodyPlaceholder(file) {
+  if (/^<.+>$/.test(file)) return true; // <draft-file>, <path>, …
+  return BODY_PLACEHOLDER_NAMES.has(file);
+}
+
 export function readBodyInput(source) {
   if (source === '-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
   }
   if (typeof source === 'string' && source.startsWith('@')) {
     const file = source.slice(1);
-    if (!existsSync(file)) die(`Body file not found: ${file}`);
+    if (!existsSync(file)) {
+      if (isBodyPlaceholder(file)) {
+        die(`\`@${file}\` is a placeholder, not a real path — write the body to a file first, then pass it:\n` +
+          `  @/tmp/my-draft.md   read the body from that file\n` +
+          `  -                   read the body from stdin (\`cat notes.md | dotmd …\`)\n` +
+          `  --message "..."     short one-liners only`);
+      }
+      die(`Body file not found: ${file}`);
+    }
     return readFileSync(file, 'utf8');
   }
   return source;

package/src/prompts.mjs

@@ -397,23 +397,80 @@ function prepareLinkedPromptClaim(planRef, config) {
 // Read-only peek: print the body WITHOUT consuming. The sanctioned triage path
 // — surveying pending prompts must not archive them (that's `use`'s job), and
 // it must not require raw cat/Read (which the guard warns about).
-function runPromptsShow(argv, config) {
-  const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts show <file-or-slug>');
-  const filePath = resolvePromptInput(input, config);
-
+// Read one prompt for peeking. Returns null rather than dying so a bulk sweep
+// isn't aborted by a single bad doc.
+function readPromptForShow(filePath, config, { strict }) {
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
   const repoPath = toRepoPath(filePath, config.repoRoot);
   if (asString(parsed.type) !== 'prompt') {
-    die(`Not a prompt (type: ${asString(parsed.type) ?? 'unknown'}): ${repoPath}`);
+    if (strict) die(`Not a prompt (type: ${asString(parsed.type) ?? 'unknown'}): ${repoPath}`);
+    return null;
+  }
+  return { repoPath, body, status: asString(parsed.status) ?? 'unknown' };
+}
+
+// Triage the queue without consuming it. Bulk mode exists because surveying a
+// backlog was the one thing `show` could not do: sessions sweeping 25-28 saved
+// prompts had to fall back to Read, which the guard then warned about once per
+// file. `--all` and multiple paths make the supported route the cheap one.
+function runPromptsShow(argv, config) {
+  const all = argv.includes('--all');
+  const limitIdx = argv.indexOf('--limit');
+  const limit = limitIdx >= 0 ? Number.parseInt(argv[limitIdx + 1], 10) : null;
+  if (limitIdx >= 0 && (!Number.isInteger(limit) || limit < 1)) {
+    die('--limit takes a positive integer.');
   }
+  // Skip the value that belongs to --limit; it is not a prompt name. Guard the
+  // absent case explicitly — limitIdx is -1 there, and -1 + 1 would drop argv[0].
+  const limitValueIdx = limitIdx >= 0 ? limitIdx + 1 : -1;
+  const inputs = argv.filter((a, i) => !a.startsWith('-') && i !== limitValueIdx);
 
-  const status = asString(parsed.status) ?? 'unknown';
-  process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`dotmd use ${repoPath}\` to consume\n`));
-  process.stdout.write(body);
-  if (!body.endsWith('\n')) process.stdout.write('\n');
+  if (!inputs.length && !all) {
+    die('Usage: dotmd prompts show <file-or-slug>...\n       dotmd prompts show --all [--limit N]   # peek the whole pending queue');
+  }
+  if (inputs.length && all) die('Pass either prompt names or --all, not both.');
+
+  let targets;
+  if (all) {
+    const queue = pendingPromptsOldestFirst(config);
+    if (!queue.length) die('No pending prompts.');
+    targets = queue.filter(entry => entry.abs).map(entry => entry.abs);
+  } else {
+    targets = inputs.map(input => resolvePromptInput(input, config));
+  }
+  const total = targets.length;
+  if (limit !== null) targets = targets.slice(0, limit);
+
+  // Single-target output is unchanged: bare body on stdout, one dim header on
+  // stderr. Only a multi-target sweep adds separators, so scripts piping one
+  // prompt keep working.
+  const multi = targets.length > 1;
+  let shown = 0;
+  for (const filePath of targets) {
+    const prompt = readPromptForShow(filePath, config, { strict: !all && !multi });
+    if (!prompt) continue;
+    const { repoPath, body, status } = prompt;
+    if (multi) {
+      if (shown > 0) process.stdout.write('\n');
+      process.stdout.write(dim(`──── ${repoPath} [${status}] ────\n`));
+    } else {
+      process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`dotmd use ${repoPath}\` to consume\n`));
+    }
+    process.stdout.write(body);
+    if (!body.endsWith('\n')) process.stdout.write('\n');
+    shown++;
+  }
+
+  // Footer whenever the sweep showed more than one OR hid some: a truncated
+  // --limit 1 collapses to single-prompt formatting, and silently dropping the
+  // rest would read as "that's the whole queue".
+  const truncated = total > targets.length;
+  if (multi || truncated) {
+    const suffix = truncated ? ` of ${total} (use --limit to change)` : '';
+    process.stderr.write(dim(`\n${shown} prompt${shown === 1 ? '' : 's'}${suffix} — read-only peek; \`dotmd use <file>\` to consume one\n`));
+  }
 }
 
 function runPromptsArchive(argv, config, opts = {}) {