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

package/dist/core/config/engine-semantics.js

@@ -0,0 +1,28 @@
+// 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/.
+export const ENGINE_NAME_PATTERN_SOURCE = "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$";
+export const BUILTIN_IMPROVE_STRATEGY_NAMES = [
+    "default",
+    "quick",
+    "thorough",
+    "memory-focus",
+    "graph-refresh",
+    "frequent",
+    "consolidate",
+    "catchup",
+    "reflect-distill",
+    "proactive-maintenance",
+];
+/** Engine capability required by each configured improve process. `null` means engine-free. */
+export const IMPROVE_PROCESS_ENGINE_CAPABILITIES = {
+    reflect: "llm",
+    distill: "llm",
+    consolidate: "llm",
+    memoryInference: "llm",
+    graphExtraction: "llm",
+    extract: "llm",
+    validation: "llm",
+    triage: "runner",
+    proactiveMaintenance: null,
+};

package/dist/core/config/experimental.js

@@ -0,0 +1,21 @@
+// 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/.
+/**
+ * True only when the user has explicitly opted into autonomous `akm improve`
+ * mutation.
+ *
+ * Accepts a partial config so callers holding a plain object (tests, the
+ * strategy resolver) do not need a fully-parsed one.
+ */
+export function isImproveAutonomyEnabled(config) {
+    return config?.experimental?.improveAutonomy === true;
+}
+/**
+ * The config key an operator sets to enable a gated lane.
+ *
+ * Named rather than inlined because it is user-facing text: it goes into the
+ * `improve_skipped` event metadata, the `akm task doctor` output, and the
+ * health advisory, and those three must name the same key as the schema.
+ */
+export const IMPROVE_AUTONOMY_CONFIG_KEY = "experimental.improveAutonomy";

package/dist/core/config/schema/embedding.js

@@ -0,0 +1,38 @@
+// 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/.
+/**
+ * Embedding connection config (`embedding`). Extracted verbatim from the former
+ * `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+import { ENV_REFERENCE_PATTERN, positiveInt } from "./primitives.js";
+const EmbeddingOllamaOptionsSchema = z
+    .object({
+    num_ctx: positiveInt.optional(),
+})
+    .passthrough();
+/**
+ * Embedding connection config. Both `endpoint` and `model` are optional:
+ *   - Remote: provide `endpoint` (http/https URL) + `model`.
+ *   - Local-only: omit `endpoint`/`model`; set `localModel` (or fall back to
+ *     {@link DEFAULT_LOCAL_MODEL}).
+ *
+ * Consumers route via `hasRemoteEndpoint()` which checks for an http(s)
+ * endpoint — absent fields take the local path naturally, no sentinels needed.
+ */
+export const EmbeddingConnectionConfigSchema = z
+    .object({
+    provider: z.string().optional(),
+    endpoint: z.string().optional(),
+    model: z.string().optional(),
+    apiKey: z.string().regex(ENV_REFERENCE_PATTERN, `apiKey must be $VAR or \${VAR}`).optional(),
+    dimension: positiveInt.optional(),
+    localModel: z.string().min(1).optional(),
+    maxTokens: positiveInt.optional(),
+    batchSize: positiveInt.optional(),
+    chunkSize: positiveInt.optional(),
+    contextLength: positiveInt.optional(),
+    ollamaOptions: EmbeddingOllamaOptionsSchema.optional(),
+})
+    .passthrough();

package/dist/core/config/schema/engines.js

@@ -0,0 +1,116 @@
+// 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/.
+/**
+ * OpenAI-compatible LLM connection configs + named agent/LLM engine schemas
+ * (`engines`). Extracted verbatim from the former `config-schema.ts` monolith —
+ * no behavior change.
+ */
+import { z } from "zod";
+// Harness ids come straight from the dependency-free `harnesses/ids` leaf (the
+// same source `config-types.ts` re-exports them from). Importing them here
+// rather than via `../config-types` keeps `schema/*` free of any edge to
+// `config-types`, which type-derives from this barrel via
+// `typeof import("./config-schema")` — routing through config-types would mint
+// a config-schema ↔ config-types type cycle that collapses inference.
+import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../../integrations/harnesses/ids.js";
+import { chatCompletionsEndpoint, ENV_REFERENCE_PATTERN, ExtraParamsSchema, engineName, LlmCapabilitiesSchema, ModelAliasMapSchema, nonEmptyString, positiveInt, } from "./primitives.js";
+// ── Connection configs (LLM) ────────────────────────────────────────────────
+/**
+ * OpenAI-compatible connection fields shared by named LLM engines and bounded
+ * internal call helpers. `model` is required at schema level — partial entries
+ * created by `akm config set llm.endpoint <url>` (where model is left absent)
+ * are normalized to `model: ""` *before* Zod sees them by the load-time
+ * pre-Zod migrator hook, so this strict shape gates CLI writes without
+ * breaking legacy load-time partial configs.
+ */
+export const LlmConnectionConfigSchema = z
+    .object({
+    provider: z.string().optional(),
+    endpoint: z.string(),
+    model: z.string(),
+    apiKey: z.string().optional(),
+    temperature: z.number().finite().optional(),
+    maxTokens: positiveInt.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    concurrency: positiveInt.optional(),
+    capabilities: LlmCapabilitiesSchema.optional(),
+    extraParams: ExtraParamsSchema.optional(),
+    contextLength: positiveInt.optional(),
+    enableThinking: z.boolean().optional(),
+})
+    .passthrough();
+export const LlmProfileConfigSchema = LlmConnectionConfigSchema.extend({
+    supportsJsonSchema: z.boolean().optional(),
+}).passthrough();
+// ── Agent engines ───────────────────────────────────────────────────────────
+// Derives from the canonical VALID_HARNESS_IDS (#565) so the Zod gate cannot
+// drift from the TS union / parse check / setup detection.
+const AgentPlatformSchema = z.enum(VALID_HARNESS_IDS);
+const LlmEngineSchema = z
+    .object({
+    kind: z.literal("llm"),
+    provider: z.string().optional(),
+    endpoint: chatCompletionsEndpoint,
+    model: nonEmptyString,
+    apiKey: z.string().regex(ENV_REFERENCE_PATTERN, `apiKey must be $VAR or \${VAR}`).optional(),
+    temperature: z.number().finite().optional(),
+    maxTokens: positiveInt.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    concurrency: positiveInt.optional(),
+    supportsJsonSchema: z.boolean().optional(),
+    extraParams: ExtraParamsSchema.optional(),
+    contextLength: positiveInt.optional(),
+    enableThinking: z.boolean().optional(),
+})
+    .passthrough()
+    .superRefine((value, ctx) => {
+    for (const key of ["platform", "bin", "args", "workspace", "modelAliases", "llmEngine"]) {
+        if (key in value)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an LLM engine` });
+    }
+});
+const AgentEngineSchema = z
+    .object({
+    kind: z.literal("agent"),
+    platform: AgentPlatformSchema.refine((platform) => HARNESS_AGENT_DISPATCH_IDS.has(platform), {
+        message: "platform does not support agent dispatch",
+    }),
+    bin: nonEmptyString.optional(),
+    args: z.array(z.string()).optional(),
+    workspace: nonEmptyString.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    modelAliases: ModelAliasMapSchema.optional(),
+    llmEngine: engineName.optional(),
+})
+    .passthrough()
+    .superRefine((value, ctx) => {
+    for (const key of [
+        "provider",
+        "endpoint",
+        "apiKey",
+        "temperature",
+        "maxTokens",
+        "concurrency",
+        "supportsJsonSchema",
+        "extraParams",
+        "contextLength",
+        "enableThinking",
+    ]) {
+        if (key in value)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: `${key} is not valid on an agent engine` });
+    }
+    if (value.platform !== "opencode-sdk" && value.llmEngine !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["llmEngine"],
+            message: "llmEngine is only valid on opencode-sdk",
+        });
+    }
+    if (value.platform === "opencode-sdk" && value.args !== undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["args"], message: "args is not valid on opencode-sdk" });
+    }
+});
+export const EngineConfigSchema = z.union([LlmEngineSchema, AgentEngineSchema]);
+export const EnginesSchema = z.record(engineName, EngineConfigSchema);

package/dist/core/config/schema/experimental.js

@@ -0,0 +1,47 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `experimental` config section — explicit opt-ins for behaviour that is not
+ * covered by the stability contract (D8).
+ *
+ * An entry here exists so a user can turn something ON deliberately. Every key
+ * defaults to OFF, and the runtime must treat "absent" and "false" identically:
+ * autonomy is never inferred from a partially-written config.
+ */
+import { z } from "zod";
+export const ExperimentalConfigSchema = z
+    .object({
+    /**
+     * Allow `akm improve` to mutate assets without review.
+     *
+     * OFF by default. Gates memory-cleanup, memory-inference writes, and triage
+     * `applyMode: "promote"`. Consolidation stays enabled because destructive
+     * operations are advisory and promotion emits a reviewable proposal.
+     * `akm improve` itself stays on either way — what this gates is autonomy,
+     * not the feature.
+     *
+     * `sync.push` is deliberately NOT gated by this key: it publishes
+     * already-committed content to a remote the user configured for that
+     * purpose, and it has its own `sync.push: false` / `--no-push` controls.
+     */
+    improveAutonomy: z.boolean().optional(),
+    /**
+     * Allow the `akm workflow` native engine to run (Q-05).
+     *
+     * OFF by default. Gates `akm workflow run` (the native step-execution
+     * engine) and `akm workflow brief`/`report` (the harness-neutral driver
+     * protocol).
+     *
+     * Deliberately NOT gated: authoring/linting the unified markdown format
+     * and the manual workflow CLI contract (`start`/`next`/`complete`/
+     * `status`/`list`/`create`/`resume`/`abandon`) remain stable regardless of
+     * this key.
+     *
+     * Unlike `improveAutonomy`, a gated call here REFUSES outright rather than
+     * degrading: a workflow step either executes or it does not, so there is
+     * no safe partial-execution fallback to fall back to.
+     */
+    workflowEngine: z.boolean().optional(),
+})
+    .passthrough();

package/dist/core/config/schema/feedback.js

@@ -0,0 +1,31 @@
+// 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/.
+/**
+ * Feedback taxonomy + `feedback` config section. Extracted verbatim from the
+ * former `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+import { nonEmptyString } from "./primitives.js";
+// ── Feedback failure modes (F-3 / #384) ─────────────────────────────────────
+/**
+ * Curated taxonomy of failure modes for negative feedback.
+ *
+ * Structured failure modes enable aggregation across feedback events so the
+ * distill pipeline can detect that "5 assets failed for the same reason" and
+ * act on it — free-text strings about the same issue are not aggregatable.
+ */
+export const FEEDBACK_FAILURE_MODES = [
+    "incorrect", // Factually wrong or logically flawed content
+    "outdated", // Correct at some point but now stale
+    "dangerous", // Could cause harm if followed (security, safety)
+    "incomplete", // Missing key steps, context, or caveats
+    "redundant", // Duplicates another asset without adding value
+];
+// ── Feedback ────────────────────────────────────────────────────────────────
+export const FeedbackConfigSchema = z
+    .object({
+    requireReason: z.boolean().optional(),
+    allowedFailureModes: z.array(nonEmptyString).optional(),
+})
+    .passthrough();

package/dist/core/config/schema/improve-processes.js

@@ -0,0 +1,389 @@
+// 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/.
+/**
+ * Improve profile + per-process (WI-9.6) discriminated schemas. Extracted
+ * verbatim from the former `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../engine-semantics.js";
+import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
+// ── Improve profile / process ──────────────────────────────────────────────
+//
+// WI-9.6 (§4.2/§10.2): each of the 9 improve processes (reflect, distill,
+// consolidate, memoryInference, graphExtraction, extract, validation, triage,
+// proactiveMaintenance) gets its OWN schema below — a shared base (engine,
+// model, llm, enabled, timeoutMs) extended with only the fields meaningful on
+// that process — replacing the prior single ImproveProcessConfigSchema reused
+// via `.optional()` for all 9 keys (which accepted, and silently ignored, any
+// field on any process). Field→process assignment is derived from each
+// field's original "only meaningful on X" doc comment, cross-checked against
+// its actual runtime consumers and the built-in strategy assets
+// (src/assets/improve-strategies/*.json).
+//
+// `ImproveProcessConfigSchema` ITSELF STAYS (unnarrowed — the union of every
+// field across every process): it backs (a) the wide `ImproveProcessConfig`
+// TS type that generic dynamic-process-name code needs (getImproveProcessConfig,
+// ResolvedImproveProcess.config, agent/runner.ts's cast — the process name
+// isn't known at the type level there, so the type must be a supertype every
+// process's narrow output is assignable to), and (b) two existing tests that
+// parse fields from multiple processes against it directly with no process
+// context (tests/integration/extract-command.test.ts,
+// tests/config-triage-process.test.ts). Real per-config validation for
+// `processes.<name>` uses the NARROW per-process schemas via
+// {@link ImproveProfileProcessesSchema} below — setting a field on the wrong
+// process there is now rejected (the intended §4.2 improvement).
+const IMPROVE_PROCESS_BASE_FIELDS = {
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    llm: LlmInvocationOverridesSchema.optional(),
+    enabled: z.boolean().optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+};
+/** Reflect/distill/consolidate: process-level asset-type filter (see improve-strategies.ts shouldSkipRef/DEFAULT_ALLOWED_TYPES). */
+const allowedTypesField = z.array(z.string().min(1)).optional();
+/**
+ * Consolidate process: hard cap on memories processed per pass.
+ * Reflect/distill: max refs processed (same as profile-level `limit`).
+ * proactiveMaintenance: fallback when `maxPerRun` is absent.
+ */
+const processLimitField = positiveInt.optional();
+/**
+ * Distill process: LLM-as-judge lesson quality gate. Default ON (R3);
+ * fail-open — judge failure/timeout/parse errors pass through. Set
+ * `enabled: false` on the distill process to opt out. Also read on the
+ * `reflect` process (proposal-side quality gate; see reflect.ts).
+ */
+const qualityGateField = z.object({ enabled: z.boolean().optional() }).passthrough().optional();
+/** Consolidate process: gate for the M-1 (#367) contradiction-detection pass. */
+const contradictionDetectionField = z.object({ enabled: z.boolean().optional() }).passthrough().optional();
+/**
+ * WS-3b: CLS (Complementary Learning System) interleaving (step 9).
+ * distill/memoryInference prompts include embedding-retrieved existing adjacent
+ * lessons/knowledge to prevent catastrophic interference with prior generalizations.
+ * Default OFF. Only meaningful on `distill` and `memoryInference` processes.
+ */
+const clsField = z
+    .object({
+    enabled: z.boolean().optional(),
+    // Number of adjacent lessons/knowledge to include in prompts (default 3).
+    adjacentCount: z.number().int().min(1).optional(),
+})
+    .passthrough()
+    .optional();
+/**
+ * WS-3b: Distill→source fidelity check (step 10). After a distill proposal,
+ * check it against its cited source memories; a contradiction flag forces
+ * human review. Default OFF. Distill process only.
+ */
+const fidelityCheckField = z.object({ enabled: z.boolean().optional() }).passthrough().optional();
+/**
+ * #639 — semantic value-floor filter for the `reflect` process. When
+ * enabled, proposals classified as "low-value" by the deterministic noise
+ * gate are deferred. DEFAULT OFF (absent / { enabled: false } = pre-#639
+ * byte-identical behaviour). Reflect process only.
+ */
+const lowValueFilterField = z.object({ enabled: z.boolean().optional() }).passthrough().optional();
+/**
+ * #626 — extract process: pre-LLM heuristic triage gate. When enabled, a
+ * deterministic scorer decides BEFORE the extraction LLM call whether a
+ * session carries enough signal to be worth extracting; low-signal sessions
+ * are skipped at zero LLM cost. Default OFF. `minScore` is the minimum total
+ * heuristic score to PASS (default 2). Extract process only — NOTE: unrelated
+ * to the `triage` PROCESS (`processes.triage`); this is a nested object under
+ * `processes.extract.triage` that happens to share the name.
+ */
+const extractTriageGateField = z
+    .object({
+    enabled: z.boolean().optional(),
+    minScore: z.number().min(0).optional(),
+})
+    .passthrough()
+    .optional();
+/** Triage process: LLM-as-judge triage-apply decision engine override. */
+const triageJudgmentField = z
+    .object({
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    llm: LlmInvocationOverridesSchema.optional(),
+})
+    .passthrough()
+    .optional();
+/**
+ * WS-3b: Anti-collapse guards (step 8). Prevents the consolidation pipeline
+ * from collapsing too aggressively and losing diversity. Consolidate process
+ * only. Default ON since R5 (opt out via enabled: false).
+ *   - maxGeneration: refuse to merge two assets both above this generation (default 2).
+ *   - lexicalDiversityCheck: low n-gram diversity ⇒ raise merge threshold.
+ *   - randomClusterFraction: occasional random (non-similar) cluster in pool (default 0.05).
+ *   - mergeInformationFloor: LIVE gate (anti-collapse.ts:143) — NOT a
+ *     decorative/inert knob. `false` skips the merge-information-floor
+ *     measurement entirely (no counting, no warning) for every merge;
+ *     true/absent (default) measures it on every merge. The MEASUREMENT's
+ *     outcome is advisory in v1: a failing merge is counted
+ *     (`merge_floor_violations`) and warned but never refused (promotion path:
+ *     docs/architecture/specs/improve-collapse-churn-detector-design.md §7). In short:
+ *     this field gates whether the check runs at all (a real code path), not
+ *     whether a merge is allowed.
+ *   - minSpecificityRetention: distinct-token retention floor for merges (default 0.6).
+ * (WS-3b step 0a `homeostaticDemotion` was removed — R4. Continuous decay is
+ * now part of the always-applied salience recency term.)
+ */
+const antiCollapseField = z
+    .object({
+    enabled: z.boolean().optional(),
+    maxGeneration: z.number().int().min(1).optional(),
+    lexicalDiversityCheck: z.boolean().optional(),
+    randomClusterFraction: z.number().min(0).max(1).optional(),
+    mergeInformationFloor: z.boolean().optional(),
+    minSpecificityRetention: z.number().min(0).max(1).optional(),
+})
+    .passthrough()
+    .optional();
+const REFLECT_PROCESS_FIELDS = {
+    allowedTypes: allowedTypesField,
+    limit: processLimitField,
+    qualityGate: qualityGateField,
+    lowValueFilter: lowValueFilterField,
+};
+const DISTILL_PROCESS_FIELDS = {
+    allowedTypes: allowedTypesField,
+    limit: processLimitField,
+    qualityGate: qualityGateField,
+    // Skip distill entirely when reflect produced zero planned refs.
+    requirePlannedRefs: z.boolean().optional(),
+    cls: clsField,
+    fidelityCheck: fidelityCheckField,
+};
+const CONSOLIDATE_PROCESS_FIELDS = {
+    allowedTypes: allowedTypesField,
+    limit: processLimitField,
+    // Minimum eligible-memory pool size below which the consolidation pass skips
+    // entirely (emits `pool_below_min_size`). 0 disables the guard. Default 500.
+    minPoolSize: z.number().int().min(0).optional(),
+    maxChunkSize: z.number().int().min(1).max(50).optional(),
+    // Narrow candidate pool to memories modified within this duration window
+    // plus their graph neighbours. Absent = full-pool sweep.
+    incrementalSince: z.string().optional(),
+    // Graph neighbours per changed memory during incremental consolidation.
+    // Default 5. Only meaningful with incrementalSince.
+    neighborsPerChanged: z.number().int().min(1).optional(),
+    // Fallback p90 wall-clock time per consolidation chunk in seconds, used for
+    // cold-start budget estimation when no telemetry history exists. The actual
+    // p90 is derived from observed run durations once sufficient history
+    // accumulates; this value is only used on the very first run. Default 30s.
+    p90ChunkSecondsDefault: z.number().finite().positive().optional(),
+    antiCollapse: antiCollapseField,
+    contradictionDetection: contradictionDetectionField,
+};
+const MEMORY_INFERENCE_PROCESS_FIELDS = {
+    // Minimum pending memory count to run the pass.
+    minPendingCount: z.number().int().min(0).optional(),
+    cls: clsField,
+};
+/**
+ * GraphExtraction process fields: improve-owned graph extraction scope and
+ * batching. Passed to the invocation directly and never inherited from
+ * standalone index.graph.
+ */
+const GRAPH_EXTRACTION_PROCESS_FIELDS = {
+    // #624 P2: when set, rank eligible files by utility_scores DESC and process
+    // only the top-N per run (incremental high-signal-first sweep). Unset =
+    // process all eligible (current behavior).
+    topN: positiveInt.optional(),
+    includeTypes: z.array(z.string().min(1)).min(1).optional(),
+    batchSize: positiveInt.optional(),
+    // Full-corpus scan. When true, graph extraction runs on ALL stash files
+    // instead of only files touched by actionable refs in the current run.
+    // Used by the `graph-refresh` built-in profile / a scheduled weekly task.
+    fullScan: z.boolean().optional(),
+};
+const EXTRACT_PROCESS_FIELDS = {
+    defaultSince: z.string().min(1).optional(),
+    maxTotalChars: positiveInt.optional(),
+    // Minimum raw session size (pre-filter inputCount) below which the extract
+    // LLM call is skipped (#595/#596). 0 disables the gate. Absent = default 10
+    // (skip only truly empty sessions).
+    minContentChars: z.number().int().min(0).optional(),
+    triage: extractTriageGateField,
+    // Minimum number of new (unseen, in-window) candidate sessions below which
+    // the extract pass skips entirely (emits an `improve_skipped` event with
+    // `reason: "below_min_new_sessions"`). 0 disables the guard. Default 0
+    // (disabled) so existing behaviour is preserved; only opted-in profiles set it.
+    minNewSessions: z.number().int().min(0).optional(),
+    // Cap on NEW sessions processed (LLM-called) per run; the rest roll to the
+    // next run (still unseen). 0 disables. Absent = default 25.
+    maxSessionsPerRun: z.number().int().min(0).optional(),
+    // #561 — index agent sessions as a searchable `session` asset. Absent =
+    // on-when-an-LLM-is-available (fail-open when offline). COST: when on, each
+    // processed session makes a SECOND LLM call (the session summary) on top of
+    // the extraction call — i.e. ~2 LLM calls/session. Set to false to halve
+    // per-session extract cost at the price of unsearchable sessions.
+    // (Unchanged/skip sessions still cost zero — the content-hash ledger gates
+    // both calls upstream.)
+    indexSessions: z.boolean().optional(),
+    // #561 — minimum session duration in minutes for session indexing. 0
+    // disables the gate. Absent = default 5.
+    minSessionDuration: z.number().min(0).optional(),
+};
+const TRIAGE_PROCESS_FIELDS = {
+    applyMode: z.enum(["queue", "promote"]).optional(),
+    policy: z.string().min(1).optional(),
+    maxAcceptsPerRun: positiveInt.optional(),
+    maxDiffLines: positiveInt.optional(),
+    rejectEmpty: z.boolean().optional(),
+    judgment: triageJudgmentField,
+};
+/** proactiveMaintenance process fields (Layer 2). */
+const PROACTIVE_MAINTENANCE_PROCESS_FIELDS = {
+    // Staleness gate + rotation cooldown in days (default 30).
+    dueDays: z.number().int().min(0).optional(),
+    // Top-N bound per run (default 25). Alias for `limit`; `maxPerRun` wins
+    // when both are set.
+    maxPerRun: positiveInt.optional(),
+    limit: processLimitField,
+};
+/**
+ * Shared cross-process superRefine: rejects the retired `mode`/`profile`
+ * knobs (top-level and inside a `judgment` sub-object) in favour of `engine`.
+ * Applied identically to every per-process schema and to the wide
+ * ImproveProcessConfigSchema.
+ */
+function checkRetiredProcessKeys(value, ctx) {
+    for (const key of ["mode", "profile"]) {
+        if (key in value) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: `${key} is retired; use engine` });
+        }
+    }
+    const judgment = value.judgment;
+    if (judgment) {
+        for (const key of ["mode", "profile"]) {
+            if (key in judgment) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["judgment", key],
+                    message: `${key} is retired; use engine`,
+                });
+            }
+        }
+    }
+}
+export const ImproveProcessConfigSchema = z
+    .object({
+    ...IMPROVE_PROCESS_BASE_FIELDS,
+    ...REFLECT_PROCESS_FIELDS,
+    ...DISTILL_PROCESS_FIELDS,
+    ...CONSOLIDATE_PROCESS_FIELDS,
+    ...MEMORY_INFERENCE_PROCESS_FIELDS,
+    ...GRAPH_EXTRACTION_PROCESS_FIELDS,
+    ...EXTRACT_PROCESS_FIELDS,
+    ...TRIAGE_PROCESS_FIELDS,
+    ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS,
+})
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.reflect` — narrow per-process schema (WI-9.6). */
+export const ReflectProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...REFLECT_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.distill` — narrow per-process schema (WI-9.6). */
+export const DistillProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...DISTILL_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.consolidate` — narrow per-process schema (WI-9.6). */
+export const ConsolidateProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...CONSOLIDATE_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.memoryInference` — narrow per-process schema (WI-9.6). */
+export const MemoryInferenceProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...MEMORY_INFERENCE_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.graphExtraction` — narrow per-process schema (WI-9.6). */
+export const GraphExtractionProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...GRAPH_EXTRACTION_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.extract` — narrow per-process schema (WI-9.6). */
+export const ExtractProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...EXTRACT_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.validation` — narrow per-process schema (WI-9.6); no extra fields beyond the shared base. */
+export const ValidationProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.triage` — narrow per-process schema (WI-9.6). */
+export const TriageProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...TRIAGE_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+/** `processes.proactiveMaintenance` — narrow per-process schema (WI-9.6). */
+export const ProactiveMaintenanceProcessConfigSchema = z
+    .object({ ...IMPROVE_PROCESS_BASE_FIELDS, ...PROACTIVE_MAINTENANCE_PROCESS_FIELDS })
+    .passthrough()
+    .superRefine(checkRetiredProcessKeys);
+const ImproveProfileProcessesSchema = z
+    .object({
+    reflect: ReflectProcessConfigSchema.optional(),
+    distill: DistillProcessConfigSchema.optional(),
+    consolidate: ConsolidateProcessConfigSchema.optional(),
+    memoryInference: MemoryInferenceProcessConfigSchema.optional(),
+    graphExtraction: GraphExtractionProcessConfigSchema.optional(),
+    extract: ExtractProcessConfigSchema.optional(),
+    validation: ValidationProcessConfigSchema.optional(),
+    triage: TriageProcessConfigSchema.optional(),
+    proactiveMaintenance: ProactiveMaintenanceProcessConfigSchema.optional(),
+})
+    .passthrough()
+    .superRefine((val, ctx) => {
+    // 0.8.0 removed the duplicated `feedbackDistillation` process key — it was
+    // a thin wrapper around `processes.distill.enabled`. Keep the migration
+    // hint so a stale config gets an actionable message rather than silently
+    // doing nothing. Other unknown process keys remain preserved for
+    // cross-version compatibility, but an enabled one is rejected below because
+    // this version cannot execute it.
+    if ("feedbackDistillation" in val) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "feedbackDistillation was removed in 0.8.0 — use processes.distill.enabled instead. " +
+                "It now controls both the orchestration gate and the LLM-call gate.",
+        });
+    }
+    for (const [name, process] of Object.entries(val)) {
+        if (!(name in IMPROVE_PROCESS_ENGINE_CAPABILITIES) &&
+            process !== null &&
+            typeof process === "object" &&
+            process.enabled === true) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [name],
+                message: `Unknown enabled improve process "${name}"`,
+            });
+        }
+    }
+});
+export const ImproveProfileConfigSchema = z
+    .object({
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    llm: LlmInvocationOverridesSchema.optional(),
+    description: z.string().min(1).optional(),
+    processes: ImproveProfileProcessesSchema.optional(),
+    limit: positiveInt.optional(),
+    sync: z
+        .object({
+        enabled: z.boolean().optional(),
+        push: z.boolean().optional(),
+        message: z.string().min(1).optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();