@jeffober/thatch 0.1.43 → 0.1.44

package/src/commands.ts

@@ -24,19 +24,27 @@ export const EXIT_READY_TOKEN = "THATCH_EXIT_READY";
  */
 
 const sharedChecklist = `1. Flush pending persistence. Call thatch_get_extraction_payload; if it returns buffered tool interactions, process them now (write any memories worth keeping), then call thatch_extraction_done to mark them complete. Complete any memory writes you promised earlier but have not made.
-2. Check for loose ends. Review the conversation for todos, follow-ups, or open questions raised earlier that were never addressed, and surface anything the user should address before the wrap-up completes.
+2. Check for loose ends. Review the conversation for todos, follow-ups, or open questions raised earlier that were never addressed, and surface anything the user should address before the wrap-up completes.`;
 
-Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:`;
+const userMessageSection = `# User Message
+
+$ARGUMENTS
+
+(That section carries the text typed after the command. When it is empty, treat the user message as n/a - the command was run bare.)`;
 
 const COMPACT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then compact if clear
 ---
-$ARGUMENTS
+${userMessageSection}
+
+# Pre-compact wrap-up
 
-Pre-compaction wrap-up. Work through this checklist before responding:
+Work through this checklist before responding:
 
 ${sharedChecklist}
 
+Do not start new work beyond this checklist. If every item is handled and nothing needs the user's attention first, end your final response with exactly this token as the very last line, with no formatting around it:
+
 ${COMPACT_READY_TOKEN}
 
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
@@ -44,9 +52,11 @@ If anything is outstanding, list the items concisely so the user can address the
 const EXIT_TEMPLATE = `---
 description: Flush thatch persistence, check for loose ends, then exit opencode if clear
 ---
-$ARGUMENTS
+${userMessageSection}
+
+# Pre-exit wrap-up
 
-Pre-exit wrap-up. Work through this checklist before responding:
+Work through this checklist before responding:
 
 ${sharedChecklist}
 3. Leave the chat directory. Call thatch_chat_unregister for this session - the session is exiting, so other sessions must stop addressing mail to it.

package/src/db.ts

@@ -284,6 +284,20 @@ export class ThatchDB {
       )
     `);
 
+    // Hook-parent-process -> session mapping (Claude Code identity anchor):
+    // hooks learn the true session id from the host's hook payload and run
+    // as children of the same process that spawned the MCP server, so the
+    // server resolves its own parent pid against this table - an identity
+    // the model cannot claim. Rows are timestamped; stale rows are ignored
+    // (pid reuse) rather than deleted.
+    this.#db.run(`
+      CREATE TABLE IF NOT EXISTS chat_host_pids (
+        ppid       INTEGER PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        seen_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    `);
+
     this.#migrateColumns();
     this.#migrateChatNameCollation();
     this.#migrateChatTopic();
@@ -291,6 +305,7 @@ export class ThatchDB {
     this.#migrateChatBroadcastFlag();
     this.#migrateChatAuto();
     this.#migrateChatWorktree();
+    this.#migrateChatHostPid();
   }
 
   // chat_sessions tables created before the auto column lack it; the ALTER
@@ -322,6 +337,16 @@ export class ThatchDB {
     }
   }
 
+  // The released schema has no host_pid column (liveness is heartbeat age;
+  // see chatLiveness). A development database may carry one; drop it so
+  // every database matches a fresh install.
+  #migrateChatHostPid(): void {
+    const cols = (this.#db.query("PRAGMA table_info(chat_sessions)").all() as any[]).map((r) => r.name);
+    if (cols.includes("host_pid")) {
+      this.#db.run("ALTER TABLE chat_sessions DROP COLUMN host_pid");
+    }
+  }
+
   // chat_messages tables created before the via_broadcast column lack it;
   // the ALTER adds it, and existing rows read as direct sends (which they
   // were).
@@ -935,6 +960,18 @@ export class ThatchDB {
     return this.#chat.unreadCount(sessionID);
   }
 
+  recordChatHostPid(ppid: number, sessionID: string) {
+    return this.#chat.recordHostPid(ppid, sessionID);
+  }
+
+  findChatSessionByHostPid(ppid: number, maxAgeSeconds: number): string | null {
+    return this.#chat.findSessionByHostPid(ppid, maxAgeSeconds);
+  }
+
+  continueChatSession(oldSessionID: string, newSessionID: string) {
+    return this.#chat.continueSession(oldSessionID, newSessionID);
+  }
+
   heartbeatChatSessions(sessionIDs: string[]) {
     return this.#chat.heartbeat(sessionIDs);
   }

package/src/debug.ts

@@ -0,0 +1,44 @@
+import { appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// Opt-in diagnostic logging for questions a live harness cannot otherwise
+// answer ("what did the plugin actually see at init?"). Lines go to
+// debug.log beside the database, never to the host's stdout or stderr:
+// the plugin runs inside opencode's TUI process, where console output is
+// invisible or garbles the screen, and test sandboxes point the database at
+// a tmp dir so their debug output never reaches the quality gate.
+//
+// Off unless THATCH_DEBUG is set. THATCH_DEBUG=1 (or "all" / "*") logs every
+// tag. Otherwise it is a comma-separated list of tag filters: a filter
+// matches a tag when it equals the whole tag ("chat:startup") or the
+// feature part before the colon ("chat" matches every chat:* tag).
+//
+// Tags are `feature:aspect`, rendered in square brackets, so a grep on
+// "[chat:" pulls one feature's story out of a shared file.
+
+export type DebugLog = (tag: string, msg: string) => void;
+
+// Decide, from a THATCH_DEBUG value, whether a tag is enabled. Exported for
+// tests; callers use createDebugLog.
+export function debugEnabled(spec: string | undefined, tag: string): boolean {
+  if (!spec) return false;
+  const s = spec.trim();
+  if (s === "1" || s === "all" || s === "*") return true;
+  const feature = tag.split(":")[0];
+  return s.split(",").map((f) => f.trim()).filter(Boolean).some((f) => f === tag || f === feature);
+}
+
+// Build the logger for a database location. Every line: ISO timestamp,
+// bracketed tag, message. Writes never throw: diagnostics must not break
+// the host, so a missing directory or a full disk simply drops the line.
+export function createDebugLog(dbPath: string, spec: string | undefined = process.env.THATCH_DEBUG): DebugLog {
+  const file = join(dirname(dbPath), "debug.log");
+  return (tag, msg) => {
+    if (!debugEnabled(spec, tag)) return;
+    try {
+      appendFileSync(file, `${new Date().toISOString()} [${tag}] ${msg}\n`);
+    } catch {
+      // Intentionally silent; see above.
+    }
+  };
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { createDebugLog } from "./debug";
 import type { Plugin } from "@opencode-ai/plugin";
 import { ThatchDB } from "./db";
 import { BgeEmbeddingModel } from "./embeddings";
@@ -24,7 +26,7 @@ import { seedDefaultBehaviors } from "./seed-behaviors";
 import { startVersionChecker, stopVersionChecker, getVersionChecker, readOnDiskVersion, compareSemver } from "./version-check";
 import { WatcherRegistry, ghApiRun, ghAvailable } from "./watchers";
 import { watcherNotificationNudge, chatNotificationNudge, chatEchoText, isChatEchoParts } from "./prompts";
-import { ChatPoller, isDefaultSessionTitle, slugifyTitle } from "./chat";
+import { ChatPoller, createWakeGate, isDefaultSessionTitle } from "./chat";
 import { chatEnabled, chatAutoRegister, loadConfig } from "./config";
 import pkg from "../package.json";
 
@@ -62,6 +64,73 @@ const WRAPUP_COMMANDS: Record<string, { token: string; kind: "compact" | "exit"
   "thatch/exit": { token: EXIT_READY_TOKEN, kind: "exit" },
 };
 
+/**
+ * Parses the session id a harness was started to continue from an argument
+ * list (`opencode -s <id>` / `--session <id>` / `--session=<id>`). Pure:
+ * the caller supplies the list (see startupSessionId for where it comes
+ * from). The framework passes no session id to plugins and resuming a
+ * session fires no events, so the command line is the only signal that a
+ * fresh harness is the new home of a continued session. `-c/--continue`
+ * (continue last) resolves no id here - that session registers on its
+ * first idle like any other.
+ */
+export function startupSessionIdFromArgv(argv: string[]): string | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-s" || arg === "--session") return argv[i + 1] ?? null;
+    if (arg.startsWith("--session=")) return arg.slice("--session=".length) || null;
+  }
+  return null;
+}
+
+// The plugin does not run in the process's main thread: opencode's TUI
+// spawns a worker thread (cli/tui/worker.js) to host the server, and worker
+// threads get their own argv (just the worker script) with none of the CLI
+// flags. The thread still shares the process's pid, so the OS-level command
+// line for our own pid is the real `opencode -s ses_...` invocation. Read it
+// from /proc on Linux or via ps on macOS. Returns [] when unavailable;
+// callers treat that as "no session flag". The readers are injectable so
+// tests can drive each branch without a real /proc or ps.
+export interface OsArgsDeps {
+  /** Reads a file as UTF-8, throwing when it does not exist. */
+  readFile: (path: string) => string;
+  /** Runs `ps -p <pid> -o args=`; returns its exit code and stdout. */
+  ps: (pid: number) => { exitCode: number; stdout: string };
+}
+
+const defaultOsArgsDeps: OsArgsDeps = {
+  readFile: (path) => readFileSync(path, "utf8"),
+  ps: (pid) => {
+    const res = Bun.spawnSync(["ps", "-p", String(pid), "-o", "args="]);
+    return { exitCode: res.exitCode, stdout: res.stdout.toString() };
+  },
+};
+
+export function osProcessArgs(deps: OsArgsDeps = defaultOsArgsDeps, pid = process.pid): string[] {
+  try {
+    // Linux: cmdline is NUL-separated argv, exact and cheap.
+    return deps.readFile("/proc/self/cmdline").split("\0").filter(Boolean);
+  } catch {
+    // macOS has no /proc; ask ps for this pid's full command. Splitting on
+    // whitespace is safe for our purpose: session ids never contain spaces.
+    try {
+      const res = deps.ps(pid);
+      if (res.exitCode !== 0) return [];
+      return res.stdout.trim().split(/\s+/).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Resolve the session id this harness was launched to resume, if any:
+// prefer the thread-local argv (covers tests and any non-worker host), then
+// fall back to the process's OS-level command line (the real harness path).
+// The caller passes the OS command line in so it is read once per init.
+export function startupSessionId(osArgs: string[]): string | null {
+  return startupSessionIdFromArgv(process.argv) ?? startupSessionIdFromArgv(osArgs);
+}
+
 export const server: Plugin = async ({ client, worktree }) => {
   // The opencode server's cwd is wherever the server happened to start;
   // `worktree` is the project this plugin instance actually serves.
@@ -78,6 +147,9 @@ export const server: Plugin = async ({ client, worktree }) => {
   const chatOn = chatEnabled(loadConfig(dbPath).config);
 
   const db = new ThatchDB(dbPath);
+  // Opt-in diagnostics (THATCH_DEBUG), written to debug.log beside the db.
+  // See debug.ts for the tag filter semantics.
+  const debug = createDebugLog(dbPath);
   const model = new BgeEmbeddingModel(modelName);
   const extraction = new ExtractionPipeline();
 
@@ -119,22 +191,17 @@ export const server: Plugin = async ({ client, worktree }) => {
   // event stream, and a stale "idle" turns a wake into mid-turn context
   // injection (observed live: a session read mail mid-burst, contradicted
   // its own in-flight plan, and looped).
-  const canPromptSession = async (sessionID: string): Promise<boolean> => {
-    if (compacting.has(sessionID)) return false;
-    if (sessionStatus.get(sessionID) !== "idle") return false;
-    try {
+  const canPromptSession = createWakeGate({
+    isCompacting: (sessionID) => compacting.has(sessionID),
+    mappedStatus: (sessionID) => sessionStatus.get(sessionID),
+    fetchStatuses: async () => {
       const { data } = await client.session.status();
-      // The server's status map only carries ACTIVE sessions - it deletes
-      // the entry when a session goes idle (session/status.ts), so absent
-      // means idle. Fail closed on busy/retry, pass on idle-or-absent.
-      const live = data?.[sessionID];
-      return !live || live.type === "idle";
-    } catch (err) {
-      // Unreachable server: do not deliver (the mail stays pending).
+      return data ?? {};
+    },
+    onStatusError: (sessionID, err) => {
       console.error(`[thatch] status check failed for ${sessionID}: ${err}`);
-      return false;
-    }
-  };
+    },
+  });
 
   // In-memory watcher registry for proactive event notifications (GitHub PR
   // and branch watching, plus local command watches). Deliberately
@@ -187,24 +254,17 @@ export const server: Plugin = async ({ client, worktree }) => {
   });
   watchers.start();
 
-  // The proactive-prompt gate, shared by both delivery registries
-  // (watchers and chat). Two layers, in cost order: the compacting set and
-  // the event-fed sessionStatus map answer cheaply, and a final check
-  // verifies against the server's live status - the map is only as fresh
-  // as the event stream, and a stale "idle" turns a wake into mid-turn
-  // context injection (observed live: a session read mail mid-burst,
-  // contradicted its own in-flight plan, and looped).
   const chatPoller = new ChatPoller({
     store: db,
     hostedSessions: () => {
-      // Sub-agent children share this process's sessionStatus (their
-      // status events land here), but they are never legitimate chat
-      // participants - a registered child would be heartbeat-ed
-      // fresh-forever and burn nudge budget on undeliverable wake
-      // prompts. Keep them out of the hosted set even when guidance
-      // against registering them is ignored.
-      const hosted = [...sessionStatus.keys()].filter((id) => !childToParent.has(id));
-      return hosted;
+      // Hosting = the sessions this harness serves: those seen as events
+      // here (used in this TUI) plus the `-s` startup session. Sub-agent
+      // children are excluded even if someone registered one - a
+      // registered child would be heartbeat-ed fresh-forever and burn
+      // nudge budget on undeliverable wake prompts.
+      const hosted = [...sessionStatus.keys()];
+      if (startupSession) hosted.push(startupSession);
+      return hosted.filter((id) => !childToParent.has(id));
     },
     deliver: async (sessionID, senders, count) => {
       await client.session.promptAsync({
@@ -231,6 +291,46 @@ export const server: Plugin = async ({ client, worktree }) => {
   // sessions and burn wake budget against a feature the user turned off.
   if (chatOn) chatPoller.start();
 
+  // Startup registration: `opencode -s <id>` continues a session whose
+  // directory row may predate this process (its harness died, or the
+  // machine restarted). The framework passes no session id to plugins and
+  // resuming fires no events, so the command line is the source (see
+  // startupSessionId). Registering here RECLAIMS the row - the name is
+  // owned by the session id and never changes - and refreshes its
+  // heartbeat synchronously: local SQLite, it cannot fail on a server that
+  // is still starting. The async tail (title fetch, asleep-mail delivery)
+  // is best-effort - the poller retries whatever it misses, and the first
+  // idle converges the topic.
+  const osArgs = osProcessArgs();
+  const startupSession = startupSessionId(osArgs);
+  const autoRegisterOn = chatAutoRegister(loadConfig(dbPath).config);
+  const tombstoned = startupSession ? db.hasChatLeaveTombstone(startupSession) : false;
+  debug("chat:startup", `init: argv=${JSON.stringify(process.argv.slice(0, 8))} osArgs=${JSON.stringify(osArgs.slice(0, 8))} parsed=${startupSession} chatOn=${chatOn} autoRegister=${autoRegisterOn} tombstone=${startupSession ? tombstoned : "n/a"}`);
+  if (chatOn && autoRegisterOn && startupSession && !tombstoned) {
+    const res = db.registerChatSession(startupSession, repo, null, "opencode", null, detectWorktreeKind(worktree));
+    debug("chat:startup", `registration for ${startupSession}: ok=${res.ok} name=${res.ok ? res.name : res.error}`);
+    if (res.ok) {
+      void (async () => {
+        try {
+          const { data } = await client.session.get({ path: { id: startupSession } });
+          const title = data?.title ?? "";
+          const topic = title && !isDefaultSessionTitle(title) ? title : null;
+          if (topic) db.refreshChatTopic(startupSession, topic);
+        } catch {
+          // Server may still be starting; the topic converges on the
+          // session's first idle either way.
+        }
+        try {
+          // Asleep-mail: deliver what queued while this session was away,
+          // through the normal path (gate, nudge, toast, stamps).
+          await chatPoller.deliverPending();
+        } catch {
+          // The poller cycle retries delivery; nothing to do here.
+        }
+      })();
+    }
+  }
+
   // Sessions currently being compacted. chat.message nudges are skipped while
   // a session is in this set - the agent can't call tools during summary
   // generation, so a recall or extraction nudge would cause a blocked-tool
@@ -966,20 +1066,34 @@ export const server: Plugin = async ({ client, worktree }) => {
         // Auto-registration: every top-level opencode session joins the
         // chat directory on its first idle event (unless the user turned
         // auto-registration off). The name is assigned, never chosen - a
-        // slug of the session title plus a never-reused counter - and the
-        // live title rides the topic column, refreshed on every idle so the
-        // roster tracks what the session is actually working on. Titles are
-        // usually placeholders at first idle and real within a turn or two,
-        // so both name and topic converge fast. Fire-and-forget: a failed
-        // registration or title fetch must never block event delivery.
+        // pool draw plus a never-reused counter, kept short because it
+        // appears in wake prompts and rosters. The live session title rides
+        // the topic column instead (refreshed on every idle), so the name
+        // and the description stay separate identities. Fire-and-forget: a
+        // failed registration or title fetch must never block event
+        // delivery.
         if (chatOn && chatAutoRegister(loadConfig(dbPath).config) && sessionID && !db.hasChatLeaveTombstone(sessionID)) {
           void (async () => {
             try {
               const { data } = await client.session.get({ path: { id: sessionID } });
               const title = data?.title ?? "";
-              const base = title && !isDefaultSessionTitle(title) ? slugifyTitle(title) : null;
-              db.registerChatSession(sessionID, repo, base ? title : null, "opencode", base, detectWorktreeKind(worktree));
-              if (base) db.refreshChatTopic(sessionID, title);
+              // Placeholder titles never become topics (the real one
+              // converges on a later idle via refreshChatTopic).
+              const topic = title && !isDefaultSessionTitle(title) ? title : null;
+              const res = db.registerChatSession(sessionID, repo, topic, "opencode", null, detectWorktreeKind(worktree));
+              // The topic converges as the auto-titler lands a real title:
+              // registration is once-per-session, so later idles must
+              // refresh it explicitly.
+              if (res.ok && topic) db.refreshChatTopic(sessionID, topic);
+              if (res.ok && res.created) {
+                // First registration is the one moment the user should
+                // notice: a quiet toast, not a conversation message.
+                try {
+                  await client.tui.showToast({ body: { message: `registered in chat as ${res.name}`, variant: "info", duration: 4000 } });
+                } catch {
+                  // Headless or disconnected TUI - registration stands.
+                }
+              }
             } catch (err) {
               console.error(`[thatch] chat auto-register failed for ${sessionID}: ${err}`);
             }

package/src/mcp.ts

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { z } from "zod";
 import { ThatchDB } from "./db";
+import { mcpSessionID } from "./chat";
 import { BgeEmbeddingModel } from "./embeddings";
 import { detectRepo } from "./git";
 import { checkSetup, setupClaudeCode, setupCursor } from "./setup";
@@ -134,6 +135,21 @@ export async function runMcpServer(): Promise<void> {
     defaultStore: repo,
     extractionPayloadProvider,
     drainExtractionQueue,
+    // Claude Code identity anchor, two model-proof layers:
+    //  1. The hooks record (parent pid -> session) from payloads the model
+    //     cannot influence, and this server is a child of the same Claude
+    //     Code process - current even after a session fork.
+    //  2. CLAUDE_CODE_SESSION_ID, set by the host in this server's env at
+    //     spawn ("retains the ID it was spawned with") - covers the case
+    //     where hook and server parent pids diverge, but goes stale after a
+    //     fork/continue, so it is the fallback, not the primary.
+    // A miss on both falls back to the caller-claimed `as` (Cursor).
+    chatDerivedIdentity: () => {
+      const mapped = db.findChatSessionByHostPid(process.ppid, 600);
+      if (mapped) return mapped;
+      const envID = process.env.CLAUDE_CODE_SESSION_ID;
+      return envID ? db.findChatSession(mcpSessionID(envID))?.session_id ?? null : null;
+    },
   };
   const tools = compileTools();
 

package/src/prompts.ts

@@ -20,8 +20,8 @@ const chatPromptSection = `
 
 Sessions on this machine - opencode, Claude Code, and Cursor alike - can
 message each other through thatch. opencode sessions join the directory
-automatically: your display name is assigned by thatch (a slug of your
-session title plus a counter, e.g. fix-auth-bug-00001) and is never
+automatically: your display name is assigned by thatch (a name drawn from
+a built-in pool plus a counter, e.g. al-go-rithm-00001) and is never
 reassigned or reused, so a given name is always the same session.
 thatch_chat_register with no arguments reports your name or rejoins after
 unregistering. On MCP hosts, pass the name your thatch hook printed as the