akm-cli 0.8.3 → 0.9.0-beta.1

package/dist/commands/{consolidate.js → improve/consolidate.js}

@@ -5,28 +5,28 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
-import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAssetFromString } from "../core/asset-serialize";
-import { resolveStashDir, timestampForFilename } from "../core/common";
-import { getDefaultLlmConfig, loadConfig } from "../core/config";
-import { ConfigError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { writeContradictEdge } from "../core/memory-belief";
-import { parseEmbeddedJsonResponse } from "../core/parse";
-import { hasHotCaptureMode, hasSupersededStatus, MERGE_ABSOLUTE_FLOOR_CHARS, MERGE_SHRINK_RATIO_MIN, validateProposalFrontmatter, } from "../core/proposal-quality-validators";
-import { createProposal, isProposalSkipped, listProposals } from "../core/proposals";
-import { detectTruncatedDescription } from "../core/text-truncation";
+import { parse as yamlParse } from "yaml";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir, timestampForFilename } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { detectTruncatedDescription } from "../../core/text-truncation.js";
+import { hasHotCaptureMode, hasSupersededStatus, MERGE_ABSOLUTE_FLOOR_CHARS, MERGE_SHRINK_RATIO_MIN, validateProposalFrontmatter, } from "../proposal/validators/proposal-quality-validators.js";
+import { createProposal, isProposalSkipped, listProposals } from "../proposal/validators/proposals.js";
+import { writeContradictEdge } from "./memory/memory-belief.js";
 // Re-export the moved helpers so existing test imports continue to resolve.
 export { hasSupersededStatus, validateProposalFrontmatter };
-import { warn } from "../core/warn";
-import { deleteAssetFromSource, resolveWriteTarget, writeAssetToSource } from "../core/write-source";
-import { closeDatabase, findEntryIdByRef, getAllEntries, getEntryById, getNeighborsByEntryId, openExistingDatabase, } from "../indexer/db";
-import { resolveImproveProcessRunnerFromProfile } from "../integrations/agent/runner";
-import { chatCompletion } from "../llm/client";
-import { cosineSimilarity, embedBatch } from "../llm/embedder";
-import { isLlmFeatureEnabled, tryLlmFeature } from "../llm/feature-gate";
+import { warn } from "../../core/warn.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { closeDatabase, findEntryIdByRef, getAllEntries, getEntryById, getNeighborsByEntryId, openExistingDatabase, } from "../../indexer/db/db.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+import { cosineSimilarity, embedBatch } from "../../llm/embedder.js";
+import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
 // ── Prompts ─────────────────────────────────────────────────────────────────
 const CONSOLIDATE_SYSTEM_PROMPT = `You are the akm consolidate assistant analyzing memory assets.
 
@@ -704,7 +704,7 @@ function archiveMemory(filePath, stashDir, ref, reason, opIndex, supersededBy, w
             ...(supersededBy ? { superseded_by: supersededBy } : {}),
             superseded_reason: reason,
         };
-        content = assembleAssetFromString(yamlStringify(newFm).trimEnd(), parsed.content);
+        content = assembleAssetFromString(serializeFrontmatter(newFm), parsed.content);
     }
     catch {
         if (warnings)
@@ -745,7 +745,7 @@ function archiveMemory(filePath, stashDir, ref, reason, opIndex, supersededBy, w
 function resolveConsolidateLlmConfig(config) {
     const consolidateProcess = config.profiles?.improve?.default?.processes?.consolidate;
     const runnerSpec = resolveImproveProcessRunnerFromProfile(consolidateProcess, config);
-    if (runnerSpec && runnerSpec.kind === "llm") {
+    if (runnerSpec && runnerIsLlm(runnerSpec)) {
         return runnerSpec.connection;
     }
     // Non-LLM runner modes (agent/sdk) don't apply to consolidate's HTTP path;
@@ -877,11 +877,12 @@ export async function akmConsolidate(opts = {}) {
     // health rollup can aggregate without regex-parsing English warning
     // strings. See `/tmp/akm-health-investigations/tuning-reasons-investigation.md` §Q2.
     const skipReasons = [];
-    // Tracks refs already emitted to skipReasons. A ref can only occupy one
-    // accounting bucket; subsequent skip ops for the same ref are recorded as
-    // warnings but must not push a second skipReasons entry (that would inflate
+    // Per-ref grouping of skipReasons entries. A ref occupies exactly one
+    // accounting bucket and therefore exactly one skipReasons array entry;
+    // subsequent skip ops for the same ref append to that entry's `skips[]`
+    // rather than pushing a second array entry (that would inflate
     // Σ(skipReasons) and break the invariant by +1 per duplicate).
-    const skipReasonEmittedRefs = new Set();
+    const skipReasonByRef = new Map();
     const pushSkipReason = (op, ref, reason) => {
         // 2026-05-27 cross-chunk double-count fix: if `ref` already contributed
         // to judgedNoAction in its own chunk (a different chunk proposed an op
@@ -891,14 +892,17 @@ export async function akmConsolidate(opts = {}) {
         // Σ(skipReasons) + failedChunkMemories.
         if (judgedNoActionRefs.delete(ref))
             judgedNoAction--;
-        if (skipReasonEmittedRefs.has(ref)) {
-            // Already counted once. Record the extra skip for observability but
-            // don't push to skipReasons — that would break the accounting invariant.
-            warnings.push(`Skip: ${ref} already in skipReasons (${reason} via ${op}); not re-counted.`);
+        const existing = skipReasonByRef.get(ref);
+        if (existing) {
+            // Already counted once for accounting. Append the extra skip to the
+            // ref's grouped entry for observability without adding a new array
+            // entry (which would break the accounting invariant).
+            existing.skips.push({ op, reason });
             return;
         }
-        skipReasonEmittedRefs.add(ref);
-        skipReasons.push({ op, ref, reason });
+        const entry = { ref, skips: [{ op, reason }] };
+        skipReasonByRef.set(ref, entry);
+        skipReasons.push(entry);
     };
     // judgedNoAction tracks memories the LLM saw inside a chunk but proposed
     // no op for. Computed per chunk as `chunk.length − unique(targetRefs in ops)`.
@@ -1560,7 +1564,7 @@ export async function akmConsolidate(opts = {}) {
                     ...(parsedMemory.data ?? {}),
                     description,
                 };
-                const serializedMergedFm = yamlStringify(mergedBodyFm).trimEnd();
+                const serializedMergedFm = serializeFrontmatter(mergedBodyFm);
                 const proposalContent = assembleAssetFromString(serializedMergedFm, parsedMemory.content);
                 // Pre-emit dedup against pending consolidate proposals from the
                 // same improve run (slug-variant match). The cross-run content-hash
@@ -1634,6 +1638,14 @@ export async function akmConsolidate(opts = {}) {
             }
         }
     }
+    // 0.9.0 (issue #507): batch-at-boundary commit. The merge/delete loop above
+    // wrote one merged primary and deleted N secondaries to the resolved target
+    // with NO per-asset commit. If the target is a writable git source and any
+    // asset was mutated, commit the whole batch ONCE here (stages .akm/ +
+    // siblings together). No-op for filesystem/primary-stash targets.
+    if (merged > 0 || deleted > 0) {
+        commitWriteTargetBoundary(target, `Consolidate: ${merged} merged, ${deleted} removed`);
+    }
     cleanupJournal(stashDir, timestamp);
     // TTL cleanup: remove archive entries older than archiveRetentionDays (default 90).
     // C-5 / #391: emit an `archive_cleanup` event before each deletion so the
@@ -1828,7 +1840,7 @@ export function sanitizeMergedContent(raw) {
     // Recovery: if the strict yaml library fails, fall back to the lenient
     // hand-rolled parseFrontmatter parser, which tolerates common LLM YAML
     // quirks (unescaped special chars, bare scalars, etc.). If it recovers
-    // at least one key, proceed — yamlStringify below will re-serialize
+    // at least one key, proceed — serializeFrontmatter below will re-serialize
     // cleanly. Only reject if both parsers fail to extract any data.
     let parsedFm;
     try {
@@ -1855,7 +1867,7 @@ export function sanitizeMergedContent(raw) {
     // Re-serialise via yaml.stringify to fix any quoting quirks.
     let serialized;
     try {
-        serialized = yamlStringify(fm).trimEnd();
+        serialized = serializeFrontmatter(fm);
     }
     catch (e) {
         return { ok: false, reason: `YAML_STRINGIFY_FAILED: ${e instanceof Error ? e.message : String(e)}` };
@@ -2205,7 +2217,7 @@ async function generateMergedContent(config, primaryRef, primaryBody, secondaryR
                         : secFm.data[key];
             }
             normalizeUpdatedField(repairedFmData);
-            const repairedYaml = yamlStringify(repairedFmData).trimEnd();
+            const repairedYaml = serializeFrontmatter(repairedFmData);
             const bodyPart = mergedFm.content ?? "";
             return { content: `---\n${repairedYaml}\n---\n${bodyPart}` };
         }

package/dist/commands/{distill-promotion-policy.js → improve/distill-promotion-policy.js}

@@ -1,9 +1,9 @@
 // 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/.
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAsset } from "../core/asset-serialize";
-import { parseFrontmatter } from "../core/frontmatter";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 function hasNonEmptyList(value) {
     return Array.isArray(value) && value.some((item) => typeof item === "string" && item.trim().length > 0);
 }

package/dist/commands/{distill.js → improve/distill.js}

@@ -52,22 +52,22 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAssetFromString } from "../core/asset-serialize";
-import { resolveStashDir, timestampForFilename } from "../core/common";
-import { getDefaultLlmConfig, loadConfig } from "../core/config";
-import { ConfigError, UsageError } from "../core/errors";
-import { appendEvent, readEvents } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { lintLessonContent } from "../core/lesson-lint";
-import { stripMarkdownFences } from "../core/markdown";
-import { createProposal, isProposalSkipped, listProposals, } from "../core/proposals";
-import { warnVerbose } from "../core/warn";
-import { resolveAssetPath } from "../indexer/path-resolver";
-import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
-import { isLlmFeatureEnabled, tryLlmFeature } from "../llm/feature-gate";
-import { assessMemoryKnowledgePromotionCandidate, deriveKnowledgeRef } from "./distill-promotion-policy";
-import { akmSearch } from "./search";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAssetFromString } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { resolveStashDir, timestampForFilename } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { lintLessonContent } from "../../core/lesson-lint.js";
+import { warnVerbose } from "../../core/warn.js";
+import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
+import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
+import { akmSearch } from "../read/search.js";
+import { assessMemoryKnowledgePromotionCandidate, deriveKnowledgeRef } from "./distill-promotion-policy.js";
 /**
  * Asset-ref types that `akm distill` structurally refuses as inputs.
  *
@@ -112,13 +112,14 @@ export function deriveLessonRef(inputRef) {
         .replace(/^-|-$/g, "");
     return `lesson:${safe}-lesson`;
 }
+import { repairTruncatedDescription } from "../../core/text-truncation.js";
 // ── Content quality validators ──────────────────────────────────────────────
 //
 // The actual implementations now live in `core/proposal-quality-validators.ts`
 // so the same checks run inside `runProposalValidators` on `proposal accept`.
 // We re-export the public-facing helpers here so existing imports
-// (`from "../src/commands/distill"`) continue to resolve.
-import { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse } from "../core/proposal-quality-validators";
+// (`from "../../src/commands/distill"`) continue to resolve.
+import { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse, } from "../proposal/validators/proposal-quality-validators.js";
 export { detectDoubleFrontmatter, isValidDescription, isValidWhenToUse };
 // ── Prompt assembly ─────────────────────────────────────────────────────────
 const LESSON_SYSTEM_PROMPT = [
@@ -1121,6 +1122,26 @@ export async function akmDistill(options) {
             }
         }
     }
+    // Post-generation truncation repair (#556): if the LLM sliced the
+    // description mid-sentence, deterministically complete it from its own text
+    // / the lesson body BEFORE the lint + quality validators run. No-op
+    // (byte-identical) for already-complete descriptions, so this never alters
+    // a valid proposal. Runs on the lesson path only (knowledge has no
+    // description field gate here).
+    if (effectiveProposalKind !== "knowledge") {
+        const parsedRepair = parseFrontmatter(content);
+        const fmRepair = (parsedRepair.data ?? {});
+        const descRepairRaw = typeof fmRepair.description === "string" ? fmRepair.description : "";
+        if (descRepairRaw) {
+            const repaired = repairTruncatedDescription(descRepairRaw, parsedRepair.content);
+            if (repaired !== descRepairRaw) {
+                const repairedFmLines = Object.entries({ ...fmRepair, description: repaired })
+                    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+                    .join("\n");
+                content = assembleAssetFromString(repairedFmLines, parsedRepair.content);
+            }
+        }
+    }
     // Parse + lint the lesson before creating the proposal. The lint is the
     // canonical gate for required frontmatter (v1 spec §13). On failure we
     // surface a structured error and exit non-zero — but still emit

package/dist/commands/{eval-cases.js → improve/eval-cases.js}

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { writeFileAtomic } from "../core/common";
+import { writeFileAtomic } from "../../core/common.js";
 export function writeEvalCase(stashDir, evalCase) {
     const evalDir = path.join(stashDir, ".akm", "eval-cases");
     fs.mkdirSync(evalDir, { recursive: true });

package/dist/commands/{extract-cli.js → improve/extract-cli.js}

@@ -15,10 +15,10 @@
  * `--auto` runs multiple harnesses).
  */
 import { defineCommand } from "citty";
-import { output, runWithJsonErrors } from "../cli/shared";
-import { UsageError } from "../core/errors";
-import { getAvailableHarnesses } from "../integrations/session-logs";
-import { akmExtract } from "./extract";
+import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { UsageError } from "../../core/errors.js";
+import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
+import { akmExtract } from "./extract.js";
 export const extractCommand = defineCommand({
     meta: {
         name: "extract",

package/dist/commands/{extract-prompt.js → improve/extract-prompt.js}

@@ -14,7 +14,7 @@
  * happy path. `additionalProperties: false` means any hallucinated keys
  * the model emits get dropped before we parse.
  */
-import promptTemplate from "../assets/prompts/extract-session.md" with { type: "text" };
+import promptTemplate from "../../assets/prompts/extract-session.md" with { type: "text" };
 /**
  * JSON Schema for the structured extract output. Passed to `chatCompletion`
  * when the configured LLM connection has `supportsJsonSchema: true`.
@@ -55,7 +55,7 @@ export const EXTRACT_JSON_SCHEMA = {
                         type: "string",
                         minLength: 20,
                         maxLength: 400,
-                        description: "One-sentence summary of the candidate.",
+                        description: "One-sentence summary of the candidate. Must be a complete sentence; do not end mid-clause.",
                     },
                     when_to_use: {
                         type: "string",

package/dist/commands/{extract.js → improve/extract.js}

@@ -1,21 +1,47 @@
 // 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/.
-import { stringify as yamlStringify } from "yaml";
-import { assembleAssetFromString } from "../core/asset-serialize";
-import { resolveStashDir, timestampForFilename } from "../core/common";
-import { getDefaultLlmConfig, loadConfig } from "../core/config";
-import { ConfigError, UsageError } from "../core/errors";
-import { appendEvent } from "../core/events";
-import { createProposal, isProposalSkipped } from "../core/proposals";
-import { getExtractedSessionsMap, openStateDatabase, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../core/state-db";
-import { warn } from "../core/warn";
-import { resolveImproveProcessRunnerFromProfile } from "../integrations/agent/runner";
-import { getAvailableHarnesses } from "../integrations/session-logs";
-import { preFilterSession } from "../integrations/session-logs/pre-filter";
-import { chatCompletion } from "../llm/client";
-import { isLlmFeatureEnabled, tryLlmFeature } from "../llm/feature-gate";
-import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt";
+/**
+ * `akm extract` — session-insight extractor.
+ *
+ * Replaces the akm-plugin session-checkpoint hook with an on-demand extractor
+ * that reads native session files (claude-code JSONL, opencode storage tree)
+ * through the {@link SessionLogHarness} registry, pre-filters noise, and asks
+ * a bounded in-tree LLM to produce candidate memory/lesson/knowledge proposals
+ * for content the agent did NOT preserve via inline `akm remember`/`akm feedback`.
+ *
+ * Architectural notes:
+ *   - Stateless. All file/LLM access goes through injectable seams so tests
+ *     never touch a real platform.
+ *   - Bounded LLM call wrapped by {@link tryLlmFeature} under the
+ *     `session_extraction` gate (default-on; opt out via
+ *     `profiles.improve.default.processes.extract.enabled: false`).
+ *   - Proposals routed via `createProposal({ source: "extract", ... })` — the
+ *     same review queue as reflect / distill / consolidate. Never direct-write.
+ *   - Per-candidate body assembly merges description (+ when_to_use for lessons)
+ *     into the body's YAML frontmatter so the accept-time
+ *     descriptionQualityValidator passes — same pattern as the
+ *     consolidate-writer fix.
+ */
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { resolveStashDir, timestampForFilename } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { getExtractedSessionsMap, openStateDatabase, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../core/state-db.js";
+import { repairTruncatedDescription } from "../../core/text-truncation.js";
+import { warn } from "../../core/warn.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
+import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
+import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
+import { chatCompletion } from "../../llm/client.js";
+import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
+import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
+import { buildSessionSummaryPrompt, parseSessionSummary, SESSION_SUMMARY_JSON_SCHEMA, sessionMeetsDurationGate, writeSessionAsset, } from "./session-asset.js";
+/** Default minimum session duration (minutes) for session indexing (#561). */
+const DEFAULT_MIN_SESSION_DURATION_MINUTES = 5;
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Parse a since-string into an absolute ms-epoch cutoff. Accepts:
@@ -49,7 +75,15 @@ export function parseSinceArg(value, now = Date.now()) {
  */
 function resolveHarness(type, harnesses) {
     const pool = harnesses ?? getAvailableHarnesses();
-    return pool.find((h) => h.name === type);
+    // #563 id-normalization bridge: a provider's `name` is its runtime id (e.g.
+    // the Claude provider is "claude-code"), but the canonical harness id is
+    // "claude". Normalize BOTH the requested `--type` and each provider name to
+    // canonical before comparing, so `--type claude` and `--type claude-code`
+    // both resolve to the Claude provider. Behaviour fix: previously only the
+    // exact runtime string ("claude-code") matched; the canonical "claude" used
+    // everywhere else (agent profiles, config schema) silently found nothing.
+    const wanted = normalizeHarnessId(type);
+    return pool.find((h) => normalizeHarnessId(h.name) === wanted);
 }
 /**
  * Build the ref + content for a candidate. The body must contain a
@@ -59,16 +93,19 @@ function resolveHarness(type, harnesses) {
  */
 function buildCandidateProposal(candidate, sourceRef) {
     const ref = `${candidate.type}:${candidate.name}`;
+    // Post-generation repair pass (#556): deterministically complete a
+    // description the LLM sliced mid-sentence before it reaches the
+    // auto-accept validators. No-op (byte-identical) for valid descriptions.
+    const description = repairTruncatedDescription(candidate.description, candidate.body);
     const fm = {
-        description: candidate.description,
+        description,
         sources: [`session:${sourceRef.harness}:${sourceRef.sessionId}`],
     };
     if (candidate.type === "lesson" && candidate.when_to_use) {
         fm.when_to_use = candidate.when_to_use;
     }
-    const serialized = yamlStringify(fm).trimEnd();
-    const content = assembleAssetFromString(serialized, candidate.body);
-    return { ref, content };
+    const content = assembleAsset(fm, candidate.body);
+    return { ref, content, description };
 }
 /**
  * Process one session through the full pipeline: read → pre-filter → LLM →
@@ -78,7 +115,7 @@ function buildCandidateProposal(candidate, sourceRef) {
  * proposal validation failure) the session result records a warning and
  * keeps going — one session's bad luck never aborts a multi-session run.
  */
-async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars) {
+async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, sessionIndexing) {
     const warnings = [];
     let data;
     try {
@@ -100,6 +137,30 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
     });
     const prompt = buildExtractPrompt({ data, events: filtered.events, inlineRefs: data.inlineRefs });
+    // #561 — ADDITIVE session indexing. Generate + write the session asset
+    // (`sessions/<harness>/<id>.md`). FAIL-OPEN: any failure only records a
+    // warning; it NEVER changes the proposal/skip outcome of extract. Returns the
+    // frontmatter fields to merge into the per-session result for state-db
+    // correlation. When disabled this closure makes NO LLM call and writes NOTHING.
+    const maybeWriteSessionAsset = async () => {
+        if (!sessionIndexing.enabled || dryRun)
+            return {};
+        if (!sessionMeetsDurationGate(data, sessionIndexing.minDurationMinutes))
+            return {};
+        try {
+            const result = await writeSessionAsset(data, stashDir, sessionIndexing.generate);
+            if (result.written) {
+                return {
+                    ...(result.ref ? { sessionAssetRef: result.ref } : {}),
+                    ...(result.logPath ? { sessionLogPath: result.logPath } : {}),
+                };
+            }
+        }
+        catch (err) {
+            warnings.push(`session asset write failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return {};
+    };
     let llmRaw = "";
     const llmResult = await tryLlmFeature("session_extraction", config, async () => {
         llmRaw = await chat(llmConfig, [{ role: "user", content: prompt }], {
@@ -141,6 +202,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                 preFilterOutput: filtered.stats.outputCount,
             },
         }, ctx);
+        const sessionAsset = await maybeWriteSessionAsset();
         return {
             sessionId: sessionRef.sessionId,
             harness: harness.name,
@@ -153,6 +215,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                 truncatedCount: filtered.stats.truncatedCount,
             },
             warnings,
+            ...sessionAsset,
         };
     }
     for (const candidate of payload.candidates) {
@@ -161,7 +224,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             continue;
         }
         try {
-            const { ref, content } = buildCandidateProposal(candidate, sessionRef);
+            const { ref, content, description } = buildCandidateProposal(candidate, sessionRef);
             const result = createProposal(stashDir, {
                 ref,
                 source: "extract",
@@ -169,7 +232,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
                 payload: {
                     content,
                     frontmatter: {
-                        description: candidate.description,
+                        description,
                         ...(candidate.when_to_use ? { when_to_use: candidate.when_to_use } : {}),
                         ...(typeof candidate.confidence === "number" ? { confidence: candidate.confidence } : {}),
                         sources: [`session:${sessionRef.harness}:${sessionRef.sessionId}`],
@@ -202,6 +265,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             preFilterOutput: filtered.stats.outputCount,
         },
     }, ctx);
+    const sessionAsset = await maybeWriteSessionAsset();
     return {
         sessionId: sessionRef.sessionId,
         harness: harness.name,
@@ -213,6 +277,7 @@ async function processSession(harness, sessionRef, stashDir, config, llmConfig,
             truncatedCount: filtered.stats.truncatedCount,
         },
         warnings,
+        ...sessionAsset,
     };
 }
 // ── Public entrypoint ────────────────────────────────────────────────────────
@@ -257,7 +322,7 @@ export async function akmExtract(options) {
     let llmConfig;
     const runnerSpec = resolveImproveProcessRunnerFromProfile(extractProcess, config);
     if (runnerSpec) {
-        if (runnerSpec.kind !== "llm") {
+        if (!runnerIsLlm(runnerSpec)) {
             throw new ConfigError(`Extract only supports mode: "llm" (in-tree LLM call). Got mode: "${runnerSpec.kind}" from profiles.improve.default.processes.extract — change it to "llm" or remove the override.`, "INVALID_CONFIG_FILE");
         }
         llmConfig = runnerSpec.connection;
@@ -276,6 +341,35 @@ export async function akmExtract(options) {
     const maxTotalChars = typeof extractProcess?.maxTotalChars === "number" ? extractProcess.maxTotalChars : undefined;
     // Default discovery window — process config can override the built-in 24h.
     const effectiveSince = options.since ?? extractProcess?.defaultSince;
+    // #561 — resolve session-indexing config. Default ON: we only reach this code
+    // when `session_extraction` is enabled AND an LLM is configured (both checked
+    // above), so defaulting on costs nothing offline (the summary call fails open)
+    // while making sessions searchable in the common LLM-configured case. Set
+    // `processes.extract.indexSessions: false` for byte-identical legacy behaviour.
+    const sessionIndexingEnabled = extractProcess?.indexSessions ?? true;
+    const minSessionDuration = typeof extractProcess?.minSessionDuration === "number"
+        ? extractProcess.minSessionDuration
+        : DEFAULT_MIN_SESSION_DURATION_MINUTES;
+    // Production summary generator: a bounded in-tree LLM call wrapped in the same
+    // fail-open `tryLlmFeature` seam as the rest of extract. Returns `undefined`
+    // on disablement / timeout / error so no asset is written. Tests inject a fake.
+    const chatForSummary = options.chat ?? chatCompletion;
+    const defaultSessionSummaryGenerator = async (data) => {
+        let raw = "";
+        await tryLlmFeature("session_extraction", config, async () => {
+            raw = await chatForSummary(llmConfig, [{ role: "user", content: buildSessionSummaryPrompt(data) }], {
+                timeoutMs,
+                responseSchema: SESSION_SUMMARY_JSON_SCHEMA,
+            });
+            return raw;
+        }, "", { timeoutMs });
+        return parseSessionSummary(raw);
+    };
+    const sessionIndexing = {
+        enabled: sessionIndexingEnabled,
+        minDurationMinutes: minSessionDuration,
+        generate: options.generateSessionSummary ?? defaultSessionSummaryGenerator,
+    };
     const harness = resolveHarness(options.type, options.harnesses);
     if (!harness) {
         return {
@@ -355,7 +449,7 @@ export async function akmExtract(options) {
     let seenMap = new Map();
     if (trackingEnabled && candidates.length > 0) {
         try {
-            stateDb = options.stateDb ?? openStateDatabase();
+            stateDb = options.stateDb ?? openStateDatabase(options.stateDbPath);
             seenMap = getExtractedSessionsMap(stateDb, harness.name, candidates.map((c) => c.sessionId));
         }
         catch (err) {
@@ -389,7 +483,7 @@ export async function akmExtract(options) {
             continue;
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars);
+            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, sessionIndexing);
             sessions.push(result);
             if (result.skipped)
                 skippedCount += 1;
@@ -423,6 +517,11 @@ export async function akmExtract(options) {
                             preFilterOutputCount: result.preFilter.outputCount,
                             preFilterTruncatedCount: result.preFilter.truncatedCount,
                             ...(result.skipReason ? { skipReason: result.skipReason } : {}),
+                            // #561 — record the session's log_path for correlation across
+                            // index rebuilds (the session asset frontmatter is the primary
+                            // durable key; this is the state-db mirror of it).
+                            ...(result.sessionLogPath ? { logPath: result.sessionLogPath } : {}),
+                            ...(result.sessionAssetRef ? { sessionAssetRef: result.sessionAssetRef } : {}),
                         },
                     });
                 }
@@ -475,3 +574,63 @@ export async function akmExtract(options) {
         durationMs: Date.now() - startMs,
     };
 }
+/**
+ * Count NEW (unseen, in-window) extract candidate sessions across all available
+ * harnesses WITHOUT making any LLM calls. Mirrors the discovery + seen-filter
+ * logic in {@link akmExtract} so the `#554 minNewSessions` gate in `improve`
+ * can decide whether the extract pass is worth running before any work begins.
+ *
+ * A session is a "new candidate" when it is in the `since` window AND it would
+ * not be skipped by {@link shouldSkipAlreadyExtractedSession} (i.e. it has never
+ * been extracted, or new events have arrived since it was last extracted).
+ */
+export function countNewExtractCandidates(config, options = {}) {
+    const extractProcess = config.profiles?.improve?.default?.processes?.extract;
+    const effectiveSince = options.since ?? extractProcess?.defaultSince;
+    const sinceMs = parseSinceArg(effectiveSince);
+    const harnesses = (options.harnesses ?? getAvailableHarnesses()).filter((h) => h.isAvailable());
+    let stateDb = options.stateDb;
+    let openedStateDb = false;
+    let total = 0;
+    try {
+        for (const harness of harnesses) {
+            const candidates = harness.listSessions({ sinceMs });
+            if (candidates.length === 0)
+                continue;
+            let seenMap = new Map();
+            try {
+                if (!stateDb) {
+                    stateDb = openStateDatabase(options.stateDbPath);
+                    openedStateDb = true;
+                }
+                seenMap = getExtractedSessionsMap(stateDb, harness.name, candidates.map((c) => c.sessionId));
+            }
+            catch (err) {
+                // state.db unavailable — treat every in-window session as a new
+                // candidate (fail-open: never let a transient sqlite error wrongly
+                // trip the gate and skip a pass that should have run).
+                const msg = err instanceof Error ? err.message : String(err);
+                warn(`[extract] state.db unavailable while counting candidates, treating all as new: ${msg}`);
+                total += candidates.length;
+                continue;
+            }
+            for (const summary of candidates) {
+                const prior = seenMap.get(summary.sessionId);
+                if (shouldSkipAlreadyExtractedSession(prior, summary.endedAt))
+                    continue;
+                total += 1;
+            }
+        }
+    }
+    finally {
+        if (stateDb && openedStateDb) {
+            try {
+                stateDb.close();
+            }
+            catch {
+                // best-effort close
+            }
+        }
+    }
+    return total;
+}