runlist 0.99.1 → 0.100.0

package/src/config-setting.mjs

@@ -0,0 +1,163 @@
+// A conservative lexical editor for one named, immutable string export. This
+// does not evaluate JavaScript or print it back out: only the literal's byte
+// span changes. Unlike the status editor, groups may contain regex literals.
+// Ambiguous lexical contexts are refused rather than guessed.
+const VALUES = ['untracked', 'tracked', 'local'];
+
+function manual(reason) {
+  throw new Error(`${reason} Edit promptTracking manually in your config using one direct declaration, for example: export const promptTracking = 'untracked'; Allowed values: 'untracked', 'tracked', 'local'. Then rerun runlist config show. No config changes were made.`);
+}
+
+const REGEX_PREFIX = new Set([
+  'return', 'throw', 'yield', 'await', 'case', 'delete', 'void', 'typeof',
+  'instanceof', 'in', 'of', 'new', 'else', 'do', 'default',
+]);
+
+function stringEnd(text, start) {
+  const quote = text[start];
+  for (let i = start + 1; i < text.length; i++) {
+    if (text[i] === '\\') { i++; continue; }
+    if (text[i] === quote) return i + 1;
+    if (quote === '`' && text[i] === '$' && text[i + 1] === '{') {
+      i = groupEnd(text, i + 1) - 1;
+    }
+  }
+  manual('Unterminated string.');
+}
+
+function regexEnd(text, start) {
+  let characterClass = false;
+  for (let i = start + 1; i < text.length; i++) {
+    if (text[i] === '\\') { i++; continue; }
+    if (text[i] === '[') characterClass = true;
+    if (text[i] === ']') characterClass = false;
+    if (text[i] === '/' && !characterClass) {
+      i++;
+      while (/[A-Za-z]/.test(text[i] ?? '')) i++;
+      return i;
+    }
+    if (text[i] === '\n' || text[i] === '\r') break;
+  }
+  manual('Cannot safely locate a regular expression.');
+}
+
+function triviaEnd(text, start) {
+  let i = start;
+  while (i < text.length) {
+    if (/\s/.test(text[i])) { i++; continue; }
+    if (text.startsWith('//', i) || (i === 0 && text.startsWith('#!', i))) {
+      const end = text.indexOf('\n', i);
+      i = end < 0 ? text.length : end + 1;
+      continue;
+    }
+    if (text.startsWith('/*', i)) {
+      const end = text.indexOf('*/', i + 2);
+      if (end < 0) manual('Unterminated comment.');
+      i = end + 2;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+
+function tokenAt(text, start, previous) {
+  const c = text[start];
+  let end;
+  let kind = 'punctuation';
+  if (c === "'" || c === '"' || c === '`') {
+    end = stringEnd(text, start);
+    kind = c === '`' ? 'template' : 'string';
+  } else if ('{[('.includes(c)) {
+    end = groupEnd(text, start);
+    kind = 'group';
+  } else if (c === '/') {
+    // A slash after a closing group needs statement/expression grammar to
+    // disambiguate (if (...) /re/ vs fn(...) / divisor). Refuse that rare case.
+    if (previous?.kind === 'group') manual('A slash after a bracket group is ambiguous to the setting editor.');
+    const expressionEnd = previous && (
+      ['string', 'template', 'regex', 'number'].includes(previous.kind)
+      || (previous.kind === 'identifier' && !REGEX_PREFIX.has(previous.raw))
+      || ['++', '--', '.', '?.'].includes(previous.raw)
+    );
+    end = expressionEnd ? start + (text[start + 1] === '=' ? 2 : 1) : regexEnd(text, start);
+    if (!expressionEnd) kind = 'regex';
+  } else if (/[A-Za-z_$]/.test(c)) {
+    end = start + 1;
+    while (/[A-Za-z0-9_$]/.test(text[end] ?? '')) end++;
+    kind = 'identifier';
+  } else if (/[0-9]/.test(c)) {
+    end = start + 1;
+    while (/[A-Za-z0-9_.]/.test(text[end] ?? '')) end++;
+    kind = 'number';
+  } else {
+    if (c === '\\' || c.charCodeAt(0) > 127) manual('Escaped or Unicode identifiers need a manual setting edit.');
+    end = start + 1;
+    if (['++', '--', '=>', '?.'].includes(text.slice(start, start + 2))) end++;
+  }
+  return { start, end, raw: text.slice(start, end), kind };
+}
+
+function groupEnd(text, start) {
+  const close = { '{': '}', '[': ']', '(': ')' }[text[start]];
+  let i = start + 1;
+  let previous;
+  while ((i = triviaEnd(text, i)) < text.length) {
+    if (text[i] === close) return i + 1;
+    if ('}])'.includes(text[i])) manual('Unbalanced brackets.');
+    previous = tokenAt(text, i, previous);
+    i = previous.end;
+  }
+  manual('Unterminated bracket group.');
+}
+
+export function renderPromptTrackingSetting(content, value) {
+  if (!VALUES.includes(value)) throw new Error("promptTracking must be 'untracked', 'tracked', or 'local'.");
+  const tokens = [];
+  let i = 0;
+  while ((i = triviaEnd(content, i)) < content.length) {
+    const token = tokenAt(content, i, tokens.at(-1));
+    tokens.push(token);
+    i = token.end;
+  }
+  let literal;
+  for (let n = 0; n < tokens.length; n++) {
+    const token = tokens[n];
+    if (token.raw === 'export') {
+      const next = tokens[n + 1];
+      if (next?.raw === '*' || next?.raw === 'default' || next?.raw.startsWith('{')) {
+        manual('Export lists, reexports, and default exports are outside the supported setting shape.');
+      }
+    }
+    if (token.raw !== 'promptTracking') continue;
+    // Requiring every top-level occurrence to be this binding also refuses
+    // mutable assignments, aliases, and multi-declaration bindings.
+    if (tokens[n - 2]?.raw !== 'export' || tokens[n - 1]?.raw !== 'const' || tokens[n + 1]?.raw !== '=') {
+      manual('promptTracking is not a simple named const export.');
+    }
+    if (literal) manual('Multiple promptTracking declarations are ambiguous.');
+    const candidate = tokens[n + 2];
+    if (candidate?.kind !== 'string' || !VALUES.includes(candidate.raw.slice(1, -1))) {
+      manual('promptTracking uses a computed or unsupported value.');
+    }
+    const after = tokens[n + 3];
+    // Semicolonless declarations are safe only at EOF or before another
+    // explicit module declaration, separated by a newline.
+    if (after && after.raw !== ';' && !(
+      ['export', 'import'].includes(after.raw) && /[\r\n]/.test(content.slice(candidate.end, after.start))
+    )) manual('promptTracking has a computed initializer or ambiguous declaration boundary.');
+    literal = candidate;
+  }
+  if (literal) {
+    const quote = literal.raw[0];
+    return {
+      content: content.slice(0, literal.start) + quote + value + quote + content.slice(literal.end),
+      previousValue: literal.raw.slice(1, -1),
+    };
+  }
+  const newline = content.includes('\r\n') ? '\r\n' : '\n';
+  return {
+    content: content + (content && !content.endsWith('\n') ? newline : '') + `export const promptTracking = '${value}';${newline}`,
+    previousValue: 'local',
+  };
+}

package/src/config.mjs

@@ -19,7 +19,14 @@ const REPLACE_KEYS = new Set([
 ]);
 
 const DEFAULTS = {
+  // 'plans' (the full plan/doc/prompt system) or 'handoffs': session handoffs
+  // only, written by the first `runlist baton` in a repository with no config.
+  // Handoffs mode pairs with a `root` that is the prompt folder itself, so the
+  // scan never reaches the project's own docs; this flag only changes wording
+  // and refuses plan verbs. `runlist setup` flips it to 'plans'.
+  mode: 'plans',
   root: '.',
+  promptTracking: 'untracked',
   archiveDir: 'archived',
   excludeDirs: [],
   externalBodyLinkRoots: [],
@@ -474,24 +481,46 @@ export function locateConfig(cwd, explicitConfigPath) {
   return {configPath,configDir,repoRoot};
 }
 
-export async function resolveConfig(cwd, explicitConfigPath) {
-  const {configPath,configDir,repoRoot} = locateConfig(cwd, explicitConfigPath);
+// `options.exports` stands in for a config file that does not exist yet (a
+// dry-run of the handoffs config baton would create); `options.overrides`
+// replaces exports of the file that does (setup previewing a planning upgrade).
+// Both are internal: neither writes anything.
+export async function resolveConfig(cwd, explicitConfigPath, options = {}) {
+  const located = locateConfig(cwd, explicitConfigPath);
+  const virtual = Boolean(options.exports && explicitConfigPath);
+  const {configPath} = located;
+  let {configDir, repoRoot} = located;
+  if (virtual) {
+    configDir = path.dirname(configPath);
+    repoRoot = locateConfig(configDir).repoRoot;
+  }
 
   let userConfig = {};
   let hooks = {};
-
-  if (configPath && existsSync(configPath)) {
-    const configUrl = pathToFileURL(configPath).href;
-    let mod;
-    try {
-      mod = await import(configUrl);
-    } catch (err) {
-      die('Failed to load config: ' + configPath + '\n' + err.message + '\nCheck for syntax errors in your config file.');
+  const fileExists = Boolean(configPath && existsSync(configPath));
+  let promptTrackingSource = fileExists || virtual ? 'legacy-default' : 'default';
+
+  if (fileExists || virtual) {
+    let mod = options.exports;
+    if (!virtual) {
+      const configUrl = pathToFileURL(configPath).href;
+      try {
+        mod = await import(configUrl);
+      } catch (err) {
+        die('Failed to load config: ' + configPath + '\n' + err.message + '\nCheck for syntax errors in your config file.');
+      }
     }
+    if (options.overrides) mod = { ...mod, ...options.overrides };
 
     for (const [key, value] of Object.entries(mod)) {
       if (key === 'default') continue;
-      if (typeof value === 'function') {
+      if (key === 'promptTracking') {
+        if (!['untracked', 'tracked', 'local'].includes(value)) {
+          throw new Error(`Config: promptTracking must be 'untracked', 'tracked', or 'local' (${configPath}).`);
+        }
+        userConfig[key] = value;
+        promptTrackingSource = 'config';
+      } else if (typeof value === 'function') {
         hooks[key] = value;
       } else {
         userConfig[key] = value;
@@ -500,12 +529,14 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   }
 
   // Backwards compat: `readme` config key maps to `index`
-  if (userConfig.readme && !userConfig.index) {
+  const legacyIndex = Boolean(userConfig.readme && !userConfig.index);
+  if (legacyIndex) {
     userConfig.index = userConfig.readme;
     delete userConfig.readme;
   }
 
   const config = deepMerge(DEFAULTS, userConfig);
+  if (promptTrackingSource === 'legacy-default') config.promptTracking = 'local';
   // Replacement links remain repairable even with custom reference-field lists
   // or after the repository turns off goal display.
   config.referenceFields.unidirectional = [...new Set([
@@ -633,6 +664,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     }
   }
 
+  let mode = 'plans';
+  if (config.mode === 'handoffs' || config.mode === 'plans') mode = config.mode;
+  else earlyWarnings.push(`Config: mode must be 'plans' or 'handoffs'; ignoring \`${config.mode}\`.`);
+
   const configWarnings = [...earlyWarnings, ...validateConfig(userConfig, config, validStatuses, indexPath)];
 
   return {
@@ -644,6 +679,16 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     configDir,
     configPath: configPath ?? null,
     configFound: Boolean(configPath),
+    mode,
+    planning: mode !== 'handoffs',
+    promptTracking: config.promptTracking,
+    promptTrackingSource,
+    settingSources: {
+      mode: Object.hasOwn(userConfig, 'mode') ? 'config' : 'default',
+      root: Object.hasOwn(userConfig, 'root') ? 'config' : 'default',
+      'index.path': Object.hasOwn(userConfig.index ?? {}, 'path') ? (legacyIndex ? 'legacy-readme' : 'config') : 'default',
+      archiveDir: Object.hasOwn(userConfig, 'archiveDir') ? 'config' : 'default',
+    },
     archiveDir: config.archiveDir,
     excludeDirs: new Set(config.excludeDirs),
     externalBodyLinkRoots: Array.isArray(config.externalBodyLinkRoots) ? config.externalBodyLinkRoots : [],

package/src/doctor-hosts.mjs

@@ -0,0 +1,192 @@
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import * as inventory from './agent-hosts.mjs';
+import { shellQuote } from './util.mjs';
+import { sanitizeTelemetryText } from './journal.mjs';
+import { installationReport } from './installation.mjs';
+
+const HOSTS = ['claude', 'codex', 'opencode'];
+const valueFlags = new Set(['--repair', '--claude-config', '--claude-bin']);
+const flags = new Set(['--hosts', '--json', '--apply', '--yes']);
+
+export function hostDoctorOptions(argv, { dryRun = false } = {}) {
+  const options = { repairs: [], claudeConfigDirs: [], claudeBin: undefined, json: false, apply: false, dryRun };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (flags.has(arg)) {
+      if (arg === '--json') options.json = true;
+      if (arg === '--apply' || arg === '--yes') options.apply = true;
+      continue;
+    }
+    if (!valueFlags.has(arg) || !argv[i + 1] || argv[i + 1].startsWith('--')) {
+      throw new Error(`Unsupported host diagnostic argument: ${arg}. Use doctor --hosts [--repair <host>] [--apply] [--json].`);
+    }
+    const value = argv[++i];
+    if (arg === '--repair') {
+      if (!HOSTS.includes(value)) throw new Error('--repair must name claude, codex, or opencode. Repeat it to select more hosts.');
+      options.repairs.push(value);
+    } else if (arg === '--claude-config') {
+      if (!path.isAbsolute(value)) throw new Error('--claude-config requires an absolute profile directory.');
+      options.claudeConfigDirs.push(path.resolve(value));
+    } else {
+      if (options.claudeBin) throw new Error('--claude-bin may be supplied once.');
+      options.claudeBin = path.resolve(value);
+    }
+  }
+  options.repairs = [...new Set(options.repairs)];
+  options.claudeConfigDirs = [...new Set(options.claudeConfigDirs)];
+  if (options.apply && !options.repairs.length) throw new Error('doctor --hosts --apply requires explicitly selected --repair <host> targets.');
+  return options;
+}
+
+function commandFor(action, options) {
+  const argv = ['runlist', 'doctor', '--hosts', '--repair', action.host, '--apply'];
+  if (action.configDir) argv.push('--claude-config', action.configDir);
+  if (options.claudeBin) argv.push('--claude-bin', options.claudeBin);
+  return argv;
+}
+
+export function planHostRepairs(report, options) {
+  const actions = [];
+  for (const host of options.repairs) {
+    const info = report.hosts[host], executable = report.executables[host]?.selected;
+    if (host === 'claude') {
+      const profiles = info.profiles.filter(profile => !options.claudeConfigDirs.length
+        || options.claudeConfigDirs.some(dir => (profile.configDirs ?? [profile.configDir]).includes(dir)));
+      for (const profile of profiles) {
+        const configDir = options.claudeConfigDirs.find(dir => (profile.configDirs ?? [profile.configDir]).includes(dir)) ?? profile.configDir;
+        const blocked = !executable ? 'Claude executable unavailable; install/select the intended host binary first.'
+          : !profile.repair.targetable ? profile.repair.reason
+            : !profile.installed && profiles.length > 1 && !options.claudeConfigDirs.length
+              ? 'Select --claude-config explicitly to install into an additional missing profile.' : null;
+        const action = { host, id: `claude:${profile.storeKey}`, configDir, storeKey: profile.storeKey,
+          profileDirs: profile.configDirs ?? [profile.configDir], executable: executable?.path, kind: profile.installed ? 'update' : 'install',
+          status: blocked ? 'blocked' : 'planned', reason: blocked,
+          description: `${profile.installed ? 'Refresh installed' : 'Install missing'} Claude integration in ${configDir}; shared store updated once` };
+        if (profile.state === 'current') {
+          action.kind = 'none'; action.status = 'current';
+          action.reason = null;
+          action.description = `Claude files already match the registered catalog in ${configDir}; saved enablement and live loading are separate`;
+          if (!executable) action.remedy = 'The Claude executable is unavailable; install/select the host separately to check activation.';
+        }
+        if (blocked && action.kind !== 'none') {
+          const native = [...new Map((report.executables.claude.candidates ?? []).filter(candidate => candidate.kind.startsWith('native'))
+            .map(candidate => [candidate.resolvedPath ?? candidate.path, candidate])).values()];
+          const safeSource = profile.state !== 'foreign' && profile.registryState !== 'unreadable' && profile.knownMarketplacesState !== 'unreadable'
+            && !profile.settings?.some(settings => settings.configDir === configDir && settings.state === 'unreadable');
+          action.nextCommands = safeSource ? native.map(candidate => ['runlist', 'doctor', '--hosts', '--repair', 'claude', '--claude-config', configDir, '--claude-bin', candidate.path]) : [];
+          action.remedy = action.nextCommands.length ? 'Preview with the intended native binary and profile below; these commands do not apply changes.'
+            : 'Inspect the registry/marketplace/settings and intended profile with the host plugin manager; restore readable, managed records before retrying. No automatic replacement is offered.';
+        } else if (action.kind !== 'none') action.command = commandFor(action, options);
+        actions.push(action);
+      }
+      if (!profiles.length) actions.push({ host, id: 'claude:unresolved', status: 'blocked', reason: 'No selected Claude profile could be resolved.' });
+    } else {
+      const blocked = !executable ? `${host} executable unavailable; install the host separately first.`
+        : !info.repair.targetable ? info.repair.reason : null;
+      const action = { host, id: host, kind: info.state === 'missing' ? 'install' : 'update',
+        status: blocked ? 'blocked' : 'planned', reason: blocked,
+        description: `${info.state === 'missing' ? 'Install missing' : 'Refresh managed'} ${host} integration; preserve unmarked files` };
+      if (host === 'opencode' && info.state === 'current') {
+        action.kind = 'none'; action.status = 'current'; action.reason = null;
+        action.description = 'OpenCode generated file already matches this CLI candidate; no file repair is needed. Live loading remains unknown.';
+      }
+      if (host === 'codex' && info.state === 'current') action.description = 'Verify the installed Codex copy; the marketplace source already matches this CLI candidate';
+      if (action.status === 'blocked') action.remedy = 'Keep the unmarked/unreadable content. Inspect it and use the host plugin manager or move your own file aside before explicitly installing a managed integration; nothing is overwritten automatically.';
+      else if (action.kind !== 'none') action.command = commandFor(action, options);
+      actions.push(action);
+    }
+  }
+  return actions;
+}
+
+function runRepair(action, { options, config, env }) {
+  // Reuse the existing verbs in a fresh process without importing project JS.
+  // User values travel on stdin as data, never interpolated into shell code.
+  const script = `import { readFileSync } from 'node:fs';
+    import { runInstall } from ${JSON.stringify(new URL('./install.mjs', import.meta.url).href)};
+    import { runUpdate } from ${JSON.stringify(new URL('./update.mjs', import.meta.url).href)};
+    const request = JSON.parse(readFileSync(0, 'utf8'));
+    if (request.kind === 'install') await runInstall([request.host], request.config, { claudeBin: request.claudeBin });
+    else await runUpdate(request.argv, request.config);`;
+  const argv = ['--host', action.host];
+  if (action.configDir) argv.push('--claude-config', action.configDir);
+  if (options.claudeBin) argv.push('--claude-bin', options.claudeBin);
+  return spawnSync(process.execPath, ['--input-type=module', '-e', script], {
+    cwd: config.repoRoot, input: JSON.stringify({ kind: action.kind, host: action.host, argv,
+      config: { repoRoot: config.repoRoot }, claudeBin: action.host === 'claude' ? options.claudeBin ?? action.executable : undefined }),
+    encoding: 'utf8', timeout: 180_000, maxBuffer: 4 * 1024 * 1024,
+    env: { ...env, ...(action.configDir ? { CLAUDE_CONFIG_DIR: action.configDir } : {}), RUNLIST_JOURNAL: '0', DOTMD_JOURNAL: '0' },
+  });
+}
+
+function targetState(report, action) {
+  if (action.host !== 'claude') return report.hosts[action.host].state;
+  return report.hosts.claude.profiles.find(profile => (profile.configDirs ?? [profile.configDir]).includes(action.configDir))?.state ?? 'unknown';
+}
+
+function render(report, out, json) {
+  if (json) { out.write(`${JSON.stringify(report, null, 2)}\n`); return; }
+  const { cli, node, updateEffect } = report.runtime;
+  out.write(`CLI launcher: ${cli.launcher?.path ?? 'unknown'} → ${cli.launcher?.resolvedPath ?? 'unknown'}\n`);
+  out.write(`Node: ${node.version} · ${node.path} · prefix ${node.prefix}\nnpm on PATH: ${node.npm ?? 'not found'}\n`);
+  out.write(`Update scope: ${updateEffect}\n\n`);
+  const format = inventory.formatAgentHostReport;
+  if (format) out.write(format(report));
+  else {
+    out.write(`runlist host health — CLI ${report.candidate.version ?? 'unknown'} (${report.candidate.kind})\n`);
+    for (const host of HOSTS) out.write(`${host}: ${report.hosts[host].state}; live loading unknown\n`);
+  }
+  if (!report.repairs.selectedHosts.length) {
+    out.write('\nRepairs are explicit: runlist doctor --hosts --repair <host> previews; add --apply to execute.\n');
+    return;
+  }
+  out.write(`\nRepairs: ${report.repairs.mode}\n`);
+  for (const action of report.repairs.actions) {
+    out.write(`  ${action.status}: ${action.description ?? action.id}${action.reason ? ` — ${action.reason}` : ''}\n`);
+    if (action.command) out.write(`    ${action.command.map(shellQuote).join(' ')}\n`);
+    if (action.remedy) out.write(`    ${action.remedy}\n`);
+    for (const command of action.nextCommands ?? []) out.write(`    ${command.map(shellQuote).join(' ')}\n`);
+  }
+  for (const item of report.repairs.outstanding) out.write(`  Outstanding: ${item}\n`);
+  if (report.repairs.failed.length) out.write(`Failed repairs: ${report.repairs.failed.length}; completed: ${report.repairs.completed.length}. Other selected hosts were still attempted.\n`);
+}
+
+export async function runDoctorHosts(argv, config = { repoRoot: process.cwd() }, opts = {}) {
+  const options = hostDoctorOptions(argv, opts), env = opts.env ?? process.env;
+  const reportOptions = { home: opts.home ?? os.homedir(), env, ...(opts.root ? { root: opts.root } : {}),
+    claudeConfigDirs: options.claudeConfigDirs, claudeBin: options.claudeBin };
+  const read = opts.inventory ?? inventory.agentHostReport;
+  const before = read(config, reportOptions);
+  const installation = installationReport(config, reportOptions);
+  const runtime = { cli: installation.cli, node: installation.node, project: installation.project, updateEffect: installation.updateEffect };
+  const actions = planHostRepairs(before, options);
+  const repairs = { mode: options.apply && !options.dryRun ? 'apply' : options.repairs.length ? 'preview' : 'none',
+    selectedHosts: options.repairs, actions, completed: [], failed: [], outstanding: [] };
+  let report = { ...before, runtime, repairs };
+  let attempted = false;
+  if (repairs.mode === 'apply') {
+    for (const action of actions) {
+      if (action.status === 'blocked') { repairs.failed.push({ id: action.id, reason: action.reason }); continue; }
+      if (action.kind === 'none') { repairs.completed.push({ id: action.id, host: action.host, sourceState: 'current', action: 'no change needed', installedOrLoaded: 'not attested by filesystem inventory' }); continue; }
+      try {
+        attempted = true;
+        const result = await (opts.run ?? runRepair)(action, { options, config, env });
+        action.output = sanitizeTelemetryText(`${result.stdout ?? ''}${result.stderr ?? ''}${result.error?.message ?? ''}`);
+        if (result.status !== 0) throw new Error(`Repair command exited ${result.status ?? 'unknown'}${result.error ? `: ${result.error.message}` : ''}`);
+        const after = read(config, reportOptions), state = targetState(after, action);
+        action.sourceState = state;
+        if (['missing', 'stale', 'foreign'].includes(state)) throw new Error(`Repair command exited successfully but source state remains ${state}.`);
+        action.status = 'completed';
+        repairs.completed.push({ id: action.id, host: action.host, sourceState: state, installedOrLoaded: 'not attested by filesystem inventory' });
+        if (state === 'unknown') repairs.outstanding.push(`${action.host}: command completed but source parity remains unknown; inspect the host's installed copy.`);
+      } catch (error) { action.status = 'failed'; action.reason = error.message; repairs.failed.push({ id: action.id, reason: error.message }); }
+    }
+    report = { ...read(config, reportOptions), readOnly: !attempted, runtime, repairs };
+    if (repairs.failed.length) process.exitCode = 1;
+    for (const host of options.repairs) repairs.outstanding.push(...(report.hosts[host].requirements ?? [`Restart/reload ${host}; live activation remains unknown.`]));
+  }
+  render(report, opts.out ?? process.stdout, options.json);
+  return report;
+}

package/src/doctor.mjs

@@ -85,7 +85,8 @@ function runDoctorTransactions(argv, config, opts = {}) {
     const mark = clearedIds.has(item.id) ? green('✓') : blocking ? yellow('!') : dim('·');
     const note = clearedIds.has(item.id)
       ? 'cleared'
-      : item.resolvable ? 'resolvable' : (item.reason ?? item.status);
+      : item.ownerLiveness === 'live' || item.lockHeld ? 'in progress; rerun later once it finishes'
+        : item.resolvable ? 'resolvable' : (item.reason ?? item.status);
     process.stdout.write(`  ${mark} ${item.id} [${item.status}] ${item.operation} — owner ${item.ownerLiveness}, ${note}\n`);
     for (const participant of item.participants) {
       process.stdout.write(dim(`      ${participant.state.padEnd(9)} ${toRepoPath(participant.path, config.repoRoot)}\n`));
@@ -97,15 +98,17 @@ function runDoctorTransactions(argv, config, opts = {}) {
 
   const resolvable = report.filter(item => item.resolvable && !clearedIds.has(item.id));
   if (cleared.length) {
-    process.stdout.write(green(`\n✓ Cleared ${cleared.length} transaction${cleared.length === 1 ? '' : 's'} whose files already agreed on one generation.\n`));
+    process.stdout.write(green(`\n✓ Cleared ${cleared.length} transaction${cleared.length === 1 ? '' : 's'} with verified recovery or cleanup evidence.\n`));
   }
   if (resolvable.length) {
-    process.stdout.write(`\n${resolvable.length} resolvable — the canonical files already agree on one generation.\n`);
+    process.stdout.write(`\n${resolvable.length} resolvable — recovery or cleanup evidence is verified.\n`);
     process.stdout.write(dim('Run `runlist doctor --transactions --apply` to clear them (no document content is touched).\n'));
   }
-  const stuck = report.filter(item => !item.resolvable && !clearedIds.has(item.id) && (item.status === 'failed-manual' || !item.readable));
+  const inProgress = report.filter(item => item.ownerLiveness === 'live' || item.lockHeld);
+  if (inProgress.length) process.stdout.write(dim(`\n${inProgress.length} in progress — another runlist process is mid-move; rerun later once it finishes.\n`));
+  const stuck = report.filter(item => !item.resolvable && !clearedIds.has(item.id) && !inProgress.includes(item));
   if (stuck.length) {
-    process.stdout.write(yellow(`\n${stuck.length} need manual review — generations disagree, so clearing them could lose work.\n`));
+    process.stdout.write(yellow(`\n${stuck.length} need manual review — generations or retained artifacts could not be verified.\n`));
     process.stdout.write(dim('Inspect the participant paths above against the artifacts in each transaction directory.\n'));
   }
 }
@@ -171,7 +174,7 @@ async function runDoctorClaims(argv, config, opts = {}) {
     return;
   }
   if (claims.length === 0) {
-    process.stdout.write(green('✓') + ' No plans are claimed — nothing can be wedged by ownership.\n');
+    process.stdout.write(green('✓') + (config.mode === 'handoffs' ? ' Nothing is claimed.\n' : ' No plans are claimed — nothing can be wedged by ownership.\n'));
     return;
   }
 
@@ -287,6 +290,7 @@ export function runDoctor(argv, config, opts = {}) {
     ? dim('[preview — run with --apply to write]')
     : dim('[applying changes]');
   process.stdout.write(bold('runlist doctor') + ' ' + modeNote + '\n\n');
+  process.stdout.write(dim('Agent integrations: runlist doctor --hosts (read-only); select --repair <host> to preview host repairs.\n\n'));
   if (dryRun) {
     const skippedHooks = ['validate', 'transformDoc', 'formatSnapshot', 'renderCheck']
       .filter(name => typeof config.hooks?.[name] === 'function');
@@ -447,6 +451,11 @@ function runDoctorProject(config, { json = false } = {}) {
   const skillDriftWarnings = checkSkillDrift(config);
   const result = {
     cliVersion: cliPackage?.version ?? null,
+    promptTracking: {
+      value: config.promptTracking ?? 'local',
+      source: config.promptTrackingSource ?? 'legacy-default',
+      configPath: config.configPath ?? null,
+    },
     installations: installationReport(config),
     packageDependency: depVersion,
     claudeCommandWarnings,
@@ -465,6 +474,7 @@ function runDoctorProject(config, { json = false } = {}) {
   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(`- prompt tracking: ${result.promptTracking.value} (source: ${result.promptTracking.source}) — inspect/change with runlist config; ignore files and Git state are unchanged\n`);
   process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);
   if (deprecatedCommandMentions.length) {
     process.stdout.write(`- docs mentioning deprecated commands: ${deprecatedCommandMentions.length}\n`);

package/src/export.mjs

@@ -5,6 +5,8 @@ import { buildIndex } from './index.mjs';
 import { buildGraph } from './graph.mjs';
 import { resolveDocPath, resolveRefPath, toRepoPath, capitalize, die } from './util.mjs';
 import { allocateOutputIdentities } from './output-identity.mjs';
+import { assertInsideHandoffs } from './handoffs-scope.mjs';
+import { assertOutsideLegacyPromptFolder } from './managed-path.mjs';
 
 export function runExport(argv, config, opts = {}) {
   const positional = [];
@@ -28,6 +30,14 @@ export function runExport(argv, config, opts = {}) {
     positional.push(argv[i]);
   }
 
+  // Before any config and where planning is off, nothing is written into the
+  // root prompts/ (src/naming.mjs), an export file or folder included.
+  const destination = output ?? (format === 'html' ? (existsSync('dotmd-export') ? 'dotmd-export' : 'runlist-export') : null);
+  if (destination) {
+    try { assertOutsideLegacyPromptFolder(destination, config, 'Export output'); }
+    catch (err) { die(err.message); }
+  }
+
   if (!['md', 'html', 'json'].includes(format)) {
     die(`Invalid format: ${format}\nValid: md, html, json`);
   }
@@ -37,6 +47,7 @@ export function runExport(argv, config, opts = {}) {
 
   if (positional[0]) {
     // Single doc + deps mode
+    assertInsideHandoffs(positional[0], config);
     const filePath = resolveDocPath(positional[0], config);
     if (!filePath) die(`File not found: ${positional[0]}`);
     const repoPath = toRepoPath(filePath, config.repoRoot);

package/src/git.mjs

@@ -41,7 +41,7 @@ function ensureGit() {
   gitChecked = true;
 }
 
-function literalGitPathspec(filePath) {
+export function literalGitPathspec(filePath) {
   return filePath === '.' ? ':(top,literal)' : `:(top,literal)${filePath}`;
 }
 
@@ -508,13 +508,69 @@ export function gitMv(source, target, repoRoot) {
 
 export function isTracked(source, repoRoot) {
   const relSource = path.isAbsolute(source) ? path.relative(repoRoot, source) : source;
-  const result = spawnSync('git', ['ls-files', '--error-unmatch', '--', relSource], {
+  const result = spawnSync('git', ['ls-files', '--error-unmatch', '--', literalGitPathspec(relSource)], {
     cwd: repoRoot,
     encoding: 'utf8',
   });
   return result.status === 0;
 }
 
+// A path-limited commit needs both sides of a staged move: the old path is
+// absent from the index but still in HEAD. Never offer to add that missing
+// path, or commit a missing path that Git has never known about.
+export function gitCommitPaths(paths, repoRoot, options = {}) {
+  const unique = [...new Set(paths)];
+  if (!unique.length) return { paths: [], add: [] };
+  const maxPathsPerBatch = boundedPositiveInteger(options.maxPathsPerBatch, DEFAULT_GIT_METADATA_PATH_BATCH, 'maxPathsPerBatch');
+  const runGit = options.runGit ?? spawnSync;
+  const spawnOptions = { cwd: repoRoot, encoding: 'utf8' };
+  // On incomplete classification, preserve the original plain commit hint.
+  // Partial results must never drop a tracked move source or propose staging.
+  const fallback = () => ({ paths: unique, add: [] });
+  try {
+    assertSafeGitPaths(unique);
+    const indexed = new Set();
+    for (let offset = 0; offset < unique.length; offset += maxPathsPerBatch) {
+      const batch = unique.slice(offset, offset + maxPathsPerBatch);
+      const listed = runGit('git', ['ls-files', '-z', '--', ...batch.map(literalGitPathspec)], spawnOptions);
+      if (listed.error || listed.status !== 0) return fallback();
+      for (const file of listed.stdout.split('\0').filter(Boolean)) indexed.add(file);
+    }
+    const missing = new Set(unique.filter(file => !indexed.has(file) && !existsSync(path.resolve(repoRoot, file))));
+    const inHead = new Set();
+    if (missing.size) {
+      const missingPaths = [...missing];
+      for (let offset = 0; offset < missingPaths.length; offset += maxPathsPerBatch) {
+        const batch = missingPaths.slice(offset, offset + maxPathsPerBatch);
+        const head = runGit('git', ['ls-tree', '-r', '--name-only', '-z', 'HEAD', '--', ...batch.map(literalGitPathspec)], spawnOptions);
+        if (head.error || head.status !== 0) {
+          // An unborn HEAD is normal; other failures cannot prove paths absent.
+          const revision = runGit('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], spawnOptions);
+          if (!head.error && !revision.error && revision.status === 1) break;
+          return fallback();
+        }
+        for (const file of head.stdout.split('\0').filter(Boolean)) inHead.add(file);
+      }
+    }
+    const candidates = unique.filter(file => !indexed.has(file) && !missing.has(file));
+    const ignored = new Set();
+    if (candidates.length) {
+      // NUL input preserves filename boundaries and treats brackets literally;
+      // check-ignore still parses leading ':' pathspec magic.
+      const result = runGit('git', ['check-ignore', '--stdin', '-z'], {
+        ...spawnOptions, input: candidates.join('\0') + '\0',
+      });
+      if (result.error || ![0, 1].includes(result.status)) return fallback();
+      if (result.status === 0) for (const file of result.stdout.split('\0').filter(Boolean)) ignored.add(file);
+    }
+    const add = candidates.filter(file => !ignored.has(file));
+    const committable = new Set([...indexed, ...inHead, ...add]);
+    return { paths: unique.filter(file => committable.has(file)), add };
+  } catch {
+    return fallback();
+  }
+}
+
 export function gitIndexLocations(repoRoot) {
   const result = spawnSync('git', ['rev-parse', '--git-dir'], { cwd: repoRoot, encoding: 'utf8' });
   if (result.error || result.status !== 0) throw new Error(`Could not locate Git directory: ${result.error?.message || result.stderr.trim()}`);