@jeffober/thatch 0.2.5 → 0.2.7

package/src/opencode/v2.ts

@@ -5,11 +5,11 @@ import type { ToolContext as V2ToolContext } from "@opencode/plugin/promise/tool
 import type { ThatchDB } from "../db";
 import type { HostCapabilities, PromptPart, ToastInput } from "../capabilities";
 import { createRuntime } from "../runtime";
-import { wrapUpCommandContent } from "../commands";
+import { wrapUpCommandContent, wrapUpCommandDescription } from "../commands";
 import { deriveTitle } from "../extraction";
 import { detectRepo, detectWorktreeKind } from "../git";
 import { chatEnabled, loadConfig } from "../config";
-import { SESSION_TAB_RPC, TAB_CLOSED_EVENT, TAB_OPENED_EVENT, buildSubordinatePrompt, tabClosedEventType, tabOpenedEventType } from "../session-tab-shared";
+import { EXIT_TAB_CLOSED_EVENT, SESSION_TAB_RPC, TAB_CLOSED_EVENT, TAB_OPENED_EVENT, TOAST_EVENT, buildSubordinatePrompt, tabClosedEventType, tabOpenedEventType } from "../session-tab-shared";
 import { TOOL_DEFS, trimHostContext, type HostToolContext, type SessionTabCloseInput, type SessionTabHost, type SessionTabSpawnInput, type SessionTabSpawnResult } from "../tool-defs";
 
 // The opencode v2 adapter (opencode 2.x, plugin API @opencode/plugin 2.x).
@@ -29,9 +29,9 @@ import { TOOL_DEFS, trimHostContext, type HostToolContext, type SessionTabCloseI
 //   array; the runtime's plain strings convert to {type: "text", text}
 //   parts at the boundary.
 // - per-message nudges: the prompt hook computes the turn's injections;
-//   the generate hook appends them to the outbound request's last user
-//   message `content` array (v2 wire Messages have no `parts` field).
-//   Injections stay out of the stored prompt text.
+//   the context hook appends them to the outbound request's user message
+//   that matches the entry's prompt text (v2 wire Messages have no
+//   `parts` field). Injections stay out of the stored prompt text.
 // - noReply deliveries (chat echoes, session-start reminder): v2's prompt
 //   endpoint cannot suppress the model turn, so the runtime gates them off
 //   via capabilities.noReplyDelivery.
@@ -46,18 +46,52 @@ import { TOOL_DEFS, trimHostContext, type HostToolContext, type SessionTabCloseI
 // - TUI reach: the ONLY server-to-TUI channel is the rpc event bridge - the
 //   session-tab rpc definition is registered at setup and its events reach
 //   the TUI CLI plugin (the package's ./tui entrypoint), which drives the
-//   tab strip (ui.tabs). Toast/command/exit pushes still have no surface.
-// - toasts, tui commands, session delete/list endpoints:
+//   tab strip (ui.tabs) and shows toasts (ui.toast). Keymap-command pushes
+//   still have no surface.
+// - wrap-up actions: compact rides session.compact on the promise domain
+//   (upstream #52385, newer than the pinned dev types, so runtime-guarded);
+//   exit records the session's watcher deaths synchronously in the runtime
+//   and then emits the bridge's exit-tab-closed event, which the TUI plugin
+//   turns into closing the session's OWN tab (see exitHost in
+//   buildCapabilities).
+// - toasts ride the bridge's toast event (TUI plugin's ui.toast.show);
+//   extraction-child cleanup rides session.remove (upstream #52387, also
+//   runtime-guarded). tui commands, session list endpoints:
 //   no v2 surface reachable from a plugin - degrades as no-op/null.
 //   fetchStatuses returns {} because the wake gate treats an unknown session
 //   as idle; the event-fed status map inside the runtime does the gating.
 //   Session MESSAGES are readable via session.context (mapped into the v1
-//   shape), so the wrap-up greenlight check works; the compaction TRIGGER
-//   does not (no session.compact on the promise domain).
+//   shape), so the wrap-up greenlight check works.
 
 type V2Context = Plugin.Context;
 type V2Cleanup = Plugin.Cleanup;
 
+// Both ends of the prompt-text binding must reconstruct text the same way:
+// the prompt-session adapter joins outbound prompt parts with this helper,
+// and the context hook joins a wire message's text parts with it before
+// comparing against the stored prompt text. A separator mismatch would
+// silently fail the equality and drop the turn's nudges.
+function joinTextParts(parts: Array<{ text: string }>): string {
+  return parts.map((p) => p.text).join("\n\n");
+}
+
+// Reconstructs a wire message's text for the prompt-text binding. A string
+// content is the common case; multi-part messages join with joinTextParts
+// so the read side agrees with the write side's separator.
+function messageText(message: { content: unknown }): string {
+  if (typeof message.content === "string") return message.content;
+  const parts = (Array.isArray(message.content) ? message.content : []).filter(
+    (p: any) => p?.type === "text",
+  );
+  return joinTextParts(parts);
+}
+
+// The wrap-up exit's tab-close emitter, late-bound in setup (see the
+// tuiBridge holder there). One shape, referenced at the holder, the
+// buildCapabilities seam, and the assignment - a local alias so the payload
+// shape has a single drift point in this file.
+type ExitTabCloseEmitter = (data: { sessionID: string }) => Promise<unknown>;
+
 // Raw setup function: the dual entry (src/index.ts) owns the plugin id and
 // the merged default export; this adapter only implements the v2 setup.
 export async function setup(context: V2Context): Promise<V2Cleanup | void> {
@@ -77,14 +111,26 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // differs from this instance's directory whenever opencode is launched
   // below the project root. Their events would never pass the directory
   // filter, so they are forwarded by ID: sessionCreate records every child
-  // here, and the pump lets their events through.
+  // here, and the pump lets their events through. Ids are never removed
+  // (children are deleted, but their id never recurs and the set dies with
+  // this activation - only a long-lived instance grows it).
   const childSessions = new Set<string>();
 
   // Tool executions currently running against this instance's runtime (see
   // the counter in the tool execute wrapper below).
   let inflightTools = 0;
 
-  const capabilities = buildCapabilities(context, worktree, childSessions);
+  // TUI-bridge holder: the wrap-up exit emits the exit-tab-closed rpc event
+  // (the TUI plugin closes the session's own tab) and every runtime toast
+  // rides the toast event - both through this late-bound holder, because
+  // capabilities are built before the rpc registration exists. Assigned when
+  // the registration wires (below); undefined forever on an SDK floor
+  // without the rpc surface, which both emitters' guards degrade.
+  const tuiBridge: {
+    emitExitTabClose?: ExitTabCloseEmitter;
+    emitToast?: (toast: ToastInput) => Promise<unknown>;
+  } = {};
+  const capabilities = buildCapabilities(context, worktree, childSessions, tuiBridge);
   const runtime = await createRuntime({ capabilities, directory, worktree, v2Tools: true });
   // Seed the forwarding set from rehydrated child bookkeeping: after a
   // reload, an in-flight extraction child's maps come back from the journal,
@@ -111,13 +157,27 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   if (tabRegistration) {
     const emitTabOpened = (data: { sessionID: string; directory: string }) =>
       tabRegistration.events.emit(TAB_OPENED_EVENT, data);
+    // The session_tab_close tool's confirmed-close emitter: the pump
+    // translates this event into the runtime's death path, so it is the
+    // tool's only route to that bookkeeping.
+    const emitTabClosed = (data: { sessionID: string; chatName: string | null }) =>
+      tabRegistration.events.emit(TAB_CLOSED_EVENT, data);
+    // The wrap-up exit's own emitter: TUI-only (the runtime records the
+    // exit's deaths synchronously before the action fires, so the pump
+    // deliberately never translates this one).
+    tuiBridge.emitExitTabClose = (data) => tabRegistration.events.emit(EXIT_TAB_CLOSED_EVENT, data);
+    // Every runtime toast rides this emitter (alerts, extraction metrics,
+    // chat registration, blocked wrap-ups) - TUI-only by nature. The spread
+    // widens the interface into a plain object type: the rpc emit's
+    // schema-inferred input wants an index signature, which interfaces
+    // never carry.
+    tuiBridge.emitToast = (toast) => tabRegistration.events.emit(TOAST_EVENT, { ...toast });
     runtime.coreContext.sessionTabHost = buildSessionTabHost({
       context,
       directory,
       db: runtime.coreContext.db,
       emitTabOpened,
-      emitTabClosed: (data: { sessionID: string; chatName: string | null }) =>
-        tabRegistration.events.emit(TAB_CLOSED_EVENT, data),
+      emitTabClosed,
       debug: runtime.debug,
     });
   } else {
@@ -199,12 +259,34 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   //   (the v1 contract); v2's system parts are { type: "text", text }
   //   objects, so convert at the boundary.
   // - per-turn nudges: append the prompt hook's stored injections to the
-  //   OUTBOUND request's last user message. The stored user message stays
-  //   clean (v1 delivered nudges as TUI-hidden synthetic parts; v2's prompt
-  //   text IS the stored message), and the request is rebuilt per round
-  //   trip, so injecting here reproduces v1's persistent-synthetic-part
-  //   semantics: the model sees the nudges on every call of the turn.
-  const pendingInjections = new Map<string, string[]>();
+  //   OUTBOUND request's user message whose text matches the entry's
+  //   stored prompt (see the binding check below). The stored user message
+  //   stays clean (v1 delivered nudges as TUI-hidden synthetic parts; v2's
+  //   prompt text IS the stored message), and the request is rebuilt per
+  //   round trip, so injecting here reproduces v1's
+  //   persistent-synthetic-part semantics: the model sees the nudges on
+  //   every call of the turn.
+  // Per-turn nudge injections, keyed by session, then by the prompt text
+  // they were computed from. Each entry is bound to that text: the context
+  // hook injects an entry only when the request contains a user message
+  // whose text equals it. A bare sessionID-keyed entry that outlives its
+  // turn (the prompt hook missed or failed on a later message) replays a
+  // stale nudge block onto a message it was never computed for - deleted
+  // predictions surfaced as current with their old confidence labels (the
+  // October 2026 staleness report).
+  //
+  // The per-session set holds a small bounded number of entries (oldest
+  // evicted) so a prompt queued mid-turn keeps its own fresh entry instead
+  // of evicting the running turn's: the running turn's remaining rounds
+  // still match their own prompt, and the queued prompt's turn matches
+  // its own. A prompt whose nudge computation comes up empty clears the
+  // session's whole set - an entry left behind would match its own prompt
+  // text in the session HISTORY of later requests and replay a stale block
+  // there - so a queued prompt with no nudges drops the running turn's
+  // remaining-round block. That cost is smaller than the staleness it
+  // prevents; opencode-plugin.md discloses it.
+  const PENDING_INJECTION_CAP = 3;
+  const pendingInjections = new Map<string, Map<string, { promptText: string; injections: string[] }>>();
   const registerSystem = await context.session.hook(
     "context",
     async (request: { sessionID: string; system: unknown[]; messages?: any[] }) => {
@@ -213,16 +295,51 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
       for (const part of pushed) {
         request.system.push(typeof part === "string" ? { type: "text", text: part } : part);
       }
-      const injections = pendingInjections.get(request.sessionID);
-      if (!injections?.length) return;
-      const lastUser = [...(request.messages ?? [])].reverse().find((m) => m?.role === "user");
-      if (!lastUser) return;
+      const pending = pendingInjections.get(request.sessionID);
+      if (!pending?.size) return;
+      // Binding check: a stored v2 user message IS its prompt text (the
+      // prompt hook's injections are computed from it), so text equality
+      // identifies the message an entry belongs to. Wire message ids are
+      // optional on the v2 Message schema and cannot be relied on here.
+      //
+      // The match searches the request's user messages for the LAST one
+      // whose joined text equals the entry's prompt - it is not simply the
+      // request's last user message. Sibling context hooks (opencode's plan
+      // plugin) splice their own user-role reminder into the request
+      // mid-turn: BEFORE the prompt when the request's last message is
+      // user-role, but AT THE TAIL when it is not (mid-turn rounds), which
+      // would make the reminder the last user message, fail the equality,
+      // and silently drop every nudge for the turn. Injecting into the
+      // prompt's own message is v1's persistent-synthetic-part semantics.
+      //
+      // Entries are tried newest first: when several are pending for the
+      // session, the latest prompt-hook run wins a text match.
+      //
+      // Text equality is the tightest binding available here, not an
+      // airtight one: an identical prompt re-submitted after a missed
+      // prompt hook still matches and replays. The next prompt-hook run
+      // that fires is the recovery.
+      let target: any;
+      let matched: { promptText: string; injections: string[] } | undefined;
+      for (const entry of [...pending.values()].reverse()) {
+        target = [...(request.messages ?? [])]
+          .reverse()
+          .find((m) => m?.role === "user" && messageText(m) === entry.promptText);
+        if (target) {
+          matched = entry;
+          break;
+        }
+      }
+      if (!matched) {
+        runtime.debug("v2:hook:context", `session=${request.sessionID} no user message matches a stored prompt; skipping injections`);
+        return;
+      }
       // v2's wire Message carries parts in `content: Array<ContentPart>` -
       // it has no `parts` field, so injecting there would write a stray
       // property the provider formatter never reads (silent nudge loss).
-      const content = Array.isArray(lastUser.content) ? lastUser.content : (lastUser.content = []);
-      for (const text of injections) content.push({ type: "text", text });
-      runtime.debug("v2:hook:context", `session=${request.sessionID} injected=${injections.length} messages=${request.messages?.length}`);
+      const content = Array.isArray(target.content) ? target.content : (target.content = []);
+      for (const text of matched.injections) content.push({ type: "text", text });
+      runtime.debug("v2:hook:context", `session=${request.sessionID} injected=${matched.injections.length} messages=${request.messages?.length}`);
     },
   );
 
@@ -241,12 +358,29 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
         );
       } catch (err) {
         console.error(`[thatch] v2 prompt hook failed: ${err}`);
+        // The hook owns no fresh entry for this prompt; a retained one
+        // belongs to a superseded prompt and would replay on an identical
+        // re-submission. Drop the session's whole set.
+        pendingInjections.delete(request.sessionID);
         return;
       }
       const injections = parts.slice(1).map((part) => part.text);
       if (injections.length > 0) runtime.debug("v2:hook:prompt", `session=${request.sessionID} injections=${injections.length}`);
-      if (injections.length > 0) pendingInjections.set(request.sessionID, injections);
-      else pendingInjections.delete(request.sessionID);
+      if (injections.length > 0) {
+        const entries = pendingInjections.get(request.sessionID) ?? new Map();
+        if (!entries.has(request.prompt.text) && entries.size >= PENDING_INJECTION_CAP) {
+          // Bounded set: evict the oldest entry (insertion order).
+          entries.delete(entries.keys().next().value!);
+        }
+        entries.set(request.prompt.text, { promptText: request.prompt.text, injections });
+        pendingInjections.set(request.sessionID, entries);
+      } else {
+        // A prompt that produced no nudges clears the session's whole set:
+        // an entry left behind would match its own prompt text in the
+        // session history of later requests and replay a stale block there.
+        // See the pendingInjections comment above for the disclosed cost.
+        pendingInjections.delete(request.sessionID);
+      }
     },
   );
 
@@ -278,10 +412,9 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
     for (const kind of ["compact", "exit"] as const) {
       editor.add({
         name: `thatch/${kind}`,
-        description:
-          kind === "compact"
-            ? "Flush thatch persistence, check for loose ends, then compact if clear"
-            : "Flush thatch persistence, check for loose ends, then exit opencode if clear",
+        // Shared with the v1 command file's frontmatter so the two hosts'
+        // menu descriptions cannot drift.
+        description: wrapUpCommandDescription(kind),
         // The user's typed arguments ride invocation.prompt (a
         // PromptInput.Prompt with a text field). v1's host expanded
         // $ARGUMENTS from the command file; v2's session.prompt does no
@@ -699,14 +832,41 @@ function buildSessionTabHost(input: {
   };
 }
 
+// Runtime guard for promise-domain members newer than the pinned dev types
+// (compact - upstream #52385; remove - #52387): a typed call fails tsc
+// against the pin, and an unguarded cast crashes on an older host. Returns
+// the member as a callable, or undefined on the floor - the CALLER owns the
+// degrade (a log for user-requested actions like compact; silence for
+// best-effort ones like the child cleanup). The rpc registration guard in
+// setup is the same idiom at domain granularity and stays inline: it gates
+// a whole registration, not one call.
+export function optionalDomainMethod(
+  domain: object,
+  method: string,
+): ((input: unknown) => Promise<unknown>) | undefined {
+  const fn = (domain as Record<string, unknown>)[method];
+  return typeof fn === "function" ? (fn as (input: unknown) => Promise<unknown>) : undefined;
+}
+
 // The HostCapabilities implementation over the v2 promise context. Every
 // operation the v2 surface lacks degrades as a no-op or null - the shared
 // runtime's callers treat those results as best-effort and log, never crash.
-function buildCapabilities(context: V2Context, worktree: string, childSessions: Set<string>): HostCapabilities {
+function buildCapabilities(
+  context: V2Context,
+  worktree: string,
+  childSessions: Set<string>,
+  tuiBridge: {
+    emitExitTabClose?: ExitTabCloseEmitter;
+    emitToast?: (toast: ToastInput) => Promise<unknown>;
+  },
+): HostCapabilities {
   // Typed against the SDK's own SessionDomain: the shape errors the
   // original cast (as unknown as {...}) suppressed are exactly what the
-  // review caught (message.list and compact do not exist here; get takes
-  // {sessionID}). Let the typecheck keep holding that line.
+  // review caught (message.list does not exist here; get takes
+  // {sessionID}). compact and remove DO exist on newer SDK builds but not
+  // on the pinned dev types - both calls go through optionalDomainMethod
+  // (above). Let the typecheck keep holding that line for the pinned
+  // surface.
   const session = context.session;
 
   return {
@@ -731,14 +891,20 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
       childSessions.add(id);
       return { id };
     },
-    // No delete on the v2 SessionDomain: extraction child sessions are not
-    // cleaned up on v2 (documented gap; the bookkeeping maps still keep the
-    // claim/completion lifecycle consistent). Two user-visible consequences: the session
-    // picker accumulates one thatch-extraction entry per extraction, and
-    // "continue last session" (-c) logic that picks the newest top-level
-    // session will land in an extraction child after any session that
-    // triggered extraction, because the child is top-level and newer.
-    sessionDelete: async () => {},
+    // Extraction child cleanup: upstream exposed session.remove on the
+    // promise domain (#52387), the same era as compact - guarded the same
+    // way (optionalDomainMethod; the pinned dev types predate the surface).
+    // An older host keeps the documented gap: the session picker accumulates
+    // one thatch-extraction entry per extraction, and "continue last session"
+    // (-c) logic that picks the newest top-level session lands in an
+    // extraction child after any session that triggered extraction,
+    // because the child is top-level and newer.
+    sessionDelete: async (id: string) => {
+      const remove = optionalDomainMethod(session, "remove");
+      // Best-effort by the caller's contract: the floor degrades silently.
+      if (!remove) return;
+      await remove({ sessionID: id });
+    },
     promptSession: async (sessionID, body, _mode) => {
       // v2's prompt endpoint takes text, not parts, and has no synthetic /
       // noReply semantics. Nudge injections ride the prompt hook.
@@ -749,7 +915,7 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
       // prompt); v2's prompt enqueues the message and returns while the
       // model turn runs asynchronously, so the extraction background flag
       // degrades: both modes enqueue the same way.
-      const text = body.parts.map((part) => part.text).join("\n\n");
+      const text = joinTextParts(body.parts);
       if (!body.noReply && body.parts.length > 0 && body.parts.every((part) => part.synthetic)) {
         await session.synthetic({ sessionID, text });
         return;
@@ -764,36 +930,51 @@ function buildCapabilities(context: V2Context, worktree: string, childSessions:
     },
     sessionList: async () => null,
     sessionMessages: async (id) => {
-      // The v2 promise domain has no message-list endpoint (no
-      // `message` accessor and no compact/remove in the SessionDomain Pick).
+      // The pinned promise domain has no message-list endpoint (no `message`
+      // accessor; compact/remove exist on newer SDK builds but not here).
       // `session.context` IS exposed and returns the session's message list
       // (Array<SessionMessageInfo>); map into the v1 shape the wrap-up
       // greenlight check reads.
       const result = await session.context({ sessionID: id });
       return mapSessionContextMessages(result);
     },
-    showToast: async (_toast: ToastInput) => {
-      // No toast publish path reachable from the promise context (the
-      // tui.toast.show event has no producer surface here). A `tui`
-      // companion plugin entrypoint (ui.toast.show) is the known lift
-      // candidate - not yet wired. Degrades.
+    showToast: async (toast: ToastInput) => {
+      // The toast rpc event is the only TUI feedback channel on v2 - the
+      // TUI plugin's ui.toast.show. Best-effort by contract (the runtime's
+      // call sites catch-and-ignore): a TUI-less environment (headless run,
+      // still connecting) or an rpc-less SDK floor simply never shows it,
+      // and that is the correct silent degrade, not an error.
+      const emit = tuiBridge.emitToast;
+      if (!emit) return;
+      await emit(toast);
     },
-    compactSession: async () => {
-      // No compaction trigger is reachable from the promise context: the
-      // SessionDomain Pick has no session.compact, and the built-in
-      // /compact is a TUI palette action calling the server endpoint
-      // directly (the server command registry only knows config/plugin-
-      // registered names). The compact wrap-up still runs its checklist
-      // and flush; only the automatic compaction itself degrades.
-      console.error("[thatch] v2: compaction trigger unavailable; wrap-up checklist ran, compact skipped");
+    compactSession: async (sessionID: string) => {
+      // Upstream exposed session.compact on the promise SessionDomain
+      // (#52385) - the same core compaction the built-in /compact runs.
+      // The pinned dev types predate that surface, so the call goes through
+      // optionalDomainMethod: an older host degrades to a logged no-op (the
+      // wrap-up checklist and flush still ran).
+      const compact = optionalDomainMethod(session, "compact");
+      if (!compact) {
+        console.error("[thatch] v2: compaction trigger unavailable; wrap-up checklist ran, compact skipped");
+        return;
+      }
+      await compact({ sessionID });
     },
-    exitHost: async () => {
-      // No TUI surface on v2; the exit wrap-up's checklist and flush run,
-      // the exit itself does not. When upstream restores a publish path
-      // (or the `tui` companion entrypoint's ui.tabs.close is wired),
-      // the right v2 target closes THIS session's tab, not app.exit - on
-      // a shared daemon app.exit would take down every tab. Tracked in
-      // anomalyco/opencode#50984.
+    exitHost: async (sessionID: string) => {
+      // Tab-scoped close (the close anomalyco/opencode#50984 asks for):
+      // the daemon hosts every tab, so app.exit would take down unrelated
+      // sessions. This emit is TUI-only - the runtime records the
+      // session's watcher deaths synchronously BEFORE calling here, and
+      // the pump deliberately never translates this event (a second
+      // death pass would erase the durable death row the first one
+      // wrote).
+      const emit = tuiBridge.emitExitTabClose;
+      if (!emit) {
+        console.error("[thatch] v2: rpc surface unavailable; wrap-up checklist ran, tab close skipped");
+        return;
+      }
+      await emit({ sessionID });
     },
   };
 }

package/src/prompts.ts

@@ -1,5 +1,31 @@
 import type { PredictionNudgeItem, BehaviorNudgeItem } from "./db";
 
+/**
+ * The review specialist roster, in the coordinator's dispatch order. This is
+ * the single source of truth for the roster and its count in code: both host
+ * instruction skill lists (the opencode system prompt and the Claude
+ * Code/Cursor instructions), the review-mode command couching in
+ * src/commands.ts, and the shared-skills install list in src/skills.ts all
+ * derive from it, so a roster change lands in code everywhere at once.
+ * Prose copies cannot interpolate and remain hand-maintained: the
+ * coordinator and followup skills' count phrases are pinned by a
+ * setup.test.ts alarm, and the rest (the coordinator's Step 6 name list,
+ * the synthesizer's specialist list, the user-doc tables) need a grep of
+ * the artifacts and docs when the roster changes.
+ */
+export const REVIEW_SPECIALISTS: readonly string[] = [
+  "thatch-review-pedantic",
+  "thatch-review-acceptance",
+  "thatch-review-state-flow",
+  "thatch-review-economy",
+  "thatch-review-no-slop",
+  "thatch-review-clarity",
+  "thatch-review-breadcrumbs",
+  "thatch-review-mark-and-sweep",
+  "thatch-review-highlights",
+  "thatch-review-technique",
+];
+
 /**
  * Shared verb selection for prediction formatting. 0-evidence predictions
  * use the hedged "you may prefer"; predictions with any evidence use the
@@ -188,7 +214,7 @@ exposes tools through code.
 Thatch ships skills for code review, project investigation, and memory
 workflows. The host auto-discovers them, but reach for them proactively:
 
-- \`thatch-code-review\` - full multi-agent code review (dispatches 8 specialists + synthesizer). Requires sub-agent support.
+- \`thatch-code-review\` - full multi-agent code review (dispatches ${REVIEW_SPECIALISTS.length} specialist sub-agents, then synthesizes). Requires sub-agent support.
 - \`thatch-coordination\` - coordinate subordinate LLM sessions: dispatch with thatch_session_tab (opencode v2), track each in your task list, supervise over cross-session chat, verify before declaring done.
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
 - \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
@@ -551,7 +577,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-economy\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` / \`-technique\` - nine specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- ${REVIEW_SPECIALISTS.map((name) => "`" + name + "`").join(" / ")} - ${REVIEW_SPECIALISTS.length} specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
 - \`thatch-project-primer\` - investigate a new project and write foundational memories.
 - \`thatch-session-reflection\` - record what you learned at end of session.
 - \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
@@ -992,12 +1018,32 @@ function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
 // update on user response).
 // ---------------------------------------------------------------------------
 
-export function predictionNudge(items: PredictionNudgeItem[]): string {
+// Shared tail of the prediction and behavior nudges. The re-check tool name
+// is resolved by the caller's ToolNamer: the same renderers serve the
+// opencode plugin path (thatch_*) and the MCP flush-tools path
+// (mcp__thatch__*), where hosts spell tools differently.
+function snapshotFooter(store: string, recheckTool: string): string {
+  const cap = store[0].toUpperCase() + store.slice(1);
+  return (
+    `Snapshot: these labels reflect the ${store} store as of this message's submission. ` +
+    `${cap} updated after submission (including during this turn) do not refresh it; ` +
+    `re-check with ${recheckTool} before relying on them.`
+  );
+}
+
+export function predictionNudge(items: PredictionNudgeItem[], tool: ToolNamer = opencodeToolName): string {
   const lines = items.map((p) => {
     const verb = predictionVerb(p.evidence_count);
     return `- ${formatWhenLine(p.confidence, p.evidence_count, p.matcher_description, p.statement, verb)}`;
   });
-  return `[thatch] User decision model\n${lines.join("\n")}`;
+  // Snapshot basis (the Oct 2026 staleness report): the block is computed
+  // once when the message is submitted and stays attached to it for the
+  // whole turn. Predictions mutated after submission (by this turn's own
+  // tool calls, or a concurrent session) do not refresh it - the labels
+  // below can lag the store. Point the consumer at the live tool instead
+  // of implying a per-round refresh.
+  const footer = snapshotFooter("prediction", tool("prediction_query"));
+  return `[thatch] User decision model\n${lines.join("\n")}\n${footer}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -1006,12 +1052,15 @@ export function predictionNudge(items: PredictionNudgeItem[]): string {
 // how to act (follow relevant rules, ham/spam each match via behavior_feedback).
 // ---------------------------------------------------------------------------
 
-export function behaviorNudge(items: BehaviorNudgeItem[]): string {
+export function behaviorNudge(items: BehaviorNudgeItem[], tool: ToolNamer = opencodeToolName): string {
   const lines = items.map((b) => {
     const verb = b.evidence_count === 0 ? "consider" : "do";
     return `- ${formatWhenLine(b.confidence, b.evidence_count, b.matcher_description, b.statement, verb)}`;
   });
-  return `[thatch] Situational behaviors\n${lines.join("\n")}`;
+  // Same snapshot basis as the prediction nudge: computed at submission,
+  // not refreshed by mid-turn behavior feedback.
+  const footer = snapshotFooter("behavior", tool("behavior_list"));
+  return `[thatch] Situational behaviors\n${lines.join("\n")}\n${footer}`;
 }
 
 /**