akm-cli 0.9.0-beta.52 → 0.9.0-beta.53

package/dist/assets/hints/cli-hints-full.md

@@ -58,7 +58,7 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | knowledge | `content` (with view modes: `full`, `toc`, `frontmatter`, `section`, `lines`) |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
-| env | `keys`, `comments` (key names + comments only — values never returned) |
+| env | `keys` (key names only — values and comment text never returned) |
 | secret | `name` only (the whole file is the value — never returned) |
 | wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
 
@@ -122,15 +122,16 @@ search results. No `--llm` anywhere — akm never reasons about page content.
 ## Env files
 
 A group of related CONFIGURATION for an app/service in one `.env` file at
-`<stashDir>/env/<name>.env`, sourced/injected wholesale. Key names + comments
-are discoverable; values stay on disk and never reach stdout or the index. akm
-does not edit entries — you edit the file with your own editor and akm loads it.
+`<stashDir>/env/<name>.env`, sourced/injected wholesale. Key names are
+discoverable; values and comment text stay on disk and never reach stdout or
+the index (comments can contain commented-out credentials). akm does not edit
+entries — you edit the file with your own editor and akm loads it.
 
 ```sh
 akm env create prod                           # Create an empty env file
 akm env create prod --from-file ./.env        # Ingest an existing .env
 akm env list                                  # List all env files across stashes with key names
-akm show env:prod                             # Inspect key names + comments (never values)
+akm show env:prod                             # Inspect key names (never values or comments)
 akm env run env:prod -- ./deploy.sh           # Run a command with the whole .env injected (the safe path)
 akm env run env:prod -- $SHELL                # Open an interactive shell with values injected
 akm env export env:prod --out ./env.sh        # Write a sourceable script to a file (mode 0600)

package/dist/cli.js

@@ -544,13 +544,6 @@ 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/env/env-cli.js

@@ -10,8 +10,9 @@
  * copy.
  *
  * `akm env` manages whole `.env` files under each stash's env/ directory.
- * Values are NEVER written to stdout or structured output — only key NAMES and
- * start-of-line comments are surfaced. akm does not manage individual entries;
+ * Values and comment text are NEVER written to stdout or structured output —
+ * only key NAMES are surfaced (comments routinely contain commented-out
+ * credentials). akm does not manage individual entries;
  * you edit the `.env` file yourself and akm loads it. Replaced the deprecated
  * `vault` type (removed in 0.9.0).
  */

package/dist/commands/env/env.js

@@ -18,10 +18,13 @@
  * round-trip through `dotenv`; the shell-load safety guarantee still lives on
  * the READ path (see `buildShellExportScript` + `akm env export`).
  *
- * Invariant: env values must never be written to stdout, returned through the
- * indexer, the `akm show` renderer, or any structured output channel. Key
- * NAMES and start-of-line comments ARE surfaced by design (discoverability) —
- * only values are secret. The supported value-load paths are:
+ * Invariant: nothing from an env file except key NAMES may be written to
+ * stdout, returned through the indexer, the `akm show` renderer, or any
+ * structured output channel. Key NAMES are surfaced for discoverability;
+ * comment text is NOT — real .env files routinely carry commented-out
+ * `KEY=value` lines and free-text notes containing live credentials, so
+ * comments are treated exactly like values. The supported value-load paths
+ * are:
  *
  *   - `akm env run <ref> -- <command>` — values injected into the child
  *     process env (never via a shell), see `injectIntoEnv` / `loadEnv`. This is
@@ -71,75 +74,19 @@ function scanKeys(text) {
     return keys;
 }
 /**
- * Scan lines and return start-of-line `#` comments (with the leading `#` and
- * any leading whitespace stripped). Inline/trailing `#` after an assignment is
- * never extracted.
- */
-function scanComments(text) {
-    const comments = [];
-    for (const line of text.split(/\r?\n/)) {
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith("#")) {
-            comments.push(trimmed.slice(1).trimStart());
-        }
-    }
-    return comments;
-}
-/**
- * Read and return ONLY non-secret metadata (keys + start-of-line comments).
+ * Read and return ONLY non-secret metadata: key names.
  *
  * The function reads the whole file into memory (same as any dotenv parser)
- * but deliberately does not parse values — the LHS-only regex scanners above
- * ensure no value content is retained or returned. The guarantee is that
- * values never leave this function.
+ * but deliberately does not parse values — the LHS-only regex scanner above
+ * ensures no value content is retained or returned. Comment text is never
+ * returned either: comments routinely contain commented-out `KEY=value`
+ * credentials and free-text secrets, so they never leave this function.
  */
 export function listKeys(envPath) {
     if (!fs.existsSync(envPath))
-        return { keys: [], comments: [] };
-    const text = fs.readFileSync(envPath, "utf8");
-    return { keys: scanKeys(text), comments: scanComments(text) };
-}
-/**
- * Return structured `entries` pairing each key with the nearest preceding
- * comment line (if any). This is an easier-to-consume shape than the parallel
- * `keys[]` + `comments[]` of `listKeys` (QA #35).
- *
- * Values are never included — the same privacy guarantee as `listKeys`.
- */
-export function listEntries(envPath) {
-    if (!fs.existsSync(envPath))
-        return [];
+        return { keys: [] };
     const text = fs.readFileSync(envPath, "utf8");
-    const lines = text.split(/\r?\n/);
-    const seen = new Set();
-    const entries = [];
-    let pendingComment;
-    for (const line of lines) {
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith("#")) {
-            // Capture the most recent comment before a key
-            pendingComment = trimmed.slice(1).trimStart() || undefined;
-            continue;
-        }
-        const m = line.match(ASSIGN_RE);
-        if (m) {
-            const key = m[1];
-            if (!seen.has(key)) {
-                seen.add(key);
-                const entry = { key };
-                if (pendingComment)
-                    entry.comment = pendingComment;
-                entries.push(entry);
-            }
-            pendingComment = undefined;
-        }
-        else {
-            // Any non-comment, non-assignment line (including blank lines)
-            // breaks "nearest preceding comment line" association.
-            pendingComment = undefined;
-        }
-    }
-    return entries;
+    return { keys: scanKeys(text) };
 }
 /**
  * Read all KEY=value pairs from an env file. Intended for programmatic callers

package/dist/commands/health/checks.js

@@ -191,21 +191,34 @@ export const HEALTH_CHECKS = [
     {
         name: "semantic-search-runtime",
         channel: "advisory",
-        run: (ctx) => ({
-            name: "semantic-search-runtime",
-            kind: "deterministic",
-            status: !ctx.semanticStatus ||
-                ctx.semanticStatus.status === "pending" ||
-                ctx.semanticStatus.status === "ready-js" ||
-                ctx.semanticStatus.status === "ready-vec"
-                ? "pass"
-                : "warn",
-            confidence: "medium",
-            message: ctx.semanticStatus
-                ? `Semantic search status: ${ctx.semanticStatus.status}`
-                : "No semantic-search runtime status recorded yet.",
-            evidence: ctx.semanticStatus ? { ...ctx.semanticStatus } : undefined,
-        }),
+        run: (ctx) => {
+            const blocked = ctx.semanticStatus?.status === "blocked";
+            // The generic "status: blocked" line is not actionable when the real
+            // problem is a configured remote embedding endpoint that is down while
+            // semanticSearchMode leaves semantic search enabled — every index run
+            // burns time failing against it and searches silently degrade to
+            // keyword-only. Name the endpoint and the two ways out.
+            const remoteReason = ctx.semanticStatus?.reason?.startsWith("remote-") === true;
+            const endpointAdvisory = blocked && remoteReason && ctx.embeddingEndpoint
+                ? `Configured embedding endpoint ${ctx.embeddingEndpoint} is failing ` +
+                    `(${ctx.semanticStatus?.reason}${ctx.semanticStatus?.message ? `: ${ctx.semanticStatus.message}` : ""}) ` +
+                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "auto"}". Searches fall back to keyword-only. ` +
+                    `Restore the endpoint, or set semanticSearchMode to "off" (or remove embedding.endpoint to use the local model).`
+                : undefined;
+            return {
+                name: "semantic-search-runtime",
+                kind: "deterministic",
+                status: !ctx.semanticStatus || !blocked ? "pass" : "warn",
+                confidence: "medium",
+                message: endpointAdvisory ??
+                    (ctx.semanticStatus
+                        ? `Semantic search status: ${ctx.semanticStatus.status}`
+                        : "No semantic-search runtime status recorded yet."),
+                evidence: ctx.semanticStatus
+                    ? { ...ctx.semanticStatus, ...(ctx.embeddingEndpoint ? { embeddingEndpoint: ctx.embeddingEndpoint } : {}) }
+                    : undefined,
+            };
+        },
     },
     {
         // session-log-failures: demoted to informational — the ERROR_PATTERNS regex

package/dist/commands/health.js

@@ -2,11 +2,12 @@
 // 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/.
 import fs from "node:fs";
+import { loadConfig } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { buildTaskRunId, getLoggedRunIds, openLogsDatabase } from "../core/logs-db.js";
 import { getStateDbPathInDataDir } from "../core/paths.js";
-import { listExistingTableNames, listProposalGateDecisions, listStateProposals, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
+import { getLatestCycleMetrics, listExistingTableNames, listProposalGateDecisions, listStateProposals, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
 import { parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
 import { getExecutionLogCandidates } from "../integrations/session-logs/index.js";
@@ -1411,6 +1412,18 @@ export function akmHealth(options = {}) {
         const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
         const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
         const semanticStatus = readSemanticStatus();
+        // For the embedding-endpoint advisory. Best-effort: an unloadable config
+        // leaves both undefined and the check falls back to its generic message.
+        let semanticSearchMode;
+        let embeddingEndpoint;
+        try {
+            const config = loadConfig();
+            semanticSearchMode = config.semanticSearchMode;
+            embeddingEndpoint = config.embedding?.endpoint;
+        }
+        catch {
+            // fall through with 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;
@@ -1453,6 +1466,58 @@ export function akmHealth(options = {}) {
                     "The 0.10+ rich in-session outcome signal is no longer deferrable. See plan §WS-2.",
             });
         }
+        // R5 collapse/churn detector: surface any collapse_detector_alert events
+        // in the health window, plus the latest cycle row's headline numbers so
+        // the operator can act without opening the DB. `unknown` when the detector
+        // has never produced a cycle row (no consolidate/recombine work yet).
+        try {
+            // Reuse the already-open state.db handle (readEvents supports a
+            // borrowed connection) — no extra open/migrate/close per health call.
+            const collapseAlertEvents = readEvents({ since, type: "collapse_detector_alert" }, { dbPath: stateDbPath, db }).events;
+            const latestCycle = getLatestCycleMetrics(db);
+            const cycleSummary = latestCycle
+                ? `Latest cycle (${latestCycle.ts}, ${latestCycle.pass}): mean canary recall ${latestCycle.mean_recall.toFixed(3)}, ` +
+                    `distinct-content ratio ${latestCycle.distinct_content_ratio.toFixed(3)}, ` +
+                    `${latestCycle.accepted_actions} accepted action(s).`
+                : "";
+            if (collapseAlertEvents.length > 0) {
+                const kinds = [...new Set(collapseAlertEvents.map((e) => String(e.metadata?.kind ?? "unknown")))];
+                const collapseKinds = kinds.filter((k) => k.startsWith("collapse"));
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "warn",
+                    kind: "deterministic",
+                    // Collapse kinds are measured, not inferred; churn/merge-floor
+                    // volume thresholds are still being tuned (design doc §7).
+                    confidence: collapseKinds.length > 0 ? "high" : "medium",
+                    message: `R5 detector fired ${collapseAlertEvents.length} alert(s) in window (kinds: ${kinds.join(", ")}). ` +
+                        `${cycleSummary} See docs/design/improve-collapse-churn-detector-design.md §6.3 runbook queries.`,
+                });
+            }
+            else if (latestCycle) {
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "pass",
+                    kind: "deterministic",
+                    confidence: "high",
+                    message: `No collapse/churn alerts in window. ${cycleSummary}`,
+                });
+            }
+            else {
+                advisories.push({
+                    name: "collapse-churn-detector",
+                    status: "unknown",
+                    kind: "deterministic",
+                    confidence: "high",
+                    message: "No detector cycle rows yet — the collapse/churn detector runs only on improve cycles " +
+                        "where consolidate/recombine did work (synthesis lanes may be idle).",
+                });
+            }
+        }
+        catch {
+            // Table may predate migration 016 in odd mixed-version setups — advisory
+            // is best-effort and must never fail the health command.
+        }
         let sessionLogEntries = [];
         try {
             const sinceDays = Math.max(0, Math.ceil((now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
@@ -1482,6 +1547,8 @@ export function akmHealth(options = {}) {
             logBackingRate,
             stuckActiveRuns,
             semanticStatus,
+            semanticSearchMode,
+            embeddingEndpoint,
             sessionLogEntries,
             sessionExtraction: improveSummary.sessionExtraction,
             autoAccept: improveSummary.autoAccept,