akm-cli 0.9.0-beta.11 → 0.9.0-beta.26

package/dist/commands/feedback-cli.js

@@ -11,11 +11,9 @@ import { writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
+import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
-import { ensureIndex } from "../indexer/ensure-index.js";
-import { withIndexWriterLease } from "../indexer/index-writer-lock.js";
-import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
@@ -204,51 +202,57 @@ export const feedbackCommand = defineCommand({
                 ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
             };
             const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
-            const utilityResult = await withIndexWriterLease({ purpose: "feedback-write" }, async () => {
-                // Feedback is itself an index.db writer, so it must not spawn a detached
-                // reindex and then compete with it for the same database file.
-                const sources = resolveSourceEntries();
-                if (sources.length > 0) {
-                    await ensureIndex(sources[0].path, { mode: "blocking" });
+            // Feedback only needs the index to exist, not to be current. A stale index
+            // is fine — the ref lookup works against any populated DB. We do NOT call
+            // ensureIndex here: it either blocks (3+ min inline reindex) or spawns a
+            // background process that holds the writer lock, causing the feedback write
+            // to spin-wait for the full reindex duration. If the DB is absent we give a
+            // clear error below rather than silently triggering a rebuild.
+            if (!fs.existsSync(getDbPath())) {
+                throw new UsageError("Index not found. Run 'akm index' first to build the index before recording feedback.", "MISSING_REQUIRED_ARGUMENT", "akm index");
+            }
+            // Feedback writes exactly 2 rows (usage_events + utility_score). SQLite
+            // WAL mode + busy_timeout=30s handles concurrent access with an ongoing
+            // `akm improve` run without needing the application-level writer lock.
+            // The lock was originally needed to prevent feedback from racing a
+            // background reindex it spawned — now that ensureIndex is removed, holding
+            // the lock only causes feedback to block for the full improve run duration.
+            let utilityResult;
+            const db = openExistingDatabase();
+            try {
+                const entryId = findEntryIdByRef(db, ref);
+                if (entryId === undefined) {
+                    throw new UsageError(`Ref "${ref}" is not in the index. ` +
+                        "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
                 }
-                let scopedUtilityResult;
-                const db = openExistingDatabase();
+                // Persist the feedback signal into usage_events. For positive signals,
+                // the EMA utility score is updated immediately on the next read path.
+                // For negative signals, the score is adjusted the next time `akm index`
+                // runs — the signal is durable in the DB but does NOT suppress ranking
+                // in search results until after reindexing.
+                insertUsageEvent(db, {
+                    event_type: "feedback",
+                    entry_ref: ref,
+                    entry_id: entryId,
+                    signal,
+                    metadata: metadataStr,
+                });
+                // Apply feedback-derived utility score adjustment immediately so that
+                // positive/negative signals influence search ranking without requiring
+                // a full reindex. We query the total accumulated feedback counts from
+                // usage_events so the delta reflects the entire signal history.
+                // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
                 try {
-                    const entryId = findEntryIdByRef(db, ref);
-                    if (entryId === undefined) {
-                        throw new UsageError(`Ref "${ref}" is not in the index. ` +
-                            "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
-                    }
-                    // Persist the feedback signal into usage_events. For positive signals,
-                    // the EMA utility score is updated immediately on the next read path.
-                    // For negative signals, the score is adjusted the next time `akm index`
-                    // runs — the signal is durable in the DB but does NOT suppress ranking
-                    // in search results until after reindexing.
-                    insertUsageEvent(db, {
-                        event_type: "feedback",
-                        entry_ref: ref,
-                        entry_id: entryId,
-                        signal,
-                        metadata: metadataStr,
-                    });
-                    // Apply feedback-derived utility score adjustment immediately so that
-                    // positive/negative signals influence search ranking without requiring
-                    // a full reindex. We query the total accumulated feedback counts from
-                    // usage_events so the delta reflects the entire signal history.
-                    // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
-                    try {
-                        const { pos, neg } = countFeedbackSignals(db, entryId);
-                        scopedUtilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
-                    }
-                    catch {
-                        // best-effort — feedback recording succeeds even if utility update fails
-                    }
+                    const { pos, neg } = countFeedbackSignals(db, entryId);
+                    utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
                 }
-                finally {
-                    closeDatabase(db);
+                catch {
+                    // best-effort — feedback recording succeeds even if utility update fails
                 }
-                return scopedUtilityResult;
-            });
+            }
+            finally {
+                closeDatabase(db);
+            }
             appendEvent({
                 eventType: "feedback",
                 ref,

package/dist/commands/health/html-report.js

@@ -29,6 +29,11 @@ const ECHARTS_CDN = "https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"
 const ECHARTS_VENDOR_PATH = path.join(getDirname(import.meta.url), "../../assets/templates/html/vendor/echarts.min.js");
 // ── Small formatters (ports of render.py helpers) ───────────────────────────
 const esc = escapeHtml;
+/** Emit a <time> element that the browser's JS will reformat to the viewer's local timezone. */
+function isoTimeTag(iso) {
+    const fallback = iso.slice(0, 16).replace("T", " ");
+    return `<time data-iso="${esc(iso)}">${esc(fallback)}</time>`;
+}
 function num(value) {
     return Math.round(value).toLocaleString("en-US");
 }
@@ -264,6 +269,19 @@ export function buildHealthHtmlReplacements(result, opts) {
     const mi = improve.memoryInference;
     const ge = improve.graphExtraction;
     const wallTime = improve.wallTime;
+    // WS-5: perf telemetry, coverage, and degradation metrics.
+    const perf = improve.perfTelemetry ?? {
+        dedupPoolSize: 0,
+        llmPoolSize: 0,
+        judgedCacheSkipped: 0,
+        embedMs: 0,
+        embedCacheHits: 0,
+        embedCacheMisses: 0,
+        overBudgetRuns: 0,
+        runsWithTelemetry: 0,
+    };
+    const coverage = improve.coverage;
+    const degradation = improve.degradation;
     // #576: real per-stage LLM token/time accounting (replaces the GPU-time
     // proxy). Optional-guarded so reports built from older health JSON without
     // the aggregate still render.
@@ -292,7 +310,7 @@ export function buildHealthHtmlReplacements(result, opts) {
     // ── Meta (collect.py steps 10-11) ──────────────────────────────────────────
     const sinceIso = result.since;
     const reportDate = sinceIso.slice(0, 10);
-    const sinceHuman = sinceIso ? `${sinceIso.slice(0, 16).replace("T", " ")} UTC → now` : `last ${opts.window}`;
+    const sinceHuman = sinceIso ? `${isoTimeTag(sinceIso)} → now` : `last ${esc(opts.window)}`;
     const reportTitle = reportDate ? `AKM Health Report — ${reportDate}` : "AKM Health Report";
     const lastRun = runs[runs.length - 1];
     const generatedAt = lastRun ? lastRun.completedAt || lastRun.startedAt || sinceIso : sinceIso;
@@ -308,9 +326,7 @@ export function buildHealthHtmlReplacements(result, opts) {
     const generatedMs = Date.parse(generatedAt);
     const idleTailMs = Number.isFinite(latestRunMs) && Number.isFinite(generatedMs) ? Math.max(0, generatedMs - latestRunMs) : 0;
     const isStale = totalRuns === 0 || (Number.isFinite(latestRunMs) && Number.isFinite(sinceMs) && idleTailMs > STALE_MS);
-    const latestRunHuman = lastRun
-        ? `${(lastRun.completedAt || lastRun.startedAt).slice(0, 16).replace("T", " ")} UTC`
-        : "—";
+    const latestRunHuman = lastRun ? isoTimeTag(lastRun.completedAt || lastRun.startedAt) : "—";
     // ── Status badges ──────────────────────────────────────────────────────────
     const badgeByStatus = {
         pass: { badge: "badge-pass", dot: "dot-pass", label: "PASS" },
@@ -353,7 +369,7 @@ export function buildHealthHtmlReplacements(result, opts) {
     const snapRows = latest
         ? [
             li("Run id", `<code>${esc(latest.id.slice(0, 28))}</code>`),
-            li("Completed", `${esc((latest.completedAt || latest.startedAt).slice(0, 16).replace("T", " "))} UTC`),
+            li("Completed", isoTimeTag(latest.completedAt || latest.startedAt)),
             li("Status", latest.ok ? "✅ ok" : "❌ failed"),
             li("Wall time", fmtMs(latest.wallTimeMs)),
             li("Reflect ok/fail", `${latest.reflectOk} / ${latest.reflectFailed}`),
@@ -404,7 +420,7 @@ export function buildHealthHtmlReplacements(result, opts) {
     const verdictSentence = `${verdictWord} — ${esc(verdictRest)}.`;
     const verdictHtml = `<div class="verdict ${result.status}"><b>Verdict:</b> ${verdictSentence}</div>`;
     // ── Freshness line ─────────────────────────────────────────────────────────
-    const freshnessHtml = `<div class="freshness${isStale ? " stale" : ""}">${isStale ? "⚠️ Stale: " : ""}Latest run ${esc(latestRunHuman)} &nbsp;·&nbsp; generated ${esc(generatedAt)}${isStale ? " — no recent activity (newest run older than the 6h freshness threshold)." : "."}</div>`;
+    const freshnessHtml = `<div class="freshness${isStale ? " stale" : ""}">${isStale ? "⚠️ Stale: " : ""}Latest run ${latestRunHuman} &nbsp;·&nbsp; generated ${isoTimeTag(generatedAt)}${isStale ? " — no recent activity (newest run older than the 6h freshness threshold)." : "."}</div>`;
     const execSummary = `
     <h2>${overallEmoji} Executive Summary
         <span class="badge-pill ${badge.badge}" style="font-size:11px;">
@@ -513,6 +529,97 @@ export function buildHealthHtmlReplacements(result, opts) {
         ],
         ["LLM wall time", fmtMs(llm.totalDurationMs), trend.latency],
     ];
+    // #612 — auto-accept gate calibration. Only surface when the gate actually
+    // acted on proposals in the window (samples > 0); a default ungated install
+    // reports an empty summary and we omit the rows to keep the table parity-clean.
+    const calibration = improve.calibration;
+    if (calibration && calibration.samples > 0) {
+        summaryRows.push([
+            "Calibration samples",
+            num(calibration.samples),
+            "flat",
+            "Auto-accept gate decisions (auto-accepted + auto-rejected) the calibration join measured this window.",
+        ], [
+            "Calibration accept rate",
+            String(calibration.overallAcceptRate),
+            "flat",
+            "Realized accept rate of acted-on gate decisions (auto-accepted / total acted-on).",
+        ], [
+            "Calibration gap",
+            String(calibration.calibrationGap),
+            "flat",
+            "Mean predicted confidence minus realized accept rate. Positive = the gate is over-confident.",
+        ]);
+    }
+    // WS-5: denominator-fixed coverage rows (only when we have real data).
+    if (coverage && !Number.isNaN(coverage.rate)) {
+        summaryRows.push([
+            "Coverage rate",
+            pct(coverage.rate, 1),
+            "flat",
+            "Accepted proposals / total stash assets (denominator-fixed). Shows what fraction of the corpus has been touched.",
+        ], [
+            "Eligible fraction",
+            pct(coverage.eligibleFraction, 1),
+            "flat",
+            "Eligible assets / total stash assets. Fraction the improve pipeline actively considers.",
+        ], [
+            "Coverage accepted",
+            num(coverage.acceptedProposals),
+            "up",
+            "Total accepted proposals used for the denominator-fixed coverage rate.",
+        ]);
+    }
+    // WS-5: perf telemetry rows (only when at least one run reported telemetry).
+    if (perf.runsWithTelemetry > 0) {
+        const embedCacheTotal = perf.embedCacheHits + perf.embedCacheMisses;
+        const embedCacheHitRate = embedCacheTotal > 0 ? pct(perf.embedCacheHits / embedCacheTotal, 1) : "—";
+        summaryRows.push([
+            "Embed cache hit rate",
+            embedCacheHitRate,
+            "flat",
+            "Fraction of embedding lookups served from cache (>95% is healthy). Aggregated across WS-5 runs.",
+        ], [
+            "Embed wall time",
+            fmtMs(perf.embedMs),
+            "flat",
+            "Cumulative embedding wall-clock time across consolidation runs in the window.",
+        ], [
+            "Judged-cache skipped",
+            num(perf.judgedCacheSkipped),
+            "flat",
+            "Candidates skipped by the judged-cache (not sent to LLM). Higher = more efficient reuse of prior judgments.",
+        ], [
+            "Dedup pool size",
+            num(perf.dedupPoolSize),
+            "flat",
+            "Average memory pool size after deduplication (before judged-cache narrowing). WS-5 perf telemetry.",
+        ], [
+            "Over-budget consolidation runs",
+            String(perf.overBudgetRuns),
+            perf.overBudgetRuns > 0 ? "down" : "flat",
+            "Runs where consolidation alone exceeded the total run budget (estimatedBudgetFractionUsed > 1.0).",
+        ]);
+    }
+    // WS-5: degradation metrics rows.
+    if (degradation) {
+        summaryRows.push([
+            "Corpus diversity (Gini)",
+            num(degradation.corpusCentroidDistance),
+            degradation.entrenchmentFlagged ? "down" : "flat",
+            "Gini coefficient of retrieval_salience for top-100 ranked assets. High Gini (>0.35) = entrenchment risk.",
+        ], [
+            "Merge fidelity contradiction rate",
+            pct(degradation.mergeFidelityContradictionRate, 1),
+            "flat",
+            "Fraction of consolidated proposals that involved a contradiction, from consolidation result envelopes.",
+        ], [
+            "High-generation fraction",
+            pct(degradation.highGenerationFraction, 1),
+            "flat",
+            "Fraction of assets with consecutive_no_ops >= 2 (proxy for high-generation assets in the salience table).",
+        ]);
+    }
     const summaryRowsHtml = summaryRows
         .map(([label, value, t, tip]) => {
         const labelHtml = tip ? `<abbr title="${esc(tip)}">${esc(label)}</abbr>` : esc(label);
@@ -606,6 +713,31 @@ export function buildHealthHtmlReplacements(result, opts) {
             descHtml: `Newest run is ${esc(latestRunHuman)} — older than the 6h freshness threshold. Check the improve scheduler/cron.`,
         });
     }
+    // WS-5: corpus entrenchment flag.
+    if (degradation?.entrenchmentFlagged) {
+        pushItem({
+            key: "corpus-entrenchment",
+            prio: "P2",
+            cls: "warn",
+            title: "Corpus entrenchment risk: retrieval_salience Gini > 0.35",
+            descHtml: "A small set of assets dominates retrieval — retrieval diversity is low. " +
+                "Review top-ranked assets for stale or over-represented content. " +
+                `Corpus diversity proxy: ${esc(String(degradation.corpusCentroidDistance))}.`,
+            remedy: "akm health --format json | jq '.improve.degradation'",
+        });
+    }
+    // WS-5: over-budget consolidation advisory.
+    if (perf.overBudgetRuns > 0) {
+        pushItem({
+            key: "over-budget-consolidation",
+            prio: "P2",
+            cls: "warn",
+            title: `${perf.overBudgetRuns} consolidation run${perf.overBudgetRuns === 1 ? "" : "s"} exceeded budget`,
+            descHtml: "Consolidation phase wall time exceeded the total run budget on these runs. " +
+                "Consider increasing the timeout or reducing the consolidation pool via profile config.",
+            remedy: "akm config show",
+        });
+    }
     // Session-log notes (informational, lowest priority).
     if (result.sessionLogAdvisories.length > 0) {
         const patterns = result.sessionLogAdvisories
@@ -629,24 +761,17 @@ export function buildHealthHtmlReplacements(result, opts) {
         ? proposals
             .map((p, i) => {
             const tagCls = p.source === "extract" ? "tag-extract" : "tag-consolidate";
-            const ts = p.createdAt.slice(0, 16).replace("T", " ");
             return (`<tr><td>${i + 1}</td><td><code>${esc(p.ref)}</code></td>` +
                 `<td><span class="tag ${tagCls}">${esc(p.source)}</span></td>` +
-                `<td>${esc(ts)}</td></tr>`);
+                `<td>${isoTimeTag(p.createdAt)}</td></tr>`);
         })
             .join("\n")
         : '<tr><td colspan="4" style="text-align:center;color:var(--muted);">No pending proposals</td></tr>';
-    // ── Commands used ──────────────────────────────────────────────────────────
-    const commandsHtml = [
-        `      <div><span>akm health --since=${esc(opts.window)} --group-by run --format json</span></div>`,
-        `      <div><span>akm health --since=${esc(opts.window)} --window-compare=${esc(opts.compare)} --format json</span></div>`,
-        "      <div><span>akm proposal list</span></div>",
-    ].join("\n");
     return {
         "%%ECHARTS_TAG%%": buildEchartsTag(opts),
         "%%REPORT_TITLE%%": esc(reportTitle),
         "%%WINDOW%%": esc(opts.window),
-        "%%SINCE_HUMAN%%": esc(sinceHuman),
+        "%%SINCE_HUMAN%%": sinceHuman,
         "%%RUN_COUNT%%": num(totalRuns),
         "%%STATUS_BADGE_HTML%%": `${statusBadge}\n    ${failBadge}`,
         "%%EXEC_SUMMARY_HTML%%": execSummary,
@@ -659,7 +784,6 @@ export function buildHealthHtmlReplacements(result, opts) {
         "%%ACTION_ITEMS_HTML%%": actionItemsHtml,
         "%%PROPOSAL_ROWS_HTML%%": proposalRowsHtml,
         "%%PROPOSAL_COUNT%%": String(proposals.length),
-        "%%COMMANDS_HTML%%": commandsHtml,
         "%%GENERATED_AT%%": esc(generatedAt),
         "%%AKM_VERSION%%": esc(pkgVersion),
     };