@jeffober/thatch 0.1.41 → 0.1.42

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

@@ -1,11 +1,11 @@
 # Cross-Session Chat
 
 Cross-session chat lets independent opencode sessions on one machine message
-each other through thatch: a session registers in a shared directory, other
-sessions see it in the list, and messages land in its inbox. An idle
-recipient is woken with a prompt when mail arrives, so coordination does not
-route through the human ("ask the other session whether the release is
-green" instead of "Jeff, go ask").
+each other through thatch: sessions join a shared directory (automatically,
+under assigned names), see each other in the list, and messages land in
+inboxes. An idle recipient is woken with a prompt when mail arrives, so
+coordination does not route through the human ("ask the other session
+whether the release is green" instead of "Jeff, go ask").
 
 User-facing behavior is documented in
 [docs/user/cross-session-chat.md](../../user/cross-session-chat.md).
@@ -14,8 +14,11 @@ User-facing behavior is documented in
 
 - `thatch_chat_register` / `thatch_chat_list` / `thatch_chat_send` /
   `thatch_chat_read` / `thatch_chat_unregister` / `thatch_chat_broadcast`
-  tools (shared across hosts; opencode injects identity, MCP hosts
-  self-declare with the as argument)
+  tools (shared across hosts; opencode injects identity, MCP hosts pass the
+  name their thatch hook printed as the `as` argument)
+- Automatic registration: the plugin inserts a top-level session's
+  directory row on its first idle event, with an assigned never-reused
+  name (`chat.autoRegister: false` opts out)
 - A shared SQLite directory and inbox in thatch.db, writable by any opencode
   process on the machine
 - A per-process poller that heartbeats hosted sessions and delivers wake
@@ -54,40 +57,63 @@ outlives a process, so liveness needs a signal beyond process lifetime.
 
 ### Registration and identity
 
-`chat_register` joins the directory. Without a name it draws one at random
-from the built-in pool (`src/chat-names.ts`): whimsical geek-culture names
-in the style of fnord's Nomenclater, statically baked in so assignment never
-costs a model call. Pool draws redraw on the rare collision a concurrent
-registration can cause, and skip any name a session already claimed by
-custom registration - so the pool is the recommended path. With a name,
-the session claims it as a custom name -
-uniqueness is case-insensitive ("Landru" and "landru" are one name), so two
-visually identical identities cannot coexist, and message addressing follows
-the same rule. Databases created before the case-insensitive constraint are
-rebuilt at schema init (first row wins per case group; message history
-survives because the endpoints are not foreign keys).
-
-Identity is the host session ID, which the model cannot know or forge.
-Re-registering renames. Unregistered sessions are invisible and
-unmessageable in both directions. Only top-level sessions should register -
-sub-agent children are ephemeral - which the tool descriptions and system
-prompt state; there is no mechanical barrier, a documented trust posture.
-
-Names are claimable by any session (no impersonation defense). The trust
-model is the same as the shared memory stores: every agent on this machine
+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
+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.
+
+`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
+existing name via `as`. Re-registering keeps the name. Unregistered
+sessions are invisible and unmessageable in both directions. Only
+top-level sessions should register - sub-agent children are ephemeral -
+which the tool descriptions and system prompt state; there is no
+mechanical barrier, a documented trust posture.
+
+### Leave tombstones
+
+Every exit path - `chat_unregister` and `session.deleted` alike - 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
+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`
+(src/chat.ts), which also closes the in-flight race: an auto-register
+IIFE whose session was deleted during its title-fetch await finds the
+tombstone and stops instead of resurrecting a dead session. An explicit
+`chat_register` clears the tombstone before re-registering (fresh name -
+assigned identities are never reused), and tombstones age out in the
+hourly prune (7-day TTL; a resumed session after expiry simply
+auto-registers under a fresh name).
+
+Because names are system-minted and never recycled, the impersonation
+surface shrinks to whatever the operator runs: every agent on this machine
 is the operator's agent.
 
 ### Topics
 
-The optional topic is the roster's "who is working on what" signal: with a
-dozen registered sessions, a name like "Kurn the Typechecker" says nothing,
-but `topic:QAing the release` in `chat_list` tells a coordinator which
-session to address. Topics are free text, sanitized to one roster line
+The topic is the roster's "who is working on what" signal. For
+auto-registered sessions it is the live session title, refreshed on every
+idle event - the auto-titler usually lands a real title within a turn or
+two, so the roster converges to the actual work with nobody filling in
+forms. Legacy rows (from the claimed-names era) keep whatever topic was
+set at their registration: free text, sanitized to one roster line
 (whitespace runs collapse, 80-character cap, advisory - oversizing degrades
-rather than errors). The null/empty distinction is deliberate: omitting the
-topic on re-register keeps the existing one; an empty topic clears it.
-Broadcast senders benefit most: `chat_broadcast` answers "which of you is
-working on X?" with the roster already in hand.
+rather than errors). There is no tool path to set a topic anymore - topics
+are title-derived for everything the current code mints. Broadcast senders
+benefit most: `chat_broadcast` answers "which of you is working on X?"
+with the roster already in hand.
 
 ### Messages
 
@@ -167,19 +193,36 @@ turn reads. The accepted edge: a real user message whose every visible
 part starts with the prefix is skipped the same way, losing that one turn's
 advisory nudges.
 
+### The untrusted-content frame
+
+Message bodies are other agents' text delivered verbatim into the reading
+model's context - a prompt-injection surface by construction. The watcher
+privacy model solves the same surface with pointer-only notifications, but
+chat's payload IS the body, so `chat_read` frames the boundary instead:
+`chatInboxFrame()` (src/prompts.ts) wraps the message lines in
+begin/end fences with an explicit do-not-follow warning. The frame exists only in
+the tool output - persisted rows are untouched - and pairs with the wake
+nudge's anti-loop rule and the isChatEchoParts skip as the feature's three
+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 [--once]` follows the message stream. The tail diffs
-`ChatStore.messageFeed()` snapshots via `chatTailDiff()` (unit-tested in
-`tests/chat.test.ts`): sent lines on first view, then new sends and newly-
-read messages per poll. `chat_messages.via_broadcast` marks fan-out rows so
-the tail renders one `-> broadcast` line per recipient instead of what
-would otherwise look like identical direct sends. 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.
+renders the roster with human-readable heartbeat ages, and `thatch chat
+tail` follows the message stream as cards. The backlog renders 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
+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
+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.
 
 ## Interactions with other features
 
@@ -197,14 +240,23 @@ process opens the database.
   non-thatch tool calls made during a chat notification turn are buffered
   and extracted like any other turn's.
 - Multi-host ([multi-host.md](multi-host.md)): the chat tools are shared -
-  MCP hosts register with a self-declared identity (the `as` argument;
-  the stored session ID is synthetic, `mcp_<hash of name>`), and pending
-  mail surfaces at prompt time through the flush-tools hook line and
-  `chat_status`. Wake-up delivery remains opencode-only: no MCP server
-  can start a turn in the client's conversation.
+  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
+  tools take that name as `as`. Wake-up delivery remains opencode-only: no
+  MCP server can start a turn in the client's conversation.
 
 ## Multi-host delivery tiers
 
+Chat works on every host, and can be disabled entirely: `chat.enabled:
+false` in the thatch config makes every chat tool refuse (a `[disabled]`
+reply naming the re-enable path), stops the poller at init, omits the
+system prompt's chat section, and silences the hook lines. The tools
+re-read the config per call, so a toggle applies immediately; the poller
+gate is read once at init and needs a restart. The hook lines gate on the
+same config, so a disabled feature never advertises itself through any
+surface.
+
 Chat works on every host. Earlier designs for the MCP path - a JSONL
 temp-file inbox, a socket or daemon - were rejected: the DB already is the
 inbox, and MCP hosts cannot hold connections across turns, so both
@@ -217,12 +269,15 @@ wake analog is the existing hook channel.
 | claude code | yes          | flush-tools hook line        | no           |
 | cursor      | yes          | flush-tools hook line        | no           |
 
-MCP identity is the registered name: `chat_register` without a host
-session stores a synthetic `mcp_<sha256(name)[0:12]>` session ID, so the
-identity is stable across the ephemeral sessions those harnesses run.
-`chat_status` is the quiet check (registered flag + pending/total); the
-flush-tools hook line names the addressee sessions and prints nothing
-when the project has no pending chat - absence is silent by construction.
+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
+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
+(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
 "between turns" (broadcast always delivers).
@@ -231,19 +286,23 @@ process is gone (broadcast skips it), while an mcp row's age only means
 
 Timing constants live in `src/chat.ts`: poll interval 30s, staleness
 threshold 10 minutes, re-nudge window 15 minutes, nudge cap 6 per recipient
-per hour. There are no environment overrides yet; add them the way
-`THATCH_WATCH_POLL_SECONDS` works if a user needs them.
+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, pool assignment),
-  ChatPoller (heartbeat, gated delivery, re-nudge, rate cap), staleness
-  helper
-- `src/chat-names.ts` - the static display-name pool (nomenclater style)
-- `src/db.ts` - the chat tables in schema init, the NOCASE collation
-  migration and topic column migration, delegated methods
+- `src/chat.ts` - ChatStore (directory + inbox SQL, assigned-name draw:
+  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
+- `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 flush,
+- `src/index.ts` - poller construction, delivery closure, idle
+  auto-registration + topic refresh, idle flush,
   session.deleted unregister, dispose, transcript echo in
   tool.execute.after
 - `src/prompts.ts` - `chatNotificationNudge()`, `chatEchoText()` /

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

@@ -21,7 +21,8 @@ host-agnostic tools plus the opencode-only tools, which the MCP server
 filters out. The opencode-only set covers host-session capabilities MCP
 hosts lack: `get_session_info`, `session_search`/`session_get` (no session
 concept or session database), the `watch_create`/`watch_branch_create`/
-`watch_list`/`watch_cancel` watcher tools (no poller or proactive-prompt
+`watch_command_create`/`watch_list`/`watch_cancel` watcher tools (no
+poller or proactive-prompt
 channel), and the `chat_register`/`chat_list`/`chat_send`/`chat_read`/
 `chat_unregister`/`chat_broadcast` chat tools (no session identity or
 wake-up channel). The
@@ -188,7 +189,7 @@ behavior, with some features having no MCP counterpart.
 | Tool batching | N/A (in-process) | PostToolBatch (batch) | postToolUse (per-tool) |
 | `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 and branch watchers) | Yes (tools) | No | No |
+| `watch_*` (PR, branch, and command watchers) | Yes (tools) | No | No |
 | `chat_*` (cross-session chat) | Yes | No | No |
 
 For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
@@ -239,4 +240,4 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 - The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
 - The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
 - The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts` (opencode's list includes opencode-only tools; the MCP lists exclude them). The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.
-- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts, `get_session_info`, `session_search`/`session_get`, PR watchers, cross-session chat) have no MCP counterpart. The `thatch session` CLI subcommands work anywhere - they only need an opencode.db file to read.
+- opencode-only features (direct extraction, compaction recovery, code-review coordinator, background sub-agents, TUI toasts, `get_session_info`, `session_search`/`session_get`, all watchers (PR, branch, and command), cross-session chat wake-up) have no MCP counterpart. The `thatch session` CLI subcommands work anywhere - they only need an opencode.db file to read.

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/mcp-parity.md

@@ -18,7 +18,7 @@ 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 |

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,7 +190,7 @@ 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_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), each session's project and 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. |

package/docs/user/cli.md

@@ -47,7 +47,11 @@ 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
@@ -55,19 +59,63 @@ 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 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:
 
 ```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