@jeffober/thatch 0.1.41 → 0.1.43

package/src/tool-defs.ts

@@ -3,20 +3,25 @@ import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
 import {
   CONFIG_SECTIONS,
+  chatEnabled,
+  chatPrefsSchema,
   loadConfig,
+  mergeChatPrefs,
   mergeNotificationPrefs,
   notificationDefaults,
   notificationPrefsSchema,
   saveConfig,
+  type ChatPrefs,
   type Config,
   type ConfigSection,
   type NotificationPrefs,
 } from "./config";
 import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
-import { predictionVerb } from "./prompts";
+import { predictionVerb, chatInboxFrame } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
-import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
-import { CHAT_STALE_MINUTES, isStale, renderChatParticipant, mcpSessionID, type ChatHostKind } from "./chat";
+import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
+import { CHAT_STALE_MINUTES, isStale, renderChatParticipant, humanAge, type ChatHostKind } from "./chat";
+import { detectWorktreeKind } from "./git";
 
 // Near-duplicate thresholds for matcher/prediction/behavior dedup at
 // creation time. Matches the thatch_find_duplicates threshold (0.85).
@@ -75,6 +80,9 @@ export interface CoreContext {
    *  path - MCP hosts have no poller, no event bus, and no way to deliver a
    *  proactive prompt, so watch tools are opencode-only. */
   watchers?: WatcherRegistry;
+  /** The plugin host's project directory. Command watchers run their
+   *  commands here. Only wired on the opencode path, alongside watchers. */
+  projectDir?: string;
   /** Injectable command runner for notify_user. Defaults to Bun.spawn.
    *  Tests inject a mock so notifications never actually fire or speak. */
   spawner?: Spawner;
@@ -891,6 +899,15 @@ function renderNotificationSection(prefs: NotificationPrefs | undefined): string
   return lines.join("\n");
 }
 
+/** Renders the chat section. Both fields default to on. */
+function renderChatSection(prefs: ChatPrefs | undefined): string {
+  return [
+    "chat:",
+    `  enabled: ${prefs?.enabled ?? "<unset>"} (default: on)`,
+    `  autoRegister: ${prefs?.autoRegister ?? "<unset>"} (default: on; opencode sessions join the chat directory automatically)`,
+  ].join("\n");
+}
+
 /** Drops keys explicitly set to undefined so a merge never overwrites. */
 function stripUndefined(obj: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -904,7 +921,7 @@ const configGetDef: ToolDef = {
     "The config file (~/.config/thatch/config.json, beside thatch.db) is " +
     "also hand-editable. Call this before config_set.",
   args: {
-    section: z.enum(["notifications"]).optional().describe(
+    section: z.enum(["notifications", "chat"]).optional().describe(
       "Restrict output to one section. Omit to read all sections.",
     ),
   },
@@ -919,6 +936,9 @@ const configGetDef: ToolDef = {
       if (name === "notifications") {
         lines.push(renderNotificationSection(loaded.config.notifications));
       }
+      if (name === "chat") {
+        lines.push(renderChatSection(loaded.config.chat));
+      }
     }
     lines.push("", `file: ${loaded.path}`);
     return lines.join("\n");
@@ -950,24 +970,50 @@ const configSetDef: ToolDef = {
       "Notification preferences to update. Fields you omit keep their " +
       "current values.",
     ),
+    chat: z.strictObject({
+      enabled: z.boolean().optional().describe(
+        "Cross-session chat on/off. Unset or true is the default; false " +
+        "makes every chat tool refuse and stops wake delivery.",
+      ),
+      autoRegister: z.boolean().optional().describe(
+        "Whether opencode sessions join the chat directory automatically " +
+        "(assigned names). Unset or true is the default; false restores " +
+        "opt-in joining via chat_register only.",
+      ),
+    }).optional().describe(
+      "Chat preferences to update. Fields you omit keep their current " +
+      "values.",
+    ),
   },
   async execute(args) {
     const loaded = loadConfig();
     const config: Config = { ...loaded.config };
-    const patch = args.notifications as Record<string, unknown> | undefined;
-    if (!patch || Object.keys(stripUndefined(patch)).length === 0) {
+    const notifPatch = args.notifications as Record<string, unknown> | undefined;
+    const chatPatch = args.chat as Record<string, unknown> | undefined;
+    const notifClean = notifPatch ? stripUndefined(notifPatch) : {};
+    const chatClean = chatPatch ? stripUndefined(chatPatch) : {};
+    if (Object.keys(notifClean).length === 0 && Object.keys(chatClean).length === 0) {
       return (
         "Nothing to update: pass a section with fields to change.\n" +
-        renderNotificationSection(config.notifications)
+        renderNotificationSection(config.notifications) + "\n" +
+        renderChatSection(config.chat)
+      );
+    }
+    if (Object.keys(notifClean).length > 0) {
+      config.notifications = notificationPrefsSchema.parse(
+        mergeNotificationPrefs(config.notifications, notifClean),
+      );
+    }
+    if (Object.keys(chatClean).length > 0) {
+      config.chat = chatPrefsSchema.parse(
+        mergeChatPrefs(config.chat, chatClean),
       );
     }
-    config.notifications = notificationPrefsSchema.parse(
-      mergeNotificationPrefs(config.notifications, stripUndefined(patch)),
-    );
     const path = saveConfig(config);
     return (
       `[saved] ${path}\n` +
-      renderNotificationSection(config.notifications)
+      (Object.keys(notifClean).length > 0 ? renderNotificationSection(config.notifications) + "\n" : "") +
+      (Object.keys(chatClean).length > 0 ? renderChatSection(config.chat) : "")
     );
   },
 };
@@ -1166,14 +1212,17 @@ const watchCreateDef: ToolDef = {
   name: "watch_create",
   description:
     "Watch a GitHub PR for events and get notified in this session when they " +
-    "happen. Events: new top-level comments, new inline review comments, " +
-    "replies to review comments, review thread resolutions, new commits " +
-    "(head SHA change), PR status changes, title/description edits, and " +
-    "completed CI check runs. The watcher polls in the background and " +
-    "injects a notification prompt; notifications carry pointers only " +
-    "(author, URL) - fetch details yourself with the gh CLI when you decide " +
-    "to act. Watches live until cancelled, the session ends, or opencode " +
-    "restarts. Requires the gh CLI.",
+    "happen: new top-level comments, inline review comments and replies, " +
+    "review thread resolutions, new commits (head SHA change), PR status " +
+    "changes, title/description edits, and completed CI check runs. For CI " +
+    "waits: a short bounded wait (about 2-3 minutes) is fine as a single " +
+    "in-turn gh poll; for longer or unknown waits, use this watcher instead " +
+    "of sleep-polling. The watcher polls about every 60s by default - the " +
+    "first check lands within ~60s of creation. Notifications carry a short " +
+    "machine summary (event type, actor, and for CI the check name and " +
+    "conclusion); use the gh CLI only for logs and further details. Watches " +
+    "live until cancelled, the session ends, or opencode restarts. Requires " +
+    "the gh CLI.",
   args: {
     pr: z.number().int().positive().describe(
       "The PR number to watch.",
@@ -1184,6 +1233,11 @@ const watchCreateDef: ToolDef = {
     events: z.array(z.enum(PR_EVENT_TYPES as [PrWatcherEventType, ...PrWatcherEventType[]])).optional().describe(
       "Which event types to watch. Omit for all PR event types.",
     ),
+    once: z.boolean().optional().describe(
+      "Fire only once: after the first matching event happens, the watcher " +
+      "cancels itself. Use for one-shot waits like 'tell me when this run " +
+      "finishes'. Default false - a standing watch.",
+    ),
   },
   opencodeOnly: true,
   async execute(args, ctx, host) {
@@ -1195,18 +1249,21 @@ const watchCreateDef: ToolDef = {
     }
     const repo = (args.repo as string | undefined) ?? ctx.defaultStore;
     const events = (args.events as PrWatcherEventType[] | undefined) ?? [...PR_EVENT_TYPES];
-    const result = await ctx.watchers.createPr(host.sessionID, repo, args.pr as number, events);
+    const result = await ctx.watchers.createPr(host.sessionID, repo, args.pr as number, events, { once: args.once === true });
     if (!result.ok) return `Watcher not created: ${result.error}`;
     const w = result.watcher;
     return (
       `[watching] ${w.repo}#${w.pr}\n` +
       `id: ${w.id}\n` +
       `events: ${w.events.join(", ")}\n` +
+      (w.once ? `mode: one-shot - auto-cancels after the first event\n` : "") +
       `head: ${w.state.headSha.slice(0, 7)} (${w.state.state}${w.state.merged ? ", merged" : ""})\n\n` +
-      `The baseline is captured now - only changes from this point notify. ` +
+      `The baseline is captured now - only changes from this point notify, ` +
+      `and the first poll lands within ~${ctx.watchers.pollSeconds}s. ` +
       `You will receive a system notification in this session when a watched event happens. ` +
-      `State any handling policy for those notifications now (e.g. what to act on, what just to report), ` +
-      `since the notification itself carries only pointers.`
+      `State any handling policy for those notifications now (e.g. what to act on, what just to report) - ` +
+      `the notification carries a short machine summary (for CI: check name and conclusion), ` +
+      `and you fetch details with the gh CLI only when you decide to act.`
     );
   },
 };
@@ -1234,8 +1291,11 @@ const watchListDef: ToolDef = {
     const minutesLeft = (w: { expiresAt: number }) => Math.max(0, Math.round((w.expiresAt - Date.now()) / 60_000));
     return watchers
       .map((w) => {
+        if (w.source === "command") {
+          return `${w.id}: cmd: ${commandTargetLabel(w.command)} [${w.source}]${w.once ? " [once]" : ""} events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m lastExit=${w.state.lastExit}`;
+        }
         const target = w.source === "pr" ? `${w.repo}#${w.pr}` : `${w.repo}@${w.branch}`;
-        return `${w.id}: ${target} [${w.source}] events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`;
+        return `${w.id}: ${target} [${w.source}]${w.once ? " [once]" : ""} events=[${w.events.join(",")}] expires in ${minutesLeft(w)}m head=${w.state.headSha.slice(0, 7)}`;
       })
       .join("\n");
   },
@@ -1254,10 +1314,15 @@ const watchBranchCreateDef: ToolDef = {
     "when things happen on it: branch_commit when new commits land (e.g. a " +
     "PR merged), branch_ci when a check run on the head completes, and " +
     "branch_workflow when a GitHub Actions workflow run starts or finishes " +
-    "on the branch. Optionally filter to workflow names (substring match). " +
-    "The watcher polls in the background and injects a notification prompt; " +
-    "notifications carry pointers only - fetch details with the gh CLI when " +
-    "you decide to act. Watches live until cancelled, the session ends, or " +
+    "on the branch. This is how you watch CI against main or wait for a " +
+    "post-merge build. For CI waits: a short bounded wait (about 2-3 " +
+    "minutes) is fine as a single in-turn gh poll; for longer or unknown " +
+    "waits, use this watcher instead of sleep-polling. Optionally filter to " +
+    "workflow names (substring match). The watcher polls about every 60s by " +
+    "default - the first check lands within ~60s of creation. Notifications " +
+    "carry a short machine summary (event type, and for CI and workflow " +
+    "runs the name and conclusion); use the gh CLI only for logs and " +
+    "further details. Watches live until cancelled, the session ends, or " +
     "opencode restarts. Requires the gh CLI.",
   args: {
     branch: z.string().describe(
@@ -1272,6 +1337,11 @@ const watchBranchCreateDef: ToolDef = {
     workflows: z.array(z.string()).optional().describe(
       "Only notify for workflow runs whose name contains one of these substrings (case-insensitive). Omit for all workflows.",
     ),
+    once: z.boolean().optional().describe(
+      "Fire only once: after the first matching event happens, the watcher " +
+      "cancels itself. Use for one-shot waits like 'tell me when this run " +
+      "finishes'. Default false - a standing watch.",
+    ),
   },
   opencodeOnly: true,
   async execute(args, ctx, host) {
@@ -1289,6 +1359,7 @@ const watchBranchCreateDef: ToolDef = {
       args.branch as string,
       events,
       (args.workflows as string[] | undefined) ?? [],
+      { once: args.once === true },
     );
     if (!result.ok) return `Watcher not created: ${result.error}`;
     const w = result.watcher;
@@ -1297,11 +1368,84 @@ const watchBranchCreateDef: ToolDef = {
       `id: ${w.id}\n` +
       `events: ${w.events.join(", ")}\n` +
       (w.workflows.length > 0 ? `workflow filter: ${w.workflows.join(", ")}\n` : "") +
+      (w.once ? `mode: one-shot - auto-cancels after the first event\n` : "") +
       `head: ${w.state.headSha.slice(0, 7)}\n\n` +
-      `The baseline is captured now - only changes from this point notify. ` +
+      `The baseline is captured now - only changes from this point notify, ` +
+      `and the first poll lands within ~${ctx.watchers.pollSeconds}s. ` +
       `You will receive a system notification in this session when a watched event happens. ` +
-      `State any handling policy for those notifications now (e.g. what to act on, what just to report), ` +
-      `since the notification itself carries only pointers.`
+      `State any handling policy for those notifications now (e.g. what to act on, what just to report) - ` +
+      `the notification carries a short machine summary (for CI: check name and conclusion), ` +
+      `and you fetch details with the gh CLI only when you decide to act.`
+    );
+  },
+};
+
+/**
+ * Registers a background watcher on a local shell command. The command is a
+ * CONDITION VARIABLE, not a data pipe: the poller re-runs it every cycle and
+ * reads only its exit code - stdout and stderr are discarded, never delivered.
+ * The session gets one synthetic notification the first time the command
+ * exits 0, and the watcher cancels itself. This is the generic "wait for an
+ * arbitrary condition" escape hatch: wait for a marker file, an endpoint to
+ * come up, a lock to clear. opencode-only, like the other watch tools.
+ * Requires bash, not the gh CLI.
+ */
+const watchCommandCreateDef: ToolDef = {
+  name: "watch_command_create",
+  description:
+    "Register a local shell command as a background condition and get " +
+    "notified in this session when it first exits 0. THE COMMAND IS A " +
+    "CONDITION VARIABLE, NOT A DATA PIPE: the watcher only reads its exit " +
+    "code - stdout and stderr are discarded, never returned to you. Write " +
+    "the command as a fast, idempotent status check (exit 0 = the wait is " +
+    "over) such as 'test -f marker', 'curl -sf endpoint >/dev/null', or a " +
+    "'gh run list --json' query - NOT a command whose output you want, and " +
+    "NOT a blocking wait (no 'gh run watch', 'tail -f', or 'sleep': the " +
+    "per-run timeout kills a blocking command each cycle, wasting up to " +
+    "30s of the shared poll cycle on a check that can never succeed). " +
+    "Use this for long or unknown-duration waits on any local condition " +
+    "instead of sleep-polling. The command runs in this project directory " +
+    "via bash -c about every 60s, killed at a 30s per-run timeout " +
+    "(THATCH_WATCH_COMMAND_TIMEOUT_SECONDS overrides; a timed-out run " +
+    "means not-done-yet). One-shot by design: it fires once on the first " +
+    "exit 0, auto-cancels, and the notification carries only the exit code " +
+    "and duration - re-run the command or read logs yourself if you need " +
+    "details. The command runs once at registration as validation: if it " +
+    "already exits 0 the watcher is refused (the condition is already met - " +
+    "proceed instead), and a command-not-found (exit 127) is refused too. " +
+    "Counts against the per-session watcher limit; expires with the " +
+    "session's other watchers.",
+  args: {
+    command: z.string().min(1).describe(
+      "The shell command to run as a condition: a fast, idempotent status " +
+      "check that exits 0 when the wait is over. Its output is discarded.",
+    ),
+  },
+  opencodeOnly: true,
+  async execute(args, ctx, host) {
+    if (!host) {
+      return "Watching is unavailable: this host did not provide a session context.";
+    }
+    if (!ctx.watchers) {
+      return "Watching is unavailable: no watcher registry was wired by this host.";
+    }
+    if (!ctx.projectDir) {
+      return "Watching is unavailable: no project directory was wired by this host.";
+    }
+    const command = args.command as string;
+    const result = await ctx.watchers.createCommand(host.sessionID, command, ctx.projectDir);
+    if (!result.ok) return `Watcher not created: ${result.error}`;
+    const w = result.watcher;
+    return (
+      `[watching] cmd: ${commandTargetLabel(w.command)}\n` +
+      `id: ${w.id}\n` +
+      `mode: one-shot - fires on the first exit 0, then auto-cancels\n` +
+      `lastExit: ${w.state.lastExit} (baseline exit code; 124 = the baseline run was killed at the timeout)\n\n` +
+      `The command re-runs about every ${ctx.watchers.pollSeconds}s and the first check already happened at registration - ` +
+      `the next run lands within ~${ctx.watchers.pollSeconds}s. ` +
+      `You will receive a system notification when the command exits 0; it carries the exit code and duration only. ` +
+      `State any handling policy for that notification now (e.g. what to do once the condition is met) - ` +
+      `the notification is the signal, not the data: re-run the command or read logs yourself when it arrives.`
     );
   },
 };
@@ -1314,7 +1458,7 @@ const watchCancelDef: ToolDef = {
   name: "watch_cancel",
   description: "Cancel one of this session's watchers by id. opencode-only.",
   args: {
-    id: z.string().describe("The watcher id from watch_create, watch_branch_create, or watch_list."),
+    id: z.string().describe("The watcher id from watch_create, watch_branch_create, watch_command_create, or watch_list."),
   },
   opencodeOnly: true,
   async execute(args, ctx, host) {
@@ -1351,6 +1495,18 @@ const watchCancelDef: ToolDef = {
  * the same change as chatEchoText and its tests.
  */
 
+/**
+ * Refusal text when the user disabled cross-session chat by config. Every
+ * chat tool returns this so the model can report the toggle to the user
+ * instead of concluding the feature is broken.
+ */
+function chatDisabledReply(): string {
+  return (
+    "[disabled] Cross-session chat is off (chat.enabled: false in the thatch config). " +
+    "Use thatch config_set { chat: { enabled: true } } to re-enable if the user asks."
+  );
+}
+
 /**
  * Resolves the chat identity for a tool call. opencode supplies the host
  * session; MCP hosts (host === undefined) declare theirs with the `as`
@@ -1362,6 +1518,9 @@ async function resolveChatIdentity(
   host: HostToolContext | undefined,
   as: unknown,
 ): Promise<{ ok: true; sessionID: string; kind: ChatHostKind } | { ok: false; error: string }> {
+  if (!chatEnabled(loadConfig().config)) {
+    return { ok: false, error: chatDisabledReply() };
+  }
   if (host) return { ok: true, sessionID: host.sessionID, kind: "opencode" };
   if (typeof as !== "string" || !as.trim()) {
     return {
@@ -1381,98 +1540,119 @@ async function resolveChatIdentity(
 }
 
 /** The zod arg shared by chat tools whose MCP mode needs the caller's
- *  registered name: MCP hosts have no session context, so identity is
- *  self-declared (the documented trust posture). opencode ignores it. */
+ *  assigned name: MCP hosts have no session context, so identity is passed
+ *  as the name the host's thatch hook printed (names are assigned by
+ *  thatch, never claimed). opencode ignores it. */
 function mcpIdentityArg() {
   return z.string().optional().describe(
-    "Your registered display name. Only needed on hosts without session " +
+    "Your assigned display name - the one your host's thatch hook printed, " +
+    "or that chat_register returned. Only needed on hosts without session " +
     "context (Claude Code, Cursor); opencode supplies your identity itself.",
   );
 }
 
-/** The degraded-delivery notice appended to MCP-path registration output:
- *  wake prompts are an opencode capability, so other hosts poll. */
+/**
+ * The delivery-model notes appended to registration output, one per host
+ * kind. Without these a session has no way to learn how mail reaches it,
+ * and defaults to sleep-polling its inbox. The wake prompt is an opencode
+ * capability; other hosts learn about pending mail at their next prompt.
+ */
+function wakeDeliveryNote(): string {
+  return "\nDelivery: you are woken automatically in this session when a message arrives - no need to poll (a busy session gets the wake when its turn ends).\n";
+}
+
 function degradedDeliveryNote(): string {
-  return "\nNote: wake-up delivery is opencode-only; on this host your inbox is checked at prompt time (chat_status, or the flush-tools hook line).\n";
+  return "\nDelivery: wake-up is opencode-only; on this host pending mail is reported at your next prompt (chat_read, chat_status, or the flush-tools hook line).\n";
 }
 
 /**
- * Joins the chat directory. Without a name, draws one at random from the
- * built-in name pool (whimsical, geek-flavored, guaranteed unused) - the
- * recommended path, since it cannot collide. With a name, claims it
- * case-insensitively; registration is the gate for both directions.
+ * Joins the chat directory (or reports/renews an existing registration).
+ * Names are assigned by thatch, never claimed: there is no name or topic
+ * argument, and registration is the gate for both directions. MCP hosts
+ * without a hook-printed name get a fresh per-conversation identity.
  */
 const chatRegisterDef: ToolDef = {
   name: "chat_register",
   description:
     "Join the cross-session chat directory so other sessions on this " +
     "machine can message you and you can message them (works from opencode, " +
-    "Claude Code, and Cursor). Omit the name to be assigned one from the " +
-    "built-in pool (recommended - cannot collide); pass a name to claim it " +
-    "instead, case-insensitively unique. Include a topic: it is what other " +
-    "sessions see in chat_list when deciding who to talk to. Pass an empty " +
-    "topic to clear it; omit it to keep the current one. Safe to call " +
-    "again - the same name is a no-op, a new name renames you, and a new " +
-    "topic updates it. Only top-level sessions should register; never " +
-    "register a sub-agent session.",
+    "Claude Code, and Cursor). Display names are assigned by thatch, never " +
+    "chosen: a slug plus a never-reused counter (the slug comes from your " +
+    "session title when one exists, otherwise from a built-in pool), so a " +
+    "name always refers to the same session and cannot be claimed by anyone " +
+    "else. Call with no arguments to join, to rejoin after chat_unregister, " +
+    "or to check your assigned name (opencode sessions are usually " +
+    "registered automatically already). On hosts without session context, " +
+    "pass `as` with the name your thatch hook printed for you, or omit it " +
+    "to be assigned a fresh identity for this conversation. Delivery: " +
+    "opencode sessions are woken automatically when mail arrives; on other " +
+    "hosts pending mail is reported at your next prompt. Only top-level " +
+    "sessions should register; never register a sub-agent session.",
   args: {
-    name: z.string().optional().describe(
-      "Custom display name. Omit to draw one from the built-in name pool.",
-    ),
-    topic: z.string().optional().describe(
-      "One line about what this session is working on (shown to other " +
-      "sessions in chat_list). Omit on re-register to keep the existing " +
-      "topic; pass an empty string to clear it.",
-    ),
     as: mcpIdentityArg(),
   },
   async execute(args, ctx, host) {
-    const custom = typeof args.name === "string" ? args.name : null;
-    const topic = typeof args.topic === "string" ? args.topic : null;
+    if (!chatEnabled(loadConfig().config)) return chatDisabledReply();
     const kind: ChatHostKind = host ? "opencode" : "mcp";
-    // MCP mode (host absent): the claimed name is the identity, stored
-    // under a deterministic synthetic session ID so a later conversation
-    // claiming the same name finds the same row.
-    const sessionID = host ? host.sessionID : mcpSessionID(custom!.trim());
-    if (custom !== null) {
-      const result = ctx.db.registerChatSession(sessionID, custom, ctx.defaultStore, topic, kind);
-      if (!result.ok) return `Registration failed: ${result.error}`;
+    // MCP reclaim: `as` must name an EXISTING registration - the identity
+    // printed by the host's thatch hook for this conversation. Names are
+    // assigned, so there is no claim path; a stale name from an old
+    // conversation still resolves to the same row it always did.
+    const asName = host ? null : typeof args.as === "string" ? args.as.trim() : null;
+    if (!host && !asName) {
+      // Fresh identity for this conversation: without session context or a
+      // hook-printed name there is nothing stable to anchor to, and a new
+      // conversation is a new peer anyway. Persistent identity on MCP hosts
+      // comes from the hook, which re-registers the same session ID and
+      // prints the assigned name each prompt.
+      const sessionID = `mcp_${crypto.randomUUID().replaceAll("-", "").slice(0, 12)}`;
+      const res = ctx.db.registerChatSession(sessionID, ctx.defaultStore, null, kind, null, detectWorktreeKind(ctx.projectDir));
+      if (!res.ok) return `Registration failed: ${res.error}`;
       return (
-        `[registered] ${custom.trim()}\n` +
+        `[registered] ${res.name}\n` +
         `session_id: ${sessionID}\n` +
         `project: ${ctx.defaultStore}\n` +
-        // The store returns the sanitized topic it kept, so the
-        // confirmation shows the roster value, not the raw input.
-        (result.topic ? `topic: ${result.topic}\n` : "") +
-        (host ? "" : degradedDeliveryNote()) +
+        degradedDeliveryNote() +
         `\n` +
-        `Other sessions can now message you by name with chat_send; use ` +
-        `chat_list to see who else is available.`
+        `This identity is fresh for this conversation. If your host runs the ` +
+        `thatch hook, its output names your persistent identity - use that ` +
+        `as the 'as' argument on other chat tools. Use chat_list to see who ` +
+        `is available.`
       );
     }
-    // Pool draw: MCP mode requires an explicit name anyway (the identity
-    // must be known to the caller), so a host-less draw is routed through
-    // the same assign path with the name the caller declared.
-    const mcpAs = host ? null : typeof args.as === "string" ? args.as.trim() : null;
-    if (!host && !mcpAs) {
-      return "Chat needs an identity: pass `name` (or `as`) with your display name, since this host has no session context to derive one from.";
+    if (!host) {
+      const row = ctx.db.findChatSession(asName!);
+      if (!row) {
+        return `No registered session named "${asName}" - names are assigned by thatch (your host hook prints yours); you cannot claim a new one.`;
+      }
+      return (
+        `[registered] ${row.name}\n` +
+        `session_id: ${row.session_id}\n` +
+        `project: ${row.project ?? ctx.defaultStore}\n` +
+        degradedDeliveryNote() +
+        `\n` +
+        `You were already registered. Other sessions can message you by name ` +
+        `with chat_send, or reach everyone at once with chat_broadcast; use ` +
+        `chat_list to see who else is available.`
+      );
     }
-    const drawSessionID = host ? host.sessionID : mcpSessionID(mcpAs!.trim());
-    const assigned = ctx.db.assignChatName(drawSessionID, ctx.defaultStore, topic, kind);
-    if (!assigned.ok) return `Registration failed: ${assigned.error}`;
-    const origin = assigned.drawn
-      ? "Your name was drawn from the built-in pool."
-      : "You were already registered - keeping your current name.";
+    // An explicit join clears the leave tombstone BEFORE registering:
+    // "I want back in" is the opposite of "I left", and the tombstone must
+    // not block the rejoin it is supposed to yield to. (register() treats
+    // a tombstoned opencode session as blocked; the tombstone is for the
+    // idle path, not for the model's explicit intent.)
+    ctx.db.clearChatLeaveTombstone?.(host.sessionID);
+    const res = ctx.db.registerChatSession(host.sessionID, ctx.defaultStore, null, kind, null, detectWorktreeKind(ctx.projectDir));
+    if (!res.ok) return `Registration failed: ${res.error}`;
     return (
-      `[registered] ${assigned.name}\n` +
-      `session_id: ${drawSessionID}\n` +
+      `[registered] ${res.name}\n` +
+      `session_id: ${host.sessionID}\n` +
       `project: ${ctx.defaultStore}\n` +
-      (assigned.topic ? `topic: ${assigned.topic}\n` : "") +
-      (host ? "" : degradedDeliveryNote()) +
+      wakeDeliveryNote() +
       `\n` +
-      `${origin} Other sessions can now message you by name with chat_send, ` +
-      `or reach everyone at once with chat_broadcast; use chat_list to see ` +
-      `who else is available.`
+      `Other sessions can now message you by name with chat_send, or reach ` +
+      `everyone at once with chat_broadcast; use chat_list to see who else ` +
+      `is available.`
     );
   },
 };
@@ -1493,7 +1673,7 @@ const chatListDef: ToolDef = {
     if (!identity.ok) return identity.error;
     const sessions = ctx.db.listChatSessions();
     if (sessions.length === 0) {
-      return "No sessions registered. chat_register opts in; you would be the first.";
+      return "No sessions registered. Sessions join the directory automatically on their first idle (opencode), or via chat_register - you would be the first.";
     }
     const unread = ctx.db.unreadChatCount(identity.sessionID);
     const lines = sessions.map((s) => {
@@ -1502,11 +1682,26 @@ const chatListDef: ToolDef = {
         ? isStale(s, CHAT_STALE_MINUTES) ? "idle" : "active"
         : isStale(s, CHAT_STALE_MINUTES) ? "stale" : "fresh";
       const project = s.project ? ` project:${s.project}` : "";
+      // The age turns the liveness bucket into a concrete last-check-in;
+      // the checkout kind tells sessions on a shared tree who sits in a
+      // worktree versus the project root.
+      const age = ` last seen ${humanAge(s.last_seen)}`;
+      const loc = s.worktree ? ` loc:${s.worktree}` : "";
       const topic = s.topic ? ` topic:${s.topic}` : "";
       const mailbox = self ? (unread > 0 ? ` ${unread} unread` : "") : "";
-      return `- ${s.name} (${s.session_id.slice(0, 12)})${project} ${liveness}${topic}${self ? " [you]" : ""}${mailbox}`;
+      return `- ${s.name} (${s.session_id.slice(0, 12)})${project}${age}${loc} ${liveness}${topic}${self ? " [you]" : ""}${mailbox}`;
     });
-    return `[chat] ${sessions.length} session${sessions.length === 1 ? "" : "s"} registered\n${lines.join("\n")}`;
+    // The name-stability note closes the roster because it answers the
+    // question a reader asking "is this the same X as before?" needs:
+    // assigned names are unique forever; only hook-anchored MCP identities
+    // can be revisited by an old name.
+    return (
+      `[chat] ${sessions.length} session${sessions.length === 1 ? "" : "s"} registered\n` +
+      `${lines.join("\n")}\n` +
+      `Names are assigned by thatch and never reused or reassigned, so the ` +
+      `same name is always the same session. A name whose row shows stale or ` +
+      `idle has not been seen recently.`
+    );
   },
 };
 
@@ -1571,7 +1766,11 @@ const chatReadDef: ToolDef = {
       const sender = renderChatParticipant(m.from_name, m.from_session);
       return `[from ${sender}, ${formatChatTimestamp(m.created_at)}] ${m.body}`;
     });
-    return `${lines.join("\n")}\n(${messages.length} message${messages.length === 1 ? "" : "s"}, marked read)`;
+    // The frame is the injection boundary: bodies are other agents' text,
+    // so the tool output marks everything between the fences as untrusted
+    // data (chatInboxFrame in prompts.ts). The persisted rows are
+    // untouched - the frame exists only in this output.
+    return `${chatInboxFrame(lines, messages.length)}\n(${messages.length} message${messages.length === 1 ? "" : "s"}, marked read)`;
   },
 };
 
@@ -1663,7 +1862,10 @@ const chatStatusDef: ToolDef = {
     }
     return (
       `[chat] registered as ${status.name}: ${status.pending} unread of ${status.total} total` +
-      (status.pending > 0 ? " - call chat_read to read them." : ".")
+      (status.pending > 0 ? " - call chat_read to read them." : ".") +
+      (host
+        ? " You are woken automatically when a message arrives - no need to poll."
+        : " Pending mail is reported at your next prompt; chat_read drains it.")
     );
   },
 };
@@ -1701,6 +1903,7 @@ export const TOOL_DEFS: ToolDef[] = [
   sessionGetDef,
   watchCreateDef,
   watchBranchCreateDef,
+  watchCommandCreateDef,
   watchListDef,
   watchCancelDef,
   chatRegisterDef,

package/src/tools.ts

@@ -18,6 +18,7 @@ export function createTools(
     extractionPayloadProvider?: CoreContext["extractionPayloadProvider"];
     drainExtractionQueue?: CoreContext["drainExtractionQueue"];
     watcherRegistry?: WatcherRegistry;
+    projectDir?: string;
   },
 ): Record<string, ReturnType<typeof tool>> {
   const ctx: CoreContext = {
@@ -27,6 +28,7 @@ export function createTools(
     extractionPayloadProvider: extensions?.extractionPayloadProvider,
     drainExtractionQueue: extensions?.drainExtractionQueue,
     watchers: extensions?.watcherRegistry,
+    projectDir: extensions?.projectDir,
   };
 
   const tools: Record<string, ReturnType<typeof tool>> = {};