akm-cli 0.9.17-alpha.1 → 0.9.17-alpha.3

package/CHANGELOG.md

@@ -6,6 +6,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.17-alpha.3] - 2026-09-24
+
+### Fixed
+
+- **Unscoped `akm task sync` no longer aborts the whole host on the first
+  bundle root that happens to contain any symlink.** `captureGuardedDirectoryManifest`
+  threw for every symbolic directory entry it listed, even one the scheduler
+  never reads (e.g. a third-party skill repo's `CLAUDE.md -> AGENTS.md`) —
+  `SchedulerSourceCollector` manifests every scanned bundle's root, so one
+  such bundle among many enabled ones failed sync entirely, dry-run included.
+  A symlink that stays inside its bundle root is now recorded in the guarded
+  directory manifest as its own `"symlink"` kind, identified without
+  following it (its `readlink` text plus its no-follow `lstat` identity), so
+  change detection still works; it is never read or descended into. A symlink
+  sitting exactly where a task or workflow source lives (a `.yml` under
+  `tasks/`, any `.yml` under an `akm-task` bundle, or a workflow-named file
+  under `workflows/`) is reported as its own per-source failure — "is a
+  symbolic source; guarded reads require a regular no-follow owner" — and its
+  ref is not scheduled, even when a real sibling file shares that ref, while
+  every other task and workflow still reconciles. A
+  symlink that resolves outside the bundle root, or one that is broken and
+  cannot be identified safely, is still refused, and a bundle root whose
+  `tasks` or `workflows` entry is itself a symlink still refuses loudly,
+  since that is a schedulable source location.
+
+## [0.9.17-alpha.2] - 2026-09-24
+
+### Fixed
+
+- **A config carrying the retired `experimental.workflowEngine` key no longer
+  fails to load.** `ExperimentalConfigSchema` moved from `.passthrough()` to
+  `.strict()` in 0.9.16 (`cc6152e02`), after `workflowEngine` had already been
+  removed from it in `e0655d13c`; a real config a 0.9.15 install wrote (whose
+  passthrough still accepted the key) then failed every command with
+  `Invalid config: experimental: Unrecognized key(s) in object: 'workflowEngine'`.
+  The config loader now strips known-retired `experimental.*` keys in memory
+  before validation, warning once and naming `akm migrate apply`; a genuinely
+  unknown/misspelled key (e.g. `improveAutonomyy`) still fails closed.
+  `akm migrate apply` removes the retired key from `config.json` on disk
+  (with the usual backup), and `--dry-run` reports the pending removal.
+- **Unscoped `akm task sync` no longer crashes when an enabled website or npm
+  bundle is configured.** The sync plan loop resolved every active source
+  through the write-target resolver, which rejects any kind other than
+  `filesystem`/`git` outright (writes, and therefore scheduler state, are
+  undefined for those kinds — the same rejection `akm task enable` already
+  hit). Unscoped sync now skips non-filesystem/git bundles when building
+  install operations — they never carried schedulable tasks — while
+  inactive-bundle removal/revocation still sees them. A scoped
+  `akm task sync --bundle <website-or-npm-bundle>` now fails with a clear
+  usage error instead of the write-target `ConfigError`.
+
 ## [0.9.17-alpha.1] - 2026-09-24
 
 ### Added

package/dist/commands/tasks/tasks.js

@@ -23,7 +23,7 @@ import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../cor
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, isWriteCapableSourceKind, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { activeSchedulerActivations, isSchedulerRefEnabled, setSchedulerRefEnabled, } from "../../tasks/activation-config.js";
@@ -411,7 +411,24 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const nativeArtifacts = inspection.artifacts;
     const configuredSources = resolveConfiguredSources(config);
     const activeSources = resolveActiveConfiguredSources(config);
-    const sourceNames = bundleTarget ? [bundleTarget] : activeSources.map((source) => source.name);
+    if (bundleTarget) {
+        // adaptConfiguredSource (src/core/write-source.ts) rejects any kind
+        // other than filesystem/git outright, so a website/npm bundle can never
+        // carry scheduler state (akm task enable already fails the same way).
+        // Surface that as a clear usage error here instead of letting the
+        // write-target resolution below raise a generic ConfigError.
+        const targetSource = activeSources.find((source) => source.name === bundleTarget);
+        if (targetSource && !isWriteCapableSourceKind(targetSource.type)) {
+            throw new UsageError(`Bundle "${bundleTarget}" has kind "${targetSource.type}"; task scheduling is only supported for filesystem and git bundles.`, "INVALID_FLAG_VALUE");
+        }
+    }
+    // Unscoped sync only installs/removes bindings for bundles that can carry
+    // them (filesystem/git). A website/npm bundle contributes no installs and
+    // must not crash the loop; inactiveOperations below still sees it via
+    // configuredSources for removal/revocation.
+    const sourceNames = bundleTarget
+        ? [bundleTarget]
+        : activeSources.filter((source) => isWriteCapableSourceKind(source.type)).map((source) => source.name);
     const inactiveOperations = bundleTarget
         ? []
         : inactiveBundleRemovalOperations(config, configuredSources, allEntries, nativeArtifacts);

package/dist/core/config/config.js

@@ -16,6 +16,7 @@ import { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundlesTo
 import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig, isPlainObject } from "./deep-merge.js";
 import { migrateLegacySourceShape } from "./legacy-source-shape-shim.js";
+import { stripRetiredExperimentalKeys } from "./retired-experimental-keys-shim.js";
 import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
@@ -147,7 +148,8 @@ export function acquireConfigReadFence() {
  * before it is either validated (the local/top-level file) or merged in as
  * an `extends` base: JSONC parse already done by the caller, then version
  * shim, then legacy `stashDir`/`sources[]`/`installed[]` shim, then the
- * legacy `extraParams` lift (#852). Shared by {@link parseAndValidateConfigText}
+ * legacy `extraParams` lift (#852), then the retired `experimental.*` key
+ * shim. Shared by {@link parseAndValidateConfigText}
  * (the local file) and {@link resolveExtendsChain} (each base in the chain) so
  * a fleet-shared base config can carry its own old `configVersion` / legacy
  * shape independently of the file that extends it.
@@ -155,7 +157,8 @@ export function acquireConfigReadFence() {
 function runConfigFilePipeline(text, sourcePath) {
     const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
-    return liftExtraParamsOrThrow(parsedRaw, sourcePath);
+    const liftedRaw = liftExtraParamsOrThrow(parsedRaw, sourcePath);
+    return stripRetiredExperimentalKeys(liftedRaw, sourcePath);
 }
 /**
  * #852 (following #815): a config still using legacy `extraParams` keys —

package/dist/core/config/retired-experimental-keys-shim.js

@@ -0,0 +1,62 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `experimental.*` retired-key shim.
+ *
+ * `ExperimentalConfigSchema` (`./schema/experimental.ts`) moved from
+ * `.passthrough()` to `.strict()` in 0.9.16 (`cc6152e02`) so a typo in an
+ * authority flag (e.g. `improveAutonomyy`) fails loudly instead of silently
+ * doing nothing. `workflowEngine` was removed from that block earlier, in
+ * `e0655d13c`, but 0.9.15's passthrough still accepted it — so a real config
+ * written by 0.9.15 can carry `experimental.workflowEngine` and now fails
+ * every command with `Invalid config: experimental: Unrecognized key(s)`.
+ *
+ * Per AGENTS.md "Reading persisted data": a reader tolerates what older
+ * releases wrote, converts in memory, warns once, and leaves the on-disk
+ * rewrite to `akm migrate apply`. This mirrors `./legacy-source-shape-shim.ts`
+ * exactly — strip the retired key(s) before schema validation, warn once
+ * naming the key and the migrate command — rather than reintroducing
+ * `.passthrough()`, which would also let a live key typo through silently.
+ */
+import { isRecord } from "../common.js";
+import { warnOnce } from "../warn.js";
+/**
+ * Every `experimental.*` key `ExperimentalConfigSchema` has ever retired.
+ * `workflowEngine` (removed in `e0655d13c`) is the only one so far — kept as
+ * a list because the shim and `akm migrate apply`
+ * (`scripts/akm-migrate/migrate/config-retired-experimental-keys.ts`) share
+ * it.
+ */
+export const RETIRED_EXPERIMENTAL_KEYS = ["workflowEngine"];
+/**
+ * Which `RETIRED_EXPERIMENTAL_KEYS` are present in a raw config's
+ * `experimental` section. Returns `[]` when `raw.experimental` is missing or
+ * not a record. Shared by `stripRetiredExperimentalKeys` below and by
+ * `akm migrate apply`'s on-disk counterpart
+ * (`scripts/akm-migrate/migrate/config-retired-experimental-keys.ts`).
+ */
+export function retiredExperimentalKeysIn(raw) {
+    const experimental = raw.experimental;
+    if (!isRecord(experimental))
+        return [];
+    return RETIRED_EXPERIMENTAL_KEYS.filter((key) => key in experimental);
+}
+/**
+ * Drop retired `experimental.*` keys from a raw parsed config object before
+ * schema validation, warning once per source when any were present. Live
+ * keys (including an unrecognized one, e.g. a typo) are left untouched for
+ * `ExperimentalConfigSchema.strict()` to reject as before.
+ */
+export function stripRetiredExperimentalKeys(raw, sourcePath) {
+    const present = retiredExperimentalKeysIn(raw);
+    if (present.length === 0)
+        return raw;
+    const original = raw.experimental;
+    const experimental = { ...original };
+    for (const key of present)
+        delete experimental[key];
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    warnOnce(`config:retired-experimental-key${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired experimental key(s) ${present.join(", ")} — ignored in memory. Run \`akm migrate apply\` to remove ${present.length === 1 ? "it" : "them"} from the config file and silence this warning.`);
+    return { ...raw, experimental };
+}

package/dist/core/write-source.js

@@ -1028,6 +1028,14 @@ export function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
         return;
     throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
 }
+/**
+ * The write-capable source kinds. Writes (and therefore scheduler state,
+ * which only ever binds to a writable source) are defined only for these
+ * two kinds; anything else throws `ConfigError`.
+ */
+export function isWriteCapableSourceKind(kind) {
+    return kind === "filesystem" || kind === "git";
+}
 /**
  * Reject any kind reaching the write/delete helpers other than the two
  * supported writable kinds. The config loader is the first line of defence
@@ -1035,7 +1043,7 @@ export function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
  * bypass the loader still get a clear error.
  */
 function assertSupportedKind(source) {
-    if (source.kind === "filesystem" || source.kind === "git")
+    if (isWriteCapableSourceKind(source.kind))
         return;
     throw new ConfigError(`write-source: unsupported kind "${source.kind}" for source "${source.name}". ` +
         "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Set `kind: "filesystem"` (or `kind: "git"`) on the source, or add a parallel filesystem entry.');
@@ -1073,7 +1081,7 @@ function adaptConfiguredSource(runtime) {
     // reaching this point is a config-loader bug (assertWritableAllowedForKind
     // should have rejected it). Throw a ConfigError rather than silently
     // forwarding an unsupported kind.
-    if (runtime.type !== "filesystem" && runtime.type !== "git") {
+    if (!isWriteCapableSourceKind(runtime.type)) {
         throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` +
             "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
     }

package/dist/execution/guarded-source.js

@@ -179,6 +179,18 @@ export function captureGuardedDirectoryManifest(directoryPathInput, containmentR
                     if (relative.startsWith("..") || path.isAbsolute(relative)) {
                         throw new UsageError(`${entryPath} resolves outside the bundle root through a symbolic source.`, "PATH_ESCAPE_VIOLATION");
                     }
+                    // A symlink that stays inside the containment root is recorded as
+                    // its own kind, identified without following it (readlink text
+                    // plus its own no-follow lstat identity), so change detection
+                    // still works. It is never a directory or file candidate to any
+                    // manifest consumer.
+                    return Object.freeze({
+                        name: entry.name,
+                        kind: "symlink",
+                        physicalIdentity: physicalIdentity(entryPath, entryStat),
+                        version: statVersion(entryStat),
+                        target: fs.readlinkSync(entryPath),
+                    });
                 }
                 throw new UsageError(`${entryPath} is a symbolic source with a physical source identity collision; guarded reads require one no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
             }
@@ -323,8 +335,10 @@ export class GuardedExecutionSourceCollector {
                 const candidate = path.join(directory, entry.name);
                 if (entry.kind === "directory")
                     visit(candidate);
-                else
+                else if (entry.kind === "file")
                     files.push(candidate);
+                // A "symlink" entry is recorded for change detection but is never
+                // read, descended into, or made a candidate source.
             }
         };
         visit(path.resolve(directoryPath));

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

@@ -77671,6 +77671,31 @@ function upgradeConfigVersion(raw, sourcePath) {
 
 // src/core/config/config.ts
 init_legacy_source_shape_shim();
+
+// src/core/config/retired-experimental-keys-shim.ts
+init_common();
+init_warn();
+var RETIRED_EXPERIMENTAL_KEYS = ["workflowEngine"];
+function retiredExperimentalKeysIn(raw) {
+  const experimental = raw.experimental;
+  if (!isRecord(experimental))
+    return [];
+  return RETIRED_EXPERIMENTAL_KEYS.filter((key) => (key in experimental));
+}
+function stripRetiredExperimentalKeys(raw, sourcePath) {
+  const present = retiredExperimentalKeysIn(raw);
+  if (present.length === 0)
+    return raw;
+  const original = raw.experimental;
+  const experimental = { ...original };
+  for (const key of present)
+    delete experimental[key];
+  const where = sourcePath ? ` at ${sourcePath}` : "";
+  warnOnce(`config:retired-experimental-key${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired experimental key(s) ${present.join(", ")} — ignored in memory. Run \`akm migrate apply\` to remove ${present.length === 1 ? "it" : "them"} from the config file and silence this warning.`);
+  return { ...raw, experimental };
+}
+
+// src/core/config/config.ts
 init_paths();
 init_warn();
 var DEFAULT_CONFIG = {
@@ -77730,7 +77755,8 @@ function loadUserConfig() {
 function runConfigFilePipeline(text, sourcePath) {
   const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
   const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
-  return liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  const liftedRaw = liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  return stripRetiredExperimentalKeys(liftedRaw, sourcePath);
 }
 function liftExtraParamsOrThrow(parsedRaw, sourcePath) {
   const where = sourcePath ? ` at ${sourcePath}` : "";
@@ -86389,8 +86415,11 @@ function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
     return;
   throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
 }
+function isWriteCapableSourceKind(kind) {
+  return kind === "filesystem" || kind === "git";
+}
 function adaptConfiguredSource(runtime) {
-  if (runtime.type !== "filesystem" && runtime.type !== "git") {
+  if (!isWriteCapableSourceKind(runtime.type)) {
     throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` + "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
   }
   const kind = runtime.type;
@@ -93226,32 +93255,7 @@ var GLOBAL_OUTPUT_ARGS2 = {
 init_errors();
 
 // scripts/akm-migrate/help.txt
-var help_default = `Usage: akm-migrate <command> [options]
-
-The one migration tool for an akm installation. Every historical shape akm
-has ever written lives here; the CLI proper reads only current schemas.
-\`status\` and \`apply\` run every step, in order, and print one combined JSON
-plan (exit 1 when any step is blocked):
-
-  1. legacy config \`extraParams\` keys lifted onto first-class engine fields
-  2. scheduler grants bound to the configured source installation that was
-     approved (stale grants whose bundle no longer exists are removed)
-  3. pending state.db migrations, historical-destructive ones included,
-     with a verified sibling safety copy (the only path that admits them)
-  4. task-v2 files to task v3, then task-v3 files to task source v4
-  5. superseded pre-0.9.0 \`.akm\` residue and stale filesystem transactions
-  6. live \`.akm\` writers relocated to \`$STATE\`/\`$CACHE\`, for every local
-     bundle (distill-rejected, eval-cases, measurement verdicts, and stale
-     improve-pipeline locks — a lock a live run still holds is left alone)
-
-\`akm migrate status|apply\` wraps this executable; \`akm upgrade\` runs
-\`apply\` after its install step, so an image that ships akm can put either
-in its entrypoint (a current installation is a no-op).
-
-Commands:
-  status              Inspect every pending migration without changing anything.
-  apply [--dry-run]   Back up and apply every pending migration.
-`;
+var help_default = "Usage: akm-migrate <command> [options]\n\nThe one migration tool for an akm installation. Every historical shape akm\nhas ever written lives here; the CLI proper reads only current schemas.\n`status` and `apply` run every step, in order, and print one combined JSON\nplan (exit 1 when any step is blocked):\n\n  1. legacy config `extraParams` keys lifted onto first-class engine fields\n  2. retired `experimental.*` config keys removed (today `workflowEngine`)\n  3. scheduler grants bound to the configured source installation that was\n     approved (stale grants whose bundle no longer exists are removed)\n  4. pending state.db migrations, historical-destructive ones included,\n     with a verified sibling safety copy (the only path that admits them)\n  5. source-owned schedule enablement converted to host-local scheduler\n     grants\n  6. task-v2 files to task v3, then task-v3 files to task source v4\n  7. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions\n  8. live `.akm` writers relocated to `$STATE`/`$CACHE`, for every local\n     bundle (distill-rejected, eval-cases, measurement verdicts, and stale\n     improve-pipeline locks — a lock a live run still holds is left alone)\n\n`akm migrate status|apply` wraps this executable; `akm upgrade` runs\n`apply` after its install step, so an image that ships akm can put either\nin its entrypoint (a current installation is a no-op).\n\nCommands:\n  status              Inspect every pending migration without changing anything.\n  apply [--dry-run]   Back up and apply every pending migration.\n";
 
 // scripts/akm-migrate/run-migrate.ts
 init_common();
@@ -94787,10 +94791,44 @@ function applyConfigExtraParamsLift(configPath) {
   return { applied: true, lifted, conflicts: [] };
 }
 
+// scripts/akm-migrate/migrate/config-retired-experimental-keys.ts
+function readRawConfig2(configPath) {
+  const text = readConfigText(configPath);
+  if (text === undefined)
+    return;
+  return parseConfigText(text, configPath);
+}
+function findConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { removed: [] };
+  return { removed: retiredExperimentalKeysIn(raw).map((key) => `experimental.${key}`) };
+}
+function applyConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { applied: false, removed: [] };
+  const retired = retiredExperimentalKeysIn(raw);
+  if (retired.length === 0)
+    return { applied: false, removed: [] };
+  const experimental = { ...raw.experimental };
+  for (const key of retired)
+    delete experimental[key];
+  const config = { ...raw, experimental };
+  const release = acquireConfigLock();
+  try {
+    backupExistingConfig(configPath);
+    writeConfigAtomic(configPath, config);
+  } finally {
+    release();
+  }
+  return { applied: true, removed: retired.map((key) => `experimental.${key}`) };
+}
+
 // scripts/akm-migrate/migrate/config-scheduler-source-ids.ts
 init_asset_ref();
 init_bundle_id();
-function readRawConfig2(configPath) {
+function readRawConfig3(configPath) {
   const text = readConfigText(configPath);
   return text === undefined ? undefined : parseConfigText(text, configPath);
 }
@@ -94845,13 +94883,13 @@ function implicitBundleSourceId(raw, bundleId) {
   return implicitId === bundleId ? filesystemBundleSourceId(root) : undefined;
 }
 function findConfigSchedulerSourceIdMigration(configPath) {
-  const raw = readRawConfig2(configPath);
+  const raw = readRawConfig3(configPath);
   return Object.freeze({ changes: Object.freeze(raw ? migrationChanges(raw) : []) });
 }
 function applyConfigSchedulerSourceIdMigration(configPath) {
   const release = acquireConfigLock();
   try {
-    const raw = readRawConfig2(configPath);
+    const raw = readRawConfig3(configPath);
     if (!raw)
       return Object.freeze({ applied: false, changes: Object.freeze([]) });
     const changes = migrationChanges(raw);
@@ -104071,12 +104109,16 @@ async function runMigration(options) {
   if (apply && configExtraParams.applied)
     resetConfigCache();
   const pendingLift = apply ? undefined : configExtraParams.pending;
+  const configRetiredExperimentalKeys = apply ? applyConfigRetiredExperimentalKeys(configPath) : { pending: findConfigRetiredExperimentalKeys(configPath) };
+  if (apply && configRetiredExperimentalKeys.applied)
+    resetConfigCache();
   if (pendingLift && pendingLift.lifted.length > 0) {
     return {
       schemaVersion: 1,
       status: "blocked",
       blockers: pendingLift.lifted,
       configExtraParams,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104091,6 +104133,7 @@ async function runMigration(options) {
       blockers: pendingSchedulerBindings.changes.map((change) => `${change.kind === "bind" ? "bind" : "drop"} scheduler activation ${change.ref}` + (change.reason ? `: ${change.reason}` : "")),
       configExtraParams,
       configSchedulerSourceIds,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104110,12 +104153,14 @@ async function runMigration(options) {
   }
   const stateStatus = "pending" in stateMigrations && stateMigrations.pending.length > 0 ? "ready" : "current";
   const schedulerStatus = "pending" in schedulerActivation && schedulerActivation.pending.length > 0 ? "ready" : "current";
+  const retiredKeysStatus = "pending" in configRetiredExperimentalKeys && configRetiredExperimentalKeys.pending.removed.length > 0 ? "ready" : "current";
   return {
     schemaVersion: 1,
-    status: worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus),
+    status: worstStatus(worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus), retiredKeysStatus),
     blockers: [...taskV3.blockers, ...taskV4.blockers],
     configExtraParams,
     configSchedulerSourceIds,
+    configRetiredExperimentalKeys,
     stateMigrations,
     schedulerActivation,
     taskV3Migration: taskV3.taskV3Migration,

package/dist/scripts/akm-migrate.js

@@ -76999,6 +76999,31 @@ function upgradeConfigVersion(raw, sourcePath) {
 
 // src/core/config/config.ts
 init_legacy_source_shape_shim();
+
+// src/core/config/retired-experimental-keys-shim.ts
+init_common();
+init_warn();
+var RETIRED_EXPERIMENTAL_KEYS = ["workflowEngine"];
+function retiredExperimentalKeysIn(raw) {
+  const experimental = raw.experimental;
+  if (!isRecord(experimental))
+    return [];
+  return RETIRED_EXPERIMENTAL_KEYS.filter((key) => (key in experimental));
+}
+function stripRetiredExperimentalKeys(raw, sourcePath) {
+  const present = retiredExperimentalKeysIn(raw);
+  if (present.length === 0)
+    return raw;
+  const original = raw.experimental;
+  const experimental = { ...original };
+  for (const key of present)
+    delete experimental[key];
+  const where = sourcePath ? ` at ${sourcePath}` : "";
+  warnOnce(`config:retired-experimental-key${sourcePath ? `:${sourcePath}` : ""}`, `Config${where} uses the retired experimental key(s) ${present.join(", ")} \u2014 ignored in memory. Run \`akm migrate apply\` to remove ${present.length === 1 ? "it" : "them"} from the config file and silence this warning.`);
+  return { ...raw, experimental };
+}
+
+// src/core/config/config.ts
 init_paths();
 init_warn();
 var DEFAULT_CONFIG = {
@@ -77058,7 +77083,8 @@ function loadUserConfig() {
 function runConfigFilePipeline(text, sourcePath) {
   const versioned = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
   const parsedRaw = migrateLegacySourceShape(versioned, sourcePath);
-  return liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  const liftedRaw = liftExtraParamsOrThrow(parsedRaw, sourcePath);
+  return stripRetiredExperimentalKeys(liftedRaw, sourcePath);
 }
 function liftExtraParamsOrThrow(parsedRaw, sourcePath) {
   const where = sourcePath ? ` at ${sourcePath}` : "";
@@ -85717,8 +85743,11 @@ function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
     return;
   throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
 }
+function isWriteCapableSourceKind(kind) {
+  return kind === "filesystem" || kind === "git";
+}
 function adaptConfiguredSource(runtime) {
-  if (runtime.type !== "filesystem" && runtime.type !== "git") {
+  if (!isWriteCapableSourceKind(runtime.type)) {
     throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` + "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
   }
   const kind = runtime.type;
@@ -93182,32 +93211,7 @@ var GLOBAL_OUTPUT_ARGS = {
 init_errors();
 
 // scripts/akm-migrate/help.txt
-var help_default = `Usage: akm-migrate <command> [options]
-
-The one migration tool for an akm installation. Every historical shape akm
-has ever written lives here; the CLI proper reads only current schemas.
-\`status\` and \`apply\` run every step, in order, and print one combined JSON
-plan (exit 1 when any step is blocked):
-
-  1. legacy config \`extraParams\` keys lifted onto first-class engine fields
-  2. scheduler grants bound to the configured source installation that was
-     approved (stale grants whose bundle no longer exists are removed)
-  3. pending state.db migrations, historical-destructive ones included,
-     with a verified sibling safety copy (the only path that admits them)
-  4. task-v2 files to task v3, then task-v3 files to task source v4
-  5. superseded pre-0.9.0 \`.akm\` residue and stale filesystem transactions
-  6. live \`.akm\` writers relocated to \`$STATE\`/\`$CACHE\`, for every local
-     bundle (distill-rejected, eval-cases, measurement verdicts, and stale
-     improve-pipeline locks \u2014 a lock a live run still holds is left alone)
-
-\`akm migrate status|apply\` wraps this executable; \`akm upgrade\` runs
-\`apply\` after its install step, so an image that ships akm can put either
-in its entrypoint (a current installation is a no-op).
-
-Commands:
-  status              Inspect every pending migration without changing anything.
-  apply [--dry-run]   Back up and apply every pending migration.
-`;
+var help_default = "Usage: akm-migrate <command> [options]\n\nThe one migration tool for an akm installation. Every historical shape akm\nhas ever written lives here; the CLI proper reads only current schemas.\n`status` and `apply` run every step, in order, and print one combined JSON\nplan (exit 1 when any step is blocked):\n\n  1. legacy config `extraParams` keys lifted onto first-class engine fields\n  2. retired `experimental.*` config keys removed (today `workflowEngine`)\n  3. scheduler grants bound to the configured source installation that was\n     approved (stale grants whose bundle no longer exists are removed)\n  4. pending state.db migrations, historical-destructive ones included,\n     with a verified sibling safety copy (the only path that admits them)\n  5. source-owned schedule enablement converted to host-local scheduler\n     grants\n  6. task-v2 files to task v3, then task-v3 files to task source v4\n  7. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions\n  8. live `.akm` writers relocated to `$STATE`/`$CACHE`, for every local\n     bundle (distill-rejected, eval-cases, measurement verdicts, and stale\n     improve-pipeline locks \u2014 a lock a live run still holds is left alone)\n\n`akm migrate status|apply` wraps this executable; `akm upgrade` runs\n`apply` after its install step, so an image that ships akm can put either\nin its entrypoint (a current installation is a no-op).\n\nCommands:\n  status              Inspect every pending migration without changing anything.\n  apply [--dry-run]   Back up and apply every pending migration.\n";
 
 // scripts/akm-migrate/run-migrate.ts
 init_common();
@@ -94743,10 +94747,44 @@ function applyConfigExtraParamsLift(configPath) {
   return { applied: true, lifted, conflicts: [] };
 }
 
+// scripts/akm-migrate/migrate/config-retired-experimental-keys.ts
+function readRawConfig2(configPath) {
+  const text = readConfigText(configPath);
+  if (text === undefined)
+    return;
+  return parseConfigText(text, configPath);
+}
+function findConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { removed: [] };
+  return { removed: retiredExperimentalKeysIn(raw).map((key) => `experimental.${key}`) };
+}
+function applyConfigRetiredExperimentalKeys(configPath) {
+  const raw = readRawConfig2(configPath);
+  if (!raw)
+    return { applied: false, removed: [] };
+  const retired = retiredExperimentalKeysIn(raw);
+  if (retired.length === 0)
+    return { applied: false, removed: [] };
+  const experimental = { ...raw.experimental };
+  for (const key of retired)
+    delete experimental[key];
+  const config = { ...raw, experimental };
+  const release = acquireConfigLock();
+  try {
+    backupExistingConfig(configPath);
+    writeConfigAtomic(configPath, config);
+  } finally {
+    release();
+  }
+  return { applied: true, removed: retired.map((key) => `experimental.${key}`) };
+}
+
 // scripts/akm-migrate/migrate/config-scheduler-source-ids.ts
 init_asset_ref();
 init_bundle_id();
-function readRawConfig2(configPath) {
+function readRawConfig3(configPath) {
   const text = readConfigText(configPath);
   return text === undefined ? undefined : parseConfigText(text, configPath);
 }
@@ -94801,13 +94839,13 @@ function implicitBundleSourceId(raw, bundleId) {
   return implicitId === bundleId ? filesystemBundleSourceId(root2) : undefined;
 }
 function findConfigSchedulerSourceIdMigration(configPath) {
-  const raw = readRawConfig2(configPath);
+  const raw = readRawConfig3(configPath);
   return Object.freeze({ changes: Object.freeze(raw ? migrationChanges(raw) : []) });
 }
 function applyConfigSchedulerSourceIdMigration(configPath) {
   const release = acquireConfigLock();
   try {
-    const raw = readRawConfig2(configPath);
+    const raw = readRawConfig3(configPath);
     if (!raw)
       return Object.freeze({ applied: false, changes: Object.freeze([]) });
     const changes = migrationChanges(raw);
@@ -104027,12 +104065,16 @@ async function runMigration(options) {
   if (apply && configExtraParams.applied)
     resetConfigCache();
   const pendingLift = apply ? undefined : configExtraParams.pending;
+  const configRetiredExperimentalKeys = apply ? applyConfigRetiredExperimentalKeys(configPath) : { pending: findConfigRetiredExperimentalKeys(configPath) };
+  if (apply && configRetiredExperimentalKeys.applied)
+    resetConfigCache();
   if (pendingLift && pendingLift.lifted.length > 0) {
     return {
       schemaVersion: 1,
       status: "blocked",
       blockers: pendingLift.lifted,
       configExtraParams,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104047,6 +104089,7 @@ async function runMigration(options) {
       blockers: pendingSchedulerBindings.changes.map((change) => `${change.kind === "bind" ? "bind" : "drop"} scheduler activation ${change.ref}` + (change.reason ? `: ${change.reason}` : "")),
       configExtraParams,
       configSchedulerSourceIds,
+      configRetiredExperimentalKeys,
       stateMigrations: { pending: listPendingStateMigrations() }
     };
   }
@@ -104066,12 +104109,14 @@ async function runMigration(options) {
   }
   const stateStatus = "pending" in stateMigrations && stateMigrations.pending.length > 0 ? "ready" : "current";
   const schedulerStatus = "pending" in schedulerActivation && schedulerActivation.pending.length > 0 ? "ready" : "current";
+  const retiredKeysStatus = "pending" in configRetiredExperimentalKeys && configRetiredExperimentalKeys.pending.removed.length > 0 ? "ready" : "current";
   return {
     schemaVersion: 1,
-    status: worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus),
+    status: worstStatus(worstStatus(worstStatus(worstStatus(taskV3.status, taskV4.status), stateStatus), schedulerStatus), retiredKeysStatus),
     blockers: [...taskV3.blockers, ...taskV4.blockers],
     configExtraParams,
     configSchedulerSourceIds,
+    configRetiredExperimentalKeys,
     stateMigrations,
     schedulerActivation,
     taskV3Migration: taskV3.taskV3Migration,

package/dist/tasks/scheduler-sync.js

@@ -299,6 +299,15 @@ async function compileDesiredSourceSet(input, collector) {
 async function compileTaskSources(input, collector, out, failures) {
     if (input.adapterId !== "akm" && input.adapterId !== "akm-task")
         return;
+    for (const symlink of collector.symlinkSources()) {
+        if (!isAuthoredTaskRelativePath(input.adapterId, symlink.relativePath))
+            continue;
+        const qualifiedRef = makeBundleRef(input.bundleName, symlink.relativePath.slice(0, -4));
+        if (input.enabledActivations && !input.enabledActivations.has(schedulerActivationKey("task", qualifiedRef))) {
+            continue;
+        }
+        failures.push(taskFailure(symlink.sourcePath, qualifiedRef, symbolicSourceError(symlink.sourcePath)));
+    }
     const physicalOwners = new Map();
     for (const guarded of collector.authoredTaskSources(input.adapterId)) {
         const sourcePath = guarded.sourcePath;
@@ -531,6 +540,26 @@ function enumerateWorkflowLookups(input, collector, failures) {
         owners.push(guarded);
         lookups.set(canonicalName, owners);
     }
+    for (const symlink of collector.symlinkSources()) {
+        if (!isAuthoredWorkflowRelativePath(input.adapterId, symlink.relativePath))
+            continue;
+        if (path.basename(symlink.sourcePath).toLowerCase() === "readme.md")
+            continue;
+        const authoredName = workflowNameForSourcePath(input.sourceRoot, input.adapterId, symlink.sourcePath);
+        if (authoredName === undefined)
+            continue;
+        const canonicalName = canonicalizeWorkflowName(authoredName);
+        // A real sibling sharing this name must not compile either: runtime
+        // resolution follows the symlink and may pick it over the file the
+        // binding was compiled from. The symbolic failure below is the ref's
+        // only report.
+        lookups.delete(canonicalName);
+        const failureRef = makeBundleRef(input.bundleName, input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName);
+        if (input.enabledActivations && !input.enabledActivations.has(schedulerActivationKey("workflow", failureRef))) {
+            continue;
+        }
+        failures.push(workflowFailure(symlink.sourcePath, failureRef, symbolicSourceError(symlink.sourcePath)));
+    }
     return new Map([...lookups]
         .sort(([left], [right]) => compareCodePoints(left, right))
         .map(([name, sources]) => [name, Object.freeze(sources.sort(compareGuardedSources))]));
@@ -596,6 +625,14 @@ function assertUniqueInstalledIds(installed) {
         seen.add(binding.id);
     }
 }
+/**
+ * The reason recorded for a symlinked task/workflow source: it stays a
+ * per-source failure (like the read boundary it replaces), never a silent
+ * drop and never a follow.
+ */
+function symbolicSourceError(sourcePath) {
+    return new UsageError(`${sourcePath} is a symbolic source; guarded reads require a regular no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
+}
 function taskFailure(file, ref, cause) {
     const detail = taskSourceErrorDetail(cause);
     const reason = detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
@@ -629,6 +666,29 @@ export function assertSchedulerSourceSnapshot(snapshot) {
         throw new UsageError(`Scheduler desired source read set changed after projection; refusing native mutation: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
     }
 }
+/**
+ * Shared with the symlink classification in {@link compileTaskSources}: a
+ * `.yml` under `tasks/` (or, for `akm-task`, anywhere) is a task candidate —
+ * one classifier for both a captured file and an uncaptured symlink entry.
+ */
+function isAuthoredTaskRelativePath(adapterId, relativePath) {
+    if (!relativePath.endsWith(".yml"))
+        return false;
+    if (adapterId === "akm-task")
+        return true;
+    return path.posix.dirname(relativePath) === "tasks";
+}
+/**
+ * Shared with the symlink classification in {@link enumerateWorkflowLookups}:
+ * anything under `workflows/` (or, for `akm-workflow`, anywhere) is a
+ * workflow candidate — one classifier for both a captured file and an
+ * uncaptured symlink entry.
+ */
+function isAuthoredWorkflowRelativePath(adapterId, relativePath) {
+    if (adapterId === "akm-workflow")
+        return true;
+    return relativePath.startsWith("workflows/");
+}
 class SchedulerSourceCollector {
     #adapterId;
     #sourceRoot;
@@ -637,6 +697,14 @@ class SchedulerSourceCollector {
         this.#adapterId = input.adapterId;
         this.#sourceRoot = path.resolve(input.sourceRoot);
         const root = this.#collector.trackDirectory(this.#sourceRoot, this.#sourceRoot);
+        if (input.adapterId === "akm") {
+            for (const scheduledName of ["tasks", "workflows"]) {
+                const entry = root.entries.find((candidate) => candidate.name === scheduledName);
+                if (entry?.kind === "symlink") {
+                    throw new UsageError(`${path.join(this.#sourceRoot, scheduledName)} is a symbolic source with a physical source identity collision; guarded reads require one no-follow owner.`, "RESOURCE_ALREADY_EXISTS");
+                }
+            }
+        }
         const rootDirectories = new Set(root.entries.filter((entry) => entry.kind === "directory").map((entry) => entry.name));
         const candidates = [];
         if (input.adapterId === "akm") {
@@ -669,27 +737,33 @@ class SchedulerSourceCollector {
     authoredTaskSources(adapterId) {
         return this.#collector
             .snapshot()
-            .sources.filter((file) => {
-            if (!file.authored || !file.relativePath.endsWith(".yml"))
-                return false;
-            if (adapterId === "akm-task")
-                return true;
-            return path.posix.dirname(file.relativePath) === "tasks";
-        })
+            .sources.filter((file) => file.authored && isAuthoredTaskRelativePath(adapterId, file.relativePath))
             .sort(compareGuardedSources);
     }
     authoredWorkflowSources(adapterId) {
         return this.#collector
             .snapshot()
-            .sources.filter((file) => {
-            if (!file.authored)
-                return false;
-            if (adapterId === "akm-workflow")
-                return true;
-            return file.relativePath.startsWith("workflows/");
-        })
+            .sources.filter((file) => file.authored && isAuthoredWorkflowRelativePath(adapterId, file.relativePath))
             .sort(compareGuardedSources);
     }
+    /**
+     * Every `kind: "symlink"` entry across the directory manifests captured so
+     * far (never read, never followed — see `captureGuardedDirectoryManifest`),
+     * with its path relative to the source root so callers can classify it
+     * with the same predicates as a real, captured file.
+     */
+    symlinkSources() {
+        const entries = [];
+        for (const manifest of this.#collector.snapshot().directoryManifests) {
+            for (const entry of manifest.entries) {
+                if (entry.kind !== "symlink")
+                    continue;
+                const sourcePath = path.join(manifest.directoryPath, entry.name);
+                entries.push({ sourcePath, relativePath: toPosix(path.relative(this.#sourceRoot, sourcePath)) });
+            }
+        }
+        return entries;
+    }
     readBytes(file, containmentRoot) {
         this.#trackAncestors(file, containmentRoot);
         return this.#collector.readBytes(file, containmentRoot);

package/docs/reference/cli.md

@@ -1673,16 +1673,25 @@ in order:
 
 1. legacy config `extraParams` keys lifted onto first-class engine fields
    (`configExtraParams`);
-2. pending `state.db` migrations, historical-destructive ones included, with
+2. retired `experimental.*` config keys removed, today `workflowEngine`
+   (`configRetiredExperimentalKeys`) — config loading already ignores them
+   with a one-time warning, so this only cleans the file;
+3. scheduler grants bound to the configured source installation that was
+   approved, with stale grants for removed bundles dropped
+   (`configSchedulerSourceIds`);
+4. pending `state.db` migrations, historical-destructive ones included, with
    a verified sibling safety copy (`stateMigrations`) — the only path besides
    `akm upgrade` that admits released migration 018, which an ordinary
    command refuses;
-3. task-v2 files to task v3, then task-v3 files to task source v4
+5. source-owned schedule enablement converted to host-local scheduler grants
+   (`schedulerActivation`);
+6. task-v2 files to task v3, then task-v3 files to task source v4
    (`taskV3Migration`, `taskV4Migration`), each keeping its own lock, backup,
    prevalidation, and rollback, so a file blocked in the first generation does
    not stop the second from converting files already at `version: 3`;
-4. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
-   (`deadResidue`, `staleTxns`).
+7. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
+   (`deadResidue`, `staleTxns`), then live `.akm` writers relocated to
+   `$STATE`/`$CACHE` (`writerRelocation`).
 
 ```sh
 akm migrate status

package/package.json

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