@jeffober/thatch 0.1.44 → 0.1.45

package/README.md

@@ -51,6 +51,54 @@ thatch setup --claude --global  # or --cursor --global
 Restart your editor and thatch's tools are available as `mcp__thatch__*`.
 Requires [Bun] on PATH.
 
+The embedding model downloads once at first use. It is cached in the
+platform's per-user cache dir: `~/Library/Caches/thatch/models` on macOS (or
+`$XDG_CACHE_HOME/thatch/models` when `XDG_CACHE_HOME` is set),
+`$XDG_CACHE_HOME/thatch/models` (default `~/.cache/thatch/models`) elsewhere.
+Set `THATCH_MODEL_CACHE` to override the location. The cache survives
+upgrades and works from read-only installs.
+
+### NixOS / Nix
+
+This repo is a flake. Bun and the native embedding runtime are bundled, so no
+global `npm install` or `bun` on PATH is required.
+
+Try it without installing:
+
+```bash
+nix run github:sysread/thatch -- --version
+```
+
+Install system-wide via the NixOS module (in your flake `configuration.nix`):
+
+```nix
+{
+  inputs.thatch.url = "github:sysread/thatch";
+
+  # in your NixOS system's modules:
+  imports = [ inputs.thatch.nixosModules.default ];
+  programs.thatch.enable = true;   # puts `thatch` on PATH for every user
+}
+```
+
+Or add the package yourself with the overlay
+(`nixpkgs.overlays = [ inputs.thatch.overlays.default ];` then
+`environment.systemPackages = [ pkgs.thatch ];`), or drop
+`inputs.thatch.packages.${system}.default` into a `home.packages` /
+`environment.systemPackages` list directly.
+
+Once `thatch` is on PATH, wire it into your editor as usual:
+
+```bash
+cd /path/to/your/project
+thatch setup --claude --global   # or --cursor
+```
+
+The embedding model still downloads once at first use and is cached in the
+platform's per-user cache dir (the per-platform paths above; override with
+`THATCH_MODEL_CACHE`), so it survives upgrades and works from the read-only
+Nix store.
+
 ### Other MCP-compatible harnesses
 
 ```json
@@ -108,13 +156,17 @@ Thatch gives your agent:
   hostile message cannot impersonate your instructions. Disable the whole
   feature with `chat.enabled: false` in the thatch config (or just the
   auto-joining with `chat.autoRegister: false`).
-- **Wrap-up commands** (opencode only) -- `/thatch/compact` and `/thatch/exit`
-  run a pre-flight checklist before a compaction or an exit: the agent flushes
-  pending fact extraction, finishes promised memory writes, and surfaces
-  todos or follow-ups it never addressed. It ends its response with a
-  greenlight token only when the checklist is clean; thatch then triggers the
-  compaction or quits opencode. With items outstanding, the agent lists them
-  and nothing fires -- you decide when to retry.
+- **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
+  `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
+  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
+  the session learned) run on demand the same behaviors the nudges run on
+  their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
+  `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
+  the agent flushes pending fact extraction, finishes promised memory
+  writes, and surfaces todos or follow-ups it never addressed. It ends its
+  response with a greenlight token only when the checklist is clean; thatch
+  then triggers the compaction or quits opencode. With items outstanding,
+  the agent lists them and nothing fires -- you decide when to retry.
 - **Notifications + user config** -- the agent can ping you out-of-band when a
   long-running outcome lands: a desktop banner, a spoken voice
   announcement, or both (macOS and Linux). Preferences live in a
@@ -131,6 +183,24 @@ See the [user guide](docs/user/README.md) for the full tool list, CLI
 commands, configuration, environment variables, and detailed setup for each
 host.
 
+## What works in Claude Code
+
+The memory tools, prediction and behavior engines, conversation search via
+the `thatch session` CLI, cross-session chat (with stop-hook wake), skills,
+and the on-demand actions `/thatch/defrag`, `/thatch/hygiene`, and
+`/thatch/reflect` (synced by `thatch setup --claude`). Not available: the
+wrap-up commands and `/thatch/extract` (they need the opencode plugin's
+session identity and TUI control routes), live recall/prediction nudges
+beyond the hook-based flow, and toast notifications.
+
+## What works in Cursor
+
+The same core set as Claude Code (memory, predictions, behaviors, chat with
+stop-hook wake, skills, and the `defrag`/`hygiene`/`reflect` actions). Cursor
+has no file-based slash commands, so the actions surface through MCP prompts
+instead. Not available: the wrap-up commands, `/thatch/extract`, and toast
+notifications.
+
 ## Privacy
 
 Everything is local. The embedding model downloads once from Hugging Face Hub
@@ -152,6 +222,9 @@ bun install
 mise run check     # typecheck + bun test + markdownlint (the CI gate)
 ```
 
+On Nix, `nix develop` drops you into a shell with bun, mise, and node already
+on PATH -- no system install needed.
+
 Tests never reach outside the sandbox: temp-directory SQLite files, mock
 embeddings, no network.
 

package/bin/thatch

@@ -10,7 +10,7 @@ import { hygieneReport } from "../src/hygiene";
 import { claudeSessionStartReminder } from "../src/prompts";
 import { setupClaudeCode, setupCursor, registerClaudeMcpServer } from "../src/setup";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToTranscriptEntries, partToFullJson, messageToFullJson, type SessionPart } from "../src/session-db";
-import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
+import { chatTailDiff, chatTailBacklog, filterChatTailRows, formatChatTailJsonl, CHAT_TAIL_DEFAULT_LIMIT, parseChatTimeBound, CHAT_STALE_MS, CHAT_RENUDGE_MINUTES, chatLiveness, humanAge, splitChatRoster, sortChatRoster, mcpSessionID, isoMinutesAgo, renderChatParticipant, resolveRegisteredPredecessor, type ChatSessionRow, type ChatTailFilter } from "../src/chat";
 import { chatEnabled, loadConfig } from "../src/config";
 import { chatNotificationNudge } from "../src/prompts";
 import { createDebugLog } from "../src/debug";
@@ -49,8 +49,11 @@ function usage(): never {
                                    Full conversation as OpenAI chat-completions JSONL
   thatch session search <query> [--session <id>] [--regex] [--limit N]
                                    JSONL of matching parts across sessions (decoded content)
-  thatch chat list                 Registered chat sessions, grouped Active/Stale:
-                                   name, age, status, project, topic
+  thatch chat list [--stale N|all]  Registered chat sessions, grouped Active/Stale:
+                                    name, age, status, project, topic.
+                                    --stale N (days) hides stale sessions
+                                    older than N; default 1. --stale all
+                                    shows every stale session.
   thatch chat tail [--once] [--limit N|all] [--match RE]
                    [--from NAME] [--to NAME] [--since DT] [--until DT]
                                    Follow cross-session chat as a JSONL
@@ -412,14 +415,17 @@ const CHAT_ROSTER_HEADER = ["NAME", "AGE", "STATUS", "PROJECT", "TOPIC"];
  * an aligned-column table under a header row. Section headers are bold,
  * the stale explainer is muted italic; rows use green names, dim age,
  * green/red status, and a muted italic topic.
+ * staleCapMs bounds how old a stale row is displayed (null = no bound);
+ * rows past the cap collapse into a muted hidden-count note so the reader
+ * knows rows exist that the window left out.
  * Color is applied only when stdout is an interactive terminal (and
  * NO_COLOR is unset), so piped output - grep, redirect, QA runners - stays
  * clean plain text.
  */
-function formatChatRoster(sessions: ChatSessionRow[]): string {
+function formatChatRoster(sessions: ChatSessionRow[], staleCapMs: number | null = null): string {
   const colored = process.stdout.isTTY === true && !process.env.NO_COLOR;
   const paint = (code: string, s: string) => (colored ? `\x1b[${code}m${s}\x1b[0m` : s);
-  const { active, stale } = splitChatRoster(sessions);
+  const { active, stale, staleHidden } = splitChatRoster(sortChatRoster(sessions), Date.now(), staleCapMs);
   const renderTable = (rows: ChatSessionRow[]) => {
     const cells = (r: ChatSessionRow) => [
       r.name,
@@ -449,9 +455,21 @@ function formatChatRoster(sessions: ChatSessionRow[]): string {
   if (active.length > 0) {
     parts.push([paint("1", "# Active Sessions"), renderTable(active)].join("\n"));
   }
-  if (stale.length > 0) {
-    const explainer = `These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume.`;
-    parts.push([paint("1", "# Stale Sessions"), paint("3;90", explainer), renderTable(stale)].join("\n"));
+  if (stale.length > 0 || staleHidden > 0) {
+    const lines = [paint("1", "# Stale Sessions")];
+    if (stale.length > 0) {
+      const explainer = `These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume.`;
+      lines.push(paint("3;90", explainer), renderTable(stale));
+    }
+    if (staleHidden > 0) {
+      lines.push(
+        paint(
+          "3;90",
+          `${staleHidden} older stale session${staleHidden === 1 ? "" : "s"} hidden; --stale N widens the window to N days, --stale all shows everything.`,
+        ),
+      );
+    }
+    parts.push(lines.join("\n"));
   }
   return parts.join("\n\n");
 }
@@ -461,12 +479,26 @@ async function chatCommand(rest: string[]): Promise<void> {
 
   switch (sub) {
     case "list": {
+      // --stale N bounds how old a stale row the roster displays, in days
+      // (fractions allowed); the default of one day keeps long-dead
+      // sessions from burying the fresh signal. --stale all restores the
+      // unbounded view. A bad value dies loudly rather than silently
+      // shrinking the roster.
+      const staleArg = flagValue(restArgs, "--stale");
+      let staleCapMs: number | null = 24 * 60 * 60 * 1000;
+      if (staleArg !== undefined) {
+        if (staleArg === "all") staleCapMs = null;
+        else if (!/^\d+(\.\d+)?$/.test(staleArg) || Number(staleArg) <= 0) {
+          console.error(`error: --stale expects a positive number of days or "all", got "${staleArg}"`);
+          process.exit(1);
+        } else staleCapMs = Number(staleArg) * 24 * 60 * 60 * 1000;
+      }
       const sessions = db.listChatSessions();
       if (sessions.length === 0) {
         console.log("No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register.");
         break;
       }
-      console.log(formatChatRoster(sessions));
+      console.log(formatChatRoster(sessions, staleCapMs));
       break;
     }
 
@@ -831,6 +863,9 @@ switch (command) {
       console.log(`  Instructions:  ${result.claudeMd}`);
       console.log(`  Hooks:         ${result.settings}`);
       printSkills(result);
+      if (result.commands.length > 0) {
+        console.log(`  Commands:      ${result.commands.length} written (${result.commands.map((p) => p.split("/").pop()).join(", ")})`);
+      }
       console.log();
       if (result.mcpAddCommand) {
         // Global setup cannot write ~/.claude.json directly, so run the

package/docs/dev/README.md

@@ -24,7 +24,8 @@ Shared core
   ├── embeddings.ts   → embedding model via transformers.js
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
-  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, CLAUDE.md instructions
+  ├── prompts.ts      → system prompt, compaction, reminders, recall/prediction/behavior nudges, prompt cores, CLAUDE.md instructions
+  ├── commands.ts     → /thatch slash-command registry: actions from prompt cores + wrap-ups, per-host sync
   ├── sideband.ts     → Unix socket server + client: warm-model semantic match for hook processes
   ├── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
   ├── scoring-engine.ts → generic four-table scoring base (shared by prediction + behavior engines)
@@ -83,7 +84,8 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `chat.ts` | Cross-session chat between opencode sessions on one machine (opencode-only). `ChatStore` holds the shared directory and inbox in SQLite so any process can read/write them; `ChatPoller` heartbeats hosted sessions and delivers wake prompts through an injected callback when the recipient is idle - only the recipient's host process delivers, so there is no cross-process double-delivery. Heartbeat staleness flags crashed sessions; a per-recipient nudge rate cap is the anti-loop hard brake. See [features/cross-session-chat.md](features/cross-session-chat.md). |
 | `chat-names.ts` | The static display-name pool for the chat directory: whimsical geek-culture names in fnord's Nomenclater style, baked in so name assignment never costs a model call. The pool is the fallback base for registrations with no usable session title. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
-| `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
+| `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), watcher notification (`watcherNotificationNudge`), version warning (`versionWarningNudge`), chat wake notification (`chatNotificationNudge`), chat transcript echo text and echo recognizer (`chatEchoText` / `isChatEchoParts`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. Also the prompt cores (`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) - host-agnostic behavior instruction bodies shared by nudges and `/thatch` commands, parameterized by a `ToolNamer` for per-host tool spellings. See [features/commands.md](features/commands.md). |
+| `commands.ts` | Slash-command registry and sync. `actionDefs(tool)` renders the on-demand actions (defrag, extract, hygiene, reflect) from the prompt cores; the wrap-up commands (compact, exit) are bespoke greenlight-gated templates. Renderers produce full command files for opencode (`installOpencodeCommands`, synced by the plugin at init) and Claude Code (`installClaudeCommands`, synced by setup); `compilePrompts` in `mcp.ts` exposes the same actions as MCP prompts for Cursor. A parity-guard test pins the three sets to the documented exclusions. See [features/commands.md](features/commands.md). |
 | `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |

package/docs/dev/features/README.md

@@ -23,6 +23,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [behavior-engine.md](behavior-engine.md) | Behavior engine (LLM self-discipline rules, ham/spam, auto-fire) |
 | [hygiene.md](hygiene.md) | Hygiene system (duplicate, stale, orphaned branch signals) |
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
+| [commands.md](commands.md) | Slash commands (on-demand actions from shared prompt cores, wrap-ups, host sync) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |

package/docs/dev/features/commands.md

@@ -0,0 +1,74 @@
+# Slash commands: actions and wrap-ups
+
+Thatch's `/thatch/*` commands come in two families:
+
+- **Actions** (`defrag`, `extract`, `hygiene`, `reflect`) — user-invoked
+  wrappers around behaviors the nudges otherwise run on their own schedule.
+- **Wrap-ups** (`compact`, `exit`) — greenlight-gated pre-compaction and
+  pre-exit checklists. opencode only: the greenlight check needs the
+  plugin's `command.execute.before` arming and TUI control routes.
+
+User-facing guide: [../../user/commands.md](../../user/commands.md).
+
+## Prompt cores
+
+Action bodies are **prompt cores**: constants in `src/prompts.ts`
+(`defragCore`, `hygieneCore`, `reflectCore`, `extractionCore`) that hold the
+host-agnostic instruction text for one behavior. The nudge envelopes wrap
+the same cores with escalation tiers and the stop-and-wait ending; command
+and prompt renderers wrap them with frontmatter and a user-message section.
+The point is drift-proofing: a wording change lands in the nudge and the
+command at once, and a test asserts each rendered file contains its core
+verbatim.
+
+The stop-and-wait ending ("do not advance pending work on this nudge's
+account") is nudge-only by design. A `/thatch` command IS user input, so
+the command envelope must not inherit it.
+
+Cores that name memory tools take a `ToolNamer` because spellings differ
+per host: `thatch_find_duplicates` on opencode, `mcp__thatch__find_duplicates`
+on MCP hosts. Each host's renderer passes its own namer
+(`opencodeToolName` / `mcpToolName`).
+
+## Rendering and sync
+
+`src/commands.ts` is the single registry:
+
+- `actionDefs(tool)` returns the action set with bodies rendered for one
+  host. Actions needing plugin-only capabilities are marked `opencodeOnly`
+  (`extract`: needs session identity via `get_session_info`).
+- `opencodeCommandDefs()` = wrap-up templates + all actions. Synced by the
+  plugin at init into `$XDG_CONFIG_HOME/opencode/command/thatch/`
+  (`installOpencodeCommands`), content-compare, self-healing.
+- `claudeCommandDefs()` = actions minus `opencodeOnly`. Synced by
+  `thatch setup --claude` (`installClaudeCommands`) into
+  `<claudeDir>/commands/thatch/`, reported in the setup output. There is no
+  plugin on this host to sync on load, so setup is the sync point.
+- MCP prompts: `compilePrompts()` in `src/mcp.ts` exposes the same
+  non-opencodeOnly actions through `prompts/list` / `prompts/get`, which
+  Cursor surfaces as slash commands. The optional `focus` argument is
+  appended to the body as a `Focus:` line, standing in for the file
+  commands' `$ARGUMENTS`.
+
+A parity-guard test asserts the three sets are the same actions minus the
+documented exclusions: opencode = Claude Code set + `compact`, `exit`,
+`extract`; MCP prompts = Claude Code's set.
+
+## The extract action and session IDs
+
+`/thatch/extract` runs the extraction flow on demand: learn the session ID
+from `thatch_get_session_info`, dispatch the extractor sub-agent with an
+explicit `session_id`, acknowledge with `thatch_extraction_done`. The
+explicit ID matters because the sub-agent's session differs from the
+parent's — the same reason the extraction nudge passes it.
+
+`get_extraction_payload` accepts an omitted `session_id`: on the opencode
+path the wrapper supplies the invoking session's `HostToolContext.sessionID`.
+The zod arg shape is shared between hosts, so optionality cannot be
+per-host at the schema level; on MCP hosts (no session context) an omitted
+`session_id` returns a clear "pass the parent's session_id" error. The rule
+the model applies, stated in the arg descriptions and the dev docs:
+
+> Omit `session_id` when acting on the session you are running in. Pass the
+> parent session's `session_id` when running inside a sub-agent dispatched
+> to process another session's extraction queue.

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

@@ -58,10 +58,13 @@ outlives a process, so liveness needs a signal beyond process lifetime.
 
 ### Registration and identity
 
-Sessions are auto-registered by the plugin: the first `session.status`
-idle event for a top-level session inserts its directory row, and a
-session continued via `-s <id>` registers at harness start (below);
-both paths are skipped when `chat.autoRegister: false` or when the
+Sessions are auto-registered by the plugin: a top-level session's first
+real user message inserts its directory row (the `chat.message` hook,
+which fires before the model runs - so the session is addressable within
+its very first turn), and the first `session.status` idle event remains a
+backstop that also converges the topic once the auto-titler lands. A
+session continued via `-s <id>` or `-c` registers at harness start
+(below). All paths are skipped when `chat.autoRegister: false` or when the
 session left explicitly (a leave tombstone, see below). Names are assigned, never
 claimed: a pool draw (`CHAT_NAME_POOL`, src/chat-names.ts) plus a
 per-base counter row (`chat_name_counters`, src/db.ts) that only ever
@@ -94,9 +97,14 @@ args=` on macOS) and parses `-s`/`--session` from that.
 Registration is keyed by session id: the row already exists, so the name
 is RECLAIMED (names are owned by the session id, minted once, never
 renamed) and the row's heartbeat is refreshed - hosting is the
-heartbeat, so the serving harness beats and delivers for the row again. `-c/--continue` resolves no id on the
-command line; that
-session registers on its first idle like any other. Asleep-mail: the
+heartbeat, so the serving harness beats and delivers for the row again.
+`-c/--continue` resolves no id on the command line, so the plugin
+resolves the same target the harness does: `client.session.list()`
+(directory-scoped, the plugin's client carries the directory), sorted by
+`time.updated` descending like the TUI does, first row without a
+`parentID`. That registration is not synchronous at init (the list call
+is a server round trip), but it lands within a beat of startup - the
+heartbeat is live long before the first prompt. Asleep-mail: the
 startup path kicks a delivery pass when it finishes, so the continued
 session learns what it missed at startup instead of waiting out the
 first poll cycle.
@@ -118,8 +126,8 @@ publishing `app.exit`, so the roster stops advertising a host that is
 about to vanish; the exit template's checklist step asks the model to do
 the same earlier) - writes a
 `chat_leave_tombstones` row in the same transaction that deletes the
-directory row. The tombstone is what makes a leave stick: both
-registration paths consult it (the plugin's idle auto-registerer is
+directory row. The tombstone is what makes a leave stick: all
+registration paths consult it (the plugin's idle and prompt auto-registerers are
 suppressed outright; the MCP hook's ensure-register prints the leave line
 instead of rejoining), so a leave cannot be silently undone by the next
 idle moment. The gate lives in `ChatStore.register` via `#tombstoneGate`
@@ -187,7 +195,13 @@ 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
 explainer says what stale means - and `chat_send` states the recipient's
 liveness at send time, so a sender mailing a ghost learns it immediately
-instead of waiting on a wake that will never fire.
+instead of waiting on a wake that will never fire. Both roster surfaces
+order rows with `sortChatRoster` (also src/chat.ts): project first,
+alphabetical, with no-project rows last; most recently seen first within
+a project. The CLI roster bounds
+the stale display to one day by default (`--stale N` in days, `--stale all`
+unbounded), collapsing older rows into a hidden-count note; the tool
+surface stays unbounded so an agent always sees the full directory.
 `session.deleted` is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap

package/docs/dev/features/extraction.md

@@ -197,6 +197,11 @@ continues working while the child extracts.
 - **opencode**: peeks accepted + pending interactions, builds JSON via
   `buildExtractionPayload`
 - **MCP**: peeks the file-backed queue, builds the same JSON payload
+- `session_id` is optional: omitted, it resolves to the invoking session
+  via `HostToolContext.sessionID` (opencode path). On MCP hosts there is no
+  session context, so an omitted `session_id` returns a "pass the parent
+  session's session_id" error. Explicit IDs always win - that is how a
+  sub-agent drains the parent's queue
 - Returns `null` when no interactions are queued
 - Read-only — it peeks the queue; it does not consume it. Consumption is
   `extraction_done`'s job

package/docs/dev/gotchas.md

@@ -146,6 +146,14 @@ here first. These are the things that have already cost time.
 - **The binary path is baked into installed hook commands.** `thatch setup`
   resolves `<bin>` from PATH (or the script's absolute path) and writes it into
   every hook command, so hooks survive after the setup session ends.
+- **Tool-arg optionality cannot be per-host at the schema level.** The zod
+  arg shape in `TOOL_DEFS` is shared by the opencode plugin and the MCP
+  server, so making an arg optional (e.g. `get_extraction_payload`'s
+  `session_id`) makes it optional everywhere. Per-host enforcement has to
+  happen in the tool's `execute`: fall back to `HostToolContext.sessionID`
+  on the opencode path, return a "pass the parent's session_id" error on
+  MCP hosts, which have no session context. See
+  [features/commands.md](features/commands.md).
 
 ## Tests
 

package/docs/dev/mcp-parity.md

@@ -23,6 +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 |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **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 |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |

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

@@ -50,10 +50,12 @@ the TUI is not connected (headless mode).
 | Instructions | `CLAUDE.md` (idempotent `appendBlock`) | `$CLAUDE_CONFIG_DIR/CLAUDE.md` |
 | Hooks | `.claude/settings.json` | `$CLAUDE_CONFIG_DIR/settings.json` |
 | Skills | `.claude/skills/` (in the repo) | `$CLAUDE_CONFIG_DIR/skills/` |
+| Commands | `.claude/commands/thatch/` (in the repo) | `$CLAUDE_CONFIG_DIR/commands/thatch/` |
 
 `CLAUDE_CONFIG_DIR` overrides the default `~/.claude` for all user-scoped
 paths. Project-local keeps everything in the repo: `.mcp.json`, `CLAUDE.md`,
-`.claude/settings.json`, and `.claude/skills/` (so skills version with the
+`.claude/settings.json`, `.claude/skills/`, and `.claude/commands/thatch/`
+(so skills and commands version with the
 project and every contributor gets them).
 
 ### Hook events (nested `settings.json`)

package/docs/plans/thatch-actions.md

@@ -66,6 +66,12 @@ substitution, matching the existing systemPrompt/mcpInstructions convention.
 The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
 becomes a core reused by both templates (already true via `sharedChecklist`).
 
+`/thatch/extract` interacts with opencode's direct extraction (parent idle
+spawns the extractor child; the nudge is only a fallback). The action must
+reuse the same accept/complete semantics and must not fight the `extracting`
+set: if direct extraction is already running for the session, the action
+should report that and stop rather than double-dispatch.
+
 ## Host parity
 
 Commands are markdown or MCP prompts, synced per host. Behavior parity is the
@@ -74,30 +80,52 @@ goal; format differences are documented, not hidden.
 - **opencode** (existing): `installOpencodeCommands` syncs markdown to
   `~/.config/opencode/command/thatch/` on every plugin load.
 - **Claude Code**: native user-level slash commands read markdown from
-  `~/.claude/commands/thatch/` with the same `$ARGUMENTS` substitution.
-  `thatch setup --claude` gains a sync step (idempotent content-compare, same
-  as the opencode installer). Differences: no plugin, so no
+  `~/.claude/commands/thatch/` (user scope) or `.claude/commands/thatch/`
+  (project scope), with the same `$ARGUMENTS` substitution. The sync lives in
+  `setup.ts` alongside the existing installers and follows their patterns:
+  idempotent content-compare like `installSkills`, both global and local
+  scopes, reported in the setup output next to the skills report.
+  (Deviation from the draft below: no `checkSetup` entry. That function
+  answers one question - "is thatch set up at all" - and command files
+  self-heal on every setup run, so flagging their absence as a startup
+  warning would be noise.) Differences: no plugin, so no
   `command.execute.before` arming -- greenlight-token wrap-up commands do not
-  ship to Claude Code; and tool names use the `mcp__thatch__` prefix.
+  ship to Claude Code; and tool names use the `mcp__thatch__` prefix. MCP
+  hosts do have hooks now (session-start reminders, chat-wake stop hooks), so
+  hook wiring is not the barrier; the missing piece is only the plugin's TUI
+  control routes.
 - **Cursor**: no file-based commands. The stdio MCP server (`mcp.ts`) gains
   MCP Prompts support (`prompts/list`, `prompts/get`), which Cursor surfaces
-  as slash commands. Prompt arguments use MCP's
+  as slash commands. The dispatch switch currently handles `initialize`,
+  `tools/list`, `tools/call`, and `ping`; prompts get a `compileTools`-style
+  `compilePrompts()` and two new cases. Prompt arguments use MCP's
   `{{argument}}`-style templating, so each action core gets an MCP-prompt
   rendering alongside the markdown rendering.
 
 README gains "What works in Claude Code" and "What works in Cursor" sections
-listing per-host support without restating the shared docs.
+listing per-host support without restating the shared docs. The parity matrix
+in `docs/dev/mcp-parity.md` gets an Actions row next to the existing
+Wrap-up commands row.
 
 ## Session ID plumbing
 
-`get_extraction_payload` and `extraction_done` take `session_id`. Today the
-nudge carries the ID; an action has no way to know it.
+Since the plan was drafted, `HostToolContext` (tool-defs.ts) landed: every
+tool's `execute` receives the invoking session's ID as a third parameter on
+the opencode path, and the watch tools already consume it. `extraction_done`
+also already has the optional `session_id` with the omit-vs-parent rule in
+its description. The remaining work is narrower than first planned:
+
+- `get_extraction_payload`: `session_id` becomes optional. `execute` uses
+  `args.session_id ?? host?.sessionID`. On the opencode path the wrapper
+  supplies the invoking session, so omitted means "this session."
+- MCP path: the host context is omitted (no session concept), so an omitted
+  `session_id` returns a clear error telling the model to pass the parent
+  session's ID from the extraction nudge.
 
-- opencode path: the thin wrappers in `tools.ts` receive the invoking
-  session's ID from the host. `session_id` becomes optional there; omitted
-  means "the current session."
-- MCP path: there is no session context in a tool call, so `session_id`
-  stays required. The tool description and docs state this plainly.
+One wrinkle to document: the zod arg shape is shared between hosts, so
+optionality is global -- you cannot make the arg required on MCP and optional
+on opencode at the schema level. Enforcement happens in `execute` per host,
+and the arg description must carry the rule so the model self-corrects.
 
 The rule the LLM must apply, stated everywhere the tools are described:
 
@@ -105,10 +133,10 @@ The rule the LLM must apply, stated everywhere the tools are described:
 > parent session's `session_id` when running inside a sub-agent that was
 > dispatched to process another session's extraction queue.
 
-This rule appears in: the tool descriptions in `tool-defs.ts`, the extraction
+This rule appears in: the arg descriptions in `tool-defs.ts`, the extraction
 prompt core (used by both nudge and action envelopes), the fact-extractor
-skill, and the dev docs. Tests cover both paths: omit-resolves-to-current and
-explicit-parent-ID (the existing sub-agent drain bug's regression path).
+skill, and the dev docs. Tests cover both paths: omit-resolves-to-current
+and explicit-parent-ID (the existing sub-agent drain bug's regression path).
 
 ## Decisions
 
@@ -127,18 +155,25 @@ explicit-parent-ID (the existing sub-agent drain bug's regression path).
 - `tests/commands.test.ts` (or the existing plugin tests): command-file
   content assertions per host, including that each action's markdown contains
   its core text verbatim.
+- Claude setup tests: command sync writes, updates only on content change,
+  and `checkSetup` flags a missing or stale command file.
 - MCP tests: `prompts/list` returns every action; `prompts/get` interpolates
-  arguments.
-- Plugin tests: `get_extraction_payload` without `session_id` resolves to the
-  invoking session; with an explicit parent ID, drains the parent's queue.
+  arguments; an omitted-session-ID `get_extraction_payload` call errors with
+  the pass-the-parent-ID message (no host context on the MCP path).
+- Plugin tests: `get_extraction_payload` without `session_id` resolves via
+  the host context to the invoking session; with an explicit parent ID,
+  drains the parent's queue (the existing sub-agent drain bug's regression
+  path).
 - Parity guard: a test asserts every opencode command def has a
   corresponding MCP prompt (and vice versa) except the documented exclusions
   (wrap-up greenlight commands on non-opencode hosts).
 
 ## Docs
 
-- `docs/dev/commands.md` (two-tier: dev doc + user-facing README section):
+- `docs/dev/features/commands.md` and `docs/user/commands.md` (two-tier):
   action list, host parity matrix, session ID rule.
+- `docs/dev/mcp-parity.md`: Actions row in the parity matrix; revisit the
+  Wrap-up commands row if greenlight arming ever lands on MCP hosts.
 - README: "What works in Claude Code" / "What works in Cursor" sections.
 - QA use cases: one auto use case for `/thatch/defrag` end-to-end, one for
   `/thatch/extract` with omitted session ID.

package/docs/user/README.md

@@ -19,6 +19,7 @@ This README is the overview. Each feature has its own guide:
 - [default-behaviors.md](default-behaviors.md): what ships automatically
 - [hygiene.md](hygiene.md): store maintenance signals
 - [deduplication.md](deduplication.md): duplicate detection and resolution
+- [commands.md](commands.md): `/thatch/*` slash commands (on-demand actions and wrap-ups)
 - [skills.md](skills.md): structured workflow skills
 - [code-review.md](code-review.md): multi-agent code review pipeline
 - [setup.md](setup.md): installation and configuration
@@ -242,7 +243,10 @@ Beyond the tools, thatch hooks into opencode itself:
   agent listed, and you re-run the command once they're handled. Text typed
   after the command reaches the agent first, labeled as a `User Message`
   section ahead of the checklist (say goodbye or hand off context:
-  `/thatch/exit Good work - see you tomorrow`).
+  `/thatch/exit Good work - see you tomorrow`). Alongside the wrap-ups,
+  on-demand actions (`/thatch/defrag`, `/thatch/extract`, `/thatch/hygiene`,
+  `/thatch/reflect`) run the memory-maintenance behaviors whenever you want,
+  not just when a nudge fires -- see [commands.md](commands.md).
   A greenlit `/thatch/exit` also unregisters the session from the chat
   directory, so other sessions stop sending it mail. The commands
   self-install into `~/.config/opencode/command/thatch/` at plugin startup;