akm-cli 0.7.4 → 0.8.0-rc1

package/dist/commands/graph.js

@@ -0,0 +1,222 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { loadConfig } from "../core/config";
+import { NotFoundError, UsageError } from "../core/errors";
+import { closeDatabase, openExistingDatabase } from "../indexer/db";
+import { listRelatedPathsForFile } from "../indexer/graph-boost";
+import { loadStoredGraphSnapshot } from "../indexer/graph-db";
+import { lookup } from "../indexer/indexer";
+import { resolveAssetPath } from "../indexer/path-resolver";
+import { findSourceForPath, resolveSourceEntries } from "../indexer/search-source";
+function resolveGraphStashPath(source) {
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    if (sources.length === 0) {
+        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
+    }
+    if (!source || source === "primary")
+        return sources[0].path;
+    const matched = sources.find((entry) => entry.registryId === source || entry.path === source);
+    if (!matched) {
+        throw new NotFoundError(`Source not found: ${source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
+    }
+    return matched.path;
+}
+function loadGraph(source) {
+    const stashPath = resolveGraphStashPath(source);
+    let db;
+    try {
+        db = openExistingDatabase();
+        const snapshot = loadStoredGraphSnapshot(stashPath, db);
+        if (!snapshot) {
+            throw new NotFoundError(`Graph data not found for source ${stashPath}.`, "FILE_NOT_FOUND", "Run the improvement flow that refreshes graph extraction data.");
+        }
+        return {
+            graph: {
+                schemaVersion: snapshot.schemaVersion,
+                generatedAt: snapshot.generatedAt,
+                stashRoot: snapshot.stashPath,
+                files: snapshot.files,
+                entities: snapshot.entities,
+                relations: snapshot.relations,
+                ...(snapshot.quality ? { quality: snapshot.quality } : {}),
+            },
+            stashPath,
+            graphPath: snapshot.graphPath,
+        };
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+function countEntitiesByFile(nodes) {
+    const counts = new Map();
+    for (const node of nodes) {
+        const seen = new Set();
+        for (const entity of node.entities) {
+            if (seen.has(entity))
+                continue;
+            seen.add(entity);
+            counts.set(entity, (counts.get(entity) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+export function akmGraphSummary(options) {
+    const { graph, stashPath, graphPath } = loadGraph(options?.source);
+    return {
+        schemaVersion: 1,
+        shape: "graph-summary",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        fileCount: graph.files.length,
+        entityCount: Array.isArray(graph.entities) ? graph.entities.length : countEntitiesByFile(graph.files).size,
+        relationCount: Array.isArray(graph.relations)
+            ? graph.relations.length
+            : graph.files.reduce((sum, node) => sum + node.relations.length, 0),
+        ...(graph.quality ? { quality: graph.quality } : {}),
+    };
+}
+export function akmGraphEntities(options) {
+    const { graph, stashPath, graphPath } = loadGraph(options?.source);
+    const limit = options?.limit;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
+    }
+    const counts = countEntitiesByFile(graph.files);
+    const entities = [...counts.entries()]
+        .map(([name, fileCount]) => ({ name, fileCount }))
+        .sort((a, b) => b.fileCount - a.fileCount || a.name.localeCompare(b.name));
+    const sliced = typeof limit === "number" ? entities.slice(0, limit) : entities;
+    return {
+        schemaVersion: 1,
+        shape: "graph-entities",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        total: entities.length,
+        entities: sliced,
+    };
+}
+export function akmGraphRelations(options) {
+    const { graph, stashPath, graphPath } = loadGraph(options?.source);
+    const limit = options?.limit;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
+    }
+    const counts = new Map();
+    for (const node of graph.files) {
+        for (const rel of node.relations) {
+            const key = `${rel.from}\u0000${rel.to}\u0000${rel.type ?? ""}`;
+            const existing = counts.get(key);
+            if (existing) {
+                existing.count += 1;
+            }
+            else {
+                counts.set(key, { from: rel.from, to: rel.to, ...(rel.type ? { type: rel.type } : {}), count: 1 });
+            }
+        }
+    }
+    const relations = [...counts.values()].sort((a, b) => b.count - a.count || a.from.localeCompare(b.from) || a.to.localeCompare(b.to));
+    const sliced = typeof limit === "number" ? relations.slice(0, limit) : relations;
+    return {
+        schemaVersion: 1,
+        shape: "graph-relations",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        total: relations.length,
+        relations: sliced,
+    };
+}
+export function akmGraphExport(options) {
+    if (!options.out?.trim()) {
+        throw new UsageError("`akm graph export` requires --out <path>.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const format = options.format ?? "json";
+    if (format !== "json" && format !== "jsonl") {
+        throw new UsageError("--format must be one of: json, jsonl.", "INVALID_FLAG_VALUE");
+    }
+    const { graph, stashPath, graphPath } = loadGraph(options.source);
+    const outPath = path.resolve(options.out);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    const payload = format === "json"
+        ? `${JSON.stringify(graph, null, 2)}\n`
+        : `${[
+            ...graph.files.flatMap((file) => file.entities.map((entity) => JSON.stringify({ kind: "entity", entity, file: file.path }))),
+            ...graph.files.flatMap((file) => file.relations.map((relation) => JSON.stringify({ kind: "relation", ...relation, file: file.path }))),
+        ].join("\n")}\n`;
+    fs.writeFileSync(outPath, payload, "utf8");
+    return {
+        schemaVersion: 1,
+        shape: "graph-export",
+        stashPath,
+        graphPath,
+        outPath,
+        format,
+        bytes: Buffer.byteLength(payload, "utf8"),
+    };
+}
+export async function akmGraphRelated(options) {
+    const ref = options.ref.trim();
+    if (!ref) {
+        throw new UsageError("`akm graph related` requires <ref>.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const limit = options.limit;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
+    }
+    const target = await resolveGraphTarget(ref, options.source);
+    const { graph, stashPath, graphPath } = loadGraph(target.stashPath);
+    let db;
+    const related = (() => {
+        try {
+            db = openExistingDatabase();
+            return listRelatedPathsForFile(stashPath, target.filePath, limit ?? 5, db);
+        }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
+    })();
+    return {
+        schemaVersion: 1,
+        shape: "graph-related",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        ref: target.ref,
+        path: target.filePath,
+        total: related.length,
+        related,
+        ...(related.length === 0 ? { tip: "No related graph neighbors were found for this asset." } : {}),
+    };
+}
+async function resolveGraphTarget(ref, source) {
+    const parsedRef = parseAssetRef(ref);
+    const filePath = (await resolveAssetPath(parsedRef, {
+        mode: "index-first",
+        honorOrigin: true,
+    })) ?? (await lookup(parsedRef))?.filePath;
+    if (!filePath) {
+        throw new NotFoundError(`Asset not found for ref: ${ref}`);
+    }
+    const allSources = resolveSourceEntries(undefined, loadConfig());
+    const matchedSource = findSourceForPath(filePath, allSources);
+    const inferredStashPath = matchedSource?.path;
+    const stashPath = source ? resolveGraphStashPath(source) : inferredStashPath;
+    if (!stashPath) {
+        throw new NotFoundError(`Could not determine stash source for ref: ${ref}`, "SOURCE_NOT_FOUND");
+    }
+    if (!filePath.startsWith(path.resolve(stashPath) + path.sep) && path.resolve(filePath) !== path.resolve(stashPath)) {
+        throw new UsageError(`Resolved asset ${ref} is not inside source ${source ?? stashPath}.`, "INVALID_SOURCE_VALUE", "Pass --source for the asset's source, or omit it to infer from the resolved asset path.");
+    }
+    return {
+        ref,
+        parsedRef,
+        filePath,
+        stashPath,
+    };
+}

package/dist/commands/health.js

@@ -0,0 +1,376 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { getStateDbPathInDataDir } from "../core/paths";
+import { openStateDatabase, queryTaskHistory } from "../core/state-db";
+import { parseSinceToIso } from "../core/time";
+import { readSemanticStatus } from "../indexer/semantic-status";
+import { detectAgentCliProfiles, requireAgentProfile } from "../integrations/agent";
+import { getExecutionLogCandidates } from "../integrations/session-logs";
+const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
+const IMPROVE_COMPLETED_EVENT = "improve_completed";
+const HEALTH_PROBE_EVENT = "health_probe";
+const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;
+export function parseHealthSince(since) {
+    if (since === undefined || since.trim() === "") {
+        return new Date(Date.now() - DEFAULT_SINCE_MS).toISOString();
+    }
+    const trimmed = since.trim();
+    const durationMatch = trimmed.match(/^(\d+)([dhm])$/i);
+    if (durationMatch) {
+        const amount = Number.parseInt(durationMatch[1] ?? "0", 10);
+        const unit = (durationMatch[2] ?? "d").toLowerCase();
+        if (!Number.isFinite(amount) || amount < 0) {
+            throw new UsageError("--since must be a non-negative duration or timestamp.", "INVALID_FLAG_VALUE");
+        }
+        const multiplier = unit === "h" ? 60 * 60 * 1000 : unit === "m" ? 30 * 24 * 60 * 60 * 1000 : 24 * 60 * 60 * 1000;
+        return new Date(Date.now() - amount * multiplier).toISOString();
+    }
+    return parseSinceToIso(trimmed);
+}
+function roundRate(value) {
+    return Number(value.toFixed(4));
+}
+function parseTaskMetadata(row) {
+    try {
+        return JSON.parse(row.metadata_json);
+    }
+    catch {
+        return {};
+    }
+}
+function createUnknownImproveMetrics() {
+    return {
+        invoked: 0,
+        completed: 0,
+        skipped: 0,
+        skipReasons: {},
+        plannedRefs: 0,
+        actions: {
+            reflect: 0,
+            distill: 0,
+            distillSkipped: 0,
+            memoryPrune: 0,
+            memoryInference: 0,
+            graphExtraction: 0,
+            error: 0,
+        },
+        crossStepErrorsInjected: 0,
+        feedbackRatioUsed: false,
+        coverageGapCount: 0,
+        executionLogCandidateCount: 0,
+        evalCasesWritten: 0,
+        deadUrlCount: 0,
+        memorySummary: { eligible: 0, derived: 0 },
+        memoryCleanup: {
+            pruneCandidates: 0,
+            contradictionCandidates: 0,
+            beliefStateTransitions: 0,
+            consolidationCandidates: 0,
+            archived: 0,
+            warnings: 0,
+        },
+        consolidation: { ran: false, processed: 0, durationMs: 0 },
+        memoryInference: { ran: false, writes: 0, durationMs: 0 },
+        graphExtraction: { ran: false, extractedFiles: 0, durationMs: 0 },
+    };
+}
+function toFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return 0;
+}
+function summarizeImproveCompleted(events) {
+    const metrics = createUnknownImproveMetrics();
+    metrics.completed = events.length;
+    for (const event of events) {
+        const meta = event.metadata ?? {};
+        metrics.plannedRefs += toFiniteNumber(meta.plannedRefs);
+        metrics.actions.reflect += toFiniteNumber(meta.reflectActions);
+        metrics.actions.distill += toFiniteNumber(meta.distillActions);
+        metrics.actions.distillSkipped += toFiniteNumber(meta.distillSkippedActions);
+        metrics.actions.memoryPrune += toFiniteNumber(meta.memoryPruneActions);
+        metrics.actions.memoryInference += toFiniteNumber(meta.memoryInferenceActions);
+        metrics.actions.graphExtraction += toFiniteNumber(meta.graphExtractionActions);
+        metrics.actions.error += toFiniteNumber(meta.errorActions);
+        metrics.crossStepErrorsInjected += toFiniteNumber(meta.crossStepErrorsInjected);
+        metrics.coverageGapCount += toFiniteNumber(meta.coverageGapCount);
+        metrics.executionLogCandidateCount += toFiniteNumber(meta.executionLogCandidateCount);
+        metrics.evalCasesWritten += toFiniteNumber(meta.evalCasesWritten);
+        metrics.deadUrlCount += toFiniteNumber(meta.deadUrlCount);
+        metrics.memorySummary.eligible += toFiniteNumber(meta.memoryEligible);
+        metrics.memorySummary.derived += toFiniteNumber(meta.memoryDerived);
+        metrics.memoryCleanup.pruneCandidates += toFiniteNumber(meta.memoryCleanupPruneCandidates);
+        metrics.memoryCleanup.contradictionCandidates += toFiniteNumber(meta.memoryCleanupContradictionCandidates);
+        metrics.memoryCleanup.beliefStateTransitions += toFiniteNumber(meta.memoryCleanupBeliefStateTransitions);
+        metrics.memoryCleanup.consolidationCandidates += toFiniteNumber(meta.memoryCleanupConsolidationCandidates);
+        metrics.memoryCleanup.archived += toFiniteNumber(meta.memoryCleanupArchived);
+        metrics.memoryCleanup.warnings += toFiniteNumber(meta.memoryCleanupWarnings);
+        metrics.consolidation.processed += toFiniteNumber(meta.consolidationProcessed);
+        metrics.consolidation.durationMs += toFiniteNumber(meta.consolidationDurationMs);
+        metrics.memoryInference.writes += toFiniteNumber(meta.memoryInferenceWrites);
+        metrics.memoryInference.durationMs += toFiniteNumber(meta.memoryInferenceDurationMs);
+        metrics.graphExtraction.extractedFiles += toFiniteNumber(meta.graphExtractionExtractedFiles);
+        metrics.graphExtraction.durationMs += toFiniteNumber(meta.graphExtractionDurationMs);
+        if (meta.feedbackRatioUsed === true)
+            metrics.feedbackRatioUsed = true;
+    }
+    metrics.consolidation.ran = metrics.consolidation.processed > 0 || metrics.consolidation.durationMs > 0;
+    metrics.memoryInference.ran = metrics.memoryInference.writes > 0 || metrics.memoryInference.durationMs > 0;
+    metrics.graphExtraction.ran = metrics.graphExtraction.extractedFiles > 0 || metrics.graphExtraction.durationMs > 0;
+    return metrics;
+}
+function buildImproveSkipSummary(events) {
+    const skipReasons = {};
+    for (const event of events) {
+        const reason = typeof event.metadata?.reason === "string" && event.metadata.reason.trim() ? event.metadata.reason : "unknown";
+        skipReasons[reason] = (skipReasons[reason] ?? 0) + 1;
+    }
+    return { skipped: events.length, skipReasons };
+}
+function probeStateDbRoundTrip(stateDbPath) {
+    const before = readEvents({}, { dbPath: stateDbPath }).nextOffset;
+    const started = Date.now();
+    appendEvent({ eventType: HEALTH_PROBE_EVENT, ref: "health:probe", metadata: { source: "akm health" } }, { dbPath: stateDbPath });
+    const after = readEvents({ sinceOffset: before, type: HEALTH_PROBE_EVENT, ref: "health:probe" }, { dbPath: stateDbPath });
+    const durationMs = Date.now() - started;
+    if (after.events.length === 0 || after.nextOffset <= before) {
+        return { ok: false, durationMs, error: "probe event was not readable after append" };
+    }
+    return { ok: true, durationMs };
+}
+function runAgentProbe() {
+    const config = loadConfig();
+    if (!config.agent) {
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "No agent config present.",
+        };
+    }
+    let profile;
+    try {
+        profile = requireAgentProfile(config.agent);
+    }
+    catch (error) {
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: "warn",
+            confidence: "high",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (profile.sdkMode === true) {
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: profile.model ? "pass" : "warn",
+            confidence: "high",
+            message: profile.model
+                ? `SDK mode profile "${profile.name}" is configured.`
+                : `SDK mode profile "${profile.name}" has no explicit model.`,
+            evidence: { profile: profile.name, sdkMode: true, model: profile.model ?? null },
+        };
+    }
+    const detections = detectAgentCliProfiles(config.agent);
+    const detection = detections.find((entry) => entry.name === profile.name);
+    if (!detection?.available) {
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: "fail",
+            confidence: "high",
+            message: `Default agent profile "${profile.name}" is not available on PATH.`,
+            evidence: { profile: profile.name, bin: profile.bin },
+        };
+    }
+    const version = spawnSync(profile.bin, ["--version"], { encoding: "utf8", timeout: 5_000 });
+    if ((version.status ?? 1) !== 0) {
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: "warn",
+            confidence: "medium",
+            message: `Agent binary "${profile.bin}" was found but \`--version\` failed.`,
+            evidence: {
+                profile: profile.name,
+                bin: profile.bin,
+                exitCode: version.status ?? null,
+                stderr: (version.stderr ?? "").trim(),
+            },
+        };
+    }
+    return {
+        name: "agent-profile",
+        kind: "deterministic",
+        status: "pass",
+        confidence: "high",
+        message: `Agent profile "${profile.name}" is available.`,
+        evidence: { profile: profile.name, bin: profile.bin, version: (version.stdout ?? "").trim() },
+    };
+}
+export function akmHealth(options = {}) {
+    const since = parseHealthSince(options.since);
+    const stateDbPath = getStateDbPathInDataDir();
+    const hardChecks = [];
+    const advisories = [];
+    const getExecutionLogCandidatesFn = options.getExecutionLogCandidatesFn ?? getExecutionLogCandidates;
+    let db;
+    try {
+        db = openStateDatabase(stateDbPath);
+    }
+    catch (error) {
+        throw new ConfigError(`Unable to open state.db: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
+    }
+    try {
+        const tables = db
+            .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('events', 'task_history', 'proposals', 'schema_migrations') ORDER BY name")
+            .all();
+        const tableNames = tables.map((row) => row.name).sort();
+        const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
+        const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
+        hardChecks.push({
+            name: "state-db-schema",
+            kind: "deterministic",
+            status: missingTables.length === 0 ? "pass" : "fail",
+            confidence: "high",
+            message: missingTables.length === 0
+                ? "state.db opened and required tables are present."
+                : `state.db is missing required tables: ${missingTables.join(", ")}`,
+            evidence: { path: stateDbPath, tables: tableNames },
+        });
+        const probe = probeStateDbRoundTrip(stateDbPath);
+        hardChecks.push({
+            name: "state-db-round-trip",
+            kind: "deterministic",
+            status: probe.ok ? "pass" : "fail",
+            confidence: "high",
+            message: probe.ok ? "state.db append/read round-trip succeeded." : `state.db round-trip failed: ${probe.error}`,
+            evidence: { path: stateDbPath, durationMs: probe.durationMs },
+        });
+        const taskRows = queryTaskHistory(db, { since });
+        const taskRowsWithLogs = taskRows.filter((row) => row.log_path !== null);
+        const existingLogRows = taskRowsWithLogs.filter((row) => row.log_path && fs.existsSync(row.log_path));
+        const failedTaskRows = taskRows.filter((row) => row.status === "failed");
+        const activeRows = taskRows.filter((row) => row.status === "active");
+        const stuckActiveRuns = activeRows.filter((row) => Date.now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
+        const promptRows = taskRows.filter((row) => row.target_kind === "prompt");
+        const promptFailures = promptRows.filter((row) => {
+            const detail = parseTaskMetadata(row).detail;
+            return typeof detail?.reason === "string" && detail.reason.length > 0;
+        });
+        const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;
+        const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
+        const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
+        hardChecks.push({
+            name: "task-history-read",
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `Read ${taskRows.length} task-history row(s) since ${since}.`,
+            evidence: { rows: taskRows.length, since },
+        });
+        hardChecks.push({
+            name: "task-log-backing",
+            kind: "deterministic",
+            status: logBackingRate === 1 ? "pass" : "fail",
+            confidence: "high",
+            message: logBackingRate === 1
+                ? "Every task_history log_path resolved on disk."
+                : `${taskRowsWithLogs.length - existingLogRows.length} task log(s) referenced in task_history are missing.`,
+            evidence: { totalWithLogs: taskRowsWithLogs.length, existingLogs: existingLogRows.length },
+        });
+        hardChecks.push({
+            name: "active-runs",
+            kind: "deterministic",
+            status: stuckActiveRuns === 0 ? "pass" : "warn",
+            confidence: "high",
+            message: stuckActiveRuns === 0
+                ? "No active task runs exceeded the stale threshold."
+                : `${stuckActiveRuns} active task run(s) are older than ${Math.round(ACTIVE_RUN_WARN_MS / 60000)} minutes.`,
+            evidence: { stuckActiveRuns },
+        });
+        hardChecks.push(runAgentProbe());
+        const semanticStatus = readSemanticStatus();
+        advisories.push({
+            name: "semantic-search-runtime",
+            kind: "deterministic",
+            status: !semanticStatus ||
+                semanticStatus.status === "pending" ||
+                semanticStatus.status === "ready-js" ||
+                semanticStatus.status === "ready-vec"
+                ? "pass"
+                : "warn",
+            confidence: "medium",
+            message: semanticStatus
+                ? `Semantic search status: ${semanticStatus.status}`
+                : "No semantic-search runtime status recorded yet.",
+            evidence: semanticStatus ? { ...semanticStatus } : undefined,
+        });
+        const improveInvoked = readEvents({ since, type: "improve_invoked" }, { dbPath: stateDbPath }).events.length;
+        const improveCompletedEvents = readEvents({ since, type: IMPROVE_COMPLETED_EVENT }, { dbPath: stateDbPath }).events;
+        const improveSkippedEvents = readEvents({ since, type: "improve_skipped" }, { dbPath: stateDbPath }).events;
+        const improveSummary = summarizeImproveCompleted(improveCompletedEvents);
+        improveSummary.invoked = improveInvoked;
+        const skipSummary = buildImproveSkipSummary(improveSkippedEvents);
+        improveSummary.skipped = skipSummary.skipped;
+        improveSummary.skipReasons = skipSummary.skipReasons;
+        let sessionLogEntries = [];
+        try {
+            const sinceDays = Math.max(0, Math.ceil((Date.now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
+            sessionLogEntries = getExecutionLogCandidatesFn(sinceDays).map((entry) => ({
+                topic: entry.topic,
+                frequency: entry.frequency,
+                source: entry.source,
+                isFailurePattern: entry.isFailurePattern,
+            }));
+        }
+        catch {
+            sessionLogEntries = [];
+        }
+        advisories.push({
+            name: "session-log-failures",
+            kind: "heuristic",
+            status: sessionLogEntries.length === 0 ? "pass" : "warn",
+            confidence: sessionLogEntries.length === 0 ? "low" : "medium",
+            message: sessionLogEntries.length === 0
+                ? "No repeated external session-log failure patterns were detected."
+                : `${sessionLogEntries.length} repeated external session-log failure pattern(s) detected.`,
+            evidence: { candidates: sessionLogEntries.slice(0, 5) },
+        });
+        const metrics = {
+            taskFailRate: roundRate(taskFailRate),
+            agentFailureRate: roundRate(agentFailureRate),
+            stuckActiveRuns,
+            logBackingRate: roundRate(logBackingRate),
+            probeRoundTripMs: probe.durationMs,
+        };
+        const hardFailure = hardChecks.some((check) => check.status === "fail");
+        const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");
+        const status = hardFailure ? "fail" : deterministicWarnings ? "warn" : "pass";
+        return {
+            schemaVersion: 1,
+            ok: !hardFailure,
+            status,
+            since,
+            hardChecks,
+            advisories,
+            metrics,
+            improve: improveSummary,
+            sessionLogAdvisories: sessionLogEntries,
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/commands/help/help-accept.md

@@ -0,0 +1,9 @@
+Usage:
+  akm accept <id>
+
+Description:
+  Accept a proposal and promote it into the stash.
+
+Examples:
+  akm accept proposal_123
+  akm accept proposal_123 --target team-stash

package/dist/commands/help/help-improve.md

@@ -0,0 +1,53 @@
+Usage:
+  akm improve
+  akm improve <type>
+  akm improve <ref>
+
+Description:
+  Analyze existing AKM assets and generate improvement proposals.
+
+Modes:
+  akm improve
+      Improve all eligible assets in the current scope.
+
+  akm improve <type>
+      Improve all assets of a given type.
+      Example: akm improve memory
+
+  akm improve <ref>
+      Improve one specific asset.
+      Example: akm improve workflow:release-checklist
+
+What it does:
+  - reviews feedback and recent history
+  - proposes edits to existing assets
+  - distills lessons where useful
+  - promotes durable skill lessons into skill reference-doc proposals when justified
+  - cleans and consolidates memories
+  - writes results to the proposal queue
+
+Options:
+  --task <text>        Add extra guidance for this improvement pass
+  --dry-run            Show planned actions without generating proposals
+  --target <source>    Override the write target for accepted proposals
+  --auto-accept safe   Automatically accept low-risk proposals
+  --ignore-cooldown    Disable reflect/distill/consolidate cooldown checks for this run
+  --reflect-cooldown-days <n>
+                        Override reflect cooldown with a non-negative integer
+  --distill-cooldown-days <n>
+                        Override distill cooldown with a non-negative integer
+  --consolidate-cooldown-days <n>
+                        Override consolidate cooldown with a non-negative integer
+  --consolidate-recovery <mode>
+                        Recovery mode for stale consolidate journals: abort (default) or clean
+  --require-feedback-signal
+                        Only process refs with recent feedback signal events
+  --min-retrieval-count <n>
+                        Retrieval fallback threshold when no recent feedback exists (default: 5)
+
+Examples:
+  akm improve
+  akm improve memory
+  akm improve skill
+  akm improve skill:code-review
+  akm improve workflow:incident-response --task "reduce duplication"

package/dist/commands/help/help-proposals.md

@@ -0,0 +1,15 @@
+Usage:
+  akm proposals
+
+Description:
+  List proposal queue entries.
+
+Options:
+  --status <status>    Filter by pending, accepted, or rejected
+  --type <type>        Filter by asset type
+  --ref <ref>          Filter by exact asset ref
+
+Examples:
+  akm proposals
+  akm proposals --status pending
+  akm proposals --type skill