akm-cli 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.5] - 2026-06-09
+
+### Fixed
+
+- **Consolidation starved merge recall; the memory pool grew unbounded.** Commit
+  `633ece41` made the `incrementalSince` narrowing unconditional, so every
+  consolidation run only judged memories changed since the last run plus their
+  immediate vector-neighbors. Stale-but-unmerged duplicate clusters were never
+  re-examined, so the eligible pool grew monotonically and never shrank, and
+  contradiction detection (which rides on the consolidation pass) went dark.
+  Consolidation only runs on the nightly default-profile pass (`quick`/`frequent`
+  disable it), so a full-pool sweep is correct and affordable; the override is
+  removed. `lastConsolidateTs` still gates whether the pass runs.
+
+## [0.8.4] - 2026-06-08
+
+### Fixed
+
+- **`akm tasks sync` ignored schedule changes.** Sync classified any task already
+  present in the OS scheduler as "unchanged" without comparing its installed
+  entry, so editing a task's `schedule:` in the `.yml` never reached the crontab —
+  the only way to apply a new schedule was to `remove` and re-`add` the task. The
+  same gap affected `tasks enable`/`disable`, which merely toggled the existing
+  cron line's comment and so re-enabled a stale schedule. Sync now compares the
+  backend's installed signature against the signature the current definition would
+  produce and reinstalls on drift (reported in a new `updated[]` field);
+  `enable`/`disable` reinstall from the current `.yml` instead of toggling in
+  place. Backends that can't cheaply read their installed form fall back to an
+  idempotent reinstall, so the fix is correct on launchd/schtasks too. The cron
+  backend gains `expectedSignature()` and a signature on each `list()` entry.
+
+### Added
+
+- **`akm improve --skip-if-locked`.** When another improve run already holds the
+  lock, the run logs and exits 0 with a no-op result (`skipped.reason:
+  "lock-held"`) instead of failing with the "already running" config error
+  (exit 78). Intended for high-frequency scheduled runs (e.g. an every-30-min
+  `quick` pass) that would otherwise pile up exit-78 failures whenever a longer
+  run overlaps them. Default off — the hard error is preserved for interactive
+  use. The result is still recorded so the skip is auditable.
+
 ## [0.8.3] - 2026-06-08
 
 ### Fixed

package/dist/commands/improve-cli.js

@@ -54,6 +54,11 @@ export const improveCommand = defineCommand({
             description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
             default: false,
         },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
+            default: false,
+        },
         profile: {
             type: "string",
             description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
@@ -92,6 +97,7 @@ export const improveCommand = defineCommand({
             const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
             const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
             const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const skipIfLocked = getHyphenatedBoolean(args, "skip-if-locked");
             const profileArg = getStringArg(args, "profile");
             // Only set the keys the user actually passed (citty leaves the flag
             // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
@@ -167,6 +173,7 @@ export const improveCommand = defineCommand({
                     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
                     ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
                     ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(skipIfLocked ? { skipIfLocked } : {}),
                     ...(profileArg !== undefined ? { profile: profileArg } : {}),
                     ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
                     consolidateOptions: {

package/dist/commands/improve.js

@@ -435,7 +435,7 @@ export async function akmImprove(options = {}) {
         fs.mkdirSync(path.dirname(resolvedLockPath), { recursive: true });
         const lockPayload = () => JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
         if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
-            return;
+            return "acquired";
         // Lock file already exists — probe to determine whether it's still held
         // or whether the prior run died without cleaning up.
         const probe = probeLock(resolvedLockPath, { staleAfterMs: MAX_LOCK_AGE_MS });
@@ -470,9 +470,19 @@ export async function akmImprove(options = {}) {
             }
             releaseLock(resolvedLockPath);
             if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
-                return;
+                return "acquired";
+            // Lost the race to another run that grabbed the freed stale lock.
+            if (options.skipIfLocked) {
+                warn("[improve] another run acquired the lock during stale recovery; skipping (--skip-if-locked)");
+                return "skipped";
+            }
             throw new ConfigError(`akm improve is already running. Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
         }
+        // Lock is held by a live run within the staleness window.
+        if (options.skipIfLocked) {
+            warn(`[improve] another improve run holds the lock (PID ${lock?.pid}, started ${lock?.startedAt}); skipping (--skip-if-locked)`);
+            return "skipped";
+        }
         throw new ConfigError(`akm improve is already running (PID ${lock?.pid}, started ${lock?.startedAt}). Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
     };
     // Phase 4 lock-leak guard (§7 ordering hazard): hoisting `improve.lock` above
@@ -519,7 +529,21 @@ export async function akmImprove(options = {}) {
         // The dry-run branch below produces plannedRefs/memorySummary WITHOUT the lock
         // or triage (decision: dry-run never mutates the queue).
         if (!options.dryRun) {
-            acquireLock();
+            if (acquireLock() === "skipped") {
+                // Another improve holds the lock and the caller asked to skip rather
+                // than fail. Return a clean no-op result (exit 0) before any index/DB
+                // work — never registered the exit listener, never set lockAcquired,
+                // so we release nothing belonging to the run that owns the lock.
+                return {
+                    schemaVersion: 1,
+                    ok: true,
+                    scope,
+                    dryRun: false,
+                    skipped: { reason: "lock-held" },
+                    memorySummary: { eligible: 0, derived: 0 },
+                    plannedRefs: [],
+                };
+            }
             lockAcquired = true;
             // Backstop release on process.exit() (signal handler / budget watchdog),
             // which skips the finally below. Removed in that finally on the normal path.
@@ -2138,16 +2162,13 @@ async function runImprovePostLoopStage(args) {
             // Tie consolidate proposals back to this improve invocation so
             // accept-rate-per-run aggregation works. Mirrors reflect/propose/extract.
             sourceRun: `consolidate-${Date.now()}`,
-            // Incremental consolidation: pass the last-consolidation timestamp so
-            // akmConsolidate skips chunks with no memory changed since then. Converts
-            // consolidation cost from O(pool) to O(changed clusters) — the fix for
-            // the rising p95 tail where full-pool re-judging produced 5–10 min runs
-            // that promoted ~0. undefined → full pass on first-ever run (bootstrap).
-            // volumeTriggered correctly forces the run past cooldown but must NOT
-            // override incrementalSince — the stash has ~1400 eligible memories so
-            // volumeTriggered=true on every run, permanently forcing full 12-chunk
-            // scans (~264s) instead of the intended 1-2 chunk incremental path (~44s).
-            incrementalSince: lastConsolidateTs,
+            // Full-pool sweep: consolidation only runs on the nightly default-profile
+            // pass (quick/frequent disable it), so a complete re-cluster is correct and
+            // affordable here. Do NOT pass incrementalSince — the time-window narrowing
+            // it triggers permanently excludes stale-but-unmerged duplicate clusters,
+            // starving merge recall and letting the pool grow unbounded. (The narrowing
+            // was a band-aid for an every-30-min consolidation cadence that the profile
+            // split has since eliminated.) lastConsolidateTs still gates whether we run.
             maxChunkSize: improveProfile?.processes?.consolidate?.maxChunkSize,
             // Honor profile.autoAccept (already merged into options.autoAccept at the
             // top of akmImprove). The CLI parser always supplies 90 when --auto-accept

package/dist/commands/tasks.js

@@ -218,7 +218,13 @@ export async function akmTasksSetEnabled(id, enabled) {
     fs.writeFileSync(filePath, updated, "utf8");
     const sched = selectBackend();
     try {
-        await sched.setEnabled(normalised, enabled);
+        // Reinstall from the (just-updated) definition rather than only toggling
+        // the comment. A plain toggle leaves a stale schedule in place if the
+        // .yml's `schedule:` changed while the task was disabled — re-enabling
+        // would silently keep the old cron line. install() renders the block with
+        // both the current schedule and the new enabled state, and is idempotent.
+        const task = parseTaskDocument({ yaml: updated, filePath, id: normalised });
+        await sched.install(task);
     }
     catch (err) {
         // Roll the file back so the YAML source-of-truth and the OS
@@ -254,9 +260,12 @@ export async function akmTasksHistory(input) {
  * Reconcile the on-disk task files with the OS scheduler.
  *   • install missing tasks (after validating them — invalid files are
  *     skipped with a per-task reason rather than aborting the whole sync)
+ *   • reinstall tasks whose schedule or enabled state changed in the .yml
+ *     (drift detected by comparing the backend's installed signature against
+ *     the signature the current definition would produce)
  *   • remove orphan scheduler entries that no longer have a backing file
  */
-export async function akmTasksSync() {
+export async function akmTasksSync(deps = {}) {
     const stashDir = resolveStashDir();
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
@@ -267,10 +276,13 @@ export async function akmTasksSync() {
             .filter((f) => f.endsWith(".yml"))
             .map((f) => f.slice(0, -4))
         : [];
-    const sched = selectBackend();
+    const sched = deps.backend ?? selectBackend();
     const backend = backendNameForPlatform();
-    const present = new Set((await sched.list()).map((t) => t.id));
+    // Map id → installed signature so sync can detect schedule/enabled drift on
+    // tasks that already exist in the scheduler, not just presence/absence.
+    const present = new Map((await sched.list()).map((t) => [t.id, t.signature]));
     const installed = [];
+    const updated = [];
     const unchanged = [];
     const skipped = [];
     for (const id of fileIds) {
@@ -290,22 +302,34 @@ export async function akmTasksSync() {
             skipped.push({ id, reason: err instanceof Error ? err.message : String(err) });
             continue;
         }
-        if (present.has(id)) {
+        if (!present.has(id)) {
+            await sched.install(task);
+            installed.push(id);
+            continue;
+        }
+        // Already installed — reconcile against the current definition. Compare the
+        // installed signature to what this task would render to; reinstall on drift.
+        // When the backend can't produce a signature (no expectedSignature, or it
+        // didn't record one), reinstall unconditionally — install() is idempotent,
+        // so the cost is one crontab write and correctness is guaranteed.
+        const installedSig = present.get(id);
+        const expectedSig = sched.expectedSignature?.(task);
+        if (installedSig !== undefined && expectedSig !== undefined && installedSig === expectedSig) {
             unchanged.push(id);
         }
         else {
             await sched.install(task);
-            installed.push(id);
+            updated.push(id);
         }
     }
     const removed = [];
-    for (const installedId of present) {
+    for (const installedId of present.keys()) {
         if (!fileIds.includes(installedId)) {
             await sched.uninstall(installedId);
             removed.push(installedId);
         }
     }
-    return { installed, removed, unchanged, skipped, backend: sched.name };
+    return { installed, updated, removed, unchanged, skipped, backend: sched.name };
 }
 export async function akmTasksDoctor() {
     const warnings = [];

package/dist/tasks/backends/cron.js

@@ -64,13 +64,11 @@ export function CRON_BACKEND(options = {}) {
         },
         list() {
             const existing = readCrontab(exec);
-            const ids = [];
-            for (const line of existing.split(/\r?\n/)) {
-                const m = line.match(BLOCK_RE);
-                if (m)
-                    ids.push(m[1]);
-            }
-            return ids.map((id) => ({ id }));
+            return listBlocks(existing).map(({ id, body }) => ({ id, signature: normalizeSignature(body) }));
+        },
+        expectedSignature(task) {
+            const cronLine = buildCronLine(task, akmArgv, logDir);
+            return normalizeSignature(cronBlockBody(cronLine, task.enabled));
         },
     };
 }
@@ -82,9 +80,48 @@ export function buildCronLine(task, akmArgv, logDir) {
     const cmd = [...akmArgv, "tasks", "run", task.id].map((part) => quoteForCron(part)).join(" ");
     return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
 }
+/** The crontab line as it appears inside a block — commented when disabled. */
+export function cronBlockBody(cronLine, enabled) {
+    return enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
+}
 export function renderBlock(id, cronLine, enabled) {
-    const body = enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
-    return [BEGIN(id), body, END(id)].join("\n");
+    return [BEGIN(id), cronBlockBody(cronLine, enabled), END(id)].join("\n");
+}
+/**
+ * Parse the akm-owned blocks out of a crontab, returning each task id with the
+ * raw body line(s) between its BEGIN/END markers. Used by `list()` to build a
+ * drift signature, and exported for tests.
+ */
+export function listBlocks(existing) {
+    const out = [];
+    const lines = existing.split(/\r?\n/);
+    let currentId = null;
+    let body = [];
+    for (const line of lines) {
+        const begin = line.match(BLOCK_RE);
+        if (begin) {
+            currentId = begin[1];
+            body = [];
+            continue;
+        }
+        if (currentId !== null && line === END(currentId)) {
+            out.push({ id: currentId, body: body.join("\n") });
+            currentId = null;
+            body = [];
+            continue;
+        }
+        if (currentId !== null)
+            body.push(line);
+    }
+    return out;
+}
+/** Collapse incidental whitespace so signature comparison ignores it. */
+function normalizeSignature(body) {
+    return body
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .join("\n");
 }
 export function upsertBlock(existing, id, block) {
     const trimmed = existing.replace(/\s+$/g, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [