dotmd-cli 0.77.2 → 0.78.0

package/README.md

@@ -125,8 +125,15 @@ operation:
 dotmd baton @/tmp/resume.md
 ```
 
+Baton refuses when a handoff for the same work is already pending, so one piece
+of work never has two resume prompts.
+
 Saved prompts are local session state. Consume them with `dotmd use`; inspect
-without consuming via `dotmd prompts show`.
+without consuming via `dotmd prompts show`. Consuming a baton prompt also claims
+its plan; `dotmd use --no-claim` reads and archives it without starting the plan.
+
+New plans are created `planned`; `dotmd use` starts one, and
+`dotmd new plan <name> --status <status>` sets a different starting status.
 
 ## Document Format
 

package/assets/opencode/plugin.js

@@ -32,7 +32,9 @@ function cliExecutables() {
   return process.platform === 'win32' ? ['runlist.cmd', 'dotmd.cmd'] : ['runlist', 'dotmd'];
 }
 
-function runHud(directory) {
+// Runs the CLI and resolves its trimmed stdout, or '' on any failure. `input`,
+// when given, is written to the child's stdin.
+function runCli(directory, args, input = null) {
   return new Promise(resolve => {
     let settled = false;
     const done = value => { if (!settled) { settled = true; resolve(value); } };
@@ -40,7 +42,7 @@ function runHud(directory) {
     const attempt = index => {
       if (index >= candidates.length) { done(''); return; }
       try {
-        execFile(candidates[index], ['hud'], {
+        const child = execFile(candidates[index], args, {
           cwd: directory,
           timeout: PRIMER_TIMEOUT_MS,
           windowsHide: true,
@@ -49,12 +51,33 @@ function runHud(directory) {
           if (error?.code === 'ENOENT') attempt(index + 1);
           else done(error ? '' : (stdout ?? '').trim());
         });
+        child.stdin?.on('error', () => {});
+        if (input !== null) child.stdin?.end(input);
+        else child.stdin?.end();
       } catch { attempt(index + 1); }
     };
     attempt(0);
   });
 }
 
+// OpenCode runs no Claude Code hooks, so `dotmd guard` never sees its tool
+// calls, and sessions opened pending prompts with the read tool, which prints a
+// prompt without archiving it. The guard's answer for a prompt read is a
+// warning, not a block, so it is applied after the call: the teaching text is
+// appended to what the agent sees. Only calls that name a prompt file reach
+// the CLI; everything else costs a regex.
+const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
+
+function guardPayload(tool, args) {
+  if (tool === 'read' && typeof args?.filePath === 'string' && PROMPT_FILE.test(args.filePath)) {
+    return { tool_name: 'Read', tool_input: { file_path: args.filePath } };
+  }
+  if (tool === 'bash' && typeof args?.command === 'string' && PROMPT_FILE.test(args.command)) {
+    return { tool_name: 'Bash', tool_input: { command: args.command } };
+  }
+  return null;
+}
+
 export default async function dotmdOpencodePlugin({ directory }) {
   // Keyed by session so a subagent session primes independently, the way
   // SubagentStart does under Claude Code.
@@ -68,7 +91,7 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // only the first request — and a never-refreshed one would keep announcing
     // a pending prompt this session already consumed.
     if (cached && Date.now() - cached.at < PRIMER_TTL_MS) return cached.text;
-    const text = await runHud(directory);
+    const text = await runCli(directory, ['hud']);
     primers.set(key, { text, at: Date.now() });
     return text;
   }
@@ -93,6 +116,19 @@ export default async function dotmdOpencodePlugin({ directory }) {
       } catch { /* never break a shell over this */ }
     },
 
+    // The guard's warnings, appended after the call ran. A `deny` from the
+    // guard is ignored here: the call has already happened, so there is
+    // nothing left to refuse.
+    'tool.execute.after': async (input, output) => {
+      try {
+        const payload = guardPayload(input?.tool, input?.args);
+        if (!payload || typeof output?.output !== 'string') return;
+        const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+        const note = raw ? JSON.parse(raw)?.hookSpecificOutput?.additionalContext : null;
+        if (typeof note === 'string' && note) output.output += `\n\n${note}`;
+      } catch { /* a guard failure never touches the tool result */ }
+    },
+
     // Session priming — the equivalent of the SessionStart hook that runs
     // `dotmd hud` under Claude Code. Silent outside a dotmd repo (hud prints
     // nothing and exits 0), so this is inert in unrelated projects.

package/bin/dotmd.mjs

@@ -160,6 +160,12 @@ host gets that a different way:
             with "plugin not installed"), and the README's slash commands only
             work from inside a session. Without the \`claude\` CLI on PATH the
             two in-session commands are printed instead.
+            It also repairs a plugin Claude lists as "failed to load: Marketplace
+            dotmd not found" — an install record whose marketplace registration
+            is gone — by re-adding the marketplace and updating the plugin. If
+            Claude refuses the marketplace, ~/.claude/settings.json declares it
+            under extraKnownMarketplaces with a source that no longer matches;
+            dotmd names the field but never edits that file.
 
   opencode  Writes one auto-discovered plugin file. OpenCode has no plugin
             registry but globs \`{plugin,plugins}/*.{ts,js}\` under its global
@@ -190,7 +196,11 @@ reports a missing integration but never installs one.`,
 The plugin and CLI ship in lockstep; a release bumps both. Updating the plugin
 requires a session restart (or /reload-plugins) to apply. The plugin step needs
 the \`claude\` CLI on PATH — otherwise it prints the \`/plugin update\` command to
-run from a session instead.`,
+run from a session instead. The OpenCode file is refreshed in the same run when
+it is present and behind. The hosts are independent, so a failing step does not
+stop the others: every step runs, the failures are listed together, and the
+exit code is 1. A plugin whose marketplace registration is gone gets the
+marketplace re-added before the update (see \`dotmd install claude\`).`,
 
   misuse: `dotmd misuse — read the cross-repo guard log (~/.claude/logs/dotmd-misuse.log)
 
@@ -1140,6 +1150,10 @@ Subcommands:
 slug matching a prompt basename, or a unique substring of a prompt
 path. Ambiguous substrings error with the candidate list.
 
+A prompt saved by \`dotmd baton\` links its plan; consuming it (\`use\`,
+\`next\`, or top-level \`dotmd use\`) also claims that plan for this session.
+Pass \`--no-claim\` to read and archive the prompt without starting the plan.
+
 Default prompt statuses: pending, archived.
 
 Examples:

package/package.json

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

package/src/baton.mjs

@@ -1,7 +1,7 @@
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, runSet } from './lifecycle.mjs';
@@ -26,11 +26,42 @@ export function findOwnedPlan(config, index = null) {
   return { plan: clean && owned.length === 1 ? owned[0] : null, via: clean && owned.length === 1 ? 'ownership' : null, inSession, owned, diagnostics: records.diagnostics ?? [] };
 }
 
-const BODY_USAGE = `dotmd baton needs the resume draft as its body. Write 10–20 lines first — the next concrete decision plus any gotchas, NOT a recap of the plan — then:
-  dotmd baton @/tmp/draft.md             # body from file (preferred)
-  cat /tmp/draft.md | dotmd baton        # body from stdin
-  dotmd baton --message "..."            # one-liner
-No plan in-session? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`;
+// One line that says what is missing, then one example. Baton never drafts the
+// resume itself: the session that did the work is the only one that knows the
+// next decision, and a prompt assembled from frontmatter reads like a handoff
+// while carrying nothing the plan doesn't already say.
+const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
+  dotmd baton [<plan-or-slug>] @/tmp/draft.md`;
+
+// A handoff that lands beside a pending one leaves two prompts for the same
+// work, and the next session picks whichever sorts first. Baton used to step to
+// `resume-<x>-2` silently; it now refuses and names what is waiting, so the
+// older prompt is consumed or archived on purpose. Plan mode also catches a
+// pending prompt under a different name that links the same plan.
+function pendingHandoffs(promptPath, planPath, config) {
+  const found = new Set();
+  if (existsSync(promptPath)) found.add(toRepoPath(promptPath, config.repoRoot));
+  if (planPath) {
+    const planReal = realpathSync(planPath);
+    const index = buildIndex(config, { fast: true, invokeHooks: false });
+    for (const doc of index.docs) {
+      if (doc.type !== 'prompt' || doc.status === 'archived' || isArchivedPath(doc.path, config)) continue;
+      const abs = path.resolve(config.repoRoot, doc.path);
+      let planRef;
+      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);
+    }
+  }
+  return [...found];
+}
+
+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}\nUse it (\`dotmd use ${slug}\`) or archive it (\`dotmd prompts archive ${pending[0]}\`), then run baton again.`);
+}
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
 // bare word (may be a plan slug, may be a brand-new handoff name)?
@@ -114,6 +145,14 @@ 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 = () => {
+    const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
+    const pending = pendingHandoffs(target.filePath, planPath, config);
+    if (pending.length) refusePendingHandoff(pending);
+  };
+
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
@@ -140,18 +179,19 @@ export async function runBaton(argv, config, opts = {}) {
       die('`dotmd baton --status in-session` contradicts baton release semantics. Choose active/paused/awaiting/partial/blocked.');
     }
     assertPlanMutationAuthorized(repoPath, config, { sessionId: authoritativeSessionId(), force });
+    // Before the plan-completion step: a refusal must leave nothing changed.
+    refuseIfPending();
     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();
     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).`);
   }
 
   // Plan mode publishes the already-stamped prompt, status/history update, and
   // ownership release in one transaction. Slug mode has no plan transaction.
-  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
-  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
   let createdSlug = null;
   let archiveResult = null;
   let statusChanged = false;
@@ -162,49 +202,45 @@ export async function runBaton(argv, config, opts = {}) {
   if (json) process.stdout.write = chunk => { muted.push(String(chunk)); return true; };
   try {
   if (!planPath) {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const slug = n === 1 ? slugBase : `${slugBase}-${n}`;
-      try {
-        const prepared = preparePromptDocument(slug, body, config, { dryRun });
-        newResult = await runNew(['prompt', slug, '--body', body], config, { dryRun, deferIndex: true });
-        createdSlug = slug;
-        promptRepoPath = prepared.repoPath;
-      }
-      catch (err) { if (!/File already exists/.test(String(err?.message))) throw err; }
+    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;
     }
+    createdSlug = slugBase;
+    promptRepoPath = prepared.repoPath;
   } else {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const candidate = n === 1 ? slugBase : `${slugBase}-${n}`;
-      const prepared = preparePromptDocument(candidate, body, config, { plan: repoPath, dryRun });
-      if (existsSync(prepared.filePath)) continue;
-      const setArgs = [status, planPath];
-      if (force) setArgs.push('--force');
-      if (note) setArgs.push('--note', note);
-      try {
-        if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
-        archiveResult = await runSet(setArgs, config, {
-          dryRun,
-          viaBaton: true,
-          testHooks: opts.testHooks,
-          creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
-          deferIndex: true,
-        });
-        createdSlug = prepared.slug;
-        promptRepoPath = prepared.repoPath;
-        statusChanged = oldStatus !== status;
-        if (!dryRun) {
-          try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
-          catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
-        }
-      } catch (err) {
-        if (!/Destination already exists|File already exists/.test(String(err?.message))) throw err;
-      }
+    const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
+    const setArgs = [status, planPath];
+    if (force) setArgs.push('--force');
+    if (note) setArgs.push('--note', note);
+    try {
+      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
+      archiveResult = await runSet(setArgs, config, {
+        dryRun,
+        viaBaton: true,
+        testHooks: opts.testHooks,
+        creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
+        deferIndex: true,
+      });
+    } catch (err) {
+      if (/Destination already exists|File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+      throw err;
+    }
+    createdSlug = prepared.slug;
+    promptRepoPath = prepared.repoPath;
+    statusChanged = oldStatus !== status;
+    if (!dryRun) {
+      try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
+      catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
     }
   }
   } finally {
     if (json) process.stdout.write = originalStdoutWrite;
   }
-  if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
   // 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

package/src/commands.mjs

@@ -92,16 +92,16 @@ const definitions = [
   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')] }),
-    form('next', { subcommands: ['next'] }),
-    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force')] }),
+    form('next', { subcommands: ['next'], options: [flag('--no-claim')] }),
+    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] }),
     form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
     form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
   ], { 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')] })]),
-  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
+  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('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),

package/src/guard.mjs

@@ -223,8 +223,11 @@ function editStatusResult(target, config, detail) {
     rule: 'edit-status',
     detail,
     reason:
-      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`dotmd set <status> ${target}\` instead — ` +
-      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
+      // Names the canonical executable: a session that follows this message
+      // should land on the current name, not the legacy alias.
+      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`runlist set <status> ${target}\` instead — ` +
+      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that. ` +
+      `Creating a doc? \`runlist new <type> <name> --status <status>\` writes the status in the same step.`,
   };
 }
 

package/src/host-integration.mjs

@@ -23,6 +23,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { hostSessionSource } from './util.mjs';
 import { readEnv, stateDir } from './naming.mjs';
+import { planMarketplaceRepair } from './update.mjs';
 
 export const GENERATED_MARKER = 'dotmd-generated:';
 const PLUGIN_FILENAME = 'dotmd.js';
@@ -233,6 +234,19 @@ export function degradedIdentityNotice(repoRoot, opts = {}) {
 export const CLAUDE_MARKETPLACE = 'reowens/dotmd';
 export const CLAUDE_PLUGIN_ID = 'dotmd@dotmd';
 
+// Why `claude plugin marketplace add` can refuse a marketplace that is not
+// even registered: settings.json may still DECLARE it (extraKnownMarketplaces),
+// and Claude rejects an add whose source differs from that declaration in any
+// fetch-shaping field. dotmd never writes that declaration and will not edit
+// it, so the most it can do is name the field.
+export function claudeMarketplaceRefusalHint(marketplace = 'dotmd') {
+  return [
+    `Claude refused to register marketplace "${marketplace}". If ~/.claude/settings.json declares it under`,
+    `extraKnownMarketplaces, its source must be exactly {"source":"github","repo":"${CLAUDE_MARKETPLACE}"} —`,
+    'a stray "path", "ref" or header there makes the add fail and the installed plugin fail to load.',
+  ];
+}
+
 // Pure planner, mirroring planUpdate: the orchestration is unit-testable and
 // the side effects stay in the caller.
 export function planClaudeInstall({ installed, hasClaude, remove = false } = {}) {
@@ -242,6 +256,13 @@ export function planClaudeInstall({ installed, hasClaude, remove = false } = {})
       ? [{ kind: 'run', cmd: ['claude', 'plugin', 'uninstall', installed.id] }]
       : [{ kind: 'manual', lines: [`/plugin uninstall ${installed.id}`] }];
   }
+  // An install record whose marketplace registration is gone is not an
+  // installed plugin — Claude lists it as "failed to load". Skipping here with
+  // "already installed" left the user with no dotmd verb that could repair it.
+  if (installed?.marketplaceRegistered === false) {
+    return planMarketplaceRepair(installed, { hasClaude, verb: 'update' })
+      .map(step => (step.kind === 'marketplace' || step.kind === 'plugin' ? { ...step, kind: 'run', step: step.kind } : step));
+  }
   if (installed) return [{ kind: 'skip', reason: `dotmd plugin already installed (${installed.version ?? 'unknown version'})` }];
   // The marketplace has to be registered before the plugin resolves; adding one
   // already present is a no-op, so this stays safe to re-run.

package/src/install.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bold, dim, green, yellow } from './color.mjs';
 import {
-  CLAUDE_MARKETPLACE, CLAUDE_PLUGIN_ID, installOpencodePlugin, opencodeDetected,
+  CLAUDE_MARKETPLACE, CLAUDE_PLUGIN_ID, claudeMarketplaceRefusalHint, installOpencodePlugin, opencodeDetected,
   opencodeStatus, planClaudeInstall, removeOpencodePlugin,
 } from './host-integration.mjs';
 import { readInstalledPlugin } from './update.mjs';
@@ -24,7 +24,14 @@ function flagValue(argv, name) {
 function hostStates() {
   const plugin = readInstalledPlugin();
   return {
-    claude: { installed: Boolean(plugin), version: plugin?.version ?? null, id: plugin?.id ?? CLAUDE_PLUGIN_ID },
+    claude: {
+      installed: Boolean(plugin),
+      version: plugin?.version ?? null,
+      id: plugin?.id ?? CLAUDE_PLUGIN_ID,
+      marketplace: plugin?.marketplace ?? null,
+      // false = record present, marketplace gone: Claude shows "failed to load".
+      marketplaceRegistered: plugin ? plugin.marketplaceRegistered : null,
+    },
     opencode: { ...opencodeStatus({ version: pkg.version }), detected: opencodeDetected() },
   };
 }
@@ -38,7 +45,11 @@ function reportStatus(json) {
   const { claude, opencode } = states;
   process.stdout.write(`${bold('dotmd host integrations')}  ${dim(`CLI ${pkg.version}`)}\n\n`);
 
-  process.stdout.write(`  claude    ${claude.installed ? green(claude.version ?? 'installed') : yellow('not installed')}\n`);
+  const claudeBroken = claude.installed && claude.marketplaceRegistered === false;
+  const claudeState = !claude.installed ? yellow('not installed')
+    : claudeBroken ? yellow(`${claude.version ?? 'installed'} — marketplace "${claude.marketplace}" not registered, plugin fails to load`)
+    : green(claude.version ?? 'installed');
+  process.stdout.write(`  claude    ${claudeState}\n`);
   process.stdout.write(`            ${dim(claude.installed ? claude.id : 'plugin: SessionStart primer, PreToolUse guard, workflow skill')}\n`);
 
   const ocState = opencode.foreign ? yellow('unmanaged file present')
@@ -49,7 +60,7 @@ function reportStatus(json) {
   process.stdout.write(`            ${dim(opencode.path)}\n`);
 
   const todo = [];
-  if (!claude.installed) todo.push('dotmd install claude');
+  if (!claude.installed || claudeBroken) todo.push('dotmd install claude');
   if (!opencode.exists || opencode.stale) todo.push('dotmd install opencode');
   if (todo.length) {
     process.stdout.write('\n');
@@ -73,10 +84,11 @@ function installClaude(argv, dryRun, json) {
   for (const step of steps) {
     if (step.kind === 'skip') { process.stdout.write(`${dim('skip:')} ${step.reason}\n`); continue; }
     if (step.kind === 'manual') {
-      process.stdout.write(`${yellow('claude CLI not on PATH')} — run these from a Claude Code session:\n`);
+      process.stdout.write(`${yellow(step.reason ?? 'claude CLI not on PATH')} — run these from a Claude Code session:\n`);
       for (const line of step.lines) process.stdout.write(`  ${bold(line)}\n`);
       continue;
     }
+    if (step.reason) process.stdout.write(`${step.reason}\n`);
     if (dryRun) { process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}\n`)); continue; }
     process.stdout.write(dim(`$ ${step.cmd.join(' ')}\n`));
     const result = spawnSync(executableName(step.cmd[0]), step.cmd.slice(1), {
@@ -85,6 +97,11 @@ function installClaude(argv, dryRun, json) {
     ran = true;
     if (result.status !== 0) {
       process.stdout.write(yellow(`(claude exited ${result.status ?? '?'})\n`));
+      // Each later step here depends on this one (the plugin resolves through
+      // the marketplace), so unlike `update` there is nothing independent left.
+      if (step.step === 'marketplace' || step.cmd.includes('marketplace')) {
+        for (const line of claudeMarketplaceRefusalHint(readInstalledPlugin()?.marketplace)) process.stdout.write(yellow(`${line}\n`));
+      }
       process.exitCode = 1;
       return;
     }

package/src/new.mjs

@@ -132,7 +132,10 @@ ${ctx?.bodyInput?.trim() ?? ''}
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
     dir: 'plans',
     targetRoot: 'plans',
-    defaultStatus: 'active',
+    // A scaffolded plan is scoped, not being worked; `dotmd use` starts it.
+    // Defaulting to `active` forced a second, guarded status write for every
+    // plan that was only being written down.
+    defaultStatus: 'planned',
     // Body input lands in the Problem section. Plans don't have an Overview;
     // Problem is the established opening section in the build-up shape.
     acceptsBody: true,

package/src/prompts.mjs

@@ -196,7 +196,7 @@ async function runPromptsNext(argv, config, opts = {}) {
   }
   const head = queue[0];
   if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
-  return consumePrompt(head.abs, config, opts);
+  return consumePrompt(head.abs, config, { ...opts, noClaim: argv.includes('--no-claim') });
 }
 
 // Resolve user input to a prompt path. Tries (in order): exact path,
@@ -245,8 +245,9 @@ async function runPromptsUse(argv, config, opts = {}) {
   if (!input) die('Usage: dotmd prompts use <file-or-slug>');
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
+  const noClaim = argv.includes('--no-claim');
   const filePath = resolvePromptInput(input, config);
-  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
+  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles, noClaim });
 }
 
 export async function consumePrompt(filePath, config, opts) {
@@ -269,7 +270,9 @@ export async function consumePrompt(filePath, config, opts) {
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
   let claimSkipReason = null;
-  if (planRef) {
+  if (planRef && opts.noClaim) {
+    claimSkipReason = `--no-claim, ${planRef} left as it is`;
+  } else if (planRef) {
     const outcome = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
     if (outcome?.skipped) claimSkipReason = outcome.reason;
     else linkedClaim = outcome;

package/src/update.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { green, dim, yellow } from './color.mjs';
 import { executableName, which } from './util.mjs';
-import { installOpencodePlugin, opencodeStatus } from './host-integration.mjs';
+import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, installOpencodePlugin, opencodeStatus } from './host-integration.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -50,10 +50,54 @@ export function readInstalledPluginRecords(opts = {}) {
   }
 }
 
+// Claude Code's marketplace registry, keyed by marketplace name. A plugin id
+// is `<plugin>@<marketplace>`, and the plugin only loads while its marketplace
+// is registered here — an install record alone is not an installed plugin.
+export function readKnownMarketplaces(opts = {}) {
+  const home = opts.home || os.homedir();
+  const file = path.join(home, '.claude', 'plugins', 'known_marketplaces.json');
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// `marketplaceRegistered: false` is the state `claude plugin list` shows as
+// "failed to load: Marketplace dotmd not found": the install record survived,
+// the marketplace registration did not (a settings.json declaration that no
+// longer matches, a wiped registry). Reading only the install record called
+// that "installed", so `dotmd install claude` skipped the one repair it owns
+// and `dotmd update` ran a `plugin update` that could only fail.
 export function readInstalledPlugin(opts = {}) {
   const records = readInstalledPluginRecords(opts);
   if (!records) return null;
-  return { id: records.id, version: records.entries[0]?.version ?? null };
+  const marketplace = records.id.split('@')[1] || null;
+  const known = readKnownMarketplaces(opts);
+  return {
+    id: records.id,
+    version: records.entries[0]?.version ?? null,
+    marketplace,
+    marketplaceRegistered: Boolean(marketplace && known[marketplace]),
+  };
+}
+
+// The steps that put a plugin whose marketplace registration is gone back on
+// its feet. Only the marketplace dotmd publishes has a source dotmd knows; a
+// plugin installed from some other marketplace names a source we cannot guess.
+export function planMarketplaceRepair(plugin, { hasClaude, verb }) {
+  const reason = `marketplace "${plugin.marketplace}" is not registered, so the installed plugin cannot load`;
+  if (plugin.marketplace !== 'dotmd') {
+    return [{ kind: 'skip', reason: `${reason} — re-add that marketplace (dotmd does not know its source), then rerun` }];
+  }
+  if (!hasClaude) {
+    return [{ kind: 'manual', reason, lines: [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin ${verb} ${plugin.id}`] }];
+  }
+  return [
+    { kind: 'marketplace', reason: `${reason} — re-adding it first`, cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+    { kind: 'plugin', needs: 'marketplace', cmd: ['claude', 'plugin', verb, plugin.id] },
+  ];
 }
 
 // Decide which steps `dotmd update` should run. Pure — no side effects — so the
@@ -69,6 +113,8 @@ export function planUpdate(opts, ctx) {
   if (!opts.cliOnly) {
     if (!ctx.plugin) {
       steps.push({ kind: 'skip', reason: 'dotmd plugin not installed — skipping plugin update' });
+    } else if (ctx.plugin.marketplaceRegistered === false) {
+      steps.push(...planMarketplaceRepair(ctx.plugin, { hasClaude: ctx.hasClaude, verb: 'update' }));
     } else if (!ctx.hasClaude) {
       steps.push({ kind: 'skip', reason: `claude CLI not found — run \`/plugin update ${ctx.plugin.id}\` from a session instead` });
     } else {
@@ -102,6 +148,9 @@ export function runUpdate(argv, _config, opts = {}) {
         : cmp < 0 ? yellow('behind — run `dotmd update`')
         : yellow('ahead — CLI is behind');
       process.stdout.write(`dotmd plugin: ${plugin.version ?? '?'} (${plugin.id}) ${tag}\n`);
+      if (plugin.marketplaceRegistered === false) {
+        process.stdout.write(yellow(`  marketplace "${plugin.marketplace}" is not registered — the plugin fails to load; run \`dotmd install claude\`\n`));
+      }
     } else {
       process.stdout.write(dim('dotmd plugin: not installed — `dotmd install claude`\n'));
     }
@@ -117,24 +166,41 @@ export function runUpdate(argv, _config, opts = {}) {
   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 process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}\n`));
     }
     return;
   }
+  // The hosts are independent: a failed `claude plugin update` says nothing
+  // about the OpenCode file, so every step runs and the failures are reported
+  // together at the end. Stopping at the first one left OpenCode stale behind a
+  // Claude registry problem — silently, since the abort said nothing about the
+  // steps it never reached.
   let ran = false;
-  let failed = false;
+  const failures = [];
+  const failedKinds = new Set();
   for (const s of steps) {
     if (s.kind === 'skip') {
       process.stdout.write(dim(`skip: ${s.reason}\n`));
       continue;
     }
+    if (s.kind === 'manual') {
+      process.stdout.write(`${yellow(s.reason)} — run these from a Claude Code session:\n`);
+      for (const line of s.lines) process.stdout.write(`  ${line}\n`);
+      continue;
+    }
+    if (s.needs && failedKinds.has(s.needs)) {
+      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(' ')}\n`));
     const r = spawnSync(executableName(s.cmd[0]), s.cmd.slice(1), {
       stdio: 'inherit',
@@ -142,13 +208,21 @@ export function runUpdate(argv, _config, opts = {}) {
     });
     ran = true;
     if (r.status !== 0) {
-      failed = true;
+      failedKinds.add(s.kind);
+      failures.push(s);
       process.stdout.write(yellow(`(${s.cmd[0]} exited ${r.status ?? '?'})\n`));
-      break;
+      if (s.kind === 'marketplace') for (const line of claudeMarketplaceRefusalHint(plugin?.marketplace)) process.stdout.write(yellow(`${line}\n`));
+    }
+  }
+  if (failures.length) {
+    process.stdout.write(yellow(`\n${failures.length === 1 ? '1 step' : `${failures.length} steps`} failed: ${failures.map(s => s.cmd.join(' ')).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.exitCode = 1;
+    return;
   }
-  if (ran && !failed) {
+  if (ran) {
     process.stdout.write(green('\n✓ restart your Claude Code session (or /reload-plugins) to apply.\n'));
   }
-  if (failed) process.exitCode = 1;
 }

package/src/use.mjs

@@ -15,13 +15,16 @@ import { resolveDocArg } from './index.mjs';
 // With no argument, consumes the oldest pending prompt.
 export async function runUse(argv, config, opts = {}) {
   const positional = argv.find(a => !a.startsWith('-'));
+  // `--no-claim` reads and archives a prompt without starting the plan it links.
+  const noClaim = argv.includes('--no-claim');
+  const promptOpts = { ...opts, noClaim };
 
   if (!positional) {
     const queue = pendingPromptsOldestFirst(config);
     if (queue.length === 0) die('No pending prompts. Pass a file to use a plan or doc.');
     const head = queue[0];
     if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
-    return consumePrompt(head.abs, config, opts);
+    return consumePrompt(head.abs, config, promptOpts);
   }
 
   // Exact path first, then prompt slugs (they keep precedence on a slug
@@ -39,8 +42,9 @@ export async function runUse(argv, config, opts = {}) {
   const type = asString(parsed.type);
 
   if (type === 'prompt') {
-    return consumePrompt(filePath, config, opts);
+    return consumePrompt(filePath, config, promptOpts);
   }
+  if (noClaim) die('--no-claim applies to prompts only; a plan opened with `use` is always claimed.');
   if (type === 'plan') {
     // Mark in-session (pure frontmatter) and print the plan card.
     return startPlan([filePath, ...argv.filter(a => a !== positional)], config, opts);