@jeffober/thatch 0.1.43 → 0.1.45

package/docs/dev/features/cli.md

@@ -49,24 +49,22 @@ Read-only window on the cross-session chat directory ([cross-session-chat.md](cr
 - `chat list` renders the roster as aligned columns under a header row
   (NAME/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout is a TTY
   (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
-  text). Status reuses the `isStale()` staleness convention.
-- `chat tail` follows the message stream as styled cards: label chips,
-  colored names, dimmed timestamps, topic annotations after names, and a
-  drawn rule between cards. On a TTY, sent bodies render as markdown via
-  an external renderer (`glow`, then `gum format`; plain fallback):
-  selection (`selectChatBodyRenderer()`) and body cleanup
-  (`cleanRenderedBody()`) live in `src/chat.ts`, unit-tested there;
-  `bin/thatch` owns the TTY/NO_COLOR gate, the once-per-process cache,
-  and the spawn. The card renderer is
-  `formatChatTailCard()` (optional `renderBody` hook; the read-event
-  clip is never rendered) and the event shaping is `chatTailDiff()` in
-  `src/chat.ts`, unit-tested there; the single-line `formatChatTailEvent()`
-  remains for tests and compact contexts. `--once` prints one snapshot
-  and exits, because a snapshot has no previous state to diff read
-  events against.
-- The backlog renders only the last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages;
+  text). Rows are split into Active and Stale sections by
+  `splitChatRoster()`; the status column is `chatLiveness()`'s verdict
+  (`fresh`/`stale` for opencode rows, `active`/`idle` for MCP rows).
+- `chat tail` follows the message stream as JSONL: one `ChatTailEvent`
+  per line via `formatChatTailJsonl()` (a bare `JSON.stringify`; no ANSI,
+  no markdown rendering, no local-time conversion - the tail is a log for
+  `jq` and `grep`). `sent` and `read` are separate events linked by the
+  message `id`; broadcast fan-out is one `sent` per recipient with
+  `broadcast: true` and the real `to`. Event shaping is `chatTailDiff()`
+  in `src/chat.ts`, unit-tested there. `--once` prints one snapshot and
+  exits; the snapshot includes a `read` event for every shown message
+  whose `read_at` is set, sorted by time, so it is the same log a follow
+  would have accumulated.
+- The backlog prints only the last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages;
   `chatTailBacklog()` in `src/chat.ts` filters the feed, seeds the diff
-  state from every feed row (so the limit hides cards, not history, and a
+  state from every feed row (so the limit hides lines, not history, and a
   mid-follow rename or unregister cannot resurface old rows as sent
   events), and reports the elided count for
   the CLI's stderr note. `filterChatTailRows()` ANDs body regexes

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

@@ -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
@@ -57,19 +58,25 @@ 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
+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
+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 +84,31 @@ 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, 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.
+
 `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
@@ -94,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`
@@ -146,14 +178,31 @@ 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. 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
 
@@ -222,19 +271,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 +306,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 +328,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/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/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

@@ -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
 
@@ -176,3 +184,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

@@ -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 |
@@ -144,6 +145,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

@@ -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`)
@@ -63,16 +65,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 +107,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 +132,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