akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

package/dist/assets/wiki/ingest-workflow-template.md

@@ -6,20 +6,27 @@ Schema: {{SCHEMA_PATH}}
 Follow these steps. akm commands handle the invariants; use your native
 Read/Write/Edit tools for page edits.
 
+This workflow is for ingesting sources that are ALREADY present under
+`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
+empty and the caller explicitly asked for interactive ingest.
+
 1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
    kinds, contradiction policy, and any wiki-specific conventions. Do not
    skip this step even on familiar wikis — the schema may have changed.
 
-2. **File the source under `raw/`.**
+2. **Discover the pending raw queue.**
    ```sh
-   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   akm wiki lint {{WIKI_NAME}}
    ```
-   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
+   not yet cited by any authored page. Treat each `uncited-raw` finding as a
+   pending ingest item. If there are no `uncited-raw` findings, exit cleanly
+   after a final `akm index` + `akm wiki lint {{WIKI_NAME}}` verification.
 
-3. **Find related existing pages.**
+3. **For each pending raw file, read the source and find related pages.**
+   Open the raw file directly from `{{WIKI_DIR}}/raw/`, then search:
    ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
    ```
    Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
    `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
@@ -39,8 +46,8 @@ Read/Write/Edit tools for page edits.
 6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
    page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
 
-7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
+7. **Append to `log.md`.** One entry per ingested raw source: date, raw slug,
+   one-line summary, refs to created/edited pages. Newest at the top.
 
 8. **Regenerate the index + verify.**
    ```sh
@@ -50,5 +57,5 @@ Read/Write/Edit tools for page edits.
    Resolve any lint findings before calling the ingest done.
 
 That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
+the invariants (raw immutability, ref validation, index regeneration,
+structural lint).

package/dist/cli/shared.js

@@ -15,6 +15,7 @@ import { getOutputMode } from "../output/context.js";
 import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { hasSubcommand } from "./parse-args.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -111,6 +112,33 @@ export function defineJsonCommand(def) {
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
+ * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * DERIVED from that map's keys (so the set can never silently desync from the
+ * registered subcommands), and a default body that fires ONLY for the bare
+ * group invocation — citty still runs the group body after dispatching a
+ * subcommand, so the shared guard short-circuits when `args._[0]` names a
+ * registered subcommand.
+ *
+ * The `defaultRun` body is wrapped in `runWithJsonErrors`, so it emits a
+ * byte-identical JSON error envelope on throw — exactly the per-site
+ * `run() { return runWithJsonErrors(() => { if (hasSubcommand(...)) return; … }); }`
+ * boilerplate this replaces.
+ */
+export function defineGroupCommand(def) {
+    const subcommandSet = new Set(Object.keys(def.subCommands));
+    return defineCommand({
+        meta: def.meta,
+        ...(def.args ? { args: def.args } : {}),
+        subCommands: def.subCommands,
+        run: (context) => runWithJsonErrors(() => {
+            if (hasSubcommand(context.args, subcommandSet))
+                return;
+            return def.defaultRun(context);
+        }),
+    });
+}
 /**
  * Render a command result according to the active output mode
  * (json/jsonl/yaml/text/md/html). When `--output <path>` is set, the rendered

package/dist/cli.js

@@ -77,7 +77,7 @@ import { registryCommand } from "./commands/registry-cli.js";
 import { addCommand } from "./commands/sources/add-cli.js";
 import { renderMigrationHelp } from "./commands/sources/migration-help.js";
 import { cloneCommand, historyCommand, listCommand, removeCommand, syncCommand, updateCommand, upgradeCommand, } from "./commands/sources/sources-cli.js";
-import { dbCommand, importKnowledgeCommand, indexCommand, infoCommand, initCommand, } from "./commands/sources/stash-cli.js";
+import { importKnowledgeCommand, indexCommand, infoCommand, initCommand } from "./commands/sources/stash-cli.js";
 import { tasksCommand } from "./commands/tasks/tasks-cli.js";
 import { wikiCommand } from "./commands/wiki-cli.js";
 import { workflowCommand } from "./commands/workflow-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, {
@@ -482,7 +486,6 @@ export const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
-        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,
@@ -536,6 +539,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/agent-dispatch.js

@@ -18,7 +18,7 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { requireAgentProfile } from "../../integrations/agent/config.js";
 import { runAgent } from "../../integrations/agent/spawn.js";
-import { runAgentSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
 /**
  * Fill `{{0}}`, `{{1}}`, ... placeholders in `template` with the
  * corresponding entries in `args`. Any placeholder index that exceeds the
@@ -93,7 +93,7 @@ export async function akmAgentDispatch(options) {
         ...(dispatchRequest !== undefined ? { dispatch: dispatchRequest } : {}),
     };
     const result = profile.sdkMode
-        ? await runAgentSdk(profile, prompt ?? "", runOptions, options.llmConfig)
+        ? await runOpencodeSdk(profile, prompt ?? "", runOptions, options.llmConfig)
         : await runAgent(profile, prompt, runOptions);
     return {
         schemaVersion: 1,

package/dist/commands/agent/agent-support.js

@@ -1,13 +1,6 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Shared helpers for agent-based commands (reflect, propose, etc.).
- *
- * Consolidates utility functions that were duplicated byte-for-byte across
- * `reflect.ts` and `propose.ts`. Any command that shells out to an agent
- * profile can import from here rather than copy-pasting.
- */
 import { loadConfig } from "../../core/config/config.js";
 import { requireAgentProfile, } from "../../integrations/agent/index.js";
 // ── Config helpers ───────────────────────────────────────────────────────────

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

@@ -29,7 +29,7 @@ import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getHyphenatedArg } from "../../output/context.js";
-import { akmLint } from "../lint.js";
+import { akmLint } from "../lint/index.js";
 import { akmPropose } from "../proposal/propose.js";
 import { akmAgentDispatch } from "./agent-dispatch.js";
 const EXIT_GENERAL = EXIT_CODES.GENERAL;
@@ -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/env/env-cli.js

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
 import { isWithin, writeFileAtomic } from "../../core/common.js";
@@ -499,31 +499,23 @@ const envUnsetCommand = defineCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const envSubCommands = {
-    list: envListCommand,
-    path: envPathCommand,
-    export: envExportCommand,
-    run: envRunCommand,
-    create: envCreateCommand,
-    set: envSetCommand,
-    unset: envUnsetCommand,
-    remove: envRemoveCommand,
-};
-const ENV_SUBCOMMAND_SET = new Set(Object.keys(envSubCommands));
-export const envCommand = defineCommand({
+export const envCommand = defineGroupCommand({
     meta: {
         name: "env",
         description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
-    subCommands: envSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, ENV_SUBCOMMAND_SET))
-                return;
-            const { listKeys } = await import("./env.js");
-            output("env-list", { envs: listEnvsRecursive(listKeys) });
-        });
+    subCommands: {
+        list: envListCommand,
+        path: envPathCommand,
+        export: envExportCommand,
+        run: envRunCommand,
+        create: envCreateCommand,
+        set: envSetCommand,
+        unset: envUnsetCommand,
+        remove: envRemoveCommand,
+    },
+    async defaultRun() {
+        const { listKeys } = await import("./env.js");
+        output("env-list", { envs: listEnvsRecursive(listKeys) });
     },
 });

package/dist/commands/env/secret-cli.js

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
 import { loadConfig } from "../../core/config/config.js";
 import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
@@ -233,27 +233,19 @@ const secretRemoveCommand = defineCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const secretSubCommands = {
-    list: secretListCommand,
-    path: secretPathCommand,
-    run: secretRunCommand,
-    set: secretSetCommand,
-    remove: secretRemoveCommand,
-};
-const SECRET_SUBCOMMAND_SET = new Set(Object.keys(secretSubCommands));
-export const secretCommand = defineCommand({
+export const secretCommand = defineGroupCommand({
     meta: {
         name: "secret",
         description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
     },
-    subCommands: secretSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
-                return;
-            output("secret-list", { secrets: listSecretsRecursive() });
-        });
+    subCommands: {
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
+    },
+    defaultRun() {
+        output("secret-list", { secrets: listSecretsRecursive() });
     },
 });

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-cli.js

@@ -9,12 +9,9 @@
  * same JSON envelope (stdout/stderr/exit-code) as the inline `runWithJsonErrors`
  * form it replaces.
  */
-import { defineCommand } from "citty";
-import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./graph.js";
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
 const graphSubCommands = {
     summary: defineJsonCommand({
         meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
@@ -118,15 +115,10 @@ const graphSubCommands = {
         },
     }),
 };
-const GRAPH_SUBCOMMAND_SET = new Set(Object.keys(graphSubCommands));
-export const graphCommand = defineCommand({
+export const graphCommand = defineGroupCommand({
     meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
     subCommands: graphSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            if (hasSubcommand(args, GRAPH_SUBCOMMAND_SET))
-                return;
-            output("graph-summary", akmGraphSummary());
-        });
+    defaultRun() {
+        output("graph-summary", akmGraphSummary());
     },
 });

package/dist/commands/graph/graph.js

@@ -8,10 +8,11 @@ import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openDatabase, openExistingDatabase, } from "../../indexer/db/db.js";
+import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openExistingDatabase, openIndexDatabase, } from "../../indexer/db/db.js";
 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 = openIndexDatabase(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 = openIndexDatabase(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",