akm-cli 0.9.4 → 0.9.6

package/dist/commands/tasks/tasks.js

@@ -35,11 +35,10 @@ import { exitCodeForStatus } from "../../tasks/run/task-result.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT } from "../../tasks/schedule.js";
 import { assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "../../tasks/scheduler-binding.js";
 import { schedulerContextDescriptor, schedulerContextPath, validateSchedulerContextDescriptor, writeSchedulerContextDescriptor, } from "../../tasks/scheduler-invocation.js";
-import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
-import { renderSchedulerSyncPlanPreview } from "../../tasks/scheduler-sync-preview.js";
+import { assertSchedulerNativeArtifactOwnership, assertSchedulerSourceSnapshot, buildSchedulerRemoveOperation, finalizeSchedulerSyncPlan, prepareSchedulerSyncSourceSet, } from "../../tasks/scheduler-sync.js";
+import { renderSchedulerPlanPreview, renderSchedulerSyncPlanPreview, } from "../../tasks/scheduler-sync-preview.js";
 import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
 import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
-import { TASK_V3_MAX_SOURCE_BYTES } from "../../tasks/source-v3.js";
 import { normaliseTaskConceptId, normaliseTaskId } from "../../tasks/task-id.js";
 import { applyAutonomyGate, configuredDirectAutonomyLanes, describeGatedLanes } from "../improve/autonomy-gate.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
@@ -417,6 +416,7 @@ export async function akmTasksSync(deps = {}, bundleTarget, options = {}) {
         unchanged: [...plan.unchanged],
         skipped: [],
         backend: sched.name,
+        failed: plan.failures.map((failure) => ({ ...failure })),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -434,6 +434,92 @@ export async function akmTasksSyncPlan(deps = {}, bundleTarget, options = {}) {
     const { sched, plan } = await buildSchedulerSyncPlan(deps, bundleTarget, options);
     return renderSchedulerSyncPlanPreview(sched.name, plan);
 }
+/**
+ * Classify one installed scheduler binding as a prune candidate (#851), using
+ * the same two signals `doctor`'s `inspectInstalledBinding` already computes
+ * — deliberately narrower than that function's full `status` set. Only an
+ * entry whose ownership can NEVER be resolved (`invalid-context`) or whose
+ * resolved owner no longer exists on disk (`dead-bundle-path`) is a
+ * candidate; `missing-path` (e.g. the akm binary itself moved) is a
+ * different failure mode and is intentionally NOT folded in here, per the
+ * scoping in #851 — an entry that still resolves to a live bundle is never a
+ * candidate, full stop.
+ */
+function classifyPruneCandidate(entry) {
+    let ownerBundlePath;
+    try {
+        ownerBundlePath = validateSchedulerContextDescriptor(entry.contextPath).environment.AKM_BUNDLE_DIR;
+    }
+    catch {
+        return "invalid-context";
+    }
+    if (ownerBundlePath !== undefined && !fs.existsSync(ownerBundlePath))
+        return "dead-bundle-path";
+    return undefined;
+}
+async function buildTaskPrunePlan(deps = {}, options = {}) {
+    const sched = deps.backend ?? selectBackend();
+    if (!sched.inspectBindings) {
+        throw new ConfigError(`Scheduler backend "${sched.name}" cannot provide one coherent inspection for prune.`, "INVALID_CONFIG_FILE");
+    }
+    const inspection = await sched.inspectBindings({});
+    const candidates = new Map();
+    for (const entry of inspection.installed) {
+        const reason = classifyPruneCandidate(entry);
+        if (reason)
+            candidates.set(entry.id, reason);
+    }
+    const requestedIds = options.id?.filter((id) => id.length > 0) ?? [];
+    for (const id of requestedIds) {
+        if (!candidates.has(id)) {
+            throw new UsageError(`Scheduler binding ${JSON.stringify(id)} is not an orphaned prune candidate ` +
+                "(either not installed, or it still resolves to a live bundle) — refusing to prune it.", "INVALID_FLAG_VALUE");
+        }
+    }
+    const idFilter = requestedIds.length > 0 ? new Set(requestedIds) : undefined;
+    const resolved = resolveTaskReadBundle(undefined, undefined);
+    const bundleContext = {
+        adapterId: resolved.source.adapterId ?? detectAdapterId(resolved.source.path),
+        bundleName: resolved.source.name,
+    };
+    const operations = [];
+    for (const entry of inspection.installed) {
+        const reason = candidates.get(entry.id);
+        if (!reason)
+            continue;
+        if (idFilter && !idFilter.has(entry.id))
+            continue;
+        const operation = buildSchedulerRemoveOperation(entry.id, entry, inspection.artifacts, bundleContext);
+        operations.push(Object.freeze({ ...operation, reason }));
+    }
+    return { sched, operations: Object.freeze(operations) };
+}
+/**
+ * `akm task prune` (#851): remove installed scheduler bindings `sync` can
+ * never reclaim because their own `--scheduler-context` descriptor doesn't
+ * resolve to a live bundle. Defaults to dry-run — no `--yes` and no `--id`
+ * means zero backend calls that could mutate anything, matching
+ * `akmTasksSyncPlan`'s zero-write guarantee. `--id` (one or more) narrows
+ * execution to exactly those bindings; `--yes` alone executes every
+ * currently-computed candidate. Both still return the full preview so the
+ * plan is never silent about what it did.
+ */
+export async function akmTasksPrune(deps = {}, options = {}) {
+    const { sched, operations } = await buildTaskPrunePlan(deps, options);
+    const preview = renderSchedulerPlanPreview(sched.name, operations);
+    if (!options.yes) {
+        return { backend: sched.name, dryRun: true, preview, removed: [] };
+    }
+    await applySchedulerTransaction(sched, operations, {
+        initialExpectations: operations.map((operation) => operation.expected),
+    });
+    return {
+        backend: sched.name,
+        dryRun: false,
+        preview,
+        removed: operations.map((operation) => operation.id),
+    };
+}
 export async function akmTasksDoctor(deps = {}) {
     const warnings = [];
     let invocation = {
@@ -884,13 +970,7 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
     if (!rootStat.isDirectory()) {
         throw new UsageError(`${root} is not a task source directory.`, "INVALID_FLAG_VALUE");
     }
-    const common = {
-        filePath,
-        rootRealPath,
-        rootPhysicalIdentity: rootStat.ino === 0n ? `path:${rootRealPath}` : `inode:${rootStat.dev}:${rootStat.ino}`,
-        rootMtimeNs: String(rootStat.mtimeNs),
-        rootCtimeNs: String(rootStat.ctimeNs),
-    };
+    const common = { filePath, rootRealPath };
     let descriptor;
     try {
         const noFollow = "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
@@ -899,9 +979,6 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
         if (!before.isFile()) {
             throw new UsageError(`${filePath} is not a regular task source.`, "INVALID_FLAG_VALUE");
         }
-        if (before.size > BigInt(TASK_V3_MAX_SOURCE_BYTES)) {
-            throw new UsageError(`${filePath} exceeds the 1 MiB (${TASK_V3_MAX_SOURCE_BYTES}-byte) task source limit.`, "INVALID_FLAG_VALUE");
-        }
         const bytes = fs.readFileSync(descriptor);
         const after = fs.fstatSync(descriptor, { bigint: true });
         if (!sameTaskSourceStat(before, after) || BigInt(bytes.byteLength) !== before.size) {
@@ -923,10 +1000,7 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
             state: "present",
             ...common,
             realPath,
-            physicalIdentity: before.ino === 0n ? `path:${realPath}` : `inode:${before.dev}:${before.ino}`,
             size: bytes.byteLength,
-            mtimeNs: String(before.mtimeNs),
-            ctimeNs: String(before.ctimeNs),
             sha256: createHash("sha256").update(bytes).digest("hex"),
             bytesBase64: bytes.toString("base64"),
             content,
@@ -948,6 +1022,11 @@ function captureTaskSourceExpectation(filePathInput, rootInput) {
             fs.closeSync(descriptor);
     }
 }
+// TOCTOU note: this compares CONTENT (state + sha256), not filesystem
+// identity (inode/mtime/ctime/directory timestamps) — the same split already
+// applied to the task migrator in 0.9.5. An unrelated touch to the file or
+// its containing directory must not trip a "changed after planning" refusal;
+// only a real content change should.
 function assertTaskSourceExpectation(expected) {
     const actual = captureTaskSourceExpectation(expected.filePath, expected.rootRealPath);
     if (!sameTaskSourceExpectation(actual, expected)) {
@@ -955,12 +1034,16 @@ function assertTaskSourceExpectation(expected) {
     }
 }
 function sameTaskSourceExpectation(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
+    if (left.state !== right.state || left.filePath !== right.filePath || left.rootRealPath !== right.rootRealPath) {
+        return false;
+    }
+    if (left.state === "absent")
+        return true;
+    return left.sha256 === right.sha256;
 }
 function assertTaskSourceRestored(expected) {
     const actual = captureTaskSourceExpectation(expected.filePath, expected.rootRealPath);
     const restored = actual.state === expected.state &&
-        actual.rootPhysicalIdentity === expected.rootPhysicalIdentity &&
         (actual.state === "absent" ||
             (expected.state === "present" && actual.sha256 === expected.sha256 && actual.content === expected.content));
     if (!restored) {

package/dist/commands/workflow-cli.js

@@ -20,7 +20,7 @@ import { deliverRendered } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain } from "../output/text.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
-import { WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
+import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
 import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
@@ -168,7 +168,7 @@ const workflowRunCommand = defineJsonCommand({
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
         const parameterFlags = parseWorkflowParameterFlags(rawArgs, args.target);
         const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
-        const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0, WORKFLOW_MAX_RETRIES);
+        const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0);
         const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
         const controller = new AbortController();
         let signalExitCode;

package/dist/core/adapter/adapters/akm-adapter.js

@@ -223,6 +223,8 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.tags = entry.tags;
     if (entry.content !== undefined)
         doc.content = entry.content;
+    if (entry.contentTruncated !== undefined)
+        doc.contentTruncated = entry.contentTruncated;
     if (entry.aliases !== undefined)
         doc.aliases = entry.aliases;
     if (entry.searchHints !== undefined)

package/dist/core/common.js

@@ -10,8 +10,6 @@ import { getConfigPath, getDefaultStashDir, getRegistryCacheDir, getRegistryInde
 // Moved to the platform leaf so paths.ts can use it without a common↔paths
 // cycle (chunk-8 WI-8.6, DoD 11); re-exported here for the existing surface.
 export { IS_WINDOWS } from "./platform.js";
-export const MAX_CONFIG_FILE_BYTES = 1024 * 1024;
-export const MAX_LOCAL_METADATA_BYTES = 1024 * 1024;
 export const MAX_LOCK_METADATA_BYTES = 64 * 1024;
 export function isHttpUrl(value) {
     return !!value && /^https?:\/\//.test(value);
@@ -51,10 +49,13 @@ export function readTextFileDescriptorWithLimit(fd, maxBytes, label = "File", di
     }
     return buffer.subarray(0, total).toString("utf8");
 }
-export function readTextFileWithLimit(filePath, maxBytes, label = "File") {
+export function readTextFile(filePath, label = "File") {
     const fd = fs.openSync(filePath, "r");
     try {
-        return readTextFileDescriptorWithLimit(fd, maxBytes, label, filePath);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            throw new ConfigError(`${label} is not a regular file: ${filePath}.`, "INVALID_CONFIG_FILE");
+        return fs.readFileSync(fd, "utf8");
     }
     finally {
         fs.closeSync(fd);
@@ -290,7 +291,7 @@ function isValidDirectory(dir) {
 function readStashDirFromConfig() {
     try {
         const configPath = getConfigPath();
-        const text = readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
+        const text = readTextFile(configPath, "Config file");
         // The config loader accepts JSONC, so a commented config.json is valid and
         // in use. Parsing it raw here threw, the catch swallowed it, and every
         // caller silently fell back — operating on the wrong bundle or failing with
@@ -544,21 +545,59 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
             clearTimeout(timer);
     }
 }
+/**
+ * Cap on how long a retry loop will wait between attempts, even when a
+ * server-supplied `Retry-After` claims a longer delay. Prevents an
+ * attacker-controlled or misconfigured server from parking a caller
+ * indefinitely.
+ */
+export const DEFAULT_RETRY_MAX_DELAY_MS = 30_000;
+export function shouldRetry(status) {
+    return status === 429 || status >= 500;
+}
+/** Jittered exponential backoff, capped at `maxDelayMs`. */
+export function backoffDelay(attempt, baseDelay = 500, maxDelayMs = DEFAULT_RETRY_MAX_DELAY_MS) {
+    return Math.min(maxDelayMs, baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5));
+}
+/**
+ * Determine the delay before the next retry attempt.
+ *
+ * Honors a server-supplied `Retry-After` header in both its numeric-seconds
+ * and HTTP-date forms, but always clamps the result to `maxDelayMs` — an
+ * unclamped `Retry-After` lets an attacker/misconfigured server park a
+ * caller for an arbitrarily long time. Falls back to jittered exponential
+ * backoff when the header is absent or unparseable.
+ */
+export function computeRetryDelay(response, attempt, options) {
+    const maxDelayMs = options?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS;
+    const baseDelay = options?.baseDelay ?? 500;
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds)) {
+            return seconds >= 0 ? Math.min(maxDelayMs, seconds * 1_000) : backoffDelay(attempt, baseDelay, maxDelayMs);
+        }
+        const date = Date.parse(retryAfter);
+        if (Number.isFinite(date))
+            return Math.min(maxDelayMs, Math.max(0, date - Date.now()));
+    }
+    return backoffDelay(attempt, baseDelay, maxDelayMs);
+}
 /**
  * Fetch with retry and exponential backoff.
  * Retries on network errors, 429, and 5xx responses.
- * Honors Retry-After header for 429 responses.
+ * Honors Retry-After header, capped at `maxDelayMs`.
  */
 export async function fetchWithRetry(url, init, options) {
     const maxRetries = options?.retries ?? 3;
     const baseDelay = options?.baseDelay ?? 500;
+    const maxDelayMs = options?.maxDelayMs ?? DEFAULT_RETRY_MAX_DELAY_MS;
     const timeout = options?.timeout ?? 30_000;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
             const response = await fetchWithTimeout(url, init, timeout, init?.signal ?? undefined);
             if (attempt < maxRetries && shouldRetry(response.status)) {
-                const retryAfter = parseRetryAfter(response);
-                const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
+                const delay = computeRetryDelay(response, attempt, { baseDelay, maxDelayMs });
                 await response.body?.cancel().catch(() => undefined);
                 await abortableDelay(delay, init?.signal);
                 continue;
@@ -571,8 +610,7 @@ export async function fetchWithRetry(url, init, options) {
             // A caller-supplied abort is terminal: never keep retrying past it.
             if (init?.signal?.aborted)
                 throw err;
-            const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-            await abortableDelay(delay, init?.signal);
+            await abortableDelay(backoffDelay(attempt, baseDelay, maxDelayMs), init?.signal);
         }
     }
     throw new Error("fetchWithRetry: unreachable");
@@ -584,17 +622,19 @@ export async function fetchWithRetry(url, init, options) {
  * large. Sleeping it out with a bare `setTimeout` ignored the caller's abort
  * signal entirely, so a single `429` could park an operation far past any
  * deadline its caller believed it had imposed — the request timeout bounds
- * only the request, never the wait between attempts.
+ * only the request, never the wait between attempts. Callers using this for
+ * a retry delay should pass a `maxDelayMs`-capped `ms` (see
+ * {@link computeRetryDelay}) to bound the wait itself.
  */
-function abortableDelay(ms, signal) {
+export function abortableDelay(ms, signal, abortMessage = "Aborted") {
     if (!signal)
         return new Promise((resolve) => setTimeout(resolve, ms));
     if (signal.aborted)
-        return Promise.reject(signal.reason ?? new Error("Aborted"));
+        return Promise.reject(signal.reason ?? new Error(abortMessage));
     return new Promise((resolve, reject) => {
         const onAbort = () => {
             clearTimeout(timer);
-            reject(signal.reason ?? new Error("Aborted"));
+            reject(signal.reason ?? new Error(abortMessage));
         };
         const timer = setTimeout(() => {
             signal.removeEventListener("abort", onAbort);
@@ -603,9 +643,6 @@ function abortableDelay(ms, signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
-function shouldRetry(status) {
-    return status === 429 || status >= 500;
-}
 /**
  * Read stdin as UTF-8 text if something is piped in. Returns `undefined`
  * when stdin is a TTY (no pipe) or when the piped content is empty.
@@ -789,13 +826,6 @@ export async function jsonWithByteCap(response, maxBytes = DEFAULT_RESPONSE_BYTE
     const text = await readBodyWithByteCap(response, maxBytes, limits);
     return JSON.parse(text);
 }
-function parseRetryAfter(response) {
-    const header = response.headers.get("retry-after");
-    if (!header)
-        return undefined;
-    const seconds = parseInt(header, 10);
-    return Number.isNaN(seconds) ? undefined : seconds * 1000;
-}
 export function toErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -871,8 +901,15 @@ export function stringArray(value) {
  * reported alive. Treating it as dead let a lock held by a live process in a
  * shared data dir (agent sandboxes, containers, service accounts — a
  * configuration managed-db.ts explicitly supports) be reclaimed as stale.
+ *
+ * `pid` is `unknown` because callers reading it out of untrusted on-disk
+ * JSON (e.g. a lease file) cannot guarantee it parsed as a valid PID; a
+ * non-positive-integer value is reported dead without ever reaching
+ * `process.kill`.
  */
 export function isProcessAlive(pid) {
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;

package/dist/core/config/config-io.js

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { sleepSync } from "../../runtime.js";
-import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit, stripJsonComments, writeFileAtomic } from "../common.js";
+import { readTextFile, stripJsonComments, writeFileAtomic } from "../common.js";
 import { ConfigError } from "../errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
 import { getCacheDir, getConfigDir } from "../paths.js";
@@ -25,7 +25,7 @@ import { getCacheDir, getConfigDir } from "../paths.js";
  */
 export function readConfigText(configPath) {
     try {
-        return readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
+        return readTextFile(configPath, "Config file");
     }
     catch (err) {
         if (err.code === "ENOENT")

package/dist/core/config/config-sources.js

@@ -23,6 +23,16 @@ export function bundleComponentConfig(bundle) {
  * `defaultBundle` first, then map insertion order. Each entry's `name` is its
  * bundle key. Returns `undefined` when no bundles map is configured.
  */
+/**
+ * A bundle's true identity: its configured `path` plus its component's
+ * `root` (default `"."`), fully resolved. Two bundle entries whose bare
+ * `path` differs (relative vs. absolute, trailing slash, `~` vs. expanded)
+ * can still resolve to this same directory — this is the identity akm
+ * compares before registering or reconciling a bundle (issue #870).
+ */
+export function bundleContentRoot(entryPath, componentRoot) {
+    return path.resolve(entryPath, componentRoot ?? ".");
+}
 /**
  * The resolved primary stash path — the `defaultBundle`'s filesystem `path`
  * (spec §10.1) — or `undefined` when no filesystem primary is configured.
@@ -36,9 +46,9 @@ export function primaryBundlePath(config) {
     if (!entry || typeof entry.path !== "string" || entry.path.length === 0)
         return undefined;
     const componentRoot = bundleComponentConfig(entry)?.root;
-    if (!componentRoot || componentRoot === ".")
-        return entry.path;
     const bundleRoot = path.resolve(entry.path);
+    if (!componentRoot || componentRoot === ".")
+        return bundleRoot;
     const resolved = path.resolve(bundleRoot, componentRoot);
     const relative = path.relative(bundleRoot, resolved);
     if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
@@ -46,6 +56,26 @@ export function primaryBundlePath(config) {
     }
     return resolved;
 }
+/**
+ * Every configured filesystem bundle's id paired with its resolved content
+ * root. Used to detect two bundle ids that resolve to the same directory
+ * (issue #870) and to find the id that already owns a given root before a
+ * new one is registered.
+ */
+export function bundleContentRoots(config) {
+    const bundles = config.bundles ?? {};
+    const out = [];
+    for (const [id, entry] of Object.entries(bundles)) {
+        if (typeof entry.path !== "string" || entry.path.length === 0)
+            continue;
+        out.push({ id, contentRoot: bundleContentRoot(entry.path, bundleComponentConfig(entry)?.root) });
+    }
+    return out;
+}
+/** The bundle id whose resolved content root already matches `resolvedContentRoot`, if any. */
+export function bundleKeyForContentRoot(config, resolvedContentRoot) {
+    return bundleContentRoots(config).find((entry) => entry.contentRoot === resolvedContentRoot)?.id;
+}
 export function bundlesToSourceEntries(config) {
     const bundles = config.bundles;
     if (!bundles)

package/dist/core/config/config-version-shim.js

@@ -0,0 +1,101 @@
+// 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/.
+/**
+ * The `configVersion` read shim (#863).
+ *
+ * `configVersion` used to be a hard `z.literal(CURRENT_CONFIG_VERSION)` gate:
+ * every value other than the exact current string threw
+ * `UNSUPPORTED_CONFIG_VERSION` for every command, since every akm invocation
+ * loads config first. That is the same shape of break #858/#859 (proposal
+ * rows), the `task_history` `metadataVersion` gate, and the task-source v2/v3
+ * gate each caused in 0.9.x — a version gate with no read shim — except
+ * `configVersion`'s blast radius is the whole CLI rather than one subsystem.
+ *
+ * This module mirrors the in-tree template for that fix,
+ * `src/tasks/source/parse-task-source.ts`'s v2/v3 -> v4 shim: a known-old
+ * version routes through a pure, in-memory upgrade function to the current
+ * shape, with a one-line stderr deprecation warning; the result is never
+ * written back to disk (the on-disk rewrite already happens for free — every
+ * `saveConfig`/`mutateConfig` write forces `configVersion` to
+ * {@link CURRENT_CONFIG_VERSION}, so the very next `akm config set` or any
+ * other mutating command silences the warning permanently). A version that is
+ * neither current nor a known old version — including anything NEWER than
+ * current — still fails closed with `UNSUPPORTED_CONFIG_VERSION`:
+ * forward-incompatibility is a real hazard (an older binary must not guess at
+ * a newer, unknown shape) and this shim does not soften that.
+ *
+ * IMPORTANT — as of this writing, `"0.9.0"` is the only `configVersion` akm
+ * has ever shipped; there is no real prior release to shim. `"0.0.1"` below
+ * is a SYNTHETIC placeholder entry that exists solely to stand up and
+ * exercise this mechanism — the known-versions list, the dispatch table, the
+ * warn-once-and-upgrade behavior, the fail-closed behavior for anything
+ * else — before a real bump ever needs it (see
+ * `tests/integration/config-version-shim.test.ts` and the
+ * `previous-release-corpus.test.ts` fixture). When the first genuine
+ * `configVersion` bump ships, add its real old shape as its own entry the
+ * same way and delete the synthetic `"0.0.1"` entry (and this paragraph) in
+ * the same change.
+ */
+import { ConfigError } from "../errors.js";
+import { warn } from "../warn.js";
+import { CURRENT_CONFIG_VERSION } from "./schema/primitives.js";
+/**
+ * Every `configVersion` this binary can still READ, other than
+ * {@link CURRENT_CONFIG_VERSION} itself — each with an in-memory upgrade
+ * function in {@link CONFIG_VERSION_UPGRADES}. Anything not in this list (and
+ * not equal to current) fails closed.
+ */
+export const KNOWN_OLD_CONFIG_VERSIONS = ["0.0.1"];
+function isKnownOldConfigVersion(value) {
+    return typeof value === "string" && KNOWN_OLD_CONFIG_VERSIONS.includes(value);
+}
+/**
+ * SYNTHETIC 0.0.1 -> 0.9.0 upgrade (placeholder — see module doc). Per this
+ * placeholder, 0.0.1 kept the default LLM engine name at the config root as
+ * `defaultEngine`; 0.9.0 moved it under `defaults.llmEngine`. Pure function:
+ * takes the raw parsed JSON object, returns a new raw object with the 0.9.0
+ * shape. Never touches disk.
+ */
+function upgradeFrom080(raw) {
+    const { defaultEngine, defaults, ...rest } = raw;
+    if (typeof defaultEngine !== "string" || defaultEngine.length === 0) {
+        return { ...rest, ...(defaults !== undefined ? { defaults } : {}), configVersion: CURRENT_CONFIG_VERSION };
+    }
+    const existingDefaults = defaults !== null && typeof defaults === "object" ? defaults : {};
+    return {
+        ...rest,
+        configVersion: CURRENT_CONFIG_VERSION,
+        // An explicit `defaults.llmEngine` already present in the raw 0.0.1
+        // document (should never happen for a real 0.0.1 file, but a malformed
+        // one is possible) wins over the root-level field being migrated in.
+        defaults: { llmEngine: defaultEngine, ...existingDefaults },
+    };
+}
+const CONFIG_VERSION_UPGRADES = {
+    "0.0.1": upgradeFrom080,
+};
+function unsupportedConfigVersionError(rawVersion, sourcePath) {
+    const where = sourcePath ? ` at ${sourcePath}` : "";
+    const supported = [CURRENT_CONFIG_VERSION, ...KNOWN_OLD_CONFIG_VERSIONS].map((v) => `"${v}"`).join(", ");
+    return new ConfigError(`Unsupported configVersion${where}: got ${JSON.stringify(rawVersion)}, expected one of ${supported}.`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
+}
+/**
+ * Route a raw parsed config object through the version shim before schema
+ * validation. Returns a raw object whose `configVersion` is
+ * {@link CURRENT_CONFIG_VERSION} — either unchanged (already current),
+ * in-memory-upgraded (a known old version, with a one-line stderr warning),
+ * or this throws `UNSUPPORTED_CONFIG_VERSION` (unknown, newer, missing, or
+ * malformed).
+ */
+export function upgradeConfigVersion(raw, sourcePath) {
+    const version = raw.configVersion;
+    if (version === CURRENT_CONFIG_VERSION)
+        return raw;
+    if (isKnownOldConfigVersion(version)) {
+        const upgraded = CONFIG_VERSION_UPGRADES[version](raw);
+        warn(`Config${sourcePath ? ` at ${sourcePath}` : ""} uses configVersion "${version}" — auto-upgraded to ${CURRENT_CONFIG_VERSION} in memory; the next config write (e.g. \`akm config set\`) persists this and silences the warning.`);
+        return upgraded;
+    }
+    throw unsupportedConfigVersionError(version, sourcePath);
+}

package/dist/core/config/config.js

@@ -8,6 +8,7 @@ import { liftLegacyEngineExtraParams } from "../extra-params.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
 import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
 import { bundlesToSourceEntries } from "./config-sources.js";
+import { upgradeConfigVersion } from "./config-version-shim.js";
 import { deepMergeConfig } from "./deep-merge.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
@@ -138,14 +139,13 @@ export function acquireConfigReadFence() {
  * Parse raw config text and validate via Zod.
  * ({@link AkmConfigSchema}). Returns the merged-with-defaults AkmConfig.
  *
- * The schema accepts only the current config version and validates the
- * canonical shape before defaults are merged.
+ * The schema accepts only the current config version. A known older version
+ * is auto-upgraded in memory first (see `./config-version-shim`); anything
+ * else — including anything newer — is rejected before the canonical shape
+ * is validated.
  */
 export function parseAndValidateConfigText(text, sourcePath) {
-    const parsedRaw = parseConfigText(text, sourcePath);
-    if (parsedRaw.configVersion !== CURRENT_CONFIG_VERSION) {
-        throw new ConfigError(`Unsupported configVersion${sourcePath ? ` at ${sourcePath}` : ""}: expected "${CURRENT_CONFIG_VERSION}".`, "UNSUPPORTED_CONFIG_VERSION", "Recreate engines and improve.strategies manually for AKM 0.9.0; profile-based configuration is not translated automatically.");
-    }
+    const parsedRaw = upgradeConfigVersion(parseConfigText(text, sourcePath), sourcePath);
     // #852 (following #815): lift legacy `extraParams` keys — e.g.
     // `reasoning_effort`, a documented 0.9.1 workaround — onto the first-class
     // engine field they now shadow, before the protected-key check in
@@ -376,7 +376,7 @@ export function getIndexPassConfig(config, passName) {
     return entry;
 }
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
-export { bundleComponentConfig, bundleEntryToSourceEntry, bundlesToSourceEntries, installedSourceDescriptor, parseSourceSpec, primaryBundlePath, resolveConfiguredSources, } from "./config-sources.js";
+export { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleEntryToSourceEntry, bundleKeyForContentRoot, bundlesToSourceEntries, installedSourceDescriptor, parseSourceSpec, primaryBundlePath, resolveConfiguredSources, } from "./config-sources.js";
 /**
  * Merge a partial user-config override onto a base config. Used by
  * {@link loadUserConfig} (DEFAULT_CONFIG + on-disk) and {@link updateConfig}

package/dist/core/config/schema/engines.js

@@ -15,7 +15,7 @@ import { z } from "zod";
 // a config-schema ↔ config-types type cycle that collapses inference.
 import { HARNESS_AGENT_DISPATCH_IDS, VALID_HARNESS_IDS } from "../../../integrations/harnesses/ids.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
-import { chatCompletionsEndpoint, ENV_REFERENCE_PATTERN, ExtraParamsSchema, engineName, LlmCapabilitiesSchema, nonEmptyString, positiveInt, } from "./primitives.js";
+import { chatCompletionsEndpoint, ENV_REFERENCE_PATTERN, ExtraParamsSchema, engineName, nonEmptyString, positiveInt, } from "./primitives.js";
 /**
  * Engine-config timeouts share the workflow ceiling.
  *
@@ -43,16 +43,20 @@ export const LlmConnectionConfigSchema = z
     maxTokens: positiveInt.optional(),
     timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
-    capabilities: LlmCapabilitiesSchema.optional(),
+    // User-settable override, not a cached probe verdict: attempt-then-
+    // fallback in llm/client.ts tries `response_format: json_schema` whenever
+    // a schema is supplied, degrading to plain text on an unsupported-4xx and
+    // remembering that in-memory for the rest of the process. `false` here
+    // opts a known-incompatible endpoint out of even the first attempt;
+    // `true` is advisory only.
+    supportsJsonSchema: z.boolean().optional(),
     extraParams: ExtraParamsSchema.optional(),
     contextLength: positiveInt.optional(),
     enableThinking: z.boolean().optional(),
     reasoningEffort: nonEmptyString.optional(),
 })
     .passthrough();
-export const LlmProfileConfigSchema = LlmConnectionConfigSchema.extend({
-    supportsJsonSchema: z.boolean().optional(),
-}).passthrough();
+export const LlmProfileConfigSchema = LlmConnectionConfigSchema.passthrough();
 // ── Agent engines ───────────────────────────────────────────────────────────
 // Derives from the canonical VALID_HARNESS_IDS (#565) so the Zod gate cannot
 // drift from the TS union / parse check / setup detection.
@@ -68,7 +72,6 @@ const LlmEngineSchema = z
     maxTokens: positiveInt.optional(),
     timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
-    supportsJsonSchema: z.boolean().optional(),
     extraParams: ExtraParamsSchema.optional(),
     contextLength: positiveInt.optional(),
     enableThinking: z.boolean().optional(),
@@ -103,7 +106,6 @@ const AgentEngineSchema = z
         "temperature",
         "maxTokens",
         "concurrency",
-        "supportsJsonSchema",
         "extraParams",
         "contextLength",
         "enableThinking",

package/dist/core/config/schema/primitives.js

@@ -54,11 +54,6 @@ export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx)
     }
 });
 // ── Shared connection/invocation building blocks ────────────────────────────
-export const LlmCapabilitiesSchema = z
-    .object({
-    structuredOutput: z.boolean().optional(),
-})
-    .passthrough();
 export const LlmInvocationOverridesSchema = z
     .object({
     temperature: z.number().finite().optional(),