@jeffober/thatch 0.2.0 → 0.2.1

package/src/tool-defs.ts

@@ -22,9 +22,9 @@ import {
   type NotificationPrefs,
 } from "./config";
 import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
-import { predictionVerb, chatInboxFrame } from "./prompts";
+import { predictionVerb, formatWhenLine, chatInboxFrame } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
-import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
+import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type Watcher, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
 import { CHAT_STALE_MS, chatLiveness, humanAge, renderChatParticipant, sortChatRoster, splitChatRoster, type ChatHostKind } from "./chat";
 import { detectWorktreeKind } from "./git";
 
@@ -100,12 +100,16 @@ export interface CoreContext {
   db: ThatchDB;
   model: EmbeddingModel;
   defaultStore: string;
-  /** Peeks the extraction buffer for a session and returns the serialized
-   *  JSON payload (same shape as buildExtractionPayload). Returns null when
-   *  no interactions are queued. Used by the get_extraction_payload tool so
-   *  the sub-agent fetches the payload as a tool response instead of
-   *  receiving it inline in the nudge text. */
-  extractionPayloadProvider?: (sessionID: string) => string | null;
+  /** Fetches a session's extraction payload for a fetcher. Returns the
+   *  serialized JSON payload (same shape as buildExtractionPayload), or
+   *  null when no interactions are queued. With a fetcherID, the fetch is
+   *  a CLAIM: the fetched entries stay accepted and that fetcher's
+   *  completion signal consumes only this delivery (sibling sub-agents
+   *  going idle cannot drop it). Without a fetcherID, the fetch is a pure
+   *  peek. Used by the get_extraction_payload tool so the sub-agent
+   *  fetches the payload as a tool response instead of receiving it
+   *  inline in the nudge text. */
+  extractionPayloadProvider?: (sessionID: string, fetcherID?: string) => string | null;
   /** Drains a session's extraction queue. On the MCP path this deletes the
    *  file-backed queue and resets the missed-nudge counter. On the opencode
    *  path this is unused (the tool.execute.after hook handles drain via
@@ -165,6 +169,73 @@ export interface ToolDef {
 // Formatting helpers - shared by all tools that render entries
 // ---------------------------------------------------------------------------
 
+/**
+ * Human-readable age of a memory, rendered at output time so the reading
+ * model can weigh staleness semantically (an ISO timestamp does not get
+ * weighed; "47 days ago" does). Keyed on updated_at - the last CONTENT
+ * change - and deliberately NOT on last_recalled_at: hygiene's staleness
+ * sweep treats a recall as refreshing the clock, but for content accuracy
+ * the opposite holds. A memory recalled yesterday but written eight months
+ * ago is exactly the case where the world may have moved on since the
+ * claim was recorded. Freshness-of-use is not freshness-of-claim.
+ *
+ * Bucket boundaries are a formatting choice, independent of hygiene's
+ * 90-day staleness window (db.ts STALE_DAYS) - the two 90s are a
+ * coincidence, do not couple them. Compact sibling: humanAge() in
+ * chat.ts renders roster-style "5m ago" for chat surfaces; keep the two
+ * apart when changing either.
+ */
+export function formatAge(iso: string, now: Date = new Date()): string {
+  const then = new Date(iso).getTime();
+  if (!Number.isFinite(then)) return "unknown age";
+  const seconds = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 90) return `${days} day${days === 1 ? "" : "s"} ago`;
+  if (days < 365) return `${Math.floor(days / 30)} month${Math.floor(days / 30) === 1 ? "" : "s"} ago`;
+  const years = Math.floor(days / 365);
+  return `${years} year${years === 1 ? "" : "s"} ago`;
+}
+
+/**
+ * The age sentence inserted between the meta line and a memory's content,
+ * so the model weighs staleness BEFORE reading the claim it qualifies.
+ */
+function ageLine(iso: string): string {
+  return `This memory was last updated ${formatAge(iso)}.`;
+}
+
+/**
+ * Caveat attached to memory_recall and memory_show tool output at render
+ * time - the persisted rows are untouched. The sibling of chatInboxFrame's
+ * untrusted-content framing in prompts.ts: a content-classification line
+ * that rides with the claims it qualifies, at the moment they enter the
+ * model's context, instead of a general rule it has to recall from the
+ * system prompt (or a nudge it learns to tune out). memory_list is
+ * excluded: a labels-only listing carries no artifact claims to qualify.
+ *
+ * Tool names use the BARE form (memory_remember, memory_forget) on
+ * purpose: tool-defs.ts is host-shared and has no host context. On MCP
+ * hosts the bare-name convention is established by the instructions in
+ * prompts.ts ("Bare names used below for readability"); on opencode the
+ * system prompt uses thatch_ spellings, but the model sees its own tool
+ * list and maps the bare name without a stated convention. If either
+ * convention changes, update this string with it.
+ */
+const memoryCaveat =
+  `[thatch] Memories are a point-in-time record - a guide to where to look, ` +
+  `not a source of truth. Verify artifact claims (code, docs, tickets, git) ` +
+  `against current sources before relying on them; if a memory has drifted, ` +
+  `correct it with memory_remember (overwrite: true) or memory_forget.`;
+
+function withMemoryCaveat(body: string): string {
+  return `${memoryCaveat}\n\n${body}`;
+}
+
 function formatEntry(
   entry: Awaited<ReturnType<ThatchDB["showEntry"]>>,
 ): string | null {
@@ -175,8 +246,8 @@ function formatEntry(
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
-  meta += ` created:${entry.created_at} updated:${entry.updated_at}`;
-  parts.push(meta, "", entry.content);
+  meta += ` created:${entry.created_at}`;
+  parts.push(meta, "", ageLine(entry.updated_at), entry.content);
   return parts.join("\n");
 }
 
@@ -185,9 +256,8 @@ function formatRecallResult(entry: MemoryRow & { _score: number }): string {
   if (entry.branch) meta += ` branch:${entry.branch}`;
   if (entry.confidence) meta += ` confidence:${entry.confidence}`;
   if (entry.archived) meta += " archived:true";
-  meta += ` updated:${entry.updated_at}`;
   const score = entry._score.toFixed(3);
-  return `[${meta}] [score:${score}]\n${entry.content}`;
+  return `[${meta}] [score:${score}]\n${ageLine(entry.updated_at)}\n${entry.content}`;
 }
 
 /**
@@ -195,8 +265,26 @@ function formatRecallResult(entry: MemoryRow & { _score: number }): string {
  * so a topic fragmented across N entries reads as one cluster instead of
  * O(N²) pairs. Verdicts stay pairwise (markChecked) - this is presentation only.
  */
-function renderClusters(candidates: DedupCandidate[]): string {
-  const parent = new Map<string, string>();
+/**
+ * Self-heal the watcher registry from the journal before a watch tool reads
+ * it. The runtime (and its registry) is rebuilt on session directory changes
+ * and plugin reloads, leaving journaled watchers absent from the live set
+ * while the old instance's poller keeps delivering: watch_list reported "No
+ * active watchers" and watch_cancel "No watcher in this session" for
+ * watchers that were alive and firing (observed + reproduced September
+ * 2026). Hydrating the CURRENT process's journal row for the session makes
+ * every watch-tool call converge. Cross-process (dormant) rows stay owned
+ * by the runtime's scanDormantWatchers and its revalidation.
+ */
+function reconcileSessionWatchers(ctx: CoreContext, sessionID: string): void {
+  if (!ctx.watchers) return;
+  const row = ctx.db
+    .runtimeStateAll()
+    .find((r) => r.kind === "watchers" && r.sessionID === sessionID && r.pid === process.pid);
+  if (row && Array.isArray(row.value)) ctx.watchers.hydrate(row.value as Watcher[]);
+}
+
+function renderClusters(candidates: DedupCandidate[]): string {  const parent = new Map<string, string>();
   const find = (x: string): string => {
     let root = parent.get(x) ?? x;
     while (root !== (parent.get(root) ?? root)) root = parent.get(root) ?? root;
@@ -238,8 +326,9 @@ const rememberDef: ToolDef = {
     "Each memory should be focused on a single topic. Write memories as " +
     "reference material for a future instance of yourself with zero context.",
   args: {
-    label: z.string().describe(
-      "Short descriptive title. Used for deduplication - same label in the same store is the same entry.",
+    label: z.string().optional().describe(
+      "Short descriptive title. Used for deduplication - same label in the same store is the same entry. " +
+      "Omit to derive it from the content's first heading or line (capped at 80 characters).",
     ),
     content: z.string().describe(
       "The information to remember. Self-contained, understandable without session context.",
@@ -264,8 +353,32 @@ const rememberDef: ToolDef = {
   },
   async execute(args, ctx) {
     const store = resolveStore(args, ctx);
-    const label = args.label as string;
-    const content = `# ${label}\n\n${args.content as string}`;
+    const rawContent = (args.content as string | undefined)?.trim();
+    if (!rawContent) {
+      return "No content provided - pass the information to remember in the content parameter.";
+    }
+    let label = (args.label as string | undefined)?.trim();
+    let content = rawContent;
+    if (!label) {
+      // Label omitted (or arrived under a misnamed key that schema
+      // validation stripped): derive it from the content so the write
+      // still lands instead of erroring. A leading markdown heading
+      // becomes the label and is stripped from the stored content
+      // (heading-only content keeps the heading text as the body so the
+      // entry is never empty). The 80-char cap keeps a derived label -
+      // which can be a whole first line - from bloating list output and
+      // slug keys; matches deriveTitle's cap in extraction.ts.
+      const firstLine = rawContent.split("\n")[0]?.trim() ?? "";
+      const heading = /^#{1,6}\s+(.+)$/.exec(firstLine);
+      if (heading) {
+        label = heading[1].trim().slice(0, 80);
+        const rest = rawContent.split("\n").slice(1).join("\n").trim();
+        content = rest.length > 0 ? rest : heading[1].trim();
+      } else {
+        label = firstLine.slice(0, 80);
+      }
+    }
+    content = `# ${label}\n\n${content}`;
     const embedding = await ctx.model.passageEmbed(content);
 
     const similar = ctx.db.findSimilar(store, embedding, {
@@ -332,7 +445,7 @@ const recallDef: ToolDef = {
 
     if (results.length === 0) return "No matching memories found.";
 
-    return results.map(formatRecallResult).join("\n\n-----\n\n");
+    return withMemoryCaveat(results.map(formatRecallResult).join("\n\n-----\n\n"));
   },
 };
 
@@ -382,7 +495,7 @@ const showDef: ToolDef = {
 
     if (!entry) return `No memory labeled "${args.label as string}" found in store "${store}".`;
 
-    return formatEntry(entry) || "Error formatting entry.";
+    return withMemoryCaveat(formatEntry(entry) || "Error formatting entry.");
   },
 };
 
@@ -510,7 +623,7 @@ const getExtractionPayloadDef: ToolDef = {
     if (!sessionID) {
       return 'session_id is required on this host (it has no session context). Pass the parent session\'s session_id from the extraction nudge.';
     }
-    const payload = ctx.extractionPayloadProvider(sessionID);
+    const payload = ctx.extractionPayloadProvider(sessionID, host?.sessionID);
     if (!payload) {
       return "No queued tool interactions found for this session.";
     }
@@ -524,8 +637,10 @@ const getExtractionPayloadDef: ToolDef = {
  * Called in a PARENT session after dispatching the fact-extractor, it accepts
  * the buffer: entries move to a holding area and the nudge quiets, but they
  * are not dropped until the extractor completes. Called in a CHILD extractor
- * at the end of its run, it completes the parent's accepted entries -
- * including no-save runs that write no memory. If the child errors or is
+ * at the end of its run, it completes the entries THAT child claimed via its
+ * payload fetch - never the whole accepted set, so a sibling sub-agent's
+ * completion cannot drop another extractor's in-flight payload. Completion
+ * includes no-save runs that write no memory. If the child errors or is
  * deleted before either signal, the host requeues the entries so the facts
  * are not lost.
  *
@@ -599,8 +714,7 @@ const predictionQueryDef: ToolDef = {
     if (scored.length === 0) return "No matching predictions found.";
     return scored.map((s) => {
       const verb = predictionVerb(s.evidence_count);
-      return `[${s.confidence.toFixed(2)} conf, ${s.evidence_count} tests] ` +
-        `When ${s.matcher_description}: ${verb} ${s.statement}`;
+      return formatWhenLine(s.confidence, s.evidence_count, s.matcher_description, s.statement, verb);
     }).join("\n");
   },
 };
@@ -612,7 +726,11 @@ const predictionUpdateDef: ToolDef = {
     "model. Use when the user corrects you, answers a question, or " +
     "provides a clear signal about their preferences or decision-making " +
     "strategy. The tool handles matcher and prediction lookup, dedup, " +
-    "and confidence adjustment automatically.",
+    "and confidence adjustment automatically. " +
+    "ALL FOUR of matcher, prediction, signal, and rationale are required " +
+    "in the SAME call - calls omitting any of them fail validation. " +
+    "signal must be exactly one of: create, confirm, disconfirm, soft " +
+    "(use \"create\" for a new observation - never a prose description).",
   args: {
     matcher: z.string().describe(
       "Description of the situation. What decision was being made? Word it " +
@@ -622,7 +740,11 @@ const predictionUpdateDef: ToolDef = {
       "incident never fires for the next one.",
     ),
     prediction: z.string().describe(
-      "The user's preference or tendency in this situation.",
+      "The user's preference or tendency in this situation. Phrase it as a " +
+      "tendency starting with a base-form verb (e.g. \"prefer X over Y\", " +
+      "\"push back on Z\") rather than " +
+      "a full sentence - the nudge and query renderers prefix the evidence " +
+      "verb (\"you tend to ...\") onto it.",
     ),
     signal: z.enum(["confirm", "disconfirm", "soft", "create"]).describe(
       "What happened: confirm (user confirmed the prediction), " +
@@ -782,7 +904,8 @@ const behaviorCodifyDef: ToolDef = {
     "tests before touching the area; read a large function fully before " +
     "editing it. When a review, bug, or incident reveals a CLASS of " +
     "mistake you are prone to (not a one-off), codify a guard against the " +
-    "class.",
+    "class. ALL THREE of situation, behavior, and rationale are required " +
+    "in the SAME call - calls omitting any of them fail validation.",
   args: {
     situation: z.string().describe(
       "Description of the situation that triggers this behavior. What context " +
@@ -1394,6 +1517,7 @@ const watchCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
     const events = (args.events as PrWatcherEventType[] | undefined) ?? [...PR_EVENT_TYPES];
     const result = await ctx.watchers.createPr(host.sessionID, repo, args.pr as number, events, { once: args.once === true });
@@ -1433,6 +1557,7 @@ const watchListDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const watchers = ctx.watchers.listForSession(host.sessionID);
     if (watchers.length === 0) return "No active watchers.";
     const minutesLeft = (w: { expiresAt: number }) => Math.max(0, Math.round((w.expiresAt - Date.now()) / 60_000));
@@ -1498,6 +1623,7 @@ const watchBranchCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
     const events = (args.events as BranchWatcherEventType[] | undefined) ?? [...BRANCH_EVENT_TYPES];
     const result = await ctx.watchers.createBranch(
@@ -1582,6 +1708,7 @@ const watchCommandCreateDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const dir = (args.cd as string | undefined) ?? ctx.projectDir;
     if (!dir) {
       return "Watching is unavailable: no project directory was wired by this host.";
@@ -1622,6 +1749,7 @@ const watchCancelDef: ToolDef = {
     if (!ctx.watchers) {
       return "Watching is unavailable: no watcher registry was wired by this host.";
     }
+    reconcileSessionWatchers(ctx, host.sessionID);
     const cancelled = ctx.watchers.cancel(host.sessionID, args.id as string);
     if (!cancelled) return `No watcher "${args.id}" in this session.`;
     return `[cancelled] ${args.id}`;

package/src/watchers.ts

@@ -854,6 +854,18 @@ export class WatcherRegistry {
     commandRunner: CommandRunner;
     commandTimeoutMs: number;
   };
+  /**
+   * The most recently constructed instance in this process. 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.
+   */
+  static #live: WatcherRegistry | undefined;
 
   constructor(options: WatcherRegistryOptions) {
     this.#opts = {
@@ -865,6 +877,8 @@ export class WatcherRegistry {
       ...options,
     };
     this.#journal = options.journal;
+    WatcherRegistry.#live?.stop();
+    WatcherRegistry.#live = this;
   }
 
   // -- Lifecycle -----------------------------------------------------------