@jeffober/thatch 0.2.4 → 0.2.6

package/src/session-tab-shared.ts

@@ -0,0 +1,231 @@
+/**
+ * Cross-entry contract for the session-tab feature: the single module both
+ * the opencode v2 server adapter (src/opencode/v2.ts) and the v2 TUI CLI
+ * plugin (src/opencode/tui-plugin.ts) import. SDK-free under the same
+ * isolation rule as src/index.ts - the TUI entry may import only
+ * @opencode/plugin/tui and this module, and the server entry graph must
+ * never evaluate the v1 SDK.
+ *
+ * The transport is the v2 plugin rpc surface: the server adapter registers
+ * this definition and emits events; the TUI CLI plugin receives them on the
+ * ordinary event feed (isOpenCodeEvent passes any `rpc.` type) and acts on
+ * them with the TUI-only tab primitives. Events are ephemeral - a missed
+ * event means "no tab", never "no session" (the session exists before the
+ * first emit and the tool response words the tab as requested, not
+ * guaranteed).
+ *
+ * The schemas are literal JSON Schema objects because
+ * Rpc.PortableEventValueSchema accepts StandardSchemaV1 or a JSON Schema
+ * object with type "object"; a literal object keeps this module
+ * dependency-free. The registration is the server-to-TUI transport for
+ * everything thatch pushes at the TUI (tab lifecycle plus toasts), so its
+ * id says "tabs" only historically. One event has a consumer beyond the
+ * TUI plugin's tab strip: the v2 pump (src/opencode/v2.ts) translates
+ * tab-closed into the runtime's confirmed-death path (the
+ * session_tab_close tool's only route to it), so that shape must change
+ * jointly with all consumers (docs/dev/features/session-tabs.md).
+ * exit-tab-closed is deliberately TUI-only: the wrap-up exit records the
+ * session's watcher deaths synchronously before emitting
+ * (src/runtime.ts), so the pump ignores it - a pump translation would run
+ * the death path a second time and erase the durable death row the first
+ * pass wrote. toast is TUI-only by nature (nobody else consumes it).
+ */
+
+import { realpathSync } from "node:fs";
+import { EXTRACTION_CHILD_TITLE } from "./chat";
+import { resolveMainCheckout } from "./git";
+
+export const SESSION_TAB_RPC_ID = "thatch-tabs";
+export const TAB_OPENED_EVENT = "tab-opened";
+export const TAB_CLOSED_EVENT = "tab-closed";
+export const EXIT_TAB_CLOSED_EVENT = "exit-tab-closed";
+export const TOAST_EVENT = "toast";
+
+/** Full wire type of an emitted event, e.g. "rpc.thatch-tabs.tab-opened". */
+export const tabOpenedEventType = `rpc.${SESSION_TAB_RPC_ID}.${TAB_OPENED_EVENT}`;
+
+/** Full wire type of the tab-closed event - the generalized-session-
+ *  heartbeat plan's confirmed-close consumer matches on this. */
+export const tabClosedEventType = `rpc.${SESSION_TAB_RPC_ID}.${TAB_CLOSED_EVENT}`;
+
+/** Full wire type of the wrap-up exit's TUI-only close event. */
+export const exitTabClosedEventType = `rpc.${SESSION_TAB_RPC_ID}.${EXIT_TAB_CLOSED_EVENT}`;
+
+/** Full wire type of the toast request event. */
+export const toastEventType = `rpc.${SESSION_TAB_RPC_ID}.${TOAST_EVENT}`;
+
+export const SESSION_TAB_RPC = {
+  id: SESSION_TAB_RPC_ID,
+  methods: {},
+  events: {
+    [TAB_OPENED_EVENT]: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          directory: { type: "string" },
+        },
+        required: ["sessionID", "directory"],
+        additionalProperties: false,
+      },
+    },
+    [TAB_CLOSED_EVENT]: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          // Nullable: the chat roster row may have been reaped by the time
+          // the close fires. Consumers address death notices by name when
+          // present and fall back to the session id.
+          chatName: { type: ["string", "null"] },
+        },
+        required: ["sessionID", "chatName"],
+        additionalProperties: false,
+      },
+    },
+    [EXIT_TAB_CLOSED_EVENT]: {
+      // TUI-only (see the module header): carries just the tab to close.
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+        },
+        required: ["sessionID"],
+        additionalProperties: false,
+      },
+    },
+    [TOAST_EVENT]: {
+      // TUI-only by nature. The payload is thatch's ToastInput verbatim
+      // (all three fields required there, so required here).
+      schema: {
+        type: "object",
+        properties: {
+          message: { type: "string" },
+          variant: { type: "string", enum: ["info", "success", "warning", "error"] },
+          duration: { type: "number" },
+        },
+        required: ["message", "variant", "duration"],
+        additionalProperties: false,
+      },
+    },
+  },
+} as const;
+
+/**
+ * The coordinator-authority framing delivered as the subordinate's first
+ * user message. The wording is the feature's contract with the subordinate
+ * LLM (docs/dev/features/session-tabs.md): coordinator instructions outrank
+ * nothing the user says directly.
+ */
+export function buildSubordinatePrompt(coordinatorName: string, task: string): string {
+  const preamble =
+    `Your work session was created by ${coordinatorName}, who is coordinating your actions. ` +
+    "Please treat their instructions as accepted priority, unless they conflict with the user's " +
+    "explicit preferences or instructions. If the user prompts you directly, their instructions " +
+    "supersede the coordinating LLM's.";
+  return `${preamble}\n\n${task}`;
+}
+
+/** Result of validating the session_tab title arg. */
+export type TitleValidation = { ok: true; title: string } | { ok: false; error: string };
+
+/**
+ * Titles render in the tab strip: soft target ~50 characters, hard max 80.
+ * opencode imposes no length limit (title is an unbounded optional string)
+ * and the strip truncates visually, so a hard fail at 50 would only cost
+ * retry friction - hence the loose cap.
+ *
+ * EXTRACTION_CHILD_TITLE is rejected because the chat auto-register paths
+ * treat that exact title as plugin machinery and refuse the session
+ * (src/chat.ts isMachinerySessionTitle) - a subordinate titled into
+ * machinery would silently lose its roster row and with it the
+ * coordination loop's addressing.
+ */
+export function validateTitle(raw: unknown): TitleValidation {
+  if (typeof raw !== "string") return { ok: false, error: "title must be a string." };
+  const title = raw.trim();
+  if (!title) return { ok: false, error: "title must not be empty (it was blank after trimming)." };
+  if (title.length > 80) {
+    return {
+      ok: false,
+      error: `title is too long: ${title.length} characters against a hard max of 80. Aim for about 50 - it renders in the session tab strip.`,
+    };
+  }
+  if (title === EXTRACTION_CHILD_TITLE) {
+    return { ok: false, error: "that title is reserved for plugin machinery sessions; pick a task title." };
+  }
+  return { ok: true, title };
+}
+
+/** Result of validating the exactly-one-of worktree/directory rule. */
+export type LocationValidation =
+  | { ok: true; kind: "worktree" | "directory"; path: string }
+  | { ok: false; error: string };
+
+/**
+ * The tool takes exactly one location arg. The two kinds differ in
+ * validation and intent, not in tab placement: either way the tab opens in
+ * the coordinator's window (the tab-open event routes by the coordinator
+ * instance's location, never the session's).
+ */
+export function validateLocationArgs(args: { worktree?: unknown; directory?: unknown }): LocationValidation {
+  const hasWorktree = typeof args.worktree === "string" && args.worktree.trim() !== "";
+  const hasDirectory = typeof args.directory === "string" && args.directory.trim() !== "";
+  if (hasWorktree && hasDirectory) {
+    return { ok: false, error: "Pass exactly ONE location: worktree (a git worktree of the current repository) or directory (any existing directory), not both." };
+  }
+  if (hasWorktree) return { ok: true, kind: "worktree", path: (args.worktree as string).trim() };
+  if (hasDirectory) return { ok: true, kind: "directory", path: (args.directory as string).trim() };
+  return { ok: false, error: "Pass exactly one location: worktree (a git worktree of the current repository) or directory (any existing directory)." };
+}
+
+/**
+ * Whether two directories belong to the same repository, by main-checkout
+ * identity (the parent of the absolute git common dir) rather than path
+ * equality - the coordinator may itself run in a worktree of the repo the
+ * candidate worktree hangs off. Realpaths on both sides: on macOS /tmp
+ * resolves to /private/tmp, and the two resolutions must agree on the
+ * comparison. Null (outside git, bare repo, spawn failure) never matches.
+ */
+export async function isSameMainCheckout(a: string, b: string): Promise<boolean> {
+  const [mainA, mainB] = await Promise.all([resolveMainCheckout(a), resolveMainCheckout(b)]);
+  if (!mainA || !mainB) return false;
+  try {
+    return realpathSync(mainA) === realpathSync(mainB);
+  } catch {
+    return false;
+  }
+}
+
+/** TUI-side, pure so the session-tab tests can run without the TUI runtime. */
+
+/** The event-type filter the TUI CLI plugin applies to every fed event. */
+export function isTabOpenedEvent(type: string): boolean {
+  return type === tabOpenedEventType;
+}
+
+/** The close-request filter: same transport, opposite action. */
+export function isTabClosedEvent(type: string): boolean {
+  return type === tabClosedEventType;
+}
+
+/** The wrap-up exit's close filter: same TUI action, no pump translation. */
+export function isExitTabClosedEvent(type: string): boolean {
+  return type === exitTabClosedEventType;
+}
+
+/** The toast-request filter: TUI-only by nature. */
+export function isToastEvent(type: string): boolean {
+  return type === toastEventType;
+}
+
+/**
+ * The directory guard mirrors the built-in tui.* handlers: an event only
+ * acts on the window whose directory matches the event's location (the
+ * coordinator instance's directory). An event with no location never acts -
+ * failing closed, the same as the built-ins' inequality check.
+ */
+export function passesDirectoryGuard(eventDirectory: string | undefined, windowDirectory: string | undefined): boolean {
+  if (!eventDirectory || !windowDirectory) return false;
+  return eventDirectory === windowDirectory;
+}

package/src/setup.ts

@@ -66,7 +66,7 @@ function resolvePaths(global: boolean, projectDir: string, homeDir: string): Set
 // .mcp.json - MCP server registration
 // ---------------------------------------------------------------------------
 
-function writeMcpConfig(path: string, thatchBin: string): void {
+function writeMcpConfig(path: string, thatchBin: string, projectDir?: string): void {
   let config: any = { mcpServers: {} };
   if (existsSync(path)) {
     try {
@@ -81,6 +81,12 @@ function writeMcpConfig(path: string, thatchBin: string): void {
     type: "stdio",
     command: thatchBin,
     args: ["mcp"],
+    // Project-LOCAL configs pin the project directory so the server's
+    // identity resolution is deterministic regardless of the cwd the host
+    // spawns it with. Global-scope configs must NEVER pin: one entry serves
+    // every project, and a first-in-chain env override would clobber all
+    // of them. (setup.ts:projectDir chain in src/mcp.ts.)
+    ...(projectDir ? { env: { THATCH_PROJECT_DIR: projectDir } } : {}),
   };
 
   mkdirSync(join(path, ".."), { recursive: true });
@@ -356,7 +362,7 @@ export function setupClaudeCode(
   const paths = resolvePaths(global, projectDir, home);
 
   if (paths.mcpConfigPath) {
-    writeMcpConfig(paths.mcpConfigPath, thatchBin);
+    writeMcpConfig(paths.mcpConfigPath, thatchBin, projectDir);
   }
 
   appendInstructions(paths.claudeMdPath);
@@ -622,7 +628,7 @@ export function setupCursor(
   const home = homeDir ?? homedir();
   const paths = resolveCursorPaths(global, projectDir, home);
 
-  writeMcpConfig(paths.mcpConfigPath, thatchBin);
+  writeMcpConfig(paths.mcpConfigPath, thatchBin, global ? undefined : projectDir);
   appendCursorInstructions(paths.agentsMdPath);
   writeCursorHooks(paths.hooksPath, thatchBin);
   const skills = installSkills(paths.skillsDir);

package/src/skills.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { REVIEW_SPECIALISTS } from "./prompts";
 
 export interface SkillDef {
   name: string;
@@ -53,15 +54,10 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-fact-extractor",
     "thatch-dedup-classifier",
     "thatch-project-primer",
-    "thatch-review-pedantic",
-    "thatch-review-acceptance",
-    "thatch-review-state-flow",
-    "thatch-review-economy",
-    "thatch-review-no-slop",
-    "thatch-review-breadcrumbs",
-    "thatch-review-mark-and-sweep",
-    "thatch-review-highlights",
-    "thatch-review-technique",
+    // The specialist roster (order and count) comes from prompts.ts so the
+    // install set and the review-mode commands' inline procedure cannot
+    // diverge.
+    ...REVIEW_SPECIALISTS,
     "thatch-review-synthesizer",
     "thatch-review-context",
     "thatch-code-archaeology",
@@ -92,6 +88,7 @@ function loadSharedSkills(): SkillDef[] {
 function loadOpencodeOnlySkills(): SkillDef[] {
   return [
     { name: "thatch-code-review", content: loadSkillFile("thatch-code-review") },
+    { name: "thatch-coordination", content: loadSkillFile("thatch-coordination") },
   ];
 }
 

package/src/tab-state.ts

@@ -0,0 +1,125 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CHAT_STALE_MS } from "./chat";
+
+/**
+ * Reader for opencode's per-TUI-instance tab persistence - the roster's
+ * OPEN-vs-RECENT signal. Each opencode TUI window records its open tabs in
+ * `<XDG_STATE_HOME>/opencode/<channel>/tui/tabs.json` (the middle segment is
+ * the release CHANNEL - "latest" today, so a reader must glob, never
+ * hardcode). The file answers "which sessions have a tab right now" for
+ * roster classification and broadcast targeting; it is READ-ONLY here -
+ * the heartbeat stays the only written liveness signal.
+ *
+ * This is a presence refinement, not a truth source. A killed window leaves
+ * its tab rows behind (the file is restart persistence by design), so a row
+ * classified OPEN may occasionally be residue; that trade is accepted in
+ * exchange for zero new writers. With tabs disabled (or no state tree at
+ * all) the reader returns an empty set and every row honestly degrades to
+ * RECENT - never a false OPEN.
+ */
+
+/** Test/QA override for the opencode state root (the directory that holds
+ *  one subdirectory per release channel). Unset means the real location. */
+export const OPEN_TABS_STATE_ROOT_ENV = "THATCH_OPENCODE_STATE_ROOT";
+
+/** The opencode state root: the directory containing one directory per
+ *  release channel ("latest" today). */
+export function openTabsStateRoot(env: Record<string, string | undefined> = process.env): string {
+  const override = env[OPEN_TABS_STATE_ROOT_ENV];
+  if (override) return override;
+  const stateHome = env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+  return join(stateHome, "opencode");
+}
+
+/** Shape of tabs.json (opencode v2.0.25, session-tabs storage): an optional
+ *  global section and a per-cwd section, each carrying tab rows with a
+ *  sessionID. Both sections are read because the scope depends on the
+ *  `tabs.scope` config ("cwd" or "global") and the reader must honor both. */
+interface TabsFile {
+  global?: { tabs?: { sessionID?: string }[] };
+  cwd?: Record<string, { tabs?: { sessionID?: string }[] }>;
+}
+
+function collectTabs(rows: { sessionID?: string }[] | undefined, into: Set<string>): void {
+  if (!Array.isArray(rows)) return;
+  for (const row of rows) {
+    if (row && typeof row.sessionID === "string" && row.sessionID) into.add(row.sessionID);
+  }
+}
+
+/**
+ * Every sessionID carrying a tab in ANY channel's tabs.json, from both
+ * scope modes (global section and cwd sections). Per-file failures (no
+ * file, bad JSON, malformed sections) are swallowed and contribute
+ * nothing: a missing or broken signal degrades to empty, never to an
+ * error, so roster rendering and broadcast targeting keep working.
+ */
+export function readOpenTabSessions(stateRoot: string = openTabsStateRoot()): Set<string> {
+  const open = new Set<string>();
+  let channels: string[];
+  try {
+    channels = readdirSync(stateRoot).filter((name) => !name.startsWith("."));
+  } catch {
+    // No state tree (opencode never ran here, or tabs are disabled):
+    // empty set, everything degrades to RECENT.
+    return open;
+  }
+  for (const channel of channels) {
+    let parsed: TabsFile;
+    try {
+      parsed = JSON.parse(readFileSync(join(stateRoot, channel, "tui", "tabs.json"), "utf8"));
+    } catch {
+      continue;
+    }
+    collectTabs(parsed?.global?.tabs, open);
+    const byCwd = parsed?.cwd;
+    if (byCwd && typeof byCwd === "object") {
+      for (const section of Object.values(byCwd)) collectTabs(section?.tabs, open);
+    }
+  }
+  return open;
+}
+
+/** How long a confirmed tab close keeps overriding a residue tab row. The
+ *  close's death path stops the heartbeat, so the row can only read fresh
+ *  until its frozen last_seen crosses CHAT_STALE_MS; one extra poll
+ *  interval covers a beat already in flight at close time. After the
+ *  window the marker is moot (the row is stale regardless), and a session
+ *  that later regains a tab re-derives OPEN from tabs.json alone. */
+export const CHAT_TAB_CLOSED_OVERRIDE_MS = 2 * CHAT_STALE_MS;
+
+/** One confirmed tab close: the session's tab was closed by the
+ *  session_tab tool and the bridge event confirmed it. */
+export interface ChatTabClosure {
+  sessionID: string;
+  /** ISO timestamp of the confirmed close. */
+  at: string;
+}
+
+/**
+ * Subtracts fresh confirmed tab closes from the raw tab set, so a residue
+ * row in tabs.json (a window that died between the tool's close event and
+ * the file write - or before it) cannot read OPEN right after a confirmed
+ * close. Closures older than CHAT_TAB_CLOSED_OVERRIDE_MS are ignored.
+ */
+export function effectiveOpenTabs(openTabs: ReadonlySet<string>, closures: ChatTabClosure[], now = Date.now()): Set<string> {
+  const effective = new Set(openTabs);
+  for (const closure of closures) {
+    const at = Date.parse(closure.at);
+    if (Number.isNaN(at)) continue;
+    if (now - at < CHAT_TAB_CLOSED_OVERRIDE_MS) effective.delete(closure.sessionID);
+  }
+  return effective;
+}
+
+/**
+ * The production open-tabs provider: read tabs.json at call time (never
+ * cached - the file changes between renders) and subtract the confirmed
+ * closes recorded in thatch.db. `loadClosures` is the ThatchDB lookup,
+ * injected so this composes with any database handle.
+ */
+export function chatOpenTabs(loadClosures: () => ChatTabClosure[]): () => Set<string> {
+  return () => effectiveOpenTabs(readOpenTabSessions(), loadClosures());
+}