akm-cli 0.8.6 → 0.8.14

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

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

package/dist/commands/{improve-auto-accept.js → improve/improve-auto-accept.js}

@@ -1,10 +1,10 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { loadConfig } from "../core/config";
-import { appendEvent } from "../core/events";
-import { promoteProposal } from "../core/proposals";
-import { info, warn } from "../core/warn";
+import { loadConfig } from "../../core/config/config.js";
+import { appendEvent } from "../../core/events.js";
+import { info, warn } from "../../core/warn.js";
+import { promoteProposal, recordGateDecision } from "../proposal/validators/proposals.js";
 // ---------------------------------------------------------------------------
 // Gate implementation
 // ---------------------------------------------------------------------------
@@ -26,14 +26,40 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
     }
     const effectiveThreshold = Math.max(cfg.globalThreshold, cfg.minimumThreshold ?? 0) / 100;
     const resolvedConfig = typeof cfg.config === "function" ? cfg.config() : cfg.config;
+    const gateLabel = `improve:${cfg.phase}`;
+    // #577: stamp the gate's verdict onto each proposal so `akm proposal show`
+    // can explain why a proposal is pending (e.g. "deferred: below-threshold,
+    // 0.72 < 0.90"). Best-effort — a recording failure must never abort the gate.
+    const stamp = (proposalId, decision) => {
+        try {
+            recordGateDecision(cfg.stashDir, proposalId, decision);
+        }
+        catch (err) {
+            warn(`[improve] ${cfg.phase} failed to record gate decision for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
     for (const candidate of candidates) {
         const { proposalId, confidence } = candidate;
         if (confidence === undefined || confidence < effectiveThreshold) {
+            stamp(proposalId, {
+                outcome: "deferred",
+                reason: confidence === undefined ? "no-confidence" : "below-threshold",
+                ...(confidence !== undefined ? { confidence } : {}),
+                thresholds: { autoAccept: effectiveThreshold },
+                gate: gateLabel,
+            });
             result.skipped.push(proposalId);
             continue;
         }
         try {
             const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {}, undefined);
+            stamp(promotion.proposal.id, {
+                outcome: "auto-accepted",
+                reason: "above-threshold",
+                confidence,
+                thresholds: { autoAccept: effectiveThreshold },
+                gate: gateLabel,
+            });
             appendEvent({
                 eventType: "promoted",
                 ref: promotion.ref,

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

@@ -3,16 +3,16 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, parseAutoAcceptFlag, parseNonNegativeIntFlag, parsePositiveIntFlag } from "../cli/parse-args";
-import { output, runWithJsonErrors } from "../cli/shared";
-import { loadConfig } from "../core/config";
-import { UsageError } from "../core/errors";
-import { getCacheDir } from "../core/paths";
-import { clearLogFile, setLogFile } from "../core/warn";
-import { resolveSourceEntries } from "../indexer/search-source";
-import { getHyphenatedArg, getHyphenatedBoolean, parseFlagValue } from "../output/context";
-import { akmImprove } from "./improve";
-import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file";
+import { getStringArg, parseAutoAcceptFlag, parseNonNegativeIntFlag, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { getCacheDir } from "../../core/paths.js";
+import { clearLogFile, setLogFile } from "../../core/warn.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { getHyphenatedArg, getHyphenatedBoolean, parseFlagValue } from "../../output/context.js";
+import { akmImprove } from "./improve.js";
+import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file.js";
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
@@ -144,20 +144,41 @@ export const improveCommand = defineCommand({
                     process.stderr.write(`warning: failed to persist terminated improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             };
-            const sigtermHandler = () => {
-                persistTerminated("SIGTERM");
-                process.stderr.write(`[improve] received SIGTERM; recorded terminated run ${runId}\n`);
-                process.exit(143);
+            // M5 (code-health round 2): signal -> {exit code, reason, ack message}
+            // as an explicit table instead of three near-identical handlers. The
+            // persist of the terminated-run row MUST complete before process.exit so
+            // a SIGTERM'd run (e.g. cron timeout) always leaves a row in
+            // improve_runs. recordTerminatedImproveRun is fully synchronous
+            // (bun:sqlite writes are sync), so the in-line call below blocks until
+            // the row is flushed before we exit.
+            const SIGNAL_TABLE = {
+                SIGTERM: { code: 143, reason: "SIGTERM", ack: true },
+                SIGINT: { code: 130, reason: "SIGINT", ack: true },
+                SIGHUP: { code: 129, reason: "SIGHUP", ack: false },
             };
-            const sigintHandler = () => {
-                persistTerminated("SIGINT");
-                process.stderr.write(`[improve] received SIGINT; recorded terminated run ${runId}\n`);
-                process.exit(130);
-            };
-            const sighupHandler = () => {
-                persistTerminated("SIGHUP");
-                process.exit(129);
+            const makeSignalHandler = (sig) => () => {
+                const { code, reason, ack } = SIGNAL_TABLE[sig];
+                // Hard-exit fallback: if the synchronous persist ever hangs (e.g. a
+                // stuck sqlite lock under contention), the watchdog still exits with
+                // the correct code instead of leaving a zombie process. .unref() keeps
+                // the timer from holding the loop open on the normal (fast) path.
+                const watchdog = setTimeout(() => process.exit(code), 2000);
+                if (typeof watchdog.unref === "function")
+                    watchdog.unref();
+                try {
+                    persistTerminated(reason);
+                }
+                finally {
+                    clearTimeout(watchdog);
+                }
+                if (ack) {
+                    process.stderr.write(`[improve] received ${sig}; recorded terminated run ${runId}\n`);
+                }
+                process.exit(code);
             };
+            const sigtermHandler = makeSignalHandler("SIGTERM");
+            const sigintHandler = makeSignalHandler("SIGINT");
+            const sighupHandler = makeSignalHandler("SIGHUP");
             process.once("SIGTERM", sigtermHandler);
             process.once("SIGINT", sigintHandler);
             process.once("SIGHUP", sighupHandler);
@@ -169,6 +190,7 @@ export const improveCommand = defineCommand({
                     dryRun,
                     target: targetArg,
                     autoAccept,
+                    ...(runId !== undefined ? { runId } : {}),
                     ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),

package/dist/commands/{improve-profiles.js → improve/improve-profiles.js}

@@ -1,13 +1,16 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import profileDefault from "../assets/profiles/default.json" with { type: "json" };
-import profileGraphRefresh from "../assets/profiles/graph-refresh.json" with { type: "json" };
-import profileMemoryFocus from "../assets/profiles/memory-focus.json" with { type: "json" };
-import profileQuick from "../assets/profiles/quick.json" with { type: "json" };
-import profileThorough from "../assets/profiles/thorough.json" with { type: "json" };
-import { parseAssetRef } from "../core/asset-ref";
-import { warn } from "../core/warn";
+import profileCatchup from "../../assets/profiles/catchup.json" with { type: "json" };
+import profileConsolidate from "../../assets/profiles/consolidate.json" with { type: "json" };
+import profileDefault from "../../assets/profiles/default.json" with { type: "json" };
+import profileFrequent from "../../assets/profiles/frequent.json" with { type: "json" };
+import profileGraphRefresh from "../../assets/profiles/graph-refresh.json" with { type: "json" };
+import profileMemoryFocus from "../../assets/profiles/memory-focus.json" with { type: "json" };
+import profileQuick from "../../assets/profiles/quick.json" with { type: "json" };
+import profileThorough from "../../assets/profiles/thorough.json" with { type: "json" };
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { warn } from "../../core/warn.js";
 /** Profile name used as the final fallback when nothing else resolves. */
 const FALLBACK_PROFILE_NAME = "default";
 // Built-in default allowed types per process
@@ -25,6 +28,9 @@ const BUILTIN_PROFILES = {
     thorough: profileThorough,
     "memory-focus": profileMemoryFocus,
     "graph-refresh": profileGraphRefresh,
+    frequent: profileFrequent,
+    consolidate: profileConsolidate,
+    catchup: profileCatchup,
 };
 /**
  * Default enabled-state for known improve processes when neither the user

package/dist/commands/{improve-result-file.js → improve/improve-result-file.js}

@@ -27,7 +27,7 @@
  */
 import crypto from "node:crypto";
 import path from "node:path";
-import { openStateDatabase, recordImproveRun } from "../core/state-db";
+import { openStateDatabase, recordImproveRun } from "../../core/state-db.js";
 /**
  * Build a stable run-id for a single improve invocation.
  *