akm-cli 0.9.10 → 0.9.12

package/dist/storage/repositories/index-connection.js

@@ -15,12 +15,12 @@ import { createRequire } from "node:module";
 import { ConfigError } from "../../core/errors.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
+import { warn, warnOnce } from "../../core/warn.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
 import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
-import { openSqliteReadSnapshot } from "../sqlite-read-snapshot.js";
-import { isCanonicalIndexGeneration } from "./index-entry-schema.js";
+import { openSqliteReadSnapshot, SqliteReadSnapshotUnavailableError } from "../sqlite-read-snapshot.js";
+import { CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration } from "./index-entry-schema.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 /**
@@ -130,15 +130,19 @@ export function openExistingDatabase(dbPath) {
         path: resolvedPath,
         init: (db) => {
             loadVecExtension(db);
-            assertCanonicalIndexGeneration(db, resolvedPath);
+            warnIfNonCanonicalIndexGeneration(db, resolvedPath);
         },
         create: false,
     });
 }
-function assertCanonicalIndexGeneration(db, resolvedPath) {
+function warnIfNonCanonicalIndexGeneration(db, resolvedPath) {
     if (isCanonicalIndexGeneration(db))
         return;
-    throw new ConfigError(`Index database uses an incompatible derived schema: ${resolvedPath}.`, "INDEX_SCHEMA_INCOMPATIBLE");
+    const classification = classifyIndexGeneration(db);
+    warnOnce(`index-read-noncanonical:${resolvedPath}`, `Index database at ${resolvedPath} does not match this akm's derived schema (stored generation ` +
+        `${classification.storedVersion ?? "unknown"}; this binary understands ${CANONICAL_INDEX_DB_VERSION}). ` +
+        "Reading it as-is; a query that needs a table or column this generation lacks will fail on its own. " +
+        "Run 'akm index' to rebuild it for this binary.");
 }
 /**
  * Refuse to treat an UNREADABLE index as a missing one (#791).
@@ -160,6 +164,21 @@ export function assertIndexPathReadable(resolvedPath) {
         return;
     throw new ConfigError(`Index database exists but is not readable: ${describeInaccessiblePath(resolvedPath, code)}.`, "DATA_DIR_UNREADABLE");
 }
+function openPlainReadonly(resolvedPath) {
+    return openDatabase(resolvedPath, { readonly: true, create: false });
+}
+function openIsolatedSnapshotOrFallBack(resolvedPath) {
+    try {
+        return openSqliteReadSnapshot(resolvedPath);
+    }
+    catch (error) {
+        if (!(error instanceof SqliteReadSnapshotUnavailableError))
+            throw error;
+        warnOnce(`index-read-snapshot-unavailable:${resolvedPath}`, `Could not take a non-mutating snapshot of ${resolvedPath} (${error.message}) — falling back to a plain ` +
+            "read-only open of the index database.");
+        return openPlainReadonly(resolvedPath);
+    }
+}
 /**
  * Open an existing index for queries without changing the source database or
  * running schema initialization. The default path attaches read-only to the
@@ -173,9 +192,7 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     assertIndexPathReadable(resolvedPath);
     if (classifyPathAccess(resolvedPath).access === "absent")
         return undefined;
-    const db = options?.isolatedSnapshot
-        ? openSqliteReadSnapshot(resolvedPath)
-        : openDatabase(resolvedPath, { readonly: true, create: false });
+    const db = options?.isolatedSnapshot ? openIsolatedSnapshotOrFallBack(resolvedPath) : openPlainReadonly(resolvedPath);
     if (!db)
         return undefined;
     // This opener bypasses openManagedDatabase/applyStandardPragmas by design (no
@@ -187,7 +204,7 @@ export function openReadonlyExistingDatabase(dbPath, options) {
     // connection, so apply just that one.
     try {
         db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
-        assertCanonicalIndexGeneration(db, resolvedPath);
+        warnIfNonCanonicalIndexGeneration(db, resolvedPath);
         return db;
     }
     catch (error) {

package/dist/storage/repositories/index-entry-schema.js

@@ -244,10 +244,27 @@ export function hasCanonicalEntrySchema(db) {
         return false;
     }
 }
-export function isCanonicalIndexGeneration(db) {
+export function classifyIndexGeneration(db) {
+    let storedVersion;
     try {
         const row = db.prepare("SELECT value FROM index_meta WHERE key = 'version'").get();
-        return row?.value === String(CANONICAL_INDEX_DB_VERSION) && hasCanonicalEntrySchema(db);
+        storedVersion = row?.value;
+    }
+    catch {
+        storedVersion = undefined;
+    }
+    if (storedVersion === String(CANONICAL_INDEX_DB_VERSION) && hasCanonicalEntrySchema(db)) {
+        return { status: "canonical", storedVersion };
+    }
+    const storedNumeric = storedVersion === undefined ? undefined : Number(storedVersion);
+    if (storedNumeric !== undefined && Number.isFinite(storedNumeric) && storedNumeric > CANONICAL_INDEX_DB_VERSION) {
+        return { status: "newer", storedVersion };
+    }
+    return { status: "older", storedVersion };
+}
+export function isCanonicalIndexGeneration(db) {
+    try {
+        return classifyIndexGeneration(db).status === "canonical";
     }
     catch {
         return false;

package/dist/storage/repositories/index-schema.js

@@ -1,7 +1,18 @@
 // 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/.
-import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
+/**
+ * index.db schema and version stamps, kept in the
+ * storage layer. This isolates the one genuinely risky area (schema
+ * evolution) from the CRUD/FTS/vector queries.
+ *
+ * The meta accessors, embedding purge, and vec-availability probe that
+ * `ensureSchema` leans on live in the sibling `index-meta-repository` /
+ * `index-vec-repository` modules.
+ */
+import { ConfigError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
+import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 import { isVecAvailable, purgeEmbeddings } from "./index-vec-repository.js";
 // ── Constants ───────────────────────────────────────────────────────────────
@@ -165,6 +176,15 @@ function rebuildIncompatibleIndexGeneration(db) {
         return;
     if (isCanonicalIndexGeneration(db))
         return;
+    const classification = classifyIndexGeneration(db);
+    if (classification.status === "newer") {
+        throw new ConfigError(`Index database was built by a newer akm (stored generation ${classification.storedVersion ?? "unknown"}; ` +
+            `this binary understands generation ${CANONICAL_INDEX_DB_VERSION}). Refusing to modify it — upgrade akm to ` +
+            "write to this index, or delete index.db to rebuild it from scratch with this binary.", "INDEX_SCHEMA_INCOMPATIBLE");
+    }
+    warn(`Index database generation ${classification.storedVersion ?? "unknown"} is older than this akm's generation ` +
+        `${CANONICAL_INDEX_DB_VERSION} — rebuilding the derived index (entries, FTS, embeddings, graph tables, ` +
+        "utility scores, and the LLM enrichment cache). This re-walks and re-indexes every source on the next run.");
     let vecResetPending = false;
     try {
         db.exec("DROP TABLE IF EXISTS entries_vec");
@@ -326,12 +346,16 @@ export function ensureSchema(db, embeddingDim) {
     //   - When `embeddingDim` is a number, the caller explicitly asked for
     //     that dim and owns the dim-change/backup/wipe semantics.
     const dimExplicit = embeddingDim !== undefined;
-    const effectiveDim = embeddingDim ?? (Number(getMeta(db, "embeddingDim")) || EMBEDDING_DIM);
+    const requestedDim = embeddingDim ?? (Number(getMeta(db, "embeddingDim")) || EMBEDDING_DIM);
+    const effectiveDim = Number.isInteger(requestedDim) && requestedDim > 0 ? requestedDim : EMBEDDING_DIM;
+    if (effectiveDim !== requestedDim) {
+        warn(`Invalid embedding dimension ${requestedDim} — falling back to the default (${EMBEDDING_DIM}).`);
+    }
     if (isVecAvailable(db)) {
         // Check if stored embedding dimension differs from configured one
         if (dimExplicit) {
             const storedDim = getMeta(db, "embeddingDim");
-            if (storedDim && storedDim !== String(embeddingDim)) {
+            if (storedDim && storedDim !== String(effectiveDim)) {
                 // Stored vectors are incompatible with the new dimension. Drop the vec
                 // table so the block below recreates it at the new width; the BLOB rows
                 // go too. Regenerable from markdown — re-embedded by the next index.
@@ -340,9 +364,6 @@ export function ensureSchema(db, embeddingDim) {
         }
         const vecExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='entries_vec'").get();
         if (!vecExists) {
-            if (!Number.isInteger(effectiveDim) || effectiveDim <= 0 || effectiveDim > 4096) {
-                throw new Error(`Invalid embedding dimension: ${effectiveDim}`);
-            }
             db.exec(`
         CREATE VIRTUAL TABLE entries_vec USING vec0(
           id       INTEGER PRIMARY KEY,
@@ -351,7 +372,7 @@ export function ensureSchema(db, embeddingDim) {
       `);
         }
         if (dimExplicit) {
-            setMeta(db, "embeddingDim", String(embeddingDim));
+            setMeta(db, "embeddingDim", String(effectiveDim));
         }
     }
     else {
@@ -361,11 +382,11 @@ export function ensureSchema(db, embeddingDim) {
         // changes, those stored BLOBs become silently incompatible.
         if (dimExplicit) {
             const storedDim = getMeta(db, "embeddingDim");
-            if (storedDim && storedDim !== String(embeddingDim)) {
+            if (storedDim && storedDim !== String(effectiveDim)) {
                 // JS-fallback path: no vec table, just clear the stale BLOB vectors.
                 purgeEmbeddings(db);
             }
-            setMeta(db, "embeddingDim", String(embeddingDim));
+            setMeta(db, "embeddingDim", String(effectiveDim));
         }
     }
     // Usage telemetry (usage_events) lives in state.db since Chunk-8 WI-8.3 —

package/dist/storage/repositories/proposals-repository.js

@@ -13,6 +13,7 @@ import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { bundleRefToString, isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { warnOnce } from "../../core/warn.js";
+import { escapeLikePattern } from "../like-pattern.js";
 /** Serialize `Proposal.changes` for `metadata_json` (see {@link StoredFileChange}). */
 function changesToStored(changes) {
     return changes.map((c, i) => ({
@@ -390,7 +391,7 @@ export function getStateProposal(db, id, stashDir) {
  * `%` / `_` / `\` in the prefix are escaped so the LIKE pattern is literal.
  */
 export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
-    const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    const escaped = escapeLikePattern(idPrefix);
     const rows = db
         .prepare(`SELECT id FROM proposals
        WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'

package/dist/storage/repositories/task-history-repository.js

@@ -10,6 +10,7 @@
  * @module task-history-repository
  */
 import { isRecord } from "../../core/common.js";
+import { warnOnce } from "../../core/warn.js";
 function metadataError(message) {
     throw new Error(`invalid task_history metadata_json: ${message}`);
 }
@@ -18,10 +19,6 @@ function validateDetail(value) {
         return;
     if (!isRecord(value))
         metadataError("detail must be an object or null");
-    const allowed = new Set(["runId", "reason", "error", "exitCode"]);
-    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
-    if (unknown.length > 0)
-        metadataError(`unknown detail fields: ${unknown.sort().join(", ")}`);
     for (const field of ["runId", "reason", "error"]) {
         if (value[field] !== undefined && typeof value[field] !== "string")
             metadataError(`detail.${field} must be a string`);
@@ -60,7 +57,8 @@ export function decodeTaskHistoryMetadata(input) {
     if (!isRecord(parsed))
         metadataError("root must be an object");
     if (parsed.metadataVersion !== undefined && parsed.metadataVersion !== 2) {
-        metadataError(`unsupported metadataVersion: ${String(parsed.metadataVersion)}`);
+        warnOnce(`task-history-metadata-version:${String(parsed.metadataVersion)}`, `task_history row has metadataVersion ${String(parsed.metadataVersion)}, newer than this akm's 2 — ` +
+            "decoding it best-effort as version 2 rather than rejecting the row.");
     }
     if (typeof parsed.durationMs !== "number")
         metadataError("durationMs must be a number");
@@ -69,13 +67,22 @@ export function decodeTaskHistoryMetadata(input) {
         metadataError("engine must be a string or null");
     }
     if (parsed.targetVocab !== undefined && parsed.targetVocab !== 2) {
-        metadataError("targetVocab must be 2 when present");
+        warnOnce(`task-history-target-vocab:${String(parsed.targetVocab)}`, `task_history row has targetVocab ${String(parsed.targetVocab)}, newer than this akm's 2 — falling back to ` +
+            "the legacy target_kind mapping rather than rejecting the row.");
     }
     validateDetail(detail);
+    const cleanDetail = detail
+        ? {
+            ...(detail.runId !== undefined ? { runId: detail.runId } : {}),
+            ...(detail.reason !== undefined ? { reason: detail.reason } : {}),
+            ...(detail.error !== undefined ? { error: detail.error } : {}),
+            ...(detail.exitCode !== undefined ? { exitCode: detail.exitCode } : {}),
+        }
+        : null;
     return {
         metadataVersion: 2,
         durationMs: parsed.durationMs,
-        detail: detail ?? null,
+        detail: cleanDetail,
         ...(parsed.engine !== undefined ? { engine: parsed.engine } : {}),
         ...(parsed.targetVocab === 2 ? { targetVocab: 2 } : {}),
     };

package/dist/storage/repositories/workflow-runs-repository.js

@@ -2,9 +2,10 @@
 // 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/.
 import { randomUUID } from "node:crypto";
-import { UsageError } from "../../core/errors.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
 import { openStateDatabase, withImmediateTransaction } from "../../core/state-db.js";
 import { borrowScopedStateDb, withStateDbScope } from "../../core/state-db-scope.js";
+import { escapeLikePattern } from "../like-pattern.js";
 import { resolveStorageLocations } from "../locations.js";
 import { insertEventOnce, insertEventStrict } from "./events-repository.js";
 function assertAttemptReservationLease(input, run) {
@@ -96,6 +97,19 @@ export class WorkflowRunsRepository {
         const row = this.db.prepare("SELECT 1 FROM workflow_runs WHERE id = ? LIMIT 1").get(runId);
         return !!row;
     }
+    /** The one run id starting with `prefix` (#919); `UsageError` on several, `NotFoundError` on none. */
+    resolveRunIdPrefix(prefix) {
+        const escaped = escapeLikePattern(prefix);
+        const rows = this.db
+            .prepare("SELECT id FROM workflow_runs WHERE id LIKE ? ESCAPE '\\' ORDER BY id ASC")
+            .all(`${escaped}%`);
+        if (rows.length === 1)
+            return rows[0].id;
+        if (rows.length > 1) {
+            throw new UsageError(`Ambiguous workflow run id prefix "${prefix}" — matches: ${rows.map((r) => r.id).join(", ")}`, "INVALID_FLAG_VALUE");
+        }
+        throw new NotFoundError(`Workflow run "${prefix}" not found.`, "WORKFLOW_NOT_FOUND");
+    }
     listRuns(filter) {
         const filters = [];
         const params = [];

package/dist/storage/sqlite-read-snapshot.js

@@ -13,7 +13,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { sleepSync } from "../runtime.js";
 import { openDatabaseFinalizing } from "./database.js";
+const SNAPSHOT_MAX_ATTEMPTS = 8;
+const SNAPSHOT_BACKOFF_MS = 25;
 export class SqliteReadSnapshotUnavailableError extends Error {
     constructor(message) {
         super(message);
@@ -67,19 +70,17 @@ function fingerprintsEqual(left, right) {
 export function openSqliteReadSnapshot(dbPath) {
     if (!pathExists(dbPath))
         return undefined;
-    if (pathExists(`${dbPath}-journal`)) {
-        throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal is present; a non-mutating point-in-time snapshot is unavailable");
-    }
     const snapshotDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-sqlite-read-"));
     const snapshotPath = path.join(snapshotDir, "snapshot.db");
     let db;
     try {
         let copied = false;
-        for (let attempt = 0; attempt < 3; attempt++) {
+        for (let attempt = 0; attempt < SNAPSHOT_MAX_ATTEMPTS; attempt++) {
+            if (attempt > 0)
+                sleepSync(SNAPSHOT_BACKOFF_MS * attempt);
             try {
-                if (pathExists(`${dbPath}-journal`)) {
-                    throw new SqliteReadSnapshotUnavailableError("an active SQLite rollback journal appeared while taking the non-mutating snapshot");
-                }
+                if (pathExists(`${dbPath}-journal`))
+                    continue;
                 const before = databaseFingerprint(dbPath);
                 fs.copyFileSync(dbPath, snapshotPath);
                 if (before.wal)
@@ -87,7 +88,7 @@ export function openSqliteReadSnapshot(dbPath) {
                 else
                     fs.rmSync(`${snapshotPath}-wal`, { force: true });
                 const after = databaseFingerprint(dbPath);
-                if (fingerprintsEqual(before, after)) {
+                if (fingerprintsEqual(before, after) && !pathExists(`${dbPath}-journal`)) {
                     copied = true;
                     break;
                 }
@@ -99,7 +100,8 @@ export function openSqliteReadSnapshot(dbPath) {
             }
         }
         if (!copied) {
-            throw new SqliteReadSnapshotUnavailableError("SQLite main/WAL files kept changing while taking the non-mutating snapshot");
+            throw new SqliteReadSnapshotUnavailableError(`SQLite main/WAL files did not settle after ${SNAPSHOT_MAX_ATTEMPTS} attempts with backoff — ` +
+                "a writer may be continuously active, or a hot rollback journal never cleared");
         }
         db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
         const closeSnapshot = db.close.bind(db);

package/dist/tasks/backends/cron.js

@@ -29,6 +29,7 @@
 //
 // Tests inject a fake exec so unit tests don't touch the real crontab.
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
@@ -60,9 +61,16 @@ export function CRON_BACKEND(options = {}) {
             // Create the log directory before writing the crontab line — cron
             // appends with `>>` and the surrounding shell will fail the entire
             // entry if the parent directory doesn't exist.
-            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            const cronLineParts = buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
+            const cronLine = cronLineParts.line;
             assertPortableCronLine(cronLine);
             fsLike.ensureDir(logDir);
+            if (cronLineParts.wrapper) {
+                if (!fsLike.writeFile) {
+                    throw new ConfigError("Cron backend needs to write a wrapper script for this task's long invocation, but the configured filesystem cannot write files.", "INVALID_CONFIG_FILE");
+                }
+                fsLike.writeFile(cronLineParts.wrapper.path, cronLineParts.wrapper.content);
+            }
             const existing = readCrontab(exec);
             const nativeId = schedulerBindingNativeId(task);
             const blocks = listBlocks(existing);
@@ -245,14 +253,35 @@ function isCronBindingSnapshot(value) {
         value.kind === CRON_SNAPSHOT &&
         typeof value.crontab === "string");
 }
-// ── helpers (exported for tests) ────────────────────────────────────────────
-export function buildCronLine(task, akmArgv, logDir, contextPath, _target) {
+function buildCronLineParts(task, akmArgv, logDir, contextPath, _target) {
     const spec = parseSchedule(task.cron, "cron");
     const cronExpr = translateToCron(spec);
-    const logPath = path.join(logDir, `${schedulerBindingNativeId(task)}.log`);
+    const nativeId = schedulerBindingNativeId(task);
+    const logPath = path.join(logDir, `${nativeId}.log`);
     const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
     const cmd = invocation.argv.map((part) => quoteForCron(part)).join(" ");
-    return `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    const directLine = `${cronExpr} ${cmd} >> ${quoteForCron(logPath)} 2>&1`;
+    if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT) {
+        return { line: directLine };
+    }
+    const content = cronWrapperScriptContent(invocation.argv);
+    const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+    const wrapperPath = path.join(logDir, `${CRON_WRAPPER_PREFIX}${nativeId}-${contentHash}.sh`);
+    const line = `${cronExpr} sh ${quoteForCron(wrapperPath)} >> ${quoteForCron(logPath)} 2>&1`;
+    return { line, wrapper: { path: wrapperPath, content } };
+}
+const CRON_WRAPPER_PREFIX = ".akm-cron-wrapper-";
+function quoteForShellScript(part) {
+    if (/^[A-Za-z0-9_\-./@:=+,]+$/.test(part))
+        return part;
+    return `'${part.replace(/'/g, `'\\''`)}'`;
+}
+function cronWrapperScriptContent(argv) {
+    const cmd = argv.map(quoteForShellScript).join(" ");
+    return `#!/bin/sh\nexec ${cmd}\n`;
+}
+export function buildCronLine(task, akmArgv, logDir, contextPath, _target) {
+    return buildCronLineParts(task, akmArgv, logDir, contextPath, _target).line;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
 export function cronBlockBody(cronLine, enabled, executionEvidenceDigest) {

package/dist/tasks/backends/launchd.js

@@ -28,6 +28,7 @@ import launchdTemplate from "../../assets/backends/launchd-template.xml" with {
 import { hasErrnoCode } from "../../core/common.js";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
@@ -514,13 +515,7 @@ function inspectStableLaunchdNamespace(seedIds, context) {
         throw new ConfigError(`launchctl failed to enumerate the loaded user domain during scheduler state inspection: ${domain.stderr || domain.stdout || "no output"}.`, "INVALID_CONFIG_FILE");
     }
     const loadedLabels = parseLaunchdLoadedLabels(domain.stdout);
-    if (loadedLabels === undefined) {
-        throw new ConfigError("launchctl returned an unsafe, unsupported, or oversized loaded-service inventory during scheduler state inspection.", "INVALID_CONFIG_FILE");
-    }
     const disabledLabels = readDisabledLabels(context.exec);
-    if (disabledLabels === undefined) {
-        throw new ConfigError("launchctl print-disabled failed during scheduler state inspection.", "INVALID_CONFIG_FILE");
-    }
     const akmDisabledLabels = [...disabledLabels].filter((label) => label.startsWith(LAUNCHD_LABEL_PREFIX)).sort();
     const plistEntries = [];
     if (context.fsLike.exists(context.agentsDir)) {
@@ -834,48 +829,50 @@ function normalizeSignature(xml) {
  * labels we will track. Exceeding either still returns `undefined`.
  */
 export function parseLaunchdLoadedLabels(output) {
-    if (Buffer.byteLength(output, "utf8") > MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES)
-        return undefined;
     const labels = new Set();
     // Our own namespace is the only thing we look for. `[^\s"{}=,()]` stops the
     // token at whatever punctuation the surrounding launchctl syntax uses, so a
     // label works whether it appears as a bare table cell, a quoted string, or a
     // dictionary key.
     const labelPattern = /com\.akm\.task\.[^\s"{}=,()]+/gu;
-    for (const match of output.matchAll(labelPattern)) {
+    for (const match of boundLaunchdOutput(output).matchAll(labelPattern)) {
         const label = match[0];
         if (!LAUNCHD_AKM_LABEL_RE.test(label))
             continue;
         labels.add(label);
-        if (labels.size > MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES)
-            return undefined;
+        if (labels.size >= MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES)
+            break;
     }
     return labels;
 }
+function boundLaunchdOutput(output) {
+    return output.length > MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES ? output.slice(0, MAX_LAUNCHD_DOMAIN_OUTPUT_BYTES) : output;
+}
 function readDisabledLabels(exec) {
     try {
         const result = exec.run(["launchctl", "print-disabled", `gui/${exec.uid()}`]);
-        if (result.status !== 0)
-            return undefined;
+        if (result.status !== 0) {
+            warn("[akm] launchctl print-disabled exited %d; assuming no akm task is disabled.", result.status);
+            return new Set();
+        }
         return parseDisabledLabels(result.stdout);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        warn("[akm] launchctl print-disabled could not be run; assuming no akm task is disabled: %s", error instanceof Error ? error.message : String(error));
+        return new Set();
     }
 }
 function parseDisabledLabels(output) {
-    const envelope = /^\s*disabled services\s*=\s*\{([\s\S]*)\}\s*$/.exec(output);
-    if (!envelope)
-        return undefined;
     const disabled = new Set();
-    let body = envelope[1];
-    while (body.trim()) {
-        const entry = /^\s*"([^"\r\n]+)"\s*=>\s*(true|false|enabled|disabled)\s*/.exec(body);
-        if (!entry)
-            return undefined;
-        if (entry[2] === "true" || entry[2] === "disabled")
-            disabled.add(entry[1]);
-        body = body.slice(entry[0].length);
+    const entryPattern = /"(com\.akm\.task\.[^"\r\n]+)"\s*=>\s*(true|false|enabled|disabled)/gu;
+    for (const match of boundLaunchdOutput(output).matchAll(entryPattern)) {
+        const label = match[1];
+        if (!LAUNCHD_AKM_LABEL_RE.test(label))
+            continue;
+        if (match[2] === "true" || match[2] === "disabled")
+            disabled.add(label);
+        if (disabled.size >= MAX_LAUNCHD_AKM_NAMESPACE_ENTRIES)
+            break;
     }
     return disabled;
 }

package/dist/tasks/backends/schtasks.js

@@ -552,6 +552,8 @@ function expandNativeTriggers(trigger) {
             return [{ kind: "daily", atHour: trigger.atHour, atMinute: trigger.atMinute }];
         case "weekly":
             return [trigger];
+        case "monthly":
+            return [trigger];
     }
 }
 function renderNativeTrigger(trigger, startBoundary) {
@@ -570,9 +572,10 @@ ${repetition}      <StartBoundary>${startBoundary}</StartBoundary>
       <ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay>
     </CalendarTrigger>`;
     }
-    const dayMap = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
-    const days = trigger.daysOfWeek.map((d) => `        <${dayMap[d]} />`).join("\n");
-    return `    <CalendarTrigger>
+    if (trigger.kind === "weekly") {
+        const dayMap = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+        const days = trigger.daysOfWeek.map((d) => `        <${dayMap[d]} />`).join("\n");
+        return `    <CalendarTrigger>
       <StartBoundary>${startBoundary}</StartBoundary>
       <Enabled>true</Enabled>
       <ScheduleByWeek>
@@ -582,6 +585,35 @@ ${days}
         <WeeksInterval>1</WeeksInterval>
       </ScheduleByWeek>
     </CalendarTrigger>`;
+    }
+    const monthMap = [
+        "January",
+        "February",
+        "March",
+        "April",
+        "May",
+        "June",
+        "July",
+        "August",
+        "September",
+        "October",
+        "November",
+        "December",
+    ];
+    const days = trigger.daysOfMonth.map((d) => `          <Day>${d}</Day>`).join("\n");
+    const months = trigger.months.map((m) => `        <${monthMap[m - 1]} />`).join("\n");
+    return `    <CalendarTrigger>
+      <StartBoundary>${startBoundary}</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByMonth>
+        <DaysOfMonth>
+${days}
+        </DaysOfMonth>
+        <Months>
+${months}
+        </Months>
+      </ScheduleByMonth>
+    </CalendarTrigger>`;
 }
 function formatRepetitionInterval(minutes) {
     return formatMinuteDuration(minutes);
@@ -617,6 +649,21 @@ function nextStartBoundary(trigger, now) {
                 boundary.setHours(trigger.atHour, trigger.atMinute, 0, 0);
             }
             return boundary;
+        case "monthly": {
+            boundary.setHours(trigger.atHour, trigger.atMinute, 0, 0);
+            const daysOfMonth = new Set(trigger.daysOfMonth);
+            const months = new Set(trigger.months);
+            for (let guard = 0; guard < 4000; guard++) {
+                if (daysOfMonth.has(boundary.getDate()) &&
+                    months.has(boundary.getMonth() + 1) &&
+                    boundary.getTime() > now.getTime()) {
+                    break;
+                }
+                boundary.setDate(boundary.getDate() + 1);
+                boundary.setHours(trigger.atHour, trigger.atMinute, 0, 0);
+            }
+            return boundary;
+        }
     }
 }
 function formatStartBoundary(d) {

package/dist/tasks/frozen-script.js

@@ -24,6 +24,8 @@ export function frozenScriptCommand(script, materializedPath) {
             return [process.execPath, materializedPath];
         case "bun-standalone":
             return [process.execPath, STANDALONE_FROZEN_SCRIPT_ARG, materializedPath];
+        case "node":
+            return ["node", materializedPath];
         case "powershell":
             return ["powershell", "-NoProfile", "-NonInteractive", "-File", materializedPath];
         case "cmd":

package/dist/tasks/prepare/prepare.js

@@ -21,6 +21,7 @@
 import fs from "node:fs";
 import { prepareCommandInvocation } from "../../commands/command/command-execution.js";
 import { UsageError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 import { base, commandEnvironmentSnapshot, currentExecutionValues, defaultTaskShell, environmentSnapshot, qualifyOwnedRef, resolvedOwnedAsset, validatePreparedCommand, validateWorkflowRuntimeSource, } from "./prepare-support.js";
 import { captureDirectoryIdentity, captureScriptTarget } from "./script-capture.js";
 /** Project one canonical task-v3 source into immutable executable work. */
@@ -79,13 +80,7 @@ export async function prepareTaskV3Execution(document, context) {
     if (target.kind === "workflow") {
         // Stays reachable — task source v4 still has a top-level env: (P4-N4).
         if (Object.keys(environment).length > 0) {
-            // P4 (docs/plans/specs/p4-deletions-closeout.md §5.5, row P-04): PRESERVED,
-            // not re-coded — tests/integration/tasks-with-classification-characterization.test.ts's
-            // P-04 block pins this exact code (CONVERT, not FLIP, per §7.2 F-A2.8:
-            // "the P-04 block ... stays reachable and stays pinned"). §5.2's target
-            // table predicted all 3 of this file's remaining sites → COMPOSITION_INVALID;
-            // this is the recorded deviation for the one site a preservation gate blocks.
-            throw new UsageError("Task workflow env cannot be consumed by the durable workflow runtime in 0.9.2; remove env or use a command target.", "INVALID_FLAG_VALUE");
+            warn("[akm] Task %s: env: is not translated for a workflow target and will be ignored; the durable workflow runtime does not consume it. Use a command target, or drop env:.", context.taskRef);
         }
         const resolved = await resolvedOwnedAsset(qualified, "workflow", context);
         validateWorkflowRuntimeSource(resolved.file, resolved.bundleRoot, context.readFile ?? ((targetPath) => fs.readFileSync(targetPath)));