runlist 0.95.2 → 0.95.5

package/README.md

@@ -47,8 +47,8 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.95.2**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.95.2).
+CLI and desktop release version: **0.95.5**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.95.5).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 
@@ -219,7 +219,14 @@ and managed scopes are reported rather than silently updating another scope.
 The release workflow uses the same scope selection and verifies every entry
 against the released version.
 
-Restart Claude Code, or run `/reload-plugins`, after a plugin update.
+Updates also refresh already installed OpenCode and Codex integrations. After
+upgrading the CLI, host installers run from the updated package so their version
+and assets match. Codex verification checks the host's installed copy separately
+from its marketplace source. Releases use these same checks and remain resumable
+if an installed host fails to update. Uninstalled hosts are not added.
+
+Restart the affected host sessions to load updated integrations; Claude Code also
+supports `/reload-plugins`.
 
 ## Quick Start
 

package/bin/runlist.mjs

@@ -293,7 +293,7 @@ Validate & Fix:
   doctor --transactions             Report/clear wedged mutation transactions (run this if mutations refuse repo-wide)
   doctor --claims                   Report/release plan claims held by sessions that are gone ("busy in another session")
   self-check                        Project/version skew diagnostic (alias: doctor --project)
-  lint [--fix]                      Check and auto-fix frontmatter issues
+  lint [files...] [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
   refs <old> <new> [--fix]          Report (or rewrite) code-root citations of a moved document
   refs repair [--fix]               Same, for every archived document still cited at its old path
@@ -923,7 +923,7 @@ Modes:
                          history; a "Migrated to v0.21 template" entry
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
-  --frontmatter-fix      Auto-fix the long-frontmatter warnings that
+  --frontmatter-fix [path]  Repair only that document when supplied; otherwise auto-fix the long-frontmatter warnings that
                          \`runlist check\` flags: \`current_state\` >1500 chars
                          or \`next_step\` >800 chars. Truncates the
                          frontmatter field at the nearest sentence
@@ -1195,9 +1195,9 @@ Options:
   --summarize            Generate AI summary using local model
   --model <name>         Model to use (default: the one \`runlist model\` shows)`,
 
-  lint: `runlist lint [--fix] — check and auto-fix frontmatter issues
+  lint: `runlist lint [files...] [--fix] — check and auto-fix frontmatter issues
 
-Scans all docs for fixable problems:
+Scans the selected documents, or all docs when no file is supplied, for fixable problems:
   - Missing status (inferred via local AI model when available)
   - Missing updated date (set to today)
   - Status casing (e.g. Active → active)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.95.2",
+  "version": "0.95.5",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.95.2",
+  "version": "0.95.5",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/src/codex-integration.mjs

@@ -4,6 +4,8 @@ import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, r
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { executableName } from './util.mjs';
 
 const SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'plugins', 'runlist-codex');
 const NAME = 'runlist-codex';
@@ -33,6 +35,26 @@ export function codexStatus({ version, homedir = os.homedir() } = {}) {
   return { ...paths, exists, foreign: exists && !installed, version: installed, stale: Boolean(installed && version && installed !== version) };
 }
 
+// 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 } = {}) {
+  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,
+    });
+    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` };
+  } catch (err) {
+    return { ok: false, reason: `cannot verify installed Codex plugin: ${err.message}` };
+  }
+}
+
 export function installCodexPlugin({ version, homedir = os.homedir(), dryRun = false } = {}) {
   const sourceVersion = JSON.parse(readFileSync(path.join(SOURCE, '.codex-plugin', 'plugin.json'), 'utf8')).version;
   if (sourceVersion !== version) throw new Error(`Codex plugin source is ${sourceVersion}, CLI is ${version}`);

package/src/commands.mjs

@@ -170,7 +170,7 @@ const definitions = [
     options: [value('--status'), value('--title'), value('--runlist'), flag('--coordination'), flag('--roadmap'), flag('--lite', '--minimal'), flag('--audit', '--findings'), value('--body', '--message'), value('--root'), flag('--show-files'), flag('--list-templates', '--list-types'), flag('--render-preview'), value('--question'), value('--answers'), value('--disposition')],
     dashPositionalsAfter: 1,
   })]),
-  command('lint', mutates('managed source sweep with --fix; otherwise read-only'), 'mutate', [form('', { options: [flag('--fix')] })]),
+  command('lint', mutates('selected managed sources with --fix; otherwise read-only'), 'mutate', [form('[files...]', { args: positionals(0, Infinity), options: [flag('--fix')] })]),
   command('rename', mutates('managed source, same-root destination, and rewrite sweep'), 'mutate', [form('<old> [new]', { args: positionals(1, 2), options: [flag('--show-files'), flag('--fix-refs'), flag('--strings')] })]),
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),

package/src/doctor.mjs

@@ -252,7 +252,7 @@ export function runDoctor(argv, config, opts = {}) {
     return;
   }
   if (argv.includes('--frontmatter-fix')) {
-    runFrontmatterFix(config, opts);
+    runFrontmatterFix(config, { ...opts, files: argv.filter(arg => !arg.startsWith('-')) });
     return;
   }
   if (argv.includes('--transactions')) {

package/src/filing-categories.mjs

@@ -0,0 +1,54 @@
+// Condense cycles before propagating outer categories through local hub indexes.
+export function resolveHubCategories(hubs, rows) {
+  const next = new Map(hubs.map(hub => [hub, new Set()]));
+  const prev = new Map(hubs.map(hub => [hub, new Set()]));
+  for (const child of hubs) for (const row of rows.get(child) ?? []) {
+    if (!next.has(row.hub)) continue;
+    next.get(row.hub).add(child);
+    prev.get(child).add(row.hub);
+  }
+  const seen = new Set(), order = [];
+  for (const hub of hubs) {
+    if (seen.has(hub)) continue;
+    seen.add(hub);
+    const stack = [[hub, next.get(hub).values()]];
+    while (stack.length) {
+      const [node, children] = stack.at(-1), child = children.next();
+      if (child.done) { order.push(node); stack.pop(); }
+      else if (!seen.has(child.value)) {
+        seen.add(child.value);
+        stack.push([child.value, next.get(child.value).values()]);
+      }
+    }
+  }
+  const component = new Map(), groups = [];
+  for (const hub of order.reverse()) {
+    if (component.has(hub)) continue;
+    const id = groups.length, stack = [hub];
+    groups.push({ categories: new Set(), fallback: new Set(), children: new Map(), incoming: 0 });
+    component.set(hub, id);
+    while (stack.length) for (const parent of prev.get(stack.pop())) {
+      if (!component.has(parent)) { component.set(parent, id); stack.push(parent); }
+    }
+  }
+  for (const child of hubs) for (const row of rows.get(child) ?? []) {
+    if (!component.has(row.hub)) continue;
+    const from = component.get(row.hub), to = component.get(child);
+    if (from === to) { if (row.category) groups[to].fallback.add(row.category); continue; }
+    if (!groups[from].children.has(to)) {
+      groups[from].children.set(to, new Set());
+      groups[to].incoming++;
+    }
+    if (row.category) groups[from].children.get(to).add(row.category);
+  }
+  const queue = groups.flatMap((group, id) => group.incoming === 0 ? [id] : []);
+  for (let i = 0; i < queue.length; i++) {
+    const group = groups[queue[i]];
+    if (!group.categories.size) for (const label of group.fallback) group.categories.add(label);
+    for (const [child, labels] of group.children) {
+      for (const label of group.categories.size ? group.categories : labels) groups[child].categories.add(label);
+      if (--groups[child].incoming === 0) queue.push(child);
+    }
+  }
+  return new Map(hubs.map(hub => [hub, groups[component.get(hub)].categories]));
+}

package/src/filing.mjs

@@ -1,3 +1,4 @@
+import { resolveHubCategories } from './filing-categories.mjs';
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter } from './frontmatter.mjs';
@@ -167,26 +168,8 @@ export function assembleFilingCoverage(docs, config, preparedRows, parentTargets
 
   // Explicit first-cell hub index rows pass categories to the hub's plan rows,
   // including indexes without status columns. Hub titles are not guessed.
-  const hubCategories = new Map();
   const liveHubs = docs.filter(doc => isHubDoc(doc) && !closed(doc, config));
-  for (const hub of liveHubs) hubCategories.set(hub.path, new Set());
-  const dependents = new Map();
-  const queue = [];
-  const addCategory = (hub, category) => {
-    const categories = hubCategories.get(hub);
-    if (categories && !categories.has(category)) { categories.add(category); queue.push([hub, category]); }
-  };
-  for (const hub of liveHubs) for (const row of categoryRows.get(hub.path) ?? []) {
-    if (row.category) addCategory(hub.path, row.category);
-    else {
-      if (!dependents.has(row.hub)) dependents.set(row.hub, new Set());
-      dependents.get(row.hub).add(hub.path);
-    }
-  }
-  for (let i = 0; i < queue.length; i++) {
-    const [hub, category] = queue[i];
-    for (const dependent of dependents.get(hub) ?? []) addCategory(dependent, category);
-  }
+  const hubCategories = resolveHubCategories(liveHubs.map(hub => hub.path), categoryRows);
   for (const rows of homes.values()) {
     // Metadata reads can finish in any order. Keep CLI/GUI evidence and home
     // pagination stable by source path and physical line, retaining duplicates.

package/src/frontmatter-fix.mjs

@@ -1,9 +1,8 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
-import { collectDocFiles } from './index.mjs';
+import { resolveRepairSources, publishRepairs } from './repair-sources.mjs';
 import { bold, green, dim } from './color.mjs';
-import { authorizeManagedSweep } from './managed-path.mjs';
 
 // Caps must stay in lockstep with the warnings emitted by validatePlanShape in
 // src/validate.mjs — that's where the user first sees these numbers. Targets
@@ -16,8 +15,8 @@ const FIELDS = [
 
 export function runFrontmatterFix(config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
-  const allFiles = collectDocFiles(config);
-  authorizeManagedSweep(allFiles, config, { kind: 'Frontmatter fix source' });
+  const allFiles = resolveRepairSources(opts.files ?? [], config);
+  const repairs = [];
   const results = [];
 
   for (const filePath of allFiles) {
@@ -52,13 +51,16 @@ export function runFrontmatterFix(config, opts = {}) {
       newBody = insertOrAppendSection(newBody, op.heading, op.tail);
     }
 
-    if (!dryRun) {
-      writeFileSync(filePath, `---\n${newFm}\n---\n${newBody}`, 'utf8');
-      try { config.hooks.onLint?.({ path: toRepoPath(filePath, config.repoRoot), fixes: ops.map(o => ({ field: o.field, type: 'frontmatter-fix' })) }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
-    }
+    repairs.push({ path: filePath, expectedContent: raw, content: `---\n${newFm}\n---\n${newBody}` });
     results.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot), ops });
   }
 
+  publishRepairs(repairs, config, opts);
+  if (!dryRun) for (const result of results) {
+    try { config.hooks.onLint?.({ path: result.repoPath, fixes: result.ops.map(op => ({ field: op.field, type: 'frontmatter-fix' })) }); }
+    catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
+  }
+
   const prefix = dryRun ? dim('[dry-run] ') : '';
   const banner = dryRun ? dim(' [preview — run without --dry-run to write]') : '';
   out.write(bold('runlist doctor --frontmatter-fix') + banner + '\n\n');

package/src/install.mjs

@@ -9,7 +9,7 @@ import {
 } from './host-integration.mjs';
 import { LEGACY_PLUGIN_ID, readInstalledPlugin, readInstalledPluginRecords } from './update.mjs';
 import { executableName, which } from './util.mjs';
-import { codexStatus, installCodexPlugin } from './codex-integration.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'));
@@ -111,9 +111,12 @@ function installCodex(argv, dryRun, json) {
     stdio: json ? 'pipe' : 'inherit', encoding: json ? 'utf8' : undefined,
     shell: process.platform === 'win32',
   });
-  if (json) process.stdout.write(JSON.stringify({ ...result, pluginAdd: added.status === 0 ? 'installed' : 'failed', pluginAddExit: added.status }, null, 2) + '\n');
-  if (added.status !== 0) {
-    process.stderr.write(`Codex plugin source is ready; finish installation with: codex plugin add ${selector}\n`);
+  const installed = added.status === 0 ? installedCodexStatus() : { ok: false, reason: added.error?.message ?? `codex plugin add exited ${added.status ?? '?'}` };
+  const verified = installed.ok && installed.version === pkg.version;
+  if (json) process.stdout.write(JSON.stringify({ ...result, pluginAdd: verified ? 'installed' : 'failed', pluginAddExit: added.status,
+    installedVersion: installed.version ?? null, ...(!verified ? { reason: installed.reason ?? `Codex has ${installed.version}, expected ${pkg.version}` } : {}) }, null, 2) + '\n');
+  if (!verified) {
+    process.stderr.write(`Codex plugin installation is unverified: ${installed.reason ?? `has ${installed.version}, expected ${pkg.version}`}. Retry: codex plugin add ${selector}\n`);
     process.exitCode = 1;
   } else if (!json) {
     process.stdout.write('Start a new Codex thread and review/trust the plugin hooks to enable the primer and guard.\n');

package/src/lint.mjs

@@ -1,12 +1,13 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
-import { buildIndex, collectDocFiles } from './index.mjs';
-import { updateFrontmatter } from './lifecycle.mjs';
+import { buildIndex } from './index.mjs';
+import { resolveRepairSources, publishRepairs } from './repair-sources.mjs';
+import { renderLifecycleMutation } from './lifecycle.mjs';
 import { runModel } from './ai.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
-import { authorizeManagedSweep, findLexicalDocsRoot } from './managed-path.mjs';
+import { findLexicalDocsRoot } from './managed-path.mjs';
 
 const KEY_RENAMES = {
   nextStep: 'next_step',
@@ -69,7 +70,8 @@ function formatYamlScalar(value) {
 export function runLint(argv, config, opts = {}) {
   const { dryRun } = opts;
   const fix = argv.includes('--fix');
-  const allFiles = collectDocFiles(config);
+  const allFiles = resolveRepairSources(argv.filter(arg => !arg.startsWith('-')), config);
+  const selectedPaths = new Set(allFiles.map(file => toRepoPath(file, config.repoRoot)));
   const fixable = [];
 
   for (const filePath of allFiles) {
@@ -164,7 +166,7 @@ export function runLint(argv, config, opts = {}) {
     }
 
     if (fixes.length > 0) {
-      fixable.push({ filePath, repoPath, fixes });
+      fixable.push({ filePath, repoPath, fixes, source: raw });
     }
   }
 
@@ -187,6 +189,7 @@ export function runLint(argv, config, opts = {}) {
       }
     }
     nonFixable = [...index.errors, ...index.warnings].filter(issue => {
+      if (!selectedPaths.has(issue.path)) return false;
       if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
       const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
       if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
@@ -235,11 +238,12 @@ export function runLint(argv, config, opts = {}) {
   }
 
   // Fix mode
-  authorizeManagedSweep(fixable.map(item => item.filePath), config, { kind: 'Lint fix source' });
+  const repairs = [];
   const prefix = dryRun ? dim('[dry-run] ') : '';
   let totalFixes = 0;
 
-  for (const { filePath, repoPath, fixes } of fixable) {
+  for (const { filePath, repoPath, fixes, source } of fixable) {
+    let raw = source;
     const updates = {};
     const keyRenames = [];
     let needsEofFix = false;
@@ -258,101 +262,94 @@ export function runLint(argv, config, opts = {}) {
         singularToPlural.push(f);
       } else if (f.type === 'drop-singular') {
         dropSingular.push(f);
-      } else {
+      } else if (f.type !== 'infer-status') {
         updates[f.field] = f.newValue;
       }
     }
 
-    if (!dryRun) {
-      // Apply infer-status fixes via AI
-      for (const f of fixes.filter(f => f.type === 'infer-status')) {
-        const raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fmInfer } = extractFrontmatter(raw);
-        const parsedInfer = parseSimpleFrontmatter(fmInfer);
-        const inferType = asString(parsedInfer.type);
-        const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
-        const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
-        const { body } = extractFrontmatter(raw);
-        const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
-        const result = runModel(prompt, { maxTokens: 10 });
-        const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
-        const inferValid = inferTypeSet ?? config.validStatuses;
-        if (suggested && inferValid.has(suggested)) {
-          updateFrontmatter(filePath, { status: suggested });
-          f.newValue = suggested;
-        }
+    // Apply infer-status fixes via AI
+    for (const f of dryRun ? [] : fixes.filter(f => f.type === 'infer-status')) {
+      const { frontmatter: fmInfer } = extractFrontmatter(raw);
+      const parsedInfer = parseSimpleFrontmatter(fmInfer);
+      const inferType = asString(parsedInfer.type);
+      const inferTypeSet = inferType ? config.typeStatuses?.get(inferType) : null;
+      const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
+      const { body } = extractFrontmatter(raw);
+      const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
+      const result = runModel(prompt, { maxTokens: 10 });
+      const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
+      const inferValid = inferTypeSet ?? config.validStatuses;
+      if (suggested && inferValid.has(suggested)) {
+        updates.status = suggested;
+        f.newValue = suggested;
       }
+    }
 
-      // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
-      // Removes the singular key block; merges its value(s) into the plural array,
-      // or creates the plural block if absent. Duplicates are skipped.
-      for (const sa of singularToPlural) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        const parsedFm = parseSimpleFrontmatter(fm);
-        const pluralValue = parsedFm[sa.pluralKey];
-        const existing = Array.isArray(pluralValue)
-          ? pluralValue.filter(value => typeof value === 'string' && value.trim())
-          : asString(pluralValue) ? [asString(pluralValue)] : [];
-        const merged = [...new Set([...sa.newValue, ...existing])];
-        const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
-        let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
-        const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
-        const pluralBlock = pluralLines.join('\n');
-        if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
-          newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
-        } else {
-          newFm = `${newFm.trim()}\n${pluralBlock}`;
-        }
-        raw = replaceFrontmatter(raw, newFm.trim());
-        writeFileSync(filePath, raw, 'utf8');
+    // Apply singular-to-plural fixes (module/surface → modules/surfaces array).
+    // Removes the singular key block; merges its value(s) into the plural array,
+    // or creates the plural block if absent. Duplicates are skipped.
+    for (const sa of singularToPlural) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      const parsedFm = parseSimpleFrontmatter(fm);
+      const pluralValue = parsedFm[sa.pluralKey];
+      const existing = Array.isArray(pluralValue)
+        ? pluralValue.filter(value => typeof value === 'string' && value.trim())
+        : asString(pluralValue) ? [asString(pluralValue)] : [];
+      const merged = [...new Set([...sa.newValue, ...existing])];
+      const comments = [...frontmatterFieldComments(fm, sa.field), ...frontmatterFieldComments(fm, sa.pluralKey)];
+      let newFm = replaceFrontmatterFieldBlock(fm, sa.field);
+      const pluralLines = [sa.pluralKey + ':', ...comments.map(comment => `  ${comment}`), ...merged.map(v => `  - ${formatYamlScalar(v)}`)];
+      const pluralBlock = pluralLines.join('\n');
+      if (Object.prototype.hasOwnProperty.call(parsedFm, sa.pluralKey)) {
+        newFm = replaceFrontmatterFieldBlock(newFm, sa.pluralKey, pluralBlock);
+      } else {
+        newFm = `${newFm.trim()}\n${pluralBlock}`;
       }
+      raw = replaceFrontmatter(raw, newFm.trim());
+    }
 
-      // Drop empty deprecated singular keys. The value is known-empty (the fix
-      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
-      // exactly — never a line carrying content — and removes it.
-      for (const ds of dropSingular) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        const comments = frontmatterFieldComments(fm, ds.field);
-        const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
-        raw = replaceFrontmatter(raw, newFm.trim());
-        writeFileSync(filePath, raw, 'utf8');
-      }
+    // Drop empty deprecated singular keys. The value is known-empty (the fix
+    // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+    // exactly — never a line carrying content — and removes it.
+    for (const ds of dropSingular) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      const comments = frontmatterFieldComments(fm, ds.field);
+      const newFm = replaceFrontmatterFieldBlock(fm, ds.field, comments.join('\n'));
+      raw = replaceFrontmatter(raw, newFm.trim());
+    }
 
-      // Apply key renames and trim fixes via raw string manipulation
-      if (keyRenames.length > 0 || trimFixes.length > 0) {
-        let raw = readFileSync(filePath, 'utf8');
-        const { frontmatter: fm } = extractFrontmatter(raw);
-        let newFm = fm;
-        for (const kr of keyRenames) {
-          const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
-          newFm = newFm.replace(regex, `${kr.newValue}:`);
-        }
-        for (const tf of trimFixes) {
-          const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
-          newFm = newFm.replace(regex, `$1${tf.newValue}`);
-        }
-        if (newFm !== fm) {
-          raw = replaceFrontmatter(raw, newFm);
-          writeFileSync(filePath, raw, 'utf8');
-        }
+    // Apply key renames and trim fixes via raw string manipulation
+    if (keyRenames.length > 0 || trimFixes.length > 0) {
+      const { frontmatter: fm } = extractFrontmatter(raw);
+      let newFm = fm;
+      for (const kr of keyRenames) {
+        const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
+        newFm = newFm.replace(regex, `${kr.newValue}:`);
       }
-
-      // Apply value updates via updateFrontmatter
-      if (Object.keys(updates).length > 0) {
-        updateFrontmatter(filePath, updates);
+      for (const tf of trimFixes) {
+        const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
+        newFm = newFm.replace(regex, `$1${tf.newValue}`);
       }
-
-      // EOF fix
-      if (needsEofFix) {
-        const current = readFileSync(filePath, 'utf8');
-        if (!current.endsWith('\n')) {
-          writeFileSync(filePath, current + '\n', 'utf8');
-        }
+      if (newFm !== fm) {
+        raw = replaceFrontmatter(raw, newFm);
       }
     }
 
+    // Apply value updates to the prepared source
+    if (Object.keys(updates).length > 0) {
+      raw = renderLifecycleMutation(raw, updates, null);
+    }
+
+    // EOF fix
+    if (needsEofFix) {
+      if (!raw.endsWith('\n')) raw += '\n';
+    }
+
+    repairs.push({ path: filePath, expectedContent: source, content: raw });
+  }
+  publishRepairs(repairs, config, opts);
+
+  for (const { repoPath, fixes } of fixable) {
     process.stdout.write(`${prefix}${green('Fixed')}: ${repoPath} (${fixes.length} issue${fixes.length > 1 ? 's' : ''})\n`);
     for (const f of fixes) {
       if (f.type === 'rename-key') {

package/src/repair-sources.mjs

@@ -0,0 +1,23 @@
+import { collectDocFiles, resolveDocArg } from './index.mjs';
+import { authorizeManagedSweep } from './managed-path.mjs';
+import { assertPlanMutationAuthorized, ownershipPathFor, availableSessionId } from './pickup.mjs';
+import { mutateFileSet } from './atomic-mutation.mjs';
+
+export function resolveRepairSources(inputs, config) {
+  const files = inputs.length ? [...new Set(inputs.map(input => resolveDocArg(input, config)))] : collectDocFiles(config);
+  authorizeManagedSweep(files, config, { kind: 'Repair source' });
+  return files;
+}
+
+export function publishRepairs(repairs, config, opts = {}) {
+  const changed = repairs.filter(item => item.content !== item.expectedContent);
+  const guards = changed.map(item => {
+    const ownership = assertPlanMutationAuthorized(item.path, config, { sessionId: availableSessionId() });
+    return ownership ? { path: ownership.recordPath, expectedContent: ownership.raw }
+      : { path: ownershipPathFor(item.path, config), absent: true };
+  });
+  if (opts.dryRun || !changed.length) return;
+  mutateFileSet({ updates: changed.map(item => ({ path: item.path,
+    expectedContent: item.expectedContent, render: () => item.content })), guards },
+  { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+}

package/src/section.mjs

@@ -154,12 +154,21 @@ const PHASE_COMPOUND_COMMENTARY = new RegExp(
   'i',
 );
 
+// Dated execution receipts describe an attempt or acceptance record, not a work phase.
+const PHASE_DATED_RECEIPT = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+` +
+  `(?:execution|completed[- ]work\\s+record|personal\\s+billing\\s+acceptance|portal\\s+attempt)` +
+  `\\s*,\\s*(?:closed\\s+)?(?:[A-Z][a-z]+\\s+\\d{1,2},\\s+\\d{4}|\\d{4}-\\d{2}-\\d{2})\\b`,
+  'i',
+);
+
 export function isPhaseHeading(section) {
   if (section.level !== 3) return false;
   if (FILES_MANIFEST_ANCESTOR.test(section.h2Ancestor ?? '')) return false;
   return PHASE_LEAD.test(section.heading)
     && !PHASE_COMMENTARY.test(section.heading)
-    && !PHASE_COMPOUND_COMMENTARY.test(section.heading);
+    && !PHASE_COMPOUND_COMMENTARY.test(section.heading)
+    && !PHASE_DATED_RECEIPT.test(section.heading);
 }
 
 // A phase's OWN checklist — the boxes directly under its heading, stopping at

package/src/update.mjs

@@ -5,8 +5,8 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { green, dim, yellow } from './color.mjs';
 import { executableName, which } from './util.mjs';
-import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, installOpencodePlugin, opencodeStatus } from './host-integration.mjs';
-import { codexStatus } from './codex-integration.mjs';
+import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, opencodeStatus } from './host-integration.mjs';
+import { codexStatus, installedCodexStatus } from './codex-integration.mjs';
 import { desktopLaunch } from './desktop.mjs';
 import { compareDesktopVersions, installedDesktopVersion } from './desktop-install.mjs';
 
@@ -203,10 +203,10 @@ export function planUpdate(opts, ctx) {
     // the moment the CLI moves on. Refresh it here — but only if it is already
     // installed. `update` keeps hosts in lockstep; it never adopts a new one,
     // which stays the job of the explicit `runlist install`.
-    if (ctx.opencode?.exists && ctx.opencode.stale) {
-      steps.push({ kind: 'opencode', path: ctx.opencode.path });
-    } else if (ctx.opencode?.foreign) {
+    if (ctx.opencode?.foreign) {
       steps.push({ kind: 'skip', reason: `${ctx.opencode.path} was not written by runlist — leaving it alone` });
+    } else if (ctx.opencode?.exists && (ctx.opencode.stale || (!opts.pluginOnly && ctx.hasNpm))) {
+      steps.push({ kind: 'opencode', cmd: ['runlist', 'install', 'opencode'] });
     }
     if (ctx.codex?.foreign) {
       steps.push({ kind: 'skip', reason: `${ctx.codex.plugin} was not written by runlist — leaving it alone` });
@@ -220,6 +220,28 @@ export function planUpdate(opts, ctx) {
   return steps;
 }
 
+export function verifyManagedHostUpdates(before, after, expectedVersion) {
+  const failures = [];
+  for (const host of ['opencode', 'codex']) {
+    if (!before[host]?.exists || before[host].foreign) continue;
+    const current = after[host];
+    if (!current?.exists || current.foreign || current.version !== expectedVersion || current.stale) {
+      failures.push(`${host} integration has ${current?.version ?? 'no managed installation'}, expected ${expectedVersion}`);
+    }
+    if (host === 'codex' && (!current?.installed?.ok || current.installed.version !== expectedVersion)) {
+      failures.push(`Codex installed plugin ${current?.installed?.reason ?? `has ${current?.installed?.version ?? 'unknown'}, expected ${expectedVersion}`}`);
+    }
+  }
+  return failures;
+}
+
+function currentCodexStatus(version) {
+  const source = codexStatus({ version });
+  if (!source.exists || source.foreign) return source;
+  const installed = which('codex') ? installedCodexStatus() : { ok: false, reason: 'codex CLI not found; installed plugin is unverified' };
+  return { ...source, installed, stale: source.stale || !installed.ok || installed.version !== version };
+}
+
 export async function runUpdate(argv, _config, opts = {}) {
   const check = argv.includes('--check');
   const cliOnly = argv.includes('--cli-only');
@@ -252,10 +274,10 @@ export async function runUpdate(argv, _config, opts = {}) {
     if (!oc.exists) process.stdout.write(dim('runlist opencode: not installed\n'));
     else if (oc.foreign) process.stdout.write(`runlist opencode: ${yellow('unmanaged file — not written by runlist')}\n`);
     else process.stdout.write(`runlist opencode: ${oc.version} ${oc.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
-    const cx = codexStatus({ version: pkg.version });
+    const cx = currentCodexStatus(pkg.version);
     if (!cx.exists) process.stdout.write(dim('runlist codex: not installed\n'));
     else if (cx.foreign) process.stdout.write(`runlist codex: ${yellow('unmanaged plugin directory')}\n`);
-    else process.stdout.write(`runlist codex: ${cx.version} ${cx.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
+    else process.stdout.write(`runlist codex: source ${cx.version}; installed ${cx.installed?.version ?? 'unverified'} ${cx.stale ? yellow('out of sync — run `runlist update`') : green('in sync')}\n`);
     if (desktop) {
       const version = await installedDesktopVersion(desktop);
       process.stdout.write(`runlist desktop: ${version} ${compareDesktopVersions(version, pkg.version) < 0 ? yellow('behind — quit Runlist and run `runlist update`') : green('in sync')}\n`);
@@ -264,13 +286,12 @@ export async function runUpdate(argv, _config, opts = {}) {
   }
 
   const opencode = opencodeStatus({ version: pkg.version });
-  const codex = codexStatus({ version: pkg.version });
+  const codex = currentCodexStatus(pkg.version);
   const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, legacyPlugin, opencode, codex, desktop, hasClaude: which('claude'), hasNpm: which('npm') });
   if (opts.dryRun) {
     for (const step of steps) {
       if (step.kind === 'skip') process.stdout.write(dim(`[dry-run] skip: ${step.reason}\n`));
       else if (step.kind === 'manual') for (const line of step.lines) process.stdout.write(dim(`[dry-run] Run from a session: ${line}\n`));
-      else if (step.kind === 'opencode') process.stdout.write(dim(`[dry-run] Would refresh: ${step.path}\n`));
       else if (step.kind === 'refusal') process.stdout.write(yellow(`[dry-run] Refused: ${step.reason}\n`));
       else process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}${step.cwd ? ` (in ${step.cwd})` : ''}\n`));
     }
@@ -304,18 +325,17 @@ export async function runUpdate(argv, _config, opts = {}) {
       process.stdout.write(dim(`skip: ${s.cmd.join(' ')} — the ${s.needs} step it depends on failed\n`));
       continue;
     }
-    if (s.kind === 'opencode') {
-      const result = installOpencodePlugin({ version: pkg.version });
-      process.stdout.write(dim(`refreshed opencode integration → ${pkg.version}  ${result.path}\n`));
-      ran = true;
-      continue;
-    }
     if (s.reason) process.stdout.write(dim(`${s.reason}\n`));
     process.stdout.write(dim(`$ ${s.cmd.join(' ')}${s.cwd ? ` (in ${s.cwd})` : ''}\n`));
-    const r = spawnSync(executableName(s.cmd[0]), s.cmd.slice(1), {
+    // npm can replace this package during the CLI step. A new Node process
+    // reads the new installers/assets; this process still holds the old modules.
+    // Use this installation's entry point, not another runlist earlier on PATH.
+    const ownCli = s.cmd[0] === 'runlist';
+    const r = spawnSync(ownCli ? process.execPath : executableName(s.cmd[0]),
+      ownCli ? [path.join(__dirname, '..', 'bin', 'runlist.mjs'), ...s.cmd.slice(1)] : s.cmd.slice(1), {
       stdio: 'inherit',
       ...(s.cwd ? { cwd: s.cwd } : {}),
-      shell: process.platform === 'win32',
+      shell: !ownCli && process.platform === 'win32',
     });
     ran = true;
     if (r.status !== 0) {
@@ -325,17 +345,27 @@ export async function runUpdate(argv, _config, opts = {}) {
       if (s.kind === 'marketplace') for (const line of claudeMarketplaceRefusalHint(plugin?.marketplace)) process.stdout.write(yellow(`${line}\n`));
     }
   }
-  if (plugin?.id === DEFAULT_PLUGIN_ID && steps.some(step => step.kind === 'plugin') && !failedKinds.has('plugin') && !failedKinds.has('marketplace')) {
+  const currentVersion = opts.expectedVersion ?? JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+  if (!cliOnly) {
+    const after = { opencode: opencodeStatus({ version: currentVersion }), codex: currentCodexStatus(currentVersion) };
+    for (const reason of verifyManagedHostUpdates({ opencode, codex }, after, currentVersion)) {
+      failures.push({ reason });
+      process.stdout.write(yellow(`${reason}\n`));
+    }
+  }
+  if (!cliOnly && plugin?.id === DEFAULT_PLUGIN_ID && !failedKinds.has('plugin') && !failedKinds.has('marketplace')) {
     // npm may have replaced this package while this process was running.
-    const currentVersion = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
-    const verified = verifyPluginScopeUpdates(plugin, readInstalledPluginRecords({ id: plugin.id }), { minimumVersion: currentVersion });
+    const verified = verifyPluginScopeUpdates(plugin, readInstalledPluginRecords({ id: plugin.id }),
+      opts.expectedVersion ? { expectedVersion: currentVersion } : { minimumVersion: currentVersion });
     if (!verified.ok) {
       failures.push({ reason: verified.reason });
       process.stdout.write(yellow(`${verified.reason}\n`));
     }
   }
+  if (!cliOnly && legacyPlugin && readInstalledPluginRecords({ id: LEGACY_PLUGIN_ID })) {
+    failures.push({ reason: `legacy Claude plugin ${LEGACY_PLUGIN_ID} remains installed; migration is incomplete` });
+  }
   if (desktop && steps.some(step => step.kind === 'desktop') && !failedKinds.has('desktop')) {
-    const currentVersion = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
     if (compareDesktopVersions(await installedDesktopVersion(desktop), currentVersion) < 0) {
       failures.push({ reason: 'The matching desktop installer is not published yet; retry `runlist update` after the product release completes.' });
     }
@@ -343,12 +373,12 @@ export async function runUpdate(argv, _config, opts = {}) {
   if (failures.length) {
     process.stdout.write(yellow(`\n${failures.length === 1 ? '1 step' : `${failures.length} steps`} failed: ${failures.map(s => s.cmd ? `${s.cmd.join(' ')}${s.cwd ? ` (in ${s.cwd})` : ''}` : s.reason).join('; ')}\n`));
     if (ran && failures.length < steps.filter(s => s.kind !== 'skip' && s.kind !== 'manual').length) {
-      process.stdout.write(dim('the other steps completed; restart your Claude Code session (or /reload-plugins) to apply them.\n'));
+      process.stdout.write(dim('the other steps completed; restart the affected host sessions to load the updated integrations.\n'));
     }
     process.exitCode = 1;
     return;
   }
   if (ran) {
-    process.stdout.write(green('\n✓ restart your Claude Code session (or /reload-plugins) to apply.\n'));
+    process.stdout.write(green('\n✓ restart the affected host sessions to load the updated integrations.\n'));
   }
 }