@jeffober/thatch 0.1.48 → 0.2.1

package/src/runtime.ts

@@ -0,0 +1,2004 @@
+import { join } from "node:path";
+import { createDebugLog } from "./debug";
+import { ThatchDB, repoPathCache } from "./db";
+import { SharedModelPool } from "./embeddings";
+import { detectRepo, detectWorktreeKind, resolveSpawnCwd } from "./git";
+import { buildCoreContext } from "./tool-defs";
+import {
+  systemPrompt,
+  compactionContext,
+  sessionStartReminder,
+  recallNudge,
+  extractionNudge,
+  extractionDirectPrompt,
+  predictionNudge,
+  behaviorNudge,
+  versionWarningNudge,
+  skewWarningText,
+  type NudgeMatch,
+} from "./prompts";
+import { ExtractionPipeline, isMetaToolName, unwrapExecuteThatchCalls, type ToolInteraction } from "./extraction";
+import { createAlerts, deriveRoundShape, isNoWorkTool, replyRequestID } from "./alerts";
+import { mostRecentTopLevelSessionId } from "./session-db";
+import type { CoreContext } from "./tool-defs";
+import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
+import { installOpencodeCommands, opencodeActionCommandDefs, removeWrapUpCommandFiles, COMPACT_READY_TOKEN, EXIT_READY_TOKEN } from "./commands";
+import { hygieneReport } from "./hygiene";
+import { seedDefaultBehaviors } from "./seed-behaviors";
+import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
+import { WatcherRegistry, ghApiRun, ghAvailable, runWatchedCommand, watcherTarget, withCwdFallback, type Watcher } from "./watchers";
+import { watcherNotificationNudge, watcherRearmNotice, watcherDeathNotice, chatNotificationNudge, chatEchoText, isChatEchoParts } from "./prompts";
+import { ChatPoller, createWakeGate, hostedSessionIds, isDefaultSessionTitle, unexpiredGraceRehosts } from "./chat";
+import { chatEnabled, chatAutoRegister, loadConfig, alertMode, notificationDefaults } from "./config";
+import { sendNotification } from "./notify";
+import { osProcessArgs, startupSessionId, continuesLastSessionFromArgv, continuesLastSessionId } from "./os-args";
+import type { HostCapabilities } from "./capabilities";
+import pkg from "../package.json";
+
+// ---------------------------------------------------------------------------
+// Shared plugin runtime - host-agnostic across opencode v1 and v2
+// ---------------------------------------------------------------------------
+
+// Minimum cosine score for the prompt-aware recall nudge. Lower than
+// findDuplicates' 0.85 (near-dupes) because "relates to" is a weaker signal
+// than "duplicate." Tunable via THATCH_RECALL_THRESHOLD.
+const RECALL_THRESHOLD = parseFloat(process.env.THATCH_RECALL_THRESHOLD ?? "0.55");
+
+// How long a dormant watcher journal row (a restart kept it because its
+// session may yet be resumed) survives past its newest definition's TTL
+// before aging out. The TTL alone would kill the row the morning after an
+// overnight watch; the grace keeps recovery possible for sessions the user
+// returns to days later.
+const DORMANT_WATCHER_GRACE_MS = 24 * 60 * 60 * 1000;
+
+// Grace rehosting after a RESTART (see the hosted-row branch in the
+// rehydration loop): the dead daemon's hosted set re-hosts for this window.
+// Open TUI tabs reconnect to the new daemon but emit no events until the
+// user types, so without the grace they go falsely stale ("presumed gone")
+// while alive-idle, and mail stops waking them. Sessions that emit activity
+// graduate to permanent hosting via the event stream; still-silent ones
+// (closed tabs) age out at the grace and go stale again. Matches
+// DORMANT_WATCHER_GRACE_MS - same resumability shape, same trade.
+const CHAT_REHOST_GRACE_MS =
+  (Number(process.env.THATCH_CHAT_REHOST_GRACE_MINUTES ?? 0) * 60_000) || 24 * 60 * 60 * 1000;
+
+/**
+ * True when every definition in a dormant watcher row is past its TTL plus
+ * the dormant grace period - the row is a corpse no resume can usefully
+ * re-arm. An empty or malformed payload counts as stale.
+ */
+function dormantWatchersStale(defs: Watcher[]): boolean {
+  if (!Array.isArray(defs) || defs.length === 0) return true;
+  const lastExpiry = Math.max(...defs.map((w) => Number((w as { expiresAt?: number })?.expiresAt ?? 0)));
+  return Date.now() > lastExpiry + DORMANT_WATCHER_GRACE_MS;
+}
+
+/** Process-wide pool for the shared embedding models (see SharedModelPool). */
+const sharedModels = new SharedModelPool();
+
+// Prompts shorter than this skip the recall nudge - trivially short prompts
+// like "yes" or "ok" match too broadly to be useful.
+const MIN_PROMPT_LEN = 10;
+
+// Minimum cosine score for the prediction auto-fire. Higher than the
+// recall nudge (0.55) because surfacing a user-preference nudge is more
+// disruptive than surfacing a memory -- the agent may act on it or
+// surface it to the user. 0.60 cuts noise in dense embedding spaces
+// while still catching genuinely related contexts.
+const PREDICTION_THRESHOLD = parseFloat(process.env.THATCH_PREDICTION_THRESHOLD ?? "0.60");
+
+// Same threshold for behavior auto-fire. Same rationale: surfacing a
+// self-discipline rule is disruptive and should only fire when the
+// situation genuinely matches.
+const BEHAVIOR_THRESHOLD = parseFloat(process.env.THATCH_BEHAVIOR_THRESHOLD ?? "0.60");
+
+// Wrap-up command registry: command name as opencode derives it from the
+// installed file path (~/.config/opencode/command/thatch/<name>.md), the
+// greenlight token the command instructs the model to end its response with,
+// and which TUI action the greenlight triggers.
+const WRAPUP_COMMANDS: Record<string, { token: string; kind: "compact" | "exit" }> = {
+  "thatch/compact": { token: COMPACT_READY_TOKEN, kind: "compact" },
+  "thatch/exit": { token: EXIT_READY_TOKEN, kind: "exit" },
+};
+
+// The handler-set shape both host adapters consume. The methods correspond
+// to the v1 hook surface (plus the per-call coreContext and the
+// host-agnostic debug log); the v2 adapter routes its domain hooks into
+// these same methods. Part and message shapes are kept structural (the v1
+// bodies already treat parts loosely) so neither adapter has to convert
+// host SDK types.
+export interface ThatchRuntime {
+  /** The shared per-call context both adapters register TOOL_DEFS with. */
+  coreContext: CoreContext;
+  /** The host-agnostic diagnostic log (THATCH_DEBUG; no-op when unset). */
+  debug(tag: string, message: string): void;
+  /**
+   * Session IDs with live child bookkeeping (in-flight extraction children).
+   * The v2 adapter seeds its event-forwarding set from this after a reload:
+   * the rehydrated child maps must be visible to the pump's directory
+   * filter, or a below-root launch drops the child's events again.
+   */
+  childSessionIds(): string[];
+  onSystemTransform(output: { system: string[] }): Promise<void>;
+  onSessionCompacting(input: { sessionID: string }, output: { context: string[] }): Promise<void>;
+  onCompactionAutocontinue(input: { sessionID: string }): Promise<void>;
+  onToolExecuteAfter(
+    input: { tool: string; sessionID: string; args?: unknown },
+    output: { title: string; output: string },
+  ): Promise<void>;
+  onCommandExecuteBefore(input: { command: string; sessionID: string }): Promise<void>;
+  onChatMessage(
+    input: { sessionID: string; messageID?: string },
+    output: { parts: any[]; message: { id: string } },
+  ): Promise<void>;
+  onEvent(event: any): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export async function createRuntime(input: {
+  capabilities: HostCapabilities;
+  directory: string;
+  worktree: string;
+}): Promise<ThatchRuntime> {
+  const { capabilities: caps, directory, worktree } = input;
+  // The opencode server's cwd is wherever the server happened to start;
+  // `worktree` is the project this plugin instance actually serves.
+  // `directory` is the session's own directory - on resume after the
+  // worktree was deleted, opencode reassigns worktree to "/" (it walks up
+  // from the missing dir, finds no .git, and boots the global project) but
+  // still forwards the original path as directory, which is the only input
+  // the repo_paths cache can recover identity from.
+  const home = process.env.HOME ?? "/tmp";
+  const configHome = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+  const dbPath = process.env.THATCH_DB_PATH ?? join(configHome, "thatch", "thatch.db");
+  const modelName = process.env.THATCH_MODEL ?? "Xenova/bge-small-en-v1.5";
+
+  // Set by dispose(). Delayed async work (the child-reconcile timer, the
+  // extraction pipeline's queued finalization, queued event handlers) can
+  // fire after the db is closed; anything running past this flag must not
+  // touch the db - and journal writes must no-op BEFORE the lazy reopen
+  // accessor (src/db.ts) would hand them a fresh connection, because after
+  // a v2 plugin reload the RELOADED instance owns those rows.
+  let disposed = false;
+
+  // The DB must exist before identity detection: detectRepo consults the
+  // repo_paths cache when the session directory is gone.
+  const db = new ThatchDB(dbPath);
+  const repoCache = repoPathCache(db);
+  const repo = await detectRepo(directory ?? worktree, repoCache);
+
+  // Whether cross-session chat is on (chat.enabled, default on). Read once
+  // at init: it gates the chat poller and the prompt's chat section. The
+  // chat tools re-read the file per call, so a toggle takes effect there
+  // without a restart.
+  const chatOn = chatEnabled(loadConfig(dbPath).config);
+
+  const debug = createDebugLog(dbPath);
+
+  // Shared embedding model: refcounted per db path (see SharedModelPool).
+  const model = sharedModels.acquire(dbPath, modelName);
+  const releaseModel = () => sharedModels.release(dbPath);
+
+  // Extraction buffer, journaled to runtime_state so a v2 plugin reload
+  // (same process, graph rebuilt) can rehydrate it. The journal callback
+  // checks the disposed flag FIRST: a finalization delayed past dispose
+  // (await points inside the pipeline) must not write through the lazy
+  // reopen accessor after the reload - the reloaded instance owns those
+  // rows. Same ownership rule as journalChild below.
+  const extraction = new ExtractionPipeline((kind, sessionID, value) => {
+    if (disposed) return;
+    if (value === undefined) db.runtimeStateDelete(kind, sessionID);
+    else db.runtimeStatePut(kind, sessionID, value, directory);
+  });
+
+  // Seed default behaviors into the global store on first run, and
+  // update them when their content changes across releases. Idempotent:
+  // behaviors are matched by key stamp, not by cosine similarity, so
+  // user-codified behaviors are never overwritten. See seed-behaviors.ts
+  // for the full mechanism.
+  await seedDefaultBehaviors(db, model);
+
+  // Start background npm update polling. The checker caches the latest
+  // version in memory and to a file. Never blocks the plugin or tool calls.
+  // The opencode plugin path has no hook/server split, so version skew
+  // between hooks and server is not a concern here. But two opencode
+  // sessions on different versions sharing one DB can cause schema/data
+  // corruption. The npm update nudge covers the "please update" case.
+  // The on-disk version check (readOnDiskVersion) catches the case where
+  // the user ran `npm update` but hasn't restarted opencode yet.
+  startVersionChecker(dbPath);
+
+  // The running version, frozen at module load time. Compared against the
+  // on-disk package.json version on each chat.message to detect post-upgrade
+  // non-restart.
+  const runningVersion = pkg.version;
+
+  // Latest observed opencode session status per session ("busy" | "idle" |
+  // "retry"). Keys enter from session.status events and leave only in
+  // session.deleted (which shrinks the chat poller's hosted set). Readers:
+  // the watcher registry's and the chat poller's canDeliver gates
+  // (proactive prompts only fire into idle sessions, never into a running
+  // turn), and the chat poller's hostedSessions set (the sessions this
+  // process may deliver chat mail to - the map's keys).
+  const sessionStatus = new Map<string, string>();
+
+  // LLM alerts (docs/plans/llm-alerts.md): notify when the LLM pauses for
+  // human input or finishes a round of real work. Plain in-memory state -
+  // a v2 reload mid-turn loses that turn's transition and stays silent
+  // (accepted). Delivery reuses the notify_user dispatcher; the alerts
+  // config section picks the channel per event, defaulting to banner. The
+  // config is re-read per delivery so a config_set (or hand edit) applies
+  // without a restart, the same contract the chat tools' per-call config
+  // read gives the chat section.
+  const alerts = createAlerts({
+    config: () => loadConfig(dbPath).config,
+    roundShape: async (sessionID) =>
+      deriveRoundShape(await caps.sessionMessages(sessionID)),
+    sessionTitle: async (sessionID) => (await caps.sessionGet(sessionID))?.title,
+    notify: async ({ kind, title, message }) => {
+      const defaults = notificationDefaults();
+      await sendNotification({
+        message,
+        title,
+        source: title,
+        // The machine owns the per-event "none" gate and never calls here
+        // with one - this cast records that contract.
+        channel: alertMode(loadConfig(dbPath).config, kind) as "both" | "banner" | "voice",
+        voice: defaults.voice,
+        sound: defaults.sound,
+      });
+    },
+  });
+
+  // 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).
+  const canPromptSession = createWakeGate({
+    isCompacting: (sessionID) => compacting.has(sessionID),
+    mappedStatus: (sessionID) => sessionStatus.get(sessionID),
+    fetchStatuses: async () => {
+      return (await caps.fetchStatuses()) ?? {};
+    },
+    onStatusError: (sessionID, err) => {
+      console.error(`[thatch] status check failed for ${sessionID}: ${err}`);
+    },
+  });
+
+  // In-memory watcher registry for proactive event notifications (GitHub PR
+  // and branch watching, plus local command watches). Live state is
+  // process-scoped; definitions are journalled for reload rehydration and
+  // restart dormancy. See src/watchers.ts for the rationale.
+  //
+  // Delivery prompts the session with a synthetic part - the same mechanism
+  // opencode uses for background task completions - so a watched event
+  // triggers a model turn even when the user is away. Events carry pointer
+  // data plus machine status (check conclusions, exit codes); the model
+  // fetches logs and further details itself with gh.
+  // Watched-command runner: resolves the spawn cwd per poll. When the
+  // project directory is deleted mid-watch (worktree merged and cleaned up),
+  // the poll falls back to the repo_paths cache's main checkout instead of
+  // spinning ENOENT errors until the TTL. The wrapper logs the fallback
+  // once per dead directory - per-cycle error logging is the existing
+  // failure mode and it spams.
+  const watchedCommandRunner = withCwdFallback(runWatchedCommand, (cwd) => resolveSpawnCwd(cwd, repoCache), (from, to) => {
+    console.error(`[thatch] project directory ${from} deleted; watcher falling back to main checkout ${to}`);
+  });
+
+  const watchers = new WatcherRegistry({
+    // Journal watcher definitions so a v2 plugin reload (same process) can
+    // re-arm them; the registry journals after every membership change.
+    // Disposed check FIRST: a poll cycle suspended at an await can outlive
+    // watchers.dispose() and reach this callback after db.close(); with the
+    // lazy reopen it would otherwise hand a stale writer a fresh connection
+    // and resurrect an expired watcher after the reload. Same ownership rule
+    // as the extraction callback and journalChild.
+    journal: (sessionID, sessionWatchers) => {
+      if (disposed) return;
+      if (sessionWatchers.length === 0) db.runtimeStateDelete("watchers", sessionID);
+      else db.runtimeStatePut("watchers", sessionID, sessionWatchers, directory);
+    },
+    deliver: async (sessionID, events) => {
+      // Events carry their watch's target label from the registry, so the
+      // notification header is correct for every source (PRs, branches,
+      // commands, CI events whose URLs would not parse).
+      await caps.promptSession(
+        sessionID,
+        {
+          parts: [
+            { type: "text", text: watcherNotificationNudge(events[0]?.target ?? "watched target", events, watchers.pollSeconds), synthetic: true },
+          ],
+        },
+        "async",
+      );
+      // Toast: the notification part is TUI-hidden, so without this the
+      // user watching the session sees the model wake up with no visible
+      // cause. Announce what fired. Failed checks/workflows surface as a
+      // warning variant; routine events as info. Best-effort - the TUI may
+      // not be connected (headless mode).
+      const failed = events.some((e) => e.summary.includes("failure"));
+      const more = events.length > 1 ? ` +${events.length - 1} more` : "";
+      try {
+        await caps.showToast({
+          message: `⏰ ${events[0]?.target ?? "watched target"}: ${events[0]?.summary ?? ""}${more}`,
+          variant: failed ? "warning" : "info",
+          duration: 5000,
+        });
+      } catch {
+        // TUI may not be connected. Best-effort.
+      }
+    },
+    canDeliver: canPromptSession,
+    ghRunner: ghApiRun,
+    commandRunner: watchedCommandRunner,
+  });
+  // gh presence decides whether watch_create and watch_branch_create work;
+  // checked lazily by the tools, but log once at startup so misconfiguration
+  // is visible in debug logs. watch_command_create needs only bash, not gh.
+  void ghAvailable().then((ok) => {
+    if (!ok) console.error("[thatch] gh CLI not found - GitHub watch tools will report unavailable");
+  });
+  watchers.start();
+
+  // 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.
+  // Startup-resumed chat sessions. A Set (not a scalar): one plugin
+  // instance can serve several sessions - shared-server tabs in the same
+  // directory each resolve their own -c/-s target.
+  const resumedSessions = new Set<string>();
+
+  // 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: () => {
+      const now = Date.now();
+      const hosted = hostedSessionIds({
+        statusKeys: sessionStatus.keys(),
+        resumedSessions: resumedSessions,
+        rehostedSessions: [...rehostedSessions, ...unexpiredGraceRehosts(rehostGrace, now)],
+        exclude: childToParent.keys(),
+      });
+      // The journal NEVER SHRINKS within a process lifetime: a plugin
+      // reload rebuilds the hosted set empty (sessionStatus is in-memory),
+      // so a session that was idle across a reload would otherwise be
+      // dropped from the set and never re-hosted - falsely stale while its
+      // tab is open. The union means the next reload re-graces everything
+      // this process ever hosted (bounded by the 24h grace decay);
+      // shrinking happens only through session.deleted, which rewrites the
+      // row.
+      const prevRow = db
+        .runtimeStateAll()
+        .find((r) => r.kind === "hosted" && r.sessionID === directory);
+      const prevIds = prevRow && Array.isArray(prevRow.value) ? (prevRow.value as string[]) : [];
+      const merged = [...new Set([...prevIds, ...hosted])];
+      db.runtimeStatePut("hosted", directory, merged, directory);
+      return hosted;
+    },
+    deliver: async (sessionID, senders, count) => {
+      await caps.promptSession(
+        sessionID,
+        {
+          parts: [{ type: "text", text: chatNotificationNudge(senders, count), synthetic: true }],
+        },
+        "async",
+      );
+      try {
+        await caps.showToast({
+          message: `💬 chat: ${count} unread from ${senders.join(", ")}`,
+          variant: "info",
+          duration: 5000,
+        });
+      } catch {
+        // TUI may not be connected. Best-effort.
+      }
+    },
+    canDeliver: canPromptSession,
+  });
+  // With chat disabled the tools refuse, so the poller would only heartbeat
+  // 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 caps.sessionGet(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));
+  // The session whose journalled runtime state a restart inherits: -s names
+  // it on the command line; -c means "most recent top-level session in this
+  // directory", resolved straight from the session database because the
+  // rehydration loop below is synchronous and the v2 plugin context has no
+  // session.list for the SDK route. Resolving it HERE is the point -
+  // after the loop, the inherited rows are already pruned.
+  const continueTarget = continueLast && startupSession === undefined
+    ? mostRecentTopLevelSessionId(directory ?? worktree)
+    : null;
+  const inheritSession = startupSession ?? continueTarget ?? undefined;
+  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) {
+    resumedSessions.add(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 caps.sessionList();
+        const target = continuesLastSessionId(data ?? []);
+        debug("chat:startup", `-c resolved: ${target ?? "none"}`);
+        if (!target || db.hasChatLeaveTombstone(target)) return;
+        resumedSessions.add(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
+  // error. Cleared by experimental.compaction.autocontinue (success), the
+  // session.compacted event (redundant belt-and-suspenders), or chat.message
+  // itself when a non-compaction message arrives (compaction failure fallback
+  // - autocontinue never fired, so the next real user message clears the
+  // stale flag). If all three somehow miss, the flag leaks (graceful
+  // degradation: nudges stay off for that session, but no crash).
+  const compacting = new Set<string>();
+
+  // Per-session count of consecutive extraction nudges delivered without any
+  // memory_remember call in between. Drives nudge escalation: the agent gets
+  // a couple of polite chances, then the tone shifts to directive, then to
+  // all-caps shouting. Reset to 0 whenever the agent writes a memory.
+  const missedNudges = new Map<string, number>();
+
+  // Parent-child session mapping for cross-session buffer drain. opencode
+  // creates real child sessions with their own IDs for sub-agents; without
+  // this map, a memory_remember call in a child (e.g. a background
+  // fact-extractor task) drains the child's empty buffer but leaves the
+  // parent's buffer untouched, causing the nudge to replay indefinitely.
+  // Populated from session.created events that carry a parentID.
+  const childToParent = new Map<string, string>();
+
+  // Per-child kind ("extraction" | "task"), recorded at session.created from
+  // the live extractionChildren set and at restore from the journal record.
+  // The parent-state mutations a child's lifecycle triggers (snapshot drain
+  // on memory write, whole-set requeue on error/deletion) are only correct
+  // for extraction children - a task sub-agent saving its own findings never
+  // processed the parent's buffer, and treating its lifecycle as extraction
+  // evidence silently dropped in-flight or pending entries (the v2
+  // all-children-linked loss vector, September 2026).
+  const childKinds = new Map<string, "extraction" | "task">();
+
+  // Snapshot of the parent's buffer at the moment each child was dispatched.
+  // When the child writes a memory, consumeSnapshot drains only these entries
+  // (by reference identity), preserving interleaved-turn entries that arrived
+  // while the sub-agent was running. Without this, the child's memory_remember
+  // would drain the parent's ENTIRE buffer - silently dropping facts from
+  // any tool calls the parent made concurrently with the sub-agent.
+  const parentSnapshots = new Map<string, ToolInteraction[]>();
+
+  // Parent sessions with an active direct-extraction child. When the parent
+  // goes idle with pending tool interactions, the plugin creates a child
+  // session and prompts it directly through the host's prompt capability
+  // instead of injecting a nudge into the next user message. This set
+  // suppresses the nudge path
+  // while the child runs, and prevents re-triggering if the parent goes idle
+  // again before the child finishes. Cleared when the child goes idle, errors,
+  // or is deleted. If direct extraction fails, the set is cleared so the nudge
+  // path takes over as a fallback on the next chat.message.
+  const extracting = new Set<string>();
+
+  // Child session IDs created by triggerExtraction (direct extraction only).
+  // The child idle handler uses this to distinguish plugin-created extraction
+  // children from task-dispatched sub-agents (code review specialists, the
+  // nudge-path fact-extractor, any model-dispatched task). Only extraction
+  // children get the full cleanup: buffer drain, session deletion, toast.
+  // Non-extraction children get claim-scoped completion (a no-op for a
+  // child that never fetched a payload) + missedNudges.reset so their
+  // sessions are not deleted out from under the task tool that dispatched
+  // them.
+  const extractionChildren = new Set<string>();
+
+  // Per-child-session extraction metrics for the toast notification. When the
+  // child session goes idle, these counts are formatted into a toast that
+  // shows the user thatch is working without polluting the conversation.
+  // Keyed by child session ID. Cleaned up on child idle, error, or deletion.
+  const childMetrics = new Map<string, { new: number; updated: number; deleted: number }>();
+
+  // Journal the child bookkeeping (parent link, buffer snapshot, metrics) so
+  // a v2 plugin reload can rehydrate an in-flight extraction instead of
+  // orphaning it. A child with no parent entry journals a delete. The kind
+  // marker distinguishes extraction children from task-dispatched sub-agents
+  // (the live source of truth is the extractionChildren set): restoring a
+  // task sub-agent as an extraction child let its idle take the extraction
+  // branch - consumeSnapshot silently dropped the parent's buffered entries
+  // without extraction, and the task tool's session got a delete call.
+  const journalChild = (childId: string) => {
+    if (disposed) return;
+    const parentID = childToParent.get(childId);
+    if (!parentID) {
+      db.runtimeStateDelete("child", childId);
+      return;
+    }
+    db.runtimeStatePut("child", childId, {
+      kind: extractionChildren.has(childId) ? "extraction" : "task",
+      parentID,
+      snapshot: parentSnapshots.get(childId) ?? [],
+      metrics: childMetrics.get(childId) ?? { new: 0, updated: 0, deleted: 0 },
+    }, directory);
+  };
+
+  // Wrap-up slash commands (/thatch/compact, /thatch/exit) awaiting their
+  // greenlight check. command.execute.before marks the session when one of
+  // these commands runs; when the session next goes idle, the plugin reads
+  // the final assistant message for the ready token (the greenlight) and
+  // triggers the TUI action. Token absence means the model listed blockers
+  // instead, so nothing fires beyond a toast. Cleared on resolution or on
+  // session deletion.
+  const pendingWrapUp = new Map<string, { token: string; kind: "compact" | "exit" }>();
+
+  // Rehydrate persisted runtime state (docs/dev/features/opencode-plugin.md,
+  // the runtime_state row).
+  // Rows are instance-scoped (kind+session, tagged with the writer's pid and
+  // location directory):
+  // - same pid, same directory: a v2 plugin reload rebuilt THIS instance's
+  //   graph - rehydrate everything.
+  // - same pid, other directory: a live sibling instance's rows (one serve
+  //   hosts one instance per location) - leave them alone; hydrating them
+  //   would double-poll watchers and re-deliver another instance's state.
+  // - foreign pid: a process restart, whose sessions died with their
+  //   harness. Only a startup-resumed session (-s/-c) in this directory
+  //   inherits recovery-safe state; everything else is pruned.
+  const rehydratedSessions = new Set<string>();
+  // Extraction children restored by a same-pid reload (childId -> parentId).
+  // Their idle event may have fired during the reload window and been lost;
+  // reconciled after setup (see reconcileRestoredChildren).
+  const restoredChildren = new Map<string, string>();
+  // Sessions this instance hosted, restored from the journal on a reload
+  // (same pid + same directory). Written through by the poller's hosted-set
+  // read, so the next reload picks up the latest set.
+  const rehostedSessions = new Set<string>();
+  // Foreign-pid hosted rows (restart): the dead daemon's hosted set,
+  // re-hosted under a grace window instead of dropped - open TUI tabs
+  // reconnect but emit no events until the user types. id -> grace
+  // deadline (epoch ms).
+  const rehostGrace = new Map<string, number>();
+  const rehydrated: Record<string, number> = {};
+  for (const row of db.runtimeStateAll()) {
+    const samePid = row.pid === process.pid;
+    const ownDirectory = row.directory === directory;
+    const isStartup = inheritSession !== undefined && row.sessionID === inheritSession;
+    if (samePid && !ownDirectory) continue; // live sibling - untouched
+    if (!samePid && !ownDirectory) continue; // another location's instance owns these rows - its own restart cleans them
+    if (!samePid && !isStartup) {
+      // Watcher definitions survive a restart as DORMANT rows instead of
+      // being pruned: the defining session's harness died with the old
+      // process, but the session itself is resumable (session picker, v2
+      // tab reopen), and resuming it re-arms the watches through
+      // scanDormantWatchers. Rows whose every definition outlived the
+      // watcher TTL plus the dormant grace period age out here instead -
+      // corpses of sessions that will probably never return.
+      if (row.kind === "watchers" && !dormantWatchersStale((row.value as Watcher[] | null) ?? [])) {
+        continue;
+      }
+      // A foreign-pid HOSTED row re-hosts under a grace window instead of
+      // being pruned: open TUI tabs reconnect to the new daemon but emit
+      // no events until the user types, so dropping the set made them
+      // falsely stale ("presumed gone") while alive-idle, and mail to
+      // them stopped waking the tab. Sessions that emit activity graduate
+      // to permanent hosting via the event stream; still-silent ones
+      // (closed tabs) age out at the grace and go stale. The row itself
+      // stays: the poller's next hosted-set journal rewrites it, and a
+      // further restart re-graces whatever it then holds.
+      if (row.kind === "hosted") {
+        for (const id of (row.value ?? []) as string[]) {
+          rehostGrace.set(id, Date.now() + CHAT_REHOST_GRACE_MS);
+        }
+        continue;
+      }
+      db.runtimeStateDelete(row.kind, row.sessionID);
+      continue;
+    }
+    if (row.kind === "buffer") {
+      extraction.hydrate(row.value as ToolInteraction[], []);
+    } else if (row.kind === "accepted") {
+      // On a RESTART the extractor child died with the old process - there
+      // is nobody left to complete the accepted queue, and the first
+      // unrelated completion signal would silently drop it. Requeue as
+      // pending instead: the resumed session's next nudge honestly
+      // re-extracts it. On a reload the child may still be running and
+      // stays accepted.
+      if (!samePid) extraction.hydrate(row.value as ToolInteraction[], []);
+      else extraction.hydrate([], row.value as ToolInteraction[]);
+    } else if (row.kind === "watchers") {
+      watchers.hydrate((row.value ?? []) as Watcher[]);
+    } else if (row.kind === "hosted") {
+      // Same-pid reload: re-host permanently (the plugin re-ran in place;
+      // the sessions may still be running). Foreign-pid rows were graced
+      // in the restart branch above.
+      for (const id of (row.value ?? []) as string[]) rehostedSessions.add(id);
+    } else if (row.kind === "child") {
+      const rec = row.value as { kind?: "extraction" | "task"; parentID?: string; snapshot?: ToolInteraction[]; metrics?: { new: number; updated: number; deleted: number } };
+      if (samePid && rec?.parentID) {
+        // Reload: the child may still be running - restore its live
+        // bookkeeping so its idle event finds the maps populated. The
+        // default covers rows written before the marker existed; it errs
+        // toward extraction (defaulting to task would strand a legacy
+        // in-flight extraction child with extracting never restored,
+        // suppressing both extraction paths for the session's life), at
+        // the cost of resurrecting the restore-time misclassification for
+        // the rarer pre-upgrade in-flight task child - a one-window trade,
+        // self-healing as rows are rewritten with kinds.
+        const kind = rec.kind ?? "extraction";
+        childKinds.set(row.sessionID, kind);
+        childToParent.set(row.sessionID, rec.parentID);
+        parentSnapshots.set(row.sessionID, rec.snapshot ?? []);
+        if (rec.metrics) childMetrics.set(row.sessionID, rec.metrics);
+        if (kind === "extraction") {
+          extractionChildren.add(row.sessionID);
+          extracting.add(rec.parentID);
+          restoredChildren.set(row.sessionID, rec.parentID);
+        }
+      } else {
+        // Restart: the child ran in the dead process and no execution event
+        // will ever arrive for it. Recover the snapshot as plain pending
+        // entries (extraction stays available) and drop the record - never
+        // restore `extracting`, which would suppress both extraction paths
+        // for the resumed session forever. The guard tests the child's
+        // PARENT against the inherited session, not the row's own session
+        // id: child rows are keyed by child id, so an isStartup-style check
+        // could never hold and the snapshot recovery was unreachable.
+        if (inheritSession !== undefined && rec?.parentID === inheritSession && Array.isArray(rec.snapshot)) {
+          for (const interaction of rec.snapshot) extraction.push(interaction);
+        }
+        db.runtimeStateDelete(row.kind, row.sessionID);
+        continue;
+      }
+    } else if (row.kind === "wrapup") {
+      if (!samePid) {
+        // An armed wrap-up inherited across a restart could auto-fire
+        // compact/exit on the resumed session's first idle if the final
+        // message already carries the token. Too dangerous to inherit.
+        db.runtimeStateDelete(row.kind, row.sessionID);
+        continue;
+      }
+      pendingWrapUp.set(row.sessionID, row.value as { token: string; kind: "compact" | "exit" });
+    } else {
+      continue; // unknown kind - leave it for a future version
+    }
+    rehydrated[row.kind] = (rehydrated[row.kind] ?? 0) + 1;
+    rehydratedSessions.add(row.sessionID);
+  }
+  if (Object.keys(rehydrated).length > 0) {
+    const counts = Object.entries(rehydrated)
+      .map(([kind, n]) => `${kind}=${n}`)
+      .join(" ");
+    debug("runtime:rehydrate", `restored ${counts}`);
+    // Ping the restored sessions directly: the reload/restart happened
+    // outside their event stream, so without this the sessions would not
+    // know the plugin is back. Synthetic + noReply on v1 renders a visible
+    // bubble and starts no model turn. On v2 there is no turn-free delivery
+    // (a noReply body falls through to session.prompt: a real message and a
+    // model turn in every restored session on every file save), so v2 skips
+    // the notice entirely - the re-hosted poller's mail delivery is the
+    // wake there.
+    if (chatOn && caps.noReplyDelivery) {
+      for (const sessionID of rehydratedSessions) {
+        void caps
+          .promptSession(
+            sessionID,
+            {
+              parts: [
+                {
+                  type: "text",
+                  text: "[thatch] plugin reloaded - persisted state restored (extraction buffers, watchers, wrap-ups). No action needed.",
+                  synthetic: true,
+                },
+              ],
+              noReply: true,
+            },
+            "async",
+          )
+          .catch(() => {
+            // The session may be gone (restart prune edge) - the poller's
+            // normal gates handle delivery; nothing to do here.
+          });
+      }
+    }
+  }
+
+  // Dormant watcher recovery (watcher-continuity fast-follow). A restart
+  // keeps foreign-pid watcher journal rows instead of pruning them (see the
+  // rehydration loop): the defining session's harness died, but the session
+  // is resumable. A resumed session's first message scans the dormant rows:
+  //   - the session's own rows re-arm into the live registry (no
+  //     re-registration step, so stated watch policy survives reboots);
+  //   - rows of other still-dead sessions in THIS directory earn the live
+  //     session a one-line death notice - a watch that will never fire is
+  //     at least heard about. Deduplicated per process per target, so one
+  //     active session hears about each corpse once;
+  //   - rows past the TTL plus the dormant grace age out silently.
+  // Death notices are gated on the owning pid actually being dead: a v1
+  // sibling process (separate TUI window, shared project db, different pid,
+  // still alive) owns live watchers that must never be reported dead.
+  const dormantScanned = new Set<string>();
+  const notifiedWatcherDeaths = new Set<string>();
+  const pidAlive = (pid: number): boolean => {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      // ESRCH: no such process. Anything else (e.g. EPERM on a foreign-user
+      // pid) means the pid exists - fail toward "alive" and stay silent.
+      return (err as NodeJS.ErrnoException).code !== "ESRCH";
+    }
+  };
+  const scanDormantWatchers = async (sessionID: string): Promise<string[]> => {
+    if (dormantScanned.has(sessionID)) return [];
+    dormantScanned.add(sessionID);
+    try {
+      const rows = db.runtimeStateAll().filter((r) => r.kind === "watchers" && r.pid !== process.pid);
+      const own: Watcher[] = [];
+      const deadSessions = new Map<string, string[]>();
+      for (const row of rows) {
+        const defs = Array.isArray(row.value) ? (row.value as Watcher[]) : [];
+        if (dormantWatchersStale(defs)) {
+          db.runtimeStateDelete("watchers", row.sessionID);
+          continue;
+        }
+        if (row.sessionID === sessionID) {
+          // The startup-resume case hydrated these live at setup already -
+          // re-arming is a no-op there and the notice would be redundant.
+          if (!rehydratedSessions.has(sessionID)) own.push(...defs);
+        } else if (row.directory === directory && !pidAlive(row.pid)) {
+          // Dedup per dead SESSION (not per target): a resumed-then-died-
+          // again cycle re-arms the same session under new ids, and its
+          // second death deserves a fresh notice. Its own re-arm clears
+          // the entry below.
+          if (!notifiedWatcherDeaths.has(row.sessionID)) {
+            deadSessions.set(row.sessionID, defs.map(watcherTarget));
+          }
+        }
+      }
+      for (const dead of deadSessions.keys()) notifiedWatcherDeaths.add(dead);
+      const notices: string[] = [];
+      if (own.length > 0) {
+        const { rearmed, expired, failed } = await watchers.rearm(sessionID, own);
+        // This session came back to life: its own previous death notice is
+        // obsolete - a future death deserves a fresh one.
+        notifiedWatcherDeaths.delete(sessionID);
+        if (rearmed.length > 0) notices.push(watcherRearmNotice(rearmed.map(watcherTarget), expired, failed));
+      }
+      if (deadSessions.size > 0) {
+        const targets = [...new Set([...deadSessions.values()].flat())];
+        notices.push(watcherDeathNotice(targets));
+      }
+      return notices;
+    } catch (err) {
+      // Recovery must never break the message that triggered it.
+      console.error(`[thatch] dormant watcher scan failed for ${sessionID}: ${err}`);
+      return [];
+    }
+  };
+
+  // Finalizes an extraction child that finished. The session.status idle
+  // handler calls it when the child's idle event arrives; the reload
+  // reconciler calls it for restored children whose idle event was lost to
+  // the reload window.
+  const finishExtractionChild = async (sessionID: string, parentID: string) => {
+    if (extractionChildren.has(sessionID)) {
+      // The child's claimed delivery is consumed by completeClaimed below -
+      // the fetch recorded exactly what the child received, so nothing else
+      // is dropped here. Entries the child never received (post-fetch
+      // arrivals, or a never-fetched payload) stay pending and re-nudge;
+      // the old snapshot drain here would have silently dropped the
+      // never-fetched case without extraction. (Snapshot drain removed
+      // September 2026 - claim semantics subsume it. The journal's
+      // snapshot field remains for restart recovery.)
+
+      // Fire a toast with the extraction metrics. Only show a toast when
+      // memories were actually written - no toast for no-save runs to avoid
+      // notification fatigue.
+      const metrics = childMetrics.get(sessionID);
+      const parts: string[] = [];
+      if (metrics) {
+        if (metrics.new > 0) parts.push(`new: ${metrics.new}`);
+        if (metrics.updated > 0) parts.push(`updated: ${metrics.updated}`);
+        if (metrics.deleted > 0) parts.push(`deleted: ${metrics.deleted}`);
+      }
+      if (parts.length > 0) {
+        try {
+          await caps.showToast({
+            message: `💭 ${parts.join(", ")}`,
+            variant: "success",
+            duration: 4000,
+          });
+        } catch {
+          // TUI may not be connected (e.g. headless mode).
+        }
+      }
+
+      // Scope the completion to THIS child's claimed delivery. A fetcher
+      // that never fetched (a sibling sub-agent going idle, an extractor
+      // that crashed before its payload call) has no claim and must not
+      // drop the accepted set - another extractor may hold it in flight.
+      extraction.completeClaimed(sessionID);
+      missedNudges.delete(parentID);
+      extracting.delete(parentID);
+      childKinds.delete(sessionID);
+      childToParent.delete(sessionID);
+      parentSnapshots.delete(sessionID);
+      childMetrics.delete(sessionID);
+      extractionChildren.delete(sessionID);
+      journalChild(sessionID);
+      extraction.consume(sessionID);
+      // Delete the child session to avoid clutter.
+      try {
+        await caps.sessionDelete(sessionID);
+      } catch {
+        // Best-effort - the child is idle and harmless if not deleted.
+      }
+    } else {
+      // Task-dispatched sub-agent went idle. Complete only what THIS child
+      // claimed via its payload fetch - sibling specialists going idle have
+      // no claim and must be a no-op, or their idle signal drops another
+      // extractor's in-flight accepted payload. An extractor that never
+      // fetched leaves its entries held; requeueStaleAccepted bounds the
+      // linger.
+      extraction.completeClaimed(sessionID);
+      missedNudges.delete(parentID);
+    }
+  };
+
+  // A restored child may have gone idle DURING the reload window - its idle
+  // event fired before the plugin's event pump resubscribed and was lost.
+  // Without reconciliation, `extracting` stays populated forever and BOTH
+  // extraction paths stay suppressed for the session's life. Wait a beat
+  // for the pump to repopulate the status map, then finalize any restored
+  // child that is no longer running. A child genuinely mid-turn keeps its
+  // own idle event, and the finalize is idempotent if both paths race.
+  const reconcileRestoredChildren = async () => {
+    if (restoredChildren.size === 0) return;
+    await new Promise<void>((resolve) => {
+      const t = setTimeout(resolve, 10_000);
+      t.unref?.();
+    });
+    // Dispose (a v2 plugin reload or process exit) may have closed the db
+    // during the 10s window; finalizing into it would throw on the journal
+    // write. The reloaded instance's own reconciler owns the rows now.
+    if (disposed) return;
+    let live: Record<string, { type: string }> = {};
+    try {
+      live = (await caps.fetchStatuses()) ?? {};
+    } catch {
+      // Map-only liveness then - the event-fed statuses are the fallback.
+    }
+    for (const [childId, parentId] of restoredChildren) {
+      const mapped = sessionStatus.get(childId);
+      const remote = live[childId]?.type;
+      if (remote === "busy" || remote === "retry" || mapped === "busy" || mapped === "retry") continue;
+      restoredChildren.delete(childId);
+      await finishExtractionChild(childId, parentId);
+    }
+  };
+  void reconcileRestoredChildren();
+
+  // Skills always install to the global opencode config - installing into the
+  // worktree would mutate the user's repo (untracked files in git status).
+  // A failed install degrades the nudge workflow but must not kill the plugin.
+  try {
+    installSkills(join(configHome, "opencode", "skills"), [
+      ...SHARED_SKILLS,
+      ...OPENCODE_ONLY_SKILLS,
+    ]);
+  } catch (err) {
+    console.error(`[thatch] skill install failed: ${err}`);
+  }
+
+  // Same for the wrap-up slash commands: synced into the global config dir on
+  // every load so template updates self-heal. Config is loaded before plugins
+  // during server startup, so a first-ever install lands on the next start.
+  // Hosts that register commands natively (v2) get the action commands as
+  // files only - the wrap-ups register in code (onCommandExecuteBefore), and a file with
+  // the same name as a registered command would collide.
+  try {
+    if (caps.nativeCommands) removeWrapUpCommandFiles(configHome);
+    installOpencodeCommands(configHome, caps.nativeCommands ? opencodeActionCommandDefs() : undefined);
+  } catch (err) {
+    console.error(`[thatch] command install failed: ${err}`);
+  }
+
+  const sys = systemPrompt(repo, chatOn);
+  const compact = compactionContext(repo);
+
+  // Direct extraction: create a child session linked to the parent and prompt
+  // it with the extraction payload. The child runs the fact-extractor skill,
+  // writes memories, and goes idle. The existing childToParent / snapshot
+  // drain machinery handles buffer cleanup. The nudge path is a fallback if
+  // this throws.
+  //
+  // Does NOT call extraction.accept - entries stay in pending so consumeSnapshot
+  // can drain them by reference identity when the child writes a memory. The
+  // extracting set (not accept) suppresses the nudge in chat.message.
+  //
+  // The child ID is added to extractionChildren so the idle handler can
+  // distinguish plugin-created extraction children from task-dispatched
+  // sub-agents. Only extraction children get the full cleanup (buffer drain,
+  // session deletion, toast).
+  async function triggerExtraction(parentID: string): Promise<void> {
+    extracting.add(parentID);
+
+    const batch = extraction.peek(parentID);
+    const promptText = extractionDirectPrompt(batch.length, parentID);
+
+    const result = await caps.sessionCreate({
+      parentID,
+      title: "thatch-extraction",
+    });
+    // session.created event fires here, setting childToParent and
+    // parentSnapshots (snapshot of the full pending buffer, since we
+    // have not called accept).
+    const childId = result.id;
+    extractionChildren.add(childId);
+    // v2's session API cannot create a CHILD session (no parentID in its
+    // create input), so the adapter returns a top-level session and no
+    // session.created event carries the parent mapping. Set both here
+    // eagerly; on v1 the event sets the same values (idempotent).
+    if (!childToParent.has(childId)) {
+      childToParent.set(childId, parentID);
+      parentSnapshots.set(childId, [...extraction.peek(parentID)]);
+    }
+    journalChild(childId);
+
+    // Clean up the child session and all map entries if prompting fails.
+    // Without this, the child exists on the server but was never prompted,
+    // so it never goes idle and the maps leak.
+    const cleanupChild = () => {
+      extracting.delete(parentID);
+      extractionChildren.delete(childId);
+      childKinds.delete(childId);
+      childToParent.delete(childId);
+      parentSnapshots.delete(childId);
+      childMetrics.delete(childId);
+      journalChild(childId);
+      try { void caps.sessionDelete(childId); } catch {}
+    };
+
+    const bgEnabled =
+      process.env.OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS === "true" ||
+      process.env.OPENCODE_EXPERIMENTAL === "true";
+
+    if (bgEnabled) {
+      try {
+        await caps.promptSession(
+          childId,
+          {
+            parts: [{ type: "text", text: promptText }],
+          },
+          "async",
+        );
+      } catch (err) {
+        console.error(`[thatch] extraction child prompt failed: ${err}`);
+        cleanupChild();
+        throw err;
+      }
+    } else {
+      // Fire and forget - the parent is already idle, so blocking the event
+      // handler would only delay other event processing. The child runs to
+      // completion and its idle event triggers cleanup.
+      caps
+        .promptSession(
+          childId,
+          {
+            parts: [{ type: "text", text: promptText }],
+          },
+          "sync",
+        )
+        .catch((err: unknown) => {
+          console.error(`[thatch] extraction child failed: ${err}`);
+          cleanupChild();
+        });
+    }
+  }
+
+  // Hook-semantics handlers for the memory/extraction tools. Both direct
+  // tool calls (input.tool match in onToolExecuteAfter) and Code Mode
+  // execute calls that wrap them (unwrapExecuteThatchCalls) must run the
+  // same logic, so the bodies live here instead of inline in the hook.
+  const toolMemoryRemember = async (sessionID: string, overwrite: unknown) => {
+    extraction.consume(sessionID);
+    missedNudges.delete(sessionID);
+    // A session that fetched its own payload (direct parent-side fetch or a
+    // child's payload call) completes its claim when it writes a memory -
+    // the write proves the delivered entries were processed.
+    extraction.completeClaimed(sessionID);
+    // Track extraction metrics for toast display. Counted for any
+    // child session (both direct-extraction and nudge-path sub-agents)
+    // since childToParent covers both. The toast only fires for
+    // extraction children (extractionChildren set) on idle.
+    const parentID = childToParent.get(sessionID);
+    if (parentID) {
+      const metrics = childMetrics.get(sessionID) ?? { new: 0, updated: 0, deleted: 0 };
+      if (overwrite) metrics.updated++;
+      else metrics.new++;
+      childMetrics.set(sessionID, metrics);
+      journalChild(sessionID);
+      // Complete the parent's accepted entries (the extractor confirmed
+      // it is alive and saving). Completion is scoped to THIS child's
+      // claimed delivery - the fetch IS the delivery record, so whatever
+      // the child received is consumed here and nothing else. Pending
+      // entries the child never received (post-fetch arrivals, or a child
+      // that never fetched) stay pending and re-nudge: no silent loss.
+      // (The old dispatch-time snapshot drain was either a no-op under
+      // claim semantics or a silent-loss vector for children that never
+      // fetched - removed September 2026. The journal's snapshot field
+      // remains for restart recovery.)
+      extraction.completeClaimed(sessionID);
+      journalChild(sessionID);
+      missedNudges.delete(parentID);
+      journalChild(sessionID);
+      missedNudges.delete(parentID);
+    }
+  };
+  const toolExtractionDone = (sessionID: string, targetID?: string) => {
+    const parentID = childToParent.get(sessionID);
+    if (parentID) {
+      // The child's completion consumes its own claimed delivery. The
+      // whole-set fallback covers a child that acks without ever fetching
+      // (its payload call errored) - rare, and the ack is a deliberate
+      // processed signal, unlike the automatic idle path which is
+      // claim-scoped only.
+      if (!extraction.completeClaimed(sessionID)) {
+        extraction.completeAccepted(parentID);
+      }
+      missedNudges.delete(parentID);
+      extraction.consume(sessionID);
+    } else if (targetID && targetID !== sessionID) {
+      // A completion ack for ANOTHER session - the fact-extractor sub-agent
+      // naming its parent. v2 links no parentID on dispatched sessions
+      // (SessionCreateInput has none), so childToParent cannot know this
+      // relationship and the explicit session_id is the only signal that
+      // the target's accepted entries are accounted for. Without this
+      // branch the accepted queue lingers forever and a tool-dense session
+      // re-nudges every idle on never-draining exhaust. Completion is
+      // scoped to the child's claimed delivery; the whole-set fallback
+      // covers the no-claim case (a fetch that errored, or the MCP path
+      // where the file-backed queue was drained instead).
+      if (!extraction.completeClaimed(sessionID)) {
+        extraction.completeAccepted(targetID);
+      }
+      missedNudges.delete(targetID);
+    } else {
+      extraction.accept(sessionID);
+    }
+    missedNudges.delete(sessionID);
+  };
+  const toolMemoryForget = (sessionID: string) => {
+    const metrics = childMetrics.get(sessionID) ?? { new: 0, updated: 0, deleted: 0 };
+    metrics.deleted++;
+    childMetrics.set(sessionID, metrics);
+  };
+
+  return {
+    coreContext: buildCoreContext(db, model, repo, {
+      extractionPayloadProvider: (targetID: string, fetcherID?: string): string | null => {
+        // A fetcher identity turns the fetch into the delivery record: the
+        // claimed entries stay accepted, and THAT fetcher's completion
+        // signal consumes only them (claim semantics). Without a fetcher
+        // (no host session context) the fetch is a pure peek - legacy
+        // behavior.
+        const all = fetcherID
+          ? extraction.claim(targetID, fetcherID)
+          : [...extraction.peekAccepted(targetID), ...extraction.peek(targetID)];
+        if (all.length === 0) return null;
+        return extraction.buildPayload(all, repo);
+      },
+      watcherRegistry: watchers,
+      projectDir: worktree,
+    }),
+    debug,
+    childSessionIds: () => [...extractionChildren],
+
+    // 1. System prompt - always in context.
+    onSystemTransform: async (output) => {
+      output.system.push(sys);
+    },
+
+    // 2. Compaction context - re-familiarizes after compaction. The flag
+    //    suppresses chat.message nudges during summary generation (tool
+    //    calls are blocked there).
+    onSessionCompacting: async (input, output) => {
+      compacting.add(input.sessionID);
+      output.context.push(compact);
+    },
+
+    // 2b. Clear the compacting flag after compaction succeeds so chat.message
+    //     nudges resume for the synthetic auto-continue turn and beyond.
+    onCompactionAutocontinue: async (input) => {
+      compacting.delete(input.sessionID);
+    },
+
+    // 3. Tool buffering - feeds the extraction pipeline (direct extraction
+    //    via SDK or nudge fallback). Excluded tools:
+    //    - thatch_*: extracting facts from memory ops would echo the store
+    //    - skill/task: meta-tools that orchestrate agent behavior (loading
+    //      skills, dispatching sub-agents). Buffering them creates a feedback
+    //      loop - extraction triggers a skill load, which gets buffered, which
+    //      triggers another extraction on the next turn.
+    //    Memory writes consume the buffer and reset the missed-nudge counter.
+    //    The buffer is NOT drained on nudge delivery - it persists until the
+    //    agent writes a memory, so ignored nudges accumulate and the payload
+    //    grows with each missed cycle.
+    //
+    //    Buffer lifecycle is AMQP-style accept/complete, so a failed
+    //    extractor does not silently drop unprocessed interactions:
+    //    - thatch_extraction_done in the parent ACCEPTS the buffer: it moves
+    //      to a holding area and the nudge quiets, but entries are not
+    //      dropped yet.
+    //    - COMPLETE drops the held entries. Signals: a memory_remember or
+    //      extraction_done call in a child session of that parent (the
+    //      extractor confirming it processed them), or the child going idle
+    //      (a no-save run that never acks still counts as processed).
+    //      Completion is CLAIM-SCOPED: the pipeline records which fetcher
+    //      received the payload (get_extraction_payload), and a completion
+    //      signal consumes only that fetcher's delivery. A sibling
+    //      sub-agent going idle - a code-review specialist, a slow child
+    //      from a previous round - has no claim and is a no-op, so it can
+    //      no longer silently drop another extractor's in-flight payload
+    //      (the accept-then-racing-completion loss, fixed September 2026).
+    //    - REQUEUE returns the held entries to pending. Signals: the child
+    //      session errors or is deleted before completing.
+    //
+    //    A memory_remember call in a child session (sub-agent) also drains
+    //    the parent's pending buffer - but only the entries that existed at
+    //    dispatch time (the snapshot). Entries from interleaved turns survive
+    //    so their facts aren't silently dropped.
+    //
+    //    Code Mode `execute` calls are unwrapped before this filter applies
+    //    (unwrapExecuteThatchCalls): an execute call whose code invokes
+    //    tools.thatch_* runs the wrapped tool's hook semantics and is never
+    //    buffered. Matching on the outer tool name alone would re-queue the
+    //    pipeline's own dispatch/ack traffic every cycle - the self-feeding
+    //    extraction loop this removes (September 2026, observed live in an
+    //    oink session).
+    onToolExecuteAfter: async (input, output) => {
+      const { tool, sessionID } = input;
+      if (tool === "thatch_memory_remember") {
+        await toolMemoryRemember(sessionID, (input.args as Record<string, unknown> | undefined)?.overwrite);
+        return;
+      }
+      // thatch_extraction_done has two roles depending on the session:
+      // - parent, after dispatching the fact-extractor: ACCEPT the buffer
+      //   (quiet the nudge, hold the entries for completion).
+      // - child extractor, at the end of its run: COMPLETE the parent's
+      //   accepted entries, including no-save runs that write no memory,
+      //   and drop the child's own buffer (its work is done).
+      if (tool === "thatch_extraction_done") {
+        toolExtractionDone(sessionID, (input.args as { session_id?: string } | undefined)?.session_id);
+        return;
+      }
+      // Track memory deletions in child sessions for the toast metrics.
+      // Same scoping as the remember handler above - only child sessions,
+      // not the parent or manual memory writes from the user's session.
+      if (tool === "thatch_memory_forget" && childToParent.has(sessionID)) {
+        toolMemoryForget(sessionID);
+        return;
+      }
+      // Chat conversational events echo back into the transcript as visible
+      // message parts. Plugin tools render as muted one-line entries with
+      // the output hidden behind a default-off TUI toggle, so without this
+      // the human watching a session never sees the conversation happen.
+      // Delivery is a non-synthetic noReply promptAsync: the part renders
+      // as a visible bubble and starts no model turn (the server's prompt
+      // path returns before the completion loop). Non-synthetic also means
+      // later turns see the echo in context - a small duplication of the
+      // tool call it mirrors, accepted for visibility. Fire-and-forget: an
+      // echo failure must never fail the tool call it follows.
+      if (input.tool.startsWith("thatch_chat_")) {
+        const echo = chatEchoText(
+          input.tool,
+          (input.args ?? {}) as Record<string, unknown>,
+          typeof output.output === "string" ? output.output : "",
+        );
+        // noReply hosts only: on a host whose prompt endpoint starts a real
+        // model turn, delivering the echo would create a turn that calls
+        // chat tools, which echoes again - the loop the noReply flag exists
+        // to prevent.
+        if (echo && caps.noReplyDelivery) {
+          void caps
+            .promptSession(
+              input.sessionID,
+              {
+                noReply: true,
+                parts: [{ type: "text", text: echo }],
+              },
+              "async",
+            )
+            .catch((err) => {
+              // The echo must never fail the tool call, but a silent catch
+              // would hide a systemic promptAsync failure (bubbles would
+              // stop appearing everywhere with no diagnostics).
+              console.error(`[thatch] chat echo delivery failed: ${err}`);
+            });
+        }
+        return;
+      }
+      // "task" is v1's dispatch tool and "subagent" is v2's - a dispatch
+      // buffers itself otherwise, and the nudge then fires on the pipeline's
+      // own exhaust (the subagent-dispatch loop, sibling of the
+      // execute-wrapped-ack loop below). isMetaToolName owns the set.
+      if (isMetaToolName(input.tool)) return;
+      // Code Mode execute calls: when the code wraps thatch_* invocations,
+      // run the wrapped tools' hook semantics and never buffer the call
+      // itself - it is the pipeline's own traffic, and buffering it feeds
+      // the extraction loop with its own exhaust (the September 2026
+      // infinite dispatch/ack loop). Execute calls that do not touch thatch
+      // tools fall through and buffer as normal: they did real work.
+      if (input.tool === "execute") {
+        const wrapped = unwrapExecuteThatchCalls(input.args);
+        if (wrapped.tools.length > 0) {
+          for (const name of wrapped.tools) {
+            if (name === "thatch_memory_remember") await toolMemoryRemember(sessionID, wrapped.overwrite);
+            else if (name === "thatch_extraction_done") toolExtractionDone(sessionID, wrapped.sessionID);
+            else if (name === "thatch_memory_forget" && childToParent.has(sessionID)) toolMemoryForget(sessionID);
+            // Other thatch_* tools (recall, show, list, ...) carry no hook
+            // semantics - doing nothing with them is the whole point.
+          }
+          return;
+        }
+      }
+      extraction.push({
+        tool: input.tool,
+        sessionID: input.sessionID,
+        args: (input.args as Record<string, unknown>) ?? {},
+        title: output.title,
+        output: typeof output.output === "string" ? output.output : "",
+      });
+      // The push site is the single classification of "this call was real
+      // work" - meta tools and execute-wrapped thatch calls never reach it -
+      // so it is also the done-alert signal. todowrite/question reach it
+      // (the buffer wants them) but are no-work for alerts - see
+      // isNoWorkTool in src/alerts.ts for why they must not move into
+      // isMetaToolName.
+      if (!isNoWorkTool(input.tool)) {
+        alerts.sessionRealWork(sessionID);
+      }
+    },
+
+    // 4. Per-message nudge - two priority tiers:
+    //   a. Extraction nudge: prior tool interactions are queued for fact
+    //      extraction (carries the JSON payload for thatch-fact-extractor).
+    //   b. Recall + prediction + behavior nudge: when no extraction is pending, embed
+    //      the user's prompt (shared embedding for all three) and:
+    //        - search memories by cosine (recall nudge)
+    //        - search matchers by cosine, score predictions (prediction fire)
+    //        - search behavior matchers by cosine, score behaviors (behavior fire)
+    //      All three fire independently; any subset may inject.
+    //      The auto-fires reuse the embedding already computed for recall,
+    //      adding only cosine scans against the matchers tables.
+    //      No extra model calls.
+    //
+    // Skipped during compaction: the agent can't call tools while generating
+    // a summary, so a nudge that says "use thatch_memory_recall" triggers a
+    // blocked-tool error.
+    // Wrap-up commands mark their session here; the actual trigger happens
+    // on the session's next idle event, once the model's greenlight response
+    // is complete.
+    onCommandExecuteBefore: async (input) => {
+      const wrapUp = WRAPUP_COMMANDS[input.command];
+      if (wrapUp) {
+        pendingWrapUp.set(input.sessionID, wrapUp);
+        // Journaled so a v2 plugin reload before the session's next idle
+        // does not silently drop the armed wrap-up. Disposed check FIRST:
+        // a command execute still in flight when the reload's cleanup runs
+        // must not land a stale wrap-up row through the lazy reopen (the
+        // reloaded instance owns the journal rows; same rule as the
+        // extraction and watcher journal callbacks).
+        if (disposed) return;
+        db.runtimeStatePut("wrapup", input.sessionID, wrapUp, directory);
+      }
+    },
+
+    onChatMessage: async (input, output) => {
+      // Chat transcript echoes are non-synthetic noReply parts, so they
+      // arrive here like any user message - but no model turn ever reads
+      // them, and the nudge machinery would embed and scan their text for
+      // nothing (and fire spurious toasts when thresholds cross). Skip
+      // them entirely.
+      if (isChatEchoParts(output.parts)) return;
+
+      // Dormant watcher recovery: a resumed session's first message re-arms
+      // its restarted watchers and hears about dead ones (see
+      // scanDormantWatchers). Injected as synthetic parts - the same path
+      // nudges take, so the model sees them on every call of the turn -
+      // plus a best-effort toast for the human.
+      const rearmNotices = !childToParent.has(input.sessionID) ? await scanDormantWatchers(input.sessionID) : [];
+      if (rearmNotices.length > 0) {
+        for (const text of rearmNotices) {
+          output.parts.push({
+            id: `prt_thatch_watch_${Math.random().toString(36).slice(2)}`,
+            sessionID: input.sessionID,
+            messageID: input.messageID ?? output.message.id,
+            type: "text",
+            text,
+            synthetic: true,
+          });
+        }
+        try {
+          await caps.showToast({ message: rearmNotices[0].split("\n")[0].replace("[thatch] ", "⏰ "), variant: "info", duration: 5000 });
+        } catch {
+          // TUI may not be connected. Best-effort.
+        }
+      }
+
+      // 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 caps.showToast({ 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),
+        // suppress nudges - tools are blocked during summary generation and a
+        // nudge would cause a blocked-tool error. If it is NOT a compaction
+        // message, compaction has already failed (autocontinue never fired)
+        // and the user is sending a new message. Clear the stale flag and
+        // proceed normally - tools are available again.
+        const isCompactionMsg = (output.parts as any[]).some((p) => p.type === "compaction");
+        if (isCompactionMsg) return;
+        compacting.delete(input.sessionID);
+      }
+
+      // Version warning: check if the on-disk package.json version differs
+      // from the running version (user upgraded but didn't restart opencode),
+      // or if the npm poller found a newer version. Best-effort: any failure
+      // silently skips. Injected as a synthetic part so the LLM sees it and
+      // can tell the user to restart.
+      try {
+        const onDisk = readOnDiskVersion();
+        const checker = getVersionChecker();
+        const npmUpdate = checker?.getUpdateWarning() ?? null;
+        const skewWarning = onDisk && compareSemver(runningVersion, onDisk) < 0
+          ? skewWarningText(onDisk, runningVersion)
+          : null;
+        const warning = skewWarning ?? npmUpdate;
+        if (warning) {
+          output.parts.push({
+            id: `prt_thatch_ver_${Math.random().toString(36).slice(2)}`,
+            sessionID: input.sessionID,
+            messageID: input.messageID ?? output.message.id,
+            type: "text",
+            text: versionWarningNudge(warning),
+            synthetic: true,
+          });
+          try {
+            const short = skewWarning
+              ? `⚠️ thatch upgraded to v${onDisk} (running v${runningVersion})`
+              : `⚠️ thatch v${checker?.getLatestVersion()} is available`;
+            await caps.showToast({
+              message: short,
+              variant: "warning",
+              duration: 5000,
+            });
+          } catch {
+            // TUI may not be connected. Best-effort.
+          }
+        }
+      } catch {
+        // Best-effort. Version check failure must not block nudges.
+      }
+
+      // Extraction nudge (fallback path). Skipped when the extracting set
+      // is active - that means a direct-extraction child session is running
+      // and the plugin is handling extraction via the SDK. The nudge fires
+      // here only when direct extraction was never triggered or threw.
+      // Accepted entries whose completion signal never came (crashed
+      // extractor, or a v2 dispatch whose ack never named the parent)
+      // requeue here so they are honestly re-extracted instead of lingering
+      // as silent loss.
+      extraction.requeueStaleAccepted();
+      // Task-dispatched sub-agent sessions may have restricted tool lists
+      // that exclude the thatch tools, and even where the tools exist the
+      // child is driven by its dispatch prompt, so nudges only burn "No
+      // tool named ..." error rounds or add noise there. Extraction
+      // children are excluded: they run with full tools and are driven by
+      // extractionDirectPrompt.
+      if (childToParent.has(input.sessionID) && !extractionChildren.has(input.sessionID)) return;
+      if (!extracting.has(input.sessionID) && extraction.pending(input.sessionID)) {
+        const batch = extraction.peek(input.sessionID);
+        const missed = missedNudges.get(input.sessionID) ?? 0;
+        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", input.sessionID);
+        missedNudges.set(input.sessionID, missed + 1);
+
+        output.parts.push({
+          id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+          sessionID: input.sessionID,
+          messageID: input.messageID ?? output.message.id,
+          type: "text",
+          text,
+          synthetic: true,
+        });
+        return;
+      }
+
+      // No extraction pending - try the prompt-aware recall nudge. Extract
+      // the user's prompt text from the message parts, embed it with the
+      // warm in-process model, and search for matches. Best-effort: any
+      // failure (no text, model not loaded, empty store) silently skips.
+      try {
+        const promptText = (output.parts as any[])
+          .filter((p) => p.type === "text" && !p.synthetic)
+          .map((p) => p.text)
+          .join(" ");
+        if (promptText.length < MIN_PROMPT_LEN) return;
+
+        const embedding = await model.queryEmbed(promptText);
+
+        // Recall nudge: separate try/catch so a memory-search failure
+        // does not block the prediction fire (they share only the embedding).
+        try {
+          const results = db.search([repo, "global"], embedding, { limit: 5 });
+          const matches: NudgeMatch[] = results
+            .filter((r) => r._score >= RECALL_THRESHOLD)
+            .map((r) => ({ label: r.label, score: Math.round(r._score * 1000) / 1000 }));
+
+          if (matches.length > 0) {
+            output.parts.push({
+              id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+              sessionID: input.sessionID,
+              messageID: input.messageID ?? output.message.id,
+              type: "text",
+              text: recallNudge(matches),
+              synthetic: true,
+            });
+            try {
+              await caps.showToast({
+                message: `💭 recalled ${matches.length} memor${matches.length === 1 ? "y" : "ies"}`,
+                variant: "info",
+                duration: 3000,
+              });
+            } catch {
+              // TUI may not be connected. Best-effort.
+            }
+          }
+        } catch (err) {
+          console.error(`[thatch] recall nudge failed: ${err}`);
+        }
+
+        // Prediction fire: independent of recall; a failure here does
+        // not affect the recall nudge that may have already been pushed.
+        try {
+          const predItems = db.scorePredictionNudge([repo, "global"], embedding, PREDICTION_THRESHOLD);
+          if (predItems.length > 0) {
+            output.parts.push({
+              id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+              sessionID: input.sessionID,
+              messageID: input.messageID ?? output.message.id,
+              type: "text",
+              text: predictionNudge(predItems),
+              synthetic: true,
+            });
+            try {
+              await caps.showToast({
+                message: `💭 ${predItems.length} prediction${predItems.length === 1 ? "" : "s"} surfaced`,
+                variant: "info",
+                duration: 3000,
+              });
+            } catch {
+              // TUI may not be connected. Best-effort.
+            }
+          }
+        } catch (err) {
+          console.error(`[thatch] prediction nudge failed: ${err}`);
+        }
+
+        // Behavior fire: independent of recall and prediction. Same
+        // embedding, one more cosine scan against behavior_matchers.
+        try {
+          const behaviorItems = db.scoreBehaviorNudge([repo, "global"], embedding, BEHAVIOR_THRESHOLD);
+          if (behaviorItems.length > 0) {
+            output.parts.push({
+              id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
+              sessionID: input.sessionID,
+              messageID: input.messageID ?? output.message.id,
+              type: "text",
+              text: behaviorNudge(behaviorItems),
+              synthetic: true,
+            });
+            try {
+              await caps.showToast({
+                message: `💭 ${behaviorItems.length} behavior${behaviorItems.length === 1 ? "" : "s"} surfaced`,
+                variant: "info",
+                duration: 3000,
+              });
+            } catch {
+              // TUI may not be connected. Best-effort.
+            }
+          }
+        } catch (err) {
+          console.error(`[thatch] behavior nudge failed: ${err}`);
+        }
+      } catch (err) {
+        console.error(`[thatch] nudge hook failed: ${err}`);
+      }
+    },
+
+    // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is
+    //    best-effort: a failure there must not cost the reminder itself.
+    //
+    // Also tracks parent-child session relationships for cross-session buffer
+    // drain. session.created with a parentID records the mapping AND
+    // snapshots the parent's current buffer so the child's later
+    // memory_remember drains only those snapshot entries, not the parent's
+    // entire buffer (which may have grown from interleaved turns).
+    //
+    // Child lifecycle events: idle means the extractor finished; error or
+    // deletion before completion means the facts were never extracted, so
+    // entries go back to pending. Only extraction children (created by
+    // triggerExtraction, tracked in extractionChildren) get the full cleanup
+    // (buffer drain, session deletion, toast). Task-dispatched sub-agents
+    // get the old behavior (completeAccepted + missedNudges.reset) so their
+    // sessions are not deleted out from under the task tool.
+    onEvent: async (event) => {
+      // Pause alerts: the LLM blocked on a human decision. Both lines
+      // publish these on the bus; v2's adapter translates them into the
+      // same property names (requestID on all reply events).
+      if (event.type === "question.asked") {
+        await alerts.questionAsked(event.properties.sessionID, event.properties.id);
+        return;
+      }
+      if (event.type === "question.replied" || event.type === "question.rejected") {
+        alerts.questionResolved(event.properties.sessionID, replyRequestID(event.properties));
+        return;
+      }
+      if (event.type === "permission.asked") {
+        await alerts.permissionAsked(event.properties.sessionID, event.properties.id);
+        return;
+      }
+      if (event.type === "permission.replied") {
+        alerts.permissionResolved(event.properties.sessionID, replyRequestID(event.properties));
+        return;
+      }
+      if (event.type === "session.created") {
+        const info = event.properties.info;
+        if (info.parentID) {
+          childToParent.set(info.id, info.parentID);
+          childKinds.set(info.id, extractionChildren.has(info.id) ? "extraction" : "task");
+          parentSnapshots.set(info.id, [...extraction.peek(info.parentID)]);
+          journalChild(info.id);
+          // Child sessions don't need the session-start reminder - only
+          // top-level sessions do. Returning here prevents extraction
+          // children from receiving the hygiene report and tool overview.
+          return;
+        }
+      }
+      if (event.type === "session.error") {
+        const childID = event.properties.sessionID;
+        // Alert bookkeeping first: the error name decides abort-silence vs
+        // the needs-attention alert when the session then goes idle (on v2
+        // the adapter emits session.error + idle as a pair for terminal
+        // failures and interrupts, so the verdict always follows). Children
+        // are excluded - their failure requeues extraction here and the
+        // parent turn continues; the child session itself never alerts.
+        const errorObj = event.properties.error as { name?: string; type?: string } | undefined;
+        if (!childToParent.has(childID ?? "")) {
+          alerts.sessionError(childID ?? "", errorObj?.name ?? errorObj?.type ?? null);
+        }
+        const parentID = childID ? childToParent.get(childID) : undefined;
+        if (parentID && childID) {
+          // Requeue what THIS child actually held: its claimed delivery if
+          // it fetched. ERROR is a terminal death signal, so a claim-less
+          // child (died before fetching - boot failures land here) falls
+          // back to whole-set requeue for immediate recovery, regardless
+          // of kind: the worst case is a benign duplicate extraction, never
+          // silent loss.
+          if (!extraction.requeueClaimed(childID)) {
+            extraction.requeueAccepted(parentID);
+          }
+          extracting.delete(parentID);
+          childKinds.delete(childID);
+          childToParent.delete(childID);
+          parentSnapshots.delete(childID);
+          childMetrics.delete(childID);
+          extractionChildren.delete(childID);
+          journalChild(childID);
+        }
+        return;
+      }
+      if (event.type === "session.status") {
+        const sessionID = event.properties.sessionID;
+        const statusType = event.properties.status?.type;
+        // Record the latest status so the watcher registry can gate
+        // proactive prompt delivery on idle sessions.
+        if (sessionID && statusType) sessionStatus.set(sessionID, statusType);
+        // Busy resets the round; a retry (v1 only) clears a recorded error
+        // but preserves the real-work flag - the tool calls before the
+        // retry happened.
+        if (sessionID && statusType === "busy") alerts.sessionBusy(sessionID);
+        else if (sessionID && statusType === "retry") alerts.sessionRetry(sessionID);
+        if (statusType !== "idle") return;
+        const parentID = sessionID ? childToParent.get(sessionID) : undefined;
+        if (parentID && sessionID) {
+          // A child session went idle. Two cases:
+          // - Extraction child (created by triggerExtraction, tracked in
+          //   extractionChildren): drain the parent's snapshot, fire a toast
+          //   with metrics, delete the child session, clean up all maps.
+          // - Task-dispatched sub-agent (code review specialist, nudge-path
+          //   fact-extractor, any model-dispatched task): complete the
+          //   parent's accepted entries and reset missedNudges. Do NOT drain
+          //   the buffer or delete the session - the task tool that
+          //   dispatched the sub-agent needs to read its output.
+          await finishExtractionChild(sessionID, parentID);
+          return;
+        }
+        // Turn-end alert: fires only when the round did real work (the
+        // classifier skips nudge/completion-driven bookkeeping rounds).
+        // Runs before the wrap-up branches so a greenlit compact or exit
+        // still ends with its completion alert.
+        if (sessionID) await alerts.sessionIdle(sessionID);
+        // Wrap-up command resolution: the session went idle right after
+        // /thatch/compact or /thatch/exit. The final assistant message's
+        // trailing token is the greenlight - the command instructs the model
+        // to end with it only after flushing persistence and confirming no
+        // loose ends. Token absence means the model listed blockers, so the
+        // action never fires; a toast points the user at the blockers above.
+        const wrapUp = sessionID ? pendingWrapUp.get(sessionID) : undefined;
+        if (wrapUp) {
+          pendingWrapUp.delete(sessionID);
+          db.runtimeStateDelete("wrapup", sessionID);
+          let ready = false;
+          try {
+            const data = await caps.sessionMessages(sessionID);
+            const last = [...(data ?? [])].reverse().find((m) => m.info.role === "assistant");
+            const text = (last?.parts ?? [])
+              .filter((p) => p.type === "text")
+              .map((p) => p.text ?? "")
+              .join("\n")
+              .trimEnd();
+            ready = text.endsWith(wrapUp.token);
+          } catch (err) {
+            console.error(`[thatch] wrap-up message fetch failed: ${err}`);
+          }
+          if (ready) {
+            // An exit-greenlit session is leaving the process: leave the
+            // chat directory too, so other sessions stop addressing mail to
+            // a roster entry whose host is about to vanish. The unregister
+            // tombstone also stops any straggler auto-register from
+            // resurrecting the row during shutdown. Compact keeps the
+            // session alive, so only the exit path does this.
+            if (wrapUp.kind === "exit") {
+              try {
+                db.unregisterChatSession(sessionID);
+              } catch (err) {
+                console.error(`[thatch] chat unregister on exit failed: ${err}`);
+              }
+            }
+            try {
+              if (wrapUp.kind === "compact") {
+                await caps.compactSession(sessionID);
+              } else {
+                await caps.exitHost();
+              }
+            } catch (err) {
+              console.error(`[thatch] wrap-up action failed: ${err}`);
+            }
+            // Skip extraction and pending deliveries: compaction is starting
+            // (the checklist drained the buffer) or the process is exiting.
+            return;
+          }
+          try {
+            await caps.showToast({
+              message:
+                wrapUp.kind === "compact"
+                  ? "⏸ Not compacting - resolve the items listed above, then run /thatch/compact again"
+                  : "⏸ Not exiting - resolve the items listed above, then run /thatch/exit again",
+              variant: "warning",
+              duration: 8000,
+            });
+          } catch {
+            // TUI may not be connected (e.g. headless mode).
+          }
+          // Blocked: fall through so extraction and pending deliveries still
+          // run - the model may have buffered tool interactions to flush.
+        }
+        // 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
+        // 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. TOP-LEVEL ONLY: child sessions (extraction sub-agents,
+        // task sub-agents) are machinery, not chat participants - without
+        // this check every fact-extractor run registered a roster row
+        // (the "thatch-extraction" corpse flood, September 2026). The
+        // prompt-register path above has the same check.
+        if (
+          chatOn &&
+          chatAutoRegister(loadConfig(dbPath).config) &&
+          sessionID &&
+          !childToParent.has(sessionID) &&
+          !db.hasChatLeaveTombstone(sessionID)
+        ) {
+          void (async () => {
+            try {
+              const data = await caps.sessionGet(sessionID);
+              const title = data?.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 caps.showToast({ 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}`);
+            }
+          })();
+        }
+        // Parent went idle - trigger direct extraction if there are pending
+        // tool interactions and no extraction is already running. Falls
+        // back to the nudge path on the next chat.message if this throws.
+        if (
+          sessionID &&
+          !compacting.has(sessionID) &&
+          !extracting.has(sessionID) &&
+          extraction.pending(sessionID)
+        ) {
+          try {
+            await triggerExtraction(sessionID);
+          } catch (err) {
+            console.error(`[thatch] direct extraction trigger failed: ${err}`);
+            debug("extraction", `direct extraction trigger failed for ${sessionID}: ${err}`);
+            extracting.delete(sessionID);
+          }
+        }
+        // The session just became idle, so watcher events queued while it
+        // was busy can be delivered now - the poll interval may otherwise
+        // hold them for up to a full cycle. Best-effort; failures stay
+        // pending and retry on the next poll.
+        try {
+          await watchers.deliverPending();
+        } catch (err) {
+          console.error(`[thatch] watcher delivery on idle failed: ${err}`);
+        }
+        // Same for chat messages: mail that arrived mid-turn lands now
+        // instead of waiting for the next poll cycle.
+        try {
+          await chatPoller.deliverPending();
+        } catch (err) {
+          console.error(`[thatch] chat delivery on idle failed: ${err}`);
+        }
+        return;
+      }
+      if (event.type === "session.deleted") {
+        const id = event.properties.info.id;
+        // Drop the session's alert state first - it has no reason to outlive
+        // the session.
+        alerts.sessionDeleted(id);
+        // Shrink the chat poller's hosted set FIRST: the rest of this
+        // branch runs extraction calls that could throw on a transient DB
+        // error, and a leaked status key would keep heartbeat-ing a dead
+        // session as permanently fresh.
+        sessionStatus.delete(id);
+        // Tombstone the auto-registerer: an idle IIFE already in flight
+        // (title fetch pending) would otherwise re-insert a directory row
+        // for a session the user just deleted - a week-long roster zombie
+        // whose host is gone. The unregister below tombstones (see
+        // ChatStore.unregister), and the tombstone is cleared only by an
+        // explicit chat_register rejoin, so a genuinely new session is
+        // unaffected.
+        // A child deleted before completing never processed its payload -
+        // unless it was a task-kind child: task sub-agents finish and get
+        // deleted ROUTINELY, and a finished task child's later deletion
+        // must not requeue the parent's extraction state (it would yank an
+        // in-flight extractor's accepted set back to pending for duplicate
+        // extraction). Requeue what the child actually held: its claim, or
+        // for a claim-less extraction child the whole accepted set.
+        const parentID = childToParent.get(id);
+        const childKind = childKinds.get(id) ?? "extraction";
+        if (parentID) {
+          if (!extraction.requeueClaimed(id) && childKind === "extraction") {
+            extraction.requeueAccepted(parentID);
+          }
+          if (childKind === "extraction") extracting.delete(parentID);
+        }
+        extraction.dropClaim(id);
+        childKinds.delete(id);
+        childToParent.delete(id);
+        // A deleted session's grace rehost ends immediately - the user
+        // closed it deliberately; the roster must not keep it fresh. The
+        // hosted-row journal is pruned too: the union never shrinks on its
+        // own, and a deleted session must not re-host into the grace on
+        // the next reload.
+        rehostGrace.delete(id);
+        const hostedRow = db
+          .runtimeStateAll()
+          .find((r) => r.kind === "hosted" && r.sessionID === directory);
+        if (hostedRow && Array.isArray(hostedRow.value)) {
+          db.runtimeStatePut(
+            "hosted",
+            directory,
+            (hostedRow.value as string[]).filter((sid) => sid !== id),
+            directory,
+          );
+        }
+        parentSnapshots.delete(id);
+        childMetrics.delete(id);
+        extractionChildren.delete(id);
+        journalChild(id);
+        pendingWrapUp.delete(id);
+        db.runtimeStateDelete("wrapup", id);
+        // A deleted parent takes its accepted entries with it, and its
+        // watchers die with it - the session that would receive their
+        // notifications no longer exists.
+        extraction.completeAccepted(id);
+        extraction.dropClaim(id);
+        extracting.delete(id);
+        watchers.cancelSession(id);
+        // Leaving the chat directory is the graceful-exit fast path; a
+        // crashed process never fires session.deleted, so the heartbeat
+        // staleness in chat_list is the covering signal for that case.
+        try {
+          db.unregisterChatSession(id);
+        } catch (err) {
+          console.error(`[thatch] chat unregister on delete failed: ${err}`);
+        }
+        return;
+      }
+
+      // session.compacted fires on successful compaction. Redundant with
+      // experimental.compaction.autocontinue, but belt-and-suspenders: if
+      // autocontinue didn't fire or wasn't installed, the event still clears
+      // the compacting flag so nudges resume.
+      if (event.type === "session.compacted") {
+        compacting.delete(event.properties.sessionID);
+        return;
+      }
+
+      if (event.type !== "session.created") return;
+      const id = event.properties.info.id;
+
+      // noReply hosts only: a host without noReply delivery would turn the
+      // reminder into a real model turn replying to itself. The system
+      // prompt (onSystemTransform) still carries the essentials everywhere.
+      // The gate precedes the hygiene scan so v2 sessions (and any other
+      // noReply-less host) do not pay a DB + repo scan for a skipped report.
+      if (!caps.noReplyDelivery) return;
+
+      let hygiene: string | null = null;
+      try {
+        hygiene = await hygieneReport(db, repo, worktree, repoCache);
+      } catch (err) {
+        console.error(`[thatch] hygiene report failed: ${err}`);
+      }
+
+      try {
+        await caps.promptSession(
+          id,
+          {
+            noReply: true,
+            parts: [{ type: "text", text: sessionStartReminder(repo, hygiene), synthetic: true }],
+          },
+          "sync",
+        );
+      } catch (err) {
+        console.error(`[thatch] session-start reminder failed: ${err}`);
+      }
+    },
+
+    dispose: async () => {
+      disposed = true;
+      stopVersionChecker();
+      watchers.dispose();
+      chatPoller.dispose();
+      try {
+        await releaseModel();
+      } finally {
+        // In finally so a releaseModel rejection cannot leak the connection.
+        // Note: the runtime_state journal is deliberately NOT cleared here.
+        // Disposal happens before every v2 plugin reload, and the reloaded
+        // setup() rehydrates from it; stale rows from dead processes are
+        // pruned by the setup-time partition instead.
+        db.close();
+      }
+    },
+  };
+}