dotmd-cli 0.87.2 → 0.89.1

package/README.md

@@ -37,13 +37,28 @@ integration for whichever host you run:
 ```bash
 runlist install             # what's installed for each host
 runlist install claude      # Claude Code plugin (marketplace + plugin)
+runlist install codex       # Codex skill and hooks (personal marketplace)
 runlist install opencode    # OpenCode plugin (one auto-discovered file)
 runlist doctor --session    # what identity runlist sees here, and from where
 ```
 
-Both are one-time and global; `runlist update` keeps them in step with the CLI.
-Codex needs no install for identity: it exports `CODEX_THREAD_ID` to every tool
-shell, and runlist reads it as a per-session identity automatically.
+The integrations are one-time and global. Codex exports `CODEX_THREAD_ID` to
+every tool shell, so its identity works without the plugin; the plugin adds a
+workflow skill, session orientation, and the tool guard.
+
+### Codex Plugin
+
+`runlist install codex` copies the plugin included in the npm package into the
+personal Codex marketplace and runs `codex plugin add runlist-codex@personal`.
+Codex asks you to review and trust plugin hooks separately. Start a new thread
+after installation so the skill and SessionStart primer load. The hooks use
+the globally installed `runlist` CLI; a missing CLI produces one install hint
+and otherwise leaves tool calls alone. `CODEX_THREAD_ID` stays the ownership
+source. The CLI refuses to overwrite a plugin directory it did not generate.
+
+Direct prompt reads warn by default in Codex and Claude. A repository can set
+`export const guard = { promptReads: 'deny' };` to block reads of existing
+pending prompts; `runlist prompts show` remains the read-only inspection verb.
 
 ### Claude Code Plugin
 
@@ -72,6 +87,9 @@ supplies the two things the CLI cannot get on its own:
 - **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 `runlist hud`.
+- **Prompt-read guardrails.** Recognized reads are checked before execution so
+  the opt-in strict policy can stop them. Default warnings are attached to the
+  result because OpenCode's before hook cannot return model context.
 
 Restart OpenCode after installing. The file is version-stamped (`runlist-generated:`, or
 `dotmd-generated:` from older releases); a `dotmd.js` without either stamp is
@@ -131,7 +149,15 @@ runlist 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.
+of work never has two resume prompts. Inspect the pending handoff with
+`runlist prompts show <slug>`. Keep it if current; if stale, pass `--replace`
+with a new draft. Baton archives the previous text and refreshes the pending
+prompt in the same operation as any plan release.
+
+Repositories with a commit wrapper can export `batonCommitCommand(message, paths)`
+from `dotmd.config.mjs` and return an argv array such as
+`['just', 'commit', message, ...paths]`. Baton quotes the printed command and
+excludes session prompts from `paths`.
 
 Saved prompts are local session state. Consume them with `runlist use`; inspect
 without consuming via `runlist prompts show`. Consuming a baton prompt also claims

package/assets/opencode/plugin.js

@@ -11,10 +11,8 @@
 //     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 "runlist does nothing here"
-//     rather than to a broken session.
+//  2. Only a deliberate guard denial may throw. OpenCode awaits hooks inside
+//     the chat request, so every other failure degrades to a no-op.
 //
 // Runs under Bun inside the OpenCode process. Node builtins only, no deps.
 
@@ -64,12 +62,9 @@ function runCli(directory, args, input = null) {
   });
 }
 
-// OpenCode runs no Claude Code hooks, so `runlist 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.
+// OpenCode runs no Claude Code hooks. Evaluate recognized prompt reads before
+// the tool so opt-in strict mode can block them. Its V1 before hook cannot
+// return model context, so ordinary warnings are appended to the result.
 const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
 
 function guardPayload(tool, args) {
@@ -86,6 +81,14 @@ 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();
+  const guardDecisions = new Map();
+
+  async function guardFor(tool, args) {
+    const payload = guardPayload(tool, args);
+    if (!payload) return null;
+    const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+    return raw ? JSON.parse(raw)?.hookSpecificOutput ?? null : null;
+  }
 
   async function primerFor(sessionId) {
     const key = sessionId ?? '';
@@ -101,6 +104,18 @@ export default async function dotmdOpencodePlugin({ directory }) {
   }
 
   return {
+    'tool.execute.before': async (input, output) => {
+      let refusal = null;
+      try {
+        const decision = await guardFor(input?.tool, output?.args);
+        if (input?.callID && decision) guardDecisions.set(input.callID, decision);
+        if (decision?.permissionDecision === 'deny') {
+          if (input?.callID) guardDecisions.delete(input.callID);
+          refusal = decision.permissionDecisionReason;
+        }
+      } catch { /* a missing/broken guard must not fail the chat turn */ }
+      if (refusal) throw new Error(`[runlist] ${refusal}`);
+    },
     // Ownership identity. OpenCode sets no session-id variable of its own, and
     // `OPENCODE_PID` — what runlist falls back to without this plugin — names the
     // OpenCode *process*, so every session in one TUI shares it and can release
@@ -126,10 +141,10 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // 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 output?.output !== 'string') return;
+        const decision = input?.callID ? guardDecisions.get(input.callID) : null;
+        if (input?.callID) guardDecisions.delete(input.callID);
+        const note = (decision ?? await guardFor(input?.tool, input?.args))?.additionalContext;
         if (typeof note === 'string' && note) output.output += `\n\n${note}`;
       } catch { /* a guard failure never touches the tool result */ }
     },

package/bin/dotmd.mjs

@@ -147,8 +147,9 @@ with a one-line recap naming the habit to break.`,
 
   runlist install                report what is installed for each known host
   runlist install claude         install the Claude Code plugin (marketplace + plugin)
+  runlist install codex          install/refresh the Codex plugin (personal marketplace)
   runlist install opencode       install/refresh the OpenCode plugin (global config dir)
-  runlist install <host> --remove
+  runlist install opencode --remove
   runlist install opencode --path <dir>   write to a specific plugin directory
   runlist install opencode --force        overwrite a runlist.js runlist did not write
 
@@ -168,6 +169,12 @@ host gets that a different way:
             under extraKnownMarketplaces with a source that no longer matches;
             runlist names the field but never edits that file.
 
+  codex     Copies the npm-packaged runlist-codex plugin into the personal
+            marketplace and invokes \`codex plugin add\`. It supplies a compact
+            skill, SessionStart orientation, and a PreToolUse guard. Codex
+            requires a separate hook trust review; start a new thread after
+            installing. CODEX_THREAD_ID remains the ownership identity.
+
   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
@@ -302,7 +309,7 @@ Create & Export:
 
 Setup:
   init                              Create starter config + docs directory
-  install [opencode]                Install the agent-host integration (no arg = status)
+  install [claude|codex|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
@@ -849,7 +856,7 @@ Modes:
   --migrate-prompts      Retrofit pre-existing markdown files under any docs
                          root's prompts/ subdirectory with proper prompt
                          frontmatter (type, status, created from git
-                         history, dotmd_version, context, related_plans).
+                         history, runlist_version, context, related_plans).
                          Skips files that already have frontmatter.
   --migrate-template <file>  Migrate just one plan.
   --migrate-template --include-archived
@@ -1271,13 +1278,21 @@ Options:
   --note "why"           Append the reason to ## Version History (plan mode only)
   --message / --body     Inline body (one-liners; prefer @path or stdin)
   --force                Recover another session's plan (explicit path required)
+  --replace              Replace exactly one pending handoff; archive its prior text
   --json                 Structured repository/session/generated file result
   --dry-run, -n          Preview without writing
 
+Repo-specific commit hint (dotmd.config.mjs):
+  export function batonCommitCommand(message, paths) {
+    return ['just', 'commit', message, ...paths];
+  }
+The function returns argv; baton shell-quotes each argument before printing.
+
 Examples:
   runlist baton @/tmp/draft.md
   runlist baton checkout-fixes @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/draft.md
+  runlist baton docs/plans/auth.md @/tmp/new-draft.md --replace
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
   cat /tmp/draft.md | runlist baton
 
@@ -1296,11 +1311,13 @@ cooperating transaction:
   grant ownership. A live pickup-hook delivery lease blocks release and force
   takeover; hooks are at-least-once and deduplicate the stable operationId.
 
-Slug mode (no plan involved) saves resume-<slug> and touches nothing else: no
-status change, no commit. A bare word that names a plan is treated as that plan.
+Slug mode (no plan involved) saves resume-<slug> without a status change or
+commit. A bare word that names a plan is treated as that plan.
 
 Baton saves nothing while a handoff for the same work is pending (resume-<name>,
-or a pending prompt linked to the plan): consume or archive it, then re-run.
+or a pending prompt linked to the plan): inspect it with \`runlist prompts show\`.
+Keep it if current; use \`--replace\` with a new draft if stale. Replacement
+preserves the prior text under archived/ and refuses multiple matches.
 With no @file, \`-\` or --message, baton reads stdin only when something is piped
 in; an open pipe that sends nothing is given up on after a moment.`,
 

package/package.json

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

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

@@ -0,0 +1,18 @@
+{
+  "name": "runlist-codex",
+  "version": "0.89.1",
+  "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
+  "author": {
+    "name": "Reo Owens"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Runlist Codex",
+    "shortDescription": "Plan, handoff, and document workflow for Codex.",
+    "longDescription": "Adds a concise runlist skill, session primer, and prompt/status guard hooks for managed Markdown repositories.",
+    "developerName": "Reo Owens",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": "Show my runlist plans and pending handoffs."
+  }
+}

package/plugins/runlist-codex/bin/runlist-hook

@@ -0,0 +1,86 @@
+#!/bin/sh
+# runlist Codex plugin hook wrapper.
+#
+# The plugin's hooks drive the whole workflow through the PATH `runlist` binary
+# (`runlist hud`, `runlist guard`), falling back to the legacy `dotmd` alias. If a user enables the plugin but hasn't run
+# `npm i -g dotmd-cli`, the binary is missing, the hook errors `command not
+# found`, and the session is primed with *silent nothing* — no signal that the
+# whole workflow is one install away. runlist can't warn about its own absence
+# (it's the thing that's missing), so the check lives here, outside the binary.
+#
+# Usage: runlist-hook [--hint] <runlist-subcommand> [args...]
+#   --hint  emit a one-line install hint to stdout when no CLI is on PATH.
+#           Only SessionStart passes this, so the hint surfaces once per hook
+#           invocation (stdout becomes session context), never on a tool call.
+#
+# When the CLI is missing we always exit 0 with no further output: hooks must
+# stay non-blocking, and the PreToolUse guard in particular must never deny a
+# tool just because the optional CLI isn't installed.
+hint=0
+if [ "$1" = "--hint" ]; then
+  hint=1
+  shift
+fi
+
+if command -v runlist >/dev/null 2>&1; then
+  CLI=runlist
+elif command -v dotmd >/dev/null 2>&1; then
+  CLI=dotmd
+else
+  if [ "$hint" = "1" ]; then
+    echo "runlist plugin: neither \`runlist\` nor \`dotmd\` is on PATH, so its hooks are no-ops. Enable the workflow with: npm i -g dotmd-cli"
+  fi
+  exit 0
+fi
+
+# PreToolUse fast path: the guard fires on matched Bash, apply_patch, and MCP
+# read calls, and
+# a full Node boot (~100ms: CLI startup + config discovery) is pure overhead for
+# the vast majority of payloads no guard rule can possibly match. Every rule
+# needs a `.md` path AND either a prompts/ path (commit/cat/read-prompt) or the
+# word `status` (edit-status) somewhere in the payload — a cheap shell glob
+# decides that without leaving sh. Anything else gets the no-opinion reply
+# (`{}`) directly. False positives here just pay the old cost (Node runs and
+# returns {}); false negatives are impossible because the globs are strictly
+# weaker than the rules they gate.
+if [ "$1" = "guard" ]; then
+  payload=$(cat)
+  # Broad Git forms do not name a .md file in the payload; Node inspects the
+  # actual eligible/staged path set before deciding whether a live prompt is
+  # included. Always route those forms through the guard.
+  case "$payload" in
+    *git*add*|*git*stage*|*git*commit*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit $?
+      ;;
+  esac
+  case "$payload" in
+    *.md*)
+      case "$payload" in
+        *prompts/*|*prompts\\*|*status*)
+          printf '%s' "$payload" | "$CLI" "$@"
+          exit $?
+          ;;
+      esac
+      ;;
+  esac
+  printf '{}\n'
+  exit 0
+fi
+
+# UserPromptSubmit fast path is retained for compatibility with the Claude
+# wrapper; Codex does not register that hook here. It would fire on every
+# message that asks for a handoff gets an answer. The glob is strictly weaker
+# than the Node-side match, so a skipped payload could never have matched.
+if [ "$1" = "hud" ] && [ "$2" = "--prompt-submit" ]; then
+  payload=$(cat)
+  case "$payload" in
+    *[Bb][Aa][Tt][Oo][Nn]*|*[Hh][Aa][Nn][Dd]*[Oo][Ff][Ff]*|*[Rr][Ee][Ss][Uu][Mm][Ee]*|*[Pp][Ii][Cc][Kk]*[Uu][Pp]*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit 0
+      ;;
+  esac
+  exit 0
+fi
+
+exec "$CLI" "$@"

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

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" --hint hud", "timeout": 5 }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|mcp__.*__(read_file|read_text_file|read_media_file|read_multiple_files)",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" guard", "timeout": 5 }]
+      }
+    ]
+  }
+}

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: runlist
+description: Manage a repository's plans, docs, decisions, and saved prompts with the runlist CLI. Use when starting or closing plan work, checking the plan queue, or creating or consuming a handoff.
+---
+
+# Runlist workflow
+
+Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`. The CLI is `runlist` (from `dotmd-cli`; `dotmd` remains an alias). The session hook prints a short live orientation. `CODEX_THREAD_ID` is the session identity used for plan claims; do not replace it with a process ID.
+
+- Orient with `runlist plans`. Use `runlist agent-context` for structured state; `runlist briefing` is the comprehensive view and can be large.
+- Start plan work with `runlist use <plan-file>`. It claims the plan, marks it `in-session`, and prints the card.
+- Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
+- Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
+- For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
+- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. For read-only triage, use `runlist prompts show <file>` or `runlist prompts show --all`; never open pending prompts with a file reader or `cat`.
+- Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
+- Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.
+- Record a decision with `runlist new decision <plan> --question "…" @<record-file>`; configured registers may also require `--answers`.
+- If a lifecycle mutation reports an abandoned transaction, inspect `runlist doctor --transactions` before retrying. Use `--apply` only for cases the doctor identifies as recoverable.
+
+The `PreToolUse` hook warns on direct pending-prompt reads and denies hand-edited status transitions or Git operations that would include a live prompt. A repo can opt into blocking direct reads of existing pending prompts with `guard: { promptReads: 'deny' }`. Archived prompts and `runlist prompts show` remain readable. Codex requires explicit trust of a plugin's hooks before they run.

package/runlist.config.example.mjs

@@ -13,6 +13,11 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
+// Agent-host tool guard: direct reads of existing pending prompts warn by
+// default. Set promptReads to 'deny' to block those reads before execution;
+// `runlist prompts show` and archived prompt reads remain available.
+// export const guard = { promptReads: 'deny' };
+
 // Floor under the scan surface. `runlist check` fails when it scans fewer docs than
 // this, so a broken root or an over-eager exclude can't read as a clean estate —
 // zero errors and zero docs look identical otherwise. Off when unset. Set it well

package/src/atomic-mutation.mjs

@@ -1159,7 +1159,7 @@ function reserveExclusive(filePath, mode, content, testHooks = {}) {
     fd = openSync(filePath, 'wx', mode);
     const opened = fstatSync(fd, { bigint: true });
     openedIdentity = { dev: opened.dev, ino: opened.ino };
-    const reservationContent = content ?? JSON.stringify({ dotmdReservation: true, pid: process.pid, createdAt: new Date().toISOString() }) + '\n';
+    const reservationContent = content ?? JSON.stringify({ runlistReservation: true, pid: process.pid, createdAt: new Date().toISOString() }) + '\n';
     writeFileSync(fd, reservationContent, 'utf8');
     testHooks.afterReserveWrite?.(filePath);
     testHooks.beforeReserveFsync?.(filePath);
@@ -1310,6 +1310,10 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
     // transaction manifest exists, so a guard conflict can never leave a
     // transaction to recover from.
     for (const guard of guards) {
+      if (guard.absent) {
+        if (existsSync(guard.path)) throw new MutationConflictError(`File appeared while the move mutation set was being prepared: ${path.resolve(guard.path)}`);
+        continue;
+      }
       const snapshot = snapshotFile(guard.path);
       if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
         throw new MutationConflictError(`File changed while the move mutation set was being prepared: ${snapshot.path}`);
@@ -1353,7 +1357,7 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       for (const item of creations) ensureTransactionDirectory(path.dirname(item.path), transaction, options, item.path);
       try {
         reservation = reserveExclusive(targetPath, source.identity.mode, JSON.stringify({
-          dotmdReservation: true,
+          runlistReservation: true,
           transactionId,
           sourcePath,
           backup,
@@ -1657,6 +1661,10 @@ export function mutateFileSet({ updates = [], creations = [], guards = [] }, opt
     // is created — a guard conflict must leave the tree byte-identical, not even
     // an empty directory behind.
     for (const guard of guards) {
+      if (guard.absent) {
+        if (existsSync(guard.path)) throw new MutationConflictError(`File appeared while the mutation set was being prepared: ${path.resolve(guard.path)}`);
+        continue;
+      }
       const snapshot = snapshotFile(guard.path);
       if (guard.expectedContent !== undefined && snapshot.content !== guard.expectedContent) {
         throw new MutationConflictError(`File changed while the mutation set was being prepared: ${snapshot.path}`);