runlist 0.94.2 → 0.95.0

package/bin/runlist.mjs

@@ -1337,8 +1337,9 @@ Usage (write the resume to a file first, then pick the form that matches):
   runlist baton @/tmp/draft.md               # a plan is in-session: save resume-<plan-slug>, release the plan
   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
+  runlist baton --done [<plan-file>]         # after a plan handoff: confirm the plan was brought up to date
   The resume can also come from stdin (\`-\`, or a pipe) or --message "..." for one-liners.
-  Baton prints the prompt name it saved and, in plan mode, the git commit to run.
+  Baton prints the prompt name it saved, as its last line too, and, in plan mode, the git commit to run.
 
 The resume (10–20 lines): the next concrete decision plus any gotchas, and the
 paths of the plans/docs it concerns — not a recap of the plan body.
@@ -1349,6 +1350,7 @@ Options:
   --message / --body     Inline body (one-liners; prefer @path or stdin)
   --force                Recover another session's plan (explicit path required)
   --replace              Replace exactly one pending handoff; archive its prior text
+  --done                 Report a plan handoff done once next_step changed after the prompt was saved
   --json                 Structured repository/session/generated file result
   --dry-run, -n          Preview without writing
 
@@ -1376,6 +1378,11 @@ cooperating transaction:
   3. Defers the shared generated index and prints exact repository-only commit
      guidance. Prompt and ownership records stay session-local and OUT of the
      pathspec.
+  4. When the plan was in-session and has a next_step field, the handoff is not
+     done yet: bring the plan up to date (the body, then next_step), then run
+     \`runlist baton --done\`, which refuses while next_step still reads as it
+     did when the prompt was saved. The prompt is saved first, so a stop between
+     the two steps loses nothing, and \`--done <plan-file>\` works from any session.
   Which plan? Pass it explicitly, or baton resolves exactly one plan owned by
   this authoritative session. Journal entries and global in-session counts never
   grant ownership. A live pickup-hook delivery lease blocks release and force

package/package.json

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

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.94.2",
+  "version": "0.95.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/src/baton.mjs

@@ -5,7 +5,8 @@ import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
-import { green, dim } from './color.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';
@@ -99,6 +100,12 @@ function commitCommand(config, message, paths) {
   return argv.map(shellQuote).join(' ');
 }
 
+// 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';
+}
+
 // Is this positional a filesystem reference (must resolve, typos die) or a
 // bare word (may be a plan slug, may be a brand-new handoff name)?
 function looksLikePath(arg) {
@@ -115,6 +122,7 @@ export async function runBaton(argv, config, opts = {}) {
   let bodyFlag = null;
   let force = false;
   let replace = false;
+  let done = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -123,6 +131,7 @@ export async function runBaton(argv, config, opts = {}) {
     if ((a === '--body' || a === '--message') && argv[i + 1]) { bodyFlag = argv[++i]; continue; }
     if (a === '--force') { force = true; continue; }
     if (a === '--replace') { replace = true; continue; }
+    if (a === '--done') { done = true; continue; }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
@@ -136,6 +145,13 @@ export async function runBaton(argv, config, opts = {}) {
     if (bodyArg === null) bodyArg = p; // trailing inline body
   }
 
+  // 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 });
+  }
+
   // Body FIRST — it's the common failure (`new prompt` without a body was the
   // top real-world baton error), and nothing must mutate before it's secured.
   let body = null;
@@ -382,6 +398,14 @@ export async function runBaton(argv, config, opts = {}) {
   const repositoryFiles = [...new Set(touched.filter(candidate => candidate && candidate !== ownershipRepoPath && candidate !== promptRepoPath && candidate !== archivedPromptRepoPath && candidate !== normalizeRepoPath(config.indexPath)))];
   const sessionFiles = [...new Set([...(newResult?.sessionFiles ?? []), promptRepoPath, archivedPromptRepoPath, ownershipRepoPath].filter(Boolean))];
   const deferredGeneratedFiles = [...new Set(newResult?.deferredGeneratedFiles ?? (config.indexPath ? [normalizeRepoPath(config.indexPath)] : []))];
+  // A released in-session plan is not handed off until its next_step says
+  // where the work now stands. The prompt is already saved either way.
+  let pendingHandoff = null;
+  if (planPath && !dryRun && !planGuard && (oldStatus === 'in-session' || wouldReleaseClaim)) {
+    try {
+      pendingHandoff = recordPendingHandoff(config, { planRepoPath: normalizeRepoPath(archiveResult?.newRepoPath) ?? repoPath, promptRepoPath, promptName: createdSlug });
+    } catch (err) { warn(`Could not record the pending plan update (${err.message}); bring the plan up to date anyway.`); }
+  }
   const operationResult = {
     operation: 'baton',
     dryRun: Boolean(dryRun),
@@ -403,6 +427,8 @@ export async function runBaton(argv, config, opts = {}) {
       alreadyCurrent: replacement.alreadyCurrent,
     } : null,
     claimRelease: planPath ? { wouldRelease: wouldReleaseClaim, released: !dryRun && wouldReleaseClaim } : null,
+    handoffDone: !pendingHandoff,
+    savedPrompt: createdSlug,
   };
 
   const prefix = dryRun ? dim('[dry-run] ') : '';
@@ -410,7 +436,7 @@ export async function runBaton(argv, config, opts = {}) {
     process.stdout.write(JSON.stringify(operationResult, null, 2) + '\n');
     return operationResult;
   }
-  const verdict = replacement?.alreadyCurrent ? '✓ Handoff kept' : replacement ? '✓ Baton replaced' : '✓ Baton passed';
+  const verdict = replacement?.alreadyCurrent ? '✓ Handoff kept' : pendingHandoff ? '✓ Prompt saved' : replacement ? '✓ Baton replaced' : '✓ Baton passed';
   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) {
@@ -431,5 +457,8 @@ export async function runBaton(argv, config, opts = {}) {
     }
   }
   if (operationResult.deferredGeneratedFiles.length) process.stderr.write(dim(`Generated index deferred: ${operationResult.deferredGeneratedFiles.join(', ')}\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`);
   return operationResult;
 }

package/src/commands.mjs

@@ -140,7 +140,7 @@ const definitions = [
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--done'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),

package/src/handoff-record.mjs

@@ -0,0 +1,107 @@
+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 { stateDir } from './naming.mjs';
+import { resolveDocArg } from './index.mjs';
+import { authoritativeSessionId } from './pickup.mjs';
+import { 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
+// is the part sessions skipped: they saved the prompt, reported the handoff
+// 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.
+// 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.
+
+function recordsDir(config) {
+  return path.join(stateDir(config.repoRoot), 'handoffs');
+}
+
+function recordPath(config, planRepoPath) {
+  return path.join(recordsDir(config), `${path.basename(planRepoPath, '.md')}.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 };
+  return { present: true, value: JSON.stringify(fm.next_step ?? null) };
+}
+
+// Called by baton after the prompt and the plan release are published. Returns
+// 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);
+  if (!present) return null;
+  const record = {
+    plan: planRepoPath,
+    prompt: promptRepoPath,
+    name: promptName,
+    savedAt: nowIso(),
+    nextStep: value,
+    sessionId: authoritativeSessionId() ?? null,
+  };
+  mkdirSync(recordsDir(config), { recursive: true });
+  writeFileSync(recordPath(config, planRepoPath), JSON.stringify(record, null, 2) + '\n');
+  return record;
+}
+
+export function listPendingHandoffs(config) {
+  const dir = recordsDir(config);
+  if (!existsSync(dir)) return [];
+  const records = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    try { records.push({ ...JSON.parse(readFileSync(path.join(dir, name), 'utf8')), recordFile: path.join(dir, name) }); }
+    catch { /* a torn record is not a handoff to wait on */ }
+  }
+  return records;
+}
+
+export function pendingHandoffsForSession(config, sessionId = authoritativeSessionId()) {
+  if (!sessionId) return [];
+  return listPendingHandoffs(config).filter(record => record.sessionId === sessionId);
+}
+
+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}\`.`;
+}
+
+// `runlist baton --done [<plan>]`
+export function runBatonDone(planArg, config, { json = false } = {}) {
+  let record;
+  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.`);
+  } 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')}`);
+    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}`);
+  }
+  rmSync(record.recordFile, { force: true });
+  const result = { operation: 'baton-done', plan: record.plan, prompt: record.prompt, name: record.name, nextStepChanged: true };
+  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`);
+  process.stderr.write(`Saved prompt: ${record.name}\n`);
+  return result;
+}

package/src/hud.mjs

@@ -11,6 +11,7 @@ import { readJournalEntries, journalFilePath, readMisuseEntries } from './journa
 import { compareVersions } from './update.mjs';
 import { findOwnedPlan } from './baton.mjs';
 import { listOwnedPlans, surveyOwnershipClaims } from './pickup.mjs';
+import { handoffNotDoneLine, pendingHandoffsForSession } from './handoff-record.mjs';
 import { actionablePromptStatuses, comparePromptDocs, resolveStatusMetadata } from './status-metadata.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
@@ -327,14 +328,47 @@ export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
 // form for its situation before it goes looking. Sessions ran `baton --help`
 // before nearly every baton even with the form in CLAUDE.md, because the right
 // form depends on whether this session owns a plan, which only runlist knows.
-const HANDOFF_ASK = /\bbaton\b|\bhand[\s-]?off\b|\bresume[\s-]prompt\b|\bsave (?:a |the )?resume\b|\bpick (?:it|this|that) (?:back )?up (?:next time|later|tomorrow)\b/i;
+//
+// Only a request fires it. Matching the word anywhere answered questions about
+// batons ("what is the deal with the baton?") with handoff steps, and sessions
+// read that as a go to hand off. So the prompt is read clause by clause: a
+// clause that opens as a question never counts, and "baton" counts only as a
+// verb (opening the clause, after "and"/"then", or "do a baton"), never as the
+// subject of a sentence ("baton prints its name first").
+const HANDOFF_PHRASE = /\bhand[\s-]?off\b|\bresume[\s-]prompt\b|\bsave (?:a |the )?resume\b|\bpick (?:it|this|that) (?:back )?up (?:next time|later|tomorrow)\b/i;
+const LEAD_WORDS = String.raw`(?:(?:ok(?:ay)?|alright|right|now|then|and|also|but|so|yes|yep|great|good|cool|thanks|please|pls|go ahead and|let'?s|lets|time to)\b[,\s]*)*`;
+const POLITE = String.raw`(?:(?:can|could|would|will) you (?:please )?(?:mind )?)`;
+const BATON_AS_NOUN = String.raw`(?:(?:do|doing|make|write|leave|save|pass|run|drop) (?:a |the |your |another |one more )?)`;
+// A word here after "baton" makes it the subject or a noun ("baton is",
+// "baton prints", "baton command"), not a request.
+const NOT_A_VERB = String.raw`(?!\s+(?:is|isn'?t|was|wasn'?t|are|were|does|doesn'?t|did|didn'?t|do|has|had|have|seems|should|shall|would|will|won'?t|can|can'?t|could|keeps|kept|works|worked|fails|failed|prints|printed|says|said|saves|saved|refuses|refused|output|outputs|command|commands|text|hint|hook|line|skill|tool|step|steps|definition|prompt|prompts)\b)(?!'s\b)`;
+const BATON_REQUEST = [
+  new RegExp(String.raw`^${LEAD_WORDS}${POLITE}?(?:please )?${BATON_AS_NOUN}?batons?\b${NOT_A_VERB}`, 'i'),
+  new RegExp(String.raw`(?:\band|\bthen|&)\s+(?:please )?${BATON_AS_NOUN}?batons?\b${NOT_A_VERB}`, 'i'),
+  new RegExp(String.raw`\b(?:do|make|write|leave|save|pass) (?:a |your |another |one more )baton\b`, 'i'),
+];
+const QUESTION_START = new RegExp(String.raw`^${LEAD_WORDS}(?:what'?s|whats|what|why|how|when|where|who|whose|which|is|isn'?t|are|aren'?t|was|wasn'?t|were|does|doesn'?t|did|didn'?t|has|have|had|should|shall|do(?! (?:a |the |your |another |one more )?baton)|(?:can|could|would|will)(?! you\b))\b`, 'i');
 
 // The harness hands background-task events to UserPromptSubmit as if typed.
 // A finished agent's report that names its handoff file is not a request.
 const SYSTEM_EVENT = /<task-notification>|\[SYSTEM NOTIFICATION\b/;
 
+function clauses(prompt) {
+  return prompt.split(/(?<=[.!?;\n])/).map(clause => clause.trim()).filter(Boolean);
+}
+
 export function isHandoffAsk(prompt) {
-  return typeof prompt === 'string' && !SYSTEM_EVENT.test(prompt) && HANDOFF_ASK.test(prompt);
+  if (typeof prompt !== 'string' || SYSTEM_EVENT.test(prompt)) return false;
+  return clauses(prompt).some(clause => !QUESTION_START.test(clause)
+    && (BATON_REQUEST.some(re => re.test(clause)) || HANDOFF_PHRASE.test(clause)));
+}
+
+// The repo's own definition of baton (`templates.prompt.baton` in its config),
+// when it has one. Read from the loaded config only: the hook path never builds
+// the index.
+export function repoBatonDefinition(config) {
+  const text = config?.raw?.templates?.prompt?.baton;
+  return typeof text === 'string' && text.trim() ? text.trim() : null;
 }
 
 export function buildHandoffContext(config) {
@@ -346,15 +380,26 @@ export function buildHandoffContext(config) {
     const records = listOwnedPlans(config);
     if (!records.diagnostics?.length) ownedPaths = records.map(record => record.plan);
   } catch { /* fall through to the no-plan form */ }
-  const draft = 'Write the resume first (the next concrete decision, any gotchas, the plan/doc paths it concerns; not a recap) to a file in your scratchpad.';
-  const tail = 'Baton prints the prompt name it saved; tell the user that name. No `--help` needed.';
+  const done = 'Baton does not report the handoff done until the plan\'s next_step has been updated after the prompt was saved: update the plan, then run';
+  let who;
+  let command;
   if (ownedPaths.length === 1) {
-    return `[runlist] Baton: this session owns ${ownedPaths[0]}. ${draft} Then run \`runlist baton @<file>\`: it saves the prompt, releases the plan to active (\`--status paused|awaiting|partial|blocked\` and \`--note "why"\` if that fits better), and prints the commit to run. ${tail}`;
+    who = `this session owns ${ownedPaths[0]}.`;
+    command = `Save the prompt with \`runlist baton @<file>\`: it releases the plan to active (\`--status paused|awaiting|partial|blocked\` and \`--note "why"\` if that fits better). ${done} \`runlist baton --done\`.`;
+  } else if (ownedPaths.length > 1) {
+    who = `this session owns ${ownedPaths.length} plans (${ownedPaths.join(', ')}), so name the one to hand off.`;
+    command = `Save it with \`runlist baton <plan-file> @<file>\`. ${done} \`runlist baton --done <plan-file>\`.`;
+  } else {
+    who = 'this session owns no plan.';
+    command = 'Save the prompt with `runlist baton <slug> @<file>` (saves resume-<slug>, changes nothing else), or `runlist baton <plan-file> @<file>` to hand off a plan by path.';
   }
-  if (ownedPaths.length > 1) {
-    return `[runlist] Baton: this session owns ${ownedPaths.length} plans (${ownedPaths.join(', ')}), so name the one to hand off. ${draft} Then run \`runlist baton <plan-file> @<file>\`. ${tail}`;
+  const tail = 'Baton prints the prompt name it saved as its last line; tell the user that name. No `--help` needed.';
+  const definition = repoBatonDefinition(config);
+  if (definition) {
+    return `[runlist] Baton: ${who} ${command} Where the definition below names a command, use this form. ${tail}\nThis repo defines baton (templates.prompt.baton in its runlist config):\n${definition}`;
   }
-  return `[runlist] Baton: this session owns no plan. ${draft} Then run \`runlist baton <slug> @<file>\` (saves resume-<slug>, changes nothing else), or \`runlist baton <plan-file> @<file>\` to hand off a plan by path. ${tail}`;
+  const draft = 'Write the resume first (the next concrete decision, any gotchas, the plan/doc paths it concerns; not a recap) to a file in your scratchpad.';
+  return `[runlist] Baton: ${who} ${draft} ${command} ${tail}`;
 }
 
 export async function runPromptSubmitHud(config, { readStdin } = {}) {
@@ -368,6 +413,16 @@ export async function runPromptSubmitHud(config, { readStdin } = {}) {
   process.stdout.write(buildHandoffContext(config) + '\n');
 }
 
+// Names, not paths, and at most PROMPT_NAMES_SHOWN of them, so the line stays
+// one line however long the queue grows.
+const PROMPT_NAMES_SHOWN = 12;
+export function pendingPromptsLine(prompts) {
+  const n = prompts.length;
+  const names = prompts.slice(0, PROMPT_NAMES_SHOWN).map(p => path.basename(p, '.md'));
+  const more = n > names.length ? ` (+${n - names.length} more: \`runlist prompts\`)` : '';
+  return `[runlist] ${n} pending prompt${n === 1 ? '' : 's'}: ${names.join(', ')}${more}. Resume one only when the user asks for it (\`runlist use <name>\`); never consume the oldest by default. Peek without consuming: \`runlist prompts show <name>\`.`;
+}
+
 function isRunlistRepo(config) {
   return Boolean(config?.configFound);
 }
@@ -409,21 +464,29 @@ export function runHud(argv, config) {
   // `runlist hud --json`. Two signals ARE instructions and must print, because
   // the handoff loop dies without them (sessions were saving batons that no
   // next session ever picked up):
-  //   - pending prompts: the previous session queued work for THIS one;
-  //     consuming it is the very next action.
+  //   - pending prompts: earlier sessions queued work. The line lists them
+  //     and says to resume one only when the user asks. It used to say
+  //     "consume the oldest" unless told otherwise, but a new session nearly
+  //     always has a task from the user, the hook cannot see it, and the
+  //     oldest prompt is rarely the useful one.
   //   - an in-session plan attributed to this sid via durable ownership: this
   //     session (pre-compaction) owns it and should continue or hand it off.
   //     Global in-session counts never provide a fallback.
   // The misuse recap stays for the same reason: a repeat-offense rule means
   // the primer alone isn't landing, so name the habit to break.
-  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<plan-or-slug>] @<draft-file> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<plan-or-slug>] @<draft-file> (save a resume prompt; releases the in-session plan if any)') + '\n');
   process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
   if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[runlist] in-session (yours): ${hud.owned.path} — continue it; hand off with \`runlist baton @/tmp/draft.md\` before stopping.`) + '\n');
   }
+  // A handoff this session started and did not finish (a compaction or a stop
+  // between saving the prompt and updating the plan).
+  try {
+    for (const record of pendingHandoffsForSession(config)) process.stdout.write(yellow(`[runlist] ${handoffNotDoneLine(record, `runlist baton --done ${record.plan}`)}`) + '\n');
+  } catch { /* advisory */ }
   if (hud.prompts.length > 0) {
     const n = hud.prompts.length;
-    process.stdout.write(yellow(`[runlist] ${n} pending prompt${n === 1 ? '' : 's'} queued for this session — unless the user asks for something else, start by running \`runlist use\` to consume the oldest (${hud.prompts[0]}) and act on it. Peek first: \`runlist prompts show <file>\`; list: \`runlist prompts\`.`) + '\n');
+    process.stdout.write(yellow(pendingPromptsLine(hud.prompts)) + '\n');
   }
   if (hud.misuseRecap) process.stdout.write(yellow(`[runlist] ${hud.misuseRecap}`) + '\n');
   if (hud.deadClaimsLine) process.stdout.write(yellow(hud.deadClaimsLine) + '\n');

package/src/plan-changes.mjs

@@ -0,0 +1,72 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { isGitIgnored } from './git.mjs';
+
+// What happened to a plan since a prompt about it was written. A resumed
+// prompt is a snapshot: when its plan moved on since, the session needs to
+// know which parts may be stale before it acts on them. Read-only; every git
+// failure degrades to "unknown" rather than blocking the consume.
+
+const SHOWN_COMMITS = 10;
+
+function git(args, repoRoot) {
+  const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf8' });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout;
+}
+
+function nextStepOf(raw) {
+  const { frontmatter } = extractFrontmatter(raw);
+  if (!frontmatter) return undefined;
+  const fm = parseSimpleFrontmatter(frontmatter);
+  return Object.prototype.hasOwnProperty.call(fm, 'next_step') ? JSON.stringify(fm.next_step ?? null) : undefined;
+}
+
+export function planChangesSince(planRepoPath, since, config) {
+  const when = since ? new Date(since) : null;
+  if (!when || Number.isNaN(when.getTime())) return null;
+  const abs = path.resolve(config.repoRoot, planRepoPath);
+  if (!existsSync(abs)) return null;
+  const sinceIso = when.toISOString();
+
+  const tracked = !isGitIgnored(abs, config.repoRoot) && git(['ls-files', '--error-unmatch', '--', planRepoPath], config.repoRoot) !== null;
+  if (!tracked) {
+    // Not in git (a gitignored planning tree): the file's own clock is all there is.
+    return { plan: planRepoPath, since: sinceIso, tracked: false, commits: [], modifiedAfter: statSync(abs).mtime > when, nextStepChanged: null };
+  }
+
+  const log = git(['log', '--oneline', `--since=${sinceIso}`, '--', planRepoPath], config.repoRoot);
+  const commits = log ? log.split('\n').filter(Boolean) : [];
+  const current = nextStepOf(readFileSync(abs, 'utf8'));
+  let nextStepChanged = null;
+  const base = git(['log', '-1', '--format=%H', `--before=${sinceIso}`, '--', planRepoPath], config.repoRoot)?.trim();
+  if (base) {
+    const then = git(['show', `${base}:${planRepoPath}`], config.repoRoot);
+    if (then !== null) nextStepChanged = nextStepOf(then) !== current;
+  }
+  return { plan: planRepoPath, since: sinceIso, tracked: true, commits, nextStepChanged };
+}
+
+export function formatPlanChanges(changes) {
+  if (!changes) return [];
+  const lines = [];
+  if (!changes.tracked) {
+    lines.push(changes.modifiedAfter
+      ? `→ ${changes.plan} was edited after this prompt was written (${changes.since}); it is not in git, so read it for what changed before acting on the prompt.`
+      : `→ ${changes.plan} has not been edited since this prompt was written (${changes.since}).`);
+    return lines;
+  }
+  if (changes.commits.length === 0) {
+    lines.push(`→ ${changes.plan} has no commits since this prompt was written (${changes.since}).`);
+  } else {
+    const n = changes.commits.length;
+    lines.push(`→ ${changes.plan} changed in ${n} commit${n === 1 ? '' : 's'} since this prompt was written (${changes.since}); the prompt may be stale where they touch it:`);
+    for (const commit of changes.commits.slice(0, SHOWN_COMMITS)) lines.push(`    ${commit}`);
+    if (n > SHOWN_COMMITS) lines.push(`    +${n - SHOWN_COMMITS} more: git log --oneline --since=${changes.since} -- ${changes.plan}`);
+  }
+  if (changes.nextStepChanged === true) lines.push('  next_step changed since then: where the prompt and the plan disagree, the plan is newer.');
+  else if (changes.nextStepChanged === false) lines.push('  next_step is unchanged since then.');
+  return lines;
+}

package/src/prompts.mjs

@@ -17,6 +17,7 @@ import {
 } from './pickup.mjs';
 import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
+import { formatPlanChanges, planChangesSince } from './plan-changes.mjs';
 
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
@@ -234,6 +235,10 @@ export function resolvePromptInput(input, config, options = {}) {
 
   const byBasename = prompts.filter(d => path.basename(d.path, '.md') === slug);
   if (byBasename.length === 1) return path.resolve(config.repoRoot, byBasename[0].path);
+  // A name session start lists is the live prompt; its consumed copies under
+  // archived/ share the basename and are reached by path.
+  const live = byBasename.filter(d => d.status !== 'archived' && !isArchivedPath(d.path, config));
+  if (live.length === 1) return path.resolve(config.repoRoot, live[0].path);
   if (byBasename.length > 1) {
     die(`Multiple prompts match "${input}" by basename:\n${byBasename.map(d => '  ' + d.path).join('\n')}`);
   }
@@ -345,6 +350,12 @@ export async function consumePrompt(filePath, config, opts) {
   }
   if (claimSkipReason) process.stderr.write(`${yellow('→ Not claimed')}: ${claimSkipReason}\n`);
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
+  if (planRef) {
+    try {
+      const linked = linkedClaim?.repoPath ?? linkedPlanRepoPath(planRef, filePath, config);
+      for (const line of formatPlanChanges(linked ? planChangesSince(linked, asString(parsed.created), config) : null)) process.stderr.write(`${line}\n`);
+    } catch { /* what changed is advice; the consume already happened */ }
+  }
   const ownershipRecordPath = linkedClaim?.prepared?.recordPath ?? (linkedClaim ? readPlanOwnership(linkedClaim.repoPath, config)?.recordPath : null);
   const ownershipPath = ownershipRecordPath ? toRepoPath(ownershipRecordPath, config.repoRoot) : null;
   const normalize = candidate => path.isAbsolute(candidate) ? toRepoPath(candidate, config.repoRoot) : candidate.split(path.sep).join('/');
@@ -373,6 +384,11 @@ export async function consumePrompt(filePath, config, opts) {
   };
 }
 
+function linkedPlanRepoPath(planRef, promptPath, config) {
+  const abs = resolveRefPath(planRef, path.dirname(promptPath), config.repoRoot);
+  return abs && existsSync(abs) ? toRepoPath(abs, config.repoRoot) : null;
+}
+
 export async function writeConsumedBody(body, archivedPath, write = null, linkedPlan = null) {
   const content = body.endsWith('\n') ? body : `${body}\n`;
   try {