runlist 0.94.1 → 0.95.0

package/README.md

@@ -46,14 +46,13 @@ Stage filters, grouping and editing are included. Optional grepmax semantic
 controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
-The previous Apple Silicon GUI was **0.94.0-rc.1**, signed and accepted by Apple.
-Its public installers have been withdrawn during a privacy cleanup. A clean
-replacement has not yet been built. Existing installations can still be opened.
-The desktop app is separate from CLI 0.94.1,
+The Apple Silicon GUI is **[0.94.1](https://github.com/reowens/runlist/releases/tag/desktop-v0.94.1)**,
+signed, accepted by Apple and stapled. It replaces the installers withdrawn
+during the privacy cleanup. The desktop app is separate from CLI 0.94.1,
 which includes optional plan-filing checks and the owner-written product yardstick,
 corrected hub-category inheritance, updates for every saved Claude plugin scope,
 and `runlist desktop install`.
-Updating the CLI does not replace the GUI's bundled engine; this GUI reports 0.94.0-rc.1.
+Updating the CLI does not replace the GUI's bundled engine; this GUI reports 0.94.1.
 Earlier development packages and their qualification results are historical;
 see the [desktop validation record](desktop/VALIDATION.md).
 
@@ -85,7 +84,7 @@ Deferred work awaiting selection:
    older distributions, real-version upgrades, fresh/minimum-version and Intel
    Macs, plus native rendering, focus, accessibility and whole-window memory.
 
-Mac GUI downloads are temporarily unavailable pending a clean replacement.
+Mac GUI 0.94.1 is available from the [desktop release](https://github.com/reowens/runlist/releases/tag/desktop-v0.94.1).
 CLI 0.94.1 includes the optional product yardstick.
 The supported desktop
 release is Apple Silicon macOS 13.5 or newer. Broader platform work and
@@ -96,11 +95,11 @@ command-line tools. The published Node.js CLI remains cross-platform.
 
 ### Optional desktop GUI
 
-The CLI works on its own. Public GUI downloads are temporarily unavailable
-during a privacy cleanup; a clean replacement has not yet been built. On an
-Apple Silicon Mac (macOS 13.5 or newer), open an existing installation with:
+The CLI works on its own. On an Apple Silicon Mac (macOS 13.5 or newer),
+install the optional GUI and open it with:
 
 ```bash
+runlist desktop install
 runlist desktop
 ```
 
@@ -110,8 +109,8 @@ without opening it. The app bundles its runtime and reads local files through
 private pipes, with no listening server. Choose your checkout folder in the app.
 No checkout configuration is loaded by these CLI commands.
 
-The GUI is versioned separately from the CLI. There is currently no public Mac
-installer available to `runlist desktop install`.
+The GUI is versioned separately from the CLI. `runlist desktop install` selects
+the public Mac 0.94.1 installer.
 Windows, Linux and Intel Mac GUI downloads are not yet available through this
 command. An existing app is kept as-is. To replace it using a downloaded signed
 DMG, quit Runlist and run:
@@ -274,7 +273,7 @@ needs no installed Node, browser access link or listening server. CLI 0.92.0 pro
 The GUI remains optional:
 
 ```bash
-runlist desktop install                 # requires an available public installer
+runlist desktop install                 # install the public Mac GUI
 runlist desktop                         # open the installed GUI
 runlist desktop install --from /path/to/Runlist.dmg  # install a local signed DMG
 ```
@@ -283,12 +282,11 @@ The installer currently supports Apple Silicon Macs. It verifies the published
 download checksum, Runlist developer signature and Apple approval, and installs
 without opening the app. An existing app is kept unless `--from` supplies a
 replacement; replacement keeps a rollback copy. `--dry-run` uses no network and
-changes no files. Public Mac downloads have been withdrawn during a privacy
-cleanup; a clean replacement is pending. `--from` still works with a local
-approved installer. These commands ship
+changes no files. The public Mac 0.94.1 download replaces the withdrawn
+installers. These commands ship
 in [CLI 0.92.0](https://github.com/reowens/runlist/releases/tag/v0.92.0) and can also
 be used from this checkout as `node bin/runlist.mjs desktop …`. The GUI remains
-separately versioned at **0.94.0-rc.1**; npm installation does not download it.
+separately versioned at **0.94.1**; npm installation does not download it.
 
 The optional browser document app is available from this source checkout (unreleased):
 
@@ -830,14 +828,14 @@ local model or server. GUI controls are implemented in the source checkout:
 Product goal shows the saved statement, delivery and assessment, with reviewed
 Serves/Clear/Close/Fold actions and retained recovery. Structured plans display
 the comparison with an explanation when assessment changes are unavailable.
-These controls are included in the public desktop package 0.94.0-rc.1;
+These controls are included in the public desktop package 0.94.1;
 updating the CLI alone does not replace an existing app.
 
 ### Plan Homes And Filing Checks
 
 This policy is available in CLI 0.93.0. From a source checkout, invoke the
 commands below as `node bin/runlist.mjs …`. The separately versioned GUI
-0.94.0-rc.1 also includes a read-only Filing view. The correction
+The desktop app also includes a read-only Filing view. The correction
 for category inheritance from status-less hub indexes is included in CLI
 0.93.1.
 
@@ -882,7 +880,7 @@ is labeled and suppresses absence/uniqueness findings. Path/type-scoped output
 keeps the full hub/ancestor evidence while reporting only selected plans.
 The source checkout also includes a read-only Filing view: open it to scan,
 filter 50-plan pages, and inspect exact hub rows in 20-row evidence pages. Saved
-edits invalidate the report. This view is included in public desktop package 0.94.0-rc.1.
+edits invalidate the report. This view is included in public desktop package 0.94.1.
 The policy is off when `filing` is unset, false, or `{ enabled: false }`.
 It can replace a repository's older “any link counts” coverage script once
 that repository enables it and retires its custom check.

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.1",
+  "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.1",
+  "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/hub.mjs

@@ -25,6 +25,10 @@ export function isCoordinationHub(doc) {
   // use to promote a roadmap above the Runlists section; here a roadmap counts as
   // a coordination hub so all the existing held-out plumbing covers it for free.
   if (doc.executionMode === 'coordination' || doc.executionMode === 'roadmap') return true;
+  // Any other declared `execution_mode` has answered: the name is only a fallback
+  // for hubs that predate the field, so a plan ABOUT runlists that declares
+  // `implementation` stays a plan. Same rule as the slug nudge in validate.mjs.
+  if (doc.executionMode) return false;
   const base = (doc.path.split('/').pop() || '').replace(/\.md$/, '');
   return base === 'runlist' || base.endsWith('-runlist');
 }

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 {

package/src/public-inspection.mjs

@@ -0,0 +1,19 @@
+// Neutral publication checks; no private vocabulary or credentials.
+export const PRIVATE_ROOT = /^(?:docs|\.runlist|\.dotmd|\.gmax|\.claude\/logs|desktop\/releases)(?:\/|$)/;
+export const CREDENTIAL_FILE = /(?:^|\/)(?:\.env(?:\..*)?|\.npmrc|[^/]*\.(?:pem|p12|pfx|key))$/;
+
+
+export function inspectBaselineText(text, file) {
+  const findings = [];
+  const fixture = /^(?:test|desktop\/test)\//.test(file);
+  for (const [index, line] of text.split('\n').entries()) {
+    const paths = line.match(/\/(?:Users|home)\/[a-z0-9._-]+/g) ?? [];
+    if (paths.some(value => !fixture || !/\/(?:test|me|u|user|example)$/i.test(value))) {
+      findings.push({ file, line: index + 1, category: 'personal absolute path' });
+    }
+    if (file.endsWith('.json') && !fixture && /"email"\s*:/.test(line)) {
+      findings.push({ file, line: index + 1, category: 'contact address in public metadata' });
+    }
+  }
+  return findings;
+}

package/src/validate.mjs

@@ -540,6 +540,7 @@ export function checkRoadmapHubExecutionMode(docs, config) {
     if (!d) return false;
     if (d.executionMode === 'coordination' || d.executionMode === 'roadmap') return true;
     if (Array.isArray(d.refFields?.runlist) && d.refFields.runlist.length > 0) return true;
+    if (d.executionMode) return false;
     const b = (d.path.split('/').pop() || '').replace(/\.md$/, '');
     return b === 'runlist' || b.endsWith('-runlist');
   };