akm-cli 0.8.6 → 0.8.14

package/dist/core/assert.js

@@ -0,0 +1,40 @@
+// 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/.
+/**
+ * assert.ts — exhaustiveness keystone.
+ *
+ * `assertNever` is the single helper the exhaustive-switch refactors consume.
+ * Placing it in the `never` arm of a `switch`/`if` chain turns any unhandled
+ * union variant into a *compile-time* error (the argument no longer narrows to
+ * `never`), and — if the impossible case is somehow reached at runtime — throws
+ * with the offending value serialized for diagnostics instead of silently
+ * falling through.
+ */
+/**
+ * Assert that a code path is unreachable.
+ *
+ * Call this in the default/else arm of an exhaustive dispatch over a union. If
+ * a new variant is added to the union without a handling arm, the call site
+ * stops type-checking, surfacing the drift at compile time.
+ *
+ * @param x the value the type system has narrowed to `never`
+ * @param context optional label included in the thrown message for diagnostics
+ * @throws always — this function never returns
+ */
+export function assertNever(x, context) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(x);
+    }
+    catch {
+        // Circular structures / non-serializable values fall back to String().
+        serialized = String(x);
+    }
+    if (serialized === undefined) {
+        // JSON.stringify(undefined) returns undefined, not a string.
+        serialized = String(x);
+    }
+    const where = context ? ` (${context})` : "";
+    throw new Error(`Unexpected value reached assertNever${where}: ${serialized}`);
+}

package/dist/core/asset/asset-create.js

@@ -0,0 +1,54 @@
+// 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/.
+/**
+ * Shared `--path` / `--name` semantics for asset-creating commands
+ * (`remember`, `import`, `propose`, `workflow create`, ...).
+ *
+ * The contract, applied consistently across the command surface:
+ *   - `--name` (or the name positional) is a FLAT asset name — no `/`.
+ *   - `--path` is a relative directory, applied rooted at the asset's type
+ *     directory. The final asset name is `<path>/<name>`.
+ *
+ * Subdirectory placement is `--path`'s job, not `--name`'s. System-derived
+ * names (e.g. a URL-path-derived knowledge name) are exempt — only the user's
+ * explicit name should be flat-checked, at the command layer.
+ */
+import { UsageError } from "../errors.js";
+/**
+ * Normalise an optional `--path` value: a relative directory, applied rooted
+ * at the asset's type directory (e.g. `personal/projects` under `memories/`).
+ * Rejects absolute paths and `.`/`..` segments. Returns `""` when unset.
+ */
+export function normalizeCreateSubPath(subPath) {
+    if (subPath === undefined)
+        return "";
+    const trimmed = subPath
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\/+|\/+$/g, "");
+    if (!trimmed)
+        return "";
+    if (trimmed.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new UsageError("--path must be a relative directory without '.' or '..' segments.");
+    }
+    return trimmed;
+}
+/**
+ * Enforce that an explicit, user-supplied name is a flat (single-segment)
+ * name. A `/` in the name is rejected with guidance to use `--path`. Applied
+ * at the command layer to the user's name only — system-derived names may nest.
+ */
+export function assertFlatAssetName(name) {
+    if (name?.replace(/\\/g, "/").replace(/\.md$/i, "").includes("/")) {
+        throw new UsageError("Asset --name must be a flat name without '/'. Use --path to choose a subdirectory " +
+            "(e.g. --path personal --name grocery-list).");
+    }
+}
+/**
+ * Combine a normalised `--path` subdirectory with a flat base name into the
+ * nested asset name the path resolver expects. `subPath` may be `""`.
+ */
+export function combineCreatePath(subPath, baseName) {
+    return subPath ? `${subPath}/${baseName}` : baseName;
+}

package/dist/core/{asset-ref.js → asset/asset-ref.js}

@@ -2,8 +2,8 @@
 // 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 path from "node:path";
-import { isAssetType } from "./common";
-import { UsageError } from "./errors";
+import { isAssetType } from "../common.js";
+import { UsageError } from "../errors.js";
 /** Accepted spelling aliases mapping to a canonical asset type. */
 const TYPE_ALIASES = {
     environment: "env",
@@ -30,6 +30,19 @@ export function makeAssetRef(type, name, origin) {
         return asset;
     return `${origin}//${asset}`;
 }
+/**
+ * Serialize a parsed {@link AssetRef} value-object back to its canonical
+ * `[origin//]type:name` string form. The single formatter for refs — call
+ * this instead of hand-building `${type}:${name}` template strings so the
+ * serialization rules (origin prefix, name normalization) live in one place
+ * and stay in lockstep with {@link parseAssetRef}.
+ *
+ * `refToString(parseAssetRef(s))` round-trips for any `s` that
+ * `parseAssetRef` accepts.
+ */
+export function refToString(ref) {
+    return makeAssetRef(ref.type, ref.name, ref.origin);
+}
 // ── Parsing ─────────────────────────────────────────────────────────────────
 /**
  * Parse a ref string in the format `[origin//]type:name`.
@@ -53,9 +66,13 @@ export function parseAssetRef(ref) {
     }
     const rawType = body.slice(0, colon);
     const rawName = body.slice(colon + 1);
+    // The `vault` asset type was removed in 0.9.0. Point callers at its
+    // replacements rather than failing with a generic unknown-type error.
+    if (rawType === "vault") {
+        throw new UsageError("The `vault` asset type was removed in 0.9.0 — use `env:` (whole .env config) or `secret:` (a single value).", "MISSING_REQUIRED_ARGUMENT");
+    }
     // Type aliases: `environment:` is an accepted spelling of the canonical
-    // `env:` type. (`vault:` remains its own deprecated type so the frozen
-    // `vaults/` copy keeps resolving through the 0.8.x window.)
+    // `env:` type.
     const resolvedType = TYPE_ALIASES[rawType] ?? rawType;
     if (!isAssetType(resolvedType)) {
         throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");

package/dist/core/{asset-registry.js → asset/asset-registry.js}

@@ -13,7 +13,7 @@
  * `db-search.ts` import from, eliminating the import-order dependency
  * entirely.
  */
-import { buildWorkflowAction } from "../output/renderers";
+import { buildWorkflowAction } from "../../output/renderers.js";
 /** Map asset types to their primary renderer names. */
 export const TYPE_TO_RENDERER = {
     script: "script-source",
@@ -25,10 +25,10 @@ export const TYPE_TO_RENDERER = {
     memory: "memory-md",
     workflow: "workflow-md",
     env: "env-file",
-    vault: "vault-env",
     secret: "secret-file",
     wiki: "wiki-md",
     task: "task-yaml",
+    session: "session-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -41,10 +41,10 @@ export const ACTION_BUILDERS = {
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
     env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (the agent-safe path — values never reach stdout). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
-    vault: (ref) => `DEPRECATED (use env): akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with injected env`,
     secret: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
     task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
+    session: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
 };
 /**
  * Register a type-to-renderer mapping.

package/dist/core/{asset-spec.js → asset/asset-spec.js}

@@ -2,9 +2,9 @@
 // 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 path from "node:path";
-import { buildWorkflowAction } from "../output/renderers";
-import { registerActionBuilder, registerTypeRenderer } from "./asset-registry";
-import { toPosix } from "./common";
+import { buildWorkflowAction } from "../../output/renderers.js";
+import { toPosix } from "../common.js";
+import { registerActionBuilder, registerTypeRenderer } from "./asset-registry.js";
 const buildTaskAction = (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`;
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
@@ -66,9 +66,9 @@ const ASSET_SPECS_INTERNAL = {
     },
     script: { stashDir: "scripts", ...scriptSpec },
     memory: { stashDir: "memories", ...markdownSpec },
-    // Environment assets — whole `.env` files sourced/injected wholesale. Replaces
-    // the deprecated `vault` type (see below). Key NAMES + start-of-line comments
-    // are surfaced as metadata; values are never read for indexing.
+    // Environment assets — whole `.env` files sourced/injected wholesale. Replaced
+    // the deprecated `vault` type (removed in 0.9.0). Key NAMES + start-of-line
+    // comments are surfaced as metadata; values are never read for indexing.
     env: {
         stashDir: "env",
         isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
@@ -91,31 +91,6 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "env-file",
         actionBuilder: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (values never reach stdout); akm env export ${ref} --out <file> -> write a sourceable script to a file`,
     },
-    // DEPRECATED in 0.8.0, removed in 0.9.0 — use `env` instead. Retained so the
-    // frozen `vaults/` copy left by the migration still resolves and so existing
-    // `vault:` refs keep working through the deprecation window.
-    vault: {
-        stashDir: "vaults",
-        isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
-        toCanonicalName: (typeRoot, filePath) => {
-            const rel = toPosix(path.relative(typeRoot, filePath));
-            const fileName = path.basename(rel);
-            // Treat ".env" as the "default" vault; "<name>.env" → "<name>"
-            if (fileName === ".env") {
-                const dir = path.dirname(rel);
-                return dir === "." || dir === "" ? "default" : `${dir}/default`;
-            }
-            const stripped = rel.endsWith(".env") ? rel.slice(0, -4) : rel;
-            return stripped;
-        },
-        toAssetPath: (typeRoot, name) => {
-            if (name === "default")
-                return path.join(typeRoot, ".env");
-            return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
-        },
-        rendererName: "vault-env",
-        actionBuilder: (ref) => `DEPRECATED (use env): akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with injected env`,
-    },
     // Secrets — a single sensitive value used on its own for authentication (a
     // PEM key, API token, TLS cert). Unlike `env` (a group of related .env
     // configuration), the ENTIRE file is the one secret value — there is no safe
@@ -168,6 +143,17 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "task-yaml",
         actionBuilder: buildTaskAction,
     },
+    // #561 — agent sessions indexed as a first-class searchable asset type.
+    // Generated (derived) markdown written by the `extract` pass to
+    // `sessions/<harness>/<session-id>.md`; carries `log_path` + `access`
+    // frontmatter so any agent can navigate into the raw session log. A plain
+    // markdown spec — the summary body is the searchable surface.
+    session: {
+        stashDir: "sessions",
+        ...markdownSpec,
+        rendererName: "session-md",
+        actionBuilder: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**

package/dist/core/{markdown.js → asset/markdown.js}

@@ -1,7 +1,7 @@
 // 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 { parseFrontmatter } from "./frontmatter";
+import { parseFrontmatter } from "./frontmatter.js";
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {
     const lines = content.split(/\r?\n/);

package/dist/core/{stash-meta.js → asset/stash-meta.js}

@@ -18,7 +18,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { UsageError } from "./errors";
+import { UsageError } from "../errors.js";
 /** Root-relative directory holding a stash's meta docs. */
 export const META_DIR = ".meta";
 /** Default meta doc shown when no name is given (`akm show <ref>//meta`). */

package/dist/core/best-effort.js

@@ -0,0 +1,64 @@
+// 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/.
+/**
+ * `bestEffort` — a single chokepoint for the project's many intentionally
+ * silent error swallows (`} catch { /* nothing *\/ }`).
+ *
+ * Historically these were scattered as bare `try/catch {}` blocks with no
+ * binding and no handling, hiding errors with no way to opt into visibility.
+ * This helper centralizes that pattern WITHOUT changing default behaviour:
+ *
+ *   - It runs `fn`. On success it returns the result.
+ *   - On throw it SWALLOWS the error and returns `undefined` — byte-identical
+ *     to the previous bare swallow at the default verbosity level.
+ *   - ONLY when verbose/debug output is enabled (`isVerbose()`) does it route a
+ *     one-line diagnostic to the existing verbose stderr seam (`warnVerbose`).
+ *     At the default (non-verbose) verbosity this emits nothing — no new
+ *     stdout, no new stderr, no changed control flow.
+ *
+ * It deliberately does NOT add a test-isolation rethrow or any other handling:
+ * the contract is "centralize the existing silent swallow + add opt-in verbose
+ * visibility", nothing more. Sites that need `rethrowIfTestIsolationError` or
+ * any real handling already bind the error and are out of scope for this
+ * helper.
+ */
+import { isVerbose, warnVerbose } from "./warn.js";
+/**
+ * Run `fn` for its side effect/value, swallowing any thrown error and
+ * returning `undefined` on failure — exactly as a bare `try { … } catch {}`
+ * would. When verbose output is enabled, the swallowed error is surfaced on the
+ * existing verbose stderr seam (prefixed with `context` when provided).
+ *
+ * @param fn      the operation to attempt
+ * @param context short human-readable reason for the swallow (for verbose logs)
+ * @returns the result of `fn`, or `undefined` if it threw
+ */
+export function bestEffort(fn, context) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        if (isVerbose()) {
+            warnVerbose(`[akm:best-effort] ${context ? `${context}: ` : ""}swallowed error`, err);
+        }
+        return undefined;
+    }
+}
+/**
+ * Async variant of {@link bestEffort}. Awaits `fn()`, swallowing any rejection
+ * and resolving to `undefined` on failure — byte-identical to a bare
+ * `try { await … } catch {}` at the default verbosity level. Surfaces the
+ * swallowed error on the verbose seam only when verbose output is enabled.
+ */
+export async function bestEffortAsync(fn, context) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (isVerbose()) {
+            warnVerbose(`[akm:best-effort] ${context ? `${context}: ` : ""}swallowed error`, err);
+        }
+        return undefined;
+    }
+}

package/dist/core/common.js

@@ -4,24 +4,26 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { TYPE_DIRS } from "./asset-spec";
-import { ConfigError } from "./errors";
-import { getConfigPath, getDefaultStashDir } from "./paths";
+import { getAssetTypes, TYPE_DIRS } from "./asset/asset-spec.js";
+import { ConfigError } from "./errors.js";
+import { getConfigPath, getDefaultStashDir } from "./paths.js";
 // ── Types ───────────────────────────────────────────────────────────────────
-export const ASSET_TYPES = [
-    "skill",
-    "command",
-    "agent",
-    "knowledge",
-    "workflow",
-    "script",
-    "memory",
-    "env",
-    "vault",
-    "secret",
-    "wiki",
-    "lesson",
-];
+/**
+ * The canonical catalog of built-in asset types.
+ *
+ * SINGLE SOURCE OF TRUTH: derived from the {@link ASSET_SPECS} registry in
+ * `asset-spec.ts` rather than hand-maintained here. Before #490/WS7 this was a
+ * hand-written literal array that had DRIFTED from the registry (it omitted
+ * `task`, which the registry has always carried). Deriving from the registry
+ * kills that drift — see `tests/asset-type-union-source.test.ts` for the
+ * intentional-`task`-delta guard.
+ *
+ * Note: `AkmAssetType` stays a static literal union of the BUILT-IN types
+ * (those present at module-eval time). Dynamically `registerAssetType`-d types
+ * are accepted at runtime via {@link isAssetType} but are not part of the
+ * static union — identical to the pre-WS7 contract.
+ */
+export const ASSET_TYPES = Object.freeze([...getAssetTypes()]);
 export const ASSET_TYPE_SET = new Set(ASSET_TYPES);
 // ── Constants ───────────────────────────────────────────────────────────────
 export const IS_WINDOWS = process.platform === "win32";
@@ -67,6 +69,11 @@ export function isAssetType(type) {
  * The temp file is opened with the target `mode` (default 0o600) from the
  * start, so it is never world-readable even briefly.
  *
+ * `content` may be a string or a `Buffer`. Buffer callers (e.g. secrets, where
+ * binary certs and CRLF/LF endings must round-trip byte-exact) get the same
+ * fsync'd temp-file-plus-rename guarantees as string callers — there is a
+ * single atomic-write implementation.
+ *
  * Durability: fsync'd against the May 2026 config-clobber incident (#472).
  * On ext4 (data=ordered) and NVMe-with-TRIM, a power-loss inside the kernel
  * writeback window could leave the renamed file truncated to zero — defeating
@@ -82,7 +89,14 @@ export function writeFileAtomic(target, content, mode) {
     const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
     const fd = fs.openSync(tmp, "w", mode ?? 0o600);
     try {
-        fs.writeSync(fd, content);
+        // fs.writeSync has two non-overlapping overloads (Buffer vs string); branch
+        // so each call resolves to a single overload. Both write byte-exact.
+        if (typeof content === "string") {
+            fs.writeSync(fd, content);
+        }
+        else {
+            fs.writeSync(fd, content);
+        }
         try {
             fs.fdatasyncSync(fd);
         }

package/dist/core/{config-io.js → config/config-io.js}

@@ -14,10 +14,11 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { writeFileAtomic } from "./common";
-import { ConfigError } from "./errors";
-import { probeLock, releaseLock, tryAcquireLockSync } from "./file-lock";
-import { getCacheDir, getConfigDir } from "./paths";
+import { sleepSync } from "../../runtime.js";
+import { writeFileAtomic } from "../common.js";
+import { ConfigError } from "../errors.js";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
+import { getCacheDir, getConfigDir } from "../paths.js";
 /**
  * Read the raw text of a config file. Returns `undefined` when the file does
  * not exist (legitimate cold-start). Other I/O errors propagate.
@@ -79,22 +80,18 @@ export function writeConfigAtomic(configPath, config) {
 }
 /** Maximum number of timestamped config backups to retain (#459). */
 const MAX_CONFIG_BACKUPS = 5;
-/**
- * Snapshot the current config file to `<cacheDir>/config-backups/`. Writes
- * both a timestamped copy and a `config.latest.json` pointer, then prunes the
- * timestamped set to {@link MAX_CONFIG_BACKUPS} most-recent entries.
- *
- * No-op when the source file does not exist (cold-start safe).
- */
 export function backupExistingConfig(configPath) {
     if (!fs.existsSync(configPath))
-        return;
+        return undefined;
     const backupDir = path.join(getCacheDir(), "config-backups");
     fs.mkdirSync(backupDir, { recursive: true });
     const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    fs.copyFileSync(configPath, path.join(backupDir, `config-${timestamp}.json`));
-    fs.copyFileSync(configPath, path.join(backupDir, "config.latest.json"));
+    const timestamped = path.join(backupDir, `config-${timestamp}.json`);
+    const latest = path.join(backupDir, "config.latest.json");
+    fs.copyFileSync(configPath, timestamped);
+    fs.copyFileSync(configPath, latest);
     pruneOldBackups(backupDir);
+    return { timestamped, latest };
 }
 function pruneOldBackups(backupDir) {
     let entries;
@@ -140,6 +137,14 @@ function getConfigLockPath() {
 }
 const CONFIG_LOCK_MAX_RETRIES = 10;
 const CONFIG_LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Block the current thread for `ms` without busy-spinning (H8). Delegates to
+ * the runtime boundary's `sleepSync`, a real blocking sleep that yields the
+ * thread to the OS scheduler.
+ */
+function sleepSyncMs(ms) {
+    sleepSync(ms);
+}
 /**
  * Acquire an exclusive sentinel around config writes.
  *
@@ -169,11 +174,16 @@ export function acquireConfigLock() {
             continue; // Reclaimed — retry immediately.
         }
         if (attempt < CONFIG_LOCK_MAX_RETRIES - 1) {
-            // Busy spin (synchronous) — config writes are fast.
-            const deadline = Date.now() + CONFIG_LOCK_RETRY_DELAY_MS;
-            while (Date.now() < deadline) {
-                // spin
-            }
+            // H8: yield the thread between retries instead of busy-spinning.
+            // The previous `while (Date.now() < deadline)` loop burned CPU for up to
+            // 50ms per retry (≈500ms total), freezing the single JS thread and
+            // starving co-scheduled work under parallel load. `sleepSync` is a
+            // real blocking sleep that releases the thread to the OS scheduler.
+            // Kept synchronous (rather than an async sleep) to preserve the sync
+            // `withConfigLock` signature and avoid an async ripple through every
+            // `saveConfig`/`loadConfig` caller. Lock semantics are unchanged: same
+            // retry count, same delay budget, same best-effort fall-through.
+            sleepSyncMs(CONFIG_LOCK_RETRY_DELAY_MS);
         }
     }
     // Best-effort: proceed without lock.

package/dist/core/{config-migration.js → config/config-migration.js}

@@ -12,7 +12,8 @@
  * location and stripped from the raw config. Production code reads ONLY the
  * new shape. There are no backward-compat shims after this migration.
  */
-import { warn } from "./warn";
+import { v1ProfilePlatform } from "../../integrations/harnesses/index.js";
+import { warn } from "../warn.js";
 /**
  * Current config schema version sentinel.
  * Configs at this version are considered fully migrated and will not be rewritten.
@@ -579,14 +580,15 @@ export function migrateConfigShape(raw) {
  * platform).
  */
 function guessAgentPlatform(name) {
-    const lower = name.toLowerCase();
-    if (lower === "claude" || lower === "claude-code")
-        return "claude";
-    if (lower.startsWith("opencode-sdk"))
-        return "opencode-sdk";
-    if (lower.startsWith("opencode"))
-        return "opencode";
-    return undefined;
+    // #566: consult the harness registry instead of re-deriving the heuristic.
+    // `v1ProfilePlatform` iterates HARNESS_REGISTRY and asks each harness's own
+    // `matchesV1ProfileName()`, so:
+    //   - 'claude' AND the 'claude-code' alias both resolve to canonical 'claude'
+    //     (the normalization bridge keeps legacy v1 names round-tripping);
+    //   - decorated names like 'opencode-sdk-x' resolve most-specific-first;
+    //   - an unknown harness name returns undefined (caller drops it) instead of
+    //     being silently misclassified. Adding a harness needs no edit here.
+    return v1ProfilePlatform(name);
 }
 /**
  * Map a v1 process name (e.g. `"reflect"`, `"propose"`) to its v2 improve

package/dist/core/{config-schema.js → config/config-schema.js}

@@ -28,6 +28,7 @@
  *   enforced at save time via `superRefine` on the top-level schema.
  */
 import { z } from "zod";
+import { VALID_HARNESS_IDS } from "./config-types.js";
 // ── Reusable atomic schemas ─────────────────────────────────────────────────
 /** Positive integer (used for tokens, timeouts, batch sizes). */
 const positiveInt = z.number().int().positive();
@@ -108,7 +109,9 @@ export const EmbeddingConnectionConfigSchema = z
 })
     .strict();
 // ── Agent profiles ──────────────────────────────────────────────────────────
-const AgentPlatformSchema = z.enum(["opencode", "claude", "opencode-sdk"]);
+// 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);
 export const AgentProfileConfigSchema = z
     .object({
     platform: AgentPlatformSchema,
@@ -126,18 +129,33 @@ export const ImproveProcessConfigSchema = z
     profile: z.string().min(1).optional(),
     timeoutMs: z.union([positiveInt, z.null()]).optional(),
     allowedTypes: z.array(z.string().min(1)).optional(),
+    // Consolidate process: minimum eligible-memory pool size below which the
+    // consolidation pass skips entirely (emits `pool_below_min_size`). 0 disables
+    // the guard. Only meaningful on the `consolidate` process. Default 500.
+    minPoolSize: z.number().int().min(0).optional(),
     qualityGate: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     contradictionDetection: z.object({ enabled: z.boolean().optional() }).strict().optional(),
     // Extract process config (only meaningful for extract process)
     defaultSince: z.string().min(1).optional(),
     maxTotalChars: positiveInt.optional(),
+    // Extract process: 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). Only meaningful
+    // on the `extract` process.
+    minContentChars: z.number().int().min(0).optional(),
     maxChunkSize: z.number().int().min(1).max(50).optional(),
-    // Consolidate process: when set, narrows the candidate pool to memories
-    // modified within this window (e.g. "7d", "48h") plus their graph
-    // neighbours. Useful when consolidation runs more than once per day —
-    // keeps each pass focused on recent changes without re-scanning the full
-    // pool. Leave unset (full-pool sweep) for the nightly default pass.
-    incrementalSince: z.string().min(1).optional(),
+    // Extract process: 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. Only meaningful on the `extract` process. Default 0
+    // (disabled) so existing behaviour is preserved; only opted-in profiles set it.
+    minNewSessions: z.number().int().min(0).optional(),
+    // #561 — index agent sessions as a searchable `session` asset (extract
+    // process). Absent = on-when-an-LLM-is-available (fail-open when offline).
+    indexSessions: z.boolean().optional(),
+    // #561 — minimum session duration in minutes for session indexing. 0
+    // disables the gate. Absent = default 5. Only meaningful on `extract`.
+    minSessionDuration: z.number().min(0).optional(),
     // Triage process config (only meaningful for the `triage` process)
     applyMode: z.enum(["queue", "promote"]).optional(),
     policy: z.string().min(1).optional(),
@@ -231,6 +249,11 @@ export const DefaultsSchema = z
 // ── Sources / registries / installed ────────────────────────────────────────
 const SourceConfigEntryOptionsSchema = z
     .object({
+    /**
+     * @deprecated 0.9.0 (issue #507). Retired per-asset push-on-commit. Kept so
+     * old configs still parse; its intent maps onto the batch push gate and
+     * encountering it emits a one-time deprecation warning.
+     */
     pushOnCommit: z.boolean().optional(),
 })
     .passthrough();
@@ -479,6 +502,25 @@ export const IndexConfigSchema = z.preprocess((raw, ctx) => {
     stalenessDetection: StalenessDetectionSchema.optional(),
 })
     .catchall(IndexPassConfigSchema));
+// ── Setup-derived recommendations ──────────────────────────────────────────
+/**
+ * Cron-style schedule hints derived by `akm setup --reset-recommended`.
+ *
+ * These record the *recommended* cadence for the improve and index background
+ * tasks. They are advisory metadata persisted into config so the value
+ * survives a re-run; actual task scheduling lives in the tasks subsystem.
+ */
+export const SetupTaskSchedulesSchema = z
+    .object({
+    improve: z.string().min(1).optional(),
+    index: z.string().min(1).optional(),
+})
+    .strict();
+export const SetupConfigSchema = z
+    .object({
+    taskSchedules: SetupTaskSchedulesSchema.optional(),
+})
+    .strict();
 // ── Top-level AkmConfig ────────────────────────────────────────────────────
 /**
  * Base object schema used both as the top-level shape and as the source of
@@ -508,6 +550,7 @@ export const AkmConfigShape = {
     feedback: FeedbackConfigSchema.optional(),
     archiveRetentionDays: nonNegativeNumber.optional(),
     improve: ImproveConfigSchema.optional(),
+    setup: SetupConfigSchema.optional(),
 };
 export const AkmConfigBaseSchema = z.object(AkmConfigShape).strict();
 export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {

package/dist/core/config/config-types.js

@@ -0,0 +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/.
+// VALID_HARNESS_IDS now derives from the unified HARNESS_REGISTRY (#562), which
+// is the single source of truth replacing the previously-disconnected
+// registries. config ← harnesses is the only import direction (harnesses/ is a
+// dependency-graph leaf), so there is no cycle.
+import { VALID_HARNESS_IDS } from "../../integrations/harnesses/index.js";
+/**
+ * Canonical list of valid agent harness / platform ids. Re-exported from the
+ * unified harness registry (#562) so the Zod `AgentPlatformSchema` enum, the
+ * `AgentProfileConfigV2` platform union, `parseAgentProfilesMapV2`'s membership
+ * check, and setup's `DetectedHarness` union all derive from one place and
+ * cannot drift. Add a harness in `src/integrations/harnesses/index.ts`.
+ */
+export { VALID_HARNESS_IDS };