@jeffober/thatch 0.2.0 → 0.2.1

package/artifacts/skills/thatch-fact-extractor.md

@@ -18,7 +18,7 @@ The extraction nudge or dispatch prompt will give you a session ID. Call `get_ex
 4. Apply the durability test before saving: will this still be true and useful in a future session that knows nothing about this branch, commit, or session? If not, skip it. Do not store point-in-time values (migration indices, line numbers, file counts), commit hashes or branch history narratives (git is the source of truth), or anything re-derivable from the codebase faster than recalling it.
 5. Write for a future session with zero current context. No "we", "our session", "just now".
 6. Call `extraction_done` (with `session_id` set to the parent session's ID from the nudge) to mark the run complete. Do this even when nothing was worth saving: the parent session holds the buffered interactions until a completion signal arrives, and a memory write is not one on a no-save run.
-7. Your final message must be exactly: "Extraction complete." — do not list or summarize what you saved. The memories are in the store; the parent session does not need a report.
+7. Your final message must be exactly: "Extraction complete. This is the extractor's final report - a background-task completion, not an extraction nudge; the buffer is drained. Never re-dispatch an extractor because a completion arrived - a new extraction nudge is the only dispatch signal." - do not list or summarize what you saved. The memories are in the store; the parent session does not need a report. The frame rides with the completion on purpose: a bare "Extraction complete." was indistinguishable from nudge traffic mid-loop, and the parent model misread it as new work (the September 2026 re-dispatch loop).
 
 ## What to extract
 

package/artifacts/skills/thatch-memory-verify.md

@@ -20,7 +20,7 @@ This skill is the catch.
 
 Call `thatch_memory_show` with the label (or accept the memory content directly if dispatched by a coordinator that already read it).
 
-Note the `created_at` and `updated_at` dates. A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
+Note the age line ("This memory was last updated N ago"). A memory that was last updated recently is less likely to be stale than one that has not been touched in months.
 
 ## Step 2: Classify Claims
 
@@ -111,6 +111,6 @@ If no corrections were needed, report "all claims verified, no updates needed."
 
 # Proactive Use
 
-When `thatch_memory_show` or `thatch_memory_recall` returns a memory with an old `updated_at` date (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The `updated_at` date is included in the memory output for this purpose.
+When `thatch_memory_show` or `thatch_memory_recall` returns a memory whose age line shows it has not been updated in a while (more than a few weeks), consider loading this skill to fact-check it before relying on its code-related claims. The age prose ("This memory was last updated N ago") is included in the memory output for this purpose.
 
 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.

package/docs/dev/README.md

@@ -127,7 +127,7 @@ methods. The v1 hook shapes:
 | `command.execute.before` | Arms the wrap-up greenlight check: `/thatch/compact` and `/thatch/exit` mark their session in `pendingWrapUp`. The next `session.status` idle resolves it by inspecting the final assistant message for the greenlight token and, when present, triggering the TUI action (`session_compact` via `executeCommand`, `app.exit` via `publish`; the exit path unregisters the session from the chat directory first). See [features/session-lifecycle.md](features/session-lifecycle.md). |
 | `experimental.compaction.autocontinue` | Clears the compacting flag so `chat.message` nudges resume. Without this, nudges that instruct tool calls would fire during summary generation where tools are blocked. The `chat.message` hook also clears the flag if it fires for a session still in the compacting set but the incoming message has no compaction-type part — this handles compaction failure, where the session would otherwise be stuck with nudges off forever. |
 | `tool.execute.after` | Buffers every non-`thatch_*`, non-`skill`, non-`task` tool call into the session's extraction buffer. (Skill/task are excluded — buffering them creates a feedback loop where the nudge triggers a skill load, which gets buffered, which triggers another nudge.) Memory writes (`thatch_memory_remember`) and `thatch_extraction_done` drain the buffer and reset the missed-nudge counter. For child sessions (`childToParent.has(sessionID)`), also tracks metrics: `remember` with `overwrite:false` → new++, `overwrite:true` → updated++, `forget` → deleted++. For `thatch_chat_*` tool calls, builds the transcript echo (`chatEchoText`) and posts it as a visible non-synthetic `noReply` part. This is a plugin hook, NOT a bus event — do not move it into the `event` handler; the event bus has no such event and it will silently never fire. |
-| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation). |
+| `chat.message` | Two priority tiers: (a) if extraction buffer has interactions and the session is NOT in the `extracting` set (direct extraction in progress), **peeks** the buffer (does NOT drain it) and injects a synthetic text part carrying the extraction nudge with the session ID and fetch tool name (not the full payload) — the sub-agent calls `thatch_get_extraction_payload` to retrieve the interactions as a tool response, keeping the full payload out of the main session's context window. The buffer persists until the agent writes a memory or calls `thatch_extraction_done`, so ignored nudges repeat and escalate (polite → insistent → ALL-CAPS) via the `missedNudges` counter; (b) otherwise, embeds the user's prompt text with the in-process warm model, searches `db.search()` across repo + global, and pushes a recall nudge if matches exceed the threshold (default 0.55). The same embedding also feeds the prediction auto-fire (`db.scorePredictionNudge`, injects `[thatch] User decision model`) and the behavior auto-fire (`db.scoreBehaviorNudge`, injects `[thatch] Situational behaviors`). All three nudges (recall, prediction, behavior) fire independently in separate try/catch blocks with separate synthetic parts. Chat transcript echoes (non-synthetic `noReply` parts whose text is entirely `[chat]`-prefixed bubbles) are skipped before any tier — no model turn reads them, so nudging them wastes an embedding. Skipped entirely while the session is compacting (tool calls are blocked during summary generation), and for task-dispatched sub-agent sessions (`childToParent` without `extractionChildren`) - their tool lists may exclude the thatch tools and their work is driven by the dispatch prompt. |
 | `event` | Subscribes to all session bus events. `session.created`: records `childToParent` + `parentSnapshots` (shallow copy of the parent's buffer for snapshot-aware drain), then sends the session-start reminder via `client.session.prompt` carrying the hygiene heartbeat (pending dedup pairs, stale count, orphaned branch memories) when any signal is non-zero. `session.status`: records the session's live status for the watcher and chat delivery gates; on idle, if the session is a child, drains its snapshot, fires a toast with `childMetrics`, and deletes the child session; if the session is a parent with pending tool interactions and not already extracting, calls `triggerExtraction` to create a direct-extraction child, then flushes pending watcher events and pending chat mail (the session just became deliverable). `session.error`: requeues the parent's buffer (child died without draining). `session.deleted`: cleans up `childToParent`, `parentSnapshots`, `childMetrics`, and `extracting`, cancels the session's watchers, and unregisters it from the chat directory (the crash path — a dead process fires no event — is covered by heartbeat staleness). `session.compacted`: clears the compacting flag so `chat.message` nudges resume. |
 | `dispose` | Stops the version checker, the watcher poller, and the chat poller, closes the DB. |
 
@@ -179,11 +179,15 @@ Two of these hooks were dead for weeks because failures were invisible.
 10. **Background completion narration is suppressed, not prevented.** When a
     background sub-agent completes, opencode injects a `<task_result>` block
     into the parent session and triggers a full model generation. Thatch
-    cannot cancel this turn (no pre-response hook). Two mitigations: the
-    fact-extractor skill's return value is constrained to the literal
-    "Extraction complete." so the injected block has no narratable content,
-    and the system prompt's "Background Task Completions" section instructs
-    the model not to narrate completions or treat them as approval to act.
+    cannot cancel this turn (no pre-response hook). The mitigations: the
+    fact-extractor skill's return value is a fixed string so the injected
+    block has nothing to narrate AND the string self-identifies as a
+    completion, not an extraction nudge (a bare "Extraction complete." was
+    misread mid-loop as new nudge traffic and re-dispatched - the September
+    2026 re-dispatch loop); the system prompt's "Background Task
+    Completions" section instructs the model not to narrate completions or
+    treat them as approval to act, and that a completion is never a
+    re-dispatch signal.
 11. **Prediction engine is a statistical model, not an LLM call.** The query
     (embed prompt, cosine-match against matchers, score linked predictions)
     is mechanical — same shape as `thatch_memory_recall` but against different
@@ -209,7 +213,7 @@ Two of these hooks were dead for weeks because failures were invisible.
 ## Data flow
 
 ```text
-thatch_memory_remember(label, content)
+thatch_memory_remember(label?, content)
   → model.passageEmbed("# label\n\ncontent") → Float32Array
   → db.findSimilar(store, embedding) — write-time collision check (no telemetry)
   → db.remember(store, label, content, embedding, model.name, opts)

package/docs/dev/features/cross-session-chat.md

@@ -191,7 +191,14 @@ rather than one so a single late poll cycle does not flap the roster.
 Heartbeat age is the ONLY liveness signal, by design. A host process id
 cannot serve: the same session is re-hosted by a new process on every
 `-s` resume, so a pid stamped on the row lies as soon as a different
-harness beats it (it says dead while the heartbeat proves alive). `isStale`
+harness beats it (it says dead while the heartbeat proves alive). RESTART
+grace: a new daemon re-hosts the dead one's hosted set under a bounded
+window (`CHAT_REHOST_GRACE_MS`, 24h, `THATCH_CHAT_REHOST_GRACE_MINUTES`
+to override) - open TUI tabs reconnect but emit no events until typed
+into, so without the grace they would read stale while alive-idle and
+mail to them would not wake the tab. Sessions that emit activity
+graduate to permanent hosting; still-silent ones (closed tabs) age out
+at the grace and go stale. `isStale`
 (src/chat.ts) is the single rule; `chatLiveness`, the `chat_send` note,
 and the broadcast skip all call it, so they cannot disagree. `chat_list`
 groups the result into Active and Stale sections - the stale section's

package/docs/dev/features/memory-store.md

@@ -58,7 +58,7 @@ The "global" store always exists — it is inserted at schema init (`INSERT OR I
 ### Write path (memory_remember)
 
 ```text
-agent calls memory_remember(label, content, opts)
+agent calls memory_remember(label?, content, opts) - label is derived from the content's first heading or line when omitted
   → model.passageEmbed("# label\n\ncontent")  →  Float32Array
   → db.findSimilar(store, embedding, { excludeSlug })  →  write-time collision check
   → db.remember(store, label, content, embedding, model.name, opts)

package/docs/dev/features/nudge-pipeline.md

@@ -49,6 +49,18 @@ not a compaction summary, compaction has already failed (the auto-continue
 never fired). Thatch clears the stale `compacting` flag and proceeds normally.
 See [compaction-recovery.md](compaction-recovery.md).
 
+#### Task sub-agent guard
+
+If the session is a child in `childToParent` but not in `extractionChildren`
+(a task-dispatched sub-agent), all nudge tiers are skipped and the hook
+returns before tier 1. Dispatched sub-agents may have restricted tool lists
+that exclude the thatch tools, and even where the tools exist the child is
+driven by its dispatch prompt, so a nudge only produces "No tool named"
+error rounds or noise. `extraction.requeueStaleAccepted()` still runs before
+the guard - it is session-independent maintenance. See
+[session-lifecycle.md](session-lifecycle.md) for the `extractionChildren`
+distinction.
+
 #### Tier 1---Extraction nudge (fallback path)
 
 Fires only when direct extraction was never triggered or threw (the session is

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,60 @@ 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.

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/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. |

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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/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);