runlist 0.99.1 → 0.100.0

package/src/install.mjs

@@ -9,12 +9,13 @@ 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 { installationReport, formatInstallationReport, persistentCliOnPath, PERSISTENT_CLI_WARNING } from './installation.mjs';
 import { codexStatus, installCodexPlugin, installedCodexStatus } from './codex-integration.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
+const CLAUDE_CODE_SETUP_URL = 'https://code.claude.com/docs/en/setup';
 const HOSTS = ['claude', 'codex', 'opencode'];
 const ALIASES = { 'claude-code': 'claude', claudecode: 'claude' };
 
@@ -85,20 +86,23 @@ function reportStatus(json, config) {
   }
 }
 
-function installCodex(argv, dryRun, json) {
+function installCodex(argv, dryRun, json, prerequisites) {
   if (argv.includes('--remove')) {
     process.stderr.write('Codex removal is managed by `codex plugin remove`; the personal marketplace source is left available.\n');
     process.exitCode = 1;
     return;
   }
-  const result = installCodexPlugin({ version: pkg.version, dryRun });
+  const result = { ...installCodexPlugin({ version: pkg.version, dryRun }), ...prerequisites };
   if (result.action === 'refused') {
     if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     else process.stderr.write(`refused: ${result.reason}\n`);
     process.exitCode = 1;
     return;
   }
-  if (!json) process.stdout.write(`${dryRun ? '[dry-run] ' : ''}${result.action} codex integration (${pkg.version}) at ${result.plugin}\n`);
+  if (!json) {
+    const action = dryRun ? ({ installed: 'Would install', updated: 'Would update', current: 'Already current' }[result.action] ?? result.action) : result.action;
+    process.stdout.write(`${dryRun ? '[dry-run] ' : ''}${action} codex integration (${pkg.version}) at ${result.plugin}\n`);
+  }
   if (dryRun) {
     if (json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     return;
@@ -125,11 +129,11 @@ function installCodex(argv, dryRun, json) {
   }
 }
 
-function installClaude(argv, dryRun, json) {
+function installClaude(argv, dryRun, json, opts = {}, prerequisites = {}) {
   const remove = argv.includes('--remove');
-  const steps = planClaudeInstall({ installed: readInstalledPlugin(), legacyInstalled: readInstalledPluginRecords({ id: LEGACY_PLUGIN_ID }), hasClaude: which('claude'), remove });
+  const steps = planClaudeInstall({ installed: readInstalledPlugin(), legacyInstalled: readInstalledPluginRecords({ id: LEGACY_PLUGIN_ID, ...(process.env.CLAUDE_CONFIG_DIR ? { configDir: process.env.CLAUDE_CONFIG_DIR } : {}) }), hasClaude: opts.claudeBin || which('claude'), remove });
   if (json) {
-    process.stdout.write(JSON.stringify({ host: 'claude', dryRun, steps }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ host: 'claude', dryRun, steps, ...prerequisites }, null, 2) + '\n');
     return;
   }
   let ran = false;
@@ -141,6 +145,17 @@ function installClaude(argv, dryRun, json) {
       continue;
     }
     if (step.kind === 'manual') {
+      if (step.lines.some(line => line.startsWith('/plugin install'))) {
+        // Newcomers mostly land here from Claude Desktop with no `claude` command, so lead with
+        // the documented terminal form. Desktop's plugin browser only lists marketplaces that are
+        // already registered, so it is where to find runlist afterwards, not where to add it.
+        process.stdout.write(`${step.reason ? `${step.reason}. ` : ''}${yellow('The claude CLI is not on PATH.')} Install the Claude Code CLI (${CLAUDE_CODE_SETUP_URL}), then run in a terminal:\n`);
+        for (const line of step.lines) process.stdout.write(`  ${bold(line.replace(/^\/plugin /, 'claude plugin '))}\n`);
+        process.stdout.write('Or run these from inside a Claude Code session:\n');
+        for (const line of step.lines) process.stdout.write(`  ${bold(line)}\n`);
+        process.stdout.write(dim('Claude Desktop\'s Code tab reads the same plugin settings as the terminal. Once the marketplace is added, runlist appears under Code tab → + → Add plugins.\n'));
+        continue;
+      }
       process.stdout.write(`${yellow(step.reason ?? 'claude CLI not on PATH')} — run these from a Claude Code session:\n`);
       for (const line of step.lines) process.stdout.write(`  ${bold(line)}\n`);
       continue;
@@ -148,8 +163,8 @@ function installClaude(argv, dryRun, json) {
     if (step.reason) process.stdout.write(`${step.reason}\n`);
     if (dryRun) { process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}${step.cwd ? ` (in ${step.cwd})` : ''}\n`)); continue; }
     process.stdout.write(dim(`$ ${step.cmd.join(' ')}${step.cwd ? ` (in ${step.cwd})` : ''}\n`));
-    const result = spawnSync(executableName(step.cmd[0]), step.cmd.slice(1), {
-      stdio: 'inherit', shell: process.platform === 'win32',
+    const result = spawnSync(opts.claudeBin || executableName(step.cmd[0]), step.cmd.slice(1), {
+      stdio: 'inherit', shell: process.platform === 'win32' && !opts.claudeBin,
       ...(step.cwd ? { cwd: step.cwd } : {}),
     });
     ran = true;
@@ -167,12 +182,12 @@ function installClaude(argv, dryRun, json) {
   if (ran && !remove && !process.exitCode) process.stdout.write(green('\n✓ restart Claude Code (or /reload-plugins) to apply.\n'));
 }
 
-function installOpencode(argv, dryRun, json) {
+function installOpencode(argv, dryRun, json, prerequisites) {
   const force = argv.includes('--force');
   const dir = flagValue(argv, '--path');
-  const result = argv.includes('--remove')
+  const result = { ...(argv.includes('--remove')
     ? removeOpencodePlugin({ dryRun, force, dir })
-    : installOpencodePlugin({ version: pkg.version, dryRun, force, dir });
+    : installOpencodePlugin({ version: pkg.version, dryRun, force, dir })), ...prerequisites };
 
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
@@ -197,13 +212,12 @@ function installOpencode(argv, dryRun, json) {
       process.stdout.write(dim('Restart OpenCode to apply. Sessions fall back to a process-scoped identity.\n'));
       return result;
     default:
-      process.stdout.write(`${prefix}${green('✓')} ${result.action} opencode integration (${pkg.version})\n${dim(result.path)}\n`);
+      process.stdout.write(`${prefix}${dryRun ? ({ installed: 'Would install', updated: 'Would update' }[result.action] ?? result.action) : `${green('✓')} ${result.action}`} opencode integration (${pkg.version})\n${dim(result.path)}\n`);
       if (dryRun) return result;
       process.stdout.write('\nRestart OpenCode to apply. New sessions then get:\n');
       process.stdout.write(`  ${dim('·')} a per-session ownership identity (one session can no longer release another's plan)\n`);
       process.stdout.write(`  ${dim('·')} the ${bold('runlist hud')} primer at session start, like Claude Code's SessionStart hook\n`);
-      process.stdout.write(dim('\nPlans already in-session were claimed under the old process-scoped identity;\n'));
-      process.stdout.write(dim('close them before restarting, or reclaim with --force afterwards.\n'));
+      process.stdout.write(dim('\nIf plans were claimed under a previous process-scoped identity, close them before restarting or explicitly reclaim them afterwards.\n'));
       return result;
   }
 }
@@ -221,7 +235,10 @@ export function runInstall(argv, _config, opts = {}) {
   }
 
   const dryRun = Boolean(opts.dryRun);
-  if (host === 'claude') { installClaude(argv, dryRun, json); return; }
-  if (host === 'codex') { installCodex(argv, dryRun, json); return; }
-  installOpencode(argv, dryRun, json);
+  const persistentCliMissing = !argv.includes('--remove') && !persistentCliOnPath().available;
+  const prerequisites = persistentCliMissing ? { persistentCliMissing: true } : {};
+  if (persistentCliMissing && !json) process.stderr.write(`Warning: ${PERSISTENT_CLI_WARNING}\n`);
+  if (host === 'claude') { installClaude(argv, dryRun, json, opts, prerequisites); return; }
+  if (host === 'codex') { installCodex(argv, dryRun, json, prerequisites); return; }
+  installOpencode(argv, dryRun, json, prerequisites);
 }

package/src/installation.mjs

@@ -1,5 +1,4 @@
-import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { accessSync, constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
@@ -7,38 +6,122 @@ import { fileURLToPath } from 'node:url';
 import { desktopLaunch } from './desktop.mjs';
 import { codexStatus } from './codex-integration.mjs';
 import { opencodeStatus } from './host-integration.mjs';
+import { sourceFingerprint } from './agent-hosts.mjs';
+import { LEGACY_PRODUCT_NAME, PRODUCT_NAME } from './naming.mjs';
+export { sourceFingerprint } from './agent-hosts.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'] : [''];
+function executable(name, env, { cwd = process.cwd(), runnable = false, accept = () => true } = {}) {
+  const suffixes = process.platform === 'win32' ? ['', ...(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';')] : [''];
   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 {}
+    const file = path.resolve(cwd, dir, name + suffix);
+    try {
+      if (!accept(file)) continue;
+      if (runnable) {
+        if (!statSync(file).isFile()) continue;
+        accessSync(file, constants.X_OK);
+        return file;
+      }
+      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);
+export const PERSISTENT_CLI_WARNING = 'Host hooks need a globally installed `runlist` on PATH and will not run without one. A temporary npx/one-shot copy does not count; run `npm install -g runlist`, then restart/reload the host.';
+
+export function isOneShotCliPath(file) {
+  const value = file.replace(/\\/g, '/');
+  return /(?:^|\/)_npx\/[^/]+\/node_modules(?:\/|$)/.test(value)
+    || /(?:^|\/)dlx\/(?:[a-z2-7]{26}|[a-f0-9]{32,64})\/[^/]+\/node_modules(?:\/|$)/i.test(value)
+    || /(?:^|\/)tmp\/dlx-[0-9]+\/node_modules(?:\/|$)/.test(value)
+    || /(?:^|\/)bunx-[0-9]+-[^/]+\/node_modules(?:\/|$)/.test(value)
+    || /(?:^|\/)\.bunx-[0-9]+\/[^/]+\/node_modules(?:\/|$)/.test(value);
+}
+
+export function persistentCliOnPath({ env = process.env, cwd = process.cwd() } = {}) {
+  const normalize = file => {
+    const value = path.resolve(cwd, file).replace(/\\/g, '/');
+    return process.platform === 'win32' ? value.toLowerCase() : value;
+  };
+  const injectedBins = new Set();
+  const excludeBin = bin => {
+    injectedBins.add(normalize(bin));
+    injectedBins.add(normalize(resolved(bin) || bin));
+  };
+  // Evidence: npm 11.20.0, offline npx --package <local tarball> <probe>,
+  // exported npm_command=exec, npm_lifecycle_event=npx and prepended
+  // <cache>/_npx/<hash>/node_modules/.bin, then project/ancestor bins.
+  // libnpmexec/lib/index.js and @npmcli/run-script/lib/set-path.js confirm
+  // those shapes. Also observed with pnpm 11.17.0 and a local probe tarball:
+  // $XDG_CACHE_HOME/pnpm/dlx/<hash>/<id>/node_modules/.bin on PATH.
+  // pnpm v11.17.0 pnpm11/exec/commands/src/dlx.ts builds that shape under
+  // any configured cacheDir, using a 32-hex key (v10.11.0 uses 64).
+  // Its config/reader/src/dirs.ts defaults to pnpm-cache on Windows.
+  // v9.15.9 uses the same layout with a 26-character base32 cache key,
+  // also observed with a local runlist tarball in an isolated HOME/cache.
+  // pnpm v8.15.9 exec/plugin-commands-script-runners/src/dlx.ts instead
+  // prepends <storeDir>/tmp/dlx-<pid>/node_modules/.bin. Source-verified:
+  // https://github.com/pnpm/pnpm/blob/v11.17.0/pnpm11/exec/commands/src/dlx.ts
+  // https://github.com/pnpm/pnpm/blob/v9.15.9/exec/plugin-commands-script-runners/src/dlx.ts
+  // https://github.com/pnpm/pnpm/blob/v8.15.9/exec/plugin-commands-script-runners/src/dlx.ts
+  // Source-inferred (not runtime-tested here): Bun bun-v1.3.3's
+  // src/cli/bunx_command.zig uses <tmp>/bunx-<uid>-<package>/node_modules/.bin;
+  // current src/runtime/cli/bunx_command.rs also uses
+  // <cache-or-tmp>/.bunx-<uid>/<package>/node_modules/.bin on Unix.
+  // Match whole path segments under these roots, including resolved links.
+  // These are one-shot launchers regardless of npm env markers.
+  // npm also injects project/ancestor bins,
+  // even for local devDependencies; exclude those while under npm.
+  // Do not infer persistence from the launcher.
+  if (env.npm_command || env.npm_execpath || env.npm_lifecycle_event) {
+    for (const start of [cwd, env.INIT_CWD, env.npm_config_local_prefix, env.npm_package_json && path.dirname(env.npm_package_json)].filter(Boolean)) {
+      let dir = path.resolve(cwd, start);
+      for (;;) {
+        const bin = path.join(dir, 'node_modules', '.bin');
+        excludeBin(bin);
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
       }
-    };
-    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'}; }
+    }
+  }
+  // Yarn 4.9.2 scriptUtils.ts: executePackageAccessibleBinary and
+  // makeScriptEnv create a separate <tmp>/xfs-<id> wrapper folder, prepend
+  // it to PATH and export BERRY_BIN_FOLDER. run/exec use it too. The wrappers
+  // are regular files; their realpaths do not reveal the dlx package folder.
+  // Observed with a local probe tarball and source-verified at
+  // a9edb7777f04ba16f51503ef6775325b353b67cc:
+  // https://github.com/yarnpkg/berry/blob/a9edb7777f04ba16f51503ef6775325b353b67cc/packages/yarnpkg-core/sources/scriptUtils.ts
+  // Nested Yarn calls retain outer wrapper folders on PATH while replacing
+  // BERRY_BIN_FOLDER (observed with a devDependency via `yarn run ybin`, whose
+  // script calls `yarn runlist`). xfs.ts creates xfs-<8 hex> under os.tmpdir():
+  // https://github.com/yarnpkg/berry/blob/a9edb7777f04ba16f51503ef6775325b353b67cc/packages/yarnpkg-fslib/sources/xfs.ts
+  // Exclude all xfs wrapper folders under the real temp root
+  // only while Yarn's marker is set; an ordinary shell may use such a folder.
+  if (env.BERRY_BIN_FOLDER) {
+    excludeBin(env.BERRY_BIN_FOLDER);
+    const tmp = normalize(resolved(os.tmpdir()) || os.tmpdir());
+    for (const bin of (env.PATH ?? '').split(path.delimiter).filter(Boolean)) {
+      const realBin = resolved(path.resolve(cwd, bin)) || path.resolve(cwd, bin);
+      if (normalize(path.dirname(realBin)) === tmp && /^xfs-[0-9a-f]{8}$/.test(path.basename(realBin))) excludeBin(bin);
+    }
+  }
+  const inCache = file => isOneShotCliPath(normalize(file));
+  const accept = file => {
+    const dir = path.dirname(file), realDir = resolved(dir) || dir;
+    const realFile = resolved(file) || file;
+    return !injectedBins.has(normalize(dir)) && !injectedBins.has(normalize(realDir))
+      && !injectedBins.has(normalize(path.dirname(realFile)))
+      && !inCache(dir) && !inCache(realDir) && !inCache(realFile);
+  };
+  for (const name of [PRODUCT_NAME, LEGACY_PRODUCT_NAME]) {
+    const file = executable(name, env, { cwd, runnable: true, accept });
+    if (file) return { available: true, path: file };
+  }
+  return { available: false, path: null };
 }
 
 function identity(root) {
@@ -49,8 +132,8 @@ function identity(root) {
 }
 
 // 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??{};
+export function readInstalledPluginRecords({home=os.homedir(),configDir=path.join(home,'.claude'),id}={}) {
+  const plugins=json(path.join(configDir,'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)};
@@ -79,7 +162,7 @@ export function installationReport(config={}, {root=packageRoot,home=os.homedir(
   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 pluginFiles=['skills','commands','hooks','hooks.json','bin','.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};

package/src/journal.mjs

@@ -27,7 +27,7 @@ const REDACTED = '[redacted]';
 const SENSITIVE_VALUE_FLAGS = new Set([
   '--body', '--message', '--note', '--reason', '--question', '--answers', '--choice', '--title',
   '--token', '--password', '--passphrase', '--secret', '--api-key', '--apikey',
-  '--auth', '--authorization', '--cookie', '--header',
+  '--auth', '--authorization', '--cookie', '--header', '--current-state', '--next-step',
 ]);
 
 function sanitizeCredentialShapes(value) {
@@ -120,7 +120,7 @@ export function sanitizeTelemetryText(value, secrets = []) {
     text = text.split(secret).join(REDACTED);
   }
   return sanitizeCredentialShapes(text)
-    .replace(/((?:--body|--message|--note|--reason|--token|--password|--passphrase|--secret|--api-key|--apikey|--auth|--authorization|--cookie|--header)(?:=|\s+))([^\s]+)/gi, `$1${REDACTED}`)
+    .replace(/((?:--body|--message|--note|--reason|--token|--password|--passphrase|--secret|--api-key|--apikey|--auth|--authorization|--cookie|--header|--current-state|--next-step)(?:=|\s+))([^\s]+)/gi, `$1${REDACTED}`)
     .replace(/(git\s+commit\b[^\n]*?(?:\s-m|\s--message)(?:=|\s+))((?:"[^"]*")|(?:'[^']*')|[^\s]+)/gi, `$1${REDACTED}`)
     .replace(/((?:sed|perl|g?awk)\b[^\n]*?\s(?:-e\s+)?)((?:"[^"]*")|(?:'[^']*'))/gi, `$1${REDACTED}`);
 }

package/src/lifecycle.mjs

@@ -33,6 +33,8 @@ import {
   updateOwnershipOperation,
   validatedClaimOperation,
 } from './pickup.mjs';
+import { assertInsideHandoffs } from './handoffs-scope.mjs';
+import { LEGACY_PROMPT_DIR, PROMPT_DIR, rootIsWorkingFolder } from './naming.mjs';
 
 export function renderLifecycleMutation(raw, updates, historyEntry, { createSection = false, bodyTransform = null } = {}) {
   raw = normalizeEol(raw);
@@ -165,20 +167,24 @@ export function updateFrontmatterAtomic(filePath, updates, config, options = {})
   });
 }
 
-function defaultTypeDir(docType, config) {
-  if (docType === 'plan') return 'plans';
-  if (docType === 'prompt') return 'prompts';
+// Before any config the root is the working folder, so prompts sit two levels
+// down in docs/prompts/; one an older build saved in a root prompts/ still files
+// beside itself until it is carried over (src/naming.mjs).
+function defaultTypeDirs(docType, config) {
+  if (docType === 'plan') return ['plans'];
+  if (docType === 'prompt') return rootIsWorkingFolder(config) ? [PROMPT_DIR, LEGACY_PROMPT_DIR] : ['prompts'];
   const templateDir = config.raw?.templates?.[docType]?.dir;
-  return typeof templateDir === 'string' && templateDir ? templateDir : null;
+  return typeof templateDir === 'string' && templateDir ? [templateDir] : [];
 }
 
 function findFilingRoot(filePath, fileRoot, docType, config) {
-  const dirName = defaultTypeDir(docType, config);
-  if (!dirName) return fileRoot;
-  if (path.basename(fileRoot) === dirName) return fileRoot;
-
   const relSegments = path.relative(fileRoot, filePath).split(path.sep);
-  if (relSegments[0] === dirName) return path.join(fileRoot, dirName);
+  for (const dirName of defaultTypeDirs(docType, config)) {
+    // A template's own dir is one folder name, as it always was.
+    const segments = dirName === PROMPT_DIR ? dirName.split('/') : [dirName];
+    if (fileRoot.split(path.sep).slice(-segments.length).join('/') === dirName) return fileRoot;
+    if (segments.every((segment, i) => relSegments[i] === segment)) return path.join(fileRoot, ...segments);
+  }
   return fileRoot;
 }
 
@@ -188,7 +194,7 @@ function findFilingRoot(filePath, fileRoot, docType, config) {
 // prompt churn doesn't bury plans/docs in the shared <root>/<archiveDir>.
 // Everything else archives under fileRoot. Used by both runStatus (set
 // archived) and runArchive so the two paths stay in lockstep.
-function archiveBaseFor(filePath, fileRoot, docType, config) {
+export function archiveBaseFor(filePath, fileRoot, docType, config) {
   const nest = config.lifecycle?.archiveNestedTypes?.has(docType) ?? false;
   return nest ? findFilingRoot(filePath, fileRoot, docType, config) : fileRoot;
 }
@@ -378,7 +384,9 @@ export async function runStatus(argv, config, opts = {}) {
   let newStatus = argv[1];
 
   if (!opts.suppressDeprecation) {
-    process.stderr.write(dim('`runlist status <file> <status>` is deprecated; prefer `runlist set <status> [<file>]` (note: <status> first; <file> optional when a plan is in-session). Removed in a future major.\n'));
+    process.stderr.write(dim(config.mode === 'handoffs'
+      ? '`runlist status <file> <status>` is deprecated; prefer `runlist set <status> <prompt>` (note: <status> first). Removed in a future major.\n'
+      : '`runlist status <file> <status>` is deprecated; prefer `runlist set <status> [<file>]` (note: <status> first; <file> optional when a plan is in-session). Removed in a future major.\n'));
   }
 
   if (!input) { die('Usage: runlist status <file> <new-status>'); }
@@ -979,6 +987,8 @@ export async function runSet(argv, config, opts = {}) {
 
   if (!newStatus) die('Usage: runlist set <status> [<path>]');
   let sessionId = null;
+  // Where planning is off there is no claimed plan to default to.
+  if (!input && config.mode === 'handoffs') die(`Name the prompt to change: runlist set ${newStatus} <prompt>`);
   if (!input) {
     sessionId = authoritativeSessionId();
     const owned = listOwnedPlans(config, sessionId);
@@ -1119,6 +1129,7 @@ export function runBulkArchive(argv, config, opts = {}) {
   const matched = [];
 
   for (const input of inputs) {
+    assertInsideHandoffs(input, config);
     const filePath = resolveDocPath(input, config);
     if (filePath) {
       matched.push(filePath);

package/src/managed-path.mjs

@@ -1,5 +1,7 @@
 import { existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { managesFile, outsideHandoffsLine } from './handoffs-scope.mjs';
+import { LEGACY_PROMPT_DIR, PROMPT_DIR } from './naming.mjs';
 
 // These checks are authorization preflights, not filesystem transactions. A
 // concurrent actor can still replace a checked ancestor before the later write
@@ -38,13 +40,20 @@ function lexicalRootsFor(config) {
   }));
 }
 
-function rootsFor(config) {
+function rootsFor(config, { allowMissingRoots = false } = {}) {
   return lexicalRootsFor(config).map(root => {
     const { configuredPath, lexicalPath } = root;
     let canonicalPath;
     try {
       canonicalPath = realpathSync(lexicalPath);
     } catch (err) {
+      if (allowMissingRoots && err.code === 'ENOENT') {
+        const ancestor = nearestExistingAncestor(lexicalPath, [root], 'Configured docs root');
+        let existing = lexicalPath;
+        while (!existsSync(existing)) existing = path.dirname(existing);
+        canonicalPath = path.resolve(ancestor, path.relative(existing, lexicalPath));
+        return { configuredPath, lexicalPath, canonicalPath };
+      }
       throw new Error(`Configured docs root cannot be resolved: ${lexicalPath} (${err.message})`);
     }
     return { configuredPath, lexicalPath, canonicalPath };
@@ -95,8 +104,8 @@ export function findLexicalDocsRoot(input, config) {
   return lexicalOwner(path.resolve(input), lexicalRootsFor(config))?.lexicalPath ?? null;
 }
 
-export function authorizeManagedSource(input, config, { kind = 'Managed mutation source' } = {}) {
-  const roots = rootsFor(config);
+export function authorizeManagedSource(input, config, { kind = 'Managed mutation source', allowMissingRoots = false } = {}) {
+  const roots = rootsFor(config, { allowMissingRoots });
   const lexicalPath = path.resolve(input);
   markdown(lexicalPath, kind, roots);
 
@@ -116,6 +125,9 @@ export function authorizeManagedSource(input, config, { kind = 'Managed mutation
   if (!statSync(canonicalPath).isFile()) {
     throw new Error(`${kind} is not a file: ${lexicalPath}\nConfigured docs roots: ${rootsMessage(roots)}`);
   }
+  if (!managesFile(canonicalPath, config)) {
+    throw new Error(`${kind}: ${outsideHandoffsLine(path.relative(config.repoRoot, lexicalPath).split(path.sep).join('/'))}`);
+  }
 
   const lexical = lexicalOwner(lexicalPath, roots);
   if (lexical && !aliasContainment(lexical.canonicalPath, canonicalPath).contained) {
@@ -137,10 +149,62 @@ export function authorizeManagedSource(input, config, { kind = 'Managed mutation
   return { path: managedPath, canonicalPath, root };
 }
 
-export function authorizeManagedDestination(input, config, { root: requiredRoot = null, kind = 'Managed mutation destination' } = {}) {
+// One prompt location (src/naming.mjs): before any config, and where
+// planning is off, nothing is created in the root prompts/ an older runlist
+// saved prompts in. Its prompts are carried out to docs/prompts/ instead.
+// Transaction recovery restoring a carry's source is not a new file.
+// Whether `file` is in the root prompts/, by its path or by where its folders
+// physically lead: a docs/ that is a symlink to prompts/ puts docs/prompts/
+// inside it. Configured planning projects keep the prompt folder they chose,
+// so callers ask only before any config or where planning is off.
+export function inLegacyPromptFolder(file, repoRoot) {
+  const top = path.resolve(repoRoot);
+  const legacy = path.join(top, LEGACY_PROMPT_DIR);
+  const lexical = path.resolve(file);
+  if (contains(legacy, lexical)) return true;
+  let existing = lexical;
+  const rest = [];
+  while (!existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return false;
+    rest.unshift(path.basename(existing));
+    existing = parent;
+  }
+  try {
+    const physical = path.join(realpathSync(existing), ...rest);
+    const physicalLegacy = existsSync(legacy) ? realpathSync(legacy) : path.join(realpathSync(top), LEGACY_PROMPT_DIR);
+    return contains(physicalLegacy, physical);
+  } catch { return false; }
+}
+
+export function legacyPromptFolderMessage(file, repoRoot, kind) {
+  const relative = path.relative(repoRoot, path.resolve(file)).split(path.sep).join('/') || '.';
+  return `${kind}: ${relative} ${legacyPromptFolderPlace(file, repoRoot)}, where runlist no longer writes; prompts live in ${PROMPT_DIR}/.`;
+}
+
+export function legacyPromptFolderPlace(file, repoRoot) {
+  return contains(path.join(path.resolve(repoRoot), LEGACY_PROMPT_DIR), path.resolve(file))
+    ? `is in ${LEGACY_PROMPT_DIR}/ at the project root`
+    : `leads into ${LEGACY_PROMPT_DIR}/ at the project root through a symlinked folder`;
+}
+
+function assertNotLegacyPromptFolder(lexicalPath, config, kind) {
+  if (config.configFound && config.mode !== 'handoffs') return;
+  if (!inLegacyPromptFolder(lexicalPath, config.repoRoot)) return;
+  throw new Error(legacyPromptFolderMessage(lexicalPath, config.repoRoot, kind));
+}
+
+// Files runlist writes outside the document roots (exports): before any
+// config and where planning is off, never into the root prompts/.
+export function assertOutsideLegacyPromptFolder(file, config, kind) {
+  assertNotLegacyPromptFolder(path.resolve(file), config, kind);
+}
+
+export function authorizeManagedDestination(input, config, { root: requiredRoot = null, kind = 'Managed mutation destination', recovery = false } = {}) {
   const roots = rootsFor(config);
   const lexicalPath = path.resolve(input);
   markdown(lexicalPath, kind, roots);
+  if (!recovery) assertNotLegacyPromptFolder(lexicalPath, config, kind);
 
   const root = requiredRoot
     ? roots.find(candidate => candidate.lexicalPath === requiredRoot.lexicalPath && candidate.canonicalPath === requiredRoot.canonicalPath)

package/src/migrate.mjs

@@ -6,6 +6,7 @@ import { collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
 import { bold, green, dim } from './color.mjs';
 import { authorizeManagedSweep } from './managed-path.mjs';
+import { assertInsideHandoffs, isHandoffsMode, planningRefusal } from './handoffs-scope.mjs';
 
 export function runMigrate(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -25,6 +26,11 @@ export function runMigrate(argv, config, opts = {}) {
   if (!field || !oldValue || !newValue) {
     die('Usage: runlist migrate <field> <old-value> <new-value> [files...]');
   }
+  // A handoffs-only project manages prompts and nothing else: a prompt given
+  // another type would drop out of every listing (src/handoffs-scope.mjs).
+  if (isHandoffsMode(config) && field === 'type' && newValue !== 'prompt') {
+    die(planningRefusal(`\`runlist migrate type ${oldValue} ${newValue}\``));
+  }
 
   const allFiles = collectDocFiles(config);
 
@@ -34,6 +40,7 @@ export function runMigrate(argv, config, opts = {}) {
     const matched = [];
     const unresolved = [];
     for (const input of fileArgs) {
+      assertInsideHandoffs(input, config);
       const filePath = resolveDocPath(input, config);
       if (filePath) {
         matched.push(filePath);

package/src/naming.mjs

@@ -22,6 +22,32 @@ export const CONFIG_FILENAMES = [
   'dotmd.config.js',
 ];
 
+// Where runlist writes prompts before any config, in a handoffs-only project
+// and in a project `runlist init` starts. Builds before that saved them in a
+// root prompts/ when there was no config; that folder is now only a source to
+// carry them from (src/setup-carry.mjs), never a place anything new is
+// written. A configured planning project keeps the prompt folder it chose.
+export const PROMPT_DIR = 'docs/prompts';
+export const LEGACY_PROMPT_DIR = 'prompts';
+
+// Prompt statuses older builds wrote and later dropped: a prompt saved with
+// one is still one runlist saved (carried like any other), and `check` names
+// the verb that settles it rather than calling the status unknown.
+export const RETIRED_PROMPT_STATUSES = new Set(['held', 'shelved', 'claimed']);
+
+// The prompt routing a config written by `runlist setup` spells out, so its
+// prompts go to <docs root>/prompts/ whatever the root is called. Without it
+// the built-in routing reads a root whose name ends in "prompts" (notes/prompts,
+// review-prompts) as the prompt folder itself, as configured projects rely on.
+export const SETUP_PROMPT_ROUTING = Object.freeze({ dir: 'prompts', targetRoot: null });
+
+// Before any config the docs root is the working folder itself, so prompts sit
+// two levels down in it. A layout projected for a config about to be written
+// (init, setup) has a docs root of its own and keeps the usual prompts/ in it.
+export function rootIsWorkingFolder(config) {
+  return !config.configFound && Boolean(config.configDir) && path.resolve(config.docsRoot) === path.resolve(config.configDir);
+}
+
 export const ENV_PREFIX = 'RUNLIST_';
 export const LEGACY_ENV_PREFIX = 'DOTMD_';