akm-cli 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -6,6 +6,43 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-08-29
+
+### Fixed
+
+- **A failing Windows `shell: powershell`/`pwsh` task could lose its exit
+  code's fidelity through `-Command` (#845).** `-Command` derives its own
+  process exit code from `$?`, so a genuinely failing command already
+  produced a nonzero exit and `status: "failed"` — but any native exit code
+  outside `{0, 1}` was collapsed to `1`, discarding the real value reported
+  in task history. The inner shell invocation built by `shellCommand()` now
+  appends a guard that reads `$?` first (reproducing `-Command`'s own
+  completed/failed determination, immune to a stale `$LASTEXITCODE` from an
+  earlier native call in the same command) and only then upgrades to the
+  precise native exit code when the failing last statement actually set
+  one — a bare `exit $LASTEXITCODE` was rejected because `$LASTEXITCODE`
+  stays `$null` for a pure-PowerShell command, and `exit $null` is exit
+  code `0`, which would have turned a failed cmdlet into a false
+  `"completed"`. Verified via unit tests asserting the exact argv `-Command`
+  string on `platform: "win32"`; the runtime exit-code behavior itself is
+  unverified on a real Windows host pending the owner's manual run (see the
+  PR body for the procedure) — Windows scheduler paths still have no
+  automated coverage (#770).
+- **A valid 0.9.1 config hard-failed to load after upgrading to 0.9.2
+  (#852).** `reasoningEffort` became a first-class `engines.<name>` field in
+  0.9.2 (#815), so `extraParams.reasoning_effort` — the documented 0.9.1
+  workaround for LM Studio, where `enableThinking` is a no-op — started
+  tripping the extraParams protected-key check and hard-failing every
+  command that loads config, with no migration. Config load now lifts
+  `extraParams.{reasoning_effort,temperature,maxtokens,enablethinking}`
+  onto their first-class field automatically (in-memory only; the file is
+  not rewritten, and a warning names each lifted key) unless the
+  extraParams value and the first-class field disagree, in which case
+  config load still fails, now naming both values and the field to keep.
+  Any other protected `extraParams` key without a first-class equivalent
+  still hard-fails, but the error now names the fix instead of only the
+  rule.
+
 ## [0.9.2] - 2026-08-29
 
 ### Fixed

package/dist/core/config/config.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../errors.js";
+import { liftLegacyEngineExtraParams } from "../extra-params.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
 import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
 import { bundlesToSourceEntries } from "./config-sources.js";
@@ -141,14 +142,29 @@ export function acquireConfigReadFence() {
  * canonical shape before defaults are merged.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const raw = parseConfigText(text, sourcePath);
-    if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+    const parsedRaw = parseConfigText(text, sourcePath);
+    if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
         throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
     }
+    // #852 (following #815): lift legacy `extraParams` keys — e.g.
+    // `reasoning_effort`, a documented 0.9.1 workaround — onto the first-class
+    // engine field they now shadow, before the protected-key check in
+    // `ExtraParamsSchema` gets a chance to hard-reject them. In-memory only;
+    // never written back to the file.
+    const { config: raw, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    if (conflicts.length > 0) {
+        const lines = conflicts
+            .map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`)
+            .join("\n");
+        throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:\n${lines}\n\nEach extraParams key above has a first-class equivalent and akm will not guess which value you meant — remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
+    }
+    if (lifted.length > 0) {
+        warn(`Config${where} uses deprecated extraParams keys with first-class equivalents; treating them as the first-class fields for this run (not written back to the file):\n  - ${lifted.join("\n  - ")}`);
+    }
     const parsed = AkmConfigSchema.safeParse(raw);
     if (!parsed.success) {
         const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
-        const where = sourcePath ? ` at ${sourcePath}` : "";
         throw new ConfigError(`Invalid config${where}:\n${lines}`, "INVALID_CONFIG_FILE");
     }
     const merged = deepMergeConfig(DEFAULT_CONFIG, parsed.data);

package/dist/core/extra-params.js

@@ -25,6 +25,46 @@ export const EXTRA_PARAMS_CREDENTIAL_KEYS = [
 ];
 const PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
 const CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+// ── Protected-key remedies (#852) ───────────────────────────────────────────
+//
+// `EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS` rightly stops a provider extra from
+// shadowing an AKM-managed field, but naming the rule without naming the fix
+// leaves the reader stuck (#852). Every protected key gets a one-line remedy
+// baked into its issue message; keys with a genuine scalar first-class field
+// are also eligible for the automatic config-load lift below.
+/** normalizeExtraParamKey(key) -> the first-class engine field it shadows. */
+const LEGACY_EXTRA_PARAMS_FIELD = {
+    model: "model",
+    temperature: "temperature",
+    maxtokens: "maxTokens",
+    enablethinking: "enableThinking",
+    reasoningeffort: "reasoningEffort",
+};
+/**
+ * Subset of {@link LEGACY_EXTRA_PARAMS_FIELD} that {@link liftLegacyEngineExtraParams}
+ * will move onto the first-class field automatically. `model` is deliberately
+ * excluded: unlike the others it was never a "no first-class field yet"
+ * workaround (`model` has always been required on an LLM engine), so a
+ * mismatch is far more likely a genuine mistake than a stale 0.9.1 config —
+ * it stays a hard rejection rather than being silently reinterpreted.
+ */
+const LIFTABLE_EXTRA_PARAMS_KEYS = new Set(["temperature", "maxtokens", "enablethinking", "reasoningeffort"]);
+/** Remedies for protected keys with no scalar first-class field to lift onto. */
+const EXTRA_PARAMS_NO_FIELD_REMEDY = {
+    messages: "AKM builds the request messages internally — remove it from extraParams",
+    responseformat: "AKM controls the response format internally — remove it from extraParams",
+    stream: "AKM controls streaming internally — remove it from extraParams",
+    streamoptions: "AKM controls streaming internally — remove it from extraParams",
+    chattemplatekwargs: "set engines.<name>.enableThinking instead of chat_template_kwargs.enable_thinking",
+};
+function protectedKeyRemedy(normalized) {
+    const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+    if (field) {
+        const note = normalized === "reasoningeffort" ? " (moved to a first-class field in 0.9.2)" : "";
+        return `set engines.<name>.${field} instead${note}`;
+    }
+    return EXTRA_PARAMS_NO_FIELD_REMEDY[normalized];
+}
 export function normalizeExtraParamKey(key) {
     return key.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
@@ -57,7 +97,11 @@ export function validateExtraParams(value) {
         for (const [key, child] of Object.entries(entry)) {
             const normalized = normalizeExtraParamKey(key);
             if (path.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
-                issues.push({ path: [key], message: `${key} is protected by AKM` });
+                const remedy = protectedKeyRemedy(normalized);
+                issues.push({
+                    path: [key],
+                    message: remedy ? `${key} is protected by AKM — ${remedy}.` : `${key} is protected by AKM`,
+                });
             }
             if (CREDENTIAL_KEYS.has(normalized)) {
                 issues.push({ path: [...path, key], message: `${key} cannot carry credentials` });
@@ -72,3 +116,73 @@ export function formatExtraParamsIssue(label, issue) {
     const suffix = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${part}`)).join("");
     return `${label}${suffix} ${issue.message}`;
 }
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Lift legacy `extraParams` keys onto their first-class engine field before
+ * schema validation runs, so a 0.9.1-shaped config using (e.g.)
+ * `extraParams.reasoning_effort` keeps loading now that `reasoningEffort` is
+ * a first-class — and therefore protected — field (#852, following #815).
+ *
+ * In-memory only: this never rewrites the config file. Callers should warn
+ * using the returned `lifted` descriptions so the user knows to update the
+ * file by hand, and reject using `conflicts` rather than silently preferring
+ * either value.
+ */
+export function liftLegacyEngineExtraParams(raw) {
+    const lifted = [];
+    const conflicts = [];
+    const rawEngines = raw.engines;
+    if (!isPlainObject(rawEngines)) {
+        return { config: raw, lifted, conflicts };
+    }
+    const engines = {};
+    let anyEngineChanged = false;
+    for (const [name, engineValue] of Object.entries(rawEngines)) {
+        if (!isPlainObject(engineValue) || !isPlainObject(engineValue.extraParams)) {
+            engines[name] = engineValue;
+            continue;
+        }
+        const engine = { ...engineValue };
+        const extraParams = { ...engineValue.extraParams };
+        let engineChanged = false;
+        for (const [rawKey, value] of Object.entries(engineValue.extraParams)) {
+            const normalized = normalizeExtraParamKey(rawKey);
+            if (!LIFTABLE_EXTRA_PARAMS_KEYS.has(normalized))
+                continue;
+            const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+            if (!field)
+                continue;
+            const existing = engine[field];
+            if (existing !== undefined && existing !== value) {
+                conflicts.push({ engine: name, key: rawKey, field, extraParamsValue: value, fieldValue: existing });
+                continue;
+            }
+            delete extraParams[rawKey];
+            engineChanged = true;
+            if (existing === value) {
+                lifted.push(`engines.${name}.extraParams.${rawKey} is redundant — engines.${name}.${field} is already set to the same value; dropped the extraParams entry`);
+                continue;
+            }
+            engine[field] = value;
+            lifted.push(`engines.${name}.extraParams.${rawKey} -> engines.${name}.${field}`);
+        }
+        if (!engineChanged) {
+            engines[name] = engineValue;
+            continue;
+        }
+        anyEngineChanged = true;
+        if (Object.keys(extraParams).length > 0) {
+            engine.extraParams = extraParams;
+        }
+        else {
+            delete engine.extraParams;
+        }
+        engines[name] = engine;
+    }
+    if (!anyEngineChanged) {
+        return { config: raw, lifted, conflicts };
+    }
+    return { config: { ...raw, engines }, lifted, conflicts };
+}

package/dist/scripts/akm-migrate-node.js

@@ -16471,6 +16471,29 @@ var EXTRA_PARAMS_CREDENTIAL_KEYS = [
 ];
 var PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
 var CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+var LEGACY_EXTRA_PARAMS_FIELD = {
+  model: "model",
+  temperature: "temperature",
+  maxtokens: "maxTokens",
+  enablethinking: "enableThinking",
+  reasoningeffort: "reasoningEffort"
+};
+var LIFTABLE_EXTRA_PARAMS_KEYS = new Set(["temperature", "maxtokens", "enablethinking", "reasoningeffort"]);
+var EXTRA_PARAMS_NO_FIELD_REMEDY = {
+  messages: "AKM builds the request messages internally — remove it from extraParams",
+  responseformat: "AKM controls the response format internally — remove it from extraParams",
+  stream: "AKM controls streaming internally — remove it from extraParams",
+  streamoptions: "AKM controls streaming internally — remove it from extraParams",
+  chattemplatekwargs: "set engines.<name>.enableThinking instead of chat_template_kwargs.enable_thinking"
+};
+function protectedKeyRemedy(normalized) {
+  const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+  if (field) {
+    const note = normalized === "reasoningeffort" ? " (moved to a first-class field in 0.9.2)" : "";
+    return `set engines.<name>.${field} instead${note}`;
+  }
+  return EXTRA_PARAMS_NO_FIELD_REMEDY[normalized];
+}
 function normalizeExtraParamKey(key) {
   return key.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
@@ -16498,7 +16521,11 @@ function validateExtraParams(value) {
     for (const [key, child] of Object.entries(entry)) {
       const normalized = normalizeExtraParamKey(key);
       if (path9.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
-        issues.push({ path: [key], message: `${key} is protected by AKM` });
+        const remedy = protectedKeyRemedy(normalized);
+        issues.push({
+          path: [key],
+          message: remedy ? `${key} is protected by AKM — ${remedy}.` : `${key} is protected by AKM`
+        });
       }
       if (CREDENTIAL_KEYS.has(normalized)) {
         issues.push({ path: [...path9, key], message: `${key} cannot carry credentials` });
@@ -16513,6 +16540,64 @@ function formatExtraParamsIssue(label, issue) {
   const suffix = issue.path.map((part) => typeof part === "number" ? `[${part}]` : `.${part}`).join("");
   return `${label}${suffix} ${issue.message}`;
 }
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function liftLegacyEngineExtraParams(raw) {
+  const lifted = [];
+  const conflicts = [];
+  const rawEngines = raw.engines;
+  if (!isPlainObject2(rawEngines)) {
+    return { config: raw, lifted, conflicts };
+  }
+  const engines = {};
+  let anyEngineChanged = false;
+  for (const [name, engineValue] of Object.entries(rawEngines)) {
+    if (!isPlainObject2(engineValue) || !isPlainObject2(engineValue.extraParams)) {
+      engines[name] = engineValue;
+      continue;
+    }
+    const engine = { ...engineValue };
+    const extraParams = { ...engineValue.extraParams };
+    let engineChanged = false;
+    for (const [rawKey, value] of Object.entries(engineValue.extraParams)) {
+      const normalized = normalizeExtraParamKey(rawKey);
+      if (!LIFTABLE_EXTRA_PARAMS_KEYS.has(normalized))
+        continue;
+      const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+      if (!field)
+        continue;
+      const existing = engine[field];
+      if (existing !== undefined && existing !== value) {
+        conflicts.push({ engine: name, key: rawKey, field, extraParamsValue: value, fieldValue: existing });
+        continue;
+      }
+      delete extraParams[rawKey];
+      engineChanged = true;
+      if (existing === value) {
+        lifted.push(`engines.${name}.extraParams.${rawKey} is redundant — engines.${name}.${field} is already set to the same value; dropped the extraParams entry`);
+        continue;
+      }
+      engine[field] = value;
+      lifted.push(`engines.${name}.extraParams.${rawKey} -> engines.${name}.${field}`);
+    }
+    if (!engineChanged) {
+      engines[name] = engineValue;
+      continue;
+    }
+    anyEngineChanged = true;
+    if (Object.keys(extraParams).length > 0) {
+      engine.extraParams = extraParams;
+    } else {
+      delete engine.extraParams;
+    }
+    engines[name] = engine;
+  }
+  if (!anyEngineChanged) {
+    return { config: raw, lifted, conflicts };
+  }
+  return { config: { ...raw, engines }, lifted, conflicts };
+}
 
 // src/workflows/source-ir/compare.ts
 function compareWorkflowSourceCodePoints(left, right) {
@@ -21777,11 +21862,11 @@ var CONSUMED_FRONTMATTER_KEYS = [
   "stale_after",
   "okf_version"
 ];
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function parseActorMapping(value) {
-  if (!isPlainObject2(value))
+  if (!isPlainObject3(value))
     return;
   const by = nonEmptyString(value.by);
   if (by === undefined)
@@ -21806,7 +21891,7 @@ function parseOkfSources(value) {
     return;
   const out = [];
   for (const item of value) {
-    if (!isPlainObject2(item))
+    if (!isPlainObject3(item))
       continue;
     const resource = nonEmptyString(item.resource);
     if (resource === undefined)
@@ -21912,7 +21997,7 @@ function recognize8(c, file) {
   const description = nonEmptyString(data.description);
   const tags = readTags(data.tags);
   const links = resolveOkfLinks(body, file.relPath);
-  const generatedMapping = isPlainObject2(data.generated) ? data.generated : undefined;
+  const generatedMapping = isPlainObject3(data.generated) ? data.generated : undefined;
   const generatedAt = generatedMapping ? nonEmptyString(generatedMapping.at) : undefined;
   const generatedBy = generatedMapping ? nonEmptyString(generatedMapping.by) : undefined;
   const legacyTimestamp = nonEmptyString(data.timestamp);
@@ -27542,7 +27627,7 @@ var AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
 
 // src/core/config/deep-merge.ts
 var UNSAFE_KEYS3 = new Set(["__proto__", "constructor", "prototype"]);
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value))
     return false;
   const prototype = Object.getPrototypeOf(value);
@@ -27551,7 +27636,7 @@ function isPlainObject3(value) {
 function copyConfigValue(value) {
   if (Array.isArray(value))
     return value.map(copyConfigValue);
-  if (!isPlainObject3(value))
+  if (!isPlainObject4(value))
     return value;
   const copy = {};
   for (const key of Object.keys(value)) {
@@ -27570,7 +27655,7 @@ function deepMergeConfig(base, override) {
     if (next === undefined)
       continue;
     const current = result[key];
-    result[key] = isPlainObject3(current) && isPlainObject3(next) ? deepMergeConfig(current, next) : copyConfigValue(next);
+    result[key] = isPlainObject4(current) && isPlainObject4(next) ? deepMergeConfig(current, next) : copyConfigValue(next);
   }
   return result;
 }
@@ -27630,15 +27715,29 @@ function loadUserConfig() {
   return finalConfig;
 }
 function parseAndValidateConfigText(text, sourcePath) {
-  const raw = parseConfigText(text, sourcePath);
-  if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+  const parsedRaw = parseConfigText(text, sourcePath);
+  if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
     throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
   }
+  const { config: raw, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+  const where = sourcePath ? ` at ${sourcePath}` : "";
+  if (conflicts.length > 0) {
+    const lines = conflicts.map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`).join(`
+`);
+    throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:
+${lines}
+
+Each extraParams key above has a first-class equivalent and akm will not guess which value you meant — remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
+  }
+  if (lifted.length > 0) {
+    warn(`Config${where} uses deprecated extraParams keys with first-class equivalents; treating them as the first-class fields for this run (not written back to the file):
+  - ${lifted.join(`
+  - `)}`);
+  }
   const parsed = AkmConfigSchema.safeParse(raw);
   if (!parsed.success) {
     const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join(`
 `);
-    const where = sourcePath ? ` at ${sourcePath}` : "";
     throw new ConfigError(`Invalid config${where}:
 ${lines}`, "INVALID_CONFIG_FILE");
   }

package/dist/scripts/akm-migrate.js

@@ -16393,6 +16393,29 @@ var EXTRA_PARAMS_CREDENTIAL_KEYS = [
 ];
 var PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
 var CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+var LEGACY_EXTRA_PARAMS_FIELD = {
+  model: "model",
+  temperature: "temperature",
+  maxtokens: "maxTokens",
+  enablethinking: "enableThinking",
+  reasoningeffort: "reasoningEffort"
+};
+var LIFTABLE_EXTRA_PARAMS_KEYS = new Set(["temperature", "maxtokens", "enablethinking", "reasoningeffort"]);
+var EXTRA_PARAMS_NO_FIELD_REMEDY = {
+  messages: "AKM builds the request messages internally \u2014 remove it from extraParams",
+  responseformat: "AKM controls the response format internally \u2014 remove it from extraParams",
+  stream: "AKM controls streaming internally \u2014 remove it from extraParams",
+  streamoptions: "AKM controls streaming internally \u2014 remove it from extraParams",
+  chattemplatekwargs: "set engines.<name>.enableThinking instead of chat_template_kwargs.enable_thinking"
+};
+function protectedKeyRemedy(normalized) {
+  const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+  if (field) {
+    const note = normalized === "reasoningeffort" ? " (moved to a first-class field in 0.9.2)" : "";
+    return `set engines.<name>.${field} instead${note}`;
+  }
+  return EXTRA_PARAMS_NO_FIELD_REMEDY[normalized];
+}
 function normalizeExtraParamKey(key) {
   return key.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
@@ -16420,7 +16443,11 @@ function validateExtraParams(value) {
     for (const [key, child] of Object.entries(entry)) {
       const normalized = normalizeExtraParamKey(key);
       if (path9.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
-        issues.push({ path: [key], message: `${key} is protected by AKM` });
+        const remedy = protectedKeyRemedy(normalized);
+        issues.push({
+          path: [key],
+          message: remedy ? `${key} is protected by AKM \u2014 ${remedy}.` : `${key} is protected by AKM`
+        });
       }
       if (CREDENTIAL_KEYS.has(normalized)) {
         issues.push({ path: [...path9, key], message: `${key} cannot carry credentials` });
@@ -16435,6 +16462,64 @@ function formatExtraParamsIssue(label, issue) {
   const suffix = issue.path.map((part) => typeof part === "number" ? `[${part}]` : `.${part}`).join("");
   return `${label}${suffix} ${issue.message}`;
 }
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function liftLegacyEngineExtraParams(raw) {
+  const lifted = [];
+  const conflicts = [];
+  const rawEngines = raw.engines;
+  if (!isPlainObject2(rawEngines)) {
+    return { config: raw, lifted, conflicts };
+  }
+  const engines = {};
+  let anyEngineChanged = false;
+  for (const [name, engineValue] of Object.entries(rawEngines)) {
+    if (!isPlainObject2(engineValue) || !isPlainObject2(engineValue.extraParams)) {
+      engines[name] = engineValue;
+      continue;
+    }
+    const engine = { ...engineValue };
+    const extraParams = { ...engineValue.extraParams };
+    let engineChanged = false;
+    for (const [rawKey, value] of Object.entries(engineValue.extraParams)) {
+      const normalized = normalizeExtraParamKey(rawKey);
+      if (!LIFTABLE_EXTRA_PARAMS_KEYS.has(normalized))
+        continue;
+      const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
+      if (!field)
+        continue;
+      const existing = engine[field];
+      if (existing !== undefined && existing !== value) {
+        conflicts.push({ engine: name, key: rawKey, field, extraParamsValue: value, fieldValue: existing });
+        continue;
+      }
+      delete extraParams[rawKey];
+      engineChanged = true;
+      if (existing === value) {
+        lifted.push(`engines.${name}.extraParams.${rawKey} is redundant \u2014 engines.${name}.${field} is already set to the same value; dropped the extraParams entry`);
+        continue;
+      }
+      engine[field] = value;
+      lifted.push(`engines.${name}.extraParams.${rawKey} -> engines.${name}.${field}`);
+    }
+    if (!engineChanged) {
+      engines[name] = engineValue;
+      continue;
+    }
+    anyEngineChanged = true;
+    if (Object.keys(extraParams).length > 0) {
+      engine.extraParams = extraParams;
+    } else {
+      delete engine.extraParams;
+    }
+    engines[name] = engine;
+  }
+  if (!anyEngineChanged) {
+    return { config: raw, lifted, conflicts };
+  }
+  return { config: { ...raw, engines }, lifted, conflicts };
+}
 
 // src/workflows/source-ir/compare.ts
 function compareWorkflowSourceCodePoints(left, right) {
@@ -21699,11 +21784,11 @@ var CONSUMED_FRONTMATTER_KEYS = [
   "stale_after",
   "okf_version"
 ];
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function parseActorMapping(value) {
-  if (!isPlainObject2(value))
+  if (!isPlainObject3(value))
     return;
   const by = nonEmptyString(value.by);
   if (by === undefined)
@@ -21728,7 +21813,7 @@ function parseOkfSources(value) {
     return;
   const out = [];
   for (const item of value) {
-    if (!isPlainObject2(item))
+    if (!isPlainObject3(item))
       continue;
     const resource = nonEmptyString(item.resource);
     if (resource === undefined)
@@ -21834,7 +21919,7 @@ function recognize8(c, file) {
   const description = nonEmptyString(data.description);
   const tags = readTags(data.tags);
   const links = resolveOkfLinks(body, file.relPath);
-  const generatedMapping = isPlainObject2(data.generated) ? data.generated : undefined;
+  const generatedMapping = isPlainObject3(data.generated) ? data.generated : undefined;
   const generatedAt = generatedMapping ? nonEmptyString(generatedMapping.at) : undefined;
   const generatedBy = generatedMapping ? nonEmptyString(generatedMapping.by) : undefined;
   const legacyTimestamp = nonEmptyString(data.timestamp);
@@ -27464,7 +27549,7 @@ var AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) => {
 
 // src/core/config/deep-merge.ts
 var UNSAFE_KEYS3 = new Set(["__proto__", "constructor", "prototype"]);
-function isPlainObject3(value) {
+function isPlainObject4(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value))
     return false;
   const prototype = Object.getPrototypeOf(value);
@@ -27473,7 +27558,7 @@ function isPlainObject3(value) {
 function copyConfigValue(value) {
   if (Array.isArray(value))
     return value.map(copyConfigValue);
-  if (!isPlainObject3(value))
+  if (!isPlainObject4(value))
     return value;
   const copy = {};
   for (const key of Object.keys(value)) {
@@ -27492,7 +27577,7 @@ function deepMergeConfig(base, override) {
     if (next === undefined)
       continue;
     const current = result[key];
-    result[key] = isPlainObject3(current) && isPlainObject3(next) ? deepMergeConfig(current, next) : copyConfigValue(next);
+    result[key] = isPlainObject4(current) && isPlainObject4(next) ? deepMergeConfig(current, next) : copyConfigValue(next);
   }
   return result;
 }
@@ -27552,15 +27637,29 @@ function loadUserConfig() {
   return finalConfig;
 }
 function parseAndValidateConfigText(text, sourcePath) {
-  const raw = parseConfigText(text, sourcePath);
-  if (raw.configVersion !== CURRENT_CONFIG_VERSION) {
+  const parsedRaw = parseConfigText(text, sourcePath);
+  if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
     throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
   }
+  const { config: raw, lifted, conflicts } = liftLegacyEngineExtraParams(parsedRaw);
+  const where = sourcePath ? ` at ${sourcePath}` : "";
+  if (conflicts.length > 0) {
+    const lines = conflicts.map((c) => `  - engines.${c.engine}.extraParams.${c.key} (${JSON.stringify(c.extraParamsValue)}) conflicts with engines.${c.engine}.${c.field} (${JSON.stringify(c.fieldValue)})`).join(`
+`);
+    throw new ConfigError(`Invalid config${where}: extraParams and the first-class field disagree:
+${lines}
+
+Each extraParams key above has a first-class equivalent and akm will not guess which value you meant \u2014 remove the extraParams entry once the field carries the value you want.`, "INVALID_CONFIG_FILE");
+  }
+  if (lifted.length > 0) {
+    warn(`Config${where} uses deprecated extraParams keys with first-class equivalents; treating them as the first-class fields for this run (not written back to the file):
+  - ${lifted.join(`
+  - `)}`);
+  }
   const parsed = AkmConfigSchema.safeParse(raw);
   if (!parsed.success) {
     const lines = parsed.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join(`
 `);
-    const where = sourcePath ? ` at ${sourcePath}` : "";
     throw new ConfigError(`Invalid config${where}:
 ${lines}`, "INVALID_CONFIG_FILE");
   }

package/dist/tasks/run/run-native-task.js

@@ -64,13 +64,40 @@ export function shellCommand(task, platform = process.platform, env = process.en
             return [task.shell, "-c", command];
         case "pwsh":
         case "powershell":
-            return [shellExecutable(task.shell, platform, env), "-NoProfile", "-NonInteractive", "-Command", command];
+            return [
+                shellExecutable(task.shell, platform, env),
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                withExitCodePropagation(command),
+            ];
         case "cmd":
             return [shellExecutable("cmd", platform, env), "/d", "/s", "/c", command];
         default:
             return assertNever(task.shell, "shellCommand");
     }
 }
+/**
+ * `-Command` (documented identically for powershell.exe 5.1 and pwsh 7+, in
+ * about_PowerShell_exe / about_Pwsh) already derives its own process exit
+ * code from `$?`, so a genuinely failing last statement already yields a
+ * nonzero exit and status "failed" — but any native exit code outside {0, 1}
+ * is collapsed to 1, discarding the real value that task history reports.
+ *
+ * Appending a bare `exit $LASTEXITCODE` to recover it is unsafe on its own:
+ * `$LASTEXITCODE` stays `$null` for a command that never runs a native
+ * executable (a pure PowerShell/cmdlet command), and `exit $null` resolves
+ * to exit code 0 — turning a failed cmdlet into a false "completed".
+ *
+ * Reading `$?` first, before anything else can run, reproduces -Command's
+ * own completed/failed determination exactly (immune to that regression and
+ * to a `$LASTEXITCODE` left stale by an earlier native call in the same
+ * command), then upgrades to the precise native exit code only when the
+ * failing last statement actually set one.
+ */
+function withExitCodePropagation(command) {
+    return `${command}; if ($?) { exit 0 } elseif ($LASTEXITCODE -ne $null) { exit $LASTEXITCODE } else { exit 1 }`;
+}
 /**
  * Bind an unambiguous leading bare `akm` (including the task-v2 migrator's
  * quoted form) to this installation. Explicit paths and arbitrary shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [