@jeffober/thatch 0.2.3 → 0.2.5

package/src/watchers.ts

@@ -47,7 +47,18 @@ export type BranchWatcherEventType = "branch_commit" | "branch_ci" | "branch_wor
 /** Event type for source "command": the watched shell command exited 0. */
 export type CommandWatcherEventType = "command_success";
 
-export type WatcherEventType = PrWatcherEventType | BranchWatcherEventType | CommandWatcherEventType;
+/**
+ * Lifecycle event the registry itself emits, not tied to a source: a watch
+ * passed its TTL and was dropped. Delivered to the owning session instead of
+ * vanishing silently.
+ */
+export type LifecycleWatcherEventType = "watch_expired";
+
+export type WatcherEventType =
+  | PrWatcherEventType
+  | BranchWatcherEventType
+  | CommandWatcherEventType
+  | LifecycleWatcherEventType;
 
 export const PR_EVENT_TYPES: PrWatcherEventType[] = [
   "pr_comment",
@@ -68,8 +79,13 @@ export const BRANCH_EVENT_TYPES: BranchWatcherEventType[] = [
 
 export const COMMAND_EVENT_TYPES: CommandWatcherEventType[] = ["command_success"];
 
-/** Every event type across all sources - for diagnostics and tests. */
-export const WATCHER_EVENT_TYPES: WatcherEventType[] = [...PR_EVENT_TYPES, ...BRANCH_EVENT_TYPES, ...COMMAND_EVENT_TYPES];
+/** Every event type across all sources plus registry lifecycle events - for diagnostics and tests. */
+export const WATCHER_EVENT_TYPES: WatcherEventType[] = [
+  ...PR_EVENT_TYPES,
+  ...BRANCH_EVENT_TYPES,
+  ...COMMAND_EVENT_TYPES,
+  "watch_expired",
+];
 
 /**
  * A single detected change, ready for delivery. Pointer data plus machine
@@ -258,6 +274,13 @@ export function withCwdFallback(
 }
 
 export interface WatcherRegistryOptions {
+  /**
+   * The constructing instance's location directory. Scopes the per-process
+   * live handoff: a new registry stops only a same-directory predecessor,
+   * so a second per-location instance (a worktree subordinate's boot) never
+   * stops the coordinator's poller. Omitted by tests and non-plugin hosts.
+   */
+  directory?: string;
   /** Delivers a batch of events for a session. Injected so tests never spawn. */
   deliver: (sessionID: string, events: WatcherEvent[]) => Promise<void>;
   /**
@@ -280,6 +303,48 @@ export interface WatcherRegistryOptions {
   maxPerSession?: number;
   /** Persistence hook: called after membership changes with the session's watcher list. */
   journal?: (sessionID: string, watchers: Watcher[]) => void;
+  /**
+   * Persistence hook for the PENDING event queue (the reload-loss fix):
+   * called whenever a session's queue changes. undefined clears the
+   * session's row. Without this, a plugin reload between detection and
+   * delivery silently eats the notification (observed 2026-10-07:
+   * watch_qn449jio's CI notice lost in the 09b805f reload window).
+   */
+  journalPending?: (sessionID: string, pending: { event: WatcherEvent; queuedAt: number }[] | undefined) => void;
+  /**
+   * Death callback: the registry declares a session dead (pending queue
+   * aged out with consecutive thrown deliveries, 404-class re-check
+   * passed) and has already cancelled its watchers and dropped its queue.
+   * The runtime removes the chat hosting state and tells live same-project
+   * sessions. A pending `watcher_death` row is the runtime's durable
+   * fallback for sessions that were busy at death time.
+   */
+  onSessionDeath?: (sessionID: string, death: { chatName: string | null; targets: string[] }) => void;
+  /** Eligibility for death detection: only sessions this process hosts are eligible (sibling v1 processes and MCP sessions never qualify). */
+  isHostedSession?: (sessionID: string) => boolean;
+  /** Pending-age threshold for death detection in minutes; defaults to THATCH_WATCH_DEATH_MINUTES or 120. */
+  deathMinutes?: number;
+  /** Clock for the pending-age test; injectable for tests. */
+  now?: () => number;
+}
+
+/**
+ * Minimum consecutive THROWN deliveries before the death scan may fire -
+ * a lone 404 (a transient blip mid-outage) must not kill watches.
+ */
+const MIN_DEATH_THROWS = 5;
+
+/**
+ * Whether a delivery error is the "session's route is gone" class - the
+ * closed-tab signature (verified live 2026-10-07: prompt_async to a closed
+ * v2 tab returns 404 while the session row persists). 5xx loops are a
+ * wedged server - an outage must never mass-cancel watches.
+ */
+export function isNotFoundClass(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { statusCode?: number; status?: number; message?: string };
+  if (e.statusCode === 404 || e.status === 404) return true;
+  return /404|not found/i.test(String(e.message ?? ""));
 }
 
 // ---------------------------------------------------------------------------
@@ -868,9 +933,14 @@ export class WatcherRegistry {
   #watchers = new Map<string, Watcher>();
   /** sessionID -> events detected but not yet delivered. */
   #pending = new Map<string, WatcherEvent[]>();
+  /** sessionID -> queuedAt of the oldest still-pending event (death-test clock). */
+  #firstPendingAt = new Map<string, number>();
+  /** sessionID -> consecutive THROWN delivery attempts; skips and successes reset. */
+  #consecutiveDeliveryThrows = new Map<string, number>();
   #timer: ReturnType<typeof setInterval> | null = null;
   #delivering = false;
   #polling = false;
+  #now: () => number;
   /**
    * Persistence hook (optional): called after every membership change with
    * the session's current watcher list, so the runtime can journal the
@@ -878,38 +948,59 @@ export class WatcherRegistry {
    * (tests, MCP) keeps the registry in-memory only.
    */
   #journal?: (sessionID: string, watchers: Watcher[]) => void;
+  /** Persistence hook for the pending queue - see WatcherRegistryOptions. */
+  #journalPending?: WatcherRegistryOptions["journalPending"];
+  /** Death callback - see WatcherRegistryOptions. */
+  #onSessionDeath?: WatcherRegistryOptions["onSessionDeath"];
+  /** Hosting eligibility - see WatcherRegistryOptions. */
+  #isHostedSession?: WatcherRegistryOptions["isHostedSession"];
   readonly #opts: WatcherRegistryOptions & {
     pollIntervalMs: number;
     ttlMinutes: number;
     maxPerSession: number;
     commandRunner: CommandRunner;
     commandTimeoutMs: number;
+    deathThresholdMs: number;
   };
   /**
-   * The most recently constructed instance in this process. opencode v2
-   * re-runs plugin setup() when the session's directory changes
+   * The most recently constructed instance per location directory. opencode
+   * v2 re-runs plugin setup() when the session's directory changes
    * (session_move between directories of the same repo) or on plugin-file
    * changes; each setup() built a fresh registry while the OLD instance's
    * poller timer kept running - the watch tools then queried an empty
    * registry ("No active watchers" / "No watcher in this session") while
    * delivery kept flowing from the orphaned poller. The handoff stops the
-   * predecessor's poller at construction so at most one registry polls per
-   * process; the watch tools' journal reconcile covers the state transfer.
+   * predecessor at construction so at most one registry polls PER LOCATION:
+   * a reload (same directory) hands off as before, while a second
+   * per-location instance (a worktree subordinate's boot) must NOT stop the
+   * coordinator's poller - one serve process hosts one instance per
+   * location, and each polls only its own directory's watchers. The watch
+   * tools' journal reconcile covers the state transfer.
    */
-  static #live: WatcherRegistry | undefined;
+  static #live = new Map<string, WatcherRegistry>();
+  /** This registry's live-map key: the instance directory, or "" when the
+   *  constructing test/host passes no directory. */
+  readonly #liveKey: string;
 
   constructor(options: WatcherRegistryOptions) {
+    const envDeathMinutes = Number(process.env.THATCH_WATCH_DEATH_MINUTES ?? 0) || 120;
     this.#opts = {
       pollIntervalMs: Number(process.env.THATCH_WATCH_POLL_SECONDS ?? 0) * 1000 || 60_000,
       ttlMinutes: Number(process.env.THATCH_WATCH_TTL_MINUTES ?? 0) || 480,
       maxPerSession: Number(process.env.THATCH_WATCH_MAX_PER_SESSION ?? 0) || 5,
       commandRunner: runWatchedCommand,
       commandTimeoutMs: defaultCommandTimeoutMs(),
+      deathThresholdMs: (options.deathMinutes ?? envDeathMinutes) * 60_000,
       ...options,
     };
+    this.#now = options.now ?? Date.now;
     this.#journal = options.journal;
-    WatcherRegistry.#live?.stop();
-    WatcherRegistry.#live = this;
+    this.#journalPending = options.journalPending;
+    this.#onSessionDeath = options.onSessionDeath;
+    this.#isHostedSession = options.isHostedSession;
+    this.#liveKey = options.directory ?? "";
+    WatcherRegistry.#live.get(this.#liveKey)?.stop();
+    WatcherRegistry.#live.set(this.#liveKey, this);
   }
 
   // -- Lifecycle -----------------------------------------------------------
@@ -947,8 +1038,13 @@ export class WatcherRegistry {
   /** Stops polling and drops all state. Called from the plugin's dispose. */
   dispose(): void {
     this.stop();
+    // Only clear the live slot if THIS instance still owns it - a reload's
+    // replacement registered under the same key after this one.
+    if (WatcherRegistry.#live.get(this.#liveKey) === this) WatcherRegistry.#live.delete(this.#liveKey);
     this.#watchers.clear();
     this.#pending.clear();
+    this.#firstPendingAt.clear();
+    this.#consecutiveDeliveryThrows.clear();
   }
 
   // -- CRUD ----------------------------------------------------------------
@@ -1181,6 +1277,9 @@ export class WatcherRegistry {
       if (w.sessionID === sessionID) this.#watchers.delete(id);
     }
     this.#pending.delete(sessionID);
+    this.#firstPendingAt.delete(sessionID);
+    this.#consecutiveDeliveryThrows.delete(sessionID);
+    this.#journalPending?.(sessionID, undefined);
     this.#emit(sessionID);
   }
 
@@ -1201,15 +1300,31 @@ export class WatcherRegistry {
       for (const [id, watcher] of this.#watchers) {
         if (now > watcher.expiresAt) {
           this.#watchers.delete(id);
+          // Report the expiry instead of dropping the watch silently: a
+          // notification that just stops arriving looks identical to a
+          // broken poller, and a session waiting on a watch that gated
+          // greenlit work must be told the wait ended without the event.
+          const minutes = Math.max(1, Math.round((watcher.expiresAt - watcher.createdAt) / 60_000));
+          const target = watcherTarget(watcher);
+          const queue = this.#pending.get(watcher.sessionID) ?? [];
+          queue.push({
+            type: "watch_expired",
+            target,
+            summary: `watch on ${target} expired after ${minutes} min - no further notifications will arrive from it`,
+            url: this.#watchUrl(watcher),
+          });
+          this.#pending.set(watcher.sessionID, queue);
+          this.#journalPendingNow(watcher.sessionID);
           this.#emit(watcher.sessionID);
           continue;
         }
         try {
-          const events = await this.#pollOne(watcher);
+          const { events, stateChanged } = await this.#pollOne(watcher);
           if (events.length > 0) {
             const queue = this.#pending.get(watcher.sessionID) ?? [];
             queue.push(...events);
             this.#pending.set(watcher.sessionID, queue);
+            this.#journalPendingNow(watcher.sessionID);
             // One-shot watchers end at first detection, not first delivery:
             // the queued events deliver through the normal pending path even
             // if the session is busy. Cancellation at detection time keeps
@@ -1218,8 +1333,15 @@ export class WatcherRegistry {
             if (watcher.once) {
               this.#watchers.delete(id);
               this.#emit(watcher.sessionID);
+              continue;
             }
           }
+          // Journal on state change, not just membership change: the poller
+          // advances watcher.state in memory, and registry rebuilds (v2
+          // reload rehydration, the watch tools' journal reconcile) hydrate
+          // the journaled state back in verbatim. A journal that lags the
+          // poller replays already-delivered events on the next diff.
+          if (stateChanged) this.#emit(watcher.sessionID);
         } catch (err) {
           console.error(`[thatch] watcher ${id} poll failed: ${err}`);
         }
@@ -1230,14 +1352,20 @@ export class WatcherRegistry {
     }
   }
 
-  /** Fetches and diffs one watcher, filtered to its watched event types. */
-  async #pollOne(watcher: Watcher): Promise<WatcherEvent[]> {
+  /**
+   * Fetches and diffs one watcher, filtered to its watched event types. Also
+   * reports whether the fetched snapshot differed from the last-seen state -
+   * the caller journals on change so a rebuild rehydrates a current baseline
+   * instead of replaying old transitions.
+   */
+  async #pollOne(watcher: Watcher): Promise<{ events: WatcherEvent[]; stateChanged: boolean }> {
     if (watcher.source === "pr") {
       const after = await fetchPrState(this.#opts.ghRunner, watcher.repo, watcher.pr);
       const events = diffPrState(watcher.state, after, watcherTarget(watcher), this.#prUrl(watcher))
         .filter((e) => watcher.events.includes(e.type as PrWatcherEventType));
+      const stateChanged = JSON.stringify(watcher.state) !== JSON.stringify(after);
       watcher.state = after;
-      return events;
+      return { events, stateChanged };
     }
     if (watcher.source === "command") {
       const result = await this.#opts.commandRunner(watcher.command, watcher.cwd, watcher.timeoutMs);
@@ -1246,17 +1374,22 @@ export class WatcherRegistry {
       // transition guard: the baseline refusal keeps lastExit non-zero at
       // registration, and the one-shot cancel in poll() removes the watcher
       // the moment this event fires.
+      const stateChanged = !result.timedOut && watcher.state.lastExit !== result.exitCode;
       if (!result.timedOut) watcher.state = { lastExit: result.exitCode };
-      if (result.timedOut || result.exitCode !== 0) return [];
-      return [{
-        type: "command_success",
-        target: watcherTarget(watcher),
-        summary: `command exited 0 (took ${(result.durationMs / 1000).toFixed(1)}s)`,
-        url: "",
-      }];
+      if (result.timedOut || result.exitCode !== 0) return { events: [], stateChanged };
+      return {
+        events: [{
+          type: "command_success",
+          target: watcherTarget(watcher),
+          summary: `command exited 0 (took ${(result.durationMs / 1000).toFixed(1)}s)`,
+          url: "",
+        }],
+        stateChanged,
+      };
     }
     const after = await fetchBranchState(this.#opts.ghRunner, watcher.repo, watcher.branch);
     const all = diffBranchState(watcher.state, after, watcherTarget(watcher), watcher.repo);
+    const stateChanged = JSON.stringify(watcher.state) !== JSON.stringify(after);
     watcher.state = after;
     // The workflow-name filter narrows branch_workflow events only -
     // commits and check runs pass through unfiltered, or a watch filtered
@@ -1265,14 +1398,20 @@ export class WatcherRegistry {
       e.type !== "branch_workflow" ||
       watcher.workflows.length === 0 ||
       watcher.workflows.some((wf) => e.summary.toLowerCase().includes(wf.toLowerCase()));
-    return all
-      .filter((e) => watcher.events.includes(e.type as BranchWatcherEventType) && matchesFilter(e));
+    return {
+      events: all
+        .filter((e) => watcher.events.includes(e.type as BranchWatcherEventType) && matchesFilter(e)),
+      stateChanged,
+    };
   }
 
   /**
    * Delivers pending events for every session that can accept a prompt.
    * Failed deliveries stay pending and retry on the next cycle or the next
-   * idle event.
+   * idle event. A THROWN delivery is death evidence: consecutive throws
+   * with the pending queue aged past the threshold (and a 404-class error)
+   * declare the session dead. A skipped attempt (busy/compacting) is the
+   * OPPOSITE - alive by definition - and resets the throw chain.
    */
   async deliverPending(): Promise<void> {
     if (this.#delivering) return;
@@ -1289,12 +1428,21 @@ export class WatcherRegistry {
         } catch (err) {
           console.error(`[thatch] canDeliver gate failed for ${sessionID}: ${err}`);
         }
-        if (!deliverable) continue;
+        if (!deliverable) {
+          // A skipped attempt is never death evidence - a busy or
+          // compacting session is alive by definition.
+          this.#consecutiveDeliveryThrows.delete(sessionID);
+          continue;
+        }
         try {
           await this.#opts.deliver(sessionID, events);
           this.#pending.delete(sessionID);
+          this.#firstPendingAt.delete(sessionID);
+          this.#consecutiveDeliveryThrows.delete(sessionID);
+          this.#journalPending?.(sessionID, undefined);
         } catch (err) {
           console.error(`[thatch] watcher delivery to ${sessionID} failed: ${err}`);
+          this.#maybeDeclareDeath(sessionID, err);
         }
       }
     } finally {
@@ -1302,12 +1450,101 @@ export class WatcherRegistry {
     }
   }
 
+  /**
+   * Death scan for one failed delivery. Death requires ALL of: the
+   * session's pending queue aged past the threshold, a run of CONSECUTIVE
+   * thrown attempts, a 404-class throw (a wedged server's 5xx loop is not
+   * death - an outage must not mass-cancel watches), and hosting
+   * eligibility (sibling v1 processes and MCP sessions are never declared
+   * dead here). On death the watchers and queue are dropped and the
+   * runtime's death callback carries the notice.
+   */
+  #maybeDeclareDeath(sessionID: string, err: unknown): void {
+    const firstAt = this.#firstPendingAt.get(sessionID);
+    const throws = (this.#consecutiveDeliveryThrows.get(sessionID) ?? 0) + 1;
+    this.#consecutiveDeliveryThrows.set(sessionID, throws);
+    if (!firstAt || this.#now() - firstAt < this.#opts.deathThresholdMs) return;
+    if (throws < MIN_DEATH_THROWS) return;
+    if (this.#isHostedSession && !this.#isHostedSession(sessionID)) return;
+    if (!isNotFoundClass(err)) return;
+    this.sessionDied(sessionID);
+  }
+
+  /**
+   * Declares a session dead: cancels its watchers, drops its pending
+   * queue, and hands the runtime the death summary. Two callers: the
+   * delivery-persistence heuristic (above) and the session-tab
+   * `tab-closed` event (a CONFIRMED close skips the heuristic entirely -
+   * instant path).
+   */
+  sessionDied(sessionID: string, death: { chatName?: string | null } = {}): void {
+    const watchers = this.listForSession(sessionID);
+    const pending = this.#pending.get(sessionID) ?? [];
+    for (const w of watchers) this.#watchers.delete(w.id);
+    this.#pending.delete(sessionID);
+    this.#firstPendingAt.delete(sessionID);
+    this.#consecutiveDeliveryThrows.delete(sessionID);
+    this.#emit(sessionID); // empty list - the runtime's journal callback deletes the row
+    this.#journalPending?.(sessionID, undefined);
+    const targets = [...new Set([...watchers.map(watcherTarget), ...pending.map((e) => e.target)])];
+    this.#onSessionDeath?.(sessionID, { chatName: death.chatName ?? null, targets });
+  }
+
+  /**
+   * Restores persisted pending events (reload rehydration, or a resumed
+   * session's dormant scan rehydrating its own queue). Dedups by event
+   * fingerprint and keeps the OLDEST queuedAt so the death-test clock
+   * stays honest.
+   */
+  hydratePending(sessionID: string, pending: { event: WatcherEvent; queuedAt: number }[]): void {
+    if (!pending || pending.length === 0) return;
+    const queue = this.#pending.get(sessionID) ?? [];
+    const seen = new Set(queue.map((e) => `${e.type}:${e.target}:${e.summary}`));
+    for (const { event, queuedAt } of pending) {
+      if (seen.has(`${event.type}:${event.target}:${event.summary}`)) continue;
+      queue.push(event);
+      const existing = this.#firstPendingAt.get(sessionID);
+      if (existing === undefined || queuedAt < existing) this.#firstPendingAt.set(sessionID, queuedAt);
+    }
+    this.#pending.set(sessionID, queue);
+    // Re-journal the hydrated queue. Hydration consumers delete the durable
+    // row as they hand it over (the rehydrate loop, the dormant scan), and
+    // delivery may not run before the NEXT reload - the queue must be
+    // durable again the moment it is back in memory, or a second reload
+    // loses the events.
+    this.#journalPendingNow(sessionID);
+  }
+
+/** Journals the session's current pending queue, or clears the row when empty. */
+  #journalPendingNow(sessionID: string): void {
+    const queue = this.#pending.get(sessionID);
+    if (!queue || queue.length === 0) {
+      this.#journalPending?.(sessionID, undefined);
+      return;
+    }
+    if (!this.#firstPendingAt.has(sessionID)) this.#firstPendingAt.set(sessionID, this.#now());
+    const queuedAt = this.#firstPendingAt.get(sessionID)!;
+    this.#journalPending?.(sessionID, queue.map((event) => ({ event, queuedAt })));
+  }
+
+  /** Snapshot of the events waiting for a session, oldest first. */
+  pendingEvents(sessionID: string): WatcherEvent[] {
+    return [...(this.#pending.get(sessionID) ?? [])];
+  }
+
   /** Diagnostic: number of events waiting for a session. */
   pendingCount(sessionID: string): number {
-    return (this.#pending.get(sessionID) ?? []).length;
+    return this.pendingEvents(sessionID).length;
   }
 
   #prUrl(watcher: PrWatcher): string {
     return `https://github.com/${watcher.repo}/pull/${watcher.pr}`;
   }
+
+  /** Best pointer for a lifecycle event about a watch: the watched target itself. */
+  #watchUrl(watcher: Watcher): string {
+    if (watcher.source === "pr") return this.#prUrl(watcher);
+    if (watcher.source === "branch") return `https://github.com/${watcher.repo}/actions`;
+    return "";
+  }
 }

package/docs/plans/intuition-drives.md

@@ -1,147 +0,0 @@
-# Intuition Drives
-
-## Synopsis
-
-A pre-response deliberation layer that runs on the first message of a new
-opencode session: perception classifies the prompt, parallel drive sub-agents
-react from their motivational lenses, and a synthesis pass distills them into a
-directive injected into the main agent's context. opencode-only; requires
-parallel sub-agent dispatch via Task.
-
-## Background
-
-Fnord runs as a CLI escript where every user invocation carries significant
-intent because it requires a full command-line invocation. Its coordinator runs
-an "intuition" step before responding: a perception pass classifies the prompt,
-ten parallel "drives" (curiosity, skepticism, optimization, modularity,
-convention, laziness, empathy, standing, pragmatism, stewardship) each react
-from their lens, and a synthesis pass distills them into a directive injected
-into the conscious agent's context.
-
-In opencode's chat TUI, user messages have far less friction. Running the full
-intuition pipeline on every message would burn tokens on "ok" and "yes." This
-feature is gated to the first message of a new session only.
-
-## Session detection
-
-This feature depends on knowing "is this the first message of a new session."
-The opencode plugin hook surface provides this:
-
-- `session.created` fires ONLY when a brand-new session object is constructed
-  (fresh creation or fork). It does NOT fire when a user resumes or continues an
-  existing conversation (`--continue`/`--session` without `--fork` reuses the
-  existing session ID).
-- `chat.message` fires on every incoming user message but carries no turn
-  number or first-message flag in its input or output.
-
-Detection mechanism:
-1. Track `session.created` events for top-level sessions (no `parentID`) in a
-   `Set<string>`.
-2. First `chat.message` for a session ID in that set = first message. Remove
-   from set, trigger the feature.
-3. Continued/resumed conversations never fire `session.created`, so they are
-   never in the set. Second messages also don't trigger (already removed).
-
-Edge cases:
-- `--fork` fires `session.created` (correct: a fork is a new conversation).
-- Plugin not running when the session was created (e.g., `--continue` of a
-  session from a prior run): no `session.created`, no trigger (correct: it is a
-  continued conversation, not new).
-- Child sessions (sub-agents) fire `session.created` with a `parentID` —
-  filtered out by the `parentID` check.
-
-## What it does
-
-On the first message of a new session, before the main agent responds, a
-deliberation layer runs:
-
-1. **Perception** — classify the prompt (interface, codebase, correction,
-   continuation, meta, ambiguous) and produce a short first-person interpretation.
-2. **Drive reactions** — parallel sub-agents, each arguing from a specific
-   motivational lens. Drives are the same as fnord's: curiosity, skepticism,
-   optimization, modularity, convention, laziness, empathy, standing, pragmatism,
-   stewardship.
-3. **Synthesis** — distill the drive reactions into a single directive injected
-   into the main agent's context.
-
-## Why port it
-
-No existing skill does pre-response deliberation. The drives carry real
-personality and map to Jeff's stance (stewardship = "correctness over comfort";
-skepticism = "no reassurance without verification"). The parallel sub-agent
-dispatch is natural for opencode's Task tool.
-
-## Constraints
-
-- **opencode-only.** Requires parallel sub-agent dispatch via Task. Claude Code
-  agents running skills cannot spawn sub-agents.
-- **First-message-only.** Gated by the session-detection mechanism above.
-  Running on every message would burn tokens on trivial follow-ups.
-- **Prompt injection, not a tool.** The synthesis output is injected as a
-  synthetic text part into the first `chat.message`, like the recall nudge. The
-  main agent sees it as context, not as a tool result.
-- **No pre-response hook exists.** The synthesis must complete inside the
-  `chat.message` hook (before the LLM loop runs) or be injected as a system
-  message via `experimental.chat.system.transform`. The hook fires before the
-  message is persisted and before the LLM loop starts, so a synchronous
-  sub-agent dispatch inside `chat.message` would block the turn. The
-  `experimental.chat.system.transform` hook is a better injection point because
-  it runs on every turn and can append to the system prompt — but it does not
-  have access to the user's message text. A hybrid: compute the synthesis in
-  `chat.message` (which has the prompt text), cache it in a per-session map, and
-  inject it in `experimental.chat.system.transform` on the same turn.
-
-## Open questions
-
-1. **Latency.** Ten parallel sub-agent calls add latency to the first turn. Is
-   the value worth it? Options: reduce to 3-4 drives, run drives with a fast
-   model, or make it opt-in.
-2. **Injection point.** The `chat.message` hook fires before the LLM loop but
-   injecting a synthetic part there adds it to the user message, not the system
-   prompt. `experimental.chat.system.transform` can append to the system prompt
-   but fires on every turn and lacks the user message text. The hybrid
-   (compute-in-chat.message, inject-in-system.transform) requires a per-session
-   cache with one-turn TTL.
-3. **Drive selection.** Fnord runs all 10 drives. A smaller set (stewardship,
-   skepticism, pragmatism, empathy) might capture 80% of the value at 40% of the
-   cost.
-
-## Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| opencode-only | Requires parallel sub-agent dispatch via Task |
-| First-message-only | Chat TUI has low message friction; running on every message wastes tokens |
-| Detection via session.created + chat.message | session.created fires only on new sessions; chat.message provides the first-message trigger |
-| Parallel drives via Task sub-agents | Matches fnord's architecture; drives are independent and parallelizable |
-| Injection via system.transform with chat.message cache | chat.message has the prompt text; system.transform can append to the system prompt; hybrid avoids blocking the turn |
-
-## Architecture
-
-```
-session.created (top-level, no parentID)
-  → add sessionID to newSessions Set
-
-chat.message (first message for sessionID in newSessions)
-  → remove from newSessions
-  → perception + parallel drives + synthesis → cache in Map<sessionID, directive>
-
-experimental.chat.system.transform
-  → if directive cached: append directive, then clear cache (one-shot)
-
-session.deleted
-  → delete from directive cache, newSessions set
-```
-
-## Dependencies
-
-### Runtime
-
-- Fast model for perception and drive reactions (parallel sub-agents)
-- Task tool for parallel drive dispatch (opencode sub-agent support)
-
-### Built-in
-
-- Plugin hooks: `event` (session.created, session.deleted),
-  `chat.message`, `experimental.chat.system.transform`
-- In-process `Map` for per-session caching (directive, newSessions set)