dotmd-cli 0.74.0 → 0.74.2

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
@@ -1741,7 +1757,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.0",
+  "version": "0.74.2",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/atomic-mutation.mjs

@@ -1279,9 +1279,9 @@ export function createFileExclusive(filePath, content, options) {
 }
 
 export function moveFileAtomic(sourcePath, targetPath, render, options) {
-  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [] } = options;
+  const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [], guards = [] } = options;
   recoverAbandonedTransactions(repoRoot, options);
-  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path)], options, () => {
+  return withPathLocks([sourcePath, targetPath, ...updates.map(item => item.path), ...creations.map(item => item.path), ...deletions.map(item => item.path), ...guards.map(item => item.path)], options, () => {
     testHooks?.afterTransactionPhase?.('lock', { sourcePath, targetPath });
     testHooks?.beforeMoveSnapshot?.({ sourcePath, targetPath });
     const source = snapshotFile(sourcePath);
@@ -1304,6 +1304,15 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       }
       return { ...item, snapshot };
     });
+    // Read-only participants (see `mutateFileSet`). Checked before the
+    // transaction manifest exists, so a guard conflict can never leave a
+    // transaction to recover from.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the move mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
@@ -1627,9 +1636,30 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
   });
 }
 
-export function mutateFileSet({ updates = [], creations = [] }, options) {
-  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path)];
+// `guards` are read-only participants: files the mutation's VALIDITY depends on
+// but that it never writes. They take part in locking and in the same
+// compare-and-swap as `updates`, so a mutation decided from a file it doesn't
+// modify cannot land after that file changed underneath it.
+//
+// Without this, a decision read and the write it justifies are two separate
+// steps with nothing holding the gap. A claim that adopts an already-in-session
+// plan writes only the ownership record — so a concurrent `set` releasing that
+// plan could win the status write while the claim still took ownership, leaving
+// a record that owns a plan the file says is `active`. A no-op update on the
+// plan file would close the gap too, but it would rewrite bytes and report the
+// plan as changed to anything counting touched files. A guard says what is meant.
+export function mutateFileSet({ updates = [], creations = [], guards = [] }, options) {
+  const paths = [...updates.map(item => item.path), ...creations.map(item => item.path), ...guards.map(item => item.path)];
   return withPathLocks(paths, options, () => {
+    // Guards are pure preconditions, so they are checked before anything at all
+    // is created — a guard conflict must leave the tree byte-identical, not even
+    // an empty directory behind.
+    for (const guard of guards) {
+      const snapshot = snapshotFile(guard.path);
+      if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
+        throw new MutationConflictError(`File changed while the mutation set was being prepared: ${snapshot.path}`);
+      }
+    }
     const createdDirectories = [];
     for (const item of creations) {
       const directory = path.dirname(item.path);
@@ -1654,7 +1684,7 @@ export function mutateFileSet({ updates = [], creations = [] }, options) {
     for (const item of creations) {
       if (existsSync(item.path)) throw new MutationConflictError(`Destination already exists: ${path.resolve(item.path)}`);
     }
-    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations });
+    options.testHooks?.afterSetPreflight?.({ updates: preparedUpdates, creations, guards });
 
     const committedUpdates = [];
     const committedCreations = [];

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,
@@ -107,6 +108,7 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
         }),
       })), ...additionalUpdates],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
       gitMove: tracked,
       gitIndex,
       operation: 'lifecycle-move',
@@ -115,12 +117,13 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     });
     return { ...result, sourceContent: moveResult.source.content, updatedPaths: moveResult.updatedPaths };
   }
-  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0) {
+  if ((options.additionalUpdates?.length ?? 0) > 0 || (options.creations?.length ?? 0) > 0 || (options.guards?.length ?? 0) > 0) {
     const sourceContent = readFileSync(filePath, 'utf8');
     const result = render(sourceContent);
     mutateFileSet({
       updates: [{ path: filePath, expectedContent: sourceContent, content: result.content }, ...(options.additionalUpdates ?? [])],
       creations: options.creations ?? [],
+      guards: options.guards ?? [],
     }, { repoRoot: config.repoRoot, testHooks: options.testHooks });
     return { ...result, sourceContent, updatedPaths: [] };
   }
@@ -605,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,
@@ -767,6 +771,7 @@ export function runArchive(argv, config, opts = {}) {
         createSection: Boolean(note),
         additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
         creations: opts.creations,
+        guards: opts.guards,
         testHooks: opts.testHooks,
       });
     if (!noIndex && !opts.deferIndex) regenIndex(config);
@@ -833,6 +838,7 @@ export function runArchive(argv, config, opts = {}) {
       testHooks: opts.testHooks,
       additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
       creations: opts.creations,
+      guards: opts.guards,
       skipInboundRefs: opts.skipInboundRefs,
       bodyTransform: closeoutTemplate ? currentBody => {
         committedCloseoutAction = planCloseoutInjection(currentBody);
@@ -955,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

@@ -287,8 +287,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 +718,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 …`,

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,21 +339,31 @@ 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) {
     updates.push({ path: filePath, expectedContent: sourceContent, content: renderedContent });
+  } else {
+    // An `adopt` claim writes only the ownership record — the plan is already
+    // `in-session`, so there is nothing to render. The DECISION still rests on
+    // the plan's status, which was read before this mutation was prepared, so
+    // the plan file joins as a read-only guard. Without it, a concurrent
+    // `set active` could win the status write while this claim takes ownership,
+    // leaving a record that owns a plan the file calls `active`.
+    guards.push({ path: filePath, expectedContent: sourceContent });
   }
   const creations = [];
   if (ownership) updates.push({ path: recordPath, expectedContent: ownership.raw, content });
   else creations.push({ path: recordPath, content });
-  return { identity, recordPath, updates, creations, operationId };
+  return { identity, recordPath, updates, creations, guards, operationId };
 }
 
 export function commitPlanClaim(args) {
   const prepared = preparePlanClaim(args);
   mkdirSync(path.dirname(prepared.recordPath), { recursive: true });
-  mutateFileSet({ updates: prepared.updates, creations: prepared.creations }, {
+  mutateFileSet({ updates: prepared.updates, creations: prepared.creations, guards: prepared.guards }, {
     repoRoot: args.config.repoRoot,
     testHooks: args.testHooks,
   });
@@ -282,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 {
@@ -299,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) {
@@ -446,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';
@@ -289,6 +290,10 @@ export async function consumePrompt(filePath, config, opts) {
     skipInboundRefs: true,
     additionalUpdates: linkedClaim?.prepared?.updates,
     creations: linkedClaim?.prepared?.creations,
+    // An adopt-shaped claim writes no plan content, so the plan file rides
+    // along as a read-only guard — the claim is only valid while the plan still
+    // says what the disposition was read from.
+    guards: linkedClaim?.prepared?.guards,
   });
   const consumedBody = archiveResult?.consumedBody ?? body;
 
@@ -376,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`);
 }