akm-cli 0.9.0-beta.3 → 0.9.0-beta.31

package/dist/cli.js

@@ -320,10 +320,14 @@ const healthCommand = defineCommand({
             // window-compare read for the trend deltas (defaults to 24h,
             // overridable via --compare).
             if (mode.format === "html") {
-                const compare = args.compare ?? windowCompareRaw ?? "24h";
-                const result = akmHealth({ since: args.since, groupBy: "run" });
+                // Default the compare window to the report's own `--since` window so the
+                // trend deltas are like-for-like (e.g. last 7d vs the prior 7d). A fixed
+                // 24h default made a `--since 7d` report compare its 7-day totals against
+                // a 24-hour prior window, producing meaningless deltas.
+                const compare = args.compare ?? windowCompareRaw ?? args.since ?? "24h";
+                const result = akmHealth({ since: args.since, groupBy: "run", windowCompare: compare });
                 resultStatus = result.status;
-                const deltas = akmHealth({ since: args.since, windowCompare: compare }).deltas;
+                const deltas = result.deltas;
                 const { buildHealthHtmlReplacements } = await import("./commands/health/html-report.js");
                 const { listPendingProposals } = await import("./commands/proposal/proposal.js");
                 const replacements = buildHealthHtmlReplacements(result, {
@@ -536,6 +540,13 @@ const EXIT_HEALTH_WARN = EXIT_CODES.HEALTH_WARN;
 // The wrapper sets `AKM_NODE_ENTRY=1` to opt into the startup block. The test
 // harness never sets it, so importing cli.ts under Bun stays inert as before.
 if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
+    // Mark that this process is the real akm CLI: its `process.argv[1]` is the
+    // akm entrypoint, so the background auto-reindex may safely re-invoke it as a
+    // detached child. Hosts that merely import this module (the in-process test
+    // harness, library embeddings) never reach this block, so they fall back to
+    // an inline reindex instead of spawning the wrong program. See
+    // `ensureIndex` in src/indexer/ensure-index.ts.
+    process.env.AKM_CLI_ENTRY = "1";
     // citty reads process.argv directly and does not accept a custom argv array,
     // so we must replace process.argv with the normalized version before runMain.
     process.argv = normalizeShowArgv(process.argv);

package/dist/commands/agent/contribute-cli.js

@@ -122,23 +122,36 @@ export const lintCommand = defineCommand({
         description: "Scan stash .md files for structural issues (unquoted colons, missing updated field, orphaned stubs, placeholder stubs, missing name/type, stale paths). Use --fix to auto-fix Tier 1 issues. Exits 0 on success regardless of findings; use --fail-on-flagged for CI fail-on-finding behavior.",
     },
     args: {
-        fix: { type: "boolean", description: "Apply auto-fixes in place", default: false },
+        fix: {
+            type: "boolean",
+            alias: "auto-fix",
+            description: "Apply auto-fixes in place (alias: --auto-fix)",
+            default: false,
+        },
         dir: { type: "string", description: "Override stash root directory (default: from config)" },
         "fail-on-flagged": {
             type: "boolean",
             description: "Exit non-zero when summary.flagged > 0 (CI-friendly). Default: exit 0 regardless of findings.",
             default: false,
         },
+        type: {
+            type: "string",
+            description: "Only lint assets of this type (e.g. workflows, tasks, memories)",
+            default: undefined,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
             const result = akmLint({
                 fix: args.fix ?? false,
                 dir: getStringArg(args, "dir"),
+                typeFilter: getStringArg(args, "type"),
             });
             output("lint", result);
-            if (args["fail-on-flagged"] && result.summary.flagged > 0)
-                process.exit(EXIT_GENERAL);
+            if (args["fail-on-flagged"] && result.summary.flagged > 0) {
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
         });
     },
 });

package/dist/commands/feedback-cli.js

@@ -11,10 +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 { 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_]*$/;
@@ -203,11 +202,21 @@ export const feedbackCommand = defineCommand({
                 ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
             };
             const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
-            // Auto-index when stale so the index is current before recording feedback.
-            const sources = resolveSourceEntries();
-            if (sources.length > 0) {
-                await ensureIndex(sources[0].path);
+            // 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 {

package/dist/commands/graph/graph.js

@@ -12,6 +12,7 @@ import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashR
 import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
+import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
 import { lookup } from "../../indexer/indexer.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
@@ -375,85 +376,88 @@ export async function akmGraphUpdate(options) {
         }
     }
     const scoped = Array.isArray(options.refs) && options.refs.length > 0;
-    let candidatePaths;
-    if (scoped && options.refs) {
-        // Resolve each ref to an absolute file path via the index DB.
-        const dbPath = getDbPath();
-        let db;
-        const resolvedPaths = new Set();
-        try {
-            db = openDatabase(dbPath);
-            for (const ref of options.refs) {
-                const trimmed = ref.trim();
-                if (!trimmed)
-                    continue;
-                const entryId = findEntryIdByRef(db, trimmed);
-                if (entryId === undefined) {
-                    warn(`[graph] ref not found in index, skipping: ${trimmed}`);
-                    continue;
+    return withIndexWriterLease({ purpose: "graph-update" }, async () => {
+        let candidatePaths;
+        if (scoped && options.refs) {
+            // Resolve each ref to an absolute file path while the writer lease is held
+            // so the scoped graph write sees the same index snapshot it resolved from.
+            const dbPath = getDbPath();
+            let db;
+            const resolvedPaths = new Set();
+            try {
+                db = openDatabase(dbPath);
+                for (const ref of options.refs) {
+                    const trimmed = ref.trim();
+                    if (!trimmed)
+                        continue;
+                    const entryId = findEntryIdByRef(db, trimmed);
+                    if (entryId === undefined) {
+                        warn(`[graph] ref not found in index, skipping: ${trimmed}`);
+                        continue;
+                    }
+                    const row = getEntryById(db, entryId);
+                    if (!row?.filePath) {
+                        warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
+                        continue;
+                    }
+                    resolvedPaths.add(row.filePath);
                 }
-                const row = getEntryById(db, entryId);
-                if (!row?.filePath) {
-                    warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
-                    continue;
-                }
-                resolvedPaths.add(row.filePath);
             }
+            finally {
+                if (db)
+                    closeDatabase(db);
+            }
+            if (resolvedPaths.size === 0) {
+                warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
+                return {
+                    shape: "graph-update",
+                    ok: true,
+                    filesExtracted: 0,
+                    entitiesUpserted: 0,
+                    relationsUpserted: 0,
+                    durationMs: 0,
+                    scoped: true,
+                };
+            }
+            candidatePaths = resolvedPaths;
         }
-        finally {
-            if (db)
-                closeDatabase(db);
-        }
-        if (resolvedPaths.size === 0) {
-            warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
+        const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
+        const passOptions = candidatePaths ? { candidatePaths } : {};
+        let db;
+        const startMs = Date.now();
+        try {
+            db = openDatabase(getDbPath());
+            const onProgress = (event) => {
+                if (!event.currentPath)
+                    return;
+                const file = path.basename(event.currentPath);
+                warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
+            };
+            const result = await extractionFn({
+                config,
+                sources,
+                signal: undefined,
+                db,
+                reEnrich: false,
+                onProgress,
+                options: passOptions,
+            });
+            const durationMs = Date.now() - startMs;
             return {
                 shape: "graph-update",
                 ok: true,
-                filesExtracted: 0,
-                entitiesUpserted: 0,
-                relationsUpserted: 0,
-                durationMs: 0,
-                scoped: true,
+                filesExtracted: result.quality.extractedFiles,
+                entitiesUpserted: result.quality.entityCount,
+                relationsUpserted: result.quality.relationCount,
+                durationMs,
+                scoped,
             };
         }
-        candidatePaths = resolvedPaths;
-    }
-    const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
-    const passOptions = candidatePaths ? { candidatePaths } : {};
-    let db;
-    const startMs = Date.now();
-    try {
-        db = openDatabase(getDbPath());
-        const onProgress = (event) => {
-            if (!event.currentPath)
-                return;
-            const file = path.basename(event.currentPath);
-            warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
-        };
-        const result = await extractionFn({
-            config,
-            sources,
-            signal: undefined,
-            db,
-            reEnrich: false,
-            onProgress,
-            options: passOptions,
-        });
-        const durationMs = Date.now() - startMs;
-        return {
-            shape: "graph-update",
-            ok: true,
-            filesExtracted: result.quality.extractedFiles,
-            entitiesUpserted: result.quality.entityCount,
-            relationsUpserted: result.quality.relationCount,
-            durationMs,
-            scoped,
-        };
-    }
-    finally {
-        if (db)
-            closeDatabase(db);
-    }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
+    });
 }
 async function resolveGraphTarget(ref, source) {
     const parsedRef = parseAssetRef(ref);

package/dist/commands/health/checks.js

@@ -257,6 +257,54 @@ export const HEALTH_CHECKS = [
             };
         },
     },
+    {
+        // #603: pool-saturation advisory. The raw `sessionsScanned` count fired on
+        // normal cadence changes (the Jun 12 false alarm). Instead track the ratio
+        // of NEW (unseen) sessions to the total session pool extract evaluated in
+        // the window: a low ratio is the *expected* steady state, only a near-zero
+        // ratio signals a possible discovery/dedup bug.
+        //
+        // unseen ≈ `sessionsScanned` (extract only processes new sessions; already-
+        // seen ones are deduped into `sessionsSkipped`). total = scanned + skipped.
+        // This is a heuristic approximation — `sessionsSkipped` also folds in
+        // too-short skips — so the check is informational and never gates status.
+        name: "pool-saturation",
+        channel: "advisory",
+        run: (ctx) => {
+            const sx = ctx.sessionExtraction;
+            const total = sx.sessionsScanned + sx.sessionsSkipped;
+            const unseen = sx.sessionsScanned;
+            const ratio = total > 0 ? unseen / total : null;
+            const pct = ratio === null ? null : Math.round(ratio * 1000) / 10;
+            let status = "pass";
+            let confidence = "low";
+            let message;
+            if (!sx.ran || ratio === null) {
+                message = "Pool saturation: no extract activity in the window — no signal.";
+            }
+            else if (ratio < 0.02) {
+                status = "warn";
+                confidence = "medium";
+                message = `Session pool near-exhausted: only ${pct}% of the ${total}-session pool was new (<2%). Possible discovery/dedup bug — verify extract is still finding new sessions.`;
+            }
+            else if (ratio < 0.1) {
+                confidence = "medium";
+                message = `Session pool saturation: ${pct}% of ${total} sessions were new (<10%, steady-state expected — informational).`;
+            }
+            else {
+                confidence = "medium";
+                message = `Session pool healthy: ${pct}% of ${total} sessions were new.`;
+            }
+            return {
+                name: "pool-saturation",
+                kind: "heuristic",
+                status,
+                confidence,
+                message,
+                evidence: { totalSessions: total, unseenSessions: unseen, saturationRatio: ratio },
+            };
+        },
+    },
     {
         name: "auto-accept-validation",
         channel: "advisory",