dotmd-cli 0.74.1 → 0.74.3

package/bin/dotmd.mjs

@@ -202,6 +202,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)
+  doctor --claims                   Report/release plan claims held by sessions that are gone ("busy in another session")
   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
@@ -727,6 +728,21 @@ Modes:
                          clear the transactions whose files already agree on
                          one generation (no document content is touched);
                          the rest are reported for manual review.
+  --claims               Report which plans are claimed by which session, how
+                         old each claim is, and whether the owning session's
+                         process is still alive. A claim is what makes \`set\`,
+                         \`archive\`, \`baton\`, and \`rename\` refuse a single
+                         plan ("Plan is busy in another session"); nothing
+                         expires one, so a session that died holds its plan
+                         until someone takes it back. Add --apply to release
+                         the claims whose owning process is provably gone
+                         (their plans return to \`active\`).
+  --claims --apply --older-than <24h|3d>
+                         Also release claims dotmd cannot judge — ones written
+                         before it recorded the owning process, or held on
+                         another machine — that are older than the duration.
+                         That threshold is your judgement, not dotmd's: it
+                         cannot tell a dead session from a slow one.
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -903,7 +919,10 @@ Plan body variants (plans only — pick one body shape):
 Other options:
   --status <s>         Set initial status (defaults to first valid status for the type)
   --title <t>          Override the auto-derived title
-  --root <name>        Create in a specific docs root
+  --root <name>        Create in a specific docs root. Applies to a nested name
+                       too: \`new doc prospects/kim --root docs\` writes
+                       docs/prospects/kim.md. Without it, a name containing a
+                       \`/\` is read relative to the repo.
   --show-files         Append \`files: …\` line to stderr listing what was touched
                        (the new doc + the index file). See \`dotmd archive --help\`.
   --list-types         Show registered types (alias: --list-templates)
@@ -1741,7 +1760,9 @@ async function main() {
     const doctorDryRun = doctorSubMode ? dryRun : (dryRun || !doctorExplicitApply);
     const filtered = restArgs.filter(a => a !== '--apply' && a !== '--yes');
     const { runDoctor } = await import('../src/doctor.mjs');
-    runDoctor(filtered, config, { dryRun: doctorDryRun });
+    // Awaited because --claims releases through `runSet`, which is async; the
+    // other modes return undefined and are unaffected.
+    await runDoctor(filtered, config, { dryRun: doctorDryRun });
     return;
   }
   if (command === 'statuses') { const { runStatuses } = await import('../src/statuses.mjs'); await runStatuses(restArgs, config, { dryRun, type: typeArg }); return; }

package/package.json

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

package/src/commands.mjs

@@ -134,7 +134,7 @@ const definitions = [
   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('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  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('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('--claims'), value('--older-than'), 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

@@ -1,9 +1,9 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
 import { syncHubStatuses } from './sync-status.mjs';
-import { runTouch } from './lifecycle.mjs';
+import { runSet, runTouch } from './lifecycle.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
@@ -14,8 +14,9 @@ import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
 import { normalizeEol } from './frontmatter.mjs';
-import { toRepoPath } from './util.mjs';
+import { die, relTime, toRepoPath } from './util.mjs';
 import { inspectTransactions, resolveTransactions } from './atomic-mutation.mjs';
+import { availableSessionId, releaseVanishedPlanClaim, surveyOwnershipClaims } from './pickup.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).
@@ -105,6 +106,109 @@ function runDoctorTransactions(argv, config, opts = {}) {
   }
 }
 
+function parseOlderThan(argv) {
+  const idx = argv.indexOf('--older-than');
+  if (idx === -1) return null;
+  const raw = argv[idx + 1];
+  const match = /^(\d+)([hd])$/.exec(raw ?? '');
+  if (!match) die('--older-than takes a duration like 24h or 3d');
+  return Number(match[1]) * (match[2] === 'h' ? 3600_000 : 86_400_000) ;
+}
+
+// The counterpart to --transactions: a claim nobody will ever release wedges
+// `set`, `archive`, `baton` and `rename` on that plan forever, and until now
+// nothing in the tool could even show you the claims, let alone end one.
+//
+// Two tiers, because two very different things are being asked. A claim whose
+// session process is provably gone is released by --apply on its own: that is
+// dotmd observing a fact, the same bar a forced hook-delivery takeover uses.
+// A claim dotmd *cannot* judge — written before it recorded the owning process,
+// taken from a plain terminal, or held on another machine — is never released
+// by a plain --apply, because "I can't see the owner" is not evidence the owner
+// left. Releasing those needs --older-than, which is the user supplying the
+// judgement dotmd doesn't have, as a policy rather than a guess.
+async function runDoctorClaims(argv, config, opts = {}) {
+  const json = argv.includes('--json');
+  const apply = !opts.dryRun;
+  const olderThanMs = parseOlderThan(argv);
+  const claims = surveyOwnershipClaims(config);
+
+  const dead = claims.filter(claim => !claim.corrupt && claim.liveness === 'dead');
+  const aged = olderThanMs === null ? [] : claims.filter(claim =>
+    !claim.corrupt && claim.liveness !== 'dead' && claim.ageMs !== null && claim.ageMs >= olderThanMs);
+  const targets = [...dead, ...aged];
+
+  const released = [];
+  // The repair runs under whatever identity the shell has, and a shell with none
+  // is a normal place to run it from — this is the command you reach for when the
+  // sessions are gone. Mirrors the synthetic id `set --dry-run` already uses.
+  const operator = availableSessionId() ?? 'doctor:claims-repair';
+  if (apply) {
+    for (const claim of targets) {
+      try {
+        // Two shapes of release, because a vanished plan has no file to write a
+        // status into. Deciding by existence here rather than by catching
+        // runSet's "File not found" keeps the bypass narrow and explicit.
+        if (existsSync(path.resolve(config.repoRoot, claim.plan))) {
+          await runSet(['active', claim.plan], config, { force: true, sessionId: operator, note: 'Claim released by `dotmd doctor --claims` — the owning session was gone.' });
+        } else {
+          releaseVanishedPlanClaim(claim, config);
+          claim.vanished = true;
+        }
+        released.push(claim.plan);
+      } catch (err) {
+        claim.error = err.message.split('\n')[0];
+      }
+    }
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ claims, released }, null, 2) + '\n');
+    return;
+  }
+  if (claims.length === 0) {
+    process.stdout.write(green('✓') + ' No plans are claimed — nothing can be wedged by ownership.\n');
+    return;
+  }
+
+  const releasedSet = new Set(released);
+  process.stdout.write(bold(`Plan claims (${claims.length})\n`));
+  for (const claim of claims) {
+    if (claim.corrupt) {
+      process.stdout.write(`  ${yellow('?')} ${path.basename(claim.recordPath)} — ${claim.reason}\n`);
+      continue;
+    }
+    const mark = releasedSet.has(claim.plan) ? green('✓') : claim.liveness === 'dead' ? yellow('!') : dim('·');
+    const age = claim.since ? relTime(claim.since) : 'age unknown';
+    const note = releasedSet.has(claim.plan)
+      ? (claim.vanished ? 'released (plan no longer exists)' : 'released')
+      : claim.error ?? `owner ${claim.liveness}`;
+    process.stdout.write(`  ${mark} ${claim.plan} — ${age}, session ${claim.sessionId}, ${note}\n`);
+  }
+
+  if (released.length) {
+    // Only the claims with a plan behind them came back as `active`; saying so
+    // of a vanished one would promise a file the next command cannot open.
+    const vanished = targets.filter(claim => claim.vanished && releasedSet.has(claim.plan)).length;
+    const revived = released.length - vanished;
+    const parts = [];
+    if (revived) parts.push(`${revived} plan${revived === 1 ? ' is' : 's are'} active again`);
+    if (vanished) parts.push(`${vanished} pinned a plan that no longer exists`);
+    process.stdout.write(green(`\n✓ Released ${released.length} claim${released.length === 1 ? '' : 's'}; ${parts.join(', ')}.\n`));
+  }
+  const pendingDead = dead.filter(claim => !releasedSet.has(claim.plan));
+  if (pendingDead.length) {
+    process.stdout.write(yellow(`\n${pendingDead.length} held by a session whose process is gone.\n`));
+    process.stdout.write(dim('Run `dotmd doctor --claims --apply` to release them.\n'));
+  }
+  const unjudgeable = claims.filter(claim =>
+    !claim.corrupt && claim.liveness !== 'dead' && !releasedSet.has(claim.plan));
+  if (unjudgeable.length && olderThanMs === null) {
+    process.stdout.write(dim(`\n${unjudgeable.length} cannot be judged from here — no owning process was recorded, or it is on another machine.\n`));
+    process.stdout.write(dim('If you know those sessions are over: `dotmd doctor --claims --apply --older-than 24h`.\n'));
+  }
+}
+
 export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
@@ -130,6 +234,9 @@ export function runDoctor(argv, config, opts = {}) {
     runDoctorTransactions(argv, config, opts);
     return;
   }
+  if (argv.includes('--claims')) {
+    return runDoctorClaims(argv, config, opts);
+  }
 
   const { dryRun, testHooks } = opts;
   // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run

package/src/hud.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { currentSessionId, isArchivedPath } from './util.mjs';
+import { currentSessionId, isArchivedPath, relTime } from './util.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
@@ -67,19 +67,6 @@ const REJECTIONS_CAP = 3;
 const FLEET_WINDOW_MS = 24 * 60 * 60 * 1000;
 const REJECTIONS_WINDOW_MS = 60 * 60 * 1000;
 
-function relTime(ts, now = Date.now()) {
-  const t = new Date(ts).getTime();
-  if (!Number.isFinite(t)) return '?';
-  const delta = Math.max(0, now - t);
-  const sec = Math.floor(delta / 1000);
-  if (sec < 60) return `${sec}s ago`;
-  const min = Math.floor(sec / 60);
-  if (min < 60) return `${min}m ago`;
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  return `${Math.floor(hr / 24)}d ago`;
-}
-
 // Coarse error-class for rejection grouping. Most dotmd die() messages follow
 // `<class>: <variable detail>` (e.g. "File not found: docs/foo.md", "Already
 // archived: docs/plans/x.md", "Too many arguments to status"). Take the chunk

package/src/lifecycle.mjs

@@ -24,6 +24,7 @@ import {
   commitPlanClaim,
   finishClaimHookDelivery,
   listOwnedPlans,
+  ownershipLiveness,
   pickupFactsForDoc,
   prepareOwnershipRelease,
   readPlanOwnership,
@@ -607,6 +608,7 @@ export async function startPlan(argv, config, opts = {}) {
   let disposition = classifyPlanPickup({
     type: docType,
     status: oldStatus,
+    ownerLiveness: ownershipLiveness(ownership),
     validStatuses: config.typeStatuses?.get('plan') ?? config.validStatuses,
     startableStatuses: config.lifecycle.startableStatuses,
     terminalStatuses: config.lifecycle.terminalStatuses,
@@ -959,7 +961,13 @@ export async function runSet(argv, config, opts = {}) {
   const releasing = asString(oldFm?.type) === 'plan'
     && (asString(oldFm?.status) === 'in-session' || oldOwnership?.state === 'owned' || oldOwnership?.corrupt);
   if (releasing) {
-    sessionId ??= authoritativeSessionId();
+    // opts.sessionId lets a repair caller supply the operator identity. Only
+    // `doctor --claims` passes it: releasing a claim stamps the id into the
+    // tombstone as provenance and takes nothing, so demanding an *authoritative*
+    // one of the repairer is backwards for the command that exists to unwedge
+    // sessions — it made the recovery path unusable from any shell without a
+    // session of its own (a bare login shell, cron, CI).
+    sessionId ??= opts.sessionId ?? authoritativeSessionId();
     assertPlanMutationAuthorized(repoPath, config, { sessionId, force });
     if (!dryRun) ensurePlanCompletionBeforeRelease(repoPath, config, { testHooks: opts.testHooks });
     else if (planHasPendingCompletion(repoPath, config)) process.stderr.write(`${dim('[dry-run]')} Pending claim completion would block this release.\n`);

package/src/new.mjs

@@ -60,6 +60,27 @@ function fullBodyShortcut(title, bodyInput) {
   return hasOwnTitle ? `\n${b}\n` : `\n# ${title}\n\n${b}\n`;
 }
 
+function lexicallyInside(parent, child) {
+  return child === parent || child.startsWith(parent + path.sep);
+}
+
+// The default root for a type that doesn't name one of its own. This used to be
+// "whichever root is listed first", which drops a `doc` into `docs/plans` for
+// any project that lists its plans root first — the plan type's own root, for a
+// type that isn't a plan. When one configured root contains another it is
+// structurally the catch-all (`docs` holding `docs/plans` and `docs/adr`), so
+// prefer that; the deepest one, so a nested chain picks the most specific
+// container rather than the outermost. Single-root projects and flat sibling
+// roots have no catch-all to find and keep first-listed order.
+export function catchAllRoot(config) {
+  const roots = config.docsRoots ?? [config.docsRoot];
+  if (roots.length < 2) return config.docsRoot;
+  const containers = roots.filter(root => roots.some(other => other !== root && lexicallyInside(root, other)));
+  if (!containers.length) return config.docsRoot;
+  const depth = root => root.split(path.sep).length;
+  return containers.reduce((deepest, root) => depth(root) > depth(deepest) ? root : deepest);
+}
+
 const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
@@ -287,8 +308,15 @@ function isBodyPlaceholder(file) {
   return BODY_PLACEHOLDER_NAMES.has(file);
 }
 
+// `@-` is the natural composition of the two spellings dotmd documents (`@path`
+// and `-`), and agents write it — three times in the platform transcripts, each
+// with a valid heredoc already on stdin that was then thrown away for a file
+// literally named `-`. Nothing else can sensibly be meant by it, so it means
+// stdin, unconditionally. That follows the universal CLI convention rather than
+// the placeholder rule below (where a real file wins): under this convention a
+// file actually named `-` is spelled `./-`, which still takes the file branch.
 export function readBodyInput(source) {
-  if (source === '-') {
+  if (source === '-' || source === '@-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
   }
   if (typeof source === 'string' && source.startsWith('@')) {
@@ -711,7 +739,9 @@ export async function runNew(argv, config, opts = {}) {
   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');
+    bodyInputSource = (bodyArg === '-' || bodyArg === '@-')
+      ? `stdin (\`${bodyArg}\`)`
+      : (bodyArg.startsWith('@') ? `file (\`${bodyArg}\`)` : 'inline body argument');
   } else {
     // Auto-consume piped or redirected stdin so agents don't need the `-`
     // placeholder for the most common pattern (`cat draft.md | dotmd new …`,
@@ -791,6 +821,9 @@ export async function runNew(argv, config, opts = {}) {
   } else if (name.endsWith('.md')) {
     namePart = name.slice(0, -3);
   }
+  // A prefix the *user* typed and one a template declares resolve differently
+  // below, so the distinction has to survive the template's assignment to nameDir.
+  const userNameDir = nameDir;
 
   // Slugify
   const slug = namePart.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
@@ -802,7 +835,7 @@ export async function runNew(argv, config, opts = {}) {
   // Resolve target root. Precedence: CLI --root > template.targetRoot > config.docsRoot.
   // When the chosen root is a first-class type-container (matched by --root or targetRoot),
   // we skip the `template.dir` join — the root already points at the right directory.
-  let targetRoot = config.docsRoot;
+  let targetRoot = catchAllRoot(config);
   let routedToTypeRoot = false;
   if (rootName) {
     const roots = config.docsRoots || [config.docsRoot];
@@ -828,10 +861,46 @@ export async function runNew(argv, config, opts = {}) {
     nameDir = path.join(path.relative(config.repoRoot, targetRoot), template.dir);
   }
 
-  // Path — if user provided a directory prefix OR template declared one, resolve relative to repoRoot
-  const baseDir = nameDir ? path.resolve(config.repoRoot, nameDir) : targetRoot;
+  // Path — a directory prefix is read relative to the repo, because `dotmd new
+  // plan docs/plans/feature` is a full repo path and has to stay one. That was
+  // the ONLY reading, which is how `--root` came to be silently ignored the
+  // moment a name contained a slash: the block above picked a root and this line
+  // threw it away, so the one flag the out-of-root error advertises could not
+  // fix the error. With an explicit --root the prefix is now read relative to
+  // that root — unless the repo-relative reading already lands inside it, so
+  // full paths keep working.
+  const allRoots = config.docsRoots ?? [config.docsRoot];
+  let baseDir;
+  if (!nameDir) baseDir = targetRoot;
+  else if (userNameDir && rootName) {
+    const repoRelative = path.resolve(config.repoRoot, nameDir);
+    baseDir = lexicallyInside(targetRoot, repoRelative) ? repoRelative : path.resolve(targetRoot, nameDir);
+  } else baseDir = path.resolve(config.repoRoot, nameDir);
   const filePath = path.join(baseDir, slug + '.md');
   const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  // Without --root there is nothing to disambiguate with, so a prefix pointing
+  // outside every root stays an error — but it names the flag that resolves it,
+  // and the flag now works. The generic containment error underneath reports
+  // absolute paths and no remedy, which is what agents kept re-guessing at.
+  //
+  // Gated on the remedy actually working: the suggestion is only offered when
+  // `--root` would land the file inside that root. That is what keeps this off
+  // a traversal (`../escaped`, an absolute path), where `--root` fixes nothing
+  // and the containment check below is the error that should speak — printing
+  // an untested remedy is the very defect this finding is about.
+  if (userNameDir && !rootName && !allRoots.some(root => lexicallyInside(root, filePath))) {
+    const rooted = path.resolve(targetRoot, userNameDir, slug + '.md');
+    if (lexicallyInside(targetRoot, rooted)) {
+      die(`Destination is outside every configured root:\n`
+        + `  ${repoPath}\n\n`
+        + `A name with a \`/\` is read relative to the repo.\n`
+        + `To place it under a root instead:\n`
+        + `  dotmd new ${typeName} ${name} --root ${path.basename(targetRoot)}\n`
+        + `     → ${toRepoPath(rooted, config.repoRoot)}\n\n`
+        + `Roots: ${allRoots.map(root => path.basename(root)).join(', ')}`);
+    }
+  }
   const destinationAuthorization = authorizeManagedDestination(filePath, config, { kind: 'New document destination' });
 
   if (existsSync(filePath)) {
@@ -853,12 +922,15 @@ export async function runNew(argv, config, opts = {}) {
   // When the project has >1 root and `--root` was omitted, surface the choice
   // so agents can see that an alternative root was available. Cheap visibility
   // for the "ended up in docs/plans/ for a doc" foot-gun.
-  const allRoots = config.docsRoots ?? [config.docsRoot];
+  // Report the root the file actually landed in, not the one resolution started
+  // from: a directory prefix can move the destination into a different root
+  // entirely, and the line used to say `Root: plans` while writing docs/prospects/.
   let rootHint = '';
   if (!rootName && allRoots.length > 1) {
-    const chosenLabel = path.basename(targetRoot);
+    const owningRoot = destinationAuthorization.root.lexicalPath;
+    const chosenLabel = path.basename(owningRoot);
     const others = allRoots
-      .filter(r => r !== targetRoot)
+      .filter(r => r !== owningRoot)
       .map(r => path.basename(r));
     rootHint = `Root: ${chosenLabel} (others: ${others.join(', ')} — pass --root <name> to change)\n`;
   }

package/src/pickup.mjs

@@ -2,9 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-path.mjs';
-import { currentProcessOwner, mutateFileSet, processOwnerLiveness, replaceSnapshot, snapshotFile, withPathLocks } from './atomic-mutation.mjs';
+import os from 'node:os';
+import { currentProcessOwner, mutateFileSet, processOwnerLiveness, processStartIdentity, replaceSnapshot, snapshotFile, withPathLocks } from './atomic-mutation.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString } from './util.mjs';
+import { asString, relTime } from './util.mjs';
 
 export const OWNERSHIP_SCHEMA = 2;
 export const HOOK_DELIVERY_LEASE_MS = 30_000;
@@ -29,6 +30,34 @@ export function availableSessionId(env = process.env) {
   try { return authoritativeSessionId(env); } catch { return null; }
 }
 
+// The process that OWNS the session, not the one taking the claim. `dotmd` exits
+// within the second, so its own pid is always dead a moment later and can say
+// nothing about whether the session still exists; the agent harness that spawned
+// it is what outlives the command. Recording that process is what lets a claim
+// answer "is its owner still there?" with the liveness check dotmd already has,
+// instead of an age threshold that cannot tell a three-day-dead session from a
+// long-running one. Absent (a plain terminal, an unknown harness) is not an
+// error — it yields null, which reads as 'unverifiable' and never auto-reclaims.
+export function sessionProcessOwner(env = process.env) {
+  const raw = (env.DOTMD_SESSION_PID ?? env.CLAUDE_PID)?.trim();
+  const pid = Number(raw);
+  if (!raw || !Number.isInteger(pid) || pid <= 0) return null;
+  return {
+    pid,
+    hostname: os.hostname(),
+    processStartIdentity: processStartIdentity(pid),
+  };
+}
+
+// Only a claim that names a process we can probe, on this host, can be judged.
+// Everything else — a record written before sessionOwner existed, a claim from a
+// plain terminal, another machine's claim on a shared filesystem — is
+// 'unverifiable' and is treated as live, so a takeover stays an explicit --force.
+export function ownershipLiveness(ownership) {
+  if (!ownership || ownership.corrupt || !ownership.sessionOwner) return 'unverifiable';
+  return processOwnerLiveness(ownership.sessionOwner);
+}
+
 function sameIdentity(left, right, fs = { statSync }) {
   try {
     const a = fs.statSync(left, { bigint: true });
@@ -61,6 +90,10 @@ export function classifyPlanPickup(facts) {
   const {
     type, status, validStatuses, startableStatuses, terminalStatuses,
     archiveStatuses, physicallyArchived, ownership, sessionId, malformed,
+    // Defaulted rather than required: a caller with no view of the owning
+    // process (and every existing test) gets the conservative answer, which is
+    // that the owner might still be there.
+    ownerLiveness = 'unverifiable',
   } = facts;
   if (malformed) return { kind: 'malformed', pickupable: false };
   if (type !== 'plan') return { kind: 'wrong-type', pickupable: false };
@@ -68,11 +101,15 @@ export function classifyPlanPickup(facts) {
   if (physicallyArchived) return { kind: 'physical-archive', pickupable: false };
   if (archiveStatuses?.has(status) || terminalStatuses?.has(status)) return { kind: 'terminal', pickupable: false };
   if (ownership?.corrupt) return { kind: 'ownership-corrupt', pickupable: false };
-  if (ownership?.state === 'owned' && ownership.sessionId !== sessionId) {
+  if (ownership?.state === 'owned' && ownership.sessionId !== sessionId && ownerLiveness !== 'dead') {
     return { kind: 'busy', pickupable: false, owner: ownership.sessionId };
   }
   if (status === 'in-session') {
-    if (ownership?.state === 'owned') return { kind: 'resume', pickupable: true };
+    // `resume` means picking my own claim back up. A record left by a session
+    // whose process is gone reached here because it is no longer busy, and
+    // taking that over is an adopt — the same disposition as a plan sitting
+    // `in-session` with no record at all.
+    if (ownership?.state === 'owned' && ownership.sessionId === sessionId) return { kind: 'resume', pickupable: true };
     return { kind: 'adopt', pickupable: true };
   }
   if (startableStatuses?.has(status)) return { kind: 'start', pickupable: true };
@@ -150,6 +187,40 @@ function parseOwnership(raw, recordPath) {
   }
 }
 
+// The bar for reclaiming another session's plan without being asked to, and it is
+// deliberately the same bar `assertHookDeliveryReclaimable` already sets for a
+// forced hook-delivery takeover: *demonstrably* dead. `processOwnerLiveness`
+// answers 'dead' only for a probe that came back ESRCH on this host, or a pid
+// whose process start-identity no longer matches the one recorded — so a reused
+// pid reads live, another machine's claim reads unverifiable, and a record
+// written before `sessionOwner` existed reads unverifiable. Every one of those
+// keeps the refusal and leaves the takeover to an explicit --force. Only a
+// process we watched go away is treated as gone.
+function abandonedByDeadSession(ownership) {
+  return ownershipLiveness(ownership) === 'dead';
+}
+
+const BUSY_TAKEOVER_RECOVERY = 're-run this command with --force to take the plan over.';
+
+// A busy refusal almost always fires on the command that would have *cleared*
+// the wedge — `baton`, `set`, `archive` — so the message has to carry the two
+// things that decide what to do next: how long the owner has held the claim, and
+// the verb that takes it back. Nothing expires a session claim, so an owner
+// three days gone looks exactly like one mid-edit; a survey of real sessions
+// found 16 of these against 7 plans, every owner long dead, and not one of them
+// recovered. What agents did instead was re-run the same command with the plan
+// addressed differently (path, then slug) — reading a bare "busy in another
+// session (<uuid>)" as "you named the plan wrong". The age is the judgement
+// input and the recovery line is the way out; neither was there to read.
+function planBusyError(repoPath, ownership, recovery = BUSY_TAKEOVER_RECOVERY) {
+  const since = ownership.updatedAt ?? ownership.claimedAt ?? null;
+  const age = since ? relTime(since) : null;
+  const held = age && age !== '?' ? ` since ${since} (${age})` : '';
+  return new Error(`Plan is busy in another session: ${repoPath}\n`
+    + `  held by session ${ownership.sessionId}${held}\n`
+    + `  If that session is gone, ${recovery}`);
+}
+
 function validateBinding(record, identity, config) {
   if (record.corrupt) return record;
   const expectedPath = recordPathForIdentity(identity, config);
@@ -176,14 +247,20 @@ export function prepareOwnershipMigration(oldRepoPath, newPath, config, { sessio
   const ownership = readPlanOwnership(oldRepoPath, config);
   if (!ownership) return null;
   if (ownership.corrupt) throw new Error(`Ownership record is corrupt for ${oldRepoPath}: ${ownership.reason}; repair or release it before rename.`);
-  if (ownership.state === 'owned' && ownership.sessionId !== sessionId) {
-    throw new Error(`Plan is busy in another session (${ownership.sessionId}): ${oldRepoPath}`);
+  if (ownership.state === 'owned' && ownership.sessionId !== sessionId && !abandonedByDeadSession(ownership)) {
+    // `rename` has no --force of its own: a rename carries the claim across to
+    // the new path rather than ending it, so the takeover has to happen first.
+    throw planBusyError(oldRepoPath, ownership,
+      `release it first with \`dotmd set <status> ${oldRepoPath} --force\`, then rename.`);
   }
   const identity = plannedPlanIdentity(newPath, config);
   const recordPath = recordPathForIdentity(identity, config);
   const content = recordContent({
     identity,
     sessionId: ownership.sessionId,
+    // A rename moves the claim, it does not re-take it: the same session still
+    // owns the plan, so its owning process carries across untouched.
+    sessionOwner: ownership.sessionOwner,
     state: ownership.state,
     now,
     claimedAt: ownership.claimedAt,
@@ -228,7 +305,12 @@ export function listOwnedPlans(config, sessionId = authoritativeSessionId()) {
   return Object.assign(found, { diagnostics });
 }
 
-function recordContent({ identity, sessionId, state, now, claimedAt, operation }) {
+// `sessionOwner` is deliberately additive rather than a schema bump: parseOwnership
+// accepts exactly OWNERSHIP_SCHEMA, so raising it would turn every record already
+// on disk corrupt — which is a worse wedge than the one this fixes. An old record
+// simply has no sessionOwner and stays 'unverifiable' for its whole life; an older
+// dotmd reading a new record ignores a field it does not validate.
+function recordContent({ identity, sessionId, state, now, claimedAt, operation, sessionOwner }) {
   return JSON.stringify({
     schema: OWNERSHIP_SCHEMA,
     state,
@@ -236,6 +318,7 @@ function recordContent({ identity, sessionId, state, now, claimedAt, operation }
     canonicalPath: identity.canonicalPath,
     identityKey: identity.key,
     sessionId,
+    sessionOwner: sessionOwner ?? null,
     claimedAt: claimedAt ?? now,
     updatedAt: now,
     operation: operation ?? null,
@@ -256,7 +339,8 @@ export function preparePlanClaim({ filePath, sourceContent, renderedContent, own
     hook: 'pending',
   };
   const content = recordContent({ identity, sessionId, state: 'owned', now,
-    claimedAt: ownership && !ownership.corrupt ? ownership.claimedAt : null, operation });
+    sessionOwner: sessionProcessOwner(), operation,
+    claimedAt: ownership && !ownership.corrupt ? ownership.claimedAt : null });
   const updates = [];
   const guards = [];
   if (renderedContent !== null && renderedContent !== sourceContent) {
@@ -291,8 +375,9 @@ export function prepareOwnershipRelease(repoPath, config, { sessionId = authorit
   const ownership = readPlanOwnership(repoPath, config);
   if (!ownership) return null;
   if (ownership.corrupt && !force) throw new Error(`Ownership record is corrupt for ${repoPath}: ${ownership.reason}; use an explicit path with --force to recover.`);
-  if (!ownership.corrupt && ownership.state === 'owned' && ownership.sessionId !== sessionId && !force) {
-    throw new Error(`Plan is busy in another session (${ownership.sessionId}): ${repoPath}`);
+  if (!ownership.corrupt && ownership.state === 'owned' && ownership.sessionId !== sessionId
+    && !force && !abandonedByDeadSession(ownership)) {
+    throw planBusyError(repoPath, ownership);
   }
   if (!ownership.corrupt && ownership.state === 'released') return null;
   return {
@@ -308,12 +393,90 @@ export function assertPlanMutationAuthorized(repoPath, config, { sessionId = aut
   if (ownership?.corrupt && !force) {
     throw new Error(`Ownership record is corrupt for ${repoPath}: ${ownership.reason}; use an explicit path with --force to recover.`);
   }
-  if (ownership?.state === 'owned' && ownership.sessionId !== sessionId && !force) {
-    throw new Error(`Plan is busy in another session (${ownership.sessionId}): ${repoPath}`);
+  if (ownership?.state === 'owned' && ownership.sessionId !== sessionId
+    && !force && !abandonedByDeadSession(ownership)) {
+    throw planBusyError(repoPath, ownership);
   }
   return ownership;
 }
 
+// Every owned claim in the repo, whoever holds it — the survey `listOwnedPlans`
+// deliberately cannot do, since that one answers "what does THIS session own?".
+// Unlike that function this keeps records whose plan has drifted or vanished:
+// a claim pinning a plan nobody can read is exactly the kind that wedges a repo
+// and so is exactly the kind worth showing.
+export function surveyOwnershipClaims(config, now = Date.now()) {
+  const root = ownershipRoot(config);
+  if (!existsSync(root)) return [];
+  const claims = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const recordPath = path.join(root, entry.name);
+    let record;
+    try { record = parseOwnership(readFileSync(recordPath, 'utf8'), recordPath); }
+    catch { record = { corrupt: true, recordPath, reason: 'unreadable ownership record' }; }
+    if (record.corrupt) {
+      claims.push({ recordPath, plan: null, corrupt: true, reason: record.reason, liveness: 'unverifiable', ageMs: null });
+      continue;
+    }
+    if (record.state !== 'owned') continue;
+    const since = record.updatedAt ?? record.claimedAt ?? null;
+    const parsed = since ? Date.parse(since) : NaN;
+    claims.push({
+      recordPath,
+      plan: record.plan,
+      sessionId: record.sessionId,
+      corrupt: false,
+      since,
+      ageMs: Number.isFinite(parsed) ? Math.max(0, now - parsed) : null,
+      liveness: ownershipLiveness(record),
+    });
+  }
+  claims.sort((a, b) => (b.ageMs ?? 0) - (a.ageMs ?? 0));
+  return claims;
+}
+
+// A claim whose plan file no longer exists — deleted, or renamed by something
+// other than `dotmd rename`, which would have carried the record across. The
+// survey deliberately keeps these (a claim pinning a plan nobody can read is
+// exactly the kind worth showing), but the release path could not act on one:
+// it routes through `runSet`, which needs a file to write a status into, so the
+// record survived every `--apply` and sat in the report forever. Worse, the key
+// is a hash of the path, so a plan later created at that same path would read
+// as owned by a session years gone — born wedged.
+//
+// So this releases from the record itself. No `canonicalPlanIdentity` (it
+// realpaths, which is the thing that cannot work here); the record already
+// carries the identity it was written with. Existence is re-checked under the
+// lock, because "the plan is gone" is the entire justification for bypassing
+// the status write, and a `dotmd new` racing us would invalidate it.
+export function releaseVanishedPlanClaim(claim, config, { now = new Date().toISOString() } = {}) {
+  const recordPath = claim.recordPath;
+  return withPathLocks([recordPath], { repoRoot: config.repoRoot }, () => {
+    const snapshot = snapshotFile(recordPath);
+    const ownership = parseOwnership(snapshot.content, recordPath);
+    if (ownership.corrupt || ownership.state !== 'owned') {
+      throw new Error(`Claim changed under us for ${claim.plan}; re-run to see the current state.`);
+    }
+    if (existsSync(path.resolve(config.repoRoot, ownership.plan))) {
+      throw new Error(`${ownership.plan} exists after all — release it with \`dotmd set active\` instead.`);
+    }
+    replaceSnapshot(snapshot, JSON.stringify({
+      schema: OWNERSHIP_SCHEMA,
+      state: 'released',
+      plan: ownership.plan,
+      canonicalPath: ownership.canonicalPath,
+      identityKey: ownership.identityKey,
+      sessionId: ownership.sessionId,
+      sessionOwner: ownership.sessionOwner ?? null,
+      claimedAt: ownership.claimedAt ?? now,
+      updatedAt: now,
+      operation: null,
+    }, null, 2) + '\n', { repoRoot: config.repoRoot, locked: true });
+    return ownership.plan;
+  });
+}
+
 export function updateOwnershipOperation(repoPath, config, expected, mutate) {
   const ownership = readPlanOwnership(repoPath, config);
   if (!ownership || ownership.corrupt || ownership.state !== 'owned' || !ownership.operation) {
@@ -455,6 +618,7 @@ export function pickupFactsForDoc(doc, config, { sessionId = availableSessionId(
     type: doc?.type ?? null,
     status: doc?.status ?? null,
     validStatuses: config.typeStatuses?.get('plan') ?? config.validStatuses,
+    ownerLiveness: ownershipLiveness(ownership),
     startableStatuses: config.lifecycle.startableStatuses,
     terminalStatuses: config.lifecycle.terminalStatuses,
     archiveStatuses: config.lifecycle.archiveStatuses,

package/src/prompts.mjs

@@ -11,6 +11,7 @@ import { authorizeManagedSource } from './managed-path.mjs';
 import {
   authoritativeSessionId,
   classifyPlanPickup,
+  ownershipLiveness,
   preparePlanClaim,
   readPlanOwnership,
 } from './pickup.mjs';
@@ -380,6 +381,7 @@ function prepareLinkedPromptClaim(planRef, config, promptDir) {
   const disposition = classifyPlanPickup({
     type: asString(parsed.type),
     status: oldStatus,
+    ownerLiveness: ownershipLiveness(ownership),
     validStatuses: config.typeStatuses?.get('plan') ?? config.validStatuses,
     startableStatuses: config.lifecycle.startableStatuses,
     terminalStatuses: config.lifecycle.terminalStatuses,

package/src/util.mjs

@@ -92,6 +92,23 @@ export function nowIso() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
 
+// Coarse "how long ago", for messages where the exact interval matters less than
+// which order of magnitude it is — a claim held 3d is a dead session, one held
+// 4m is a colleague mid-edit. Lives here rather than in either caller because
+// `hud` and `pickup` both need it and util is a leaf both already import.
+export function relTime(ts, now = Date.now()) {
+  const t = new Date(ts).getTime();
+  if (!Number.isFinite(t)) return '?';
+  const delta = Math.max(0, now - t);
+  const sec = Math.floor(delta / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  return `${Math.floor(hr / 24)}d ago`;
+}
+
 export function warn(message) {
   process.stderr.write(`${dim(message)}\n`);
 }