runlist 0.99.2 → 0.100.0

package/src/guard.mjs

@@ -5,6 +5,8 @@ import { inspectGitCommandPaths } from './git.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { recordGuardEvent } from './journal.mjs';
 import { readEnv } from './naming.mjs';
+import { promptDirectory, promptRouting } from './new.mjs';
+import { isHandoffsMode, managesFile } from './handoffs-scope.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -18,8 +20,8 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 //
 // Two decision levels:
 //   'deny' — block the call and feed the reason back to the model. Reserved for
-//            moves that are guaranteed-wrong: committing a gitignored prompt (it
-//            would fail anyway) and hand-editing a `status:` field (`runlist set`
+//            pending-prompt Git operations under the local policy, and
+//            hand-editing a `status:` field (`runlist set`
 //            is a complete substitute; config `guard: { deny: false }` drops the
 //            status rules back to warn).
 //   'warn' — let the call proceed but inject teaching context so the agent learns
@@ -38,18 +40,37 @@ function toSlash(p) {
 }
 
 // A path that ends in .md and sits under a `prompts/` directory is a
-// session-local saved prompt regardless of which doc root it belongs to —
+// saved prompt regardless of which doc root it belongs to —
 // robust across repos without needing the resolved config. Archived prompts
 // (`…/prompts/archived/…`, the default nested archive for the prompt type) are
-// committable history, NOT session-local, so they're explicitly excluded — the
+// committable history, so they are explicitly excluded — the
 // guard must not block committing or reading them.
 function isPromptPath(p, config) {
   const s = toSlash(p);
   if (typeof s !== 'string' || !s.endsWith('.md')) return false;
-  if (!/(^|\/)prompts\//.test(s)) return false;
   const archiveDir = toSlash(config?.archiveDir || 'archived').replace(/^\/+|\/+$/g, '');
   if (archiveDir && s.split('/').includes(archiveDir)) return false;
-  return true;
+  // Where planning is off, a saved prompt is a `type: prompt` file in the
+  // prompt folder and nothing else (src/handoffs-scope.mjs): the user's own
+  // Markdown there is not one.
+  if (isHandoffsMode(config)) return managesFile(path.resolve(config.repoRoot, s), config);
+  if (/(^|\/)prompts\//.test(s)) return true;
+  // Respect a configured prompt location too. When prompts share a whole doc
+  // root, inspect the file's type rather than treating every Markdown doc as a
+  // prompt. Directory routing uses the same resolver as prompt creation.
+  if (!config?.repoRoot || !config.docsRoot) return false;
+  try {
+    // Markdown template-store overrides change content only; routing is owned
+    // by the JS template config. Avoid reading that store on each hook token.
+    const directory = path.resolve(promptDirectory(config, promptRouting(config)));
+    const file = path.resolve(config.repoRoot, s);
+    const relative = path.relative(directory, file);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false;
+    const roots = config.docsRoots ?? [config.docsRoot];
+    if (!roots.some(root => path.resolve(root) === directory)) return true;
+    const { frontmatter } = extractFrontmatter(readFileSync(file, 'utf8'));
+    return Boolean(frontmatter && parseSimpleFrontmatter(frontmatter).type === 'prompt');
+  } catch { return false; }
 }
 
 // Loose "is this a runlist-managed doc" test: a .md file under one of the
@@ -57,6 +78,9 @@ function isPromptPath(p, config) {
 function isManagedDoc(p, config) {
   const s = toSlash(p);
   if (typeof s !== 'string' || !s.endsWith('.md')) return false;
+  // Where planning is off, runlist manages the prompts in the prompt folder
+  // alone, so only their status edits go through `runlist set`.
+  if (isHandoffsMode(config)) return managesFile(path.resolve(config.repoRoot, s), config);
   const roots = config?.docsRoots || (config?.docsRoot ? [config.docsRoot] : ['docs']);
   return roots.some(r => {
     const rNorm = toSlash(r).replace(/\/+$/, '');
@@ -276,22 +300,26 @@ function evalBash(command, config, inspectGitPaths, baseCwd, deps = {}) {
       continue;
     }
 
-    // Rule A — deny only when Git's current state says the command would
+    // Rule A — apply the project's prompt tracking policy only when Git says it would
     // actually include a live prompt. This covers broad forms (`add .`, `-A`,
     // pathless commit, commit -a) without blocking ignored or clean prompts.
     const git = parseGitInvocation(segTokens, cwd);
     if (git) {
       const includedPaths = inspectGitPaths(git.subcommand, git.args, git.cwd);
       const targets = [...new Set(includedPaths.filter(candidate => isPromptPath(candidate, config)))];
-      if (targets.length > 0) {
+      const tracking = config.promptTracking ?? 'local';
+      if (targets.length > 0 && tracking !== 'tracked') {
         return {
-          decision: 'deny',
+          decision: tracking === 'untracked' ? 'warn' : 'deny',
           rule: 'commit-prompt',
           detail: `git ${git.subcommand} ${targets.join(' ')}`,
-          reason:
-            `Saved prompts (${targets.join(', ')}) are session-local runlist artifacts, not source to commit. ` +
-            `Don't git add/commit them — commit your other changes without the prompt in the pathspec. ` +
-            `The next session consumes a prompt with \`runlist use <file>\` (or \`runlist use\` for the oldest pending), which prints the body and archives it atomically.`,
+          reason: tracking === 'untracked'
+            ? `This project's promptTracking is untracked: leaving pending prompts (${targets.join(', ')}) out of commits is recommended to reduce commit churn. ` +
+              `Untracked does not mean ignored; broad commands such as \`git add -A\` can include them. ` +
+              `Choose files explicitly, or use \`runlist config set promptTracking tracked\` if the project wants to commit prompts.`
+            : `This project's promptTracking is local (the legacy default for existing configs). ` +
+              `Exclude pending prompts (${targets.join(', ')}) from this Git operation. ` +
+              `Inspect the policy with \`runlist config get promptTracking\`; explicitly choose tracked to allow prompt commits, or untracked for advisory warnings.`,
         };
       }
     }

package/src/handoff-record.mjs

@@ -1,11 +1,17 @@
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { die, nowIso, toRepoPath } from './util.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { replaceFrontmatterField } from './frontmatter-fix.mjs';
+import { renderLifecycleMutation } from './lifecycle.mjs';
+import { mutateFile, withPathLocks } from './atomic-mutation.mjs';
+import { commitRename } from './durable-rename.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import { DotmdError, die, isArchivedPath, nowIso, shellQuote, toRepoPath } from './util.mjs';
 import { stateDir } from './naming.mjs';
-import { resolveDocArg } from './index.mjs';
+import { docArgMissMessage, resolveDocArg } from './index.mjs';
 import { authoritativeSessionId } from './pickup.mjs';
-import { green } from './color.mjs';
+import { dim, green } from './color.mjs';
 
 // A baton that releases an in-session plan saves the prompt first, so a usage
 // stop partway through the handoff loses nothing. The plan update that follows
@@ -13,6 +19,7 @@ import { green } from './color.mjs';
 // done, and left next_step saying what it said before the work. So baton leaves
 // a record of the plan's next_step as it stood when the prompt was saved, and
 // `runlist baton --done` reports the handoff done only once next_step differs.
+// `--next-step` writes the new value in the same call.
 // The record is local state under the runlist state directory, one per plan,
 // so a later session (or this one after a compaction) can still confirm it.
 
@@ -20,15 +27,25 @@ function recordsDir(config) {
   return path.join(stateDir(config.repoRoot), 'handoffs');
 }
 
+// Keyed by the plan's whole repo path: two plans sharing a file name in
+// different directories each keep their own record. The hash keeps the name
+// legal on every filesystem; the file name in front is only for a human
+// listing the directory. Records written before this were keyed by the file
+// name alone (`widget.json`); they are still read, and matched by the `plan`
+// they carry, never by their name.
 function recordPath(config, planRepoPath) {
-  return path.join(recordsDir(config), `${path.basename(planRepoPath, '.md')}.json`);
+  const key = createHash('sha256').update(planRepoPath).digest('hex').slice(0, 16);
+  return path.join(recordsDir(config), `${path.basename(planRepoPath, '.md')}-${key}.json`);
 }
 
-function planNextStep(absPath) {
-  const { frontmatter } = extractFrontmatter(readFileSync(absPath, 'utf8'));
-  if (!frontmatter) return { present: false, value: null };
-  const fm = parseSimpleFrontmatter(frontmatter);
-  if (!Object.prototype.hasOwnProperty.call(fm, 'next_step')) return { present: false, value: null };
+function frontmatterOf(content) {
+  const { frontmatter } = extractFrontmatter(content);
+  return frontmatter ? parseSimpleFrontmatter(frontmatter) : null;
+}
+
+function nextStepOf(content) {
+  const fm = frontmatterOf(content);
+  if (!fm || !Object.prototype.hasOwnProperty.call(fm, 'next_step')) return { present: false, value: null };
   return { present: true, value: JSON.stringify(fm.next_step ?? null) };
 }
 
@@ -36,10 +53,13 @@ function planNextStep(absPath) {
 // the record when the plan carries a next_step to wait on, else null (a repo
 // whose plans have no next_step field has nothing for --done to check).
 export function recordPendingHandoff(config, { planRepoPath, promptRepoPath, promptName }) {
-  const abs = path.resolve(config.repoRoot, planRepoPath);
-  const { present, value } = planNextStep(abs);
+  const content = readFileSync(path.resolve(config.repoRoot, planRepoPath), 'utf8');
+  const { present, value } = nextStepOf(content);
   if (!present) return null;
+  // `id` names this generation of the record: savedAt has one-second
+  // resolution, so two batons for one plan within a second share it.
   const record = {
+    id: randomUUID(),
     plan: planRepoPath,
     prompt: promptRepoPath,
     name: promptName,
@@ -47,8 +67,20 @@ export function recordPendingHandoff(config, { planRepoPath, promptRepoPath, pro
     nextStep: value,
     sessionId: authoritativeSessionId() ?? null,
   };
+  const file = recordPath(config, planRepoPath);
+  // An older record for this same plan (the name-keyed form) is replaced, not
+  // left beside the new one to be finished separately.
+  const superseded = listPendingHandoffs(config).filter(r => r.plan === planRepoPath && r.recordFile !== file).map(r => r.recordFile);
   mkdirSync(recordsDir(config), { recursive: true });
-  writeFileSync(recordPath(config, planRepoPath), JSON.stringify(record, null, 2) + '\n');
+  // Under the record's lock, like `--done`, so a confirmation that checked
+  // the previous record can never remove this one.
+  withPathLocks([file, ...superseded], { repoRoot: config.repoRoot }, () => {
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(record, null, 2) + '\n');
+    try { commitRename(temp, file); }
+    catch (err) { rmSync(temp, { force: true }); throw err; }
+    for (const stale of superseded) rmSync(stale, { force: true });
+  });
   return record;
 }
 
@@ -69,39 +101,267 @@ export function pendingHandoffsForSession(config, sessionId = authoritativeSessi
   return listPendingHandoffs(config).filter(record => record.sessionId === sessionId);
 }
 
+// The frontmatter half of the update is a flag on --done, so the guidance never
+// asks for a hand edit of next_step: the body is prose the session writes, the
+// two fields are what this verb writes.
 export function handoffNotDoneLine(record, doneCommand = 'runlist baton --done') {
-  return `Handoff not done yet: the prompt is saved, and ${record.plan} still needs bringing up to date (the body, then next_step). Then run \`${doneCommand}\`.`;
+  return `Handoff not done yet: the prompt is saved, and ${record.plan} still needs bringing up to date. Update the plan body first, then run \`${doneCommand} --next-step "<next move>"\` (add \`--current-state "<where it stands>"\` if that changed): it writes the frontmatter and confirms the handoff.`;
+}
+
+// Whitespace runs collapse to one space: that is what the folded scalar the
+// writer emits reads back as, so a value differing only in spacing is the same
+// next_step and must not pass the gate.
+function normalizeFieldValue(value) {
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+// Every completion path compares the same way: a string next_step after
+// whitespace normalisation, anything else (a list, a boolean) as parsed.
+function comparableNextStep(json) {
+  let value;
+  try { value = JSON.parse(json); } catch { return undefined; }
+  return JSON.stringify(typeof value === 'string' ? normalizeFieldValue(value) : value);
+}
+
+function stillAsRecorded(record, content) {
+  const { present, value } = nextStepOf(content);
+  return present && comparableNextStep(value) === comparableNextStep(record.nextStep);
+}
+
+// One line of prose per field. A newline is refused rather than folded away:
+// the writer emits a folded scalar, which would silently join the lines, and a
+// next_step that needs several lines belongs in the plan body.
+function checkedFieldValue(flag, value) {
+  if (typeof value !== 'string' || !value.trim()) die(`${flag} needs a nonempty value, e.g. ${flag} "<text>".`);
+  if (/[\r\n]/.test(value)) die(`${flag} takes one line; put anything longer in the plan body.`);
+  return normalizeFieldValue(value);
+}
+
+function renderFieldUpdates(raw, fields) {
+  const { frontmatter } = extractFrontmatter(raw);
+  if (!frontmatter) throw new Error('the plan has no frontmatter block');
+  let next = frontmatter;
+  for (const [key, value] of Object.entries(fields)) next = replaceFrontmatterField(next, key, value);
+  return renderLifecycleMutation(replaceFrontmatter(raw, next), { updated: nowIso() }, null);
 }
 
-// `runlist baton --done [<plan>]`
-export function runBatonDone(planArg, config, { json = false } = {}) {
+
+function readRecord(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); }
+  catch { return null; }
+}
+
+// Whether the record on disk is still the generation this call read. A record
+// written before ids existed is compared whole.
+function sameGeneration(record, current) {
+  if (!current) return false;
+  if (record.id !== undefined) return current.id === record.id;
+  const { recordFile: _file, ...saved } = record;
+  return JSON.stringify(current) === JSON.stringify(saved);
+}
+
+const isGone = (config, record) => !existsSync(path.resolve(config.repoRoot, record.plan));
+
+function recordLine(config, record) {
+  return `  ${record.plan} (${isGone(config, record) ? 'gone' : 'still in place'}; record ${toRepoPath(record.recordFile, config.repoRoot)}, prompt ${record.name}, saved ${record.savedAt})`;
+}
+
+// Every command printed for a path is quoted, so it runs as shown.
+const doneCommand = repoPath => `runlist baton --done ${shellQuote(repoPath)}`;
+const clearCommand = record => doneCommand(record.plan);
+const ARCHIVE_HINT = 'To archive a plan as part of a handoff, use `runlist baton --status archived`.';
+
+// Whether a gone plan has a copy where `runlist archive` would have put it.
+function archivedCopyExists(config, repoPath) {
+  const abs = path.resolve(config.repoRoot, repoPath);
+  return (config.docsRoots || [config.docsRoot]).some(root => {
+    const rel = path.relative(root, abs);
+    return rel && !rel.startsWith('..') && !path.isAbsolute(rel) && existsSync(path.join(root, config.archiveDir, path.basename(abs)));
+  });
+}
+
+// A plan whose handoff names a path it is no longer at. Writes never follow
+// it: the fields go only to the plan at the path the handoff was saved for.
+function goneMessage(config, record, writing) {
+  const lead = writing
+    ? `${record.plan} is gone (moved or archived?), so nothing was written: --next-step and --current-state write only the plan at the path its handoff was saved for.`
+    : `${record.plan} is gone (moved or archived?).`;
+  const hint = writing && archivedCopyExists(config, record.plan) ? `\n${ARCHIVE_HINT}` : '';
+  return `${lead} Bring the plan up to date where it is now, then run \`runlist baton --done <its new path>\`; or clear this handoff by its old path: \`${clearCommand(record)}\`.${hint}\nSaved prompt: ${record.name}`;
+}
+
+// A named plan finishes the record saved for that exact path. The one
+// exception is plain --done (no fields to write) for a plan that moved after
+// the prompt was saved: when exactly one record shares the file name and its
+// plan is gone, that record is cleared once the plan at the new path has a
+// different next_step. It writes no plan, so the worst a wrong guess does is
+// clear a reminder; anything less certain is refused with the records listed.
+function namedHandoff(config, repoPath, writing) {
+  const records = listPendingHandoffs(config);
+  const exact = records.find(r => r.plan === repoPath);
+  if (exact) return { record: exact, relocated: false };
+  const sameName = records.filter(r => typeof r.plan === 'string' && path.basename(r.plan) === path.basename(repoPath));
+  const moved = sameName.filter(r => isGone(config, r));
+  if (!sameName.length) die(`No handoff waits on ${repoPath}: baton has not saved a prompt for it that needs the plan brought up to date.`);
+  if (!moved.length) die(`No handoff waits on ${repoPath}. The handoff for a plan of the same file name is ${sameName.map(r => r.plan).join(', ')}, which is still in place; finish it there: ${clearCommand(sameName[0])}`);
+  // With several candidates, at most one was saved for this plan, and
+  // clearing it says nothing about whose the others are.
+  const clearOne = `At most one of these was saved for this plan; clear that one by its old path (only its record is removed, the others stay pending):\n${moved.map(r => `  ${clearCommand(r)}`).join('\n')}`;
+  if (writing) {
+    const recover = sameName.length === 1
+      ? `If ${repoPath} is that plan, moved: bring it up to date by any means and run \`${doneCommand(repoPath)}\`, or clear the handoff by its old path: \`${clearCommand(moved[0])}\`.`
+      : clearOne;
+    const hint = isArchivedPath(repoPath, config) ? `\n${ARCHIVE_HINT}` : '';
+    die(`No handoff was saved for ${repoPath}, so nothing was written: --next-step and --current-state write only the plan at the path a handoff was saved for.\n${sameName.map(r => recordLine(config, r)).join('\n')}\n${recover}${hint}`);
+  }
+  if (sameName.length > 1) {
+    die(`No handoff was saved for ${repoPath}, and ${sameName.length} handoffs for plans of that file name could be meant:\n${sameName.map(r => recordLine(config, r)).join('\n')}\n${clearOne}`);
+  }
+  return { record: moved[0], relocated: true };
+}
+
+// `runlist baton --done [<plan>] [--next-step "…"] [--current-state "…"]`
+export function runBatonDone(planArg, config, { json = false, dryRun = false, nextStep = null, currentState = null } = {}) {
+  const fields = {};
+  if (nextStep !== null) fields.next_step = checkedFieldValue('--next-step', nextStep);
+  if (currentState !== null) fields.current_state = checkedFieldValue('--current-state', currentState);
+  const writing = Object.keys(fields).length > 0;
+  if (dryRun && !writing) die('`runlist baton --done` changes nothing but its own record; run it without --dry-run, or preview a write with --next-step.');
+
   let record;
+  let relocated = false;
+  let abs = null;
   if (planArg) {
-    const abs = resolveDocArg(planArg, config);
-    const repoPath = toRepoPath(abs, config.repoRoot);
-    record = listPendingHandoffs(config).find(r => r.plan === repoPath)
-      ?? listPendingHandoffs(config).find(r => path.basename(r.plan) === path.basename(repoPath));
-    if (!record) die(`No handoff waits on ${repoPath}: baton has not saved a prompt for it that needs the plan brought up to date.`);
+    // The argument is first taken as a path, exactly as typed: a record saved
+    // for that path is the handoff meant, whether or not the plan is still
+    // there. Resolving it as a doc first could land on another plan (another
+    // root, a slug, a file name) while the named path is gone.
+    // As for any doc argument, a path typed without `.md` names the file with it.
+    const argRepoPath = toRepoPath(path.resolve(config.repoRoot, planArg), config.repoRoot);
+    const candidates = argRepoPath.endsWith('.md') ? [argRepoPath] : [argRepoPath, `${argRepoPath}.md`];
+    const pending = listPendingHandoffs(config);
+    record = candidates.map(candidate => pending.find(r => r.plan === candidate)).find(Boolean);
+    if (!record) {
+      abs = resolveDocArg(planArg, config, { dieOnMiss: false });
+      if (!abs) die(docArgMissMessage(planArg, config));
+      ({ record, relocated } = namedHandoff(config, toRepoPath(abs, config.repoRoot), writing));
+    }
   } else {
     const mine = pendingHandoffsForSession(config);
     if (mine.length === 0) die('No handoff of this session waits on a plan update. Name the plan: runlist baton --done <plan-file>');
-    if (mine.length > 1) die(`This session has ${mine.length} handoffs waiting; name the plan:\n${mine.map(r => `  runlist baton --done ${r.plan}`).join('\n')}`);
+    if (mine.length > 1) die(`This session has ${mine.length} handoffs waiting; name the plan:\n${mine.map(r => `  ${doneCommand(r.plan)}`).join('\n')}`);
     record = mine[0];
   }
 
-  const abs = path.resolve(config.repoRoot, record.plan);
-  if (!existsSync(abs)) die(`${record.plan} is gone (moved or archived?). Run \`runlist baton --done <its new path>\` once it is up to date.\nSaved prompt: ${record.name}`);
-  const { present, value } = planNextStep(abs);
-  if (present && value === record.nextStep) {
-    die(`Not done: ${record.plan} next_step is the same as when the prompt was saved (${record.savedAt}). Bring the plan up to date (the body, then next_step), then run \`runlist baton --done${planArg ? ` ${record.plan}` : ''}\` again.\nSaved prompt: ${record.name}`);
+  abs ??= path.resolve(config.repoRoot, record.plan);
+  const planGone = !existsSync(abs);
+  // Naming the gone path itself is how a handoff whose plan moved away is
+  // cleared; with fields to write, or with no path named, it is refused.
+  if (planGone && (writing || !planArg)) die(goneMessage(config, record, writing));
+  const planRepoPath = toRepoPath(abs, config.repoRoot);
+  const again = planArg ? doneCommand(planRepoPath) : 'runlist baton --done';
+
+  if (fields.next_step !== undefined && JSON.stringify(fields.next_step) === comparableNextStep(record.nextStep)) {
+    die(`Not done: --next-step repeats the next_step ${planRepoPath} had when the prompt was saved (${record.savedAt}). Write where the work goes from here.\nSaved prompt: ${record.name}`);
+  }
+
+  let source = abs;
+  if (writing) {
+    try { source = authorizeManagedSource(abs, config, { kind: 'Baton --done plan' }).path; }
+    catch (err) { die(err.message); }
   }
-  rmSync(record.recordFile, { force: true });
-  const result = { operation: 'baton-done', plan: record.plan, prompt: record.prompt, name: record.name, nextStepChanged: true };
+
+  const finish = raw => {
+    const next = writing ? renderFieldUpdates(raw, fields) : raw;
+    if (stillAsRecorded(record, next)) {
+      die(`Not done: ${planRepoPath} next_step is the same as when the prompt was saved (${record.savedAt}). Update the plan body first, then run \`${again} --next-step "<next move>"\`.\nSaved prompt: ${record.name}`);
+    }
+    return next;
+  };
+  const failed = err => {
+    if (err instanceof DotmdError) throw err;
+    const verb = planGone ? 'clear the handoff for' : writing ? 'write' : 'check';
+    die(`Could not ${verb} ${planRepoPath} (${err.message}); the handoff is still pending.\nSaved prompt: ${record.name}`);
+  };
+  // Checked under the record's lock, before any plan write is published and
+  // before the record is removed: a baton that saved a newer record for this
+  // plan meanwhile is never finished by a call that read the older one.
+  const current = () => {
+    if (!sameGeneration(record, readRecord(record.recordFile))) {
+      die(`The handoff record for ${record.plan} changed while this ran (a new baton, or another --done); run \`${again}\` again.\nSaved prompt: ${record.name}`);
+    }
+  };
+
+  let preview = null;
+  if (dryRun) {
+    try { preview = finish(readFileSync(source, 'utf8')); } catch (err) { failed(err); }
+  } else {
+    try {
+      if (planGone || relocated) {
+        // No plan is written, so no plan is locked: a relocated plan is read
+        // the way any reader would, and the old path is not touched at all.
+        if (relocated) finish(readFileSync(source, 'utf8'));
+        withPathLocks([record.recordFile], { repoRoot: config.repoRoot }, () => {
+          current();
+          // The saved path was gone when this started; a restore since then
+          // (`set active` on the archived copy) brings the plan back as it
+          // was, and that handoff is finished there, not cleared.
+          if (existsSync(path.resolve(config.repoRoot, record.plan))) {
+            die(`${record.plan} is back at the path its handoff was saved for, so the handoff was not cleared. Finish it there: \`${clearCommand(record)}\` once the plan is up to date.\nSaved prompt: ${record.name}`);
+          }
+          rmSync(record.recordFile, { force: true });
+        });
+      } else {
+        // One sorted lock set, record and plan, so the verdict is reached on
+        // the plan as it stands while the record cannot change: a refused call
+        // publishes nothing, and the record goes only after the plan passed.
+        // No other caller holds a plan lock while it takes a record lock
+        // (baton records after its plan transaction releases). Like baton
+        // itself, this leaves the shared generated index deferred.
+        withPathLocks([record.recordFile, source], { repoRoot: config.repoRoot }, () => {
+          current();
+          mutateFile(source, { repoRoot: config.repoRoot, locked: true }, finish);
+          rmSync(record.recordFile, { force: true });
+        });
+      }
+    } catch (err) { failed(err); }
+  }
+
+  const result = {
+    operation: 'baton-done',
+    dryRun: Boolean(dryRun),
+    plan: planRepoPath,
+    prompt: record.prompt,
+    name: record.name,
+    nextStepChanged: !planGone,
+    planGone,
+    written: fields,
+  };
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     return result;
   }
-  process.stderr.write(`${green('✓ Handoff done')}: ${record.plan} next_step was updated after the prompt was saved.\n`);
+  if (dryRun) {
+    const prefix = dim('[dry-run] ');
+    process.stderr.write(`${prefix}Would write ${planRepoPath}:\n`);
+    const { frontmatter } = extractFrontmatter(preview);
+    const lines = frontmatter.split('\n');
+    for (const key of Object.keys(fields)) {
+      const at = lines.findIndex(line => line.startsWith(`${key}:`));
+      for (let i = at; i >= 0 && i < lines.length && (i === at || /^[ \t]/.test(lines[i])); i++) process.stderr.write(`${prefix}  ${lines[i]}\n`);
+    }
+    process.stderr.write(`${prefix}Would report the handoff done and remove its record.\n`);
+    process.stderr.write(`Saved prompt: ${record.name}\n`);
+    return result;
+  }
+  if (planGone) {
+    process.stderr.write(`${green('✓ Handoff cleared')}: ${planRepoPath} is gone, so there is no plan to update there; its record is removed.\n`);
+    const others = listPendingHandoffs(config).filter(r => typeof r.plan === 'string' && path.basename(r.plan) === path.basename(planRepoPath));
+    if (others.length) process.stderr.write(`Still pending, each for its own saved path: ${others.map(r => r.plan).join(', ')}.\n`);
+  } else {
+    const how = writing ? `${Object.keys(fields).join(' and ')} written` : 'next_step was updated after the prompt was saved';
+    process.stderr.write(`${green('✓ Handoff done')}: ${planRepoPath} ${how}.\n`);
+  }
   process.stderr.write(`Saved prompt: ${record.name}\n`);
   return result;
 }

package/src/handoffs-help.mjs

@@ -0,0 +1,143 @@
+// Per-command help where planning is off (a handoffs-only project,
+// src/handoffs-mode.mjs), for the commands that still work there but whose
+// usual help describes plans. `runlist help <cmd>` and `runlist <cmd> --help`
+// both read this through the dispatcher's one help renderer. A planning
+// command's help there is the planning-off line itself.
+
+const OFF = '(planning is off in this project)';
+const SETUP = '`runlist setup` turns it on (your prompts stay where they are).';
+
+const HELP = {
+  baton: `runlist baton — save a resume prompt for the next session ${OFF}
+
+Usage (write the resume to a file first):
+  runlist baton <slug> @/tmp/draft.md   # saves resume-<slug> in docs/prompts/
+  The resume can also come from stdin (\`-\`, or a pipe) or --message "..." for one-liners.
+  Baton prints the prompt name it saved as its last line.
+
+The resume (10–20 lines): the next concrete decision plus any gotchas, and the
+paths it concerns — not a recap. The next session's hud lists the prompt and
+\`runlist use <name>\` resumes it. When a handoff for the same work is already
+pending, baton saves nothing and names it: inspect it with
+\`runlist prompts show <name>\`, then pass --replace to refresh its text.
+
+Options:
+  --message / --body     Inline body (one-liners; prefer @path or stdin)
+  --subagent             Save subagent-<name> instead of resume-<name>
+  --parent <resume-name>  Group this --subagent handoff under its parent in prompts listings
+  --template             Print a resume draft (or --subagent draft)
+  --replace              Replace exactly one pending handoff; archive its prior text
+  --json                 Structured result
+  --dry-run, -n          Preview without writing
+
+Examples:
+  runlist baton --template > /tmp/resume.md
+  runlist baton checkout-fixes @/tmp/draft.md
+  runlist baton checkout-fixes @/tmp/new-draft.md --replace
+  runlist baton --subagent totals-review --parent resume-checkout-fixes @/tmp/child.md
+
+Handing off a plan comes with planning; ${SETUP}`,
+
+  new: `runlist new prompt <name> [body] — save a prompt under a name of its own ${OFF}
+
+The prompt lands in docs/prompts/<name>.md as pending; the next session's hud
+lists it and \`runlist use <name>\` resumes it. A name with a folder in it must
+stay inside docs/prompts/.
+
+Body: @<file> (preferred for more than one line), - (stdin), --message "...",
+or inline for one-liners.
+
+Options:
+  --title "..."          Title (default: from the name)
+  --message / --body     Inline body
+  --dry-run, -n          Preview without writing
+
+Examples:
+  runlist new prompt look-at-retries @/tmp/draft.md
+  runlist new prompt cleanup --message "look at the remaining lint warnings"
+
+Plans and docs come with planning; ${SETUP}`,
+
+  set: `runlist set <status> <prompt> — change a saved prompt's status ${OFF}
+
+A prompt is pending (waiting for a session) or archived (consumed or set
+aside). \`runlist set archived <prompt>\` sets one aside, as
+\`runlist prompts archive <prompt>\` does.
+
+Options:
+  --dry-run, -n          Preview without writing
+
+Plan statuses come with planning; ${SETUP}`,
+
+  status: `runlist status <prompt> <status> — deprecated; use \`runlist set <status> <prompt>\` ${OFF}
+
+A prompt is pending or archived. Plan statuses come with planning; ${SETUP}`,
+
+  statuses: `runlist statuses — the prompt statuses ${OFF}
+
+  runlist statuses                  Table of the prompt statuses and their flags
+  runlist statuses list --json      The same as JSON
+  runlist statuses add|set|remove <name> --type prompt
+                                    Edit the prompt statuses in runlist.config.mjs
+
+Plan and doc statuses come with planning; ${SETUP}`,
+
+  archive: `runlist archive <prompt> — set a saved prompt aside without reading it ${OFF}
+
+Sets the prompt to archived and moves it to docs/prompts/archived/, as
+\`runlist prompts archive <prompt>\` does. <prompt> is a path or a name.
+
+Options:
+  --dry-run, -n          Preview without writing`,
+
+  prompts: `runlist prompts — saved prompts ${OFF}
+
+Prompts are the handoffs runlist keeps in docs/prompts/. Consuming one prints
+its body and archives it (one-shot). Only an agent session consumes; in a plain
+terminal \`use\` and \`next\` print the body and the command the session runs.
+
+Subcommands:
+  list                       List pending prompts (default)
+  next                       Consume the oldest pending prompt
+  use <name>                 Consume a named prompt (\`resume\` is an alias)
+  show <name...>             Read prompts without consuming them (\`peek\` is an alias)
+  archive <name>             Set a prompt aside without reading it
+  link <child...> --parent <resume-name>
+                             Attach existing child handoffs to their parent
+  new <slug> [body]          Save a prompt (\`runlist new prompt <slug>\`)
+
+A prompt is pending or archived.
+
+Examples:
+  runlist prompts                     # pending prompts
+  runlist prompts show resume-foo     # peek without consuming
+  runlist prompts show a b c          # peek several by name
+  runlist prompts use resume-foo      # in a session: consume it
+  runlist prompts archive old-thing   # set one aside`,
+
+  briefing: `runlist briefing — the check counts ${OFF}
+
+Shows the stale, error and warning counts, then says planning is off;
+\`runlist prompts\` lists the saved prompts. Plan pipelines come with
+planning; ${SETUP}
+
+Options:
+  --json                 Output as JSON`,
+
+  hud: `runlist hud — what a new session is told at startup ${OFF}
+
+Prints the pending prompts, saying to resume one only when asked
+(\`runlist use <name>\`), and actionable notices; silent when nothing needs
+attention. --prompt-submit reads a hook JSON payload from stdin: save requests
+get baton instructions; pickup requests get a hint only when prompts are
+pending. Text hooks read prompt frontmatter without building the index.
+
+Options:
+  --prompt-submit        Request-specific save/pickup hint (hook JSON on stdin)
+  --subagent             Compact workflow primer for child agents
+  --json                 Output as JSON`,
+};
+
+export function handoffsCommandHelp(command) {
+  return HELP[command] ?? null;
+}