@jeffober/thatch 0.1.41 → 0.1.42

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

@@ -7,15 +7,17 @@ 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
@@ -53,19 +55,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
@@ -82,6 +79,58 @@ or closed process stops heartbeat-ing, and the session shows as stale in
 its inbox unread - a dead session never reads them. Explicitly closing a
 session (deleting it in the TUI) unregisters it immediately.
 
+## 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
 
 - **Wake-up delivery is opencode only.** The chat tools work everywhere
@@ -95,8 +144,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/watchers.md

@@ -1,10 +1,11 @@
 # Watchers
 
-Watchers monitor external sources - today, GitHub pull requests and
-branches - and inject a notification into the conversation when
-something happens. You ask the agent to watch a PR or a branch; thatch
-polls it in the background; the agent gets woken up when a watched
-event occurs. No one has to keep asking "any updates yet?"
+Watchers monitor external sources - today, GitHub pull requests,
+branches, and local shell commands - and inject a notification into
+the conversation when something happens. You ask the agent to watch a
+PR, a branch, or a command; thatch polls it in the background; the
+agent gets woken up when a watched event occurs. No one has to keep
+asking "any updates yet?"
 
 ## What it does
 
@@ -34,18 +35,47 @@ Branch watched events:
   on the branch, optionally filtered by workflow name (substring,
   case-insensitive)
 
+Command watched events:
+
+- `command_success` - the watched command exited 0. The agent calls
+  `thatch_watch_command_create` with a shell command that works as a
+  **condition variable, not a data pipe**: the watcher re-runs it every
+  poll and reads only the exit code - the command's output is
+  discarded, never delivered. A command watch is one-shot by design:
+  the first exit 0 fires one notification, then the watcher cancels
+  itself. The command must be a fast, idempotent status check (a
+  marker-file test, a health endpoint curl, a `gh run list` query).
+  Blocking waits like `gh run watch` or `tail -f` are not refused -
+  the tool guidance tells the agent not to use them, and a blocking
+  command is killed at the per-run timeout each cycle and
+  treated as not-done-yet. The command runs once at registration as
+  validation: a command that already exits 0 is refused (the condition
+  is already met), as is a command-not-found.
+
 Notifications are delivered as synthetic parts: the model sees them,
 the transcript does not. A notification triggers a model turn, so the
 agent can act on the event even while you are away.
 
 ## Privacy model
 
-Notifications carry pointer data only: who commented, what happened,
-and a URL. Comment bodies, diff contents, and CI logs never enter the
-context from the notification itself. This is deliberate - GitHub
-comments are written by strangers, and untrusted text flowing into a
-model's context is a prompt-injection vector. The agent fetches details
-on demand with `gh` when it decides to act.
+Notifications carry pointer data and machine status: who acted, what
+happened, a URL, and - for CI - the check or workflow name with its
+conclusion (success, failure). Comment bodies, diff contents, and CI
+logs never enter the context from the notification itself. This is
+deliberate - GitHub comments are written by strangers, and untrusted
+text flowing into a model's context is a prompt-injection vector.
+Machine status fields come from the GitHub API rather than
+user-written text, so they are safe to deliver. The agent fetches
+everything else on demand with `gh` when it decides to act.
+
+Command watches follow the same rule with a stricter boundary: the
+notification carries the exit code and duration only. The command's
+stdout and stderr are discarded - command output can be external
+content (a curl response, a build log), so it never rides a
+notification. The agent re-runs the command or reads logs itself when
+it acts. The command runs in the project directory as the local user;
+each run is killed at a 30-second timeout
+(`THATCH_WATCH_COMMAND_TIMEOUT_SECONDS` overrides it).
 
 ## How to use it
 
@@ -56,13 +86,21 @@ Ask for it in conversation:
 
 The handling policy lives in your instruction. State it when you ask -
 the notification turn reads your policy from the conversation and
-follows it. The notification says what happened and where, not what to
-do about it.
+follows it. The notification says what happened and where, not what
+to do about it.
+
+For waiting on CI, pick the tool that fits the wait. A short bounded
+wait (a couple of minutes) can simply be polled in the conversation.
+Watchers are the better fit for longer or open-ended waits, and for
+post-merge builds on main; the creation output states when the first
+poll lands so the choice compares real numbers.
 
 Other tools:
 
 - `thatch_watch_branch_create` - watch a branch (typically main) for
   commits, CI check runs, and workflow runs
+- `thatch_watch_command_create` - wait on any local condition via a
+  shell command that exits 0 when the wait is over
 - `thatch_watch_list` - shows the session's active watchers
 - `thatch_watch_cancel` - cancels one by id
 
@@ -72,7 +110,13 @@ Watchers are in-memory and process-scoped:
 
 - Ending the opencode process (or restarting it) drops all watchers.
 - A watcher expires after 8 hours by default.
-- Each session can hold up to 5 active watchers.
+- Each session can hold up to 5 active watchers (all sources share
+  the budget).
+- A one-shot watch cancels itself after its first event - a single
+  "tell me when this run finishes" request leaves nothing polling
+  afterwards. Standing watches (the default) keep going until they
+  are cancelled, expire, or the process ends. Command watches are
+  always one-shot.
 
 If opencode restarts while a watch is active, re-register it - the
 session's conversation survives, so the policy you stated is still
@@ -83,8 +127,9 @@ there.
 - **opencode only.** MCP hosts (Claude Code, Cursor) have no way for a
   plugin to start a conversation turn, so the watch tools are not
   available there.
-- **Requires the `gh` CLI** to be installed and authenticated. Watch
-  creation reports a clear error if it is not.
+- **Requires the `gh` CLI** to be installed and authenticated for PR
+  and branch watches. Watch creation reports a clear error if it is
+  not. Command watches need only `bash`, not `gh`.
 - **Polling, not webhooks.** Events appear on the next poll cycle
   (60 seconds by default), not instantly.
 - **No delivery during an active turn.** If the agent is mid-turn when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.17.13",
+    "@opencode-ai/sdk": "1.17.13",
     "@types/bun": "^1.3.14",
     "markdownlint-cli2": "^0.23.0",
     "typescript": "^5.7.0",

package/src/chat-names.ts

@@ -7,14 +7,13 @@
  * Klingons, Discworld, Sandman, D&D, pulp detectives with software puns,
  * hackerspeak callsigns, AI puns, golden-age sci-fi, spoofed famous robots,
  * unnamed-cast extras). fnord generates its names with an LLM at runtime;
- * thatch bakes the pool in - static contents, no model call - while the
- * draw itself is random (see ChatStore.assign).
+ * thatch bakes the pool in - static contents, no model call.
  *
- * A session may still claim a custom name (chat_register's optional arg);
- * the pool is the default and keeps the directory colorful with zero
- * bikeshedding. Pool names are case-insensitively distinct from each other,
- * matching the directory's NOCASE uniqueness rule - so pool assignment can
- * never collide with another pool name, only with a custom claim.
+ * The pool is the fallback base for registrations with no usable session
+ * title (ChatStore.register slugifies a random pool name). Pool names are
+ * case-insensitively distinct from each other; slugify is lossy, but a
+ * shared base is harmless - the per-base counter still yields unique
+ * names.
  *
  * Names are deliberately short: they appear inside wake prompts and
  * chat_list output, so every character costs context.