@jeffober/thatch 0.2.1 → 0.2.3

package/src/runtime.ts

@@ -9,7 +9,6 @@ import {
   compactionContext,
   sessionStartReminder,
   recallNudge,
-  extractionNudge,
   extractionDirectPrompt,
   predictionNudge,
   behaviorNudge,
@@ -497,12 +496,6 @@ export async function createRuntime(input: {
   // degradation: nudges stay off for that session, but no crash).
   const compacting = new Set<string>();
 
-  // Per-session count of consecutive extraction nudges delivered without any
-  // memory_remember call in between. Drives nudge escalation: the agent gets
-  // a couple of polite chances, then the tone shifts to directive, then to
-  // all-caps shouting. Reset to 0 whenever the agent writes a memory.
-  const missedNudges = new Map<string, number>();
-
   // Parent-child session mapping for cross-session buffer drain. opencode
   // creates real child sessions with their own IDs for sub-agents; without
   // this map, a memory_remember call in a child (e.g. a background
@@ -531,24 +524,21 @@ export async function createRuntime(input: {
 
   // Parent sessions with an active direct-extraction child. When the parent
   // goes idle with pending tool interactions, the plugin creates a child
-  // session and prompts it directly through the host's prompt capability
-  // instead of injecting a nudge into the next user message. This set
-  // suppresses the nudge path
-  // while the child runs, and prevents re-triggering if the parent goes idle
-  // again before the child finishes. Cleared when the child goes idle, errors,
-  // or is deleted. If direct extraction fails, the set is cleared so the nudge
-  // path takes over as a fallback on the next chat.message.
+  // session and prompts it directly through the host's prompt capability.
+  // This set prevents re-triggering if the parent goes idle again before
+  // the child finishes. Cleared when the child goes idle, errors, or is
+  // deleted. If direct extraction fails, the set is cleared so the next
+  // idle retries - there is no model-facing nudge fallback.
   const extracting = new Set<string>();
 
   // Child session IDs created by triggerExtraction (direct extraction only).
   // The child idle handler uses this to distinguish plugin-created extraction
-  // children from task-dispatched sub-agents (code review specialists, the
-  // nudge-path fact-extractor, any model-dispatched task). Only extraction
-  // children get the full cleanup: buffer drain, session deletion, toast.
-  // Non-extraction children get claim-scoped completion (a no-op for a
-  // child that never fetched a payload) + missedNudges.reset so their
-  // sessions are not deleted out from under the task tool that dispatched
-  // them.
+  // children from task-dispatched sub-agents (code review specialists, any
+  // model-dispatched task). Only extraction children get the full cleanup:
+  // buffer drain, session deletion, toast. Non-extraction children get
+  // claim-scoped completion (a no-op for a child that never fetched a
+  // payload) so their sessions are not deleted out from under the task tool
+  // that dispatched them.
   const extractionChildren = new Set<string>();
 
   // Per-child-session extraction metrics for the toast notification. When the
@@ -876,7 +866,6 @@ export async function createRuntime(input: {
       // that crashed before its payload call) has no claim and must not
       // drop the accepted set - another extractor may hold it in flight.
       extraction.completeClaimed(sessionID);
-      missedNudges.delete(parentID);
       extracting.delete(parentID);
       childKinds.delete(sessionID);
       childToParent.delete(sessionID);
@@ -899,7 +888,6 @@ export async function createRuntime(input: {
       // fetched leaves its entries held; requeueStaleAccepted bounds the
       // linger.
       extraction.completeClaimed(sessionID);
-      missedNudges.delete(parentID);
     }
   };
 
@@ -912,12 +900,17 @@ export async function createRuntime(input: {
   // own idle event, and the finalize is idempotent if both paths race.
   const reconcileRestoredChildren = async () => {
     if (restoredChildren.size === 0) return;
+    // The reload window: how long to let the event pump repopulate the
+    // status map before judging a restored child "no longer running".
+    // Read at call time (not module load) so the test suite can shorten it
+    // per server() instance instead of waiting out the production 10s.
+    const windowMs = Number(process.env.THATCH_CHILD_RECONCILE_MS) || 10_000;
     await new Promise<void>((resolve) => {
-      const t = setTimeout(resolve, 10_000);
+      const t = setTimeout(resolve, windowMs);
       t.unref?.();
     });
     // Dispose (a v2 plugin reload or process exit) may have closed the db
-    // during the 10s window; finalizing into it would throw on the journal
+    // during the window; finalizing into it would throw on the journal
     // write. The reloaded instance's own reconciler owns the rows now.
     if (disposed) return;
     let live: Record<string, { type: string }> = {};
@@ -966,13 +959,16 @@ export async function createRuntime(input: {
 
   // Direct extraction: create a child session linked to the parent and prompt
   // it with the extraction payload. The child runs the fact-extractor skill,
-  // writes memories, and goes idle. The existing childToParent / snapshot
-  // drain machinery handles buffer cleanup. The nudge path is a fallback if
-  // this throws.
+  // writes memories, and goes idle. The childToParent / claim machinery
+  // handles buffer cleanup. If this throws, the entries stay pending and
+  // the next idle retries.
   //
-  // Does NOT call extraction.accept - entries stay in pending so consumeSnapshot
-  // can drain them by reference identity when the child writes a memory. The
-  // extracting set (not accept) suppresses the nudge in chat.message.
+  // Does NOT call extraction.accept - entries stay in pending. The child's
+  // payload fetch claims them (the fetch is the delivery record); entries
+  // that arrive after the fetch stay pending for the next idle. The
+  // extracting set (not accept) suppresses nothing any more - there is no
+  // model-facing extraction nudge - but it still gates re-triggering while
+  // a child runs.
   //
   // The child ID is added to extractionChildren so the idle handler can
   // distinguish plugin-created extraction children from task-dispatched
@@ -1060,7 +1056,6 @@ export async function createRuntime(input: {
   // same logic, so the bodies live here instead of inline in the hook.
   const toolMemoryRemember = async (sessionID: string, overwrite: unknown) => {
     extraction.consume(sessionID);
-    missedNudges.delete(sessionID);
     // A session that fetched its own payload (direct parent-side fetch or a
     // child's payload call) completes its claim when it writes a memory -
     // the write proves the delivered entries were processed.
@@ -1079,52 +1074,56 @@ export async function createRuntime(input: {
       // Complete the parent's accepted entries (the extractor confirmed
       // it is alive and saving). Completion is scoped to THIS child's
       // claimed delivery - the fetch IS the delivery record, so whatever
-      // the child received is consumed here and nothing else. Pending
-      // entries the child never received (post-fetch arrivals, or a child
-      // that never fetched) stay pending and re-nudge: no silent loss.
-      // (The old dispatch-time snapshot drain was either a no-op under
-      // claim semantics or a silent-loss vector for children that never
-      // fetched - removed September 2026. The journal's snapshot field
-      // remains for restart recovery.)
+      // the child received is consumed here and nothing else. Accepted
+      // entries the child never received stay held; requeueStaleAccepted
+      // bounds their linger: no silent loss, no whole-set wipe.
       extraction.completeClaimed(sessionID);
       journalChild(sessionID);
-      missedNudges.delete(parentID);
-      journalChild(sessionID);
-      missedNudges.delete(parentID);
     }
   };
   const toolExtractionDone = (sessionID: string, targetID?: string) => {
     const parentID = childToParent.get(sessionID);
     if (parentID) {
-      // The child's completion consumes its own claimed delivery. The
-      // whole-set fallback covers a child that acks without ever fetching
-      // (its payload call errored) - rare, and the ack is a deliberate
-      // processed signal, unlike the automatic idle path which is
-      // claim-scoped only.
-      if (!extraction.completeClaimed(sessionID)) {
-        extraction.completeAccepted(parentID);
-      }
-      missedNudges.delete(parentID);
+      // The child's completion consumes its own claimed delivery. A child
+      // that acks without ever fetching (its payload call errored, or it
+      // acked before fetching) has no claim - it processed NOTHING, so its
+      // ack must be a no-op here, never a whole-set drop: the accepted set
+      // may be another extractor's in-flight delivery. Held entries without
+      // a completer requeue via requeueStaleAccepted (15 min bound).
+      extraction.completeClaimed(sessionID);
       extraction.consume(sessionID);
     } else if (targetID && targetID !== sessionID) {
       // A completion ack for ANOTHER session - the fact-extractor sub-agent
       // naming its parent. v2 links no parentID on dispatched sessions
       // (SessionCreateInput has none), so childToParent cannot know this
       // relationship and the explicit session_id is the only signal that
-      // the target's accepted entries are accounted for. Without this
-      // branch the accepted queue lingers forever and a tool-dense session
-      // re-nudges every idle on never-draining exhaust. Completion is
-      // scoped to the child's claimed delivery; the whole-set fallback
-      // covers the no-claim case (a fetch that errored, or the MCP path
-      // where the file-backed queue was drained instead).
+      // the target's accepted entries are accounted for. Completion is
+      // scoped to the child's claimed delivery; a no-claim ack is a no-op
+      // for the same reason as above - the ack proves nothing was
+      // processed, so it must not drop entries another extractor holds.
+      // (The old whole-set completeAccepted fallback here was the
+      // accept-before-fetch interaction loss: a child acking - or mis-
+      // targeting - before its fetch wiped the accepted set the new
+      // extractor was about to claim, silently, every round. September
+      // 2026 dispatch-loop report, defect 1.)
+      extraction.completeClaimed(sessionID);
+    } else {
+      // A top-level session acking its own buffer. Two legitimate shapes:
+      // - The wrap-up checklist (/thatch/compact, /thatch/exit): the
+      //   parent fetched its OWN payload (recording a claim on itself),
+      //   processed it inline, and acks - a no-save run writes no memory,
+      //   so this ack is the only completion signal for that claim.
+      // - A legacy dispatch-time ack (MCP-style habit, or an in-flight
+      //   nudge from an older plugin version) with no claim: accept is
+      //   non-destructive - entries move to the holding area and a
+      //   crashed extractor's entries requeue via requeueStaleAccepted.
+      // Note the opencode plugin no longer ASKS the parent to ack after a
+      // dispatch - direct extraction (triggerExtraction at idle) owns the
+      // whole lifecycle; the accept branch is tolerance, not protocol.
       if (!extraction.completeClaimed(sessionID)) {
-        extraction.completeAccepted(targetID);
+        extraction.accept(sessionID);
       }
-      missedNudges.delete(targetID);
-    } else {
-      extraction.accept(sessionID);
     }
-    missedNudges.delete(sessionID);
   };
   const toolMemoryForget = (sessionID: string) => {
     const metrics = childMetrics.get(sessionID) ?? { new: 0, updated: 0, deleted: 0 };
@@ -1140,9 +1139,21 @@ export async function createRuntime(input: {
         // signal consumes only them (claim semantics). Without a fetcher
         // (no host session context) the fetch is a pure peek - legacy
         // behavior.
+        //
+        // An omitted (or self-named) target resolves to the fetcher's own
+        // session - which for a child is the WRONG key: the buffer belongs
+        // to the parent. When the plugin knows the parent link
+        // (childToParent - populated for plugin-created extraction
+        // children, and for v1 model-dispatched ones), retarget to the
+        // parent so the model never has to copy a session ID at all. v2
+        // model-dispatched sub-agents carry no parentID, so no link exists
+        // for them and the explicit-ID path remains the only signal.
+        const resolved = (fetcherID && targetID === fetcherID && childToParent.has(fetcherID))
+          ? childToParent.get(fetcherID)!
+          : targetID;
         const all = fetcherID
-          ? extraction.claim(targetID, fetcherID)
-          : [...extraction.peekAccepted(targetID), ...extraction.peek(targetID)];
+          ? extraction.claim(resolved, fetcherID)
+          : [...extraction.peekAccepted(resolved), ...extraction.peek(resolved)];
         if (all.length === 0) return null;
         return extraction.buildPayload(all, repo);
       },
@@ -1172,7 +1183,7 @@ export async function createRuntime(input: {
     },
 
     // 3. Tool buffering - feeds the extraction pipeline (direct extraction
-    //    via SDK or nudge fallback). Excluded tools:
+    //    via SDK at session idle). Excluded tools:
     //    - thatch_*: extracting facts from memory ops would echo the store
     //    - skill/task: meta-tools that orchestrate agent behavior (loading
     //      skills, dispatching sub-agents). Buffering them creates a feedback
@@ -1471,38 +1482,34 @@ export async function createRuntime(input: {
         // Best-effort. Version check failure must not block nudges.
       }
 
-      // Extraction nudge (fallback path). Skipped when the extracting set
-      // is active - that means a direct-extraction child session is running
-      // and the plugin is handling extraction via the SDK. The nudge fires
-      // here only when direct extraction was never triggered or threw.
-      // Accepted entries whose completion signal never came (crashed
-      // extractor, or a v2 dispatch whose ack never named the parent)
-      // requeue here so they are honestly re-extracted instead of lingering
-      // as silent loss.
-      extraction.requeueStaleAccepted();
+      // Extraction is plugin-driven on opencode (triggerExtraction at
+      // session idle) - there is deliberately NO model-facing extraction
+      // nudge here. The old nudge-driven handshake (model dispatches a
+      // sub-agent, parent acks with extraction_done, child fetches by
+      // copied session id) raced its own state machine: acks landed before
+      // fetches, no-claim completions wiped in-flight accepted sets, and
+      // mis-targeted ids made every transition a silent no-op - the
+      // buffered count then re-fired identically forever (the September
+      // 2026 dispatch-loop report, defects 1 and 2). Accepted entries whose
+      // completion signal never came (crashed extractor, a v2 dispatch
+      // whose ack never named the parent) requeue at the idle site, the
+      // only consumer of pending state now.
+      // Nudges skip injected prompts. A background-task completion, chat
+      // notification, or watcher notification arrives as a prompt whose
+      // parts are all synthetic - it is not user input, and nudging on it
+      // feeds the pipeline its own exhaust: an extractor sub-agent's
+      // completion would otherwise re-trigger the nudge machinery for the
+      // entries the handling turn itself queued (the circular-nudge
+      // pattern). Real user messages carry at least one non-synthetic
+      // part, and an empty-parts message keeps nudging (unchanged
+      // behavior).
+      if (output.parts.length > 0 && (output.parts as any[]).every((p) => p.synthetic)) return;
       // Task-dispatched sub-agent sessions may have restricted tool lists
-      // that exclude the thatch tools, and even where the tools exist the
-      // child is driven by its dispatch prompt, so nudges only burn "No
-      // tool named ..." error rounds or add noise there. Extraction
-      // children are excluded: they run with full tools and are driven by
-      // extractionDirectPrompt.
+      // that exclude the thatch tools, so recall/prediction/behavior
+      // nudges there only burn "No tool named ..." error rounds or add
+      // noise. Extraction children are excluded: they run with full tools
+      // and are driven by extractionDirectPrompt.
       if (childToParent.has(input.sessionID) && !extractionChildren.has(input.sessionID)) return;
-      if (!extracting.has(input.sessionID) && extraction.pending(input.sessionID)) {
-        const batch = extraction.peek(input.sessionID);
-        const missed = missedNudges.get(input.sessionID) ?? 0;
-        const text = extractionNudge(batch.length, missed, "thatch_memory_remember", input.sessionID);
-        missedNudges.set(input.sessionID, missed + 1);
-
-        output.parts.push({
-          id: `prt_thatch_${Math.random().toString(36).slice(2)}`,
-          sessionID: input.sessionID,
-          messageID: input.messageID ?? output.message.id,
-          type: "text",
-          text,
-          synthetic: true,
-        });
-        return;
-      }
 
       // No extraction pending - try the prompt-aware recall nudge. Extract
       // the user's prompt text from the message parts, embed it with the
@@ -1620,8 +1627,8 @@ export async function createRuntime(input: {
     // entries go back to pending. Only extraction children (created by
     // triggerExtraction, tracked in extractionChildren) get the full cleanup
     // (buffer drain, session deletion, toast). Task-dispatched sub-agents
-    // get the old behavior (completeAccepted + missedNudges.reset) so their
-    // sessions are not deleted out from under the task tool.
+    // get claim-scoped completion only, so their sessions are not deleted
+    // out from under the task tool.
     onEvent: async (event) => {
       // Pause alerts: the LLM blocked on a human decision. Both lines
       // publish these on the bus; v2's adapter translates them into the
@@ -1704,13 +1711,14 @@ export async function createRuntime(input: {
         if (parentID && sessionID) {
           // A child session went idle. Two cases:
           // - Extraction child (created by triggerExtraction, tracked in
-          //   extractionChildren): drain the parent's snapshot, fire a toast
-          //   with metrics, delete the child session, clean up all maps.
-          // - Task-dispatched sub-agent (code review specialist, nudge-path
-          //   fact-extractor, any model-dispatched task): complete the
-          //   parent's accepted entries and reset missedNudges. Do NOT drain
-          //   the buffer or delete the session - the task tool that
-          //   dispatched the sub-agent needs to read its output.
+          //   extractionChildren): fire a toast with metrics, delete the
+          //   child session, clean up all maps. Completion of the parent's
+          //   accepted entries is claim-scoped inside.
+          // - Task-dispatched sub-agent (code review specialist, any
+          //   model-dispatched task): complete what THIS child claimed via
+          //   its payload fetch, nothing more. Do NOT drain the buffer or
+          //   delete the session - the task tool that dispatched the
+          //   sub-agent needs to read its output.
           await finishExtractionChild(sessionID, parentID);
           return;
         }
@@ -1834,8 +1842,13 @@ export async function createRuntime(input: {
           })();
         }
         // Parent went idle - trigger direct extraction if there are pending
-        // tool interactions and no extraction is already running. Falls
-        // back to the nudge path on the next chat.message if this throws.
+        // tool interactions and no extraction is already running. This is
+        // the ONLY extraction trigger on opencode: no model-facing nudge
+        // exists any more. Stale accepted entries (a crashed extractor,
+        // a v2 dispatch whose ack never named the parent) requeue first so
+        // this same idle re-extracts them instead of leaving them held
+        // until the next idle.
+        extraction.requeueStaleAccepted();
         if (
           sessionID &&
           !compacting.has(sessionID) &&

package/src/skills.ts

@@ -71,6 +71,13 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-session-reflection",
     "thatch-coding-workflow",
     "thatch-plan-refinement",
+    "thatch-refine",
+    "thatch-refine-team-app",
+    "thatch-refine-personal",
+    "thatch-refine-shared-lib",
+    "thatch-refine-spike",
+    "thatch-refine-infra",
+    "thatch-refine-oss-contribution",
     "thatch-pr-description",
     "thatch-ticket-description",
     "thatch-split-overlarge-pr",

package/src/tool-defs.ts

@@ -24,8 +24,8 @@ import {
 import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
 import { predictionVerb, formatWhenLine, chatInboxFrame } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
-import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, type WatcherRegistry, type Watcher, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
-import { CHAT_STALE_MS, chatLiveness, humanAge, renderChatParticipant, sortChatRoster, splitChatRoster, type ChatHostKind } from "./chat";
+import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, commandTargetLabel, describeBaselineCheckRuns, type WatcherRegistry, type Watcher, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
+import { CHAT_STALE_MS, MAX_BODY_LEN, chatLiveness, humanAge, renderChatParticipant, sortChatRoster, splitChatRoster, type ChatHostKind } from "./chat";
 import { detectWorktreeKind } from "./git";
 
 // Near-duplicate thresholds for matcher/prediction/behavior dedup at
@@ -602,7 +602,9 @@ const getExtractionPayloadDef: ToolDef = {
     "the session_id from the extraction nudge to get the JSON payload " +
     "(interactions, projectStore, globalStore). Then run the " +
     "thatch-fact-extractor skill on the returned payload. Omit session_id " +
-    "when acting on the session you are running in.",
+    "when acting on the session you are running in. If you are an " +
+    "extraction child whose parent link the plugin knows, an omitted or " +
+    "self-named session_id resolves to the parent's queue automatically.",
   args: {
     session_id: z.string().optional().describe(
       "The session whose tool interactions are queued for extraction. " +
@@ -632,45 +634,47 @@ const getExtractionPayloadDef: ToolDef = {
 };
 
 /**
- * Extraction-buffer acknowledgment, with AMQP-style accept/complete roles.
+ * Extraction-buffer acknowledgment.
  *
- * Called in a PARENT session after dispatching the fact-extractor, it accepts
- * the buffer: entries move to a holding area and the nudge quiets, but they
- * are not dropped until the extractor completes. Called in a CHILD extractor
- * at the end of its run, it completes the entries THAT child claimed via its
- * payload fetch - never the whole accepted set, so a sibling sub-agent's
- * completion cannot drop another extractor's in-flight payload. Completion
- * includes no-save runs that write no memory. If the child errors or is
+ * In the fact-extractor sub-agent, call at the end of the run to mark the
+ * entries THIS child claimed via its payload fetch complete - never the
+ * whole accepted set, so a sibling sub-agent's completion cannot drop
+ * another extractor's in-flight payload. Completion includes no-save runs
+ * that write no memory. Pass session_id (the parent's) to drain the
+ * parent's file-backed queue on the MCP path. If the child errors or is
  * deleted before either signal, the host requeues the entries so the facts
  * are not lost.
  *
+ * On the MCP path the parent session may also call this after dispatching
+ * the fact-extractor, to reset the nudge escalation counter. The ack does
+ * NOT drain the parent's queue - a drain at ack time deleted the queue
+ * before the sub-agent's payload fetch (the accept-before-fetch loss); the
+ * queue is consumed by the extractor's completion instead.
+ *
  * The actual state changes happen in the host's post-tool hook
  * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) -
  * this tool's execute function is a no-op confirmation. The tool exists so
- * the model has a recognizable tool name to key on. In the MCP path the
- * file-backed queue is consumed on this call (or on any memory_remember),
- * which is durable across interruption because the queue persists on disk
- * until then.
+ * the model has a recognizable tool name to key on.
  *
- * The optional session_id parameter lets a sub-agent drain the PARENT's
- * file-backed queue on the MCP path, where the sub-agent's session ID
- * differs from the parent's and appendBatch's self-detection would drain
- * the wrong (empty) queue.
+ * On the opencode plugin path there is no parent ack any more: the plugin
+ * drives extraction end-to-end (triggerExtraction at session idle), so the
+ * model never runs the dispatch handshake. A parent-side extraction_done
+ * there is tolerated as a non-destructive accept (entries held, not
+ * dropped) for backward compatibility with an in-flight older nudge.
  */
 const extractionDoneDef: ToolDef = {
   name: "extraction_done",
   description:
-    "Acknowledge extraction-buffer work. In a parent session, call after " +
-    "dispatching the fact-extractor to a sub-agent: accepts the buffer " +
-    "(quiets the nudge) while keeping entries until the extractor completes. " +
-    "In the fact-extractor sub-agent, call at the end of the run to mark the " +
-    "entries complete, even when nothing was worth saving. Pass session_id " +
-    "when running as a sub-agent to drain the parent session's queue.",
+    "Acknowledge extraction-buffer work. In the fact-extractor sub-agent, " +
+    "call at the end of the run to mark the entries you claimed complete, " +
+    "even when nothing was worth saving. Pass session_id (the parent " +
+    "session's ID from the extraction nudge) to drain the parent's queue.",
   args: {
     session_id: z.string().optional().describe(
-      "The parent session's ID, when called from a sub-agent on the MCP " +
-      "path. Drains the parent's file-backed queue. Omit when called from " +
-      "the parent session itself (opencode path handles drain via hooks).",
+      "The parent session's ID, when called from a sub-agent. Drains the " +
+      "parent's file-backed queue (MCP path) and completes the entries " +
+      "this sub-agent claimed. Omit when called from the parent session " +
+      "itself.",
     ),
   },
   async execute(args, ctx) {
@@ -1523,12 +1527,14 @@ const watchCreateDef: ToolDef = {
     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;
+    const ciNote = w.events.includes("pr_ci") ? describeBaselineCheckRuns(w.state.checkRuns, w.state.headSha) : null;
     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` +
+      (ciNote ? `${ciNote}\n\n` : "") +
       `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. ` +
@@ -1636,6 +1642,7 @@ const watchBranchCreateDef: ToolDef = {
     );
     if (!result.ok) return `Watcher not created: ${result.error}`;
     const w = result.watcher;
+    const ciNote = w.events.includes("branch_ci") ? describeBaselineCheckRuns(w.state.checkRuns, w.state.headSha) : null;
     return (
       `[watching] ${w.repo}@${w.branch}\n` +
       `id: ${w.id}\n` +
@@ -1643,6 +1650,7 @@ const watchBranchCreateDef: ToolDef = {
       (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` +
+      (ciNote ? `${ciNote}\n\n` : "") +
       `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. ` +
@@ -2039,7 +2047,7 @@ const chatSendDef: ToolDef = {
     "sessions on other machines cannot be reached.",
   args: {
     to: z.string().describe("Recipient display name (see chat_list)."),
-    body: z.string().describe("Message body. Keep it short and self-contained - the recipient may lack your context."),
+    body: z.string().describe(`Message body, at most ${MAX_BODY_LEN} characters (longer is refused, not truncated). Keep it short and self-contained - the recipient may lack your context.`),
     as: mcpIdentityArg(),
   },
   async execute(args, ctx, host) {
@@ -2144,8 +2152,8 @@ const chatBroadcastDef: ToolDef = {
     "turn on it.",
   args: {
     body: z.string().describe(
-      "Message body, delivered to every other registered session. Keep it " +
-      "short and self-contained - the recipients may lack your context.",
+      `Message body, delivered to every other registered session, at most ${MAX_BODY_LEN} characters ` +
+      "(longer is refused, not truncated). Keep it short and self-contained - the recipients may lack your context.",
     ),
     as: mcpIdentityArg(),
   },

package/src/watchers.ts

@@ -703,6 +703,37 @@ export async function fetchBranchState(gh: GhRunner, repo: string, branch: strin
 /** At most this many events per watcher per cycle; comment floods collapse. */
 const MAX_EVENTS_PER_DIFF = 10;
 
+/**
+ * Describes the check runs already present on a head at watcher creation,
+ * for the registration response. The diff only fires on a not-completed ->
+ * completed transition, so runs that are ALREADY completed in the baseline
+ * can never produce a CI event for this head - a watcher registered after a
+ * fast CI (one that finishes in under a minute) is silently dead for the
+ * head it was meant to cover. Saying so at creation lets the caller just
+ * read the result instead of waiting on a notification that cannot come.
+ * Returns null when there is nothing to say: no runs yet, or some still
+ * running (those WILL transition and notify).
+ */
+export function describeBaselineCheckRuns(checkRuns: Record<string, CheckRunRef>, headSha: string): string | null {
+  const runs = Object.values(checkRuns);
+  if (runs.length === 0) return null;
+  const completed = runs.filter((r) => r.status === "completed");
+  if (completed.length < runs.length) return null;
+  const counts = new Map<string, number>();
+  for (const r of completed) {
+    const key = r.conclusion ?? "no conclusion";
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const breakdown = [...counts.entries()].map(([k, n]) => `${n} ${k}`).join(", ");
+  return (
+    `NOTE: all ${completed.length} check run${completed.length === 1 ? "" : "s"} on ${headSha.slice(0, 7)} ` +
+    `${completed.length === 1 ? "has" : "have"} already completed (${breakdown}). ` +
+    `CI events fire only on a running -> completed transition, so this watcher will NOT notify for this head's CI - ` +
+    `read the result now (gh api repos/<owner>/<repo>/commits/${headSha.slice(0, 7)}/check-runs) ` +
+    `rather than waiting. To catch a push's CI, register the watcher BEFORE pushing.`
+  );
+}
+
 /**
  * Shared check-run diff: emits one event per run that reaches a completed
  * status. A run that was already completed before produces nothing; a run