akm-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/commands/improve/extract.js

@@ -39,9 +39,26 @@ 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 { resolveProcessEnabled } from "./improve-profiles.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;
+/**
+ * Default cap on NEW sessions the extract pass will LLM-process in a single run
+ * (`processes.extract.maxSessionsPerRun` overrides; `0` disables). Bounds per-run
+ * wall time + token spend so a backlog of accumulated sessions can't run a single
+ * pass past its scheduled-task timeout. Overflow sessions stay unseen and are
+ * processed by subsequent runs, so coverage is preserved — just spread out.
+ */
+const DEFAULT_MAX_SESSIONS_PER_RUN = 25;
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /**
  * Parse a since-string into an absolute ms-epoch cutoff. Accepts:
@@ -115,7 +132,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, sessionIndexing) {
+async function processSession(harness, sessionRef, stashDir, config, llmConfig, chat, ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, minContentChars, sessionIndexing) {
     const warnings = [];
     let data;
     try {
@@ -136,6 +153,31 @@ 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
@@ -290,13 +332,20 @@ export async function akmExtract(options) {
     const stashDir = options.stashDir ?? resolveStashDir();
     const dryRun = options.dryRun ?? false;
     const sourceRun = options.sourceRun ?? `extract-${timestampForFilename()}`;
-    // Read the per-process extract config from the active improve profile. Matches
-    // the pattern reflect/distill/consolidate use: `profiles.improve.<active>.processes.extract`.
-    // Only the `default` improve profile is consulted here — extract isn't invoked
-    // with a profile flag yet (parity item for a future change).
-    const extractProcess = config.profiles?.improve?.default?.processes?.extract;
+    // 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
+        : config.profiles?.improve?.default?.processes?.extract;
+    const extractEnabled = activeProfile
+        ? resolveProcessEnabled("extract", activeProfile)
+        : isLlmFeatureEnabled(config, "session_extraction");
     // Feature-gate early so we get a clean "skipped because disabled" envelope.
-    if (!isLlmFeatureEnabled(config, "session_extraction")) {
+    if (!extractEnabled) {
         return {
             schemaVersion: 1,
             ok: true,
@@ -339,6 +388,15 @@ 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;
+    // 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;
     // #561 — resolve session-indexing config. Default ON: we only reach this code
@@ -482,8 +540,15 @@ export async function akmExtract(options) {
             skippedCount += 1;
             continue;
         }
+        // Per-run cap on LLM-processed sessions (skip-tracked seen sessions above
+        // don't count). Single-session / --force modes bypass the cap (explicit
+        // intent). Overflow sessions are left unseen for the next run.
+        if (!options.sessionId && !options.force && maxSessionsPerRun > 0 && processedCount >= maxSessionsPerRun) {
+            topLevelWarnings.push(`Reached maxSessionsPerRun=${maxSessionsPerRun}; ${candidates.length - processedCount - skippedCount} session(s) deferred to a later run.`);
+            break;
+        }
         try {
-            const result = await processSession(harness, summary, stashDir, config, llmConfig, chat, options.ctx, sourceRun, dryRun, timeoutMs, maxTotalChars, sessionIndexing);
+            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;

package/dist/commands/improve/improve-auto-accept.js

@@ -4,7 +4,24 @@
 import { loadConfig } from "../../core/config/config.js";
 import { appendEvent } from "../../core/events.js";
 import { info, warn } from "../../core/warn.js";
-import { promoteProposal } from "../proposal/validators/proposals.js";
+import { promoteProposal, recordGateDecision } from "../proposal/validators/proposals.js";
+/**
+ * Derive a stable, low-cardinality reason bucket from an auto-accept promotion
+ * error. `promoteProposal` throws a `validateProposal` report formatted as
+ * `[kind] message` lines; we extract the first finding kind. Non-validation
+ * throws collapse to `promote-error`.
+ */
+function classifyPromoteFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const finding = /\[([a-z][a-z0-9-]*)\]/i.exec(message);
+    if (finding)
+        return `validation:${finding[1]}`;
+    if (/not pending/i.test(message))
+        return "not-pending";
+    if (/unknown asset type/i.test(message))
+        return "unknown-type";
+    return "promote-error";
+}
 // ---------------------------------------------------------------------------
 // Gate implementation
 // ---------------------------------------------------------------------------
@@ -18,7 +35,7 @@ import { promoteProposal } from "../proposal/validators/proposals.js";
  * @param promoteFn   Injectable override for `promoteProposal` (test seam).
  */
 export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProposal) {
-    const result = { promoted: [], skipped: [], failed: [] };
+    const result = { promoted: [], skipped: [], failed: [], failedByReason: {} };
     // --- Guard: gate is disabled or context is incomplete ---
     if (cfg.dryRun || cfg.globalThreshold === undefined || !cfg.stashDir) {
         result.skipped = candidates.map((c) => c.proposalId);
@@ -26,14 +43,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,
@@ -46,14 +89,31 @@ export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProp
                     confidence,
                     threshold: effectiveThreshold,
                     phase: cfg.phase,
+                    // Attribution tagging: carry the eligibility lane from the proposal
+                    // record onto the auto-accept promoted event so the lane survives to
+                    // accept time even when promotion happens in a later run.
+                    ...(promotion.proposal.eligibilitySource !== undefined
+                        ? { eligibilitySource: promotion.proposal.eligibilitySource }
+                        : {}),
                 },
             }, cfg.eventsCtx ?? {});
             info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
             result.promoted.push(proposalId);
         }
         catch (err) {
-            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
+            const reason = classifyPromoteFailure(err);
+            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId} (${reason}): ${err instanceof Error ? err.message : String(err)}`);
             result.failed.push(proposalId);
+            result.failedByReason[reason] = (result.failedByReason[reason] ?? 0) + 1;
+            // Record WHY on the proposal so `akm proposal show` explains the rejection
+            // and the leak is no longer blind. Best-effort.
+            stamp(proposalId, {
+                outcome: "auto-rejected",
+                reason,
+                confidence,
+                thresholds: { autoAccept: effectiveThreshold },
+                gate: gateLabel,
+            });
         }
     }
     return result;

package/dist/commands/improve/improve-cli.js

@@ -54,6 +54,11 @@ export const improveCommand = defineCommand({
             description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
             default: false,
         },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
+            default: false,
+        },
         profile: {
             type: "string",
             description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
@@ -92,6 +97,7 @@ export const improveCommand = defineCommand({
             const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
             const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
             const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const skipIfLocked = getHyphenatedBoolean(args, "skip-if-locked");
             const profileArg = getStringArg(args, "profile");
             // Only set the keys the user actually passed (citty leaves the flag
             // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
@@ -189,6 +195,7 @@ export const improveCommand = defineCommand({
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
                     ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(skipIfLocked ? { skipIfLocked } : {}),
                     ...(profileArg !== undefined ? { profile: profileArg } : {}),
                     ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
                     consolidateOptions: {

package/dist/commands/improve/improve-profiles.js

@@ -54,6 +54,10 @@ const IMPROVE_PROCESS_DEFAULTS = {
     // proposal-queue triage drains the standing backlog. Opt-in (default off),
     // like `validation` — needs an explicit `enabled: true`.
     triage: false,
+    // Layer 2 proactive-maintenance selector. Opt-in (default off) — surfaces
+    // stale high-value assets on a schedule. Enable per-profile with an explicit
+    // `processes.proactiveMaintenance.enabled: true`.
+    proactiveMaintenance: false,
 };
 /**
  * Compute the effective enabled-state for a named improve process.