runlist 0.96.0 → 0.97.0

package/src/hud.mjs

@@ -12,7 +12,7 @@ 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';
+import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
 
@@ -286,39 +286,18 @@ export function buildHud(config) {
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
-// with ZERO project context and no SessionStart history — it has never seen the
-// command sheet the top-level session got. Without this, subagents reflexively
-// grep/cat/commit managed docs instead of using runlist. Keep it to a few dense
-// lines: the verbs + the three wrong-moves the guard exists to stop, so the
-// subagent self-corrects before the guard ever has to fire.
+// with ZERO project context and no SessionStart history. Without this,
+// subagents reflexively grep/cat/commit managed docs instead of using runlist.
+// It fires on every SubagentStart and CwdChanged, so every byte here is paid
+// 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.
 const SUBAGENT_PRIMER = [
-  'runlist manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter).',
-  'Verbs: plans|briefing | query <filters> | use [<file>] | set <status> <file> | new <type> <slug> | archive <file>.',
-  'Child handoff: `runlist baton --subagent <task-slug> @<draft-file>` saves subagent-<task-slug>. Use a task slug under a parent-owned plan; release only your own plan. Parent batons default to resume-<name>.',
-  'Claims: `runlist doctor --claims` lists which session holds each plan; `--apply` releases the ones whose session is gone.',
-  'Do NOT: cat/read a docs/prompts/*.md (use `runlist use <file>` — archive/claim commits before at-most-once output);',
-  'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `runlist set`).',
+  '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).',
 ].join('\n');
 
-export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
-  const statuses = (resolveStatusMetadata(config).byType.plan ?? []).map(item => item.name);
-  const fallback = 'run `runlist statuses list --type plan`';
-  if (statuses.length === 0) return `Plan statuses unavailable; ${fallback}.`;
-  const prefix = 'Plan statuses: ';
-  const full = `${prefix}${statuses.join(', ')}`;
-  if (full.length <= maxChars) return full;
-
-  const shown = [];
-  for (const status of statuses) {
-    const omitted = statuses.length - shown.length - 1;
-    const candidate = `${prefix}${[...shown, status].join(', ')}, ... (+${omitted}; ${fallback})`;
-    if (candidate.length > maxChars) break;
-    shown.push(status);
-  }
-  const omitted = statuses.length - shown.length;
-  return `${prefix}${shown.join(', ')}${shown.length ? ', ' : ''}... (+${omitted}; ${fallback})`;
-}
-
 // The plugin's SessionStart/SubagentStart hooks fire in EVERY repo (it's enabled
 // globally), but the primer only helps where runlist is actually used. Gate on a
 // discovered config: `runlist init` writes runlist.config.mjs, so "has a config" is
@@ -399,7 +378,7 @@ export function buildHandoffContext(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 (the next concrete decision, any gotchas, the plan/doc paths it concerns; not a recap) to a file in your scratchpad.';
+  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}`;
 }
 
@@ -414,14 +393,11 @@ 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;
+// 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) {
   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>\`.`;
+  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.`;
 }
 
 function isRunlistRepo(config) {
@@ -440,7 +416,6 @@ export function runHud(argv, config) {
   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(buildPlanStatusPrimer(config)) + '\n');
     if (drift) process.stdout.write(yellow(drift) + '\n');
     return;
   }
@@ -457,26 +432,29 @@ export function runHud(argv, config) {
 
   const hud = buildHudFast(config);
 
-  // SessionStart contract: the command primer, plus ONLY signals that carry a
-  // direct instruction for this session. Passive state (error counts,
-  // slash-command refresh notices, previous-self / fleet / recent-rejections)
-  // stays suppressed — those nudged agents into phantom follow-up work (e.g.
-  // "errors: 1" prompting a check run) and live in their proper commands and
-  // `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: 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
+  // 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
+  // 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
+  // `runlist hud --json`. What prints:
+  //   - pending prompts, as a count: earlier sessions queued work, and the
+  //     line says to resume one only when the user asks. 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.
+  //   - open flags, as a count: the person asked that every session start
+  //     knowing where things stand. Worded as awareness, not an instruction.
   //   - 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)') + '\n');
-  process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
+  //   - an unfinished handoff, a repeat-offense misuse rule, and plans held by
+  //     sessions that are gone: each names the command that clears it.
+  const queue = [];
+  if (hud.prompts.length > 0) queue.push(pendingPromptsLine(hud.prompts));
+  const flagsLine = flagsHudLine(config);
+  if (flagsLine) queue.push(flagsLine);
+  if (queue.length) process.stdout.write(yellow(`[runlist] ${queue.join(' ')}`) + '\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');
   }
@@ -485,16 +463,7 @@ export function runHud(argv, config) {
   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(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');
-  // Open flags are the one piece of passive state printed here: the person
-  // asked that every session start knowing where things stand. It is worded
-  // as awareness, not an instruction, so no session treats it as its task.
-  const flagsLine = flagsHudLine(config);
-  if (flagsLine) process.stdout.write(yellow(flagsLine) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\n');
 }

package/src/index.mjs

@@ -426,6 +426,8 @@ export function parseDocFile(filePath, config, opts = {}) {
     path: relativePath,
     root: rootLabel,
     type: docType,
+    ...(docType === 'prompt' ? { parentPrompt: asString(parsedFrontmatter.parent_prompt) ?? null,
+      parentPromptInvalid: (Object.hasOwn(parsedFrontmatter,'parent_prompt') && typeof parsedFrontmatter.parent_prompt !== 'string') || fmWarnings.some(w=>w.message.includes('`parent_prompt`')) } : {}),
     status: asString(parsedFrontmatter.status) ?? null,
     // Preserve ships without coercing lists/objects into apparently valid stages.
     ships: parsedFrontmatter.ships ?? null,

package/src/install.mjs

@@ -9,6 +9,7 @@ import {
 } from './host-integration.mjs';
 import { LEGACY_PLUGIN_ID, readInstalledPlugin, readInstalledPluginRecords } from './update.mjs';
 import { executableName, which } from './util.mjs';
+import { installationReport, formatInstallationReport } from './installation.mjs';
 import { codexStatus, installCodexPlugin, installedCodexStatus } from './codex-integration.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -38,12 +39,13 @@ function hostStates() {
   };
 }
 
-function reportStatus(json) {
-  const states = hostStates();
+function reportStatus(json, config) {
+  const states = hostStates(), installations = installationReport(config);
   if (json) {
-    process.stdout.write(JSON.stringify({ cli: pkg.version, hosts: states }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ cli: pkg.version, hosts: states, installations }, null, 2) + '\n');
     return;
   }
+  process.stdout.write(formatInstallationReport(installations)+'\n');
   const { claude, codex, opencode } = states;
   process.stdout.write(`${bold('runlist host integrations')}  ${dim(`CLI ${pkg.version}`)}\n\n`);
 
@@ -210,7 +212,7 @@ export function runInstall(argv, _config, opts = {}) {
   const json = argv.includes('--json');
   const requested = argv.find(a => !a.startsWith('-'));
 
-  if (!requested) { reportStatus(json); return; }
+  if (!requested) { reportStatus(json, _config); return; }
   const host = ALIASES[requested] ?? requested;
   if (!HOSTS.includes(host)) {
     process.stderr.write(`Unknown host "${requested}". Known: ${HOSTS.join(', ')}\n`);

package/src/installation.mjs

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { desktopLaunch } from './desktop.mjs';
+import { codexStatus } from './codex-integration.mjs';
+import { opencodeStatus } from './host-integration.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+function json(file) { try { return JSON.parse(readFileSync(file,'utf8')); } catch { return null; } }
+function resolved(file) { try { return realpathSync(file); } catch { return null; } }
+function executable(name, env) {
+  const suffixes = process.platform === 'win32' ? ['', '.cmd', '.exe'] : [''];
+  for (const dir of (env.PATH ?? '').split(path.delimiter).filter(Boolean)) for (const suffix of suffixes) {
+    const file = path.resolve(dir,name+suffix);
+    try { if (lstatSync(file).isFile() || lstatSync(file).isSymbolicLink()) return file; } catch {}
+  }
+  return null;
+}
+
+// Hash only the shared engine inputs, never plans, state, credentials or runtime
+// binaries. Ignore the release label so a local candidate can prove code parity.
+export function sourceFingerprint(root, entries = ['package.json','src','bin','assets','desktop/helper.mjs','desktop/trust.mjs','desktop/line-framer.mjs']) {
+  try {
+    const files=[],hash=createHash('sha256');let bytes=0;
+    const visit = name => {
+      const file=path.join(root,name),stat=lstatSync(file);
+      if(stat.isSymbolicLink())throw new Error('symlink');
+      if(stat.isDirectory()) { for(const child of readdirSync(file).sort())visit(`${name}/${child}`); }
+      else if(stat.isFile()) {
+        bytes+=stat.size;if(bytes>64*1024*1024||files.length>=2000)throw new Error('limit');
+        let content=readFileSync(file);
+        if(name==='package.json'){const pkg=JSON.parse(content);delete pkg.version;content=Buffer.from(JSON.stringify(pkg));}
+        hash.update(name+'\0').update(createHash('sha256').update(content).digest());files.push(name);
+      }
+    };
+    for(const name of [...entries].sort())if(existsSync(path.join(root,name)))visit(name);
+    return files.length ? {state:'readable',sha256:hash.digest('hex'),files:files.length} : {state:'unavailable'};
+  } catch { return {state:'unreadable'}; }
+}
+
+function identity(root) {
+  const realRoot=resolved(root),pkg=realRoot&&json(path.join(realRoot,'package.json'));
+  if(!pkg||typeof pkg!=='object'||Array.isArray(pkg))return {path:root,resolvedPath:realRoot,state:existsSync(root)?'unreadable':'missing'};
+  return {path:root,resolvedPath:realRoot,state:'readable',version:pkg.version??null,
+    kind:existsSync(path.join(realRoot,'.git'))?'checkout':'package',fingerprint:sourceFingerprint(realRoot)};
+}
+
+// Shared with update; reading a host registry does not activate or modify it.
+export function readInstalledPluginRecords({home=os.homedir(),id}={}) {
+  const plugins=json(path.join(home,'.claude/plugins/installed_plugins.json'))?.plugins??{};
+  id ??= plugins['runlist@runlist']?'runlist@runlist':plugins['dotmd@dotmd']?'dotmd@dotmd':Object.keys(plugins).find(k=>/^(?:runlist|dotmd)@/.test(k));
+  if(!id||!plugins[id])return null;
+  return {id,entries:(Array.isArray(plugins[id])?plugins[id]:[plugins[id]]).filter(Boolean)};
+}
+
+export function installationReport(config={}, {root=packageRoot,home=os.homedir(),env=process.env,node=process.execPath,entry=process.argv[1],platform=process.platform,app}={}) {
+  config ??= {};
+  const cli=identity(root),nodeDirectory=path.dirname(node);
+  cli.launcher=entry?{path:path.resolve(entry),resolvedPath:resolved(path.resolve(entry))}:null;
+  const nodePrefix=path.basename(nodeDirectory)==='bin'?path.dirname(nodeDirectory):nodeDirectory;
+  const projectRoot=config.repoRoot??process.cwd(),projectPackage=json(path.join(projectRoot,'package.json'));
+  const dependency=projectPackage?.dependencies?.runlist??projectPackage?.devDependencies?.runlist??null;
+  let project={declaration:dependency,state:'not-resolved'};
+  try {
+    if(projectPackage?.name!=='runlist') {
+      let dir=path.dirname(createRequire(path.join(projectRoot,'package.json')).resolve('runlist'));
+      for(let n=0;n<8;n++,dir=path.dirname(dir))if(json(path.join(dir,'package.json'))?.name==='runlist'){project={...identity(dir),declaration:dependency};break;}
+    }
+  } catch {}
+  const appPath=app??desktopLaunch([],{platform,home,env}).app;
+  const desktop=appPath ? platform==='darwin'?{...identity(path.join(appPath,'Contents/Resources/engine')),application:appPath}: {application:appPath,state:'unverified'} : {state:'not-installed'};
+  desktop.sameEngineSource=cli.fingerprint?.sha256&&desktop.fingerprint?.sha256?cli.fingerprint.sha256===desktop.fingerprint.sha256:null;
+  const claude=readInstalledPluginRecords({home});
+  const codex=codexStatus({homedir:home,version:cli.version});
+  const market=json(codex.marketplace)?.name??'personal';
+  const cache=path.join(home,'.codex/plugins/cache',market,'runlist-codex');
+  let cached=[];
+  try {cached=readdirSync(cache).slice(0,20).map(version=>({path:path.join(cache,version),version,role:'cached copy; active host copy unverified'}));}catch{}
+  const pluginFiles=['skills','commands','hooks','.claude-plugin','.codex-plugin'];
+  const pluginCopy = (file,version,role,source) => {
+    const fingerprint=file?sourceFingerprint(file,pluginFiles):{state:'unavailable'},expected=sourceFingerprint(source,pluginFiles);
+    return {path:file,version:version??null,role,fingerprint,sameSource:fingerprint.sha256&&expected.sha256?fingerprint.sha256===expected.sha256:null};
+  };
+  const warnings=[];
+  const claudeRegistry=path.join(home,'.claude/plugins/installed_plugins.json');
+  if(existsSync(claudeRegistry)&&!json(claudeRegistry))warnings.push('Claude registry unreadable; installed copies are unknown.');
+  if(codex.foreign)warnings.push('Codex marketplace directory is unmanaged; its active installed copy is unverified.');
+  const integrations={
+    claude:(claude?.entries??[]).map(e=>pluginCopy(e.installPath,e.version,`${e.scope??'unknown'} registry entry`,path.join(root,'plugins/runlist'))),
+    codex:[...(codex.exists?[pluginCopy(codex.plugin,codex.version,'marketplace source; not proof of active host copy',path.join(root,'plugins/runlist-codex'))]:[]),...cached.map(e=>pluginCopy(e.path,e.version,e.role,path.join(root,'plugins/runlist-codex')))],
+    opencode:opencodeStatus({env,homedir:home,version:cli.version}),
+  };
+  return {cli,warnings,node:{path:node,version:process.version,prefix:nodePrefix,npm:executable('npm',env)},project,desktop,integrations,
+    updateEffect:'update installs the published CLI into the npm global scope selected by npm on PATH, replacing its local link if present. It does not edit checkout sources or a project dependency. Desktop and managed host copies are separate update steps.'};
+}
+
+export function formatInstallationReport(report) {
+  const id = copy => `${copy.state}${copy.version?` ${copy.version}`:''}${copy.fingerprint?.sha256?` · source ${copy.fingerprint.sha256.slice(0,12)}`:''}`;
+  const lines=[`CLI: ${id(report.cli)} · ${report.cli.kind??'unknown'} · ${report.cli.resolvedPath??report.cli.path}`,
+    `Launcher: ${report.cli.launcher?.path??'unknown'} → ${report.cli.launcher?.resolvedPath??'unknown'}`,
+    `Node: ${report.node.version} · ${report.node.path} · prefix ${report.node.prefix}`,
+    `npm on PATH: ${report.node.npm??'not found'}`,
+    `Project dependency: ${report.project.declaration??'not declared'} · ${id(report.project)}${report.project.resolvedPath?` · ${report.project.resolvedPath}`:''}`,
+    `Desktop: ${id(report.desktop)}${report.desktop.application?` · ${report.desktop.application}`:''} · engine source ${report.desktop.sameEngineSource===null?'unverified':report.desktop.sameEngineSource?'matches CLI':'differs from CLI'}`];
+  for(const warning of report.warnings??[])lines.push(warning);
+  for(const host of ['claude','codex']) {
+    const copies=report.integrations[host];
+    if(!copies.length)lines.push(`${host}: no registered/cached copies found`);
+    for(const copy of copies)lines.push(`${host}: ${copy.version??'unknown'} · ${copy.role} · ${copy.path??'path unknown'} · source ${copy.sameSource===null?'unverified':copy.sameSource?'matches checkout':'differs from checkout'}`);
+  }
+  const oc=report.integrations.opencode;
+  lines.push(`opencode: ${oc.exists?`${oc.foreign?'unmanaged':oc.version??'unknown'} · ${oc.path}`:'not installed'}`,`Update effect: ${report.updateEffect}`);
+  return lines.join('\n')+'\n';
+}

package/src/new.mjs

@@ -1,4 +1,5 @@
 import { applyTemplateOverride, readTemplateStore, templateFile } from './template-store.mjs';
+import { HANDOFF_TEMPLATES } from './prompt-handoff.mjs';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
@@ -86,7 +87,7 @@ export function catchAllRoot(config) {
 
 const BUILTIN_TEMPLATES = {
   doc: {
-    description: 'Reference doc, design note, module overview — build-up shape lite',
+    description: 'Reference document for context, guidance or design notes; active by default.',
     defaultStatus: 'active',
     // Body input optional. When passed (inline / --body / @file / stdin),
     // it lands in the Overview section. Without it, Overview is left blank
@@ -132,7 +133,7 @@ ${ctx?.bodyInput?.trim() ?? ''}
     },
   },
   plan: {
-    description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
+    description: 'Execution plan with goals, constraints, decisions, phases and closeout; planned until work starts.',
     dir: 'plans',
     targetRoot: 'plans',
     // A scaffolded plan is scoped, not being worked; `runlist use` starts it.
@@ -227,7 +228,7 @@ Status markers (put in heading text):
     },
   },
   prompt: {
-    description: 'Saved prompt to seed a future Claude session — body is required',
+    description: 'Saved prompt wrapper: metadata and authored body. Use the resume or subagent draft to write a handoff.',
     dir: 'prompts',
     targetRoot: 'prompts',
     defaultStatus: 'pending',
@@ -419,7 +420,14 @@ export function promptDirectory(config, template = resolveTemplate('prompt', con
   return template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
 }
 
-export function preparePromptDocument(name, bodyInput, config, { plan = null, dryRun = false } = {}) {
+function bindPromptParent(content, parentPrompt) {
+  if (!parentPrompt) return content;
+  const { frontmatter, body } = extractFrontmatter(content);
+  if (!frontmatter) throw new Error('Prompt template must return frontmatter for parent binding.');
+  return `---\n${mergeBodyFrontmatter(frontmatter, { parent_prompt: parentPrompt }, 'prompt')}\n---\n${body}`;
+}
+
+export function preparePromptDocument(name, bodyInput, config, { plan = null, parentPrompt = null, dryRun = false } = {}) {
   const template = resolveTemplate('prompt', config);
   const typeStatuses = config.typeStatuses?.get('prompt');
   const status = template.defaultStatus && (!typeStatuses || typeStatuses.has(template.defaultStatus))
@@ -451,7 +459,7 @@ export function preparePromptDocument(name, bodyInput, config, { plan = null, dr
     if (plan) fm = mergeBodyFrontmatter(fm, { plan }, 'prompt');
     content = `---\n${fm}\n---\n${template.body(title, ctx)}`;
   }
-  return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content };
+  return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content: bindPromptParent(content, parentPrompt) };
 }
 
 // Resolve one `--runlist` token to a scaffolded child plan: a bare slug becomes
@@ -1081,6 +1089,8 @@ export async function runNew(argv, config, opts = {}) {
     return;
   }
 
+  if (typeName === 'prompt') content = bindPromptParent(content, opts.parentPrompt);
+
   // Ensure parent dir exists (templates with `dir:` may target a new subdirectory)
   mkdirSync(path.dirname(filePath), { recursive: true });
 
@@ -1314,8 +1324,18 @@ export function appTemplates(config) {
     const ctx = {title:'{{title}}',status:'{{status}}',today:'{{date}}',bodyInput:'{{body}}',validSurfaces:config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null),validModules:config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null)};
     const defaultSource = `---\n${builtin.frontmatter(ctx.status,ctx.today,ctx)}\n---\n${builtin.body(ctx.title,ctx)}`.replaceAll(pkg.version,'{{version}}');
     const configured = config.raw?.templates?.[name];
-    return {name,description:builtin.description,source:store.data.templates[name]?.source ?? defaultSource,defaultSource,overridden:!!store.data.templates[name],origin:store.data.templates[name] ? templateFile : configured ? `${configFile} (JavaScript)` : 'Built-in',configuredSource:configured ? code(configured) : null,editable:true};
+    return {name,label:name==='prompt'?'Prompt wrapper':name==='plan'?'Execution plan':'Reference doc',kind:'document',description:builtin.description,source:store.data.templates[name]?.source ?? defaultSource,defaultSource,overridden:!!store.data.templates[name],origin:store.data.templates[name] ? templateFile : configured ? `${configFile} (JavaScript)` : 'Built-in',configuredSource:configured ? code(configured) : null,editable:true};
+  });
+  const baton = config.raw?.templates?.prompt?.baton;
+  for (const [name,draft] of Object.entries(HANDOFF_TEMPLATES)) templates.push({
+    name,label:draft.label,kind:'handoff',description:draft.description,
+    source:store.data.templates[name]?.source ?? draft.source,defaultSource:draft.source,
+    overridden:!!store.data.templates[name],origin:store.data.templates[name] ? templateFile : 'Built-in',
+    configuredSource:typeof baton==='string'&&baton.trim()?baton.trim():null,
+    configLabel:'Repository baton instructions',
+    configNote:'These repository instructions still apply to handoffs. Saving a draft outline does not replace them or the saved prompt wrapper.',
+    editable:true,
   });
-  for (const [name,value] of Object.entries(config.raw?.templates ?? {})) if (!BUILTIN_TEMPLATES[name]) templates.push({name,description:value.description ?? 'Repository template',origin:`${configFile} (JavaScript)`,source:code(value),editable:false});
+  for (const [name,value] of Object.entries(config.raw?.templates ?? {})) if (!BUILTIN_TEMPLATES[name]&&!Object.hasOwn(HANDOFF_TEMPLATES,name)) templates.push({name,description:value.description ?? 'Repository template',origin:`${configFile} (JavaScript)`,source:code(value),editable:false});
   return {templates,revision:store.revision,file:templateFile,version:pkg.version};
 }

package/src/prompt-handoff.mjs

@@ -0,0 +1,132 @@
+import path from 'node:path';
+
+export function parentPromptName(value) {
+  if (typeof value !== 'string' || !/^resume-[a-z0-9]+(?:-[a-z0-9]+)*(?:\.md)?$/.test(value)) {
+    throw new Error('A parent resume prompt name is required, e.g. resume-session-name.');
+  }
+  return value.replace(/\.md$/, '');
+}
+
+export const HANDOFF_TEMPLATES = {
+  'handoff:resume': {
+    label: 'Resume draft',
+    description: 'Cold-start handoff outline for baton --template; does not change saved prompt formatting or repository baton instructions.',
+    source: `<!-- Follow repository baton instructions. Keep this focused on what the next session needs. -->
+## Resume
+<!-- Work to resume and owning plan path + section, or a durable brief if there is no plan. -->
+
+## State and next move
+<!-- What is in hand, what remains, and the exact next action or blocker. -->
+
+## Decisions and waiting items
+<!-- Why this direction; rejected or failed approaches that should not be repeated. -->
+<!-- Outstanding decisions, answers or approvals, with a durable record path for each. -->
+
+## Evidence and working material
+<!-- Relevant commits, checks that passed, and claims still unverified. -->
+<!-- Repo-relative paths to briefs, reports and scripts; scratch paths are supplementary. -->
+
+## Boundaries
+<!-- Current user priorities, authorization limits and anything requiring a new go. -->
+<!-- Review linked child handoffs and record completed results in the owning plan. -->
+`,
+  },
+  'handoff:subagent': {
+    label: 'Subagent draft',
+    description: 'Bounded child handoff outline for baton --subagent --template; parent_prompt links it to a resume prompt.',
+    source: `---
+parent_prompt: {{parent_prompt}}
+---
+<!-- Follow the repository's baton instructions alongside these child-specific fields. -->
+## Task
+<!-- One sentence: the bounded job and its owning plan or brief. -->
+
+## State
+<!-- Continue, blocked, or complete. If complete, say what the parent must record. -->
+
+## Next
+<!-- The exact next action, or the blocker and what clears it. No remaining work: say so. -->
+<!-- Include outstanding decisions or approvals and where each is recorded. -->
+
+## Evidence
+<!-- Commits, checks that passed, and checks still unverified. -->
+<!-- Keep the full record in a durable repo-relative path; scratch paths are supplementary. -->
+
+## Boundaries
+<!-- Owned files, shared claims, current authorization, and any required new go. -->
+<!-- Do not release or claim the parent's plan. This handoff grants no new authority. -->
+`,
+  },
+};
+
+// Explicit links win, including missing/ambiguous parents. Legacy child names
+// may share a parent stem; the longest whole-stem match is the most specific.
+
+export function promptParentCandidates(doc, parents) {
+  if(doc.parentPromptInvalid)return [];
+  const slug = doc => path.basename(doc.path, '.md');
+  let matches;
+  if (doc.parentPrompt) {
+    const ref = doc.parentPrompt.replace(/\.md$/, '');
+    matches = parents.filter(parent => ref.includes('/')
+      ? parent.path.replace(/\.md$/, '') === ref
+      : path.dirname(parent.path) === path.dirname(doc.path) && slug(parent) === ref);
+  } else {
+    const stem = slug(doc).replace(/^(?:subagent|agent|session)-/, '');
+    if (stem === slug(doc)) return [];
+    matches = parents.filter(parent => {
+      const parentStem = slug(parent).slice('resume-'.length);
+      return path.dirname(parent.path) === path.dirname(doc.path)
+        && (stem === parentStem || stem.startsWith(`${parentStem}-`));
+    }).sort((a, b) => slug(b).length - slug(a).length);
+    if (matches.length > 1 && slug(matches[0]).length > slug(matches[1]).length) matches = matches.slice(0, 1);
+  }
+  return matches;
+}
+
+export function groupPrompts(prompts) {
+  const slug = doc => path.basename(doc.path, '.md');
+  const parents = prompts.filter(doc => slug(doc).startsWith('resume-')&&!doc.parentPrompt&&!doc.parentPromptInvalid);
+  const children = new Map();
+  const parentFor = new Map();
+  for (const doc of prompts) {
+    if (slug(doc).startsWith('resume-')) continue;
+    const matches = promptParentCandidates(doc, parents);
+    if (matches.length !== 1) continue;
+    const parent = matches[0];
+    parentFor.set(doc, parent);
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(doc);
+  }
+  const groups = [], emitted = new Set();
+  for (const doc of prompts) {
+    const root = parentFor.get(doc) ?? doc;
+    if (emitted.has(root)) continue;
+    emitted.add(root);
+    groups.push({ doc: root, children: children.get(root) ?? [] });
+  }
+  return groups;
+}
+
+export function diagnosePromptParents(prompts, config) {
+  const archived = doc => doc.status === 'archived' || doc.path.split('/').includes(config.archiveDir);
+  const parents = prompts.filter(doc => path.basename(doc.path).startsWith('resume-'));
+  const live = parents.filter(doc => !archived(doc)&&!doc.parentPrompt&&!doc.parentPromptInvalid);
+  const history = parents.filter(archived).map(doc => ({...doc, path:doc.path.split('/').filter(part=>part!==config.archiveDir).join('/'), archivedPath:doc.path}));
+  const links=[];
+  for(const doc of prompts.filter(doc=>!archived(doc))) {
+    const isResume=path.basename(doc.path).startsWith('resume-');
+    if(!doc.parentPrompt&&!doc.parentPromptInvalid&&(isResume||!/^(?:subagent|agent|session)-/.test(path.basename(doc.path))))continue;
+    let state,candidates=[];
+    if(doc.parentPromptInvalid||(isResume&&doc.parentPrompt))state='invalid';
+    else {
+      candidates=promptParentCandidates(doc,live);
+      if(candidates.length===1)state=doc.parentPrompt?'linked':'inferred';
+      else if(candidates.length>1)state='ambiguous';
+      else {candidates=promptParentCandidates(doc,history);state=candidates.length?'archived':'missing';}
+    }
+    links.push({path:doc.path,parentPrompt:doc.parentPrompt??null,state,candidates:candidates.map(parent=>parent.archivedPath??parent.path)});
+  }
+  const counts={};for(const link of links)counts[link.state]=(counts[link.state]??0)+1;
+  return {children:links.length,counts,links,findings:links.filter(link=>link.state!=='linked')};
+}