dotmd-cli 0.87.2 → 0.89.1

package/src/baton.mjs

@@ -1,12 +1,13 @@
-import { readFileSync, existsSync, writeFileSync, realpathSync } from 'node:fs';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath, nowIso } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
-import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, runSet } from './lifecycle.mjs';
+import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, renderLifecycleMutation, runSet } from './lifecycle.mjs';
 import { green, dim } from './color.mjs';
-import { authorizeManagedSource } from './managed-path.mjs';
+import { authorizeManagedDestination, authorizeManagedSource } from './managed-path.mjs';
+import { mutateFileSet } from './atomic-mutation.mjs';
 import { assertPlanMutationAuthorized, authoritativeSessionId, listOwnedPlans, readPlanOwnership } from './pickup.mjs';
 
 // `dotmd baton` is the one-command handoff: save the resume prompt AND release
@@ -56,7 +57,8 @@ function pendingHandoffs(promptPath, planPath, config) {
       try { planRef = asString(parseSimpleFrontmatter(extractFrontmatter(readFileSync(abs, 'utf8')).frontmatter).plan); }
       catch { continue; }
       const linked = planRef ? resolveRefPath(planRef, path.dirname(abs), config.repoRoot) : null;
-      if (linked && realpathSync(linked) === planReal) found.add(doc.path);
+      try { if (linked && realpathSync(linked) === planReal) found.add(doc.path); }
+      catch { /* stale plan link is not evidence this prompt belongs to the plan */ }
     }
   }
   return [...found];
@@ -65,7 +67,36 @@ function pendingHandoffs(promptPath, planPath, config) {
 function refusePendingHandoff(pending) {
   const lines = pending.map(p => `  ${p}`).join('\n');
   const slug = path.basename(pending[0], '.md');
-  die(`Nothing saved: a handoff for this is already pending:\n${lines}\nInspect it with \`runlist prompts show ${slug}\`. If it is current, keep it and do not hand off again. If it is stale, run \`runlist prompts archive ${pending[0]}\`, then run baton again.`);
+  die(`Nothing saved: a handoff for this is already pending:\n${lines}\nInspect it with \`runlist prompts show ${slug}\`. If it is current, keep it and do not hand off again. If it is stale, re-run baton with \`--replace\` to preserve the old handoff under archived/.`);
+}
+
+function archivedCopyPath(promptPath, config) {
+  const dir = path.join(path.dirname(promptPath), config.archiveDir);
+  const ext = path.extname(promptPath);
+  const stem = path.basename(promptPath, ext);
+  let candidate = path.join(dir, `${stem}${ext}`);
+  for (let n = 2; existsSync(candidate); n++) candidate = path.join(dir, `${stem}-${n}${ext}`);
+  return authorizeManagedDestination(candidate, config, { kind: 'Baton replacement archive' }).path;
+}
+
+function shellQuote(value) {
+  const raw = String(value);
+  return /^[A-Za-z0-9_./:@+-]+$/.test(raw) ? raw : `"${raw.replace(/["\\$`]/g, '\\$&')}"`;
+}
+
+function commitCommand(config, message, paths) {
+  const fallback = ['git', 'commit', '-m', message, '--', ...paths];
+  let argv = fallback;
+  if (typeof config.hooks.batonCommitCommand === 'function') {
+    try {
+      const custom = config.hooks.batonCommitCommand(message, [...paths]);
+      if (!Array.isArray(custom) || custom.length === 0 || !custom.every(part => typeof part === 'string' && part.length > 0)) {
+        throw new Error('return a nonempty string argv array');
+      }
+      argv = custom;
+    } catch (err) { warn(`batonCommitCommand failed (${err.message}); printing the default git command.`); }
+  }
+  return argv.map(shellQuote).join(' ');
 }
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
@@ -83,6 +114,7 @@ export async function runBaton(argv, config, opts = {}) {
   let note = null;
   let bodyFlag = null;
   let force = false;
+  let replace = false;
   const positionals = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -90,6 +122,7 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--note' && argv[i + 1]) { note = argv[++i]; continue; }
     if ((a === '--body' || a === '--message') && argv[i + 1]) { bodyFlag = argv[++i]; continue; }
     if (a === '--force') { force = true; continue; }
+    if (a === '--replace') { replace = true; continue; }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
     die(`Unknown flag for \`runlist baton\`: ${a}`);
@@ -152,16 +185,45 @@ export async function runBaton(argv, config, opts = {}) {
 
   const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
   const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
-  const refuseIfPending = () => {
+  let replacement = null;
+  const resolvePending = () => {
     const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
     const pending = pendingHandoffs(target.filePath, planPath, config);
-    if (pending.length) refusePendingHandoff(pending);
+    if (!replace) {
+      if (pending.length) refusePendingHandoff(pending);
+      return;
+    }
+    if (pending.length !== 1) {
+      const detail = pending.length ? `Found ${pending.length}:\n${pending.map(p => `  ${p}`).join('\n')}` : 'No pending handoff matches this work.';
+      die(`Nothing replaced: --replace requires exactly one pending handoff. ${detail}`);
+    }
+    const oldRepoPath = pending[0];
+    const oldPath = authorizeManagedSource(path.resolve(config.repoRoot, oldRepoPath), config, { kind: 'Baton replacement source' }).path;
+    const oldRaw = readFileSync(oldPath, 'utf8');
+    const { frontmatter, body: oldBody } = extractFrontmatter(oldRaw);
+    const fm = parseSimpleFrontmatter(frontmatter);
+    if (asString(fm.type) !== 'prompt' || asString(fm.status) !== 'pending') {
+      die(`Nothing replaced: ${oldRepoPath} is not a pending prompt.`);
+    }
+    const priorPlanRef = asString(fm.plan);
+    const priorPlanPath = priorPlanRef ? resolveRefPath(priorPlanRef, path.dirname(oldPath), config.repoRoot) : null;
+    if (!planPath && priorPlanRef) {
+      die(`Nothing replaced: ${oldRepoPath} links a plan (${priorPlanRef}). Use \`runlist baton <plan-file> @<draft-file> --replace\` so the plan link and release stay together.`);
+    }
+    replacement = {
+      oldPath, oldRepoPath, oldRaw,
+      archivedPath: archivedCopyPath(oldPath, config),
+      alreadyCurrent: oldBody.trim() === body.trim()
+        && (!planPath || (priorPlanPath && path.resolve(priorPlanPath) === path.resolve(planPath))),
+      canonicalPath: target.filePath,
+    };
   };
 
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
   let planGuard = null;
+  let wouldReleaseClaim = false;
   if (planPath) {
     planPath = authorizeManagedSource(planPath, config, { kind: 'Baton plan source' }).path;
     repoPath = toRepoPath(planPath, config.repoRoot);
@@ -187,6 +249,7 @@ export async function runBaton(argv, config, opts = {}) {
     const sessionId = authoritativeSessionId();
     const ownership = assertPlanMutationAuthorized(repoPath, config, { sessionId, force });
     const ownedHere = ownership?.state === 'owned' && ownership.sessionId === sessionId;
+    wouldReleaseClaim = ownership?.state === 'owned';
     // Baton's release only means something when there is a claim to release. A
     // plan that is neither in-session nor owned here carries a status someone
     // chose on purpose (`awaiting`, `blocked`, a repo's own `awaiting-testing`),
@@ -208,16 +271,36 @@ export async function runBaton(argv, config, opts = {}) {
       if (note) warn('--note ignored — the plan\'s status is unchanged, so there is no transition to record.');
     }
     // Before the plan-completion step: a refusal must leave nothing changed.
-    refuseIfPending();
+    resolvePending();
+    // A status transition may file the plan at a new path. Refreshing the
+    // prompt inside that transaction keeps its plan link valid even when its
+    // body text happened to be identical to the previous handoff.
+    if (replacement && status !== oldStatus) replacement.alreadyCurrent = false;
     ownershipPath = readPlanOwnership(repoPath, config)?.recordPath ?? null;
     if (!dryRun) ensurePlanCompletionBeforeRelease(repoPath, config, { testHooks: opts.testHooks });
     else if (planHasPendingCompletion(repoPath, config)) process.stderr.write(`${dim('[dry-run]')} Pending claim completion would block this release.\n`);
   } else {
-    refuseIfPending();
+    resolvePending();
     if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
 
+  const preparedReplacement = prepared => {
+    if (!replacement || replacement.alreadyCurrent) return { updates: [], creations: [], guards: [] };
+    let archivedContent = renderLifecycleMutation(replacement.oldRaw,
+      { status: 'archived', updated: nowIso() }, () => 'Archived.');
+    if (repoPath) archivedContent = archivedContent.replace(/^plan:[ \t]*\S.*$/m, `plan: ${repoPath}`);
+    return {
+      updates: [{ path: replacement.oldPath, expectedContent: replacement.oldRaw, content: prepared.content }],
+      creations: [{ path: replacement.archivedPath, content: archivedContent }],
+      guards: path.resolve(replacement.canonicalPath) === path.resolve(replacement.oldPath)
+        ? [] : [{ path: replacement.canonicalPath, absent: true }],
+    };
+  };
+  if (dryRun && !json && replacement && !replacement.alreadyCurrent) {
+    process.stdout.write(`${dim('[dry-run]')} Would preserve old handoff: ${replacement.oldRepoPath} → ${toRepoPath(replacement.archivedPath, config.repoRoot)}\n`);
+  }
+
   // Plan mode publishes the already-stamped prompt, status/history update, and
   // ownership release in one transaction. Slug mode has no plan transaction.
   let createdSlug = null;
@@ -230,29 +313,39 @@ export async function runBaton(argv, config, opts = {}) {
   if (json) process.stdout.write = chunk => { muted.push(String(chunk)); return true; };
   try {
   if (!planPath) {
-    const prepared = preparePromptDocument(slugBase, body, config, { dryRun });
-    try {
-      newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
-    } catch (err) {
-      // Lost a race with another baton between the pending check and the write.
-      if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
-      throw err;
+    const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
+    const prepared = preparePromptDocument(promptName, body, config, { dryRun });
+    if (replacement) {
+      const mutation = preparedReplacement(prepared);
+      if (!dryRun && !replacement.alreadyCurrent) mutateFileSet(mutation, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+      newResult = { sessionFiles: [replacement.oldRepoPath, ...(replacement.alreadyCurrent ? [] : [toRepoPath(replacement.archivedPath, config.repoRoot)])] };
+    } else {
+      try {
+        newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
+      } catch (err) {
+        // Lost a race with another baton between the pending check and the write.
+        if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+        throw err;
+      }
     }
-    createdSlug = slugBase;
-    promptRepoPath = prepared.repoPath;
+    createdSlug = promptName;
+    promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
   } else {
-    const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
+    const promptName = replacement ? path.basename(replacement.oldPath, '.md') : slugBase;
+    const prepared = preparePromptDocument(promptName, body, config, { plan: repoPath, dryRun });
+    const mutation = preparedReplacement(prepared);
     const setArgs = [status, planPath];
     if (force) setArgs.push('--force');
     if (note && !planGuard) setArgs.push('--note', note);
     try {
-      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
+      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would ${replacement ? (replacement.alreadyCurrent ? 'keep' : 'replace') : 'create'}: ${replacement?.oldRepoPath ?? prepared.repoPath}\n`);
       archiveResult = await runSet(setArgs, config, {
         dryRun,
         viaBaton: true,
         testHooks: opts.testHooks,
-        creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
-        guards: planGuard && !dryRun ? [planGuard] : [],
+        additionalUpdates: dryRun ? [] : mutation.updates,
+        creations: dryRun ? [] : replacement ? mutation.creations : [{ path: prepared.filePath, content: prepared.content }],
+        guards: dryRun ? [] : [...mutation.guards, ...(planGuard ? [planGuard] : [])],
         deferIndex: true,
       });
     } catch (err) {
@@ -260,9 +353,9 @@ export async function runBaton(argv, config, opts = {}) {
       throw err;
     }
     createdSlug = prepared.slug;
-    promptRepoPath = prepared.repoPath;
+    promptRepoPath = replacement?.oldRepoPath ?? prepared.repoPath;
     statusChanged = oldStatus !== status;
-    if (!dryRun) {
+    if (!dryRun && !replacement) {
       try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
       catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
     }
@@ -271,24 +364,12 @@ export async function runBaton(argv, config, opts = {}) {
     if (json) process.stdout.write = originalStdoutWrite;
   }
 
-  // A release status can FILE the plan into a bucket (`lifecycle.filedStatuses`,
-  // e.g. paused → docs/plans/held/). The prompt is created inside the same
-  // transaction as that move, so its `plan:` link necessarily holds the
-  // pre-move path and is stale the instant it lands. The move's own reference
-  // rewrite does not cover it: `plan` is deliberately not a `referenceFields`
-  // entry, so nothing validates or repoints it. Retarget it here.
-  if (!dryRun && promptRepoPath && archiveResult?.newRepoPath && archiveResult.newRepoPath !== repoPath) {
-    const promptPath = path.join(config.repoRoot, promptRepoPath);
-    try {
-      const { frontmatter, body } = extractFrontmatter(readFileSync(promptPath, 'utf8'));
-      // Rewritten in place rather than through replaceFrontmatterField, which
-      // always emits a folded block scalar — right for prose fields, wrong for
-      // a path every other prompt carries on one line. Baton wrote this line
-      // itself moments ago, so the single-line form is guaranteed.
-      const rewritten = frontmatter.replace(/^plan:[ \t]*\S.*$/m, `plan: ${archiveResult.newRepoPath}`);
-      if (rewritten !== frontmatter) writeFileSync(promptPath, `---\n${rewritten}\n---\n${body}`, 'utf8');
-    }
-    catch (err) { warn(`Saved the prompt, but could not repoint its plan link to ${archiveResult.newRepoPath}: ${err.message}`); }
+  if (!dryRun && replacement && !replacement.alreadyCurrent) {
+    const archivedRepoPath = toRepoPath(replacement.archivedPath, config.repoRoot);
+    try { config.hooks.onArchive?.({ path: archivedRepoPath, oldStatus: 'pending' }, { oldPath: replacement.oldRepoPath, newPath: archivedRepoPath }); }
+    catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
+    try { config.hooks.onNew?.({ path: replacement.oldRepoPath, status: 'pending', title: createdSlug, type: 'prompt' }); }
+    catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
   }
 
   const normalizeRepoPath = candidate => {
@@ -297,13 +378,14 @@ export async function runBaton(argv, config, opts = {}) {
   };
   const touched = (archiveResult?.touched ?? (planPath && statusChanged ? [repoPath] : [])).map(normalizeRepoPath);
   const ownershipRepoPath = normalizeRepoPath(ownershipPath);
-  const repositoryFiles = [...new Set(touched.filter(candidate => candidate && candidate !== ownershipRepoPath && candidate !== promptRepoPath && candidate !== normalizeRepoPath(config.indexPath)))];
-  const sessionFiles = [...new Set([...(newResult?.sessionFiles ?? []), promptRepoPath, ownershipRepoPath].filter(Boolean))];
+  const archivedPromptRepoPath = replacement && !replacement.alreadyCurrent ? toRepoPath(replacement.archivedPath, config.repoRoot) : null;
+  const repositoryFiles = [...new Set(touched.filter(candidate => candidate && candidate !== ownershipRepoPath && candidate !== promptRepoPath && candidate !== archivedPromptRepoPath && candidate !== normalizeRepoPath(config.indexPath)))];
+  const sessionFiles = [...new Set([...(newResult?.sessionFiles ?? []), promptRepoPath, archivedPromptRepoPath, ownershipRepoPath].filter(Boolean))];
   const deferredGeneratedFiles = [...new Set(newResult?.deferredGeneratedFiles ?? (config.indexPath ? [normalizeRepoPath(config.indexPath)] : []))];
   const operationResult = {
     operation: 'baton',
     dryRun: Boolean(dryRun),
-    disposition: dryRun ? 'would-change' : 'applied',
+    disposition: replacement?.alreadyCurrent && !statusChanged && !wouldReleaseClaim ? 'already-current' : dryRun ? 'would-change' : 'applied',
     wouldChange: Boolean(dryRun),
     mode: planPath ? 'plan' : 'slug',
     status: planPath ? { from: oldStatus, to: status, changed: statusChanged } : null,
@@ -313,6 +395,14 @@ export async function runBaton(argv, config, opts = {}) {
     deferredGeneratedFiles,
     prompt: promptRepoPath,
     plan: archiveResult?.newRepoPath ?? repoPath,
+    planMovement: planPath ? { from: repoPath, to: archiveResult?.newRepoPath ?? repoPath } : null,
+    replacement: replacement ? {
+      previousPrompt: replacement.oldRepoPath,
+      archivedPrompt: archivedPromptRepoPath,
+      pendingPrompt: promptRepoPath,
+      alreadyCurrent: replacement.alreadyCurrent,
+    } : null,
+    claimRelease: planPath ? { wouldRelease: wouldReleaseClaim, released: !dryRun && wouldReleaseClaim } : null,
   };
 
   const prefix = dryRun ? dim('[dry-run] ') : '';
@@ -320,13 +410,14 @@ export async function runBaton(argv, config, opts = {}) {
     process.stdout.write(JSON.stringify(operationResult, null, 2) + '\n');
     return operationResult;
   }
-  process.stderr.write(`\n${prefix}${green('✓ Baton passed')}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  const verdict = replacement?.alreadyCurrent ? '✓ Handoff kept' : replacement ? '✓ Baton replaced' : '✓ Baton passed';
+  process.stderr.write(`\n${prefix}${green(verdict)}: ${createdSlug} (the next session's hud surfaces it — nothing to paste into chat)\n`);
+  if (archivedPromptRepoPath) process.stderr.write(dim(`${prefix}Previous handoff preserved: ${archivedPromptRepoPath}\n`));
   if (planGuard) {
     process.stderr.write(dim(`${repoPath} left at \`${oldStatus}\` — it was not in-session, so there was no claim to release.\n`));
     process.stderr.write(dim(`Meant to change it? runlist set <status> ${repoPath}\n`));
   }
   if (statusChanged) {
-    const pathspec = operationResult.repositoryFiles.join(' ');
     let gitignored = false;
     try {
       const { isGitIgnored } = await import('./git.mjs');
@@ -336,7 +427,7 @@ export async function runBaton(argv, config, opts = {}) {
       process.stderr.write(dim(`${repoPath} is gitignored — no commit needed.\n`));
     } else {
       process.stderr.write(`${prefix}Commit the repository files (session files stay OUT of the pathspec):\n`);
-      process.stderr.write(`${prefix}  git commit -m "baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}" -- ${pathspec}\n`);
+      process.stderr.write(`${prefix}  ${commitCommand(config, `baton: ${path.basename(planPath, '.md')} ${oldStatus} → ${status}`, operationResult.repositoryFiles)}\n`);
     }
   }
   if (operationResult.deferredGeneratedFiles.length) process.stderr.write(dim(`Generated index deferred: ${operationResult.deferredGeneratedFiles.join(', ')}\n`));

package/src/codex-integration.mjs

@@ -0,0 +1,81 @@
+// 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 os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SOURCE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'plugins', 'runlist-codex');
+const NAME = 'runlist-codex';
+const MARKER = '.runlist-generated.json';
+
+export function codexPaths(homedir = os.homedir()) {
+  const root = path.join(homedir, '.agents', 'plugins');
+  // The implicit personal marketplace file lives under ~/.agents/plugins,
+  // but Codex resolves its `./plugins/...` sources relative to the home dir.
+  return { root, marketplace: path.join(root, 'marketplace.json'), plugin: path.join(homedir, 'plugins', NAME) };
+}
+
+function marketplaceAt(file) {
+  if (!existsSync(file)) return { name: 'personal', interface: { displayName: 'Personal' }, plugins: [] };
+  const data = JSON.parse(readFileSync(file, 'utf8'));
+  if (!data || typeof data.name !== 'string' || !Array.isArray(data.plugins)) {
+    throw new Error(`${file} is not a valid personal marketplace`);
+  }
+  return data;
+}
+
+export function codexStatus({ version, homedir = os.homedir() } = {}) {
+  const paths = codexPaths(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) };
+}
+
+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}`);
+  const status = codexStatus({ version, homedir });
+  if (status.foreign) return { ...status, action: 'refused', reason: 'plugin directory exists without a runlist marker' };
+  let market;
+  try { market = marketplaceAt(status.marketplace); }
+  catch (err) { return { ...status, action: 'refused', reason: err.message }; }
+  const expected = `./plugins/${NAME}`;
+  const entry = market.plugins.find(p => p.name === NAME);
+  if (entry && (entry.source?.source !== 'local' || entry.source?.path !== expected)) {
+    return { ...status, action: 'refused', reason: 'marketplace entry points to a different plugin source' };
+  }
+  if (!entry) market.plugins.push({
+    name: NAME, source: { source: 'local', path: expected },
+    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, category: 'Productivity',
+  });
+  if (status.exists && !status.stale && entry) return { ...status, action: 'current', marketplaceName: market.name };
+  if (dryRun) return { ...status, action: status.exists ? 'updated' : 'installed', marketplaceName: market.name, dryRun: true };
+
+  const parent = path.dirname(status.plugin);
+  mkdirSync(parent, { recursive: true });
+  mkdirSync(path.dirname(status.marketplace), { recursive: true });
+  const stage = mkdtempSync(path.join(parent, '.runlist-codex-stage-'));
+  const backup = `${stage}-previous`;
+  const marketStage = `${status.marketplace}.runlist-stage-${process.pid}`;
+  let movedOld = false;
+  let published = false;
+  try {
+    cpSync(SOURCE, stage, { recursive: true });
+    writeFileSync(path.join(stage, MARKER), JSON.stringify({ version }) + '\n');
+    writeFileSync(marketStage, JSON.stringify(market, null, 2) + '\n');
+    if (status.exists) { renameSync(status.plugin, backup); movedOld = true; }
+    renameSync(stage, status.plugin);
+    published = true;
+    renameSync(marketStage, status.marketplace);
+    if (movedOld) rmSync(backup, { recursive: true, force: true });
+  } catch (err) {
+    if (published) rmSync(status.plugin, { recursive: true, force: true });
+    if (movedOld) renameSync(backup, status.plugin);
+    rmSync(stage, { recursive: true, force: true });
+    rmSync(marketStage, { force: true });
+    throw err;
+  }
+  return { ...codexStatus({ version, homedir }), action: status.exists ? 'updated' : 'installed', marketplaceName: market.name };
+}

package/src/commands.mjs

@@ -123,7 +123,7 @@ 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'), flag('--force'), 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'), flag('--force'), flag('--replace'), 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')] }),

package/src/config.mjs

@@ -147,9 +147,9 @@ const DEFAULTS = {
   // and users who want usage observability flip this on (or set RUNLIST_JOURNAL=1).
   journal: false,
 
-  // PreToolUse guard behavior. `deny: false` drops the status-edit rules from
-  // deny (block the tool call) back to warn-only teaching context.
-  guard: { deny: true },
+  // PreToolUse guard behavior. `deny: false` drops status edits to warnings;
+  // `promptReads: 'deny'` blocks direct reads of existing pending prompts.
+  guard: { deny: true, promptReads: 'warn' },
 
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
@@ -667,8 +667,8 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     moduleRequiredStatuses,
 
     indexPath,
-    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:dotmd:start -->',
-    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:dotmd:end -->',
+    indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:runlist:start -->',
+    indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:runlist:end -->',
     indexSnapshot: config.index?.snapshot ?? 'status',
     archivedHighlightLimit: config.index?.archivedLimit ?? 8,
 
@@ -678,7 +678,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     presets: config.presets,
     configuredPresetNames: new Set(Object.keys(userConfig.presets ?? {})),
     journal: config.journal === true,
-    guard: { deny: config.guard?.deny !== false },
+    guard: {
+      deny: config.guard?.deny !== false,
+      promptReads: config.guard?.promptReads === 'deny' ? 'deny' : 'warn',
+    },
     hooks,
     configWarnings,
   };

package/src/export.mjs

@@ -99,7 +99,7 @@ export function runExport(argv, config, opts = {}) {
       }
     }
   } else if (format === 'html') {
-    const outDir = output ?? 'dotmd-export';
+    const outDir = output ?? (existsSync('dotmd-export') ? 'dotmd-export' : 'runlist-export');
     const identities = allocateOutputIdentities(index.docs);
     exportHtml(docsWithBody, config, outDir, identities, { dryRun });
     if (dryRun) {

package/src/guard.mjs

@@ -1,7 +1,8 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inspectGitCommandPaths } from './git.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { recordGuardEvent } from './journal.mjs';
 import { readEnv } from './naming.mjs';
 
@@ -241,7 +242,26 @@ const STREAM_EDITOR_INPLACE = [
   /\bg?awk\b[^|;&<>]*\binplace\b/,
 ];
 
-function evalBash(command, config, inspectGitPaths, baseCwd) {
+function promptReadDecision(filePath, config, deps = {}) {
+  if (config?.guard?.promptReads !== 'deny') return 'warn';
+  if (!isManagedDoc(filePath, config)) return 'warn';
+  const readFile = deps.readFile ?? ((p) => readFileSync(p, 'utf8'));
+  try {
+    const absolute = path.resolve(deps.gitCwd ?? process.cwd(), filePath);
+    const real = p => { try { return realpathSync(p); } catch { return p; } };
+    const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : ['docs']);
+    const insideRoot = roots.some(root => {
+      const base = real(path.resolve(config.repoRoot ?? process.cwd(), root));
+      const relative = path.relative(base, real(absolute));
+      return relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    });
+    if (!insideRoot) return 'warn';
+    const fm = parseSimpleFrontmatter(extractFrontmatter(readFile(absolute)).frontmatter);
+    return fm.type === 'prompt' && fm.status === 'pending' ? 'deny' : 'warn';
+  } catch { return 'warn'; }
+}
+
+function evalBash(command, config, inspectGitPaths, baseCwd, deps = {}) {
   const segments = shellSegments(command);
   let cwd = baseCwd;
 
@@ -279,7 +299,7 @@ function evalBash(command, config, inspectGitPaths, baseCwd) {
     // Rule B — reading a prompt through the shell instead of consuming it.
     if (SHELL_READERS.has(cmd0) && promptTokens.length) {
       return {
-        decision: 'warn',
+        decision: promptReadDecision(promptTokens[0], config, { ...deps, gitCwd: cwd }),
         rule: 'cat-prompt',
         detail: `${cmd0} ${promptTokens.join(' ')}`,
         reason:
@@ -301,10 +321,10 @@ function evalBash(command, config, inspectGitPaths, baseCwd) {
   return null;
 }
 
-function evalRead(filePath, config) {
+function evalRead(filePath, config, deps = {}) {
   if (!isPromptPath(filePath, config)) return null;
   return {
-    decision: 'warn',
+    decision: promptReadDecision(filePath, config, deps),
     rule: 'read-prompt',
     detail: filePath,
     reason:
@@ -314,6 +334,31 @@ function evalRead(filePath, config) {
   };
 }
 
+// Codex and OpenCode expose patch edits as one string. Only +/- hunk lines
+// count: context mentioning status is an anchor, not an edit. New files are
+// creation, and status on a deleted file is not a hand-edited transition.
+function evalPatch(command, config) {
+  if (typeof command !== 'string') return null;
+  let target = null;
+  let removed = [];
+  let added = [];
+  const changed = () => target && statusLines(removed.join('\n')).join('\n') !== statusLines(added.join('\n')).join('\n');
+  for (const line of command.split('\n')) {
+    const update = line.match(/^\*\*\* Update File: (.+)$/);
+    if (update || /^\*\*\* (?:Add|Delete) File: /.test(line) || line === '*** End Patch') {
+      if (changed()) return editStatusResult(target, config, target);
+      target = update && isManagedDoc(update[1], config) ? update[1] : null;
+      removed = [];
+      added = [];
+      continue;
+    }
+    if (!target || line.startsWith('***')) continue;
+    if (line.startsWith('+')) added.push(line.slice(1));
+    else if (line.startsWith('-')) removed.push(line.slice(1));
+  }
+  return changed() ? editStatusResult(target, config, target) : null;
+}
+
 // Every `status:` line in a snippet, normalized for comparison.
 function statusLines(s) {
   if (typeof s !== 'string') return [];
@@ -359,8 +404,16 @@ export function evaluateGuard(payload, config, deps = {}) {
   const inspectGitPaths = deps.inspectGitPaths
     || ((subcommand, args, cwd) => inspectGitCommandPaths(subcommand, args, cwd ?? deps.gitCwd ?? process.cwd()));
 
-  if (tool === 'Bash') return evalBash(input.command || '', config, inspectGitPaths, deps.gitCwd ?? process.cwd());
-  if (tool === 'Read') return evalRead(input.file_path || '', config);
+  if (tool === 'Bash') return evalBash(input.command || input.cmd || '', config, inspectGitPaths, input.workdir ?? deps.gitCwd ?? process.cwd(), deps);
+  if (tool === 'Read') return evalRead(input.file_path || '', config, deps);
+  if (tool === 'apply_patch') return evalPatch(input.command || input.patchText || '', config);
+  if (/^mcp__.*__(?:read_file|read_text_file|read_media_file|read_multiple_files)$/.test(tool ?? '')) {
+    const paths = Array.isArray(input.paths) ? input.paths : [input.path ?? input.file_path];
+    for (const p of paths) {
+      const result = evalRead(p, config, deps);
+      if (result) return result;
+    }
+  }
   if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config, deps);
   return null;
 }

package/src/hub-membership.mjs

@@ -273,7 +273,7 @@ export function checkHubMembershipDrift(docs, config) {
     warnings.push({
       path: child.path,
       level: 'warning',
-      message: `is ranked in the body order of \`${hub.path}\` (the list \`runlist runlist next\` walks) but has no \`parent_plan:\`. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
+      message: `is ranked in the body order of \`${hub.path}\` (used by \`runlist runlist next\`) but has no \`parent_plan:\`. Add \`parent_plan: ${hub.path}\` so reverse-link tooling (pickup-card Related:, graph) stays consistent.`,
       meta: { kind: BACKREF_KIND, hub: hub.path, source: 'body-order' },
     });
   }

package/src/index-file.mjs

@@ -5,15 +5,29 @@ import { formatSnapshot } from './render.mjs';
 import { authorizeRepoGeneratedPath } from './managed-path.mjs';
 import { mutateFile } from './atomic-mutation.mjs';
 
+function indexMarkers(current, config) {
+  const start = config.indexStartMarker;
+  const end = config.indexEndMarker;
+  if (current.includes(start) && current.includes(end)) return { start, end };
+  // A config that omitted markers may point at an index from an older release.
+  // Keep updating that block in place; newly initialized indexes use runlist.
+  if (start === '<!-- GENERATED:runlist:start -->' && end === '<!-- GENERATED:runlist:end -->'
+    && current.includes('<!-- GENERATED:dotmd:start -->') && current.includes('<!-- GENERATED:dotmd:end -->')) {
+    return { start: '<!-- GENERATED:dotmd:start -->', end: '<!-- GENERATED:dotmd:end -->' };
+  }
+  return { start, end };
+}
+
 export function renderIndexFile(index, config, current = readFileSync(config.indexPath, 'utf8')) {
-  const start = current.indexOf(config.indexStartMarker);
-  const end = current.indexOf(config.indexEndMarker);
+  const markers = indexMarkers(current, config);
+  const start = current.indexOf(markers.start);
+  const end = current.indexOf(markers.end);
 
   if (start === -1 || end === -1 || end < start) {
     throw new Error(`${config.indexPath} is missing generated block markers.`);
   }
 
-  const before = current.slice(0, start + config.indexStartMarker.length);
+  const before = current.slice(0, start + markers.start.length);
   const after = current.slice(end);
   const generated = `\n\n${renderGeneratedBlock(index, config)}\n`;
   return `${before}${generated}${after}`;
@@ -130,8 +144,9 @@ export function checkIndex(docs, config, opts = {}) {
   }
 
   const current = readFileSync(config.indexPath, 'utf8');
-  const start = current.indexOf(config.indexStartMarker);
-  const end = current.indexOf(config.indexEndMarker);
+  const markers = indexMarkers(current, config);
+  const start = current.indexOf(markers.start);
+  const end = current.indexOf(markers.end);
 
   if (start === -1 || end === -1 || end < start) {
     errors.push({ path: config.indexPath, level: 'error', message: 'Missing generated index block markers.' });