dotmd-cli 0.16.0 → 0.17.0

package/README.md

@@ -117,12 +117,12 @@ The default plan vocabulary is shaped around the **unstuck-action test**: every
 | `planned` | Wait for trigger | Queued; not yet ready to execute. |
 | `blocked` | **Monitor** | External arrival on its own schedule (hardware, vendor, third-party rollout). You can't speed it up. |
 | `partial` | **Spawn successors** | Shipped most of the plan; tail deferred. Body should reference successor plans tracking the tail. Visible but quiet (no nagging). |
-| `paused` | **Re-evaluate** | Intentionally set aside, no external dependency. Resume by deciding the work is still worth doing. Quiet. |
+| `paused` | **Re-evaluate** | Started but stopped mid-work; needs near-term review. NOT quiet — short (3-day) stale threshold so resume-decisions don't decay. |
 | `awaiting` | **Ask** | Needs a human decision or input. NOT quiet — pings get forgotten, so this status generates stale pressure to chase the answer. |
 | `queued-after` | **Check predecessor** | Sequenced behind another plan; can start once that one ships. Quiet. |
 | `archived` | — | No longer relevant; auto-moved to the archive directory on transition. |
 
-Each *quiet* status (`partial`, `paused`, `queued-after`, `archived`) is exempt from stale-warning pressure but still appears in active scope and metrics — quietness is a presentation flag, not a closure flag. `awaiting` deliberately stays loud so unanswered questions don't decay into invisible backlog.
+Each *quiet* status (`partial`, `queued-after`, `archived`) is exempt from stale-warning pressure but still appears in active scope and metrics — quietness is a presentation flag, not a closure flag. `awaiting` and `paused` deliberately stay loud so unanswered questions and stalled mid-flight work don't decay into invisible backlog.
 
 > **Heads-up:** versions before 0.15 included a `done` plan status in the defaults. It saw effectively zero real-world use (plans went `in-session`/`active` → `archived` directly), so it was dropped from the built-in vocabulary. To finish a plan, run `dotmd archive <plan-file>` — or, if you preferred the previous behavior, add `done` back via the `types.plan.statuses` key in your config.
 
@@ -402,6 +402,62 @@ dotmd finish docs/plans/my-plan.md       # set done + bump date
 dotmd finish docs/plans/my-plan.md active  # back to active for more work
 ```
 
+### Session leases & unpickup
+
+`dotmd pickup` records a lease at `<repoRoot>/.dotmd/in-session.json` that
+identifies which Claude session owns the plan. The lease enables three
+distinct outcomes when a plan is already `in-session`:
+
+- **Same session re-attach.** A fresh `dotmd pickup` of a plan you already
+  hold (e.g., after `/clear` or auto-compaction) silently re-attaches and
+  re-prints the body. No conflict.
+- **Cross-session conflict.** If another live session holds the plan,
+  pickup refuses with `Held by <host>/<session> (pid <pid>) since <time>`.
+- **Stale lease.** If the holder's pid is dead (or the lease is >24h old),
+  pickup refuses but suggests `--takeover`.
+
+Releasing leases:
+
+```bash
+dotmd unpickup                    # release every lease owned by current session
+dotmd unpickup docs/plans/foo.md  # release that one (refuses cross-session)
+dotmd unpickup --to planned       # override target status (default: lease.oldStatus)
+dotmd unpickup --stale            # release leases with dead pid or >24h old
+dotmd unpickup --all              # release every lease (administrative)
+dotmd unpickup --json             # { released: [...], skipped: [...] }
+```
+
+`finish`, `archive`, and `rename` auto-release / migrate the lease, so the
+common closeout paths are covered without ceremony.
+
+**Session id resolution** (in order, first wins):
+
+1. `$CLAUDE_CODE_SESSION_ID` (set by Claude Code in Bash subprocess env)
+2. `$CLAUDE_SESSION_ID` (legacy alias)
+3. `$TERM_SESSION_ID` (macOS Terminal/iTerm — stable per window)
+4. `shell:<user>@<host>` (last-resort coarse fallback)
+
+The session id survives `/clear` and auto-compaction, so a re-attach after
+either is silent.
+
+**Auto-release on Claude Code session end** — add this to
+`~/.claude/settings.json`:
+
+```json
+{
+  "SessionEnd": [
+    { "type": "command", "command": "dotmd unpickup", "timeout": 10 }
+  ]
+}
+```
+
+When the Claude Code session ends, the hook runs `dotmd unpickup` with
+`$CLAUDE_CODE_SESSION_ID` in the environment, releasing every lease for
+that session and flipping plans back to their prior status.
+
+`dotmd briefing` surfaces a `Stuck in-session: N` line when stale leases
+exist, with a `dotmd unpickup --stale` suggestion.
+
 ### Touch
 
 ```bash

package/bin/dotmd.mjs

@@ -41,7 +41,8 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
-  pickup <file>                     Pick up a plan (set in-session + print)
+  pickup <file> [--takeover]        Pick up a plan (set in-session + print)
+  unpickup [<file>] [--to <s>]      Release in-session lease (default: all owned by current session)
   finish <file> [done|active]       Finish a plan (set done or active)
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
@@ -115,15 +116,44 @@ Filters:
 
   pickup: `dotmd pickup <file> — pick up a plan and start working
 
-Sets the plan to in-session and prints its content.
-Fails if the plan is already in-session, blocked, done, or archived.
+Sets the plan to in-session and prints its content. Writes a session
+lease to <repoRoot>/.dotmd/in-session.json so the same Claude session
+can re-attach silently after compaction or /clear.
+
+If a plan is already in-session:
+- Same session → silent re-attach (prints body, no error).
+- Different session, live pid → refuses with "Held by …" message.
+- Different session, dead pid or >24h old → suggests --takeover.
 
 Options:
+  --takeover             Force-claim a plan held by another session
   --json                 Output as JSON
   --dry-run, -n          Preview without writing
 
 If no file is given, prompts with a list of active plans.`,
 
+  unpickup: `dotmd unpickup [<file>] — release a plan from in-session
+
+With no file: releases every lease owned by the current session.
+This is the form intended for a Claude Code SessionEnd hook.
+
+With <file>: releases that one. Refuses if held by another session
+(use --force to override).
+
+Flips the plan's frontmatter status from in-session back to its
+prior status (recorded by pickup), or whatever --to specifies.
+
+Options:
+  --to <status>          Override target status (default: lease.oldStatus → fallback active)
+  --all                  Release every lease in the file (administrative)
+  --stale                Release leases whose pid is dead or age >24h
+  --force                Override "not yours" refusal on a specific file
+  --json                 Output as JSON ({ released, skipped })
+  --dry-run, -n          Preview without writing
+
+Manual-edit fallback: if the plan's status is in-session but no lease
+exists, --to <status> flips it anyway with a warning.`,
+
   finish: `dotmd finish <file> [done|active] — finish working on a plan
 
 Sets the plan status to done (default) or back to active.
@@ -606,6 +636,7 @@ async function main() {
 
   // Lifecycle commands
   if (command === 'pickup') { const { runPickup } = await import('../src/lifecycle.mjs'); await runPickup(restArgs, config, { dryRun }); return; }
+  if (command === 'unpickup') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
   if (command === 'finish') { const { runFinish } = await import('../src/lifecycle.mjs'); await runFinish(restArgs, config, { dryRun }); return; }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }

package/dotmd.config.example.mjs

@@ -50,7 +50,7 @@ export const excludeDirs = ['evidence'];
 //       'planned':      { context: 'listed', staleDays: 30, requiresModule: true },
 //       'blocked':      { context: 'listed', staleDays: 30, requiresModule: true },
 //       'partial':      { context: 'expanded', requiresModule: true, quiet: true },     // shipped + deferred tail; visible, no nagging
-//       'paused':       { context: 'listed', requiresModule: true, quiet: true },       // intentionally set aside, no external dep
+//       'paused':       { context: 'listed', staleDays: 3, requiresModule: true },      // stopped mid-work, near-term review — loud (short stale threshold)
 //       'awaiting':     { context: 'listed', staleDays: 14, requiresModule: true },     // human input/decision wait — NOT quiet (pings get forgotten)
 //       'queued-after': { context: 'counted', requiresModule: true, quiet: true },      // sequenced behind another plan
 //       'archived':     { context: 'counted', archive: true, terminal: true, quiet: true },

package/package.json

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

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -33,7 +33,8 @@ const COMMAND_FLAGS = {
   stale: ['--json', '--sort', '--limit', '--all'],
   actionable: ['--json', '--sort', '--limit', '--all'],
   briefing: ['--json'],
-  pickup: ['--json'],
+  pickup: ['--json', '--takeover'],
+  unpickup: ['--json', '--all', '--stale', '--to', '--force'],
   finish: ['--json'],
   status: [],
   archive: [],

package/src/config.mjs

@@ -28,7 +28,7 @@ const DEFAULTS = {
         listed: ['planned', 'blocked', 'paused', 'awaiting'],
         counted: ['queued-after', 'archived'],
       },
-      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, awaiting: 14 },
+      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, paused: 3, awaiting: 14 },
     },
     doc: {
       statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
@@ -55,8 +55,8 @@ const DEFAULTS = {
 
   lifecycle: {
     archiveStatuses: ['archived'],
-    skipStaleFor: ['archived', 'reference', 'partial', 'paused', 'queued-after'],
-    skipWarningsFor: ['archived', 'partial', 'paused', 'queued-after'],
+    skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
+    skipWarningsFor: ['archived', 'partial', 'queued-after'],
     terminalStatuses: ['archived', 'deprecated', 'reference'],
   },
 

package/src/init.mjs

@@ -139,6 +139,24 @@ export function runInit(cwd, config) {
     process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
   }
 
+  // .gitignore: ensure .dotmd/ is ignored (session leases live there)
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const ignoreLine = '.dotmd/';
+  if (existsSync(gitignorePath)) {
+    const current = readFileSync(gitignorePath, 'utf8');
+    const has = current.split('\n').some(l => l.trim() === ignoreLine || l.trim() === '.dotmd');
+    if (!has) {
+      const sep = current.endsWith('\n') ? '' : '\n';
+      writeFileSync(gitignorePath, `${current}${sep}${ignoreLine}\n`, 'utf8');
+      process.stdout.write(`  ${green('update')}  .gitignore (+${ignoreLine})\n`);
+    } else {
+      process.stdout.write(`  ${dim('exists')}  .gitignore\n`);
+    }
+  } else {
+    writeFileSync(gitignorePath, `${ignoreLine}\n`, 'utf8');
+    process.stdout.write(`  ${green('create')}  .gitignore\n`);
+  }
+
   // Claude Code integration — auto-detect .claude/ directory
   if (config) {
     const results = scaffoldClaudeCommands(cwd, config);

package/src/lease.mjs

@@ -0,0 +1,221 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, openSync, closeSync, unlinkSync, statSync, renameSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { warn } from './util.mjs';
+
+const LEASE_DIR = '.dotmd';
+const LEASE_FILE = 'in-session.json';
+const LOCK_FILE = 'in-session.lock';
+const LOCK_STALE_MS = 5_000;
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_WAIT_MS = 2_000;
+const STALE_LEASE_AGE_MS = 24 * 60 * 60 * 1000;
+
+const _sleepBuf = new Int32Array(new SharedArrayBuffer(4));
+function syncSleep(ms) { Atomics.wait(_sleepBuf, 0, 0, ms); }
+
+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()}`;
+}
+
+function dirFor(config) { return path.join(config.repoRoot, LEASE_DIR); }
+function leaseFilePath(config) { return path.join(dirFor(config), LEASE_FILE); }
+function lockFilePath(config) { return path.join(dirFor(config), LOCK_FILE); }
+
+export function readLeases(config) {
+  const file = leaseFilePath(config);
+  if (!existsSync(file)) return {};
+  try {
+    const raw = readFileSync(file, 'utf8');
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    return {};
+  } catch (err) {
+    warn(`Lease file at ${file} is corrupt (${err.message}); treating as empty.`);
+    return {};
+  }
+}
+
+export function writeLeases(config, leases) {
+  const dir = dirFor(config);
+  mkdirSync(dir, { recursive: true });
+  const file = leaseFilePath(config);
+  if (Object.keys(leases).length === 0) {
+    if (existsSync(file)) {
+      try { unlinkSync(file); } catch {}
+    }
+    return;
+  }
+  const tmp = `${file}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  writeFileSync(tmp, JSON.stringify(leases, null, 2) + '\n', 'utf8');
+  renameSync(tmp, file);
+}
+
+export function withLeaseLock(config, fn) {
+  const dir = dirFor(config);
+  mkdirSync(dir, { recursive: true });
+  const lock = lockFilePath(config);
+  const start = Date.now();
+  let fd = null;
+  while (true) {
+    try {
+      fd = openSync(lock, 'wx');
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const st = statSync(lock);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+          try { unlinkSync(lock); } catch {}
+          continue;
+        }
+      } catch {}
+      if (Date.now() - start > LOCK_MAX_WAIT_MS) {
+        throw new Error(`Could not acquire lease lock at ${lock} within ${LOCK_MAX_WAIT_MS}ms`);
+      }
+      syncSleep(LOCK_RETRY_MS);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { closeSync(fd); } catch {}
+    try { unlinkSync(lock); } catch {}
+  }
+}
+
+export function isPidAlive(pid, host) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (host && host !== os.hostname()) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+export function isLeaseStale(lease) {
+  const t = new Date(lease.pickedUpAt).getTime();
+  if (Number.isNaN(t)) return true;
+  return Date.now() - t > STALE_LEASE_AGE_MS;
+  // Note: pid liveness is intentionally NOT used here. dotmd's own CLI pid is
+  // dead the moment the process exits, so it's not a useful signal for "is the
+  // session that wrote this lease still active." Use age and explicit takeover.
+}
+
+export function findStaleLeases(config) {
+  const leases = readLeases(config);
+  return Object.values(leases).filter(isLeaseStale);
+}
+
+export function acquireLease(config, repoPath, oldStatus, opts = {}) {
+  return withLeaseLock(config, () => {
+    const leases = readLeases(config);
+    const existing = leases[repoPath];
+    const session = opts.session ?? currentSessionId();
+
+    if (existing && existing.session === session) {
+      existing.pickedUpAt = new Date().toISOString();
+      existing.pid = process.pid;
+      leases[repoPath] = existing;
+      writeLeases(config, leases);
+      return { outcome: 'reattached', lease: existing, conflict: null };
+    }
+
+    if (existing && !opts.takeover) {
+      const ageMs = Date.now() - new Date(existing.pickedUpAt).getTime();
+      const stale = Number.isNaN(ageMs) || ageMs > STALE_LEASE_AGE_MS;
+      return {
+        outcome: stale ? 'conflict-stale' : 'conflict-alive',
+        conflict: existing,
+        lease: null,
+      };
+    }
+
+    const newLease = {
+      path: repoPath,
+      oldStatus: oldStatus ?? 'active',
+      pid: process.pid,
+      host: os.hostname(),
+      session,
+      pickedUpAt: new Date().toISOString(),
+    };
+    if (existing && opts.takeover) {
+      newLease.takenOverFrom = {
+        session: existing.session,
+        pid: existing.pid,
+        pickedUpAt: existing.pickedUpAt,
+      };
+    }
+    leases[repoPath] = newLease;
+    writeLeases(config, leases);
+    return { outcome: existing ? 'taken-over' : 'acquired', lease: newLease, conflict: existing ?? null };
+  });
+}
+
+export function releaseLease(config, repoPath, opts = {}) {
+  return withLeaseLock(config, () => {
+    const leases = readLeases(config);
+    const existing = leases[repoPath];
+    if (!existing) return { released: false, lease: null, reason: 'no-lease' };
+    const session = opts.session ?? currentSessionId();
+    if (existing.session !== session && !opts.force) {
+      return { released: false, lease: existing, reason: 'not-yours' };
+    }
+    delete leases[repoPath];
+    writeLeases(config, leases);
+    return { released: true, lease: existing, reason: null };
+  });
+}
+
+export function releaseAllForSession(config, sessionId, opts = {}) {
+  return withLeaseLock(config, () => {
+    const leases = readLeases(config);
+    const released = [];
+    for (const [key, lease] of Object.entries(leases)) {
+      if (lease.session === sessionId) {
+        released.push(lease);
+        delete leases[key];
+      }
+    }
+    if (released.length > 0) writeLeases(config, leases);
+    return { released };
+  });
+}
+
+export function releaseStale(config) {
+  return withLeaseLock(config, () => {
+    const leases = readLeases(config);
+    const released = [];
+    for (const [key, lease] of Object.entries(leases)) {
+      if (isLeaseStale(lease)) {
+        released.push(lease);
+        delete leases[key];
+      }
+    }
+    if (released.length > 0) writeLeases(config, leases);
+    return { released };
+  });
+}
+
+export function migrateLease(config, oldPath, newPath) {
+  return withLeaseLock(config, () => {
+    const leases = readLeases(config);
+    if (!leases[oldPath]) return false;
+    const lease = leases[oldPath];
+    lease.path = newPath;
+    leases[newPath] = lease;
+    delete leases[oldPath];
+    writeLeases(config, leases);
+    return true;
+  });
+}
+
+export function leasePathFor(config) {
+  return leaseFilePath(config);
+}

package/src/lifecycle.mjs

@@ -7,6 +7,15 @@ import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { isInteractive, promptChoice } from './prompt.mjs';
+import {
+  acquireLease,
+  releaseLease,
+  releaseAllForSession,
+  releaseStale,
+  readLeases,
+  currentSessionId,
+  migrateLease,
+} from './lease.mjs';
 
 function findFileRoot(filePath, config) {
   const roots = config.docsRoots || [config.docsRoot];
@@ -124,6 +133,7 @@ export async function runStatus(argv, config, opts = {}) {
 export async function runPickup(argv, config, opts = {}) {
   const { dryRun } = opts;
   const json = argv.includes('--json');
+  const takeover = argv.includes('--takeover');
   let input = argv.find(a => !a.startsWith('-'));
 
   // Interactive: pick from active plans
@@ -152,32 +162,200 @@ export async function runPickup(argv, config, opts = {}) {
 
   if (docType && docType !== 'plan') warn(`${repoPath} has type '${docType}', not 'plan'.`);
 
-  if (oldStatus === 'in-session') die(`Already in-session — another Claude instance may be working on this.\n  ${repoPath}`);
   if (oldStatus === 'blocked') {
     const blockers = parsedFm.blockers ? (Array.isArray(parsedFm.blockers) ? parsedFm.blockers.join(', ') : String(parsedFm.blockers)) : 'unknown';
     die(`Plan is blocked: ${blockers}\n  ${repoPath}`);
   }
-  const pickupable = new Set(['active', 'planned']);
+
+  // 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 pick up a plan with status '${oldStatus}'. Must be active or planned.\n  ${repoPath}`);
 
   const today = new Date().toISOString().slice(0, 10);
+  const leaseOldStatus = oldStatus === 'in-session' ? 'active' : (oldStatus ?? 'active');
+  let leaseOutcome = 'acquired';
 
   if (dryRun) {
-    process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
+    if (oldStatus === 'in-session') {
+      process.stderr.write(`${dim('[dry-run]')} Would acquire lease (status already in-session)\n`);
+    } else {
+      process.stderr.write(`${dim('[dry-run]')} Would update: status: ${oldStatus} → in-session, updated: ${today}\n`);
+    }
   } else {
-    updateFrontmatter(filePath, { status: 'in-session', updated: today });
+    const result = acquireLease(config, repoPath, leaseOldStatus, { takeover });
+    leaseOutcome = result.outcome;
+    if (result.outcome === 'conflict-alive') {
+      const c = result.conflict;
+      die(`Held by ${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(`Stale in-session lease from ${c.host}/${c.session} since ${c.pickedUpAt} (>24h old).\nUse --takeover to claim.\n  ${repoPath}`);
+    }
+    if (oldStatus !== 'in-session') {
+      updateFrontmatter(filePath, { status: 'in-session', updated: today });
+    }
   }
 
   if (json) {
-    process.stdout.write(JSON.stringify({ path: repoPath, oldStatus, newStatus: 'in-session', title, body: body?.trim() ?? '' }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({
+      path: repoPath, oldStatus, newStatus: 'in-session', title,
+      reattached: leaseOutcome === 'reattached',
+      takenOver: leaseOutcome === 'taken-over',
+      body: body?.trim() ?? '',
+    }, null, 2) + '\n');
   } else {
-    process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus} → in-session)\n\n`);
+    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`);
+    }
     if (body?.trim()) process.stdout.write(body.trim() + '\n');
   }
 
   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 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 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 = new Date().toISOString().slice(0, 10);
+        updateFrontmatter(filePath, { status: newStatus, updated: today });
+      }
+      // 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 => {
+        const age = Date.now() - new Date(l.pickedUpAt).getTime();
+        return Number.isNaN(age) || age > 24 * 60 * 60 * 1000;
+      });
+      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 {
+    if (targets.length === 0 && !json) {
+      process.stderr.write(`No leases to release${fileArg ? ` for ${fileArg}` : ` for session ${session}`}.\n`);
+    }
+    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`);
+    }
+  }
+}
+
 export async function runFinish(argv, config, opts = {}) {
   const { dryRun } = opts;
   const json = argv.includes('--json');
@@ -230,6 +408,10 @@ export async function runFinish(argv, config, opts = {}) {
     process.stdout.write(`${green('✓ Finished')}: ${repoPath} (in-session → ${targetStatus})\n`);
   }
 
+  if (!dryRun) {
+    try { releaseLease(config, repoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${repoPath}: ${err.message}`); }
+  }
+
   try { config.hooks.onFinish?.({ path: repoPath, oldStatus, newStatus: targetStatus }); } catch (err) { warn(`Hook 'onFinish' threw: ${err.message}`); }
 }
 
@@ -296,6 +478,8 @@ export function runArchive(argv, config, opts = {}) {
   if (updatedRefCount > 0) process.stdout.write(`Updated references in ${updatedRefCount} file(s).\n`);
   if (config.indexPath) process.stdout.write('Index regenerated.\n');
 
+  try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }
+
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
 }
 

package/src/rename.mjs

@@ -1,6 +1,7 @@
 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 { gitMv } from './git.mjs';
 import { green, dim } from './color.mjs';
@@ -98,6 +99,8 @@ export async function runRename(argv, config, opts = {}) {
     }
   }
 
+  try { migrateLease(config, oldRepoPath, newRepoPath); } catch (err) { warn(`Could not migrate lease ${oldRepoPath} → ${newRepoPath}: ${err.message}`); }
+
   process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (updatedCount > 0) {
     process.stdout.write(`Updated references in ${updatedCount} file(s).\n`);

package/src/render.mjs

@@ -4,6 +4,7 @@ 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';
 
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
@@ -297,6 +298,13 @@ export function renderBriefing(index, config) {
   const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
   lines.push(`Stale: ${stale} | Errors: ${index.errors.length} | Warnings: ${index.warnings.length}`);
 
+  try {
+    const staleLeases = findStaleLeases(config);
+    if (staleLeases.length > 0) {
+      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>1d or dead pid, run \`dotmd unpickup --stale\`)`));
+    }
+  } catch {}
+
   return lines.join('\n') + '\n';
 }