akm-cli 0.9.1 → 0.9.2-alpha.1

package/dist/commands/improve/extract.js

@@ -5,7 +5,7 @@
  * `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)
+ * that reads native session files (claude 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`.
@@ -34,20 +34,20 @@ import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquire
 import { tryAcquireMaintenanceBarrier } from "../../core/maintenance-barrier.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { resolveTypeConventions, typeConventionRef } from "../../core/standards/resolve-type-conventions.js";
-import { getStateDbPath, openStateDatabase, withStateDb } from "../../core/state-db.js";
+import { getStateDbPath, openStateDatabase } from "../../core/state-db.js";
 import { repairTruncatedDescription } from "../../core/text-truncation.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { warn } from "../../core/warn.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
-import { resolveLlmEngineUse } from "../../integrations/agent/engine-resolution.js";
-import { materializeLlmRunnerConnection, resolveImproveProcessRunner, } from "../../integrations/agent/runner.js";
-import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
+import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
-import { callStructured } from "../../llm/structured-call.js";
+import { callStructured, preflightStructuredLlmRunner } from "../../llm/structured-call.js";
 import { sha256Hex } from "../../runtime.js";
 import { getExtractedSessionsMap, getLastExtractRunAt, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../storage/repositories/extract-sessions-repository.js";
+import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { isProposalSkipped } from "../proposal/repository.js";
+import { resolveImproveLlmExecution } from "./execution.js";
 import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { emitProposal } from "./proposal-envelope.js";
@@ -99,21 +99,35 @@ function resolveDefaultSinceMs(harnessName, now, opts) {
     const floor = now - DEFAULT_SINCE_FLOOR_MS;
     if (opts.skipTracking)
         return floor;
+    let snapshot;
     try {
-        return withStateDb((db) => {
-            const lastRun = getLastExtractRunAt(db, harnessName);
-            return lastRun != null ? Math.min(lastRun, floor) : floor;
-        }, { path: opts.stateDbPath, borrowed: opts.stateDb });
+        let db = opts.stateDb;
+        if (!db) {
+            snapshot = openSqliteReadSnapshot(opts.stateDbPath ?? getStateDbPath());
+            db = snapshot;
+        }
+        if (!db)
+            return floor;
+        const lastRun = getLastExtractRunAt(db, harnessName);
+        return lastRun != null ? Math.min(lastRun, floor) : floor;
     }
     catch {
         return floor;
     }
+    finally {
+        snapshot?.close();
+    }
 }
 /** Filesystem-safe per-session lock path, co-located with the state.db. */
 function getExtractSessionLockPath(harness, sessionId, stateDbPath) {
     const safe = `${harness}-${sessionId}`.replace(/[^A-Za-z0-9._-]/g, "_");
     return path.join(path.dirname(stateDbPath), "extract-locks", `extract-${safe}.lock`);
 }
+function extractSessionLockIsUnavailable(harness, sessionId, stateDbPath) {
+    const lockPath = getExtractSessionLockPath(harness, sessionId, stateDbPath);
+    const probe = probeLock(lockPath, { staleAfterMs: EXTRACT_SESSION_LOCK_STALE_MS });
+    return probe.state === "held" || probe.state === "inaccessible";
+}
 /**
  * Try to claim the per-session extract lock so a concurrent extract (e.g. a
  * session-end hook firing `--session-id` while the hourly improve pass runs
@@ -172,27 +186,28 @@ export function resolveStandaloneExtractPlan(config, selection) {
         ...(selection.engine ? { engine: selection.engine } : {}),
         ...(Object.hasOwn(selection, "timeoutMs") ? { timeoutMs: selection.timeoutMs ?? null } : {}),
     };
-    const resolved = resolveLlmEngineUse(config, [selected.config, process, invocation], { optional: true });
+    const resolved = resolveImproveLlmExecution({
+        config,
+        profile: selected.config,
+        process,
+        current: invocation,
+        processName: "extract",
+    });
     if (!resolved) {
         throw new ConfigError("No LLM engine configured for extract. Set defaults.llmEngine, pass --engine, or select an improve strategy with processes.extract.engine.", "LLM_NOT_CONFIGURED");
     }
-    const runner = {
-        kind: "llm",
-        engine: resolved.engine,
-        connection: resolved.connection,
-        ...(resolved.credential ? { credential: resolved.credential } : {}),
-        timeoutMs: resolved.timeoutMs,
-    };
+    const runner = resolved.runner;
     return Object.freeze({
         strategy: selected.name,
-        engine: resolved.engine,
+        engine: runner.engine,
         // `akm extract` is an explicit operation. The strategy supplies behavior,
         // but its improve-stage enablement gate does not disable this command.
         enabled: true,
         process,
         runner: cloneAndFreeze(runner),
-        timeoutMs: resolved.timeoutMs,
+        timeoutMs: Object.hasOwn(runner, "timeoutMs") ? (runner.timeoutMs ?? null) : 600_000,
         embeddingConfig: cloneAndFreeze(config.embedding),
+        ...(resolved.notices.length > 0 ? { notices: cloneAndFreeze(resolved.notices) } : {}),
     });
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
@@ -233,15 +248,7 @@ export function parseSinceArg(value, now = Date.now()) {
  */
 function resolveHarness(type, harnesses) {
     const pool = harnesses ?? getAvailableHarnesses();
-    // #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);
+    return pool.find((h) => h.name === type);
 }
 /**
  * Build the ref + content for a candidate. The body must contain a
@@ -366,19 +373,7 @@ function runPreLlmSessionGates(args) {
     // `--force` overrides it to re-extract a previously-extracted session.
     const contentHash = hashSessionContent(data);
     if (!force && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
-        return {
-            skip: {
-                sessionId: sessionRef.sessionId,
-                harness: harness.name,
-                candidateCount: 0,
-                proposalIds: [],
-                preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
-                warnings: [`already extracted (content unchanged) at ${prior?.processed_at}; pass --force to re-process`],
-                skipped: true,
-                skipReason: "already_extracted",
-                contentHash,
-            },
-        };
+        return { skip: alreadyExtractedResult(harness.name, sessionRef.sessionId, prior, contentHash) };
     }
     const filtered = preFilterSession(data, {
         ...(typeof maxTotalChars === "number" ? { maxTotalChars } : {}),
@@ -440,57 +435,124 @@ function runPreLlmSessionGates(args) {
     }
     return { data, filtered, contentHash };
 }
+function alreadyExtractedResult(harness, sessionId, prior, contentHash) {
+    return {
+        sessionId,
+        harness,
+        candidateCount: 0,
+        proposalIds: [],
+        preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
+        warnings: [`already extracted (content unchanged) at ${prior?.processed_at}; pass --force to re-process`],
+        skipped: true,
+        skipReason: "already_extracted",
+        contentHash,
+    };
+}
+function lockedConcurrentResult(harness, summary) {
+    return {
+        sessionId: summary.sessionId,
+        harness,
+        candidateCount: 0,
+        proposalIds: [],
+        preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
+        warnings: ["concurrent extract holds this session's lock — skipped (handled by the other run)"],
+        skipped: true,
+        skipReason: "locked_concurrent",
+    };
+}
+function planExtractSessions(args) {
+    const { candidates, options, harness, seenMap, maxSessionsPerRun, trackingEnabled, dryRun } = args;
+    const plans = [];
+    let modelCount = 0;
+    for (let index = 0; index < candidates.length; index++) {
+        if (options.signal?.aborted)
+            return { plans, deferredCandidates: candidates.slice(index) };
+        if (!options.sessionId && !options.force && maxSessionsPerRun > 0 && modelCount >= maxSessionsPerRun) {
+            return { plans, deferredCandidates: candidates.slice(index) };
+        }
+        const summary = candidates[index];
+        if (!summary)
+            continue;
+        if (trackingEnabled && !dryRun && !options.stateDb) {
+            if (extractSessionLockIsUnavailable(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath())) {
+                plans.push({ kind: "skip", summary, result: lockedConcurrentResult(harness.name, summary) });
+                continue;
+            }
+        }
+        const gate = runPreLlmSessionGates({
+            harness,
+            sessionRef: summary,
+            prior: seenMap.get(summary.sessionId),
+            force: options.force === true,
+            maxTotalChars: args.maxTotalChars,
+            minContentChars: args.minContentChars,
+            triage: args.triage,
+        });
+        if ("skip" in gate) {
+            plans.push({ kind: "skip", summary, result: gate.skip });
+            continue;
+        }
+        // Reading and classifying a session can take long enough for a concurrent
+        // session-end hook to claim its lock. Re-probe the fully classified model
+        // plan before it consumes a cap slot or forces credential materialization.
+        if (trackingEnabled &&
+            !dryRun &&
+            !options.stateDb &&
+            extractSessionLockIsUnavailable(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath())) {
+            plans.push({ kind: "skip", summary, result: lockedConcurrentResult(harness.name, summary) });
+            continue;
+        }
+        plans.push({ kind: "model", summary, gate });
+        modelCount += 1;
+    }
+    return { plans, deferredCandidates: [] };
+}
 /**
- * The bounded per-session extraction LLM call. Resolves the connection with
- * the same fail-open contract the gated fn had (a `getLlmConfig()` throw —
- * `materializeLlmConnection` can raise ConfigError — takes the skipped path,
- * never propagates), then routes through `callStructured` under the
- * `session_extraction` gate. Returns the seam result plus the `llmRaw`
+ * The bounded per-session extraction LLM call. Routes the already-resolved
+ * symbolic runner through `callStructured` under the `session_extraction`
+ * gate. Invalid configuration escapes before session/proposal state is
+ * persisted. Returns the seam result plus the `llmRaw`
  * side-channel value that distinguishes fallback-took-over from a
  * genuinely-empty response.
  */
 async function runSessionExtractionLlmCall(args) {
-    const { config, getLlmConfig, chat, prompt, timeoutMs, signal } = args;
-    let extractLlm;
-    try {
-        extractLlm = getLlmConfig();
-    }
-    catch {
-        extractLlm = undefined;
-    }
+    const { config, llmRunner, lease, chat, prompt, timeoutMs, signal, onNotices } = args;
     let llmRaw = "";
-    const llmResult = extractLlm === undefined
-        ? ""
-        : await callStructured({
-            feature: "session_extraction",
-            akmConfig: config,
-            config: extractLlm,
-            messages: [{ role: "user", content: prompt }],
-            request: {
-                timeoutMs,
-                responseSchema: EXTRACT_JSON_SCHEMA,
-                ...(signal ? { signal } : {}),
-                ...(chat ? { chat } : {}),
-            },
-            parse: (raw) => {
-                llmRaw = raw ?? "";
-                return llmRaw;
-            },
-            // A transport throw takes the "" fallback with llmRaw left unset —
-            // the same skipped path the gated-fn throw produced before.
-            onError: () => "",
-            fallback: "",
-        });
+    const llmResult = await callStructured({
+        feature: "session_extraction",
+        akmConfig: config,
+        runner: llmRunner,
+        lease,
+        messages: [{ role: "user", content: prompt }],
+        request: {
+            timeoutMs,
+            responseSchema: EXTRACT_JSON_SCHEMA,
+            ...(signal ? { signal } : {}),
+            ...(chat ? { chat } : {}),
+        },
+        onNotices,
+        parse: (raw) => {
+            llmRaw = raw ?? "";
+            return llmRaw;
+        },
+        // A transport throw takes the "" fallback with llmRaw left unset —
+        // the same skipped path the gated-fn throw produced before.
+        onError: () => "",
+        fallback: "",
+    });
     return { llmResult, llmRaw };
 }
+function extractNoticeFields(getNotices) {
+    const notices = getNotices();
+    return notices.length > 0 ? { notices } : {};
+}
 async function processSession(runCtx, session) {
-    const { harness, stashDir, config, getLlmConfig, chat, ctx, eventsCtx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, signal, standardsContext, } = runCtx;
-    const { sessionRef, prior, force } = session;
+    const { harness, stashDir, config, llmRunner, lease, onNotices, getNotices, chat, ctx, eventsCtx, sourceRun, dryRun, timeoutMs, sessionIndexing, signal, standardsContext, } = runCtx;
+    const { sessionRef, gate } = session;
     const warnings = [];
-    const gate = runPreLlmSessionGates({ harness, sessionRef, prior, force, maxTotalChars, minContentChars, triage });
-    if ("skip" in gate)
-        return gate.skip;
     const { data, filtered, contentHash } = gate;
+    if (!lease)
+        throw new TypeError("extract model work requires an operation dispatch lease");
     const prompt = buildExtractPrompt({
         data,
         events: filtered.events,
@@ -508,7 +570,7 @@ async function processSession(runCtx, session) {
         if (!sessionMeetsDurationGate(data, sessionIndexing.minDurationMinutes))
             return {};
         try {
-            const result = await writeSessionAsset(data, stashDir, sessionIndexing.generate);
+            const result = await writeSessionAsset(data, stashDir, (summaryData) => sessionIndexing.generate(summaryData, lease));
             if (result.written) {
                 // Write-path indexing (itself fail-open): standalone `akm extract`
                 // (session-end hook) has no post-loop reindex to pick this file up.
@@ -521,17 +583,21 @@ async function processSession(runCtx, session) {
             }
         }
         catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
             warnings.push(`session asset write failed: ${err instanceof Error ? err.message : String(err)}`);
         }
         return {};
     };
     const { llmResult, llmRaw } = await runSessionExtractionLlmCall({
         config,
-        getLlmConfig,
+        llmRunner,
+        lease,
         chat,
         prompt,
         timeoutMs,
         signal,
+        onNotices,
     });
     if (llmResult === "" && !llmRaw) {
         // The seam took the fallback path (disabled / timeout / error). Return skipped.
@@ -549,6 +615,7 @@ async function processSession(runCtx, session) {
             skipped: true,
             skipReason: "llm_unavailable",
             contentHash,
+            ...extractNoticeFields(getNotices),
         };
     }
     const payload = parseExtractPayload(llmRaw);
@@ -583,17 +650,12 @@ async function processSession(runCtx, session) {
             warnings,
             contentHash,
             ...sessionAsset,
+            ...extractNoticeFields(getNotices),
         };
     }
     // §23.6 fingerprint model-id term: the profile resolved for this session's
     // LLM call (best-effort — an unconfigured profile leaves the term empty).
-    let extractModelId;
-    try {
-        extractModelId = runCtx.getLlmConfig().model;
-    }
-    catch {
-        extractModelId = undefined;
-    }
+    const extractModelId = llmRunner.connection.model;
     for (const candidate of payload.candidates) {
         const built = buildCandidateProposal(candidate, data.ref, sessionAsset.sessionAssetRef);
         if (dryRun) {
@@ -658,8 +720,73 @@ async function processSession(runCtx, session) {
         warnings,
         contentHash,
         ...sessionAsset,
+        ...extractNoticeFields(getNotices),
     };
 }
+function recordExtractSessionOutcome(args) {
+    const { stateDb, trackingEnabled, dryRun, harness, summary, result, sourceRun } = args;
+    if (!trackingEnabled ||
+        !stateDb ||
+        dryRun ||
+        result.skipReason === "already_extracted" ||
+        result.skipReason === "locked_concurrent")
+        return;
+    try {
+        const outcome = result.skipped
+            ? result.skipReason === "read_failed" || result.skipReason === "exception"
+                ? "failed"
+                : "skipped"
+            : result.candidateCount === 0
+                ? "no_candidates"
+                : "candidates_queued";
+        upsertExtractedSession(stateDb, {
+            harness,
+            sessionId: summary.sessionId,
+            processedAt: new Date().toISOString(),
+            sessionEndedAt: summary.endedAt ?? null,
+            outcome,
+            candidateCount: result.candidateCount,
+            proposalCount: result.proposalIds.length,
+            rationale: result.rationaleIfEmpty ?? null,
+            sourceRun,
+            contentHash: result.skipReason === "llm_unavailable" || result.skipReason === "triaged_out"
+                ? null
+                : (result.contentHash ?? null),
+            metadata: {
+                preFilterInputCount: result.preFilter.inputCount,
+                preFilterOutputCount: result.preFilter.outputCount,
+                preFilterTruncatedCount: result.preFilter.truncatedCount,
+                ...(result.skipReason ? { skipReason: result.skipReason } : {}),
+                ...(result.sessionLogPath ? { logPath: result.sessionLogPath } : {}),
+                ...(result.sessionAssetRef ? { sessionAssetRef: result.sessionAssetRef } : {}),
+            },
+        });
+    }
+    catch (err) {
+        warn(`[extract] failed to record session ${summary.sessionId} in state.db: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function accountExtractSessionResult(result, triageEnabled, output) {
+    output.sessions.push(result);
+    if (triageEnabled) {
+        const preempted = result.skipReason === "read_failed" ||
+            result.skipReason === "too_short" ||
+            result.skipReason === "already_extracted" ||
+            result.skipReason === "locked_concurrent";
+        if (!preempted) {
+            output.triageEvaluated += 1;
+            if (result.skipReason === "triaged_out")
+                output.triagedOut += 1;
+            else
+                output.triagePassed += 1;
+        }
+    }
+    if (result.skipped)
+        output.skippedCount += 1;
+    else
+        output.processedCount += 1;
+    output.allProposalIds.push(...result.proposalIds);
+}
 /**
  * Iterate the discovered candidate sessions: enforce the per-run cap, take the
  * per-session cross-process lock, dispatch to {@link processSession}, aggregate
@@ -668,164 +795,137 @@ async function processSession(runCtx, session) {
  * aggregation, and seen-row upsert are byte-identical.
  */
 async function runExtractSessionLoop(args) {
-    const { candidates, options, harness, seenMap, stateDb, trackingEnabled, dryRun, stashDir, config, getLlmConfig, chat, sourceRun, timeoutMs, maxTotalChars, minContentChars, maxSessionsPerRun, triage, sessionIndexing, extractStandardsContext, topLevelWarnings, } = args;
+    const { plans, deferredCandidates, seenMap, options, harness, stateDb, trackingEnabled, dryRun, stashDir, config, llmRunner, lease, onNotices, getNotices, chat, sourceRun, timeoutMs, triage, sessionIndexing, extractStandardsContext, topLevelWarnings, } = args;
     // WI-7.7 §2: run-scoped processSession inputs, resolved once per run.
     const sessionRunCtx = {
         harness,
         stashDir,
         config,
-        getLlmConfig,
+        llmRunner,
+        lease,
+        onNotices,
+        getNotices,
         chat,
         ctx: options.ctx,
         eventsCtx: options.eventsCtx,
         sourceRun,
         dryRun,
         timeoutMs,
-        maxTotalChars,
-        minContentChars,
-        triage,
         sessionIndexing,
         signal: options.signal,
         standardsContext: extractStandardsContext,
     };
-    const sessions = [];
-    let processedCount = 0;
-    let skippedCount = 0;
-    // #626 — per-run triage aggregation counters (counts-only telemetry, AC4).
-    let triageEvaluated = 0;
-    let triagePassed = 0;
-    let triagedOut = 0;
-    const allProposalIds = [];
-    for (const summary of candidates) {
+    const output = {
+        sessions: [],
+        processedCount: 0,
+        skippedCount: 0,
+        triageEvaluated: 0,
+        triagePassed: 0,
+        triagedOut: 0,
+        allProposalIds: [],
+        deferred: 0,
+    };
+    const workPlans = [...plans];
+    let remainingCandidates = deferredCandidates;
+    const refillModelSlot = () => {
+        if (remainingCandidates.length === 0 || options.signal?.aborted)
+            return;
+        const refill = planExtractSessions({
+            candidates: remainingCandidates,
+            options,
+            harness,
+            seenMap,
+            maxTotalChars: args.maxTotalChars,
+            minContentChars: args.minContentChars,
+            maxSessionsPerRun: 1,
+            triage,
+            trackingEnabled,
+            dryRun,
+        });
+        workPlans.push(...refill.plans);
+        remainingCandidates = refill.deferredCandidates;
+    };
+    for (const plan of workPlans) {
         if (options.signal?.aborted)
             break;
-        // #602 — the already-extracted skip moved INTO processSession (the content
-        // hash needs the session body, only available after readSession). The prior
-        // row + bypass flags are threaded through; an unchanged session returns
-        // skipReason 'already_extracted' WITHOUT any LLM call.
-        const prior = seenMap.get(summary.sessionId);
-        // Per-run cap on LLM-processed sessions (skip-tracked seen sessions above
-        // don't count). Single-session / --force modes bypass the cap (explicit
-        // intent). Overflow sessions are left unseen for the next run.
-        if (!options.sessionId && !options.force && maxSessionsPerRun > 0 && processedCount >= maxSessionsPerRun) {
-            topLevelWarnings.push(`Reached maxSessionsPerRun=${maxSessionsPerRun}; ${candidates.length - processedCount - skippedCount} session(s) deferred to a later run.`);
-            break;
+        const { summary } = plan;
+        if (plan.kind === "skip") {
+            accountExtractSessionResult(plan.result, triage.enabled, output);
+            recordExtractSessionOutcome({
+                stateDb,
+                trackingEnabled,
+                dryRun,
+                harness: harness.name,
+                summary,
+                result: plan.result,
+                sourceRun,
+            });
+            continue;
         }
-        // Q5 — per-session lock so two concurrent extracts (e.g. a session-end hook
-        // firing `--session-id` while the hourly improve discovery pass runs) can't
-        // both LLM-process the SAME session. The holder records the outcome; a
-        // second run skips without any LLM call. Engaged only for real cross-process
-        // runs (those that open their own state.db): dry-run is read-only, an
-        // injected `stateDb` handle is an in-process/test scenario with no cross-
-        // process race, and skip-tracking-off opts out entirely.
         let sessionLockOwnership;
         if (trackingEnabled && !dryRun && !options.stateDb) {
             const sessionLockPath = getExtractSessionLockPath(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath());
             const sessionLock = acquireExtractSessionLock(sessionLockPath);
             if (!sessionLock.proceed) {
-                sessions.push({
-                    sessionId: summary.sessionId,
-                    harness: harness.name,
-                    candidateCount: 0,
-                    proposalIds: [],
-                    preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
-                    warnings: ["concurrent extract holds this session's lock — skipped (handled by the other run)"],
-                    skipped: true,
-                    skipReason: "locked_concurrent",
-                });
-                skippedCount += 1;
+                accountExtractSessionResult(lockedConcurrentResult(harness.name, summary), triage.enabled, output);
+                refillModelSlot();
                 continue;
             }
             sessionLockOwnership = sessionLock.ownership;
         }
         try {
-            const result = await processSession(sessionRunCtx, {
+            // Planning stays read-only so a credential failure creates no state. Once
+            // this run owns the session lock, read and gate the session again: the log
+            // may have grown, become too short after replacement, or been completed by
+            // another extractor between the planning snapshot and acquisition.
+            const currentPrior = stateDb
+                ? getExtractedSessionsMap(stateDb, harness.name, [summary.sessionId]).get(summary.sessionId)
+                : seenMap.get(summary.sessionId);
+            const executionGate = runPreLlmSessionGates({
+                harness,
                 sessionRef: summary,
-                prior,
+                prior: currentPrior,
                 force: options.force === true,
+                maxTotalChars: args.maxTotalChars,
+                minContentChars: args.minContentChars,
+                triage,
             });
-            sessions.push(result);
-            // #626 — triage aggregation. A session reached the triage gate only when it
-            // was NOT already preempted by an earlier skip (read_failed / too_short /
-            // already_extracted handled above the processSession call). When triage is
-            // enabled, processSession either triages-out (skipReason 'triaged_out') or
-            // proceeds past the gate — both count as "evaluated".
-            if (triage.enabled) {
-                const preemptedBeforeTriage = result.skipReason === "read_failed" ||
-                    result.skipReason === "too_short" ||
-                    result.skipReason === "already_extracted";
-                if (!preemptedBeforeTriage) {
-                    triageEvaluated += 1;
-                    if (result.skipReason === "triaged_out")
-                        triagedOut += 1;
-                    else
-                        triagePassed += 1;
-                }
-            }
-            if (result.skipped)
-                skippedCount += 1;
-            else
-                processedCount += 1;
-            allProposalIds.push(...result.proposalIds);
-            // Persist outcome so the next run skips this session unless its content
-            // changes. We only track non-dry-run paths — dry-run is for inspection
-            // and should never poison the seen-table. #602: an `already_extracted`
-            // skip is a no-op (the row already carries the matching hash), so don't
-            // re-write it — that keeps `processed_at` stable across unchanged runs.
-            if (trackingEnabled && stateDb && !dryRun && result.skipReason !== "already_extracted") {
-                try {
-                    const outcome = result.skipped
-                        ? result.skipReason === "read_failed" || result.skipReason === "exception"
-                            ? "failed"
-                            : "skipped"
-                        : result.candidateCount === 0
-                            ? "no_candidates"
-                            : "candidates_queued";
-                    upsertExtractedSession(stateDb, {
-                        harness: harness.name,
-                        sessionId: summary.sessionId,
-                        processedAt: new Date().toISOString(),
-                        sessionEndedAt: summary.endedAt ?? null,
-                        outcome,
-                        candidateCount: result.candidateCount,
-                        proposalCount: result.proposalIds.length,
-                        rationale: result.rationaleIfEmpty ?? null,
-                        sourceRun,
-                        // #602 — persist the freshly computed content hash so the NEXT run
-                        // can compare byte-for-byte. read_failed (before hash) → null, which
-                        // keeps the row eligible for retry (matches failed-row semantics).
-                        // R4 — llm_unavailable (LLM was down) and triaged_out (deferred by the
-                        // triage gate) are transient outcomes: persist null so the null-hash
-                        // retry re-processes them on a later run instead of pinning them as
-                        // "seen" forever against the current byte content.
-                        contentHash: result.skipReason === "llm_unavailable" || result.skipReason === "triaged_out"
-                            ? null
-                            : (result.contentHash ?? null),
-                        metadata: {
-                            preFilterInputCount: result.preFilter.inputCount,
-                            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 } : {}),
-                        },
-                    });
-                }
-                catch (err) {
-                    // Tracking failure must not abort the run — log + continue.
-                    const msg = err instanceof Error ? err.message : String(err);
-                    warn(`[extract] failed to record session ${summary.sessionId} in state.db: ${msg}`);
-                }
+            if ("skip" in executionGate) {
+                accountExtractSessionResult(executionGate.skip, triage.enabled, output);
+                recordExtractSessionOutcome({
+                    stateDb,
+                    trackingEnabled,
+                    dryRun,
+                    harness: harness.name,
+                    summary,
+                    result: executionGate.skip,
+                    sourceRun,
+                });
+                refillModelSlot();
+                continue;
             }
+            const result = await processSession(sessionRunCtx, {
+                sessionRef: summary,
+                gate: executionGate,
+            });
+            accountExtractSessionResult(result, triage.enabled, output);
+            recordExtractSessionOutcome({
+                stateDb,
+                trackingEnabled,
+                dryRun,
+                harness: harness.name,
+                summary,
+                result,
+                sourceRun,
+            });
         }
         catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
             const msg = err instanceof Error ? err.message : String(err);
             warn(`[extract] session ${summary.sessionId} threw: ${msg}`);
             topLevelWarnings.push(`session ${summary.sessionId} threw: ${msg}`);
-            sessions.push({
+            accountExtractSessionResult({
                 sessionId: summary.sessionId,
                 harness: harness.name,
                 candidateCount: 0,
@@ -834,15 +934,16 @@ async function runExtractSessionLoop(args) {
                 warnings: [msg],
                 skipped: true,
                 skipReason: "exception",
-            });
-            skippedCount += 1;
+                ...extractNoticeFields(getNotices),
+            }, triage.enabled, output);
         }
         finally {
             if (sessionLockOwnership)
                 releaseLock(sessionLockOwnership);
         }
     }
-    return { sessions, processedCount, skippedCount, triageEvaluated, triagePassed, triagedOut, allProposalIds };
+    output.deferred = remainingCandidates.length;
+    return output;
 }
 /**
  * Resolve the run-scoped LLM/engine, budget, triage, and session-indexing
@@ -851,25 +952,43 @@ async function runExtractSessionLoop(args) {
  * session-summary generator seam, and the default resolutions are byte-identical.
  */
 function resolveExtractRunConfig(options, config, extractProcess, activeProfile) {
-    // Improve supplies its invocation-owned connection. Standalone extract
-    // resolves the selected process engine, then defaults.llmEngine.
-    const runnerSpec = options.resolvedPlan
-        ? options.resolvedPlan.runner
-        : resolveImproveProcessRunner(activeProfile, "extract", config);
-    const fixedLlmConfig = options.resolvedPlan ? undefined : options.llmConfig;
-    if (!runnerSpec && !fixedLlmConfig) {
+    const executionNotices = new Map();
+    const onNotices = (notices) => {
+        for (const notice of notices)
+            executionNotices.set(JSON.stringify(notice), notice);
+    };
+    const getNotices = () => Object.freeze([...executionNotices.values()]);
+    // Improve supplies its invocation-owned symbolic runner. Standalone extract
+    // resolves the selected process engine through the shared execution planner.
+    let llmRunner;
+    if (options.resolvedPlan) {
+        llmRunner = options.resolvedPlan.runner;
+        onNotices(options.resolvedPlan.notices ?? []);
+    }
+    else if (options.llmRunner) {
+        llmRunner = options.llmRunner;
+    }
+    else {
+        const resolved = resolveImproveLlmExecution({
+            config,
+            profile: activeProfile,
+            process: extractProcess,
+            processName: "extract",
+        });
+        llmRunner = resolved?.runner;
+        if (resolved)
+            onNotices(resolved.notices);
+    }
+    if (!llmRunner) {
         throw new ConfigError("No LLM engine configured for extract. Set defaults.llmEngine or improve.strategies.<name>.processes.extract.engine.", "LLM_NOT_CONFIGURED");
     }
     const timeoutMs = options.resolvedPlan
         ? options.resolvedPlan.timeoutMs
         : Object.hasOwn(options, "timeoutMs")
             ? (options.timeoutMs ?? null)
-            : runnerSpec?.timeoutMs !== undefined
-                ? runnerSpec.timeoutMs
-                : fixedLlmConfig && Object.hasOwn(fixedLlmConfig, "timeoutMs")
-                    ? (fixedLlmConfig.timeoutMs ?? null)
-                    : 600_000;
-    const getLlmConfig = () => runnerSpec ? materializeLlmRunnerConnection(runnerSpec) : fixedLlmConfig;
+            : Object.hasOwn(llmRunner, "timeoutMs")
+                ? (llmRunner.timeoutMs ?? null)
+                : 600_000;
     // Pre-filter budget — process config can raise it for large-context models.
     const maxTotalChars = typeof extractProcess?.maxTotalChars === "number" ? extractProcess.maxTotalChars : undefined;
     // #595/#596 — minimum raw session size; sessions below it skip the LLM call
@@ -899,36 +1018,28 @@ function resolveExtractRunConfig(options, config, extractProcess, activeProfile)
     // same fail-open `callStructured` seam as the rest of extract. Returns
     // `undefined` on disablement / timeout / error so no asset is written.
     // Tests inject a fake.
-    const defaultSessionSummaryGenerator = async (data) => {
-        // Same fail-open contract as the per-session call: a getLlmConfig()
-        // throw takes the "" fallback rather than propagating.
-        let summaryLlm;
-        try {
-            summaryLlm = getLlmConfig();
-        }
-        catch {
-            summaryLlm = undefined;
-        }
+    const defaultSessionSummaryGenerator = async (data, lease) => {
         let raw = "";
-        if (summaryLlm !== undefined) {
-            await callStructured({
-                feature: "session_extraction",
-                akmConfig: config,
-                config: summaryLlm,
-                messages: [{ role: "user", content: buildSessionSummaryPrompt(data) }],
-                request: {
-                    timeoutMs,
-                    responseSchema: SESSION_SUMMARY_JSON_SCHEMA,
-                    ...(options.chat ? { chat: options.chat } : {}),
-                },
-                parse: (r) => {
-                    raw = r ?? "";
-                    return raw;
-                },
-                onError: () => "",
-                fallback: "",
-            });
-        }
+        await callStructured({
+            feature: "session_extraction",
+            akmConfig: config,
+            runner: llmRunner,
+            ...(lease ? { lease } : {}),
+            messages: [{ role: "user", content: buildSessionSummaryPrompt(data) }],
+            request: {
+                timeoutMs,
+                responseSchema: SESSION_SUMMARY_JSON_SCHEMA,
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(options.chat ? { chat: options.chat } : {}),
+            },
+            onNotices,
+            parse: (r) => {
+                raw = r ?? "";
+                return raw;
+            },
+            onError: () => "",
+            fallback: "",
+        });
         return parseSessionSummary(raw);
     };
     const sessionIndexing = {
@@ -938,7 +1049,9 @@ function resolveExtractRunConfig(options, config, extractProcess, activeProfile)
     };
     return {
         timeoutMs,
-        getLlmConfig,
+        llmRunner,
+        onNotices,
+        getNotices,
         maxTotalChars,
         minContentChars,
         maxSessionsPerRun,
@@ -999,30 +1112,11 @@ function discoverExtractCandidates(options, harness, effectiveSince, startMs, dr
 /**
  * WI-9.10: build one `akm extract` run's {@link RunContext} from values
  * `akmExtract` has already resolved by the time it calls this (config,
- * stashDir, dryRun, sourceRun, and `resolveExtractRunConfig`'s own
- * `getLlmConfig`) — no second config load, no new db handle.
- *
- * `RunContext.getLlmConfig` is typed `() => LlmConnectionConfig | null`, but
- * extract's own resolved `getLlmConfig` returns `LlmProfileConfig` (a
- * superset — `supportsJsonSchema` — of `LlmConnectionConfig`) and, per its
- * documented fail-open contract, MAY THROW (`materializeLlmConnection` can
- * raise ConfigError) rather than return null; every existing caller in this
- * file wraps it in try/catch for exactly that reason. The thin closure below
- * adapts at the boundary: it derives from the SAME already-resolved
- * runner/profile (this doesn't widen `RunContext.getLlmConfig`'s type), and —
- * matching the file's own fail-open contract — coalesces a throw to `null`
- * instead of propagating.
+ * stashDir, dryRun, sourceRun, and `resolveExtractRunConfig`'s symbolic runner)
+ * — no second config load, credential materialization, or new db handle.
  */
 function buildExtractRunContext(args) {
-    const { options, config, stashDir, dryRun, sourceRun, getLlmConfig } = args;
-    const getRunContextLlmConfig = () => {
-        try {
-            return getLlmConfig();
-        }
-        catch {
-            return null;
-        }
-    };
+    const { options, config, stashDir, dryRun, sourceRun, llmRunner } = args;
     return createRunContext({
         stashDir,
         config,
@@ -1030,16 +1124,71 @@ function buildExtractRunContext(args) {
         // Not yet wired into any proposal call site this stage (mirrors
         // buildImproveRunContext's proposalsCtx comment in improve.ts).
         proposalsCtx: options.ctx ?? {},
-        getLlmConfig: getRunContextLlmConfig,
+        getLlmRunner: () => llmRunner,
         sourceRun,
         dryRun,
         signal: options.signal,
     });
 }
+function loadExtractSeenMapReadOnly(args) {
+    const { options, harness, candidates, trackingEnabled, warnings } = args;
+    if (!trackingEnabled || candidates.length === 0)
+        return new Map();
+    let snapshot;
+    try {
+        if (!options.stateDb)
+            snapshot = openSqliteReadSnapshot(options.stateDbPath ?? getStateDbPath());
+        const db = options.stateDb ?? snapshot;
+        return db
+            ? getExtractedSessionsMap(db, harness, candidates.map((candidate) => candidate.sessionId))
+            : new Map();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        warn(`[extract] state.db snapshot unavailable, planning without skip-tracking: ${msg}`);
+        warnings.push(`state.db snapshot unavailable: ${msg}`);
+        return new Map();
+    }
+    finally {
+        snapshot?.close();
+    }
+}
+function openExtractLiveStateDb(args) {
+    const { options, trackingEnabled, hasModelWork, dryRun, warnings } = args;
+    if (!trackingEnabled)
+        return undefined;
+    if (options.stateDb)
+        return options.stateDb;
+    if (!hasModelWork || dryRun)
+        return undefined;
+    try {
+        return openStateDatabase(options.stateDbPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        warn(`[extract] state.db unavailable, processing without skip-tracking: ${msg}`);
+        warnings.push(`state.db unavailable: ${msg}`);
+        return undefined;
+    }
+}
+function emitExtractTriageEvent(args) {
+    const { modelPlanCount, triageEnabled, result, sourceRun, eventsCtx } = args;
+    if (modelPlanCount === 0 || !triageEnabled || result.triageEvaluated === 0)
+        return;
+    appendEvent({
+        eventType: "extract_triaged",
+        metadata: {
+            evaluated: result.triageEvaluated,
+            passed: result.triagePassed,
+            triagedOut: result.triagedOut,
+            sourceRun,
+        },
+    }, eventsCtx);
+}
 export async function akmExtract(options) {
     const startMs = Date.now();
     if (!options.type || options.type.trim() === "") {
-        throw new UsageError("--type is required. Pass a harness name (e.g. --type claude-code).", "MISSING_REQUIRED_ARGUMENT");
+        throw new UsageError("--type is required. Pass a harness name (e.g. --type claude).", "MISSING_REQUIRED_ARGUMENT");
     }
     const config = options.config ?? loadConfig();
     const stashDir = resolveRunStashDir(options.stashDir);
@@ -1075,10 +1224,10 @@ export async function akmExtract(options) {
             durationMs: Date.now() - startMs,
         };
     }
-    const { timeoutMs, getLlmConfig, maxTotalChars, minContentChars, maxSessionsPerRun, effectiveSince, triage, sessionIndexing, } = resolveExtractRunConfig(options, config, extractProcess, activeProfile);
+    const { timeoutMs, llmRunner, onNotices, getNotices, maxTotalChars, minContentChars, maxSessionsPerRun, effectiveSince, triage, sessionIndexing, } = resolveExtractRunConfig(options, config, extractProcess, activeProfile);
     // WI-9.10: construct this run's RunContext (extracted to
     // buildExtractRunContext to keep akmExtract under the fn-size bar — R31).
-    const ctx = buildExtractRunContext({ options, config, stashDir, dryRun, sourceRun, getLlmConfig });
+    const ctx = buildExtractRunContext({ options, config, stashDir, dryRun, sourceRun, llmRunner });
     const harness = resolveHarness(options.type, options.harnesses);
     if (!harness) {
         return {
@@ -1118,76 +1267,94 @@ export async function akmExtract(options) {
         return discovery.notFound;
     const candidates = discovery.candidates;
     const topLevelWarnings = [];
-    // Open state.db once for the run and bulk-load seen-rows for the candidate
-    // set so we can decide skip/process in O(1) per session. Tracking is opt-out
-    // via options.skipTracking (used by tests + one-shot debug calls).
     const trackingEnabled = options.skipTracking !== true;
-    let stateDb;
-    let seenMap = new Map();
-    if (trackingEnabled && candidates.length > 0) {
-        try {
-            stateDb = options.stateDb ?? openStateDatabase(options.stateDbPath);
-            seenMap = getExtractedSessionsMap(stateDb, harness.name, candidates.map((c) => c.sessionId));
-        }
-        catch (err) {
-            // state.db open is best-effort — log and proceed without skip-tracking
-            // so a transient sqlite error never blocks the actual extraction.
-            const msg = err instanceof Error ? err.message : String(err);
-            warn(`[extract] state.db unavailable, processing without skip-tracking: ${msg}`);
-            topLevelWarnings.push(`state.db unavailable: ${msg}`);
-            stateDb = undefined;
-        }
-    }
-    // Stash authoring standards (convention/meta fact bodies) for non-wiki
-    // extract output. Resolved ONCE per run and threaded into each session's
-    // prompt so facts are not re-read per session.
-    const extractStandardsContext = resolveExtractStandards(stashDir);
-    const { sessions, processedCount, skippedCount, triageEvaluated, triagePassed, triagedOut, allProposalIds } = await runExtractSessionLoop({
+    const seenMap = loadExtractSeenMapReadOnly({
+        options,
+        harness: harness.name,
+        candidates,
+        trackingEnabled,
+        warnings: topLevelWarnings,
+    });
+    const planned = planExtractSessions({
         candidates,
         options,
         harness,
         seenMap,
-        stateDb,
-        trackingEnabled,
-        dryRun,
-        stashDir,
-        config,
-        getLlmConfig,
-        chat: options.chat,
-        sourceRun,
-        timeoutMs,
         maxTotalChars,
         minContentChars,
         maxSessionsPerRun,
         triage,
-        sessionIndexing,
-        extractStandardsContext,
-        topLevelWarnings,
+        trackingEnabled,
+        dryRun,
     });
-    // Close the state.db connection we opened. Callers that injected stateDb
-    // via the test seam own its lifecycle.
-    if (stateDb && !options.stateDb) {
-        try {
-            stateDb.close();
-        }
-        catch {
-            // best-effort close
+    const modelPlanCount = planned.plans.filter((plan) => plan.kind === "model").length;
+    // Eligible dry-runs still dispatch to produce their candidate preview. Only
+    // deterministic no-work plans are credential-free. Materialize once after
+    // every read-only gate and before opening live state or acquiring a lock.
+    const dispatchLease = modelPlanCount > 0 ? await preflightStructuredLlmRunner(llmRunner) : undefined;
+    let stateDb;
+    let loopResult;
+    try {
+        stateDb = openExtractLiveStateDb({
+            options,
+            trackingEnabled,
+            hasModelWork: modelPlanCount > 0,
+            dryRun,
+            warnings: topLevelWarnings,
+        });
+        // Stash authoring standards (convention/meta fact bodies) for non-wiki
+        // extract output. Resolved ONCE per run and threaded into each session's
+        // prompt so facts are not re-read per session.
+        const extractStandardsContext = modelPlanCount > 0 ? resolveExtractStandards(stashDir) : "";
+        loopResult = await runExtractSessionLoop({
+            plans: planned.plans,
+            deferredCandidates: planned.deferredCandidates,
+            seenMap,
+            options,
+            harness,
+            stateDb,
+            trackingEnabled,
+            dryRun,
+            stashDir,
+            config,
+            llmRunner,
+            lease: dispatchLease,
+            onNotices,
+            getNotices,
+            chat: options.chat,
+            sourceRun,
+            timeoutMs,
+            maxTotalChars,
+            minContentChars,
+            triage,
+            sessionIndexing,
+            extractStandardsContext,
+            topLevelWarnings,
+        });
+    }
+    finally {
+        if (stateDb && !options.stateDb) {
+            try {
+                stateDb.close();
+            }
+            catch {
+                // best-effort close
+            }
         }
+        if (dispatchLease)
+            disposeLoweredExecutionDispatchLease(dispatchLease);
     }
-    // #626 — counts-only triage telemetry (AC4). Exactly ONE aggregated event per
-    // run, emitted only when the gate was enabled and actually evaluated at least
-    // one session. No per-session events (avoids the log-spam the issue warns of).
-    if (triage.enabled && triageEvaluated > 0) {
-        appendEvent({
-            eventType: "extract_triaged",
-            metadata: {
-                evaluated: triageEvaluated,
-                passed: triagePassed,
-                triagedOut,
-                sourceRun,
-            },
-        }, options.eventsCtx);
+    const { sessions, processedCount, skippedCount, allProposalIds } = loopResult;
+    if (loopResult.deferred > 0) {
+        topLevelWarnings.push(`Reached maxSessionsPerRun=${maxSessionsPerRun}; ${loopResult.deferred} session(s) deferred to a later run.`);
     }
+    emitExtractTriageEvent({
+        modelPlanCount,
+        triageEnabled: triage.enabled,
+        result: loopResult,
+        sourceRun,
+        eventsCtx: options.eventsCtx,
+    });
     return {
         schemaVersion: 1,
         ok: true,
@@ -1206,6 +1373,7 @@ export async function akmExtract(options) {
         sessions,
         warnings: topLevelWarnings,
         durationMs: Date.now() - startMs,
+        ...(getNotices().length > 0 ? { notices: getNotices() } : {}),
     };
 }
 /**
@@ -1241,10 +1409,21 @@ export function countNewExtractCandidates(_config, options = {}) {
                 resolveDefaultSinceMs(harness.name, Date.now(), {
                     ...(options.stateDb ? { stateDb: options.stateDb } : {}),
                     ...(options.stateDbPath ? { stateDbPath: options.stateDbPath } : {}),
+                    ...(options.readOnly && !options.stateDb ? { skipTracking: true } : {}),
                 });
-            const candidates = harness.listSessions({ sinceMs });
+            const candidates = harness.listSessions({
+                sinceMs,
+                ...(options.readOnly ? { isolatedSnapshot: true } : {}),
+            });
             if (candidates.length === 0)
                 continue;
+            // A dry planner with no pre-existing state database has no seen-session
+            // ledger by definition. Count the discovered sessions directly instead
+            // of creating state.db merely to prove that it is empty.
+            if (options.readOnly && !stateDb) {
+                total += candidates.length;
+                continue;
+            }
             let seenMap = new Map();
             try {
                 if (!stateDb) {