akm-cli 0.10.261012-beta → 0.10.261013-beta

package/dist/commands/sources/bundle-cli.js

@@ -8,9 +8,7 @@
  * group, hard break, no alias kept at the top level:
  *   - `create` (= old top-level `init`, src/commands/sources/init.ts)
  *   - `add`    (= old top-level `add`, src/commands/sources/add-cli.ts — the
- *     command definition moved here; `add-cli.ts` keeps its exported helpers,
- *     including `auditInstalledStashForDangerousKeys`, which a test imports
- *     directly)
+ *     command definition moved here; `add-cli.ts` keeps its exported helpers)
  *   - `list`   (= old top-level `list`)
  *   - `remove` (= old top-level `remove`)
  *   - `update` (= old top-level `update`)
@@ -134,18 +132,21 @@ const updateCommand = defineJsonCommand({
             description: "Exit successfully when index/state database contention shows another akm operation is active",
             default: false,
         },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Installing a bundle is the trust decision: an
+        // update no longer scans env files for process-hijacking keys.
         "allow-dangerous-env-keys": {
             type: "boolean",
-            description: "Allow an update containing dangerous env keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the staged bundle.",
+            description: "Deprecated, no effect: update no longer scans env files for process-hijacking keys. Accepted through 0.10 for existing scripts.",
             default: false,
         },
         // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
-        // fail with UNKNOWN_FLAG. Deleting the previous directory of a read-only
-        // install whose content moved no longer asks: it is a re-fetchable cache.
+        // fail with UNKNOWN_FLAG. Pruning old install directories of a read-only
+        // bundle no longer asks: they are a re-fetchable cache.
         yes: {
             type: "boolean",
             alias: "y",
-            description: "Deprecated, no effect: update no longer asks before deleting a moved read-only install directory. Accepted through 0.10 for existing scripts.",
+            description: "Deprecated, no effect: update no longer asks before pruning old install directories of a read-only bundle. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
@@ -156,7 +157,6 @@ const updateCommand = defineJsonCommand({
                 target: args.target,
                 all: args.all,
                 force: args.force,
-                allowDangerousEnvKeys: args["allow-dangerous-env-keys"],
             });
         }
         catch (error) {
@@ -173,7 +173,6 @@ const updateCommand = defineJsonCommand({
                 target: args.target ?? null,
                 all: args.all === true,
                 force: args.force === true,
-                allowDangerousEnvKeys: args["allow-dangerous-env-keys"] === true,
                 processed: Array.isArray(result.processed)
                     ? result.processed.length
                     : 0,

package/dist/commands/sources/installed-stashes.js

@@ -22,20 +22,19 @@ import { AkmError, ConfigError, NotFoundError, UsageError } from "../../core/err
 import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath, getRegistryCacheDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { resolveGitContentRoot } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { readLockfile, upsertLockEntry } from "../../integrations/lockfile.js";
-import { parseRegistryRef } from "../../registry/resolve.js";
+import { parseRegistryRef, resolveRegistryArtifact } from "../../registry/resolve.js";
 import { getCachePaths, parseGitRepoUrl, runGit, syncMirroredRepo } from "../../sources/providers/git.js";
 import { replaceDirectory } from "../../sources/providers/git-install.js";
+import { installRevisionDir, isDirectory } from "../../sources/providers/provider-utils.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
 import { createWebsiteProvider } from "../../sources/providers/website.js";
 import { storeSecretResolver } from "../../sources/snapshot-fetchers/secret-seam.js";
 import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ingest.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
-import { auditStashForDangerousKeys } from "./dangerous-env-audit.js";
 import { removeInstalledRegistryEntry } from "./source-add.js";
 import { removeStash } from "./source-manage.js";
 /** Enumerate the registry-managed installs (lock-backed bundles) in a config. */
@@ -55,6 +54,7 @@ function listManagedInstalls(config) {
             source: lock.source,
             ref: lock.ref,
             localRoot: lock.localRoot ?? "",
+            installedAt: lock.installedAt ?? "",
             resolvedVersion: lock.resolvedVersion,
             resolvedRevision: lock.resolvedRevision,
             writable: componentWritable ?? bundle.writable === true,
@@ -379,18 +379,6 @@ function bundleComponent(config, id) {
     const component = bundleComponentConfig(bundle);
     return { root: component?.root ?? ".", writable: component?.writable ?? bundle?.writable === true };
 }
-async function auditStagedUpdate(auditRoot, ref, allowDangerousEnvKeys) {
-    const decision = await auditStashForDangerousKeys({
-        stashRoot: auditRoot,
-        ref,
-        allowDangerousKeys: allowDangerousEnvKeys,
-        isTTY: process.stdin.isTTY === true,
-        operation: "update",
-        renderBlockedError: false,
-    });
-    if (decision.blocked)
-        throw new NotFoundError(decision.error, decision.code);
-}
 function gitOrThrow(repoDir, args) {
     const result = runGit(["-C", repoDir, ...args], { timeout: 120_000 });
     if (result.status !== 0) {
@@ -399,7 +387,7 @@ function gitOrThrow(repoDir, args) {
     return result.stdout.trim();
 }
 /**
- * Publish an audited writable checkout: fast-forward the live checkout to
+ * Publish a staged writable checkout: fast-forward the live checkout to
  * exactly the staged commit. Git refuses a non-fast-forward or a merge that
  * would overwrite local work, and changes nothing in that case.
  */
@@ -423,15 +411,61 @@ function publishAndIndex(stashDir, publish) {
         return reindexAfterUpdate(stashDir);
     });
 }
+function managedCredential(managed) {
+    return managed.credential ? resolveSecret(managed.credential, storeSecretResolver.resolveSecret) : undefined;
+}
+/**
+ * The unchanged result for a read-only git or npm install whose upstream still
+ * resolves to the locked revision while its `<rev>` directory is in place, so
+ * there is nothing to fetch, publish or replace. Undefined when the install
+ * must be updated: `--force`, a writable or lockless install, a missing
+ * directory, or a new upstream revision.
+ */
+async function unchangedManagedItem(managed, force) {
+    if (force || managed.writable || !managed.resolvedRevision || !managed.localRoot)
+        return undefined;
+    if (managed.source !== "git" && managed.source !== "github" && managed.source !== "npm")
+        return undefined;
+    const revisionDir = installRevisionDir(getRegistryCacheDir(), managed.localRoot);
+    if (!revisionDir || !isDirectory(managed.localRoot))
+        return undefined;
+    const resolved = await resolveRegistryArtifact(parseRegistryRef(managed.ref), {
+        gitCredential: managedCredential(managed),
+    });
+    if (resolved.resolvedRevision !== managed.resolvedRevision)
+        return undefined;
+    return {
+        id: managed.installId,
+        source: managed.source,
+        ref: managed.ref,
+        previous: {
+            resolvedVersion: managed.resolvedVersion,
+            resolvedRevision: managed.resolvedRevision,
+            cacheDir: managed.localRoot,
+        },
+        installed: {
+            id: managed.installId,
+            source: managed.source,
+            ref: managed.ref,
+            artifactUrl: resolved.artifactUrl,
+            resolvedVersion: managed.resolvedVersion,
+            resolvedRevision: managed.resolvedRevision,
+            stashRoot: managed.localRoot,
+            cacheDir: revisionDir,
+            installedAt: managed.installedAt,
+            writable: false,
+            extractedDir: path.join(revisionDir, "extracted"),
+        },
+        changed: { version: false, revision: false, any: false },
+    };
+}
 /** Fetch a registry-managed install into staging without touching its live content. */
 async function stageManagedUpdate(managed, force) {
-    const credential = managed.credential
-        ? resolveSecret(managed.credential, storeSecretResolver.resolveSecret)
-        : undefined;
+    const credential = managedCredential(managed);
     if (managed.writable && managed.localRoot) {
         // A writable install is a checkout that may carry local commits: the
-        // provider fast-forwards a copy, the copy is audited, and the live
-        // checkout is then fast-forwarded to exactly the audited commit.
+        // provider fast-forwards a copy, and the live checkout is then
+        // fast-forwarded to exactly that fetched commit.
         const topLevel = runGit(["-C", managed.localRoot, "rev-parse", "--show-toplevel"]);
         if (topLevel.status !== 0 || !topLevel.stdout.trim()) {
             throw new UsageError(`Writable Git install at ${managed.localRoot} is not a checkout; refusing to update it.`);
@@ -452,7 +486,6 @@ async function stageManagedUpdate(managed, force) {
             return {
                 synced: { ...fetched, contentDir: managed.localRoot, cacheDir: liveRepo, extractedDir: liveRepo },
                 staged: {
-                    auditRoot: path.resolve(fetched.contentDir, managed.componentRoot),
                     publish: () => fastForwardCheckout(liveRepo, stagedRepo),
                     cleanup: () => cleanupDirectoryBestEffort(stagingParent, "bundle update"),
                 },
@@ -468,7 +501,7 @@ async function stageManagedUpdate(managed, force) {
         const synced = await syncFromRef(managed.ref, { force, writable: managed.writable });
         return {
             synced,
-            staged: { auditRoot: path.resolve(synced.contentDir, managed.componentRoot), publish() { }, cleanup() { } },
+            staged: { publish() { }, cleanup() { } },
         };
     }
     const cacheRoot = getRegistryCacheDir();
@@ -490,7 +523,6 @@ async function stageManagedUpdate(managed, force) {
                 extractedDir: toLive(fetched.extractedDir),
             },
             staged: {
-                auditRoot: path.resolve(fetched.contentDir, managed.componentRoot),
                 publish: () => replaceDirectory(fetched.cacheDir, liveCacheDir),
                 cleanup: () => cleanupDirectoryBestEffort(stagingParent, "bundle update"),
             },
@@ -501,8 +533,8 @@ async function stageManagedUpdate(managed, force) {
         throw error;
     }
 }
-/** Fetch a plain git source into staging, audit it, publish it, and reindex. */
-async function syncGitPlainSource(config, gitSource, stashDir, allowDangerousEnvKeys) {
+/** Fetch a plain git source into staging, publish it, and reindex. */
+async function syncGitPlainSource(config, gitSource, stashDir) {
     const id = gitSource.name ?? gitSource.url ?? "";
     const ref = gitSource.url ?? "";
     if (!gitSource.url)
@@ -514,7 +546,7 @@ async function syncGitPlainSource(config, gitSource, stashDir, allowDangerousEnv
     try {
         const stagedPaths = getCachePaths(canonicalUrl, stagingParent);
         // A writable mirror may carry local commits: pull into a copy, then
-        // fast-forward the live checkout once the copy passes the audit.
+        // fast-forward the live checkout to it.
         const liveCheckout = component.writable && fs.existsSync(livePaths.repoDir);
         if (liveCheckout)
             fs.cpSync(livePaths.rootDir, stagedPaths.rootDir, { recursive: true, preserveTimestamps: true });
@@ -526,7 +558,6 @@ async function syncGitPlainSource(config, gitSource, stashDir, allowDangerousEnv
                 ? { credential: resolveSecret(gitSource.credential, storeSecretResolver.resolveSecret) }
                 : {}),
         });
-        await auditStagedUpdate(path.resolve(resolveGitContentRoot(stagedPaths.repoDir), component.root), ref, allowDangerousEnvKeys);
         const index = await publishAndIndex(stashDir, () => {
             if (liveCheckout)
                 fastForwardCheckout(livePaths.repoDir, stagedPaths.repoDir);
@@ -543,7 +574,7 @@ async function syncGitPlainSource(config, gitSource, stashDir, allowDangerousEnv
  * Re-crawl a website source and reindex. The website provider already builds
  * its snapshot in a staging directory and swaps it in, so a killed refresh
  * keeps the previous mirror; a snapshot holds only knowledge pages, so there
- * is no env file to audit.
+ * is no env file in it.
  */
 async function syncWebsitePlainSource(websiteSource, stashDir) {
     const id = websiteSource.name ?? websiteSource.url ?? "";
@@ -556,8 +587,8 @@ async function syncWebsitePlainSource(websiteSource, stashDir) {
     return { item: { id, kind: "website", ref: websiteSource.url ?? "" }, index };
 }
 /** Sync a git-mirrored (plain) source and return an UpdateResponse (single-target path). */
-async function updateGitSource(config, stashDir, target, all, gitSource, allowDangerousEnvKeys) {
-    const synced = await syncGitPlainSource(config, gitSource, stashDir, allowDangerousEnvKeys);
+async function updateGitSource(config, stashDir, target, all, gitSource) {
+    const synced = await syncGitPlainSource(config, gitSource, stashDir);
     return buildUpdateResponse(stashDir, target, all, [], { plainSynced: [synced.item], index: synced.index });
 }
 /** Re-crawl a website (plain) source and return an UpdateResponse (single-target path). */
@@ -602,6 +633,7 @@ function managedInstallViewOfPlainNpm(config, npmSource) {
         source: "npm",
         ref: spec.startsWith("npm:") ? spec : `npm:${spec}`,
         localRoot: "",
+        installedAt: "",
         writable: false,
         componentRoot: bundleComponent(config, id).root,
         requiredRoots: [],
@@ -609,18 +641,21 @@ function managedInstallViewOfPlainNpm(config, npmSource) {
 }
 /**
  * Sync a single registry-managed install and return the processed record:
- * fetch into staging, audit, publish, write its lock entry, reindex.
+ * fetch into staging, publish, write its lock entry, reindex.
  *
- * Read-only installs are keyed by resolved revision, so every upstream change
- * resolves a new content directory, and the previous one is deleted once the
- * new one is published. That directory is a re-fetchable cache: local and
- * writable installs never take this path, and a directory another bundle or
- * lock entry still references is kept. So deleting it never asks for confirmation.
+ * Read-only installs are keyed by resolved revision. An unchanged revision
+ * returns early: nothing is fetched or published. After a real change the new
+ * <rev> directory is published, the previous <rev> directory is kept, and older
+ * ones are pruned, unless another bundle or lock entry still references them.
+ * Those directories are a re-fetchable cache (local and writable installs never
+ * take this path), so none of this prompts.
  */
-async function updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys) {
+async function updateManagedInstall(managed, force, stashDir) {
+    const unchanged = await unchangedManagedItem(managed, force);
+    if (unchanged)
+        return { item: unchanged };
     const { synced, staged } = await stageManagedUpdate(managed, force);
     try {
-        await auditStagedUpdate(staged.auditRoot, managed.ref, allowDangerousEnvKeys);
         const installedEntry = {
             id: managed.installId,
             // Preserve the original source classification. syncFromRef() re-derives the
@@ -655,14 +690,8 @@ async function updateManagedInstall(managed, force, stashDir, allowDangerousEnvK
                 installedAt: synced.syncedAt,
             });
         });
-        if (movedRoot) {
-            if (referencesRoot(managed.localRoot, loadConfig(), readLockfile())) {
-                warn(`[akm bundle update] kept previous install directory at ${managed.localRoot} because another configured or locked bundle still references it.`);
-            }
-            else {
-                cleanupDirectoryBestEffort(managed.localRoot, "update");
-            }
-        }
+        if (movedRoot)
+            pruneOlderRevisions(managed.localRoot, synced.cacheDir);
         const versionChanged = (managed.resolvedVersion ?? "") !== (synced.resolvedVersion ?? "");
         const revisionChanged = (managed.resolvedRevision ?? "") !== (synced.resolvedRevision ?? "");
         return {
@@ -689,6 +718,31 @@ async function updateManagedInstall(managed, force, stashDir, allowDangerousEnvK
         staged.cleanup();
     }
 }
+/**
+ * After a real revision change, keep the previous `<rev>` directory (a process
+ * may still be running from it) and remove every older sibling in the install's
+ * directory, unless another configured or locked bundle still uses it.
+ */
+function pruneOlderRevisions(previousRoot, currentCacheDir) {
+    const previousDir = installRevisionDir(getRegistryCacheDir(), previousRoot);
+    const installDir = path.dirname(path.resolve(currentCacheDir));
+    if (!previousDir || path.dirname(previousDir) !== installDir)
+        return;
+    const keep = new Set([previousDir, path.resolve(currentCacheDir)]);
+    const config = loadConfig();
+    const locks = readLockfile();
+    for (const entry of fs.readdirSync(installDir, { withFileTypes: true })) {
+        const dir = path.join(installDir, entry.name);
+        if (!entry.isDirectory() || keep.has(dir))
+            continue;
+        if (referencesRoot(dir, config, locks)) {
+            warn(`[akm bundle update] kept older install directory at ${dir} because another configured or locked bundle still references it.`);
+        }
+        else {
+            cleanupDirectoryBestEffort(dir, "update");
+        }
+    }
+}
 function referencesRoot(target, config, locks) {
     const resolvedTarget = path.resolve(target);
     const locksById = new Map(locks.map((entry) => [entry.id, entry]));
@@ -716,15 +770,16 @@ export async function akmUpdate(input) {
     const target = input?.target?.trim();
     const all = input?.all === true;
     const force = input?.force === true;
-    const allowDangerousEnvKeys = input?.allowDangerousEnvKeys === true;
     const config = loadConfig();
     const managedInstalls = listManagedInstalls(config);
     if (target && !all) {
         // Registry-managed install (lock-backed) — re-download from its locator.
         const managed = resolveManagedTarget(config, target);
         if (managed) {
-            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
-            return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
+            const updated = await updateManagedInstall(managed, force, stashDir);
+            return buildUpdateResponse(stashDir, target, all, [updated.item], {
+                index: updated.index ?? readCurrentIndexSummary(),
+            });
         }
         // Plain git / website source (bundles without a lock) — provider re-sync.
         const stashes = getSources(config);
@@ -752,7 +807,7 @@ export async function akmUpdate(input) {
             return false;
         });
         if (gitMatch)
-            return updateGitSource(config, stashDir, target, all, gitMatch, allowDangerousEnvKeys);
+            return updateGitSource(config, stashDir, target, all, gitMatch);
         const websiteMatch = stashes.find((s) => {
             if (s.type !== "website")
                 return false;
@@ -780,8 +835,10 @@ export async function akmUpdate(input) {
             return false;
         });
         if (npmMatch) {
-            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, stashDir, allowDangerousEnvKeys);
-            return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
+            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, stashDir);
+            return buildUpdateResponse(stashDir, target, all, [updated.item], {
+                index: updated.index ?? readCurrentIndexSummary(),
+            });
         }
         const filesystemMatch = stashes.find((source) => {
             if (source.type !== "filesystem")
@@ -803,9 +860,9 @@ export async function akmUpdate(input) {
     let latestIndex;
     for (const managed of selected) {
         try {
-            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managed, force, stashDir);
             processed.push(updated.item);
-            latestIndex = updated.index;
+            latestIndex = updated.index ?? latestIndex;
         }
         catch (error) {
             if (!all)
@@ -828,14 +885,14 @@ export async function akmUpdate(input) {
             const id = plain.name ?? plain.path ?? plain.url ?? "";
             try {
                 if (plain.type === "git") {
-                    const updated = await syncGitPlainSource(config, plain, stashDir, allowDangerousEnvKeys);
+                    const updated = await syncGitPlainSource(config, plain, stashDir);
                     plainSynced.push(updated.item);
                     latestIndex = updated.index;
                 }
                 else if (plain.type === "npm") {
-                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, stashDir, allowDangerousEnvKeys);
+                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, stashDir);
                     processed.push(updated.item);
-                    latestIndex = updated.index;
+                    latestIndex = updated.index ?? latestIndex;
                 }
                 else if (plain.type === "website") {
                     const updated = await syncWebsitePlainSource(plain, stashDir);
@@ -896,14 +953,13 @@ function sourceKindForInstall(source) {
 }
 function updateFailureOutcome(id, kind, error) {
     const code = error instanceof AkmError ? error.code : undefined;
-    const status = code === "DANGEROUS_ENV_KEY" || code === "DANGEROUS_ENV_AUDIT_FAILED" ? "blocked" : "failed";
     const message = error instanceof Error ? error.message : String(error);
     return {
         id,
         kind,
-        status,
+        status: "failed",
         ...(code ? { code } : {}),
-        reason: `${status}: ${message}`,
+        reason: `failed: ${message}`,
     };
 }
 function selectManagedTargets(config, installs, target, all) {

package/dist/commands/sources/schema-repair.js

@@ -244,7 +244,5 @@ async function defaultFindFilePath(ref, stashDir) {
     return resolveAssetPath(ref, {
         stashDir,
         mode: "index-first",
-        directoryIndexNames: ["SKILL.md", "index.md", "README.md"],
-        preserveDirectNameFallback: true,
     });
 }

package/dist/commands/sources/source-clone.js

@@ -12,7 +12,7 @@ import { isBundleSlug } from "../../core/asset/asset-ref.js";
 import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter, replaceFrontmatterBlocks } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
-import { isWithin } from "../../core/common.js";
+import { isWithin, safeRealpath } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { defaultBundleForTarget } from "../../core/mutation-target.js";
@@ -23,6 +23,7 @@ import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { buildFileContext } from "../../indexer/walk/file-context.js";
+import { isFileOrFileSymlink } from "../../indexer/walk/walker.js";
 import { isRemoteOrigin, resolveSourcesForLocator, resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
@@ -161,18 +162,20 @@ export async function akmClone(options) {
         : writeTarget?.selector
             ? `in target "${writeTarget.selector}"`
             : "in working stash";
-    // Guard against self-clone
+    // Guard against self-clone. Compare physical paths: sourcePath is the
+    // authored path, and a source that is a symlink to the destination is the
+    // same file (or skill) even though the authored paths differ.
     if (isSkill) {
-        const sourceSkillDir = path.resolve(path.dirname(sourcePath));
-        const destSkillDir = path.resolve(path.join(destRoot, typeDir, destName));
+        const sourceSkillDir = safeRealpath(path.dirname(sourcePath));
+        const destSkillDir = safeRealpath(path.join(destRoot, typeDir, destName));
         if (sourceSkillDir === destSkillDir) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
         }
     }
     else {
-        const resolvedSource = path.resolve(sourcePath);
+        const resolvedSource = safeRealpath(sourcePath);
         const effectiveDestName = !path.extname(destFileName) && sourceExt ? destFileName + sourceExt : destFileName;
-        const resolvedDest = path.resolve(path.join(destRoot, typeDir, effectiveDestName));
+        const resolvedDest = safeRealpath(path.join(destRoot, typeDir, effectiveDestName));
         if (resolvedSource === resolvedDest) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
         }
@@ -182,7 +185,9 @@ export async function akmClone(options) {
         let overwritten;
         let operationPaths;
         if (isSkill) {
-            const sourceSkillDir = path.dirname(sourcePath);
+            // sourcePath is the authored path; a symlinked skill directory must be
+            // copied by content, never as the link.
+            const sourceSkillDir = fs.realpathSync(path.dirname(sourcePath));
             const destSkillDir = path.join(destRoot, typeDir, destName);
             assertNoDestinationSymlinkParent(destRoot, destSkillDir);
             const existing = lstatIfExists(destSkillDir);
@@ -195,7 +200,11 @@ export async function akmClone(options) {
             // final symlink is removed as an entry, never traversed.
             const stagingDir = `${destSkillDir}.tmp-${randomUUID()}`;
             try {
+                // Directory links are copied as links and never descended (as the walker
+                // does); each file link is then replaced by its content, so the stamp
+                // below never writes through a link.
                 fs.cpSync(sourceSkillDir, stagingDir, { recursive: true, errorOnExist: true, force: false });
+                materializeFileLinks(stagingDir);
                 stampCloneOrigin(path.join(stagingDir, "SKILL.md"), originRef);
                 if (overwritten)
                     fs.rmSync(destSkillDir, { recursive: true, force: true });
@@ -348,6 +357,21 @@ function assertNoDestinationSymlinkParent(root, destination) {
         throw new UsageError(`Clone destination has a symbolic-link parent outside the selected target boundary: ${parentDir}.`, "PATH_ESCAPE_VIOLATION");
     }
 }
+/** Replace each file symlink under `root` with a regular file holding its target's bytes. Directory links are left as links. */
+function materializeFileLinks(root) {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            materializeFileLinks(entryPath);
+        }
+        else if (entry.isSymbolicLink() && isFileOrFileSymlink(entryPath)) {
+            const content = fs.readFileSync(entryPath);
+            const { mode } = fs.statSync(entryPath);
+            fs.rmSync(entryPath);
+            fs.writeFileSync(entryPath, content, { mode });
+        }
+    }
+}
 function listTreeFiles(root) {
     const files = [];
     for (const entry of fs.readdirSync(root, { withFileTypes: true })) {

package/dist/commands/tasks/explain.js

@@ -247,7 +247,7 @@ export async function akmTaskExplain(ref, options = {}) {
     }
     const sourcePath = owner.path;
     const yaml = fs.readFileSync(sourcePath, "utf8");
-    const parsed = parseTaskSource({ yaml, filePath: sourcePath, workspaceRoot: bundle.source.path });
+    const parsed = parseTaskSource({ yaml, filePath: sourcePath });
     const inputContract = parsed.v4.inputs ?? {};
     // Code-review finding (explain.ts:299, B-N4): `akm task run`'s
     // load-task.ts copies this same materialize -> applyInputDefaults ->