runlist 0.95.6 → 0.96.1

package/src/app.mjs

@@ -7,6 +7,14 @@ import { SourceEditError } from './source-editor.mjs';
 import { resolveDocArg } from './index.mjs';
 
 const assets = new URL('../assets/app/', import.meta.url);
+const staticFiles = new Map([
+  'app.mjs','theme.mjs','transport.mjs','shared.mjs','document-create.mjs',
+  'quick-navigation.mjs','recovery-center.mjs','settings.mjs','document-lifecycle.mjs',
+  'record-navigation.mjs','library-navigation.mjs','outline.mjs','editor-navigation.mjs',
+  'template-editor.mjs','block-model.mjs','block-editor.mjs','git-changes.mjs','git-commit.mjs',
+  'document-views.mjs','document-stages.mjs','document-yardstick.mjs',
+  'filing-navigation.mjs','semantic-search.mjs','stage-source.mjs','app.css',
+].map(file => [`/${file}`, [file, file.endsWith('.css') ? 'text/css' : 'text/javascript']]));
 const ttl = 12 * 60 * 60 * 1000;
 const secret = () => randomBytes(32).toString('base64url');
 function problem(code,message) { throw new SourceEditError(code,message); }
@@ -40,10 +48,7 @@ export async function startApp({ config, port = 5173, initialPath = null, actor
       if (!origin || ![new URL(origin).host, `localhost:${server.address().port}`].includes(req.headers.host)) problem('forbidden', 'Invalid local application host.');
       const url = new URL(req.url, origin);
       if (req.method === 'GET' && url.pathname === '/') return send(200, readFileSync(new URL('index.html', assets)), 'text/html; charset=utf-8');
-      const staticFiles = { '/document-create.mjs':['document-create.mjs','text/javascript'], '/quick-navigation.mjs':['quick-navigation.mjs','text/javascript'], '/recovery-center.mjs':['recovery-center.mjs','text/javascript'], '/transport.mjs':['transport.mjs','text/javascript'], '/settings.mjs':['settings.mjs','text/javascript'], '/document-lifecycle.mjs':['document-lifecycle.mjs','text/javascript'], '/record-navigation.mjs':['record-navigation.mjs','text/javascript'], '/theme.mjs':['theme.mjs','text/javascript'], '/library-navigation.mjs':['library-navigation.mjs','text/javascript'], '/outline.mjs':['outline.mjs','text/javascript'], '/editor-navigation.mjs':['editor-navigation.mjs','text/javascript'], '/template-editor.mjs':['template-editor.mjs','text/javascript'], '/block-model.mjs':['block-model.mjs','text/javascript'], '/block-editor.mjs':['block-editor.mjs','text/javascript'], '/app.mjs': ['app.mjs','text/javascript'], '/shared.mjs':['shared.mjs','text/javascript'], '/app.css':['app.css','text/css'] };
-      staticFiles['/git-changes.mjs']=['git-changes.mjs','text/javascript'];
-      staticFiles['/git-commit.mjs']=['git-commit.mjs','text/javascript'];
-      if (req.method === 'GET' && staticFiles[url.pathname]) { const [file, type] = staticFiles[url.pathname]; return send(200, readFileSync(new URL(file, assets)), `${type}; charset=utf-8`); }
+      if (req.method === 'GET' && staticFiles.has(url.pathname)) { const [file, type] = staticFiles.get(url.pathname); return send(200, readFileSync(new URL(file, assets)), `${type}; charset=utf-8`); }
       const requestOrigin = req.headers.origin;
       const permittedOrigins = [origin, `http://localhost:${server.address().port}`];
       if (requestOrigin && !permittedOrigins.includes(requestOrigin)) problem('forbidden', 'Cross-origin requests are refused.');

package/src/baton.mjs

@@ -3,13 +3,15 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
-import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
+import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput, slugify } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { handoffNotDoneLine, recordPendingHandoff, runBatonDone } from './handoff-record.mjs';
 import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
 import { mutateFileSet } from './atomic-mutation.mjs';
 import { assertPlanMutationAuthorized, authoritativeSessionId, listOwnedPlans, readPlanOwnership } from './pickup.mjs';
+import { HANDOFF_TEMPLATES, parentPromptName } from './prompt-handoff.mjs';
+import { readTemplateStore, templateFile } from './template-store.mjs';
 
 // `runlist baton` is the one-command handoff: save the resume prompt AND release
 // the plan in a single atomic-ish verb. It exists because the three-step skill
@@ -123,6 +125,9 @@ export async function runBaton(argv, config, opts = {}) {
   let force = false;
   let replace = false;
   let done = false;
+  let subagent = false;
+  let parentPrompt = null;
+  let template = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -132,10 +137,32 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--force') { force = true; continue; }
     if (a === '--replace') { replace = true; continue; }
     if (a === '--done') { done = true; continue; }
+    if (a === '--subagent') { subagent = true; continue; }
+    if (a === '--template') { template = true; continue; }
+    if (a === '--parent') {
+      const value = argv[++i];
+      try { parentPrompt = parentPromptName(value); }
+      catch { die('--parent requires a resume prompt name, e.g. --parent resume-session-name.'); }
+      continue;
+    }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
   }
+  if (parentPrompt && !subagent) die('--parent requires --subagent.');
+  if (template) {
+    if (done || replace || force || statusFlag || note !== null || positionals.length || bodyFlag !== null) {
+      die('Use `runlist baton --template` or `runlist baton --subagent --template [--parent resume-name]` to print a draft without saving.');
+    }
+    if (subagent && !parentPrompt && process.env.RUNLIST_PARENT_PROMPT) parentPrompt = parentPromptName(process.env.RUNLIST_PARENT_PROMPT);
+    const name = subagent ? 'subagent' : 'resume';
+    const key = `handoff:${name}`;
+    const override = config ? readTemplateStore(config).data.templates[key]?.source : null;
+    const source = override ?? HANDOFF_TEMPLATES[key].source;
+    const draft = source.replaceAll('{{parent_prompt}}', parentPrompt ?? '<resume-parent-name>');
+    process.stdout.write(json ? JSON.stringify({ operation: 'baton-template', name, origin: override ? templateFile : 'Built-in', parentPrompt, template: draft }, null, 2) + '\n' : draft);
+    return;
+  }
 
   let planArg = null;
   let bodyArg = null;
@@ -162,6 +189,13 @@ export async function runBaton(argv, config, opts = {}) {
     body = readPipedBodyInput();
   }
   if (!body || !body.trim()) die(BODY_USAGE);
+  const draft = extractFrontmatter(body);
+  const draftFm = parseSimpleFrontmatter(draft.frontmatter);
+  if (!subagent && asString(draftFm.parent_prompt)) die('parent_prompt requires --subagent; a resume handoff cannot be its own child.');
+  if (subagent && !parentPrompt) {
+    const draftParent = asString(draftFm.parent_prompt);
+    if (draftParent) parentPrompt = parentPromptName(draftParent);
+  }
 
   // Resolve what's being handed off. Two modes:
   //   plan mode — a plan is released alongside the prompt (one status flip).
@@ -199,12 +233,30 @@ export async function runBaton(argv, config, opts = {}) {
     }
   }
 
-  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
-  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  const nameBase = slugify(planPath ? path.basename(planPath, '.md') : promptSlug);
+  const handoffPrefix = subagent ? 'subagent-' : 'resume-';
+  const recognizedPrefix = /^(resume-|subagent-)/.exec(nameBase)?.[0];
+  if (recognizedPrefix && recognizedPrefix !== handoffPrefix) {
+    die(`Nothing saved: ${nameBase} conflicts with ${subagent ? '--subagent' : 'the parent handoff default'}. Use an unprefixed name or ${handoffPrefix}<name>${subagent ? ', or omit --subagent for a parent handoff' : ', or pass --subagent for a child handoff'}.`);
+  }
+  const unprefixed = recognizedPrefix ? nameBase.slice(handoffPrefix.length) : nameBase;
+  if (!unprefixed || /^(resume-|subagent-)/.test(unprefixed)) {
+    die('Nothing saved: use a nonempty handoff name with at most one resume- or subagent- prefix.');
+  }
+  const slugBase = `${handoffPrefix}${unprefixed}`;
   let replacement = null;
+  let alternatePromptPath = null;
   const resolvePending = () => {
     const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
     const pending = pendingHandoffs(target.filePath, planPath, config);
+    if (planPath) {
+      const alternateSlug = `${subagent ? 'resume-' : 'subagent-'}${unprefixed}`;
+      alternatePromptPath = preparePromptDocument(alternateSlug, body, config, { dryRun: true }).filePath;
+      if (existsSync(alternatePromptPath)) {
+        const alternate = toRepoPath(alternatePromptPath, config.repoRoot);
+        if (!pending.includes(alternate)) pending.push(alternate);
+      }
+    }
     if (!replace) {
       if (pending.length) refusePendingHandoff(pending);
       return;
@@ -214,6 +266,9 @@ export async function runBaton(argv, config, opts = {}) {
       die(`Nothing replaced: --replace requires exactly one pending handoff. ${detail}`);
     }
     const oldRepoPath = pending[0];
+    if (subagent && /^resume-/i.test(path.basename(oldRepoPath))) {
+      die(`Nothing replaced: ${oldRepoPath} is a parent handoff. Inspect it with \`runlist prompts show ${path.basename(oldRepoPath, '.md')}\`; use a separate task slug for the child handoff, or omit --subagent to refresh the parent handoff.`);
+    }
     const oldPath = authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
     const oldRaw = readFileSync(oldPath, 'utf8');
     const { frontmatter, body: oldBody } = extractFrontmatter(oldRaw);
@@ -226,10 +281,14 @@ export async function runBaton(argv, config, opts = {}) {
     if (!planPath && priorPlanRef) {
       die(`Nothing replaced: ${oldRepoPath} links a plan (${priorPlanRef}). Use \`runlist baton <plan-file> @<draft-file> --replace\` so the plan link and release stay together.`);
     }
+    const priorParent = asString(fm.parent_prompt);
+    parentPrompt ??= priorParent;
     replacement = {
-      oldPath, oldRepoPath, oldRaw,
+      oldPath, oldRepoPath, oldRaw, priorParent,
       archivedPath: archivedCopyPath(oldPath, config),
-      alreadyCurrent: oldBody.trim() === body.trim()
+      alreadyCurrent: oldBody.trim() === draft.body.trim()
+        && Object.entries(draftFm).every(([key, value]) => key === 'parent_prompt' || JSON.stringify(fm[key]) === JSON.stringify(value))
+        && (priorParent ?? null) === parentPrompt
         && (!planPath || (priorPlanPath && path.resolve(priorPlanPath) === path.resolve(planPath))),
       canonicalPath: target.filePath,
     };
@@ -301,6 +360,12 @@ export async function runBaton(argv, config, opts = {}) {
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
 
+  if (subagent) {
+    if (!parentPrompt && process.env.RUNLIST_PARENT_PROMPT) parentPrompt = parentPromptName(process.env.RUNLIST_PARENT_PROMPT);
+    if (replacement && (replacement.priorParent ?? null) !== parentPrompt) replacement.alreadyCurrent = false;
+    if (!parentPrompt) warn('Subagent handoff has no parent link. Pass --parent resume-name, include parent_prompt in the draft, or inherit RUNLIST_PARENT_PROMPT. Use `runlist prompts link <child> --parent <resume-name>` to repair an existing handoff.');
+  }
+
   const preparedReplacement = prepared => {
     if (!replacement || replacement.alreadyCurrent) return { updates: [], creations: [], guards: [] };
     let archivedContent = renderLifecycleMutation(replacement.oldRaw,
@@ -330,25 +395,25 @@ export async function runBaton(argv, config, opts = {}) {
   try {
   if (!planPath) {
     const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
-    const prepared = preparePromptDocument(promptName, body, config, { dryRun });
+    const prepared = preparePromptDocument(promptName, body, config, { parentPrompt, dryRun });
     if (replacement) {
       const mutation = preparedReplacement(prepared);
       if (!dryRun && !replacement.alreadyCurrent) mutateFileSet(mutation, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
       newResult = { sessionFiles: [replacement.oldRepoPath, ...(replacement.alreadyCurrent ? [] : [toRepoPath(replacement.archivedPath, config.repoRoot)])] };
     } else {
       try {
-        newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
+        newResult = await runNew(['prompt', slugBase, '--body', body], config, { parentPrompt, dryRun, deferIndex: true });
       } catch (err) {
         // Lost a race with another baton between the pending check and the write.
         if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
         throw err;
       }
     }
-    createdSlug = promptName;
     promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
+    createdSlug = path.basename(promptRepoPath, '.md');
   } else {
     const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
-    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, dryRun });
+    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, parentPrompt, dryRun });
     const mutation = preparedReplacement(prepared);
     const setArgs = [status, planPath];
     if (force) setArgs.push('--force');
@@ -361,15 +426,18 @@ export async function runBaton(argv, config, opts = {}) {
         testHooks: opts.testHooks,
         additionalUpdates: dryRun ? [] : mutation.updates,
         creations: dryRun ? [] : replacement ? mutation.creations : [{ path: prepared.filePath, content: prepared.content }],
-        guards: dryRun ? [] : [...mutation.guards, ...(planGuard ? [planGuard] : [])],
+        guards: dryRun ? [] : [
+          ...mutation.guards, ...(planGuard ? [planGuard] : []),
+          ...(!replacement && alternatePromptPath ? [{ path: alternatePromptPath, absent: true }] : []),
+        ],
         deferIndex: true,
       });
     } catch (err) {
       if (/Destination already exists|File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
       throw err;
     }
-    createdSlug = prepared.slug;
     promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
+    createdSlug = path.basename(promptRepoPath, '.md');
     statusChanged = oldStatus !== status;
     if (!dryRun && !replacement) {
       try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
@@ -408,6 +476,7 @@ export async function runBaton(argv, config, opts = {}) {
   }
   const operationResult = {
     operation: 'baton',
+    parentPrompt,
     dryRun: Boolean(dryRun),
     disposition: replacement?.alreadyCurrent && !statusChanged && !wouldReleaseClaim ? 'already-current' : dryRun ? 'would-change' : 'applied',
     wouldChange: Boolean(dryRun),

package/src/commands.mjs

@@ -134,13 +134,14 @@ const definitions = [
     form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] }),
     form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
+    form('link <child...> --parent <resume-name>', { subcommands: ['link'], args: positionals(1, Infinity), options: [value('--parent'), flag('--json')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
     form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--replace'), flag('--done'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), value('--parent'), flag('--template'), flag('--force'), flag('--replace'), flag('--done'), flag('--subagent'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
     form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
@@ -180,7 +181,7 @@ const definitions = [
   ]),
   command('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })]),
   command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--prompts'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),

package/src/config.mjs

@@ -88,14 +88,10 @@ const DEFAULTS = {
     skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
     skipWarningsFor: ['archived', 'partial', 'queued-after'],
     terminalStatuses: ['archived', 'deprecated', 'reference'],
-    // F15: per-status filing buckets (status → dirName). Built-in held/paused
-    // statuses file under the owning type folder; archive remains a separate
-    // primitive untouched.
-    // Plans only. A paused plan files under <plansDir>/held/ so the live plan
-    // list stays readable. Prompts were removed from this map 2026-08-30 along
-    // with their held/shelved statuses — `archived` is the only directory a
-    // prompt ever moves into.
-    filedStatuses: { paused: 'held' },
+    // Optional status → directory filing. Ordinary status changes keep the
+    // current path by default; archive remains a separate move. Repositories
+    // can opt in here or with per-status `filed: true` / `filed: 'held'`.
+    filedStatuses: {},
     // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
     // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
     // Prompts are session-local churn — keeping their archive out of the shared
@@ -465,14 +461,24 @@ function deepMerge(defaults, overrides, parentPath = '') {
   return result;
 }
 
-export async function resolveConfig(cwd, explicitConfigPath) {
+// Locate repository data without importing or executing its JavaScript config.
+export function locateConfig(cwd, explicitConfigPath) {
   const configPath = explicitConfigPath
     ? path.resolve(cwd, explicitConfigPath)
     : findConfigFile(cwd);
+  const configDir = configPath && existsSync(configPath) ? path.dirname(configPath) : cwd;
+  let repoRoot = configDir;
+  for (let dir = configDir; dir !== path.parse(dir).root; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, '.git'))) { repoRoot = dir; break; }
+  }
+  return {configPath,configDir,repoRoot};
+}
+
+export async function resolveConfig(cwd, explicitConfigPath) {
+  const {configPath,configDir,repoRoot} = locateConfig(cwd, explicitConfigPath);
 
   let userConfig = {};
   let hooks = {};
-  let configDir = cwd;
 
   if (configPath && existsSync(configPath)) {
     const configUrl = pathToFileURL(configPath).href;
@@ -483,8 +489,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
       die('Failed to load config: ' + configPath + '\n' + err.message + '\nCheck for syntax errors in your config file.');
     }
 
-    configDir = path.dirname(configPath);
-
     for (const [key, value] of Object.entries(mod)) {
       if (key === 'default') continue;
       if (typeof value === 'function') {
@@ -523,20 +527,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
-  // Find repo root by walking up looking for .git
-  let repoRoot = configDir;
-  {
-    let dir = configDir;
-    const fsRoot = path.parse(dir).root;
-    while (dir !== fsRoot) {
-      if (existsSync(path.join(dir, '.git'))) {
-        repoRoot = dir;
-        break;
-      }
-      dir = path.dirname(dir);
-    }
-  }
-
   // Resolve document types
   const typesConfig = config.types ?? {};
   const validTypes = new Set(Object.keys(typesConfig));

package/src/doctor.mjs

@@ -1,4 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { installationReport, formatInstallationReport } from './installation.mjs';
+import { diagnosePromptParents } from './prompt-handoff.mjs';
 import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
@@ -235,6 +237,17 @@ function runDoctorSession(argv) {
 }
 
 export function runDoctor(argv, config, opts = {}) {
+  if (argv.includes('--prompts')) {
+    const index=buildIndex(config,{fast:true,invokeHooks:false});
+    const result=diagnosePromptParents(index.docs.filter(doc=>doc.type==='prompt'),config);
+    if(argv.includes('--json'))process.stdout.write(JSON.stringify(result,null,2)+'\n');
+    else {
+      process.stdout.write(`Prompt parent links: ${result.children} child handoffs · ${result.counts.linked??0} explicitly linked\n`);
+      for(const item of result.findings)process.stdout.write(`  ${item.state}: ${item.path}${item.parentPrompt?` → ${item.parentPrompt}`:''}${item.candidates.length?` (${item.candidates.join(', ')})`:''}\n`);
+      if(result.findings.length)process.stdout.write('Inspect with `runlist prompts show <child>`. Repair an existing link with `runlist prompts link <child> --parent <resume-name>`; diagnostics change no prompts.\n');
+    }
+    return result;
+  }
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
     return;
@@ -434,6 +447,7 @@ function runDoctorProject(config, { json = false } = {}) {
   const skillDriftWarnings = checkSkillDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
+    installations: installationReport(config),
     packageDependency: depVersion,
     claudeCommandWarnings,
     deprecatedCommandMentions,
@@ -448,6 +462,7 @@ function runDoctorProject(config, { json = false } = {}) {
   }
 
   process.stdout.write(bold('runlist doctor --project') + '\n\n');
+  process.stdout.write(formatInstallationReport(result.installations)+'\n');
   process.stdout.write(`- running CLI version: ${result.cliVersion ?? 'unknown'}\n`);
   process.stdout.write(`- package dependency: ${result.packageDependency ?? '(none found)'}\n`);
   process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);

package/src/hud.mjs

@@ -294,6 +294,8 @@ export function buildHud(config) {
 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>. Add --parent resume-<name> when known to group it under its parent prompt. Use a task slug under a parent-owned plan; release only your own plan. Parent batons default to resume-<name>.',
+  'Child draft: `runlist baton --subagent --template --parent resume-<name>` prints the checkout’s child outline (built-in: Task, State, Next, Evidence and Boundaries). Carry parent_prompt in the draft or pass RUNLIST_PARENT_PROMPT into the child environment. Save full records at durable repo-relative paths. Repair old links with `runlist prompts link <child...> --parent 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`).',
@@ -398,7 +400,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}`;
 }
 

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