akm-cli 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.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
+
+- **`improve.lock` leaked on signal death (cron timeout).** The improve
+  SIGTERM/SIGINT/SIGHUP handler calls `process.exit()`, which skips `finally`
+  blocks — so the `finally` that releases `improve.lock` never ran, and every
+  timed-out cron run leaked the lock sentinel. (It wasn't a permanent deadlock
+  only because the next run reclaims a dead-PID lock, a path that PID reuse can
+  defeat.) The lock is now released from a `process.on("exit", …)` handler
+  registered at acquire time (exit handlers DO run on `process.exit()`), via a
+  new ownership-checked `releaseLockIfOwned(path, pid)` so a backstop release can
+  never delete a different run's lock. This generalizes to the budget watchdog
+  and any future exit path.
+- **`quick` profile was not quick.** It was documented "Reflect-only" but did
+  not disable the session-`extract` process (which is default-ON), so a `quick`
+  run processed the entire unindexed-session backlog (~40 min) — guaranteeing a
+  5-minute cron timeout → SIGTERM → the lock leak above, every run. `quick` now
+  explicitly sets `processes.extract.enabled: false`.
+
 ## [0.8.2] - 2026-06-05
 
 ### Added

package/dist/assets/profiles/quick.json

@@ -1,10 +1,11 @@
 {
-  "description": "Reflect-only pass — no distill, consolidate, memoryInference, or graphExtraction.",
+  "description": "Reflect-only pass — no extract, distill, consolidate, memoryInference, or graphExtraction.",
   "processes": {
     "reflect": {
       "enabled": true,
       "allowedTypes": ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"]
     },
+    "extract": { "enabled": false },
     "distill": { "enabled": false },
     "consolidate": { "enabled": false },
     "memoryInference": { "enabled": false },

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

@@ -8,7 +8,7 @@ import { daysToMs, isAssetType } from "../core/common";
 import { getDefaultLlmConfig, loadConfig } from "../core/config";
 import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
+import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../core/file-lock";
 import { parseFrontmatter } from "../core/frontmatter";
 import { detectAndWriteContradictions } from "../core/memory-contradiction-detect";
 import { analyzeMemoryCleanup, applyMemoryCleanup, } from "../core/memory-improve";
@@ -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
@@ -497,6 +507,17 @@ export async function akmImprove(options = {}) {
         }
         lockAcquired = false;
     };
+    // Signal-safe lock release (0.8.3 hotfix). The SIGTERM/SIGINT/SIGHUP handler
+    // in improve-cli.ts calls `process.exit()`, which does NOT run the `finally`
+    // below that owns lock release — so a cron-timeout SIGTERM leaked
+    // `improve.lock` every run. `process.exit()` DOES fire `'exit'` listeners,
+    // so we release the lock from one. `releaseLockIfOwned` only unlinks a lock
+    // still owned by this PID, so it is safe even if a later run re-acquired it.
+    // The listener is removed in the `finally` so the normal path stays single-release
+    // and repeated in-process `akmImprove` calls (tests) do not accumulate listeners.
+    const releaseLockOnExit = () => {
+        releaseLockIfOwned(resolvedLockPath, process.pid);
+    };
     const preEnsureCleanupWarnings = [];
     let plannedRefs;
     let memorySummary;
@@ -508,8 +529,25 @@ 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.
+            process.on("exit", releaseLockOnExit);
             // Phase 4 triage pre-pass (§7, §13): drain the standing pending backlog
             // BEFORE ensureIndex so improve generates fresh proposals against a cleared
             // queue (no `duplicate_pending` collisions) and ensureIndex absorbs triage's
@@ -922,6 +960,9 @@ export async function akmImprove(options = {}) {
         catch {
             // ignore
         }
+        // The normal path released the lock above; drop the process.exit backstop so
+        // it does not fire later (or accumulate across repeated in-process calls).
+        process.removeListener("exit", releaseLockOnExit);
         // I1: close the long-lived state.db connection opened at the top of the run.
         try {
             eventsDb?.close();

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/core/file-lock.js

@@ -79,6 +79,28 @@ export function releaseLock(lockPath) {
         // Sentinel already gone — fine.
     }
 }
+/**
+ * Release a lock ONLY if it is still owned by `ownerPid`. Safe to call from a
+ * `process.exit()` / `'exit'` handler as a backstop: `process.exit()` skips
+ * `finally` blocks — so the normal lock-release never runs on signal death
+ * (SIGTERM/SIGINT) — but it DOES fire `'exit'` listeners synchronously. Checking
+ * ownership first means that if the lock was already released and re-acquired by
+ * a different process, this leaves that process's lock intact (no cross-run
+ * deletion / PID-reuse footgun). Synchronous so it is valid inside an exit handler.
+ */
+export function releaseLockIfOwned(lockPath, ownerPid) {
+    let rawContent;
+    try {
+        rawContent = fs.readFileSync(lockPath, "utf8");
+    }
+    catch {
+        // Absent or unreadable — nothing of ours to release.
+        return;
+    }
+    if (extractHolderPid(rawContent) === ownerPid) {
+        releaseLock(lockPath);
+    }
+}
 /**
  * Extract a PID from a sentinel body. Accepts the two shapes used across
  * the codebase: a bare numeric string (config-io, vault, lockfile) and

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.2",
+  "version": "0.8.4",
   "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": [