akm-cli 0.9.6 → 0.9.7

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

@@ -11525,6 +11525,7 @@ var SCRIPT_EXTENSIONS = new Set([
   ".kts"
 ]);
 var WORKFLOW_EXTENSIONS = [".md", ".yml"];
+var DERIVED_SUFFIX = ".derived";
 var KNOWN_TYPES = [
   "skill",
   "command",
@@ -11685,6 +11686,9 @@ function assetPathForName(assetType, typeRoot, name) {
 }
 function assetPathCandidatesForName(assetType, typeRoot, name) {
   const primary = assetPathForName(assetType, typeRoot, name);
+  if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
+    return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
+  }
   if (assetType !== "env")
     return [primary];
   const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;
@@ -17606,6 +17610,9 @@ function peekTaskSourceVersion(root) {
   return typeof value === "number" ? value : undefined;
 }
 var TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+function unmigratableVersionError(filePath, version, reason, detail) {
+  return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run — the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
+}
 function unsupportedVersionError(filePath, version) {
   return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
@@ -17625,12 +17632,12 @@ function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
   } else {
     const v3Outcome = planTaskToV3File(baseInput);
     if (v3Outcome.status !== "changed")
-      return;
+      return { reason: v3Outcome.reason, detail: v3Outcome.detail };
     v3Bytes = v3Outcome.after;
   }
   const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
   if (v4Outcome.status !== "changed")
-    return;
+    return { reason: v4Outcome.reason, detail: v4Outcome.detail };
   return v4Outcome.after.toString("utf8");
 }
 function parseTaskSource(input) {
@@ -17638,16 +17645,17 @@ function parseTaskSource(input) {
   const version = peekTaskSourceVersion(root);
   if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
     if (version === 2 || version === 3) {
-      const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-      if (v4Yaml !== undefined) {
+      const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+      if (typeof shimmed === "string") {
         const v4 = parseTaskSourceV4({
-          yaml: v4Yaml,
+          yaml: shimmed,
           filePath: input.filePath,
           ...input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}
         });
         warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
         return Object.freeze({ version: 4, v4 });
       }
+      throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
     }
     throw unsupportedVersionError(input.filePath, version);
   }
@@ -27990,9 +27998,7 @@ var BUILTIN_IMPROVE_STRATEGY_NAMES = [
   "default",
   "quick",
   "thorough",
-  "memory-focus",
   "graph-refresh",
-  "frequent",
   "consolidate",
   "catchup",
   "reflect-distill",

package/dist/scripts/akm-migrate.js

@@ -11524,6 +11524,7 @@ var SCRIPT_EXTENSIONS = new Set([
   ".kts"
 ]);
 var WORKFLOW_EXTENSIONS = [".md", ".yml"];
+var DERIVED_SUFFIX = ".derived";
 var KNOWN_TYPES = [
   "skill",
   "command",
@@ -11684,6 +11685,9 @@ function assetPathForName(assetType, typeRoot, name) {
 }
 function assetPathCandidatesForName(assetType, typeRoot, name) {
   const primary = assetPathForName(assetType, typeRoot, name);
+  if (assetType === "memory" && !name.endsWith(DERIVED_SUFFIX)) {
+    return [primary, assetPathForName(assetType, typeRoot, `${name}${DERIVED_SUFFIX}`)];
+  }
   if (assetType !== "env")
     return [primary];
   const base = name === "default" ? "" : name.endsWith("/default") ? name.slice(0, -"default".length) : undefined;
@@ -17528,6 +17532,9 @@ function peekTaskSourceVersion(root) {
   return typeof value === "number" ? value : undefined;
 }
 var TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+function unmigratableVersionError(filePath, version, reason, detail) {
+  return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run \u2014 the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
+}
 function unsupportedVersionError(filePath, version) {
   return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
@@ -17547,12 +17554,12 @@ function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
   } else {
     const v3Outcome = planTaskToV3File(baseInput);
     if (v3Outcome.status !== "changed")
-      return;
+      return { reason: v3Outcome.reason, detail: v3Outcome.detail };
     v3Bytes = v3Outcome.after;
   }
   const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
   if (v4Outcome.status !== "changed")
-    return;
+    return { reason: v4Outcome.reason, detail: v4Outcome.detail };
   return v4Outcome.after.toString("utf8");
 }
 function parseTaskSource(input) {
@@ -17560,16 +17567,17 @@ function parseTaskSource(input) {
   const version = peekTaskSourceVersion(root);
   if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
     if (version === 2 || version === 3) {
-      const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-      if (v4Yaml !== undefined) {
+      const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+      if (typeof shimmed === "string") {
         const v4 = parseTaskSourceV4({
-          yaml: v4Yaml,
+          yaml: shimmed,
           filePath: input.filePath,
           ...input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}
         });
         warn(`akm: task ${input.filePath} uses schema v${version} \u2014 auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
         return Object.freeze({ version: 4, v4 });
       }
+      throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
     }
     throw unsupportedVersionError(input.filePath, version);
   }
@@ -27912,9 +27920,7 @@ var BUILTIN_IMPROVE_STRATEGY_NAMES = [
   "default",
   "quick",
   "thorough",
-  "memory-focus",
   "graph-refresh",
-  "frequent",
   "consolidate",
   "catchup",
   "reflect-distill",

package/dist/sources/snapshot-fetchers/website-ingest.js

@@ -23,6 +23,9 @@ const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 const QUEUE_EXPANSION_FACTOR = 5;
 const MAX_PAGES_DEFAULT = 50;
 const MAX_DEPTH_DEFAULT = 3;
+/** Byte cap for the `llms.txt` manifest itself — a curated link list, never a large file. */
+const LLMS_TXT_BYTE_CAP = 512 * 1024;
+const LLMS_TXT_BODY_TIMEOUT_MS = 15_000;
 /**
  * Per-page body cap for website scraping. HTML pages this large are
  * almost never useful as agent knowledge sources and a runaway server
@@ -531,6 +534,38 @@ async function crawlWebsite(startUrl, options) {
         ? createAllowAllRobotsPolicy()
         : createRobotsPolicy((robotsUrl) => loadRobotsTxt(robotsUrl, { allowPrivateHosts: options.allowPrivateHosts, signal: crawlSignal }));
     await assertStartUrlAllowedByRobots(robots, start, options.rawStartUrl);
+    // llms.txt fast path: an increasing number of doc sites publish a curated,
+    // deduplicated link list at `/llms.txt` specifically for tools like this
+    // one. When present, use it as the crawl frontier instead of discovering
+    // links by parsing HTML — each linked page still goes through the exact
+    // same robots-compliant, host-guarded `fetchWebsitePage` call below, so
+    // ingested pages stay individually addressable. Gated to origin-root start
+    // URLs only (mirrors `extractGithubRepository`'s repo-root restriction):
+    // adding a specific page must fetch that page, not silently pull in the
+    // whole site's manifest.
+    if (isOriginRootUrl(start)) {
+        const manifest = await fetchLlmsManifest(start, robots, {
+            allowPrivateHosts: options.allowPrivateHosts,
+            signal: crawlSignal,
+        });
+        if (manifest) {
+            warn("[akm] Using llms.txt manifest from %s", manifest.manifestUrl);
+            queue.length = 0;
+            for (const link of manifest.links) {
+                // A manifest can name arbitrary hosts; only same-origin links are
+                // honored by default, same as links discovered mid-crawl below.
+                if (link.origin !== allowedOrigin)
+                    continue;
+                const candidate = normalizeCrawlUrl(link.toString());
+                if (!candidate)
+                    continue;
+                // depth = maxDepth: fetch each manifest page individually, but don't
+                // treat it as a fresh BFS seed — the manifest is already the
+                // author-curated set of pages worth ingesting.
+                queue.push({ url: candidate, rawUrl: link.toString(), depth: options.maxDepth, deferrals: 0 });
+            }
+        }
+    }
     // Counts actual `fetchWebsitePage` invocations (regardless of outcome) so
     // Crawl-delay pacing skips the first fetch and never charges a delay slot
     // to a URL that robots.txt skipped without ever being fetched (C-11).
@@ -870,6 +905,97 @@ function buildMarkdownSnapshot(page, slug, tags) {
         "",
     ].join("\n");
 }
+/**
+ * True for a start URL that names an origin's root (no path, no query).
+ * Matches how `extractGithubRepository` restricts its own special-case match
+ * to repository-root URLs — the llms.txt probe must not fire for a
+ * user-supplied deep link, or `akm bundle add <site>/guides/foo` would
+ * silently ingest the whole site's manifest instead of the page requested.
+ */
+export function isOriginRootUrl(url) {
+    return url.pathname === "/" && !url.search;
+}
+/**
+ * Parses the `llms.txt` link-list format: list items shaped like
+ * `- [title](path) - description` (the description, and its separator, are
+ * ignored — only the link target is needed). Any line that isn't a markdown
+ * link list item — headings, the leading `# Title`/`> summary` lines, prose —
+ * is simply not a link line and is skipped.
+ */
+export function parseLlmsTxtLinks(text, baseUrl) {
+    const links = [];
+    const seen = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const match = line.trim().match(/^-\s*\[[^\]]*\]\(([^)\s]+)\)/);
+        const href = match?.[1];
+        if (!href)
+            continue;
+        let resolved;
+        try {
+            resolved = new URL(href, baseUrl);
+        }
+        catch {
+            continue;
+        }
+        if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+            continue;
+        const key = resolved.toString();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        links.push(resolved);
+    }
+    return links;
+}
+/**
+ * Probes `<origin>/llms.txt` and, if present, returns its parsed link list.
+ * Reuses `fetchWebsiteResponse` so the manifest fetch itself gets the exact
+ * same SSRF host guard, redirect handling, and (via `robots`) robots.txt
+ * compliance as any other page fetch — this is still a fetch against a
+ * user-supplied host, no different from the rest of the crawl.
+ *
+ * `llms-full.txt` (the single-file concatenation of every page) is
+ * deliberately NOT read here. Its `## <path>` separators are ambiguous — page
+ * content legitimately contains `##` headings too — so recovered page
+ * boundaries can't be trusted, whereas per-page fetches through the existing
+ * pipeline are cheap, bounded by this author-curated list, and produce
+ * cleanly addressable assets. See the issue's "alternatives considered".
+ */
+async function fetchLlmsManifest(start, robots, options) {
+    const manifestUrl = new URL("/llms.txt", start.origin).toString();
+    const decision = await resolveCrawlRobotsDecision(robots, manifestUrl);
+    if (!decision.allowed)
+        return null;
+    let fetched;
+    try {
+        fetched = await fetchWebsiteResponse(decision.fetchUrl, 0, {
+            allowPrivateHosts: options.allowPrivateHosts,
+            signal: options.signal,
+            robots,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!fetched.response.ok) {
+        await fetched.response.body?.cancel().catch(() => undefined);
+        return null;
+    }
+    let text;
+    try {
+        text = await readBodyWithByteCap(fetched.response, LLMS_TXT_BYTE_CAP, {
+            bodyTimeoutMs: LLMS_TXT_BODY_TIMEOUT_MS,
+            signal: options.signal,
+        });
+    }
+    catch {
+        return null;
+    }
+    const links = parseLlmsTxtLinks(text, fetched.finalUrl);
+    if (links.length === 0)
+        return null;
+    return { manifestUrl: fetched.finalUrl, links };
+}
 function normalizeCrawlUrl(rawUrl) {
     try {
         const parsed = new URL(rawUrl);

package/dist/storage/repositories/index-connection.js

@@ -10,10 +10,12 @@
  * import their opener from a sibling here instead of reaching up into the
  * indexer — inverting the old storage→indexer arrow.
  */
+import fs from "node:fs";
 import { createRequire } from "node:module";
 import { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
 import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
@@ -21,9 +23,23 @@ import { openSqliteReadSnapshot } from "../sqlite-read-snapshot.js";
 import { isCanonicalIndexGeneration } from "./index-entry-schema.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
+/**
+ * Whether `error` is SQLite reporting on-disk corruption (`SQLITE_CORRUPT`,
+ * "database disk image is malformed") rather than a permission, lock, or
+ * schema problem. Matched on both `code` (bun:sqlite, better-sqlite3) and
+ * message text, since driver error shapes are not perfectly uniform.
+ */
+function isCorruptionError(error) {
+    const code = error?.code;
+    if (code === "SQLITE_CORRUPT")
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("database disk image is malformed") || message.includes("SQLITE_CORRUPT");
+}
 export function openIndexDatabase(dbPath, options) {
-    return openManagedDatabase({
-        path: dbPath ?? getDbPath(),
+    const resolvedPath = dbPath ?? getDbPath();
+    const spec = {
+        path: resolvedPath,
         init: (db) => {
             // Try to load sqlite-vec extension
             loadVecExtension(db);
@@ -41,7 +57,33 @@ export function openIndexDatabase(dbPath, options) {
             // Warn once at init if using JS fallback with many entries
             warnIfVecMissing(db, { once: true });
         },
-    });
+    };
+    try {
+        return openManagedDatabase(spec);
+    }
+    catch (error) {
+        // index.db is a derived cache, fully regenerable from the stash on disk
+        // (see src/core/state-db.ts's "Why a separate database from index.db"
+        // note) — so real on-disk corruption is recovered by deleting the file
+        // and rebuilding, not by surfacing a raw SQLITE_CORRUPT to the caller or
+        // quietly falling through to an unreadable index. This mirrors the
+        // existing stale-version-marker rebuild below, one layer further down
+        // (that path opens fine and rewrites tables in place; corruption prevents
+        // even opening, so the file itself has to go first).
+        if (!isCorruptionError(error))
+            throw error;
+        warn(`Index database is corrupt at ${resolvedPath} — rebuilding.`);
+        for (const suffix of ["", "-wal", "-shm"]) {
+            try {
+                fs.rmSync(`${resolvedPath}${suffix}`, { force: true });
+            }
+            catch {
+                // Best-effort cleanup; the retried open below still fails loudly if
+                // the file could not actually be removed.
+            }
+        }
+        return openManagedDatabase(spec);
+    }
 }
 /**
  * Read the operator-configured embedding dimension from the on-disk config.

package/dist/tasks/backends/cron.js

@@ -31,7 +31,7 @@ import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
-import { buildScheduledBindingInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { buildScheduledBindingInvocation, parsePublicSchedulerInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, SCHEDULER_CONTEXT_ARG, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
 import { nodeFs, throwIfNotOk } from "./exec-utils.js";
 const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
 const END = (id) => `# akm:task ${assertCronValue(id)} END`;
@@ -105,7 +105,7 @@ export function CRON_BACKEND(options = {}) {
             replaceCrontab(exec, existing, next);
         },
         list() {
-            return [...inspectCronState(readCrontab(exec)).installed];
+            return [...inspectCronState(readCrontab(exec), defaultContextPath).installed];
         },
         listForRebind() {
             const existing = readCrontab(exec);
@@ -123,14 +123,14 @@ export function CRON_BACKEND(options = {}) {
             });
         },
         listNativeArtifacts() {
-            return [...inspectCronState(readCrontab(exec)).artifacts];
+            return [...inspectCronState(readCrontab(exec), defaultContextPath).artifacts];
         },
         inspectBindings() {
-            return inspectCronState(readCrontab(exec));
+            return inspectCronState(readCrontab(exec), defaultContextPath);
         },
         snapshotBindings(ids) {
             const crontab = readCrontab(exec);
-            const inspection = inspectCronState(crontab);
+            const inspection = inspectCronState(crontab, defaultContextPath);
             const keys = new Set(ids.map(schedulerNativeArtifactKey));
             return Object.freeze({
                 kind: CRON_SNAPSHOT,
@@ -144,7 +144,7 @@ export function CRON_BACKEND(options = {}) {
                 throw new ConfigError("Invalid cron scheduler snapshot.", "INVALID_CONFIG_FILE");
             }
             const existing = readCrontab(exec);
-            const current = inspectCronState(existing);
+            const current = inspectCronState(existing, defaultContextPath);
             const safeNativeIds = [];
             const errors = [];
             if (expectedCurrent) {
@@ -192,7 +192,7 @@ export function CRON_BACKEND(options = {}) {
         },
     };
 }
-function inspectCronState(crontab) {
+function inspectCronState(crontab, fallbackContextPath) {
     const installed = [];
     const artifacts = [];
     for (const { id, body } of listBlocks(crontab)) {
@@ -207,7 +207,14 @@ function inspectCronState(crontab) {
             signature: fingerprint,
             ...(parsed.target !== undefined ? { target: parsed.target } : {}),
             binding: parsed.binding,
-            contextPath: parsed.contextPath,
+            // A legacy (pre-`--scheduler-context`) row has no real descriptor
+            // path to report — `extractLegacyCronInvocation` leaves it "". Fall
+            // back to the current default so downstream consumers (context
+            // validation in `akm task prune`/`explain`, `sync`'s reuse of an
+            // existing binding's contextPath) see a real, resolvable descriptor
+            // rather than an empty path, since the row is about to be reconciled
+            // to a current one anyway (#881).
+            contextPath: parsed.contextPath || fallbackContextPath,
         };
         Object.defineProperty(ref, "nativeId", { value: id });
         Object.defineProperty(ref, "invocation", { value: Object.freeze([...parsed.invocation]) });
@@ -323,7 +330,40 @@ export function extractCronInvocation(body) {
     const redirectIndex = fields.indexOf(">>", commandStart);
     if (redirectIndex === -1)
         return undefined;
-    return parseScheduledBindingArgv(fields.slice(commandStart, redirectIndex));
+    const tail = fields.slice(commandStart, redirectIndex);
+    const parsed = parseScheduledBindingArgv(tail);
+    if (parsed)
+        return parsed;
+    // Rows written by akm < 0.9.2 (before `--scheduler-context` existed) have
+    // no context argument at all — just the akm argv immediately followed by
+    // the public `task run …` / `workflow run …` tail. `extractCronInvocation`
+    // only ever runs on a body already isolated between this backend's own
+    // `# akm:task … BEGIN/END` sentinels (see `parseBlocks`), so recognizing
+    // this older shape here doesn't extend trust to any unmarked crontab
+    // line — it only lets sync see and reconcile a row akm already owns
+    // instead of treating it as absent and colliding with the still-present
+    // artifact (#881). Guarded on the marker's absence so a row that DOES
+    // carry `--scheduler-context` but fails to parse for some other reason
+    // is never silently reinterpreted as legacy.
+    if (tail.includes(SCHEDULER_CONTEXT_ARG))
+        return undefined;
+    return extractLegacyCronInvocation(tail);
+}
+function extractLegacyCronInvocation(tail) {
+    for (let index = 0; index < tail.length - 1; index += 1) {
+        if ((tail[index] === "task" || tail[index] === "workflow") && tail[index + 1] === "run") {
+            const publicInvocation = parsePublicSchedulerInvocation(tail.slice(index));
+            if (!publicInvocation)
+                return undefined;
+            return {
+                binding: tail.slice(0, index),
+                contextPath: "",
+                invocation: publicInvocation.invocation,
+                ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
+            };
+        }
+    }
+    return undefined;
 }
 /** Reverse {@link quoteForCron} for a single whitespace-free token. */
 function splitCronShellWords(value) {

package/dist/tasks/resolve-akm-bin.js

@@ -10,7 +10,11 @@
  * Resolution order:
  *
  *   1. `process.execPath` alone for a Bun standalone executable.
- *   2. Absolute Node plus the public `dist/akm` package launcher.
+ *   2. Absolute Node plus the public `dist/akm` package launcher — eligible
+ *      when it is the active npm global install, or when this process
+ *      cannot write to the directory containing it (a read-only mount, e.g.
+ *      an image-baked install, gives the same "won't change out from under
+ *      the scheduler" guarantee npm-global ownership does).
  *   3. Absolute runtime plus the source/build CLI entry, classified as a
  *      checkout that requires explicit `--rebind` for scheduler writes.
  *
@@ -51,12 +55,13 @@ export function resolveAkmInvocation(options = {}) {
             }
         }
         const npmGlobal = !checkout && packageBelongsToNpmGlobalRoot(launcherPath, npmGlobalRoot);
+        const readOnlyInstall = !checkout && !npmGlobal && !(options.isPathWritable ?? isPathWritable)(path.dirname(launcherPath));
         const kind = checkout ? "checkout" : npmGlobal ? "npm" : "package-local";
         return {
             argv: [absoluteInvocationPath(nodePath), absoluteInvocationPath(launcherPath)],
             via: kind,
             kind,
-            eligible: npmGlobal,
+            eligible: npmGlobal || readOnlyInstall,
         };
     }
     const checkoutEntry = resolveCheckoutEntry(options.cliEntryUrl ?? import.meta.url, runtime, mainPath);
@@ -117,6 +122,16 @@ function isCheckoutLauncher(file) {
     const packageRoot = path.dirname(path.dirname(launcher));
     return fs.existsSync(path.join(packageRoot, ".git"));
 }
+/** Whether this process can write to `dir` — false also covers a read-only mount. */
+function isPathWritable(dir) {
+    try {
+        fs.accessSync(dir, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function packageBelongsToNpmGlobalRoot(launcherPath, npmGlobalRoot) {
     if (!npmGlobalRoot)
         return false;

package/dist/tasks/scheduler-invocation.js

@@ -189,7 +189,14 @@ export function parseScheduledBindingArgv(argv) {
         ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
     };
 }
-function parsePublicSchedulerInvocation(invocation) {
+/**
+ * Parse just the public `task run …` / `workflow run …` tail, with no
+ * `--scheduler-context` wrapper. Exported so a backend can recognize a
+ * pre-`--scheduler-context` invocation still sitting inside akm's own
+ * ownership-marked block (see `extractCronInvocation` in
+ * `src/tasks/backends/cron.ts`) without re-implementing this grammar.
+ */
+export function parsePublicSchedulerInvocation(invocation) {
     if (invocation[0] === "task" && invocation[1] === "run" && invocation[2]) {
         try {
             if (normaliseTaskConceptId(invocation[2]) !== invocation[2])

package/dist/tasks/source/parse-task-source.js

@@ -17,7 +17,7 @@
  *   | root `version`        | outcome                                                        |
  *   |------------------------|-----------------------------------------------------------------|
  *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
- *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) — the shim removes friction for the deterministic case, it never hides a real problem |
+ *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape — the file needs a human decision, not a re-run), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED` naming the specific blocked reason (issue #869) — the shim removes friction for the deterministic case, it never hides a real problem |
  *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
  *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
  *
@@ -57,6 +57,18 @@ export function peekTaskSourceVersion(root) {
     return typeof value === "number" ? value : undefined;
 }
 const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
+/**
+ * Thrown only when the deterministic conversion itself could not produce a
+ * task source v4 document — a case where a person must decide the intended
+ * behavior (e.g. an ambiguous shell command), not one the migrator can just
+ * be re-run to fix. `reason`/`detail` are the SAME blocked outcome
+ * `akm migrate status`/`apply` reports for this file, so the message names
+ * the actual decision instead of pointing at a command that will report the
+ * identical block.
+ */
+function unmigratableVersionError(filePath, version, reason, detail) {
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run — the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
+}
 function unsupportedVersionError(filePath, version) {
     return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
 }
@@ -64,9 +76,10 @@ function unsupportedVersionError(filePath, version) {
  * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
  * chained v2->v3->v4) migration planner(s) — never touches disk, never
  * writes the file, never re-reads it from disk. Returns the produced v4
- * YAML text, or `undefined` when the deterministic conversion cannot
- * proceed (an unmigratable v2/v3 shape) — the caller falls back to the same
- * hard error this gate threw before the shim existed.
+ * YAML text, or the blocked reason/detail when the deterministic conversion
+ * cannot proceed (an unmigratable v2/v3 shape) — the caller falls back to
+ * the same hard error this gate threw before the shim existed, now naming
+ * that reason.
  */
 function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
     const bytes = Buffer.from(yaml, "utf8");
@@ -89,12 +102,12 @@ function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
     else {
         const v3Outcome = planTaskToV3File(baseInput);
         if (v3Outcome.status !== "changed")
-            return undefined;
+            return { reason: v3Outcome.reason, detail: v3Outcome.detail };
         v3Bytes = v3Outcome.after;
     }
     const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
     if (v4Outcome.status !== "changed")
-        return undefined;
+        return { reason: v4Outcome.reason, detail: v4Outcome.detail };
     return v4Outcome.after.toString("utf8");
 }
 /** Parse task source YAML, routing per the terminal table above. */
@@ -103,16 +116,17 @@ export function parseTaskSource(input) {
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
         if (version === 2 || version === 3) {
-            const v4Yaml = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-            if (v4Yaml !== undefined) {
+            const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
+            if (typeof shimmed === "string") {
                 const v4 = parseTaskSourceV4({
-                    yaml: v4Yaml,
+                    yaml: shimmed,
                     filePath: input.filePath,
                     ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
                 });
                 warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
                 return Object.freeze({ version: 4, v4 });
             }
+            throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
         }
         throw unsupportedVersionError(input.filePath, version);
     }

package/docs/reference/cli.md

@@ -2032,7 +2032,9 @@ when one exists.
 Scan bundle markdown files for structural issues: unquoted colons, missing
 `updated` field, orphaned stubs, placeholder stubs, missing `name`/`type`,
 stale paths, and broken refs — in body text and in
-`refs`/`xrefs`/`supersededBy`/`contradictedBy` frontmatter. Also reports
+`refs`/`xrefs`/`supersededBy`/`contradictedBy` frontmatter. A belief edge
+pointing at a memory that `akm improve` pruned resolves through the archive
+tombstone under `.akm/memory-cleanup/archive/` and is not reported (#884). Also reports
 `dangerous-env-key` findings for env files (the same key set `akm bundle add`
 enforces — see [Dangerous env key audit](#dangerous-env-key-audit) — but
 non-blocking here; `lint` only warns). `--type workflows` structurally parses
@@ -2046,6 +2048,7 @@ akm lint --fix                  # Auto-fix Tier-1 issues in place
 akm lint --type workflows       # Only lint one asset type
 akm lint --dir ~/other-bundle    # Override the bundle root (default: from config)
 akm lint --fail-on-flagged      # CI-friendly: exit non-zero when summary.flagged > 0
+akm lint --prune-dangling-edges # Opt-in: drop belief edges whose target is gone
 ```
 
 | Flag | Description |
@@ -2054,6 +2057,7 @@ akm lint --fail-on-flagged      # CI-friendly: exit non-zero when summary.flagge
 | `--dir` | Override the bundle root directory (default: from config) |
 | `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`). **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
 | `--fail-on-flagged` | Exit non-zero when `summary.flagged > 0`. Default: exit 0 regardless of findings. |
+| `--prune-dangling-edges` | Opt-in repair (#884): drop `supersededBy`/`contradictedBy` entries whose target has neither a file nor a prune tombstone. **Not** implied by `--fix` — it edits well-formed files to delete a belief-graph claim, so review a plain `akm lint` report first. Clears the same `writable: false` gate `--fix` does. |
 
 Returns `fixed[]` and `flagged[]` arrays plus a `summary: { fixed, flagged }`
 count. Each entry carries `file`, `issue`, `detail`, and whether it was

package/package.json

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