runlist 0.96.0 → 0.97.0

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/section.mjs

@@ -3,26 +3,32 @@
 // and body-relative line numbers (1-indexed). Callers with stripped frontmatter
 // add extractFrontmatter().bodyLineOffset before exposing file coordinates.
 
-export function walkSections(body) {
-  const lines = body.split('\n');
+// Calls visit(line, index) for every line outside a fenced code block. A fence
+// closes only on the character that opened it, so ``` inside ~~~ stays code.
+function eachUnfencedLine(lines, visit) {
   const fenceRe = /^(`{3,}|~{3,})/;
-  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
-  const sections = [];
   let fenceChar = null;
-  let h2Ancestor = null;
-
   for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const fence = line.match(fenceRe);
+    const fence = lines[i].match(fenceRe);
     if (fence) {
       const tok = fence[1][0]; // ` or ~
       if (fenceChar === null) fenceChar = tok;
       else if (fenceChar === tok) fenceChar = null;
       continue;
     }
-    if (fenceChar !== null) continue;
+    if (fenceChar === null) visit(lines[i], i);
+  }
+}
+
+export function walkSections(body) {
+  const lines = body.split('\n');
+  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
+  const sections = [];
+  let h2Ancestor = null;
+
+  eachUnfencedLine(lines, (line, i) => {
     const h = line.match(headingRe);
-    if (!h) continue;
+    if (!h) return;
     const level = h[1].length;
     const heading = h[2];
     if (level === 1) h2Ancestor = null;
@@ -35,7 +41,7 @@ export function walkSections(body) {
       bodyLineStart: i + 2,
     });
     if (level === 2) h2Ancestor = heading;
-  }
+  });
 
   for (let i = 0; i < sections.length; i++) {
     const next = sections.find((s, j) => j > i && s.level <= sections[i].level);
@@ -57,6 +63,35 @@ export function findSection(sections, name) {
   return sections.find(s => norm(s.heading) === target) ?? null;
 }
 
+// Every section whose heading matches `query`, best first: exact, then prefix,
+// then substring, document order within each. Case-insensitive; leading `#`s
+// and trailing markers are ignored on both sides, as in findSection.
+export function matchSections(sections, query) {
+  const norm = (s) => s.toLowerCase().replace(/^#+\s*/, '').replace(/[^\w\s]+$/, '').replace(/\s+/g, ' ').trim();
+  const q = norm(query);
+  if (!q) return [];
+  const tiers = [[], [], []];
+  for (const s of sections) {
+    const h = norm(s.heading);
+    if (h === q) tiers[0].push(s);
+    else if (h.startsWith(q)) tiers[1].push(s);
+    else if (h.includes(q)) tiers[2].push(s);
+  }
+  return tiers.flat();
+}
+
+// Checklist boxes outside code fences, with body-relative 1-indexed lines.
+// `[ ]` and `[~]` are open, as in phaseTally and the index's checklist counts.
+const BOX_RE = /^\s*[-*]\s+\[([ xX~])\](?:\s+(.*?))?\s*$/;
+export function walkChecklist(body) {
+  const boxes = [];
+  eachUnfencedLine(body.split('\n'), (line, i) => {
+    const m = line.match(BOX_RE);
+    if (m) boxes.push({ line: i + 1, open: m[1].toLowerCase() !== 'x', text: m[2] ?? '' });
+  });
+  return boxes;
+}
+
 // Status marker detection for phase headings. Returns one of:
 //   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
 // Glyphs are checked BEFORE prose, not interleaved with it. A glyph is a

package/src/show.mjs

@@ -1,13 +1,16 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFrontmatter, normalizeEol, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { buildBrief, collapseFrontmatter, cut, LIMITS, readSection, SURVEY_LIMITS } from './brief.mjs';
 import { parseDocFile, resolveDocArg } from './index.mjs';
 import { resolveBodyLinkTarget } from './body-link.mjs';
-import { die, normalizeStringList, resolveRefPath, toRepoPath } from './util.mjs';
+import { die, normalizeStringList, resolveRefPath, shellQuote, toRepoPath } from './util.mjs';
 
 // `runlist show <file...>` — one document's card as data: its title, status,
 // next step, blockers and checklist, the plans and docs its frontmatter names,
-// and the documents its body links to. Read-only; nothing is claimed.
+// and the documents its body links to, followed by its brief (outline and open
+// boxes with line numbers; src/brief.mjs). `--section` reads one section in
+// place of the whole file. Read-only; nothing is claimed.
 
 // Frontmatter lists that name other documents. The configured reference fields
 // are read too; `related_docs` is read whether or not a repo configures it.
@@ -76,26 +79,139 @@ export function showDoc(abs, config) {
   };
 }
 
+// Fields the text card prints. Everything else non-empty is named on one line
+// so a reader knows it is there without printing the frontmatter.
+const CARD_FIELDS = new Set(['title', 'status', 'next_step', 'blockers']);
+
+function otherFields(abs, config) {
+  const raw = readFileSync(abs, 'utf8');
+  const fm = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter ?? '', []);
+  const shown = new Set([...CARD_FIELDS, ...relatedFields(config)]);
+  return Object.keys(fm).filter(k => !shown.has(k) && normalizeStringList(fm[k]).some(v => String(v).trim()));
+}
+
+function parseShowArgs(args) {
+  const opts = { json: false, card: false, all: false, frontmatter: false, section: null, from: null, targets: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--card') opts.card = true;
+    else if (a === '--all') opts.all = true;
+    else if (a === '--frontmatter') opts.frontmatter = true;
+    else if (a === '--section' || a === '-s') opts.section = args[++i] ?? die('--section needs a heading');
+    else if (a === '--from') opts.from = args[++i];
+    else if (a.startsWith('-')) die(`Unknown option for show: ${a}`);
+    else opts.targets.push(a);
+  }
+  if (opts.from != null) {
+    if (opts.section == null) die('--from continues a --section read; name the section too');
+    const n = Number(opts.from);
+    if (!Number.isInteger(n) || n < 1) die(`--from takes a line number, got: ${opts.from}`);
+    opts.from = n;
+  }
+  return opts;
+}
+
+const pad = (n, width) => String(n).padStart(width);
+
+function runSection(target, opts, config) {
+  const abs = resolveDocArg(target, config);
+  const rel = toRepoPath(abs, config.repoRoot);
+  const r = readSection(readFileSync(abs, 'utf8'), opts.section, { from: opts.from });
+  const again = from => `runlist show ${shellQuote(rel)} --section ${shellQuote(opts.section)} --from ${from}`;
+  if (opts.json) {
+    const { headings, ...rest } = r;
+    const out = r.found
+      ? { path: rel, ...rest, ...(r.next ? { continue: again(r.next) } : {}) }
+      : { path: rel, error: 'no heading matches', query: r.query, headings: headings.map(({ line, level, heading }) => ({ line, level, heading })) };
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+    if (!r.found || r.past) process.exitCode = 1;
+    return;
+  }
+  if (!r.found) {
+    const list = r.headings.slice(0, 20).map(h => `  ${h.line}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}`);
+    if (r.headings.length > 20) list.push(`  (+${r.headings.length - 20} more)`);
+    process.stderr.write([`No heading in ${rel} matches "${opts.section}". Headings:`, ...list].join('\n') + '\n');
+    process.exitCode = 1;
+    return;
+  }
+  const h = r.heading;
+  if (r.past) {
+    process.stderr.write(`${rel}: "${h.heading}" runs ${h.line} to ${h.end}; --from ${r.from} is past its end.\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const width = String(r.to).length;
+  const span = r.from === h.line && !r.next ? `${h.line} to ${h.end}` : `${r.from} to ${r.to} of ${h.line} to ${h.end}`;
+  const out = [`${rel} lines ${span} (${'#'.repeat(h.level)} ${h.heading}):`];
+  for (const row of r.rows) out.push(`${pad(row.line, width)}\t${row.text}`);
+  if (r.next) out.push(`(cut at line ${r.to}; the section runs to ${h.end}. Next: ${again(r.next)})`);
+  if (r.others.length) out.push(`Also matching: ${r.others.map(o => `${o.line} ${cut(o.heading, 60)}`).join('; ')}`);
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+function renderBrief(card, brief) {
+  const out = [];
+  const width = String(brief.lines).length;
+  const kb = Math.max(1, Math.round(brief.bytes / 1024));
+  out.push('', `Outline: ${brief.lines.toLocaleString('en-US')} lines, ${kb} KB (line, heading)`);
+  if (!brief.outline.length) out.push('  (no headings)');
+  for (const h of brief.outline) out.push(`  ${pad(h.line, width)}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}`);
+  if (brief.outlineOmitted) out.push(`  (+${brief.outlineOmitted} deeper headings not shown; a --section read shows them)`);
+  const total = brief.boxes.open + brief.boxes.done;
+  if (total) {
+    out.push(`Open boxes: ${brief.boxes.open} of ${total} (line, text)`);
+    for (const b of brief.open) out.push(`  ${pad(b.line, width)}  ${cut(b.text)}`);
+    if (brief.openOmitted) out.push(`  (+${brief.openOmitted} more: add --all)`);
+  }
+  if (brief.frontmatter) {
+    out.push(`Frontmatter (lines 1 to ${brief.frontmatterLines}):`, ...brief.frontmatter.map(l => `  ${l}`));
+  } else if (card.otherFields?.length) {
+    out.push(`Other fields: ${card.otherFields.join(', ')} (--frontmatter prints them)`);
+  }
+  return out;
+}
+
 export function runShow(args, config) {
-  const json = args.includes('--json');
-  const targets = args.filter(a => !a.startsWith('-'));
-  if (!targets.length) die('Usage: runlist show <file...> [--json]');
+  const opts = parseShowArgs(args);
+  if (!opts.targets.length) die('Usage: runlist show <file...> [--section "<heading>" [--from <line>]] [--all] [--card] [--frontmatter] [--json]');
+  if (opts.section != null) {
+    if (opts.targets.length > 1) die('--section reads one file; name one');
+    runSection(opts.targets[0], opts, config);
+    return;
+  }
+  const limits = opts.targets.length > 1 ? SURVEY_LIMITS : LIMITS;
   const cards = [];
-  for (const t of targets) {
-    const abs = resolveDocArg(t, config, { dieOnMiss: !json });
-    cards.push(abs ? showDoc(abs, config) : { path: t, error: 'not found' });
+  for (const t of opts.targets) {
+    const abs = resolveDocArg(t, config, { dieOnMiss: !opts.json });
+    if (!abs) { cards.push({ path: t, error: 'not found' }); continue; }
+    const card = showDoc(abs, config);
+    if (!opts.card) {
+      const raw = readFileSync(abs, 'utf8');
+      card.brief = buildBrief(raw, { all: opts.all, limits });
+      if (opts.frontmatter) card.brief.frontmatter = collapseFrontmatter(extractFrontmatter(normalizeEol(raw)).frontmatter, limits);
+      card.otherFields = otherFields(abs, config);
+    }
+    cards.push(card);
   }
-  if (json) {
+  if (opts.json) {
     process.stdout.write(`${JSON.stringify(cards, null, 2)}\n`);
     return;
   }
   cards.forEach((c, n) => {
     if (n) process.stdout.write('\n');
-    process.stdout.write(`${c.title}  (${c.status ?? 'no status'})\n${c.path}\n`);
-    if (c.nextStep) process.stdout.write(`Next: ${c.nextStep}\n`);
-    for (const b of c.blockers) process.stdout.write(`Blocker: ${b}\n`);
-    if (c.checklist?.total) process.stdout.write(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done\n`);
-    for (const r of c.related) process.stdout.write(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}\n`);
-    if (c.links.length) process.stdout.write(`Linked from the body: ${c.links.map(l => l.path).join(', ')}\n`);
+    const out = [`${c.title}  (${c.status ?? 'no status'})`, c.path];
+    if (c.nextStep) out.push(`Next: ${c.nextStep}`);
+    for (const b of c.blockers) out.push(`Blocker: ${b}`);
+    // The brief's open-box line carries the same count, read outside code fences.
+    if (c.checklist?.total && !c.brief) out.push(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done`);
+    for (const r of c.related) out.push(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}`);
+    if (c.links.length) out.push(`Linked from the body: ${c.links.map(l => l.path).join(', ')}`);
+    if (c.brief) out.push(...renderBrief(c, c.brief));
+    process.stdout.write(out.join('\n') + '\n');
   });
+  if (!opts.card) {
+    const file = cards.length === 1 ? shellQuote(cards[0].path) : '<file>';
+    process.stdout.write(`\nOne section: runlist show ${file} --section "<heading>"\n`);
+  }
 }

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;
   }

package/src/util.mjs

@@ -306,6 +306,13 @@ export function suggestCandidates(query, candidates, max = 3) {
     .map(([cand]) => cand);
 }
 
+// One argument as it must be typed into a POSIX shell: bare when it is plainly
+// safe, otherwise double-quoted with `"`, `\`, `$` and backtick escaped.
+export function shellQuote(value) {
+  const raw = String(value);
+  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
+}
+
 export function resolveDocPath(input, config) {
   if (!input) return null;
   if (path.isAbsolute(input)) return existsSync(input) ? input : null;