@jeffober/thatch 0.1.43 → 0.1.45

package/src/index.ts

@@ -1,4 +1,6 @@
 import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { createDebugLog } from "./debug";
 import type { Plugin } from "@opencode-ai/plugin";
 import { ThatchDB } from "./db";
 import { BgeEmbeddingModel } from "./embeddings";
@@ -24,7 +26,7 @@ import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
 import { WatcherRegistry, ghApiRun, ghAvailable } from "./watchers";
 import { watcherNotificationNudge, chatNotificationNudge, chatEchoText, isChatEchoParts } from "./prompts";
-import { ChatPoller, isDefaultSessionTitle, slugifyTitle } from "./chat";
+import { ChatPoller, createWakeGate, isDefaultSessionTitle } from "./chat";
 import { chatEnabled, chatAutoRegister, loadConfig } from "./config";
 import pkg from "../package.json";
 
@@ -62,6 +64,104 @@ const WRAPUP_COMMANDS: Record<string, { token: string; kind: "compact" | "exit"
   "thatch/exit": { token: EXIT_READY_TOKEN, kind: "exit" },
 };
 
+/**
+ * Parses the session id a harness was started to continue from an argument
+ * list (`opencode -s <id>` / `--session <id>` / `--session=<id>`). Pure:
+ * the caller supplies the list (see startupSessionId for where it comes
+ * from). The framework passes no session id to plugins and resuming a
+ * session fires no events, so the command line is the only signal that a
+ * fresh harness is the new home of a continued session.
+ */
+export function startupSessionIdFromArgv(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-s" || arg === "--session") return argv[i + 1] ?? null;
+    if (arg.startsWith("--session=")) return arg.slice("--session=".length) || null;
+  }
+  return null;
+}
+
+/**
+ * Whether the harness was started with `-c`/`--continue` (continue the most
+ * recent session). Pure. Yargs-style boolean flags only: `--continue=false`
+ * reads as the negation, everything else as a plain switch. The session id
+ * itself is not on the command line - the harness resolves "most recent
+ * top-level session" at startup, which the plugin replicates via the SDK
+ * (continuesLastSessionId).
+ */
+export function continuesLastSessionFromArgv(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === "-c" || arg === "--continue") return true;
+    if (arg.startsWith("--continue=")) return arg.slice("--continue=".length) !== "false";
+  }
+  return false;
+}
+
+/**
+ * Picks the session `opencode -c` continues: the most recently updated
+ * top-level session. Pure; the caller supplies the session list from
+ * client.session.list() (directory-scoped, like the plugin's own client).
+ * The server's list order is not trusted - the TUI re-sorts by
+ * time.updated before picking, and so does this.
+ */
+export function continuesLastSessionId(
+  sessions: { id: string; parentID?: string; time?: { updated?: number } }[],
+): string | null {
+  return (
+    [...sessions]
+      .sort((a, b) => (b.time?.updated ?? 0) - (a.time?.updated ?? 0))
+      .find((s) => !s.parentID)?.id ?? null
+  );
+}
+
+// The plugin does not run in the process's main thread: opencode's TUI
+// spawns a worker thread (cli/tui/worker.js) to host the server, and worker
+// threads get their own argv (just the worker script) with none of the CLI
+// flags. The thread still shares the process's pid, so the OS-level command
+// line for our own pid is the real `opencode -s ses_...` invocation. Read it
+// from /proc on Linux or via ps on macOS. Returns [] when unavailable;
+// callers treat that as "no session flag". The readers are injectable so
+// tests can drive each branch without a real /proc or ps.
+export interface OsArgsDeps {
+  /** Reads a file as UTF-8, throwing when it does not exist. */
+  readFile: (path: string) => string;
+  /** Runs `ps -p <pid> -o args=`; returns its exit code and stdout. */
+  ps: (pid: number) => { exitCode: number; stdout: string };
+}
+
+const defaultOsArgsDeps: OsArgsDeps = {
+  readFile: (path) => readFileSync(path, "utf8"),
+  ps: (pid) => {
+    const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "args="]);
+    return { exitCode: res.exitCode, stdout: res.stdout.toString() };
+  },
+};
+
+export function osProcessArgs(deps: OsArgsDeps = defaultOsArgsDeps, pid = process.pid): string[] {
+  try {
+    // Linux: cmdline is NUL-separated argv, exact and cheap.
+    return deps.readFile("/proc/self/cmdline").split("\0").filter(Boolean);
+  } catch {
+    // macOS has no /proc; ask ps for this pid's full command. Splitting on
+    // whitespace is safe for our purpose: session ids never contain spaces.
+    try {
+      const res = deps.ps(pid);
+      if (res.exitCode !== 0) return [];
+      return res.stdout.trim().split(/\s+/).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Resolve the session id this harness was launched to resume, if any:
+// prefer the thread-local argv (covers tests and any non-worker host), then
+// fall back to the process's OS-level command line (the real harness path).
+// The caller passes the OS command line in so it is read once per init.
+export function startupSessionId(osArgs: string[]): string | null {
+  return startupSessionIdFromArgv(process.argv) ?? startupSessionIdFromArgv(osArgs);
+}
+
 export const server: Plugin = async ({ client, worktree }) => {
   // The opencode server's cwd is wherever the server happened to start;
   // `worktree` is the project this plugin instance actually serves.
@@ -78,6 +178,9 @@ export const server: Plugin = async ({ client, worktree }) => {
   const chatOn = chatEnabled(loadConfig(dbPath).config);
 
   const db = new ThatchDB(dbPath);
+  // Opt-in diagnostics (THATCH_DEBUG), written to debug.log beside the db.
+  // See debug.ts for the tag filter semantics.
+  const debug = createDebugLog(dbPath);
   const model = new BgeEmbeddingModel(modelName);
   const extraction = new ExtractionPipeline();
 
@@ -119,22 +222,17 @@ export const server: Plugin = async ({ client, worktree }) => {
   // event stream, and a stale "idle" turns a wake into mid-turn context
   // injection (observed live: a session read mail mid-burst, contradicted
   // its own in-flight plan, and looped).
-  const canPromptSession = async (sessionID: string): Promise<boolean> => {
-    if (compacting.has(sessionID)) return false;
-    if (sessionStatus.get(sessionID) !== "idle") return false;
-    try {
+  const canPromptSession = createWakeGate({
+    isCompacting: (sessionID) => compacting.has(sessionID),
+    mappedStatus: (sessionID) => sessionStatus.get(sessionID),
+    fetchStatuses: async () => {
       const { data } = await client.session.status();
-      // The server's status map only carries ACTIVE sessions - it deletes
-      // the entry when a session goes idle (session/status.ts), so absent
-      // means idle. Fail closed on busy/retry, pass on idle-or-absent.
-      const live = data?.[sessionID];
-      return !live || live.type === "idle";
-    } catch (err) {
-      // Unreachable server: do not deliver (the mail stays pending).
+      return data ?? {};
+    },
+    onStatusError: (sessionID, err) => {
       console.error(`[thatch] status check failed for ${sessionID}: ${err}`);
-      return false;
-    }
-  };
+    },
+  });
 
   // In-memory watcher registry for proactive event notifications (GitHub PR
   // and branch watching, plus local command watches). Deliberately
@@ -187,24 +285,30 @@ export const server: Plugin = async ({ client, worktree }) => {
   });
   watchers.start();
 
-  // The proactive-prompt gate, shared by both delivery registries
-  // (watchers and chat). Two layers, in cost order: the compacting set and
-  // the event-fed sessionStatus map answer cheaply, and a final check
-  // verifies against the server's live status - the map is only as fresh
-  // as the event stream, and a stale "idle" turns a wake into mid-turn
-  // context injection (observed live: a session read mail mid-burst,
-  // contradicted its own in-flight plan, and looped).
+  // The session this harness was launched to resume, resolved at startup:
+  // `-s <id>` names it on the command line, `-c` means "most recent in this
+  // directory" and resolves through the SDK. Either way the poller hosts it
+  // from the first beat, so the heartbeat and delivery are live before the
+  // user's first prompt.
+  let resumedSession: string | null = null;
+
+  // Chat names assigned by the startup resume paths (-s and -c) wait here
+  // until the session's first message or idle event, which toast them. At
+  // plugin-init time the TUI is not yet connected, so an immediate toast
+  // would be dropped silently.
+  const chatStartupNames = new Map<string, string>();
+
   const chatPoller = new ChatPoller({
     store: db,
     hostedSessions: () => {
-      // Sub-agent children share this process's sessionStatus (their
-      // status events land here), but they are never legitimate chat
-      // participants - a registered child would be heartbeat-ed
-      // fresh-forever and burn nudge budget on undeliverable wake
-      // prompts. Keep them out of the hosted set even when guidance
-      // against registering them is ignored.
-      const hosted = [...sessionStatus.keys()].filter((id) => !childToParent.has(id));
-      return hosted;
+      // Hosting = the sessions this harness serves: those seen as events
+      // here (used in this TUI) plus the resumed startup session. Sub-agent
+      // children are excluded even if someone registered one - a
+      // registered child would be heartbeat-ed fresh-forever and burn
+      // nudge budget on undeliverable wake prompts.
+      const hosted = [...sessionStatus.keys()];
+      if (resumedSession) hosted.push(resumedSession);
+      return hosted.filter((id) => !childToParent.has(id));
     },
     deliver: async (sessionID, senders, count) => {
       await client.session.promptAsync({
@@ -231,6 +335,72 @@ export const server: Plugin = async ({ client, worktree }) => {
   // sessions and burn wake budget against a feature the user turned off.
   if (chatOn) chatPoller.start();
 
+  // Startup registration: `opencode -s <id>` continues a session whose
+  // directory row may predate this process (its harness died, or the
+  // machine restarted); `opencode -c` continues the most recent session in
+  // this directory. The framework passes no session id to plugins and
+  // resuming fires no events, so the command line is the source (see
+  // startupSessionId). Registering here RECLAIMS the row - the name is
+  // owned by the session id and never changes - and refreshes its
+  // heartbeat: synchronously for -s (local SQLite, it cannot fail on a
+  // server that is still starting); for -c after an SDK list call resolves
+  // the target. The async tail (title fetch, asleep-mail delivery) is
+  // best-effort - the poller retries whatever it misses, and the first
+  // idle converges the topic.
+  const reclaimTail = (sessionID: string) => {
+    void (async () => {
+      try {
+        const { data } = await client.session.get({ path: { id: sessionID } });
+        const title = data?.title ?? "";
+        const topic = title && !isDefaultSessionTitle(title) ? title : null;
+        if (topic) db.refreshChatTopic(sessionID, topic);
+      } catch {
+        // Server may still be starting; the topic converges on the
+        // session's first idle either way.
+      }
+      try {
+        // Asleep-mail: deliver what queued while this session was away,
+        // through the normal path (gate, nudge, toast, stamps).
+        await chatPoller.deliverPending();
+      } catch {
+        // The poller cycle retries delivery; nothing to do here.
+      }
+    })();
+  };
+  const osArgs = osProcessArgs();
+  const startupSession = startupSessionId(osArgs);
+  const continueLast = !startupSession && (continuesLastSessionFromArgv(process.argv) || continuesLastSessionFromArgv(osArgs));
+  const autoRegisterOn = chatAutoRegister(loadConfig(dbPath).config);
+  const tombstoned = startupSession ? db.hasChatLeaveTombstone(startupSession) : false;
+  debug("chat:startup", `init: argv=${JSON.stringify(process.argv.slice(0, 8))} osArgs=${JSON.stringify(osArgs.slice(0, 8))} parsed=${startupSession} continue=${continueLast} chatOn=${chatOn} autoRegister=${autoRegisterOn} tombstone=${startupSession ? tombstoned : "n/a"}`);
+  if (chatOn && autoRegisterOn && startupSession && !tombstoned) {
+    resumedSession = startupSession;
+    const res = db.registerChatSession(startupSession, repo, null, "opencode", null, detectWorktreeKind(worktree));
+    debug("chat:startup", `registration for ${startupSession}: ok=${res.ok} name=${res.ok ? res.name : res.error}`);
+    if (res.ok) {
+      chatStartupNames.set(startupSession, res.name);
+      reclaimTail(startupSession);
+    }
+  } else if (chatOn && autoRegisterOn && continueLast) {
+    void (async () => {
+      try {
+        const { data } = await client.session.list();
+        const target = continuesLastSessionId(data ?? []);
+        debug("chat:startup", `-c resolved: ${target ?? "none"}`);
+        if (!target || db.hasChatLeaveTombstone(target)) return;
+        resumedSession = target;
+        const res = db.registerChatSession(target, repo, null, "opencode", null, detectWorktreeKind(worktree));
+        debug("chat:startup", `registration for ${target}: ok=${res.ok} name=${res.ok ? res.name : res.error}`);
+        if (res.ok) {
+          chatStartupNames.set(target, res.name);
+          reclaimTail(target);
+        }
+      } catch (err) {
+        console.error(`[thatch] chat -c startup registration failed: ${err}`);
+      }
+    })();
+  }
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -592,6 +762,42 @@ export const server: Plugin = async ({ client, worktree }) => {
       // nothing (and fire spurious toasts when thresholds cross). Skip
       // them entirely.
       if (isChatEchoParts(output.parts)) return;
+
+      // Prompt-path registration: a brand-new session joins the chat
+      // directory the moment its first real user message arrives - before
+      // the model runs - so it is addressable within that first turn (the
+      // first-idle path alone leaves a turn-long dark window). Local
+      // SQLite, so it runs inline; on an already-registered session this
+      // is a free mid-turn heartbeat touch. Sub-agent children are excluded
+      // (they register only by mistake, and their deletion tombstones the
+      // row), as are sessions that left via chat_unregister. The idle path
+      // below stays as the backstop and converges the topic.
+      if (
+        chatOn &&
+        chatAutoRegister(loadConfig(dbPath).config) &&
+        input.sessionID &&
+        !childToParent.has(input.sessionID) &&
+        !db.hasChatLeaveTombstone(input.sessionID)
+      ) {
+        try {
+          const res = db.registerChatSession(input.sessionID, repo, null, "opencode", null, detectWorktreeKind(worktree));
+          // First registration - or a startup resume reclaiming its name,
+          // announced here because the TUI was not connected at init - is
+          // the one moment the user should notice: a quiet toast, not a
+          // conversation message.
+          if (res.ok && (res.created || chatStartupNames.has(input.sessionID))) {
+            chatStartupNames.delete(input.sessionID);
+            try {
+              await client.tui.showToast({ body: { message: res.created ? `registered in chat as ${res.name}` : `rejoined chat as ${res.name}`, variant: "info", duration: 4000 } });
+            } catch {
+              // Headless or disconnected TUI - registration stands.
+            }
+          }
+        } catch (err) {
+          console.error(`[thatch] chat prompt-register failed for ${input.sessionID}: ${err}`);
+        }
+      }
+
       if (compacting.has(input.sessionID)) {
         // The session is marked as compacting. If this message is the
         // compaction summary generation itself (has a compaction-type part),
@@ -966,20 +1172,37 @@ export const server: Plugin = async ({ client, worktree }) => {
         // Auto-registration: every top-level opencode session joins the
         // chat directory on its first idle event (unless the user turned
         // auto-registration off). The name is assigned, never chosen - a
-        // slug of the session title plus a never-reused counter - and the
-        // live title rides the topic column, refreshed on every idle so the
-        // roster tracks what the session is actually working on. Titles are
-        // usually placeholders at first idle and real within a turn or two,
-        // so both name and topic converge fast. Fire-and-forget: a failed
-        // registration or title fetch must never block event delivery.
+        // pool draw plus a never-reused counter, kept short because it
+        // appears in wake prompts and rosters. The live session title rides
+        // the topic column instead (refreshed on every idle), so the name
+        // and the description stay separate identities. Fire-and-forget: a
+        // failed registration or title fetch must never block event
+        // delivery.
         if (chatOn && chatAutoRegister(loadConfig(dbPath).config) && sessionID && !db.hasChatLeaveTombstone(sessionID)) {
           void (async () => {
             try {
               const { data } = await client.session.get({ path: { id: sessionID } });
               const title = data?.title ?? "";
-              const base = title && !isDefaultSessionTitle(title) ? slugifyTitle(title) : null;
-              db.registerChatSession(sessionID, repo, base ? title : null, "opencode", base, detectWorktreeKind(worktree));
-              if (base) db.refreshChatTopic(sessionID, title);
+              // Placeholder titles never become topics (the real one
+              // converges on a later idle via refreshChatTopic).
+              const topic = title && !isDefaultSessionTitle(title) ? title : null;
+              const res = db.registerChatSession(sessionID, repo, topic, "opencode", null, detectWorktreeKind(worktree));
+              // The topic converges as the auto-titler lands a real title:
+              // registration is once-per-session, so later idles must
+              // refresh it explicitly.
+              if (res.ok && topic) db.refreshChatTopic(sessionID, topic);
+              // First registration - or a startup resume reclaiming its
+              // name, announced here because the TUI was not connected at
+              // init - is the one moment the user should notice: a quiet
+              // toast, not a conversation message.
+              if (res.ok && (res.created || chatStartupNames.has(sessionID))) {
+                chatStartupNames.delete(sessionID);
+                try {
+                  await client.tui.showToast({ body: { message: res.created ? `registered in chat as ${res.name}` : `rejoined chat as ${res.name}`, variant: "info", duration: 4000 } });
+                } catch {
+                  // Headless or disconnected TUI - registration stands.
+                }
+              }
             } catch (err) {
               console.error(`[thatch] chat auto-register failed for ${sessionID}: ${err}`);
             }

package/src/mcp.ts

@@ -1,10 +1,13 @@
 import { resolve } from "node:path";
 import { z } from "zod";
 import { ThatchDB } from "./db";
+import { mcpSessionID } from "./chat";
 import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
 import { checkSetup, setupClaudeCode, setupCursor } from "./setup";
 import { TOOL_DEFS, type CoreContext, type ToolDef } from "./tool-defs";
+import { actionDefs, type ActionDef } from "./commands";
+import { mcpToolName } from "./prompts";
 import { SidebandServer, sidebandSocketPath } from "./sideband";
 import { peekQueue, consumeQueue, resetMissedCount } from "./extract-queue";
 import { buildExtractionPayload } from "./extraction";
@@ -43,11 +46,13 @@ const SERVER_NAME = "thatch";
 const SERVER_VERSION = pkg.version;
 
 /**
- * MCP capabilities declared in the initialize response. Thatch is a tools-only
- * server - no resources, prompts, or subscriptions.
+ * MCP capabilities declared in the initialize response. Tools plus the
+ * prompts that Cursor surfaces as slash commands; no resources or
+ * subscriptions.
  */
 const CAPABILITIES = {
   tools: { listChanged: false },
+  prompts: { listChanged: false },
 };
 
 // ---------------------------------------------------------------------------
@@ -76,6 +81,25 @@ export function compileTools(): Map<string, CompiledTool> {
   return map;
 }
 
+// ---------------------------------------------------------------------------
+// Prompt index - the on-demand actions Cursor surfaces as slash commands
+// ---------------------------------------------------------------------------
+
+/**
+ * The prompts the MCP server exposes: the shared actions minus the
+ * opencode-only ones. Prompts render the same instruction bodies as the
+ * command files (src/commands.ts) without the $ARGUMENTS section - the
+ * optional focus argument stands in for it.
+ */
+export function compilePrompts(): Map<string, ActionDef> {
+  const map = new Map<string, ActionDef>();
+  for (const def of actionDefs(mcpToolName)) {
+    if (def.opencodeOnly) continue;
+    map.set(def.name, def);
+  }
+  return map;
+}
+
 // ---------------------------------------------------------------------------
 // MCP server
 // ---------------------------------------------------------------------------
@@ -134,8 +158,24 @@ export async function runMcpServer(): Promise<void> {
     defaultStore: repo,
     extractionPayloadProvider,
     drainExtractionQueue,
+    // Claude Code identity anchor, two model-proof layers:
+    //  1. The hooks record (parent pid -> session) from payloads the model
+    //     cannot influence, and this server is a child of the same Claude
+    //     Code process - current even after a session fork.
+    //  2. CLAUDE_CODE_SESSION_ID, set by the host in this server's env at
+    //     spawn ("retains the ID it was spawned with") - covers the case
+    //     where hook and server parent pids diverge, but goes stale after a
+    //     fork/continue, so it is the fallback, not the primary.
+    // A miss on both falls back to the caller-claimed `as` (Cursor).
+    chatDerivedIdentity: () => {
+      const mapped = db.findChatSessionByHostPid(process.ppid, 600);
+      if (mapped) return mapped;
+      const envID = process.env.CLAUDE_CODE_SESSION_ID;
+      return envID ? db.findChatSession(mcpSessionID(envID))?.session_id ?? null : null;
+    },
   };
   const tools = compileTools();
+  const prompts = compilePrompts();
 
   // Check whether `thatch setup` was run for the current host. If not, or if
   // markers are broken, surface a warning on the first tools/call response so
@@ -232,7 +272,7 @@ export async function runMcpServer(): Promise<void> {
 
       // Notifications (no id) are fire-and-forget - no response expected.
       const isNotification = req.id === null || req.id === undefined;
-      const res = await dispatch(req, tools, ctx);
+      const res = await dispatch(req, tools, prompts, ctx);
       if (res === null || isNotification) continue;
 
       // Surface the setup warning on the first tools/call response so the
@@ -274,6 +314,7 @@ export async function runMcpServer(): Promise<void> {
 async function dispatch(
   req: JsonRpcRequest,
   tools: Map<string, CompiledTool>,
+  prompts: Map<string, ActionDef>,
   ctx: CoreContext,
 ): Promise<JsonRpcResponse | null> {
   const { id, method } = req;
@@ -339,6 +380,40 @@ async function dispatch(
         }
       }
 
+      case "prompts/list":
+        return ok(id, {
+          prompts: [...prompts.values()].map((p) => ({
+            name: p.name,
+            description: p.description,
+            arguments: [
+              {
+                name: "focus",
+                description: "Optional scope for the action, e.g. which store to work on",
+                required: false,
+              },
+            ],
+          })),
+        });
+
+      case "prompts/get": {
+        const prompt = prompts.get(req.params?.name);
+        if (!prompt) {
+          return {
+            jsonrpc: "2.0",
+            id,
+            error: { code: METHOD_NOT_FOUND, message: `Unknown prompt: ${req.params?.name}` },
+          };
+        }
+        const focus = req.params?.arguments?.focus;
+        const text = focus
+          ? `${prompt.body}\n\nFocus: ${focus}`
+          : prompt.body;
+        return ok(id, {
+          description: prompt.description,
+          messages: [{ role: "user", content: { type: "text", text } }],
+        });
+      }
+
       case "ping":
         return ok(id, {});
 

package/src/prompts.ts

@@ -20,8 +20,8 @@ const chatPromptSection = `
 
 Sessions on this machine - opencode, Claude Code, and Cursor alike - can
 message each other through thatch. opencode sessions join the directory
-automatically: your display name is assigned by thatch (a slug of your
-session title plus a counter, e.g. fix-auth-bug-00001) and is never
+automatically: your display name is assigned by thatch (a name drawn from
+a built-in pool plus a counter, e.g. al-go-rithm-00001) and is never
 reassigned or reused, so a given name is always the same session.
 thatch_chat_register with no arguments reports your name or rejoins after
 unregistering. On MCP hosts, pass the name your thatch hook printed as the
@@ -620,6 +620,59 @@ export function versionWarningNudge(message: string): string {
   return `[thatch] ${message} This is a system nudge, not user input. After informing the user, continue with their request.`;
 }
 
+// ---------------------------------------------------------------------------
+// Prompt cores - behavior instruction bodies shared by nudges and /thatch
+// command files (src/commands.ts). A core is the host-agnostic instruction
+// body for one behavior. The nudge envelope adds escalation tiers and the
+// stop-and-wait ending; the command envelope adds frontmatter and the
+// user-message section. The stop-and-wait ending is nudge-only: a /thatch
+// command IS user input, so it must not inherit it.
+//
+// Cores take a ToolNamer because tool spellings differ per host
+// (thatch_find_duplicates on opencode, mcp__thatch__find_duplicates on MCP
+// hosts); the renderer for each host passes its own namer.
+// ---------------------------------------------------------------------------
+
+/** Maps a bare tool name to the host's spelling. */
+export type ToolNamer = (name: string) => string;
+
+export const opencodeToolName: ToolNamer = (name) => `thatch_${name}`;
+export const mcpToolName: ToolNamer = (name) => `mcp__thatch__${name}`;
+
+/**
+ * The extraction instruction body. sessionIdArg is either ` with session_id
+ * "X"` (the nudge path: the sub-agent's session differs from the parent's)
+ * or an omit note (the invoking session's ID is the default).
+ */
+export function extractionCore(fetchTool: string, drainTool: string, sessionIdArg: string): string {
+  return `Call ${fetchTool}${sessionIdArg} to retrieve the queued tool interactions, then run the thatch-fact-extractor skill to extract durable facts. Call ${drainTool}${sessionIdArg} when finished, even if nothing was worth saving.`;
+}
+
+/**
+ * The memory consolidation (defrag) instruction body. Shared by the
+ * /thatch/defrag command file and the MCP prompt of the same name.
+ */
+export function defragCore(tool: ToolNamer): string {
+  return `Run ${tool("find_duplicates")} to surface duplicate-candidate memory pairs and clusters. For each pair or cluster, read every memory with ${tool("memory_show")}, classify the relationship, and consolidate per the thatch-dedup-classifier skill: merge duplicates (${tool("memory_remember")} with overwrite: true, then ${tool("memory_forget")} the rest), update supplements, keep contradictions, and call ${tool("dedup_mark_checked")} on every pair you are not deleting so it stops being re-reported. Call ${tool("find_duplicates")} again at the end to verify the store is clean, and summarize what you merged, kept, and deleted.`;
+}
+
+/**
+ * The memory hygiene instruction body. Shared by the /thatch/hygiene command
+ * file and the MCP prompt of the same name. Drives the thatch CLI (not
+ * memory tools), so it needs no tool namer.
+ */
+export function hygieneCore(): string {
+  return `Run the shell command "thatch hygiene" to print the hygiene report for the current repo store. It lists duplicate-candidate pairs pending review, memories gone stale, and memories scoped to deleted branches. For each finding, act: consolidate duplicates with the thatch-dedup-classifier workflow, correct or overwrite stale memories that are simply out of date, and consolidate branch-scoped memories into one archived record when their branch is gone. Ask the user before forgetting anything that may still matter. Re-run "thatch hygiene" at the end to confirm the store is healthy, and summarize what you changed.`;
+}
+
+/**
+ * The session reflection instruction body. Shared by the /thatch/reflect
+ * command file and the MCP prompt of the same name.
+ */
+export function reflectCore(tool: ToolNamer): string {
+  return `Run the thatch-session-reflection skill to persist what this session learned: follow the skill's instructions and record each distinct learning with ${tool("memory_remember")}. When the skill's checklist is worked through, report a one-line summary of what you saved.`;
+}
+
 /**
  * Extraction nudge with escalation. Both the opencode plugin (src/index.ts)
  * and the Claude Code/Cursor CLI (bin/thatch flush-tools) call this with
@@ -682,7 +735,8 @@ function buildExtractionNudge(
   sessionID: string,
 ): string {
   const acknowledge = `After dispatching, call ${drainTool} to acknowledge.`;
-  const subAgentPrompt = `Call ${fetchTool} with session_id "${sessionID}" to retrieve the queued tool interactions, then run the thatch-fact-extractor skill to extract durable facts. Call ${drainTool} with session_id "${sessionID}" when finished, even if nothing was worth saving.`;
+  const sessionIdArg = ` with session_id "${sessionID}"`;
+  const subAgentPrompt = extractionCore(fetchTool, drainTool, sessionIdArg);
 
   if (missedCount >= 3) {
     return `[thatch] YOU ARE IGNORING EXTRACTION INSTRUCTIONS. ` +