akm-cli 0.9.0-beta.43 → 0.9.0-beta.45

package/dist/commands/health.js

@@ -134,6 +134,7 @@ function createUnknownImproveMetrics() {
             failures: 0,
             htmlErrors: 0,
             retryAttempts: 0,
+            nonArrayBatchFailures: 0,
             durationMs: 0,
         },
         sessionExtraction: {
@@ -440,6 +441,7 @@ function projectRunMetrics(result) {
             metrics.graphExtraction.failures += toFiniteNumber(telemetry.failureCount);
             metrics.graphExtraction.htmlErrors += toFiniteNumber(telemetry.htmlErrorCount);
             metrics.graphExtraction.retryAttempts += toFiniteNumber(telemetry.retryAttempts);
+            metrics.graphExtraction.nonArrayBatchFailures += toFiniteNumber(telemetry.nonArrayBatchFailures);
         }
     }
     metrics.graphExtraction.durationMs += toFiniteNumber(result.graphExtractionDurationMs);
@@ -587,6 +589,7 @@ function mergeImproveMetrics(dst, src) {
     dst.graphExtraction.truncations += src.graphExtraction.truncations;
     dst.graphExtraction.failures += src.graphExtraction.failures;
     dst.graphExtraction.htmlErrors += src.graphExtraction.htmlErrors;
+    dst.graphExtraction.nonArrayBatchFailures += src.graphExtraction.nonArrayBatchFailures;
     dst.graphExtraction.durationMs += src.graphExtraction.durationMs;
     dst.sessionExtraction.sessionsScanned += src.sessionExtraction.sessionsScanned;
     dst.sessionExtraction.sessionsExtracted += src.sessionExtraction.sessionsExtracted;
@@ -990,6 +993,7 @@ const INTERESTING_DELTA_PATHS = [
     "improve.graphExtraction.cacheHitRate",
     "improve.graphExtraction.failures",
     "improve.graphExtraction.htmlErrors",
+    "improve.graphExtraction.nonArrayBatchFailures",
     "improve.sessionExtraction.sessionsScanned",
     "improve.sessionExtraction.proposalsCreated",
     "improve.autoAccept.promoted",
@@ -1655,6 +1659,7 @@ export function renderWindowCompareMd(windows, deltas) {
         "improve.actions.reflect.failed",
         "improve.actions.distill.llmFailed",
         "improve.graphExtraction.failures",
+        "improve.graphExtraction.nonArrayBatchFailures",
         "improve.wallTime.medianMs",
         "improve.wallTime.p95Ms",
         "improve.memoryInference.skippedNoFacts",

package/dist/commands/improve/improve.js

@@ -3987,6 +3987,7 @@ async function runImprovePostLoopStage(args) {
                 // #632 — clustering-tuning knobs. UNSET = pre-#632 behaviour.
                 maxClusterSize: improveProfile.processes?.recombine?.maxClusterSize,
                 excludeTags: improveProfile.processes?.recombine?.excludeTags,
+                excludeEntities: improveProfile.processes?.recombine?.excludeEntities,
             });
         }
         catch (e) {

package/dist/commands/improve/recombine.js

@@ -57,7 +57,27 @@ import { isConsolidationEligibleMemoryName } from "./consolidate.js";
 const RECOMBINE_SYSTEM_PROMPT = recombineSystemPrompt;
 const DEFAULT_MIN_CLUSTER_SIZE = 3;
 const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
-const DEFAULT_RELATEDNESS_SOURCE = "tags";
+// #632 — slots in each run's processed budget reserved for the top TAG clusters
+// when entity clusters are present, so tag-only topics (a topic with a good tag
+// but no extracted graph entity) are never fully starved by entity preference.
+// Entities still take the rest of the budget; whichever kind is short, the other
+// backfills. UNSET of entities (tags-only stash) ignores this and takes top-N tags.
+const RESERVED_TAG_SLOTS = 3;
+// #632 — a tag cluster larger than this is treated as an over-broad project
+// mega-bucket (low-coherence, the bland signal #632 de-emphasizes), so the
+// reserved tag slots prefer TIGHTER clusters at or below this size first.
+const TAG_RESERVE_SOFT_CAP = 20;
+// #632 — default to the UNION of tag + graph-entity relatedness, with entity
+// clusters PREFERRED at selection time (see the rank in buildRelatednessClusters).
+// Entity clustering surfaces coherent, subject-scoped clusters (a tool/subsystem)
+// that the coarse stash-wide tag buckets miss, while tags still cover memories the
+// graph has no entity for. The `entity:` vs `tag:` signature namespaces are
+// independent, so a pure tag cluster's confirmation streak is only re-baselined
+// when its OWN membership changes — which is exactly what the session-capture pool
+// exclusion intends for the telemetry-polluted buckets (re-baselining a noisy
+// cluster's streak is correct, not a regression). A stash with no extracted graph
+// entities falls through to tag-only.
+const DEFAULT_RELATEDNESS_SOURCE = "both";
 /** #625 — re-induction count required before a hypothesis promotes to a lesson. */
 const DEFAULT_CONFIRM_THRESHOLD = 2;
 /**
@@ -131,6 +151,76 @@ export function isJunkTag(tag) {
         return true; // short hex hashes: 002c624c, 192d
     return false;
 }
+/**
+ * #632 — generic extraction-artefact entities the graph routinely emits: session
+ * bookkeeping (`session_id`, `session_checkpoint`), structured-log field names
+ * (`reason`, `harness`, `structured event log`), and the like. They are
+ * stash-wide and carry no topical signal, so an `entity:<norm>` cluster keyed on
+ * one is exactly the bland mega-bucket #632 aims to remove. Lowercased; matched
+ * against the already-normalised `entity_norm`.
+ */
+const JUNK_ENTITY_NORMS = new Set([
+    "session",
+    "session_id",
+    "session_checkpoint",
+    "checkpoint",
+    "reason",
+    "harness",
+    "event",
+    "event log",
+    "structured event",
+    "structured event log",
+    "timestamp",
+    "metadata",
+    "status",
+]);
+/**
+ * #632 — AKM session-capture telemetry memories: auto-generated session-end
+ * checkpoints named `<harness>-session-<YYYYMMDD>-<id>` or
+ * `<harness>-checkpoint-<YYYYMMDD…>-<id>`, carrying an embedded
+ * `akm_memory_kind: session_checkpoint` metadata block. Their bodies are
+ * pipeline bookkeeping, so the graph extracts their metadata FIELDS
+ * (`session_checkpoint`, `harness`, `buffered observations`, `tool_*_observed`,
+ * …) as ENTITIES — which then dominate entity clustering as bland, stash-wide
+ * mega-buckets (the #632 symptom, just under an `entity:` signature). They are
+ * session telemetry, not durable knowledge to generalize, so recombine excludes
+ * them from its pool. The `\d{8}` datestamp anchor is what distinguishes a
+ * capture name from a durable memory that merely MENTIONS session/checkpoint
+ * (e.g. `akm-plugins-session-end-extract-hook`, `session-checkpoint-lint-skips`),
+ * which stay in the pool.
+ */
+export function isSessionCaptureMemoryName(name) {
+    return /-(session|checkpoint)-\d{8}/.test(name);
+}
+/**
+ * #632 — an entity carries no clustering signal (and must be skipped) when it is
+ * a generic extraction artefact (session / structured-log bookkeeping), a raw
+ * filesystem path (absolute paths the extractor lifts verbatim), or the same
+ * number / date / hash / version / stopword junk `isJunkTag` rejects. Mirrors
+ * `isJunkTag` so the graph relatedness source does not reintroduce the very
+ * bland buckets entity clustering is meant to replace. Unlike `excludeEntities`
+ * (a fixed user list), this catches the OPEN-ENDED junk without config upkeep.
+ */
+export function isJunkEntity(entity) {
+    const e = entity.trim().toLowerCase();
+    if (e.length <= 1)
+        return true;
+    if (JUNK_ENTITY_NORMS.has(e))
+        return true;
+    if (JUNK_STOPWORD_TAGS.has(e))
+        return true;
+    if (e.includes("/") || e.includes("\\"))
+        return true; // raw file paths
+    if (/^\d+$/.test(e))
+        return true; // pure numbers + dates
+    if (/^v?\d+(?:\.\d+)+$/.test(e))
+        return true; // versions
+    if (/^v\d+$/.test(e))
+        return true; // v0, v2
+    if (/^[0-9a-f]{4,}$/.test(e) && /\d/.test(e))
+        return true; // short hex hashes
+    return false;
+}
 /**
  * Build relatedness clusters from the memory pool. Clustering is driven purely
  * by shared tags / graph entities — it MUST NOT use embedding similarity, so
@@ -146,13 +236,19 @@ export function isJunkTag(tag) {
  * A cluster is a signal whose member set is >= `minClusterSize`. Overlapping
  * clusters are de-duplicated by member-set identity, and the result is RANKED
  * by member-count descending (deterministic alphabetical tiebreak). The
- * `maxClustersPerRun` cap is NOT applied here — call {@link capClusters} on the
- * result for the processed slice; the full ranked list is retained so the
- * cap-aware decay sweep can tell cap-displacement from corpus absence (#658).
+ * `maxClustersPerRun` cap is NOT applied here — call {@link selectClustersForRun}
+ * (entity-aware blend) or {@link capClusters} (tags-only) on the result for the
+ * processed slice; the full ranked list is retained so the cap-aware decay sweep
+ * can tell cap-displacement from corpus absence (#658).
  */
 export function buildRelatednessClusters(entries, opts) {
     // Only consolidation-eligible memories participate (exclude `.derived`).
-    const memories = entries.filter((e) => e.entry.type === "memory" && isConsolidationEligibleMemoryName(e.entry.name));
+    // #632 — durable memories only: exclude `.derived` (via
+    // `isConsolidationEligibleMemoryName`) AND session-capture telemetry dumps
+    // whose embedded metadata pollutes both tag and entity clustering.
+    const memories = entries.filter((e) => e.entry.type === "memory" &&
+        isConsolidationEligibleMemoryName(e.entry.name) &&
+        !isSessionCaptureMemoryName(e.entry.name));
     // signal -> member entries
     const groups = new Map();
     const add = (signal, entry) => {
@@ -173,9 +269,13 @@ export function buildRelatednessClusters(entries, opts) {
     const hasEntities = !!opts.entityByEntryId && opts.entityByEntryId.size > 0;
     const useGraph = (opts.relatednessSource === "graph" || opts.relatednessSource === "both") && hasEntities;
     const tagsFallback = !useTags && opts.relatednessSource === "graph" && !hasEntities;
-    // #632 — tags excluded from tag-based clustering (applies regardless of
-    // source). UNSET/[] leaves clustering byte-identical to the pre-#632 path.
+    // #632 — tags/entities excluded from clustering (applies regardless of
+    // source). UNSET/[] leaves tag clustering byte-identical to the pre-#632 path.
     const excludeTags = new Set(opts.excludeTags ?? []);
+    // `entity_norm` is always lowercased (graph-dedup.ts), so normalise the
+    // user-supplied exclusion list to match — `excludeEntities: ["OpenCode"]`
+    // should suppress the stored `opencode` entity (Reviewer A, #632).
+    const excludeEntities = new Set((opts.excludeEntities ?? []).map((e) => e.toLowerCase()));
     for (const entry of memories) {
         if (useTags || tagsFallback) {
             for (const tag of entry.entry.tags ?? []) {
@@ -187,8 +287,13 @@ export function buildRelatednessClusters(entries, opts) {
             }
         }
         if (useGraph && opts.entityByEntryId) {
-            for (const ent of opts.entityByEntryId.get(entry.id) ?? [])
+            for (const ent of opts.entityByEntryId.get(entry.id) ?? []) {
+                if (excludeEntities.has(ent))
+                    continue;
+                if (isJunkEntity(ent))
+                    continue; // #632 — skip generic extraction-artefact / path entities
                 add(`entity:${ent}`, entry);
+            }
         }
     }
     // Keep only groups at or above the minimum cluster size. #632 — when
@@ -216,12 +321,25 @@ export function buildRelatednessClusters(entries, opts) {
         seenMemberKeys.add(memberKey);
         return true;
     });
-    // Rank largest-first (deterministic alphabetical tiebreak). The cap is applied
-    // by the caller via {@link capClusters}, NOT here, so the FULL formed set
-    // (every cluster that genuinely re-forms this run) stays available for the
-    // cap-aware decay sweep — a cluster displaced by the cap must not be confused
-    // with a cluster that vanished from the corpus (#658).
-    clusters.sort((a, b) => b.members.length - a.members.length || a.signature.localeCompare(b.signature));
+    // #632 — rank ENTITY clusters ahead of tag clusters, then largest-first within
+    // each kind (deterministic alphabetical tiebreak). A graph entity is an
+    // EXTRACTED SUBJECT (a tool / subsystem / component), so it is a far
+    // higher-signal cluster key than an auto-tokenized frontmatter tag, whose
+    // broadest buckets (`tag:<project>` — e.g. every memory tagged `akm`) are the
+    // coarse, bland clusters #632 set out to kill. Largest-first ALONE let those
+    // tag mega-buckets fill the `maxClustersPerRun` slice every run and starve the
+    // coherent entity clusters this pass produces. Preferring entities keeps tag
+    // clustering as the fallback (a stash with no graph entities, or a topic with a
+    // tag but no extracted entity, still clusters) while ensuring the better signal
+    // wins the cap. The processed slice is chosen by the caller via
+    // {@link selectClustersForRun} (NOT here), so the FULL formed set stays
+    // available for the cap-aware decay sweep —
+    // a cluster displaced by the cap must not be confused with a cluster that
+    // vanished from the corpus (#658).
+    const entityRank = (sig) => (sig.startsWith("entity:") ? 0 : 1);
+    clusters.sort((a, b) => entityRank(a.signature) - entityRank(b.signature) ||
+        b.members.length - a.members.length ||
+        a.signature.localeCompare(b.signature));
     return clusters;
 }
 /**
@@ -235,6 +353,54 @@ export function buildRelatednessClusters(entries, opts) {
 export function capClusters(ranked, maxClustersPerRun) {
     return ranked.slice(0, Math.max(0, maxClustersPerRun));
 }
+/**
+ * #632 — pick the per-run PROCESSED slice from the full ranked list, BLENDING
+ * entity and tag clusters so neither starves the other:
+ *
+ *   - No entity clusters → top `maxClustersPerRun` TAG clusters (a tags-only
+ *     stash is byte-identical to {@link capClusters}).
+ *   - Entity clusters present → ENTITIES LEAD the budget (the higher-signal key —
+ *     an extracted subject vs an auto-tokenized filename tag), but RESERVE up to
+ *     `RESERVED_TAG_SLOTS` for tag clusters so tag-only topics still surface every
+ *     run. Entities are never starved below one slot when present and the budget
+ *     allows. Whichever kind is short, the other backfills, so the full budget is
+ *     always used when enough clusters exist.
+ *
+ * The reserved tag slots prefer TIGHTER tag clusters (size <= `TAG_RESERVE_SOFT_CAP`,
+ * largest-first within that band, then the over-cap buckets): a broad
+ * auto-tokenized `tag:<project>` mega-bucket is exactly the bland, low-coherence
+ * signal #632 de-emphasizes, so the reserve should not spend its protected slots
+ * on the largest tags. Entities themselves stay largest-first — an entity is a
+ * coherent subject at any size.
+ *
+ * Entities lead the returned order. The FULL pre-cap `ranked` list (not this
+ * slice) still feeds the cap-aware decay sweep (#658), so a cluster left out of
+ * the processed slice this run is NOT decayed as if it vanished.
+ */
+export function selectClustersForRun(ranked, maxClustersPerRun) {
+    const max = Math.max(0, maxClustersPerRun);
+    if (max === 0)
+        return [];
+    const entities = ranked.filter((c) => c.signature.startsWith("entity:"));
+    if (entities.length === 0)
+        return ranked.slice(0, max); // tags-only → top-N (capClusters parity)
+    const tags = ranked.filter((c) => !c.signature.startsWith("entity:"));
+    // Reserve up to RESERVED_TAG_SLOTS for tags, but never below one slot for the
+    // leading entities when the budget allows (so a small `maxClustersPerRun` does
+    // not silently invert the entity preference).
+    const reservedForTags = Math.min(tags.length, RESERVED_TAG_SLOTS, Math.max(0, max - 1));
+    const entityTake = Math.min(entities.length, max - reservedForTags);
+    const tagTake = Math.min(tags.length, max - entityTake); // tags take their reserve + any slot entities left
+    // Prefer tight tags (<= soft cap) over broad mega-buckets for the reserve.
+    const reserveTags = [...tags]
+        .sort((a, b) => {
+        const aOver = a.members.length > TAG_RESERVE_SOFT_CAP ? 1 : 0;
+        const bOver = b.members.length > TAG_RESERVE_SOFT_CAP ? 1 : 0;
+        return aOver - bOver || b.members.length - a.members.length || a.signature.localeCompare(b.signature);
+    })
+        .slice(0, tagTake);
+    return [...entities.slice(0, entityTake), ...reserveTags];
+}
 // ── Prompt + ref derivation ───────────────────────────────────────────────────
 /** Read a memory body (frontmatter stripped) for the cluster prompt. */
 function readBody(entry) {
@@ -408,8 +574,9 @@ export async function akmRecombine(opts) {
         ...(entityByEntryId ? { entityByEntryId } : {}),
         ...(opts.maxClusterSize != null ? { maxClusterSize: opts.maxClusterSize } : {}),
         ...(opts.excludeTags ? { excludeTags: opts.excludeTags } : {}),
+        ...(opts.excludeEntities ? { excludeEntities: opts.excludeEntities } : {}),
     });
-    const clusters = capClusters(rankedClusters, maxClustersPerRun);
+    const clusters = selectClustersForRun(rankedClusters, maxClustersPerRun);
     let clustersFormed = 0;
     let proposalsEmitted = 0;
     let lessonsPromoted = 0;

package/dist/core/config/config-schema.js

@@ -316,9 +316,13 @@ export const ImproveProcessConfigSchema = z
     // (generic project-wide tags). Default UNSET/[]. Only meaningful on
     // `recombine`.
     excludeTags: z.array(z.string().min(1)).optional(),
+    // #632 — recombine process: entity_norm values that must never form an
+    // entity cluster (user counterpart to the built-in generic-entity filter).
+    // Default UNSET/[]. Only meaningful on `recombine`.
+    excludeEntities: z.array(z.string().min(1)).optional(),
     // #609 — recombine process: relatedness signal used to form clusters
     // (tags | graph | both). Clustering is by relatedness, never embedding
-    // similarity. Default "tags". Only meaningful on `recombine`.
+    // similarity. Default "both" (#632). Only meaningful on `recombine`.
     relatednessSource: z.enum(["tags", "graph", "both"]).optional(),
     // #609 — recombine process: consecutive re-inductions required before a
     // hypothesis is promoted to a lesson. Default 2. Only meaningful on

package/dist/core/parse.js

@@ -98,16 +98,24 @@ export function parseJsonResponse(raw) {
  * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
  * substring. Returns `undefined` if no valid JSON structure is found.
  *
- * Non-array results are preferred: if a `{…}` object is found first, it is
- * returned immediately. Arrays (`[…]`) are captured as a fallback and
- * returned only when no object was found.
+ * Shape preference is controlled by {@link ParseEmbeddedJsonOptions.expect}:
+ * - `"any"` (default): non-array results are preferred — a `{…}` object found
+ *   first is returned immediately; arrays (`[…]`) are a fallback.
+ * - `"array"`: only top-level arrays are returned. The direct parse is
+ *   accepted only if it is an array, and the scanner returns the first
+ *   balanced `[…]` while skipping `{…}` openers entirely.
  */
-export function parseEmbeddedJsonResponse(raw) {
+export function parseEmbeddedJsonResponse(raw, options) {
+    const expectArray = options?.expect === "array";
     const direct = parseJsonResponse(raw);
-    if (direct !== undefined)
+    if (direct !== undefined && (!expectArray || Array.isArray(direct)))
         return direct;
     const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
     let arrayFallback;
+    // Scan only *top-level* balanced structures: once a `{…}`/`[…]` is matched we
+    // jump `start` past its closing bracket rather than re-scanning its interior.
+    // This keeps array mode from salvaging an array *nested inside* a leading
+    // object (e.g. the `entities` array of a bare `{entities,relations}` object).
     for (let start = 0; start < text.length; start++) {
         const opener = text[start];
         if (opener !== "{" && opener !== "[")
@@ -116,6 +124,7 @@ export function parseEmbeddedJsonResponse(raw) {
         let depth = 0;
         let inString = false;
         let escaped = false;
+        let end = -1;
         for (let i = start; i < text.length; i++) {
             const ch = text[i];
             if (inString) {
@@ -139,20 +148,31 @@ export function parseEmbeddedJsonResponse(raw) {
             if (ch === closer) {
                 depth -= 1;
                 if (depth === 0) {
-                    try {
-                        const parsed = JSON.parse(text.slice(start, i + 1));
-                        if (!Array.isArray(parsed)) {
-                            return parsed;
-                        }
-                        arrayFallback ??= parsed;
-                        break;
-                    }
-                    catch {
-                        break;
-                    }
+                    end = i;
+                    break;
                 }
             }
         }
+        if (end === -1)
+            continue; // never balanced — let the next opener try
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (Array.isArray(parsed)) {
+                // First valid array wins in array mode; in "any" mode it is the
+                // fallback returned only if no object is found.
+                if (expectArray)
+                    return parsed;
+                arrayFallback ??= parsed;
+            }
+            else if (!expectArray) {
+                return parsed;
+            }
+            // Skip past this balanced structure so we don't descend into it.
+            start = end;
+        }
+        catch {
+            // Malformed candidate — advance one char and try the next opener.
+        }
     }
     return arrayFallback;
 }

package/dist/indexer/graph/graph-extraction.js

@@ -372,6 +372,7 @@ export async function runGraphExtractionPass(ctx) {
         failureCount: 0,
         htmlErrorCount: 0,
         retryAttempts: 0,
+        nonArrayBatchFailures: 0,
     };
     const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
     const runtimeTelemetry = {
@@ -625,6 +626,7 @@ export async function runGraphExtractionPass(ctx) {
     telemetry.failureCount = runtimeTelemetry.failureCount ?? 0;
     telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
     telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
+    telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
     const qualityConsidered = mergedNodes.length;
     const qualityExtracted = mergedNodes.filter((node) => node.status === "extracted" && node.entities.length > 0).length;
     const quality = computeGraphQualityTelemetry(qualityConsidered, qualityExtracted, deduped.entities.length, deduped.relations.length);

package/dist/llm/graph-extract.js

@@ -433,6 +433,18 @@ function buildBatchSystemPrompt() {
         "The array length MUST equal the number of assets provided. " +
         'Use {"entities":[],"relations":[]} for assets with no extractable graph content.');
 }
+/**
+ * Hardened system prompt for the single batch retry (#635). Used only after a
+ * first response failed array salvage — leans harder on "raw array only" so a
+ * model that wrapped the array in prose/fences corrects itself before we pay
+ * the per-asset fallback.
+ */
+function buildBatchRetrySystemPrompt() {
+    return (`${buildBatchSystemPrompt()} ` +
+        "Your previous response could NOT be parsed as a JSON array. " +
+        "Respond with ONLY the raw JSON array — start with '[' and end with ']'. " +
+        "No prose, no explanation, no markdown code fences, no preamble.");
+}
 function buildBatchUserPrompt(bodies) {
     const count = bodies.length;
     const assetBlocks = bodies.map((body, i) => `${BATCH_ASSET_SEPARATOR} ${i + 1} ===\n${body.trim()}`).join("\n\n");
@@ -542,7 +554,21 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
             });
             if (!raw)
                 return null;
-            const parsed = parseEmbeddedJsonResponse(raw);
+            // Array-preferring salvage (#635): the batch contract is a top-level
+            // JSON array. A leading/example `{…}` object in the response must not
+            // mask a valid `[…]` array as a false "non-array" failure.
+            let parsed = parseEmbeddedJsonResponse(raw, { expect: "array" });
+            if (!Array.isArray(parsed)) {
+                // One stricter-reprompt retry before paying the per-asset fallback
+                // (#635). Many genuine non-array responses recover when the model is
+                // told explicitly to emit only the raw array.
+                bumpTelemetry(options.telemetry, "retryAttempts");
+                const retryRaw = await chatCompletion(llmConfig, [
+                    { role: "system", content: buildBatchRetrySystemPrompt() },
+                    { role: "user", content: userPrompt },
+                ], { temperature: 0, timeoutMs: llmConfig.timeoutMs, signal });
+                parsed = retryRaw ? parseEmbeddedJsonResponse(retryRaw, { expect: "array" }) : undefined;
+            }
             if (!Array.isArray(parsed)) {
                 nonArrayResponse = true;
                 bumpTelemetry(options.telemetry, "nonArrayBatchFailures");
@@ -552,8 +578,9 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
                         batchState.batchingDisabled = true;
                     }
                 }
-                warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s); ` +
-                    `will fall back per-asset. promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
+                warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s) ` +
+                    `even after a stricter retry; will fall back per-asset. ` +
+                    `promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
                 return null;
             }
             return parsed;

package/dist/scripts/migrate-storage.js

@@ -16083,6 +16083,7 @@ var init_config_schema = __esm(() => {
     maxClustersPerRun: positiveInt.optional(),
     maxClusterSize: positiveInt.optional(),
     excludeTags: exports_external.array(exports_external.string().min(1)).optional(),
+    excludeEntities: exports_external.array(exports_external.string().min(1)).optional(),
     relatednessSource: exports_external.enum(["tags", "graph", "both"]).optional(),
     confirmThreshold: exports_external.number().int().min(1).optional(),
     minRecurrence: exports_external.number().int().min(2).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.43",
+  "version": "0.9.0-beta.45",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [