@jeffober/thatch 0.1.41 → 0.1.43

package/docs/dev/features/watchers.md

@@ -3,10 +3,11 @@
 Watchers are the general mechanism for event-driven notifications from
 external sources: the model registers a watch on something outside the
 session, thatch polls it in the background, and the plugin prompts the
-session when a watched event happens. Two sources ship: GitHub pull
-requests (source `pr`) and GitHub branches (source `branch`, for
-watching CI and workflow runs on main). The registry, poller, and
-delivery are source-agnostic - a new source adds a fetch-and-diff
+session when a watched event happens. Three sources ship: GitHub pull
+requests (source `pr`), GitHub branches (source `branch`, for watching
+CI and workflow runs on main), and local shell commands (source
+`command`, for waiting on arbitrary conditions). The registry, poller,
+and delivery are source-agnostic - a new source adds a fetch-and-diff
 function pair and event types.
 
 User-facing behavior is documented in [docs/user/watchers.md](../../user/watchers.md).
@@ -14,13 +15,16 @@ User-facing behavior is documented in [docs/user/watchers.md](../../user/watcher
 ## What it does
 
 - `thatch_watch_create` (PRs) / `thatch_watch_branch_create` (branches) /
-  `thatch_watch_list` / `thatch_watch_cancel` tools (all opencode-only)
+  `thatch_watch_command_create` (commands) / `thatch_watch_list` /
+  `thatch_watch_cancel` tools (all opencode-only)
 - A background poller in the plugin process diffs each watcher's target
   against its last-seen state
 - Delivery prompts the session with a synthetic part - the same
   mechanism opencode uses for background task completions
-- Notifications carry pointer data only (author, URL, counts); the
-  model fetches content on demand with `gh`
+- Notifications carry pointer data plus machine status (author, URL,
+  check names and conclusions, exit codes); external content is fetched
+  on demand with `gh` or by re-running a watched command, never
+  delivered
 
 ## The process-lifetime decision
 
@@ -72,6 +76,12 @@ attempt delivery. Poll errors are per-watcher; one bad PR never
 blocks the others. The diff is a pure function, so it is unit-tested
 without any network access.
 
+The interval is surfaced to the model through the registry's
+`pollSeconds` getter: watch-creation output states when the first
+poll lands, and notifications carry a cadence line, so a model
+choosing between a watcher and an in-turn poll compares real numbers
+even when `THATCH_WATCH_POLL_SECONDS` overrides the default.
+
 Event detection:
 
 - comments by id monotonicity (fetch is sorted descending)
@@ -89,6 +99,57 @@ Event detection:
 A diff emits at most 10 events per watcher per cycle, so comment
 floods collapse into one batch.
 
+### One-shot watches
+
+`watch_create` and `watch_branch_create` accept `once: true`. The
+watcher cancels itself when its first matching event is detected, not
+when it is delivered - the event still queues and delivers through the
+normal pending path, so a session busy at fire time does not lose the
+notification. Cancellation at detection time is what keeps a "tell me
+when this run finishes" request from leaving a standing watch polling
+a target nobody is waiting on. `watch_list` marks one-shot watchers
+with a `[once]` tag, and the registration output states the mode.
+
+### Command watches
+
+The command source stretches the fetch/diff recipe in two ways:
+
+1. **The fetch has side effects.** `runWatchedCommand()` executes the
+   watched command via `bash -c` in the project directory each cycle.
+   This is the point - the command IS the condition - but it means
+   command watchers must not block: the tool description and system
+   prompt state the contract (fast, idempotent status check; never
+   `gh run watch` or `tail -f`), and a per-run kill timeout
+   (default 30s, `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS`) bounds a
+   hung command's cost to one partial poll cycle - other watchers
+   wait out the kill rather than stalling, but a blocking command
+   still burns its timeout slice every cycle. A timed-out run means
+   "not done yet": the last-seen exit is left untouched and the watch
+   keeps polling.
+2. **The diff is a trivial exit-code check.** The command is a
+   condition variable, not a data pipe: stdout is drained (a full
+   pipe buffer would deadlock the child) but discarded, and stderr is
+   kept only for registration-time error messages. The notification
+   carries the exit code and duration; command output can be external
+   content, so it never rides a notification. This is the strictest
+   application of the notification content rule. The pipe drains are also
+   raced against a hard deadline, because a
+   command that backgrounds a long-lived child leaves a grandchild
+   holding the pipe write-ends past the kill - without the race, the
+   drains never resolve and the shared poll cycle stalls forever.
+
+`createCommand()` runs the command once at registration as baseline
+validation, like `createPr()`'s baseline fetch: exit 0 at baseline
+means the condition is already met (refused, so the caller proceeds
+now), exit 127 means the command does not exist (refused with the
+stderr tail), and a spawn failure fails registration with a real
+error. A baseline run that times out records the 124 sentinel as the
+last-seen exit - the killed process may have exited 0 while dying, and
+the watcher's first real exit 0 must fire. Registered command
+watchers carry `once: true` inherently - "run until it returns 0,
+then notify, then stop" is the whole concept. The `CommandRunner` is
+injectable like `GhRunner`, so tests never spawn processes.
+
 ### Delivery
 
 Events queue in an in-memory pending map keyed by session. Delivery
@@ -101,9 +162,15 @@ on the session with a synthetic text part built by
 `watcherNotificationNudge()`. This triggers a full model turn - the
 model reads the notification and decides whether to act. The
 notification text borrows the background-task-completion framing
-(system event, not user input, not approval to advance other work),
-following the same load-bearing wording discipline as the extraction
-nudge.
+(system event, not user input, not approval to advance other work)
+with one carve-out: a watch registered to gate work the user already
+greenlit (for example "wait for CI, then merge") makes the
+notification the continuation signal for exactly that work. The
+carve-out lives in the nudge itself, not only the system prompt,
+because the nudge is what the model reads at the act-or-wait decision
+point. The wrapper also states that check-run and workflow
+conclusions are already in the event summaries, so gh fetches are
+needed only for logs and bodies.
 
 Failed or gated deliveries stay pending and retry on the next poll
 cycle or when the session next goes idle (the event hook calls
@@ -114,7 +181,10 @@ cycle or when the session next goes idle (the event hook calls
 `pr_comment`, `pr_review_comment`, `pr_review_reply`,
 `pr_review_resolved`, `pr_commit`, `pr_status`, `pr_description`,
 `pr_ci`. The tool's `events` argument selects a subset; the default is
-all eight.
+all eight. Branch watchers add `branch_commit`, `branch_ci`, and
+`branch_workflow` (the full vocabulary is `WATCHER_EVENT_TYPES` in
+src/watchers.ts, test-enforced); command watchers register the single
+`command_success` type.
 
 ## Interactions with other features
 
@@ -134,28 +204,48 @@ all eight.
 - `THATCH_WATCH_POLL_SECONDS` - poll interval (default 60)
 - `THATCH_WATCH_TTL_MINUTES` - watcher time-to-live (default 480)
 - `THATCH_WATCH_MAX_PER_SESSION` - active watchers per session
-  (default 5)
+  (default 5; all sources share the budget)
+- `THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` - per-run kill timeout for
+  watched commands (default 30)
 
 ## Source files
 
-- `src/watchers.ts` - registry, poller, gh CLI runner, diff functions
-- `src/tool-defs.ts` - the three watch tool definitions
+- `src/watchers.ts` - registry, poller, gh CLI runner, command runner,
+  diff functions
+- `src/tool-defs.ts` - the watch tool definitions (see `TOOL_DEFS`)
 - `src/index.ts` - registry construction, delivery closure,
   session.status tracking, session.deleted cleanup, dispose
 - `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
   Watchers section
 - `tests/watchers.test.ts` - registry, poll, and diff unit tests
-  (mocked gh, no network)
+  (mocked gh and command runners, no network)
+- `tests/tool-defs.test.ts` - watch tool execute-function tests
 - `tests/qa/auto/uc-095-watchers.ts` - end-to-end lifecycle against a
   mocked gh runner
+- `tests/qa/auto/uc-101-command-watchers.ts` - command-watch lifecycle
+  against a mocked command runner
 
 ## Adding a new source type
 
-The registry is a discriminated union over sources: `PrWatcher` and
-`BranchWatcher` implement the same lifecycle (id, session, repo,
-events, expiry, snapshot), and `poll()` dispatches to the source's
-fetch/diff pair. Adding a third source means: new event types, a
-`fetchXState`/`diffXState` pair, a new arm of the `Watcher` union, a
-`#pollOne` branch, and the tool surface for registering it. Keep the
-pointer-only notification rule: external content enters the context on
-explicit fetch, never via notification.
+The registry is a discriminated union over sources: `PrWatcher`,
+`BranchWatcher`, and `CommandWatcher` implement the same lifecycle
+(id, session, events, expiry, snapshot), and `poll()` dispatches to
+the source's fetch/diff pair. Adding a new source means: new event
+types, a fetch function and diff (or a trivial inline diff like the
+command source's), a new arm of the `Watcher` union, a `#pollOne`
+branch, and the tool surface for registering it. Keep the
+notification content rule: external content enters the context on
+explicit fetch, never via notification. Machine status fields (names,
+conclusions, counts, exit codes) come from the API rather than
+user-written text and belong in event summaries.
+
+Two caveats from the command source, worth carrying to future
+sources:
+
+- If the source's fetch does anything beyond reading an API, inject a
+  runner (like `GhRunner`/`CommandRunner`) so tests never spawn real
+  work, and bound it with a timeout so a hung fetch cannot stall the
+  shared sequential poll cycle.
+- If the source has no natural URL (a local command has none), emit
+  an empty `url` in the event; `watcherNotificationNudge()` omits
+  empty URLs rather than rendering a dangling space.

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

package/docs/dev/mcp-parity.md

@@ -18,10 +18,11 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR and branch watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel. The `chat_*` tools (cross-session chat) are opencode-only — no host session identity and no wake-up channel |
+| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR, branch, and command watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel. The `chat_*` tools (cross-session chat) are opencode-only — no host session identity and no wake-up channel |
 | **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 |

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:
 

package/docs/user/README.md

@@ -11,7 +11,7 @@ This README is the overview. Each feature has its own guide:
 
 - [memory.md](memory.md): persistent memory store
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
-- [watchers.md](watchers.md): event-driven notifications (PR and branch watching)
+- [watchers.md](watchers.md): event-driven notifications (PR, branch, and command watching)
 - [cross-session-chat.md](cross-session-chat.md): sessions messaging each other on one machine
 - [notifications.md](notifications.md): banner and voice notifications, user config
 - [prediction-engine.md](prediction-engine.md): user decision model
@@ -179,6 +179,7 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 |------|-------------|
 | `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, thread resolutions, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
 | `thatch_watch_branch_create` | Watch a GitHub branch (typically main) for commit landings, CI check-run completions, and workflow runs, with an optional workflow-name filter. |
+| `thatch_watch_command_create` | Wait on any local condition via a shell command that exits 0 when the wait is over. One-shot: one notification on the first exit 0, then it cancels itself. |
 | `thatch_watch_list` | List this session's active watchers. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
@@ -189,8 +190,8 @@ requirements.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_chat_register` | Join the cross-session chat directory, so other opencode sessions on this machine can message you. Without a name, one is drawn from the built-in pool (recommended - cannot collide); with a name, it is claimed case-insensitively. Pass a topic (one line about what the session is working on) so the roster tells others who to talk to. Safe to call again - same name is a no-op, a new name renames, a new topic updates. |
-| `thatch_chat_list` | List registered sessions with a liveness marker (fresh = its process is alive, stale = likely gone), each session's project and 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 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_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. |
@@ -231,6 +232,20 @@ Beyond the tools, thatch hooks into opencode itself:
   notification (`[thatch] recalled 3 memories`, `[thatch] 2 predictions
   surfaced`, or `[thatch] 1 behavior surfaced`). The toast is ephemeral. It
   fades after a few seconds.
+- **Wrap-up commands.** `/thatch/compact` and `/thatch/exit` (opencode only)
+  run a pre-flight checklist before you compact or close a session: the agent
+  flushes pending fact extraction, finishes any promised memory writes, and
+  surfaces todos or follow-ups it never addressed. The agent ends its
+  response with a greenlight token only when the checklist is clean. Thatch
+  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`).
+  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;
+  a first install becomes available after the next opencode start.
 - **Compaction context.** When opencode compacts a long session, thatch injects
   a reminder so the summarized session still knows memory tools exist.
 - **Prediction auto-fire.** When a prompt matches learned contexts, thatch
@@ -313,6 +328,7 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections, project-context research, clarity checks, and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
 
 ### opencode-only skills
 

package/docs/user/cli.md

@@ -47,27 +47,81 @@ Read-only access to the chat directory your opencode sessions share
 ```bash
 thatch chat list               # who is registered: name, age, project, topic
 thatch chat tail               # follow sent and read events, live
-thatch chat tail --once        # print the messages sent so far and exit
+thatch chat tail --once        # print the last 20 messages and exit
+thatch chat tail --once --limit 50   # a longer backlog (or --limit all)
+thatch chat tail --match "rebase" --match "payments"   # body must match both
+thatch chat tail --from al --to bob        # substring match on names
+thatch chat tail --since 2026-09-12 --until "2026-09-13 09:00"   # a window
 ```
 
-`chat list` shows every registered session with how long since its last
-heartbeat (a large age means the session's process is probably gone), its
-project, and the topic it registered with - the fastest way to answer
-"which session should I talk to about X?"
-
-`chat tail` prints the conversation as it happens:
+`chat list` shows every registered session as aligned columns under a
+header row: how long since its last heartbeat (a large age means the
+session's process is probably gone), its status (`fresh` or `STALE`),
+its project, and the topic it registered with - the fastest way to
+answer "which session should I talk to about X?" Color is added only
+when the output is a terminal; a pipe prints plain aligned text.
+
+`chat tail` prints the conversation as styled chat cards (labels on a
+colored background, names in color, timestamps dimmed; a drawn rule
+separates cards, with blank lines on either side). After each name, the
+session's registered topic appears in muted italics - so the tail tells
+you not just who is talking but what they are working on. In a
+terminal, message bodies render as markdown: if `glow` (or `gum`) is
+installed, bodies with headings, lists, code blocks, and emphasis are
+styled; plain-text bodies print exactly as sent. Piped output - and a
+system without either tool - always gets the raw body.
 
 ```text
-[2026-09-12T14:02:11Z] Kurn the Typechecker -> Marlowe the Cherry Picker: CI is green on main
-[2026-09-12T21:07:52Z] Marlowe the Cherry Picker -> broadcast: rebasing payments, hold off
-[2026-09-12T21:08:03Z] Marlowe the Cherry Picker read a message from Kurn the Typechecker: direct ping
+ From   Al Go Rithm <cross-session messaging between opencode sessions>
+ To     Brute the Dream Farrier <diagnosing watcher underuse>
+ When   2026-09-12 14:02 America/Denver
+
+CI is green on main
+____________________________________________________________
+
+ To     broadcast
+ When   2026-09-12 21:07 America/Denver
+
+rebasing payments, hold off
+____________________________________________________________
+
+ From   Kurn the Typechecker <release QA>
+ read Marlowe the Cherry Picker <payments refactor>
+ When   2026-09-12 21:08 America/Denver
+
+direct ping
 ```
 
 Follow mode runs until Ctrl-C. Read events appear only in follow mode
-(they fire when an inbox is drained after the tail started). The chat
-itself flows through the agents (the CLI never sends, reads, or
-registers on a session's behalf; that happens from opencode sessions
-via the `thatch_chat_*` tools).
+(they fire when an inbox is drained after the tail started). When
+timestamps are in your local timezone. The chat itself flows through the
+agents (the CLI never sends, reads, or registers on a session's behalf;
+that happens from opencode sessions via the `thatch_chat_*` tools).
+
+The backlog shows the last 20 messages before follow mode takes over.
+When messages are hidden, tail prints a one-line note on stderr saying
+how many there were; `--limit N` raises or lowers the backlog and
+`--limit all` shows everything. All the filters apply to live events
+too, so a filtered tail keeps watching the same way:
+
+- `--match PATTERN` filters message bodies. Repeat it to AND patterns
+  together: every one must match the message body.
+- `--from NAME` and `--to NAME` match participant names (case doesn't
+  matter). A departed sender can only be found as the `unknown`
+  rendering the tail shows. Broadcast cards say `broadcast` in the To
+  slot, but the row underneath keeps the real recipient: `--to <name>`
+  finds the fan-out rows that reached them, while `--to broadcast`
+  matches nothing.
+- `--since DT` and `--until DT` bound the window; a message counts if
+  it was sent at or after `--since` and before `--until`. The date
+  format is `YYYY-MM-DD` with an optional `HH:MM` in your local
+  timezone.
+
+A `--until` already in the past exits after the backlog (a closed
+window has nothing left to follow); one in the future follows until
+the window closes. Note that the limit hides sent cards, not their
+reads: a hidden message that gets read during follow mode still emits
+its read card.
 
 ## Priming a new project
 

package/docs/user/cross-session-chat.md

@@ -7,19 +7,22 @@ between tabs all afternoon.
 
 ## What it does
 
-Each session opts in with `thatch_chat_register`. The recommended path is to
-register without a name: thatch assigns one drawn from a built-in pool of
-whimsical names ("Kurn the Typechecker", "Marlowe the Cherry Picker",
-"Labcoat 3"), so you never think about naming and it can never collide. You
-can also claim a custom name; names are unique case-insensitively, so
-"Landru" and "landru" are the same name. Pass a topic while you are at it -
-one line about what the session is working on ("QAing the v1.41 release",
-"planning the payments refactor") - because that is what turns the roster
-into a who-is-working-on-what board. Once registered:
+opencode sessions join the directory automatically, on their first idle
+moment. Names are assigned by thatch, never chosen: a lowercase slug of the
+session's title plus a counter (a session titled "Fix auth bug" becomes
+`fix-auth-bug-00001`). The counter only ever increments, so a name is
+minted exactly once per machine - pruning an old session never reissues its
+name to someone else, and the same name always refers to the same session.
+The live title rides along as the session's topic (refreshed as the
+auto-titler converges), so the roster reads as a who-is-working-on-what
+board without anyone filling in forms. A session can also join or rejoin
+explicitly with `thatch_chat_register` (no arguments) - useful after
+`chat_unregister`, or just to check your assigned name. Once registered:
 
 - `thatch_chat_list` shows every registered session on the machine, with a
-  liveness marker (fresh or stale), its project, its topic, and your unread
-  count
+  liveness marker (fresh or stale), how long ago it last checked in, its
+  project, whether it runs in the project root or a linked git worktree,
+  its topic, and your unread count
 - `thatch_chat_send` delivers a message to another registered session, by
   name or session id
 - `thatch_chat_read` drains the session's inbox
@@ -53,19 +56,14 @@ toggle reveals those output blocks if you want them.)
 
 ## How to use it
 
-Tell each session to register, then let them coordinate:
+With auto-registration you usually do nothing: both sessions are already
+in the directory. To introduce them, just tell each session who to talk to:
 
-> Register in the thatch chat. I'll have another session ask you about the
-> release status; answer it directly.
+> Ask the other session whether the release has shipped; answer its
+> questions directly.
 
-and in the other session:
-
-> Register in the thatch chat, then ask the other session whether the
-> release has shipped.
-
-(Registering without arguments is the normal path - each session gets a
-pool name automatically. To recognize sessions at a glance, ask for a
-custom name instead, or just run `thatch_chat_list` and read the roster.)
+Sessions find each other with `thatch_chat_list` and address each other by
+their assigned names.
 
 Received messages are treated as informational, not as your instructions: an
 agent that gets mail will not treat it as approval to start work, and it
@@ -80,7 +78,63 @@ A session shows as fresh while its opencode process is running. A crashed
 or closed process stops heartbeat-ing, and the session shows as stale in
 `thatch_chat_list` after ten minutes. Messages to a stale session wait in
 its inbox unread - a dead session never reads them. Explicitly closing a
-session (deleting it in the TUI) unregisters it immediately.
+session (deleting it in the TUI) unregisters it immediately, and a
+greenlit `/thatch/exit` unregisters the session too: the wrap-up
+checklist calls `chat_unregister`, and the plugin removes the row itself
+when the exit token passes the greenlight check, so other sessions stop
+addressing mail to a process that is about to vanish.
+
+## Turning chat off
+
+Set `chat.enabled: false` in the thatch config file
+(`~/.config/thatch/config.json`) - or ask an agent:
+`config_set with chat: { enabled: false }`. When off:
+
+- every chat tool refuses, stating that chat is disabled and how to
+  re-enable it
+- the poller never starts, so nothing is woken or heartbeated
+- the system prompt omits the chat section entirely, and the hook lines
+  print nothing - the feature stops existing as far as any agent can tell
+
+Takes effect for the tools immediately (they re-read the config per
+call); a restart applies it to the poller and prompt. Delete the setting
+(or set it true) to turn chat back on.
+
+## Turning auto-registration off
+
+Set `chat.autoRegister: false` in the same config file when you want the
+old opt-in behavior: opencode sessions stay out of the directory until
+they call `chat_register`. (The Claude Code / Cursor hook still ensures
+its conversation's identity is registered on each prompt - that is the
+host's identity anchor, not auto-joining; remove the hook with
+`thatch setup` if you want those hosts out too.) Wake delivery for
+registered sessions still works; there is just no automatic joining.
+
+## Leaving the directory
+
+`chat_unregister` is a real exit on every host: a leave tombstone
+suppresses re-joining (auto-registration on opencode, the hook's ensure on
+other hosts) until the session explicitly calls `chat_register` again.
+Without the tombstone, the next idle moment would silently re-register the
+session under a fresh name and undo the leave. Rejoining mints a new name
+(assigned names are never reused, even by the same session).
+
+## Security model
+
+Chat messages are text written by OTHER agent sessions, delivered into a
+reading agent's context verbatim - a prompt-injection surface by
+construction. Three mitigations:
+
+- **Framed at read time.** `chat_read` wraps its output in an explicit
+  untrusted-content frame (begin/end fences with a do-not-follow warning).
+  The frame exists only in the tool output; the persisted messages are
+  untouched.
+- **Names are assigned, not claimed.** Display names are minted by thatch
+  with a never-reused counter, so a name cannot be grabbed by an unrelated
+  session and an old name cannot be resurrected by an impersonator.
+- **No external content via wake.** The wake notification names senders
+  and counts only - bodies flow exclusively through the framed
+  `chat_read` surface.
 
 ## Requirements and limitations
 
@@ -95,8 +149,7 @@ session (deleting it in the TUI) unregisters it immediately.
 - **Loop safety.** Thatch caps wake prompts per recipient per hour, so two
   agents acknowledging each other cannot ping-pong forever even if both
   models decide to be chatty.
-- **Names are claimable.** Any session can pick any unused name (uniqueness
-  is case-insensitive). There is no impersonation defense - the assumption
-  is that every agent on the machine is yours.
 - **Message retention.** Messages are kept as history; unregistering does
-  not delete them. There is no automatic pruning yet.
+  not delete them. Auto-registered sessions whose host has been gone for a
+  week are pruned from the directory (their names are never reused), and
+  unread mail addressed to them is removed on a later sweep.

package/docs/user/skills.md

@@ -68,6 +68,7 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-pr-description` | Drafts PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis for scanning. |
 | `thatch-ticket-description` | Drafts ticket or issue descriptions (Linear or Jira) with clear sections and bold/italic emphasis for scanning. |
 | `thatch-split-overlarge-pr` | Splits already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+| `thatch-clear-writing` | Prose rules for every human-facing text the dedicated writing skills do not cover: PR and ticket comments, documentation, plans, reports, and chat replies. Clarity over compression. |
 
 ### Workflow skills