runlist 0.96.0 → 0.96.1

package/src/baton.mjs

@@ -10,6 +10,8 @@ import { handoffNotDoneLine, recordPendingHandoff, runBatonDone } from './handof
 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
@@ -124,6 +126,8 @@ export async function runBaton(argv, config, opts = {}) {
   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];
@@ -134,10 +138,31 @@ export async function runBaton(argv, config, opts = {}) {
     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;
@@ -164,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).
@@ -249,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,
     };
@@ -324,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,
@@ -353,14 +395,14 @@ 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]);
@@ -371,7 +413,7 @@ export async function runBaton(argv, config, opts = {}) {
     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');
@@ -434,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('--subagent'), 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,7 +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>. Use a task slug under a parent-owned plan; release only your own plan. Parent batons default to resume-<name>.',
+  '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`).',
@@ -399,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';
+}

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