selftune 0.2.18 → 0.2.20

package/cli/selftune/localdb/schema.ts

@@ -121,7 +121,12 @@ CREATE TABLE IF NOT EXISTS evolution_audit (
   skill_name      TEXT,
   action          TEXT NOT NULL,
   details         TEXT,
-  eval_snapshot_json TEXT
+  eval_snapshot_json TEXT,
+  iterations_used  INTEGER,
+  validation_mode  TEXT,
+  validation_agent TEXT,
+  validation_fixture_id TEXT,
+  validation_evidence_ref TEXT
 )`;
 
 // -- Local telemetry tables (from JSONL logs) ---------------------------------
@@ -239,6 +244,21 @@ CREATE TABLE IF NOT EXISTS upload_queue (
   last_error    TEXT
 )`;
 
+// -- Creator contribution staging --------------------------------------------
+
+export const CREATE_CREATOR_CONTRIBUTION_STAGING = `
+CREATE TABLE IF NOT EXISTS creator_contribution_staging (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  dedupe_key   TEXT NOT NULL,
+  skill_name   TEXT NOT NULL,
+  creator_id   TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'pending',
+  staged_at    TEXT NOT NULL,
+  updated_at   TEXT NOT NULL,
+  last_error   TEXT
+)`;
+
 // -- Canonical upload staging -------------------------------------------------
 
 export const CREATE_CANONICAL_UPLOAD_STAGING = `
@@ -327,6 +347,10 @@ export const CREATE_INDEXES = [
   // -- Alpha upload queue indexes ---------------------------------------------
   `CREATE INDEX IF NOT EXISTS idx_upload_queue_status ON upload_queue(status)`,
   `CREATE INDEX IF NOT EXISTS idx_upload_queue_type_status ON upload_queue(payload_type, status)`,
+  // -- Creator contribution staging indexes -----------------------------------
+  `CREATE INDEX IF NOT EXISTS idx_creator_contrib_status ON creator_contribution_staging(status)`,
+  `CREATE INDEX IF NOT EXISTS idx_creator_contrib_skill ON creator_contribution_staging(skill_name)`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS idx_creator_contrib_dedup ON creator_contribution_staging(dedupe_key)`,
   // -- Canonical upload staging indexes ---------------------------------------
   `CREATE INDEX IF NOT EXISTS idx_staging_kind ON canonical_upload_staging(record_kind)`,
   `CREATE INDEX IF NOT EXISTS idx_staging_session ON canonical_upload_staging(session_id)`,
@@ -350,6 +374,10 @@ export const MIGRATIONS = [
   `ALTER TABLE skill_invocations ADD COLUMN source TEXT`,
   // Track how many iteration loops each evolution run used
   `ALTER TABLE evolution_audit ADD COLUMN iterations_used INTEGER`,
+  `ALTER TABLE evolution_audit ADD COLUMN validation_mode TEXT`,
+  `ALTER TABLE evolution_audit ADD COLUMN validation_agent TEXT`,
+  `ALTER TABLE evolution_audit ADD COLUMN validation_fixture_id TEXT`,
+  `ALTER TABLE evolution_audit ADD COLUMN validation_evidence_ref TEXT`,
   // Canonical contract fields for upload staging (sessions already has schema_version, platform, normalized_at)
   `ALTER TABLE sessions ADD COLUMN normalizer_version TEXT`,
   `ALTER TABLE sessions ADD COLUMN capture_mode TEXT`,
@@ -422,6 +450,7 @@ export const ALL_DDL = [
   CREATE_GRADING_RESULTS,
   CREATE_IMPROVEMENT_SIGNALS,
   CREATE_UPLOAD_QUEUE,
+  CREATE_CREATOR_CONTRIBUTION_STAGING,
   CREATE_UPLOAD_WATERMARKS,
   CREATE_CANONICAL_UPLOAD_STAGING,
   CREATE_COMMIT_TRACKING,

package/cli/selftune/recover.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from "node:util";
+
+import {
+  CANONICAL_LOG,
+  EVOLUTION_AUDIT_LOG,
+  EVOLUTION_EVIDENCE_LOG,
+  ORCHESTRATE_RUN_LOG,
+  TELEMETRY_LOG,
+} from "./constants.js";
+import { getDb } from "./localdb/db.js";
+import {
+  materializeFull,
+  materializeIncremental,
+  type MaterializeOptions,
+  type MaterializeResult,
+} from "./localdb/materialize.js";
+import { CLIError, handleCLIError } from "./utils/cli-error.js";
+
+interface RecoverSummary {
+  mode: "incremental" | "full";
+  source: "legacy_jsonl_or_export_snapshot";
+  since: string | null;
+  force: boolean;
+  result: MaterializeResult;
+}
+
+function buildMaterializeOptions(values: Record<string, unknown>): MaterializeOptions {
+  return {
+    canonicalLogPath: (values["canonical-log"] as string | undefined) ?? CANONICAL_LOG,
+    telemetryLogPath: (values["telemetry-log"] as string | undefined) ?? TELEMETRY_LOG,
+    evolutionAuditPath:
+      (values["evolution-audit-log"] as string | undefined) ?? EVOLUTION_AUDIT_LOG,
+    evolutionEvidencePath:
+      (values["evolution-evidence-log"] as string | undefined) ?? EVOLUTION_EVIDENCE_LOG,
+    orchestrateRunLogPath:
+      (values["orchestrate-run-log"] as string | undefined) ?? ORCHESTRATE_RUN_LOG,
+    force: (values.force as boolean | undefined) ?? false,
+  };
+}
+
+function printHumanSummary(summary: RecoverSummary): void {
+  const rows = [
+    `mode: ${summary.mode}`,
+    "source: legacy JSONL or explicit export snapshot",
+    `sessions: ${summary.result.sessions}`,
+    `prompts: ${summary.result.prompts}`,
+    `skill invocations: ${summary.result.skillInvocations}`,
+    `execution facts: ${summary.result.executionFacts}`,
+    `session telemetry: ${summary.result.sessionTelemetry}`,
+    `legacy skill usage: ${summary.result.skillUsage}`,
+    `evolution audit: ${summary.result.evolutionAudit}`,
+    `evolution evidence: ${summary.result.evolutionEvidence}`,
+    `orchestrate runs: ${summary.result.orchestrateRuns}`,
+  ];
+  console.log(`selftune recover\n${rows.map((row) => `  ${row}`).join("\n")}`);
+}
+
+export function cliMain(): void {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      full: { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      since: { type: "string" },
+      json: { type: "boolean", default: false },
+      "canonical-log": { type: "string", default: CANONICAL_LOG },
+      "telemetry-log": { type: "string", default: TELEMETRY_LOG },
+      "evolution-audit-log": { type: "string", default: EVOLUTION_AUDIT_LOG },
+      "evolution-evidence-log": { type: "string", default: EVOLUTION_EVIDENCE_LOG },
+      "orchestrate-run-log": { type: "string", default: ORCHESTRATE_RUN_LOG },
+      help: { type: "boolean", short: "h", default: false },
+    },
+    strict: true,
+  });
+
+  if (values.help) {
+    console.log(`selftune recover — Recover SQLite from legacy/exported JSONL
+
+Usage:
+  selftune recover [options]
+
+Use this only for legacy backfill or explicit export-based recovery. Normal
+operation should use \`selftune sync\`, which replays native source data into
+SQLite and preserves alpha-upload compatibility.
+
+Options:
+  --full                           Rebuild SQLite tables from scratch
+  --force                          Skip preflight rebuild guard for SQLite-only rows
+  --since <date>                   Incrementally materialize records on/after date
+  --canonical-log <path>           Canonical JSONL path
+  --telemetry-log <path>           Session telemetry JSONL path
+  --evolution-audit-log <path>     Evolution audit JSONL path
+  --evolution-evidence-log <path>  Evolution evidence JSONL path
+  --orchestrate-run-log <path>     Orchestrate runs JSONL path
+  --json                           Output JSON summary
+  -h, --help                       Show this help`);
+    process.exit(0);
+  }
+
+  if (values.full && values.since) {
+    throw new CLIError(
+      "Cannot combine --full with --since.",
+      "INVALID_FLAG",
+      "Use either `selftune recover --full` or `selftune recover --since 2026-01-01`.",
+    );
+  }
+
+  let sinceIso: string | null = null;
+  if (values.since) {
+    const parsed = new Date(values.since as string);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new CLIError(
+        `Invalid --since date: ${values.since}`,
+        "INVALID_FLAG",
+        "selftune recover --since 2026-01-01",
+      );
+    }
+    sinceIso = parsed.toISOString();
+  }
+
+  const db = getDb();
+  const materializeOptions = buildMaterializeOptions(values);
+  if (!values.full) materializeOptions.since = sinceIso;
+
+  const result = values.full
+    ? materializeFull(db, materializeOptions)
+    : materializeIncremental(db, materializeOptions);
+
+  const summary: RecoverSummary = {
+    mode: values.full ? "full" : "incremental",
+    source: "legacy_jsonl_or_export_snapshot",
+    since: sinceIso,
+    force: (values.force as boolean | undefined) ?? false,
+    result,
+  };
+
+  if (values.json || !process.stdout.isTTY) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  printHumanSummary(summary);
+}
+
+if (import.meta.main) {
+  try {
+    cliMain();
+  } catch (error) {
+    handleCLIError(error);
+  }
+}

package/cli/selftune/repair/skill-usage.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 
+import type { Database } from "bun:sqlite";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { parseArgs } from "node:util";
@@ -19,7 +20,9 @@ import {
   parseRolloutFile,
 } from "../ingestors/codex-rollout.js";
 import { getDb } from "../localdb/db.js";
+import { writeSkillCheckToDb } from "../localdb/direct-write.js";
 import { queryQueryLog, querySkillUsageRecords } from "../localdb/queries.js";
+import { buildCanonicalSkillInvocation, deriveInvocationMode } from "../normalization.js";
 import type { QueryLogRecord, SkillUsageRecord } from "../types.js";
 import { readJsonl } from "../utils/jsonl.js";
 import { isActionableQueryText } from "../utils/query-filter.js";
@@ -60,6 +63,47 @@ interface ResolvedSkillPath {
   resolutionSource: NonNullable<SkillUsageRecord["skill_path_resolution_source"]>;
 }
 
+export interface RepairSQLiteResult {
+  deleted_legacy_rows: number;
+  deleted_prior_repair_rows: number;
+  inserted_repair_rows: number;
+  skipped_pairs_with_canonical: number;
+  repaired_pairs_inserted: number;
+}
+
+function deleteRedundantLegacyRows(db: Database): number {
+  const deleteTriggered = db.run(`
+    DELETE FROM skill_invocations
+    WHERE skill_invocation_id LIKE '%:su:%'
+      AND triggered = 1
+      AND EXISTS (
+        SELECT 1
+        FROM skill_invocations current
+        WHERE current.session_id = skill_invocations.session_id
+          AND lower(current.skill_name) = lower(skill_invocations.skill_name)
+          AND current.skill_invocation_id NOT LIKE '%:su:%'
+          AND current.triggered = 1
+      )
+  `);
+
+  const deleteMisses = db.run(`
+    DELETE FROM skill_invocations
+    WHERE skill_invocation_id LIKE '%:su:%'
+      AND triggered = 0
+      AND EXISTS (
+        SELECT 1
+        FROM skill_invocations current
+        WHERE current.session_id = skill_invocations.session_id
+          AND lower(current.skill_name) = lower(skill_invocations.skill_name)
+          AND COALESCE(current.query, '') = COALESCE(skill_invocations.query, '')
+          AND current.skill_invocation_id NOT LIKE '%:su:%'
+          AND current.triggered = 0
+      )
+  `);
+
+  return deleteTriggered.changes + deleteMisses.changes;
+}
+
 function isEphemeralLauncherProjectRoot(projectRoot: string): boolean {
   return projectRoot.startsWith("/tmp/") || projectRoot.startsWith("/private/tmp/");
 }
@@ -238,6 +282,7 @@ function extractSessionSkillUsage(
   let lastUserMessage: ActionableUserMessage | null = null;
   let sessionCwd: string | undefined;
   const seen = new Set<string>();
+  const pendingContextualReads = new Map<string, SkillUsageRecord>();
   const pendingSkillCalls = new Map<string, { skillName: string; recordIndex?: number }>();
   const repaired: SkillUsageRecord[] = [];
 
@@ -336,9 +381,25 @@ function extractSessionSkillUsage(
       if (toolName === "Read") {
         const filePath = (input.file_path as string) ?? "";
         if (filePath.endsWith("SKILL.md")) {
-          const inferredSkillName = basename(dirname(filePath)).trim().toLowerCase();
+          const inferredSkillName = basename(dirname(filePath)).trim();
           if (inferredSkillName && !skillPathLookup.has(inferredSkillName)) {
-            skillPathLookup.set(inferredSkillName, filePath);
+            skillPathLookup.set(inferredSkillName.toLowerCase(), filePath);
+          }
+          if (lastUserMessage && inferredSkillName) {
+            const dedupeKey = invocationKey(sessionId, inferredSkillName, lastUserMessage.query);
+            if (!seen.has(dedupeKey) && !pendingContextualReads.has(dedupeKey)) {
+              pendingContextualReads.set(dedupeKey, {
+                timestamp: timestamp || lastUserMessage.timestamp || fallbackTimestamp,
+                session_id: sessionId,
+                skill_name: inferredSkillName,
+                skill_path: filePath,
+                ...classifySkillPath(filePath, homeDir, codexHome),
+                skill_path_resolution_source: "raw_log",
+                query: lastUserMessage.query,
+                triggered: false,
+                source: "claude_code_repair",
+              });
+            }
           }
         }
         continue;
@@ -350,9 +411,10 @@ function extractSessionSkillUsage(
       if (!skillName) continue;
       const toolUseId = optionalString(toolUse.id);
 
-      const dedupeKey = [sessionId, skillName, lastUserMessage.query].join("\u0000");
+      const dedupeKey = invocationKey(sessionId, skillName, lastUserMessage.query);
       if (seen.has(dedupeKey)) continue;
       seen.add(dedupeKey);
+      pendingContextualReads.delete(dedupeKey);
 
       const knownSkillPath = skillPathLookup.get(skillName.toLowerCase());
       const { skillPath, resolutionSource } = knownSkillPath
@@ -378,6 +440,10 @@ function extractSessionSkillUsage(
     }
   }
 
+  if (pendingContextualReads.size > 0) {
+    repaired.push(...pendingContextualReads.values());
+  }
+
   return { processed: true, records: repaired };
 }
 
@@ -465,6 +531,297 @@ export function rebuildSkillUsageFromTranscripts(
   return { repairedRecords, repairedSessionIds };
 }
 
+function inferRepairPlatform(source: string | undefined): "claude_code" | "codex" {
+  return source?.includes("codex") ? "codex" : "claude_code";
+}
+
+function normalizeRepairSkillName(skillName: string): string {
+  return skillName.trim().toLowerCase();
+}
+
+function pairKey(sessionId: string, skillName: string): string {
+  return `${sessionId}\u0000${normalizeRepairSkillName(skillName)}`;
+}
+
+function splitPairKey(key: string): { sessionId: string; skillName: string } {
+  const [sessionId, skillName] = key.split("\u0000");
+  return { sessionId, skillName: normalizeRepairSkillName(skillName) };
+}
+
+function compareRepairRecords(a: SkillUsageRecord, b: SkillUsageRecord): number {
+  return (
+    a.timestamp.localeCompare(b.timestamp) ||
+    a.query.localeCompare(b.query) ||
+    a.skill_path.localeCompare(b.skill_path) ||
+    Number(a.triggered) - Number(b.triggered)
+  );
+}
+
+function invocationKey(sessionId: string, skillName: string, query: string): string {
+  return `${sessionId}\u0000${skillName.trim().toLowerCase()}\u0000${query}`;
+}
+
+function stableKeyHash(value: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+/**
+ * Persist repaired skill usage into the canonical skill_invocations table.
+ *
+ * Strategy:
+ * - delete legacy triggered :su: rows for repaired session/skill pairs
+ * - delete prior capture_mode=repair rows for those pairs (idempotent reruns)
+ * - insert repaired rows only when the pair has no canonical triggered rows
+ *
+ * This lets repair improve SQLite without overriding source-truth canonical
+ * replay/hook rows, while also removing duplicate legacy trigger rows from
+ * mixed historical sessions.
+ */
+export function persistRepairedSkillUsageToDb(
+  db: Database,
+  records: SkillUsageRecord[],
+): RepairSQLiteResult {
+  const triggeredRecords = records.filter((record) => record.triggered);
+  const missedRecords = records.filter((record) => !record.triggered);
+  const recordsByPair = new Map<string, SkillUsageRecord[]>();
+  const missedRecordsByKey = new Map<string, SkillUsageRecord>();
+
+  for (const record of triggeredRecords) {
+    const key = pairKey(record.session_id, record.skill_name);
+    const bucket = recordsByPair.get(key);
+    if (bucket) {
+      bucket.push(record);
+    } else {
+      recordsByPair.set(key, [record]);
+    }
+  }
+  for (const record of missedRecords) {
+    const key = invocationKey(record.session_id, record.skill_name, record.query);
+    const existing = missedRecordsByKey.get(key);
+    if (!existing || compareRepairRecords(record, existing) < 0) {
+      missedRecordsByKey.set(key, record);
+    }
+  }
+
+  if (recordsByPair.size === 0 && missedRecordsByKey.size === 0) {
+    return {
+      deleted_legacy_rows: 0,
+      deleted_prior_repair_rows: 0,
+      inserted_repair_rows: 0,
+      skipped_pairs_with_canonical: 0,
+      repaired_pairs_inserted: 0,
+    };
+  }
+
+  const selectExisting = db.prepare(`
+    SELECT
+      COALESCE(SUM(CASE WHEN skill_invocation_id LIKE '%:su:%' AND triggered = 1 THEN 1 ELSE 0 END), 0) AS legacy_rows,
+      COALESCE(SUM(CASE WHEN capture_mode = 'repair' AND triggered = 1 THEN 1 ELSE 0 END), 0) AS repair_rows,
+      COALESCE(
+        SUM(
+          CASE
+            WHEN skill_invocation_id NOT LIKE '%:su:%'
+             AND COALESCE(capture_mode, '') != 'repair'
+             AND triggered = 1
+            THEN 1 ELSE 0
+          END
+        ),
+        0
+      ) AS canonical_rows
+    FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ?
+  `);
+  const deleteLegacyTriggered = db.prepare(`
+    DELETE FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ? AND skill_invocation_id LIKE '%:su:%' AND triggered = 1
+  `);
+  const deleteRepairTriggered = db.prepare(`
+    DELETE FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ? AND capture_mode = 'repair' AND triggered = 1
+  `);
+  const selectExistingMiss = db.prepare(`
+    SELECT
+      COALESCE(SUM(CASE WHEN skill_invocation_id LIKE '%:su:%' AND triggered = 0 THEN 1 ELSE 0 END), 0) AS legacy_rows,
+      COALESCE(SUM(CASE WHEN capture_mode = 'repair' AND triggered = 0 THEN 1 ELSE 0 END), 0) AS repair_rows,
+      COALESCE(
+        SUM(
+          CASE
+            WHEN skill_invocation_id NOT LIKE '%:su:%'
+             AND COALESCE(capture_mode, '') != 'repair'
+             AND triggered = 0
+            THEN 1 ELSE 0
+          END
+        ),
+        0
+      ) AS canonical_rows
+    FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ? AND query = ?
+  `);
+  const deleteLegacyMiss = db.prepare(`
+    DELETE FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ? AND query = ? AND skill_invocation_id LIKE '%:su:%' AND triggered = 0
+  `);
+  const deleteRepairMiss = db.prepare(`
+    DELETE FROM skill_invocations
+    WHERE session_id = ? AND LOWER(skill_name) = ? AND query = ? AND capture_mode = 'repair' AND triggered = 0
+  `);
+
+  const result: RepairSQLiteResult = {
+    deleted_legacy_rows: 0,
+    deleted_prior_repair_rows: 0,
+    inserted_repair_rows: 0,
+    skipped_pairs_with_canonical: 0,
+    repaired_pairs_inserted: 0,
+  };
+
+  db.run("BEGIN IMMEDIATE");
+  try {
+    const redundantLegacyRows = deleteRedundantLegacyRows(db);
+    result.deleted_legacy_rows += redundantLegacyRows;
+
+    for (const [key, pairRecords] of recordsByPair.entries()) {
+      const { sessionId, skillName } = splitPairKey(key);
+      const existing = selectExisting.get(sessionId, skillName) as
+        | { legacy_rows: number; repair_rows: number; canonical_rows: number }
+        | undefined;
+
+      const legacyRows = existing?.legacy_rows ?? 0;
+      const repairRows = existing?.repair_rows ?? 0;
+      const canonicalRows = existing?.canonical_rows ?? 0;
+
+      if (repairRows > 0) {
+        deleteRepairTriggered.run(sessionId, skillName);
+        result.deleted_prior_repair_rows += repairRows;
+      }
+      if (legacyRows > 0) {
+        deleteLegacyTriggered.run(sessionId, skillName);
+        result.deleted_legacy_rows += legacyRows;
+      }
+      if (canonicalRows > 0) {
+        result.skipped_pairs_with_canonical += 1;
+        continue;
+      }
+
+      const sortedRecords = [...pairRecords].sort(compareRepairRecords);
+      const canonicalSkillName = sortedRecords[0]?.skill_name.trim() || skillName;
+      const { invocation_mode, confidence } = deriveInvocationMode({ is_repaired: true });
+
+      for (let index = 0; index < sortedRecords.length; index++) {
+        const record = sortedRecords[index];
+        const platform = inferRepairPlatform(record.source);
+        const canonical = buildCanonicalSkillInvocation({
+          platform,
+          capture_mode: "repair",
+          source_session_kind: "repaired",
+          session_id: record.session_id,
+          raw_source_ref: {
+            event_type: "repair-skill-usage",
+            metadata: {
+              source: record.source ?? null,
+              skill_path_resolution_source: record.skill_path_resolution_source ?? null,
+              skill_project_root: record.skill_project_root ?? null,
+              skill_registry_dir: record.skill_registry_dir ?? null,
+            },
+          },
+          skill_invocation_id: `${record.session_id}:r:${canonicalSkillName}:${index}`,
+          occurred_at: record.timestamp,
+          skill_name: canonicalSkillName,
+          skill_path: record.skill_path,
+          invocation_mode,
+          triggered: true,
+          confidence,
+        });
+
+        writeSkillCheckToDb({
+          ...canonical,
+          query: record.query,
+          skill_path: record.skill_path,
+          skill_scope: record.skill_scope,
+          source: record.source,
+        });
+        result.inserted_repair_rows += 1;
+      }
+
+      result.repaired_pairs_inserted += 1;
+    }
+
+    for (const record of missedRecordsByKey.values()) {
+      const canonicalSkillName = record.skill_name.trim();
+      const normalizedSkillName = normalizeRepairSkillName(canonicalSkillName);
+      const existing = selectExistingMiss.get(
+        record.session_id,
+        normalizedSkillName,
+        record.query,
+      ) as { legacy_rows: number; repair_rows: number; canonical_rows: number } | undefined;
+
+      const legacyRows = existing?.legacy_rows ?? 0;
+      const repairRows = existing?.repair_rows ?? 0;
+      const canonicalRows = existing?.canonical_rows ?? 0;
+
+      if (repairRows > 0) {
+        deleteRepairMiss.run(record.session_id, normalizedSkillName, record.query);
+        result.deleted_prior_repair_rows += repairRows;
+      }
+      if (legacyRows > 0) {
+        deleteLegacyMiss.run(record.session_id, normalizedSkillName, record.query);
+        result.deleted_legacy_rows += legacyRows;
+      }
+      if (canonicalRows > 0) {
+        result.skipped_pairs_with_canonical += 1;
+        continue;
+      }
+
+      const platform = inferRepairPlatform(record.source);
+      const { invocation_mode, confidence } = deriveInvocationMode({ is_repaired: true });
+      const canonical = buildCanonicalSkillInvocation({
+        platform,
+        capture_mode: "repair",
+        source_session_kind: "repaired",
+        session_id: record.session_id,
+        raw_source_ref: {
+          event_type: "repair-skill-usage",
+          metadata: {
+            source: record.source ?? null,
+            skill_path_resolution_source: record.skill_path_resolution_source ?? null,
+            skill_project_root: record.skill_project_root ?? null,
+            skill_registry_dir: record.skill_registry_dir ?? null,
+            miss_type: "contextual_read",
+          },
+        },
+        skill_invocation_id: `${record.session_id}:rmiss:${canonicalSkillName}:${stableKeyHash(record.query)}`,
+        occurred_at: record.timestamp,
+        skill_name: canonicalSkillName,
+        skill_path: record.skill_path,
+        invocation_mode,
+        triggered: false,
+        confidence,
+      });
+
+      writeSkillCheckToDb({
+        ...canonical,
+        query: record.query,
+        skill_path: record.skill_path,
+        skill_scope: record.skill_scope,
+        source: record.source,
+      });
+      result.inserted_repair_rows += 1;
+      result.repaired_pairs_inserted += 1;
+    }
+
+    db.run("COMMIT");
+  } catch (error) {
+    db.run("ROLLBACK");
+    throw error;
+  }
+
+  return result;
+}
+
 export function cliMain(): void {
   try {
     const { values } = parseArgs({
@@ -571,13 +928,15 @@ Options:
       return;
     }
 
+    const sqlite = persistRepairedSkillUsageToDb(getDb(), repairedRecords);
+
     writeRepairedSkillUsageRecords(
       repairedRecords,
       repairedSessionIds,
       values.out ?? REPAIRED_SKILL_LOG,
       values["sessions-marker"] ?? REPAIRED_SKILL_SESSIONS_MARKER,
     );
-    console.log(JSON.stringify(summary, null, 2));
+    console.log(JSON.stringify({ ...summary, sqlite }, null, 2));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`[ERROR] Failed to repair skill usage: ${message}`);