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

package/CHANGELOG.md

@@ -6,6 +6,31 @@ 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

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/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/package.json

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