akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/improve/extract.js

@@ -13,9 +13,9 @@
  * 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`).
+ *   - Bounded LLM call routed through `callStructured`. Improve-stage
+ *     enablement comes from the active strategy; explicit `akm extract` always
+ *     runs regardless of that stage toggle.
  *   - 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)
@@ -26,30 +26,32 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
-import { resolveStashDir, timestampForFilename } from "../../core/common.js";
-import { getDefaultLlmConfig, getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
+import { timestampForFilename } from "../../core/common.js";
+import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../../core/file-lock.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
+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 { 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 { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.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 { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
-import { chatCompletion } from "../../llm/client.js";
-import { embed } from "../../llm/embedder.js";
-import { tryLlmFeature } from "../../llm/feature-gate.js";
+import { callStructured } from "../../llm/structured-call.js";
 import { sha256Hex } from "../../runtime.js";
 import { getExtractedSessionsMap, getLastExtractRunAt, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../storage/repositories/extract-sessions-repository.js";
-import { createProposal, isProposalSkipped } from "../proposal/repository.js";
+import { isProposalSkipped } from "../proposal/repository.js";
 import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload } from "./extract-prompt.js";
-import { buildHotProbationFrontmatter } from "./hot-probation.js";
-import { resolveProcessEnabled } from "./improve-profiles.js";
-import { applySchemaSimilarityPenalty, loadDerivedLayerEmbeddings, } from "./schema-similarity-gate.js";
+import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
+import { emitProposal } from "./proposal-envelope.js";
+import { createRunContext, resolveRunStashDir } from "./run-context.js";
 import { buildSessionSummaryPrompt, parseSessionSummary, SESSION_SUMMARY_JSON_SCHEMA, sessionMeetsDurationGate, writeSessionAsset, } from "./session-asset.js";
 import { resolveTriageConfig, scoreSessionTriage } from "./triage.js";
 /** Default minimum session duration (minutes) for session indexing (#561). */
@@ -123,20 +125,75 @@ function getExtractSessionLockPath(harness, sessionId, stateDbPath) {
  * extraction outright.
  */
 function acquireExtractSessionLock(lockPath) {
+    const releaseBarrier = tryAcquireMaintenanceBarrier();
+    if (!releaseBarrier)
+        return { proceed: false };
     try {
         fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-        if (tryAcquireLockSync(lockPath, String(process.pid)))
-            return true;
+        let ownership = tryAcquireLockSync(lockPath, createLockPayload());
+        if (ownership)
+            return { proceed: true, ownership };
         const probe = probeLock(lockPath, { staleAfterMs: EXTRACT_SESSION_LOCK_STALE_MS });
         if (probe.state === "held")
-            return false;
-        // absent (released between attempt + probe) or stale → reclaim and retry once.
-        releaseLock(lockPath);
-        return tryAcquireLockSync(lockPath, String(process.pid));
+            return { proceed: false };
+        // Absent (released between attempt + probe) or successfully reclaimed stale lock → retry once.
+        if (probe.state === "stale" && !reclaimStaleLock(lockPath, probe))
+            return { proceed: false };
+        ownership = tryAcquireLockSync(lockPath, createLockPayload());
+        return ownership ? { proceed: true, ownership } : { proceed: false };
     }
     catch {
-        return true;
+        return { proceed: true };
     }
+    finally {
+        releaseBarrier();
+    }
+}
+function cloneAndFreeze(value) {
+    const clone = structuredClone(value);
+    const freeze = (item) => {
+        if (typeof item !== "object" || item === null || Object.isFrozen(item))
+            return;
+        for (const child of Object.values(item))
+            freeze(child);
+        Object.freeze(item);
+    };
+    freeze(clone);
+    return clone;
+}
+/** Resolve standalone extract selection once before discovery, auto iteration, or watch startup. */
+export function resolveStandaloneExtractPlan(config, selection) {
+    if (selection.engine && selection.strategy) {
+        throw new UsageError("--engine and --strategy are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+    }
+    const selected = resolveImproveStrategy(selection.strategy, config);
+    const process = cloneAndFreeze(getImproveProcessConfig("extract", selected.config) ?? {});
+    const invocation = {
+        ...(selection.engine ? { engine: selection.engine } : {}),
+        ...(Object.hasOwn(selection, "timeoutMs") ? { timeoutMs: selection.timeoutMs ?? null } : {}),
+    };
+    const resolved = resolveLlmEngineUse(config, [selected.config, process, invocation], { optional: true });
+    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,
+    };
+    return Object.freeze({
+        strategy: selected.name,
+        engine: resolved.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,
+        embeddingConfig: cloneAndFreeze(config.embedding),
+    });
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
@@ -146,6 +203,12 @@ function acquireExtractSessionLock(lockPath) {
  *
  * Throws UsageError on unparseable input so the CLI surfaces a clear error
  * rather than silently defaulting.
+ *
+ * The recognizer is deliberately CASE-INSENSITIVE and whitespace-tolerant —
+ * `5M` means 5 MINUTES here, diverging from the core grammar's case-sensitive
+ * `M`=months (pinned by tests/commands/goldens-duration-flags.test.ts); only
+ * the unit arithmetic is delegated to the canonical {@link DURATION_UNITS}
+ * table via {@link parseDuration}.
  */
 export function parseSinceArg(value, now = Date.now()) {
     if (!value || value.trim() === "") {
@@ -154,10 +217,9 @@ export function parseSinceArg(value, now = Date.now()) {
     const trimmed = value.trim();
     const relMatch = trimmed.match(/^(\d+)\s*([mhd])$/i);
     if (relMatch) {
-        const n = Number.parseInt(relMatch[1] ?? "0", 10);
-        const unit = (relMatch[2] ?? "h").toLowerCase();
-        const ms = unit === "m" ? n * 60_000 : unit === "h" ? n * 3_600_000 : n * 86_400_000;
-        return now - ms;
+        const ms = parseDuration(`${relMatch[1] ?? "0"}${(relMatch[2] ?? "h").toLowerCase()}`, DURATION_UNITS);
+        if (ms !== null)
+            return now - ms;
     }
     const iso = Date.parse(trimmed);
     if (!Number.isNaN(iso))
@@ -187,31 +249,53 @@ function resolveHarness(type, harnesses) {
  * so the accept-time descriptionQualityValidator passes — same pattern as
  * the consolidate-writer fix at consolidate.ts.
  */
-function buildCandidateProposal(candidate, sourceRef) {
-    const ref = `${candidate.type}:${candidate.name}`;
+function buildCandidateProposal(candidate, sourceRef, sessionAssetRef) {
+    const ref = deriveExtractCandidateRef(candidate, sourceRef);
     // 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,
-        sources: [`session:${sourceRef.harness}:${sourceRef.sessionId}`],
+        ...(sessionAssetRef ? { xrefs: [sessionAssetRef] } : {}),
     };
     if (candidate.type === "lesson" && candidate.when_to_use) {
         fm.when_to_use = candidate.when_to_use;
     }
-    // #615 WS-0: preserve ordered-action + outcome data in frontmatter so the data
-    // survives even if source transcripts are not re-extractable later. The
-    // procedural-compilation feature (detection/compilation) is deferred to 0.10+.
-    if (candidate.orderedActions && candidate.orderedActions.length > 0) {
-        fm.orderedActions = candidate.orderedActions;
-        if (candidate.outcomeData) {
-            fm.outcomeData = candidate.outcomeData;
-        }
-    }
     const content = assembleAsset(fm, candidate.body);
     return { ref, content, description };
 }
+function canonicalSegment(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function deriveExtractCandidateRef(candidate, sourceRef) {
+    const candidateParts = candidate.name.split("/").map(canonicalSegment).filter(Boolean);
+    const leaf = candidateParts.at(-1) ?? "extracted-insight";
+    if (candidate.type === "memory" || candidate.type === "lesson") {
+        const projectName = sourceRef.projectHint?.split(/[\\/]/).filter(Boolean).at(-1);
+        const scope = projectName ? canonicalSegment(projectName) : "";
+        const subdir = candidate.type === "memory" ? "memories" : "lessons";
+        return `${subdir}/${scope ? `${scope}/` : ""}${leaf}`;
+    }
+    return `knowledge/${leaf}`;
+}
+function resolveExtractStandards(stashDir) {
+    const sections = [];
+    const general = resolveStashStandards(stashDir);
+    if (general)
+        sections.push(general);
+    for (const type of ["memory", "lesson", "knowledge"]) {
+        const body = resolveTypeConventions(stashDir, type);
+        if (body)
+            sections.push(`# ${typeConventionRef(type)} (soft per-type conventions — guidance, not enforced)\n${body}`);
+    }
+    return sections.join("\n\n");
+}
 /**
  * Canonicalize a session's content into a single deterministic string for
  * hashing (#602). Each event is rendered `<role>\n<text>` and events are joined
@@ -245,36 +329,32 @@ export function hashSessionContent(data) {
  * 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, minContentChars, 
-// #626 — pre-LLM heuristic triage gate. Default-off (enabled:false) takes the
-// exact pre-change path (no scorer call, no new skipReason).
-// #641 — proceduralAwareFloor is opt-in, DEFAULT OFF.
-triage, sessionIndexing, schemaSimilarityCtx, 
-// #602 — already-extracted skip moved INSIDE processSession: the content hash
-// can only be computed after readSession, so the skip decision lives here. The
-// prior row + bypass flags are threaded in from the caller. Skipping here still
-// costs ZERO LLM calls (the expensive resource #602 protects); only the cheap
-// file read is incurred.
-prior, force, 
-// Stash authoring standards (convention/meta fact bodies) for non-wiki
-// output. Resolved ONCE per run by the caller and threaded in so facts are
-// not re-read per session. Empty string when none exist.
-standardsContext) {
-    const warnings = [];
+/**
+ * The zero-LLM pre-flight gates for one session: read, the #602 content-hash
+ * already-extracted skip, the #595/#596 minContentChars floor, and the #626
+ * heuristic triage gate. Returns a terminal skip result, or the read `data` +
+ * pre-filtered events + content hash to carry into the extraction prompt.
+ * Extracted verbatim from `processSession` — every skip shape/reason is
+ * byte-identical.
+ */
+function runPreLlmSessionGates(args) {
+    const { harness, sessionRef, prior, force, maxTotalChars, minContentChars, triage } = args;
     let data;
     try {
         data = harness.readSession(sessionRef);
     }
     catch (err) {
         return {
-            sessionId: sessionRef.sessionId,
-            harness: harness.name,
-            candidateCount: 0,
-            proposalIds: [],
-            preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
-            warnings: [`readSession failed: ${err instanceof Error ? err.message : String(err)}`],
-            skipped: true,
-            skipReason: "read_failed",
+            skip: {
+                sessionId: sessionRef.sessionId,
+                harness: harness.name,
+                candidateCount: 0,
+                proposalIds: [],
+                preFilter: { inputCount: 0, outputCount: 0, truncatedCount: 0 },
+                warnings: [`readSession failed: ${err instanceof Error ? err.message : String(err)}`],
+                skipped: true,
+                skipReason: "read_failed",
+            },
         };
     }
     // #602 — content-hash skip. Computed on the RAW event stream immediately after
@@ -287,15 +367,17 @@ standardsContext) {
     const contentHash = hashSessionContent(data);
     if (!force && shouldSkipAlreadyExtractedSession(prior, contentHash)) {
         return {
-            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,
+            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,
+            },
         };
     }
     const filtered = preFilterSession(data, {
@@ -312,32 +394,7 @@ standardsContext) {
     const rawContentChars = data.events.reduce((sum, event) => sum + event.text.length, 0);
     if (minContentChars > 0 && rawContentChars < minContentChars) {
         return {
-            sessionId: sessionRef.sessionId,
-            harness: harness.name,
-            candidateCount: 0,
-            proposalIds: [],
-            preFilter: {
-                inputCount: filtered.stats.inputCount,
-                outputCount: filtered.stats.outputCount,
-                truncatedCount: filtered.stats.truncatedCount,
-            },
-            warnings: [],
-            skipped: true,
-            skipReason: "too_short",
-            contentHash,
-        };
-    }
-    // #626 — pre-LLM heuristic triage gate. Runs AFTER minContentChars + the
-    // already-extracted skip check (both in the caller / above), BEFORE the
-    // extraction prompt and the session-asset write. When the session scores below
-    // the configured threshold we triage it out: no chat() call, no session asset,
-    // no proposals. Pure-heuristic — zero added LLM cost. Default-off → skipped.
-    if (triage.enabled) {
-        const t = scoreSessionTriage(data, triage.minScore, {
-            proceduralAwareFloor: triage.proceduralAwareFloor,
-        });
-        if (!t.pass) {
-            return {
+            skip: {
                 sessionId: sessionRef.sessionId,
                 harness: harness.name,
                 candidateCount: 0,
@@ -349,11 +406,91 @@ standardsContext) {
                 },
                 warnings: [],
                 skipped: true,
-                skipReason: "triaged_out",
+                skipReason: "too_short",
                 contentHash,
+            },
+        };
+    }
+    // #626 — pre-LLM heuristic triage gate. Runs AFTER minContentChars + the
+    // already-extracted skip check (both in the caller / above), BEFORE the
+    // extraction prompt and the session-asset write. When the session scores below
+    // the configured threshold we triage it out: no chat() call, no session asset,
+    // no proposals. Pure-heuristic — zero added LLM cost. Default-off → skipped.
+    if (triage.enabled) {
+        const t = scoreSessionTriage(data, triage.minScore);
+        if (!t.pass) {
+            return {
+                skip: {
+                    sessionId: sessionRef.sessionId,
+                    harness: harness.name,
+                    candidateCount: 0,
+                    proposalIds: [],
+                    preFilter: {
+                        inputCount: filtered.stats.inputCount,
+                        outputCount: filtered.stats.outputCount,
+                        truncatedCount: filtered.stats.truncatedCount,
+                    },
+                    warnings: [],
+                    skipped: true,
+                    skipReason: "triaged_out",
+                    contentHash,
+                },
             };
         }
     }
+    return { data, filtered, contentHash };
+}
+/**
+ * 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`
+ * 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;
+    }
+    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: "",
+        });
+    return { llmResult, llmRaw };
+}
+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 warnings = [];
+    const gate = runPreLlmSessionGates({ harness, sessionRef, prior, force, maxTotalChars, minContentChars, triage });
+    if ("skip" in gate)
+        return gate.skip;
+    const { data, filtered, contentHash } = gate;
     const prompt = buildExtractPrompt({
         data,
         events: filtered.events,
@@ -388,16 +525,16 @@ standardsContext) {
         }
         return {};
     };
-    let llmRaw = "";
-    const llmResult = await tryLlmFeature("session_extraction", config, async () => {
-        llmRaw = await chat(llmConfig, [{ role: "user", content: prompt }], {
-            timeoutMs,
-            responseSchema: EXTRACT_JSON_SCHEMA,
-        });
-        return llmRaw;
-    }, "", { timeoutMs });
+    const { llmResult, llmRaw } = await runSessionExtractionLlmCall({
+        config,
+        getLlmConfig,
+        chat,
+        prompt,
+        timeoutMs,
+        signal,
+    });
     if (llmResult === "" && !llmRaw) {
-        // tryLlmFeature took the fallback path (disabled / timeout / error). Return skipped.
+        // The seam took the fallback path (disabled / timeout / error). Return skipped.
         return {
             sessionId: sessionRef.sessionId,
             harness: harness.name,
@@ -416,10 +553,12 @@ standardsContext) {
     }
     const payload = parseExtractPayload(llmRaw);
     const proposalIds = [];
+    // Provenance refs are added only after the cited session asset exists.
+    const sessionAsset = await maybeWriteSessionAsset();
     if (payload.candidates.length === 0) {
         appendEvent({
             eventType: "extract_invoked",
-            ref: `session:${harness.name}:${sessionRef.sessionId}`,
+            ...(sessionAsset.sessionAssetRef ? { ref: sessionAsset.sessionAssetRef } : {}),
             metadata: {
                 outcome: "no_candidates",
                 sessionId: sessionRef.sessionId,
@@ -429,8 +568,7 @@ standardsContext) {
                 preFilterInput: filtered.stats.inputCount,
                 preFilterOutput: filtered.stats.outputCount,
             },
-        }, ctx);
-        const sessionAsset = await maybeWriteSessionAsset();
+        }, eventsCtx);
         return {
             sessionId: sessionRef.sessionId,
             harness: harness.name,
@@ -447,63 +585,41 @@ standardsContext) {
             ...sessionAsset,
         };
     }
-    // WS-3b step 0c: hot-probation intake buffer (#604).
-    // When enabled, system-generated extractions enter captureMode: hot-probation
-    // so they spend ONE consolidation cycle in probation before the deterministic
-    // dedup+quality pass promotes them. Default OFF.
-    // Reads the `default` profile deliberately: this per-session hot-probation
-    // flag lives inside the 18-arg `processSession`, which has no handle to the
-    // active profile, and threading a 19th positional arg for a DEFAULT-OFF flag
-    // isn't worth the param bloat. The extract STAGE toggle (in `akmExtract`,
-    // below) already honors `--profile`.
-    const hotProbationEnabled = getImproveProcessConfig(config, "extract")?.hotProbation?.enabled === true;
+    // §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;
+    }
     for (const candidate of payload.candidates) {
+        const built = buildCandidateProposal(candidate, data.ref, sessionAsset.sessionAssetRef);
         if (dryRun) {
-            proposalIds.push(`dry-run:${candidate.type}:${candidate.name}`);
+            proposalIds.push(`dry-run:${built.ref}`);
             continue;
         }
         try {
-            // WS-3b Step-0b: schema-similarity intake gate. When enabled and the
-            // candidate is a lesson/knowledge whose body embedding is within ε of an
-            // existing derived-layer node, down-prioritize by multiplying confidence by
-            // the penalty. PARITY: schemaSimilarityCtx is null when the flag is off →
-            // applySchemaSimilarityPenalty returns the original confidence untouched and
-            // never embeds. (Logic lives in schema-similarity-gate.ts so it is unit-testable.)
-            const gateResult = await applySchemaSimilarityPenalty(candidate, schemaSimilarityCtx, (text) => schemaSimilarityCtx?.embedFn
-                ? schemaSimilarityCtx.embedFn(text)
-                : embed(text, schemaSimilarityCtx?.embeddingConfig));
-            const effectiveConfidence = gateResult.effectiveConfidence;
-            if (gateResult.warning)
-                warn(gateResult.warning);
-            const { ref, content, description } = buildCandidateProposal(candidate, sessionRef);
-            const result = createProposal(stashDir, {
+            const { ref, content, description } = built;
+            const result = emitProposal({ stashDir, proposalsCtx: ctx }, {
                 ref,
                 source: "extract",
                 sourceRun,
+                // §23.6 fingerprint model-id term (WI-6.4). The LLM already ran for
+                // this session, so the profile is resolvable; guard anyway.
+                ...(extractModelId ? { modelId: extractModelId } : {}),
                 payload: {
                     content,
                     frontmatter: {
                         description,
                         ...(candidate.when_to_use ? { when_to_use: candidate.when_to_use } : {}),
-                        ...(effectiveConfidence !== undefined ? { confidence: effectiveConfidence } : {}),
-                        sources: [`session:${sessionRef.harness}:${sessionRef.sessionId}`],
+                        confidence: candidate.confidence,
+                        ...(sessionAsset.sessionAssetRef ? { xrefs: [sessionAsset.sessionAssetRef] } : {}),
                         evidence: candidate.evidence,
-                        // #615 WS-0: mirror ordered-action + outcome data in the proposal
-                        // frontmatter record so downstream tooling can read it without
-                        // re-parsing the content body. Omitted when not present.
-                        ...(candidate.orderedActions && candidate.orderedActions.length > 0
-                            ? { orderedActions: candidate.orderedActions }
-                            : {}),
-                        ...(candidate.outcomeData ? { outcomeData: candidate.outcomeData } : {}),
-                        // WS-3b step 0c: tag system-generated extractions as hot-probation
-                        // when the feature is enabled. The consolidation pass will exclude
-                        // them from the LLM merge pool until the intake dedup+quality pass
-                        // runs against them. User-explicit `akm remember` (captureMode: hot)
-                        // is unaffected — this only applies to extract-generated proposals.
-                        ...(hotProbationEnabled ? buildHotProbationFrontmatter() : {}),
                     },
                 },
-            }, ctx);
+            });
             if (isProposalSkipped(result)) {
                 warnings.push(`candidate ${candidate.type}:${candidate.name} skipped: ${result.reason}: ${result.message}`);
             }
@@ -517,7 +633,7 @@ standardsContext) {
     }
     appendEvent({
         eventType: "extract_invoked",
-        ref: `session:${harness.name}:${sessionRef.sessionId}`,
+        ...(sessionAsset.sessionAssetRef ? { ref: sessionAsset.sessionAssetRef } : {}),
         metadata: {
             outcome: "candidates_queued",
             sessionId: sessionRef.sessionId,
@@ -528,8 +644,7 @@ standardsContext) {
             preFilterInput: filtered.stats.inputCount,
             preFilterOutput: filtered.stats.outputCount,
         },
-    }, ctx);
-    const sessionAsset = await maybeWriteSessionAsset();
+    }, eventsCtx);
     return {
         sessionId: sessionRef.sessionId,
         harness: harness.name,
@@ -545,191 +660,34 @@ standardsContext) {
         ...sessionAsset,
     };
 }
-// ── Public entrypoint ────────────────────────────────────────────────────────
-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");
-    }
-    const config = options.config ?? loadConfig();
-    const stashDir = options.stashDir ?? resolveStashDir();
-    const dryRun = options.dryRun ?? false;
-    const sourceRun = options.sourceRun ?? `extract-${timestampForFilename()}`;
-    // Read the per-process extract config + enabled-state from the ACTIVE improve
-    // profile when `akmImprove` threaded it; otherwise fall back to the `default`
-    // profile (the explicit `akm extract` path, which has no active profile). This
-    // is what stops a non-default profile's `extract.enabled` from being silently
-    // overridden by the default profile and vice-versa.
-    const activeProfile = options.improveProfile;
-    const extractProcess = activeProfile ? activeProfile.processes?.extract : getImproveProcessConfig(config, "extract");
-    // The `extract.enabled` process toggle gates extract as a STAGE of `akm improve`
-    // (the activeProfile path) — consistent with #593/#594 where the active profile,
-    // not `default`, is the source of truth. An EXPLICIT `akm extract` invocation
-    // (no activeProfile) is a direct user/cron action and always runs; gating it on
-    // the default improve profile's stage toggle was a footgun — dropping extract
-    // from the daily improve profile would silently disable the standalone command.
-    const extractEnabled = activeProfile ? resolveProcessEnabled("extract", activeProfile) : true;
-    // Feature-gate early so we get a clean "skipped because disabled" envelope.
-    if (!extractEnabled) {
-        return {
-            schemaVersion: 1,
-            ok: true,
-            shape: "extract-result",
-            dryRun,
-            type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: [
-                "session_extraction feature disabled — set profiles.improve.default.processes.extract.enabled: true to use",
-            ],
-            durationMs: Date.now() - startMs,
-        };
-    }
-    // Resolve the LLM connection. Priority order:
-    //   1. Options.config.profiles.improve.default.processes.extract.profile
-    //      (per-process override, matches reflect/distill/consolidate)
-    //   2. config.defaults.llm (the default LLM profile)
-    //   3. throw — extract requires an LLM.
-    let llmConfig;
-    const runnerSpec = resolveImproveProcessRunnerFromProfile(extractProcess, config);
-    if (runnerSpec) {
-        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;
-    }
-    else {
-        llmConfig = getDefaultLlmConfig(config) ?? undefined;
-    }
-    if (!llmConfig) {
-        throw new ConfigError("No LLM connection configured for extract. Set profiles.llm + defaults.llm, or set profiles.improve.default.processes.extract.profile to a configured LLM profile.");
-    }
-    // Honor per-process timeoutMs override; fall back to options.timeoutMs; then 60s.
-    const timeoutMs = options.timeoutMs ??
-        (typeof extractProcess?.timeoutMs === "number" ? extractProcess.timeoutMs : undefined) ??
-        60_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
-    // entirely. Set `processes.extract.minContentChars: 0` to disable the gate.
-    const minContentChars = typeof extractProcess?.minContentChars === "number" ? extractProcess.minContentChars : DEFAULT_MIN_CONTENT_CHARS;
-    // Cap on NEW sessions LLM-processed per run; 0 disables. Absent = default.
-    // Bounds per-run wall time / LLM cost so a backlog can't push a run past its
-    // task timeout — the overflow stays unseen and is picked up by later runs.
-    const maxSessionsPerRun = typeof extractProcess?.maxSessionsPerRun === "number"
-        ? extractProcess.maxSessionsPerRun
-        : DEFAULT_MAX_SESSIONS_PER_RUN;
-    // Default discovery window — process config can override the built-in 24h.
-    const effectiveSince = options.since ?? extractProcess?.defaultSince;
-    // #626 — resolve the triage gate config once per run. Default-off → the
-    // per-session path never calls the scorer and emits no telemetry.
-    const triage = resolveTriageConfig(extractProcess);
-    // #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,
+/**
+ * Iterate the discovered candidate sessions: enforce the per-run cap, take the
+ * per-session cross-process lock, dispatch to {@link processSession}, aggregate
+ * the #626 triage counters, and persist each seen-row outcome. Extracted verbatim
+ * from `akmExtract` — the maxSessionsPerRun break, lock/skip accounting, triage
+ * 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;
+    // WI-7.7 §2: run-scoped processSession inputs, resolved once per run.
+    const sessionRunCtx = {
+        harness,
+        stashDir,
+        config,
+        getLlmConfig,
+        chat,
+        ctx: options.ctx,
+        eventsCtx: options.eventsCtx,
+        sourceRun,
+        dryRun,
+        timeoutMs,
+        maxTotalChars,
+        minContentChars,
+        triage,
+        sessionIndexing,
+        signal: options.signal,
+        standardsContext: extractStandardsContext,
     };
-    const harness = resolveHarness(options.type, options.harnesses);
-    if (!harness) {
-        return {
-            schemaVersion: 1,
-            ok: false,
-            shape: "extract-result",
-            dryRun,
-            type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: [`no available harness matches type "${options.type}" (check that the platform is installed)`],
-            durationMs: Date.now() - startMs,
-        };
-    }
-    if (!harness.isAvailable()) {
-        return {
-            schemaVersion: 1,
-            ok: false,
-            shape: "extract-result",
-            dryRun,
-            type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: [`harness ${options.type} is registered but reports not-available (no session data on this machine)`],
-            durationMs: Date.now() - startMs,
-        };
-    }
-    // Decide which sessions to process: explicit sessionId OR discovery via since.
-    let candidates;
-    if (options.sessionId) {
-        const all = harness.listSessions({
-            ...(options.location ? { location: options.location } : {}),
-        });
-        const target = all.find((s) => s.sessionId === options.sessionId);
-        if (!target) {
-            return {
-                schemaVersion: 1,
-                ok: false,
-                shape: "extract-result",
-                dryRun,
-                type: options.type,
-                sessionsProcessed: 0,
-                sessionsSkipped: 0,
-                candidatesCreated: 0,
-                proposals: [],
-                sessions: [],
-                warnings: [`session ${options.sessionId} not found for harness ${options.type}`],
-                durationMs: Date.now() - startMs,
-            };
-        }
-        candidates = [target];
-    }
-    else {
-        // No explicit `--since`/`defaultSince` → default to "since the last run"
-        // (floored at 48h) so an intermittently-online host doesn't lose sessions
-        // that ended while it was off. See {@link resolveDefaultSinceMs}.
-        const sinceMs = effectiveSince
-            ? parseSinceArg(effectiveSince)
-            : resolveDefaultSinceMs(harness.name, startMs, {
-                ...(options.stateDb ? { stateDb: options.stateDb } : {}),
-                ...(options.stateDbPath ? { stateDbPath: options.stateDbPath } : {}),
-                ...(options.skipTracking ? { skipTracking: options.skipTracking } : {}),
-            });
-        candidates = harness.listSessions({
-            sinceMs,
-            ...(options.location ? { location: options.location } : {}),
-        });
-    }
     const sessions = [];
     let processedCount = 0;
     let skippedCount = 0;
@@ -738,51 +696,9 @@ export async function akmExtract(options) {
     let triagePassed = 0;
     let triagedOut = 0;
     const allProposalIds = [];
-    const topLevelWarnings = [];
-    const chat = options.chat ?? chatCompletion;
-    // 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;
-        }
-    }
-    // WS-3b Step-0b: schema-similarity intake gate.
-    // DEFAULT ON since R3 (docs/design/improve-self-learning-analysis.md G5):
-    // extract is the highest-volume acquisition path with no LLM judge, so the
-    // cheap embedding-dedup check (one embed per lesson/knowledge candidate,
-    // fail-open) is the intake quality gate. Opt out via
-    // processes.extract.schemaSimilarity.enabled: false. The gate is inert in
-    // practice when no derived-layer embeddings exist (empty ctx → no penalty).
-    const schemaSimilarityCfg = extractProcess?.schemaSimilarity;
-    let schemaSimilarityCtx = null;
-    if (schemaSimilarityCfg?.enabled !== false) {
-        const derivedEmbeddings = options.schemaSimilarityEmbeddings ?? loadDerivedLayerEmbeddings();
-        schemaSimilarityCtx = {
-            config: { ...schemaSimilarityCfg, enabled: true },
-            derivedEmbeddings,
-            embeddingConfig: config.embedding,
-            embedFn: options.schemaSimilarityEmbedFn,
-        };
-    }
-    // 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 = resolveStashStandards(stashDir);
     for (const summary of candidates) {
+        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
@@ -802,10 +718,11 @@ export async function akmExtract(options) {
         // 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 sessionLockPath;
+        let sessionLockOwnership;
         if (trackingEnabled && !dryRun && !options.stateDb) {
-            sessionLockPath = getExtractSessionLockPath(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath());
-            if (!acquireExtractSessionLock(sessionLockPath)) {
+            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,
@@ -819,9 +736,14 @@ export async function akmExtract(options) {
                 skippedCount += 1;
                 continue;
             }
+            sessionLockOwnership = sessionLock.ownership;
         }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, triage, sessionIndexing, schemaSimilarityCtx, prior, options.force === true, extractStandardsContext);
+            const result = await processSession(sessionRunCtx, {
+                sessionRef: summary,
+                prior,
+                force: options.force === true,
+            });
             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 /
@@ -916,10 +838,332 @@ export async function akmExtract(options) {
             skippedCount += 1;
         }
         finally {
-            if (sessionLockPath)
-                releaseLock(sessionLockPath);
+            if (sessionLockOwnership)
+                releaseLock(sessionLockOwnership);
+        }
+    }
+    return { sessions, processedCount, skippedCount, triageEvaluated, triagePassed, triagedOut, allProposalIds };
+}
+/**
+ * Resolve the run-scoped LLM/engine, budget, triage, and session-indexing
+ * settings for one extract invocation (throwing when no engine is configured).
+ * Extracted verbatim from `akmExtract` — the timeout precedence chain, the
+ * 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) {
+        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;
+    // 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
+    // entirely. Set `processes.extract.minContentChars: 0` to disable the gate.
+    const minContentChars = typeof extractProcess?.minContentChars === "number" ? extractProcess.minContentChars : DEFAULT_MIN_CONTENT_CHARS;
+    // Cap on NEW sessions LLM-processed per run; 0 disables. Absent = default.
+    // Bounds per-run wall time / LLM cost so a backlog can't push a run past its
+    // task timeout — the overflow stays unseen and is picked up by later runs.
+    const maxSessionsPerRun = typeof extractProcess?.maxSessionsPerRun === "number"
+        ? extractProcess.maxSessionsPerRun
+        : DEFAULT_MAX_SESSIONS_PER_RUN;
+    // Default discovery window — process config can override the built-in 24h.
+    const effectiveSince = options.since ?? extractProcess?.defaultSince;
+    // #626 — resolve the triage gate config once per run. Default-off → the
+    // per-session path never calls the scorer and emits no telemetry.
+    const triage = resolveTriageConfig(extractProcess);
+    // #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 `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;
+        }
+        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: "",
+            });
         }
+        return parseSessionSummary(raw);
+    };
+    const sessionIndexing = {
+        enabled: sessionIndexingEnabled,
+        minDurationMinutes: minSessionDuration,
+        generate: options.generateSessionSummary ?? defaultSessionSummaryGenerator,
+    };
+    return {
+        timeoutMs,
+        getLlmConfig,
+        maxTotalChars,
+        minContentChars,
+        maxSessionsPerRun,
+        effectiveSince,
+        triage,
+        sessionIndexing,
+    };
+}
+/**
+ * Resolve the session set to process: the single `--session-id` target (or a
+ * not-found envelope) or the discovery-window listing. Extracted verbatim from
+ * `akmExtract`; the 48h default-since floor and location filter are unchanged.
+ */
+function discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun) {
+    if (options.sessionId) {
+        const all = harness.listSessions({
+            ...(options.location ? { location: options.location } : {}),
+        });
+        const target = all.find((s) => s.sessionId === options.sessionId);
+        if (!target) {
+            return {
+                notFound: {
+                    schemaVersion: 1,
+                    ok: false,
+                    shape: "extract-result",
+                    dryRun,
+                    type: options.type,
+                    sessionsProcessed: 0,
+                    sessionsSkipped: 0,
+                    candidatesCreated: 0,
+                    proposals: [],
+                    sessions: [],
+                    warnings: [`session ${options.sessionId} not found for harness ${options.type}`],
+                    durationMs: Date.now() - startMs,
+                },
+            };
+        }
+        return { candidates: [target] };
     }
+    // No explicit `--since`/`defaultSince` → default to "since the last run"
+    // (floored at 48h) so an intermittently-online host doesn't lose sessions
+    // that ended while it was off. See {@link resolveDefaultSinceMs}.
+    const sinceMs = effectiveSince
+        ? parseSinceArg(effectiveSince)
+        : resolveDefaultSinceMs(harness.name, startMs, {
+            ...(options.stateDb ? { stateDb: options.stateDb } : {}),
+            ...(options.stateDbPath ? { stateDbPath: options.stateDbPath } : {}),
+            ...(options.skipTracking ? { skipTracking: options.skipTracking } : {}),
+        });
+    return {
+        candidates: harness.listSessions({
+            sinceMs,
+            ...(options.location ? { location: options.location } : {}),
+        }),
+    };
+}
+// ── Public entrypoint ────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function buildExtractRunContext(args) {
+    const { options, config, stashDir, dryRun, sourceRun, getLlmConfig } = args;
+    const getRunContextLlmConfig = () => {
+        try {
+            return getLlmConfig();
+        }
+        catch {
+            return null;
+        }
+    };
+    return createRunContext({
+        stashDir,
+        config,
+        eventsCtx: options.eventsCtx ?? {},
+        // Not yet wired into any proposal call site this stage (mirrors
+        // buildImproveRunContext's proposalsCtx comment in improve.ts).
+        proposalsCtx: options.ctx ?? {},
+        getLlmConfig: getRunContextLlmConfig,
+        sourceRun,
+        dryRun,
+        signal: options.signal,
+    });
+}
+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");
+    }
+    const config = options.config ?? loadConfig();
+    const stashDir = resolveRunStashDir(options.stashDir);
+    const dryRun = options.dryRun ?? false;
+    const sourceRun = options.sourceRun ?? `extract-${timestampForFilename()}`;
+    // Read process behavior from the frozen standalone plan or the active improve
+    // strategy. This prevents config changes during watch mode from changing later
+    // triggers and prevents one improve strategy from overriding another.
+    const activeProfile = options.improveProfile ?? (options.resolvedPlan ? undefined : resolveImproveStrategy(undefined, config).config);
+    const extractProcess = options.resolvedPlan?.process ?? getImproveProcessConfig("extract", activeProfile);
+    // The `extract.enabled` process toggle gates extract as a STAGE of `akm improve`
+    // (the activeProfile path) — consistent with #593/#594 where the active profile,
+    // not `default`, is the source of truth. An EXPLICIT `akm extract` invocation
+    // (no activeProfile) is a direct user/cron action and always runs; gating it on
+    // the default improve profile's stage toggle was a footgun — dropping extract
+    // from the daily improve profile would silently disable the standalone command.
+    const extractEnabled = options.resolvedPlan?.enabled ??
+        (options.improveProfile ? resolveProcessEnabled("extract", options.improveProfile) : true);
+    // Feature-gate early so we get a clean "skipped because disabled" envelope.
+    if (!extractEnabled) {
+        return {
+            schemaVersion: 1,
+            ok: true,
+            shape: "extract-result",
+            dryRun,
+            type: options.type,
+            sessionsProcessed: 0,
+            sessionsSkipped: 0,
+            candidatesCreated: 0,
+            proposals: [],
+            sessions: [],
+            warnings: ["extract is disabled by the selected improve strategy"],
+            durationMs: Date.now() - startMs,
+        };
+    }
+    const { timeoutMs, getLlmConfig, 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 harness = resolveHarness(options.type, options.harnesses);
+    if (!harness) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            shape: "extract-result",
+            dryRun,
+            type: options.type,
+            sessionsProcessed: 0,
+            sessionsSkipped: 0,
+            candidatesCreated: 0,
+            proposals: [],
+            sessions: [],
+            warnings: [`no available harness matches type "${options.type}" (check that the platform is installed)`],
+            durationMs: Date.now() - startMs,
+        };
+    }
+    if (!harness.isAvailable()) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            shape: "extract-result",
+            dryRun,
+            type: options.type,
+            sessionsProcessed: 0,
+            sessionsSkipped: 0,
+            candidatesCreated: 0,
+            proposals: [],
+            sessions: [],
+            warnings: [`harness ${options.type} is registered but reports not-available (no session data on this machine)`],
+            durationMs: Date.now() - startMs,
+        };
+    }
+    // Decide which sessions to process: explicit sessionId OR discovery via since.
+    const discovery = discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun);
+    if ("notFound" in discovery)
+        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({
+        candidates,
+        options,
+        harness,
+        seenMap,
+        stateDb,
+        trackingEnabled,
+        dryRun,
+        stashDir,
+        config,
+        getLlmConfig,
+        chat: options.chat,
+        sourceRun,
+        timeoutMs,
+        maxTotalChars,
+        minContentChars,
+        maxSessionsPerRun,
+        triage,
+        sessionIndexing,
+        extractStandardsContext,
+        topLevelWarnings,
+    });
     // Close the state.db connection we opened. Callers that injected stateDb
     // via the test seam own its lifecycle.
     if (stateDb && !options.stateDb) {
@@ -942,13 +1186,18 @@ export async function akmExtract(options) {
                 triagedOut,
                 sourceRun,
             },
-        }, options.ctx);
+        }, options.eventsCtx);
     }
     return {
         schemaVersion: 1,
         ok: true,
         shape: "extract-result",
-        dryRun,
+        // Sourced from ctx (identical value to the local `dryRun` — see the
+        // RunContext construction above) so the constructed RunContext has a
+        // genuine downstream reference in this verb, which currently has no
+        // content-read site to route through ctx.readAsset (see the WI-9.10c
+        // report).
+        dryRun: ctx.dryRun,
         type: options.type,
         sessionsProcessed: processedCount,
         sessionsSkipped: skippedCount,
@@ -975,8 +1224,8 @@ export async function akmExtract(options) {
  * over-/under-count here only affects whether the pass RUNS, never whether a
  * changed session is actually re-processed.
  */
-export function countNewExtractCandidates(config, options = {}) {
-    const extractProcess = getImproveProcessConfig(config, "extract", options.improveProfile);
+export function countNewExtractCandidates(_config, options = {}) {
+    const extractProcess = getImproveProcessConfig("extract", options.improveProfile);
     const effectiveSince = options.since ?? extractProcess?.defaultSince;
     // Mirror akmExtract: when no explicit window is set, default per-harness to
     // "since the last run" (floored at 48h) instead of a fixed 24h. Keeps this