akm-cli 0.10.261015-beta → 0.10.261017-beta

package/dist/commands/read/show.js

@@ -20,7 +20,7 @@ import { recognizeMatch } from "../../core/adapter/recognize-match.js";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
+import { extractSection, markdownFragmentSlugs, markdownToc } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
 import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
@@ -297,8 +297,10 @@ export async function showLocal(input) {
     const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
     let response;
+    let markdown = false;
     try {
         if (indexedRenderer === null) {
+            markdown = path.extname(assetPath).toLowerCase() === ".md";
             response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragmentContent);
         }
         else {
@@ -315,8 +317,9 @@ export async function showLocal(input) {
             const renderDefaultBundle = config.defaultBundle ?? (source?.isDefault === true ? renderBundle : undefined);
             const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, renderBundle, renderDefaultBundle);
             response = renderer.buildShowResponse(renderCtx);
+            markdown = match.renderer.endsWith("-md");
             if (parsed.fragment !== undefined) {
-                if (!match.renderer.endsWith("-md")) {
+                if (!markdown) {
                     warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
                 }
                 else {
@@ -324,6 +327,13 @@ export async function showLocal(input) {
                 }
             }
         }
+        // The outline is read from the bytes `#<slug>` resolves against, so every
+        // listed slug selects its section even when the index is stale.
+        if (markdown && parsed.fragment === undefined) {
+            const toc = markdownToc(fileCtx.content());
+            if (toc.length > 0)
+                response.toc = toc;
+        }
     }
     catch (error) {
         throwIndexedPathNotFound(error, input.ref);
@@ -598,6 +608,7 @@ function applyMarkdownResponsePayload(response, content) {
     else
         response.content = content;
 }
+const SHOW_OUTLINE_HINT = "Run `akm show <ref> --detail brief` for the document's outline (`toc`, no body), then `akm show <ref>#<slug>` for one section.";
 function requireMarkdownSection(content, fragment, name) {
     const section = extractSection(content, fragment);
     if (section)
@@ -609,7 +620,7 @@ function requireMarkdownSection(content, fragment, name) {
     }
     const available = markdownFragmentSlugs(content);
     throw new NotFoundError(`Fragment "#${fragment}" not found in ${name}.` +
-        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""));
+        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""), "ASSET_NOT_FOUND", SHOW_OUTLINE_HINT);
 }
 /**
  * Build a reduced brief response from a full ShowResponse.
@@ -625,6 +636,7 @@ function buildBriefResponse(full, assetPath) {
         ...(summary.ref ? { ref: summary.ref } : {}),
         ...(summary.description ? { description: summary.description } : {}),
         ...(summary.action ? { action: summary.action } : {}),
+        ...(full.toc ? { toc: full.toc } : {}),
         ...(summary.run ? { run: summary.run } : {}),
         ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),

package/dist/commands/sources/self-update.js

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS, ResponseTooLargeError, readBodyWithByteCap, readChunkWithDeadline, } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
+import { isQuiet, warn } from "../../core/warn.js";
 import { githubHeaders } from "../../integrations/github.js";
 import { getDirname, mainPath, semverOrder } from "../../runtime.js";
 import { resolveNpmGlobalRoot } from "../../tasks/resolve-akm-bin.js";
@@ -428,7 +428,11 @@ async function runMigrationStep(runTool) {
     return { status: "failed", error: result.stderr.trim() || line || `akm-migrate exited ${result.status}` };
 }
 /**
- * Rebuild the derived index after a successful upgrade.
+ * Rebuild the derived index after a successful upgrade. The first index after
+ * an upgrade can re-embed part of the corpus and take minutes, so the child's
+ * stderr (its progress lines) goes straight to the terminal; its stdout, never a
+ * terminal here, is captured. `--format json` keeps the progress on stderr
+ * whatever output format the user has configured, and `--quiet` is passed on.
  */
 function runPostUpgradeTasks(akmBin, opts) {
     if (opts.skip) {
@@ -439,10 +443,10 @@ function runPostUpgradeTasks(akmBin, opts) {
         };
     }
     try {
-        const result = childProcess.spawnSync(akmBin, ["index"], {
+        const result = childProcess.spawnSync(akmBin, ["index", "--format", "json", ...(isQuiet() ? ["--quiet"] : [])], {
             encoding: "utf8",
             env: process.env,
-            stdio: "pipe",
+            stdio: ["pipe", "pipe", "inherit"],
         });
         if (result.error) {
             return {
@@ -452,7 +456,7 @@ function runPostUpgradeTasks(akmBin, opts) {
             };
         }
         if (result.status !== 0) {
-            const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+            const detail = (result.stdout ?? "").trim() || `exit code ${result.status}`;
             return {
                 ok: false,
                 skipped: false,

package/dist/commands/tasks/tasks.js

@@ -178,10 +178,10 @@ export async function akmTasksRun(id, options = {}) {
     const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
     const resolvedId = taskIdForAdapter(parsed.id, adapterId);
     const scheduled = options.scheduled === true;
-    // Built ONCE at this invocation boundary. eventSource is "task"
-    // whether or not --scheduled was passed — scheduled stays a
-    // separate field carrying its own pre-existing meaning (activation policy,
-    // scheduler env), never selecting the event source.
+    // Built ONCE at this invocation boundary. eventSource is "task" whether or
+    // not --scheduled was passed — scheduled stays a separate field carrying its
+    // own meaning (activation policy, scheduler env), never selecting the event
+    // source.
     const provenance = createExecutionProvenanceContext(scheduled);
     // The raw, exact-name input flags `tasks-cli.ts`'s Stage 1 captures ride
     // through unchanged to `runTask` -> `loadPreparedTask`'s Stage 2 materializer,
@@ -206,8 +206,8 @@ export async function akmTasksRun(id, options = {}) {
     // projectability, and resolver failures therefore create no history row.
     const result = await runTask(resolvedId, runOptions);
     // "command" means the agent/LLM arm — the native shell/script arm reports
-    // "shell" / "script" — so a shell/script task's process exit 78 still passes
-    // through as CLI exit 78 (documented behavior, src/assets/hints/cli-hints-short.md).
+    // "shell" / "script". A shell/script task's process exit 78 passes through
+    // as CLI exit 78 (documented behavior, src/assets/hints/cli-hints-short.md).
     const exitCode = result.status === "failed" &&
         (result.target.kind === "shell" || result.target.kind === "script") &&
         result.detail?.exitCode === 78
@@ -597,10 +597,9 @@ export async function akmTasksDoctor(deps = {}) {
     const config = loadConfig();
     const defaultEngine = (defaultHarness(config) ?? defaultConnection(config))?.name;
     const engines = [...Object.keys(config.connections ?? {}), ...Object.keys(config.harnesses ?? {})];
-    // §6.1: surface the effective triage settings for the default improve
-    // strategy. The struct is a fixed shape, so this is a deliberate addition.
+    // Surface the effective triage settings for the default improve strategy.
     const improveStrategyName = config.improve?.strategy ?? "default";
-    // D8 — report the EFFECTIVE strategy, not the raw one. Resolving the raw
+    // Report the EFFECTIVE strategy, not the raw one. Resolving the raw
     // strategy here would report `applyMode: "promote"` for a promote strategy
     // under a review-first config, while the run actually uses "queue" — a doctor
     // command lying about the thing it exists to diagnose.
@@ -753,7 +752,7 @@ function errorMessage(cause) {
 }
 /**
  * Infer a JSON-Schema-subset `type` keyword from one `--params` value's
- * runtime shape. `null` is not one of the five runtime types
+ * runtime shape. `null` is not one of the five usual runtime types
  * (string/number/boolean/object/array) but is a value JSON.parse can still
  * produce for a param; `src/core/json-schema.ts`'s subset validator accepts
  * `"null"` as a `type`, so it is handled rather than mis-typed.
@@ -768,9 +767,9 @@ function jsonSchemaTypeOf(value) {
 /**
  * Render `--params` as typed `inputs:` declarations, one per key, each
  * carrying a `default:` equal to the authored value and a `type:` inferred
- * from its own JSON runtime shape (row B-20). Never emitted as `with:` —
- * task source v4 accepts `with:` only on `uses: akm/command` (§3.2.6's
- * `parseTarget`/`checkTopLevelKeys`), and a workflow target's declared
+ * from its own JSON runtime shape. Never emitted as `with:` —
+ * task source v4 accepts `with:` only on `uses: akm/command`
+ * (`parseTarget`/`checkTopLevelKeys`), and a workflow target's declared
  * inputs are what `load-task.ts`'s existing v4 delivery override binds into
  * the child run's params.
  */

package/dist/core/adapter/adapters/agent-skills-adapter.js

@@ -2,7 +2,7 @@
 // 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/.
 /**
- * The `agent-skills` adapter — akm 0.9.0 format-family work item (#46).
+ * The `agent-skills` adapter.
  *
  * Recognizes a COLLECTION of standalone SKILL.md packages (like
  * github.com/anthropics/skills): each `<name>/SKILL.md` is one `skill` item
@@ -38,7 +38,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/agent-skills/` + goldens
- * `tests/fixtures/format-family-goldens/agent-skills/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/agent-skills/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -52,7 +52,7 @@ const SKILL_MANIFEST = "SKILL.md";
 /** Agent Skills hard limits. */
 const NAME_MAX = 64;
 const DESCRIPTION_MAX = 1024;
-/** Agent Skills reserved words a name must not contain (real-world source). */
+/** Agent Skills reserved words a name must not contain. */
 const RESERVED_NAME_WORDS = ["anthropic", "claude"];
 /** name charset/shape rule. */
 const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
@@ -98,7 +98,7 @@ function recognize(c, file) {
         doc.tags = tags;
     return doc;
 }
-/** The Agent Skills §4.5 hard-rule checks for one SKILL.md (name + description). */
+/** The Agent Skills hard-rule checks for one SKILL.md (name + description). */
 function skillFieldDiagnostics(relPath, dirName, data) {
     const diagnostics = [];
     const name = typeof data.name === "string" ? data.name.normalize("NFKC") : "";
@@ -176,8 +176,8 @@ async function scanPackageCandidate(dir, entries, ctx, depth) {
  *
  * `validate` walks CHANGES, and a change is always a file — so a package
  * directory carrying resources but no manifest contributes nothing the
- * change-loop can see, and the check the spec (§4.5) and the lint golden's
- * `missingSkillMd` edge case both name was unreachable. This scans the
+ * change-loop can see, and the check the lint golden's `missingSkillMd` edge
+ * case names would be unreachable. This scans the
  * component root through {@link ValidateContext.list} instead, so the case is
  * actually reported.
  *
@@ -230,7 +230,7 @@ export const agentSkillsAdapter = {
     readCandidates(c, conceptId) {
         return [{ path: path.join(c.root, conceptId, SKILL_MANIFEST), conceptId }];
     },
-    /** Install-time probe (§1.2): a root that directly contains one or more `<name>/SKILL.md` skill packages. */
+    /** Install-time probe: a root that directly contains one or more `<name>/SKILL.md` skill packages. */
     looksLikeRoot(root) {
         let entries;
         try {

package/dist/core/adapter/adapters/akm-task-adapter.js

@@ -26,7 +26,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
- * `tests/fixtures/format-family-goldens/akm-task/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/akm-task/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/akm-workflow-adapter.js

@@ -15,7 +15,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-workflow/` + goldens
- * `tests/fixtures/format-family-goldens/akm-workflow/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/akm-workflow/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/claude-adapter.js

@@ -16,7 +16,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/claude/` + goldens
- * `tests/fixtures/format-family-goldens/claude/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/claude/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -25,7 +25,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/dotenv/` + goldens
- * `tests/fixtures/format-family-goldens/dotenv/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/dotenv/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -19,7 +19,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/generic-files/` + goldens
- * `tests/fixtures/format-family-goldens/generic-files/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/generic-files/{recognition,lint,renderer}.json`.
  */
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -11,7 +11,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/llm-wiki/` + goldens
- * `tests/fixtures/format-family-goldens/llm-wiki/{recognition,placement,renderer,lint}.json`.
+ * `tests/fixtures/format-family-goldens/llm-wiki/{recognition,renderer,lint}.json`.
  * The adapter is built to MATCH those goldens (driven by
  * `tests/core/adapter/llm-wiki-adapter.test.ts`).
  *

package/dist/core/adapter/adapters/opencode-adapter.js

@@ -16,7 +16,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/opencode/` + goldens
- * `tests/fixtures/format-family-goldens/opencode/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/opencode/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -22,7 +22,7 @@
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/website-snapshot/` + goldens
- * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,placement,lint,renderer}.json`.
+ * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,lint,renderer}.json`.
  */
 import fs from "node:fs";
 import path from "node:path";

package/dist/core/asset/markdown.js

@@ -16,6 +16,15 @@ export function markdownHeadingSlug(heading) {
 export function markdownFragmentSlugs(content) {
     return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
 }
+/**
+ * The headings `extractSection` can select, with the slug it resolves each by.
+ * A heading with no sluggable text has no selector, so it is left out.
+ */
+export function markdownToc(content) {
+    const headings = parseMarkdownToc(content).headings;
+    const slugs = uniqueHeadingSlugs(headings);
+    return headings.flatMap((heading, index) => slugs[index] ? [{ level: heading.level, text: heading.text, slug: slugs[index], startLine: heading.line }] : []);
+}
 /** One slug per heading, in order; a heading with no sluggable text gets "". */
 export function uniqueHeadingSlugs(headings) {
     const used = new Set();

package/dist/core/bundle-rename.js

@@ -6,7 +6,9 @@
  * bundle's key. A bundle id is a mass identity prefix: every durable ref this
  * tool minted (`entries.item_ref`/`bundle_id`, `proposals.ref`, a pending
  * proposal's `proposedTarget.source`, a workflow task_history row's
- * `target_ref`, a `workflow_runs.workflow_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
+ * `target_ref`, a `workflow_runs.workflow_ref`, a `usage_events.entry_ref`, an
+ * `events.ref`, an `asset_salience`/`asset_outcome` `asset_ref`, an
+ * `improve_ledger.ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
  * `bundles` key strands all of it (see `src/indexer/bundle-identity-guard.ts`
  * §11.5). This module is the rekey transaction that guard's docstring points
  * to.
@@ -20,17 +22,17 @@
  * `akm mv`/editing territory, not a config-identity rename. `--dry-run`
  * (and every real run) lists the indexed files that still spell the old
  * `<old>//` prefix so the operator can follow up.
- *
- * Left behind on purpose: `usage_events`/`asset_salience`/`asset_outcome`
- * keyed by the old bundle prefix (learned utility/outcome history) — outside
- * this item's scope; `warnOnBundleRenameDrift` already documents this class
- * of gap and `akm index --full` re-mints under the new id.
  */
 import fs from "node:fs";
+import { renameUsageEventRefs } from "../indexer/usage/usage-events.js";
 import { readLockfile, renameLockEntry } from "../integrations/lockfile.js";
+import { renameEventRefs } from "../storage/repositories/events-repository.js";
+import { renameImproveLedgerRefs } from "../storage/repositories/improve-ledger-repository.js";
 import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
+import { renameAssetOutcomeRefs } from "../storage/repositories/outcome-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
+import { renameAssetSalienceRefs } from "../storage/repositories/salience-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
 import { countWorkflowRunRefsForRename, renameWorkflowRunRefs } from "../storage/repositories/workflow-runs-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
@@ -262,12 +264,20 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
         }
     }
     // State: proposals.ref, a pending proposal's proposedTarget.source,
-    // workflow task_history.target_ref, and workflow_runs.workflow_ref.
+    // workflow task_history.target_ref, workflow_runs.workflow_ref, and the
+    // learned history keyed by item ref: usage_events.entry_ref (search ranking
+    // counts feedback by it), events.ref and improve_ledger.ref (improve reads
+    // feedback and its own attempts by them), and asset_salience/asset_outcome.asset_ref.
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             renameProposalsBundleRef(db, oldId, newId);
             renameTaskHistoryTargetRefs(db, oldId, newId);
             renameWorkflowRunRefs(db, oldId, newId);
+            renameUsageEventRefs(db, oldId, newId);
+            renameEventRefs(db, oldId, newId);
+            renameImproveLedgerRefs(db, oldId, newId);
+            renameAssetSalienceRefs(db, oldId, newId);
+            renameAssetOutcomeRefs(db, oldId, newId);
         });
     }
     // Scheduler: remove native rows still naming `<old>//` (see

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

@@ -27,7 +27,7 @@ import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../
 import { warnOnce } from "../warn.js";
 import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
-import { isEnvReference } from "./schema/primitives.js";
+import { isEnvReference, OpaqueFieldSchema } from "./schema/primitives.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -46,33 +46,39 @@ function parsePath(dotted) {
 function unwrap(schema) {
     let current = schema;
     while (true) {
-        if (current instanceof z.ZodOptional) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodDefault) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodNullable) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodCatch) {
+        if (current instanceof z.ZodOptional ||
+            current instanceof z.ZodDefault ||
+            current instanceof z.ZodNullable ||
             // `.catch(...)` wraps an inner schema with a fallback value.
-            current = current._def.innerType;
+            current instanceof z.ZodCatch ||
+            current instanceof z.ZodReadonly) {
+            current = current.def.innerType;
         }
-        else if (current instanceof z.ZodEffects) {
-            // `.refine()` / `.superRefine()` / `.transform()` / `.preprocess()` —
-            // descend into the inner schema (`schema` for refine/transform, `out`
-            // for preprocess — both are exposed at `_def.schema`).
-            current = current._def.schema;
-        }
-        else if (current instanceof z.ZodReadonly) {
-            current = current._def.innerType;
+        else if (current instanceof z.ZodPipe) {
+            // `.transform()` pipes the schema into a transform and `z.preprocess()` pipes a transform into it:
+            // descend into the side that is a schema. (`.refine()` and `.superRefine()` wrap nothing.)
+            const { in: input, out } = current.def;
+            current = (input instanceof z.ZodTransform ? out : input);
         }
         else {
             return current;
         }
     }
 }
+/**
+ * The schema of the keys an object takes without naming them (`index.<passName>`,
+ * a connection's request fields), or `undefined` when its extra keys are not
+ * ones akm defines. `.passthrough()` gives an object an `unknown` catchall, so
+ * only `OpaqueFieldSchema` itself says "any key, contents left to the endpoint".
+ */
+function namedCatchall(object) {
+    const catchall = object.def.catchall;
+    if (catchall === undefined || catchall instanceof z.ZodNever)
+        return undefined;
+    if (catchall instanceof z.ZodUnknown && catchall !== OpaqueFieldSchema)
+        return undefined;
+    return catchall;
+}
 /** True for a schema that accepts any value (`z.unknown()`): its contents are not keys akm defines. */
 export function isOpaqueSchema(schema) {
     return unwrap(schema) instanceof z.ZodUnknown;
@@ -91,13 +97,10 @@ export function resolveSchemaAt(path, config, raw) {
             const next = schema.shape[segment];
             if (!next) {
                 // Catchall (e.g. index.<passName>) — descend into the catchall schema.
-                const catchall = schema._def.catchall;
-                if (catchall && !(catchall instanceof z.ZodNever)) {
-                    schema = catchall;
-                }
-                else {
+                const catchall = namedCatchall(schema);
+                if (!catchall)
                     return undefined;
-                }
+                schema = catchall;
             }
             else {
                 schema = next;
@@ -106,13 +109,13 @@ export function resolveSchemaAt(path, config, raw) {
         else if (schema instanceof z.ZodRecord) {
             // Named records (connections, harnesses, improve.strategies, sources, etc.)
             // accept any string key — descend into the value schema.
-            schema = schema._def.valueType;
+            schema = schema.def.valueType;
         }
         else if (schema instanceof z.ZodUnion) {
-            const option = selectUnionObjectOption(schema._def.options, segment, existing, index === path.length - 1 ? raw : undefined);
+            const option = selectUnionObjectOption(schema.options, segment, existing, index === path.length - 1 ? raw : undefined);
             if (!option)
                 return undefined;
-            schema = (option.shape[segment] ?? option._def.catchall);
+            schema = (option.shape[segment] ?? namedCatchall(option));
         }
         else {
             // Cannot descend into a non-object schema.
@@ -145,7 +148,7 @@ function selectUnionObjectOption(candidates, segment, existing, raw) {
     }
     return (options.find((option) => segment in option.shape) ??
         // A model entry such as `{ model, reasoning_effort }` holds request fields the object does not name.
-        options.find((option) => !(option._def.catchall instanceof z.ZodNever)));
+        options.find((option) => namedCatchall(option) !== undefined));
 }
 /**
  * Get the value at the dotted path from a config-shaped object. Returns
@@ -350,7 +353,7 @@ function coerceForSchema(schema, raw, key) {
         return raw;
     }
     if (target instanceof z.ZodLiteral) {
-        return typeof target._def.value === "string" ? raw : target._def.value;
+        return typeof target.value === "string" ? raw : target.value;
     }
     if (target instanceof z.ZodArray || target instanceof z.ZodObject || target instanceof z.ZodRecord) {
         if (raw === "" || raw === "null")
@@ -366,7 +369,7 @@ function coerceForSchema(schema, raw, key) {
     if (target instanceof z.ZodUnion) {
         // Try each option in order. Use the first that the schema accepts after
         // coercion. Falls through to JSON parsing if all fail.
-        const options = target._def.options;
+        const options = target.options;
         let lastErr;
         for (const opt of options) {
             try {

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

@@ -12,7 +12,7 @@
  */
 import { z } from "zod";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
-import { connectionEndpoint, engineName, envReferenceApiKey, nonEmptyString, positiveInt, retiredApiKeyFile, } from "./primitives.js";
+import { connectionEndpoint, engineName, envReferenceApiKey, nonEmptyString, OpaqueFieldSchema, positiveInt, retiredApiKeyFile, } from "./primitives.js";
 /**
  * Timeouts share the workflow ceiling: a larger value would pass config
  * validation and then fail every run with an unlocated "invocation is invalid".
@@ -24,7 +24,10 @@ export const timeoutMsField = z.union([positiveInt.max(WORKFLOW_MAX_TIMEOUT_MS),
  * request fields of its own. The object is listed first so a JSON value given to
  * `akm config set` is read as one.
  */
-export const ModelEntrySchema = z.union([z.object({ model: nonEmptyString }).catchall(z.unknown()), nonEmptyString]);
+export const ModelEntrySchema = z.union([
+    z.object({ model: nonEmptyString }).catchall(OpaqueFieldSchema),
+    nonEmptyString,
+]);
 /** Alias (`fast`, `balanced`, `reasoning`, or any the user adds) to the model it names. */
 export const ModelAliasesSchema = z.record(nonEmptyString, ModelEntrySchema);
 export const ConnectionSchema = z
@@ -37,5 +40,5 @@ export const ConnectionSchema = z
     timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
 })
-    .catchall(z.unknown());
+    .catchall(OpaqueFieldSchema);
 export const ConnectionsSchema = z.record(engineName, ConnectionSchema);

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

@@ -13,7 +13,14 @@ import { ModelAliasesSchema, timeoutMsField } from "./connections.js";
 import { engineName, nonEmptyString } from "./primitives.js";
 export const HarnessSchema = z
     .object({
-    platform: z.enum(HARNESS_CONFIG_PLATFORMS).optional(),
+    // Zod 4's message for a value outside an enum no longer quotes the value; the warning for a dropped harness should.
+    platform: z
+        .enum(HARNESS_CONFIG_PLATFORMS, {
+        error: (issue) => issue.code === "invalid_value"
+            ? `${JSON.stringify(issue.input)} is not one of ${HARNESS_CONFIG_PLATFORMS.join(", ")}`
+            : undefined,
+    })
+        .optional(),
     bin: nonEmptyString.optional(),
     args: z.array(z.string()).optional(),
     workspace: nonEmptyString.optional(),

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

@@ -12,11 +12,22 @@ import { redactUrlCredentials } from "../../redaction.js";
 import { isSecretRefToken } from "../../ref-token.js";
 import { warnOnce } from "../../warn.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
+// Zod 4 reports a map key its key schema rejects as "Invalid key in record" and keeps that schema's own message
+// (the naming rule, the slug rule) inside the issue; config errors and warnings print only the outer message.
+z.config({
+    customError: (issue) => issue.code === "invalid_key" ? issue.issues.map((inner) => inner.message).join("; ") : undefined,
+});
 /** Persisted config schema version. Package prerelease/patch versions do not change this value. */
 export const CURRENT_CONFIG_VERSION = "0.9.0";
 // ── Reusable atomic schemas ─────────────────────────────────────────────────
 /** Positive integer (used for tokens, timeouts, batch sizes). */
 export const positiveInt = z.number().int().positive();
+/**
+ * The catchall of an object whose extra keys are the endpoint's to define (a connection's request fields):
+ * any key, contents left alone. The config walker knows it by identity: a `.passthrough()` object also has an
+ * `unknown` catchall, and its extra keys are ones akm does not define.
+ */
+export const OpaqueFieldSchema = z.unknown();
 /** Non-negative finite number (used for scores, weights, days). */
 export const nonNegativeNumber = z.number().finite().min(0);
 /** Non-empty string (rejects "" and whitespace-only). */
@@ -92,7 +103,7 @@ export const connectionEndpoint = z.string().superRefine((value, ctx) => {
         warnOnce(`connectionEndpoint:userinfo:${shown}`, `Config endpoint "${shown}" embeds a username/password; move the credential out of the URL (apiKey: "$VAR", or credentials.json).`);
     }
 });
-export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx) => {
+export const ExtraParamsSchema = z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
     for (const issue of validateExtraParams(value)) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: issue.path, message: issue.message });
     }

package/dist/core/config/schema/sources-bundles.js

@@ -16,7 +16,7 @@ import { isBundleSlug } from "../../asset/asset-ref.js";
 import { httpUrl, isApiKeyReference, nonEmptyString, positiveInt } from "./primitives.js";
 const VALID_ADAPTER_IDS_SET = new Set(VALID_ADAPTER_IDS);
 // ── Sources / registries / installed ────────────────────────────────────────
-const SourceConfigEntryOptionsSchema = z.record(z.unknown());
+const SourceConfigEntryOptionsSchema = z.record(z.string(), z.unknown());
 export const SourceConfigEntrySchema = z
     .object({
     type: nonEmptyString,
@@ -74,7 +74,7 @@ export const RegistryConfigEntrySchema = z
     name: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
     provider: z.string().min(1).optional(),
-    options: z.record(z.unknown()).optional(),
+    options: z.record(z.string(), z.unknown()).optional(),
 })
     .passthrough();
 // ── Bundles ─────────────────────────────────────────────────────────────────