@jeffober/thatch 0.1.42 → 0.1.44

package/docs/dev/features/cli.md

@@ -46,18 +46,25 @@ Inherits stdio, exits with the child's exit code. Errors and exits 1 if none fou
 
 Read-only window on the cross-session chat directory ([cross-session-chat.md](cross-session-chat.md)):
 
-- `chat list` renders the roster: display name, human-readable age since the
-  last heartbeat, project, and topic when set.
-- `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. The card renderer is `formatChatTailCard()`
-  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;
+- `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). 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/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,47 @@ 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
+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
@@ -82,7 +112,11 @@ mechanical barrier, a documented trust posture.
 
 ### Leave tombstones
 
-Every exit path - `chat_unregister` and `session.deleted` alike - writes a
+Every exit path - `chat_unregister`, `session.deleted`, and a greenlit
+`/thatch/exit` (the plugin unregisters the exiting session before
+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
@@ -136,12 +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. `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
 
@@ -208,18 +255,21 @@ injection-hygiene layers.
 ### CLI access
 
 The user watches the conversation without an agent: `thatch chat list`
-renders the roster with human-readable heartbeat ages, and `thatch chat
-tail` follows the message stream as cards. The backlog renders only the
+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 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.
@@ -242,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.
 
@@ -263,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

@@ -1,6 +1,6 @@
 # Session Lifecycle Management (opencode)
 
-opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, and handle child session cleanup.
+opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, handle child session cleanup, and resolve wrap-up commands.
 
 ## What it does
 
@@ -11,6 +11,7 @@ opencode emits bus events for session lifecycle changes. Thatch subscribes to th
 - Sub-agent lifecycle: task-dispatched sub-agents complete accepted entries but are not deleted
 - Session error recovery: child errors requeue parent's accepted entries
 - Session deletion recovery: child deletion requeues; parent deletion completes accepted entries
+- Wrap-up commands: `/thatch/compact` and `/thatch/exit` arm a greenlight check resolved on the next idle
 
 ## How it works
 
@@ -56,9 +57,29 @@ When a task-dispatched sub-agent (not created by `triggerExtraction`) goes idle:
 
 When a parent session (no parentID) goes idle:
 
+- Wrap-up resolution first (below): a pending `/thatch/compact` or `/thatch/exit` resolves here, and a greenlit action returns early
 - If not compacting, not already extracting, and buffer has pending interactions: `triggerExtraction(sessionID)`
 - On failure: log error, clear `extracting` flag (nudge path takes over as fallback on next chat.message)
 
+### 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 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)
+3. Token present: trigger the TUI action and return early -- compaction is starting (the checklist drained the buffer) or the process is exiting
+   - compact: `client.tui.executeCommand({ body: { command: "session_compact" } })`. The execute-command route only accepts legacy alias names; `session_compact` maps to the TUI's `session.compact` action, the same thing the built-in `/compact` runs
+   - exit: unregister the session from the chat directory first (a greenlit exit's host is about to vanish; other sessions must stop addressing mail to it), then `client.tui.publish({ body: { type: "tui.command.execute", properties: { command: "app.exit" } } })`. No exit alias exists, so the TUI keymap command is published directly. The exit template's checklist also asks the model to call `thatch_chat_unregister` as its last persistence step; the plugin-side unregister is the deterministic backstop. Compaction deliberately does NOT unregister - the session continues
+4. Token absent: warning toast pointing at the blockers in the response, then fall through -- the model may have buffered tool interactions that still need extraction
+
+### Command file install
+
+`installOpencodeCommands` syncs the command markdown into
+`$XDG_CONFIG_HOME/opencode/command/thatch/` on every plugin load, writing only
+files whose on-disk content differs (template updates self-heal). opencode
+loads config -- including command discovery -- before plugins, so a
+first-ever install is invisible until the next server start.
+
 ### session.error (child session)
 
 - `requeueAccepted(parentID)` -- move parent's accepted entries back to pending (the extractor never processed them)
@@ -73,6 +94,7 @@ When a parent session (no parentID) goes idle:
 
 - `completeAccepted(id)` -- a deleted parent takes its accepted entries with it
 - Clear `extracting` for the parent
+- Clear `pendingWrapUp` for the parent
 
 ### session.compacted
 
@@ -87,6 +109,7 @@ When a parent session (no parentID) goes idle:
 - **extracting**: `Set<parentID>` -- parent IDs with an active direct-extraction child (suppresses nudge)
 - **extractionChildren**: `Set<childID>` -- distinguishes extraction children from task-dispatched sub-agents
 - **compacting**: `Set<sessionID>` -- sessions currently being compacted (suppresses nudges)
+- **pendingWrapUp**: `Map<sessionID, {token, kind}>` -- wrap-up commands awaiting their greenlight check; armed by `command.execute.before`, resolved on the next idle, cleared on session deletion
 - **missedNudges**: `Map<sessionID, number>` -- extraction nudge escalation counter
 
 ## Interactions with other features

package/docs/dev/gotchas.md

@@ -51,6 +51,15 @@ here first. These are the things that have already cost time.
   the hook object returned by `server`. Moving it into the `event` handler
   (where `session.created` lives) silently never fires it — the event bus has
   no such event. This was dead for weeks because the failure was invisible.
+- **`client.tui.executeCommand` only accepts legacy alias names**
+  (`session_compact`, `agent_cycle`, ...). Unknown commands publish
+  `{command: undefined}` and silently no-op — no error surfaces. For TUI
+  commands without an alias (e.g. `app.exit`), publish
+  `tui.command.execute` directly via `client.tui.publish`.
+- **Command markdown written by the plugin is invisible until the next server
+  start.** opencode loads config (including command discovery) before
+  plugins, so `installOpencodeCommands` self-heals on every load but a
+  first-ever install only lands after a restart.
 - **`tool.execute.after` excludes `skill` and `task` tools**, not just
   `thatch_*`. Buffering them creates a feedback loop: the nudge triggers a
   skill load, which gets buffered, which triggers another nudge on the next
@@ -167,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

@@ -22,6 +22,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **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 |
 | **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 |
@@ -143,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/dev/skills.md

@@ -61,6 +61,7 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-response` | Author-side review response: triage findings, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 | `thatch-memory-verify` | Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
 | `thatch-knowledge-export` | Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via `thatch-memory-verify`. |
+| `thatch-clear-writing` | Prose rules for any human-facing text not covered by a dedicated writing skill: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression; dedicated skills win when loaded. |
 
 **opencode-only** — the coordinator needs sub-agent support: