@jeffober/thatch 0.1.43 → 0.1.44

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

@@ -43,8 +43,9 @@ The split:
   Concurrent access is the already-solved case - multiple sessions share the
   DB for memories today, under WAL plus a busy timeout.
 - **Delivery is local.** Each process polls the inbox for messages addressed
-  to sessions it hosts (those it has seen `session.status` events for) and
-  prompts them through its own SDK client. A sender never prompts a session
+  to sessions it hosts (those it has seen `session.status` events for,
+  plus the `-s` startup session) and prompts them through its own SDK
+  client. A sender never prompts a session
   in another process.
 
 This preserves the watcher rationale's core property - no process prompts a
@@ -58,18 +59,21 @@ 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 (unless
-`chat.autoRegister: false`). Names are assigned, never claimed:
-`<slug>-<counter>` where the slug is the session title lowercased and
-hyphenated (pool-draw slug when the title is still opencode's placeholder)
-and the counter comes from a per-base counter row
-(`chat_name_counters`, src/db.ts) that only ever increments - drawn
-atomically via INSERT ... ON CONFLICT ... RETURNING. A name is therefore
+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
+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
+increments - drawn atomically via INSERT ... ON CONFLICT ... RETURNING.
+Pool names are deliberately short: they appear in every wake prompt and
+roster line, and the session's descriptive identity lives in the topic
+column instead (the live session title, refreshed on every idle by
+`refreshAutoTopic` - auto rows only; legacy rows keep their old model-set
+topics; placeholder titles never become topics or names). A name is
 minted exactly once per machine: pruning an auto-registered row (host
 silent for CHAT_AUTO_TTL_DAYS = 7 days, swept hourly by the poller) can
-never reissue its name, which is what makes the prune safe. The session's
-live title rides the topic column, refreshed on every idle by
-`refreshAutoTopic` - auto rows only; legacy rows keep their old model-set topics.
+never reissue its name, which is what makes the prune safe.
 Registration also captures the checkout kind (`worktree` column):
 `detectWorktreeKind` (src/git.ts) classifies the session's serving
 directory once at registration - a `.git` file means a linked git
@@ -77,6 +81,26 @@ worktree, a `.git` directory means the project root, no `.git` reads as
 undetected. The roster shows it as a `loc:` token so sessions coordinating
 on a shared tree can tell who sits where.
 
+### Startup registration and reclaim
+
+A session continued via `opencode -s <id>` gets no event when it comes
+back up (resume writes nothing session-scoped), so the plugin reads the
+session id from the harness's command line at init and registers it then.
+The plugin does not see the CLI flags in `process.argv`: opencode hosts
+the server in a worker thread whose argv is just the worker script. The
+thread shares the process pid, so the plugin reads the OS-level command
+line for its own pid instead (`/proc/self/cmdline` on Linux, `ps -o
+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
+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.
+
 `chat_register` (no arguments) is the explicit path: idempotent ensure for
 opencode (identity is the host session ID, which the model cannot know or
 forge), a fresh identity per conversation on MCP hosts, or a reclaim of an
@@ -146,14 +170,25 @@ behavior drastically on a parameter value is two functions.
 
 ### Polling, heartbeat, staleness
 
-A `setInterval` loop (default 30s) runs one cycle per process: heartbeat the
-hosted sessions' `last_seen`, then deliver. A crashed process fires no
-`session.deleted`, so `chat_list` marks sessions whose `last_seen` is older
-than the staleness threshold (default 10 minutes) as stale rather than
-hiding them - the operator decides what to do with ghosts. Each roster row
-also renders a human-readable `last seen <age>` (shared `humanAge` helper,
-src/chat.ts, same wording the CLI roster's AGE column uses). `session.deleted`
-is the graceful-exit fast path that unregisters immediately.
+A `setInterval` loop (default 30s) runs one cycle per process: heartbeat
+the HOSTED sessions (those seen as events in this harness plus the `-s`
+startup session - idle sessions keep beating, so a session stays fresh
+while its harness lives), then deliver their mail. A crashed process
+fires no `session.deleted`, so its rows would linger - staleness catches
+them: a row that has missed two consecutive beats (`CHAT_STALE_MS`, 60s
+at the default interval) is stale, meaning its harness stopped. Two beats
+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`
+(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
+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.
+`session.deleted` is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap
 
@@ -222,19 +257,19 @@ injection-hygiene layers.
 The user watches the conversation without an agent: `thatch chat list`
 renders the roster as aligned columns under a header row (TTY-gated
 color; `formatChatRoster()` in `bin/thatch`), and `thatch chat tail`
-follows the message stream as cards, with sent bodies rendered as
-markdown on a TTY via `glow`/`gum` (plain fallback, never in pipes).
-The backlog renders only the
+follows the message stream as JSONL: one event per line, `sent` and
+`read` as separate events linked by message id, bodies verbatim.
+The backlog prints only the
 last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages via `chatTailBacklog()`;
 `filterChatTailRows()` narrows every feed snapshot (backlog and follow
 polls alike) by body regexes, participant-name substrings, and a
 half-open time window. The diff itself is `chatTailDiff()` (unit-tested
-in `tests/chat.test.ts`): sent cards on first view, then new sends and
+in `tests/chat.test.ts`): sent events on first view, then new sends and
 newly-read messages per poll, with the diff state seeded from the full
 feed so neither the limit nor a mid-follow rename/unregister can
 resurface old rows as sent events. `chat_messages.via_broadcast` marks
-fan-out rows so the tail renders one `-> broadcast` card per recipient
-instead of what would otherwise look like identical direct sends. The
+fan-out rows so each copy's `sent` event carries `broadcast: true`
+alongside its real recipient. The
 CLI takes no chat write actions (the wake machinery owns those paths);
 the only writes it can trigger are the schema migrations that run
 whenever any thatch process opens the database.
@@ -257,7 +292,8 @@ whenever any thatch process opens the database.
 - Multi-host ([multi-host.md](multi-host.md)): the chat tools are shared -
   MCP hosts get their identity from the thatch hook, which ensure-registers
   the conversation's stable session ID (`mcp_<hash of host session id>`)
-  and prints the assigned name plus unread count on every prompt; chat
+  and prints the assigned name plus unread count at session start and on
+  every prompt; chat
   tools take that name as `as`. Wake-up delivery remains opencode-only: no
   MCP server can start a turn in the client's conversation.
 
@@ -278,53 +314,86 @@ inbox, and MCP hosts cannot hold connections across turns, so both
 degenerate to the turn-granularity polling the tools already provide. The
 wake analog is the existing hook channel.
 
-| Host        | Send/receive | New-mail signal              | Echo bubbles |
-|-------------|--------------|------------------------------|--------------|
-| opencode    | yes          | promptAsync wake (idle-gated)| yes          |
-| claude code | yes          | flush-tools hook line        | no           |
-| cursor      | yes          | flush-tools hook line        | no           |
+| Host        | Send/receive | New-mail signal                                        | Echo bubbles |
+|-------------|--------------|--------------------------------------------------------|--------------|
+| opencode    | yes          | promptAsync wake (idle-gated)                          | yes          |
+| claude code | yes          | Stop-hook reminder at turn end + flush-tools hook line | no           |
+| cursor      | yes          | flush-tools hook line + chat-notify follow-up at turn end | no        |
 
 MCP identity is anchored by the host hook: `chatHookLine(sessionID)` in
-`bin/thatch` ensure-registers `mcp_<sha256(host session id)[0:12]>` on
-every prompt and prints the assigned name plus unread count, so the
+`bin/thatch` ensure-registers `mcp_<sha256(host session id)[0:12]>` at
+session start (the reminder reads the hook's stdin) and on every prompt,
+and prints the assigned name plus unread count, so the
 identity is stable across the ephemeral conversations those harnesses run
 (and a conversation without the hook gets a fresh per-conversation
 identity from `chat_register`). `chat_status` is the quiet check
+
+**Anti-spoofing layer (Claude Code).** MCP tool calls carry no session
+context, so without help the caller-claimed `as` would be the only
+identity source. On Claude Code the hooks record `(parent pid -> session)`
+into `chat_host_pids` from payloads the model cannot influence, and the
+MCP server - a child of the same Claude Code process - resolves its own
+parent pid against that table (`chatDerivedIdentity` on CoreContext,
+freshness-capped at 600s to bound pid reuse). A second model-proof layer
+is `CLAUDE_CODE_SESSION_ID`, which the host sets in the stdio server's
+environment at spawn. `resolveChatIdentity` priority: opencode host
+context > ppid mapping > env id > claimed `as`. Cursor's hooks and MCP
+servers share one workspace process (ambiguous ppid, no per-session env),
+so Cursor keeps the claimed-`as` path, documented in the user doc's
+security model.
+
+**Continuation adoption (Claude Code).** Claude Code forks the session id
+on resume - and has been observed to fork spontaneously (agent-team
+conversion, self-update, config reload) - which would strand the old
+identity and mailbox. When a hook registers an UNKNOWN session id,
+`resolveRegisteredPredecessor` reads the hook's `transcript_path` and
+scans sibling transcripts' tails for a `continued-in` record naming the
+new id (the chain walk adopts the nearest registered ancestor, bounded at
+10 hops); `ChatStore.continueSession` then migrates the old row's key to
+the new session id - name, mail (sender and recipient columns),
+host-pid anchors, and leave tombstones all follow.
+
+`chat_status` is the quiet check
 (registered flag + pending/total); the flush-tools hook line names the
 caller's identity and mailbox, and is absent entirely when chat is
 disabled - absence is silent by construction.
-Staleness semantics differ by kind: an opencode row's stale age means the
-process is gone (broadcast skips it), while an mcp row's age only means
+Staleness semantics differ by kind: an opencode row's stale age means its
+harness stopped beating (broadcast skips it), while an mcp row's age only means
 "between turns" (broadcast always delivers).
 
 ## Defaults
 
 Timing constants live in `src/chat.ts`: poll interval 30s, staleness
-threshold 10 minutes, re-nudge window 15 minutes, nudge cap 6 per recipient
+threshold two missed beats (60s), re-nudge window 15 minutes, nudge cap 6 per recipient
 per hour, auto-row TTL 7 days. There are no environment overrides yet; add
 them the way `THATCH_WATCH_POLL_SECONDS` works if a user needs them.
 
 ## Source files
 
 - `src/chat.ts` - ChatStore (directory + inbox SQL, assigned-name draw:
-  slugify, counter bump, insert, prune, topic refresh), ChatPoller
+  pool pick, slugify, counter bump, insert, prune, topic refresh), ChatPoller
   (heartbeat, gated delivery, re-nudge, rate cap, hourly prune sweep),
   staleness helper
 - `src/chat-names.ts` - the static display-name pool (nomenclater style),
-  the fallback base for title-less registrations
+  the base for every assigned name
 - `src/db.ts` - the chat tables in schema init (including
   chat_name_counters and the auto column), the NOCASE collation migration
   and topic column migration, delegated methods
 - `src/tool-defs.ts` - the chat tool definitions
-- `src/index.ts` - poller construction, delivery closure, idle
+- `src/index.ts` - poller construction, delivery closure, `-s` startup
+  registration (`osProcessArgs`, `startupSessionId`), idle
   auto-registration + topic refresh, idle flush,
   session.deleted unregister, dispose, transcript echo in
   tool.execute.after
+- `src/debug.ts` - the `THATCH_DEBUG` diagnostic log; `chat:startup` is
+  the chat consumer
 - `src/prompts.ts` - `chatNotificationNudge()`, `chatEchoText()` /
   `isChatEchoParts()`, system prompt Cross-Session Chat section, MCP
   absent-tools note
-- `tests/chat.test.ts` - store, pool, migration, echo-text, and poller unit
-  tests (temp-dir SQLite, injected delivery)
+- `tests/chat.test.ts` - store, pool, migration, echo-text, liveness, tail
+  diff/backlog, and poller unit tests (temp-dir SQLite, injected delivery)
 - `tests/qa/auto/uc-097-chat.ts` - full lifecycle against a mocked poller
+- `tests/qa/auto/uc-099-chat-cli.ts` - `chat list` roster and `chat tail`
+  JSONL contract over a seeded DB
 - `tests/qa/live/uc-098-chat-cross-session.ts` - two real sessions exchange
   a message through the shared DB

package/docs/dev/features/database.md

@@ -224,8 +224,11 @@ chat_sessions(
   name TEXT NOT NULL UNIQUE COLLATE NOCASE,
   topic TEXT,
   project TEXT,
+  host_kind TEXT NOT NULL DEFAULT 'opencode',
   registered_at TEXT NOT NULL,
-  last_seen TEXT NOT NULL
+  last_seen TEXT NOT NULL,
+  auto INTEGER NOT NULL DEFAULT 0,
+  worktree TEXT NOT NULL DEFAULT ''
 )
 ```
 
@@ -252,8 +255,9 @@ chat_messages(
 
 - `delivered_at` is the last wake-prompt stamp (restamped on re-nudges);
   `read_at` is set when the recipient drains its inbox. `via_broadcast`
-  marks rows a chat_broadcast fan-out created (the CLI tail renders them
-  as `-> broadcast`). The endpoints are
+  marks rows a chat_broadcast fan-out created (the CLI tail's `sent`
+  events carry it as `broadcast: true` beside the real recipient). The
+  endpoints are
   plain columns, not foreign keys: unregistering a session must not be
   blocked by message history, and a departed sender degrades to an unknown
   name in the reader's view.

package/docs/dev/features/multi-host.md

@@ -190,7 +190,7 @@ behavior, with some features having no MCP counterpart.
 | `get_session_info` (session identity) | Yes | No | No |
 | `session_search` / `session_get` (conversation archaeology) | Yes (tools) | CLI only (`thatch session ...`) | CLI only (`thatch session ...`) |
 | `watch_*` (PR, branch, and command watchers) | Yes (tools) | No | No |
-| `chat_*` (cross-session chat) | Yes | No | No |
+| `chat_*` (cross-session chat) | Yes (wake on delivery) | Yes (mail at prompt time) | Yes (mail at prompt time) |
 
 For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
 

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

@@ -63,7 +63,7 @@ When a parent session (no parentID) goes idle:
 
 ### Wrap-up commands (`/thatch/compact`, `/thatch/exit`)
 
-User-invoked slash commands, shipped as command markdown synced by the plugin (see `src/commands.ts`). The template instructs the model to flush pending fact extraction (`thatch_get_extraction_payload` + `thatch_extraction_done`), finish promised memory writes, and surface unaddressed todos -- then end its response with a greenlight token (`THATCH_COMPACT_READY` / `THATCH_EXIT_READY`) only when safe to proceed. Text typed after the command is forwarded into the prompt: the templates substitute opencode's `$ARGUMENTS` ahead of the checklist, so `/thatch/exit nice work` reads as "nice work" followed by the wrap-up instructions.
+User-invoked slash commands, shipped as command markdown synced by the plugin (see `src/commands.ts`). The template instructs the model to flush pending fact extraction (`thatch_get_extraction_payload` + `thatch_extraction_done`), finish promised memory writes, and surface unaddressed todos -- then end its response with a greenlight token (`THATCH_COMPACT_READY` / `THATCH_EXIT_READY`) only when safe to proceed. Text typed after the command is forwarded into a labeled `# User Message` section ahead of the `# Pre-*-wrap-up` checklist section (opencode's `$ARGUMENTS` substitution): the headers give the user's words provenance, so they cannot be misread as part of the wrap-up instructions. opencode's substitution is purely mechanical with no default-value form (verified against v1.18.30), so the template cannot switch on emptiness; instead the section always carries a fallback line telling the model to treat an empty section as n/a (bare command, no user text).
 
 1. `command.execute.before` arms the session in `pendingWrapUp` when the command runs
 2. On the session's next idle, the plugin fetches the session's messages via the SDK client and checks the final assistant message's trailing text for the token (trimmed, exact match)

package/docs/dev/gotchas.md

@@ -176,3 +176,15 @@ here first. These are the things that have already cost time.
   discovered by bun on their own. UC-095 sat out of the suite for a release
   cycle and rotted (asserted 3 watch tools when 4 existed) because nobody
   noticed it never ran.
+
+## Instruction-block markers must be sentinels, not prose
+
+The thatch instructions block in `CLAUDE.md` / `AGENTS.md` is delimited by
+`<!-- thatch:begin -->` / `<!-- thatch:end -->` (src/setup.ts). Before
+September 2026 the delimiters were prose sentences from the instructions
+themselves - and agents edit those files. An editing agent normalized
+punctuation (hyphens to em dashes) in both of Jeff's instruction files, the
+prose end marker stopped matching, and setup could never update the block
+again while `checkSetup` reported `markers-broken` on every session. Rule:
+never use file content as its own delimiter; agents will reword it. The
+legacy-prose detection constants exist only to migrate old installs.

package/docs/dev/mcp-parity.md

@@ -144,6 +144,7 @@ Claude Code / Cursor session
 ├── PostToolBatch → thatch buffer-batch (Claude Code)
 │   └── postToolUse → thatch buffer-tool (Cursor)
 └── SessionStart / sessionStart hook → thatch reminder [--json]
+    └── reads the hook's stdin session id: chat identity + mail line
 ```
 
 The socket path is derived from a SHA-256 hash of the DB path — both the MCP

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

@@ -63,16 +63,18 @@ project and every contributor gets them).
   "hooks": {
     "SessionStart":     { "hooks": [{ "type": "command", "command": "<bin> reminder" }] },
     "PostToolBatch":    { "hooks": [{ "type": "command", "command": "<bin> buffer-batch" }] },
-    "UserPromptSubmit": { "hooks": [{ "type": "command", "command": "<bin> flush-tools" }] }
+    "UserPromptSubmit": { "hooks": [{ "type": "command", "command": "<bin> flush-tools" }] },
+    "Stop":             { "hooks": [{ "type": "command", "command": "<bin> chat-notify" }] }
   }
 }
 ```
 
 | Event | Command | Output | Role |
 |-------|---------|--------|------|
-| `SessionStart` | `thatch reminder` | plain text to stdout (becomes context) | Recall instructions + hygiene heartbeat |
+| `SessionStart` | `thatch reminder` | plain text to stdout (becomes context) | Recall instructions + hygiene heartbeat + chat identity/mail line (reads the hook's stdin `session_id`) |
 | `PostToolBatch` | `thatch buffer-batch` | **silent** (no stdout) | Appends a batch of tool calls to the file-backed JSONL queue |
 | `UserPromptSubmit` | `thatch flush-tools` | nudge text to stdout | Peeks queue (extraction nudge), else fires recall, prediction, and behavior nudges via sideband in parallel, else write nudge |
+| `Stop` | `thatch chat-notify` | `{ hookSpecificOutput: { additionalContext } }` when chat mail is unread, else `{}` | Post-turn chat wake: the turn continues so the model reads its mail (Claude Code's analog of opencode's poller wake); host loop protections (`stop_hook_active`, 8-consecutive cap) plus the delivered stamp bound repeats |
 
 `PostToolBatch` is silent so the agent loop is not delayed; the buffered
 content is invisible until `UserPromptSubmit` peeks it.
@@ -103,16 +105,18 @@ is honored for symmetry and forward-compatibility. Cursor has no equivalent of
   "hooks": {
     "sessionStart":         [{ "command": "<bin> reminder --json" }],
     "postToolUse":          [{ "command": "<bin> buffer-tool" }],
-    "beforeSubmitPrompt":   [{ "command": "<bin> flush-tools --json" }]
+    "beforeSubmitPrompt":   [{ "command": "<bin> flush-tools --json" }],
+    "stop":                 [{ "command": "<bin> chat-notify", "loop_limit": 3 }]
   }
 }
 ```
 
 | Event | Command | Output | Role |
 |-------|---------|--------|------|
-| `sessionStart` | `thatch reminder --json` | `{ additional_context: "..." }` | Recall + heartbeat, JSON-wrapped for Cursor |
+| `sessionStart` | `thatch reminder --json` | `{ additional_context: "..." }` | Recall + heartbeat + chat identity/mail line, JSON-wrapped for Cursor |
 | `postToolUse` | `thatch buffer-tool` | **silent** | Appends a **single** tool call to the file-backed queue |
 | `beforeSubmitPrompt` | `thatch flush-tools --json` | JSON `additional_context` | Peeks queue, else recall, prediction, and behavior via sideband, else write nudge |
+| `stop` | `thatch chat-notify` | `{ followup_message }` or `{}` | Post-turn chat wake: when chat mail is unread, Cursor auto-submits the follow-up as the next user message (Cursor's analog of opencode's poller wake); `loop_limit: 3` bounds consecutive follow-ups |
 
 Differences from Claude Code:
 
@@ -126,9 +130,15 @@ Differences from Claude Code:
 
 All setup operations are idempotent:
 
-- **Instructions**: `appendBlock` searches for start/end markers and replaces
-  the block between them, so re-running setup updates drifted content without
-  clobbering surrounding text. No marker found → append.
+- **Instructions**: `appendBlock` wraps the block in sentinel comments
+  (`<!-- thatch:begin -->` / `<!-- thatch:end -->`) and replaces the block
+  between them, so re-running setup updates drifted content without
+  clobbering surrounding text. No marker found → append. Pre-sentinel
+  installs used prose sentences from the instructions themselves as
+  delimiters; `appendBlock` migrates intact legacy blocks and heals the
+  broken kind (an agent edit normalizing punctuation - hyphens to em
+  dashes - breaks the prose end marker) when the file tail still looks
+  like the instructions; anything else is left for manual repair.
 - **Hooks**: `replaceThatchHooks` / `replaceCursorThatchHooks` filter out any
   hook group whose command contains `thatch`, then add the current ones. A
   legacy `thatch echo` hook is replaced with `flush-tools`. Non-thatch hooks are

package/docs/plans/thatch-actions.md

@@ -0,0 +1,144 @@
+# Thatch Actions: Prompt Cores Shared by Nudges and /thatch Commands
+
+## Synopsis
+
+Extract the behavior instructions currently embedded in nudge text into
+prompt-core constants in `src/prompts.ts`, then build `/thatch/*` user-facing
+commands on top of the same constants. The nudge and the command become two
+envelopes around one instruction body: the nudge adds escalation tiers and
+stop-and-wait framing, the command adds user-invocation framing. First
+payoff is `/thatch/defrag`, but the structure covers any behavior the nudges
+currently ask the agent to perform on demand.
+
+## Background
+
+Nudges are instruction-carrying messages injected by hooks. Several encode a
+multi-step behavior the agent must execute (dispatch a sub-agent, fetch the
+extraction payload, run a skill, ack). The same behaviors have no user-facing
+invocation path: the user cannot say "drain the extraction queue now" or
+"consolidate duplicate memories now" -- they can only wait for a nudge or
+describe the desired behavior in prose and hope the agent maps it to the right
+skill + tool sequence.
+
+Two existing pieces make this cheap to add:
+
+- `src/commands.ts` already ships `/thatch/compact` and `/thatch/exit` as
+  markdown command files synced into the opencode config dir, and already
+  composes them from shared fragments (`sharedChecklist`,
+  `userMessageSection`).
+- The "Shared prose sync across prompt variants" problem is documented:
+  prompt prose lives in parallel functions with no single source of truth,
+  and drift in unasserted sections passes tests. This plan makes the shared
+  behavior text a true constant.
+
+## Design: prompt cores and envelopes
+
+A **prompt core** is a constant string in `src/prompts.ts` holding the
+host-agnostic instruction body for one behavior: which tools to call, in what
+order, with what arguments, and what "done" looks like.
+
+An **envelope** wraps a core with delivery-specific framing:
+
+- The nudge envelope adds: escalation tier wording, the load-bearing
+  stop-and-wait ending (see "Extraction nudge stop-and-wait wording is
+  load-bearing" -- the stop-and-wait text is nudge-only and must NOT leak
+  into action envelopes, because an action IS user input), and the
+  "system nudge, not user input" disclaimer.
+- The action envelope adds: frontmatter description, the `# User Message`
+  section with `$ARGUMENTS`, and any greenlight-token mechanics (wrap-up
+  commands only).
+
+Cores are plain string constants, not template functions, so both envelopes
+interpolate them identically. Where a core needs host-specific tool names
+(`thatch_memory_remember` vs `mcp__thatch__memory_remember`), the core takes
+the opencode spelling and MCP consumers apply the documented token
+substitution, matching the existing systemPrompt/mcpInstructions convention.
+
+## Actions v1
+
+| Command | Core behavior | Existing machinery |
+|---|---|---|
+| `/thatch/defrag` | Run `thatch_find_duplicates`, classify each pair with the thatch-dedup-classifier skill, consolidate (remember/overwrite or forget), mark pairs checked | find_duplicates + dedup classifier skill |
+| `/thatch/extract` | Fetch the extraction payload, run the fact-extractor skill, call `extraction_done` | get_extraction_payload + fact-extractor skill |
+| `/thatch/hygiene` | Run the hygiene report, act on stale and orphaned branch-scoped memories | `hygieneReport()` + `/thatch hygiene` CLI |
+| `/thatch/reflect` | Run the session-reflection skill over the current session | thatch-session-reflection skill |
+
+The wrap-up commands (`compact`, `exit`) stay as-is; their checklist text
+becomes a core reused by both templates (already true via `sharedChecklist`).
+
+## Host parity
+
+Commands are markdown or MCP prompts, synced per host. Behavior parity is the
+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
+  `command.execute.before` arming -- greenlight-token wrap-up commands do not
+  ship to Claude Code; and tool names use the `mcp__thatch__` prefix.
+- **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
+  `{{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.
+
+## 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.
+
+- 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.
+
+The rule the LLM must apply, stated everywhere the tools are described:
+
+> 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 that was
+> dispatched to process another session's extraction queue.
+
+This rule appears in: the tool 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).
+
+## Decisions
+
+- Prompt cores live in `src/prompts.ts`, not a new module; `commands.ts`
+  imports them. One prompt module, consistent with the existing module map.
+- Actions are generated, not hand-written: each action has one core and a
+  per-host renderer, so a wording change cannot drift between nudge and
+  command.
+- No `--dry-run` flag for defrag in v1; the dedup classifier skill already
+  asks for pair-by-pair verdicts, which is the interactive safety net.
+- MCP Prompts for Cursor are additive to `mcp.ts` and do not change the
+  tools/list contract.
+
+## Testing
+
+- `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.
+- 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.
+- 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):
+  action list, host parity matrix, session ID rule.
+- 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

@@ -190,8 +190,8 @@ requirements.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a slug plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
-| `thatch_chat_list` | List registered sessions with a liveness marker (fresh = its process is alive, stale = likely gone), how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
+| `thatch_chat_register` | Join the cross-session chat directory, so other sessions on this machine can message you. Display names are assigned by thatch, never chosen (a pool name plus a never-reused counter), so a name always refers to the same session. Call with no arguments to join, rejoin after unregistering, or check your name. On hosts without session context (Claude Code, Cursor), pass the name your thatch hook printed as `as`. |
+| `thatch_chat_list` | List registered sessions grouped into Active and Stale sections (stale = two missed heartbeats, about a minute; its host process has probably stopped), with how long ago each last checked in, each session's project and checkout kind (project root or linked worktree), its topic, and your unread count. |
 | `thatch_chat_send` | Send a message to another registered session, by name or session id. The recipient is nudged when its session is idle. |
 | `thatch_chat_read` | Drain your inbox: all unread messages oldest-first, marked read. Senders identified by display name. |
 | `thatch_chat_unregister` | Leave the chat directory. |
@@ -240,8 +240,9 @@ Beyond the tools, thatch hooks into opencode itself:
   watches for the token and then runs the compaction or exits opencode.
   Without the token nothing fires -- a toast points you at the items the
   agent listed, and you re-run the command once they're handled. Text typed
-  after the command is passed to the agent ahead of the checklist (say
-  goodbye or hand off context: `/thatch/exit Good work - see you tomorrow`).
+  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`).
   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;
@@ -445,6 +446,7 @@ Most configuration needs none. Two layers exist:
 | `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location (the config file follows it) |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Override embedding model |
 | `THATCH_EMBEDDING_BACKEND` | `wasm` | Set to `native` to run embeddings on onnxruntime-node (NAPI) instead of the wasm runtime |
+| `THATCH_DEBUG` | unset (off) | Diagnostic logging to `debug.log` beside the database. `1` logs everything; or a comma-separated list of tags, e.g. `chat` or `chat:startup` |
 
 Unchanged defaults: the database is created automatically, the embedding
 model downloads once and is cached, the store name is auto-detected from