runlist 0.99.1 → 0.100.0

package/src/atomic-mutation.mjs

@@ -286,7 +286,7 @@ function validateTransactionArtifact(candidate, directory, label) {
 function validateParticipantPath(participant, repoRoot, options, label) {
   if (!participant || typeof participant.path !== 'string' || !path.isAbsolute(participant.path)
     || !['managed', 'generated'].includes(participant.policy)
-    || !['source', 'target', 'referrer', 'ownership', 'creation', 'deletion'].includes(participant.label)) {
+    || !['source', 'target', 'referrer', 'ownership', 'handoff', 'creation', 'deletion'].includes(participant.label)) {
     throw new MutationConflictError(`Invalid transaction participant ${label}.`);
   }
   const txRoot = transactionRoot(repoRoot, options);
@@ -295,11 +295,27 @@ function validateParticipantPath(participant, repoRoot, options, label) {
     throw new MutationConflictError(`Transaction participant targets transaction/lock state: ${participant.path}`);
   }
   if (participant.policy === 'managed' && options.config) {
-    if (existsSync(participant.path)) authorizeManagedSource(participant.path, options.config, { kind: 'Transaction participant' });
-    else authorizeManagedDestination(participant.path, options.config, { kind: 'Transaction participant' });
+    try {
+      if (existsSync(participant.path)) authorizeManagedSource(participant.path, options.config, { kind: 'Transaction participant' });
+      else authorizeManagedDestination(participant.path, options.config, { kind: 'Transaction participant', recovery: true });
+    } catch (err) {
+      // A handoffs-only project manages its prompt folder alone, so a move
+      // reaching past it is the carry `runlist setup` makes when it turns
+      // planning on, stopped part-way; setup finishes it under its own roots.
+      if (options.config.mode === 'handoffs') err.message += '\n`runlist setup` stopped part-way through turning planning on here; run `runlist setup --yes` to finish the upgrade.';
+      throw err;
+    }
   } else {
     const authorized = safeGeneratedPath(participant.path, repoRoot, options, 'Transaction generated participant');
     if (options.config) {
+      // Setup carries the saved prompt/plan paths in pending handoffs in the
+      // same transaction as the document. Keep this permission as narrow as
+      // ownership state; arbitrary generated repository files remain refused.
+      if (participant.label === 'handoff') {
+        const root = path.join(stateDir(repoRoot), 'handoffs');
+        if (path.dirname(authorized) !== root || !authorized.endsWith('.json')) throw new MutationConflictError(`Generated handoff participant is outside handoff state: ${participant.path}`);
+        return;
+      }
       const ownershipRoot = path.join(stateDir(repoRoot), 'ownership');
       if (!contained(ownershipRoot, authorized)) throw new MutationConflictError(`Generated transaction participant is outside session ownership state: ${participant.path}`);
       if (participant.label !== 'ownership') throw new MutationConflictError(`Session-generated participant must be classified as ownership: ${participant.path}`);
@@ -328,7 +344,7 @@ function validateManifest(manifest, manifestPath, directory, repoRoot, options)
     validateGeneration(participant.new, directory, `participants[${index}].new`);
     const shape = `${participant.old.exists ? 1 : 0}${participant.new.exists ? 1 : 0}`;
     const expectedShapes = {
-      source: ['10'], target: ['01'], referrer: ['11'], creation: ['01'], deletion: ['10'], ownership: ['01', '10'],
+      source: ['10'], target: ['01'], referrer: ['11'], creation: ['01'], deletion: ['10'], ownership: ['01', '10'], handoff: ['11'],
     }[participant.label];
     if (!expectedShapes.includes(shape)) throw new MutationConflictError(`Invalid generation shape for transaction ${participant.label} participant.`);
     if (!Array.isArray(participant.transientHashes) || !participant.transientHashes.every(hash => typeof hash === 'string' && /^[a-f\d]{64}$/.test(hash))) {
@@ -580,6 +596,60 @@ export function recoverAbandonedTransactions(repoRoot, options = {}) {
   return recovered;
 }
 
+// Keep inspection and the locked doctor apply on the same conservative verdict.
+function transactionResolution(manifest, directory) {
+  const present = file => {
+    try { lstatSync(file); return true; }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  };
+  const participants = manifest.participants.map(item => ({ path: item.path, label: item.label, state: participantState(item) }));
+  const states = new Set(participants.map(item => item.state));
+  const uniform = states.size === 1 && (states.has('old') || states.has('new'));
+  const retainedGitPaths = [...new Set([
+    ...manifest.gitIndex.retainedPaths,
+    manifest.gitIndex.prepared?.tempPath,
+  ].filter(item => item && present(item)))];
+  const retainedDirectories = manifest.createdDirectories.filter(item => present(item.path)).map(item => item.path);
+  const knownArtifacts = new Set([
+    'manifest.json', ...manifest.participants.flatMap(item => [item.old.artifact, item.new.artifact]),
+    ...manifest.recoveryArtifacts,
+  ].filter(Boolean).map(item => path.basename(item)));
+  const otherArtifacts = readdirSync(directory).some(name => {
+    const artifact = path.join(directory, name);
+    return !knownArtifacts.has(name) || !lstatSync(artifact).isFile();
+  });
+  // Completion durably records commit or rollback. Later edits, consumption,
+  // or deletion need not match the historical participants to retire evidence.
+  const complete = manifest.status === 'complete';
+  const verifiedDirectories = complete
+    && manifest.createdDirectories.filter(item => retainedDirectories.includes(item.path)).every(item => {
+      try {
+        const stat = lstatSync(item.path);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || !item.identity
+          || stat.dev !== item.identity.dev || stat.ino !== item.identity.ino) return false;
+        const entries = readdirSync(item.path);
+        if (entries.includes(path.basename(item.marker))) {
+          if (!lstatSync(item.marker).isFile() || readFileSync(item.marker, 'utf8') !== `${item.token}\n`) return false;
+        } else if (!['removing', 'removed'].includes(item.markerState)) return false;
+        return true;
+      } catch { return false; }
+    });
+  const resolvable = (complete ? verifiedDirectories : uniform && retainedDirectories.length === 0)
+    && retainedGitPaths.length === 0 && !otherArtifacts;
+  return { participants, generation: uniform ? [...states][0] : null, retainedGitPaths, retainedDirectories, resolvable,
+    reason: resolvable ? null : !complete && !uniform ? 'Canonical files do not agree on one generation' : 'Retained artifacts need manual review' };
+}
+
+// Shared by setup's preview and refusal, using the doctor's verdict and reason.
+export function transactionResolutionAdvice(item) {
+  if (item.ownerLiveness === 'live' || item.lockHeld) return 'Another runlist process is mid-move; rerun setup once it finishes';
+  if (item.resolvable) return 'Run runlist doctor --transactions --apply, then rerun setup';
+  const retained = item.retainedGitPaths?.length ? ` Retained Git artifacts: ${item.retainedGitPaths.join(', ')}.` : '';
+  const reason = (item.reason ?? 'Recovery has not established a complete generation').replace(/\.+$/, '');
+  const generation = item.status === 'complete' ? '' : 'restore one complete generation, ';
+  return `${reason}.${retained} Manually inspect the canonical files and recovery artifacts in ${item.directory}; ${generation}preserve any unverified artifacts, then remove that transaction directory and rerun setup`;
+}
+
 // Report on every transaction manifest without mutating anything, so a wedged
 // repo can be diagnosed. `recoverAbandonedTransactions` deliberately refuses to
 // guess and throws; that left no way to even SEE the state short of reading
@@ -592,7 +662,7 @@ export function inspectTransactions(repoRoot, options = {}) {
   const report = [];
   for (const entry of readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
     if (!entry.isDirectory() || entry.isSymbolicLink()) {
-      report.push({ id: entry.name, readable: false, reason: 'Unsafe entry in transaction root', resolvable: false });
+      report.push({ id: entry.name, directory: path.join(root, entry.name), readable: false, reason: 'Unsafe entry in transaction root', resolvable: false });
       continue;
     }
     const directory = path.join(root, entry.name);
@@ -603,20 +673,20 @@ export function inspectTransactions(repoRoot, options = {}) {
       report.push({ id: entry.name, directory, manifestPath, readable: false, reason: err?.code === 'ENOENT' ? 'No manifest' : `Unreadable manifest: ${err.message}`, resolvable: false });
       continue;
     }
-    try { validateManifest(manifest, manifestPath, directory, repoRoot, options); }
+    let resolution;
+    try {
+      validateManifest(manifest, manifestPath, directory, repoRoot, options);
+      resolution = transactionResolution(manifest, directory);
+    }
     catch (err) {
-      report.push({ id: entry.name, directory, manifestPath, readable: false, reason: err.message, resolvable: false });
+      report.push({ id: entry.name, directory, manifestPath, status: manifest?.status, readable: false, reason: err.message, resolvable: false });
       continue;
     }
-    const participants = manifest.participants.map(item => ({ path: item.path, state: participantState(item) }));
-    const states = new Set(participants.map(item => item.state));
-    const retainedGitPaths = (manifest.gitIndex?.retainedPaths ?? []).filter(item => existsSync(item));
-    const retainedDirectories = manifest.createdDirectories.filter(item => existsSync(item.path)).map(item => item.path);
-    // Safe to clear only when the filesystem already shows one uniform
-    // generation: that IS the atomicity the transaction existed to guarantee,
-    // so the manifest is bookkeeping for work that is fully done or fully
-    // undone. Anything mixed, unknown, or with retained artifacts stays put.
-    const uniform = states.size === 1 && (states.has('old') || states.has('new'));
+    const lockHeld = manifest.participants.some(item => {
+      const lockPath = lockPathFor(canonicalPath(item.path), repoRoot);
+      return existsSync(lockPath) && processOwnerLiveness(lockOwner(lockPath)) !== 'dead';
+    });
+    const ownerLiveness = processOwnerLiveness(manifest.owner);
     report.push({
       id: manifest.id,
       directory,
@@ -627,35 +697,54 @@ export function inspectTransactions(repoRoot, options = {}) {
       result: manifest.result,
       operation: manifest.operation,
       createdAt: manifest.createdAt,
-      ownerLiveness: processOwnerLiveness(manifest.owner),
-      participants,
-      generation: uniform ? [...states][0] : null,
-      retainedGitPaths,
-      retainedDirectories,
-      resolvable: uniform && retainedGitPaths.length === 0 && retainedDirectories.length === 0,
-      reason: uniform
-        ? (retainedGitPaths.length || retainedDirectories.length ? 'Retained artifacts need manual review' : null)
-        : 'Canonical files do not agree on one generation',
+      ownerLiveness,
+      lockHeld,
+      ...resolution,
+      ...(lockHeld || ownerLiveness === 'live' ? { resolvable: false, reason: 'Another runlist process is mid-move; rerun later once it finishes' } : {}),
     });
   }
   return report;
 }
 
 // Clear the manifests inspectTransactions marked resolvable. Touches no
-// canonical file — those already agree on one generation; this only removes the
-// bookkeeping that is wedging later mutations.
+// canonical file. Complete manifests need only verified cleanup evidence;
+// non-complete manifests still require one uniform generation.
 export function resolveTransactions(repoRoot, options = {}) {
   const cleared = [];
   for (const item of inspectTransactions(repoRoot, options)) {
     if (!item.resolvable) continue;
-    let manifest;
-    try { manifest = JSON.parse(readFileSync(item.manifestPath, 'utf8')); } catch { continue; }
+    let manifest, manifestContent;
+    try {
+      manifestContent = readFileSync(item.manifestPath, 'utf8');
+      manifest = JSON.parse(manifestContent);
+    } catch { continue; }
     withPathLocks(manifest.participants.map(entry => entry.path), { repoRoot, ...options }, () => {
       // Re-check under the lock: nothing may have moved since inspection.
-      const states = new Set(manifest.participants.map(participantState));
-      if (states.size !== 1 || !(states.has('old') || states.has('new'))) return;
+      try {
+        if (readFileSync(item.manifestPath, 'utf8') !== manifestContent) return;
+        validateManifest(manifest, item.manifestPath, item.directory, repoRoot, options);
+      } catch { return; }
+      const verdict = transactionResolution(manifest, item.directory);
+      if (!verdict.resolvable) return;
+      // As on commit, remove verified markers deepest first, and remove only
+      // folders that become empty. A crash leaves the marker state resumable.
+      for (const entry of [...manifest.createdDirectories].sort((a, b) => b.path.length - a.path.length)) {
+        if (!verdict.retainedDirectories.includes(entry.path)) continue;
+        if (existsSync(entry.marker)) {
+          entry.markerState = 'removing';
+          durableJson(item.manifestPath, manifest, options);
+          unlinkSync(entry.marker);
+          fsyncDirectory(entry.path, options, 'transaction-directory-marker-delete');
+          entry.markerState = 'removed';
+          durableJson(item.manifestPath, manifest, options);
+        }
+        if (readdirSync(entry.path).length === 0) {
+          rmdirSync(entry.path);
+          fsyncDirectory(path.dirname(entry.path), options, 'transaction-directory-delete');
+        }
+      }
       cleanupTransactionDirectory(item.directory, manifest, options);
-      cleared.push({ id: item.id, generation: [...states][0] });
+      cleared.push({ id: item.id, generation: verdict.generation });
     });
   }
   return cleared;
@@ -699,7 +788,7 @@ function beginMoveManifest({ repoRoot, transactionId, operation, sessionId, sour
   add(targetPath, { exists: false }, { exists: true, content: targetContent, mode: source.identity.mode }, 'target');
   for (const item of updates) add(item.path,
     { exists: true, content: item.snapshot.content, hash: item.snapshot.hash, mode: item.snapshot.identity.mode },
-    { exists: true, content: item.content, mode: item.snapshot.identity.mode }, item.label === 'ownership' || !String(item.path).endsWith('.md') ? 'ownership' : 'referrer');
+    { exists: true, content: item.content, mode: item.snapshot.identity.mode }, item.label === 'handoff' ? 'handoff' : item.label === 'ownership' || !String(item.path).endsWith('.md') ? 'ownership' : 'referrer');
   for (const item of creations) add(item.path, { exists: false }, { exists: true, content: item.content, mode: item.mode ?? (0o666 & ~process.umask()) }, item.label === 'ownership' || !String(item.path).endsWith('.md') ? 'ownership' : 'creation');
   for (const item of deletions) add(item.path,
     { exists: true, content: item.snapshot.content, hash: item.snapshot.hash, mode: item.snapshot.identity.mode }, { exists: false }, item.label === 'ownership' || !String(item.path).endsWith('.md') ? 'ownership' : 'deletion');
@@ -1209,8 +1298,10 @@ export function replaceSnapshot(snapshot, newContent, options = {}) {
   return locked ? commit() : withPathLocks([snapshot.path], { repoRoot, ...options }, commit);
 }
 
+// `locked` means the caller already holds filePath's lock, taken in one sorted
+// withPathLocks set with the other paths its decision depends on.
 export function mutateFile(filePath, options, render) {
-  return withPathLocks([filePath], options, () => {
+  const mutate = () => {
     options.testHooks?.beforeMutationSnapshot?.(filePath);
     const snapshot = snapshotFile(filePath);
     const rendered = render(snapshot.content, snapshot);
@@ -1222,7 +1313,8 @@ export function mutateFile(filePath, options, render) {
       if (err.committedSnapshot) restoreUpdate(err.committedSnapshot, snapshot, err);
       throw err;
     }
-  });
+  };
+  return options.locked ? mutate() : withPathLocks([filePath], options, mutate);
 }
 
 export function createFileExclusive(filePath, content, options) {
@@ -1244,6 +1336,16 @@ export function createFileExclusive(filePath, content, options) {
         options.testHooks?.afterPublicationBeforePathOpen?.('create-hardlink', filePath);
       } catch (err) {
         if (!['ENOTSUP', 'EOPNOTSUPP', 'EPERM', 'EXDEV', 'EMLINK'].includes(err?.code)) throw err;
+        // A file that is read as code (a config every command imports) must
+        // never be seen holding reservation data, not even after a crash
+        // between the reservation and the rename, so such a caller refuses
+        // instead of falling back.
+        if (options.requireAtomicPublish) {
+          const refusal = new Error(`This filesystem cannot create ${path.resolve(filePath)} atomically (hard links unsupported: ${err.code}).`);
+          refusal.code = 'ERUNLIST_ATOMIC_PUBLISH_UNSUPPORTED';
+          refusal.cause = err;
+          throw refusal;
+        }
         // Portable fallback: reserve with O_EXCL, then replace only our own
         // reservation. This may expose the reservation briefly, but can never
         // overwrite a competing creator's file.
@@ -1282,6 +1384,9 @@ export function createFileExclusive(filePath, content, options) {
 
 export function moveFileAtomic(sourcePath, targetPath, render, options) {
   const { repoRoot, finalize, rollbackFinalize, testHooks, updates = [], creations = [], deletions = [], guards = [] } = options;
+  for (const item of updates.filter(item => item.label === 'handoff')) {
+    validateParticipantPath({ path: path.resolve(item.path), policy: 'generated', label: 'handoff' }, repoRoot, options, 'handoff update');
+  }
   recoverAbandonedTransactions(repoRoot, 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 });

package/src/baton.mjs

@@ -3,15 +3,17 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso, shellQuote } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
-import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput, slugify } from './new.mjs';
+import { preparePromptDocument, promptDirectory, runNew, readBodyInput, readPipedBodyInput, slugify, unconfiguredPromptHint } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { handoffNotDoneLine, recordPendingHandoff, runBatonDone } from './handoff-record.mjs';
 import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
 import { mutateFileSet } from './atomic-mutation.mjs';
 import { assertPlanMutationAuthorized, authoritativeSessionId, listOwnedPlans, readPlanOwnership } from './pickup.mjs';
-import { HANDOFF_TEMPLATES, parentPromptName } from './prompt-handoff.mjs';
+import { builtinHandoffTemplate, parentPromptName } from './prompt-handoff.mjs';
 import { readTemplateStore, templateFile } from './template-store.mjs';
+import { isGitIgnored, gitCommitPaths, literalGitPathspec } from './git.mjs';
+import { assertPublishedPromptFolder, carriedOnto, carryLegacyPrompts, existsAfterCarry, isHandoffsMode, planHandoffsConfig, publishHandoffsConfig, readsAsHandoffsOnly } from './handoffs-mode.mjs';
 
 // `runlist baton` is the one-command handoff: save the resume prompt AND release
 // the plan in a single atomic-ish verb. It exists because the three-step skill
@@ -41,6 +43,9 @@ const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @
   runlist baton @/tmp/draft.md               # hand off the plan this session owns
   runlist baton <plan-file> @/tmp/draft.md   # hand off a named plan
   runlist baton <slug> @/tmp/draft.md        # no plan: save resume-<slug>, change nothing else`;
+// Where planning is off (or there is no config yet) a name is the only form.
+const HANDOFFS_BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
+  runlist baton <slug> @/tmp/draft.md        # saves resume-<slug>; pick a short slug naming the work`;
 
 // A handoff that lands beside a pending one leaves two prompts for the same
 // work, and the next session picks whichever sorts first. Baton used to step to
@@ -73,34 +78,41 @@ function refusePendingHandoff(pending) {
   die(`Nothing saved: a handoff for this is already pending:\n${lines}\nInspect it with \`runlist prompts show ${slug}\`. If it is current, keep it and do not hand off again. If it is stale, re-run baton with \`--replace\` to preserve the old handoff under archived/.`);
 }
 
-function archivedCopyPath(promptPath, config) {
+// `projection` is a carry not yet made (src/handoffs-mode.mjs): its targets
+// count as taken, and the folder may not exist yet to authorize against.
+function archivedCopyPath(promptPath, config, projection = null) {
   const dir = path.join(path.dirname(promptPath), config.archiveDir);
   const ext = path.extname(promptPath);
   const stem = path.basename(promptPath, ext);
   let candidate = path.join(dir, `${stem}${ext}`);
-  for (let n = 2; existsSync(candidate); n++) candidate = path.join(dir, `${stem}-${n}${ext}`);
-  return authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
+  for (let n = 2; existsAfterCarry(projection, candidate); n++) candidate = path.join(dir, `${stem}-${n}${ext}`);
+  return projection ? candidate : authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
 }
 
 function commitCommand(config, message, paths) {
-  const fallback = ['git', 'commit', '-m', message, '--', ...paths];
-  let argv = fallback;
   if (typeof config.hooks.batonCommitCommand === 'function') {
     try {
       const custom = config.hooks.batonCommitCommand(message, [...paths]);
       if (!Array.isArray(custom) || custom.length === 0 || !custom.every(part => typeof part === 'string' && part.length > 0)) {
         throw new Error('return a nonempty string argv array');
       }
-      argv = custom;
+      return custom.map(shellQuote).join(' ');
     } catch (err) { warn(`batonCommitCommand failed (${err.message}); printing the default git command.`); }
   }
-  return argv.map(shellQuote).join(' ');
+  const files = gitCommitPaths(paths, config.repoRoot);
+  if (!files.paths.length) return null;
+  // Keep ordinary command output stable, while protecting filenames that Git
+  // would otherwise interpret as pathspec magic (shell quoting is not enough).
+  const pathspec = file => /[*?[\\]/.test(file) || file.startsWith(':') ? literalGitPathspec(file) : file;
+  const command = ['git', 'commit', '-m', message, '--', ...files.paths.map(pathspec)].map(shellQuote).join(' ');
+  if (!files.add.length) return command;
+  return `${['git', 'add', '--', ...files.add.map(pathspec)].map(shellQuote).join(' ')} && ${command}`;
 }
 
 // With no plan named, --done finds this session's record; a named plan is
 // echoed back so the command works from any session.
 function explicitPlanDone(planArg, record) {
-  return planArg ? `runlist baton --done ${record.plan}` : 'runlist baton --done';
+  return planArg ? `runlist baton --done ${shellQuote(record.plan)}` : 'runlist baton --done';
 }
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
@@ -123,6 +135,8 @@ export async function runBaton(argv, config, opts = {}) {
   let subagent = false;
   let parentPrompt = null;
   let template = false;
+  let nextStep = null;
+  let currentState = null;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -132,6 +146,11 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--force') { force = true; continue; }
     if (a === '--replace') { replace = true; continue; }
     if (a === '--done') { done = true; continue; }
+    if (a === '--next-step' || a === '--current-state') {
+      if (i + 1 >= argv.length) die(`${a} needs a value: runlist baton --done [<plan-file>] ${a} "<text>"`);
+      if (a === '--next-step') nextStep = argv[++i]; else currentState = argv[++i];
+      continue;
+    }
     if (a === '--subagent') { subagent = true; continue; }
     if (a === '--template') { template = true; continue; }
     if (a === '--parent') {
@@ -145,6 +164,9 @@ export async function runBaton(argv, config, opts = {}) {
     die(`Unknown flag for \`runlist baton\`: ${a}`);
   }
   if (parentPrompt && !subagent) die('--parent requires --subagent.');
+  for (const [flag, value] of [['--next-step', nextStep], ['--current-state', currentState]]) {
+    if (value !== null && !done) die(`${flag} only goes with --done: save the prompt first, then run \`runlist baton --done [<plan-file>] ${flag} "<text>"\`.`);
+  }
   if (template) {
     if (done || replace || force || statusFlag || note !== null || positionals.length || bodyFlag !== null) {
       die('Use `runlist baton --template` or `runlist baton --subagent --template [--parent resume-name]` to print a draft without saving.');
@@ -153,7 +175,7 @@ export async function runBaton(argv, config, opts = {}) {
     const name = subagent ? 'subagent' : 'resume';
     const key = `handoff:${name}`;
     const override = config ? readTemplateStore(config).data.templates[key]?.source : null;
-    const source = override ?? HANDOFF_TEMPLATES[key].source;
+    const source = override ?? builtinHandoffTemplate(key, { planning: !readsAsHandoffsOnly(config) });
     const draft = source.replaceAll('{{parent_prompt}}', parentPrompt ?? '<resume-parent-name>');
     process.stdout.write(json ? JSON.stringify({ operation: 'baton-template', name, origin: override ? templateFile : 'Built-in', parentPrompt, template: draft }, null, 2) + '\n' : draft);
     return;
@@ -170,8 +192,9 @@ export async function runBaton(argv, config, opts = {}) {
   // The second half of a plan handoff: the prompt is already saved, and this
   // confirms the plan was brought up to date after it (src/handoff-record.mjs).
   if (done) {
-    if (dryRun) die('`runlist baton --done` changes nothing but its own record; run it without --dry-run.');
-    return runBatonDone(planArg, config, { json });
+    if (bodyArg !== null || bodyFlag !== null) die('`runlist baton --done` takes no prompt body; the prompt was saved by the first baton call.');
+    if (isHandoffsMode(config)) die('Nothing to confirm: planning is off in this project, so the prompt baton saved is the whole handoff.');
+    return runBatonDone(planArg, config, { json, dryRun, nextStep, currentState });
   }
 
   // Body FIRST — it's the common failure (`new prompt` without a body was the
@@ -183,7 +206,7 @@ export async function runBaton(argv, config, opts = {}) {
     // Auto-consume piped/redirected stdin, same probe as `runlist new`.
     body = readPipedBodyInput();
   }
-  if (!body || !body.trim()) die(BODY_USAGE);
+  if (!body || !body.trim()) die(isHandoffsMode(config) || !config.configFound ? HANDOFFS_BODY_USAGE : BODY_USAGE);
   const draft = extractFrontmatter(body);
   const draftFm = parseSimpleFrontmatter(draft.frontmatter);
   if (!subagent && asString(draftFm.parent_prompt)) die('parent_prompt requires --subagent; a resume handoff cannot be its own child.');
@@ -222,6 +245,9 @@ export async function runBaton(argv, config, opts = {}) {
       planPath = path.resolve(config.repoRoot, owned.plan.path);
     } else if (owned.owned?.length > 1) {
       die(`Multiple plans are owned by this session; pass one explicitly:\n${owned.owned.map(d => '  runlist baton ' + d.path + ' @/tmp/draft.md').join('\n')}`);
+    } else if (isHandoffsMode(config) || !config.configFound) {
+      // No plans here: the only thing missing is a name, which the session picks.
+      die('Baton needs a short name for the handoff — a few words naming the work:\n  runlist baton <slug> @/tmp/draft.md      # saves resume-<slug>');
     } else {
       const diagnostics = owned.diagnostics?.length ? `\nIgnored ownership records:\n${owned.diagnostics.map(d => `  ${d}`).join('\n')}` : '';
       die(`No valid in-session plan is owned by this session, so baton needs a name for the resume prompt:\n  runlist baton <slug> @/tmp/draft.md      # saves resume-<slug>, touches nothing else\nHanding off a specific plan? runlist baton <plan-file> @/tmp/draft.md${diagnostics}`);
@@ -241,9 +267,14 @@ export async function runBaton(argv, config, opts = {}) {
   const slugBase = `${handoffPrefix}${unprefixed}`;
   let replacement = null;
   let alternatePromptPath = null;
-  const resolvePending = () => {
-    const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
-    const pending = pendingHandoffs(target.filePath, planPath, config);
+  // With a carry planned but not made (`projection`), the check runs against
+  // docs/prompts/ as the carry will leave it, so a refusal comes before
+  // anything moves and dry-run answers as apply will.
+  const resolvePending = (projection = null) => {
+    const target = projection ? { filePath: path.join(projection.promptDir, `${slugBase}.md`) } : preparePromptDocument(slugBase, body, config, { dryRun: true });
+    const carriedHere = projection ? carriedOnto(projection, target.filePath) : null;
+    const pending = !projection ? pendingHandoffs(target.filePath, planPath, config)
+      : carriedHere ? [carriedHere.from] : existsSync(target.filePath) ? [toRepoPath(target.filePath, config.repoRoot)] : [];
     if (planPath) {
       const alternateSlug = `${subagent ? 'resume-' : 'subagent-'}${unprefixed}`;
       alternatePromptPath = preparePromptDocument(alternateSlug, body, config, { dryRun: true }).filePath;
@@ -260,12 +291,12 @@ export async function runBaton(argv, config, opts = {}) {
       const detail = pending.length ? `Found ${pending.length}:\n${pending.map(p => `  ${p}`).join('\n')}` : 'No pending handoff matches this work.';
       die(`Nothing replaced: --replace requires exactly one pending handoff. ${detail}`);
     }
-    const oldRepoPath = pending[0];
+    const oldRepoPath = carriedHere ? carriedHere.to : pending[0];
     if (subagent && /^resume-/i.test(path.basename(oldRepoPath))) {
       die(`Nothing replaced: ${oldRepoPath} is a parent handoff. Inspect it with \`runlist prompts show ${path.basename(oldRepoPath, '.md')}\`; use a separate task slug for the child handoff, or omit --subagent to refresh the parent handoff.`);
     }
-    const oldPath = authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
-    const oldRaw = readFileSync(oldPath, 'utf8');
+    const oldPath = carriedHere ? carriedHere.target : authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
+    const oldRaw = carriedHere ? carriedHere.expectedSource : readFileSync(oldPath, 'utf8');
     const { frontmatter, body: oldBody } = extractFrontmatter(oldRaw);
     const fm = parseSimpleFrontmatter(frontmatter);
     if (asString(fm.type) !== 'prompt' || asString(fm.status) !== 'pending') {
@@ -280,7 +311,7 @@ export async function runBaton(argv, config, opts = {}) {
     parentPrompt ??= priorParent;
     replacement = {
       oldPath, oldRepoPath, oldRaw, priorParent,
-      archivedPath: archivedCopyPath(oldPath, config),
+      archivedPath: archivedCopyPath(oldPath, config, projection),
       alreadyCurrent: oldBody.trim() === draft.body.trim()
         && Object.entries(draftFm).every(([key, value]) => key === 'parent_prompt' || JSON.stringify(fm[key]) === JSON.stringify(value))
         && (priorParent ?? null) === parentPrompt
@@ -289,6 +320,57 @@ export async function runBaton(argv, config, opts = {}) {
     };
   };
 
+  // Zero setup: a prompt saved in a repository with no config creates the
+  // handoffs-only config first (src/handoffs-mode.mjs). Prompts an older
+  // version saved in the root prompts/ move to docs/prompts/ first. Every check
+  // that can refuse the save runs against docs/prompts/ as that carry leaves
+  // it, before anything moves or is written, and dry-run stops at the same
+  // point. Plan mode is left alone: a plan saved before setup belongs to
+  // `runlist setup`.
+  let handoffsCreated = null;
+  let handoffsLine = null;
+  if (!planPath && !config.configFound) {
+    const quiet = { write() {} };
+    const setup = await planHandoffsConfig(process.cwd(), config, { dryRun, out: json ? quiet : process.stderr });
+    if (setup.previewStopped) {
+      const result = { operation: 'baton', parentPrompt, dryRun: true, disposition: 'would-change', wouldChange: true, mode: 'slug', status: null,
+        repositoryFiles: [], sessionFiles: [], generatedFiles: [], deferredGeneratedFiles: [], prompt: null, plan: null, planMovement: null,
+        replacement: null, claimRelease: null, handoffDone: true, savedPrompt: null, handoffsSetup: null, pendingRecovery: true };
+      if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+      return result;
+    }
+    config = setup.config;
+    resolvePending(setup);
+    await carryLegacyPrompts(setup, { dryRun, out: json ? quiet : process.stderr });
+    handoffsCreated = setup.created;
+    if (dryRun) {
+      handoffsLine = setup.dryRunLine;
+      if (handoffsLine && !json) process.stderr.write(`${handoffsLine}\n`);
+      const prompt = replacement?.oldRepoPath ?? path.posix.join(setup.promptRoot, `${slugBase}.md`);
+      const archivedPrompt = replacement && !replacement.alreadyCurrent ? toRepoPath(replacement.archivedPath, config.repoRoot) : null;
+      const result = { operation: 'baton', parentPrompt, dryRun: true, disposition: replacement?.alreadyCurrent ? 'already-current' : 'would-change', wouldChange: true, mode: 'slug', status: null,
+        repositoryFiles: [], sessionFiles: [prompt, ...(archivedPrompt ? [archivedPrompt] : [])], generatedFiles: [], deferredGeneratedFiles: [], prompt, plan: null, planMovement: null,
+        replacement: replacement ? { previousPrompt: replacement.oldRepoPath, archivedPrompt, pendingPrompt: prompt, alreadyCurrent: replacement.alreadyCurrent } : null,
+        claimRelease: null, handoffDone: true, savedPrompt: path.basename(prompt, '.md'), handoffsSetup: handoffsCreated };
+      if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+      else {
+        if (archivedPrompt) process.stderr.write(`${dim('[dry-run]')} Would preserve old handoff: ${replacement.oldRepoPath} → ${archivedPrompt}\n`);
+        process.stderr.write(`${dim('[dry-run]')} Would ${replacement ? (replacement.alreadyCurrent ? 'keep' : 'replace') : 'create'}: ${prompt}\n`);
+      }
+      return result;
+    }
+    if (!setup.legacy) {
+      const published = await publishHandoffsConfig(setup, { testHooks: opts.testHooks });
+      config = published.config;
+      assertPublishedPromptFolder(setup, published, promptDirectory(config));
+      handoffsCreated = published.created;
+      handoffsLine = published.line;
+      if (handoffsLine && !json) process.stderr.write(`${handoffsLine}\n`);
+    }
+    // The carry is made: check again against the files themselves below.
+    replacement = null;
+  }
+
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
@@ -351,6 +433,14 @@ export async function runBaton(argv, config, opts = {}) {
     else if (planHasPendingCompletion(repoPath, config)) process.stderr.write(`${dim('[dry-run]')} Pending claim completion would block this release.\n`);
   } else {
     resolvePending();
+    // The skill's rule is "own an in-session plan → no slug"; a session that
+    // picked a slug anyway is told its plan stays claimed. Child handoffs under
+    // a parent's plan use a slug on purpose.
+    if (!subagent && config.configFound && !isHandoffsMode(config)) {
+      let owned = [];
+      try { owned = listOwnedPlans(config, authoritativeSessionId()); } catch { /* unreadable claims: say nothing */ }
+      if (owned.length) warn(`This session owns ${owned.map(record => record.plan).join(', ')}, which stays in-session: this saves ${slugBase} without handing ${owned.length === 1 ? 'it' : 'them'} off. To hand ${owned.length === 1 ? 'the plan' : 'a plan'} off with the prompt, run \`runlist baton ${owned.length === 1 ? '' : '<plan-file> '}@<draft-file>\` with no slug.`);
+    }
     if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
@@ -397,7 +487,7 @@ export async function runBaton(argv, config, opts = {}) {
       newResult = { sessionFiles: [replacement.oldRepoPath, ...(replacement.alreadyCurrent ? [] : [toRepoPath(replacement.archivedPath, config.repoRoot)])] };
     } else {
       try {
-        newResult = await runNew(['prompt', slugBase, '--body', body], config, { parentPrompt, dryRun, deferIndex: true });
+        newResult = await runNew(['prompt', slugBase, '--body', body], config, { parentPrompt, dryRun, deferIndex: true, handoffsPlanned: true });
       } catch (err) {
         // Lost a race with another baton between the pending check and the write.
         if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
@@ -493,6 +583,7 @@ export async function runBaton(argv, config, opts = {}) {
     claimRelease: planPath ? { wouldRelease: wouldReleaseClaim, released: !dryRun && wouldReleaseClaim } : null,
     handoffDone: !pendingHandoff,
     savedPrompt: createdSlug,
+    handoffsSetup: handoffsCreated,
   };
 
   const prefix = dryRun ? dim('[dry-run] ') : '';
@@ -501,26 +592,29 @@ export async function runBaton(argv, config, opts = {}) {
     return operationResult;
   }
   const verdict = replacement?.alreadyCurrent ? '✓ Handoff kept' : pendingHandoff ? '✓ Prompt saved' : replacement ? '✓ Baton replaced' : '✓ Baton passed';
+  if (!handoffsLine && !dryRun && (planPath || replacement)) process.stderr.write(unconfiguredPromptHint(config));
   process.stderr.write(`\n${prefix}${green(verdict)}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
   if (archivedPromptRepoPath) process.stderr.write(dim(`${prefix}Previous handoff preserved: ${archivedPromptRepoPath}\n`));
   if (planGuard) {
     process.stderr.write(dim(`${repoPath} left at \`${oldStatus}\` — it was not in-session, so there was no claim to release.\n`));
     process.stderr.write(dim(`Meant to change it? runlist set <status> ${repoPath}\n`));
   }
-  if (statusChanged) {
-    let gitignored = false;
-    try {
-      const { isGitIgnored } = await import('./git.mjs');
-      gitignored = isGitIgnored(planPath, config.repoRoot);
-    } catch { /* not a git repo — fall through to the hint */ }
-    if (gitignored) {
-      process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
-    } else {
+  if (statusChanged && isGitIgnored(planPath, config.repoRoot)) {
+    // Check the source even after a move: an ignored plan must not produce a
+    // commit hint for its destination or rewritten references, including hooks.
+    process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
+  } else if (statusChanged) {
+    const command = commitCommand(config, `baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}`, operationResult.repositoryFiles);
+    if (command) {
       process.stderr.write(`${prefix}Commit the repository files (session files stay OUT of the pathspec):\n`);
-      process.stderr.write(`${prefix}  ${commitCommand(config, `baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}`, operationResult.repositoryFiles)}\n`);
+      process.stderr.write(`${prefix}  ${command}\n`);
+    } else {
+      process.stderr.write(dim('No repository files to commit — no commit needed.\n'));
     }
   }
-  if (operationResult.deferredGeneratedFiles.length) process.stderr.write(dim(`Generated index deferred: ${operationResult.deferredGeneratedFiles.join(', ')}\n`));
+  // Baton leaves the shared index alone so a handoff never conflicts with other work; nothing
+  // here needs the user, so it stays out of the normal output (--json always carries it).
+  if (opts.verbose && operationResult.deferredGeneratedFiles.length) process.stderr.write(dim(`Index not refreshed by baton: ${operationResult.deferredGeneratedFiles.join(', ')} (the next runlist command that rebuilds it picks up the change)\n`));
   if (pendingHandoff) process.stderr.write(yellow(handoffNotDoneLine(pendingHandoff, explicitPlanDone(planArg, pendingHandoff))) + '\n');
   // The name again, last, so a piped `| tail` still shows what was saved.
   process.stderr.write(`${prefix}Saved prompt: ${createdSlug}\n`);