@jeffober/thatch 0.2.0 → 0.2.2

package/docs/dev/features/opencode-plugin.md

@@ -75,7 +75,7 @@ the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
 | TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984). On v2 the right target closes THIS session's tab (tab-scoped), not `app.exit`: the daemon hosts every tab; the `tui` companion entrypoint's `ui.tabs.close` is the known lift candidate) |
 | tab close | n/a | no session.deleted on v2 tab close | known gap: a closed tab's watchers keep polling until their TTL (deliveries fail their idle gate and stay pending); restart dormancy covers the daemon-restart case, not tab close |
 | wake gate after reload | `session.status` event map | map rehydrates empty | known gap: v2's fetchStatuses stub is structural (the promise context has no session.status), so in the reload window - until the session's next status event - the proactive-prompt gate is fully open |
-| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
+| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; child rows carry a kind marker (extraction vs task-dispatched sub-agent, defaulting to extraction for pre-marker rows) so only extraction children restore the `extracting`/`extractionChildren` sets; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
 
 ## Live verification and remaining unknowns
 

package/docs/dev/features/session-lifecycle.md

@@ -117,7 +117,7 @@ first-ever install is invisible until the next server start.
 ## Interactions with other features
 
 - Extraction pipeline ([extraction.md](extraction.md)): direct extraction is triggered by `session.status idle`; child lifecycle managed here
-- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `extracting` set suppresses tier 1; `compacting` set suppresses all tiers
+- Nudge pipeline ([nudge-pipeline.md](nudge-pipeline.md)): `extracting` set suppresses tier 1; `compacting` set suppresses all tiers; task-dispatched sub-agents (in `childToParent`, not in `extractionChildren`) suppress all tiers
 - Hygiene ([hygiene.md](hygiene.md)): hygiene report runs at `session.created` for top-level sessions
 - Compaction recovery ([compaction-recovery.md](compaction-recovery.md)): `session.compacted` event clears the compacting flag
 - Memory store ([memory-store.md](memory-store.md)): child sessions write memories via `memory_remember`, which triggers drain via `tool.execute.after`

package/docs/dev/gotchas.md

@@ -41,7 +41,7 @@ here first. These are the things that have already cost time.
   a memory, write it with `archived: true`; to unarchive, `archived: false`.
 - **Updating an archived memory requires explicit `archived` param.** If the
   entry is already archived and a `remember` call omits the `archived` param,
-  the tool returns an error (`db.ts:395`). Pass `archived: true` to keep it
+  the tool returns an error (`db.ts:585`). Pass `archived: true` to keep it
   archived or `archived: false` to unarchive. This guard prevents accidental
   unarchival via an unrelated content update.
 
@@ -229,3 +229,73 @@ wrapped tool's hook semantics instead of buffering. Lesson for sibling
 hooks: when a filter reasons about tool identity, an aggregator tool
 (arbitrary code execution over other tools) defeats name-based matching -
 unwrap the aggregation before classifying.
+
+## LLMs guess tool-call shapes on the first call, so teach the shape at the mention site
+
+A September 2026 audit of every thatch tool-call error in the opencode
+session database (~19k calls, both v1 and v2 storage) found the failures
+cluster on the model's FIRST thatch call - usually the startup recall round -
+and fall into a short list of avoidable mistakes:
+
+- **Bare positional string instead of an object argument** (the largest
+  bucket): `thatch_memory_recall({ query: "..." })` called as
+  `thatch_memory_recall("...")`. Root cause: the opencode system prompt's
+  startup section and the recall nudge both used positional-style examples
+  (`thatch_memory_recall "query"`), and Code Mode models mimic that shape
+  inside `execute`. Both now teach the object form.
+- **Required discriminator params omitted**: `memory_remember` without
+  `label` (models pass `title`/`id`/`statement` instead, or nothing),
+  `prediction_update` without `signal`, `behavior_codify` without
+  `situation`. Fixes: `label` is optional and derived from content;
+  tool descriptions state the all-args-required contract.
+- **Nudges leak into tool-less agent contexts**: task-dispatched sub-agents
+  (explore/general and friends) have restricted tool lists that exclude the
+  thatch tools, but `chat.message` nudges fired for them anyway, producing
+  guaranteed "No tool named ..." error rounds. The chat.message hook now
+  skips nudges for child sessions that are not extraction children.
+
+The general lesson: any surface that names a tool to an LLM (system prompt,
+nudge, skill text) is a usage-shape prior. Give the argument shape at the
+mention site, because the model's first call happens before it has seen a
+working example. Also note Code Mode `execute` validation failures are only
+persisted in the v2 `session_message` store - they are invisible in the v1
+`part` table, so error-rate analysis on old data undercounts them.
+
+## ThatchDB lazy reopen: new accessors must go through the private getters, and journal writes stay guarded at call sites
+
+`ThatchDB` reopens its SQLite connection on first use after `close()`
+(`src/db.ts`, the `#db`/`#predictions`/`#behaviors`/`#chat` private getters), so
+an in-flight tool call that races a v2 plugin reload's `dispose()` completes
+instead of throwing "Cannot use a closed database". Two rules keep this intact:
+
+- **New facade methods need no extra wiring, but new state-holding members
+  do.** The engine facades (`ChatStore`, `PredictionEngine`, `BehaviorEngine`)
+  capture the `Database` handle at construction; the reopen rebuilds them. A
+  new member that captures the Database directly must get its own private
+  getter that ensures the handle is open first - a plain field keeps serving
+  the stale closed handle and the reopen silently never fires for it (this
+  exact bug is pinned by the "engine facades are rebuilt" test in
+  tests/db.test.ts).
+- **Post-dispose journal writes are no-ops at their call sites, not in
+  db.ts.** After a reload, the RELOADED instance owns the `runtime_state`
+  rows, so delayed writers in `src/runtime.ts` check the `disposed` flag
+  BEFORE touching the db - the lazy reopen would otherwise hand a stale
+  writer a fresh connection. All three journal callbacks are guarded (the
+  extraction pipeline's finalization, the WatcherRegistry journal - a poll
+  cycle suspended at an await can outlive `watchers.dispose()` - and the
+  wrap-up arming write, whose command executes are not drained by the v2
+  cleanup). Do not "fix" the guard away by moving it into db.ts: the
+  accessor cannot tell a legitimate in-flight caller from a stale writer.
+
+## Command frontmatter descriptions must be quoted YAML scalars
+
+- **A plain-scalar frontmatter value containing a colon followed by a space
+  is invalid YAML, and not every host path rescues it.** `/thatch/hygiene`'s
+  description ("Tend the memory store: stale entries, ...") shipped unquoted;
+  the first parse throws
+  and only opencode's fallback sanitizer recovers it — and a long-lived
+  server was observed dropping the description entirely while a fresh server
+  parsed it fine, which made the bug look like a TUI rendering issue. The
+  renderer quotes every description (`yamlQuote` in src/commands.ts) and a
+  unit test pins the quoted form. Keep it that way for any new frontmatter
+  field whose value is free-form prose.

package/docs/dev/mcp-parity.md

@@ -23,7 +23,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
-| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`, `refine`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |

package/docs/dev/setup-and-hooks.md

@@ -25,7 +25,7 @@ code (`src/opencode/v1.ts`):
 | `experimental.session.compacting` | `{ sessionID }` | `{ context: string[] }` | Marks the session as compacting, pushes re-familiarization context. |
 | `experimental.compaction.autocontinue` | `{ sessionID }` | `{ enabled: boolean }` | Clears the compacting flag so `chat.message` nudges resume post-compaction. |
 | `tool.execute.after` | `{ tool, sessionID, callID, args }` | `{ title, output, metadata }` | Buffers non-`thatch_`, non-`skill`, non-`task` tool calls into the in-memory extraction ring buffer (max 20). In child sessions, also tracks new/updated/deleted counts via `childMetrics` for the extraction toast. |
-| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending and not already extracting (fallback — direct extraction via the `event` hook is the primary path), else prompt-aware recall nudge. Suppressed while compacting or while `extracting` is set. |
+| `chat.message` | `{ sessionID, messageID }` | `{ message, parts }` | Two tiers: extraction nudge if pending and not already extracting (fallback — direct extraction via the `event` hook is the primary path), else prompt-aware recall nudge. Suppressed while compacting, while `extracting` is set, or for task-dispatched sub-agent sessions (children that are not extraction children). |
 | `event` | `{ event: { type, properties } }` | — | Dispatches on `event.type`: `session.created` (top-level) → `client.session.prompt` with reminder + hygiene heartbeat; `session.created` (child with `parentID`) → records `childToParent` + snapshots parent's pending buffer. `session.status` idle (parent, pending interactions) → `triggerExtraction` (direct child-session extraction); idle (child) → complete/drain, `showToast` with metrics, delete child. `session.error` (child) → requeue parent's accepted entries. `session.deleted` → requeue if child, drop accepted if parent, clean maps. `session.compacted` → clear compacting flag. |
 | `dispose` | — | — | Closes the DB. |
 

package/docs/dev/skills.md

@@ -55,7 +55,14 @@ description: Extract durable project facts ... Use when ...
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
-| `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). |
+| `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). The generic core loop. |
+| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. 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-pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, 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. |

package/docs/user/README.md

@@ -104,7 +104,7 @@ Stores are created automatically. No setup required.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_memory_remember` | Save a piece of information. Label it, and thatch embeds it for later recall. |
+| `thatch_memory_remember` | Save a piece of information; thatch embeds it for later recall. The label is optional - it is derived from the content's first heading or line when omitted. |
 | `thatch_memory_recall` | Search for relevant information using natural language. Searches both the current project's store and `global` by default. |
 | `thatch_memory_list` | List all memory labels in a store. |
 | `thatch_memory_show` | Read the full content of a memory by exact label. |
@@ -328,6 +328,13 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
 
 ### Writing skills
 

package/docs/user/commands.md

@@ -17,6 +17,13 @@ or you invoke it.
   The agent asks before forgetting anything that may still matter.
 - `/thatch/reflect` — run the session-reflection skill to persist what the
   current session learned.
+- `/thatch/refine` — refine a plan for a code change under the current
+  project type's requirements: the agent classifies the project (team,
+  personal, shared library, spike, infrastructure, or open source
+  contribution), confirms the pick, and runs the refinement loop with
+  that type's expectations applied. Text after the command can name the
+  type directly (for example, `/thatch/refine shared-lib`) to skip
+  classification.
 - `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
   pre-flight checklist (flush extraction, finish promised memory writes,
   surface loose ends) before a compaction or an exit, gated by a greenlight
@@ -31,6 +38,7 @@ or you invoke it.
 | `/thatch/extract` | yes | no | no |
 | `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/refine` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/compact`, `/thatch/exit` | yes | no | no |
 
 Why the gaps: `/thatch/extract` needs the invoking session's ID, which only

package/docs/user/memory.md

@@ -33,7 +33,7 @@ store when recalling.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_memory_remember` | Save a memory with a label and content. Optional: branch, confidence (1-10), archived flag, overwrite. |
+| `thatch_memory_remember` | Save a memory with a label and content. The label may be omitted - it is derived from the content's first heading or line. Optional: branch, confidence (1-10), archived flag, overwrite. |
 | `thatch_memory_recall` | Semantic search across stores. Returns matching memories with similarity scores. |
 | `thatch_memory_list` | List all memories in a store (metadata only, no content). |
 | `thatch_memory_show` | Show full content of a single memory by label. |

package/docs/user/skills.md

@@ -77,6 +77,18 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
 
+### Plan refinement skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
+
 ## Stale skill cleanup
 
 When skills are renamed or removed in a new release, thatch automatically

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/chat.ts

@@ -1371,6 +1371,23 @@ export function hostedSessionIds(options: {
   return [...new Set(hosted)].filter((id) => !excluded.has(id));
 }
 
+/**
+ * Grace-rehost ids still inside their rehost window, pruning expired
+ * entries as a side effect (the map is the runtime's live restart-grace
+ * state - see CHAT_REHOST_GRACE_MS in runtime.ts). A restart re-hosts the
+ * dead daemon's hosted set under this grace: open TUI tabs reconnect but
+ * emit no events until the user types, so without it they go falsely
+ * stale while alive-idle.
+ */
+export function unexpiredGraceRehosts(grace: Map<string, number>, now: number): string[] {
+  const live: string[] = [];
+  for (const [id, deadline] of grace) {
+    if (now >= deadline) grace.delete(id);
+    else live.push(id);
+  }
+  return live;
+}
+
 export class ChatPoller {
   #opts: Required<ChatPollerOptions>;
   #timer: ReturnType<typeof setInterval> | null = null;

package/src/commands.ts

@@ -100,6 +100,16 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
       description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
       body: hygieneCore(),
     },
+    {
+      name: "refine",
+      description: "Refine a plan under the project type's requirements (classifies the project first)",
+      // A skill trigger, not a nudge behavior: the body points at the
+      // thatch-refine router skill, which classifies the project and loads
+      // the matching type deltas on top of the plan-refinement core loop.
+      body: `Load and follow the thatch-refine skill to refine a plan for the current project.
+
+The user message may name a project type (team-app, personal, shared-lib, spike, infra, oss-contribution); if it does, skip classification and use that type. If no plan is drafted yet in this session, the skill's loop starts with drafting one.`,
+    },
     {
       name: "reflect",
       description: "Persist what this session learned as memories",
@@ -108,10 +118,20 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
   ];
 }
 
+/**
+ * Renders a YAML double-quoted scalar. Plain scalars break on values
+ * containing ": " (invalid YAML - the mapping key would be ambiguous), and
+ * opencode's lenient fallback parser does not rescue every host path, so the
+ * description must always be quoted.
+ */
+function yamlQuote(value: string): string {
+  return JSON.stringify(value);
+}
+
 /** Renders one action as a full command markdown file. */
 export function renderActionCommand(action: ActionDef): string {
   return `---
-description: ${action.description}
+description: ${yamlQuote(action.description)}
 ---
 ${userMessageSection}
 
@@ -121,7 +141,7 @@ ${action.body}`;
 }
 
 const COMPACT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then compact if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then compact if clear")}
 ---
 ${userMessageSection}
 
@@ -138,7 +158,7 @@ ${COMPACT_READY_TOKEN}
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
 
 const EXIT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then exit opencode if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then exit opencode if clear")}
 ---
 ${userMessageSection}
 

package/src/db.ts

@@ -55,12 +55,67 @@ export interface DedupCandidate {
  * stored as BLOBs. Similarity search is brute-force cosine in JS.
  */
 export class ThatchDB {
-  #db: Database;
-  #predictions: PredictionEngine;
-  #behaviors: BehaviorEngine;
-  #chat: ChatStore;
+  #path: string;
+  #handle: Database | null = null;
+  #predictionsStore!: PredictionEngine;
+  #behaviorsStore!: BehaviorEngine;
+  #chatStore!: ChatStore;
 
   constructor(path: string) {
+    this.#path = path;
+    this.#open();
+  }
+
+  /**
+   * Connection accessor. Every read goes through here, so a handle closed by
+   * dispose() (a v2 plugin reload tears down the old activation while tool
+   * calls may still be in flight) transparently reopens on the next touch
+   * instead of surfacing bun:sqlite's "Cannot use a closed database". WAL
+   * journaling plus busy_timeout make the extra connection safe - the chat
+   * subsystem already runs as several concurrent connections by design.
+   *
+   * OWNERSHIP RULE: reopen serves READS and in-flight callers only. After a
+   * reload, the RELOADED instance owns the runtime_state journal rows, so
+   * post-dispose journal writes must no-op - they are guarded by the
+   * disposed flag at their call sites in src/runtime.ts, checked BEFORE any
+   * db access reaches this accessor. Do not move that guard in here: this
+   * method cannot distinguish a legitimate in-flight caller from a stale
+   * writer.
+   *
+   * Reopen caveat: a `:memory:` database has no file behind it, so a
+   * close-then-use cycle on one yields a brand-new EMPTY database. No
+   * production path does that (:memory: is test-only and tests never use the
+   * instance after close), but keep it that way - use a tmp-file db if a
+   * test needs close-then-use.
+   */
+  get #db(): Database {
+    if (this.#handle === null) this.#open();
+    return this.#handle!;
+  }
+
+  // The engine facades get the same treatment as #db: every accessor
+  // ensures an open connection first, so delegation routes through the
+  // facade REBUILT by the reopen rather than the stale one. Without this,
+  // a post-close chat call would reach the old ChatStore's captured handle
+  // and throw "Cannot use a closed database" even though ThatchDB itself
+  // reopened.
+  get #predictions(): PredictionEngine {
+    if (this.#handle === null) this.#open();
+    return this.#predictionsStore;
+  }
+
+  get #behaviors(): BehaviorEngine {
+    if (this.#handle === null) this.#open();
+    return this.#behaviorsStore;
+  }
+
+  get #chat(): ChatStore {
+    if (this.#handle === null) this.#open();
+    return this.#chatStore;
+  }
+
+  #open(): void {
+    const path = this.#path;
     // bun:sqlite creates the file but not its parent directory. On a fresh
     // machine the default path (~/.config/thatch/thatch.db) has no dir yet, so
     // create it here - otherwise every command fails with SQLITE_CANTOPEN.
@@ -68,18 +123,23 @@ export class ThatchDB {
     if (path !== ":memory:" && !path.startsWith("file:")) {
       mkdirSync(dirname(path), { recursive: true });
     }
-    this.#db = new Database(path, { create: true });
-    this.#db.run("PRAGMA journal_mode = WAL");
-    this.#db.run("PRAGMA busy_timeout = 5000");
+    const db = new Database(path, { create: true });
+    db.run("PRAGMA journal_mode = WAL");
+    db.run("PRAGMA busy_timeout = 5000");
     // Enforce FK constraints per connection. The prediction tables use
     // ON DELETE CASCADE for edges and provenance; enabling this pragma
     // ensures those cascades fire. Also enforces the entries table's
     // existing FK to stores(name), which was declarative but unenforced
     // before this branch.
-    this.#db.run("PRAGMA foreign_keys = ON");
-    this.#predictions = new PredictionEngine(this.#db);
-    this.#behaviors = new BehaviorEngine(this.#db);
-    this.#chat = new ChatStore(this.#db);
+    db.run("PRAGMA foreign_keys = ON");
+    this.#handle = db;
+    // The engine facades hold the Database handle they were constructed
+    // with, so a reopened connection rebuilds them. They are stateless
+    // views over SQLite - all durable state lives in the tables - so
+    // reconstruction is lossless.
+    this.#predictionsStore = new PredictionEngine(db);
+    this.#behaviorsStore = new BehaviorEngine(db);
+    this.#chatStore = new ChatStore(db);
     this.#initSchema();
   }
 
@@ -1169,7 +1229,12 @@ export class ThatchDB {
   }
 
   close(): void {
-    this.#db.close();
+    // Drops the current handle only. A later use reopens (see the #db
+    // accessor) - the MCP server and CLI call this on process shutdown,
+    // where nothing follows; the opencode plugin's dispose calls it on
+    // reload, where straggler in-flight tool calls must survive.
+    this.#handle?.close();
+    this.#handle = null;
   }
 }
 

package/src/extraction.ts

@@ -233,6 +233,93 @@ export class ExtractionPipeline {
     this.#journal?.("accepted", sessionID, undefined);
   }
 
+  #claims = new Map<string, { target: string; entries: ToolInteraction[] }>();
+
+  /**
+   * Claim the session's pending + previously-accepted entries for a fetcher
+   * (the extractor sub-agent fetching its payload). The entries stay in the
+   * accepted holding area; the claim records WHICH fetcher they were
+   * delivered to, so that fetcher's completion signal consumes only its own
+   * delivery. Without this, any child's completion dropped the whole
+   * accepted set - a sibling sub-agent going idle at the wrong moment
+   * silently discarded another extractor's in-flight payload (the
+   * accept-then-racing-completion loss, observed September 2026).
+   *
+   * Entries are claimed by reference identity: later accepts append new
+   * arrays, so a stale claim never reaches entries claimed after it.
+   */
+  claim(sessionID: string, fetcherID: string): ToolInteraction[] {
+    this.accept(sessionID);
+    const accepted = this.#accepted.get(sessionID) ?? [];
+    this.#claims.set(fetcherID, { target: sessionID, entries: accepted });
+    return accepted;
+  }
+
+  /**
+   * Consume only the fetcher's claimed entries. Returns false when the
+   * fetcher holds no claim - a sibling that never fetched, or a fetch that
+   * never happened. Callers must NOT fall back to whole-set completion on
+   * the idle path: a fetcher that never fetched processed nothing, and
+   * dropping the set would lose another extractor's claimed payload.
+   */
+  completeClaimed(fetcherID: string): boolean {
+    const claim = this.#claims.get(fetcherID);
+    if (!claim) return false;
+    this.#claims.delete(fetcherID);
+    const accepted = this.#accepted.get(claim.target);
+    if (accepted) {
+      const claimed = new Set(claim.entries);
+      const rest = accepted.filter((ix) => !claimed.has(ix));
+      if (rest.length > 0) {
+        this.#accepted.set(claim.target, rest);
+        this.#journal?.("accepted", claim.target, rest);
+      } else {
+        this.#accepted.delete(claim.target);
+        this.#acceptedAt.delete(claim.target);
+        this.#journal?.("accepted", claim.target, undefined);
+      }
+    }
+    return true;
+  }
+
+  /** Forget a fetcher's claim (its session was deleted or cleaned up). */
+  dropClaim(fetcherID: string): void {
+    this.#claims.delete(fetcherID);
+  }
+
+  /**
+   * Requeue only the fetcher's claimed entries back to pending: its session
+   * errored, so the delivery was never processed. Returns false when the
+   * fetcher holds no claim - a task-kind child that never fetched processed
+   * nothing, and requeueing the whole accepted set here would yank another
+   * extractor's in-flight claim back to pending for duplicate extraction.
+   * Callers decide whether a claim-less error falls back to whole-set
+   * requeue (extraction children: yes - the error is a strong immediate
+   * death signal; task children: no).
+   */
+  requeueClaimed(fetcherID: string): boolean {
+    const claim = this.#claims.get(fetcherID);
+    if (!claim) return false;
+    this.#claims.delete(fetcherID);
+    const accepted = this.#accepted.get(claim.target);
+    if (accepted) {
+      const claimed = new Set(claim.entries);
+      const rest = accepted.filter((ix) => !claimed.has(ix));
+      if (rest.length > 0) {
+        this.#accepted.set(claim.target, rest);
+        this.#journal?.("accepted", claim.target, rest);
+      } else {
+        this.#accepted.delete(claim.target);
+        this.#acceptedAt.delete(claim.target);
+        this.#journal?.("accepted", claim.target, undefined);
+      }
+    }
+    const buf = this.#buffers.get(claim.target) ?? [];
+    this.#buffers.set(claim.target, [...claim.entries, ...buf]);
+    this.#journal?.("buffer", claim.target, this.#buffers.get(claim.target));
+    return true;
+  }
+
   /**
    * Move accepted entries back to pending: the extractor errored or its
    * session was deleted before completing, so the facts were never
@@ -254,9 +341,8 @@ export class ExtractionPipeline {
   /**
    * Requeues accepted entries that have waited longer than maxAgeMs for a
    * completion signal that never came: the extractor sub-agent crashed
-   * without acking, or (v2) completed without a parent linkage the plugin
-   * could see. Without this, accepted entries linger unprocessed AND
-   * un-nudged - silent loss. Returns the session ids that had entries
+   * without acking, or the completion ack was lost. Without this, accepted
+   * entries linger unprocessed AND un-nudged - silent loss. Returns the session ids that had entries
    * requeued; the regular nudge path picks them up from pending on the
    * session's next message.
    */

package/src/index.ts

@@ -14,6 +14,8 @@
 // SDK. The pure helpers re-exported here live in SDK-free modules for the
 // same reason.
 
+import { appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { Plugin } from "@opencode-ai/plugin";
 import type { Plugin as V2Plugin } from "@opencode/plugin";
 
@@ -27,6 +29,49 @@ export {
 } from "./os-args";
 export { hygieneReport } from "./hygiene";
 
+// One-per-process unhandledRejection logger, opt-in via THATCH_DEBUG. The
+// host logs these bare ("unhandled rejection" + message, no stack), which is
+// exactly wrong for diagnosing which async continuation in the plugin
+// escaped its error handling - the dispose-race class in particular escapes
+// through several surfaces (pollers, hooks, delayed finalizers). Writes to
+// the debug log beside the database (same file createDebugLog uses), tagged
+// so a grep on "[rejection:" pulls the story out.
+//
+// Registered at module scope because rejections can fire before or after
+// setup runs, and once per process because v2 re-evaluates this module on
+// every plugin reload (a bare process.on would pile up listeners). The key
+// is a Symbol.for so the guard survives module re-evaluation in the same
+// thread; worker threads have their own globalThis and process, and one
+// logger per thread is correct anyway. Registering the listener marks the
+// rejections "handled" - suppressing the host's default crash-on-unhandled -
+// so the handler also echoes the detail to console.error to keep the
+// failure visible while diagnosing.
+const rejectionLoggerKey = Symbol.for("thatch.unhandledRejectionLogger");
+if (process.env.THATCH_DEBUG && !(globalThis as any)[rejectionLoggerKey]) {
+  const home = process.env.HOME ?? "/tmp";
+  const configHome = process.env.XDG_CONFIG_HOME ?? `${home}/.config`;
+  const dbPath = process.env.THATCH_DB_PATH ?? `${configHome}/thatch/thatch.db`;
+  // A file: URI db path has no meaningful sibling debug.log (appendFileSync
+  // cannot open "file:.../debug.log"); skip logging rather than silently
+  // drop every rejection into the catch below.
+  (globalThis as any)[rejectionLoggerKey] = !dbPath.startsWith("file:");
+  if ((globalThis as any)[rejectionLoggerKey]) {
+    const file = join(dirname(dbPath), "debug.log");
+    process.on("unhandledRejection", (reason) => {
+      const detail =
+        reason instanceof Error
+          ? `${reason.message}\n${reason.stack ?? "(no stack)"}`
+          : String(reason);
+      console.error(`[thatch] unhandled rejection: ${detail.split("\n")[0]}`);
+      try {
+        appendFileSync(file, `${new Date().toISOString()} [rejection:unhandled] ${detail}\n`);
+      } catch {
+        // Diagnostics must not break the host (same contract as debug.log).
+      }
+    });
+  }
+}
+
 // Named v1 export, preserved for the shim and tests. Lazy wrapper: never
 // evaluate the v1 adapter (and its SDK import) under a v2 host.
 export const server: Plugin = async (input, options) => (await import("./opencode/v1")).server(input, options);