runlist 0.95.6 → 0.96.1

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')};
+}

package/src/prompts.mjs

@@ -18,11 +18,13 @@ import {
 import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
 import { formatPlanChanges, planChangesSince } from './plan-changes.mjs';
+import { groupPrompts, parentPromptName } from './prompt-handoff.mjs';
+import { mutateFileSet } from './atomic-mutation.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
 // canonical output ("Consumed: …") is unchanged.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'link']);
 
 // Removed 2026-08-30 with the `held`/`shelved` statuses. Named rather than left
 // to fall through to the list filter below, which would silently answer a
@@ -53,9 +55,75 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'peek':     return runPromptsShow(rest, config);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
+    case 'link':     return runPromptsLink(rest, config, opts);
   }
 }
 
+function runPromptsLink(argv, config, opts) {
+  let parentInput = null;
+  const inputs = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--parent') { parentInput = parentPromptName(argv[++i]); continue; }
+    if (argv[i] === '--json') continue;
+    if (argv[i].startsWith('-')) die(`Unknown link option: ${argv[i]}`);
+    inputs.push(argv[i]);
+  }
+  if (!parentInput || !inputs.length) die('Usage: runlist prompts link <child...> --parent resume-name');
+  const parentPath = authorizeManagedSource(resolvePromptInput(parentInput, config), config, { kind: 'Parent prompt' }).path;
+  const parentRaw = readFileSync(parentPath, 'utf8');
+  const parentFm = parseSimpleFrontmatter(extractFrontmatter(parentRaw).frontmatter);
+  if (asString(parentFm.type) !== 'prompt' || asString(parentFm.status) !== 'pending'
+    || isArchivedPath(toRepoPath(parentPath, config.repoRoot), config) || asString(parentFm.parent_prompt)
+    || path.basename(parentPath, '.md') !== parentInput) die('The parent must be an existing pending resume prompt without its own parent.');
+  const updates = [];
+  const paths = new Set();
+  for (const input of inputs) {
+    const file = authorizeManagedSource(resolvePromptInput(input, config), config, { kind: 'Child prompt' }).path;
+    if (paths.has(file)) continue;
+    paths.add(file);
+    const raw = readFileSync(file, 'utf8');
+    const fm = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter);
+    if (file === parentPath || path.basename(file).startsWith('resume-') || asString(fm.type) !== 'prompt'
+      || asString(fm.status) !== 'pending' || isArchivedPath(toRepoPath(file, config.repoRoot), config)) {
+      die(`Child must be a pending non-resume prompt: ${toRepoPath(file, config.repoRoot)}`);
+    }
+    const ref = path.dirname(file) === path.dirname(parentPath) ? parentInput : toRepoPath(parentPath, config.repoRoot);
+    const header = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(raw);
+    if (!header || (header[2].match(/^parent_prompt:/gm) ?? []).length > 1) die(`Repair the parent_prompt frontmatter first: ${input}`);
+    if (asString(fm.parent_prompt) === ref) continue;
+    const eol = header[1].endsWith('\r\n') ? '\r\n' : '\n';
+    const field = `parent_prompt: ${JSON.stringify(ref)}`;
+    const parentField = /^parent_prompt:[^\r\n]*(?:\r?\n[ \t]+[^\r\n]*)*/m;
+    const frontmatter = parentField.test(header[2]) ? header[2].replace(parentField, field) : `${header[2]}${eol}${field}`;
+    updates.push({ path: file, expectedContent: raw, content: `${header[1]}${frontmatter}${header[3]}${raw.slice(header[0].length)}` });
+  }
+  if (!opts.dryRun && updates.length) mutateFileSet({ updates, guards: [{ path: parentPath, expectedContent: parentRaw }] }, {
+    repoRoot: config.repoRoot, testHooks: opts.testHooks,
+  });
+  const result = { operation: 'prompts-link', dryRun: Boolean(opts.dryRun), parent: toRepoPath(parentPath, config.repoRoot),
+    linked: updates.map(item => toRepoPath(item.path, config.repoRoot)) };
+  process.stdout.write(argv.includes('--json') ? JSON.stringify(result, null, 2) + '\n'
+    : `${opts.dryRun ? 'Would link' : 'Linked'} ${updates.length} child prompt(s) to ${parentInput}.\n`);
+  return result;
+}
+
+function childHandoffs(repoPath, config, index = null) {
+  if (!path.basename(repoPath).startsWith('resume-')) return { paths: [], notice: '' };
+  index ??= buildIndex(config, { fast: true, invokeHooks: false });
+  const docs = index.docs.filter(doc => doc.type === 'prompt' && doc.status !== 'archived' && !isArchivedPath(doc.path, config));
+  // Consumption removes a parent from the live index. A read-only peek at its
+  // archive can still discover children linked to its former live location.
+  const livePath = repoPath.split('/').filter(part => part !== config.archiveDir).join('/');
+  if (livePath !== repoPath && !docs.some(doc => doc.path === livePath)) {
+    docs.push({ path: livePath });
+  }
+  const children = groupPrompts(docs.sort(comparePromptDocs)).find(group => group.doc.path === livePath)?.children ?? [];
+  if (!children.length) return { paths: [], notice: '' };
+  const parent = path.basename(repoPath, '.md');
+  const names = children.map(doc => `- \`${doc.path}\``).join('\n');
+  return { paths: children.map(doc => doc.path), notice: `\n\n## Saved child handoffs\n\n${children.length} child handoff(s) remain pending:\n\n${names}\n\nInspect a child with \`rl prompts show <name>\`. Review its current state and authorization before resuming its lane. Fold completed results into the owning plan, then archive the completed handoff explicitly.\n\nPass \`--parent ${parent}\` when saving another child, or pass \`RUNLIST_PARENT_PROMPT=${parent}\` into its environment.\n` };
+}
+
 function runPromptsList(argv, config, opts = {}) {
   // Listing prompts renders slug / status / updated / target — nothing any
   // validating pass produces, and `runQuery` never reads warnings either. A
@@ -111,13 +179,29 @@ function renderPromptQueueList(index, config) {
   const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
   process.stdout.write(dim(`${prompts.length} prompts · ${summary}`) + '\n\n');
 
-  const maxSlug = Math.min(36, Math.max(...prompts.map(p => path.basename(p.path, '.md').length)));
-  for (let i = 0; i < prompts.length; i++) {
-    const p = prompts[i];
+  const groups = groupPrompts(prompts);
+  const isAgentHandoff = doc => !path.basename(doc.path).startsWith('resume-')
+    && (doc.parentPrompt || /^(?:subagent|agent|session)-/.test(path.basename(doc.path)));
+  const standalone = groups.filter(group => isAgentHandoff(group.doc));
+  const visible = groups.filter(group => !isAgentHandoff(group.doc));
+  const maxSlug = Math.min(36, Math.max(0, ...visible.map(({ doc }) => path.basename(doc.path, '.md').length)));
+  const nextPath = queue[0]?.doc.path;
+  const childCount = children => `[+ ${children.length} subagent prompt${children.length === 1 ? '' : 's'}]`;
+  for (const { doc: p, children } of visible) {
     const slug = path.basename(p.path, '.md').padEnd(maxSlug);
-    const marker = i === 0 && p.status === 'pending' ? green('[NEXT]') : '      ';
+    const marker = p.path === nextPath ? green('[NEXT]') : '      ';
     const status = `[${(p.status ?? 'unknown').toUpperCase()}]`;
-    process.stdout.write(`  ${marker} ${slug} ${status}\n`);
+    const childMarker = children.some(doc => doc.path === nextPath) ? `${green('[NEXT]')} ` : '';
+    const badge = children.length ? ` ${childMarker}${dim(childCount(children))}` : '';
+    process.stdout.write(`  ${marker} ${slug} ${status}${badge}\n`);
+  }
+  if (standalone.length) {
+    const children = standalone.map(group => group.doc);
+    const marker = children.some(doc => doc.path === nextPath) ? green('[NEXT]') : '      ';
+    process.stdout.write(`  ${marker} ${childCount(children)}\n`);
+  }
+  if (standalone.length || visible.some(group => group.children.length)) {
+    process.stdout.write(dim('\nUse `rl prompts --verbose` to expand subagent prompts.\n'));
   }
 }
 
@@ -173,12 +257,17 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
   const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
   process.stdout.write(`${prompts.length} prompt${prompts.length === 1 ? '' : 's'} · ${summary}\n\n`);
 
-  for (const p of prompts) {
+  const render = (p, child) => {
     const slug = path.basename(p.path, '.md');
     const target = findPromptTarget(p, config);
     const status = (p.status ?? 'unknown').toUpperCase();
     const arrow = target ? `  ${dim('→')} ${target}` : `  ${dim('→ (no target plan)')}`;
-    process.stdout.write(`  ${green(slug)}  [${status}]\n${arrow}\n`);
+    const indent = child ? '    - ' : '  ';
+    process.stdout.write(`${indent}${green(slug)}  [${status}]\n${child ? '    ' : ''}${arrow}\n`);
+  };
+  for (const {doc,children} of groupPrompts(prompts)) {
+    render(doc, false);
+    for (const child of children) render(child, true);
   }
 }
 
@@ -281,6 +370,7 @@ export async function consumePrompt(filePath, config, opts) {
   if (status === 'archived' || isArchivedPath(repoPath, config)) {
     die(`Already consumed: ${repoPath}`);
   }
+  const family = childHandoffs(repoPath, config);
 
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
@@ -297,12 +387,13 @@ export async function consumePrompt(filePath, config, opts) {
     const prefix = dim('[dry-run]');
     process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
     if (claimSkipReason) process.stderr.write(`${prefix} Would NOT claim the linked plan: ${claimSkipReason}\n`);
-    const bytes = Buffer.byteLength(body, 'utf8');
-    const lines = body.split('\n').length;
+    const previewBody = body + family.notice;
+    const bytes = Buffer.byteLength(previewBody, 'utf8');
+    const lines = previewBody.split('\n').length;
     process.stderr.write(`${prefix} body preview (${bytes}B, ${lines} lines):\n`);
     process.stderr.write(`${dim('---8<---')}\n`);
-    process.stderr.write(body);
-    if (!body.endsWith('\n')) process.stderr.write('\n');
+    process.stderr.write(previewBody);
+    if (!previewBody.endsWith('\n')) process.stderr.write('\n');
     process.stderr.write(`${dim('--->8---')}\n`);
     runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr, skipInboundRefs: true });
     return;
@@ -334,7 +425,7 @@ export async function consumePrompt(filePath, config, opts) {
   // Consume output is at-most-once: archive/claim commits before stdout. A
   // downstream failure cannot roll the transaction back or make it consumable
   // again; the archived path remains available through `prompts show`.
-  await writeConsumedBody(consumedBody, consumedPath, opts.writeBody, linkedClaim?.repoPath);
+  await writeConsumedBody(consumedBody + family.notice, consumedPath, opts.writeBody, linkedClaim?.repoPath);
   let completion = { indexRegenerated: false, ownershipChanged: false, hook: 'none', pending: false };
   if (linkedClaim) {
     try {
@@ -375,6 +466,7 @@ export async function consumePrompt(filePath, config, opts) {
   ].filter(Boolean).map(normalize))];
   return {
     operation: 'consume',
+    childPrompts: family.paths,
     status: { from: status ?? null, to: 'archived', changed: true },
     repositoryFiles,
     sessionFiles,
@@ -550,6 +642,7 @@ function runPromptsShow(argv, config) {
   // prompt keep working.
   const multi = targets.length > 1;
   let shown = 0;
+  let familyIndex = null;
   for (const filePath of targets) {
     const prompt = readPromptForShow(filePath, config, { strict: !all && !multi });
     if (!prompt) continue;
@@ -558,10 +651,13 @@ function runPromptsShow(argv, config) {
       if (shown > 0) process.stdout.write('\n');
       process.stdout.write(dim(`──── ${repoPath} [${status}] ────\n`));
     } else {
-      process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`runlist use ${repoPath}\` to consume\n`));
+      const hint = status === 'archived' || isArchivedPath(repoPath, config) ? 'archived prompt' : `\`runlist use ${repoPath}\` to consume`;
+      process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; ${hint}\n`));
     }
-    process.stdout.write(body);
-    if (!body.endsWith('\n')) process.stdout.write('\n');
+    if (path.basename(repoPath).startsWith('resume-')) familyIndex ??= buildIndex(config, { fast: true, invokeHooks: false });
+    const displayedBody = body + childHandoffs(repoPath, config, familyIndex).notice;
+    process.stdout.write(displayedBody);
+    if (!displayedBody.endsWith('\n')) process.stdout.write('\n');
     shown++;
   }
 

package/src/template-store.mjs

@@ -4,16 +4,24 @@ import path from 'node:path';
 import { authorizeRepoGeneratedPath } from './managed-path.mjs';
 import { mutateFileSet, MutationConflictError } from './atomic-mutation.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { HANDOFF_TEMPLATES } from './prompt-handoff.mjs';
 
 export const templateFile = 'runlist.templates.json';
-export const templateNames = ['doc','plan','prompt'];
+export const templateNames = ['doc','plan','prompt',...Object.keys(HANDOFF_TEMPLATES)];
 const tokens = new Set(['title','status','date','body','version']);
 const revision = text => createHash('sha256').update(text).digest('hex');
 function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
 export function validateTemplate(name, source) {
-  if (!templateNames.includes(name)) fail('invalid-template','Choose a doc, plan or prompt template.');
-  if (typeof source !== 'string' || Buffer.byteLength(source) > 128 * 1024) fail('invalid-template','Template must be Markdown smaller than 128 KB.');
+  if (!templateNames.includes(name)) fail('invalid-template','Choose a doc, plan, prompt, resume or subagent template.');
+  if (typeof source !== 'string' || !source.trim() || Buffer.byteLength(source) > 128 * 1024) fail('invalid-template','Template must be nonempty Markdown smaller than 128 KB.');
   const parts = extractFrontmatter(source), metadata=parseSimpleFrontmatter(parts.frontmatter);
+  if (Object.hasOwn(HANDOFF_TEMPLATES,name)) {
+    for (const match of source.matchAll(/\{\{([^{}]+)\}\}/g)) if (name !== 'handoff:subagent' || match[1] !== 'parent_prompt') fail('invalid-template',`Unknown placeholder: {{${match[1]}}}.`);
+    if (name === 'handoff:subagent' && (!source.startsWith('---\n') || metadata.parent_prompt !== '{{parent_prompt}}' || (parts.frontmatter.match(/^parent_prompt:/gm)??[]).length !== 1)) fail('invalid-template','Keep parent_prompt: {{parent_prompt}} in the subagent frontmatter.');
+    if (name === 'handoff:resume' && Object.hasOwn(metadata,'parent_prompt')) fail('invalid-template','A resume draft cannot have its own parent_prompt; use the subagent draft for child handoffs.');
+    if (['type','status','created','updated'].some(key=>Object.hasOwn(metadata,key))) fail('invalid-template','Handoff drafts contain authored content; saved prompt metadata is supplied by the prompt scaffold.');
+    return parts;
+  }
   if (!source.startsWith('---\n') || metadata.type !== name) fail('invalid-template',`Keep the frontmatter and type: ${name}.`);
   for (const match of source.matchAll(/\{\{([^{}]+)\}\}/g)) if (!tokens.has(match[1])) fail('invalid-template',`Unknown placeholder: {{${match[1]}}}.`);
   if (!/\{\{title\}\}/.test(parts.body) && name !== 'prompt') fail('invalid-template','Keep {{title}} in the document body.');
@@ -31,7 +39,7 @@ export function readTemplateStore(config) {
   let data = {version:1,templates:{}};
   if (source !== null) {
     try { data = JSON.parse(source); } catch { fail('invalid-template','runlist.templates.json contains invalid JSON.'); }
-    if (data.version !== 1 || !data.templates || typeof data.templates !== 'object' || Array.isArray(data.templates) || Object.keys(data).some(k=>!['version','templates'].includes(k))) fail('invalid-template','Unsupported template settings format.');
+    if (!data || typeof data !== 'object' || data.version !== 1 || !data.templates || typeof data.templates !== 'object' || Array.isArray(data.templates) || Object.keys(data).some(k=>!['version','templates'].includes(k))) fail('invalid-template','Unsupported template settings format.');
     for (const [name,value] of Object.entries(data.templates)) {
       if (!value || Object.keys(value).some(k=>k!=='source')) fail('invalid-template','Template settings accept a Markdown source field.');
       validateTemplate(name,value.source);
@@ -40,17 +48,20 @@ export function readTemplateStore(config) {
   return {file,source,data,revision:source === null ? null : revision(source)};
 }
 export function saveTemplate(config,{name,source,expectedRevision,reset=false}) {
-  if (!templateNames.includes(name)) fail('invalid-template','Choose a doc, plan or prompt template.');
+  if (!templateNames.includes(name)) fail('invalid-template','Choose a doc, plan, prompt, resume or subagent template.');
   if (!reset) validateTemplate(name,source);
   const store = readTemplateStore(config);
   if (expectedRevision !== store.revision) fail('template-conflict','Templates changed in another tab or process. Your draft is kept; reload the saved templates before trying again.');
   if (reset) delete store.data.templates[name]; else store.data.templates[name] = {source};
   const content = JSON.stringify(store.data,null,2)+'\n';
+  if (Buffer.byteLength(content) > 512 * 1024) fail('invalid-template','Combined template settings must be smaller than 512 KB.');
   try { mutateFileSet(store.source === null ? {creations:[{path:store.file,content}]} : {updates:[{path:store.file,expectedContent:store.source,content}]},{repoRoot:config.repoRoot}); }
   catch (error) { if (error instanceof MutationConflictError) fail('template-conflict','Templates changed while saving. Your draft is kept.'); throw error; }
   return {revision:revision(content)};
 }
 export function applyTemplateOverride(name,base,config,version) {
+  // Markdown document overrides apply only to the three built-in types.
+  if (!['doc','plan','prompt'].includes(name)) return base;
   const source = readTemplateStore(config).data.templates[name]?.source;
   if (source === undefined) return base;
   const parts = validateTemplate(name,source);

package/src/update.mjs

@@ -8,6 +8,8 @@ import { executableName, which } from './util.mjs';
 import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, opencodeStatus } from './host-integration.mjs';
 import { codexStatus, installedCodexStatus } from './codex-integration.mjs';
 import { desktopLaunch } from './desktop.mjs';
+import { installationReport, formatInstallationReport, readInstalledPluginRecords } from './installation.mjs';
+export { readInstalledPluginRecords } from './installation.mjs';
 import { compareDesktopVersions, installedDesktopVersion } from './desktop-install.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -32,30 +34,6 @@ export function compareVersions(a, b) {
   return 0;
 }
 
-// Read Claude Code's plugin install record to find the installed runlist plugin's
-// id + version. Network-free. `opts.home` is injectable for tests. Returns
-// { id, version } or null when nothing is installed / the file is absent.
-export function readInstalledPluginRecords(opts = {}) {
-  const home = opts.home || os.homedir();
-  const file = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
-  try {
-    const j = JSON.parse(readFileSync(file, 'utf8'));
-    const plugins = j.plugins || {};
-    const id = opts.id
-      ? (plugins[opts.id] ? opts.id : null)
-      : plugins[DEFAULT_PLUGIN_ID]
-        ? DEFAULT_PLUGIN_ID
-        : plugins[LEGACY_PLUGIN_ID]
-          ? LEGACY_PLUGIN_ID
-          : Object.keys(plugins).find(k => /^(?:runlist|dotmd)@/.test(k));
-    if (!id) return null;
-    const entries = Array.isArray(plugins[id]) ? plugins[id] : [plugins[id]];
-    return { id, entries: entries.filter(Boolean) };
-  } catch {
-    return null;
-  }
-}
-
 // Claude Code's marketplace registry, keyed by marketplace name. A plugin id
 // is `<plugin>@<marketplace>`, and the plugin only loads while its marketplace
 // is registered here — an install record alone is not an installed plugin.
@@ -251,6 +229,7 @@ export async function runUpdate(argv, _config, opts = {}) {
   const desktop = process.platform === 'darwin' && process.arch === 'arm64' ? desktopLaunch([]).app : null;
 
   if (check) {
+    process.stdout.write(formatInstallationReport(installationReport(_config)));
     process.stdout.write(`runlist CLI:    ${pkg.version}\n`);
     if (plugin) {
       if (plugin.id === LEGACY_PLUGIN_ID || (legacyPlugin && plugin.id !== LEGACY_PLUGIN_ID)) {
@@ -258,7 +237,7 @@ export async function runUpdate(argv, _config, opts = {}) {
       }
       for (const entry of plugin.entries) {
         const cmp = compareVersions(entry.version, pkg.version);
-        const tag = cmp === 0 ? green('in sync')
+        const tag = cmp === 0 ? green('version matches')
           : cmp === null ? dim('(unknown)')
           : cmp < 0 ? yellow('behind — run `runlist update`')
           : yellow('ahead — CLI is behind');
@@ -273,14 +252,14 @@ export async function runUpdate(argv, _config, opts = {}) {
     const oc = opencodeStatus({ version: pkg.version });
     if (!oc.exists) process.stdout.write(dim('runlist opencode: not installed\n'));
     else if (oc.foreign) process.stdout.write(`runlist opencode: ${yellow('unmanaged file — not written by runlist')}\n`);
-    else process.stdout.write(`runlist opencode: ${oc.version} ${oc.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
+    else process.stdout.write(`runlist opencode: ${oc.version} ${oc.stale ? yellow('behind — run `runlist update`') : green('version matches')}\n`);
     const cx = currentCodexStatus(pkg.version);
     if (!cx.exists) process.stdout.write(dim('runlist codex: not installed\n'));
     else if (cx.foreign) process.stdout.write(`runlist codex: ${yellow('unmanaged plugin directory')}\n`);
-    else process.stdout.write(`runlist codex: source ${cx.version}; installed ${cx.installed?.version ?? 'unverified'} ${cx.stale ? yellow('out of sync — run `runlist update`') : green('in sync')}\n`);
+    else process.stdout.write(`runlist codex: source ${cx.version}; installed ${cx.installed?.version ?? 'unverified'} ${cx.stale ? yellow('out of sync — run `runlist update`') : green('version matches')}\n`);
     if (desktop) {
       const version = await installedDesktopVersion(desktop);
-      process.stdout.write(`runlist desktop: ${version} ${compareDesktopVersions(version, pkg.version) < 0 ? yellow('behind — quit Runlist and run `runlist update`') : green('in sync')}\n`);
+      process.stdout.write(`runlist desktop: ${version} ${compareDesktopVersions(version, pkg.version) < 0 ? yellow('behind — quit Runlist and run `runlist update`') : dim('version current; see source comparison above')}\n`);
     }
     return;
   }