selftune 0.2.21 → 0.2.22

package/README.md

@@ -126,6 +126,9 @@ Your agent runs these — you just say what you want ("improve my skills", "show
 |            | `selftune eval composability --skill <name>` | Detect conflicts between co-occurring skills                                                |
 |            | `selftune eval family-overlap --prefix sc-`  | Detect sibling overlap and suggest when a skill family should be consolidated               |
 |            | `selftune eval import`                       | Import external eval corpus from [SkillsBench](https://github.com/benchflow-ai/skillsbench) |
+| **hooks**  | `selftune codex install`                     | Install selftune hooks into Codex (`--dry-run`, `--uninstall`)                              |
+|            | `selftune opencode install`                  | Install selftune hooks into OpenCode                                                        |
+|            | `selftune cline install`                     | Install selftune hooks into Cline                                                           |
 | **auto**   | `selftune cron setup`                        | Install OS-level scheduling (cron/launchd/systemd)                                          |
 |            | `selftune watch --skill <name>`              | Monitor after deploy. Auto-rollback on regression.                                          |
 | **other**  | `selftune workflows`                         | Discover and manage multi-skill workflows                                                   |
@@ -165,13 +168,15 @@ selftune is complementary to these tools, not competitive. They trace what happe
 
 ## Platforms
 
-**Claude Code** (fully supported) — Hooks install automatically. `selftune ingest claude` backfills existing transcripts. This is the primary supported platform.
+| Platform | Support | Real-time Hooks | Eval/Optimizer Agents | Batch Ingest | Config Location |
+| --- | --- | --- | --- | --- | --- |
+| **Claude Code** | Full | Automatic via `selftune init` | `claude --agent` (native) | `selftune ingest claude` | `~/.claude/settings.json` |
+| **Codex** | Experimental | `selftune codex install` | `codex exec` (inlined) | `selftune ingest codex` | `~/.codex/hooks.json` |
+| **OpenCode** | Experimental | `selftune opencode install` | `opencode run --agent` (native) | `selftune ingest opencode` | `./opencode.json` or `~/.config/opencode/opencode.json` |
+| **Cline** | Experimental | `selftune cline install` | — | — | `~/Documents/Cline/Hooks/` |
+| **OpenClaw** | Experimental | — | — | `selftune ingest openclaw` | — |
 
-**Codex** (experimental) — `selftune ingest wrap-codex -- <args>` or `selftune ingest codex`. Adapter exists but is not actively tested. Skill attribution is conservative: selftune only records explicit Codex skill evidence, not incidental assistant/meta mentions.
-
-**OpenCode** (experimental) — `selftune ingest opencode`. Adapter exists but is not actively tested.
-
-**OpenClaw** (experimental) — `selftune ingest openclaw` + `selftune cron setup` for autonomous evolution. Adapter exists but is not actively tested.
+OpenCode and Codex now support eval/optimizer agent workflows (evolution-reviewer, diagnosis-analyst, pattern-analyst, integration-guide). OpenCode agents are registered in the config during `selftune opencode install`; Codex inlines agent instructions into the prompt since it lacks a native `--agent` flag. OpenCode lacks a prompt-submission hook event, so prompt logging and auto-activate are unavailable. Cline only exposes PostToolUse and task lifecycle events, limiting coverage to commit tracking and session telemetry. All platforms write to the same shared log schema.
 
 Requires [Bun](https://bun.sh) or Node.js 18+. No extra API keys.
 
@@ -181,6 +186,6 @@ Requires [Bun](https://bun.sh) or Node.js 18+. No extra API keys.
 
 [Architecture](ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Integration Guide](docs/integration-guide.md) · [Sponsor](https://github.com/sponsors/WellDunDun)
 
-MIT licensed. Free forever. Primary support for Claude Code; experimental adapters for Codex, OpenCode, and OpenClaw.
+MIT licensed. Free forever. Hooks for Claude Code, Codex, OpenCode, and Cline; batch ingest for OpenClaw.
 
 </div>

package/cli/selftune/adapters/cline/hook.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env bun
+/**
+ * Cline hook adapter for selftune.
+ *
+ * Translates Cline hook events (PostToolUse, TaskComplete, TaskCancel)
+ * into selftune hook calls for commit tracking and session telemetry.
+ *
+ * Protocol: reads JSON from stdin, routes to the appropriate handler,
+ * and writes `{"cancel": false}` to stdout.
+ *
+ * Fail-open: never crashes, never blocks Cline. All errors are silent.
+ *
+ * Usage: echo '$HOOK_PAYLOAD' | selftune cline hook
+ */
+
+import type { StopPayload } from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Cline hook input shape
+// ---------------------------------------------------------------------------
+
+interface ClineHookInput {
+  hookName: string;
+  taskId: string;
+  workspaceRoots?: string[];
+  postToolUse?: {
+    toolName: string;
+    parameters: Record<string, unknown>;
+    result?: string;
+    success?: boolean;
+  };
+  taskComplete?: {
+    taskMetadata: { taskId: string; ulid: string };
+  };
+  taskCancel?: {
+    taskMetadata: { taskId: string; ulid: string };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function outputResponse(): void {
+  process.stdout.write(JSON.stringify({ cancel: false }));
+}
+
+async function readStdin(): Promise<{ full: string }> {
+  const raw = await Bun.stdin.text();
+  return { full: raw };
+}
+
+// ---------------------------------------------------------------------------
+// PostToolUse handler — commit tracking (inline, fast path)
+// ---------------------------------------------------------------------------
+
+async function handlePostToolUse(input: ClineHookInput): Promise<void> {
+  const { postToolUse, taskId } = input;
+  if (!postToolUse) return;
+
+  const { toolName, parameters, result } = postToolUse;
+
+  // Only care about execute_command that might be git commits
+  if (toolName !== "execute_command") return;
+
+  const command = typeof parameters.command === "string" ? parameters.command : "";
+  if (!command) return;
+
+  // Use selftune's commit-track logic
+  const { containsGitCommitCommand, parseCommitSha, parseCommitTitle, parseBranchFromOutput } =
+    await import("../../hooks/commit-track.js");
+
+  if (!containsGitCommitCommand(command)) return;
+  if (!result) return;
+
+  const commitSha = parseCommitSha(result);
+  if (!commitSha) return;
+
+  const commitTitle = parseCommitTitle(result);
+  const branch = parseBranchFromOutput(result);
+
+  // Write to SQLite
+  try {
+    const { writeCommitTracking } = await import("../../localdb/direct-write.js");
+    writeCommitTracking({
+      session_id: taskId,
+      commit_sha: commitSha,
+      commit_title: commitTitle,
+      branch,
+      timestamp: new Date().toISOString(),
+    });
+  } catch {
+    /* fail-open */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TaskComplete / TaskCancel handler — session telemetry (background)
+// ---------------------------------------------------------------------------
+
+async function handleTaskEnd(input: ClineHookInput): Promise<void> {
+  const { taskId, workspaceRoots } = input;
+  const cwd = workspaceRoots?.[0] ?? process.cwd();
+
+  // Build a StopPayload compatible with selftune's session-stop processor
+  const payload: StopPayload = {
+    session_id: taskId,
+    cwd,
+    // Cline doesn't provide a transcript path in the same way Claude Code does.
+    // session-stop will still record session-level telemetry from what's available.
+    transcript_path: "",
+  };
+
+  try {
+    const { processSessionStop } = await import("../../hooks/session-stop.js");
+    await processSessionStop(payload);
+  } catch {
+    /* fail-open */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function cliMain(): Promise<void> {
+  try {
+    const { full } = await readStdin();
+
+    if (!full.trim()) {
+      outputResponse();
+      return;
+    }
+
+    let input: ClineHookInput;
+    try {
+      input = JSON.parse(full) as ClineHookInput;
+    } catch {
+      outputResponse();
+      return;
+    }
+
+    const { hookName } = input;
+    if (!hookName) {
+      outputResponse();
+      return;
+    }
+
+    if (hookName === "PostToolUse") {
+      await handlePostToolUse(input);
+    } else if (hookName === "TaskComplete" || hookName === "TaskCancel") {
+      await handleTaskEnd(input);
+    }
+    // Unknown events are silently ignored (fail-open)
+
+    outputResponse();
+  } catch {
+    // Fail-open: always output a valid response
+    outputResponse();
+  }
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  await cliMain();
+  process.exit(0);
+}

package/cli/selftune/adapters/cline/install.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * Install selftune hooks into Cline environment.
+ *
+ * Creates hook scripts in ~/Documents/Cline/Hooks/ for:
+ *   - PostToolUse  (inline  — commit tracking, fast path)
+ *   - TaskComplete (background — session telemetry)
+ *   - TaskCancel   (background — session cleanup)
+ *
+ * Each hook is a bash shim that pipes stdin to `npx selftune cline hook`.
+ *
+ * Usage: selftune cline install [--dry-run] [--uninstall]
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CLINE_HOOKS_DIR = join(homedir(), "Documents", "Cline", "Hooks");
+const MARKER = "# selftune-managed";
+
+// ---------------------------------------------------------------------------
+// Hook script generators
+// ---------------------------------------------------------------------------
+
+/** Build a hook command that prefers SELFTUNE_CLI_PATH, then npx. */
+const HOOK_CMD =
+  'if [ -n "$SELFTUNE_CLI_PATH" ]; then "$SELFTUNE_CLI_PATH" cline hook; else npx selftune cline hook; fi';
+
+function hookScript(hookName: string): string {
+  if (hookName === "PostToolUse") {
+    // Inline — commit tracking is fast; finish before Cline moves on.
+    // hook.ts writes {"cancel": false} to stdout, so we suppress only stderr.
+    return `#!/usr/bin/env bash
+${MARKER}
+input=$(cat)
+echo "$input" | (${HOOK_CMD}) 2>/dev/null || echo '{"cancel": false}'
+`;
+  }
+
+  // Background — session telemetry upload can be slow; don't block Cline
+  return `#!/usr/bin/env bash
+${MARKER}
+input=$(cat)
+echo "$input" | (${HOOK_CMD}) &>/dev/null &
+echo '{"cancel": false}'
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Hook definitions
+// ---------------------------------------------------------------------------
+
+const HOOKS: Array<{ name: string; description: string }> = [
+  { name: "PostToolUse", description: "Track git commits via selftune" },
+  { name: "TaskComplete", description: "Record session telemetry when a Cline task completes" },
+  { name: "TaskCancel", description: "Record session telemetry when a Cline task is cancelled" },
+];
+
+// ---------------------------------------------------------------------------
+// Install
+// ---------------------------------------------------------------------------
+
+function installHooks(dryRun: boolean): void {
+  console.log("Setting up selftune hooks for Cline...");
+  console.log(`Hooks directory: ${CLINE_HOOKS_DIR}`);
+  console.log("");
+
+  if (!dryRun) {
+    mkdirSync(CLINE_HOOKS_DIR, { recursive: true });
+  }
+
+  let installed = 0;
+  let skipped = 0;
+
+  for (const hook of HOOKS) {
+    const hookPath = join(CLINE_HOOKS_DIR, hook.name);
+
+    if (existsSync(hookPath)) {
+      const existing = readFileSync(hookPath, "utf-8");
+      if (existing.includes(MARKER)) {
+        if (dryRun) {
+          console.log(`  Would update: ${hook.name}`);
+        } else {
+          writeFileSync(hookPath, hookScript(hook.name), { mode: 0o755 });
+          chmodSync(hookPath, 0o755);
+          console.log(`  Updated: ${hook.name}`);
+        }
+        installed++;
+      } else {
+        console.log(`  Skipped: ${hook.name} (existing hook not managed by selftune)`);
+        skipped++;
+      }
+    } else {
+      if (dryRun) {
+        console.log(`  Would create: ${hook.name}`);
+      } else {
+        writeFileSync(hookPath, hookScript(hook.name), { mode: 0o755 });
+        console.log(`  Created: ${hook.name}`);
+      }
+      installed++;
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`Dry run: ${installed} hook(s) would be installed.`);
+  } else if (installed > 0) {
+    console.log(`Installed ${installed} hook(s).`);
+  }
+  if (skipped > 0) {
+    console.log(`Skipped ${skipped} hook(s) with existing non-selftune content.`);
+  }
+  if (!dryRun && installed > 0) {
+    console.log("");
+    if (skipped === 0) {
+      console.log("Cline will now track commits and record session telemetry.");
+    } else {
+      console.log("Partial install: some hooks were skipped. Telemetry may be incomplete.");
+    }
+    console.log("Run `selftune status` to verify setup.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Uninstall
+// ---------------------------------------------------------------------------
+
+function uninstallHooks(dryRun: boolean): void {
+  console.log("Removing selftune hooks from Cline...");
+  console.log("");
+
+  let removed = 0;
+  let skipped = 0;
+
+  for (const hook of HOOKS) {
+    const hookPath = join(CLINE_HOOKS_DIR, hook.name);
+
+    if (!existsSync(hookPath)) {
+      console.log(`  Not found: ${hook.name}`);
+      continue;
+    }
+
+    const existing = readFileSync(hookPath, "utf-8");
+    if (!existing.includes(MARKER)) {
+      console.log(`  Skipped: ${hook.name} (not managed by selftune)`);
+      skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`  Would remove: ${hook.name}`);
+    } else {
+      rmSync(hookPath);
+      console.log(`  Removed: ${hook.name}`);
+    }
+    removed++;
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`Dry run: ${removed} hook(s) would be removed.`);
+  } else if (removed > 0) {
+    console.log(`Removed ${removed} hook(s).`);
+  }
+  if (skipped > 0) {
+    console.log(`Skipped ${skipped} hook(s) not managed by selftune.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function cliMain(): Promise<void> {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const uninstall = args.includes("--uninstall");
+
+  if (uninstall) {
+    uninstallHooks(dryRun);
+  } else {
+    installHooks(dryRun);
+  }
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    await cliMain();
+  } catch (err) {
+    console.error(
+      `[selftune] Cline install failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}

package/cli/selftune/adapters/codex/hook.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env bun
+/**
+ * Codex hook adapter for selftune.
+ *
+ * Reads Codex hook payloads from stdin and delegates to shared selftune hook logic.
+ * Codex uses the same hook protocol as Claude Code (JSON on stdin, JSON on stdout),
+ * so the payloads are structurally identical.
+ *
+ * Usage: echo '$HOOK_PAYLOAD' | selftune codex hook
+ *
+ * Event routing:
+ *   SessionStart  -> prompt-log (processPrompt) + auto-activate (processAutoActivate)
+ *   PreToolUse    -> skill-change-guard + evolution-guard
+ *   PostToolUse   -> skill-eval (processToolUse) + commit-track (processCommitTrack)
+ *   Stop          -> session-stop (processSessionStop)
+ *
+ * Exit codes:
+ *   0 = success / allow
+ *   2 = block (PreToolUse guard rejection, Claude Code convention)
+ *
+ * Fail-open: any unhandled error -> exit 0, never crash the host agent.
+ */
+
+import type {
+  PostToolUsePayload,
+  PreToolUsePayload,
+  PromptSubmitPayload,
+  StopPayload,
+} from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Codex hook payload — superset of all event fields. */
+export interface CodexHookPayload {
+  hook_event_name?: string;
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_use_id?: string;
+  tool_response?: Record<string, unknown>;
+  prompt?: string;
+  user_prompt?: string;
+  permission_mode?: string;
+  stop_hook_active?: boolean;
+  last_assistant_message?: string;
+  [key: string]: unknown;
+}
+
+/** Response written to stdout. Empty object = no-op. */
+type HookResponse = Record<string, unknown>;
+
+const EMPTY_RESPONSE: HookResponse = {};
+
+// ---------------------------------------------------------------------------
+// Event handlers (dynamic imports for fast startup)
+// ---------------------------------------------------------------------------
+
+async function handleSessionStart(payload: CodexHookPayload): Promise<HookResponse> {
+  // 1. Prompt logging
+  try {
+    const { processPrompt } = await import("../../hooks/prompt-log.js");
+    const promptPayload: PromptSubmitPayload = {
+      session_id: payload.session_id,
+      transcript_path: payload.transcript_path,
+      cwd: payload.cwd,
+      prompt: payload.prompt,
+      user_prompt: payload.user_prompt,
+      hook_event_name: "UserPromptSubmit",
+    };
+    await processPrompt(promptPayload);
+  } catch {
+    // fail-open
+  }
+
+  // 2. Auto-activate suggestions
+  let response: HookResponse = EMPTY_RESPONSE;
+  try {
+    const { processAutoActivate } = await import("../../hooks/auto-activate.js");
+    const sessionId = payload.session_id ?? "unknown";
+    const suggestions = await processAutoActivate(sessionId);
+    if (suggestions.length > 0) {
+      const context = suggestions.map((s) => `[selftune] Suggestion: ${s}`).join("\n");
+      // Codex supports hookSpecificOutput.additionalContext like Claude Code
+      response = {
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: context,
+        },
+      };
+    }
+  } catch {
+    // fail-open
+  }
+
+  return response;
+}
+
+async function handlePreToolUse(
+  payload: CodexHookPayload,
+): Promise<{ response: HookResponse; exitCode: number }> {
+  const prePayload: PreToolUsePayload = {
+    tool_name: payload.tool_name ?? "",
+    tool_input: payload.tool_input ?? {},
+    tool_use_id: payload.tool_use_id,
+    session_id: payload.session_id,
+    transcript_path: payload.transcript_path,
+    cwd: payload.cwd,
+    permission_mode: payload.permission_mode,
+    hook_event_name: "PreToolUse",
+  };
+
+  // Import constants once for both guards
+  let constants:
+    | { EVOLUTION_AUDIT_LOG: string; SELFTUNE_CONFIG_DIR: string; SESSION_STATE_DIR: string }
+    | undefined;
+  try {
+    constants = await import("../../constants.js");
+  } catch {
+    // fail-open
+  }
+
+  // 1. Evolution guard (can block with exit 2)
+  try {
+    if (constants) {
+      const { processEvolutionGuard } = await import("../../hooks/evolution-guard.js");
+      const guardResult = await processEvolutionGuard(prePayload, {
+        auditLogPath: constants.EVOLUTION_AUDIT_LOG,
+        selftuneDir: constants.SELFTUNE_CONFIG_DIR,
+      });
+      if (guardResult) {
+        process.stderr.write(`${guardResult.message}\n`);
+        return { response: EMPTY_RESPONSE, exitCode: guardResult.exitCode };
+      }
+    }
+  } catch {
+    // fail-open
+  }
+
+  // 2. Skill change guard (advisory only, never blocks)
+  try {
+    if (constants) {
+      const { processPreToolUse } = await import("../../hooks/skill-change-guard.js");
+      const sessionId = payload.session_id ?? "unknown";
+      const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+      const statePath = `${constants.SESSION_STATE_DIR}/guard-state-${safe}.json`;
+      const suggestion = processPreToolUse(prePayload, statePath);
+      if (suggestion) {
+        process.stderr.write(`[selftune] Suggestion: ${suggestion}\n`);
+      }
+    }
+  } catch {
+    // fail-open
+  }
+
+  return { response: EMPTY_RESPONSE, exitCode: 0 };
+}
+
+async function handlePostToolUse(payload: CodexHookPayload): Promise<HookResponse> {
+  const postPayload: PostToolUsePayload = {
+    tool_name: payload.tool_name ?? "",
+    tool_input: payload.tool_input ?? {},
+    tool_use_id: payload.tool_use_id,
+    tool_response: payload.tool_response,
+    session_id: payload.session_id,
+    transcript_path: payload.transcript_path,
+    cwd: payload.cwd,
+    permission_mode: payload.permission_mode,
+    hook_event_name: "PostToolUse",
+  };
+
+  // 1. Skill eval (Read/Skill tool usage tracking)
+  try {
+    const { processToolUse } = await import("../../hooks/skill-eval.js");
+    await processToolUse(postPayload);
+  } catch {
+    // fail-open
+  }
+
+  // 2. Commit tracking (git commit detection in Bash output)
+  try {
+    const { processCommitTrack } = await import("../../hooks/commit-track.js");
+    await processCommitTrack(postPayload);
+  } catch {
+    // fail-open
+  }
+
+  return EMPTY_RESPONSE;
+}
+
+async function handleStop(payload: CodexHookPayload): Promise<HookResponse> {
+  try {
+    const { processSessionStop } = await import("../../hooks/session-stop.js");
+    const stopPayload: StopPayload = {
+      session_id: payload.session_id,
+      transcript_path: payload.transcript_path,
+      cwd: payload.cwd,
+      permission_mode: payload.permission_mode,
+      stop_hook_active: payload.stop_hook_active,
+      last_assistant_message:
+        typeof payload.last_assistant_message === "string"
+          ? payload.last_assistant_message
+          : undefined,
+      hook_event_name: "Stop",
+    };
+    await processSessionStop(stopPayload);
+  } catch {
+    // fail-open
+  }
+  return EMPTY_RESPONSE;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+function writeResponseAndExit(response: HookResponse, code: number): void {
+  const data = JSON.stringify(response);
+  process.stdout.write(data, () => {
+    process.exit(code);
+  });
+}
+
+/**
+ * CLI entry point. Reads stdin, routes to the correct handler, writes response.
+ */
+export async function cliMain(): Promise<void> {
+  let exitCode = 0;
+
+  try {
+    const { readStdinWithPreview } = await import("../../hooks/stdin-preview.js");
+    const { full } = await readStdinWithPreview();
+
+    // Fast-path: empty stdin -> no-op
+    if (!full.trim()) {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    let payload: CodexHookPayload;
+    try {
+      payload = JSON.parse(full) as CodexHookPayload;
+    } catch {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    const eventName = typeof payload.hook_event_name === "string" ? payload.hook_event_name : "";
+
+    // Fast-path: use preview to skip irrelevant events without full routing
+    if (!eventName) {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    let response: HookResponse = EMPTY_RESPONSE;
+
+    switch (eventName) {
+      case "SessionStart": {
+        response = await handleSessionStart(payload);
+        break;
+      }
+      case "PreToolUse": {
+        const result = await handlePreToolUse(payload);
+        response = result.response;
+        exitCode = result.exitCode;
+        break;
+      }
+      case "PostToolUse": {
+        response = await handlePostToolUse(payload);
+        break;
+      }
+      case "Stop": {
+        response = await handleStop(payload);
+        break;
+      }
+      default: {
+        // Unknown event — no-op
+        break;
+      }
+    }
+
+    writeResponseAndExit(response, exitCode);
+  } catch {
+    // Fail-open: never crash
+    writeResponseAndExit(EMPTY_RESPONSE, 0);
+  }
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  await cliMain();
+}