akm-cli 0.9.10 → 0.9.12

package/dist/commands/tasks/validate.js

@@ -0,0 +1,186 @@
+// 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/.
+/**
+ * `akm task validate <path>` (#907) — parse ONE task file by filesystem
+ * path, not a concept ref/id, and report the same diagnostic `akm task
+ * sync` would produce for it. The file need not live in any configured
+ * bundle: unlike every other `akm task` subcommand, this one never resolves
+ * a bundle/adapter/concept id at all — it reads exactly the path it was
+ * given and classifies it.
+ *
+ * Reuses the exact version-routing shim `parseTaskSource`
+ * (`src/tasks/source/parse-task-source.ts`) already applies for every other
+ * task-source reader (`akm task sync`'s `compileTaskSources` included) —
+ * this module never forks a second parser or a second v2/v3 migration
+ * planner. `readBoundedTaskSourceYaml` / `peekTaskSourceVersion` / `own` are
+ * the SAME front-end helpers that shim itself calls first; they are used
+ * here only to recover the file's ORIGINALLY DECLARED schema version for
+ * the report, because `parseTaskSource`'s own `ParsedTaskSource.version` is
+ * always `4` post-shim — it cannot answer "was this a v2/v3/v4 file?" on
+ * its own once a v2/v3 source has been converted in memory.
+ *
+ * Beyond parsing, this module also runs the SAME two per-source gates
+ * `akm task sync`'s `compileTaskSources` runs before it ever installs a
+ * schedule — `assertTaskScheduleInputsSatisfyContract` and
+ * `assertTaskScheduleCronValid` (both extracted from `scheduler-sync.ts` for
+ * exactly this reuse) — so a file `sync` would reject can never
+ * be reported `valid`/`converts` here. Cron dialect is checked against
+ * `backendNameForPlatform()`, the same platform default `sync` falls back
+ * to whenever it has no injected/native-inspected backend to hand (see
+ * `akmTasksAdd`, `src/commands/tasks/tasks.ts`); a bare file was never
+ * installed anywhere; there is no native scheduler state to inspect for it.
+ *
+ * Deliberately DOES NOT call `prepareTaskV3Execution` (the function
+ * `compileTaskSources` calls between those two gates) or resolve an
+ * execution engine: that path resolves a composed command/persona ref
+ * against the local index and lowers the task's cascade-composed
+ * engine/model — both of which assume a real, indexed bundle and a
+ * configured engine. A bare file passed to `validate` has neither, so
+ * running that step would make an otherwise-valid command-kind task report
+ * `invalid` on any machine with no engine configured. `resolved`
+ * is therefore the compiled task shape `sync` itself would build a
+ * scheduler binding from — id, the compiled v4 `version`, `target`
+ * (`uses`/`run`), the declared `inputs` contract, and `schedule` bindings —
+ * never an execution-lowered plan.
+ *
+ * Outcome classification (mirrors `parse-task-source.ts`'s own routing
+ * table in its header, extended for the two gates above):
+ *   - `valid`       — parses as task source v4 directly (declared `version: 4`)
+ *                      and passes both sync gates.
+ *   - `converts`    — declared `version: 2` or `3`; the deterministic
+ *                      in-memory migrator produced a valid v4 document that
+ *                      passes both sync gates.
+ *   - `blocked`     — declared `version: 2` or `3`; the migrator itself
+ *                      could not convert it (an ambiguous/unmigratable
+ *                      shape) — the ONLY way `parseTaskSource` ever throws
+ *                      for those two version numbers, so no message-text
+ *                      sniffing is needed to tell this apart from `invalid`.
+ *   - `invalid`     — the document declares SOME version (`4`, or anything
+ *                      other than 2/3/4) but fails to parse/validate, OR it
+ *                      parsed (directly or via a SUCCESSFUL v2/v3
+ *                      conversion) but fails one of the two sync gates
+ *                      above, OR the YAML itself does not parse at all
+ *                      (a genuine syntax error, not merely a non-task
+ *                      shape) — reported with the parser's own reason.
+ *   - `not-a-task`  — the document parses as YAML but never declares a
+ *                      `version:` field at all (or isn't a YAML mapping) —
+ *                      the strongest signal available that the file was
+ *                      never intended as a task source in the first place.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../../core/errors.js";
+import { backendNameForPlatform } from "../../tasks/backends/index.js";
+import { assertTaskScheduleCronValid, assertTaskScheduleInputsSatisfyContract } from "../../tasks/scheduler-sync.js";
+import { own, readBoundedTaskSourceYaml } from "../../tasks/source/bounded-document.js";
+import { parseTaskSource, peekTaskSourceVersion } from "../../tasks/source/parse-task-source.js";
+/** True when `root` is a YAML mapping that itself declares a `version:` key, regardless of that key's type/value. */
+function declaresVersionKey(root) {
+    return root !== null && typeof root === "object" && !Array.isArray(root) && own(root, "version");
+}
+function buildResolved(id, v4) {
+    return {
+        id,
+        version: v4.version,
+        ...(v4.name !== undefined ? { name: v4.name } : {}),
+        ...(v4.description !== undefined ? { description: v4.description } : {}),
+        target: v4.target,
+        inputs: v4.inputs ?? {},
+        schedule: v4.schedule,
+    };
+}
+export async function akmTaskValidate(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    let stat;
+    try {
+        stat = fs.statSync(resolvedPath);
+    }
+    catch {
+        throw new UsageError(`Task file not found: ${JSON.stringify(filePath)}.`, "INVALID_FLAG_VALUE");
+    }
+    if (!stat.isFile()) {
+        throw new UsageError(`${JSON.stringify(filePath)} is not a regular file.`, "INVALID_FLAG_VALUE");
+    }
+    let yaml;
+    try {
+        yaml = fs.readFileSync(resolvedPath, "utf8");
+    }
+    catch (cause) {
+        throw new UsageError(`Task file ${JSON.stringify(filePath)} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`, "INVALID_FLAG_VALUE");
+    }
+    // Peek the declared version BEFORE the real parse, using the identical
+    // bounded YAML front end `parseTaskSource` calls internally — never a
+    // second/looser YAML reader. A front-end failure here (unparseable YAML,
+    // not a mapping, exceeds a resource bound) means the document itself does
+    // not parse at all — tracked as `peekFailed` so that case reports
+    // `invalid`, never `not-a-task` (`not-a-task` is reserved for
+    // YAML that DOES parse but never declared a task shape). The real parse
+    // below throws the identical error either way, so nothing is lost by
+    // swallowing it here.
+    let root;
+    let peekFailed = false;
+    try {
+        root = readBoundedTaskSourceYaml({ yaml, filePath: resolvedPath }, { sourceLabel: "task source" }).root;
+    }
+    catch {
+        peekFailed = true;
+    }
+    const declaredVersion = peekFailed ? undefined : peekTaskSourceVersion(root);
+    const hasVersionKey = !peekFailed && declaresVersionKey(root);
+    const workspaceRoot = path.dirname(resolvedPath);
+    const backend = backendNameForPlatform();
+    let parsed;
+    try {
+        parsed = parseTaskSource({ yaml, filePath: resolvedPath, workspaceRoot });
+    }
+    catch (cause) {
+        if (!(cause instanceof UsageError))
+            throw cause;
+        const reason = cause.message;
+        // `parseTaskSource` only ever throws for a declared version 2/3 via the
+        // unmigratable-conversion branch (see this file's header) — no separate
+        // message check needed to recognize "blocked" here.
+        if (declaredVersion === 2 || declaredVersion === 3) {
+            return { ok: false, path: resolvedPath, sourceVersion: declaredVersion, outcome: "blocked", reason };
+        }
+        if (peekFailed) {
+            return { ok: false, path: resolvedPath, outcome: "invalid", reason };
+        }
+        if (!hasVersionKey) {
+            return { ok: false, path: resolvedPath, outcome: "not-a-task", reason };
+        }
+        return {
+            ok: false,
+            path: resolvedPath,
+            ...(declaredVersion !== undefined ? { sourceVersion: declaredVersion } : {}),
+            outcome: "invalid",
+            reason,
+        };
+    }
+    // Success is unreachable from any path that leaves `declaredVersion`
+    // undefined — the router requires a numeric 2/3/4 version to reach here.
+    const sourceVersion = declaredVersion ?? 4;
+    // The document itself parsed (directly, or via a successful v2/v3
+    // conversion) — now the two gates `compileTaskSources` runs before
+    // accepting it. A violation here is `invalid`, never `blocked`: the
+    // migrator already succeeded, so this is the same kind of defect a
+    // native v4 document with the identical schedule would have.
+    try {
+        assertTaskScheduleInputsSatisfyContract(parsed.v4, resolvedPath);
+        assertTaskScheduleCronValid(parsed.v4, backend);
+    }
+    catch (cause) {
+        if (!(cause instanceof UsageError))
+            throw cause;
+        return { ok: false, path: resolvedPath, sourceVersion, outcome: "invalid", reason: cause.message };
+    }
+    const id = path.parse(resolvedPath).name;
+    return {
+        ok: true,
+        path: resolvedPath,
+        sourceVersion,
+        outcome: sourceVersion === 2 || sourceVersion === 3 ? "converts" : "valid",
+        resolved: buildResolved(id, parsed.v4),
+    };
+}

package/dist/commands/url-checker.js

@@ -1,34 +1,93 @@
 // 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/.
+import { concurrentMap } from "../core/concurrent.js";
+import { systemErrorCode } from "../core/system-error.js";
 const URL_RE = /https?:\/\/[^\s"'<>)\]]+/g;
+/**
+ * URLs are checked `URL_CHECK_CONCURRENCY` at a time via {@link concurrentMap}
+ * rather than all at once: a knowledge bundle can hold thousands of links, and
+ * firing every HEAD request in one `Promise.allSettled` batch is a
+ * self-inflicted denial-of-service against whatever host happens to be linked
+ * most. Bounding concurrency changes only how fast the check runs, never how
+ * much of it happens — every URL still gets checked.
+ */
+const URL_CHECK_CONCURRENCY = 8;
+/**
+ * Per-HEAD-request timeout, matching the old `TIMEOUT_MS` the caps this
+ * checker replaced used. A dead site rarely refuses cleanly — it hangs — so
+ * without this a handful of unresponsive hosts could stall the whole check
+ * indefinitely instead of the timed-out URLs simply showing up as dead.
+ */
+const DEAD_URL_TIMEOUT_MS = 5000;
+/**
+ * DNS/connection-level codes meaning "this machine could not reach the host
+ * right now" — a corporate DNS block, an offline sandbox, a transient blip —
+ * as opposed to "the resource is gone". Same grouping `classifyVectorFailure`
+ * (indexer/search/db-search.ts) uses for its "connection failed" bucket.
+ * These are counted in `coverage.skipped`, never reported as a `DeadUrl`: an
+ * indeterminate result is not evidence a link is dead.
+ */
+const NETWORK_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+]);
 /**
  * Check every URL in `entries` and report the ones that are dead.
  *
  * No cap, no per-entry slice, no ceiling option. There used to be a
  * `MAX_URLS = 20` plus an undocumented `slice(0, 3)` per entry, so this
  * examined at most twenty links in a bundle holding thousands and reported
- * success. The first attempt at fixing that kept the cap and layered a
- * coverage report, a warning, and an override on top — a constraint plus more
- * code to explain the constraint. Both are gone. It checks what you asked it
- * to check.
+ * success. Both are gone. It checks what you asked it to check, at a bounded
+ * concurrency (see {@link URL_CHECK_CONCURRENCY}) so a large bundle does not
+ * turn into a request flood, and each request is bounded by
+ * {@link DEAD_URL_TIMEOUT_MS} so one unresponsive host cannot stall the rest.
  *
- * A request that fails, times out, or cannot resolve surfaces as a `DeadUrl`
- * rather than being swallowed, so a network problem is visible instead of
- * looking like a clean bill of health.
+ * A `>=400` response or a timeout surfaces as a `DeadUrl` (a timeout as
+ * `status: "timeout"`) rather than being swallowed, so a network problem is
+ * visible instead of looking like a clean bill of health. A DNS/connection
+ * failure (see {@link NETWORK_ERROR_CODES}) is different: it says the check
+ * itself could not run, not that the URL is dead, so it is counted in
+ * `coverage.skipped` instead of either `deadUrls` or a silent success. Any
+ * other thrown error still reports as `status: "error"`. `coverage.checked`
+ * and `coverage.total` are equal only when nothing was skipped this way.
  */
 export async function checkDeadUrls(_stashDir, entries) {
     const urlsToCheck = entries.flatMap((entry) => (entry.body.match(URL_RE) ?? []).map((url) => ({ ref: entry.ref, url })));
-    const results = [];
-    await Promise.allSettled(urlsToCheck.map(async ({ ref, url }) => {
+    const outcomes = await concurrentMap(urlsToCheck, async ({ ref, url }) => {
         try {
-            const res = await fetch(url, { method: "HEAD", redirect: "follow" });
-            if (res.status >= 400)
-                results.push({ ref, url, status: res.status });
+            const res = await fetch(url, {
+                method: "HEAD",
+                redirect: "follow",
+                signal: AbortSignal.timeout(DEAD_URL_TIMEOUT_MS),
+            });
+            return res.status >= 400 ? { dead: { ref, url, status: res.status } } : {};
         }
-        catch {
-            results.push({ ref, url, status: "error" });
+        catch (err) {
+            if (err instanceof DOMException && err.name === "TimeoutError") {
+                return { dead: { ref, url, status: "timeout" } };
+            }
+            const code = systemErrorCode(err);
+            if (code && NETWORK_ERROR_CODES.has(code)) {
+                return { skipped: true };
+            }
+            return { dead: { ref, url, status: "error" } };
         }
-    }));
-    return results;
+    }, URL_CHECK_CONCURRENCY);
+    const deadUrls = [];
+    let skipped = 0;
+    for (const outcome of outcomes) {
+        if (outcome?.dead)
+            deadUrls.push(outcome.dead);
+        if (outcome?.skipped)
+            skipped += 1;
+    }
+    return {
+        deadUrls,
+        coverage: { checked: urlsToCheck.length - skipped, total: urlsToCheck.length, skipped },
+    };
 }

package/dist/commands/workflow-cli.js

@@ -8,14 +8,14 @@
  * GitHub-shaped `.yml` workflow sources. Validate with `akm lint --type workflows`.
  */
 import { getStringArg } from "../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output, outputWithExitCode } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
-import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
+import { abandonWorkflowRun, getWorkflowStatus, listWorkflowRuns, resolveWorkflowRunTarget, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
@@ -34,8 +34,9 @@ const workflowStatusCommand = defineJsonCommand({
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
-        if (await hasWorkflowRun(target)) {
-            const result = await getWorkflowStatus(target, { includeUnits });
+        const resolvedRunId = await resolveWorkflowRunTarget(target);
+        if (resolvedRunId !== undefined) {
+            const result = await getWorkflowStatus(resolvedRunId, { includeUnits });
             output("workflow-status", result);
             return;
         }
@@ -100,12 +101,12 @@ const workflowCreateCommand = defineJsonCommand({
         },
         force: {
             type: "boolean",
-            description: "Overwrite an existing workflow (requires --from or --reset)",
+            description: "Overwrite an existing workflow. Combined with --from, replaces its content; alone, replaces it with a fresh template.",
             default: false,
         },
         reset: {
             type: "boolean",
-            description: "Explicitly replace an existing workflow with a fresh template (use with --force)",
+            description: "Deprecated alias for --force with no --from (replaces an existing workflow with a fresh template).",
             default: false,
         },
         print: {
@@ -130,9 +131,6 @@ const workflowCreateCommand = defineJsonCommand({
             process.stdout.write(getWorkflowTemplate());
             return;
         }
-        if (args.force && !args.from && !args.reset) {
-            throw new UsageError("Refusing to overwrite with template: pass --from <file> to replace content, or --reset to explicitly replace with a fresh template.");
-        }
         const result = createWorkflowAsset({
             name: effectiveName,
             from: args.from,
@@ -157,6 +155,12 @@ const workflowRunCommand = defineJsonCommand({
         "max-steps": { type: "string", description: "Stop after executing this many steps" },
         "max-retries": { type: "string", description: "Retry a failed workflow step this many additional times" },
         timeout: { type: "string", description: "Whole-run timeout: N, Nms, Ns, or Nm (bare N is milliseconds)" },
+        new: {
+            type: "boolean",
+            description: "Start a fresh run even if one is already active for this ref, leaving the existing run untouched " +
+                "(never abandons it). A workflow ref only — passing a run id with --new is a usage error.",
+            default: false,
+        },
     },
     async run({ args, rawArgs }) {
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
@@ -186,6 +190,7 @@ const workflowRunCommand = defineJsonCommand({
                 parameterFlags,
                 ...(maxSteps !== undefined ? { maxSteps } : {}),
                 ...(maxRetries !== undefined ? { maxRetries } : {}),
+                newRun: args.new,
                 signal: controller.signal,
             });
             // The abort is observed between steps, so a deadline landing in the run's
@@ -193,14 +198,11 @@ const workflowRunCommand = defineJsonCommand({
             // timed out would send an operator to resume a run with nothing left to
             // resume — `tasks/runner.ts` suppresses the same case.
             const timedOut = deadline.timedOut() && result.run.status !== "completed";
-            const rendered = { ...result, ...(timedOut ? { timedOut: true } : {}) };
-            output("workflow-run", rendered);
             // `blocked` is a stopped, unverified run — a verification-judge failure
             // leaves it there for `akm workflow resume` — so it must not exit 0 and
             // read as success to a script (it maps to 1 for scheduled tasks too).
-            if (result.run.status === "failed" || result.run.status === "blocked" || result.gateRejection || result.aborted) {
-                process.exitCode = signalExitCode ?? EXIT_CODES.GENERAL;
-            }
+            const failed = result.run.status === "failed" || result.run.status === "blocked" || result.gateRejection || result.aborted;
+            outputWithExitCode("workflow-run", { ...result, ...(timedOut ? { timedOut: true } : {}) }, failed ? (signalExitCode ?? EXIT_CODES.GENERAL) : undefined);
         }
         finally {
             deadline.disarm();
@@ -220,7 +222,7 @@ const WORKFLOW_RUN_VALUE_FLAGS = new Set([
     "shape",
     "output",
 ]);
-const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose"]);
+const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose", "new", "no-new"]);
 export function parseWorkflowParameterFlags(rawArgs, target) {
     const flags = [];
     let targetSeen = false;

package/dist/core/activation-policy.js

@@ -1,20 +1,48 @@
 // 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/.
+/**
+ * `EDITOR`/`VISUAL`/`PAGER` are flagged by `isDangerousEnvKey` for a
+ * documented RCE vector (many tools invoke them to launch an editor/pager),
+ * but env-key-rules.ts's own module doc calls out their "high FP rate" in
+ * the same breath — an installed bundle's env file can supply a value, but
+ * nothing in akm's own env-injection path ever *invokes* EDITOR/VISUAL/PAGER
+ * with that value, so the RCE vector these three describe cannot fire from
+ * an injected env the way LD_PRELOAD or GIT_SSH_COMMAND can. Blocking a
+ * third-party install over them protects nothing while making "the operator
+ * legitimately wants to set their editor" the common case that eats the
+ * refusal. Kept as a name-level literal set (not an import of
+ * `commands/lint/env-key-rules.ts`) so this module stays the pure leaf its
+ * own doc comment promises — no new import edges into the rest of the tree.
+ */
+const INTERACTIVE_TOOL_ENV_KEYS = new Set(["EDITOR", "VISUAL", "PAGER"]);
 /**
  * Decide whether injecting an env with the given dangerous keys is allowed,
- * warned, or blocked. Third-party (registry-installed) stashes hard-block;
- * first-party stashes warn. See rule 1 above.
+ * warned, or blocked. Third-party (registry-installed) stashes hard-block a
+ * genuine RCE-class key; first-party stashes warn. The interactive-tool
+ * group (see {@link INTERACTIVE_TOOL_ENV_KEYS}) only ever warns, since akm's
+ * own env-injection path never invokes those keys as a command. An explicit
+ * `--allow-insecure` (threaded through by the caller, same override
+ * `decideDangerousKeyInstall`'s `"warn-allow"` already honors for rule 2)
+ * downgrades a remaining block to a warning too — the operator is not racing
+ * themselves. See rule 1 above.
  *
  * @param dangerousKeys The subset of injected keys flagged as process-hijacking
  *   (already filtered by the caller via `isDangerousEnvKey`).
  * @param thirdParty `true` when the env's source is a third-party stash — i.e.
  *   its origin carries a `registryId`.
+ * @param allowInsecure `true` when the operator passed `--allow-insecure` (or
+ *   its equivalent) for this injection. Defaults to `false`.
  */
 export function decideDangerousEnvInjection(input) {
     if (input.dangerousKeys.length === 0)
         return "allow";
-    return input.thirdParty ? "block" : "warn";
+    if (!input.thirdParty)
+        return "warn";
+    if (input.allowInsecure)
+        return "warn";
+    const onlyInteractiveTool = input.dangerousKeys.every((key) => INTERACTIVE_TOOL_ENV_KEYS.has(key));
+    return onlyInteractiveTool ? "warn" : "block";
 }
 /**
  * Decide the baseline install stance for a freshly-installed stash's

package/dist/core/adapter/execution-source.js

@@ -6,6 +6,8 @@ import { isMap, isScalar, parseDocument, visit } from "yaml";
 import { cloneExecutionJson, cloneExecutionJsonObject, } from "../../execution/json.js";
 import { assertSnapshotKeys, snapshotStrictRecord } from "../../execution/record.js";
 import { cloneToolSelection, createAdapterRenderedExecutionSource, } from "../../execution/source.js";
+import { UsageError } from "../errors.js";
+import { warnOnce } from "../warn.js";
 function nextLine(text, start) {
     const lf = text.indexOf("\n", start);
     if (lf < 0)
@@ -13,16 +15,39 @@ function nextLine(text, start) {
     const end = lf > start && text[lf - 1] === "\r" ? lf - 1 : lf;
     return { line: text.slice(start, end), next: lf + 1 };
 }
-/** Strict execution-only frontmatter parser; indexing's tolerant parser is deliberately not reused. */
-export function parseExecutionMarkdown(raw) {
+/**
+ * Strict execution-only frontmatter parser; indexing's tolerant parser is
+ * deliberately not reused.
+ *
+ * `filePath`, when given, names the offending asset in a thrown error so an
+ * operator (or CI) sees which file to fix instead of a bare message.
+ *
+ * A third party's markdown that genuinely cannot be parsed into a mapping
+ * (unterminated frontmatter, broken YAML syntax, a non-mapping document)
+ * throws {@link UsageError} \u2014 exit 2, an actionable usage problem, not exit
+ * 70 (`TypeError`'s "unclassified internal error" code, which is what a
+ * `throw new TypeError(...)` here used to surface as). Anchors, explicit
+ * tags, and non-string mapping keys are recognized-but-unsupported
+ * constructs rather than parse failures on their own \u2014 an anchor nobody
+ * aliases, or a tag `toJS` converts to a plain value, is harmless \u2014 so they
+ * warn once (naming the file) and fall through to conversion instead of
+ * being pre-emptively rejected by a second, stricter gate in front of it.
+ * `toJS({ maxAliasCount: 0 })` is the real, UNCHANGED safety bound against
+ * alias-expansion abuse \u2014 it disables alias RESOLUTION outright, so a value
+ * that actually references an anchor via `*name` still fails, now as a
+ * {@link UsageError} from this same conversion step rather than the removed
+ * duplicate pre-check.
+ */
+export function parseExecutionMarkdown(raw, filePath) {
     if (typeof raw !== "string")
         throw new TypeError("execution source raw content must be a string");
+    const where = filePath ? ` (${filePath})` : "";
     const withoutBom = raw.startsWith("\uFEFF") ? raw.slice(1) : raw;
     const opening = nextLine(withoutBom, 0);
     if (opening.line !== "---")
         return { content: withoutBom, data: Object.freeze({}) };
     if (opening.next === withoutBom.length) {
-        throw new TypeError("execution source has unterminated frontmatter");
+        throw new UsageError(`execution source${where} has unterminated frontmatter`);
     }
     let cursor = opening.next;
     let frontmatterEnd = -1;
@@ -40,18 +65,18 @@ export function parseExecutionMarkdown(raw) {
         cursor = current.next;
     }
     if (frontmatterEnd < 0 || bodyStart < 0) {
-        throw new TypeError("execution source has unterminated frontmatter");
+        throw new UsageError(`execution source${where} has unterminated frontmatter`);
     }
     const yaml = withoutBom.slice(opening.next, frontmatterEnd);
     const document = parseDocument(yaml, { uniqueKeys: true });
     if (document.errors.length > 0) {
-        throw new TypeError(`execution source has invalid YAML frontmatter: ${document.errors[0]?.message ?? "parse error"}`);
+        throw new UsageError(`execution source${where} has invalid YAML frontmatter: ${document.errors[0]?.message ?? "parse error"}`);
     }
     if (document.warnings.length > 0) {
-        throw new TypeError(`execution source YAML frontmatter uses an unsupported tag or construct: ${document.warnings[0]?.message}`);
+        warnOnce(`execution-source:yaml-warning:${filePath ?? "<inline>"}`, `execution source${where} YAML frontmatter uses an unsupported tag or construct: ${document.warnings[0]?.message}. Using it as parsed.`);
     }
     if (!isMap(document.contents)) {
-        throw new TypeError("execution source YAML frontmatter must be a mapping");
+        throw new UsageError(`execution source${where} YAML frontmatter must be a mapping`);
     }
     let unsupported;
     visit(document, {
@@ -69,14 +94,16 @@ export function parseExecutionMarkdown(raw) {
                 unsupported ??= "non-string mapping keys";
         },
     });
-    if (unsupported)
-        throw new TypeError(`execution source YAML frontmatter does not support ${unsupported}`);
+    if (unsupported) {
+        warnOnce(`execution-source:unsupported:${filePath ?? "<inline>"}`, `execution source${where} YAML frontmatter uses ${unsupported}, which akm does not fully support; using the bounded conversion's result as-is.`);
+    }
     let root;
     try {
         root = document.toJS({ maxAliasCount: 0 });
     }
     catch (cause) {
-        throw new TypeError("execution source YAML frontmatter could not be converted safely", { cause });
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new UsageError(`execution source${where} YAML frontmatter could not be converted safely: ${detail}`);
     }
     const data = cloneExecutionJsonObject(root, "execution source YAML frontmatter");
     return { content: withoutBom.slice(bodyStart), data: Object.freeze(data) };
@@ -279,7 +306,8 @@ export function renderMarkdownExecutionSource(input) {
     const kind = snapshots.input.kind;
     if (kind !== "command" && kind !== "persona")
         throw new TypeError("adapter execution source.kind is invalid");
-    const parsed = parseExecutionMarkdown(raw);
+    const identityFile = snapshots.identity.file;
+    const parsed = parseExecutionMarkdown(raw, typeof identityFile === "string" ? identityFile : undefined);
     const hasDefaults = Object.hasOwn(snapshots.input, "defaults");
     const defaultsProjection = snapshots.input.defaults;
     const defaults = typeof defaultsProjection === "function" ? defaultsProjection(parsed.data) : defaultsProjection;

package/dist/core/asset/stash-meta.js

@@ -18,6 +18,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isWithin } from "../common.js";
 import { UsageError } from "../errors.js";
 /** Root-relative directory holding a stash's meta docs. */
 export const META_DIR = ".meta";
@@ -113,7 +114,7 @@ export function readMetaFile(sourceRoot, name) {
         return null;
     let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY);
         const opened = fs.fstatSync(fd);
         if (!opened.isFile())
             throw metaPathEscape();
@@ -141,60 +142,25 @@ export function readMetaFile(sourceRoot, name) {
     }
 }
 function isSafeRegularMetaFile(sourceRoot, metaRoot, filePath) {
-    const sourceRootReal = realPathOrNull(sourceRoot);
-    if (!sourceRootReal)
-        return false;
-    const metaStat = lstatOrNull(metaRoot);
-    if (!metaStat)
-        return false;
-    if (metaStat.isSymbolicLink())
-        throw metaPathEscape();
-    if (!metaStat.isDirectory())
-        return false;
     const relative = path.relative(metaRoot, filePath);
     if (relative === "" || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
         throw metaPathEscape();
     }
-    let current = metaRoot;
-    for (const segment of relative.split(path.sep)) {
-        current = path.join(current, segment);
-        const stat = lstatOrNull(current);
-        if (!stat)
-            return false;
-        if (stat.isSymbolicLink())
-            throw metaPathEscape();
-    }
-    const finalStat = lstatOrNull(filePath);
+    const finalStat = statOrNull(filePath);
     if (!finalStat?.isFile())
         return false;
-    const metaRootReal = realPathOrNull(metaRoot);
-    const fileReal = realPathOrNull(filePath);
-    if (!metaRootReal || !fileReal)
-        return false;
-    if (!isWithin(sourceRootReal, metaRootReal) || !isWithin(metaRootReal, fileReal))
+    if (!isWithin(filePath, sourceRoot))
         throw metaPathEscape();
     return true;
 }
-function lstatOrNull(filePath) {
+function statOrNull(filePath) {
     try {
-        return fs.lstatSync(filePath);
+        return fs.statSync(filePath);
     }
     catch {
         return null;
     }
 }
-function realPathOrNull(filePath) {
-    try {
-        return fs.realpathSync(filePath);
-    }
-    catch {
-        return null;
-    }
-}
-function isWithin(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-}
 function metaPathEscape() {
-    return new UsageError("Meta doc must be a regular file inside the stash .meta directory; symlinks are refused.", "PATH_ESCAPE_VIOLATION");
+    return new UsageError("Meta doc must resolve to a regular file inside the stash .meta directory, not one that escapes it.", "PATH_ESCAPE_VIOLATION");
 }

package/dist/core/bundle-id.js

@@ -46,6 +46,12 @@ function ensureUniqueId(preferred, sourcePath, used) {
         n++;
     return `${suffixed}-${n}`;
 }
-function shortHash(input) {
+/**
+ * First 8 hex chars of `input`'s sha256 — deterministic and short enough to
+ * suffix a slug or a path key. Exported so callers needing the same
+ * short-hash-of-a-resolved-path primitive (e.g. `getStashStateKey` in
+ * `paths.ts`) don't grow their own duplicate.
+ */
+export function shortHash(input) {
     return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
 }