akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/commands/tasks/tasks.js

@@ -17,7 +17,6 @@ import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
-import { listAgentProfileNames } from "../../integrations/agent/index.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
@@ -25,7 +24,7 @@ import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
-import { resolveImproveProfile } from "../improve/improve-profiles.js";
+import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 export async function akmTasksAdd(input) {
     const id = normaliseTaskId(input.id);
     const hasCommand = input.command !== undefined &&
@@ -36,6 +35,12 @@ export async function akmTasksAdd(input) {
     if (targetCount !== 1) {
         throw new UsageError("Pass exactly one of --workflow <ref>, --prompt <asset-ref|./file.md|text>, or --command <shell-command>.", "INVALID_FLAG_VALUE");
     }
+    if (input.workflow && (input.engine !== undefined || input.model !== undefined || input.timeoutMs !== undefined)) {
+        throw new UsageError("Workflow tasks accept only --params; engine, model, and timeout are prompt-task fields.", "INVALID_FLAG_VALUE");
+    }
+    if (hasCommand && (input.engine !== undefined || input.model !== undefined)) {
+        throw new UsageError("Command tasks accept --timeout-ms but not --engine or --model.", "INVALID_FLAG_VALUE");
+    }
     // Validate the schedule for the active backend before writing anything.
     const backend = backendNameForPlatform();
     parseSchedule(input.schedule, backend);
@@ -56,7 +61,9 @@ export async function akmTasksAdd(input) {
         workflow: input.workflow,
         prompt: input.prompt,
         command: input.command,
-        profile: input.profile,
+        engine: input.engine,
+        model: input.model,
+        timeoutMs: input.timeoutMs,
         params: input.params,
         name: input.name,
         description: input.description,
@@ -137,11 +144,12 @@ export async function akmTasksList() {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
     if (!fs.existsSync(typeRoot))
-        return { tasks: [] };
+        return { tasks: [], stale: [] };
     const entries = fs.readdirSync(typeRoot);
     warnLegacyMdTaskFiles(typeRoot);
     const files = entries.filter((f) => f.endsWith(".yml"));
     const tasks = [];
+    const stale = [];
     for (const file of files) {
         const id = file.slice(0, -4);
         const filePath = path.join(typeRoot, file);
@@ -149,7 +157,9 @@ export async function akmTasksList() {
         try {
             task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
         }
-        catch {
+        catch (err) {
+            if (isStaleTaskError(err))
+                stale.push(id);
             continue; // skip malformed files; `akm tasks show <id>` will surface the error
         }
         tasks.push({
@@ -165,7 +175,9 @@ export async function akmTasksList() {
             tags: task.tags,
         });
     }
-    return { tasks };
+    if (stale.length > 0)
+        warnStaleTaskFiles(stale);
+    return { tasks, stale };
 }
 export async function akmTasksShow(id) {
     const normalised = normaliseTaskId(id);
@@ -234,6 +246,9 @@ export async function akmTasksSetEnabled(id, enabled) {
         warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const yaml = fs.readFileSync(filePath, "utf8");
+    // Parse before writing so stale v1 tasks are diagnosed without changing the
+    // source file or its installed scheduler entry.
+    parseTaskDocument({ yaml, filePath, id: normalised });
     const updated = setEnabledInYaml(yaml, enabled);
     const ref = taskAssetRef(normalised);
     await writeAssetToSource(target.source, target.config, ref, updated);
@@ -374,16 +389,15 @@ export async function akmTasksDoctor() {
     }
     const backend = backendNameForPlatform();
     const config = loadConfig();
-    // v2: prefer profiles.agent / defaults.agent; fall back to legacy agent.default
-    const defaultProfile = config.defaults?.agent;
-    const profiles = config.profiles?.agent ? Object.keys(config.profiles.agent) : listAgentProfileNames(config);
+    const defaultEngine = config.defaults?.engine;
+    const engines = Object.keys(config.engines ?? {});
     // §6.1: surface the effective triage settings for the default improve
-    // profile. The struct is a fixed shape, so this is a deliberate addition.
-    const improveProfileName = typeof config.defaults?.improve === "string" ? config.defaults.improve : "default";
-    const triage = resolveImproveProfile(config.defaults?.improve, config).processes?.triage;
+    // strategy. The struct is a fixed shape, so this is a deliberate addition.
+    const improveStrategyName = typeof config.defaults?.improveStrategy === "string" ? config.defaults.improveStrategy : "default";
+    const triage = resolveImproveStrategy(config.defaults?.improveStrategy, config).config.processes?.triage;
     const improveTriage = triage
         ? {
-            defaultProfile: improveProfileName,
+            defaultStrategy: improveStrategyName,
             enabled: triage.enabled === true,
             applyMode: triage.applyMode ?? "queue",
             policy: triage.policy ?? "personal-stash",
@@ -394,7 +408,9 @@ export async function akmTasksDoctor() {
         akm: invocation,
         logDir: getTaskLogDir(),
         historyDir: getTaskHistoryDir(),
-        agent: { defaultProfile, available: profiles },
+        engine: { defaultEngine, available: engines },
+        stale: collectStaleTaskIds(),
+        staleGeneratedCommands: collectStaleGeneratedCommands(),
         scheduleSubset: SCHEDULE_SUPPORTED_SUBSET_HINT,
         warnings,
         ...(improveTriage ? { improveTriage } : {}),
@@ -421,7 +437,7 @@ function resolveTaskWriteTarget() {
     return resolveWriteTarget(loadConfig());
 }
 function renderTaskYaml(input) {
-    const obj = { schedule: input.schedule };
+    const obj = { version: 2, schedule: input.schedule, enabled: input.enabled };
     if (input.workflow) {
         obj.workflow = input.workflow;
         if (input.params) {
@@ -430,16 +446,21 @@ function renderTaskYaml(input) {
     }
     else if (input.prompt) {
         obj.prompt = input.prompt;
-        if (input.profile)
-            obj.profile = input.profile;
+        if (input.engine)
+            obj.engine = input.engine;
+        if (input.model)
+            obj.model = input.model;
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
     else if (input.command !== undefined) {
         // Emit a string when given a string, an array when given an array. The
         // parser accepts both forms; preserving the caller's shape keeps the YAML
         // ergonomic for humans editing the file later.
         obj.command = input.command;
+        if (input.timeoutMs !== undefined)
+            obj.timeoutMs = input.timeoutMs;
     }
-    obj.enabled = input.enabled;
     if (input.name)
         obj.name = input.name;
     if (input.description)
@@ -450,6 +471,80 @@ function renderTaskYaml(input) {
         obj.tags = input.tags;
     return yamlStringify(obj);
 }
+function isStaleTaskError(err) {
+    return err instanceof UsageError && err.code === "TASK_SCHEMA_VERSION_UNSUPPORTED";
+}
+function warnStaleTaskFiles(ids) {
+    process.stderr.write(`WARNING: ${ids.length} task file(s) use retired task schema v1 and were not loaded.\n` +
+        `         Rewrite them with version: 2 and replace profile with engine. See docs/migration/v0.8-to-v0.9.md#task-assets.\n` +
+        `         Affected: ${ids.map((id) => `tasks/${id}.yml`).join(", ")}\n`);
+}
+function collectStaleTaskIds() {
+    const typeRoot = path.join(resolveStashDir(), "tasks");
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const stale = [];
+    for (const file of fs.readdirSync(typeRoot)) {
+        if (!file.endsWith(".yml"))
+            continue;
+        const id = file.slice(0, -4);
+        try {
+            parseTaskDocument({
+                yaml: fs.readFileSync(path.join(typeRoot, file), "utf8"),
+                filePath: path.join(typeRoot, file),
+                id,
+            });
+        }
+        catch (err) {
+            if (isStaleTaskError(err))
+                stale.push(id);
+        }
+    }
+    return stale;
+}
+const STALE_GENERATED_COMMANDS = {
+    "akm-improve-frequent": {
+        command: "akm improve --profile frequent --auto-accept safe",
+        replacement: "akm improve --strategy frequent --auto-accept safe",
+    },
+    "akm-improve-consolidate": {
+        command: "akm improve --profile consolidate --auto-accept safe",
+        replacement: "akm improve --strategy consolidate --auto-accept safe",
+    },
+    "akm-improve-nightly": {
+        command: "akm improve --profile thorough --auto-accept safe",
+        replacement: "akm improve --strategy thorough --auto-accept safe",
+    },
+    "akm-improve-catchup": {
+        command: "akm improve --profile catchup --auto-accept safe",
+        replacement: "akm improve --strategy catchup --auto-accept safe",
+    },
+    "akm-graph-refresh-weekly": {
+        command: "akm improve --profile graph-refresh --auto-accept safe",
+        replacement: "akm improve --strategy graph-refresh --auto-accept safe",
+    },
+};
+function collectStaleGeneratedCommands() {
+    const typeRoot = path.join(resolveStashDir(), "tasks");
+    if (!fs.existsSync(typeRoot))
+        return [];
+    const stale = [];
+    for (const [id, expected] of Object.entries(STALE_GENERATED_COMMANDS)) {
+        const filePath = path.join(typeRoot, `${id}.yml`);
+        if (!fs.existsSync(filePath))
+            continue;
+        try {
+            const task = parseTaskDocument({ yaml: fs.readFileSync(filePath, "utf8"), filePath, id });
+            if (task.target.kind === "command" && task.target.cmd.join(" ") === expected.command) {
+                stale.push({ id, replacement: expected.replacement });
+            }
+        }
+        catch {
+            // Stale-schema reporting owns files that cannot be parsed.
+        }
+    }
+    return stale;
+}
 function parseJsonObjectArg(raw) {
     let parsed;
     try {

package/dist/commands/wiki-cli.js

@@ -220,13 +220,13 @@ const wikiLintCommand = defineCommand({
 const wikiIngestCommand = defineJsonCommand({
     meta: {
         name: "ingest",
-        description: "Dispatch an agent to execute the ingest workflow for this wiki. Uses --profile or config.defaults.agent.",
+        description: "Dispatch an agent to execute the ingest workflow for this wiki. Uses --engine or config.defaults.engine.",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
-        profile: {
+        engine: {
             type: "string",
-            description: "Agent profile to use (default: config.defaults.agent).",
+            description: "Agent engine to use (default: config.defaults.engine).",
         },
         model: {
             type: "string",
@@ -239,17 +239,15 @@ const wikiIngestCommand = defineJsonCommand({
         const stashDir = resolveStashDir();
         const built = buildIngestWorkflow(stashDir, args.name);
         const config = loadConfig();
-        const profileName = getStringArg(args, "profile") ?? config.defaults?.agent;
-        if (!profileName) {
-            throw new UsageError("akm wiki ingest requires an agent profile. Pass --profile <name> or set defaults.agent in config.", "MISSING_REQUIRED_ARGUMENT", "Available profiles are listed under profiles.agent in your config. Run `akm config get profiles.agent` to inspect.");
+        const engine = getStringArg(args, "engine") ?? config.defaults?.engine;
+        if (!engine) {
+            throw new UsageError("akm wiki ingest requires an agent engine. Pass --engine <name> or set defaults.engine in config.", "MISSING_REQUIRED_ARGUMENT", "Available engines are listed under engines in your config. Run `akm config get engines` to inspect.");
         }
         const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
         const model = getStringArg(args, "model");
-        const { getDefaultLlmConfig } = await import("../core/config/config.js");
         const dispatchResult = await akmAgentDispatch({
-            profileName,
+            engine,
             agentConfig: config,
-            llmConfig: getDefaultLlmConfig(config),
             prompt: built.workflow,
             dispatch: {
                 prompt: built.workflow,
@@ -258,11 +256,12 @@ const wikiIngestCommand = defineJsonCommand({
             ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
         });
         output("wiki-ingest", {
+            schemaVersion: 2,
             wiki: built.wiki,
             path: built.path,
             schemaPath: built.schemaPath,
             dispatched: true,
-            profile: profileName,
+            engine,
             agentResult: dispatchResult,
         });
     },

package/dist/core/asset/frontmatter.js

@@ -10,7 +10,7 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
-import { assembleAsset } from "./asset-serialize.js";
+import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
  *
@@ -118,6 +118,13 @@ function parseFrontmatterLenient(frontmatter) {
  * or `null` to skip the write entirely (e.g. for idempotent no-ops). The body
  * content is preserved from the parse.
  *
+ * A frontmatter mutation is a METADATA edit, not a content edit: when the file
+ * already has a frontmatter block, only that block is replaced and the body
+ * bytes are kept verbatim (routing through `assembleAsset` would strip the
+ * body's leading blank lines and force a trailing newline, silently reshaping
+ * assets whose writer used a different separator style). A file gaining its
+ * FIRST frontmatter block goes through the canonical `assembleAsset` shape.
+ *
  * @returns `true` if a write occurred, `false` if the mutator returned `null`.
  */
 export function mutateFrontmatter(filePath, mutator) {
@@ -126,7 +133,10 @@ export function mutateFrontmatter(filePath, mutator) {
     const nextFrontmatter = mutator(parsed);
     if (nextFrontmatter === null)
         return false;
-    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    const next = parsed.frontmatter !== null
+        ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
+        : assembleAsset(nextFrontmatter, parsed.content);
+    fs.writeFileSync(filePath, next, "utf8");
     return true;
 }
 export function parseFrontmatterBlock(raw) {

package/dist/core/common.js

@@ -243,11 +243,12 @@ function normalizeFsPathForComparison(value) {
  */
 export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = timeoutMs === null ? undefined : setTimeout(() => controller.abort(), timeoutMs);
     const abortExternal = () => controller.abort(signal?.reason);
     if (signal) {
         if (signal.aborted) {
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             controller.abort(signal.reason);
         }
         else {
@@ -269,7 +270,8 @@ export async function fetchWithTimeout(url, opts, timeoutMs = 30_000, signal) {
     finally {
         if (signal)
             signal.removeEventListener("abort", abortExternal);
-        clearTimeout(timer);
+        if (timer)
+            clearTimeout(timer);
     }
 }
 /**

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

@@ -17,7 +17,7 @@ import path from "node:path";
 import { sleepSync } from "../../runtime.js";
 import { writeFileAtomic } from "../common.js";
 import { ConfigError } from "../errors.js";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../file-lock.js";
 import { getCacheDir, getConfigDir } from "../paths.js";
 /**
  * Read the raw text of a config file. Returns `undefined` when the file does
@@ -80,7 +80,7 @@ export function writeConfigAtomic(configPath, config) {
 }
 /** Maximum number of timestamped config backups to retain (#459). */
 const MAX_CONFIG_BACKUPS = 5;
-export function backupExistingConfig(configPath) {
+export function backupExistingConfig(configPath, now = new Date()) {
     if (!fs.existsSync(configPath))
         return undefined;
     const backupDir = path.join(getCacheDir(), "config-backups");
@@ -89,10 +89,22 @@ export function backupExistingConfig(configPath) {
     // the copy→chmod window. chmod again to tighten a dir from an older version.
     fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
     fs.chmodSync(backupDir, 0o700);
-    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    const timestamped = path.join(backupDir, `config-${timestamp}.json`);
+    const timestamp = now.toISOString().replace(/[.:]/g, "-");
+    let sequence = 0;
+    let timestamped;
+    while (true) {
+        timestamped = path.join(backupDir, `config-${timestamp}${sequence === 0 ? "" : `-${sequence}`}.json`);
+        try {
+            fs.copyFileSync(configPath, timestamped, fs.constants.COPYFILE_EXCL);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            sequence++;
+        }
+    }
     const latest = path.join(backupDir, "config.latest.json");
-    fs.copyFileSync(configPath, timestamped);
     fs.copyFileSync(configPath, latest);
     // 08-F4: a config backup carries the same sensitive fields as the live config
     // (endpoints, tokens). `copyFileSync` inherits the source's (often 0644) mode,
@@ -141,7 +153,7 @@ function pruneOldBackups(backupDir) {
  * predictable for debugging. Uses $CONFIG (not $DATA) because config.json
  * itself lives in $CONFIG — they should fail together if the dir is read-only.
  */
-function getConfigLockPath() {
+export function getConfigLockPath() {
     return path.join(getConfigDir(), "config.json.lck");
 }
 const CONFIG_LOCK_MAX_RETRIES = 10;
@@ -157,8 +169,8 @@ function sleepSyncMs(ms) {
 /**
  * Acquire an exclusive sentinel around config writes.
  *
- * Returns a release function. Best-effort: when all retries are exhausted the
- * write proceeds unlocked rather than erroring (same posture as lockfile.ts).
+ * Returns a release function. Acquisition is fail-closed: config mutation may
+ * never continue without owning the lock that protects its read/merge/write.
  */
 export function acquireConfigLock() {
     const lockPath = getConfigLockPath();
@@ -170,16 +182,16 @@ export function acquireConfigLock() {
     }
     for (let attempt = 0; attempt < CONFIG_LOCK_MAX_RETRIES; attempt++) {
         try {
-            if (tryAcquireLockSync(lockPath, String(process.pid))) {
-                return () => releaseLock(lockPath);
+            const ownership = tryAcquireLockSync(lockPath, createLockPayload());
+            if (ownership) {
+                return () => releaseLock(ownership);
             }
         }
-        catch {
-            // Non-EEXIST error (permissions, etc.) — bail out and proceed unlocked.
-            break;
+        catch (error) {
+            throw new ConfigError(`Unable to acquire config lock at ${lockPath}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
         }
-        if (probeLock(lockPath).state === "stale") {
-            releaseLock(lockPath);
+        const probe = probeLock(lockPath);
+        if (probe.state === "stale" && reclaimStaleLock(lockPath, probe)) {
             continue; // Reclaimed — retry immediately.
         }
         if (attempt < CONFIG_LOCK_MAX_RETRIES - 1) {
@@ -195,8 +207,7 @@ export function acquireConfigLock() {
             sleepSyncMs(CONFIG_LOCK_RETRY_DELAY_MS);
         }
     }
-    // Best-effort: proceed without lock.
-    return () => { };
+    throw new ConfigError(`Timed out waiting for config lock at ${lockPath}. Another AKM process may be updating config.`, "INVALID_CONFIG_FILE");
 }
 /**
  * Run `fn` inside the config write lock. Always releases the lock.