akm-cli 0.9.2-alpha.5 → 0.9.3

package/CHANGELOG.md

@@ -6,8 +6,75 @@ 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
+
+- **A blocked workflow run became permanently unresumable after `akm
+  workflow abandon` (#847).** Abandon correctly moved the run to `failed`
+  but left its current step `blocked`; the durable-spine validator then
+  rejected that honest abandoned shape as corruption before `resume` could
+  reopen the step. Failed-run validation now accepts the three legitimate
+  current-step states — `pending` for an abandoned active run, `blocked` for
+  an abandoned blocked run, and `failed` for an execution failure — and
+  `resume` normalizes each back to `pending` as promised by the CLI help.
+
+- **`akm task sync` could compute another bundle's real scheduler entries as
+  drift and try to remove them (#846).** Removal was scoped by a bundle
+  *display name* (`bundleName`/`--bundle` target) — a value derived from a
+  directory basename that two unrelated bundles can legitimately share (an
+  unconfigured bundle's name is deduped only against its own config's
+  bundles, never against other bundles actually installed on the machine).
+  A primary/unconfigured-bundle sync now additionally confirms a
+  name-matching installed entry's *resolved bundle path*, recovered from
+  that entry's own scheduler-context descriptor, before treating it as
+  eligible for reconcile — and refuses (rather than assumes) when that path
+  can't be established. **Backward compatibility:** every entry installed by
+  this codebase already carries a scheduler-context descriptor (the
+  `--scheduler-context` file used to restore the scheduled process's
+  environment), so existing installations resolve correctly with no user
+  action required. An entry whose descriptor is missing, unreadable, or
+  owned by a different OS user is never assumed to belong to the invoking
+  bundle; such an entry is simply left untouched by sync (it will not be
+  auto-repaired or removed) until it is reinstalled or removed by hand.
+
 - **Scheduled tasks on Windows ran but recorded no output.** A task fired by
   Task Scheduler logged `exit_code=0` with an empty log: the command really
   ran, but nothing it printed was captured. Captured runs asked for their own

package/dist/commands/tasks/tasks.js

@@ -337,18 +337,34 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
     }
     const inspection = await sched.inspectBindings({ rebind: options.rebind === true });
     const rawEntries = [...inspection.installed];
-    const allEntries = rawEntries.map((entry) => ({
-        ...entry,
-        ...(entry.nativeId !== undefined ? { nativeId: entry.nativeId } : {}),
-        ...(entry.invocation !== undefined ? { invocation: Object.freeze([...entry.invocation]) } : {}),
-        binding: "binding" in entry ? [...entry.binding] : [],
-        contextPath: "contextPath" in entry ? entry.contextPath : "",
-    }));
+    const allEntries = rawEntries.map((entry) => {
+        const contextPath = "contextPath" in entry ? entry.contextPath : "";
+        // #846: recover the resolved bundle path this entry was installed
+        // under from its own scheduler-context descriptor. Any failure (no
+        // descriptor, unreadable, corrupt, owned by another user) leaves
+        // ownerBundlePath unset — belongsToBundle must never treat that as
+        // "mine".
+        const ownerBundlePath = contextPath ? resolveInstalledOwnerPath(contextPath) : undefined;
+        return {
+            ...entry,
+            ...(entry.nativeId !== undefined ? { nativeId: entry.nativeId } : {}),
+            ...(entry.invocation !== undefined ? { invocation: Object.freeze([...entry.invocation]) } : {}),
+            binding: "binding" in entry ? [...entry.binding] : [],
+            contextPath,
+            ...(ownerBundlePath !== undefined ? { ownerBundlePath } : {}),
+        };
+    });
     const nativeArtifacts = inspection.artifacts;
     const common = {
         sourceRoot: stashDir,
         adapterId: resolved.source.adapterId ?? detectAdapterId(stashDir),
         bundleName: resolved.source.name,
+        // #846: only meaningful for a primary/unconfigured-bundle sync. A
+        // `--bundle <target>` entry's scheduler-context descriptor records the
+        // invoking process's OWN primary AKM_BUNDLE_DIR, not the targeted
+        // bundle's directory, so path-scoping stays gated on the case it's
+        // actually valid for (see belongsToBundle).
+        ...(syncTarget === undefined ? { bundlePath: path.resolve(stashDir) } : {}),
         ...(syncTarget ? { bundleTarget: syncTarget } : {}),
         backend: sched.name,
         installed: allEntries,
@@ -773,6 +789,15 @@ function groupInstalledBindings(entries, invocation) {
     }
     return [...groups.values()].map((group) => ({ ...group, taskIds: group.taskIds.sort() }));
 }
+/** Best-effort recovery of an installed binding's owning bundle path (#846). */
+function resolveInstalledOwnerPath(contextPath) {
+    try {
+        return validateSchedulerContextDescriptor(contextPath).environment.AKM_BUNDLE_DIR;
+    }
+    catch {
+        return undefined;
+    }
+}
 function inspectInstalledBinding(entry, invocation) {
     const status = [];
     const binding = entry.binding;

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/dist/tasks/scheduler-sync.js

@@ -478,6 +478,21 @@ function installOptionsFor(input, current) {
     return input.installOptions ? Object.freeze({ ...input.installOptions }) : undefined;
 }
 function belongsToBundle(entry, input) {
+    if (input.bundlePath !== undefined && entry.target === input.bundleName) {
+        // Path-scoped (#846), primary/unconfigured-bundle sync only: the name
+        // already matches, but a display name derived from a directory
+        // basename is not an identity — two unrelated bundles can legitimately
+        // share one. Require the entry's own scheduler-context descriptor to
+        // additionally confirm the resolved path. An entry whose owning path
+        // cannot be established is never assumed to be ours — that silent
+        // assumption is exactly what let an isolated/foreign bundle's sync
+        // reach for another bundle's real scheduler entries. (`bundlePath` is
+        // only set for a primary sync — a `--bundle <target>` entry's
+        // descriptor reflects the invoking process's OWN primary directory,
+        // not the targeted bundle's, so it is not a meaningful signal there;
+        // that case keeps relying on config-name uniqueness below.)
+        return entry.ownerBundlePath !== undefined && entry.ownerBundlePath === input.bundlePath;
+    }
     if (entry.target === input.bundleName || entry.target === input.bundleTarget)
         return true;
     return false;
@@ -487,8 +502,13 @@ function assertNoForeignIds(desired, input) {
     const foreign = input.installed.find((entry) => wanted.has(entry.id) && !belongsToBundle(entry, input));
     if (!foreign)
         return;
-    const where = foreign.target ? `bundle ${JSON.stringify(foreign.target)}` : "the default bundle";
-    throw new UsageError(`Scheduler id ${JSON.stringify(foreign.id)} is already scheduled from ${where}; desired source ids must not collide across bundles.`, "RESOURCE_ALREADY_EXISTS");
+    const where = foreign.ownerBundlePath
+        ? `the bundle at ${JSON.stringify(foreign.ownerBundlePath)}`
+        : foreign.target
+            ? `bundle ${JSON.stringify(foreign.target)}`
+            : "the default bundle";
+    const mine = input.bundlePath ? ` (this sync is scoped to ${JSON.stringify(input.bundlePath)})` : "";
+    throw new UsageError(`Scheduler id ${JSON.stringify(foreign.id)} is already scheduled from ${where}${mine}; desired source ids must not collide across bundles.`, "RESOURCE_ALREADY_EXISTS");
 }
 function assertUniqueDesiredIds(desired) {
     const seen = new Set();

package/dist/workflows/runtime/plan-classifier.js

@@ -122,8 +122,11 @@ export function assertWorkflowSpineMatchesPlan(plan, run, rows) {
     }
     else if (run.status === "failed") {
         // `workflow abandon` marks the run failed while intentionally leaving its
-        // current step pending so `resume` can reopen the same work.
-        if (!current || (current.status !== "failed" && current.status !== "pending"))
+        // current step unchanged so `resume` can reopen the same work. An active
+        // run leaves a pending step; a blocked run leaves a blocked step; and an
+        // execution failure already carries a failed step. All three are honest
+        // failed-run spines that `resumeWorkflowRun` normalizes back to pending.
+        if (!current || (current.status !== "failed" && current.status !== "pending" && current.status !== "blocked"))
             corruptSpine(run.id, `${run.status} status does not match the current plan step`);
     }
     else if (run.status === "completed") {

package/docs/migration/README.md

@@ -2,7 +2,7 @@
 
 Upgrade guides and per-release migration notes.
 
-- [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the single durable-v4 workflow boundary, and release behavior changes
+- [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes

package/docs/migration/release-notes/README.md

@@ -8,7 +8,8 @@ live one level up in `docs/migration/`.
 ## Available notes
 
 - [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and
-  durable v4, command diagnostics, and strategy judgment migration
+  durable-v4-family `irVersion: 5`, command diagnostics, and strategy judgment
+  migration
 
 ## Adding notes for a new release
 

package/docs/migration/v0.8-to-v0.9.md

@@ -17,7 +17,7 @@ in place is not.
 - old `index.db`, `workflow.db`, task-history JSONL, or legacy lock/cache
   layouts;
 - old ref grammar or old workflow/task execution paths;
-- in-flight pre-v4 workflow plans.
+- in-flight workflow plans older than `irVersion: 5`.
 
 Those formats are not compatibility inputs to the current runtime. Keep an
 archive if you need historical inspection; do not place it in the live 0.9
@@ -108,9 +108,9 @@ existing scheduler entry.
 ## Workflow boundary
 
 Current Markdown and GitHub-shaped YAML workflows compile to the same source
-IR and freeze durable plan IR v4. Durable v4 is the only executable stored
-plan. Do not copy an old workflow database expecting old runs to resume; start
-new runs from current authored sources.
+IR and freeze the durable plan v4 family's executable `irVersion: 5` format.
+That is the only executable stored plan. Do not copy an old workflow database
+expecting old runs to resume; start new runs from current authored sources.
 
 ## Recovery
 

package/docs/migration/v0.9.0-troubleshooting.md

@@ -109,13 +109,13 @@ backup over a file while a task sync or scheduler process is running.
 
 ## A workflow will not resume
 
-Only durable plan IR v4 executes. Pre-v4 stored plans are rejected rather than
-decoded by a compatibility runtime. Start a new run from the current Markdown
-or YAML workflow source.
+Only the durable plan v4 family's `irVersion: 5` executes. Pre-`irVersion`-5
+stored plans are rejected rather than decoded by a compatibility runtime.
+Start a new run from the current Markdown or YAML workflow source.
 
-For a v4 run, a missing or changed authored source is not a resume blocker: the
-run uses its frozen plan. A plan-hash or schema failure is durable-state
-corruption and must fail closed.
+For an `irVersion: 5` run, a missing or changed authored source is not a resume
+blocker: the run uses its frozen plan. A plan-hash or schema failure is
+durable-state corruption and must fail closed.
 
 ## A stale transaction journal is reported
 

package/docs/reference/configuration.md

@@ -147,8 +147,9 @@ defaults at the layer that selected it; explicit sibling fields and nearer
 layers still win. The resulting request carries the exact model ID and merged
 inference object. Engine lowerers consume that exact selection and never run
 alias resolution again. New workflow starts persist the exact request and
-symbolic runner selection in durable plan v4; resume consumes that frozen
-material without resolving aliases again.
+symbolic runner selection in the durable plan v4 family's executable
+`irVersion: 5`; resume consumes that frozen material without resolving aliases
+again.
 
 Copy the complete installed starter into the user configuration directory when
 you want to customize all fields:

package/docs/reference/workflow-schema.md

@@ -1021,16 +1021,17 @@ a committed *value*, so it cannot carry "whatever this build agent's
 Values passed through this way are **not** redacted from the command's output
 the way `env:` binding values are, so never list a credential here.
 
-#### Durable v4 forbids `inherit_env`
+#### Durable v4 (`irVersion: 5`) forbids `inherit_env`
 
-Every new workflow start freezes a durable v4 plan. V4 rejects
-`inherit_env: true` and any other request for whole-process inheritance; use
-exact named environment bindings and `pass_env:` instead. Both mechanisms are
-dispatch-significant, keep the visible environment surface bounded, and form
-part of the unit's input hash.
+Every new workflow start freezes the durable plan v4 family's current
+executable format, `irVersion: 5`. It rejects `inherit_env: true` and any other
+request for whole-process inheritance; use exact named environment bindings
+and `pass_env:` instead. Both mechanisms are dispatch-significant, keep the
+visible environment surface bounded, and form part of the unit's input hash.
 
-The historical `inherit_env` spelling is unsupported. Pre-v4 stored plans are
-rejected; they are never upgraded or replayed through a second runtime.
+The historical `inherit_env` spelling is unsupported. Pre-`irVersion`-5 stored
+plans are rejected; they are never upgraded or replayed through a second
+runtime.
 
 ### What `akm show` reports for an exec step
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.2-alpha.5",
+  "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": [