akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

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

@@ -6,7 +6,9 @@
  *
  * Attempts to patch missing frontmatter fields (`description`, `when_to_use`)
  * on assets that failed schema validation, using a single bounded in-tree LLM
- * call per asset. Results are recorded as `schema_repair_invoked` events.
+ * call per asset. Results are recorded as `schema_repair_invoked` events; a
+ * queued repair's `improve_ledger` row (written with the proposal) keeps the
+ * same asset from being re-queued inside the ledger's revisit window.
  *
  * This module is extracted from `improve.ts` to make the repair logic
  * independently testable and to use the shared structured execution seam.
@@ -18,52 +20,30 @@ import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { ConfigError } from "../../core/errors.js";
-import { appendEvent, readEvents } from "../../core/events.js";
+import { appendEvent } from "../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { info } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
-import { disposeLoweredExecutionDispatchLease } from "../../integrations/agent/execution-lowering.js";
-import { callStructured, preflightStructuredLlmRunner } from "../../llm/structured-call.js";
-import { createProposal, isProposalSkipped } from "../proposal/repository.js";
-// ── Constants ────────────────────────────────────────────────────────────────
-/** Minimum gap between schema-repair attempts on the same asset. */
-const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
-/**
- * Per-ref attempt cap (O-6 / #379): maximum number of schema-repair attempts
- * allowed within SCHEMA_REPAIR_WINDOW_MS. Prevents indefinite nightly re-repair
- * of assets whose source content is genuinely ambiguous or inconsistently
- * structured. After cap, the asset is skipped until the window rolls over.
- * Self-Refine arXiv:2303.17651 — iteration must be bounded.
- */
-const SCHEMA_REPAIR_MAX_ATTEMPTS = 3;
-const SCHEMA_REPAIR_WINDOW_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+import { assertRunnerCredentials } from "../../integrations/agent/runner-dispatch.js";
+import { callStructured } from "../../llm/structured-call.js";
+import { isLedgerBlocked, ledgerKey, loadLedgerSnapshot } from "../improve/ledger.js";
+import { createProposal } from "../proposal/repository.js";
+/** Proposal source and improve-ledger source for this pass. */
+const SCHEMA_REPAIR_SOURCE = "schema-repair";
 async function classifySchemaRepairs(args) {
     const { failures, startMs, budgetMs, stashDir, findFilePath, isLessonCandidateFn, repairs } = args;
     const eligibleRepairs = [];
     const pendingErrors = [];
+    const ledger = loadLedgerSnapshot(undefined, stashDir, [SCHEMA_REPAIR_SOURCE]);
+    const nowIso = new Date().toISOString();
     for (const failure of failures) {
         if (Date.now() - startMs >= budgetMs)
             break;
-        const recentRepairs = readEvents({ type: "schema_repair_invoked", ref: failure.ref });
-        const lastRepair = recentRepairs.events
-            .filter((event) => event.metadata?.outcome === "queued")
-            .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
-        if (lastRepair?.ts && Date.now() - new Date(lastRepair.ts).getTime() < SCHEMA_REPAIR_COOLDOWN_MS) {
+        if (isLedgerBlocked(ledger.get(ledgerKey(SCHEMA_REPAIR_SOURCE, failure.ref)), nowIso)) {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
             continue;
         }
-        const windowStart = Date.now() - SCHEMA_REPAIR_WINDOW_MS;
-        const attemptsInWindow = recentRepairs.events.filter((event) => event.ts !== undefined && new Date(event.ts).getTime() >= windowStart).length;
-        if (attemptsInWindow >= SCHEMA_REPAIR_MAX_ATTEMPTS) {
-            repairs.push({
-                ref: failure.ref,
-                reason: failure.reason,
-                outcome: "skipped",
-                error: `schema-repair attempt cap reached (${attemptsInWindow}/${SCHEMA_REPAIR_MAX_ATTEMPTS} in 30d window)`,
-            });
-            continue;
-        }
         const filePath = await findFilePath(failure.ref, stashDir);
         if (!filePath || path.extname(filePath).toLowerCase() !== ".md") {
             repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
@@ -152,112 +132,101 @@ export async function runSchemaRepairPass(failures, options) {
         }
         return { repairs, repairedRefs };
     }
-    const dispatchLease = await preflightStructuredLlmRunner(llmRunner);
-    try {
-        for (const repair of pendingErrors) {
-            appendEvent({
-                eventType: "schema_repair_invoked",
-                ref: repair.ref,
-                metadata: { outcome: "error", reason: repair.reason, error: repair.error },
+    assertRunnerCredentials(llmRunner);
+    for (const repair of pendingErrors) {
+        appendEvent({
+            eventType: "schema_repair_invoked",
+            ref: repair.ref,
+            metadata: { outcome: "error", reason: repair.reason, error: repair.error },
+        });
+        repairs.push(repair);
+    }
+    for (const { failure, frontmatter: fm, fieldList, messages } of eligibleRepairs) {
+        let loweringNotices = [];
+        const noticeFields = () => loweringNotices.length > 0 ? { notices: loweringNotices } : {};
+        try {
+            info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
+            const llmResponse = await callStructured({
+                feature: "schema_repair",
+                runner: llmRunner,
+                messages,
+                ...(chatFn ? { request: { chat: chatFn } } : {}),
+                onNotices: (value) => {
+                    loweringNotices = value;
+                },
+                parse: (rawResponse) => rawResponse ?? "",
+                onError: () => "",
+                fallback: "",
             });
-            repairs.push(repair);
-        }
-        for (const { failure, frontmatter: fm, fieldList, messages } of eligibleRepairs) {
-            let loweringNotices = [];
-            const noticeFields = () => loweringNotices.length > 0 ? { notices: loweringNotices } : {};
-            try {
-                info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
-                const llmResponse = await callStructured({
-                    feature: "schema_repair",
-                    runner: llmRunner,
-                    lease: dispatchLease,
-                    messages,
-                    ...(chatFn ? { request: { chat: chatFn } } : {}),
-                    onNotices: (value) => {
-                        loweringNotices = value;
-                    },
-                    parse: (rawResponse) => rawResponse ?? "",
-                    onError: () => "",
-                    fallback: "",
-                });
-                const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
-                if (!parsed) {
-                    repairs.push({
-                        ref: failure.ref,
-                        reason: failure.reason,
-                        outcome: "error",
-                        error: "LLM returned unparseable JSON for schema repair",
-                        ...noticeFields(),
-                    });
-                    continue;
-                }
-                const newFm = { ...fm.data };
-                if (parsed.description)
-                    newFm.description = parsed.description;
-                if (parsed.when_to_use)
-                    newFm.when_to_use = parsed.when_to_use;
-                const newContent = assembleAsset(newFm, fm.content);
-                // M-3 / #387: Route through proposal queue instead of writing directly to
-                // disk. This restores akm's safety invariant — the proposal queue is the
-                // only path to a committed asset write. LLM-generated `description` /
-                // `when_to_use` fields can be incorrect; routing through the queue makes
-                // them human-reviewable before they affect search ranking and curate hints.
-                // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
-                // should be human-reviewable.
-                const proposalResult = createProposal(stashDir, {
-                    ref: failure.ref,
-                    source: "schema-repair",
-                    // §23.6 fingerprint model-id term (WI-6.4).
-                    modelId: llmRunner.connection.model,
-                    payload: {
-                        content: newContent,
-                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
-                    },
-                });
-                if (isProposalSkipped(proposalResult)) {
-                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
-                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped", ...noticeFields() });
-                    continue;
-                }
-                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
-                appendEvent({
-                    eventType: "schema_repair_invoked",
-                    ref: failure.ref,
-                    metadata: {
-                        outcome: "queued",
-                        reason: failure.reason,
-                        proposalId: proposalResult.id,
-                        ...noticeFields(),
-                    },
-                });
+            const parsed = parseEmbeddedJsonResponse(llmResponse.trim());
+            if (!parsed) {
                 repairs.push({
                     ref: failure.ref,
                     reason: failure.reason,
-                    outcome: "queued",
-                    proposalId: proposalResult.id,
+                    outcome: "error",
+                    error: "LLM returned unparseable JSON for schema repair",
                     ...noticeFields(),
                 });
+                continue;
             }
-            catch (e) {
-                if (e instanceof ConfigError)
-                    throw e;
-                appendEvent({
-                    eventType: "schema_repair_invoked",
-                    ref: failure.ref,
-                    metadata: { outcome: "error", reason: failure.reason, error: String(e), ...noticeFields() },
-                });
-                repairs.push({
-                    ref: failure.ref,
+            const newFm = { ...fm.data };
+            if (parsed.description)
+                newFm.description = parsed.description;
+            if (parsed.when_to_use)
+                newFm.when_to_use = parsed.when_to_use;
+            const newContent = assembleAsset(newFm, fm.content);
+            // M-3 / #387: Route through proposal queue instead of writing directly to
+            // disk. This restores akm's safety invariant — the proposal queue is the
+            // only path to a committed asset write. LLM-generated `description` /
+            // `when_to_use` fields can be incorrect; routing through the queue makes
+            // them human-reviewable before they affect search ranking and curate hints.
+            // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
+            // should be human-reviewable.
+            const proposalResult = createProposal(stashDir, {
+                ref: failure.ref,
+                source: SCHEMA_REPAIR_SOURCE,
+                // Key the ledger row by the ref this pass reads it back under.
+                attemptedRefs: [failure.ref],
+                payload: {
+                    content: newContent,
+                    ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                },
+            });
+            info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: {
+                    outcome: "queued",
                     reason: failure.reason,
-                    outcome: "error",
-                    error: String(e),
+                    proposalId: proposalResult.id,
                     ...noticeFields(),
-                });
-            }
+                },
+            });
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "queued",
+                proposalId: proposalResult.id,
+                ...noticeFields(),
+            });
+        }
+        catch (e) {
+            if (e instanceof ConfigError)
+                throw e;
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "error", reason: failure.reason, error: String(e), ...noticeFields() },
+            });
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "error",
+                error: String(e),
+                ...noticeFields(),
+            });
         }
-    }
-    finally {
-        disposeLoweredExecutionDispatchLease(dispatchLease);
     }
     return { repairs, repairedRefs };
 }

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

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { isBundleSlug } from "../../core/asset/asset-ref.js";
+import { slugForRegistryId, validateExplicitBundleName } from "../../core/bundle-id.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
 import { bundleEntryToSourceEntry, getSources, installedSourceDescriptor, loadConfig, mutateConfig, resolveSecret, } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -38,7 +39,7 @@ export async function akmAdd(input) {
     catch {
         // Not a local ref — fall through to registry install
     }
-    return addRegistryStash(ref, stashDir, input.writable, input, input.credential);
+    return addRegistryStash(ref, stashDir, input.name, input.writable, input, input.credential);
 }
 /** Add a local directory as a filesystem bundle. */
 async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitAdapter, position = {}) {
@@ -49,6 +50,9 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitA
     mutateConfig((config) => {
         const existing = bundleKeyForPath(config, resolvedPath);
         if (existing) {
+            if (explicitName !== undefined) {
+                validateExplicitBundleName(config.bundles ?? {}, explicitName, existing);
+            }
             bundleKey = existing;
             const current = config.bundles?.[existing];
             if (current?.components && explicitAdapter === undefined)
@@ -62,6 +66,11 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitA
             return { ...config, bundles };
         }
         const bundles = { ...(config.bundles ?? {}) };
+        // D6: an explicit `--name` is a contract on this (local) add path — validated
+        // strictly before nextBundleKey derives a key, since that shared helper is also
+        // used by the out-of-scope `akm source add` (`addStash`) and stays forgiving.
+        if (explicitName !== undefined)
+            validateExplicitBundleName(bundles, explicitName);
         bundleKey = nextBundleKey(bundles, explicitName, resolvedPath);
         const entry = {
             path: resolvedPath,
@@ -75,6 +84,7 @@ async function addLocalSource(ref, sourcePath, stashDir, explicitName, explicitA
         schemaVersion: 1,
         bundleDir: stashDir,
         ref,
+        bundleId: bundleKey,
         sourceAdded: {
             type: "filesystem",
             path: resolvedPath,
@@ -100,10 +110,29 @@ async function addWebsiteSource(ref, stashDir, name, options, position = {}) {
     const maxPages = numberOption(options?.maxPages);
     const maxDepth = numberOption(options?.maxDepth);
     let entry;
+    let bundleId = "";
     mutateConfig((config) => {
         const bundles = { ...(config.bundles ?? {}) };
         const existingKey = bundleKeyForUrl(config, normalizedUrl);
-        const key = existingKey ?? nextBundleKey(bundles, name ?? toWebsiteName(normalizedUrl), normalizedUrl);
+        if (existingKey && name !== undefined) {
+            validateExplicitBundleName(bundles, name, existingKey);
+        }
+        // An explicit `--name` is a contract (D6) — validated strictly and used
+        // as-is, never silently substituted. A DERIVED default (no --name) keeps
+        // the forgiving `deriveBundleId` fallback, so a dotted hostname or a
+        // URL collision still mints a usable id instead of erroring.
+        let key;
+        if (existingKey) {
+            key = existingKey;
+        }
+        else if (name !== undefined) {
+            validateExplicitBundleName(bundles, name);
+            key = name;
+        }
+        else {
+            key = deriveBundleId(toWebsiteName(normalizedUrl), normalizedUrl, new Set(Object.keys(bundles)));
+        }
+        bundleId = key;
         // Merge onto the existing descriptor rather than replacing it: re-running
         // `bundle add` for a URL that already has a bundle would otherwise drop
         // respectRobots / refresh, silently restoring default robots enforcement
@@ -140,6 +169,7 @@ async function addWebsiteSource(ref, stashDir, name, options, position = {}) {
         schemaVersion: 1,
         bundleDir: stashDir,
         ref,
+        bundleId,
         sourceAdded: {
             type: "website",
             url: normalizedUrl,
@@ -162,7 +192,7 @@ async function addWebsiteSource(ref, stashDir, name, options, position = {}) {
  * Install a stash from a registry (npm, github, git) by dispatching to the
  * matching syncable provider and persisting the lock entry.
  */
-async function addRegistryStash(ref, stashDir, writable, position = {}, credentialRef) {
+async function addRegistryStash(ref, stashDir, explicitName, writable, position = {}, credentialRef) {
     const parsedRef = parseRegistryRef(ref);
     if (writable === true && parsedRef.source !== "git" && parsedRef.source !== "github") {
         throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
@@ -172,6 +202,14 @@ async function addRegistryStash(ref, stashDir, writable, position = {}, credenti
     }
     const currentConfig = loadConfig();
     const existingBundleKey = findInstalledBundleKey(currentConfig.bundles ?? {}, parsedRef.id);
+    // D6: validate an explicit `--name` before any network sync or write — an
+    // illegal name, a name already taken by a different bundle, or re-adding
+    // this same install under a different name than it already carries must
+    // fail loudly here, not mint a `-<hash>` fallback deep inside the config
+    // mutation below.
+    if (explicitName !== undefined) {
+        validateExplicitBundleName(currentConfig.bundles ?? {}, explicitName, existingBundleKey);
+    }
     const existingBundle = existingBundleKey ? currentConfig.bundles?.[existingBundleKey] : undefined;
     const priorLock = existingBundleKey ? readLockfile().find((entry) => entry.id === existingBundleKey) : undefined;
     const existingWritable = Object.values(existingBundle?.components ?? {})[0]?.writable ?? existingBundle?.writable === true;
@@ -200,7 +238,7 @@ async function addRegistryStash(ref, stashDir, writable, position = {}, credenti
         cacheDir: synced.cacheDir,
         installedAt: synced.syncedAt,
         writable: synced.writable,
-    }, position, credentialRef);
+    }, position, credentialRef, explicitName);
     // The prior materialized root (if this is a re-install) — read BEFORE the lock
     // upsert overwrites it, so a moved cache root can be cleaned afterwards.
     const priorLocalRoot = priorLock?.localRoot;
@@ -229,6 +267,8 @@ async function addRegistryStash(ref, stashDir, writable, position = {}, credenti
         schemaVersion: 1,
         bundleDir: stashDir,
         ref,
+        bundleId,
+        registryId: synced.id,
         installed: {
             id: synced.id,
             source: synced.source,
@@ -258,14 +298,15 @@ async function addRegistryStash(ref, stashDir, writable, position = {}, credenti
  * (spec §10.1 / §10.2 desired/resolved split). The bundle carries ONLY the
  * desired descriptor (git/npm locator + preserved `registryId` + `writable`);
  * the resolved cache root belongs exclusively in the lock (written by callers
- * via {@link upsertLockEntry} with the returned `bundleId`). Returns the config
+ * via {@link upsertLockEntry} with the returned `bundleId`). A new install is
+ * keyed by `explicitName` (the CLI's `--name`) when given. Returns the config
  * plus the derived bundle id so the caller keys its lock entry identically.
  */
-export function upsertInstalledRegistryEntry(entry, position = {}, credential) {
+export function upsertInstalledRegistryEntry(entry, position = {}, credential, explicitName) {
     let bundleId = entry.id;
     const config = mutateConfig((current) => {
         const bundles = { ...(current.bundles ?? {}) };
-        bundleId = resolveInstalledBundleKey(bundles, entry.id, entry.stashRoot);
+        bundleId = resolveInstalledBundleKey(bundles, entry.id, entry.stashRoot, explicitName);
         const existingComponents = bundles[bundleId]?.components;
         const components = existingComponents
             ? Object.fromEntries(Object.entries(existingComponents).map(([id, component]) => [
@@ -334,15 +375,24 @@ function findInstalledBundleKey(bundles, installId) {
 }
 /**
  * The stable bundle key for a registry install: reuse the existing bundle for
- * this install id (so re-installs keep the same key), otherwise derive a
- * batch-unique key via the shared {@link deriveBundleId} (D-R5), unique against
- * the currently-configured bundle keys.
+ * this install id (so re-installs keep the same key — a caller-visible name
+ * mismatch was already rejected upstream, by {@link validateExplicitBundleName}
+ * in `addRegistryStash`, before any write). Otherwise an explicit `--name`
+ * (D6) is a contract — validated strictly and used as-is, never silently
+ * substituted. Without one, a batch-unique key is derived via the shared
+ * {@link deriveBundleId} (D-R5) from the package/repo name the install id
+ * names rather than the basename of the materialized cache directory
+ * (`extracted`) — unique against the currently-configured bundle keys.
  */
-function resolveInstalledBundleKey(bundles, installId, stashRoot) {
+function resolveInstalledBundleKey(bundles, installId, stashRoot, explicitName) {
     const existing = findInstalledBundleKey(bundles, installId);
     if (existing)
         return existing;
-    return deriveBundleId(installId, path.resolve(stashRoot), new Set(Object.keys(bundles)));
+    if (explicitName !== undefined) {
+        validateExplicitBundleName(bundles, explicitName);
+        return explicitName;
+    }
+    return deriveBundleId(slugForRegistryId(installId), path.resolve(stashRoot), new Set(Object.keys(bundles)));
 }
 function toReadableId(resolvedPath) {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? "";

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

@@ -71,7 +71,7 @@ export const indexCommand = defineCommand({
         },
         reembed: {
             type: "boolean",
-            description: "Force re-embedding of every entry, bypassing the embedding-model-rename compatibility check.",
+            description: "Discard every stored vector and re-embed all entries under the configured model.",
             default: false,
         },
         "skip-if-locked": {

package/dist/commands/tasks/explain.js

@@ -34,11 +34,10 @@
  *     `with.content`, an inline `akm/command` prompt body, or a stored
  *     command's own rendered content is never read, let alone printed;
  *   - effective execution settings (engine/model/timeout) reuse
- *     `prepareResolvedExecution` (`src/integrations/agent/execution-preparation.ts`)
- *     — the SAME cascade-composition entry point `prepareCommandInvocation`
- *     itself calls once a command/persona source is already rendered — fed a
- *     BLANK inline placeholder command (`createInlineResolvedCommand`) and an
- *     EMPTY command-layer values map, instead of the task's real referenced
+ *     `resolveExecution` (`src/integrations/agent/execution.ts`) — the SAME
+ *     resolution entry point every command/persona invocation goes through —
+ *     fed a BLANK inline placeholder command (`createInlineResolvedCommand`)
+ *     and an EMPTY command-layer values map, instead of the task's real referenced
  *     command source. This is a deliberate, documented trade-off: a
  *     referenced command's OWN frontmatter overrides (its own `engine:`/
  *     `model:`, if any) do not contribute a layer here, in exchange for never
@@ -70,9 +69,8 @@
  * `suppliedInputs`). Do not paste this command's output into an untrusted
  * place on the assumption that it can never contain a credential.
  *
- * Field-level execution provenance is READ from `planExecutionCascade`'s own
- * `ResolvedExecutionPlanV1.provenance` (via `prepareResolvedExecution`) —
- * this module is a CONSUMER of the one common cascade resolver, never a
+ * Field-level execution provenance is READ from `resolveExecution`'s own
+ * `provenance` — this module is a CONSUMER of the one common resolver, never a
  * second resolver: it never re-derives engine/model precedence itself.
  */
 import fs from "node:fs";
@@ -83,7 +81,7 @@ import { NotFoundError } from "../../core/errors.js";
 import { applyInputDefaults, materializeInputFlags, } from "../../execution/input-contract.js";
 import { createInlineResolvedCommand } from "../../execution/resolved-request.js";
 import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
-import { prepareResolvedExecution } from "../../integrations/agent/execution-preparation.js";
+import { resolveExecution } from "../../integrations/agent/execution.js";
 import { isSchedulerRefEnabled } from "../../tasks/activation-config.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
 import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
@@ -209,10 +207,9 @@ function resolveExecutionSettings(document) {
     if (!isCommandTarget(document))
         return { provenance: {} };
     const current = currentExecutionValues(document);
-    const prepared = prepareResolvedExecution({
+    const prepared = resolveExecution({
         command: createInlineResolvedCommand({ template: "", content: "" }),
         config: loadConfig(),
-        invocationKind: "task",
         commandLayer: { id: "task-explain", values: {} },
         ...(Object.keys(current).length > 0 ? { current } : {}),
     });
@@ -225,7 +222,7 @@ function resolveExecutionSettings(document) {
         },
         ...(prepared.request.model !== undefined ? { model: prepared.request.model } : {}),
         ...(prepared.request.runtime.timeoutMs !== undefined ? { timeoutMs: prepared.request.runtime.timeoutMs } : {}),
-        provenance: prepared.plan.provenance,
+        provenance: prepared.provenance,
     };
 }
 /**
@@ -272,7 +269,7 @@ export async function akmTaskExplain(ref, options = {}) {
     const materializedInputs = materializeInputFlags(inputContract, options.inputFlags ?? [], TASK_INPUT_DIAGNOSTICS);
     const defaultedInputs = applyInputDefaults(inputContract, materializedInputs);
     const document = projectTaskSourceV4(parsed.v4);
-    const enabled = isSchedulerRefEnabled(loadConfig(), "task", makeBundleRef(bundle.source.name, taskConceptId));
+    const enabled = isSchedulerRefEnabled(loadConfig(), makeBundleRef(bundle.source.name, taskConceptId));
     const schedule = parsed.v4.schedule.map((entry) => ({
         ordinal: entry.ordinal,
         cron: entry.cron,

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

@@ -226,7 +226,7 @@ const tasksAddCommand = defineJsonCommand({
         force: { type: "boolean", description: "Overwrite an existing task with the same id", default: false },
         rebind: {
             type: "boolean",
-            description: "Explicitly permit scheduler creation from this ineligible local invocation",
+            description: "Also point the bundle's installed scheduler rows at this akm invocation (as `task sync --rebind`)",
             default: false,
         },
     },
@@ -358,13 +358,13 @@ export function taskSyncDryRunExitCode(preview) {
 const tasksSyncCommand = defineJsonCommand({
     meta: {
         name: "sync",
-        description: "Atomically preflight and reconcile a bundle's task/workflow schedules with the OS scheduler",
+        description: "Reconcile enabled task/workflow schedules with the OS scheduler, one row at a time",
     },
     args: {
         ...bundleArg,
         rebind: {
             type: "boolean",
-            description: "Replace installed bindings with the current invocation",
+            description: "Point installed rows at this akm invocation instead of keeping their launcher",
             default: false,
         },
         "dry-run": {
@@ -435,16 +435,17 @@ const tasksDoctorCommand = defineJsonCommand({
     },
 });
 /**
- * #907: `akm task validate`'s exit-code contract — only current-schema
- * `valid` is successful (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
+ * #907: `akm task validate`'s exit-code contract — `valid` and `converts`
+ * (a v2/v3 document the in-memory shim converted successfully) are both
+ * successful (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" ? undefined : EXIT_CODES.GENERAL;
+    return result.outcome === "valid" || result.outcome === "converts" ? undefined : EXIT_CODES.GENERAL;
 }
 const tasksValidateCommand = defineJsonCommand({
     meta: {