akm-cli 0.9.11 → 0.9.13

package/dist/commands/read/show.js

@@ -31,7 +31,7 @@ import { NotFoundError, rethrowIfDataDirUnreadable, rethrowIfTestIsolationError,
 import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnOnce } from "../../core/warn.js";
 import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
@@ -71,12 +71,11 @@ export async function akmShowUnified(input) {
         if (metaRef)
             return showStashMeta(metaRef);
     }
-    // Env/secret bodies have no safe fragment surface. Reject from the canonical
-    // ref namespace before auto-index or lookup can touch authored bytes. This is
-    // deliberately independent of on-disk suffix probing: secret filenames keep
-    // their natural extension, and a misspelled extensionless ref must not move
-    // the sensitive-fragment policy behind a not-found result.
-    assertSensitiveFragmentUnsupported(parseBundleRef(ref));
+    // Env/secret bodies have no safe fragment surface, and a fragment cannot
+    // widen what the env/secret renderers expose: both always omit the body
+    // (env — key names only; secret — never rendered), fragment or not. Warn
+    // and ignore the fragment rather than refusing the whole show.
+    warnSensitiveFragmentUnsupported(parseBundleRef(ref));
     // Auto-index when stale so the index is current before lookup.
     const { primarySource } = resolveReadSources();
     await ensurePrimaryIndexForRead(primarySource);
@@ -177,7 +176,7 @@ function enforceScopeOrThrow(filePath, ref, scope) {
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
     const parsed = parseBundleRef(input.ref);
-    assertSensitiveFragmentUnsupported(parsed);
+    warnSensitiveFragmentUnsupported(parsed);
     const assetParts = typeNameFromConceptId(parsed.conceptId);
     const config = loadConfig();
     const allSources = resolveSourceEntries(input.stashDir);
@@ -194,12 +193,19 @@ export async function showLocal(input) {
             `Stash "${parsed.bundle}" is not installed. Run: ${installCmd}`);
     }
     if (!indexedEntry && !resolution.owner) {
-        const unsupportedExtension = existingUnsupportedScriptExtension(assetParts, searchSources);
-        if (unsupportedExtension !== undefined) {
-            const displayExtension = unsupportedExtension || "no extension";
-            throw new NotFoundError(`Script ref "${makeBundleRef(parsed.bundle, parsed.conceptId)}" resolves to an existing file with ` +
-                `unsupported extension "${displayExtension}". Script refs must use a supported script extension: ` +
-                `${[...SCRIPT_EXTENSIONS].join(", ")}.`, "ASSET_NOT_FOUND");
+        const unrecognized = findUnrecognizedScriptSource(assetParts, searchSources);
+        if (unrecognized) {
+            const displayExtension = unrecognized.extension || "no extension";
+            warn(`Script ref "${makeBundleRef(parsed.bundle, parsed.conceptId)}" has extension "${displayExtension}", which is outside the recognized set used for indexing (${[...SCRIPT_EXTENSIONS].join(", ")}); showing it as plain text.`);
+            const fileCtx = buildFileContext(unrecognized.sourceRoot, unrecognized.path);
+            const renderer = await getRenderer("script-source");
+            if (renderer) {
+                const match = { type: "script", specificity: 0, renderer: "script-source" };
+                const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs);
+                const response = renderer.buildShowResponse(renderCtx);
+                response.name = assetParts?.name ?? response.name;
+                return response;
+            }
         }
     }
     if (!indexedEntry || !assetPath) {
@@ -242,9 +248,11 @@ export async function showLocal(input) {
             response = renderer.buildShowResponse(renderCtx);
             if (parsed.fragment !== undefined) {
                 if (!match.renderer.endsWith("-md")) {
-                    throw new UsageError(`Fragments are not supported for ${makeBundleRef(parsed.bundle, parsed.conceptId)}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+                    warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
+                }
+                else {
+                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName);
                 }
-                applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName);
             }
         }
     }
@@ -318,22 +326,22 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
-/** Reject body fragments for namespaces whose authored bytes are sensitive. */
-function assertSensitiveFragmentUnsupported(ref) {
+/**
+ * Warn and ignore body fragments for namespaces whose authored bytes are
+ * sensitive. `warnOnce`-keyed on the exact ref: `akmShowUnified` calls this
+ * before delegating to `showLocal`, which calls it again as its own
+ * defense-in-depth for callers that use `showLocal` directly — a single
+ * request must not print the same warning twice.
+ */
+function warnSensitiveFragmentUnsupported(ref) {
     if (ref.fragment === undefined)
         return;
     const type = typeNameFromConceptId(ref.conceptId)?.type;
     if (type !== "env" && type !== "secret")
         return;
-    throw new UsageError(`Fragments are not supported for ${makeBundleRef(ref.bundle, ref.conceptId)}. Sensitive ${type} assets do not expose body fragments.`, "INVALID_FLAG_VALUE");
+    warnOnce(`sensitive-fragment:${makeBundleRef(ref.bundle, ref.conceptId)}#${ref.fragment}`, `Fragment "#${ref.fragment}" was ignored: sensitive ${type} assets do not expose body fragments. Showing ${makeBundleRef(ref.bundle, ref.conceptId)} in full.`);
 }
-/**
- * Return the unsupported extension only when the exact canonical AKM script
- * path exists as a contained regular file. Physical owner arbitration runs
- * first; this is a diagnostic for its miss, never an alternate owner or
- * runnable-file classifier. No authored bytes are read.
- */
-function existingUnsupportedScriptExtension(assetParts, sources) {
+function findUnrecognizedScriptSource(assetParts, sources) {
     if (assetParts?.type !== "script")
         return undefined;
     const extension = path.extname(assetParts.name);
@@ -357,7 +365,7 @@ function existingUnsupportedScriptExtension(assetParts, sources) {
             const realCandidate = fs.realpathSync(candidate);
             if (!isWithin(realCandidate, realRoot) || !fs.statSync(realCandidate).isFile())
                 continue;
-            return extension;
+            return { extension, path: realCandidate, sourceRoot: realRoot };
         }
         catch {
             // Missing, unreadable, dangling, or otherwise unsafe paths remain normal
@@ -447,7 +455,7 @@ async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
 export async function showByRef(ref) {
     const parsed = parseBundleRef(ref);
     if (parsed.fragment !== undefined) {
-        throw new UsageError(`Fragments are not accepted by raw show: ${ref}`, "INVALID_FLAG_VALUE");
+        warn(`Fragment "#${parsed.fragment}" was ignored by raw show: ${ref}. Returning the whole file.`);
     }
     const entry = await lookupBundleRef(parsed);
     if (!entry) {
@@ -488,12 +496,15 @@ function indexedMatch(entry, renderer) {
     return { type: entry.type, specificity: Number.MAX_SAFE_INTEGER, renderer, meta: { name: entry.name } };
 }
 function buildIndexedProjectionResponse(entry, assetPath, fragment) {
-    if (fragment !== undefined && path.extname(assetPath).toLowerCase() !== ".md") {
-        throw new UsageError(`Fragments are not supported for ${entry.conceptId}. Only Markdown documents support heading fragments.`, "INVALID_FLAG_VALUE");
+    const isMarkdown = path.extname(assetPath).toLowerCase() === ".md";
+    if (fragment !== undefined && !isMarkdown) {
+        warn(`Fragment "#${fragment}" was ignored: ${entry.conceptId} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
     }
     const raw = fs.readFileSync(assetPath, "utf8");
     const parsed = parseFrontmatter(raw);
-    const content = fragment ? requireMarkdownSection(parsed.content, fragment, entry.name).content : parsed.content;
+    const content = fragment !== undefined && isMarkdown
+        ? requireMarkdownSection(parsed.content, fragment, entry.name).content
+        : parsed.content;
     const description = entry.document?.description ?? asNonEmptyString(parsed.data.description);
     const tags = entry.document?.tags ??
         (Array.isArray(parsed.data.tags)

package/dist/commands/registry-cli.js

@@ -4,7 +4,7 @@
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { getEffectiveRegistries, loadUserConfig, mutateConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
-import { formatRegistryUrl, hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED, registryEntryForOutput, } from "../core/registry-url.js";
+import { formatRegistryLabel, formatRegistryUrl, hasRegistryUrlCredentials, registryEntryForOutput, } from "../core/registry-url.js";
 import { warn } from "../core/warn.js";
 export const registryCommand = defineGroupCommand({
     meta: { name: "registry", description: "Manage bundle registries" },
@@ -33,7 +33,9 @@ export const registryCommand = defineGroupCommand({
             },
             async run({ args }) {
                 if (hasRegistryUrlCredentials(args.url)) {
-                    throw new UsageError(REGISTRY_CREDENTIALS_UNSUPPORTED);
+                    warn(`Registry ${formatRegistryLabel({ url: args.url, name: args.name })} was added, but its URL's ` +
+                        "username/password is ignored: authenticated registries are not supported by the built-in " +
+                        "static-index or skills-sh providers.");
                 }
                 if (!args.url.startsWith("http")) {
                     throw new UsageError("Registry URL must start with http:// or https://");

package/dist/commands/sources/init.js

@@ -12,8 +12,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { stashDirNames } from "../../core/asset/asset-placement.js";
 import { mutateConfig } from "../../core/config/config.js";
-import { ConfigError } from "../../core/errors.js";
 import { assertSafeStashDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
+import { warnOnce } from "../../core/warn.js";
 import { primaryBundlePath, withPrimaryBundle } from "./bundle-config-ops.js";
 import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./stash-skeleton.js";
 /**
@@ -37,11 +37,9 @@ import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./st
 function assertInitSandbox(stashDir, dirExplicitlyProvided) {
     if (!dirExplicitlyProvided)
         return; // Only guard explicit --dir, not default HOME resolution.
-    const isUnderTest = isUnderTestRunner();
+    const isUnderTest = process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
     if (!isUnderTest)
         return;
-    if (process.env.AKM_FORCE_INIT_TMP_STASH === "1")
-        return;
     const isTmp = stashDir.startsWith("/tmp/") ||
         stashDir === "/tmp" ||
         stashDir.startsWith("/var/tmp/") ||
@@ -50,10 +48,8 @@ function assertInitSandbox(stashDir, dirExplicitlyProvided) {
         stashDir.startsWith("/private/tmp/");
     if (!isTmp)
         return;
-    throw new ConfigError(`refusing to persist --dir stashDir to a temporary path while under test runner; set AKM_FORCE_INIT_TMP_STASH=1 if you really mean it (stashDir=${stashDir})`, "INIT_TMP_STASH_REFUSED");
-}
-function isUnderTestRunner() {
-    return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+    warnOnce(`init-tmp-stash:${stashDir}`, `Persisting --dir stashDir to a temporary path (${stashDir}) while a test-runner env var (BUN_TEST/NODE_ENV=test) is set; ` +
+        "the OS may reap this path, leaving the next run pointing at a deleted bundle.");
 }
 // ── Test seam ────────────────────────────────────────────────────────────────
 // Swap-and-restore override. Inert in production; only tests call the setter.

package/dist/commands/sources/self-update.js

@@ -346,8 +346,8 @@ export async function performUpgrade(check, opts, dependencies) {
         }
     }
     if (fs.existsSync(backupPath)) {
-        removeFileBestEffort(stagedPath);
-        throw new ConfigError(`Refusing to overwrite retained previous binary at ${backupPath}.`, "UPGRADE_BLOCKED");
+        warn(`A previous upgrade left a stale backup at ${backupPath}; overwriting it.`);
+        removeFileBestEffort(backupPath);
     }
     try {
         if (IS_WINDOWS)

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

@@ -7,6 +7,7 @@ import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { isBundleSlug } from "../../core/asset/asset-ref.js";
 import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
+import { isWithin } 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";
@@ -224,18 +225,15 @@ function lstatIfExists(filePath) {
 }
 function assertNoDestinationSymlinkParent(root, destination) {
     const resolvedRoot = path.resolve(root);
-    const relativeParent = path.relative(resolvedRoot, path.dirname(path.resolve(destination)));
+    const parentDir = path.dirname(path.resolve(destination));
+    const relativeParent = path.relative(resolvedRoot, parentDir);
     if (relativeParent === "" || relativeParent === ".")
         return;
     if (relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) {
         throw new UsageError(`Clone destination escapes the selected target: ${destination}.`, "PATH_ESCAPE_VIOLATION");
     }
-    let current = resolvedRoot;
-    for (const segment of relativeParent.split(path.sep)) {
-        current = path.join(current, segment);
-        if (lstatIfExists(current)?.isSymbolicLink()) {
-            throw new UsageError(`Clone destination has a symbolic-link parent outside the selected target boundary: ${current}.`, "PATH_ESCAPE_VIOLATION");
-        }
+    if (!isWithin(parentDir, resolvedRoot)) {
+        throw new UsageError(`Clone destination has a symbolic-link parent outside the selected target boundary: ${parentDir}.`, "PATH_ESCAPE_VIOLATION");
     }
 }
 function listTreeFiles(root) {

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

@@ -27,7 +27,7 @@
  */
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, outputWithExitCode, runWithJsonErrors, } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
@@ -54,12 +54,10 @@ export const upgradeCommand = defineJsonCommand({
         }
         const skipPostUpgrade = args["skip-post-upgrade"];
         const result = await performUpgrade(check, { force: args.force, skipPostUpgrade });
-        output("upgrade", result);
         // The install may have succeeded, but an upgrade whose migration is
         // blocked or could not run is not done: exit like `akm migrate apply` does.
-        if (result.migration?.status === "blocked" || result.migration?.status === "failed") {
-            process.exitCode = EXIT_CODES.GENERAL;
-        }
+        const migrationFailed = result.migration?.status === "blocked" || result.migration?.status === "failed";
+        outputWithExitCode("upgrade", result, migrationFailed ? EXIT_CODES.GENERAL : undefined);
     },
 });
 // `sync` body, standalone so the git-commit/push logic stays in one place.

package/dist/commands/tasks/tasks-cli.js

@@ -27,7 +27,7 @@
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, } from "../../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, outputWithExitCode, runWithJsonErrors, } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
 import { akmTaskExplain } from "./explain.js";
@@ -356,21 +356,16 @@ const tasksSyncCommand = defineJsonCommand({
         const rebind = args.rebind === true;
         if (args["dry-run"] === true) {
             const preview = await akmTasksSyncPlan({}, args.bundle, { rebind });
-            output("task-sync-dry-run", preview);
-            const exitCode = taskSyncDryRunExitCode(preview);
-            if (exitCode !== undefined)
-                process.exitCode = exitCode;
+            outputWithExitCode("task-sync-dry-run", preview, taskSyncDryRunExitCode(preview));
             return;
         }
         const result = await akmTasksSync({}, args.bundle, { rebind });
-        output("task-sync", result);
         // #867: sync degrades — sources that failed to parse/prepare are
         // excluded from reconciliation and reported in `result.failures` rather
         // than poisoning the whole sync, but their presence must still fail
         // the command's exit code so the breakage stays visible. (#906: this key
         // matches the `--dry-run` preview's `failures` field — no separate name.)
-        if (result.failures.length > 0)
-            process.exitCode = EXIT_CODES.GENERAL;
+        outputWithExitCode("task-sync", result, result.failures.length > 0 ? EXIT_CODES.GENERAL : undefined);
     },
 });
 // ── `akm task explain` — read-only introspection (P2b Lane B, spec
@@ -482,10 +477,7 @@ const tasksPruneCommand = defineJsonCommand({
                 .filter(Boolean)
             : undefined;
         const result = await akmTasksPrune({}, { yes: args.yes === true, id });
-        output("task-prune", result);
-        const exitCode = taskPruneExitCode(result);
-        if (exitCode !== undefined)
-            process.exitCode = exitCode;
+        outputWithExitCode("task-prune", result, taskPruneExitCode(result));
     },
 });
 export const taskCommand = defineGroupCommand({

package/dist/commands/tasks/tasks.js

@@ -22,6 +22,7 @@ import { resolveConfiguredSources } from "../../core/config/config-sources.js";
 import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../core/config/experimental.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
@@ -391,7 +392,7 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
     const expectedSignature = sched.expectedSignature?.bind(sched);
     const needsRuntime = preflight.operations.some((operation) => operation.kind !== "remove" && operation.options?.binding === undefined);
     const prepared = needsRuntime
-        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, options.rebind === true, "reconcile native scheduler bindings", warnings, allEntries.map((entry) => entry.binding))
+        ? prepareSchedulerSyncRuntime(syncTarget ? { target: syncTarget } : undefined, deps, warnings, allEntries.map((entry) => entry.binding))
         : undefined;
     const plan = finalizeSchedulerSyncPlan({
         ...common,
@@ -768,22 +769,24 @@ async function prepareTaskAddSchedulerTransaction(input) {
                 contextPath: installedEntry.contextPath,
             },
         }
-        : prepareSchedulerSyncRuntime(input.installOpts, input.deps, input.rebind, `create scheduler entry for task "${input.id}"`, []);
+        : prepareSchedulerSyncRuntime(input.installOpts, input.deps, []);
     const runtimeOpts = preparedRuntime.options;
     const removals = taskEntries.map((entry) => {
         const invocation = entry.invocation;
-        if (!invocation) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact parsed owner; refusing replacement.`, "RESOURCE_ALREADY_EXISTS");
-        }
         const nativeId = entry.nativeId ?? schedulerNativeBindingId(entry.id);
         const artifact = assertSchedulerNativeArtifactCardinality(nativeArtifacts, nativeId, 1);
         if (!artifact?.fingerprint || artifact.bindingId !== entry.id) {
             throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact coherent fingerprint.`, "RESOURCE_ALREADY_EXISTS");
         }
         const logicalSource = primary.logicalSource;
-        const ordinal = schedulerBindingOrdinal(entry.id, logicalSource, invocation);
-        if (ordinal === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(entry.id)} has no exact schedule ordinal; refusing replacement.`, "RESOURCE_ALREADY_EXISTS");
+        const ordinal = invocation ? schedulerBindingOrdinal(entry.id, logicalSource, invocation) : undefined;
+        if (!invocation || ordinal === undefined) {
+            warn(`Installed scheduler binding ${JSON.stringify(entry.id)} (native id ${JSON.stringify(nativeId)}) could not be exactly parsed — likely a hand-edited entry; replacing it without a compare-and-swap guard.`);
+            return Object.freeze({
+                kind: "remove",
+                id: entry.id,
+                nativeId,
+            });
         }
         return Object.freeze({
             kind: "remove",
@@ -824,6 +827,8 @@ async function prepareTaskAddSchedulerTransaction(input) {
     for (const removal of removals) {
         if (removal.kind !== "remove")
             continue;
+        if (!removal.expected)
+            continue;
         initialByKey.set(schedulerNativeArtifactKey(removal.nativeId), Object.freeze({ ...removal.expected, state: "present" }));
     }
     for (const install of installs) {
@@ -841,16 +846,16 @@ async function prepareTaskAddSchedulerTransaction(input) {
         publishOperationIndex: removals.length,
     });
 }
-function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warnings, installedBindings = []) {
+function prepareSchedulerSyncRuntime(base, deps, warnings, installedBindings = []) {
     if (deps.backend && !deps.schedulerRuntime)
         return base ? { options: base } : {};
     if (deps.schedulerRuntime) {
         const runtime = deps.schedulerRuntime();
-        warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings);
+        warnIneligibleRebind(runtime, warnings, installedBindings);
         return { options: { ...base, binding: runtime.binding, contextPath: runtime.contextPath } };
     }
-    const invocation = resolveAndValidateSchedulerInvocation(explicitRebind, operation);
-    warnIneligibleRebind(invocation, explicitRebind, warnings, installedBindings);
+    const invocation = resolveAndValidateSchedulerInvocation();
+    warnIneligibleRebind(invocation, warnings, installedBindings);
     const descriptor = schedulerContextDescriptor();
     const contextPath = schedulerContextPath(descriptor);
     return {
@@ -863,24 +868,21 @@ function prepareSchedulerSyncRuntime(base, deps, explicitRebind, operation, warn
         },
     };
 }
-function resolveAndValidateSchedulerInvocation(explicitRebind, operation) {
+function resolveAndValidateSchedulerInvocation() {
     const invocation = resolveAkmInvocation();
-    if (!invocation.eligible && !explicitRebind) {
-        throw new UsageError(`Refusing to ${operation} from an ineligible ${invocation.kind ?? "unknown"} invocation (${invocation.argv.join(" ")}).`, "INVALID_FLAG_VALUE", "npm-global ownership could not be verified. Run `npm install --global akm-cli` and use that launcher, use a standalone installation, or explicitly repeat the operation with --rebind.");
-    }
     return { binding: invocation.argv, contextPath: "", eligible: invocation.eligible, kind: invocation.kind };
 }
-function warnIneligibleRebind(runtime, explicitRebind, warnings, installedBindings) {
-    if (!explicitRebind || runtime.eligible !== false || warnings.length > 0)
+function warnIneligibleRebind(runtime, warnings, installedBindings) {
+    if (runtime.eligible !== false || warnings.length > 0)
         return;
-    // #868 residue: a `--rebind` that binds every currently-installed
-    // entry to the SAME invocation it already carries changes nothing — this
-    // is the steady state of an image-baked install re-running `task sync
-    // --rebind` on a timer. Only warn when the rebind actually moves an entry
-    // to a different invocation.
+    // #868 residue: binding every currently-installed entry to the SAME
+    // invocation it already carries changes nothing — this is the steady
+    // state of an image-baked install re-running `task sync` on a timer.
+    // Only warn when the bind actually moves an entry to a different
+    // invocation.
     if (installedBindings.length > 0 && installedBindings.every((bound) => sameArgv(bound, runtime.binding)))
         return;
-    warnings.push(`--rebind bound scheduled tasks to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
+    warnings.push(`Scheduled tasks are bound to an ineligible ${runtime.kind ?? "unknown"} invocation (${runtime.binding.join(" ")}); scheduled runs will invoke a mutable, unproven binary. Install akm via \`npm install --global akm-cli\` or a standalone release, then re-run \`akm task sync --rebind\`.`);
 }
 function groupInstalledBindings(entries, invocation) {
     const groups = new Map();
@@ -972,16 +974,20 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
     const common = { filePath, rootRealPath };
     let descriptor;
     try {
-        const noFollow = "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
-        descriptor = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow);
-        const before = fs.fstatSync(descriptor, { bigint: true });
+        descriptor = fs.openSync(filePath, fs.constants.O_RDONLY);
+        let before = fs.fstatSync(descriptor, { bigint: true });
         if (!before.isFile()) {
             throw new UsageError(`${filePath} is not a regular task source.`, "INVALID_FLAG_VALUE");
         }
-        const bytes = fs.readFileSync(descriptor);
-        const after = fs.fstatSync(descriptor, { bigint: true });
-        if (!sameTaskSourceStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
-            throw new UsageError(`${filePath} changed while its guarded bytes were read.`, "RESOURCE_ALREADY_EXISTS");
+        let bytes = fs.readFileSync(descriptor);
+        const torn = !sameTaskSourceStat(before, fs.fstatSync(descriptor, { bigint: true })) ||
+            BigInt(bytes.byteLength) !== before.size;
+        if (torn) {
+            fs.closeSync(descriptor);
+            descriptor = fs.openSync(filePath, fs.constants.O_RDONLY);
+            before = fs.fstatSync(descriptor, { bigint: true });
+            bytes = fs.readFileSync(descriptor);
+            warn(`${filePath} changed while its guarded bytes were read; retried once and proceeding with the latest read (its SHA-256 is re-verified before anything is published).`);
         }
         const realPath = fs.realpathSync(filePath);
         const physicalRelative = path.relative(rootRealPath, realPath);
@@ -1011,9 +1017,6 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
         }
         if (cause instanceof UsageError)
             throw cause;
-        if (cause.code === "ELOOP") {
-            throw new UsageError(`${filePath} must not be a symbolic task source.`, "RESOURCE_ALREADY_EXISTS");
-        }
         throw new UsageError(`${filePath} could not be guarded as a contained regular task source: ${errorMessage(cause)}`, "PATH_ESCAPE_VIOLATION");
     }
     finally {
@@ -1264,7 +1267,7 @@ function assertInlineTaskPrompt(input) {
         (!/\s/.test(value) && /[\\/]/.test(value) && path.extname(value) !== "");
     if (!isFullRefInput(value) && !pathShaped)
         return;
-    throw new UsageError("--prompt accepts inline text only; asset refs and file paths are not prompt content. Use --workflow or an authored command ref where appropriate.", "INVALID_FLAG_VALUE");
+    warn(`--prompt "${input}" looks like an asset ref or file path; --prompt sends it as literal text, not a reference. Did you mean --workflow?`);
 }
 function parseJsonObjectArg(raw) {
     let parsed;

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