dotmd-cli 0.42.0 → 0.43.0

package/bin/dotmd.mjs

@@ -636,16 +636,17 @@ Types and their default destinations:
 \`<name>\` is slugified for the filename.
 
 Body input (all built-in types — required for prompt, optional for plan/doc):
-  @path                  Read body from a file (preferred for multi-line bodies)
-  -                      Read body from stdin (heredoc-friendly for agents)
-  --message "<text>"     Explicit inline body
+  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 \`@path\` or \`-\` 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.).
-\`@/tmp/foo.md\` sidesteps both.
+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 | dotmd 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
@@ -656,12 +657,13 @@ the title + your body is emitted — no duplicated empty outline below
 Examples:
   dotmd new plan auth-revamp
   dotmd new prompt resume-foo @/tmp/draft.md
-  dotmd new prompt resume-foo - <<'EOF'
+  cat /tmp/draft.md | dotmd new prompt resume-foo
+  dotmd new prompt resume-foo <<'EOF'
   multi-line
   prompt body
   EOF
   dotmd new prompt cleanup-tomorrow "look at remaining lint warnings"
-  dotmd new plan full-spec - <<'EOF'
+  dotmd new plan full-spec <<'EOF'
   ## Problem
   …
   ## Phases
@@ -1126,6 +1128,8 @@ async function main() {
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
+    const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
+    scrubStaleSilently(config);
     const index = buildIndex(config);
     runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command });
     return;
@@ -1138,6 +1142,8 @@ async function main() {
   if (command === 'plans') {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
+    const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
+    scrubStaleSilently(config);
     const index = buildIndex(config);
     const sub = restArgs[0];
     let defaults;
@@ -1209,6 +1215,14 @@ async function main() {
   const { buildIndex } = await import('../src/index.mjs');
   const { renderCompactList, renderVerboseList, renderContext, renderBriefing, renderCheck, renderCoverage, buildCoverage } = await import('../src/render.mjs');
   const { runFocus, runQuery } = await import('../src/query.mjs');
+  // Opportunistic stale-lease scrub for user-facing "what's actionable now"
+  // views. Diagnostic commands (`check`, `coverage`, `stats`, `index`) are
+  // intentionally excluded — they should surface drift, not silently fix it.
+  const SCRUB_READ_COMMANDS = new Set(['list', 'briefing', 'context', 'focus', 'query', 'modules', 'module', 'surfaces']);
+  if (SCRUB_READ_COMMANDS.has(command)) {
+    const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
+    scrubStaleSilently(config);
+  }
   const index = buildIndex(config);
 
   // Apply --root and --type filters

package/package.json

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

package/src/hud.mjs

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
+import { readLeases, findStaleLeases, currentSessionId, STALE_LEASE_AGE_HOURS } from './lease.mjs';
+import { scrubStaleSilently } from './lease-scrub.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, red, dim } from './color.mjs';
@@ -67,6 +68,12 @@ function findActionablePrompts(config) {
 }
 
 export function buildHud(config) {
+  // Drop stale lease entries (and flip their plan frontmatter back to
+  // oldStatus) before reading anything. Without this, hud would surface
+  // zombie in-session plans from crashed sessions as "you hold N plans" if
+  // the SessionStart hook sees its own (now-stale) lease from a previous
+  // session that shared the same env-supplied session id.
+  try { scrubStaleSilently(config); } catch { /* hot-path: never break hud */ }
   const session = currentSessionId();
   const leases = readLeases(config);
   const owned = Object.values(leases).filter(l => l.session === session).map(l => l.path);
@@ -115,7 +122,7 @@ export function runHud(argv, config) {
     lines.push(green(`▶ ${hud.prompts.length} pending prompt${hud.prompts.length === 1 ? '' : 's'}: ${previewList(hud.prompts)}  ${dim('(consume: `dotmd prompts use <file>` — do not cat/read)')}`));
   }
   if (hud.stale.length > 0) {
-    lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
+    lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >${STALE_LEASE_AGE_HOURS}h  ${dim('(run: dotmd release --stale)')}`));
   }
   if (hud.errors > 0) {
     lines.push(red(`✗ ${hud.errors} validation error${hud.errors === 1 ? '' : 's'}  ${dim('(run: dotmd check)')}`));
@@ -135,7 +142,7 @@ export function runHud(argv, config) {
   // by `dotmd init`) so subsequent sessions stay silent.
   const primerMarker = path.join(config.repoRoot, '.dotmd', 'primer-shown');
   if (!existsSync(primerMarker)) {
-    lines.push(dim('dotmd: managing this repo\'s docs. Use `dotmd new prompt` for handoffs (never hand-write docs/prompts/*.md). `dotmd plans` shows the queue. `dotmd --help` for more.'));
+    lines.push(dim('dotmd: managing this repo\'s docs. Save in one shot: `cat draft.md | dotmd new <type> <slug>` (or `dotmd new <type> <slug> @path`). Types: plan, doc, prompt. `dotmd plans` shows the queue.'));
     try {
       mkdirSync(path.dirname(primerMarker), { recursive: true });
       writeFileSync(primerMarker, '');

package/src/lease-scrub.mjs

@@ -0,0 +1,49 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { releaseStale } from './lease.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, nowIso } from './util.mjs';
+
+// Inline status flip, kept local so this module doesn't have to pull in
+// lifecycle.mjs (and the rest of its dep graph) on the SessionStart-hook hot
+// path. Matches the shape of lifecycle.updateFrontmatter for these two keys.
+function flipStatus(filePath, newStatus) {
+  const raw = readFileSync(filePath, 'utf8');
+  if (!raw.startsWith('---\n')) return;
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) return;
+  let fm = raw.slice(4, endMarker);
+  const body = raw.slice(endMarker + 5);
+  const today = nowIso();
+  const statusRe = /^status:.*$/m;
+  const updatedRe = /^updated:.*$/m;
+  fm = statusRe.test(fm) ? fm.replace(statusRe, `status: ${newStatus}`) : `${fm}\nstatus: ${newStatus}`;
+  fm = updatedRe.test(fm) ? fm.replace(updatedRe, `updated: ${today}`) : `${fm}\nupdated: ${today}`;
+  writeFileSync(filePath, `---\n${fm}\n---\n${body}`, 'utf8');
+}
+
+// Opportunistic stale-lease scrub for read-side commands. Drops any lease
+// entries past STALE_LEASE_AGE_MS and best-effort flips the plan's frontmatter
+// from in-session back to the lease's oldStatus. Silent: no stderr, no warn,
+// no index regen. Returns array of scrubbed lease paths (empty in the common
+// no-op case, which is the only thing that matters for cost).
+export function scrubStaleSilently(config) {
+  const result = releaseStale(config);
+  if (result.released.length === 0) return [];
+  for (const lease of result.released) {
+    const newStatus = lease.oldStatus || 'active';
+    const filePath = path.join(config.repoRoot, lease.path);
+    try {
+      const raw = readFileSync(filePath, 'utf8');
+      const { frontmatter: fmRaw } = extractFrontmatter(raw);
+      const parsedFm = parseSimpleFrontmatter(fmRaw);
+      if (asString(parsedFm.status) === 'in-session') {
+        flipStatus(filePath, newStatus);
+      }
+    } catch {
+      // Best-effort: the lease entry is already gone; a missing or unreadable
+      // file is fine for an opportunistic backstop.
+    }
+  }
+  return result.released.map(l => l.path);
+}

package/src/lease.mjs

@@ -9,7 +9,8 @@ const LOCK_FILE = 'in-session.lock';
 const LOCK_STALE_MS = 5_000;
 const LOCK_RETRY_MS = 50;
 const LOCK_MAX_WAIT_MS = 2_000;
-const STALE_LEASE_AGE_MS = 24 * 60 * 60 * 1000;
+export const STALE_LEASE_AGE_MS = 4 * 60 * 60 * 1000;
+export const STALE_LEASE_AGE_HOURS = STALE_LEASE_AGE_MS / (60 * 60 * 1000);
 
 const _sleepBuf = new Int32Array(new SharedArrayBuffer(4));
 function syncSleep(ms) { Atomics.wait(_sleepBuf, 0, 0, ms); }

package/src/lifecycle.mjs

@@ -15,6 +15,8 @@ import {
   readLeases,
   currentSessionId,
   migrateLease,
+  STALE_LEASE_AGE_MS,
+  STALE_LEASE_AGE_HOURS,
 } from './lease.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
 import { walkSections, findSection } from './section.mjs';
@@ -245,6 +247,17 @@ export async function runPickup(argv, config, opts = {}) {
   const showFiles = argv.includes('--show-files') || opts.showFiles;
   let input = argv.find(a => !a.startsWith('-'));
 
+  // Opportunistic stale-lease scrub before pickup runs its conflict check.
+  // Without this, a stale lease from a crashed prior session would still
+  // produce 'conflict-stale' and force the agent to pass --takeover even
+  // though we already know the holder is gone.
+  if (!dryRun) {
+    try {
+      const { scrubStaleSilently } = await import('./lease-scrub.mjs');
+      scrubStaleSilently(config);
+    } catch { /* best-effort — never block pickup on scrub failure */ }
+  }
+
   // Interactive: pick from active/planned plans
   if (!input) {
     if (!isInteractive()) die('Usage: dotmd pickup <file>');
@@ -317,7 +330,7 @@ export async function runPickup(argv, config, opts = {}) {
     }
     if (result.outcome === 'conflict-stale') {
       const c = result.conflict;
-      die(`Stale in-session lease from ${c.host}/${c.session} since ${c.pickedUpAt} (>24h old).\nUse --takeover to claim.\n  ${repoPath}`);
+      die(`Stale in-session lease from ${c.host}/${c.session} since ${c.pickedUpAt} (>${STALE_LEASE_AGE_HOURS}h old).\nUse --takeover to claim.\n  ${repoPath}`);
     }
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
@@ -459,7 +472,7 @@ export async function runUnpickup(argv, config, opts = {}) {
     if (dryRun) {
       const staleLeases = Object.values(leases).filter(l => {
         const age = Date.now() - new Date(l.pickedUpAt).getTime();
-        return Number.isNaN(age) || age > 24 * 60 * 60 * 1000;
+        return Number.isNaN(age) || age > STALE_LEASE_AGE_MS;
       });
       for (const l of staleLeases) {
         process.stderr.write(`${dim('[dry-run]')} Would release stale: ${l.path} (${l.session})\n`);
@@ -473,9 +486,10 @@ export async function runUnpickup(argv, config, opts = {}) {
       }
     }
   } else {
-    if (targets.length === 0 && !json) {
-      process.stderr.write(`No leases to release${fileArg ? ` for ${fileArg}` : ` for session ${session}`}.\n`);
-    }
+    // Silent no-op: when the session has nothing to release (already
+    // auto-released by archive, or never held), exit 0 with no output.
+    // Only print when work was actually done. The fileArg path can't reach
+    // here with targets.length === 0 — it would have died at lookup.
     for (const lease of targets) {
       const newStatus = targetStatus(lease);
       if (dryRun) {

package/src/new.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
@@ -26,7 +26,7 @@ const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
     defaultStatus: 'active',
-    // Body input optional. When passed (inline / --message / @file / stdin),
+    // Body input optional. When passed (inline / --body / @file / stdin),
     // it lands in the Overview section. Without it, Overview is left blank
     // and the user fills it in.
     acceptsBody: true,
@@ -263,12 +263,18 @@ export async function runNew(argv, config, opts = {}) {
   let status = null;
   let title = null;
   let rootName = opts.root ?? null;
-  let messageFlag = null;
+  let bodyFlag = null;
+  let bodyFlagName = null; // tracks which spelling the caller used, for error attribution
   let showFiles = opts.showFiles ?? false;
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
-    if (argv[i] === '--message' && argv[i + 1]) { messageFlag = argv[++i]; continue; }
+    // --body is the canonical flag; --message is a back-compat alias.
+    if ((argv[i] === '--body' || argv[i] === '--message') && argv[i + 1]) {
+      bodyFlagName = argv[i];
+      bodyFlag = argv[++i];
+      continue;
+    }
     if (argv[i] === '--root' && argv[i + 1]) { rootName = argv[++i]; continue; }
     if (argv[i] === '--config') { i++; continue; }
     if (argv[i] === '--show-files') { showFiles = true; continue; }
@@ -304,7 +310,7 @@ export async function runNew(argv, config, opts = {}) {
       name = await promptText(`${typeName} name: `);
       if (!name) die('No name provided.');
     } else {
-      die(`Usage: dotmd new <type> <name> [body]\n       types: ${[...knownTypes].join(', ')}\n       body: inline text | "-" (stdin) | "@path" (file) | --message "..."`);
+      die(`Usage: dotmd new <type> <name> [body]\n       types: ${[...knownTypes].join(', ')}\n       body: inline text | piped stdin (auto) | "@path" (file) | --body "..."`);
     }
   }
 
@@ -331,13 +337,31 @@ export async function runNew(argv, config, opts = {}) {
     die(`Invalid status \`${status}\` for type \`${typeName}\`\nValid: ${[...effective].join(', ')}`);
   }
 
-  // Body input resolution: messageFlag > bodyArg > nothing
+  // Body input resolution: --body flag > positional bodyArg > auto-piped-stdin > nothing
   let bodyInput = null;
   let bodyInputSource = null;
-  if (messageFlag !== null) { bodyInput = readBodyInput(messageFlag); bodyInputSource = '--message'; }
+  if (bodyFlag !== null) { bodyInput = readBodyInput(bodyFlag); bodyInputSource = bodyFlagName; }
   else if (bodyArg !== null) {
     bodyInput = readBodyInput(bodyArg);
     bodyInputSource = bodyArg === '-' ? 'stdin (`-`)' : (bodyArg.startsWith('@') ? `file (\`${bodyArg}\`)` : 'inline body argument');
+  } else if (template.acceptsBody || template.requiresBody) {
+    // Auto-consume piped or redirected stdin so agents don't need the `-`
+    // placeholder for the most common pattern (`cat draft.md | dotmd new …`,
+    // `dotmd new … < draft.md`, or a `<<'EOF'` heredoc). We probe stdin via
+    // fstatSync rather than `!isTTY` so a closed/inherited fd doesn't trigger
+    // a blocking read of an empty stream. We accept FIFO (shell pipes), regular
+    // file (shell redirection / heredoc), and socket (Node spawnSync `input:`
+    // delivers stdin as an AF_UNIX socket).
+    try {
+      const stat = fstatSync(0);
+      if (stat.isFIFO() || stat.isFile() || stat.isSocket()) {
+        const piped = readFileSync(0, 'utf8');
+        if (piped.length > 0) {
+          bodyInput = piped;
+          bodyInputSource = 'piped stdin';
+        }
+      }
+    } catch { /* stdin not introspectable — skip auto-consume */ }
   }
 
   // If the body input has a leading `---…---` frontmatter block, lift its keys
@@ -355,7 +379,7 @@ export async function runNew(argv, config, opts = {}) {
   }
 
   if (template.requiresBody && (!bodyInput || !bodyInput.trim())) {
-    die(`\`${typeName}\` template requires a body. Pass inline, --message "...", - for stdin, or @path for a file.`);
+    die(`\`${typeName}\` template requires a body. Pipe stdin (\`cat draft.md | dotmd new ${typeName} <slug>\`), pass @path, --body "...", or inline text.`);
   }
 
   // Fail-fast when the user passes body input to a template that doesn't

package/src/prompts.mjs

@@ -248,7 +248,7 @@ function runPromptsArchive(argv, config, opts = {}) {
 
 async function runPromptsNew(argv, config, opts = {}) {
   if (!argv[0] || argv[0].startsWith('-')) {
-    die('Usage: dotmd prompts new <slug> [body]\n       body: inline text | "-" (stdin) | "@path" (file) | --message "..."');
+    die('Usage: dotmd prompts new <slug> [body]\n       body: inline text | piped stdin (auto) | "@path" (file) | --body "..."');
   }
   return runNew(['prompt', ...argv], config, opts);
 }

package/src/ship.mjs

@@ -48,10 +48,17 @@ function listDirtyFiles(repoRoot) {
   return result.stdout
     .split('\n')
     .filter(Boolean)
-    .map(line => ({
-      status: line.slice(0, 2),
-      path: line.slice(3),
-    }));
+    .map(line => {
+      const status = line.slice(0, 2);
+      let rawPath = line.slice(3);
+      // Renames/copies render as `R  orig -> new` (and `C  orig -> new`); only
+      // the destination is a real file we can `git add`. Without splitting on
+      // ` -> `, the literal "orig -> new" string is handed to git, which fails
+      // with "did not match any files" and aborts the ship.
+      const arrow = rawPath.indexOf(' -> ');
+      if (arrow !== -1) rawPath = rawPath.slice(arrow + 4);
+      return { status, path: rawPath };
+    });
 }
 
 function findHeldPlanTitle(config) {

package/src/validate.mjs

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
-import { readLeases, isLeaseStale } from './lease.mjs';
+import { readLeases, isLeaseStale, STALE_LEASE_AGE_HOURS } from './lease.mjs';
 
 const NOW = new Date();
 
@@ -175,9 +175,10 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
 
   // F11: `status: in-session` plans should have a matching live lease. If the
   // lease file has no entry, the previous session crashed without releasing;
-  // if the entry is stale (>24h), the holder is gone. Either way the validator
-  // is the only place that knows enough to suggest the exact unstuck command,
-  // because the lease infrastructure is otherwise invisible to `dotmd check`.
+  // if the entry is stale (> stale-threshold hours), the holder is gone.
+  // Either way the validator is the only place that knows enough to suggest
+  // the exact unstuck command, because the lease infrastructure is otherwise
+  // invisible to `dotmd check`.
   if (doc.status === 'in-session' && !config.lifecycle.skipWarningsFor.has(doc.status)) {
     const leases = readLeases(config);
     const lease = leases[doc.path];
@@ -192,7 +193,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
       doc.warnings.push({
         path: doc.path,
         level: 'warning',
-        message: `\`status: in-session\` but lease is stale (last touched ${ageHours}h ago, >24h threshold). Run \`dotmd release ${doc.path}\` to clear, or \`dotmd status ${doc.path} active\` to re-queue.`,
+        message: `\`status: in-session\` but lease is stale (last touched ${ageHours}h ago, >${STALE_LEASE_AGE_HOURS}h threshold). Run \`dotmd release ${doc.path}\` to clear, or \`dotmd status ${doc.path} active\` to re-queue.`,
       });
     }
   }