runlist 0.99.1 → 0.100.0

package/src/host-integration.mjs

@@ -113,6 +113,11 @@ export function opencodeStatus(opts = {}) {
   const installed = generated?.version ?? oldGenerated?.version ?? null;
   const legacyGenerated = Boolean(oldGenerated);
   const legacyBanner = generated?.marker === LEGACY_GENERATED_MARKER || oldGenerated?.marker === LEGACY_GENERATED_MARKER;
+  let sourceParity = { state: 'unknown' };
+  if (installed && !legacyBanner && !legacyGenerated) {
+    try { sourceParity = { state: readFileSync(filePath, 'utf8') === renderOpencodePlugin(version ?? installed) ? 'match' : 'mismatch' }; }
+    catch { /* An unreadable file cannot establish parity. */ }
+  }
   return {
     path: filePath,
     legacyPath,
@@ -121,7 +126,8 @@ export function opencodeStatus(opts = {}) {
     // Generated legacy files migrate to runlist.js. Unmarked files remain user-owned.
     foreign: (currentExists && !generated) || (!currentExists && oldExists && !oldGenerated),
     foreignPath: currentExists && !generated ? filePath : oldExists && !oldGenerated ? legacyPath : null,
-    stale: installed !== null && ((version !== undefined && installed !== version) || legacyBanner || legacyGenerated),
+    sourceParity,
+    stale: installed !== null && ((version !== undefined && installed !== version) || legacyBanner || legacyGenerated || sourceParity.state !== 'match'),
     legacyBanner,
     legacyGenerated,
   };

package/src/hud.mjs

@@ -1,8 +1,9 @@
+import { maskInlineCodeSpans } from './markdown-code-spans.mjs';
 import { flagsHudLine, openFlags } from './flags.mjs';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { asString, currentSessionId, isArchivedPath, relTime, toRepoPath } from './util.mjs';
+import { asString, currentSessionId, isArchivedPath, relTime, shellQuote, toRepoPath } from './util.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { promptDirectory } from './new.mjs';
 import { dim, yellow } from './color.mjs';
@@ -13,6 +14,7 @@ import { findOwnedPlan } from './baton.mjs';
 import { listOwnedPlans, surveyOwnershipClaims } from './pickup.mjs';
 import { handoffNotDoneLine, pendingHandoffsForSession } from './handoff-record.mjs';
 import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
+import { handoffsAnchor, isHandoffsMode, wouldCreateHandoffsConfig } from './handoffs-mode.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
 
@@ -80,12 +82,14 @@ export function findActionablePromptsInPromptDir(config) {
 export function buildHudFast(config) {
   let prompts = [];
   let owned = null;
+  let hasOwnedPlans = true; // Unknown ownership must not advertise a fresh session.
   try { prompts = findActionablePromptsInPromptDir(config); } catch { /* hud must not fail */ }
   try {
     const records = listOwnedPlans(config);
+    hasOwnedPlans = records.length > 0 || Boolean(records.diagnostics?.length);
     if (!records.diagnostics?.length && records.length === 1) owned = { path: records[0].plan, title: null, via: 'ownership' };
   } catch { /* hud must not fail */ }
-  return { owned, prompts, misuseRecap: buildMisuseRecap(config), deadClaimsLine: deadClaimsHudLine(config) };
+  return { owned, hasOwnedPlans, prompts, misuseRecap: buildMisuseRecap(config), deadClaimsLine: deadClaimsHudLine(config) };
 }
 
 // A claim whose session is provably gone wedges `set`, `archive` and `baton` on
@@ -213,7 +217,7 @@ const MISUSE_CORRECTIONS = {
   'edit-status': 'never hand-edit `status:`; use `runlist set <status> <file>`',
   'cat-prompt': 'consume prompts with `runlist use <file>`; peek without consuming via `runlist prompts show <file>`',
   'read-prompt': 'consume prompts with `runlist use <file>`; peek without consuming via `runlist prompts show <file>`',
-  'commit-prompt': 'saved prompts are session-local; never git add/commit them',
+  'commit-prompt': 'follow the project prompt Git policy: `runlist config get promptTracking`',
 };
 
 export function buildMisuseRecap(config, now = Date.now()) {
@@ -292,10 +296,18 @@ export function buildHud(config) {
 // again and again: the read verbs, the three wrong-moves the guard exists to
 // stop, and a pointer for the rare child handoff. Statuses are not listed —
 // `runlist set` names the valid ones when given a wrong one.
+// Handoffs-only projects have no plans and no status lines to guard; a child
+// needs only the prompt rules and its own handoff form.
+const HANDOFFS_SUBAGENT_PRIMER = [
+  'runlist keeps session handoffs (saved prompts) here; planning is off.',
+  'Do NOT cat/read a saved prompt file (`runlist prompts show <name>` peeks, `runlist use <name>` consumes); follow `runlist config get promptTracking` for Git.',
+  'Return completed results to the parent. Unfinished handoff: `runlist baton --subagent <task-slug> @<draft-file> --parent resume-<parent>`.',
+].join('\n');
+
 const SUBAGENT_PRIMER = [
-  'runlist manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter). Read a plan or long doc with `runlist show <file>` (outline and open boxes with line numbers), then `runlist show <file> --section "<heading>"`, never whole. Orient: `runlist plans`.',
-  'Do NOT: cat/read a docs/prompts/*.md (use `runlist use <file>`); git add/commit a prompt (session-local); hand-edit a `status:` field (use `runlist set <status> <file>`).',
-  'Handing work back as a saved prompt: `runlist baton --subagent <task-slug> @<draft-file>` (`runlist help baton` for --parent and --template).',
+  'runlist manages plans/docs/prompts. Orient: `runlist plans`. Read: `runlist show <file>`, then `runlist show <file> --section "<heading>"`, never whole.',
+  'Do NOT: cat/read a docs/prompts/*.md (`runlist prompts show <name>` peeks, `runlist use <name>` consumes); ignore promptTracking (`runlist config get promptTracking`); hand-edit status (`runlist set <status> <file>`).',
+  "Return completed results to the parent. Unfinished handoff: `runlist baton --subagent <task-slug> @<draft-file> --parent resume-<parent>`. Use a distinct non-plan slug under a parent-owned plan; preserve its claim. `runlist baton --template` prints an outline; inspect a pending prompt before --replace.",
 ].join('\n');
 
 // The plugin's SessionStart/SubagentStart hooks fire in EVERY repo (it's enabled
@@ -315,9 +327,32 @@ const SUBAGENT_PRIMER = [
 // 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 HANDOFF_PHRASE = /\bhand[\s-]?off\b|\bresume[\s-]prompt\b|\bsave (?:a |the )?resume\b|\bpick (?:it|this|that) (?:back )?up (?:next time|next session|later|tomorrow)\b/i;
+const LEAD_WORDS = String.raw`(?:(?:ok(?:ay)?|alright|right|anyway|hey|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 SESSION_REQUEST_START = String.raw`(?:^|,\s*)${LEAD_WORDS}${POLITE}?(?:(?:I want to|let'?s|lets|please) )?`;
+// Save forms name the session's work and a continuation time, or explicitly
+// end the workday. "Save where we are" is itself a session snapshot request;
+// require a request at the clause start, including after a context-setting
+// comma, and a clause end (also before a semicolon continuation).
+// Keep the suffixes narrow: progress indicators and session objects are code.
+const SESSION_SAVE = [
+  new RegExp(String.raw`${SESSION_REQUEST_START}save where we are\s*[.!?;]?$`, 'i'),
+  /\bsave (?:where we are|our progress) (?:for (?:later|tomorrow|now|today|next (?:time|session))|so (?:I|we) can continue (?:later|tomorrow|next (?:time|session)))\b/i,
+  new RegExp(String.raw`${SESSION_REQUEST_START}wrap up for (?:today|the day|tonight)\s*[.!?;]?$`, 'i'),
+  /\bstop here for now(?: and|,)? (?:continue|pick (?:it|this) up) (?:tomorrow|later|next (?:time|session))\s*[.!?;]?$/i,
+  new RegExp(String.raw`${SESSION_REQUEST_START}stop (?:here )?for (?:today|the day|tonight)\s*[.!?;]?$`, 'i'),
+  /\b(?:let'?s|lets|I think we can) call it a day\s*[.!?;]?$/i,
+  /\b(?:we'll|we will|I'll|I will|let'?s|lets) continue (?:in (?:a |the )?new session|(?:this )?tomorrow)\s*[.!?;]?$/i,
+  new RegExp(String.raw`${SESSION_REQUEST_START}save where we're at for tomorrow\s*[.!?;]?$`, 'i'),
+  new RegExp(String.raw`${SESSION_REQUEST_START}(?:let'?s|lets) pause here and continue tomorrow\s*[.!?;]?$`, 'i'),
+];
+// Strip all explicit load/resume forms before the broad handoff save matcher.
+const LOAD_HANDOFF = String.raw`\b(?:load|resume|open|use) (?:my|the|our|that) handoff\b`;
+// A continuation can start another clause with "and then". Other words after
+// stopped/left off describe code or another activity, rather than saved work.
+const PICKUP_END = String.raw`(?: (?:yesterday|last (?:time|session))(?!'s)\b)?(?=\s*(?:$|[.!?;,]|and then\b))`;
+const PICKUP_PHRASE = String.raw`(?:(?:pick up|continue|resume) (?:from )?where (?:we|I|you) (?:left off|stopped)\b${PICKUP_END}|(?:continue|resume|pick up) from (?:last (?:time|session)|yesterday)(?!'s)\b|${LOAD_HANDOFF}(?=\s*(?:$|[.!?;,]|and\b)))`;
 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.
@@ -326,21 +361,66 @@ 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'),
+  new RegExp(String.raw`\bcontext is getting tight,\s+(?:please )?baton\b${NOT_A_VERB}`, '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/;
+const SYSTEM_EVENT = /\[SYSTEM NOTIFICATION\b/i;
+const T3_RELAY_HEADER = /^[ \t]*Delegated task \S+(?: \([^\n]*?\))?(?: \[[a-z_]+\]| reached a terminal state)[:.]/im;
+// This question explicitly asks to recover earlier work, rather than asking
+// how the handoff mechanism works. Other question-led clauses stay silent.
+const PICKUP_QUESTION = new RegExp(String.raw`^${LEAD_WORDS}(?:hmm[,\s]+)?(?:what was I working on (?:in the )?last session|where were we)[?.!]*$`, 'i');
+const PICKUP_REQUEST = new RegExp(String.raw`^${LEAD_WORDS}${POLITE}?(?:please )?${PICKUP_PHRASE}`, 'i');
+
+function requestText(prompt) {
+  if (typeof prompt !== 'string' || SYSTEM_EVENT.test(prompt)) return '';
+  prompt = prompt.replaceAll('’', "'");
+  prompt = prompt.replace(/<task-notification\b[^>]*>[\s\S]*?<\/task-notification>/gi, ' ');
+  let fence = null;
+  const prose = prompt.split('\n').map(line => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+    if (fence) {
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length
+          && /^\s*$/.test(line.slice(line.indexOf(marker) + marker.length))) fence = null;
+      return '';
+    }
+    if (marker) { fence = marker; return ''; }
+    if (/^(?: {4}|\t)|^ {0,3}>/.test(line)) return '';
+    return line;
+  }).join('\n');
+  // T3 reports can contain blank lines and further relay headers. Everything
+  // from the first prose header onward belongs to the relay; only prior prose
+  // is the user's. A header inside code or a quote is not a relay envelope.
+  // Claude notifications have explicit closing tags instead.
+  const relay = T3_RELAY_HEADER.exec(prose);
+  const userProse = relay ? prose.slice(0, relay.index) : prose;
+  return maskInlineCodeSpans(userProse).replace(/"[^"\n]*"/g, ' ');
+}
 
 function clauses(prompt) {
   return prompt.split(/(?<=[.!?;\n])/).map(clause => clause.trim()).filter(Boolean);
 }
 
 export function isHandoffAsk(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)));
+  return clauses(requestText(prompt)).some(clause => !QUESTION_START.test(clause)
+    && (BATON_REQUEST.some(re => re.test(clause)) || SESSION_SAVE.some(re => re.test(clause))
+      // A request to load a handoff is the opposite of saving one.
+      || HANDOFF_PHRASE.test(clause.replace(new RegExp(LOAD_HANDOFF, 'gi'), ''))));
+}
+
+// Before a repository has any runlist config the hook only answers an explicit
+// request to save the session: a baton, or one of the session-save phrases. The
+// bare word "handoff" is common in code, and nothing here is runlist's yet.
+export function isExplicitSaveAsk(prompt) {
+  return clauses(requestText(prompt)).some(clause => !QUESTION_START.test(clause)
+    && (BATON_REQUEST.some(re => re.test(clause)) || SESSION_SAVE.some(re => re.test(clause))));
+}
+
+export function isPickupAsk(prompt) {
+  return clauses(requestText(prompt)).some(clause => PICKUP_QUESTION.test(clause)
+    || (!QUESTION_START.test(clause) && PICKUP_REQUEST.test(clause)));
 }
 
 // The repo's own definition of baton (`templates.prompt.baton` in its config),
@@ -351,7 +431,21 @@ export function repoBatonDefinition(config) {
   return typeof text === 'string' && text.trim() ? text.trim() : null;
 }
 
+const RESUME_DRAFT = 'Write the resume first (current work and exact next move, decisions and waiting approvals, durable evidence paths, unverified claims and authorization boundaries; not a recap). `runlist baton --template` prints the checkout’s editable outline. Draft in a temporary file; keep working material at durable repo-relative paths.';
+const BATON_TAIL = 'Baton prints the prompt name it saved as its last line; tell the user that name. No `--help` needed.';
+
+// Handoffs only — a repository with no config yet, or one in handoffs mode —
+// has no plans, so the form is always a name the session picks itself.
+export function buildHandoffsOnlyContext(config, { firstHandoff = false } = {}) {
+  const command = 'Save it with `runlist baton <slug> @<file>`, choosing a short slug that names the work (it saves resume-<slug>).';
+  const first = firstHandoff ? ' There is no runlist config here yet: baton also sets one up for handoffs (runlist.config.mjs, prompts in docs/prompts/) unless it finds runlist documents saved before setup, and prints what it did; relay that.' : '';
+  const definition = repoBatonDefinition(config);
+  if (definition) return `[runlist] Baton: ${command}${first} Where the definition below names a command, use this form. ${BATON_TAIL}\nThis repo defines baton (templates.prompt.baton in its runlist config):\n${definition}`;
+  return `[runlist] Baton: ${RESUME_DRAFT} ${command}${first} ${BATON_TAIL}`;
+}
+
 export function buildHandoffContext(config) {
+  if (isHandoffsMode(config)) return buildHandoffsOnlyContext(config);
   // Ownership records name their plans and are checked against those files
   // alone; building the index here cost 9s in a repo of ~5k docs, past the
   // hook's timeout.
@@ -360,43 +454,66 @@ 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 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';
+  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 body first, then run';
   let who;
   let command;
   if (ownedPaths.length === 1) {
     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\`.`;
+    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 --next-step "<next move>"\`.`;
   } 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>\`.`;
+    command = `Save it with \`runlist baton <plan-file> @<file>\`. ${done} \`runlist baton --done <plan-file> --next-step "<next move>"\`.`;
   } 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.';
   }
-  const tail = 'Baton prints the prompt name it saved as its last line; tell the user that name. No `--help` needed.';
+  const tail = BATON_TAIL;
   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}`;
   }
-  const draft = 'Write the resume first (current work and exact next move, decisions and waiting approvals, durable evidence paths, unverified claims and authorization boundaries; not a recap). `runlist baton --template` prints the checkout’s editable outline. Draft in a temporary file; keep working material at durable repo-relative paths.';
-  return `[runlist] Baton: ${who} ${draft} ${command} ${tail}`;
+  return `[runlist] Baton: ${who} ${RESUME_DRAFT} ${command} ${tail}`;
 }
 
-export async function runPromptSubmitHud(config, { readStdin } = {}) {
-  if (!isRunlistRepo(config)) return;
+export async function runPromptSubmitHud(config, { readStdin, cwd = process.cwd() } = {}) {
+  // With no config, only a Git project can take a first handoff (baton refuses
+  // elsewhere); everything else stays silent, as in any repo runlist isn't in.
+  const configured = isRunlistRepo(config);
+  if (!configured && handoffsAnchor(cwd).refusal) return;
   let prompt = '';
   try {
     const raw = await readStdin();
     if (raw && raw.trim()) prompt = JSON.parse(raw).prompt ?? '';
   } catch { return; }
-  if (!isHandoffAsk(prompt)) return;
-  process.stdout.write(buildHandoffContext(config) + '\n');
+  if (!configured) {
+    if (!isExplicitSaveAsk(prompt)) return;
+    // Plans claimed before any config exist only where someone planned without
+    // setup; the claim records are the cheap way to know, as in a configured repo.
+    let owns = false;
+    try { owns = listOwnedPlans(config).length > 0; } catch { /* no claims to read */ }
+    process.stdout.write((owns ? buildHandoffContext(config) : buildHandoffsOnlyContext(config, { firstHandoff: wouldCreateHandoffsConfig(cwd, config) })) + '\n');
+    return;
+  }
+  // Saving wins when both intents are explicit: save now, resume later.
+  if (isHandoffAsk(prompt)) {
+    process.stdout.write(buildHandoffContext(config) + '\n');
+  } else if (isPickupAsk(prompt)) {
+    let prompts;
+    try { prompts = findActionablePromptsInPromptDir(config); } catch { return; }
+    if (prompts.length) process.stdout.write(`[runlist] Pickup: ${pendingPromptsLine(prompts, { pickup: true, planning: !isHandoffsMode(config) })}\n`);
+  }
 }
 
 // A count, not names: a queue of dozens printed a dozen names nobody asked
 // about, and `runlist prompts` lists them when the user names one.
-export function pendingPromptsLine(prompts) {
+export function pendingPromptsLine(prompts, { pickup = false, planning = true } = {}) {
   const n = prompts.length;
+  if (pickup) {
+    const names = n <= 5 ? ` (${prompts.join(', ')})` : '';
+    const entry = hasPickupCommand() ? '`/pickup` or `runlist use <name>`' : '`runlist use <name>`';
+    const effect = planning ? 'archives the prompt and claims its linked plan' : 'archives the prompt and prints it';
+    return `If the user is asking to resume saved work: ${n} pending prompt${n === 1 ? '' : 's'}${names}; ${entry} consumes one (${effect}).${n > 1 ? ' Ask which one; never consume the oldest by default.' : ''}`;
+  }
   return `${n} pending prompt${n === 1 ? '' : 's'}: resume one only when the user asks for it (\`runlist prompts\` lists them, \`runlist use <name>\` resumes one, \`runlist prompts show <name>\` peeks); never consume the oldest by default.`;
 }
 
@@ -404,6 +521,30 @@ function isRunlistRepo(config) {
   return Boolean(config?.configFound);
 }
 
+function hasPickupCommand() {
+  // Codex also exports CLAUDE_PLUGIN_ROOT for compatible hooks, but its plugin
+  // has no slash commands. Offer the command only when it is actually shipped.
+  const root = process.env.CLAUDE_PLUGIN_ROOT;
+  return Boolean(root?.trim() && existsSync(path.join(root, 'commands', 'pickup.md')));
+}
+
+// Directory entries only: any Markdown file is history, including held and
+// archived prompts. Resolve the type directory via the same loader as hud;
+// recursive listing includes config.archiveDir without assuming its spelling.
+function handoffIntroLine(config, hud) {
+  // OpenCode injects hud into its system prompt every turn (plugin.js),
+  // including when RUNLIST_SESSION_ID overrides the host's identity source.
+  if (process.env.OPENCODE || process.env.OPENCODE_PID || hud.prompts.length || hud.hasOwnedPlans) return null;
+  try {
+    const dir = promptDirectory(config);
+    if (existsSync(dir) && readdirSync(dir, { withFileTypes: true, recursive: true })
+      .some(entry => entry.isFile() && entry.name.endsWith('.md'))) return null;
+  } catch { return null; } // Unreadable history cannot establish a fresh repo.
+  const pickup = hasPickupCommand()
+    ? '/pickup resumes it next time' : 'the next session lists saved handoffs at start';
+  return `[runlist] Handoffs: say "baton" to save where you are before you stop; ${pickup}.`;
+}
+
 export function runHud(argv, config) {
   const json = argv.includes('--json');
 
@@ -415,7 +556,7 @@ export function runHud(argv, config) {
   // need the operator-facing machinery, just the verbs and the guardrails.
   if (argv.includes('--subagent')) {
     if (!runlistRepo) return; // silent in repos that don't use runlist
-    process.stdout.write(dim(SUBAGENT_PRIMER) + '\n');
+    process.stdout.write(dim(isHandoffsMode(config) ? HANDOFFS_SUBAGENT_PRIMER : SUBAGENT_PRIMER) + '\n');
     if (drift) process.stdout.write(yellow(drift) + '\n');
     return;
   }
@@ -433,8 +574,8 @@ export function runHud(argv, config) {
   const hud = buildHudFast(config);
 
   // SessionStart contract: ONLY signals that carry a direct instruction for
-  // this session, and nothing at all in a clean repo. No command sheet and no
-  // status list: the runlist skill carries the verbs, and `runlist set` names
+  // this session, plus a one-line introduction until the first handoff. No
+  // command sheet or status list: the runlist skill carries the verbs, and `runlist set` names
   // the valid statuses when given a wrong one. Passive state (error counts,
   // previous-self / fleet / recent-rejections) stays suppressed — it nudged
   // agents into phantom follow-up work and lives in its own commands and
@@ -450,6 +591,8 @@ export function runHud(argv, config) {
   //     Global in-session counts never provide a fallback.
   //   - an unfinished handoff, a repeat-offense misuse rule, and plans held by
   //     sessions that are gone: each names the command that clears it.
+  const intro = handoffIntroLine(config, hud);
+  if (intro) process.stdout.write(dim(intro) + '\n');
   const queue = [];
   if (hud.prompts.length > 0) queue.push(pendingPromptsLine(hud.prompts));
   const flagsLine = flagsHudLine(config);
@@ -459,9 +602,11 @@ export function runHud(argv, config) {
     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');
+  // between saving the prompt and updating the plan). Where planning is off
+  // there is no plan to update: a record carried in from before stays on disk
+  // for `runlist setup`, and the hook asks for nothing it cannot do.
+  if (!isHandoffsMode(config)) try {
+    for (const record of pendingHandoffsForSession(config)) process.stdout.write(yellow(`[runlist] ${handoffNotDoneLine(record, `runlist baton --done ${shellQuote(record.plan)}`)}`) + '\n');
   } catch { /* advisory */ }
   if (hud.misuseRecap) process.stdout.write(yellow(`[runlist] ${hud.misuseRecap}`) + '\n');
   if (hud.deadClaimsLine) process.stdout.write(yellow(hud.deadClaimsLine) + '\n');

package/src/index.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
 import { findLexicalDocsRoot } from './managed-path.mjs';
+import { managesFile, outsideHandoffs, outsideHandoffsLine } from './handoffs-scope.mjs';
 import { openParseCache, fileStamp, stampSize } from './parse-cache.mjs';
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, checkRoadmapHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
@@ -233,7 +234,9 @@ export function collectDocFiles(config, { onError = null } = {}) {
   for (const root of roots) {
     walkMarkdownFiles(root, files, config.excludeDirs, skipPaths, seen, onError);
   }
-  return files.sort((a, b) => a.localeCompare(b));
+  // Every scanning verb collects here, so a handoffs-only project's other
+  // Markdown (src/handoffs-scope.mjs) drops out of all of them at once.
+  return files.filter(file => managesFile(file, config)).sort((a, b) => a.localeCompare(b));
 }
 
 // Shared resolver for CLI file arguments — the single path every file-taking
@@ -248,10 +251,10 @@ export function collectDocFiles(config, { onError = null } = {}) {
 export function resolveDocArg(input, config, { dieOnMiss = true } = {}) {
   if (!input) return null;
   const direct = resolveDocPath(input, config);
-  if (direct) return direct;
+  if (direct && managesFile(direct, config)) return direct;
   if (!input.endsWith('.md')) {
     const withExt = resolveDocPath(input + '.md', config);
-    if (withExt) return withExt;
+    if (withExt && managesFile(withExt, config)) return withExt;
   }
 
   const slug = input.replace(/\.md$/, '');
@@ -269,7 +272,11 @@ export function resolveDocArg(input, config, { dieOnMiss = true } = {}) {
 // `File not found` + the searched roots + up-to-3 did-you-mean candidates
 // matched on basename and printed as repo-relative paths. Exported so verbs
 // with their own resolution (e.g. interactive pickers) can reuse the message.
-export function docArgMissMessage(input, config, files = collectDocFiles(config)) {
+// In a handoffs-only project a file that is not one of its prompts was not
+// mistyped, so it hears that planning is off instead (src/handoffs-scope.mjs).
+export function docArgMissMessage(input, config, files) {
+  if (outsideHandoffs(input, config)) return outsideHandoffsLine(input);
+  files ??= collectDocFiles(config);
   const roots = config.docsRoots || [config.docsRoot];
   const searched = [toRepoPath(config.repoRoot, config.repoRoot) || '.', ...roots.map(r => toRepoPath(r, config.repoRoot))].join(', ');
   const slug = String(input).split('/').pop().replace(/\.md$/, '');