selftune 0.2.14 → 0.2.15

package/cli/selftune/grading/grade-session.ts

@@ -28,6 +28,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import {
   detectAgent as _detectAgent,
   stripMarkdownFences as _stripMarkdownFences,
@@ -743,8 +744,7 @@ Options:
 
   const skill = values.skill;
   if (!skill) {
-    console.error("[ERROR] --skill is required");
-    process.exit(1);
+    throw new CLIError("--skill is required", "MISSING_FLAG", "selftune grade --skill <name>");
   }
 
   // --- Determine agent ---
@@ -752,10 +752,11 @@ Options:
   const validAgents = [...AGENT_CANDIDATES];
   if (values.agent) {
     if (!validAgents.includes(values.agent)) {
-      console.error(
-        `[ERROR] Invalid --agent '${values.agent}'. Expected one of: ${validAgents.join(", ")}`,
+      throw new CLIError(
+        `Invalid --agent '${values.agent}'. Expected one of: ${validAgents.join(", ")}`,
+        "INVALID_FLAG",
+        `selftune grade --skill <name> --agent ${validAgents[0]}`,
       );
-      process.exit(1);
     }
     agent = values.agent;
   } else {
@@ -763,11 +764,11 @@ Options:
   }
 
   if (!agent) {
-    console.error(
-      `[ERROR] No supported agent CLI (${AGENT_CANDIDATES.join("/")}) found in PATH.\n` +
-        "Install one of the supported agent CLIs.",
+    throw new CLIError(
+      `No supported agent CLI (${AGENT_CANDIDATES.join("/")}) found in PATH`,
+      "AGENT_NOT_FOUND",
+      "Install claude, codex, or opencode CLI, then retry",
     );
-    process.exit(1);
   }
 
   console.error(`[INFO] Grading via agent: ${agent}`);
@@ -777,8 +778,11 @@ Options:
   if (values["evals-json"] && values["eval-id"] != null) {
     const evalIdNum = Number(values["eval-id"]);
     if (!Number.isFinite(evalIdNum) || !Number.isInteger(evalIdNum)) {
-      console.error(`[ERROR] --eval-id must be a finite integer, got: ${values["eval-id"]}`);
-      process.exit(1);
+      throw new CLIError(
+        `--eval-id must be a finite integer, got: ${values["eval-id"]}`,
+        "INVALID_FLAG",
+        "selftune grade --eval-id <integer>",
+      );
     }
     expectations = loadExpectationsFromEvalsJson(values["evals-json"], evalIdNum);
   } else if (values.expectations?.length) {
@@ -863,8 +867,11 @@ Options:
       agent,
     });
   } catch (err) {
-    console.error(`[ERROR] ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+    throw new CLIError(
+      `Grading failed: ${err instanceof Error ? err.message : String(err)}`,
+      "OPERATION_FAILED",
+      "Check agent availability and try again",
+    );
   }
 
   const outputPath = values.output ?? buildDefaultGradingOutputPath(sessionId);
@@ -888,8 +895,5 @@ Options:
 
 // Guard: only run when invoked directly
 if (import.meta.main) {
-  cliMain().catch((err) => {
-    console.error(`[FATAL] ${err}`);
-    process.exit(1);
-  });
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/hooks/auto-activate.ts

@@ -179,9 +179,18 @@ if (import.meta.main) {
       const statePath = sessionStatePath(sessionId);
       const suggestions = evaluateRules(DEFAULT_RULES, ctx, statePath);
 
-      for (const s of suggestions) {
-        // Output to stderr — Claude Code shows stderr as system messages
-        process.stderr.write(`[selftune] 💡 Suggestion: ${s}\n`);
+      if (suggestions.length > 0) {
+        // Output as JSON with additionalContext — Claude Code adds this to
+        // Claude's context on UserPromptSubmit (more reliable than stderr)
+        const context = suggestions.map((s) => `[selftune] Suggestion: ${s}`).join("\n");
+        process.stdout.write(
+          JSON.stringify({
+            hookSpecificOutput: {
+              hookEventName: "UserPromptSubmit",
+              additionalContext: context,
+            },
+          }),
+        );
       }
     }
   } catch {

package/cli/selftune/hooks/prompt-log.ts

@@ -154,7 +154,13 @@ export async function processPrompt(
   promptStatePath?: string,
   _signalLogPath?: string,
 ): Promise<QueryLogRecord | null> {
-  const query = (payload.user_prompt ?? "").trim();
+  const rawPrompt =
+    typeof payload.prompt === "string"
+      ? payload.prompt
+      : typeof payload.user_prompt === "string"
+        ? payload.user_prompt
+        : "";
+  const query = rawPrompt.trim();
 
   if (!query) return null;
 

package/cli/selftune/index.ts

@@ -29,6 +29,11 @@
  *   selftune hook <name>        — Run a hook by name (prompt-log, session-stop, etc.)
  */
 
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
+
+process.on("uncaughtException", handleCLIError);
+process.on("unhandledRejection", handleCLIError);
+
 const command = process.argv[2];
 
 if (command === "--help" || command === "-h") {
@@ -84,6 +89,7 @@ if (!command) {
   // Show status by default — same as `selftune status`
   const { cliMain: statusMain } = await import("./status.js");
   statusMain();
+  process.exit(0);
 }
 
 // Route to the appropriate subcommand module.
@@ -142,10 +148,11 @@ Run 'selftune ingest <agent> --help' for agent-specific options.`);
         break;
       }
       default:
-        console.error(
-          `Unknown ingest agent: ${sub}\nRun 'selftune ingest --help' for available agents.`,
+        throw new CLIError(
+          `Unknown ingest agent: ${sub}`,
+          "UNKNOWN_COMMAND",
+          "selftune ingest --help",
         );
-        process.exit(1);
     }
     break;
   }
@@ -182,10 +189,11 @@ Run 'selftune grade <subcommand> --help' for subcommand-specific options.`);
           break;
         }
         default:
-          console.error(
-            `Unknown grade mode: ${sub}\nRun 'selftune grade --help' for available modes.`,
+          throw new CLIError(
+            `Unknown grade mode: ${sub}`,
+            "UNKNOWN_COMMAND",
+            "selftune grade --help",
           );
-          process.exit(1);
       }
     }
     break;
@@ -223,10 +231,11 @@ Run 'selftune evolve <subcommand> --help' for subcommand-specific options.`);
           break;
         }
         default:
-          console.error(
-            `Unknown evolve target: ${sub}\nRun 'selftune evolve --help' for available targets.`,
+          throw new CLIError(
+            `Unknown evolve target: ${sub}`,
+            "UNKNOWN_COMMAND",
+            "selftune evolve --help",
           );
-          process.exit(1);
       }
     }
     break;
@@ -289,13 +298,18 @@ Run 'selftune eval <action> --help' for action-specific options.`);
           }));
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          console.error(`Invalid arguments: ${message}`);
-          console.error("Run 'selftune eval composability --help' for usage.");
-          process.exit(1);
+          throw new CLIError(
+            `Invalid arguments: ${message}`,
+            "INVALID_FLAG",
+            "selftune eval composability --help",
+          );
         }
         if (!values.skill) {
-          console.error("[ERROR] --skill <name> is required.");
-          process.exit(1);
+          throw new CLIError(
+            "--skill <name> is required.",
+            "MISSING_FLAG",
+            "selftune eval composability --skill <name>",
+          );
         }
         const logPath = values["telemetry-log"] ?? TELEMETRY_LOG;
         let telemetry: unknown[];
@@ -316,8 +330,11 @@ Run 'selftune eval <action> --help' for action-specific options.`);
         }
         const rawWindow = values.window as string | undefined;
         if (rawWindow !== undefined && !/^[1-9]\d*$/.test(rawWindow)) {
-          console.error("Invalid --window value. Use a positive integer number of days.");
-          process.exit(1);
+          throw new CLIError(
+            "Invalid --window value. Use a positive integer number of days.",
+            "INVALID_FLAG",
+            "selftune eval composability --skill <name> --window 30",
+          );
         }
         const windowSize = rawWindow === undefined ? undefined : Number(rawWindow);
         const report = analyzeComposability(values.skill, telemetry, windowSize);
@@ -325,10 +342,11 @@ Run 'selftune eval <action> --help' for action-specific options.`);
         break;
       }
       default:
-        console.error(
-          `Unknown eval action: ${sub}\nRun 'selftune eval --help' for available actions.`,
+        throw new CLIError(
+          `Unknown eval action: ${sub}`,
+          "UNKNOWN_COMMAND",
+          "selftune eval --help",
         );
-        process.exit(1);
     }
     break;
   }
@@ -457,10 +475,11 @@ Run 'selftune cron <subcommand> --help' for subcommand-specific options.`);
         break;
       }
       default:
-        console.error(
-          `Unknown cron subcommand: ${sub}\nRun 'selftune cron --help' for available subcommands.`,
+        throw new CLIError(
+          `Unknown cron subcommand: ${sub}`,
+          "UNKNOWN_COMMAND",
+          "selftune cron --help",
         );
-        process.exit(1);
     }
     break;
   }
@@ -505,9 +524,7 @@ Run 'selftune cron <subcommand> --help' for subcommand-specific options.`);
       }));
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      console.error(`Invalid arguments: ${message}`);
-      console.error("Run 'selftune export --help' for usage.");
-      process.exit(1);
+      throw new CLIError(`Invalid arguments: ${message}`, "INVALID_FLAG", "selftune export --help");
     }
     if (values.help) {
       console.log(`selftune export — Export SQLite data to JSONL files
@@ -544,9 +561,7 @@ Options:
       }
     } catch (err: unknown) {
       const message = err instanceof Error ? err.message : String(err);
-      console.error(`Export failed: ${message}`);
-      console.error("Ensure the SQLite database exists. Run 'selftune sync' first if needed.");
-      process.exit(1);
+      throw new CLIError(`Export failed: ${message}`, "OPERATION_FAILED", "selftune sync");
     }
     break;
   }
@@ -590,8 +605,11 @@ Run 'selftune alpha <subcommand> --help' for subcommand-specific options.`);
           }));
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
-          console.error(`Invalid arguments: ${message}`);
-          process.exit(1);
+          throw new CLIError(
+            `Invalid arguments: ${message}`,
+            "INVALID_FLAG",
+            "selftune alpha upload --help",
+          );
         }
         if (values.help) {
           console.log(`selftune alpha upload — Run a manual alpha data upload cycle
@@ -619,44 +637,20 @@ Output:
         const identity = readAlphaIdentity(SELFTUNE_CONFIG_PATH);
         if (!identity?.enrolled) {
           const guidance = getAlphaGuidance(identity);
-          console.log(
-            JSON.stringify(
-              {
-                enrolled: false,
-                prepared: 0,
-                sent: 0,
-                failed: 0,
-                skipped: 0,
-                guidance,
-              },
-              null,
-              2,
-            ),
+          throw new CLIError(
+            `[alpha upload] ${guidance.message}`,
+            "OPERATION_FAILED",
+            guidance.next_command,
           );
-          console.error(`[alpha upload] ${guidance.message}`);
-          console.error(`[alpha upload] Next: ${guidance.next_command}`);
-          process.exit(1);
         }
 
         if (!identity.user_id?.trim() || !identity.api_key?.trim()) {
           const guidance = getAlphaGuidance(identity);
-          console.log(
-            JSON.stringify(
-              {
-                enrolled: true,
-                prepared: 0,
-                sent: 0,
-                failed: 0,
-                skipped: 0,
-                guidance,
-              },
-              null,
-              2,
-            ),
+          throw new CLIError(
+            `[alpha upload] ${guidance.message}`,
+            "OPERATION_FAILED",
+            guidance.next_command,
           );
-          console.error(`[alpha upload] ${guidance.message}`);
-          console.error(`[alpha upload] Next: ${guidance.next_command}`);
-          process.exit(1);
         }
 
         const db = getDb();
@@ -742,10 +736,11 @@ Output:
         break;
       }
       default:
-        console.error(
-          `Unknown alpha subcommand: ${sub}\nRun 'selftune alpha --help' for available subcommands.`,
+        throw new CLIError(
+          `Unknown alpha subcommand: ${sub}`,
+          "UNKNOWN_COMMAND",
+          "selftune alpha --help",
         );
-        process.exit(1);
     }
     break;
   }
@@ -767,8 +762,11 @@ Output:
     };
     if (!hookName || !HOOK_MAP[hookName]) {
       const available = Object.keys(HOOK_MAP).join(", ");
-      console.error(`Unknown hook: ${hookName ?? "(none)"}\nAvailable hooks: ${available}`);
-      process.exit(1);
+      throw new CLIError(
+        `Unknown hook: ${hookName ?? "(none)"}. Available: ${available}`,
+        "UNKNOWN_COMMAND",
+        "selftune hook prompt-log",
+      );
     }
     const { resolve, dirname } = await import("node:path");
     const { fileURLToPath } = await import("node:url");
@@ -782,6 +780,5 @@ Output:
     break;
   }
   default:
-    console.error(`Unknown command: ${command}\nRun 'selftune --help' for available commands.`);
-    process.exit(1);
+    throw new CLIError(`Unknown command: ${command}`, "UNKNOWN_COMMAND", "selftune --help");
 }

package/cli/selftune/ingestors/claude-replay.ts

@@ -55,6 +55,7 @@ import type {
   SessionTelemetryRecord,
   TranscriptMetrics,
 } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import { loadMarker, saveMarker } from "../utils/jsonl.js";
 import { isActionableQueryText } from "../utils/query-filter.js";
 import {
@@ -326,26 +327,36 @@ export function buildCanonicalRecordsFromReplay(session: ParsedSession): Canonic
 
 // --- CLI main ---
 export function cliMain(): void {
-  const { values } = parseArgs({
-    options: {
-      "projects-dir": { type: "string", default: CLAUDE_CODE_PROJECTS_DIR },
-      since: { type: "string" },
-      "dry-run": { type: "boolean", default: false },
-      force: { type: "boolean", default: false },
-      verbose: { type: "boolean", short: "v", default: false },
-    },
-    strict: true,
-  });
+  let values: Record<string, string | boolean | undefined>;
+  try {
+    ({ values } = parseArgs({
+      options: {
+        "projects-dir": { type: "string", default: CLAUDE_CODE_PROJECTS_DIR },
+        since: { type: "string" },
+        "dry-run": { type: "boolean", default: false },
+        force: { type: "boolean", default: false },
+        verbose: { type: "boolean", short: "v", default: false },
+      },
+      strict: true,
+    }));
+  } catch (err) {
+    throw new CLIError(
+      err instanceof Error ? err.message : String(err),
+      "INVALID_FLAG",
+      "selftune ingest claude --since 2026-01-01",
+    );
+  }
 
   const projectsDir = values["projects-dir"] ?? CLAUDE_CODE_PROJECTS_DIR;
   let since: Date | undefined;
   if (values.since) {
     since = new Date(values.since);
     if (Number.isNaN(since.getTime())) {
-      console.error(
-        `Error: Invalid --since date: "${values.since}". Use a valid date format (e.g., 2026-01-01).`,
+      throw new CLIError(
+        `Invalid --since date: "${values.since}"`,
+        "INVALID_FLAG",
+        "selftune ingest claude --since 2026-01-01",
       );
-      process.exit(1);
     }
   }
 
@@ -401,5 +412,9 @@ export function cliMain(): void {
 }
 
 if (import.meta.main) {
-  cliMain();
+  try {
+    cliMain();
+  } catch (err) {
+    handleCLIError(err);
+  }
 }

package/cli/selftune/ingestors/codex-rollout.ts

@@ -49,6 +49,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { handleCLIError } from "../utils/cli-error.js";
 import { loadMarker, saveMarker } from "../utils/jsonl.js";
 import { extractActionableQueryText } from "../utils/query-filter.js";
 import {
@@ -717,5 +718,9 @@ export function cliMain(): void {
 }
 
 if (import.meta.main) {
-  cliMain();
+  try {
+    cliMain();
+  } catch (err) {
+    handleCLIError(err);
+  }
 }

package/cli/selftune/init.ts

@@ -44,6 +44,7 @@ import {
 import { installAgentFiles } from "./claude-agents.js";
 import { CLAUDE_CODE_HOOK_KEYS, SELFTUNE_CONFIG_DIR, SELFTUNE_CONFIG_PATH } from "./constants.js";
 import type { AgentCommandGuidance, AlphaIdentity, SelftuneConfig } from "./types.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
 import { hookKeyHasSelftuneEntry } from "./utils/hooks.js";
 import { detectAgent } from "./utils/llm-call.js";
 
@@ -692,8 +693,11 @@ export async function cliMain(): Promise<void> {
   try {
     validateAlphaMetadataFlags(values.alpha, values["alpha-email"], values["alpha-name"]);
   } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    throw new CLIError(
+      error instanceof Error ? error.message : String(error),
+      "INVALID_FLAG",
+      "Pass --alpha along with --alpha-email and --alpha-name.",
+    );
   }
 
   // Check for existing config without force
@@ -890,10 +894,11 @@ export async function cliMain(): Promise<void> {
       });
 
       if (!scheduleResult.activated) {
-        console.error(
-          "Failed to activate the autonomous scheduler. Re-run with --schedule-format or use `selftune schedule --install --dry-run` to inspect the generated artifacts first.",
+        throw new CLIError(
+          "Failed to activate the autonomous scheduler.",
+          "OPERATION_FAILED",
+          "Re-run with --schedule-format or use `selftune schedule --install --dry-run` to inspect the generated artifacts first.",
         );
-        process.exit(1);
       }
 
       console.log(
@@ -906,10 +911,11 @@ export async function cliMain(): Promise<void> {
         }),
       );
     } catch (err) {
-      console.error(
+      throw new CLIError(
         `Failed to enable autonomy: ${err instanceof Error ? err.message : String(err)}`,
+        "OPERATION_FAILED",
+        "Re-run with --schedule-format or use `selftune schedule --install --dry-run` to inspect artifacts.",
       );
-      process.exit(1);
     }
   }
 }
@@ -947,7 +953,6 @@ if (isMain) {
       console.error(JSON.stringify(err.payload));
       process.exit(1);
     }
-    console.error(`[FATAL] ${err}`);
-    process.exit(1);
+    handleCLIError(err);
   });
 }

package/cli/selftune/monitoring/watch.ts

@@ -26,6 +26,7 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { CLIError, handleCLIError } from "../utils/cli-error.js";
 import {
   filterActionableQueryRecords,
   filterActionableSkillUsageRecords,
@@ -354,34 +355,52 @@ Options:
   }
 
   if (!values.skill || !values["skill-path"]) {
-    console.error("[ERROR] --skill and --skill-path are required");
-    process.exit(1);
+    throw new CLIError(
+      "--skill and --skill-path are required.",
+      "MISSING_FLAG",
+      "Usage: selftune watch --skill <name> --skill-path <path>",
+    );
   }
   if ((values["sync-force"] ?? false) && !(values["sync-first"] ?? false)) {
-    console.error("[ERROR] --sync-force requires --sync-first");
-    process.exit(1);
+    throw new CLIError(
+      "--sync-force requires --sync-first.",
+      "INVALID_FLAG",
+      "Add --sync-first when using --sync-force.",
+    );
   }
 
   const rawWindow = values.window ?? "20";
   if (!/^\d+$/.test(rawWindow)) {
-    console.error("[ERROR] --window must be a positive integer >= 1");
-    process.exit(1);
+    throw new CLIError(
+      "--window must be a positive integer >= 1.",
+      "INVALID_FLAG",
+      "selftune watch --window 20",
+    );
   }
   const windowSessions = Number.parseInt(rawWindow, 10);
   if (windowSessions < 1) {
-    console.error("[ERROR] --window must be a positive integer >= 1");
-    process.exit(1);
+    throw new CLIError(
+      "--window must be a positive integer >= 1.",
+      "INVALID_FLAG",
+      "selftune watch --window 20",
+    );
   }
 
   const rawThreshold = values.threshold ?? "0.1";
   if (!/^\d+(\.\d+)?$/.test(rawThreshold)) {
-    console.error("[ERROR] --threshold must be a finite number between 0 and 1");
-    process.exit(1);
+    throw new CLIError(
+      "--threshold must be a finite number between 0 and 1.",
+      "INVALID_FLAG",
+      "selftune watch --threshold 0.1",
+    );
   }
   const regressionThreshold = Number.parseFloat(rawThreshold);
   if (regressionThreshold < 0 || regressionThreshold > 1) {
-    console.error("[ERROR] --threshold must be a finite number between 0 and 1");
-    process.exit(1);
+    throw new CLIError(
+      "--threshold must be a finite number between 0 and 1.",
+      "INVALID_FLAG",
+      "selftune watch --threshold 0.1",
+    );
   }
 
   const result = await watch({
@@ -399,8 +418,5 @@ Options:
 }
 
 if (import.meta.main) {
-  cliMain().catch((err) => {
-    console.error(`[FATAL] ${err}`);
-    process.exit(1);
-  });
+  cliMain().catch(handleCLIError);
 }