runlist 0.99.1 → 0.100.0

package/src/codex-integration.mjs

@@ -1,6 +1,7 @@
 // Codex's default personal marketplace is discovered without a CLI registration.
 // The npm package carries this plugin so installation does not need a Git checkout.
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +12,35 @@ const SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..',
 const NAME = 'runlist-codex';
 const MARKER = '.runlist-generated.json';
 
+// Compare the whole distributed tree, including hook scripts and manifests.
+// The ownership marker is metadata, never an asset or proof of source parity.
+export function codexAssetFingerprint(root) {
+  const hash = createHash('sha256');
+  let files = 0, bytes = 0;
+  function visit(dir, prefix = '', depth = 0) {
+    if (depth > 32) throw new Error('asset depth limit');
+    for (const name of readdirSync(dir).sort()) {
+      if (!prefix && name === MARKER) continue;
+      const relative = prefix ? `${prefix}/${name}` : name;
+      const file = path.join(dir, name);
+      const stat = lstatSync(file);
+      if (++files > 2000 || (bytes += stat.size) > 64 * 1024 * 1024) throw new Error('asset inventory limit');
+      const kind = stat.isSymbolicLink() ? 'link' : stat.isDirectory() ? 'dir' : stat.isFile() ? 'file' : 'other';
+      hash.update(JSON.stringify([relative, kind, kind === 'file' ? stat.mode & 0o111 : null]) + '\n');
+      if (kind === 'dir') visit(file, relative, depth + 1);
+      else if (kind === 'link') hash.update(JSON.stringify(readlinkSync(file)) + '\n');
+      else if (kind === 'file') hash.update(readFileSync(file));
+    }
+  }
+  try { visit(root); return hash.digest('hex'); } catch { return null; }
+}
+
+export function codexAssetParity(installedPath, sourcePath = SOURCE) {
+  const expected = codexAssetFingerprint(sourcePath);
+  const actual = codexAssetFingerprint(installedPath);
+  return { state: !expected || !actual ? 'unknown' : expected === actual ? 'match' : 'mismatch', expected, actual };
+}
+
 export function codexPaths(homedir = os.homedir()) {
   const root = path.join(homedir, '.agents', 'plugins');
   // The implicit personal marketplace file lives under ~/.agents/plugins,
@@ -32,24 +62,44 @@ export function codexStatus({ version, homedir = os.homedir() } = {}) {
   let installed = null;
   try { installed = JSON.parse(readFileSync(path.join(paths.plugin, MARKER), 'utf8')).version; } catch { /* absent or foreign */ }
   const exists = existsSync(paths.plugin);
-  return { ...paths, exists, foreign: exists && !installed, version: installed, stale: Boolean(installed && version && installed !== version) };
+  const sourceParity = installed ? codexAssetParity(paths.plugin) : { state: 'unknown' };
+  let marketplaceState = existsSync(paths.marketplace) ? 'unreadable' : 'missing';
+  let marketplaceRegistered = false, foreignRegistration = false;
+  try {
+    const marketplace = marketplaceAt(paths.marketplace);
+    const entry = marketplace.plugins.find(item => item?.name === NAME);
+    marketplaceState = existsSync(paths.marketplace) ? 'readable' : 'missing';
+    marketplaceRegistered = entry?.source?.source === 'local' && entry.source.path === `./plugins/${NAME}`;
+    foreignRegistration = Boolean(entry && !marketplaceRegistered);
+  } catch { /* An unreadable registration cannot establish a managed source. */ }
+  return { ...paths, exists, foreign: (exists && !installed) || foreignRegistration, version: installed, sourceParity,
+    marketplaceState, marketplaceRegistered,
+    stale: Boolean(installed && ((version && installed !== version) || sourceParity.state !== 'match' || !marketplaceRegistered)) };
 }
 
 // The marketplace source is not the plugin Codex loads. Ask the host about its
 // installed copy rather than treating our generated source marker as proof.
-export function installedCodexStatus({ homedir = os.homedir(), run = spawnSync } = {}) {
+export function installedCodexStatus({ homedir = os.homedir(), run = spawnSync, env = process.env, binary, offline = false } = {}) {
+  if (offline) return { ok: false, state: 'unknown', loaded: 'unknown', reason: 'offline inventory cannot attest the host installed copy or loaded session' };
   try {
     const marketplace = marketplaceAt(codexPaths(homedir).marketplace).name;
     const pluginId = `${NAME}@${marketplace}`;
-    const result = run(executableName('codex'), ['plugin', 'list', '--marketplace', marketplace, '--json'], {
-      encoding: 'utf8', shell: process.platform === 'win32', timeout: 30_000,
+    const result = run(binary || executableName('codex'), ['plugin', 'list', '--marketplace', marketplace, '--json'], {
+      encoding: 'utf8', shell: process.platform === 'win32' && (!binary || /\.(?:cmd|bat)$/i.test(binary)), timeout: 30_000, env: { ...env, HOME: homedir, USERPROFILE: homedir },
     });
     if (result.status !== 0) return { ok: false, reason: result.error?.message ?? `codex plugin list exited ${result.status ?? '?'}` };
     const installed = JSON.parse(result.stdout).installed;
     if (!Array.isArray(installed)) return { ok: false, reason: 'codex plugin list returned no installed plugin records' };
     const plugin = installed.find(entry => entry.pluginId === pluginId && entry.installed === true);
-    return plugin?.version ? { ok: true, version: plugin.version, pluginId }
-      : { ok: false, reason: `${pluginId} is not installed in Codex` };
+    if (!plugin?.version) return { ok: false, reason: `${pluginId} is not installed in Codex` };
+    // Host versions do not establish byte parity. Inspect a host-provided path
+    // when this CLI supports one, otherwise retain the explicit unknown state.
+    const installedPath = plugin.installPath ?? plugin.installedPath ?? plugin.pluginPath ?? plugin.path;
+    const sourceParity = typeof installedPath === 'string' && path.isAbsolute(installedPath)
+      ? codexAssetParity(installedPath, codexPaths(homedir).plugin) : { state: 'unknown' };
+    return { ok: sourceParity.state !== 'mismatch', version: plugin.version, pluginId, sourceParity, loaded: 'unknown',
+      ...(sourceParity.state === 'mismatch' ? { reason: 'installed Codex plugin assets differ from the managed source' } : {}),
+      ...(typeof installedPath === 'string' && path.isAbsolute(installedPath) ? { installedPath } : {}) };
   } catch (err) {
     return { ok: false, reason: `cannot verify installed Codex plugin: ${err.message}` };
   }

package/src/commands.mjs

@@ -7,8 +7,9 @@ const flag = (...names) => Object.freeze({ names: Object.freeze(names), arity: 0
 const value = (...names) => Object.freeze({ names: Object.freeze(names), arity: 1 });
 const optionalValue = (...names) => Object.freeze({ names: Object.freeze(names), arity: 'optional' });
 const positionals = (min = 0, max = min) => Object.freeze({ min, max });
-const form = (syntax, { subcommands = [], args = positionals(), options = [], passthrough = false, dashPositionalsAfter = Infinity } = {}) => Object.freeze({
+const form = (syntax, { subcommands = [], args = positionals(), options = [], passthrough = false, dashPositionalsAfter = Infinity, planning } = {}) => Object.freeze({
   syntax,
+  planning,
   subcommands: Object.freeze(subcommands),
   positionals: args,
   options: Object.freeze(options),
@@ -47,12 +48,29 @@ const command = (name, policy, group, forms, extra = {}) => Object.freeze({
   forms: Object.freeze(forms),
   aliases: Object.freeze(extra.aliases ?? []),
   visibility: extra.visibility ?? 'public',
+  planning: extra.planning ?? null,
 });
 
+// `planning` marks a command (or one form of it) that only means something
+// with planning on. In a handoffs-only project (src/handoffs-mode.mjs) the
+// dispatcher stops it before it runs: a 'view' prints the planning-off line
+// and succeeds, an 'action' refuses. A new plan or doc command opts in here;
+// test/handoffs-planning-gate.test.mjs walks this registry.
+const VIEW = Object.freeze({ planning: 'view' });
+const ACTION = Object.freeze({ planning: 'action' });
+
 const definitions = [
   command('help', none, 'setup', [form('[topic]', { args: positionals(0, 1) })]),
   command('completions', none, 'setup', [form('<bash|zsh>', { args: positionals(1, 1) })]),
-  command('init', mutates('repository setup paths and config files'), 'setup', [form('', { options: [flag('--force')] })]),
+  command('init', mutates('repository setup paths and config files; ignore rules only by explicit opt-in'), 'setup', [form('', { options: [flag('--force'), flag('--gitignore'), value('--prompt-tracking')] })], ACTION),
+  command('setup', mutates('explicit project onboarding choices; noninteractive preview unless --yes; host installation only when selected'), 'setup', [form('', {
+    options: [flag('--yes'), flag('--no-carry-prompts'), value('--docs-root'), value('--prompt-tracking'), flag('--gitignore'), value('--host'), value('--first-plan'), value('--current-state'), value('--next-step'), value('--adopt'), flag('--json')],
+  })]),
+  command('config', mutates('validated promptTracking export only; show/get are read-only'), 'setup', [
+    form('show', { subcommands: ['show'], options: [flag('--json')] }),
+    form('get <key>', { subcommands: ['get'], args: positionals(1, 1), options: [flag('--json')] }),
+    form('set <key> <value>', { subcommands: ['set'], args: positionals(2, 2), options: [flag('--json')] }),
+  ]),
   command('watch', mutates('proxy: child command policy applies'), 'setup', [form('[command...]', { args: positionals(0, Infinity), passthrough: true })]),
   command('desktop', mutates('explicit desktop installation; otherwise launch only'), 'setup', [
     form('[--app <application>]', {options:[value('--app')]}),
@@ -62,34 +80,34 @@ const definitions = [
 
   command('list', none, 'read', [form('', { options: [flag('--json'), flag('--verbose')] })]),
   command('json', none, 'read', [form('')]),
-  command('coverage', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('coverage', none, 'read', [form('', { options: [flag('--json')] })], VIEW),
   command('yardstick', mutates('explicit owner assessments and existing archive workflow; show is read-only'), 'mutate', [
-    form('show [plan]', { subcommands: ['show'], args: positionals(0, 1), options: [flag('--json')] }),
+    form('show [plan]', { planning: 'view', subcommands: ['show'], args: positionals(0, 1), options: [flag('--json')] }),
     form('mark <plan> serves', { subcommands: ['mark'], args: positionals(2, 2), options: [value('--reason'), flag('--json'), flag('--no-index')] }),
     form('close <plan> --reason <text>', { subcommands: ['close'], args: positionals(1, 1), options: [value('--reason'), flag('--json'), flag('--no-index')] }),
     form('fold <plan> --into <plan> --reason <text>', { subcommands: ['fold'], args: positionals(1, 1), options: [value('--into'), value('--reason'), flag('--json'), flag('--no-index')] }),
     form('clear <plan>', { subcommands: ['clear'], args: positionals(1, 1), options: [flag('--json'), flag('--no-index')] }),
-  ]),
-  command('stats', none, 'read', [form('', { options: [flag('--json')] })]),
-  command('graph', none, 'read', [form('', { options: [flag('--dot'), flag('--json'), value('--status'), value('--module'), value('--surface')] })]),
-  command('deps', none, 'read', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), value('--depth')] })]),
+  ], ACTION),
+  command('stats', none, 'read', [form('', { options: [flag('--json')] })], VIEW),
+  command('graph', none, 'read', [form('', { options: [flag('--dot'), flag('--json'), value('--status'), value('--module'), value('--surface')] })], VIEW),
+  command('deps', none, 'read', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), value('--depth')] })], VIEW),
   command('briefing', none, 'read', [form('', { options: [flag('--json')] })]),
   command('context', none, 'read', [form('', { options: [flag('--json'), flag('--compact'), flag('--summarize'), value('--model'), value('--sections'), value('--max-bytes')] })]),
   command('agent-context', none, 'read', [form('', { options: [flag('--json'), value('--sections'), value('--max-bytes')] })]),
   command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent'), flag('--prompt-submit')] })]),
-  command('focus', none, 'read', [form('[status]', { args: positionals(0, 1), options: [flag('--json')] })]),
+  command('focus', none, 'read', [form('[status]', { args: positionals(0, 1), options: [flag('--json')] })], VIEW),
   command('query', none, 'read', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
   command('grep', none, 'read', [form('<term> [terms...]', { args: positionals(1, Infinity), options: QUERY_OPTIONS })]),
   command('plans', none, 'read', [
     form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS }),
     form('status [terms...]', { subcommands: ['status'], args: positionals(0, Infinity), options: QUERY_OPTIONS }),
-  ]),
-  command('runlists', none, 'read', [form('', { options: [flag('--json'), value('--limit'), value('--sort')] })]),
-  command('roadmaps', none, 'read', [form('', { options: [flag('--json')] })]),
+  ], VIEW),
+  command('runlists', none, 'read', [form('', { options: [flag('--json'), value('--limit'), value('--sort')] })], VIEW),
+  command('roadmaps', none, 'read', [form('', { options: [flag('--json')] })], VIEW),
   command('diff', none, 'read', [form('[file]', { args: positionals(0, 1), options: [flag('--stat'), value('--since'), flag('--summarize'), value('--model')] })]),
   command('summary', none, 'read', [form('<file>', { args: positionals(1, 1), options: [value('--model'), value('--max-tokens'), flag('--json')] })]),
-  command('unblocks', none, 'read', [form('<file>', { args: positionals(1, 1), options: [flag('--json')] })]),
-  command('health', none, 'read', [form('', { options: [flag('--json')] })]),
+  command('unblocks', none, 'read', [form('<file>', { args: positionals(1, 1), options: [flag('--json')] })], VIEW),
+  command('health', none, 'read', [form('', { options: [flag('--json')] })], VIEW),
   command('flags', none, 'read', [form('', { options: [flag('--all'), flag('--json')] })]),
   command('flag', mutates('the flags log under the state directory'), 'mutate', [
     form('add <file[:line]> <text...>', { subcommands: ['add'], args: positionals(2, Infinity), options: [value('--severity'), value('--by')] }),
@@ -99,7 +117,7 @@ const definitions = [
     form('show <id>', { subcommands: ['show'], args: positionals(1, 1) }),
     form('sync <check-name> [findings]', { subcommands: ['sync'], args: positionals(1, 2), dashPositionalsAfter: 1 }),
   ]),
-  command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })]),
+  command('glossary', none, 'read', [form('[term]', { args: positionals(0, 1), options: [flag('--list'), flag('--json')] })], VIEW),
   command('model', mutates('~/.runlist/model.json and the local model server'), 'read', [
     form('', { options: [flag('--json')] }),
     form('status', { subcommands: ['status'], options: [flag('--json')] }),
@@ -112,21 +130,21 @@ const definitions = [
   command('show', none, 'read', [form('<file...>', { args: positionals(1, Infinity), options: [flag('--json'), flag('--card'), flag('--all'), flag('--frontmatter'), value('--section', '-s'), value('--from')] })]),
   command('xref', mutates('the flags log under the state directory with --check --flag; otherwise read-only'), 'read', [
     form('<file...> | --check [--flag]', { args: positionals(0, Infinity), options: [flag('--json'), flag('--check'), flag('--flag')] }),
-  ]),
-  command('record', mutates('native flag or decision through the shared domain writer'), 'mutate', [form('<file> <action>', { args: positionals(2, 2), options: [value('--note'), value('--option'), value('--expected-revision'), flag('--json')] })]),
-  command('decision', mutates('selected decision source through the source editor'), 'mutate', [form('<file> <id>', { args: positionals(2, 2), options: [value('--disposition'), value('--note'), value('--choice'), value('--expected-revision'), flag('--json')] })]),
-  command('decisions', none, 'read', [form('[doc-or-id]', { args: positionals(0, 1), options: [flag('--all'), flag('--json'), flag('--check')] })]),
-  command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })]),
-  command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })]),
-  command('surfaces', none, 'read', [form('', { options: [flag('--json')] })]),
+  ], VIEW),
+  command('record', mutates('native flag or decision through the shared domain writer'), 'mutate', [form('<file> <action>', { args: positionals(2, 2), options: [value('--note'), value('--option'), value('--expected-revision'), flag('--json')] })], ACTION),
+  command('decision', mutates('selected decision source through the source editor'), 'mutate', [form('<file> <id>', { args: positionals(2, 2), options: [value('--disposition'), value('--note'), value('--choice'), value('--expected-revision'), flag('--json')] })], ACTION),
+  command('decisions', none, 'read', [form('[doc-or-id]', { args: positionals(0, 1), options: [flag('--all'), flag('--json'), flag('--check')] })], VIEW),
+  command('modules', none, 'read', [form('', { options: [value('--sort'), value('--limit'), flag('--all'), flag('--json')] })], VIEW),
+  command('module', none, 'read', [form('<name>', { args: positionals(1, 1), options: [value('--sort'), flag('--json')] })], VIEW),
+  command('surfaces', none, 'read', [form('', { options: [flag('--json')] })], VIEW),
   command('journal', none, 'read', [form('', { options: [value('--tail'), flag('--errors'), value('--session'), value('--since'), flag('--by-command'), flag('--help-topics'), flag('--json')] })]),
   command('errors', none, 'read', [form('', { options: [flag('--json'), flag('--by-family'), value('--limit'), value('--tail'), value('--repo')] })]),
   command('misuse', none, 'read', [form('', { options: [flag('--json'), value('--tail'), flag('--by-rule'), value('--repo')] })]),
 
   command('roadmap', mutates('managed source when `next`; otherwise read-only'), 'workflow', [
     form('[hub]', { args: positionals(0, 1), options: [flag('--json')] }),
-    form('next [hub]', { subcommands: ['next'], args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index')] }),
-  ]),
+    form('next [hub]', { planning: 'action', subcommands: ['next'], args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index')] }),
+  ], VIEW),
   command('prompts', mutates('managed sources/destinations by subcommand'), 'workflow', [
     form('', { options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
     form('list', { subcommands: ['list', 'status'], options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
@@ -141,18 +159,18 @@ const definitions = [
   ], { aliases: ['prompt'] }),
   command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
-  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), value('--parent'), flag('--template'), flag('--force'), flag('--replace'), flag('--done'), flag('--subagent'), flag('--json')] })]),
+  command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), value('--parent'), flag('--template'), flag('--force'), flag('--replace'), flag('--done'), value('--next-step'), value('--current-state'), flag('--subagent'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
-    form('next <hub>', { subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
-    form('add <hub> <child...>', { subcommands: ['add'], args: positionals(2, Infinity), options: [flag('--json')] }),
-    form('remove <hub> <child...>', { subcommands: ['remove'], args: positionals(2, Infinity), options: [flag('--json'), flag('--clear-parent')] }),
-    form('reorder <hub> <child...>', { subcommands: ['reorder'], args: positionals(2, Infinity), options: [flag('--json'), value('--before'), value('--after')] }),
-  ]),
+    form('next <hub>', { planning: 'action', subcommands: ['next'], args: positionals(1, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files')] }),
+    form('add <hub> <child...>', { planning: 'action', subcommands: ['add'], args: positionals(2, Infinity), options: [flag('--json')] }),
+    form('remove <hub> <child...>', { planning: 'action', subcommands: ['remove'], args: positionals(2, Infinity), options: [flag('--json'), flag('--clear-parent')] }),
+    form('reorder <hub> <child...>', { planning: 'action', subcommands: ['reorder'], args: positionals(2, Infinity), options: [flag('--json'), value('--before'), value('--after')] }),
+  ], VIEW),
 
   command('export', mutates('external output path intentionally unrestricted'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [value('--format'), value('--output'), value('--status'), value('--module'), value('--root'), value('--type')] })]),
   command('guard', mutates('global misuse log; no managed document writes'), 'mutate', [form('')]),
-  command('update', mutates('global CLI and plugin installation state'), 'mutate', [form('', { options: [flag('--check'), flag('--cli-only'), flag('--plugin-only')] })]),
+  command('update', mutates('global CLI and installed host integrations; --check is offline and read-only'), 'mutate', [form('', { options: [flag('--check'), flag('--json'), flag('--cli-only'), flag('--plugin-only'), value('--host'), value('--claude-config'), value('--claude-bin')] })]),
   command('install', mutates('agent-host plugin directory outside the repo'), 'mutate', [
     form('[host]', { args: positionals(0, 1), options: [flag('--remove'), flag('--force'), flag('--json'), value('--path')] }),
   ]),
@@ -162,9 +180,9 @@ const definitions = [
   command('archive', mutates('managed source and same-root destination'), 'mutate', [form('<file>', { args: positionals(1, 1), options: [...LIFECYCLE_OPTIONS, flag('--closeout-template'), flag('--fix-refs'), flag('--strings')] })]),
   command('bulk', mutates('managed source sweep; archive destinations preserve roots'), 'mutate', [
     form('archive <files...>', { subcommands: ['archive'], args: positionals(1, Infinity), options: [flag('--json'), flag('--no-index'), flag('--show-files')] }),
-    form('tag [files...]', { subcommands: ['tag'], args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] }),
+    form('tag [files...]', { planning: 'action', subcommands: ['tag'], args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] }),
   ]),
-  command('bulk-tag', mutates('managed source sweep'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] })]),
+  command('bulk-tag', mutates('managed source sweep'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [value('--type'), value('--status'), flag('--json')] })], ACTION),
   command('touch', mutates('managed source or managed source sweep'), 'mutate', [form('[file...]', { args: positionals(0, Infinity), options: [flag('--git')] })]),
   command('new', mutates('managed document destination; external body input unrestricted'), 'mutate', [form('[type] <name> [body...]', {
     args: positionals(0, Infinity),
@@ -179,9 +197,9 @@ const definitions = [
     form('repair', { subcommands: ['repair'], options: [flag('--fix'), flag('--strings')] }),
     form('<old> <new>', { args: positionals(2, 2), options: [flag('--fix'), flag('--strings')] }),
   ]),
-  command('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })]),
-  command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--prompts'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
+  command('fix-membership', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--json')] })], ACTION),
+  command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })], ACTION),
+  command('doctor', mutates('managed sweeps and maintenance by mode; --hosts reports read-only or applies explicitly selected host repairs'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--prompts'), flag('--transactions'), flag('--claims'), flag('--session'), flag('--hosts'), value('--repair'), value('--claude-config'), value('--claude-bin'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),
@@ -200,8 +218,8 @@ const definitions = [
   command('finish', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
   command('handoff', none, 'removed', [form('[args...]', { args: positionals(0, Infinity) })], { visibility: 'removed' }),
 
-  command('stale', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
-  command('actionable', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
+  command('stale', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })], VIEW),
+  command('actionable', none, 'preset', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })], VIEW),
 ];
 
 function schemaErrors(schema) {
@@ -213,6 +231,9 @@ function schemaErrors(schema) {
     names.add(entry.name);
     if (!entry.group) errors.push(`${entry.name}: missing help group`);
     if (!entry.forms.length) errors.push(`${entry.name}: missing forms`);
+    for (const planning of [entry.planning, ...entry.forms.map(commandForm => commandForm.planning)]) {
+      if (planning != null && planning !== 'view' && planning !== 'action') errors.push(`${entry.name}: planning must be 'view' or 'action'`);
+    }
     for (const alias of entry.aliases) {
       if (!alias || names.has(alias) || aliases.has(alias)) errors.push(`${entry.name}: duplicate alias ${alias}`);
       aliases.add(alias);
@@ -310,6 +331,11 @@ function scanArgs(name, argv, options, passthrough = false, dashPositionalsAfter
     if (!option) {
       if (passthrough) continue;
       if (positional.length >= dashPositionalsAfter) { positional.push(arg); continue; }
+      if (name === 'show' && arg === '--lines') {
+        throw new Error('Unknown flag for `runlist show`: --lines\n\n'
+          + 'Drop --lines. Continue with `runlist show <file> --section "<heading>" --from <line>`.\n'
+          + 'Section output is bounded automatically; --from is an absolute file line.');
+      }
       throw new Error(`Unknown flag for \`runlist ${name}\`: ${arg}`);
     }
     if (option.arity === 1) {
@@ -325,6 +351,34 @@ function scanArgs(name, argv, options, passthrough = false, dashPositionalsAfter
   return positional;
 }
 
+// Help selects a form without requiring the arguments needed to execute it.
+export function commandHelpContext(name, argv) {
+  const definition = commandDefinition(name);
+  if (!definition) return null;
+  const options = optionMap(definition.forms);
+  for (const option of GLOBAL_OPTIONS) {
+    for (const alias of option.names) if (!options.has(alias)) options.set(alias, option);
+  }
+  const positional = scanArgs(definition.name, argv, options);
+  const selected = definition.forms.find(entry => entry.subcommands.includes(positional[0]));
+  return { positional, subcommand: selected?.subcommands[0] ?? null };
+}
+
+// Whether a command, in the form these arguments select, needs planning on:
+// `{ requirement: 'view' | 'action', subcommand }`, or null (see VIEW/ACTION
+// above). Read before argument validation, so a planning command missing its
+// arguments still hears that planning is off rather than its usage.
+export function commandPlanning(name, argv) {
+  const definition = commandDefinition(name);
+  if (!definition) return null;
+  let subcommand = null;
+  try { subcommand = commandHelpContext(definition.name, normalizeCommandArgs(definition.name, argv)).subcommand; } catch { /* unknown flag: the command's own form */ }
+  const selected = definition.forms.find(entry => entry.subcommands.includes(subcommand))
+    ?? definition.forms.find(entry => entry.subcommands.length === 0);
+  const requirement = selected?.planning ?? definition.planning;
+  return requirement ? { requirement, subcommand } : null;
+}
+
 export function normalizeCommandArgs(name, argv) {
   const canonical = canonicalCommand(name);
   if (canonical !== 'roadmap') return [...argv];

package/src/config-command.mjs

@@ -0,0 +1,115 @@
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { assertSnapshotCurrent, replaceSnapshot, snapshotFile } from './atomic-mutation.mjs';
+import { renderPromptTrackingSetting } from './config-setting.mjs';
+import { promptDirectory, promptRouting } from './new.mjs';
+
+const KEY = 'promptTracking';
+const VALUES = ['untracked', 'tracked', 'local'];
+const READABLE = Object.freeze([KEY, 'mode', 'root', 'docsRoots', 'index.path', 'archiveDir', 'promptDirectory']);
+const USAGE = 'Usage: runlist config show [--json] | get <key> [--json] | set promptTracking <untracked|tracked|local> [--json]';
+
+function inspectSettings(config) {
+  const source = key => config.settingSources?.[key] ?? 'unknown';
+  return {
+    promptTracking: { value: config.promptTracking, source: config.promptTrackingSource },
+    mode: { value: config.mode ?? 'plans', source: source('mode') },
+    root: { value: config.raw?.root ?? '.', source: source('root') },
+    docsRoots: { value: config.docsRoots ?? [config.docsRoot], source: 'derived' },
+    'index.path': { value: config.indexPath ?? null, source: source('index.path') },
+    archiveDir: { value: config.archiveDir, source: source('archiveDir') },
+    // Markdown template overrides change content, not routing. Inspect only
+    // layout so a broken content template cannot prevent settings inspection.
+    promptDirectory: { value: promptDirectory(config, promptRouting(config)), source: 'derived' },
+  };
+}
+
+function manualSetting(key, configPath) {
+  const file = configPath ?? 'runlist.config.mjs (create it with runlist setup)';
+  if (key === 'mode') return `A handoffs-only project turns planning on with runlist setup, which previews the change to ${file} first.`;
+  if (key === 'root' || key === 'docsRoots') return `Edit the root export in ${file}, review dependent index/template paths, then run runlist init --dry-run and runlist check. A new project can choose --docs-root during setup. Existing files are not moved automatically.`;
+  if (key === 'promptDirectory') return `Edit templates.prompt.dir or templates.prompt.targetRoot and the root export in ${file}, then inspect runlist config get promptDirectory. Existing prompts are not moved automatically.`;
+  return `Edit ${key === 'index.path' ? 'the index.path property (or legacy readme.path)' : 'the archiveDir export'} in ${file}, then run runlist init --dry-run and runlist check. Existing files are not moved automatically.`;
+}
+
+function checkSyntax(content) {
+  try {
+    execFileSync(process.execPath, ['--input-type=module', '--check'], { input: content, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    throw new Error("Config is not a supported JavaScript module. Edit promptTracking manually in your config; no changes were made.");
+  }
+}
+
+function assertRegularConfig(configPath, repoRoot) {
+  const resolved = path.resolve(configPath);
+  // Replacing a symlink would sever it. Refuse symlinked parent paths as well
+  // so the loaded source and the publication path cannot silently diverge.
+  const boundary = path.resolve(repoRoot);
+  for (let cursor = resolved; ; cursor = path.dirname(cursor)) {
+    if (lstatSync(cursor).isSymbolicLink()) throw new Error(`Config path uses a symlink: ${cursor}. Edit the config manually; no changes were made.`);
+    if (cursor === boundary || path.dirname(cursor) === cursor) break;
+  }
+  if (!lstatSync(resolved).isFile()) throw new Error(`Config path is not a regular file: ${resolved}`);
+  return realpathSync(resolved);
+}
+
+export async function runConfig(argv, config, { dryRun = false, out = process.stdout, testHooks } = {}) {
+  if (argv.filter(arg => arg === '--json').length > 1 || argv.some(arg => arg.startsWith('-') && arg !== '--json')) throw new Error(USAGE);
+  const json = argv.includes('--json');
+  const args = argv.filter(arg => arg !== '--json');
+  const [action, key, value] = args;
+  if (!['show', 'get', 'set'].includes(action) || args.length !== ({ show: 1, get: 2, set: 3 })[action]) throw new Error(USAGE);
+  if (action !== 'show' && !READABLE.includes(key)) throw new Error(`Unsupported config key '${key}'. Readable settings: ${READABLE.join(', ')}. Editable setting: ${KEY}. Edit other exports manually in ${config.configPath ?? 'runlist.config.mjs (create it with runlist setup)'}.`);
+  const configPath = config.configPath ?? null;
+  if (action === 'set' && key !== KEY) throw new Error(`${key} is read-only in the CLI. ${manualSetting(key, configPath)} No changes were made.`);
+  const settings = action === 'set'
+    ? { [KEY]: { value: config.promptTracking, source: config.promptTrackingSource } }
+    : inspectSettings(config);
+  const setting = { key: key ?? KEY, ...settings[key ?? KEY], configPath };
+  let result;
+  if (action === 'show') {
+    result = { supportedSettings: [KEY], readableSettings: READABLE, editableSettings: [KEY], settings, configPath };
+  } else if (action === 'get') {
+    result = { supportedSettings: [KEY], readableSettings: READABLE, editableSettings: [KEY], ...setting };
+  } else {
+    if (!VALUES.includes(value)) throw new Error("promptTracking must be 'untracked', 'tracked', or 'local'.");
+    if (!configPath || !config.configFound || !existsSync(configPath)) throw new Error('No project config found. Run runlist setup before config set.');
+    const file = assertRegularConfig(configPath, config.repoRoot);
+    const snapshot = snapshotFile(file);
+    checkSyntax(snapshot.content);
+    const edit = renderPromptTrackingSetting(snapshot.content, value);
+    checkSyntax(edit.content);
+    const changed = edit.content !== snapshot.content;
+    result = { action, supportedSettings: [KEY], key: KEY, previousValue: edit.previousValue, value, source: 'config', configPath, changed, dryRun };
+    if (!dryRun && changed) {
+      replaceSnapshot(snapshot, edit.content, {
+        repoRoot: config.repoRoot,
+        testHooks: {
+          ...testHooks,
+          beforeReplacePublish(info) {
+            testHooks?.beforeReplacePublish?.(info);
+            assertRegularConfig(configPath, config.repoRoot);
+            assertSnapshotCurrent(snapshot);
+          },
+        },
+      });
+    }
+  }
+  if (json) out.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    out.write(`Editable setting: ${KEY}\n`);
+    out.write(`Config path: ${configPath ?? '(none; run runlist setup to create one)'}\n`);
+    if (action === 'show') {
+      for (const [name, entry] of Object.entries(settings)) out.write(`${name}: ${JSON.stringify(entry.value)} (source: ${entry.source}${name === KEY ? '; editable' : '; read-only'})\n`);
+    } else {
+      if (action === 'set') out.write(`${dryRun ? '[dry-run] Would set' : changedLabel(result.changed)} ${KEY} = ${value}\n`);
+      out.write(`Effective value${action === 'set' && dryRun ? ' after proposed change' : ''}: ${action === 'set' ? value : JSON.stringify(setting.value)}\n`);
+      out.write(`Source: ${action === 'set' ? 'config' : setting.source}\n`);
+    }
+    if ((action === 'show' || key === KEY) && (action === 'set' ? value : settings.promptTracking.value) === 'untracked') out.write('Leave pending prompts untracked to reduce commit churn. git add -A can still stage them.\n');
+  }
+  return result;
+}
+
+function changedLabel(changed) { return changed ? 'Set' : 'Already set'; }