selftune 0.2.16 → 0.2.19

package/cli/selftune/hooks/commit-track.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse hook: commit-track.ts
+ *
+ * Detects git commits in Bash tool output and records commit SHA, title,
+ * branch, and session ID for session-to-commit traceability.
+ *
+ * Fail-open: exits 0 on all errors. Never blocks the host agent.
+ */
+
+import { execSync } from "node:child_process";
+
+import type { PostToolUsePayload } from "../types.js";
+
+// -- Regex patterns (pre-compiled at module load) ----------------------------
+
+/** Matches git commands that produce commits. */
+const GIT_COMMIT_CMD_RE = /\bgit\s+(commit|merge|cherry-pick|revert)\b/;
+
+/**
+ * Matches the standard git commit output format: [branch SHA] title
+ * Supports optional parenthetical like (root-commit).
+ * Branch names can contain word chars, slashes, dots, hyphens, plus signs.
+ */
+const COMMIT_OUTPUT_RE = /\[([\w/.+-]+)(?:\s+\([^)]+\))?\s+([a-f0-9]{7,40})\]\s+(.+)/;
+
+// -- Pure extraction functions (exported for testability) ---------------------
+
+/** Check if a command string contains a git commit/merge/cherry-pick/revert. */
+export function containsGitCommitCommand(command: string): boolean {
+  return GIT_COMMIT_CMD_RE.test(command);
+}
+
+/** Extract commit SHA from git output. */
+export function parseCommitSha(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[2] : undefined;
+}
+
+/** Extract commit title from git output. */
+export function parseCommitTitle(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[3].trim() : undefined;
+}
+
+/** Extract branch name from git output. */
+export function parseBranchFromOutput(output: string): string | undefined {
+  const match = output.match(COMMIT_OUTPUT_RE);
+  return match ? match[1] : undefined;
+}
+
+/** Scrub credentials from a remote URL. Returns undefined for empty input. */
+export function scrubRemoteUrl(rawUrl: string): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    parsed.username = "";
+    parsed.password = "";
+    return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+  } catch {
+    // SSH or non-URL format — safe as-is
+    return rawUrl;
+  }
+}
+
+// -- Commit tracking record shape --------------------------------------------
+
+export interface CommitTrackRecord {
+  session_id: string;
+  commit_sha: string;
+  commit_title?: string;
+  branch?: string;
+  repo_remote?: string;
+  timestamp: string;
+}
+
+// -- Core processing logic ---------------------------------------------------
+
+/**
+ * Process a PostToolUse payload for git commit tracking.
+ * Returns the record that was written, or null if skipped.
+ * Exported for testability.
+ */
+export async function processCommitTrack(
+  payload: PostToolUsePayload,
+): Promise<CommitTrackRecord | null> {
+  // Fast-path: only care about Bash tool
+  if (payload.tool_name !== "Bash") return null;
+
+  // Fast-path: if cwd is known and not inside a git repo, skip
+  const cwd = payload.cwd ?? "";
+  if (cwd) {
+    try {
+      execSync("git rev-parse --is-inside-work-tree", {
+        cwd,
+        timeout: 1000,
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+    } catch {
+      return null; // Not inside a git repo
+    }
+  }
+
+  // Fast-path: check if the command is a git commit-producing operation
+  const command = typeof payload.tool_input?.command === "string" ? payload.tool_input.command : "";
+  if (!containsGitCommitCommand(command)) return null;
+
+  // Extract stdout from tool_response
+  const response = payload.tool_response ?? {};
+  const stdout = typeof response.stdout === "string" ? response.stdout : "";
+  if (!stdout) return null;
+
+  // Parse commit SHA — if we can't find one, nothing to track
+  const commitSha = parseCommitSha(stdout);
+  if (!commitSha) return null;
+
+  const commitTitle = parseCommitTitle(stdout);
+  const outputBranch = parseBranchFromOutput(stdout);
+  const sessionId = payload.session_id;
+  if (!sessionId) return null; // No session ID — skip insert (fail-open)
+
+  // Try to get branch from git if not parsed from output
+  let branch = outputBranch;
+  if (!branch && cwd) {
+    try {
+      branch =
+        execSync("git rev-parse --abbrev-ref HEAD", {
+          cwd,
+          timeout: 3000,
+          stdio: ["ignore", "pipe", "ignore"],
+        })
+          .toString()
+          .trim() || undefined;
+    } catch {
+      /* not a git repo or git not available */
+    }
+  }
+
+  // Try to get remote URL (scrub credentials)
+  let repoRemote: string | undefined;
+  if (cwd) {
+    try {
+      const rawRemote =
+        execSync("git remote get-url origin", {
+          cwd,
+          timeout: 3000,
+          stdio: ["ignore", "pipe", "ignore"],
+        })
+          .toString()
+          .trim() || undefined;
+      if (rawRemote) {
+        repoRemote = scrubRemoteUrl(rawRemote);
+      }
+    } catch {
+      /* no remote configured */
+    }
+  }
+
+  const record: CommitTrackRecord = {
+    session_id: sessionId,
+    commit_sha: commitSha,
+    commit_title: commitTitle,
+    branch,
+    repo_remote: repoRemote,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Write to SQLite (dynamic import to reduce hook startup cost)
+  try {
+    const { writeCommitTracking } = await import("../localdb/direct-write.js");
+    writeCommitTracking(record);
+  } catch {
+    /* hooks must never block */
+  }
+
+  return record;
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    const payload: PostToolUsePayload = JSON.parse(await Bun.stdin.text());
+    await processCommitTrack(payload);
+  } catch {
+    // silent — hooks must never block Claude
+  }
+  process.exit(0);
+}

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

@@ -226,7 +226,16 @@ export async function processPrompt(
 // --- stdin main (only when executed directly, not when imported) ---
 if (import.meta.main) {
   try {
-    const payload: PromptSubmitPayload = JSON.parse(await Bun.stdin.text());
+    const { readStdinWithPreview } = await import("./stdin-preview.js");
+    const { preview, full } = await readStdinWithPreview();
+
+    // Fast-path: prompt-log only handles UserPromptSubmit events.
+    // If the keyword is absent from the first 4 KiB we can skip JSON.parse entirely.
+    if (!preview.includes('"UserPromptSubmit"')) {
+      process.exit(0);
+    }
+
+    const payload: PromptSubmitPayload = JSON.parse(full);
     await processPrompt(payload);
   } catch {
     // silent — hooks must never block Claude

package/cli/selftune/hooks/session-stop.ts

@@ -11,7 +11,7 @@
 import { execSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 
-import { CANONICAL_LOG, ORCHESTRATE_LOCK, TELEMETRY_LOG } from "../constants.js";
+import { CANONICAL_LOG, getOrchestrateLockPath, TELEMETRY_LOG } from "../constants.js";
 import {
   appendCanonicalRecords,
   buildCanonicalExecutionFact,
@@ -47,7 +47,7 @@ function hasFreshOrchestrateLock(lockPath: string): boolean {
  * Returns true if a process was spawned, false otherwise.
  */
 export async function maybeSpawnReactiveOrchestrate(
-  lockPath: string = ORCHESTRATE_LOCK,
+  lockPath: string = getOrchestrateLockPath(),
   deps: ReactiveSpawnDeps = {},
 ): Promise<boolean> {
   try {

package/cli/selftune/hooks/skill-eval.ts

@@ -359,7 +359,21 @@ async function processSkillToolUse(
 // --- stdin main (only when executed directly, not when imported) ---
 if (import.meta.main) {
   try {
-    const payload: PostToolUsePayload = JSON.parse(await Bun.stdin.text());
+    const { readStdinWithPreview } = await import("./stdin-preview.js");
+    const { preview, full } = await readStdinWithPreview();
+
+    // Fast-path: skill-eval only handles PostToolUse events.
+    if (!preview.includes('"PostToolUse"')) {
+      process.exit(0);
+    }
+
+    // Secondary fast-path: only Read and Skill tools are relevant.
+    // Most PostToolUse events are for Bash/Write/Edit — skip those entirely.
+    if (!preview.includes('"Read"') && !preview.includes('"Skill"')) {
+      process.exit(0);
+    }
+
+    const payload: PostToolUsePayload = JSON.parse(full);
     await processToolUse(payload);
   } catch {
     // silent — hooks must never block Claude

package/cli/selftune/hooks/stdin-preview.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared stdin preview utility for hook fast-path optimization.
+ *
+ * Reads all of stdin once, then exposes a small preview slice so callers
+ * can do cheap `.includes()` keyword checks before paying for JSON.parse().
+ * When the keyword is absent the hook can exit in <1ms.
+ */
+
+const STDIN_PREVIEW_BYTES = 4096;
+
+/**
+ * Read stdin and return both a preview slice and the full text.
+ *
+ * Bun's `stdin.text()` consumes the entire stream in one call, so this is
+ * not a true streaming preview. The win comes from avoiding `JSON.parse()`
+ * entirely when the preview slice already proves the payload is irrelevant.
+ *
+ * @param previewBytes  Number of leading characters to expose in `preview`.
+ *                      Defaults to 4096, which comfortably covers the
+ *                      envelope fields (`hook_event_name`, `tool_name`, etc.)
+ *                      of any Claude Code hook payload.
+ */
+export async function readStdinWithPreview(previewBytes: number = STDIN_PREVIEW_BYTES): Promise<{
+  preview: string;
+  full: string;
+}> {
+  const raw = await Bun.stdin.text();
+  return {
+    preview: raw.slice(0, previewBytes),
+    full: raw,
+  };
+}

package/cli/selftune/index.ts

@@ -6,7 +6,7 @@
  *   selftune ingest <agent>     — Ingest agent sessions (claude, codex, opencode, openclaw, wrap-codex)
  *   selftune grade [mode]       — Grade skill sessions (auto, baseline)
  *   selftune evolve [target]    — Evolve skill descriptions (body, rollback)
- *   selftune eval <action>      — Evaluation tools (generate, unit-test, import, composability)
+ *   selftune eval <action>      — Evaluation tools (generate, unit-test, import, composability, family-overlap)
  *   selftune sync               — Sync source-truth telemetry across supported agents
  *   selftune orchestrate        — Run autonomous core loop (sync → status → evolve → watch)
  *   selftune init               — Initialize agent identity and config
@@ -19,11 +19,14 @@
  *   selftune cron               — Scheduling & automation (setup, list, remove)
  *   selftune badge              — Generate skill health badges for READMEs
  *   selftune contribute         — Export anonymized skill data for community
+ *   selftune contributions      — Manage creator-directed sharing preferences
+ *   selftune creator-contributions — Manage creator-side contribution configs
  *   selftune workflows          — Discover and manage multi-skill workflows
  *   selftune quickstart         — Guided onboarding: init, ingest, status, and suggestions
  *   selftune repair-skill-usage — Rebuild trustworthy skill usage from transcripts
- *   selftune export             — Export SQLite data to JSONL files
+ *   selftune export             — Export SQLite data to JSONL snapshots
  *   selftune export-canonical   — Export canonical telemetry for downstream ingestion
+ *   selftune recover            — Recover SQLite from legacy/exported JSONL
  *   selftune telemetry          — Manage anonymous usage analytics (status, enable, disable)
  *   selftune alpha <subcommand> — Alpha program management (upload)
  *   selftune hook <name>        — Run a hook by name (prompt-log, session-stop, etc.)
@@ -46,7 +49,7 @@ Commands:
   ingest <agent>     Ingest agent sessions (claude, codex, opencode, openclaw, wrap-codex)
   grade [mode]       Grade skill sessions (auto, baseline)
   evolve [target]    Evolve skill descriptions (body, rollback)
-  eval <action>      Evaluation tools (generate, unit-test, import, composability)
+  eval <action>      Evaluation tools (generate, unit-test, import, composability, family-overlap)
   sync               Sync source-truth telemetry across supported agents
   orchestrate        Run autonomous core loop (sync → status → evolve → watch)
   init               Initialize agent identity and config
@@ -59,11 +62,14 @@ Commands:
   cron               Scheduling & automation (setup, list, remove)
   badge              Generate skill health badges for READMEs
   contribute         Export anonymized skill data for community
+  contributions      Manage creator-directed sharing preferences
+  creator-contributions Manage creator-side contribution configs
   workflows          Discover and manage multi-skill workflows
   quickstart         Guided onboarding: init, ingest, status, and suggestions
   repair-skill-usage Rebuild trustworthy skill usage from transcripts
-  export             Export SQLite data to JSONL files
+  export             Export SQLite data to JSONL snapshots
   export-canonical   Export canonical telemetry for downstream ingestion
+  recover            Recover SQLite from legacy/exported JSONL
   alpha <subcommand> Alpha program management (upload)
   telemetry          Manage anonymous usage analytics (status, enable, disable)
   hook <name>        Run a hook by name (prompt-log, session-stop, etc.)
@@ -254,6 +260,7 @@ Actions:
   unit-test      Run or generate skill unit tests
   import         Import SkillsBench task corpus as eval entries
   composability  Analyze skill co-occurrence conflicts
+  family-overlap Detect sibling-skill overlap and consolidation pressure
 
 Run 'selftune eval <action> --help' for action-specific options.`);
       process.exit(0);
@@ -341,6 +348,17 @@ Run 'selftune eval <action> --help' for action-specific options.`);
         console.log(JSON.stringify(report, null, 2));
         break;
       }
+      case "family-overlap": {
+        if (process.argv[2] === "--help" || process.argv[2] === "-h") {
+          console.log(
+            "selftune eval family-overlap --prefix <family-> | --skills <a,b,c> [--parent-skill <name>] [--min-overlap 0.3] [--min-shared 2]",
+          );
+          process.exit(0);
+        }
+        const { cliMain } = await import("./eval/family-overlap.js");
+        await cliMain();
+        break;
+      }
       default:
         throw new CLIError(
           `Unknown eval action: ${sub}`,
@@ -368,6 +386,16 @@ Run 'selftune eval <action> --help' for action-specific options.`);
     await cliMain();
     break;
   }
+  case "contributions": {
+    const { cliMain } = await import("./contributions.js");
+    await cliMain();
+    break;
+  }
+  case "creator-contributions": {
+    const { cliMain } = await import("./creator-contributions.js");
+    await cliMain();
+    break;
+  }
   case "watch": {
     const { cliMain } = await import("./monitoring/watch.js");
     await cliMain();
@@ -527,11 +555,14 @@ Run 'selftune cron <subcommand> --help' for subcommand-specific options.`);
       throw new CLIError(`Invalid arguments: ${message}`, "INVALID_FLAG", "selftune export --help");
     }
     if (values.help) {
-      console.log(`selftune export — Export SQLite data to JSONL files
+      console.log(`selftune export — Export SQLite data to JSONL snapshots
 
 Usage:
   selftune export [tables...] [options]
 
+Use this for portability, debugging, contribute flows, or explicit recovery
+snapshots. Normal runtime reads and writes stay in SQLite.
+
 Tables (default: all):
   telemetry    Session telemetry records
   skills       Skill usage records
@@ -570,6 +601,11 @@ Options:
     cliMain();
     break;
   }
+  case "recover": {
+    const { cliMain } = await import("./recover.js");
+    cliMain();
+    break;
+  }
   case "orchestrate": {
     const { cliMain } = await import("./orchestrate.js");
     await cliMain();

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

@@ -52,9 +52,9 @@ import type {
 import { handleCLIError } from "../utils/cli-error.js";
 import { loadMarker, saveMarker } from "../utils/jsonl.js";
 import { extractActionableQueryText } from "../utils/query-filter.js";
+import { getInternalPromptTargetSkill, isWrappedNonUserPart } from "../utils/skill-detection.js";
 import {
   classifySkillPath,
-  containsWholeSkillMention,
   extractExplicitSkillMentions,
   extractSkillNamesFromInstructions,
   extractSkillNamesFromPathReferences,
@@ -228,6 +228,15 @@ export function parseRolloutFile(path: string, skillNames: Set<string>): ParsedR
   let observedCwd: string | undefined;
   const sessionSkillNames = new Set(skillNames);
   let hasActionablePrompt = false;
+  const markSkillTriggered = (skillName: string, evidence: "explicit" | "inferred"): void => {
+    if (!skillsTriggered.includes(skillName)) {
+      skillsTriggered.push(skillName);
+    }
+    const existingEvidence = skillEvidence.get(skillName);
+    if (existingEvidence !== "explicit") {
+      skillEvidence.set(skillName, evidence);
+    }
+  };
   const rememberSessionSkillNames = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
     for (const skillName of extractSkillNamesFromInstructions(text, sessionSkillNames)) {
@@ -240,33 +249,23 @@ export function parseRolloutFile(path: string, skillNames: Set<string>): ParsedR
       sessionSkillNames.add(skillName);
     }
   };
-  const detectTriggeredSkills = (text: unknown): void => {
-    if (typeof text !== "string" || !text) return;
-    for (const skillName of sessionSkillNames) {
-      if (containsWholeSkillMention(text, skillName) && !skillsTriggered.includes(skillName)) {
-        skillsTriggered.push(skillName);
-      }
-      if (containsWholeSkillMention(text, skillName) && !skillEvidence.has(skillName)) {
-        skillEvidence.set(skillName, "inferred");
-      }
-    }
-  };
   const detectExplicitPromptSkillMentions = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
-    for (const skillName of extractExplicitSkillMentions(text, sessionSkillNames)) {
-      if (!skillsTriggered.includes(skillName)) {
-        skillsTriggered.push(skillName);
-      }
-      skillEvidence.set(skillName, "explicit");
+    if (isWrappedNonUserPart(text)) return;
+    const actionableText = extractActionableQueryText(text) ?? text;
+    const internalTargetSkill = getInternalPromptTargetSkill(actionableText, sessionSkillNames);
+    if (internalTargetSkill) {
+      markSkillTriggered(internalTargetSkill, "explicit");
+      return;
+    }
+    for (const skillName of extractExplicitSkillMentions(actionableText, sessionSkillNames)) {
+      markSkillTriggered(skillName, "explicit");
     }
   };
   const detectExplicitSkillReads = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
     for (const skillName of extractSkillNamesFromPathReferences(text, sessionSkillNames)) {
-      if (!skillsTriggered.includes(skillName)) {
-        skillsTriggered.push(skillName);
-      }
-      skillEvidence.set(skillName, "explicit");
+      markSkillTriggered(skillName, "explicit");
     }
   };
   const rememberPromptCandidate = (value: unknown): void => {
@@ -352,27 +351,26 @@ export function parseRolloutFile(path: string, skillNames: Set<string>): ParsedR
       if (itemType === "function_call") {
         const fnName = (payload.name as string) ?? "function_call";
         toolCalls[fnName] = (toolCalls[fnName] ?? 0) + 1;
-        // Check for skill mentions in function arguments
+        // Only path-based skill references count as triggers here.
         detectExplicitSkillReads(payload.arguments);
-        detectTriggeredSkills(payload.arguments);
       } else if (itemType === "agent_reasoning") {
         toolCalls.reasoning = (toolCalls.reasoning ?? 0) + 1;
-        detectTriggeredSkills(payload.text);
       } else if (itemType === "message") {
-        const content = Array.isArray(payload.content)
+        const parts = Array.isArray(payload.content)
           ? payload.content
               .map((part) =>
                 typeof part === "object" && part
                   ? (((part as Record<string, unknown>).text as string | undefined) ?? "")
                   : "",
               )
-              .join("\n")
-          : "";
+              .filter(Boolean)
+          : [];
+        const content = parts.join("\n");
         rememberSessionSkillNames(content);
-        if ((payload.role as string) === "assistant") {
-          detectTriggeredSkills(content);
-        } else if ((payload.role as string) === "user") {
-          detectExplicitPromptSkillMentions(content);
+        if ((payload.role as string) === "user") {
+          for (const part of parts) {
+            detectExplicitPromptSkillMentions(part);
+          }
         }
       }
     } else if (etype === "turn.started") {
@@ -410,10 +408,8 @@ export function parseRolloutFile(path: string, skillNames: Set<string>): ParsedR
       }
 
       // Detect skill names in text content on completed events
-      const textContent = ((item.text as string) ?? "") + ((item.command as string) ?? "");
-      detectExplicitSkillReads(textContent);
-      if (etype === "item.completed") {
-        detectTriggeredSkills(textContent);
+      if (itemType === "command_execution") {
+        detectExplicitSkillReads(item.command);
       }
     } else if (etype === "error") {
       errors += 1;

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

@@ -41,11 +41,13 @@ import type {
   SessionTelemetryRecord,
   SkillUsageRecord,
 } from "../types.js";
+import { extractActionableQueryText } from "../utils/query-filter.js";
+import { getInternalPromptTargetSkill, isWrappedNonUserPart } from "../utils/skill-detection.js";
 import {
   classifySkillPath,
-  containsWholeSkillMention,
   extractExplicitSkillMentions,
   extractSkillNamesFromInstructions,
+  extractSkillNamesFromPathReferences,
   findInstalledSkillNames,
   findInstalledSkillPath,
   findRepositorySkillDirs,
@@ -112,26 +114,34 @@ export function parseJsonlStream(lines: string[], skillNames: Set<string>): Pars
   let outputTokens = 0;
   const agentMessages: string[] = [];
   const sessionSkillNames = new Set(skillNames);
+  const markSkillTriggered = (skillName: string): void => {
+    if (!skillsTriggered.includes(skillName)) {
+      skillsTriggered.push(skillName);
+    }
+  };
   const rememberSessionSkillNames = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
     for (const skillName of extractSkillNamesFromInstructions(text, sessionSkillNames)) {
       sessionSkillNames.add(skillName);
     }
   };
-  const detectTriggeredSkills = (text: unknown): void => {
+  const detectExplicitSkillReads = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
-    for (const skillName of sessionSkillNames) {
-      if (containsWholeSkillMention(text, skillName) && !skillsTriggered.includes(skillName)) {
-        skillsTriggered.push(skillName);
-      }
+    for (const skillName of extractSkillNamesFromPathReferences(text, sessionSkillNames)) {
+      markSkillTriggered(skillName);
     }
   };
   const detectExplicitPromptSkillMentions = (text: unknown): void => {
     if (typeof text !== "string" || !text) return;
-    for (const skillName of extractExplicitSkillMentions(text, sessionSkillNames)) {
-      if (!skillsTriggered.includes(skillName)) {
-        skillsTriggered.push(skillName);
-      }
+    if (isWrappedNonUserPart(text)) return;
+    const actionableText = extractActionableQueryText(text) ?? text;
+    const internalTargetSkill = getInternalPromptTargetSkill(actionableText, sessionSkillNames);
+    if (internalTargetSkill) {
+      markSkillTriggered(internalTargetSkill);
+      return;
+    }
+    for (const skillName of extractExplicitSkillMentions(actionableText, sessionSkillNames)) {
+      markSkillTriggered(skillName);
     }
   };
 
@@ -187,40 +197,38 @@ export function parseJsonlStream(lines: string[], skillNames: Set<string>): Pars
         } else if (itemType === "agent_message") {
           const text = (item.text as string) ?? "";
           if (text) agentMessages.push(text.slice(0, 500));
-          detectTriggeredSkills(text);
         } else if (itemType === "reasoning") {
           toolCalls.reasoning = (toolCalls.reasoning ?? 0) + 1;
         }
       }
 
-      // Detect skill names in text on completed events (whole-word match)
-      const textContent = ((item.text as string) ?? "") + ((item.command as string) ?? "");
-      if (etype === "item.completed") {
-        detectTriggeredSkills(textContent);
+      if (etype === "item.completed" && itemType === "command_execution") {
+        detectExplicitSkillReads(item.command);
       }
     } else if (etype === "response_item") {
       const payload = (event.payload as Record<string, unknown>) ?? {};
       const itemType = (payload.type as string) ?? "";
       if (itemType === "function_call") {
-        detectTriggeredSkills(payload.arguments);
+        detectExplicitSkillReads(payload.arguments);
       } else if (itemType === "message") {
-        const content = Array.isArray(payload.content)
+        const parts = Array.isArray(payload.content)
           ? payload.content
               .map((part) =>
                 typeof part === "object" && part
                   ? (((part as Record<string, unknown>).text as string | undefined) ?? "")
                   : "",
               )
-              .join("\n")
-          : "";
+              .filter(Boolean)
+          : [];
+        const content = parts.join("\n");
         rememberSessionSkillNames(content);
-        if ((payload.role as string) === "assistant") {
-          detectTriggeredSkills(content);
-        } else if ((payload.role as string) === "user") {
-          detectExplicitPromptSkillMentions(content);
+        if ((payload.role as string) === "user") {
+          for (const part of parts) {
+            detectExplicitPromptSkillMentions(part);
+          }
         }
       } else if (itemType === "agent_reasoning") {
-        detectTriggeredSkills(payload.text);
+        detectExplicitSkillReads(payload.text);
       }
     } else if (etype === "error") {
       errors += 1;

package/cli/selftune/localdb/db.ts

@@ -54,7 +54,7 @@ export function openDb(dbPath: string = DB_PATH): Database {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes("duplicate column")) continue; // expected on subsequent runs
         throw new Error(
-          `Schema migration failed: ${msg}. Export first with 'selftune export', then remove '${dbPath}' and rerun 'selftune sync --force' or 'selftune dashboard'.`,
+          `Schema migration failed: ${msg}. Export first with 'selftune export', then remove '${dbPath}' and rerun 'selftune sync --force'. If you need legacy/export JSONL backfill, run 'selftune recover --full --force'.`,
         );
       }
     }
@@ -67,7 +67,7 @@ export function openDb(dbPath: string = DB_PATH): Database {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes("already exists")) continue; // expected on subsequent runs
         throw new Error(
-          `Schema index creation failed: ${msg}. Export first with 'selftune export', then remove '${dbPath}' and rerun 'selftune sync --force' or 'selftune dashboard'.`,
+          `Schema index creation failed: ${msg}. Export first with 'selftune export', then remove '${dbPath}' and rerun 'selftune sync --force'. If you need legacy/export JSONL backfill, run 'selftune recover --full --force'.`,
         );
       }
     }