dotmd-cli 0.74.5 → 0.75.0

package/src/install.mjs

@@ -0,0 +1,151 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+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,
+  opencodeStatus, planClaudeInstall, removeOpencodePlugin,
+} from './host-integration.mjs';
+import { readInstalledPlugin } from './update.mjs';
+import { executableName, which } from './util.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+const HOSTS = ['claude', 'opencode'];
+const ALIASES = { 'claude-code': 'claude', claudecode: 'claude' };
+
+function flagValue(argv, name) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function hostStates() {
+  const plugin = readInstalledPlugin();
+  return {
+    claude: { installed: Boolean(plugin), version: plugin?.version ?? null, id: plugin?.id ?? CLAUDE_PLUGIN_ID },
+    opencode: { ...opencodeStatus({ version: pkg.version }), detected: opencodeDetected() },
+  };
+}
+
+function reportStatus(json) {
+  const states = hostStates();
+  if (json) {
+    process.stdout.write(JSON.stringify({ cli: pkg.version, hosts: states }, null, 2) + '\n');
+    return;
+  }
+  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`);
+  process.stdout.write(`            ${dim(claude.installed ? claude.id : 'plugin: SessionStart primer, PreToolUse guard, workflow skill')}\n`);
+
+  const ocState = opencode.foreign ? yellow('unmanaged file present')
+    : !opencode.exists ? yellow('not installed')
+    : opencode.stale ? yellow(`${opencode.version} — behind CLI ${pkg.version}`)
+    : green(opencode.version);
+  process.stdout.write(`  opencode  ${ocState}\n`);
+  process.stdout.write(`            ${dim(opencode.path)}\n`);
+
+  const todo = [];
+  if (!claude.installed) todo.push('dotmd install claude');
+  if (!opencode.exists || opencode.stale) todo.push('dotmd install opencode');
+  if (todo.length) {
+    process.stdout.write('\n');
+    for (const cmd of todo) process.stdout.write(`Run ${bold(cmd)}\n`);
+  }
+  if (!opencode.exists) {
+    process.stdout.write(dim('\nWithout the OpenCode integration, every session in one OpenCode process\n'));
+    process.stdout.write(dim('shares one identity — so a session can release another session\'s plan —\n'));
+    process.stdout.write(dim('and no session-start primer runs.\n'));
+  }
+}
+
+function installClaude(argv, dryRun, json) {
+  const remove = argv.includes('--remove');
+  const steps = planClaudeInstall({ installed: readInstalledPlugin(), hasClaude: which('claude'), remove });
+  if (json) {
+    process.stdout.write(JSON.stringify({ host: 'claude', dryRun, steps }, null, 2) + '\n');
+    return;
+  }
+  let ran = false;
+  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`);
+      for (const line of step.lines) process.stdout.write(`  ${bold(line)}\n`);
+      continue;
+    }
+    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), {
+      stdio: 'inherit', shell: process.platform === 'win32',
+    });
+    ran = true;
+    if (result.status !== 0) {
+      process.stdout.write(yellow(`(claude exited ${result.status ?? '?'})\n`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+  if (ran && !remove) process.stdout.write(green('\n✓ restart Claude Code (or /reload-plugins) to apply.\n'));
+}
+
+function installOpencode(argv, dryRun, json) {
+  const force = argv.includes('--force');
+  const dir = flagValue(argv, '--path');
+  const result = argv.includes('--remove')
+    ? removeOpencodePlugin({ dryRun, force, dir })
+    : installOpencodePlugin({ version: pkg.version, dryRun, force, dir });
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    if (result.action === 'refused') process.exitCode = 1;
+    return result;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  switch (result.action) {
+    case 'refused':
+      process.stderr.write(`${result.path}\n  refused: ${result.reason}\n  Pass --force to overwrite it.\n`);
+      process.exitCode = 1;
+      return result;
+    case 'current':
+      process.stdout.write(`${green('✓')} opencode integration already current (${result.version})\n${dim(result.path)}\n`);
+      return result;
+    case 'absent':
+      process.stdout.write(`${dim('nothing to remove:')} ${result.path}\n`);
+      return result;
+    case 'removed':
+      process.stdout.write(`${prefix}removed ${result.path}\n`);
+      process.stdout.write(dim('Restart OpenCode to apply. Sessions fall back to a process-scoped identity.\n'));
+      return result;
+    default:
+      process.stdout.write(`${prefix}${green('✓')} ${result.action} opencode integration (${pkg.version})\n${dim(result.path)}\n`);
+      if (dryRun) return result;
+      process.stdout.write('\nRestart OpenCode to apply. New sessions then get:\n');
+      process.stdout.write(`  ${dim('·')} a per-session ownership identity (one session can no longer release another's plan)\n`);
+      process.stdout.write(`  ${dim('·')} the ${bold('dotmd hud')} primer at session start, like Claude Code's SessionStart hook\n`);
+      process.stdout.write(dim('\nPlans already in-session were claimed under the old process-scoped identity;\n'));
+      process.stdout.write(dim('close them before restarting, or reclaim with --force afterwards.\n'));
+      return result;
+  }
+}
+
+export function runInstall(argv, _config, opts = {}) {
+  const json = argv.includes('--json');
+  const requested = argv.find(a => !a.startsWith('-'));
+
+  if (!requested) { reportStatus(json); return; }
+  const host = ALIASES[requested] ?? requested;
+  if (!HOSTS.includes(host)) {
+    process.stderr.write(`Unknown host "${requested}". Known: ${HOSTS.join(', ')}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const dryRun = Boolean(opts.dryRun);
+  if (host === 'claude') { installClaude(argv, dryRun, json); return; }
+  installOpencode(argv, dryRun, json);
+}

package/src/pickup.mjs

@@ -5,25 +5,22 @@ import { authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-pa
 import os from 'node:os';
 import { currentProcessOwner, mutateFileSet, processOwnerLiveness, processStartIdentity, replaceSnapshot, snapshotFile, withPathLocks } from './atomic-mutation.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, relTime } from './util.mjs';
+import { asString, hostSessionId, relTime } from './util.mjs';
 
 export const OWNERSHIP_SCHEMA = 2;
 export const HOOK_DELIVERY_LEASE_MS = 30_000;
 
 export function authoritativeSessionId(env = process.env) {
-  const candidates = [
-    ['DOTMD_SESSION_ID', 'dotmd'],
-    ['CLAUDE_CODE_SESSION_ID', 'claude'],
-    ['CLAUDE_SESSION_ID', 'claude'],
-    ['OPENCODE_SESSION_ID', 'opencode'],
-    ['OPENCODE_SESSION', 'opencode'],
-    ['TERM_SESSION_ID', 'term'],
-  ];
-  for (const [name, host] of candidates) {
-    const value = env[name]?.trim();
-    if (value) return host === 'term' ? `term:${value}` : value;
-  }
-  throw new Error('No authoritative session identity. Set DOTMD_SESSION_ID for this shell or host session.');
+  const id = hostSessionId(env);
+  if (id) return id;
+  // Name the host when we can recognize it. The generic "set DOTMD_SESSION_ID"
+  // is the fallback of last resort, and a poor one to reach for first: exported
+  // from a shell profile it gives every session in that shell ONE id, which is
+  // the collision the ownership record exists to prevent.
+  const host = env.OPENCODE || env.OPENCODE_PID ? 'opencode' : null;
+  throw new Error(host
+    ? `No authoritative session identity. Run \`dotmd install ${host}\` to give each ${host} session its own, or set DOTMD_SESSION_ID for this shell.`
+    : 'No authoritative session identity. Set DOTMD_SESSION_ID for this shell or host session, or see `dotmd install` for supported hosts.');
 }
 
 export function availableSessionId(env = process.env) {
@@ -38,8 +35,10 @@ export function availableSessionId(env = process.env) {
 // instead of an age threshold that cannot tell a three-day-dead session from a
 // long-running one. Absent (a plain terminal, an unknown harness) is not an
 // error — it yields null, which reads as 'unverifiable' and never auto-reclaims.
+// `OPENCODE_PID` is the OpenCode server process, which is exactly that harness:
+// it hosts the session and outlives every tool shell it spawns.
 export function sessionProcessOwner(env = process.env) {
-  const raw = (env.DOTMD_SESSION_PID ?? env.CLAUDE_PID)?.trim();
+  const raw = (env.DOTMD_SESSION_PID ?? env.CLAUDE_PID ?? env.OPENCODE_PID)?.trim();
   const pid = Number(raw);
   if (!raw || !Number.isInteger(pid) || pid <= 0) return null;
   return {

package/src/prompts.mjs

@@ -6,7 +6,7 @@ import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
 import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
-import { green, dim } from './color.mjs';
+import { green, dim, yellow } from './color.mjs';
 import { authorizeManagedSource } from './managed-path.mjs';
 import {
   authoritativeSessionId,
@@ -259,11 +259,17 @@ export async function consumePrompt(filePath, config, opts) {
 
   const planRef = asString(parsed.plan);
   let linkedClaim = null;
-  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
+  let claimSkipReason = null;
+  if (planRef) {
+    const outcome = prepareLinkedPromptClaim(planRef, config, path.dirname(filePath));
+    if (outcome?.skipped) claimSkipReason = outcome.reason;
+    else linkedClaim = outcome;
+  }
 
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    if (claimSkipReason) process.stderr.write(`${prefix} Would NOT claim the linked plan: ${claimSkipReason}\n`);
     const bytes = Buffer.byteLength(body, 'utf8');
     const lines = body.split('\n').length;
     process.stderr.write(`${prefix} body preview (${bytes}B, ${lines} lines):\n`);
@@ -315,6 +321,7 @@ export async function consumePrompt(filePath, config, opts) {
     }
     process.stderr.write(`${green('→ Claimed')}: ${linkedClaim.repoPath} (in-session)\n`);
   }
+  if (claimSkipReason) process.stderr.write(`${yellow('→ Not claimed')}: ${claimSkipReason}\n`);
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
   const ownershipRecordPath = linkedClaim?.prepared?.recordPath ?? (linkedClaim ? readPlanOwnership(linkedClaim.repoPath, config)?.recordPath : null);
   const ownershipPath = ownershipRecordPath ? toRepoPath(ownershipRecordPath, config.repoRoot) : null;
@@ -364,16 +371,54 @@ export async function writeConsumedBody(body, archivedPath, write = null, linked
 // with `resolveDocPath` alone read only the repo-root form, so a doc-relative
 // link — the form nothing validates, since `plan` is not a `referenceFields`
 // entry — died as "missing" while pointing at a file that was plainly there.
+// Why a linked plan could not be claimed, phrased so the reader knows what to
+// do next. Each of these used to abort consumption entirely (see the skip
+// contract on prepareLinkedPromptClaim).
+// `startable` comes from the repo's own lifecycle config rather than the
+// built-in default: a repo that configures its own startable statuses would
+// otherwise be told to run `dotmd set active`, which its own validation
+// rejects.
+function explainUnclaimablePlan(disposition, repoPath, status, startable) {
+  switch (disposition.kind) {
+    case 'parked':
+      return `${repoPath} is ${status} — \`dotmd set ${startable} ${repoPath}\` to unpark it, then \`dotmd use ${repoPath}\``;
+    case 'busy':
+      return `${repoPath} is claimed by another session (${disposition.owner})`;
+    case 'terminal':
+    case 'physical-archive':
+      return `${repoPath} is already closed (${status})`;
+    case 'wrong-type':
+      return `${repoPath} is not a plan`;
+    case 'unconfigured-status':
+      return `${repoPath} has a status this repo does not configure (${status ?? 'none'})`;
+    case 'ownership-corrupt':
+      return `${repoPath} has an unreadable ownership record — \`dotmd doctor --claims\``;
+    default:
+      return `${repoPath} cannot be claimed (${disposition.kind})`;
+  }
+}
+
+// Returns a claim, or `{ skipped, reason }` when the linked plan cannot be
+// claimed. It never refuses the consumption itself.
+//
+// It used to `die` on all three of these paths, which deadlocked the handoff
+// loop the feature exists to close: `dotmd baton` stamps this link and parks
+// the plan in the same breath, and five of the seven statuses it parks with are
+// not startable — so baton routinely produced a prompt that `dotmd use` would
+// refuse forever, while the SessionStart hud kept telling every new session to
+// run exactly that command. The body is the whole point of a saved prompt, and
+// no reason to skip the claim is a reason to withhold it.
 function prepareLinkedPromptClaim(planRef, config, promptDir) {
+  const skip = reason => ({ skipped: true, reason });
   let planPath = resolveRefPath(planRef, promptDir, config.repoRoot)
     ?? resolveDocPath(planRef, config)
     ?? resolveDocArg(planRef, config, { dieOnMiss: false });
-  if (!planPath || !existsSync(planPath)) die(`Linked plan is missing; prompt was not consumed: ${planRef}`);
+  if (!planPath || !existsSync(planPath)) return skip(`linked plan is missing (moved or renamed): ${planRef}`);
   planPath = authorizeManagedSource(planPath, config, { kind: 'Prompt linked plan source' }).path;
   const raw = readFileSync(planPath, 'utf8');
   let parsed;
   try { parsed = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter); }
-  catch { die(`Linked plan is malformed; prompt was not consumed: ${planRef}`); }
+  catch { return skip(`linked plan has malformed frontmatter: ${toRepoPath(planPath, config.repoRoot)}`); }
   const repoPath = toRepoPath(planPath, config.repoRoot);
   const sessionId = authoritativeSessionId();
   const ownership = readPlanOwnership(repoPath, config);
@@ -391,7 +436,10 @@ function prepareLinkedPromptClaim(planRef, config, promptDir) {
     sessionId,
     malformed: false,
   });
-  if (!disposition.pickupable) die(`Linked plan cannot be claimed (${disposition.kind}); prompt was not consumed: ${repoPath}`);
+  if (!disposition.pickupable) {
+    const startable = [...(config.lifecycle.startableStatuses ?? [])][0] ?? 'active';
+    return skip(explainUnclaimablePlan(disposition, repoPath, oldStatus, startable));
+  }
   if (disposition.kind === 'resume') return { planPath, repoPath, prepared: null, planChanged: false, disposition: disposition.kind };
   const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
   const rendered = disposition.kind === 'start'

package/src/section.mjs

@@ -53,23 +53,121 @@ export function findSection(sections, name) {
 
 // Status marker detection for phase headings. Returns one of:
 //   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
-const MARKER_PATTERNS = [
-  { kind: 'shipped',     re: /(✅|☑|✔|\bshipped\b|\bdone\b|\bcomplete\b)/i },
-  { kind: 'skipped',     re: /(⏭|\bskip(?:ped)?\b)/i },
-  { kind: 'in-progress', re: /(🟡|🔄|\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
-  { kind: 'blocked',     re: /(🚧|🔴|\bblocked\b)/i },
-  { kind: 'todo',        re: /(⬜|⬛|◻|☐|\btodo\b|\bnot[-_ ]?started\b)/i },
+// Glyphs are checked BEFORE prose, not interleaved with it. A glyph is a
+// deliberate mark; a prose word is often about something else in the sentence:
+//
+//   ⬜ Phase 4: Retry budget rework (scoping COMPLETE)              ← the SCOPING completed
+//   Phase 2 — schema migrated ⬜ todo (column rename half DONE)     ← half a RENAME is done
+//   Phase 3 (original scope) — ⏭ superseded by the shipped Phase 3  ← a DIFFERENT phase shipped
+//
+// Interleaved, first-match-wins order called all three shipped, so
+// findActivePhase skipped a phase the author had explicitly marked unstarted.
+// Within each tier the order is still priority order, which decides a heading
+// carrying more than one mark.
+const GLYPH_PATTERNS = [
+  { kind: 'shipped',     re: /(✅|☑|✔)/ },
+  { kind: 'skipped',     re: /(⏭)/ },
+  { kind: 'in-progress', re: /(🟡|🔄)/ },
+  { kind: 'blocked',     re: /(🚧|🔴)/ },
+  { kind: 'todo',        re: /(⬜|⬛|◻|☐)/ },
+];
+
+const PROSE_PATTERNS = [
+  // A qualifier inverts the word it modifies, and these run BEFORE the plain
+  // `shipped` pattern so the qualifier wins. Otherwise `mostly done` and
+  // `(partially complete)` both read as shipped, and findActivePhase skips a
+  // phase whose own checklist still has open boxes.
+  { kind: 'todo',        re: /\b(?:not|never)[\s-]+(?:complete(?:d)?|done|shipped|started)\b/i },
+  { kind: 'in-progress', re: /\b(?:partially|partly|mostly|nearly|almost|half)[\s-]*(?:complete(?:d)?|done|shipped)\b/i },
+  { kind: 'shipped',     re: /(\bshipped\b|\bdone\b|\bcomplete\b)/i },
+  { kind: 'skipped',     re: /(\bskip(?:ped)?\b)/i },
+  { kind: 'in-progress', re: /(\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
+  { kind: 'blocked',     re: /(\bblocked\b)/i },
+  { kind: 'todo',        re: /(\btodo\b|\bnot[-_ ]?started\b)/i },
 ];
 
 export function detectMarker(heading) {
-  for (const { kind, re } of MARKER_PATTERNS) {
+  for (const { kind, re } of GLYPH_PATTERNS) {
+    if (re.test(heading)) return kind;
+  }
+  for (const { kind, re } of PROSE_PATTERNS) {
     if (re.test(heading)) return kind;
   }
   return null;
 }
 
+// Leading decoration a phase heading may carry before the word "Phase":
+// emphasis punctuation and any run of status markers. `detectMarker` already
+// reads a marker wherever it sits, but this test was anchored at `^phase`, so
+// a plan that writes `### ⬜ Phase 2 — …` had NO phases at all — not a
+// miscount, an empty phase set, which drops the pickup card to its
+// "no ## Phases section" fallback. 93 headings in one 482-plan corpus.
+// Several of these glyphs are commonly typed in emoji-presentation form
+// (the base codepoint plus a variation selector): the skip mark, the ballot
+// box, the check mark. `detectMarker` is a substring test so it never
+// noticed. This is a character CLASS, and the selector sits between the glyph
+// and the space, is not \s, and ends the run — so a heading led by the
+// emoji-presentation form was not a phase heading at all, while the bare
+// codepoint was. Reported by the owner, 2026-08-16.
+const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡⏭☑✔◻☐⬛🔴🔄][︎️]?\s*)*`;
+const PHASE_LEAD = new RegExp(`^${PHASE_DECORATION}phase\\b`, 'i');
+
+// "Phase 3 outcome" is commentary ABOUT a phase, not a phase. Counting it
+// inflates the phase set, and because `findActivePhase` ranks blocked above
+// todo, a heading like "Phase 3 smoke findings — BLOCKER" gets picked as the
+// plan's active phase over a real unstarted one. 43 in the same corpus.
+//
+// The noun list is deliberately tight. Wrongly excluding a real phase hides
+// work; wrongly including commentary only miscounts — so this errs toward
+// counting, and a word is added here only once the corpus shows it standing
+// for a retrospective rather than a phase.
+const PHASE_COMMENTARY = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+(outcome|progress|notes?|findings?|smoke|retro|review|recap|summary)\\b`,
+  'i',
+);
+
 export function isPhaseHeading(section) {
-  return section.level === 3 && /^phase\b/i.test(section.heading);
+  if (section.level !== 3) return false;
+  return PHASE_LEAD.test(section.heading) && !PHASE_COMMENTARY.test(section.heading);
+}
+
+// A phase's OWN checklist — the boxes directly under its heading, stopping at
+// the next heading of any level so a sub-section's checklist is never counted
+// as the parent phase's evidence.
+export function phaseTally(section) {
+  let checked = 0, unchecked = 0;
+  for (const line of String(section?.body ?? '').split('\n')) {
+    if (/^#{1,6}\s/.test(line)) break;
+    if (/^\s*[-*]\s*\[x\]/i.test(line)) checked++;
+    else if (/^\s*[-*]\s*\[ \]/.test(line)) unchecked++;
+  }
+  return { checked, unchecked, total: checked + unchecked };
+}
+
+/**
+ * A phase whose declared marker its own checklist contradicts.
+ *
+ * Only two disagreements are reported, because only two are unambiguous:
+ *
+ *   shipped + an open box  — the plan's own checklist says otherwise
+ *   todo    + every box checked — the work is done, the marker says unstarted
+ *
+ * `blocked` and `skipped` are judgements a tally cannot refute (blocked at 0/7
+ * is perfectly coherent), and `in-progress` with everything checked usually
+ * means work the checklist does not enumerate. Including those three took the
+ * count from 13 to 19 on a 482-plan corpus, every extra one arguable — so they
+ * are excluded rather than reported and explained away.
+ *
+ * Returns null when there is no conflict, no marker, or no checklist.
+ */
+export function phaseMarkerConflict(section) {
+  const declared = detectMarker(section?.heading ?? '');
+  if (declared !== 'shipped' && declared !== 'todo') return null;
+  const tally = phaseTally(section);
+  if (tally.total === 0) return null;
+  if (declared === 'shipped' && tally.unchecked > 0) return { declared, implied: 'in progress', ...tally };
+  if (declared === 'todo' && tally.unchecked === 0) return { declared, implied: 'shipped', ...tally };
+  return null;
 }
 
 // Summarize a phase set: { 'shipped': 2, 'in-progress': 1, 'todo': 2 }

package/src/update.mjs

@@ -4,6 +4,8 @@ import path from 'node:path';
 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';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -72,23 +74,19 @@ export function planUpdate(opts, ctx) {
     } else {
       steps.push({ kind: 'plugin', cmd: ['claude', 'plugin', 'update', ctx.plugin.id] });
     }
+    // The OpenCode integration is a file dotmd wrote, so it goes stale silently
+    // 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 `dotmd install`.
+    if (ctx.opencode?.exists && ctx.opencode.stale) {
+      steps.push({ kind: 'opencode', path: ctx.opencode.path });
+    } else if (ctx.opencode?.foreign) {
+      steps.push({ kind: 'skip', reason: `${ctx.opencode.path} was not written by dotmd — leaving it alone` });
+    }
   }
   return steps;
 }
 
-function which(bin) {
-  try {
-    const cmd = process.platform === 'win32' ? 'where' : 'which';
-    return spawnSync(cmd, [bin], { encoding: 'utf8' }).status === 0;
-  } catch {
-    return false;
-  }
-}
-
-function executableName(bin) {
-  return process.platform === 'win32' && !bin.endsWith('.cmd') ? `${bin}.cmd` : bin;
-}
-
 export function runUpdate(argv, _config, opts = {}) {
   const check = argv.includes('--check');
   const cliOnly = argv.includes('--cli-only');
@@ -105,15 +103,21 @@ export function runUpdate(argv, _config, opts = {}) {
         : yellow('ahead — CLI is behind');
       process.stdout.write(`dotmd plugin: ${plugin.version ?? '?'} (${plugin.id}) ${tag}\n`);
     } else {
-      process.stdout.write(dim('dotmd plugin: not installed\n'));
+      process.stdout.write(dim('dotmd plugin: not installed — `dotmd install claude`\n'));
     }
+    const oc = opencodeStatus({ version: pkg.version });
+    if (!oc.exists) process.stdout.write(dim('dotmd opencode: not installed\n'));
+    else if (oc.foreign) process.stdout.write(`dotmd opencode: ${yellow('unmanaged file — not written by dotmd')}\n`);
+    else process.stdout.write(`dotmd opencode: ${oc.version} ${oc.stale ? yellow('behind — run `dotmd update`') : green('in sync')}\n`);
     return;
   }
 
-  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, hasClaude: which('claude'), hasNpm: which('npm') });
+  const opencode = opencodeStatus({ version: pkg.version });
+  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, opencode, 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 === '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;
@@ -125,6 +129,12 @@ export function runUpdate(argv, _config, opts = {}) {
       process.stdout.write(dim(`skip: ${s.reason}\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;
+    }
     process.stdout.write(dim(`$ ${s.cmd.join(' ')}\n`));
     const r = spawnSync(executableName(s.cmd[0]), s.cmd.slice(1), {
       stdio: 'inherit',

package/src/util.mjs

@@ -1,16 +1,88 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { dim } from './color.mjs';
 
+// The one list of environment variables that can name the session dotmd is
+// running inside. It lives here, in a leaf module, because both consumers must
+// read the same list: `currentSessionId` below (journal attribution, which falls
+// back to the shell) and `authoritativeSessionId` in pickup.mjs (plan ownership,
+// which fails closed). Two hand-maintained copies is how the OpenCode entries
+// drifted into naming variables OpenCode does not set.
+//
+// Order is most-specific-first. `OPENCODE_PID` is a real fallback, not a guess:
+// OpenCode's CLI middleware sets it on the process every tool shell inherits,
+// and it is per-OpenCode-process rather than per-session, so it sits below the
+// session-scoped names above it and above `TERM_SESSION_ID` — a terminal id is
+// shared by every agent run in that window and outlives all of them.
+// `scope: 'session'` means the variable names one agent session; `'process'`
+// and `'terminal'` are coarser — several sessions can share one, so they cannot
+// tell two of them apart. `dotmd doctor --session` reports that distinction, and
+// it is the whole reason `dotmd install opencode` exists.
+const SESSION_ID_SOURCES = [
+  { variable: 'DOTMD_SESSION_ID', prefix: null, scope: 'session', host: 'explicit override' },
+  { variable: 'CLAUDE_CODE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },
+  { variable: 'CLAUDE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },
+  { variable: 'OPENCODE_SESSION_ID', prefix: null, scope: 'session', host: 'OpenCode' },
+  { variable: 'OPENCODE_SESSION', prefix: null, scope: 'session', host: 'OpenCode' },
+  { variable: 'OPENCODE_PID', prefix: 'opencode', scope: 'process', host: 'OpenCode' },
+  { variable: 'TERM_SESSION_ID', prefix: 'term', scope: 'terminal', host: 'terminal' },
+];
+
+// Which source named the session, with the id it produced — or null when the
+// environment names none.
+export function hostSessionSource(env = process.env) {
+  for (const source of SESSION_ID_SOURCES) {
+    const value = env[source.variable]?.trim();
+    if (!value) continue;
+    return { ...source, id: source.prefix ? `${source.prefix}:${value}` : value };
+  }
+  return null;
+}
+
+// The session id the environment names, or null when it names none.
+export function hostSessionId(env = process.env) {
+  return hostSessionSource(env)?.id ?? null;
+}
+
 // Stable identifier for the current shell/agent session. Used for journal
 // attribution and hint de-duplication — not for any plan locking.
 export function currentSessionId() {
-  if (process.env.DOTMD_SESSION_ID) return process.env.DOTMD_SESSION_ID;
-  if (process.env.CLAUDE_CODE_SESSION_ID) return process.env.CLAUDE_CODE_SESSION_ID;
-  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
-  if (process.env.TERM_SESSION_ID) return `term:${process.env.TERM_SESSION_ID}`;
-  return `shell:${os.userInfo().username}@${os.hostname()}`;
+  return hostSessionId() ?? `shell:${os.userInfo().username}@${os.hostname()}`;
+}
+
+// The running CLI's version, read once and memoized — several surfaces compare
+// it against what a host integration was generated from.
+let cachedVersion;
+export function dotmdVersion() {
+  if (cachedVersion === undefined) {
+    try {
+      const pkgPath = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'package.json');
+      cachedVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? null;
+    } catch {
+      cachedVersion = null;
+    }
+  }
+  return cachedVersion;
+}
+
+// Is `bin` runnable from PATH? Used to decide whether dotmd can drive a host's
+// own CLI or must print the in-session commands for the user to run instead.
+export function which(bin) {
+  try {
+    const cmd = process.platform === 'win32' ? 'where' : 'which';
+    return spawnSync(cmd, [bin], { encoding: 'utf8' }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// Windows resolves `foo` to `foo.cmd` only through a shell; spawn needs the
+// real name.
+export function executableName(bin) {
+  return process.platform === 'win32' && !bin.endsWith('.cmd') ? `${bin}.cmd` : bin;
 }
 
 export function escapeTable(value) {