@jeffober/thatch 0.2.0 → 0.2.2

package/src/opencode/v2.ts

@@ -72,6 +72,10 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // here, and the pump lets their events through.
   const childSessions = new Set<string>();
 
+  // Tool executions currently running against this instance's runtime (see
+  // the counter in the tool execute wrapper below).
+  let inflightTools = 0;
+
   const capabilities = buildCapabilities(context, worktree, childSessions);
   const runtime = await createRuntime({ capabilities, directory, worktree });
   // Seed the forwarding set from rehydrated child bookkeeping: after a
@@ -97,9 +101,33 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
         description: def.description,
         input: z.toJSONSchema(z.object(def.args)),
         execute: async (input: unknown, toolContext: V2ToolContext) => {
-          const host: HostToolContext | undefined = trimHostContext(toolContext);
-          const result: string = await def.execute(input as Record<string, unknown>, runtime.coreContext, host);
-          return { content: result } as Tool.Result;
+          // In-flight counter (read by the cleanup below): v2 tears the old
+          // activation down while a call it registered may still be running,
+          // so cleanup waits briefly for stragglers before disposing the
+          // runtime whose db they use.
+          inflightTools++;
+          try {
+            const host: HostToolContext | undefined = trimHostContext(toolContext);
+            const result: string = await def.execute(input as Record<string, unknown>, runtime.coreContext, host);
+            return { content: result } as Tool.Result;
+          } catch (err) {
+            // A db closed mid-call by a concurrent reload's dispose surfaces
+            // here even after the wait (the call may have started racing the
+            // cleanup itself). Fail the call with an explicit retry hint -
+            // the reloaded instance is live by then, so a retry succeeds.
+            // (Hard failures are never retried by models - every prior
+            // session that hit one just abandoned the call.)
+            if (err instanceof Error && /closed database|connection closed/i.test(err.message)) {
+              return {
+                content:
+                  "thatch: the plugin was reloaded mid-call and this instance's database handle " +
+                  "was closed underneath it. The reloaded instance is live - retry the same call.",
+              } as Tool.Result;
+            }
+            throw err;
+          } finally {
+            inflightTools--;
+          }
         },
       });
     }
@@ -296,11 +324,21 @@ export async function setup(context: V2Context): Promise<V2Cleanup | void> {
   // second setup after a skipped or partial cleanup would double every
   // poller, pump, and nudge. The pump await is safe: its body is fully
   // try/caught and abort ends the loop, so it settles promptly.
+  //
+  // Before disposing the runtime, briefly drain in-flight tool executions:
+  // v2 tears this activation down mid-turn, and an execute whose db access
+  // would race the close either completes here or (past the bound) hits the
+  // lazy reopen + retry hint in the wrapper. The bound keeps a hung tool
+  // from holding the reload hostage.
   let disposed = false;
   return async () => {
     if (disposed) return;
     disposed = true;
     controller.abort();
+    const drainDeadline = Date.now() + 5_000;
+    while (inflightTools > 0 && Date.now() < drainDeadline) {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
     await pump;
     registerTools.dispose();
     registerToolHook.dispose();
@@ -394,7 +432,13 @@ export function translateEvent(located: { type: string; data?: any }): { type: s
   const data = located.data ?? {};
   switch (located.type) {
     case "session.created":
-      return [{ type: "session.created", properties: { info: { id: data.sessionID, parentID: data.parentID } } }];
+      // v2 publishes the v1-compat payload { sessionID, info: SessionInfo };
+      // the parent link lives at info.parentID (the task tool dispatches
+      // sub-agents with parentID), not at the payload top level. Without
+      // this, childToParent never populates on v2 and every child-session
+      // behavior (buffer drain, nudge suppression, child cleanup) silently
+      // only works on v1.
+      return [{ type: "session.created", properties: { info: { id: data.sessionID, parentID: data.info?.parentID ?? data.parentID } } }];
     case "session.deleted":
       return [{ type: "session.deleted", properties: { info: { id: data.sessionID } } }];
     case "session.execution.started":

package/src/prompts.ts

@@ -10,6 +10,29 @@ export function predictionVerb(evidenceCount: number): string {
   return evidenceCount === 0 ? "you may prefer" : "you tend to";
 }
 
+/**
+ * Shared nudge-line formatter for the prediction and behavior surfaces.
+ * The model supplies the matcher and statement text, and both frequently
+ * arrive already carrying the render prefixes: matchers phrased as
+ * "When ..." (a natural situation phrasing, or copied from an earlier
+ * nudge) and statements copied with the evidence verb ("you tend to ...").
+ * The unconditional prefixes doubled that text in every rendered nudge,
+ * so each prefix is skipped when the supplied text already carries it.
+ */
+export function formatWhenLine(
+  confidence: number,
+  evidenceCount: number,
+  matcher: string,
+  statement: string,
+  verb: string,
+): string {
+  const matcherText = /^when\b/i.test(matcher) ? matcher : `When ${matcher}`;
+  const statementText = new RegExp(`^${verb}\b`, "i").test(statement) || /^you (?:tend to|may prefer)\b/i.test(statement)
+    ? statement
+    : `${verb} ${statement}`;
+  return `[${confidence.toFixed(2)} conf, ${evidenceCount} tests] ${matcherText}: ${statementText}`;
+}
+
 /**
  * Cross-session chat section of the opencode system prompt. Omitted when the
  * user disabled chat via config (chat.enabled: false), so a disabled feature
@@ -73,6 +96,49 @@ ought to trigger it and widen the wording to the broadest surface of the
 class - a matcher that only names this incident never fires for the next
 one.`;
 
+/**
+ * The artifact-pointer bullet of the "How to Write" section. Names no
+ * tools, so it is shared verbatim by both prompt variants (the
+ * class-lesson convention above).
+ */
+const artifactPointerBullet = `- Artifact memories should carry their pointers: file paths, ticket IDs,
+  package names. Verification is cheap later only if the memory says where
+  to check. A pointer is provenance for durable knowledge, not knowledge
+  itself - a bare "where X lives" is exactly what the durability test
+  excludes.`;
+
+/**
+ * "Memories are pointers, not truth" instruction body, shared by all three
+ * prompt variants. Takes a ToolNamer because the section names memory tools
+ * (thatch_memory_remember on opencode, bare on MCP hosts, whose
+ * instructions establish the bare-name convention). Staleness is a
+ * property of the claim's relationship to a mutable world, not of the
+ * memory's age.
+ */
+export function memoryPointersSection(tool: ToolNamer): string {
+  return `## Memories Are Pointers, Not Truth
+
+${tool("memory_recall")} surfaces a point-in-time record: a semantic guide
+associating "what I'm looking for" with "where I should look", written when
+the knowledge was current. Memories speed up research - they do not replace
+it, and they are not a source of truth.
+
+- **Policy memories** ("the user always wants X", "check CI after merging")
+  are self-executing: they are the ground truth for behavior.
+- **Artifact memories** ("feature X lives in <file> and uses <technique>")
+  are pointers to checkable claims about code, docs, tickets, or git.
+  Follow the pointer and assert from the source, not from the memory.
+
+Before asserting an artifact claim from memory, re-derive it from the
+current source. Confirming the reference still exists verifies little: the
+file can survive while the behavior changed (scope drift, priority shifts,
+implementation details that proved too complex in practice).
+The source wins. When reality has moved on, correct the record with
+${tool("memory_remember")} (overwrite: true) or ${tool("memory_forget")} -
+silently; memory maintenance is not user-facing. For a deep staleness check
+of a specific memory, load the thatch-memory-verify skill.`;
+}
+
 export function systemPrompt(repo: string, chatEnabled = true): string {
   return `# Persistence
 
@@ -106,13 +172,16 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 
 ## Session Startup
 
-1. thatch_memory_recall "user preferences and personality"
-2. thatch_memory_recall "project architecture and conventions"
-3. If on a non-main branch, thatch_memory_recall with the branch name
+1. thatch_memory_recall({ query: "user preferences and personality" })
+2. thatch_memory_recall({ query: "project architecture and conventions" })
+3. If on a non-main branch, thatch_memory_recall with the branch name as the query
 4. thatch_memory_list and thatch_store_list to see what's available
 
 Before diving into code, thatch_memory_recall with a query relevant to the area
-you're working in. Prior sessions may have already investigated it.
+you're working in. Prior sessions may have already investigated it. All thatch
+tools take a single object argument: never a bare positional string. Call them
+directly, or through the Code Mode execute runtime when the harness only
+exposes tools through code.
 
 ## Skills
 
@@ -123,6 +192,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
 - \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
 - \`thatch-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
@@ -134,7 +210,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
-- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory looks stale or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 - \`thatch-clear-writing\` - prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Load before drafting any of those.
 
@@ -162,15 +238,7 @@ whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
 
-## Memory Verification
-
-When thatch_memory_show or thatch_memory_recall returns a memory with an old
-updated_at date (more than a few weeks), consider loading the
-thatch-memory-verify skill to fact-check its code-related claims against the
-current codebase before relying on them. This is not mandatory for every old
-memory. Use judgment: a memory about a stable architectural decision may be
-fine for months, while a memory about file locations or function names is
-more likely to drift.
+${memoryPointersSection(opencodeToolName)}
 
 ## Background Task Completions
 
@@ -187,6 +255,12 @@ the same prompt. If the re-dispatch also fails or times out, note the gap and
 move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
+When the fact-extractor sub-agent completes, its "Extraction complete."
+report is a background-task completion, not an extraction nudge: the buffer
+is drained and nothing follows from it. Never re-dispatch an extractor
+because a completion arrived - a new extraction nudge is the only dispatch
+signal.
+
 ## Watchers
 
 Use thatch_watch_create to watch a GitHub PR for events (comments, review
@@ -304,6 +378,7 @@ config in memory.
 - One topic per memory. Write for a future instance with zero current context.
 - Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
   10: hard constraint.
+${artifactPointerBullet}
 
 ## What NOT to Store
 
@@ -422,13 +497,14 @@ WIP, PR status). Unscoped memories are project-wide and always included in searc
 
 ## Session Startup
 
-1. \`memory_recall\` "user preferences and personality" (global store)
-2. \`memory_recall\` "project architecture and conventions" (project store)
-3. If on a non-main branch, \`memory_recall\` with the branch name
+1. \`memory_recall\` with \`{"query": "user preferences and personality"}\` (global store)
+2. \`memory_recall\` with \`{"query": "project architecture and conventions"}\` (project store)
+3. If on a non-main branch, \`memory_recall\` with the branch name as the query
 4. \`memory_list\` and \`store_list\` to see what's available
 
 Before diving into code, \`memory_recall\` with a query relevant to the area
-you're working in. Prior sessions may have already investigated it.
+you're working in. Prior sessions may have already investigated it. All thatch
+tools take a single JSON object argument: never a bare positional string.
 
 ## Skills
 
@@ -437,6 +513,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 - \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
 - \`thatch-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
 - \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
@@ -450,7 +533,7 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
 - \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
 - \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
-- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory has an old \`updated_at\` date or when preparing a knowledge export.
+- \`thatch-memory-verify\` - fact-check a single memory against the current codebase and correct stale claims. Use when a memory looks stale or when preparing a knowledge export.
 - \`thatch-knowledge-export\` - compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories, and generates a clean export.
 - \`thatch-clear-writing\` - prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Load before drafting any of those.
 
@@ -478,14 +561,7 @@ whether you've discovered knowledge worth persisting. Use memory_recall to
 check for duplicates, then memory_remember for new findings. Then deliver
 your response.
 
-## Memory Verification
-
-When memory_show or memory_recall returns a memory with an old updated_at
-date (more than a few weeks), consider loading the thatch-memory-verify skill
-to fact-check its code-related claims against the current codebase before
-relying on them. This is not mandatory for every old memory. Use judgment: a
-memory about a stable architectural decision may be fine for months, while a
-memory about file locations or function names is more likely to drift.
+${memoryPointersSection(bareToolName)}
 
 ## User Decision Model
 
@@ -571,6 +647,7 @@ hand-editable; do not store thatch config in memory.
 - One topic per memory. Write for a future instance with zero current context.
 - Confidence 1-2: single signal. 5-6: moderate. 9: explicitly stated.
   10: hard constraint.
+${artifactPointerBullet}
 
 ## What NOT to Store
 
@@ -683,6 +760,13 @@ export type ToolNamer = (name: string) => string;
 export const opencodeToolName: ToolNamer = (name) => `thatch_${name}`;
 export const mcpToolName: ToolNamer = (name) => `mcp__thatch__${name}`;
 
+/**
+ * The bare name itself. Used by prompt sections embedded in instructions
+ * that establish the bare-name convention (mcpInstructions and twins): the
+ * model maps bare names to the host spelling at call time.
+ */
+export const bareToolName: ToolNamer = (name) => name;
+
 /**
  * The extraction instruction body. sessionIdArg is either ` with session_id
  * "X"` (the nudge path: the sub-agent's session differs from the parent's)
@@ -866,7 +950,11 @@ function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
   const verb = n === 1 ? "relates" : "relate";
   const labels = matches.slice(0, 2).map((m) => `"${m.label}"`).join(", ");
   const etc = n > 2 ? ", etc." : "";
-  return `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). Use ${toolName} before responding.`;
+  return (
+    `[thatch] ${n} ${word} ${verb} to this prompt (${labels}${etc}). ` +
+    `Use ${toolName}({ query: "..." }) before responding - the argument is ` +
+    `a single object with a "query" key, never a bare positional string.`
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -879,7 +967,7 @@ function formatRecallNudge(matches: NudgeMatch[], toolName: string): string {
 export function predictionNudge(items: PredictionNudgeItem[]): string {
   const lines = items.map((p) => {
     const verb = predictionVerb(p.evidence_count);
-    return `- [${p.confidence.toFixed(2)} conf, ${p.evidence_count} tests] When ${p.matcher_description}: ${verb} ${p.statement}`;
+    return `- ${formatWhenLine(p.confidence, p.evidence_count, p.matcher_description, p.statement, verb)}`;
   });
   return `[thatch] User decision model\n${lines.join("\n")}`;
 }
@@ -893,7 +981,7 @@ export function predictionNudge(items: PredictionNudgeItem[]): string {
 export function behaviorNudge(items: BehaviorNudgeItem[]): string {
   const lines = items.map((b) => {
     const verb = b.evidence_count === 0 ? "consider" : "do";
-    return `- [${b.confidence.toFixed(2)} conf, ${b.evidence_count} tests] When ${b.matcher_description}: ${verb} ${b.statement}`;
+    return `- ${formatWhenLine(b.confidence, b.evidence_count, b.matcher_description, b.statement, verb)}`;
   });
   return `[thatch] Situational behaviors\n${lines.join("\n")}`;
 }