selftune 0.2.13 → 0.2.15

package/cli/selftune/schedule.ts

@@ -18,6 +18,26 @@ import { dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 
 import { DEFAULT_CRON_JOBS } from "./cron/setup.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
+
+// ---------------------------------------------------------------------------
+// Binary resolution — launchd runs with minimal PATH, so we need full paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path to the `selftune` binary.
+ * 1. Bun.which (Bun-native, no spawn)
+ * 2. Fallback: ~/.bun/bin/selftune (common bun global install location)
+ */
+export function resolveSelftuneBin(): string {
+  try {
+    const resolved = Bun.which("selftune");
+    if (resolved) return resolved;
+  } catch {
+    // Bun.which may throw in edge cases — fall through
+  }
+  return join(homedir(), ".bun", "bin", "selftune");
+}
 
 // ---------------------------------------------------------------------------
 // Schedule definitions — derived from the shared DEFAULT_CRON_JOBS
@@ -137,6 +157,8 @@ function toSystemdExecStart(command: string): string {
 // ---------------------------------------------------------------------------
 
 export function generateCrontab(): string {
+  const resolvedBin = resolveSelftuneBin();
+  const home = homedir();
   const lines = [
     "# selftune automation — add to your crontab with: crontab -e",
     "#",
@@ -144,10 +166,13 @@ export function generateCrontab(): string {
     "# status remains a reporting job; orchestrate handles sync, candidate",
     "# selection, low-risk description evolution, and watch/rollback follow-up.",
     "#",
+    `PATH=${home}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin`,
+    "",
   ];
   for (const entry of SCHEDULE_ENTRIES) {
+    const resolvedCommand = entry.command.replace(/\bselftune\b/g, resolvedBin);
     lines.push(`# ${entry.description}`);
-    lines.push(`${entry.schedule}  ${entry.command}`);
+    lines.push(`${entry.schedule}  ${resolvedCommand}`);
     lines.push("");
   }
   return lines.join("\n");
@@ -177,10 +202,17 @@ export function mergeManagedCrontab(existing: string, managedContent: string): s
   return `${withoutExistingBlock}\n\n${managedBlock}`;
 }
 
-function buildLaunchdDefinition(entry: ScheduleEntry): { label: string; content: string } {
+function buildLaunchdDefinition(
+  entry: ScheduleEntry,
+  binPath?: string,
+): { label: string; content: string } {
   const label = `com.selftune.${entry.name.replace("selftune-", "")}`;
-  const args = toLaunchdArgs(entry.command);
+  const resolvedBin = binPath ?? resolveSelftuneBin();
+  // Replace bare `selftune` with the resolved absolute path
+  const resolvedCommand = entry.command.replace(/\bselftune\b/g, resolvedBin);
+  const args = toLaunchdArgs(resolvedCommand);
   const schedule = cronToLaunchdSchedule(entry.schedule);
+  const home = homedir();
 
   return {
     label,
@@ -198,6 +230,13 @@ function buildLaunchdDefinition(entry: ScheduleEntry): { label: string; content:
 <dict>
   <key>Label</key>
   <string>${label}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${home}/.bun/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    <key>HOME</key>
+    <string>${home}</string>
+  </dict>
   <key>ProgramArguments</key>
   <array>
 ${args}
@@ -222,14 +261,20 @@ export function generateLaunchd(): string {
   return plists.join("\n\n");
 }
 
-function buildSystemdDefinition(entry: ScheduleEntry): {
+function buildSystemdDefinition(
+  entry: ScheduleEntry,
+  binPath?: string,
+): {
   baseName: string;
   timerContent: string;
   serviceContent: string;
 } {
   const unitName = entry.name;
   const calendar = cronToOnCalendar(entry.schedule);
-  const execStart = toSystemdExecStart(entry.command);
+  const resolvedBin = binPath ?? resolveSelftuneBin();
+  const resolvedCommand = entry.command.replace(/\bselftune\b/g, resolvedBin);
+  const execStart = toSystemdExecStart(resolvedCommand);
+  const home = homedir();
 
   return {
     baseName: unitName,
@@ -247,6 +292,8 @@ Description=${entry.description}
 
 [Service]
 Type=oneshot
+Environment="PATH=${home}/.bun/bin:/usr/local/bin:/usr/bin:/bin"
+Environment="HOME=${home}"
 ExecStart=${execStart}`,
   };
 }
@@ -487,10 +534,11 @@ export function cliMain(): void {
       applyCronArtifact(values["apply-cron-artifact"]);
       return;
     } catch (err) {
-      console.error(
+      throw new CLIError(
         `Failed to apply selftune cron artifact: ${err instanceof Error ? err.message : String(err)}`,
+        "OPERATION_FAILED",
+        "selftune schedule --install --dry-run",
       );
-      process.exit(1);
     }
   }
 
@@ -523,8 +571,11 @@ For OpenClaw-specific scheduling, see: selftune cron`);
         dryRun: values["dry-run"] ?? false,
       });
       if (!result.dryRun && !result.activated) {
-        console.error("Failed to activate installed schedule artifacts.");
-        process.exit(1);
+        throw new CLIError(
+          "Failed to activate installed schedule artifacts.",
+          "OPERATION_FAILED",
+          "selftune schedule --install --dry-run",
+        );
       }
       console.log(
         JSON.stringify(
@@ -541,21 +592,30 @@ For OpenClaw-specific scheduling, see: selftune cron`);
       );
       return;
     } catch (err) {
-      console.error(
+      if (err instanceof CLIError) throw err;
+      throw new CLIError(
         `Failed to install schedule artifacts: ${err instanceof Error ? err.message : String(err)}`,
+        "OPERATION_FAILED",
+        "selftune schedule --install --dry-run",
       );
-      process.exit(1);
     }
   }
 
   const result = formatOutput(values.format);
   if (!result.ok) {
-    console.error(result.error);
-    process.exit(1);
+    throw new CLIError(
+      result.error ?? "Invalid schedule format",
+      "INVALID_FLAG",
+      "selftune schedule --format cron",
+    );
   }
   console.log(result.data);
 }
 
 if (import.meta.main) {
-  cliMain();
+  try {
+    cliMain();
+  } catch (err) {
+    handleCLIError(err);
+  }
 }

package/cli/selftune/sync.ts

@@ -62,6 +62,7 @@ import {
   rebuildSkillUsageFromTranscripts,
 } from "./repair/skill-usage.js";
 import type { SkillUsageRecord } from "./types.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
 import { loadMarker, readJsonl, saveMarker } from "./utils/jsonl.js";
 import { writeRepairedSkillUsageRecords } from "./utils/skill-log.js";
 
@@ -560,8 +561,11 @@ Options:
   if (values.since) {
     since = new Date(values.since);
     if (Number.isNaN(since.getTime())) {
-      console.error(`[ERROR] Invalid --since date: ${values.since}`);
-      process.exit(1);
+      throw new CLIError(
+        `Invalid --since date: ${values.since}`,
+        "INVALID_FLAG",
+        "selftune sync --since 2026-01-01",
+      );
     }
   }
 
@@ -665,5 +669,5 @@ Options:
 }
 
 if (import.meta.main) {
-  cliMain();
+  cliMain().catch(handleCLIError);
 }

package/cli/selftune/types.ts

@@ -166,26 +166,46 @@ export interface TranscriptMetrics {
 // Hook payloads (received via stdin from Claude Code)
 // ---------------------------------------------------------------------------
 
+/**
+ * Common fields present on ALL hook event payloads per Claude Code docs.
+ * Individual payloads extend this with event-specific fields.
+ */
+export interface CommonHookPayload {
+  session_id?: string;
+  transcript_path?: string;
+  cwd?: string;
+  permission_mode?: string;
+  hook_event_name?: string;
+  /** Present when hook fires inside a subagent. */
+  agent_id?: string;
+  /** Agent name (e.g. "Explore", "Plan", or custom agent name). */
+  agent_type?: string;
+}
+
 // Shared base for pre/post tool-use hook payloads
-export interface BaseToolUsePayload {
+export interface BaseToolUsePayload extends CommonHookPayload {
   tool_name: string;
   tool_input: Record<string, unknown>;
-  session_id?: string;
+  tool_use_id?: string;
 }
 
-export interface PromptSubmitPayload {
-  user_prompt: string;
-  session_id?: string;
+export interface PromptSubmitPayload extends CommonHookPayload {
+  /** Current field name per Claude Code docs (2025+). */
+  prompt?: string;
+  /** Legacy field name — kept for backwards compatibility. */
+  user_prompt?: string;
 }
 
 export interface PostToolUsePayload extends BaseToolUsePayload {
-  transcript_path?: string;
+  /** Tool execution result, schema depends on the tool. */
+  tool_response?: Record<string, unknown>;
 }
 
-export interface StopPayload {
-  session_id?: string;
-  transcript_path?: string;
-  cwd?: string;
+export interface StopPayload extends CommonHookPayload {
+  /** True when Claude Code is continuing as a result of a stop hook. */
+  stop_hook_active?: boolean;
+  /** Text content of Claude's final response. */
+  last_assistant_message?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -394,6 +414,18 @@ export interface EvolutionConfig {
 // Validation result base (self-contained for Pareto types)
 // ---------------------------------------------------------------------------
 
+/** Heuristic quality score for a skill description (no LLM, pure function). */
+export interface DescriptionQualityScore {
+  composite: number; // 0.0-1.0 weighted aggregate
+  criteria: {
+    length: number; // description length in optimal range
+    trigger_context: number; // includes when/if/before/after context
+    vagueness: number; // absence of vague words
+    specificity: number; // concrete action verbs present
+    not_just_name: number; // not just restating the skill name
+  };
+}
+
 /** Compact summary of an evolve run, used for CLI JSON output. */
 export interface EvolveResultSummary {
   skill: string;
@@ -412,6 +444,8 @@ export interface EvolveResultSummary {
   rationale: string;
   version?: string;
   dashboard_url: string;
+  description_quality_before?: number;
+  description_quality_after?: number;
 }
 
 export interface ValidationResultBase {

package/cli/selftune/utils/cli-error.ts

@@ -0,0 +1,102 @@
+/**
+ * Typed CLI error with machine-readable code, agent-actionable suggestion, and exit code.
+ *
+ * Replaces ad-hoc `console.error() + process.exit(1)` patterns across the CLI.
+ * When `--json` mode is active, errors serialize to structured JSON on stderr.
+ * When text mode is active, errors print human-readable messages with suggestions.
+ *
+ * @example
+ * ```ts
+ * throw new CLIError(
+ *   "No selftune config found",
+ *   "CONFIG_MISSING",
+ *   "Run: selftune init",
+ *   4,  // exit code for config-missing per agent-cli-contract
+ * );
+ * ```
+ */
+
+export type CLIErrorCode =
+  | "INVALID_FLAG"
+  | "MISSING_FLAG"
+  | "CONFIG_MISSING"
+  | "FILE_NOT_FOUND"
+  | "AGENT_NOT_FOUND"
+  | "UNKNOWN_COMMAND"
+  | "GUARD_BLOCKED"
+  | "OPERATION_FAILED"
+  | "MISSING_DATA"
+  | "INTERNAL_ERROR";
+
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    /** Machine-readable error code (SCREAMING_SNAKE_CASE). */
+    public readonly code: CLIErrorCode,
+    /** Agent-actionable next command or remediation step. */
+    public readonly suggestion?: string,
+    /** Process exit code. Default 1 (general error). */
+    public readonly exitCode: number = 1,
+    /** Whether the agent should retry the same command. */
+    public readonly retryable: boolean = false,
+  ) {
+    super(message);
+    this.name = "CLIError";
+  }
+
+  /** Structured JSON representation for `--json` mode. */
+  toJSON(): {
+    error: {
+      code: CLIErrorCode;
+      message: string;
+      suggestion?: string;
+      retryable: boolean;
+    };
+  } {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.suggestion ? { suggestion: this.suggestion } : {}),
+        retryable: this.retryable,
+      },
+    };
+  }
+}
+
+/**
+ * Top-level error handler for CLI entry points.
+ *
+ * Install at the bottom of any CLI entry point:
+ * ```ts
+ * cliMain().catch(handleCLIError);
+ * ```
+ */
+/** Detect JSON output mode: explicit --json flag or non-TTY stdout (automation). */
+export function isJsonOutputMode(): boolean {
+  return process.argv.includes("--json") || process.stdout?.isTTY === false;
+}
+
+export function handleCLIError(error: unknown): never {
+  const jsonMode = isJsonOutputMode();
+
+  if (error instanceof CLIError) {
+    if (jsonMode) {
+      console.error(JSON.stringify(error.toJSON()));
+      process.exit(error.exitCode);
+    }
+    console.error(`[ERROR] ${error.message}`);
+    if (error.suggestion) {
+      console.error(`  → ${error.suggestion}`);
+    }
+    process.exit(error.exitCode);
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  if (jsonMode) {
+    console.error(JSON.stringify({ error: { code: "INTERNAL_ERROR", message, retryable: false } }));
+    process.exit(1);
+  }
+  console.error(`[FATAL] ${message}`);
+  process.exit(1);
+}

package/cli/selftune/utils/jsonl.ts

@@ -90,6 +90,8 @@ export function readJsonlFrom<T = Record<string, unknown>>(
  * Append a single record to a JSONL file. Creates parent directories if needed.
  * When logType is provided, validates the record and logs warnings on failure
  * but still writes the record (fail-open: hooks must never block).
+ *
+ * @deprecated Phase 3: JSONL writes removed. Retained for materializer/test utilities only.
  */
 export function appendJsonl(path: string, record: unknown, logType?: LogType): void {
   if (logType) {

package/cli/selftune/workflows/workflows.ts

@@ -19,6 +19,7 @@ import type {
   SkillUsageRecord,
   WorkflowDiscoveryReport,
 } from "../types.js";
+import { CLIError } from "../utils/cli-error.js";
 import { discoverWorkflows } from "./discover.js";
 import { appendWorkflow } from "./skill-md-writer.js";
 
@@ -79,13 +80,11 @@ export async function cliMain(): Promise<void> {
     ? Number.parseInt(values["min-occurrences"], 10)
     : undefined;
   if (minOccurrences !== undefined && (Number.isNaN(minOccurrences) || minOccurrences < 0)) {
-    console.error("[ERROR] --min-occurrences must be a non-negative integer.");
-    process.exit(1);
+    throw new CLIError("--min-occurrences must be a non-negative integer.", "INVALID_FLAG");
   }
   const window = values.window ? Number.parseInt(values.window, 10) : undefined;
   if (window !== undefined && (Number.isNaN(window) || window < 0)) {
-    console.error("[ERROR] --window must be a non-negative integer.");
-    process.exit(1);
+    throw new CLIError("--window must be a non-negative integer.", "INVALID_FLAG");
   }
 
   // Read telemetry and skill usage logs from SQLite
@@ -104,8 +103,11 @@ export async function cliMain(): Promise<void> {
     // Save subcommand: find workflow, append to SKILL.md
     const nameArg = positionals[1];
     if (!nameArg) {
-      console.error("[ERROR] Usage: selftune workflows save <name-or-index>");
-      process.exit(1);
+      throw new CLIError(
+        "Usage: selftune workflows save <name-or-index>",
+        "MISSING_FLAG",
+        "Provide a workflow name or index (e.g., selftune workflows save 1).",
+      );
     }
 
     // Match by numeric index (1-based) or workflow_id
@@ -118,9 +120,11 @@ export async function cliMain(): Promise<void> {
     }
 
     if (!workflow) {
-      console.error(`[ERROR] No workflow found matching "${nameArg}".`);
-      console.error("Run 'selftune workflows' to see discovered workflows and their indices.");
-      process.exit(1);
+      throw new CLIError(
+        `No workflow found matching "${nameArg}".`,
+        "INVALID_FLAG",
+        "Run 'selftune workflows' to see discovered workflows and their indices.",
+      );
     }
 
     // Determine SKILL.md path
@@ -140,18 +144,20 @@ export async function cliMain(): Promise<void> {
         skillPath = uniquePaths[0];
       } else if (uniquePaths.length > 1) {
         // Ambiguous: multiple SKILL.md paths found across contributing sessions
-        console.error(`[ERROR] Multiple SKILL.md paths found for "${firstSkill}":`);
-        for (const p of uniquePaths) {
-          console.error(`  - ${p}`);
-        }
-        console.error("Use --skill-path to specify which one to update.");
-        process.exit(1);
+        throw new CLIError(
+          `Multiple SKILL.md paths found for "${firstSkill}": ${uniquePaths.join(", ")}`,
+          "INVALID_FLAG",
+          "Use --skill-path to specify which one to update.",
+        );
       }
     }
 
     if (!skillPath || !existsSync(skillPath)) {
-      console.error(`[ERROR] Could not determine SKILL.md path. Use --skill-path to specify.`);
-      process.exit(1);
+      throw new CLIError(
+        "Could not determine SKILL.md path.",
+        "FILE_NOT_FOUND",
+        "Use --skill-path to specify the SKILL.md file to update.",
+      );
     }
 
     // Build CodifiedWorkflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Self-improving skills CLI for AI agents",
   "keywords": [
     "agent",
@@ -73,12 +73,14 @@
     "prepublishOnly": "bun run sync-version && bun run build:dashboard",
     "typecheck:dashboard": "cd apps/local-dashboard && bunx tsc --noEmit",
     "check": "bun run lint && bun run format:check && bun run lint:arch && bun run typecheck:dashboard && bun run test",
+    "prepare": "bunx lefthook install || true",
     "start": "bun run cli/selftune/index.ts --help"
   },
   "dependencies": {
     "@selftune/telemetry-contract": "file:packages/telemetry-contract"
   },
   "devDependencies": {
+    "@evilmartians/lefthook": "^1.13.6",
     "@types/bun": "^1.1.0",
     "oxfmt": "^0.41.0",
     "oxlint": "^1.56.0"

package/packages/ui/src/components/RecentActivityFeed.tsx

@@ -0,0 +1,86 @@
+import { ZapIcon, CircleDotIcon } from "lucide-react";
+
+import { timeAgo } from "../lib/format";
+import { Badge } from "../primitives/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "../primitives/card";
+
+export interface RecentActivityItem {
+  timestamp: string;
+  session_id: string;
+  skill_name: string;
+  query: string;
+  triggered: boolean;
+  is_live: boolean;
+}
+
+export function RecentActivityFeed({ items }: { items: RecentActivityItem[] }) {
+  if (items.length === 0) {
+    return (
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2 text-sm">
+            <ZapIcon className="size-4" />
+            Recent Activity
+          </CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm text-muted-foreground text-center py-8">
+            No recent skill invocations
+          </p>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2 text-sm">
+          <ZapIcon className="size-4" />
+          Recent Activity
+        </CardTitle>
+        <CardDescription>Latest skill invocations across sessions</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-2.5">
+        {items.slice(0, 20).map((item, i) => (
+          <div
+            key={`${item.session_id}-${item.skill_name}-${i}`}
+            className="flex gap-3 rounded-md p-1.5"
+          >
+            <div
+              className={`mt-1 size-2 shrink-0 rounded-full ${
+                item.triggered ? "bg-emerald-500" : "bg-muted-foreground/40"
+              }`}
+            />
+            <div className="flex-1 min-w-0 space-y-0.5">
+              <div className="flex items-center gap-2 flex-wrap">
+                <span className="text-xs font-medium truncate">{item.skill_name}</span>
+                {item.is_live && (
+                  <Badge variant="outline" className="h-4 px-1 text-[10px] gap-1">
+                    <CircleDotIcon className="size-2.5 text-emerald-500" />
+                    live
+                  </Badge>
+                )}
+                {item.triggered ? (
+                  <Badge variant="default" className="h-4 px-1 text-[10px]">
+                    triggered
+                  </Badge>
+                ) : (
+                  <Badge variant="secondary" className="h-4 px-1 text-[10px]">
+                    checked
+                  </Badge>
+                )}
+                <span className="text-[10px] text-muted-foreground font-mono ml-auto shrink-0">
+                  {timeAgo(item.timestamp)}
+                </span>
+              </div>
+              {item.query && (
+                <p className="text-xs text-muted-foreground line-clamp-1 font-mono">{item.query}</p>
+              )}
+            </div>
+          </div>
+        ))}
+      </CardContent>
+    </Card>
+  );
+}

package/packages/ui/src/components/index.ts

@@ -3,5 +3,6 @@ export { EvidenceViewer } from "./EvidenceViewer";
 export { EvolutionTimeline } from "./EvolutionTimeline";
 export { InfoTip } from "./InfoTip";
 export { OrchestrateRunsPanel } from "./OrchestrateRunsPanel";
+export { RecentActivityFeed } from "./RecentActivityFeed";
 export { SectionCards } from "./section-cards";
 export { SkillHealthGrid } from "./skill-health-grid";

package/packages/ui/src/components/section-cards.tsx

@@ -21,6 +21,7 @@ interface SectionCardsProps {
   pendingCount: number;
   evidenceCount: number;
   hasEvolution?: boolean;
+  activeSessionsCount?: number;
 }
 
 export function SectionCards({
@@ -31,6 +32,7 @@ export function SectionCards({
   pendingCount,
   evidenceCount,
   hasEvolution = true,
+  activeSessionsCount = 0,
 }: SectionCardsProps) {
   const passRateStr = avgPassRate !== null ? `${Math.round(avgPassRate * 100)}%` : "--";
   const passRateGood = avgPassRate !== null && avgPassRate >= 0.7;
@@ -118,6 +120,17 @@ export function SectionCards({
           <CardTitle className="text-2xl font-semibold tabular-nums @[250px]/card:text-3xl">
             {sessionsCount}
           </CardTitle>
+          {activeSessionsCount > 0 && (
+            <CardAction>
+              <Badge variant="outline" className="gap-1.5">
+                <span className="relative flex size-2">
+                  <span className="absolute inline-flex size-full animate-ping rounded-full bg-emerald-400 opacity-75" />
+                  <span className="relative inline-flex size-2 rounded-full bg-emerald-500" />
+                </span>
+                {activeSessionsCount} in progress
+              </Badge>
+            </CardAction>
+          )}
         </CardHeader>
       </Card>
 

package/skill/SKILL.md

@@ -12,7 +12,7 @@ description: >
   even if they don't say "selftune" explicitly.
 metadata:
   author: selftune-dev
-  version: 0.2.13
+  version: 0.2.15
   category: developer-tools
 ---
 

package/skill/Workflows/Evolve.md

@@ -278,6 +278,10 @@ After evolution completes (deploy or dry-run), the memory writer updates:
 This ensures the next evolve, watch, or rollback workflow has full context
 even after a context window reset.
 
+### Description Quality Scoring
+
+Proposals are scored on heuristic quality criteria (no LLM required). The composite score (0.0–1.0) uses five weighted criteria: trigger context (0.30), vagueness absence (0.20), specificity (0.20), length (0.15), and not-just-name (0.15). Proposals that regress in quality score are rejected. See `docs/design-docs/evolution-pipeline.md` for full criteria details.
+
 ### Stopping Criteria
 
 The evolution loop stops when any of these conditions is met (priority order):