runlist 0.99.1 → 0.100.0

package/src/prompts.mjs

@@ -1,13 +1,14 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, openSync, readSync, closeSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { agentSessionSource, asString, toRepoPath, die, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
-import { buildIndex, resolveDocArg } from './index.mjs';
+import { buildIndex, collectDocFiles, parseDocFile, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { authorizeManagedSource } from './managed-path.mjs';
+import { isHandoffsMode, managesFile, outsideHandoffs, outsideHandoffsLine } from './handoffs-scope.mjs';
 import {
   authoritativeSessionId,
   classifyPlanPickup,
@@ -17,7 +18,7 @@ import {
 } from './pickup.mjs';
 import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
-import { formatPlanChanges, planChangesSince } from './plan-changes.mjs';
+import { formatPlanChanges, planChangesSince, summarizePlanChanges } from './plan-changes.mjs';
 import { groupPrompts, parentPromptName } from './prompt-handoff.mjs';
 import { mutateFileSet } from './atomic-mutation.mjs';
 
@@ -36,6 +37,7 @@ export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
 
   if (sub && REMOVED_SUBCOMMANDS.has(sub)) {
+    if (isHandoffsMode(config)) die(`\`runlist prompts ${sub}\` was removed — a prompt is pending or archived, and nothing else.\nTo set one aside, \`runlist prompts archive <file>\`.`);
     die(`\`runlist prompts ${sub}\` was removed — a prompt is pending or archived, and nothing else.\n`
       + 'A prompt directs work, so parking one instead of archiving it leaves work state outside the\n'
       + 'plan that owns it. Lift its content into that plan, then `runlist prompts archive <file>`.');
@@ -121,29 +123,60 @@ function childHandoffs(repoPath, config, index = null) {
   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` };
+  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. ${isHandoffsMode(config) ? 'Fold completed results into the parent\'s work' : '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 readPromptHeader(file) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const byte = Buffer.alloc(1), bytes = [];
+    let line = '', lines = 0;
+    while (bytes.length < 16 * 1024 && readSync(fd, byte, 0, 1, null)) {
+      bytes.push(byte[0]);
+      line += String.fromCharCode(byte[0]);
+      if (byte[0] !== 10) continue;
+      const marker = line.trimEnd() === '---';
+      if (lines++ === 0 && !marker) return '';
+      if (lines > 1 && marker) return Buffer.from(bytes).toString('utf8');
+      line = '';
+    }
+  } catch { /* an unreadable or disappearing header cannot supply metadata */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  return '';
+}
+
+function promptListIndex(config) {
+  const docs = [];
+  // Discovery stays inside the configured roots. Type filtering happens on
+  // the header below, including in handoffs mode, without its whole-file read.
+  for (const file of collectDocFiles({ ...config, mode: 'planning' })) {
+    const source = readPromptHeader(file);
+    const fm = parseSimpleFrontmatter(extractFrontmatter(source).frontmatter);
+    if (asString(fm.type) === 'prompt') {
+      docs.push({ ...parseDocFile(file, config, { fast: true, source }), plan: asString(fm.plan) });
+    }
+  }
+  return { docs };
 }
 
 function runPromptsList(argv, config, opts = {}) {
-  // Listing prompts renders slug / status / updated / target — nothing any
-  // validating pass produces, and `runQuery` never reads warnings either. A
-  // full `buildIndex` here parsed every body in the repo through the ref,
-  // git-staleness and hub passes just to print a small prompt list,
-  // and then `pendingPromptsOldestFirst` scanned the tree a second time. One
-  // fast index, shared, on the same terms hud reads on.
-  const index = buildIndex(config, { fast: true, invokeHooks: false });
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
   const json = argv.includes('--json');
 
+  const hasPositionalFilter = argv.some(a => !a.startsWith('-') && a !== 'list');
+  const defaultList = !json && !hasStatusFlag && !includeArchived && !hasPositionalFilter && sub !== 'status'
+    && !argv.some(a => a.startsWith('--sort') || a.startsWith('--limit') || a === '--all');
+  const index = defaultList && !opts.verbose ? promptListIndex(config) : buildIndex(config, { fast: true, invokeHooks: false });
+
   if (opts.verbose && !json) {
     renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived });
     return;
   }
 
-  const hasPositionalFilter = argv.some(a => !a.startsWith('-') && a !== 'list');
-  if (!json && !hasStatusFlag && !includeArchived && !hasPositionalFilter && sub !== 'status' && !argv.some(a => a.startsWith('--sort') || a.startsWith('--limit') || a === '--all')) {
+  if (defaultList) {
     renderPromptQueueList(index, config);
     return;
   }
@@ -180,37 +213,67 @@ function renderPromptQueueList(index, config) {
   process.stdout.write(dim(`${prompts.length} prompts · ${summary}`) + '\n\n');
 
   const groups = groupPrompts(prompts);
+  const freshness = promptFreshness(prompts, config);
   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]`;
+  const childFreshness = children => {
+    const states = new Map();
+    for (const child of children) {
+      const state = freshness.get(child).change;
+      states.set(state, (states.get(state) ?? 0) + 1);
+    }
+    const ages = children.map(child => freshness.get(child).age).filter(Number.isFinite);
+    const age = ages.length === children.length ? `${Math.min(...ages)}-${Math.max(...ages)}d old` : 'age unknown';
+    return `${age}; targets: ${[...states].map(([state, count]) => `${count} ${state}`).join(', ')}`;
+  };
   for (const { doc: p, children } of visible) {
     const slug = path.basename(p.path, '.md').padEnd(maxSlug);
-    const marker = p.path === nextPath ? green('[NEXT]') : '      ';
     const status = `[${(p.status ?? 'unknown').toUpperCase()}]`;
-    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`);
+    const badge = children.length ? ` ${dim(childCount(children))}` : '';
+    process.stdout.write(`  ${slug} ${status}${badge} · ${freshness.get(p).text}\n`);
+    if (children.length) process.stdout.write(dim(`    children: ${childFreshness(children)}\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`);
+    process.stdout.write(`  ${childCount(children)} · ${childFreshness(children)}\n`);
   }
   if (standalone.length || visible.some(group => group.children.length)) {
     process.stdout.write(dim('\nUse `rl prompts --verbose` to expand subagent prompts.\n'));
   }
 }
 
-// Resolve a prompt's "target plan" for `prompts list --verbose`. Order:
-//   1. frontmatter `related_plans:` (first entry — assumed plan slug)
-//   2. frontmatter `parent_plan:`
-//   3. first body markdown link to a .md file
+function promptFreshness(prompts, config) {
+  const resolved = new Map();
+  const targets = prompts.map(doc => {
+    if (!doc.plan) return findPromptTarget(doc, config);
+    const key = `${path.dirname(doc.path)}\0${doc.plan}`;
+    if (!resolved.has(key)) resolved.set(key, findPromptTarget(doc, config));
+    return resolved.get(key);
+  });
+  const changes = summarizePlanChanges(prompts.map((doc, i) => ({ plan: targets[i], since: doc.created })), config);
+  const now = Date.now();
+  return new Map(prompts.map((doc, i) => {
+    const time = doc.created ? new Date(doc.created).getTime() : NaN;
+    const age = Number.isFinite(time) && time <= now ? Math.floor((now - time) / 86_400_000) : null;
+    const target = targets[i]?.replace(/\s/g, ' ');
+    return [doc, { age, change: changes[i], text: `${age === null ? 'age unknown' : `${age}d old`} · ${target ?? 'target unknown'}: ${changes[i]}` }];
+  }));
+}
+
+// Explicit baton links win, then related_plans and parent_plan. Verbose
+// listings also retain the first body link fallback from the full index.
 // Returns a repo-relative display path or null.
 function findPromptTarget(promptDoc, config) {
+  if (promptDoc.plan) {
+    const promptPath = path.resolve(config.repoRoot, promptDoc.path);
+    const fallbackRoot = promptDoc.plan.startsWith(config.docsRootPrefix || 'docs/') ? config.repoRoot : path.dirname(promptPath);
+    return linkedPlanRepoPath(promptDoc.plan, promptPath, config)
+      ?? toRepoPath(path.resolve(fallbackRoot, promptDoc.plan), config.repoRoot);
+  }
   const refs = promptDoc.refFields ?? {};
   const fmTargets = [...(refs.related_plans ?? []), ...(refs.parent_plan ?? [])];
   for (const t of fmTargets) {
@@ -245,6 +308,11 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
   if (!hasStatusFlag && !includeArchived) {
     prompts = prompts.filter(d => d.status !== 'archived');
   }
+  prompts = prompts.map(doc => {
+    const header = readPromptHeader(path.resolve(config.repoRoot, doc.path));
+    const fm = parseSimpleFrontmatter(extractFrontmatter(header).frontmatter);
+    return { ...doc, plan: asString(fm.plan) };
+  });
   if (prompts.length === 0) {
     process.stdout.write('No prompts.\n');
     return;
@@ -256,6 +324,7 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
   for (const p of prompts) counts[p.status ?? 'unknown'] = (counts[p.status ?? 'unknown'] ?? 0) + 1;
   const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
   process.stdout.write(`${prompts.length} prompt${prompts.length === 1 ? '' : 's'} · ${summary}\n\n`);
+  const freshness = promptFreshness(prompts, config);
 
   const render = (p, child) => {
     const slug = path.basename(p.path, '.md');
@@ -263,7 +332,7 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
     const status = (p.status ?? 'unknown').toUpperCase();
     const arrow = target ? `  ${dim('→')} ${target}` : `  ${dim('→ (no target plan)')}`;
     const indent = child ? '    - ' : '  ';
-    process.stdout.write(`${indent}${green(slug)}  [${status}]\n${child ? '    ' : ''}${arrow}\n`);
+    process.stdout.write(`${indent}${green(slug)}  [${status}] · ${freshness.get(p).text}\n${child ? '    ' : ''}${arrow}\n`);
   };
   for (const {doc,children} of groupPrompts(prompts)) {
     render(doc, false);
@@ -305,12 +374,17 @@ async function runPromptsNext(argv, config, opts = {}) {
 // helpful message (no match / ambiguous match).
 export function resolvePromptInput(input, config, options = {}) {
   const dieOnMiss = options.dieOnMiss !== false;
+  // A handoffs-only project's other Markdown is never a prompt to resolve.
+  if (outsideHandoffs(input, config)) {
+    if (dieOnMiss) die(outsideHandoffsLine(input));
+    return null;
+  }
   const direct = resolveDocPath(input, config);
-  if (direct) return direct;
+  if (direct && managesFile(direct, config)) return direct;
 
   if (!input.endsWith('.md')) {
     const withExt = resolveDocPath(input + '.md', config);
-    if (withExt) return withExt;
+    if (withExt && managesFile(withExt, config)) return withExt;
   }
 
   const index = buildIndex(config, { fast: true, invokeHooks: false });

package/src/rename.mjs

@@ -11,6 +11,9 @@ import { availableSessionId, prepareOwnershipMigration } from './pickup.mjs';
 import { moveFileAtomic } from './atomic-mutation.mjs';
 import { configuredReferenceFields, createReferenceIdentitySet, planReferenceMove, rewriteDocumentReferences } from './reference-planner.mjs';
 import { reportMovedCodeRefs } from './code-refs.mjs';
+import { isHandoffsMode, readsAsPrompt } from './handoffs-scope.mjs';
+import { promptDirectory } from './new.mjs';
+import { PROMPT_DIR } from './naming.mjs';
 
 export async function runRename(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -35,6 +38,16 @@ export async function runRename(argv, config, opts = {}) {
   } else {
     newPath = path.join(path.dirname(oldPath), newInput.endsWith('.md') ? newInput : `${newInput}.md`);
   }
+  // One prompt location (src/naming.mjs): before any config and where
+  // planning is off, a prompt moves within the prompt folder at the project's
+  // top and nowhere else, so a rename never starts a second docs/prompts/.
+  if ((!config.configFound || isHandoffsMode(config)) && readsAsPrompt(oldPath)) {
+    const folder = config.configFound ? promptDirectory(config) : path.join(config.repoRoot, ...PROMPT_DIR.split('/'));
+    const relative = path.relative(folder, newPath);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+      die(`Nothing renamed: prompts live in ${toRepoPath(folder, config.repoRoot)}/, and ${toRepoPath(newPath, config.repoRoot)} is outside it. Choose a name inside ${toRepoPath(folder, config.repoRoot)}/.`);
+    }
+  }
   if (existsSync(newPath)) die(`Target already exists: ${toRepoPath(newPath, config.repoRoot)}`);
   newPath = authorizeManagedDestination(newPath, config, { root: sourceAuthorization.root, kind: 'Rename destination' }).path;
 

package/src/setup-carry.mjs

@@ -0,0 +1,291 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmdirSync } from 'node:fs';
+import path from 'node:path';
+import { promptDirectory, planDirectory } from './new.mjs';
+import { archiveBaseFor } from './lifecycle.mjs';
+import { collectDocFiles } from './index.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { authorizeManagedSource, authorizeManagedSweep, authorizeRepoGeneratedPath, inLegacyPromptFolder } from './managed-path.mjs';
+import { moveFileAtomic } from './atomic-mutation.mjs';
+import { configuredReferenceFields, planReferenceMove } from './reference-planner.mjs';
+import { availableSessionId, prepareOwnershipMigration } from './pickup.mjs';
+import { listPendingHandoffs } from './handoff-record.mjs';
+import { captureGitIndexGeneration, isTracked } from './git.mjs';
+import { toRepoPath } from './util.mjs';
+import { locateConfig, resolveConfig } from './config.mjs';
+import { CONFIG_FILENAMES, LEGACY_PROMPT_DIR, RETIRED_PROMPT_STATUSES, rootIsWorkingFolder } from './naming.mjs';
+import { statusMetadataFor } from './status-metadata.mjs';
+
+function markdownFiles(directory, config) {
+  authorizeRepoGeneratedPath(directory, config, { kind: 'Setup carry-over folder' });
+  if (!existsSync(directory)) return [];
+  if (!lstatSync(directory).isDirectory()) throw new Error(`Carry-over folder must be a regular directory: ${directory}`);
+  return readdirSync(directory, { withFileTypes: true }).filter(entry => entry.isFile() && entry.name.endsWith('.md'))
+    .map(entry => path.join(directory, entry.name)).sort();
+}
+
+function directories(config, type) {
+  const live = type === 'prompt' ? promptDirectory(config) : planDirectory(config);
+  const archive = path.join(archiveBaseFor(path.join(live, 'document.md'), config.docsRoot, type, config), config.archiveDir);
+  return [live, archive];
+}
+
+// Live/archive pairs to carry from: the resolver's pre-config folders.
+function sourceDirectories(config, type) {
+  return directories(config, type);
+}
+
+// The root prompts/ older builds saved prompts in before any config. Nothing
+// writes there now (src/naming.mjs); every prompt below it, at any depth, is
+// carried with its folder relative to prompts/ kept.
+export function legacyPromptRoot(config) {
+  return rootIsWorkingFolder(config) ? path.join(config.docsRoot, ...LEGACY_PROMPT_DIR.split('/')) : null;
+}
+
+function legacyMarkdownFiles(root, config) {
+  authorizeRepoGeneratedPath(root, config, { kind: 'Setup carry-over folder' });
+  if (!existsSync(root)) return [];
+  if (!lstatSync(root).isDirectory()) throw new Error(`Carry-over folder must be a regular directory: ${root}`);
+  const files = [];
+  // A folder's own files before its subfolders, so live prompts are planned
+  // ahead of the archive below them, as they always were.
+  const walk = directory => {
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) if (entry.isFile() && entry.name.endsWith('.md')) files.push(path.join(directory, entry.name));
+    for (const entry of entries) if (entry.isDirectory()) walk(path.join(directory, entry.name));
+  };
+  walk(root);
+  return files;
+}
+
+function carryKey(target) {
+  return target.normalize('NFC').toLowerCase().normalize('NFC');
+}
+
+// The project as it read before any config: the docs root is the project's
+// top, so the folders an older runlist saved plans and prompts in are the
+// carry's sources. Setup turning planning on in a handoffs-only project
+// carries from here too, under the same roots a fresh setup uses.
+export async function preConfigView(top) {
+  const view = await resolveConfig(top, path.join(top, `${CONFIG_FILENAMES[0]}.pre-config`));
+  return { ...view, configFound: false, configPath: null, mode: 'plans', planning: true };
+}
+
+// Only the resolver's pre-config locations qualify. An unrelated prompts
+// library, arbitrary Markdown, and files under an existing config are not
+// adoption candidates. Status vocabularies come from the resolved defaults.
+export function planSetupCarry(before, after, enabled = true, { types = ['prompt', 'plan'] } = {}) {
+  const result = { moves: [], outstanding: [], remaining: [] };
+  if (before.configFound) return result;
+  const candidates = new Set();
+  const seen = new Set();
+  const targets = new Set();
+  const consider = ({ source, target, type, expectedSource }) => {
+    if (source === target) return;
+    authorizeManagedSource(source, before, { kind: 'Setup carry-over source' });
+    authorizeRepoGeneratedPath(target, after, { kind: 'Setup carry-over destination' });
+    const from = toRepoPath(source, before.repoRoot), to = toRepoPath(target, before.repoRoot);
+    if (!enabled) return;
+    const targetKey = carryKey(target);
+    if (existsSync(target) || targets.has(targetKey)) {
+      result.outstanding.push({ description: `Carry-over collision: ${from} → ${to}; ${targets.has(targetKey) ? 'collides with another file being carried' : 'destination exists'}, source left in place`, path: source });
+      return;
+    }
+    try { if (type === 'plan') prepareOwnershipMigration(from, target, before, { sessionId: availableSessionId() }); }
+    catch (error) {
+      result.outstanding.push({ description: `Carry-over refused for ${from}: ${error.message}`, path: source });
+      return;
+    }
+    result.moves.push({ source, target, from, to, type, expectedSource });
+    targets.add(targetKey);
+  };
+  for (const type of types) {
+    const oldDirs = sourceDirectories(before, type);
+    const newDirs = directories(after, type);
+    for (const [i, directory] of oldDirs.entries()) {
+      if (directory === newDirs[i % 2]) continue;
+      for (const source of markdownFiles(directory, before)) {
+        candidates.add(source);
+        if (seen.has(source)) continue;
+        const expectedSource = readFileSync(source, 'utf8');
+        const parsed = parseSimpleFrontmatter(extractFrontmatter(expectedSource).frontmatter ?? '');
+        if (parsed.type !== type || !before.typeStatuses.get(type)?.has(parsed.status)) continue;
+        const archiveStatus = statusMetadataFor(before, type, parsed.status)?.archive;
+        // The shared root-level archive is also a common user folder. Its
+        // location alone is no evidence that runlist archived this document.
+        if (directory === path.join(before.repoRoot, before.archiveDir) && !archiveStatus) continue;
+        seen.add(source);
+        const archived = i % 2 === 1 || archiveStatus;
+        consider({ source, target: path.join(newDirs[archived ? 1 : 0], path.basename(source)), type, expectedSource });
+      }
+    }
+    // A `type: prompt` file anywhere below the root prompts/, with a status
+    // runlist gives prompts or one an older build did, is one runlist saved
+    // there; everything else there is the user's and stays.
+    const legacy = type === 'prompt' ? legacyPromptRoot(before) : null;
+    if (!legacy) continue;
+    for (const source of legacyMarkdownFiles(legacy, before)) {
+      candidates.add(source);
+      if (seen.has(source)) continue;
+      const expectedSource = readFileSync(source, 'utf8');
+      const parsed = parseSimpleFrontmatter(extractFrontmatter(expectedSource).frontmatter ?? '');
+      if (parsed.type !== 'prompt' || !(before.typeStatuses.get(type)?.has(parsed.status) || RETIRED_PROMPT_STATUSES.has(parsed.status))) continue;
+      seen.add(source);
+      const relative = path.relative(legacy, source);
+      const archivedAlready = relative.split(path.sep).slice(0, -1).includes(before.archiveDir);
+      const archiveStatus = before.typeStatuses.get(type)?.has(parsed.status) && statusMetadataFor(before, type, parsed.status)?.archive;
+      consider({ source, target: path.join(newDirs[archiveStatus && !archivedAlready ? 1 : 0], relative), type, expectedSource });
+    }
+  }
+  result.remaining = [...candidates].filter(file => !result.moves.some(move => move.source === file));
+  return result;
+}
+
+// Everything left in the root prompts/ (what the carry does not move) is the
+// user's, by its path or through a symlinked folder: the carry never rewrites
+// it, and a link there to a carried file is reported instead.
+function staysInLegacyFolder(file, config, carried) {
+  return !carried.has(path.resolve(file)) && inLegacyPromptFolder(file, config.repoRoot);
+}
+
+function carryReferenceFields(config) {
+  return [...new Set([...configuredReferenceFields(config), 'plan', 'parent_prompt'])];
+}
+
+// Links to a carried file from Markdown runlist does not manage, which the
+// move's reference sweep never rewrites: a README with no frontmatter that
+// points at prompts/older.md, say, or any document that stays in the root
+// prompts/. Reported for the user to update, never edited. Read only on the
+// explicit save, init and setup paths.
+export function unmanagedCarryReferences(config, moves) {
+  if (!moves.length) return [];
+  const carried = new Set(moves.map(move => path.resolve(move.source)));
+  const plain = [];
+  for (const file of collectDocFiles(config)) {
+    if (carried.has(path.resolve(file))) continue;
+    let content;
+    try { content = readFileSync(file, 'utf8'); } catch { continue; }
+    if (extractFrontmatter(content).frontmatter) {
+      if (staysInLegacyFolder(file, config, carried)) plain.push({ path: file, content });
+      continue;
+    }
+    // Lent a frontmatter block so the planner reads the body; never written.
+    plain.push({ path: file, content: `---\nrunlist-probe: true\n---\n${content}` });
+  }
+  if (!plain.length) return [];
+  const referenceFields = carryReferenceFields(config);
+  const found = [];
+  for (const move of moves) {
+    const documents = [{ path: move.source, content: move.expectedSource }, ...plain];
+    const { updates } = planReferenceMove({ documents, oldPath: move.source, newPath: move.target, repoRoot: config.repoRoot, referenceFields });
+    for (const update of updates) found.push({ file: toRepoPath(update.path, config.repoRoot), from: move.from, to: move.to });
+  }
+  return found.sort((a, b) => a.file.localeCompare(b.file) || a.from.localeCompare(b.from));
+}
+
+// Only clean parents of sources moved by this run or its recovery. An empty
+// default folder alone does not establish that setup owns its cleanup.
+export function cleanupSetupSourceDirectories(config, movedSources) {
+  if (config.configFound) return;
+  const legacy = legacyPromptRoot(config);
+  const legacyFolders = legacy ? movedSources.flatMap(source => {
+    const folders = [];
+    for (let directory = path.dirname(source); directory.startsWith(`${legacy}${path.sep}`); directory = path.dirname(directory)) folders.push(directory);
+    return path.dirname(source) === legacy || folders.length ? [...folders, legacy] : [];
+  }) : [];
+  const sources = [...new Set([...['prompt', 'plan'].flatMap(type => sourceDirectories(config, type)), ...legacyFolders])].filter(directory =>
+    movedSources.some(source => path.dirname(source) === directory || path.dirname(source).startsWith(`${directory}${path.sep}`)));
+  for (const directory of sources.sort((a, b) => b.length - a.length)) {
+    if (directory === config.repoRoot) continue;
+    authorizeRepoGeneratedPath(directory, config, { kind: 'Setup source folder' });
+    try { rmdirSync(directory); }
+    catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
+  }
+}
+
+// Carry before publishing the first config, so a retained move transaction is
+// recoverable under the same (unconfigured) roots that authorized its source.
+// Each move is transactional; setup itself remains a sequence of stages.
+// `expectedConfig` ({ path, content }) is the handoffs-only config setup is
+// about to upgrade: it must stay exactly as previewed, and no other config may
+// appear, for the whole carry.
+export function applySetupCarry(moves, config, { testHooks, expectedConfig = null } = {}) {
+  const completed = [];
+  const createdDirectories = [];
+  const expectedSources = new Map(moves.map(move => [move.source, move.expectedSource]));
+  const carried = new Set(moves.map(move => path.resolve(move.source)));
+  const configUnchanged = () => {
+    if (!expectedConfig) return !config.configFound && !locateConfig(config.configDir).configPath;
+    try { return locateConfig(config.configDir).configPath === expectedConfig.path && readFileSync(expectedConfig.path, 'utf8') === expectedConfig.content; }
+    catch { return false; }
+  };
+  const configGuards = CONFIG_FILENAMES.map(name => path.join(config.configDir, name)).map(file =>
+    expectedConfig && path.resolve(file) === path.resolve(expectedConfig.path) ? { path: file, expectedContent: expectedConfig.content } : { path: file, absent: true });
+  try {
+    const checkConfig = () => {
+      if (!configUnchanged()) throw new Error(expectedConfig ? 'The config changed after the carry-over preview; rerun setup.' : 'A config appeared after the carry-over preview; rerun setup.');
+    };
+    checkConfig();
+    for (const move of moves) {
+      if (readFileSync(move.source, 'utf8') !== move.expectedSource) throw new Error(`Carry-over source changed after preview: ${move.from}`);
+    }
+    for (const move of moves) {
+      // What stays in the root prompts/ is the user's and is never rewritten;
+      // unmanagedCarryReferences lists its links to a carried file.
+      const files = collectDocFiles(config).filter(file => !staysInLegacyFolder(file, config, carried));
+      authorizeManagedSweep(files, config, { kind: 'Setup carry-over reference source' });
+      const documents = files.map(file => ({ path: file, content: readFileSync(file, 'utf8') }));
+      const references = planReferenceMove({ documents, oldPath: move.source, newPath: move.target, repoRoot: config.repoRoot, referenceFields: carryReferenceFields(config) });
+      const ownership = move.type === 'plan' ? prepareOwnershipMigration(move.from, move.target, config, { sessionId: availableSessionId() }) : null;
+      const handoffs = listPendingHandoffs(config).flatMap(record => {
+        const expectedContent = readFileSync(record.recordFile, 'utf8');
+        const data = JSON.parse(expectedContent);
+        let changed = false;
+        for (const field of ['prompt', 'plan']) if (data[field] === move.from) { data[field] = move.to; changed = true; }
+        if (!changed) return [];
+        authorizeRepoGeneratedPath(record.recordFile, config, { kind: 'Setup handoff record' });
+        return [{ path: record.recordFile, expectedContent, content: JSON.stringify(data, null, 2) + '\n', label: 'handoff' }];
+      });
+      const tracked = isTracked(move.source, config.repoRoot);
+      // Scaffold directories belong to setup, never to the move transaction.
+      // Keep failed carry cleanup separate from transaction recovery; recovery
+      // evidence must be resolved under the old roots before setup writes config.
+      for (const directory of [path.dirname(move.target), ...(ownership ? [path.dirname(ownership.newRecordPath)] : [])]) {
+        authorizeRepoGeneratedPath(directory, config, { kind: 'Setup carry-over folder' });
+        const missing = [];
+        for (let next = directory; !existsSync(next); next = path.dirname(next)) missing.push(next);
+        for (const next of missing.reverse()) {
+          try { mkdirSync(next); }
+          catch (error) { if (error.code === 'EEXIST') continue; throw error; }
+          createdDirectories.push({ path: next, identity: lstatSync(next) });
+        }
+      }
+      checkConfig();
+      moveFileAtomic(move.source, move.target, references.movedContent, {
+        repoRoot: config.repoRoot, config, expectedSourceContent: expectedSources.get(move.source),
+        updates: [...references.updates, ...handoffs],
+        creations: ownership ? [{ path: ownership.newRecordPath, content: ownership.newContent, label: 'ownership' }] : [],
+        deletions: ownership ? [{ path: ownership.oldRecordPath, expectedContent: ownership.oldContent, label: 'ownership' }] : [],
+        guards: configGuards,
+        gitMove: tracked, gitIndex: tracked ? captureGitIndexGeneration(config.repoRoot) : null,
+        operation: 'move', sessionId: availableSessionId(), testHooks: { ...testHooks, beforeMoveSnapshot(info) {
+          testHooks?.beforeMoveSnapshot?.(info);
+          checkConfig();
+        } },
+      });
+      for (const update of references.updates) if (expectedSources.has(update.path)) expectedSources.set(update.path, update.content);
+      completed.push(move);
+      cleanupSetupSourceDirectories(config, [move.source]);
+    }
+    return { completed };
+  } catch (error) {
+    if (configUnchanged()) {
+      for (const entry of createdDirectories.reverse()) {
+        try {
+          const stat = lstatSync(entry.path);
+          if (stat.isDirectory() && stat.dev === entry.identity.dev && stat.ino === entry.identity.ino) rmdirSync(entry.path);
+        } catch { /* Keep nonempty/replaced directories and preserve the original failure. */ }
+      }
+    }
+    return { completed, error: error.message };
+  }
+}

package/src/setup-waiting.mjs

@@ -0,0 +1,20 @@
+import { resolveConfig } from './config.mjs';
+import { planHandoffsUpgrade } from './handoffs-mode.mjs';
+import { planSetupCarry, preConfigView } from './setup-carry.mjs';
+
+// In a handoffs-only project, the plans and prompts an older runlist saved
+// before there was a config, which `runlist setup` carries in when it turns
+// planning on (src/setup-carry.mjs): counted by setup's own carry planner, so
+// the planning-off line says exactly what setup will bring in. The carry reads
+// the old default folders only (plans/, the root archive, the root prompts/),
+// never the whole project, and nothing here runs on a hook path. Counting
+// never stops a command: anything it cannot read counts as nothing.
+export async function documentsWaitingForSetup(config) {
+  if (config?.mode !== 'handoffs' || !config.configPath) return 0;
+  try {
+    const upgrade = planHandoffsUpgrade(config);
+    const after = await resolveConfig(config.configDir, config.configPath, { overrides: upgrade.overrides });
+    const carry = planSetupCarry(await preConfigView(config.repoRoot), after, true);
+    return carry.moves.length + carry.outstanding.length;
+  } catch { return 0; }
+}