dotmd-cli 0.50.2 → 0.52.0

package/src/lifecycle.mjs

@@ -5,19 +5,8 @@ import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escape
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
-import { green, dim, yellow } from './color.mjs';
+import { green, dim } from './color.mjs';
 import { isInteractive, promptChoice } from './prompt.mjs';
-import {
-  acquireLease,
-  releaseLease,
-  releaseAllForSession,
-  releaseStale,
-  readLeases,
-  currentSessionId,
-  migrateLease,
-  isLeaseReclaimable,
-  STALE_LEASE_AGE_HOURS,
-} from './lease.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
 import { walkSections, findSection } from './section.mjs';
 
@@ -297,29 +286,20 @@ export async function runStatus(argv, config, opts = {}) {
   }); } catch (err) { warn(`Hook 'onStatusChange' threw: ${err.message}`); }
 }
 
-export async function runPickup(argv, config, opts = {}) {
+// Open a plan for work: flip its frontmatter status to `in-session` and print
+// its card (body + related + next steps). No lease, no claiming — just a
+// status write. Backs `dotmd use <plan>` and `dotmd runlist next`.
+export async function startPlan(argv, config, opts = {}) {
   const { dryRun } = opts;
   const json = argv.includes('--json');
-  const takeover = argv.includes('--takeover');
   const fullBody = argv.includes('--full');
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   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 && !takeover) {
-    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>');
+    if (!isInteractive()) die('Usage: dotmd use <plan>');
     const index = buildIndex(config);
     const candidates = index.docs.filter(d =>
       d.type === 'plan' && (d.status === 'active' || d.status === 'planned')
@@ -351,63 +331,20 @@ export async function runPickup(argv, config, opts = {}) {
     die(`Plan is blocked: ${blockers}\n  ${repoPath}`);
   }
 
-  // If frontmatter says we're not in-session, any lingering lease is orphaned —
-  // drop it so a fresh acquire below doesn't see a phantom conflict.
-  if (oldStatus !== 'in-session') {
-    if (readLeases(config)[repoPath]) {
-      releaseLease(config, repoPath, { force: true });
-    }
-  }
-
-  const pickupable = new Set(['active', 'planned', 'in-session']);
-  if (oldStatus && !pickupable.has(oldStatus)) {
-    die(
-      `Cannot start work on a plan with status '${oldStatus}'. Must be active or planned.\n` +
-      `  ${repoPath}\n` +
-      `\n` +
-      `Recover with:\n` +
-      `  dotmd set active ${repoPath} && dotmd set in-session ${repoPath}`,
-    );
-  }
-
   const today = nowIso();
-  const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
-  let leaseOutcome = 'acquired';
-
   if (dryRun) {
     if (oldStatus === 'in-session') {
-      process.stderr.write(`${dim('[dry-run]')} Would acquire lease (status already in-session)\n`);
+      process.stderr.write(`${dim('[dry-run]')} Already in-session: ${repoPath}\n`);
     } else {
       process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
     }
-  } else {
-    const result = acquireLease(config, repoPath, leaseOldStatus, { takeover });
-    leaseOutcome = result.outcome;
-    if (result.outcome === 'conflict-alive') {
-      const c = result.conflict;
-      die(`Plan is in-session with ${c.host}/${c.session} (pid ${c.pid}) since ${c.pickedUpAt}.\nUse --takeover to override.\n  ${repoPath}`);
-    }
-    if (result.outcome === 'conflict-stale') {
-      const c = result.conflict;
-      die(`Plan flagged in-session by ${c.host}/${c.session} since ${c.pickedUpAt} (>${STALE_LEASE_AGE_HOURS}h ago, looks abandoned).\nUse --takeover to claim.\n  ${repoPath}`);
-    }
-    if (oldStatus !== 'in-session') {
-      updateFrontmatter(filePath, { status: 'in-session', updated: today });
-      if (noIndex) {
-        process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
-      } else {
-        regenIndex(config);
-      }
-    }
-    // VH append per lease outcome:
-    //   acquired   → `Picked up (<old> → in-session).`
-    //   taken-over → `Took over from <session>.`
-    //   reattached → no entry (same-session noise)
-    if (leaseOutcome === 'acquired') {
-      appendVersionHistory(filePath, `Picked up (${oldStatus ?? 'unknown'} → in-session).`);
-    } else if (leaseOutcome === 'taken-over') {
-      const fromSession = result.conflict?.session ?? 'unknown';
-      appendVersionHistory(filePath, `Took over from ${fromSession}.`);
+  } else if (oldStatus !== 'in-session') {
+    updateFrontmatter(filePath, { status: 'in-session', updated: today });
+    appendVersionHistory(filePath, `Started (${oldStatus ?? 'unknown'} → in-session).`);
+    if (noIndex) {
+      process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+    } else {
+      regenIndex(config);
     }
   }
 
@@ -415,19 +352,11 @@ export async function runPickup(argv, config, opts = {}) {
     const card = buildCard(filePath, raw, config);
     process.stdout.write(JSON.stringify({
       path: repoPath, oldStatus, newStatus: 'in-session', title,
-      reattached: leaseOutcome === 'reattached',
-      takenOver: leaseOutcome === 'taken-over',
       body: body?.trim() ?? '',
       card,
     }, null, 2) + '\n');
   } else {
-    if (leaseOutcome === 'reattached') {
-      process.stderr.write(`${green('▶ Re-attached')}: ${repoPath}\n\n`);
-    } else if (leaseOutcome === 'taken-over') {
-      process.stderr.write(`${green('▶ Took over')}: ${repoPath} (was ${oldStatus ?? 'unset'} → in-session)\n\n`);
-    } else {
-      process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
-    }
+    process.stderr.write(`${green('▶ Started')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
     if (fullBody) {
       const header = `[dotmd] in-session: ${repoPath} — close with: dotmd set <status> ${repoPath}\n---\n`;
       process.stdout.write(header);
@@ -448,151 +377,6 @@ export async function runPickup(argv, config, opts = {}) {
   try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
 }
 
-export async function runUnpickup(argv, config, opts = {}) {
-  const { dryRun } = opts;
-  const json = argv.includes('--json');
-  const all = argv.includes('--all');
-  const stale = argv.includes('--stale');
-  const force = argv.includes('--force');
-  const noIndex = argv.includes('--no-index') || opts.noIndex;
-  const showFiles = argv.includes('--show-files') || opts.showFiles;
-  const toIdx = argv.indexOf('--to');
-  const toStatus = toIdx >= 0 ? argv[toIdx + 1] : null;
-  const positional = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--to');
-  const fileArg = positional[0];
-  const touched = [];
-
-  const session = currentSessionId();
-  const released = [];
-  const skipped = [];
-
-  // Decide which leases to act on
-  let targets = [];
-  const leases = readLeases(config);
-  if (fileArg) {
-    const filePath = resolveDocPath(fileArg, config);
-    if (!filePath) die(`File not found: ${fileArg}`);
-    const repoPath = toRepoPath(filePath, config.repoRoot);
-    if (leases[repoPath]) {
-      targets.push(leases[repoPath]);
-    } else {
-      // Manual-edit fallback: status may be in-session with no lease.
-      const raw = readFileSync(filePath, 'utf8');
-      const { frontmatter: fmRaw } = extractFrontmatter(raw);
-      const parsedFm = parseSimpleFrontmatter(fmRaw);
-      if (asString(parsedFm.status) === 'in-session') {
-        targets.push({ path: repoPath, oldStatus: null, session: null, pid: null, host: null, pickedUpAt: null, _orphan: true });
-      } else {
-        die(`Not in-session: ${repoPath}`);
-      }
-    }
-  } else if (all) {
-    targets = Object.values(leases);
-  } else if (stale) {
-    // releaseStale handled separately below — set a marker
-    targets = null;
-  } else {
-    // Default: release all owned by current session
-    targets = Object.values(leases).filter(l => l.session === session);
-  }
-
-  const targetStatus = (lease) => toStatus || lease.oldStatus || 'active';
-
-  function flipFrontmatter(repoPath, newStatus) {
-    const filePath = resolveDocPath(repoPath, config);
-    if (!filePath) {
-      warn(`Lease points at ${repoPath} but file not found — releasing lease without frontmatter update.`);
-      return;
-    }
-    try {
-      const raw = readFileSync(filePath, 'utf8');
-      const { frontmatter: fmRaw } = extractFrontmatter(raw);
-      const parsedFm = parseSimpleFrontmatter(fmRaw);
-      const cur = asString(parsedFm.status);
-      if (cur === 'in-session') {
-        const today = nowIso();
-        updateFrontmatter(filePath, { status: newStatus, updated: today });
-        appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
-        touched.push(filePath);
-        if (noIndex) {
-          process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
-        } else {
-          regenIndex(config);
-        }
-      }
-      // If frontmatter is no longer in-session (manual flip), leave it alone.
-    } catch (err) {
-      warn(`Could not update frontmatter for ${repoPath}: ${err.message}`);
-    }
-  }
-
-  if (targets === null) {
-    // --stale path
-    if (dryRun) {
-      const staleLeases = Object.values(leases).filter(l => isLeaseReclaimable(l, { currentSession: session }));
-      for (const l of staleLeases) {
-        process.stderr.write(`${dim('[dry-run]')} Would release stale: ${l.path} (${l.session})\n`);
-      }
-    } else {
-      const result = releaseStale(config);
-      for (const l of result.released) {
-        flipFrontmatter(l.path, targetStatus(l));
-        released.push({ path: l.path, oldStatus: l.oldStatus, newStatus: targetStatus(l), session: l.session, stale: true });
-        try { config.hooks.onUnpickup?.({ path: l.path, oldStatus: 'in-session', newStatus: targetStatus(l) }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
-      }
-    }
-  } else {
-    // 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) {
-        process.stderr.write(`${dim('[dry-run]')} Would release: ${lease.path} (${lease.oldStatus ?? '?'} → ${newStatus})\n`);
-        continue;
-      }
-      if (lease._orphan) {
-        // Manual-edit fallback: no lease entry, just flip frontmatter.
-        flipFrontmatter(lease.path, newStatus);
-        warn(`No lease found for ${lease.path}; flipped status manually.`);
-        released.push({ path: lease.path, oldStatus: 'in-session', newStatus, session: null, orphan: true });
-        try { config.hooks.onUnpickup?.({ path: lease.path, oldStatus: 'in-session', newStatus }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
-        continue;
-      }
-      const isMine = lease.session === session;
-      if (!isMine && !force && !all && !stale) {
-        skipped.push({ path: lease.path, reason: 'not-yours', session: lease.session });
-        continue;
-      }
-      const r = releaseLease(config, lease.path, { force: true });
-      if (r.released) {
-        flipFrontmatter(lease.path, newStatus);
-        released.push({ path: lease.path, oldStatus: lease.oldStatus, newStatus, session: lease.session });
-        try { config.hooks.onUnpickup?.({ path: lease.path, oldStatus: 'in-session', newStatus }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
-      }
-    }
-  }
-
-  if (json) {
-    process.stdout.write(JSON.stringify({ released, skipped }, null, 2) + '\n');
-  } else {
-    for (const r of released) {
-      const tag = r.stale ? ' (stale)' : (r.orphan ? ' (orphan)' : '');
-      process.stdout.write(`${green('↩ Unpicked')}: ${r.path} (in-session → ${r.newStatus})${tag}\n`);
-    }
-    for (const s of skipped) {
-      process.stderr.write(`${yellow('⚠ Skipped')}: ${s.path} (held by ${s.session}; use --force to override)\n`);
-    }
-  }
-
-  if (showFiles && touched.length > 0) {
-    const all = [...touched];
-    if (config.indexPath && !noIndex) all.push(config.indexPath);
-    emitFilesFooter(all, config);
-  }
-}
-
 export function runArchive(argv, config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
   const noIndex = argv.includes('--no-index') || opts.noIndex;
@@ -675,11 +459,6 @@ export function runArchive(argv, config, opts = {}) {
       out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
 
-    // Preview lease release (only if a lease exists for this plan)
-    if (readLeases(config)[oldRepoPath]) {
-      out.write(`${prefix} Would release in-session lease: ${oldRepoPath}\n`);
-    }
-
     // Preview onArchive hook fire
     if (config.hooks?.onArchive) {
       out.write(`${prefix} Would fire hook: onArchive\n`);
@@ -718,8 +497,6 @@ export function runArchive(argv, config, opts = {}) {
   if (config.indexPath && !noIndex) out.write('Index regenerated.\n');
   if (config.indexPath && noIndex) out.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
 
-  try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }
-
   const touched = [oldRepoPath, newRepoPath, ...refTouchedPaths];
   if (config.indexPath && !noIndex) touched.push(config.indexPath);
   if (showFiles) emitFilesFooter(touched, config);
@@ -757,42 +534,14 @@ export async function runSet(argv, config, opts = {}) {
   argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
 
   const newStatus = argv[0];
-  let input = argv[1];
-
-  if (!newStatus) die('Usage: dotmd set <status> [<path>]');
-
-  // `set in-session` acquires a lease + prints the plan body (same as the
-  // legacy `pickup` verb). Delegated so `set` is the single status verb.
-  if (newStatus === 'in-session') {
-    const pickArgs = input ? [input] : [];
-    if (argv.includes('--takeover')) pickArgs.push('--takeover');
-    if (noIndex) pickArgs.push('--no-index');
-    if (showFiles) pickArgs.push('--show-files');
-    return runPickup(pickArgs, config, { dryRun });
-  }
+  const input = argv[1];
 
-  if (!input) {
-    const leases = readLeases(config);
-    const sid = currentSessionId();
-    const owned = Object.entries(leases).filter(([_, l]) => l.session === sid);
-    if (owned.length === 0) {
-      die('No <path> given and no held lease to infer from.\nUsage: dotmd set <status> <path>');
-    }
-    if (owned.length > 1) {
-      const paths = owned.map(([p]) => `  - ${p}`).join('\n');
-      die(`No <path> given; you hold ${owned.length} leases:\n${paths}\nSpecify <path> explicitly.`);
-    }
-    input = owned[0][0];
-  }
+  if (!newStatus) die('Usage: dotmd set <status> <path>');
+  if (!input) die('Usage: dotmd set <status> <path>');
 
   const filePath = resolveDocPath(input, config);
   if (!filePath) die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
 
-  const raw = readFileSync(filePath, 'utf8');
-  const { frontmatter: fmRaw } = extractFrontmatter(raw);
-  const parsedFm = parseSimpleFrontmatter(fmRaw);
-  const oldStatus = asString(parsedFm.status);
-
   const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
 
   if (config.lifecycle.archiveStatuses.has(newStatus) && !inArchive) {
@@ -806,12 +555,6 @@ export async function runSet(argv, config, opts = {}) {
   if (noIndex) statusArgs.push('--no-index');
   if (showFiles) statusArgs.push('--show-files');
   await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true });
-
-  if (oldStatus === 'in-session' && newStatus !== 'in-session' && !dryRun) {
-    const repoPath = toRepoPath(filePath, config.repoRoot);
-    try { releaseLease(config, repoPath, { force: false }); }
-    catch (err) { warn(`Could not release lease for ${repoPath}: ${err.message}`); }
-  }
 }
 
 export function runBulkArchive(argv, config, opts = {}) {

package/src/misuse-read.mjs

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs';
+import { readMisuseEntries, globalMisuseLogPath } from './journal.mjs';
+import { dim, red, yellow } from './color.mjs';
+
+// `dotmd misuse` — read the cross-repo guard log. Every wrong-move the
+// PreToolUse guard intercepts lands here; this is the operator's window into
+// "what are sessions getting wrong, and how often."
+function parseArgs(argv) {
+  const opts = { tail: null, byRule: false, asJson: false, repo: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tail') { const n = parseInt(argv[++i], 10); opts.tail = Number.isFinite(n) && n > 0 ? n : 20; }
+    else if (a === '--by-rule') opts.byRule = true;
+    else if (a === '--json') opts.asJson = true;
+    else if (a === '--repo' && argv[i + 1]) opts.repo = argv[++i];
+  }
+  if (opts.tail === null && !opts.byRule) opts.tail = 20;
+  return opts;
+}
+
+export function runMisuse(argv, _config) {
+  const file = globalMisuseLogPath();
+  if (!existsSync(file)) {
+    process.stderr.write(
+      'No misuse log yet. The PreToolUse guard (`dotmd guard`) writes here when it intercepts a wrong move.\n' +
+      'Wire it up: add a PreToolUse hook that runs `dotmd guard` (see `dotmd help guard`).\n',
+    );
+    return;
+  }
+
+  const opts = parseArgs(argv);
+  let entries = readMisuseEntries();
+  if (opts.repo) entries = entries.filter(e => (e.repo || '').includes(opts.repo));
+
+  if (opts.byRule) {
+    const groups = new Map();
+    for (const e of entries) {
+      const key = e.rule || '(unknown)';
+      if (!groups.has(key)) groups.set(key, { rule: key, count: 0, deny: 0, warn: 0 });
+      const g = groups.get(key);
+      g.count++;
+      if (e.decision === 'deny') g.deny++; else if (e.decision === 'warn') g.warn++;
+    }
+    const rows = [...groups.values()].sort((a, b) => b.count - a.count);
+    if (opts.asJson) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return; }
+    if (!rows.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+    for (const r of rows) {
+      process.stdout.write(`${r.rule.padEnd(16)} ${String(r.count).padStart(4)}×  ${red(`${r.deny} deny`)} / ${yellow(`${r.warn} warn`)}\n`);
+    }
+    return;
+  }
+
+  if (opts.tail) entries = entries.slice(-opts.tail);
+  if (opts.asJson) { process.stdout.write(JSON.stringify(entries, null, 2) + '\n'); return; }
+  if (!entries.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+
+  for (const e of entries) {
+    const tag = e.decision === 'deny' ? red('DENY') : yellow('warn');
+    const repo = e.repo ? dim(` ${e.repo.split('/').pop()}`) : '';
+    process.stdout.write(`[${e.ts}] ${tag} ${e.rule || '?'}${repo} ${dim(e.detail || '')}\n`);
+  }
+}

package/src/new.mjs

@@ -539,6 +539,22 @@ export async function runNew(argv, config, opts = {}) {
   process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
   if (rootHint) process.stdout.write(dim(rootHint));
 
+  // Post-create guidance. Prompts are the classic confusion point: agents
+  // reflexively `git add && commit` a freshly-created file, but saved prompts
+  // are session-local handoff artifacts — the next session consumes them via
+  // `dotmd use`, and the prompts dir is often gitignored (the commit then fails
+  // confusingly). Tell the agent the next step explicitly, and flag a gitignored
+  // target for any type so "why won't this commit" never happens silently.
+  if (typeName === 'prompt') {
+    process.stdout.write(dim('Session-local — no need to commit. The next session runs `dotmd use` (or `dotmd use ' + repoPath + '`) to consume it.\n'));
+  }
+  try {
+    const { isGitIgnored } = await import('./git.mjs');
+    if (isGitIgnored(filePath, config.repoRoot)) {
+      process.stdout.write(dim(`Note: ${repoPath} is gitignored — don't try to git add/commit it.\n`));
+    }
+  } catch { /* git absent / not a repo — skip the note */ }
+
   regenIndex(config);
 
   if (showFiles) {

package/src/rename.mjs

@@ -1,7 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { toRepoPath, resolveDocPath, die, warn } from './util.mjs';
-import { migrateLease } from './lease.mjs';
 import { collectDocFiles } from './index.mjs';
 import { regenIndex } from './lifecycle.mjs';
 import { gitMv } from './git.mjs';
@@ -100,8 +99,6 @@ export async function runRename(argv, config, opts = {}) {
     }
   }
 
-  try { migrateLease(config, oldRepoPath, newRepoPath); } catch (err) { warn(`Could not migrate lease ${oldRepoPath} → ${newRepoPath}: ${err.message}`); }
-
   regenIndex(config);
 
   process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);

package/src/render.mjs

@@ -4,7 +4,6 @@ import { capitalize, toSlug, truncate, warn } from './util.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
-import { findStaleLeases } from './lease.mjs';
 import { categorizeWarnings } from './check-collapse.mjs';
 
 // Render `currentState` with an `(auto)` prefix when the value was body-scraped
@@ -357,13 +356,6 @@ export function renderBriefing(index, config) {
     : `Errors: ${errorCount}`;
   lines.push(`Stale: ${stale} | ${errorPart} | Warnings: ${index.warnings.length}`);
 
-  try {
-    const staleLeases = findStaleLeases(config);
-    if (staleLeases.length > 0) {
-      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>4h or dead same-host pid, run \`dotmd release --stale\`)`));
-    }
-  } catch {}
-
   return lines.join('\n') + '\n';
 }
 

package/src/runlist.mjs

@@ -217,20 +217,19 @@ export async function runRunlist(argv, config, opts = {}) {
     die(
       `Next child in runlist ${hubRepoPath} is ${target.path} (status: ${target.status}).\n` +
       `Resolve the blocker before continuing the runlist.\n` +
-      `  dotmd status ${target.path} active   # if ready to resume\n` +
-      `  dotmd pickup ${target.path}          # to inspect`,
+      `  dotmd set active ${target.path}   # if ready to resume\n` +
+      `  dotmd use ${target.path}          # to inspect`,
     );
   }
 
-  // Delegate to runPickup — same lease semantics, same VH append, same card
-  // render. Dynamic import to avoid circular module-load cost when the
-  // runlist command isn't used.
-  const { runPickup } = await import('./lifecycle.mjs');
-  const pickupArgs = [target.path];
-  if (argv.includes('--takeover')) pickupArgs.push('--takeover');
-  if (argv.includes('--full')) pickupArgs.push('--full');
-  if (argv.includes('--no-index')) pickupArgs.push('--no-index');
-  if (argv.includes('--show-files')) pickupArgs.push('--show-files');
-  if (json) pickupArgs.push('--json');
-  await runPickup(pickupArgs, config, opts);
+  // Open the next child: set it in-session (frontmatter) and render its card.
+  // Dynamic import to avoid circular module-load cost when the runlist command
+  // isn't used.
+  const { startPlan } = await import('./lifecycle.mjs');
+  const startArgs = [target.path];
+  if (argv.includes('--full')) startArgs.push('--full');
+  if (argv.includes('--no-index')) startArgs.push('--no-index');
+  if (argv.includes('--show-files')) startArgs.push('--show-files');
+  if (json) startArgs.push('--json');
+  await startPlan(startArgs, config, opts);
 }

package/src/ship.mjs

@@ -4,7 +4,6 @@ import path from 'node:path';
 import { die, warn, toRepoPath } from './util.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
-import { readLeases, currentSessionId } from './lease.mjs';
 
 // Files dotmd ship will auto-stage when they're dirty. Anything outside this
 // allowlist stays in the working tree — user has to `git add` it explicitly,
@@ -62,14 +61,6 @@ function listDirtyFiles(repoRoot) {
     });
 }
 
-function findHeldPlanTitle(config) {
-  const leases = readLeases(config);
-  const sid = currentSessionId();
-  const owned = Object.entries(leases).filter(([_, l]) => l.session === sid);
-  if (owned.length !== 1) return null;
-  return path.basename(owned[0][0], '.md');
-}
-
 export async function runShip(argv, config, opts = {}) {
   const { dryRun } = opts;
   const positional = argv.filter(a => !a.startsWith('-'));
@@ -127,10 +118,7 @@ export async function runShip(argv, config, opts = {}) {
     const add = spawnSync('git', ['add', '--', ...allToStage], { cwd: config.repoRoot, encoding: 'utf8' });
     if (add.status !== 0) die(`git add failed: ${add.stderr}`);
 
-    const planTitle = findHeldPlanTitle(config);
-    const subject = planTitle
-      ? `chore: release ${target} (${planTitle})`
-      : `chore: release ${target}`;
+    const subject = `chore: release ${target}`;
     const body = `Auto-staged by \`dotmd ship\`:\n${allToStage.map(p => `- ${p}`).join('\n')}`;
     const commitMsg = `${subject}\n\n${body}`;
     const commit = spawnSync('git', ['commit', '-m', commitMsg], { cwd: config.repoRoot, encoding: 'utf8' });

package/src/use.mjs

@@ -2,13 +2,13 @@ import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
 import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
-import { runPickup } from './lifecycle.mjs';
+import { startPlan } from './lifecycle.mjs';
 
 // Top-level `dotmd use [file]` — the single "start engaging with this doc"
 // verb. Dispatches by the target doc's `type:` so agents don't have to know
 // the verb-per-type rule:
 //   - prompt → print body + archive (one-shot consume)
-//   - plan   → acquire lease + print body (same as `set in-session`)
+//   - plan   → set status in-session + print the plan card
 //   - doc    → print body (read-only)
 // With no argument, consumes the oldest pending prompt.
 export async function runUse(argv, config, opts = {}) {
@@ -34,8 +34,8 @@ export async function runUse(argv, config, opts = {}) {
     return consumePrompt(filePath, config, opts);
   }
   if (type === 'plan') {
-    // Delegate to the lease-acquisition path. Same flow as `set in-session`.
-    return runPickup([filePath, ...argv.filter(a => a !== positional)], config, opts);
+    // Mark in-session (pure frontmatter) and print the plan card.
+    return startPlan([filePath, ...argv.filter(a => a !== positional)], config, opts);
   }
   // Anything else (doc, untyped, custom): print the body. The frontmatter
   // already names everything an agent needs to know about lifecycle for that

package/src/util.mjs

@@ -1,7 +1,17 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { dim } from './color.mjs';
 
+// Stable identifier for the current shell/agent session. Used for journal
+// attribution and hint de-duplication — not for any plan locking.
+export function currentSessionId() {
+  if (process.env.CLAUDE_CODE_SESSION_ID) return process.env.CLAUDE_CODE_SESSION_ID;
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+  if (process.env.TERM_SESSION_ID) return `term:${process.env.TERM_SESSION_ID}`;
+  return `shell:${os.userInfo().username}@${os.hostname()}`;
+}
+
 export function escapeTable(value) {
   return String(value).replace(/\|/g, '\\|');
 }

package/src/validate.mjs

@@ -2,7 +2,6 @@ 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, STALE_LEASE_AGE_HOURS } from './lease.mjs';
 
 const NOW = new Date();
 
@@ -202,31 +201,6 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Archived plan missing `## Closeout` section.' });
   }
 
-  // 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 (> 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];
-    if (!lease) {
-      doc.warnings.push({
-        path: doc.path,
-        level: 'warning',
-        message: `\`status: in-session\` but no session is actually working on this (previous session may have crashed). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
-      });
-    } else if (isLeaseStale(lease)) {
-      const ageHours = Math.floor((Date.now() - new Date(lease.pickedUpAt).getTime()) / (1000 * 60 * 60));
-      doc.warnings.push({
-        path: doc.path,
-        level: 'warning',
-        message: `\`status: in-session\` but last activity was ${ageHours}h ago (>${STALE_LEASE_AGE_HOURS}h, looks abandoned). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
-      });
-    }
-  }
-
   // Archive drift: a doc with an archive-flagged status (`status: archived` by
   // default) whose parent dir is a "live" type-conventional location is
   // misplaced — `dotmd archive` would have moved it under `<that>/archiveDir/`.