dotmd-cli 0.74.6 → 0.76.0

package/README.md

@@ -23,9 +23,23 @@ npx dotmd-cli init          # try it without installing
 Maintainer release automation is POSIX-only because it uses Bash and POSIX
 command-line tools. The published Node.js CLI remains cross-platform.
 
+### Agent host setup
+
+The CLI alone gives an agent no orientation and no session identity. Install the
+integration for whichever host you run:
+
+```bash
+dotmd install             # what's installed for each host
+dotmd install claude      # Claude Code plugin (marketplace + plugin)
+dotmd install opencode    # OpenCode plugin (one auto-discovered file)
+dotmd doctor --session    # what identity dotmd sees here, and from where
+```
+
+Both are one-time and global; `dotmd update` keeps them in step with the CLI.
+
 ### Claude Code Plugin
 
-The recommended Claude Code setup is the dotmd plugin:
+`dotmd install claude` runs the two steps below for you. From inside a session:
 
 ```text
 /plugin marketplace add reowens/dotmd
@@ -36,6 +50,23 @@ The plugin provides SessionStart and SubagentStart orientation, a PreToolUse
 guard, the canonical workflow skill, and `/plans`, `/docs`, `/prompts`, and
 `/baton` commands.
 
+### OpenCode Plugin
+
+`dotmd install opencode` writes one plugin file into OpenCode's global config
+directory, where OpenCode auto-discovers it — no `opencode.json` edit. It
+supplies the two things the CLI cannot get on its own:
+
+- **Per-session plan ownership.** OpenCode exports no session id to a tool
+  shell. Without the plugin, dotmd falls back to `OPENCODE_PID`, which names the
+  OpenCode *process* — so every session in one OpenCode instance shares an
+  identity and can release the others' in-session plans.
+- **A session-start briefing**, the equivalent of Claude Code's SessionStart
+  hook. OpenCode's Claude Code compatibility covers skills and the system
+  prompt, not hooks, so nothing else runs `dotmd hud`.
+
+Restart OpenCode after installing. The file is version-stamped; a `dotmd.js`
+without that stamp is treated as hand-authored and is never overwritten.
+
 The plugin requires a global CLI install because its hooks resolve `dotmd` from
 `PATH`. A project devDependency is useful for npm scripts but does not put the
 CLI on the hook's `PATH`.

package/assets/opencode/plugin.js

@@ -0,0 +1,97 @@
+// dotmd's OpenCode integration. Installed by `dotmd install opencode`, which
+// copies this file (with a version banner prepended) to the OpenCode plugin
+// directory, where OpenCode auto-discovers it — it globs
+// `{plugin,plugins}/*.{ts,js}` under `.opencode/` and the global config dir, so
+// no `opencode.json` edit is needed.
+//
+// TWO CONSTRAINTS, both load-bearing:
+//
+//  1. EXACTLY ONE EXPORT. OpenCode treats every export of a plugin module as a
+//     plugin factory and throws `Plugin export is not a function` on anything
+//     that isn't one — so an exported helper wouldn't just be untidy, it would
+//     be *called* as a second plugin. Helpers stay module-local.
+//
+//  2. NO HOOK MAY THROW. OpenCode awaits hook callbacks inside the request it
+//     is serving; a rejected promise fails the user's chat turn. Every hook
+//     body is wrapped, and a failure degrades to "dotmd does nothing here"
+//     rather than to a broken session.
+//
+// Runs under Bun inside the OpenCode process. Node builtins only, no deps.
+
+import { execFile } from 'node:child_process';
+
+// The primer is a nicety; identity is a correctness invariant. They are split
+// across two hooks deliberately: `shell.env` is stable API, while
+// `experimental.chat.system.transform` may be renamed by OpenCode. If it is,
+// priming stops and ownership keeps working — the failure lands on the half
+// that can afford it.
+const PRIMER_TTL_MS = 60_000;
+const PRIMER_TIMEOUT_MS = 5_000;
+
+function dotmdExecutable() {
+  return process.platform === 'win32' ? 'dotmd.cmd' : 'dotmd';
+}
+
+function runHud(directory) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = value => { if (!settled) { settled = true; resolve(value); } };
+    try {
+      execFile(dotmdExecutable(), ['hud'], {
+        cwd: directory,
+        timeout: PRIMER_TIMEOUT_MS,
+        windowsHide: true,
+        env: { ...process.env, NO_COLOR: '1' },
+      }, (error, stdout) => done(error ? '' : (stdout ?? '').trim()));
+    } catch {
+      // `dotmd` not on PATH, spawn refused — no primer, no noise.
+      done('');
+    }
+  });
+}
+
+export default async function dotmdOpencodePlugin({ directory }) {
+  // Keyed by session so a subagent session primes independently, the way
+  // SubagentStart does under Claude Code.
+  const primers = new Map();
+
+  async function primerFor(sessionId) {
+    const key = sessionId ?? '';
+    const cached = primers.get(key);
+    // Refreshed on a TTL rather than cached for the session's life: OpenCode
+    // rebuilds the system prompt every turn, so a once-only push would reach
+    // 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);
+    primers.set(key, { text, at: Date.now() });
+    return text;
+  }
+
+  return {
+    // Ownership identity. OpenCode sets no session-id variable of its own, and
+    // `OPENCODE_PID` — what dotmd falls back to without this plugin — names the
+    // OpenCode *process*, so every session in one TUI shares it and can release
+    // the others' plans. This is the only place the real session id is
+    // available to a tool shell.
+    'shell.env': async (input, output) => {
+      try {
+        if (input?.sessionID) output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
+        // The OpenCode server process hosts the session and outlives every tool
+        // shell, so it is the process whose liveness answers "is this claim's
+        // owner still there?" — `dotmd doctor --claims` probes exactly this.
+        output.env.DOTMD_SESSION_PID = String(process.pid);
+      } catch { /* never break a shell over this */ }
+    },
+
+    // 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.
+    'experimental.chat.system.transform': async (input, output) => {
+      try {
+        const text = await primerFor(input?.sessionID);
+        if (text) output.system.push(text);
+      } catch { /* priming is best-effort */ }
+    },
+  };
+}

package/bin/dotmd.mjs

@@ -142,6 +142,44 @@ guard entirely with DOTMD_GUARD=0. Read the log with \`dotmd misuse\`; when one
 rule trips ≥3× in 7 days in a repo, \`dotmd hud\` opens the next session there
 with a one-line recap naming the habit to break.`,
 
+  install: `dotmd install [<host>] — install dotmd's integration into an agent host
+
+  dotmd install                report what is installed for each known host
+  dotmd install claude         install the Claude Code plugin (marketplace + plugin)
+  dotmd install opencode       install/refresh the OpenCode plugin (global config dir)
+  dotmd install <host> --remove
+  dotmd install opencode --path <dir>   write to a specific plugin directory
+  dotmd install opencode --force        overwrite a dotmd.js dotmd did not write
+
+The CLI on its own gives an agent no orientation and no session identity. Each
+host gets that a different way:
+
+  claude    Drives \`claude plugin marketplace add ${'reowens/dotmd'}\` +
+            \`claude plugin install dotmd@dotmd\`. This is the FIRST install;
+            \`dotmd update\` only refreshes a plugin already present (it skips
+            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.
+
+  opencode  Writes one auto-discovered plugin file. OpenCode has no plugin
+            registry but globs \`{plugin,plugins}/*.{ts,js}\` under its global
+            config dir, so no opencode.json edit is needed. It supplies two
+            things the CLI cannot get on its own:
+              - Per-session ownership identity. OpenCode exports no session id
+                to a tool shell, so without it every session in one OpenCode
+                process shares one identity and can release the others'
+                in-session plans.
+              - The \`dotmd hud\` primer at session start, the equivalent of
+                Claude Code's SessionStart hook. OpenCode's Claude Code
+                compatibility covers skills and the system prompt — not hooks —
+                so nothing else runs it.
+            The file is version-stamped and refreshed by \`dotmd update\`. A
+            \`dotmd.js\` without that stamp is treated as hand-authored and is
+            never overwritten or removed without --force.
+
+Writing outside the repo is why this is an explicit verb: \`dotmd doctor\`
+reports a missing integration but never installs one.`,
+
   update: `dotmd update — update the dotmd CLI and the Claude Code plugin together
 
   dotmd update                 npm i -g dotmd-cli  +  claude plugin update dotmd@dotmd
@@ -232,6 +270,7 @@ Create & Export:
 
 Setup:
   init                              Create starter config + docs directory
+  install [opencode]                Install the agent-host integration (no arg = status)
   update [--check|--cli-only|--plugin-only]  Update the CLI + Claude Code plugin (--check reports skew, no network)
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
   help statuses                     Full status vocabulary + unstuck-actions + transitions
@@ -464,8 +503,9 @@ another session's work.
 a unique bare slug / basename across the doc roots (\`set paused auth-revamp\`).
 Ambiguous slugs error with the candidate list instead of guessing.
 When the path is omitted, exactly one plan must be owned by this session.
-Claude Code and OpenCode session IDs are recognized automatically. Other hosts
-must set DOTMD_SESSION_ID; anonymous ownership mutations fail closed.
+Claude Code session IDs are recognized automatically, as is OpenCode (via
+OPENCODE_PID — per OpenCode process, not per session). Other hosts must set
+DOTMD_SESSION_ID; anonymous ownership mutations fail closed.
 Pickup hooks use at-least-once delivery with a stable operationId; hook side
 effects must deduplicate that ID.
 
@@ -743,6 +783,15 @@ Modes:
                          another machine — that are older than the duration.
                          That threshold is your judgement, not dotmd's: it
                          cannot tell a dead session from a slow one.
+  --session              Read-only: what session identity dotmd resolved, from
+                         which environment variable, and whether it names THIS
+                         session or something coarser that its siblings share
+                         (a host process, a terminal) — sessions sharing an id
+                         can release each other's plans. Also reports whether
+                         the current host's integration is installed. Run this
+                         when a verb says "No authoritative session identity",
+                         or on any host dotmd has never been tried on.
+  --session --json       Machine-readable identity + host-integration state.
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -1545,6 +1594,18 @@ async function main() {
     throw err;
   }
   _resolvedConfig = config;
+  // The one place that reaches an OpenCode session running without the
+  // integration — whatever verb it reaches for first. stderr, so `--json`
+  // consumers are untouched, and once per session so it informs rather than
+  // nags. `install`/`doctor`/`update` are skipped: they report this themselves,
+  // and telling `dotmd install opencode` to run `dotmd install opencode` is
+  // noise.
+  if (!['install', 'doctor', 'update', 'hud', 'guard'].includes(command)) {
+    const { degradedIdentityNotice } = await import('../src/host-integration.mjs');
+    const notice = degradedIdentityNotice(config?.repoRoot, { version: pkg.version });
+    if (notice) process.stderr.write(`${notice}\n`);
+  }
+
   const suppressSideEffects = effectiveDryRun || command === 'hud' || passiveMachineContext;
   Object.defineProperty(config, '_execution', {
     value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects, gitStaleness },
@@ -1724,6 +1785,7 @@ async function main() {
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config, { dryRun }); return; }
   if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config, { dryRun }); return; }
+  if (command === 'install') { const { runInstall } = await import('../src/install.mjs'); runInstall(restArgs, config, { dryRun }); return; }
   if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.74.6",
+  "version": "0.76.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
   "files": [
     "bin/",
     "src/",
+    "assets/",
     "scripts/postinstall.mjs",
     "dotmd.config.example.mjs"
   ],

package/scripts/postinstall.mjs

@@ -24,6 +24,16 @@ try {
     } catch { return false; }
   })();
 
+  // OpenCode's integration is a file dotmd writes, and nothing else would ever
+  // mention it — an OpenCode user who installs only the CLI gets no primer and
+  // a process-scoped session identity, silently. One line, never an install.
+  const hasOpencode = (() => {
+    try {
+      const cmd = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(cmd, ['opencode'], { encoding: 'utf8' }).status === 0;
+    } catch { return false; }
+  })();
+
   if (process.env.DOTMD_AUTO_PLUGIN_UPDATE === '1' && hasClaude) {
     spawnSync('claude', ['plugin', 'update', 'dotmd@dotmd'], { stdio: 'ignore', timeout: 60000 });
     process.stdout.write('dotmd: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
@@ -35,6 +45,9 @@ try {
       : 'dotmd CLI installed.';
     process.stdout.write(`${nudge}\n`);
   }
+  if (hasOpencode) {
+    process.stdout.write('dotmd: OpenCode detected — run `dotmd install opencode` for per-session plan ownership and a session-start briefing.\n');
+  }
 } catch {
   // Best effort only — never break the install.
 }

package/src/commands.mjs

@@ -114,6 +114,9 @@ const definitions = [
   command('export', mutates('external output path intentionally unrestricted'), 'mutate', [form('[file]', { args: positionals(0, 1), options: [value('--format'), value('--output'), value('--status'), value('--module'), value('--root'), value('--type')] })]),
   command('guard', mutates('global misuse log; no managed document writes'), 'mutate', [form('')]),
   command('update', mutates('global CLI and plugin installation state'), 'mutate', [form('', { options: [flag('--check'), flag('--cli-only'), flag('--plugin-only')] })]),
+  command('install', mutates('agent-host plugin directory outside the repo'), 'mutate', [
+    form('[host]', { args: positionals(0, 1), options: [flag('--remove'), flag('--force'), flag('--json'), value('--path')] }),
+  ]),
   command('status', mutates('managed source and same-root destination'), 'mutate', [form('<file> [status]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('set', mutates('managed source and same-root destination'), 'mutate', [form('<status> [file]', { args: positionals(1, 2), options: LIFECYCLE_OPTIONS })]),
   command('ship', mutates('repository release/index paths and global release tooling'), 'mutate', [form('[patch|minor|major]', { args: positionals(0, 1) })]),
@@ -134,7 +137,7 @@ const definitions = [
   command('migrate', mutates('managed source sweep'), 'mutate', [form('<field> <old> <new> [files...]', { args: positionals(3, Infinity), options: [flag('--show-files')] })]),
   command('fix-refs', mutates('managed source sweep'), 'mutate', [form('', { options: [flag('--show-files')] })]),
   command('sync-status', mutates('managed source sweep'), 'mutate', [form('[hubs...]', { args: positionals(0, Infinity), options: [flag('--adopt'), flag('--json')] })]),
-  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
+  command('doctor', mutates('managed sweeps, repo index, and maintenance config paths by mode'), 'mutate', [form('[path]', { args: positionals(0, 1), options: [flag('--apply', '--yes'), flag('--statuses'), optionalValue('--migrate-template'), flag('--migrate-prompts'), flag('--frontmatter-fix'), flag('--project'), flag('--transactions'), flag('--claims'), flag('--session'), value('--older-than'), flag('--json'), flag('--include-archived')] })]),
   command('statuses', mutates('project config path; document scan is read-only'), 'mutate', [
     form('list', { subcommands: ['list'], options: [value('--type'), flag('--json')] }),
     form('add <name>', { subcommands: ['add'], args: positionals(1, 1), options: STATUS_PROPERTY_OPTIONS }),

package/src/doctor.mjs

@@ -7,15 +7,16 @@ import { runSet, runTouch } from './lifecycle.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { writeRenderedIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
-import { bold, dim, green, yellow } from './color.mjs';
+import { bold, dim, green, red, yellow } from './color.mjs';
 import { checkClaudeCommands, removeGeneratedSlashCommands } from './claude-commands.mjs';
 import { checkSkillDrift } from './skill-drift.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
 import { normalizeEol } from './frontmatter.mjs';
-import { die, relTime, toRepoPath } from './util.mjs';
+import { die, dotmdVersion, relTime, toRepoPath } from './util.mjs';
 import { inspectTransactions, resolveTransactions } from './atomic-mutation.mjs';
+import { describeSessionIdentity, opencodeStatus } from './host-integration.mjs';
 import { availableSessionId, releaseVanishedPlanClaim, surveyOwnershipClaims } from './pickup.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
@@ -209,6 +210,29 @@ async function runDoctorClaims(argv, config, opts = {}) {
   }
 }
 
+// Read-only: what session identity does dotmd see, and is the current host's
+// integration installed? Never writes — installing lives behind `dotmd install`
+// because it touches state outside the repo.
+function runDoctorSession(argv) {
+  const identity = describeSessionIdentity({ version: dotmdVersion() });
+  const oc = opencodeStatus({ version: dotmdVersion() });
+  if (argv.includes('--json')) {
+    process.stdout.write(JSON.stringify({ identity, hosts: { opencode: oc } }, null, 2) + '\n');
+    return;
+  }
+  process.stdout.write(bold('Session identity\n'));
+  const mark = identity.scope === 'session' ? green('✓') : identity.id ? yellow('!') : red('✗');
+  process.stdout.write(`  ${mark} ${identity.id ?? dim('none')}\n`);
+  process.stdout.write(`    ${dim(identity.summary)}\n`);
+  for (const line of identity.advice) process.stdout.write(`    → ${line}\n`);
+
+  process.stdout.write('\n' + bold('Host integration\n'));
+  if (oc.foreign) process.stdout.write(`  ${yellow('!')} opencode: a dotmd.js dotmd did not write — ${oc.path}\n`);
+  else if (!oc.exists) process.stdout.write(`  ${dim('·')} opencode: not installed — ${dim(oc.path)}\n`);
+  else process.stdout.write(`  ${oc.stale ? yellow('!') : green('✓')} opencode: ${oc.version}${oc.stale ? ` (CLI is ${dotmdVersion()} — run \`dotmd update\`)` : ''}\n`);
+  process.stdout.write(dim('  Claude Code ships as a plugin — `dotmd install` reports both hosts.\n'));
+}
+
 export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--project')) {
     runDoctorProject(config, { json: argv.includes('--json') });
@@ -237,6 +261,10 @@ export function runDoctor(argv, config, opts = {}) {
   if (argv.includes('--claims')) {
     return runDoctorClaims(argv, config, opts);
   }
+  if (argv.includes('--session')) {
+    runDoctorSession(argv);
+    return;
+  }
 
   const { dryRun, testHooks } = opts;
   // 0.37.0 (F4): the mode banner makes it impossible to mistake a preview run
@@ -325,6 +353,18 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('\n' + bold('Closeout guidance') + '\n');
     process.stdout.write(manual);
   }
+
+  // Not a numbered step and never auto-fixed: installing touches state outside
+  // the repo, which is `dotmd install`'s job. Doctor's part is making sure a
+  // degraded identity is something you're told about rather than something you
+  // find out when a verb fails. Silent when there is nothing to say.
+  const identity = describeSessionIdentity({ version: dotmdVersion() });
+  if (identity.advice.length) {
+    process.stdout.write('\n' + bold('Session identity') + '\n');
+    process.stdout.write(`${yellow('!')} ${identity.summary}\n`);
+    for (const line of identity.advice) process.stdout.write(dim(`  → ${line}\n`));
+    process.stdout.write(dim('  `dotmd doctor --session` for the full picture.\n'));
+  }
 }
 
 function readJsonIfPresent(filePath) {

package/src/host-integration.mjs

@@ -0,0 +1,265 @@
+// Installing dotmd's integration into agent hosts other than Claude Code.
+//
+// Claude Code gets its integration through a real plugin (`plugins/dotmd/`,
+// installed by `claude plugin`). OpenCode has no equivalent registry, but it
+// auto-discovers plugin files: it globs `{plugin,plugins}/*.{ts,js}` under the
+// global config dir and under a project's `.opencode/`, with no config entry
+// needed. So the integration ships as one generated file.
+//
+// It goes in the GLOBAL config dir, not per-repo. dotmd retired per-repo
+// generated scaffolding once already (`.claude/commands`, see
+// claude-commands.mjs) because a file copied into every repo drifts from the
+// CLI that wrote it. One global file covers every repo and is refreshed by
+// `dotmd update` in lockstep with the CLI.
+//
+// Writing outside the repo is why this is an explicit verb. `dotmd doctor`
+// reports that the integration is missing and names the command; it never
+// installs. Passive commands touch nothing.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hostSessionSource } from './util.mjs';
+
+export const GENERATED_MARKER = 'dotmd-generated:';
+const PLUGIN_FILENAME = 'dotmd.js';
+const ASSET = path.resolve(fileURLToPath(import.meta.url), '..', '..', 'assets', 'opencode', 'plugin.js');
+
+// OpenCode's own resolution order for its global config directory. Verified
+// against the shipped binary: `OPENCODE_CONFIG_DIR` is an explicit override it
+// consults directly, and the default is the XDG location.
+export function opencodeConfigDir(env = process.env, homedir = os.homedir()) {
+  const explicit = env.OPENCODE_CONFIG_DIR?.trim();
+  if (explicit) return path.resolve(explicit);
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  return xdg ? path.join(path.resolve(xdg), 'opencode') : path.join(homedir, '.config', 'opencode');
+}
+
+// Both spellings are globbed, so an existing one is adopted rather than
+// creating a second plugin directory beside the user's own plugins.
+export function opencodePluginDir(configDir) {
+  for (const name of ['plugin', 'plugins']) {
+    const candidate = path.join(configDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return path.join(configDir, 'plugin');
+}
+
+export function opencodePluginPath(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), dir } = opts;
+  if (dir) return path.join(path.resolve(dir), PLUGIN_FILENAME);
+  return path.join(opencodePluginDir(opencodeConfigDir(env, homedir)), PLUGIN_FILENAME);
+}
+
+function banner(version) {
+  return [
+    `// ${GENERATED_MARKER}${version}`,
+    '// Generated by `dotmd install opencode`. Refreshed by `dotmd update`.',
+    '// Hand edits are overwritten — remove with `dotmd install opencode --remove`.',
+    '',
+  ].join('\n');
+}
+
+export function renderOpencodePlugin(version) {
+  return banner(version) + readFileSync(ASSET, 'utf8');
+}
+
+// The version a generated file was written by, or null when the file is absent
+// or carries no dotmd banner. A file without the banner is the user's own and
+// is never written or removed — same rule the retired slash-command scaffolding
+// followed.
+export function installedVersion(filePath) {
+  let contents;
+  try { contents = readFileSync(filePath, 'utf8'); } catch { return null; }
+  const marker = contents.indexOf(GENERATED_MARKER);
+  if (marker < 0) return null;
+  const rest = contents.slice(marker + GENERATED_MARKER.length);
+  return rest.split('\n', 1)[0].trim() || null;
+}
+
+export function opencodeStatus(opts = {}) {
+  const { version, ...rest } = opts;
+  const filePath = opencodePluginPath(rest);
+  const exists = existsSync(filePath);
+  const installed = exists ? installedVersion(filePath) : null;
+  return {
+    path: filePath,
+    exists,
+    version: installed,
+    // Present but unmarked: the user put a `dotmd.js` there themselves.
+    foreign: exists && installed === null,
+    stale: installed !== null && version !== undefined && installed !== version,
+  };
+}
+
+// Is OpenCode plausibly in use on this machine? Used only to decide whether to
+// mention the integration — never to install anything.
+export function opencodeDetected(opts = {}) {
+  const { env = process.env, homedir = os.homedir() } = opts;
+  if (env.OPENCODE || env.OPENCODE_PID) return true;
+  const configDir = opencodeConfigDir(env, homedir);
+  if (!existsSync(configDir)) return false;
+  try { return readdirSync(configDir).length > 0; } catch { return false; }
+}
+
+export function installOpencodePlugin(opts = {}) {
+  const { version, dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus({ version, ...rest });
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'a dotmd.js without a dotmd banner is already there — it was not written by dotmd' };
+  }
+  if (status.exists && !status.stale && !status.foreign) {
+    return { ...status, action: 'current' };
+  }
+  const action = status.exists ? 'updated' : 'installed';
+  if (!dryRun) {
+    mkdirSync(path.dirname(status.path), { recursive: true });
+    writeFileSync(status.path, renderOpencodePlugin(version), 'utf8');
+  }
+  return { ...status, action, version };
+}
+
+// What identity does dotmd actually see here, and can it tell this session
+// apart from its siblings? This report exists because the OpenCode breakage was
+// invisible until a verb failed: dotmd looked for variables OpenCode never set,
+// and nothing surfaced that until `use` refused to run. Anyone on any host can
+// now check what dotmd resolved instead of discovering it through a failure.
+export function describeSessionIdentity(opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version } = opts;
+  const source = hostSessionSource(env);
+  const opencode = opencodeStatus({ env, homedir, version });
+  const underOpencode = Boolean(env.OPENCODE || env.OPENCODE_PID);
+
+  if (!source) {
+    return {
+      id: null, scope: 'none', source: null, host: null,
+      summary: 'no session identity — `use`, `set`, `baton` and `archive` fail closed',
+      advice: underOpencode
+        ? ['dotmd install opencode', 'or set DOTMD_SESSION_ID for this shell']
+        : ['set DOTMD_SESSION_ID for this shell or host session', 'known hosts: dotmd install'],
+    };
+  }
+
+  const advice = [];
+  // The distinction that matters: a process- or terminal-scoped id is shared by
+  // every session under it, so those sessions can release each other's plans.
+  if (source.scope === 'process' && source.host === 'OpenCode') {
+    advice.push(opencode.exists
+      // The plugin is there but this shell was spawned before it loaded, so it
+      // still carries the old identity — say so rather than leave a warning
+      // marker with no explanation.
+      ? 'restart OpenCode — this session predates the installed integration'
+      : 'dotmd install opencode  — for a per-session identity');
+  } else if (source.scope === 'terminal') {
+    advice.push('every agent session in this terminal shares this id — set DOTMD_SESSION_ID per session');
+  }
+  return {
+    id: source.id,
+    scope: source.scope,
+    source: source.variable,
+    host: source.host,
+    summary: source.scope === 'session'
+      ? `per-session identity from ${source.variable}`
+      : `${source.scope}-scoped identity from ${source.variable} — sessions sharing it can release each other's plans`,
+    advice,
+  };
+}
+
+// --- Telling the session it is running degraded -----------------------------
+//
+// Every other surface here has to be sought out: `doctor`, `install`, the npm
+// postinstall line. But the degraded mode is SILENT — with the OPENCODE_PID
+// fallback in place, `use`/`set`/`baton` all work, they just share one identity
+// across every session in the OpenCode process. Nobody goes looking for a
+// diagnostic about a thing that appears to work, so this comes to them.
+//
+// Warning, not error. Failing closed would undo the fallback that unblocked
+// OpenCode in the first place, and punish a setup that is working.
+//
+// Once per session per repo, via a marker under the gitignored .dotmd/. Silent
+// under DOTMD_NO_HINTS=1, the switch the repeat-failure hints already use.
+const NOTICE_DIR = 'notices';
+
+function noticeMarkerPath(repoRoot, key) {
+  const digest = createHash('sha256').update(key).digest('hex').slice(0, 32);
+  return path.join(path.resolve(repoRoot), '.dotmd', NOTICE_DIR, `${digest}`);
+}
+
+// Returns the notice text the first time it applies in a session, then null.
+// `record: false` answers without consuming the once-per-session budget.
+export function degradedIdentityNotice(repoRoot, opts = {}) {
+  const { env = process.env, homedir = os.homedir(), version, record = true } = opts;
+  if (env.DOTMD_NO_HINTS === '1') return null;
+  // Cheap env check first: a user on any other host pays nothing for this.
+  if (!env.OPENCODE && !env.OPENCODE_PID) return null;
+
+  const identity = describeSessionIdentity({ env, homedir, version });
+  if (identity.scope === 'session') return null;
+
+  const installed = opencodeStatus({ env, homedir, version }).exists;
+  const lines = installed
+    ? ['[dotmd] This OpenCode session started before the dotmd integration loaded, so its plan',
+      '        ownership is still process-scoped. Restart OpenCode to pick it up.']
+    : ['[dotmd] OpenCode detected, dotmd integration not installed — plan ownership is scoped to',
+      '        the OpenCode process, so another session in it can release plans this one claimed,',
+      '        and no session-start briefing runs. Fix once: dotmd install opencode'];
+
+  if (!record) return lines.join('\n');
+  if (!repoRoot) return lines.join('\n');
+  const marker = noticeMarkerPath(repoRoot, `opencode:${identity.id}:${installed ? 'restart' : 'install'}`);
+  if (existsSync(marker)) return null;
+  try {
+    mkdirSync(path.dirname(marker), { recursive: true });
+    writeFileSync(marker, '', 'utf8');
+  } catch {
+    // Unwritable .dotmd: say it once anyway rather than stay silent about a
+    // real ownership weakness. Worst case it repeats.
+  }
+  return lines.join('\n');
+}
+
+// --- Claude Code -----------------------------------------------------------
+//
+// Claude Code has a real plugin registry, so dotmd drives `claude plugin`
+// rather than writing files. What it lacked was any CLI path to the FIRST
+// install: `dotmd update` deliberately skips the plugin step when nothing is
+// installed ("dotmd plugin not installed"), and the README's two slash commands
+// only work from inside a session. So a user who installed the CLI from npm had
+// no way to discover, from the CLI, that the plugin exists.
+
+export const CLAUDE_MARKETPLACE = 'reowens/dotmd';
+export const CLAUDE_PLUGIN_ID = 'dotmd@dotmd';
+
+// Pure planner, mirroring planUpdate: the orchestration is unit-testable and
+// the side effects stay in the caller.
+export function planClaudeInstall({ installed, hasClaude, remove = false } = {}) {
+  if (remove) {
+    if (!installed) return [{ kind: 'skip', reason: 'dotmd plugin is not installed' }];
+    return hasClaude
+      ? [{ kind: 'run', cmd: ['claude', 'plugin', 'uninstall', installed.id] }]
+      : [{ kind: 'manual', lines: [`/plugin uninstall ${installed.id}`] }];
+  }
+  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.
+  if (!hasClaude) {
+    return [{ kind: 'manual', lines: [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin install ${CLAUDE_PLUGIN_ID}`] }];
+  }
+  return [
+    { kind: 'run', cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+    { kind: 'run', cmd: ['claude', 'plugin', 'install', CLAUDE_PLUGIN_ID] },
+  ];
+}
+
+export function removeOpencodePlugin(opts = {}) {
+  const { dryRun = false, force = false, ...rest } = opts;
+  const status = opencodeStatus(rest);
+  if (!status.exists) return { ...status, action: 'absent' };
+  if (status.foreign && !force) {
+    return { ...status, action: 'refused', reason: 'not a dotmd-generated file' };
+  }
+  if (!dryRun) rmSync(status.path, { force: true });
+  return { ...status, action: 'removed' };
+}

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/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) {