@jeffober/thatch 0.1.41 → 0.1.43

package/docs/dev/features/README.md

@@ -25,7 +25,7 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [deduplication.md](deduplication.md) | Deduplication system (find pairs, verdict lifecycle) |
 | [sideband.md](sideband.md) | Sideband IPC (Unix socket for MCP host hook processes) |
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
-| [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
+| [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking, wrap-up commands) |
 | [watchers.md](watchers.md) | Event-driven notifications (in-memory registry, background poller, PR watching) |
 | [cross-session-chat.md](cross-session-chat.md) | Cross-session chat (shared SQLite directory and inbox, per-process wake-up delivery) |
 | [notifications.md](notifications.md) | Out-of-band notification (banner + voice) and the user config file |

package/docs/dev/features/cli.md

@@ -22,7 +22,7 @@ The thatch CLI is a Bun script at `bin/thatch`. It provides memory inspection, M
 | `setup --claude [--cursor] [--global]` | none | `--claude`, `--cursor`, `--global` | none | Install config + instructions + hooks + skills |
 | `session list/get/transcript/search` | per subcommand | `-s/--session`, `--id`, `--after`, `--before`, `--regex`, `--limit` | none | Read-only archaeology on the opencode session database (JSONL output) |
 | `chat list` | none | none | none | Registered chat sessions: name, human-readable age, project, topic |
-| `chat tail [--once]` | none | `--once` | none | Follow cross-session chat: sent and read events (`--once` prints the backlog and exits) |
+| `chat tail` | none | `--once`, `--limit N\|all`, `--match RE` (repeatable), `--from NAME`, `--to NAME`, `--since DT`, `--until DT` | none | Follow cross-session chat: sent and read events. Backlog defaults to the last 20 messages; filters apply to follow mode too. |
 | (unknown) | none | none | none | Print usage, exit 1 |
 
 ## Global behavior
@@ -46,16 +46,36 @@ 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 [--once]` follows the message stream. Sent lines have the shape
-  `[timestamp] from -> to: body` (broadcast rows render `broadcast` via the
-  `via_broadcast` marker); in follow mode, an inbox drain emits a read line
-  (`[timestamp] ${reader} read a message from ${sender}: preview` — the
-  reader is the recipient draining its inbox). The diff logic is
-  `chatTailDiff()`/`formatChatTailEvent()` in `src/chat.ts`, unit-tested
-  there; `--once` prints one snapshot and exits, because a snapshot has no
-  previous state to diff read events against.
+- `chat list` renders the roster as aligned columns under a header row
+  (NAME/AGE/STATUS/PROJECT/TOPIC), colorized only when stdout is a TTY
+  (`formatChatRoster()` in `bin/thatch`; pipes and QA runners get plain
+  text). Status reuses the `isStale()` staleness convention.
+- `chat tail` follows the message stream as styled cards: label chips,
+  colored names, dimmed timestamps, topic annotations after names, and a
+  drawn rule between cards. On a TTY, sent bodies render as markdown via
+  an external renderer (`glow`, then `gum format`; plain fallback):
+  selection (`selectChatBodyRenderer()`) and body cleanup
+  (`cleanRenderedBody()`) live in `src/chat.ts`, unit-tested there;
+  `bin/thatch` owns the TTY/NO_COLOR gate, the once-per-process cache,
+  and the spawn. The card renderer is
+  `formatChatTailCard()` (optional `renderBody` hook; the read-event
+  clip is never rendered) and the event shaping is `chatTailDiff()` in
+  `src/chat.ts`, unit-tested there; the single-line `formatChatTailEvent()`
+  remains for tests and compact contexts. `--once` prints one snapshot
+  and exits, because a snapshot has no previous state to diff read
+  events against.
+- The backlog renders only the last `CHAT_TAIL_DEFAULT_LIMIT` (20) messages;
+  `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
+  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
+  (`--match`, repeatable), rendered-name substrings (`--from`/`--to`,
+  case-insensitive), and a half-open `--since`/`--until` window on
+  `created_at`; the same filter applies to follow polls, so non-matching
+  messages stay invisible (their read events too). A `--until` in the past
+  exits after the backlog; one in the future follows until the window
+  closes. `parseChatTimeBound()` accepts `YYYY-MM-DD [HH:MM]` local time.
 
 ## Environment variables
 

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,73 @@ 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.
+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.
+
+`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`, `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
+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
 
@@ -114,7 +150,9 @@ 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`
+hiding them - the operator decides what to do with ghosts. Each roster row
+also renders a human-readable `last seen <age>` (shared `humanAge` helper,
+src/chat.ts, same wording the CLI roster's AGE column uses). `session.deleted`
 is the graceful-exit fast path that unregisters immediately.
 
 ### Delivery, re-nudge, and the rate cap
@@ -167,19 +205,39 @@ 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 as aligned columns under a header row (TTY-gated
+color; `formatChatRoster()` in `bin/thatch`), and `thatch chat tail`
+follows the message stream as cards, with sent bodies rendered as
+markdown on a TTY via `glow`/`gum` (plain fallback, never in pipes).
+The backlog renders only the
+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 +255,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 +284,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 +301,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/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 the prompt: the templates substitute opencode's `$ARGUMENTS` ahead of the checklist, so `/thatch/exit nice work` reads as "nice work" followed by the wrap-up instructions.
+
+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