@jeffober/thatch 0.1.43 → 0.1.44

package/src/setup.ts

@@ -90,53 +90,111 @@ function writeMcpConfig(path: string, thatchBin: string): void {
 // CLAUDE.md - append thatch instructions (idempotent)
 // ---------------------------------------------------------------------------
 
+/**
+ * Sentinel delimiters for the thatch instructions block. HTML comments, not
+ * prose: agents edit these files constantly (and normalize punctuation while
+ * they are in there), so any prose sentence used as a delimiter eventually
+ * stops matching and the block becomes un-updatable. Sentinels survive prose
+ * edits because they are not prose.
+ */
+export const THATCH_BEGIN = "<!-- thatch:begin -->";
+export const THATCH_END = "<!-- thatch:end -->";
+
+/**
+ * Legacy delimiters, used by installs before the sentinels: prose sentences
+ * from the instructions themselves. Detection-only - they exist so setup can
+ * find and migrate (or heal) pre-sentinel blocks. Do not write new blocks
+ * with them; any edit to the file's prose breaks the match.
+ */
 const THATCH_MARKER = "# Persistence\n\nThatch provides persistent memory across Claude Code sessions.";
 const THATCH_END_MARKER = '"Forget X" - `memory_recall` to find it, then `memory_forget`.';
 const CURSOR_MARKER = "# Persistence\n\nThatch provides persistent memory across Cursor sessions.";
 const CURSOR_END_MARKER = THATCH_END_MARKER;
 
 /**
- * Idempotently append (or replace) a block of instructions in a markdown file.
- * The block is delimited by startMarker and endMarker so re-running setup
- * updates drifted content without clobbering surrounding text.
+ * The instructions' last line (punctuation-insensitive tail test): the
+ * "heal" rule may only consume file tail when the corruption is the known
+ * kind - the legacy block running to EOF. Without this guard, a broken
+ * legacy block followed by unrelated user content would eat that content.
  */
+const INSTRUCTIONS_TAIL_SENTINEL = "memory_forget";
+
 function appendBlock(
   path: string,
   instructions: string,
-  startMarker: string,
-  endMarker: string,
+  legacyStartMarker: string,
+  legacyEndMarker: string,
 ): void {
-  if (existsSync(path)) {
-    const existing = readFileSync(path, "utf8");
-    if (existing.includes(startMarker)) {
-      const startIdx = existing.indexOf(startMarker);
-      if (startIdx >= 0) {
-        const endIdx = existing.indexOf(endMarker, startIdx);
-        if (endIdx >= 0) {
-          const afterEnd = endIdx + endMarker.length;
-          const updated = existing.slice(0, startIdx) + instructions.trimEnd() + existing.slice(afterEnd);
-          writeFileSync(path, updated);
-          return;
-        }
-      }
-      // Marker found but block boundaries didn't parse - leave it alone.
+  const block = `${THATCH_BEGIN}\n${instructions.trimEnd()}\n${THATCH_END}`;
+
+  if (!existsSync(path)) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, block + "\n");
+    return;
+  }
+
+  const existing = readFileSync(path, "utf8");
+
+  // Current format: replace between the sentinels.
+  if (existing.includes(THATCH_BEGIN)) {
+    const beginIdx = existing.indexOf(THATCH_BEGIN);
+    const endIdx = existing.indexOf(THATCH_END, beginIdx);
+    if (endIdx >= 0) {
+      const afterEnd = endIdx + THATCH_END.length;
+      writeFileSync(path, existing.slice(0, beginIdx) + block + existing.slice(afterEnd));
       return;
     }
-    // Append to existing file.
-    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
-    writeFileSync(path, existing + sep + instructions);
-  } else {
-    mkdirSync(join(path, ".."), { recursive: true });
-    writeFileSync(path, instructions);
+    // Begin without end: the sentinel block itself was corrupted. Same heal
+    // rule as the legacy broken case below.
+    healBrokenBlock(path, existing, beginIdx, block);
+    return;
   }
+
+  // Legacy format: prose-sentence delimiters from a pre-sentinel install.
+  if (existing.includes(legacyStartMarker)) {
+    const startIdx = existing.indexOf(legacyStartMarker);
+    const endIdx = existing.indexOf(legacyEndMarker, startIdx);
+    if (endIdx >= 0) {
+      // Intact legacy block: swap the whole span for the sentinel block.
+      const afterEnd = endIdx + legacyEndMarker.length;
+      writeFileSync(path, existing.slice(0, startIdx) + block + existing.slice(afterEnd));
+      return;
+    }
+    // Broken legacy block (the observed corruption: an agent edit normalized
+    // the prose - hyphens became em dashes - so the end sentence no longer
+    // matches). Heal by replacing from the legacy start to EOF, but only
+    // when the tail is recognizably the instructions; otherwise leave it
+    // for manual repair.
+    healBrokenBlock(path, existing, startIdx, block);
+    return;
+  }
+
+  // No thatch block yet: append.
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  writeFileSync(path, existing + sep + block + "\n");
+}
+
+/**
+ * Replaces everything from `startIdx` to EOF with the fresh sentinel block,
+ * but only when the corrupted tail is recognizably the thatch instructions
+ * (the tail test). Reports via return value so callers can surface a
+ * skipped heal; the file is left untouched when the guard does not pass.
+ */
+function healBrokenBlock(path: string, existing: string, startIdx: number, block: string): boolean {
+  const tail = existing.slice(startIdx).slice(-400);
+  if (!tail.includes(INSTRUCTIONS_TAIL_SENTINEL)) {
+    return false;
+  }
+  writeFileSync(path, existing.slice(0, startIdx) + block + "\n");
+  return true;
 }
 
 function appendInstructions(path: string): void {
-  appendBlock(path, claudeInstructions() + "\n", THATCH_MARKER, THATCH_END_MARKER);
+  appendBlock(path, claudeInstructions(), THATCH_MARKER, THATCH_END_MARKER);
 }
 
 function appendCursorInstructions(path: string): void {
-  appendBlock(path, cursorInstructions() + "\n", CURSOR_MARKER, CURSOR_END_MARKER);
+  appendBlock(path, cursorInstructions(), CURSOR_MARKER, CURSOR_END_MARKER);
 }
 
 // ---------------------------------------------------------------------------
@@ -153,6 +211,7 @@ interface SettingsJson {
     SessionStart?: { hooks: HookEntry[] }[];
     PostToolBatch?: { hooks: HookEntry[] }[];
     UserPromptSubmit?: { hooks: HookEntry[] }[];
+    Stop?: { hooks: HookEntry[] }[];
   };
   [key: string]: any;
 }
@@ -178,6 +237,12 @@ function writeHooks(path: string, thatchBin: string): void {
   // falls back to the static write-nudge. Either output is transcript-visible
   // since UserPromptSubmit adds stdout to context.
   const flushCmd = `${thatchBin} flush-tools`;
+  // Stop fires when the agent turn ends. chat-notify emits a Stop-hook
+  // additionalContext reminder when chat mail is unread - the turn
+  // continues so the model can read its mail, the Claude Code analog of
+  // opencode's poller wake. The host's loop protections (stop_hook_active,
+  // the 8-consecutive cap) plus the delivered stamp bound repeats.
+  const notifyCmd = `${thatchBin} chat-notify`;
 
   settings.hooks.SessionStart = replaceThatchHooks(
     settings.hooks.SessionStart ?? [],
@@ -191,6 +256,10 @@ function writeHooks(path: string, thatchBin: string): void {
     settings.hooks.UserPromptSubmit ?? [],
     flushCmd,
   );
+  settings.hooks.Stop = replaceThatchHooks(
+    settings.hooks.Stop ?? [],
+    notifyCmd,
+  );
 
   mkdirSync(join(path, ".."), { recursive: true });
   writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
@@ -311,6 +380,92 @@ export function setupClaudeCode(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Global MCP registration (Claude Code)
+// ---------------------------------------------------------------------------
+
+/**
+ * Outcome of trying to register the thatch MCP server with the `claude`
+ * CLI. `registered` and `already-registered` mean the MCP server is
+ * usable; `claude-missing` and `failed` mean the caller must print
+ * `manualCommand` for the user to run by hand.
+ */
+export interface ClaudeMcpRegistration {
+  status: "registered" | "already-registered" | "claude-missing" | "failed";
+  manualCommand: string;
+  detail: string;
+}
+
+export interface CommandRunResult {
+  exitCode: number;
+}
+
+async function defaultCommandRun(argv: string[]): Promise<CommandRunResult> {
+  const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe" });
+  await proc.exited;
+  return { exitCode: proc.exitCode ?? 1 };
+}
+
+/**
+ * Runs `claude mcp add --scope user` on the user's behalf - the
+ * global-setup counterpart of writing .mcp.json, which project-local
+ * setup does directly. ~/.claude.json is not hand-writable (the reason
+ * setup used to print the command instead), so the claude CLI does it.
+ *
+ * Idempotent and non-destructive: an existing registration is detected
+ * via `claude mcp get thatch` (exit 1 when absent) and left untouched,
+ * whatever scope or binary it points at. `claudeBin` and `run` are
+ * injectable for tests; when `claude` is missing the result says so and
+ * the manual command stands in.
+ */
+export async function registerClaudeMcpServer(
+  thatchBin: string,
+  opts: {
+    claudeBin?: string | null;
+    run?: (argv: string[]) => Promise<CommandRunResult>;
+  } = {},
+): Promise<ClaudeMcpRegistration> {
+  const claudeBin = opts.claudeBin === undefined ? Bun.which("claude") : opts.claudeBin;
+  const manualCommand = `claude mcp add --scope user thatch -- ${thatchBin} mcp`;
+  const run = opts.run ?? defaultCommandRun;
+  if (!claudeBin) {
+    return {
+      status: "claude-missing",
+      manualCommand,
+      detail: "claude CLI not found on PATH",
+    };
+  }
+  try {
+    const get = await run([claudeBin, "mcp", "get", "thatch"]);
+    if (get.exitCode === 0) {
+      return {
+        status: "already-registered",
+        manualCommand,
+        detail: "a thatch MCP registration already exists (`claude mcp get thatch` to inspect)",
+      };
+    }
+    const add = await run([claudeBin, "mcp", "add", "--scope", "user", "thatch", "--", thatchBin, "mcp"]);
+    if (add.exitCode === 0) {
+      return {
+        status: "registered",
+        manualCommand,
+        detail: "registered with `claude mcp add --scope user`",
+      };
+    }
+    return {
+      status: "failed",
+      manualCommand,
+      detail: "`claude mcp add` exited non-zero",
+    };
+  } catch (err) {
+    return {
+      status: "failed",
+      manualCommand,
+      detail: `claude invocation failed: ${err}`,
+    };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Cursor setup - .cursor/mcp.json, AGENTS.md, .cursor/hooks.json, skills
 // ---------------------------------------------------------------------------
@@ -394,21 +549,29 @@ function writeCursorHooks(path: string, thatchBin: string): void {
   // beforeSubmitPrompt is Cursor's UserPromptSubmit equivalent. Drains the
   // queue and prints the extraction nudge as JSON additional_context.
   const flushCmd = `${thatchBin} flush-tools --json`;
+  // stop fires when the agent loop ends. chat-notify emits followup_message
+  // (auto-submitted by Cursor as the next user message) when chat mail is
+  // unread - the Cursor analog of opencode's poller wake. loop_limit bounds
+  // consecutive auto-followups; reading the mail naturally terminates the
+  // loop (unread drops to 0), the limit is the backstop.
+  const notifyCmd = `${thatchBin} chat-notify`;
 
   config.hooks.sessionStart = replaceCursorThatchHooks(config.hooks.sessionStart ?? [], sessionStartCmd);
   config.hooks.postToolUse = replaceCursorThatchHooks(config.hooks.postToolUse ?? [], bufferCmd);
   config.hooks.beforeSubmitPrompt = replaceCursorThatchHooks(config.hooks.beforeSubmitPrompt ?? [], flushCmd);
+  config.hooks.stop = replaceCursorThatchHooks(config.hooks.stop ?? [], notifyCmd, 3);
 
   mkdirSync(join(path, ".."), { recursive: true });
   writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
 }
 
 function replaceCursorThatchHooks(
-  entries: { command: string }[],
+  entries: { command: string; loop_limit?: number }[],
   command: string,
-): { command: string }[] {
+  loopLimit?: number,
+): { command: string; loop_limit?: number }[] {
   const filtered = entries.filter((e) => !e.command?.includes("thatch"));
-  filtered.push({ command });
+  filtered.push(loopLimit === undefined ? { command } : { command, loop_limit: loopLimit });
   return filtered;
 }
 
@@ -484,12 +647,19 @@ export type SetupStatus =
 
 type FileCheck = "installed" | "absent" | "broken";
 
-function checkInstructionsFile(path: string, startMarker: string, endMarker: string): FileCheck {
+function checkInstructionsFile(path: string, legacyStartMarker: string, legacyEndMarker: string): FileCheck {
   if (!existsSync(path)) return "absent";
   const content = readFileSync(path, "utf8");
-  const startIdx = content.indexOf(startMarker);
+  // Current format: sentinel-delimited. Begin without end is the same
+  // corruption class as the legacy broken case.
+  const sentinelIdx = content.indexOf(THATCH_BEGIN);
+  if (sentinelIdx !== -1) {
+    return content.indexOf(THATCH_END, sentinelIdx) === -1 ? "broken" : "installed";
+  }
+  // Legacy format: prose-sentence delimiters.
+  const startIdx = content.indexOf(legacyStartMarker);
   if (startIdx === -1) return "absent";
-  const endIdx = content.indexOf(endMarker, startIdx);
+  const endIdx = content.indexOf(legacyEndMarker, startIdx);
   if (endIdx === -1) return "broken";
   return "installed";
 }

package/src/tool-defs.ts

@@ -20,7 +20,7 @@ import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } fr
 import { predictionVerb, chatInboxFrame } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
 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 { CHAT_STALE_MS, chatLiveness, humanAge, renderChatParticipant, splitChatRoster, type ChatHostKind } from "./chat";
 import { detectWorktreeKind } from "./git";
 
 // Near-duplicate thresholds for matcher/prediction/behavior dedup at
@@ -86,6 +86,12 @@ export interface CoreContext {
   /** Injectable command runner for notify_user. Defaults to Bun.spawn.
    *  Tests inject a mock so notifications never actually fire or speak. */
   spawner?: Spawner;
+  /** Resolves the calling MCP server process's own chat identity from its
+   *  parent process id (the hook-recorded Claude Code anchor). Wired on the
+   *  MCP path only; the model cannot influence it, which is what makes it
+   *  authoritative over the caller-claimed `as` argument. Returns null when
+   *  no fresh mapping exists (Cursor, unknown server process). */
+  chatDerivedIdentity?: () => string | null;
 }
 
 /**
@@ -904,7 +910,7 @@ 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)`,
+    `  autoRegister: ${prefs?.autoRegister ?? "<unset>"} (default: on; opencode sessions join the chat directory on their first idle event)`,
   ].join("\n");
 }
 
@@ -977,7 +983,8 @@ const configSetDef: ToolDef = {
       ),
       autoRegister: z.boolean().optional().describe(
         "Whether opencode sessions join the chat directory automatically " +
-        "(assigned names). Unset or true is the default; false restores " +
+        "(assigned names, on the session's first idle event - not at " +
+        "startup). Unset or true is the default; false restores " +
         "opt-in joining via chat_register only.",
       ),
     }).optional().describe(
@@ -1129,6 +1136,13 @@ const sessionSearchDef: ToolDef = {
   },
   opencodeOnly: true,
   async execute(args) {
+    // The schema marks query required, but a caller that cross-wired this
+    // tool with another server's search (different param name) gets args
+    // without it - fail with a usage line instead of a raw dereference
+    // crash ("undefined is not an object (evaluating 'query.toLowerCase')").
+    if (typeof args.query !== "string" || !args.query.trim()) {
+      return `Usage: session_search requires a "query" string (e.g. {"query": "PR 7310 review"}); optional: regex, session_id, limit.`;
+    }
     const dbPath = resolveOpencodeDbPath();
     if (!dbPath) {
       return "Session search is unavailable: no opencode database was found (set OPENCODE_DB to point at one).";
@@ -1181,6 +1195,9 @@ const sessionGetDef: ToolDef = {
   },
   opencodeOnly: true,
   async execute(args) {
+    if (typeof args.id !== "string" || !args.id.trim()) {
+      return `Usage: session_get requires an "id" - a part id (prt_...) or message id (msg_...) from session_search results.`;
+    }
     const dbPath = resolveOpencodeDbPath();
     if (!dbPath) {
       return "Session retrieval is unavailable: no opencode database was found (set OPENCODE_DB to point at one).";
@@ -1508,10 +1525,13 @@ function chatDisabledReply(): string {
 }
 
 /**
- * Resolves the chat identity for a tool call. opencode supplies the host
- * session; MCP hosts (host === undefined) declare theirs with the `as`
- * argument, which must name a registered session. Returns either a usable
- * identity or the failure text the tool should return.
+ * Resolves the chat identity for a tool call, by priority:
+ *  1. opencode supplies the host-injected session (cannot be claimed).
+ *  2. The MCP server's derived identity (hook-recorded host-pid mapping on
+ *     Claude Code - the process fact the model cannot spoof).
+ *  3. The caller-claimed `as` argument (Cursor; documented limit).
+ * Returns either a usable identity or the failure text the tool should
+ * return.
  */
 async function resolveChatIdentity(
   ctx: CoreContext,
@@ -1522,6 +1542,11 @@ async function resolveChatIdentity(
     return { ok: false, error: chatDisabledReply() };
   }
   if (host) return { ok: true, sessionID: host.sessionID, kind: "opencode" };
+  const derived = ctx.chatDerivedIdentity?.() ?? null;
+  if (derived) {
+    const row = ctx.db.findChatSession(derived);
+    if (row) return { ok: true, sessionID: row.session_id, kind: row.host_kind };
+  }
   if (typeof as !== "string" || !as.trim()) {
     return {
       ok: false,
@@ -1529,14 +1554,14 @@ async function resolveChatIdentity(
         "Chat needs an identity: pass `as` with your registered display name (MCP hosts have no session context).",
     };
   }
-  const row = ctx.db.findChatSession(as.trim());
-  if (!row) {
+  const claimed = ctx.db.findChatSession(as.trim());
+  if (!claimed) {
     return {
       ok: false,
       error: `No registered session named "${as.trim()}" - call chat_register first (or chat_status to check).`,
     };
   }
-  return { ok: true, sessionID: row.session_id, kind: row.host_kind };
+  return { ok: true, sessionID: claimed.session_id, kind: claimed.host_kind };
 }
 
 /** The zod arg shared by chat tools whose MCP mode needs the caller's
@@ -1577,9 +1602,9 @@ const chatRegisterDef: ToolDef = {
     "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). 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 " +
+    "chosen: a name drawn from a built-in pool plus a never-reused counter, " +
+    "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, " +
@@ -1594,6 +1619,27 @@ const chatRegisterDef: ToolDef = {
   async execute(args, ctx, host) {
     if (!chatEnabled(loadConfig().config)) return chatDisabledReply();
     const kind: ChatHostKind = host ? "opencode" : "mcp";
+    // Derived identity (hook-recorded host-pid mapping): the conversation is
+    // already anchored by its own hooks, so this is an idempotent ensure -
+    // the same contract the hook path uses. An explicit join clears the
+    // leave tombstone first: "I want back in" is the model's explicit
+    // intent, and the tombstone must not override it.
+    const derived = !host ? ctx.chatDerivedIdentity?.() ?? null : null;
+    if (derived) {
+      ctx.db.clearChatLeaveTombstone?.(derived);
+      const res = ctx.db.registerChatSession(derived, ctx.defaultStore, null, kind, null, detectWorktreeKind(ctx.projectDir));
+      if (!res.ok) return `Registration failed: ${res.error}`;
+      return (
+        `[registered] ${res.name}\n` +
+        `session_id: ${derived}\n` +
+        `project: ${ctx.defaultStore}\n` +
+        degradedDeliveryNote() +
+        `\n` +
+        `Your identity comes from your host's hook anchor, so it is stable across prompts. ` +
+        `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.`
+      );
+    }
     // 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
@@ -1676,11 +1722,10 @@ const chatListDef: ToolDef = {
       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) => {
+    const { active, stale } = splitChatRoster(sessions);
+    const line = (s: (typeof sessions)[number]) => {
       const self = s.session_id === identity.sessionID;
-      const liveness = s.host_kind === "mcp"
-        ? isStale(s, CHAT_STALE_MINUTES) ? "idle" : "active"
-        : isStale(s, CHAT_STALE_MINUTES) ? "stale" : "fresh";
+      const liveness = chatLiveness(s);
       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
@@ -1690,14 +1735,26 @@ const chatListDef: ToolDef = {
       const topic = s.topic ? ` topic:${s.topic}` : "";
       const mailbox = self ? (unread > 0 ? ` ${unread} unread` : "") : "";
       return `- ${s.name} (${s.session_id.slice(0, 12)})${project}${age}${loc} ${liveness}${topic}${self ? " [you]" : ""}${mailbox}`;
-    });
+    };
+    const sections: string[] = [];
+    if (active.length > 0) {
+      sections.push(`# Active Sessions\n\n${active.map(line).join("\n")}`);
+    }
+    if (stale.length > 0) {
+      sections.push(
+        `# Stale Sessions\n\n` +
+          `_These sessions have missed their heartbeat for over ${Math.round(CHAT_STALE_MS / 1000)} seconds. ` +
+          `Their harnesses may no longer be running (stopped, or the machine slept); mail waits until they resume._\n\n` +
+          `${stale.map(line).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` +
+      `[chat] ${sessions.length} session${sessions.length === 1 ? "" : "s"} registered\n\n` +
+      `${sections.join("\n\n")}\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.`
@@ -1728,11 +1785,21 @@ const chatSendDef: ToolDef = {
     // The store returns the recipient it resolved, so no second lookup can
     // race a concurrent unregister between send and confirmation.
     const { name, session_id } = result.recipient;
+    // State the recipient's ACTUAL liveness: the boilerplate "waits until
+    // idle" is only true for a live host. A stale recipient's harness is
+    // probably gone - say so, so the sender can reroute instead of waiting
+    // on a wake that will never fire.
+    const row = ctx.db.findChatSession(session_id);
+    const liveness = row ? chatLiveness(row) : "stale";
+    const delivery =
+      liveness === "fresh"
+        ? `The recipient is fresh (last seen ${row ? humanAge(row.last_seen) : "just now"}) and will be woken when its session goes idle.`
+        : liveness === "active"
+          ? `The recipient is an MCP-host session; it sees this message at its next prompt.`
+          : `NOTE: the recipient is STALE (last seen ${row ? humanAge(row.last_seen) : "unknown"}). Its harness may no longer be running - the message waits unread until that session resumes, and no wake will fire meanwhile. If you meant a different session, check chat_list and resend.`;
     return (
       `[sent] to ${name} (${session_id.slice(0, 12)})\n\n` +
-      `The recipient is nudged when its session is idle. If its host process ` +
-      `is gone (stale in chat_list), the message waits unread - a dead ` +
-      `session never reads it.`
+      `${delivery}`
     );
   },
 };
@@ -1805,7 +1872,7 @@ const chatBroadcastDef: ToolDef = {
     "Broadcast one message to every other registered session on this " +
     "machine at once - for announcements and open questions (\"which of " +
     "you is working on X?\", \"main just moved, rebase if you are based on " +
-    "it\"). Stale opencode sessions (dead host processes) are skipped and " +
+    "it\"). Stale opencode sessions (harness stopped heartbeating) are skipped and " +
     "reported, since they will never read the mail; MCP sessions receive " +
     "it at their next prompt. Each recipient is woken like any chat " +
     "message, so broadcast sparingly: every live session spends a model " +
@@ -1858,6 +1925,13 @@ const chatStatusDef: ToolDef = {
     if (!identity.ok) return identity.error;
     const status = ctx.db.chatMessageStatus(identity.sessionID);
     if (!status.registered) {
+      // Distinguish "not YET registered" from "broken": opencode sessions
+      // auto-register when the turn goes idle, so a mid-turn check here is
+      // normal and must not read as a failure: a bare "Not registered" is
+      // indistinguishable from auto-registration being broken.
+      if (host) {
+        return "Not registered YET - this session auto-registers when the turn goes idle (or join now with chat_register).";
+      }
       return "Not registered - call chat_register to join the cross-session chat directory.";
     }
     return (