akm-cli 0.9.10 → 0.9.12

package/dist/commands/proposal/validators/proposals.js

@@ -26,14 +26,18 @@ export function validateProposal(proposal) {
  * structure and applies {@link repairTruncatedDescription} to a truncated
  * description when one is detected.
  *
- * Repairs performed (in order):
- *   1. Strip body lines that restate frontmatter fields as pseudo-frontmatter
- *      (e.g. `**description**: …` or `when_to_use: …` in the body).
- *   2. Remove stray body `---` horizontal-rule lines (leaving exactly the two
- *      frontmatter fences when the content has a valid frontmatter block).
- *   3. Apply {@link repairTruncatedDescription} to a truncated/hanging
+ * Repairs performed:
+ *   1. Apply {@link repairTruncatedDescription} to a truncated/hanging
  *      `description` field in the frontmatter.
  *
+ * It deliberately does NOT delete body lines. Two earlier repairs dropped
+ * every body line that restated a frontmatter key and every `---` in a body
+ * with frontmatter. Both fired inside fenced code blocks, so any asset
+ * documenting frontmatter — a note about akm, Claude Code skills, Jekyll,
+ * Hugo — was silently gutted on `proposal accept`, and the repaired bytes
+ * were written back over the original in the proposals database. A repair
+ * that can destroy content is not a repair.
+ *
  * Returns the repaired content string. When no repairs apply the input is
  * returned byte-identical so callers can use strict equality to detect
  * whether a repair actually happened.
@@ -81,19 +85,6 @@ export function repairProposalContent(content) {
             repairedLines.push(line);
             continue;
         }
-        // Repair 1: Strip pseudo-frontmatter restatements in the body.
-        // Matches lines like `**description**: …` or `when_to_use: …`.
-        if (/^\s*(\*\*|__)?\s*(description|when_to_use)\s*(\*\*|__)?\s*:/i.test(line)) {
-            // Drop the line — it is a structural defect, not user content.
-            continue;
-        }
-        // Repair 2: Remove stray `---` horizontal-rule lines in the body.
-        // We keep these only when the content has NO frontmatter (in that case
-        // `---` is a legitimate thematic break in plain-body content).
-        if (isFence && hasFrontmatter) {
-            // Drop: these are extra `---` fences beyond the two frontmatter delimiters.
-            continue;
-        }
         repairedLines.push(line);
     }
     let repaired = repairedLines.join("\n");

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,11 +27,12 @@
 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";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksPrune, akmTasksRun, akmTasksSync, akmTasksSyncPlan, } from "./tasks.js";
+import { akmTaskValidate } from "./validate.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
     bundle: {
@@ -355,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
@@ -414,6 +410,36 @@ const tasksDoctorCommand = defineJsonCommand({
         output("task-doctor", result);
     },
 });
+/**
+ * #907: `akm task validate`'s exit-code contract — `valid`/`converts` are
+ * successful outcomes (exit 0); `blocked`/`invalid`/`not-a-task` are
+ * diagnosed defects the caller must act on (exit 1, mirroring `task sync`'s
+ * own `failures.length > 0 -> EXIT_CODES.GENERAL`). A missing path or an
+ * unreadable file never reaches this function at all — `akmTaskValidate`
+ * throws a `UsageError` for those, which `defineJsonCommand`'s wrapping
+ * already maps to exit 2.
+ */
+export function taskValidateExitCode(result) {
+    return result.outcome === "valid" || result.outcome === "converts" ? undefined : EXIT_CODES.GENERAL;
+}
+const tasksValidateCommand = defineJsonCommand({
+    meta: {
+        name: "validate",
+        description: "Parse a single task file by filesystem path — not a concept ref, and the file need not live in a " +
+            "configured bundle — and report the same diagnostic `akm task sync` would produce for it. Read-only; " +
+            "never touches the scheduler.",
+    },
+    args: {
+        path: { type: "positional", description: "Filesystem path to a task source YAML file", required: true },
+    },
+    async run({ args }) {
+        const result = await akmTaskValidate(args.path);
+        output("task-validate", result);
+        const exitCode = taskValidateExitCode(result);
+        if (exitCode !== undefined)
+            process.exitCode = exitCode;
+    },
+});
 /**
  * #851: `akm task prune`'s exit-code contract mirrors `task sync --dry-run`'s
  * (`taskSyncDryRunExitCode` above) — non-zero whenever the preview lists
@@ -451,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({
@@ -466,6 +489,7 @@ export const taskCommand = defineGroupCommand({
         add: tasksAddCommand,
         run: tasksRunCommand,
         explain: tasksExplainCommand,
+        validate: tasksValidateCommand,
         history: tasksHistoryCommand,
         sync: tasksSyncCommand,
         prune: tasksPruneCommand,

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;