akm-cli 0.8.6 → 0.8.14

package/dist/core/state-db.js

@@ -49,11 +49,13 @@
  *
  * @module state-db
  */
-import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import path from "node:path";
-import { getDataDir } from "./paths";
-import { error } from "./warn";
+import { openDatabase } from "../storage/database.js";
+import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
+import { classifyImproveAction } from "./improve-types.js";
+import { getDataDir } from "./paths.js";
+import { error } from "./warn.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -84,11 +86,12 @@ export function getStateDbPath() {
  *     backwards compatibility; enabling them prevents orphaned rows in tables
  *     that reference each other (not used in v1 schema but guards future ones).
  *
- *   busy_timeout = 5000
+ *   busy_timeout = 30000
  *     When another connection holds a write lock, SQLite retries for up to
- *     5 000 ms before returning SQLITE_BUSY. Without this, the default timeout
- *     is 0 ms — any concurrent writer causes an immediate error. 5 s matches
- *     the same value used in openDatabase() for index.db.
+ *     30 000 ms before returning SQLITE_BUSY. Without this, the default timeout
+ *     is 0 ms — any concurrent writer causes an immediate error. 30 s (#589)
+ *     matches the value used in openDatabase() for index.db; 5 s proved too
+ *     narrow when a post-inference reindex overlapped a parallel event write.
  */
 export function openStateDatabase(dbPath) {
     const resolvedPath = dbPath ?? getStateDbPath();
@@ -96,14 +99,20 @@ export function openStateDatabase(dbPath) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const db = new Database(resolvedPath);
+    const db = openDatabase(resolvedPath);
     // PRAGMAs must run before any DDL or DML.
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     runMigrations(db);
     return db;
 }
+// ── Migration engine ─────────────────────────────────────────────────────────
+//
+// The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
+// engine at src/storage/engines/sqlite-migrations.ts. This module owns only its
+// own MIGRATIONS array and delegates application to that shared runner. The
+// {@link Migration} interface is imported from there.
 /**
  * All migrations in application order. New migrations are APPENDED to this
  * array — never inserted in the middle or reordered.
@@ -182,7 +191,9 @@ const MIGRATIONS = [
       --
       -- Extensible (metadata_json) columns:
       --   metadata_json TEXT      — JSON object for future proposal fields.
-      --                             Current fields stored here: sourceRun, review.
+      --                             Current fields stored here: sourceRun,
+      --                             review, confidence, gateDecision (#577),
+      --                             backupContent.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -450,42 +461,44 @@ const MIGRATIONS = [
         ON extract_sessions_seen(processed_at);
     `,
     },
+    // ── Migration 005 — proposal_fs_imports ─────────────────────────────────────
+    //
+    // One-shot ledger for the legacy filesystem→SQLite proposal import (#578).
+    //
+    // Before 0.9.0 the proposal queue lived as per-uuid JSON directories under
+    // `<stashDir>/.akm/proposals/` and the `proposals` table (created in 001) was
+    // dead weight. 0.9.0 makes the table canonical; the first proposal operation
+    // against a stash imports any legacy `proposal.json` files it finds (INSERT
+    // OR IGNORE, so re-runs never duplicate) and records the stash here so later
+    // invocations skip the directory walk entirely.
+    //
+    // Indexed (query) columns:
+    //   stash_dir    TEXT PK  — absolute stash root the import ran against.
+    //
+    // Non-indexed columns:
+    //   imported_at    TEXT     — ISO-8601 UTC; when the import completed.
+    //   imported_count INTEGER  — rows actually inserted by the import.
+    {
+        id: "005-proposal-fs-imports",
+        up: `
+      CREATE TABLE IF NOT EXISTS proposal_fs_imports (
+        stash_dir      TEXT    PRIMARY KEY,
+        imported_at    TEXT    NOT NULL,
+        imported_count INTEGER NOT NULL DEFAULT 0
+      );
+    `,
+    },
 ];
-/**
- * Create the migrations table if it does not exist. This must be called
- * unconditionally on every open so a fresh database bootstraps correctly.
- */
-function ensureMigrationsTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS schema_migrations (
-      id         TEXT    PRIMARY KEY,
-      applied_at TEXT    NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-}
 /**
  * Apply every pending migration in a single transaction per migration.
  *
- * Each migration is applied in its own transaction so a failure in migration N
- * does not roll back already-applied migrations 1..N-1. The migration row is
- * inserted AFTER the DDL succeeds, so a crash mid-migration leaves no row and
- * the migration will be retried on next open (all DDL in `up` uses IF NOT
- * EXISTS so the retry is safe).
+ * Delegates to the shared SQLite migration engine; state.db has no
+ * pre-versioning bootstrap step, so no `bootstrap` hook is passed.
  *
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db) {
-    ensureMigrationsTable(db);
-    const appliedRows = db.prepare("SELECT id FROM schema_migrations").all();
-    const applied = new Set(appliedRows.map((r) => r.id));
-    for (const migration of MIGRATIONS) {
-        if (applied.has(migration.id))
-            continue;
-        db.transaction(() => {
-            db.exec(migration.up);
-            db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
-        })();
-    }
+    runSqliteMigrations(db, MIGRATIONS);
 }
 /**
  * Convert a raw `EventRow` from the database to the public `EventEnvelope`
@@ -546,6 +559,9 @@ export function proposalRowToProposal(row) {
             ...(frontmatter !== undefined ? { frontmatter } : {}),
         },
         ...(meta.review !== undefined ? { review: meta.review } : {}),
+        ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
+        ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
+        ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
     };
 }
 /**
@@ -559,6 +575,12 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.sourceRun = proposal.sourceRun;
     if (proposal.review !== undefined)
         metaObj.review = proposal.review;
+    if (proposal.confidence !== undefined)
+        metaObj.confidence = proposal.confidence;
+    if (proposal.gateDecision !== undefined)
+        metaObj.gateDecision = proposal.gateDecision;
+    if (proposal.backupContent !== undefined)
+        metaObj.backupContent = proposal.backupContent;
     return {
         id: proposal.id,
         stash_dir: stashDir,
@@ -673,7 +695,10 @@ export function upsertProposal(db, proposal, stashDir) {
 }
 /**
  * List proposals, optionally filtered by stashDir, status, and/or ref.
- * Results are sorted by created_at ASC to match the existing listProposals() behaviour.
+ *
+ * Results are ordered by `created_at ASC` (matching the historical
+ * `listProposals()` sort), with `rowid` as a deterministic tiebreak so two
+ * proposals created in the same millisecond list in insertion order.
  */
 export function listStateProposals(db, options = {}) {
     const conditions = [];
@@ -694,21 +719,72 @@ export function listStateProposals(db, options = {}) {
     const rows = db
         .prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals ${where} ORDER BY created_at ASC`)
+       FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
     return rows.map(proposalRowToProposal);
 }
 /**
- * Look up a single proposal by id. Returns undefined when not found.
+ * Look up a single proposal by id, optionally scoped to one stash root.
+ * Returns undefined when not found.
  */
-export function getStateProposal(db, id) {
-    const row = db
-        .prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
+export function getStateProposal(db, id, stashDir) {
+    const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals WHERE id = ?`)
-        .get(id);
+       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
+    const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
     return row ? proposalRowToProposal(row) : undefined;
 }
+/**
+ * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
+ * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —
+ * prefix resolution is deliberately scoped to the live (pending) queue,
+ * mirroring the historical behaviour of scanning only the live directory.
+ *
+ * `%` / `_` / `\` in the prefix are escaped so the LIKE pattern is literal.
+ */
+export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
+    const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    const rows = db
+        .prepare(`SELECT id FROM proposals
+       WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'
+       ORDER BY id ASC`)
+        .all(stashDir, `${escaped}%`);
+    return rows.map((r) => r.id);
+}
+/**
+ * Whether the legacy filesystem proposal import has already run for `stashDir`.
+ * See migration 005 (`proposal_fs_imports`).
+ */
+export function hasImportedFsProposals(db, stashDir) {
+    // Drivers disagree on the no-row sentinel (bun:sqlite → null,
+    // better-sqlite3 → undefined) — Boolean() covers both.
+    return Boolean(db.prepare("SELECT 1 FROM proposal_fs_imports WHERE stash_dir = ?").get(stashDir));
+}
+/**
+ * Record that the legacy filesystem proposal import completed for `stashDir`
+ * so subsequent invocations skip the directory walk. INSERT OR REPLACE keeps
+ * the call idempotent.
+ */
+export function recordFsProposalsImport(db, stashDir, importedCount) {
+    db.prepare("INSERT OR REPLACE INTO proposal_fs_imports (stash_dir, imported_at, imported_count) VALUES (?, ?, ?)").run(stashDir, new Date().toISOString(), importedCount);
+}
+/**
+ * Insert a proposal row ONLY when the id is not already present (used by the
+ * legacy filesystem import so re-runs never clobber rows that have since been
+ * mutated through the canonical store). Returns true when a row was inserted.
+ */
+export function insertProposalIfAbsent(db, proposal, stashDir) {
+    const v = proposalToRowValues(proposal, stashDir);
+    const result = db
+        .prepare(`
+      INSERT OR IGNORE INTO proposals
+        (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+        .run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
+    const changes = result.changes ?? 0;
+    return Number(changes) > 0;
+}
 // ── task_history table helpers ───────────────────────────────────────────────
 /**
  * Upsert a task history row.
@@ -779,6 +855,47 @@ export function queryTaskHistory(db, options = {}) {
        FROM task_history ${where} ORDER BY started_at DESC`)
         .all(...params);
 }
+/**
+ * Read COMPLETED `akm-improve` task_history runs whose `started_at` falls in
+ * `[since, until)` (or `started_at >= since` when `until` is omitted), ordered
+ * oldest-first by `started_at`. Only rows with a non-null `completed_at` are
+ * returned (in-flight runs are excluded). The `task_id = 'akm-improve'`
+ * predicate is fixed because the only caller (commands/health.ts
+ * `loadTaskIntervals`) builds wall-time intervals for the improve cron task.
+ *
+ * Owns the SQL formerly inlined in commands/health.ts. Note the bound is
+ * EXCLUSIVE on the upper end (`started_at < ?`) — callers pass an already
+ * widened window; this helper does not widen.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function queryCompletedTaskIntervals(db, since, until) {
+    const sql = until
+        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
+        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}
+// ── schema introspection ─────────────────────────────────────────────────────
+/**
+ * Return the subset of `names` that exist as TABLEs in this database, ordered
+ * by name. Used by health's state-db-schema check to detect missing required
+ * tables without leaking a `sqlite_master` query into command code.
+ *
+ * The `IN (...)` predicate is built from parameter placeholders so table names
+ * are bound, never interpolated.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function listExistingTableNames(db, names) {
+    if (names.length === 0)
+        return [];
+    const placeholders = names.map(() => "?").join(", ");
+    return db
+        .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders}) ORDER BY name`)
+        .all(...names);
+}
 // ── events.jsonl import ──────────────────────────────────────────────────────
 /**
  * Import all events from an `events.jsonl` file into the `events` table.
@@ -877,25 +994,23 @@ export function computeImproveRunMetrics(result) {
     let autoAcceptedCount = 0;
     let errorCount = 0;
     for (const action of actions) {
-        switch (action.mode) {
-            case "reflect":
-            case "distill":
-            case "memory-inference":
-            case "graph-extraction":
+        // Bucketing delegated to the shared classifyImproveAction so this aggregate
+        // and the improve_completed event in improve.ts can never disagree, and so a
+        // new union variant is a compile error rather than a silent drop. Note:
+        // `reflect-guard-rejected` now counts as "rejected" (previously this switch
+        // omitted it entirely — a data-integrity miscount). "noop" (memory-prune) is
+        // intentionally counted in none of the three numeric buckets.
+        switch (classifyImproveAction(action.mode)) {
+            case "accepted":
                 acceptedCount++;
                 break;
-            case "reflect-cooldown":
-            case "reflect-skipped":
-            case "distill-skipped":
+            case "rejected":
                 rejectedCount++;
                 break;
-            case "reflect-failed":
             case "error":
                 errorCount++;
                 break;
-            case "memory-prune":
-                // Prune is bookkeeping, not "accepted" content authoring; count
-                // separately as a no-op for the audit aggregate.
+            case "noop":
                 break;
         }
         // Legacy: pre-gate action results may carry autoAccepted: true (reflect path).
@@ -929,6 +1044,26 @@ export function recordImproveRun(db, input) {
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
 }
+/**
+ * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
+ * window `[since, until)`. When `until` is omitted the window is open-ended
+ * (`started_at >= since`). Rows are returned newest-first (`ORDER BY
+ * started_at DESC`).
+ *
+ * Owns the SQL formerly inlined in commands/health.ts (`loadImproveRunRows`).
+ * The `dry_run = 0` filter is first-class so dry-run probes never pollute
+ * productivity audits.
+ *
+ * Connection-lifetime rule (WS5): `.all()` fully materializes the result set
+ * into a plain array before returning — no live cursor escapes the caller's
+ * `openStateDatabase` scope.
+ */
+export function queryImproveRuns(db, since, until) {
+    const sql = until
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}
 /**
  * Delete improve_runs rows older than `retentionDays` (default: 90). Mirrors
  * {@link purgeOldEvents} — same default, same return shape (number of rows
@@ -1027,7 +1162,7 @@ export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
 // ── registry_index_cache (goes in index.db, not state.db) ───────────────────
 /**
  * DDL for the `registry_index_cache` table that lives in the EXISTING index.db
- * (managed by src/indexer/db.ts).
+ * (managed by src/indexer/db/db.ts).
  *
  * Design: uses the same migration-safe ADD COLUMN approach. The table is
  * created with CREATE TABLE IF NOT EXISTS so it is safe to call inside
@@ -1051,7 +1186,7 @@ export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
  *   ALTER TABLE registry_index_cache ADD COLUMN error_message TEXT DEFAULT NULL;
  *
  * To add this table to index.db, call ensureRegistryIndexCacheSchema(db) from
- * within ensureSchema() in src/indexer/db.ts, or add it as a new CREATE TABLE
+ * within ensureSchema() in src/indexer/db/db.ts, or add it as a new CREATE TABLE
  * IF NOT EXISTS block inside the existing ensureSchema() call.
  */
 export const REGISTRY_INDEX_CACHE_DDL = `

package/dist/core/text-truncation.js

@@ -105,3 +105,151 @@ export function detectTruncatedDescription(description) {
     }
     return null;
 }
+// ── Post-generation repair pass (issue #556) ─────────────────────────────────
+/**
+ * Minimum length (chars) for a repaired description to be considered usable.
+ * Mirrors the floor in `isValidDescription` (≥20). Kept local so this module
+ * stays dependency-free of the validators (avoids an import cycle).
+ */
+const MIN_REPAIRED_DESCRIPTION_LEN = 20;
+/** Maximum length (chars) for a repaired description. Mirrors `isValidDescription` (≤400). */
+const MAX_REPAIRED_DESCRIPTION_LEN = 400;
+/**
+ * Strip trailing truncation fragments from a candidate clause: repeatedly drop
+ * a hanging-connector word and/or trailing `,` `;` `:` `+` and ellipses until
+ * the clause no longer looks truncated. PURE — no fabrication, only removal.
+ *
+ * Returns the trimmed-to-last-complete-token clause (may be empty if the whole
+ * thing was connectors/punctuation).
+ */
+function stripTrailingTruncationFragment(clause) {
+    let s = clause.trim();
+    // Loop because a tail can stack: "… related to the" → drop "the" → drop "to".
+    for (let guard = 0; guard < 64; guard++) {
+        const before = s;
+        // Drop trailing ellipsis / connector-only punctuation+operators.
+        s = s.replace(/\s*(\.{3,}|…)$/u, "").trim();
+        s = s.replace(/\s*[,;:+]+$/u, "").trim();
+        // Drop a trailing hanging-connector word (and any punctuation glued to it).
+        const m = s.match(/(?:^|\s)([A-Za-z']+)[.!?]*$/u);
+        if (m) {
+            const word = (m[1] ?? "").toLowerCase();
+            if (TRUNCATION_TRAILING_WORDS.has(word)) {
+                // Remove just the final word token (keep preceding text).
+                s = s.slice(0, s.length - m[0].length).trim();
+            }
+        }
+        if (s === before)
+            break;
+    }
+    return s;
+}
+/**
+ * Split prose into sentences on `.`/`!`/`?` boundaries (followed by whitespace
+ * or end). Keeps the terminating punctuation. Deliberately simple — good enough
+ * for the short, single-paragraph descriptions/bodies this repair operates on.
+ */
+function splitSentences(text) {
+    const out = [];
+    for (const match of text.matchAll(/[^.!?]+[.!?]+(?=\s|$)|[^.!?]+$/gu)) {
+        const s = match[0].trim();
+        if (s)
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * True when `candidate` is a self-contained, non-truncated clause of acceptable
+ * length. Used to gate repair outputs without importing the full validator
+ * (which would create a cycle). The full `isValidDescription` still runs
+ * downstream — this is only the truncation/length subset the repair targets.
+ */
+function isUsableClause(candidate) {
+    const c = candidate.trim();
+    if (c.length < MIN_REPAIRED_DESCRIPTION_LEN)
+        return false;
+    if (c.length > MAX_REPAIRED_DESCRIPTION_LEN)
+        return false;
+    if (detectTruncatedDescription(c) !== null)
+        return false;
+    // Must contain at least one word character (not pure punctuation).
+    if (!/[A-Za-z0-9]/.test(c))
+        return false;
+    return true;
+}
+/** Append a period when the clause lacks terminal sentence punctuation. PURE. */
+function ensureTerminalPunctuation(clause) {
+    const c = clause.trim();
+    if (/[.!?]$/.test(c))
+        return c;
+    return `${c}.`;
+}
+/**
+ * Deterministically repair an LLM-generated description that was sliced
+ * mid-sentence (issue #556). The repair NEVER fabricates new claims:
+ *
+ *   1. If the description is not truncated, it is returned **byte-identical**
+ *      (zero behaviour change for already-valid descriptions).
+ *   2. Otherwise:
+ *      a. **trim-to-last-complete-clause** — strip the trailing
+ *         truncation-indicator word(s)/punctuation; if a complete earlier
+ *         sentence survives, use the longest non-truncated prefix.
+ *      b. **swap-in first body sentence** — if (a) yields nothing usable and a
+ *         `body` is provided, use the first clean, complete sentence of the
+ *         body.
+ *      c. **fallback** — if neither produces a usable, non-truncated clause,
+ *         return the original string unchanged so the existing validation
+ *         rejects it exactly as before (no regression, no fabrication).
+ *
+ * @param description The raw description (possibly truncated).
+ * @param body Optional asset body to source a clean completion sentence from.
+ */
+export function repairTruncatedDescription(description, body) {
+    if (typeof description !== "string")
+        return description;
+    // Guarantee: untruncated input passes through byte-identical.
+    if (detectTruncatedDescription(description) === null)
+        return description;
+    const trimmed = description.trim();
+    // (a) trim-to-last-complete-clause.
+    // First, try the whole string with its trailing fragment stripped.
+    const stripped = stripTrailingTruncationFragment(trimmed);
+    if (isUsableClause(stripped)) {
+        return ensureTerminalPunctuation(stripped);
+    }
+    // If the description has multiple sentences, the truncation is in the last
+    // one — fall back to the longest leading run of complete sentences.
+    const sentences = splitSentences(trimmed);
+    if (sentences.length > 1) {
+        for (let take = sentences.length - 1; take >= 1; take--) {
+            const prefix = sentences.slice(0, take).join(" ").trim();
+            const cleaned = stripTrailingTruncationFragment(prefix);
+            if (isUsableClause(cleaned))
+                return ensureTerminalPunctuation(cleaned);
+        }
+    }
+    // (b) swap-in first clean, complete body sentence.
+    if (typeof body === "string" && body.trim().length > 0) {
+        const bodyText = body
+            .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "") // drop any frontmatter
+            .replace(/```[\s\S]*?```/g, " ") // drop fenced code
+            .replace(/`[^`]*`/g, " "); // drop inline code spans
+        for (const rawLine of bodyText.split(/\n/)) {
+            const line = rawLine
+                .replace(/\*\*([^*]+)\*\*/g, "$1")
+                .replace(/\*([^*]+)\*/g, "$1")
+                .replace(/^[#*\->_\s]+/, "")
+                .trim();
+            if (!line)
+                continue;
+            if (/^[a-z_]+:\s/i.test(line))
+                continue; // skip yaml-ish leak lines
+            for (const sentence of splitSentences(line)) {
+                if (isUsableClause(sentence))
+                    return ensureTerminalPunctuation(sentence);
+            }
+        }
+    }
+    // (c) fallback: return original unchanged — validation rejects as before.
+    return description;
+}

package/dist/core/time.js

@@ -8,7 +8,7 @@
  * interpret the same set of formats (ISO-8601, epoch ms, plain date strings)
  * consistently without private re-implementations drifting apart.
  */
-import { UsageError } from "./errors";
+import { UsageError } from "./errors.js";
 // ── Since-flag parsing ───────────────────────────────────────────────────────
 /**
  * Parse a user-supplied `--since` value and return an ISO-8601 timestamp