akm-cli 0.9.17-alpha.1 → 0.9.17-alpha.10

package/dist/tasks/backends/cron.js

@@ -7,11 +7,18 @@
 // its other lines untouched:
 //
 //     # akm:task <id> BEGIN
-//     [SCHED] /abs/akm task run <id> > /home/.../tasks/logs/<id>.log 2>&1
+//     [SCHED] AKM_BUNDLE_DIR=<working stash> /abs/akm task run <id> ... > <log> 2>&1
 //     # akm:task <id> END
 //
+// The row sets its own environment inline, as a `VAR=value` prefix (see
+// `src/tasks/scheduler-invocation.ts`); PATH is the `# akm:env` block. A
+// command over the portable line limit runs `sh <wrapper script>` instead,
+// and the script holds the same environment and argv.
+//
 // The backend reads/writes the user's crontab via `crontab -l` and
-// `crontab -`. Disabling a task comments the entry with `# akm:disabled `
+// `crontab -`. Every mutation is one read → modify the akm blocks (and the
+// `# akm:env` PATH header) → one write, with the prior crontab restored when
+// the write fails. Disabling a task comments the entry with `# akm:disabled `
 // rather than removing it, so re-enabling preserves the original schedule.
 //
 // Platform notes:
@@ -30,282 +37,131 @@
 // 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 fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
-import { assertSchedulerExecutionEvidenceDigest, assertSchedulerExpectationIdentity, assertSchedulerMutationArtifact, assertSchedulerNativeArtifactCardinality, assertSchedulerNativeArtifactOwner, assertSchedulerRemovalArtifact, assertSchedulerRollbackArtifactCardinality, schedulerBindingNativeId, schedulerLogicalBindingId, schedulerLogicalBindingOwner, schedulerNativeArtifactKey, } from "../scheduler-binding.js";
-import { buildScheduledBindingInvocation, parsePublicSchedulerInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, SCHEDULER_CONTEXT_ARG, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { schedulerBindingNativeId, schedulerLogicalBindingId } from "../scheduler-binding.js";
+import { buildScheduledInvocation, parseScheduledInvocationArgv, scheduledRowEnvironmentEntries, scheduledRowEnvironmentFrom, } from "../scheduler-invocation.js";
 import { nodeFs, throwIfNotOk } from "./exec-utils.js";
 const BEGIN = (id) => `# akm:task ${assertCronValue(id)} BEGIN`;
 const END = (id) => `# akm:task ${assertCronValue(id)} END`;
 const DISABLED_PREFIX = "# akm:disabled ";
-const SOURCE_ENABLED_PREFIX = "# akm:source-enabled ";
 const BLOCK_RE = /^# akm:task ([\w.@:_-]+) BEGIN$/;
 const BLOCK_END_RE = /^# akm:task ([\w.@:_-]+) END$/;
+const ENV_BEGIN = "# akm:env BEGIN";
+const ENV_END = "# akm:env END";
 export const PORTABLE_CRON_LINE_LIMIT = 1000;
-const CRON_SNAPSHOT = Symbol("akm-cron-binding-snapshot");
+const CRON_WRAPPER_PREFIX = ".akm-cron-wrapper-";
 export function CRON_BACKEND(options = {}) {
     const exec = options.exec ?? defaultCronExec();
     const fsLike = options.fs ?? nodeFs();
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
     const envPath = options.envPath === false ? undefined : (options.envPath ?? process.env.PATH);
-    const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
-    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext, envPath ?? ""));
+    const readFile = options.fs?.readFile ?? ((file) => fs.readFileSync(file, "utf8"));
+    const lineFor = (task, opts) => buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.environment);
     return {
         name: "cron",
-        install(task, opts, expected) {
-            if (expected)
-                assertSchedulerExpectationIdentity(expected, task);
-            // Create the log directory before writing the crontab line — the
-            // redirect target's parent directory must exist or the surrounding
-            // shell will fail the entire entry.
-            const cronLineParts = buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
-            const cronLine = cronLineParts.line;
-            assertPortableCronLine(cronLine);
+        install(task, opts) {
+            const parts = lineFor(task, opts);
+            assertPortableCronLine(parts.line);
+            // The redirect target's parent directory must exist or the surrounding
+            // shell fails the entire entry.
             fsLike.ensureDir(logDir);
-            if (cronLineParts.wrapper) {
+            if (parts.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);
+                fsLike.writeFile(parts.wrapper.path, parts.wrapper.content);
             }
             const existing = readCrontab(exec);
             const nativeId = schedulerBindingNativeId(task);
-            const blocks = listBlocks(existing);
-            const matching = blocks.filter(({ id }) => schedulerNativeArtifactKey(id) === schedulerNativeArtifactKey(nativeId));
-            const artifacts = matching.map((block) => cronArtifact(block.id, block.body));
-            const priorArtifact = expected
-                ? assertSchedulerNativeArtifactCardinality(artifacts, nativeId, expected.state === "absent" ? 0 : 1)
-                : matching.length > 1
-                    ? assertSchedulerNativeArtifactCardinality(artifacts, nativeId, 1)
-                    : artifacts[0];
-            const prior = priorArtifact ? matching.find((block) => block.id === priorArtifact.nativeId) : undefined;
-            if (expected) {
-                assertSchedulerMutationArtifact(priorArtifact, expected);
-            }
-            else if (prior) {
-                assertSchedulerNativeArtifactOwner(prior.id, task, extractCronInvocation(prior.body)?.invocation);
-            }
-            const block = renderBlock(nativeId, cronLine, task.enabled, task.executionEvidenceDigest);
-            const next = upsertBlock(existing, nativeId, block);
-            replaceCrontab(exec, existing, next);
+            const block = renderBlock(nativeId, parts.line, task.enabled);
+            replaceCrontab(exec, existing, upsertEnvBlock(upsertBlock(existing, nativeId, block), envPath));
         },
-        uninstall(nativeId, expected) {
-            if (expected)
-                assertSchedulerExpectationIdentity({ ...expected, state: "present" });
+        uninstall(nativeId) {
             const existing = readCrontab(exec);
-            const matching = listBlocks(existing).filter(({ id }) => schedulerNativeArtifactKey(id) === schedulerNativeArtifactKey(nativeId));
-            const priorArtifact = expected
-                ? assertSchedulerNativeArtifactCardinality(matching.map((block) => cronArtifact(block.id, block.body)), nativeId, 1)
-                : undefined;
-            const prior = expected
-                ? matching.find((block) => block.id === priorArtifact?.nativeId)
-                : matching.find(({ id }) => id === nativeId);
-            if (!prior)
+            if (!listBlocks(existing).some((block) => block.id === nativeId))
                 return;
-            if (expected) {
-                assertSchedulerRemovalArtifact(nativeId, expected, extractCronInvocation(prior.body)?.invocation, normalizeSignature(prior.body));
-            }
-            const next = removeBlock(existing, nativeId);
-            replaceCrontab(exec, existing, next);
+            replaceCrontab(exec, existing, upsertEnvBlock(removeBlock(existing, nativeId), envPath));
         },
         setEnabled(nativeId, enabled) {
             const existing = readCrontab(exec);
             const next = toggleBlock(existing, nativeId, enabled);
-            replaceCrontab(exec, existing, next);
+            if (next !== existing)
+                replaceCrontab(exec, existing, next);
         },
         list() {
-            return [...inspectCronState(readCrontab(exec), defaultContextPath).installed];
-        },
-        listForRebind() {
-            const existing = readCrontab(exec);
-            return listBlocks(existing).map(({ id, body }) => {
-                const installed = extractCronInvocation(body);
-                const ref = {
-                    id: installed ? schedulerLogicalBindingId(id, installed.invocation) : id,
+            const rows = [];
+            for (const { id, body } of listBlocks(readCrontab(exec))) {
+                const parsed = extractCronInvocation(body) ?? extractCronWrapperInvocation(body, readFile);
+                if (!parsed)
+                    continue;
+                rows.push({
+                    id: schedulerLogicalBindingId(id, parsed.invocation),
+                    nativeId: id,
+                    enabled: !cronIsDisabled(body),
                     signature: normalizeSignature(body),
-                    ...(installed?.target !== undefined ? { target: installed.target } : {}),
-                };
-                Object.defineProperty(ref, "nativeId", { value: id });
-                if (installed)
-                    Object.defineProperty(ref, "invocation", { value: Object.freeze([...installed.invocation]) });
-                return ref;
-            });
-        },
-        listNativeArtifacts() {
-            return [...inspectCronState(readCrontab(exec), defaultContextPath).artifacts];
-        },
-        inspectBindings() {
-            return inspectCronState(readCrontab(exec), defaultContextPath);
-        },
-        snapshotBindings(ids) {
-            const crontab = readCrontab(exec);
-            const inspection = inspectCronState(crontab, defaultContextPath);
-            const keys = new Set(ids.map(schedulerNativeArtifactKey));
-            return Object.freeze({
-                kind: CRON_SNAPSHOT,
-                nativeIds: Object.freeze([...ids]),
-                artifacts: Object.freeze(inspection.artifacts.filter((artifact) => keys.has(schedulerNativeArtifactKey(artifact.nativeId)))),
-                crontab,
-            });
-        },
-        restoreBindings(snapshot, expectedCurrent) {
-            if (!isCronBindingSnapshot(snapshot)) {
-                throw new ConfigError("Invalid cron scheduler snapshot.", "INVALID_CONFIG_FILE");
-            }
-            const existing = readCrontab(exec);
-            const current = inspectCronState(existing, defaultContextPath);
-            const safeNativeIds = [];
-            const errors = [];
-            if (expectedCurrent) {
-                for (const nativeId of snapshot.nativeIds) {
-                    try {
-                        const expected = expectedCurrent.find((candidate) => candidate.nativeId === nativeId);
-                        if (!expected) {
-                            throw new ConfigError(`Missing cron rollback expectation for ${JSON.stringify(nativeId)}.`, "INVALID_CONFIG_FILE");
-                        }
-                        assertSchedulerRollbackArtifactCardinality(current.artifacts, expected);
-                        safeNativeIds.push(nativeId);
-                    }
-                    catch (error) {
-                        errors.push(error);
-                    }
-                }
-            }
-            else {
-                safeNativeIds.push(...snapshot.nativeIds);
-            }
-            const priorBlocks = new Map(listBlocks(snapshot.crontab).map((block) => [block.id, block]));
-            let restored = existing;
-            for (const nativeId of safeNativeIds) {
-                const prior = priorBlocks.get(nativeId);
-                restored = prior
-                    ? upsertBlock(restored, nativeId, [BEGIN(nativeId), prior.body, END(nativeId)].join("\n"))
-                    : removeBlock(restored, nativeId);
-            }
-            if (restored !== existing) {
-                try {
-                    replaceCrontab(exec, existing, restored);
-                }
-                catch (error) {
-                    errors.push(error);
-                }
-            }
-            if (errors.length > 0) {
-                throw new AggregateError(errors, "Cron rollback CAS rejected one or more changed native artifacts.");
+                    ...(parsed.target !== undefined ? { target: parsed.target } : {}),
+                    binding: parsed.binding,
+                    ...(parsed.contextPath !== undefined ? { contextPath: parsed.contextPath } : {}),
+                    ...(parsed.environment !== undefined ? { environment: parsed.environment } : {}),
+                    invocation: parsed.invocation,
+                });
             }
+            return rows;
         },
         expectedSignature(task, opts) {
-            const cronLine = buildCronLine(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, opts?.target);
-            assertPortableCronLine(cronLine);
-            return normalizeSignature(cronBlockBody(cronLine, task.enabled, task.executionEvidenceDigest));
+            const line = lineFor(task, opts).line;
+            assertPortableCronLine(line);
+            return normalizeSignature(cronBlockBody(line, task.enabled));
         },
     };
 }
-function inspectCronState(crontab, fallbackContextPath) {
-    const installed = [];
-    const artifacts = [];
-    for (const { id, body } of listBlocks(crontab)) {
-        const parsed = extractCronInvocation(body);
-        const fingerprint = normalizeSignature(body);
-        const artifact = cronArtifact(id, body);
-        artifacts.push(artifact);
-        if (!parsed)
-            continue;
-        const ref = {
-            id: schedulerLogicalBindingId(id, parsed.invocation),
-            enabled: !cronIsDisabled(body),
-            signature: fingerprint,
-            ...(parsed.target !== undefined ? { target: parsed.target } : {}),
-            binding: parsed.binding,
-            // A legacy (pre-`--scheduler-context`) row has no real descriptor
-            // path to report — `extractLegacyCronInvocation` leaves it "". Fall
-            // back to the current default so downstream consumers (context
-            // validation in `akm task prune`/`explain`, `sync`'s reuse of an
-            // existing binding's contextPath) see a real, resolvable descriptor
-            // rather than an empty path, since the row is about to be reconciled
-            // to a current one anyway (#881).
-            contextPath: parsed.contextPath || fallbackContextPath,
-        };
-        Object.defineProperty(ref, "nativeId", { value: id });
-        Object.defineProperty(ref, "invocation", { value: Object.freeze([...parsed.invocation]) });
-        installed.push(ref);
-    }
-    return Object.freeze({ installed: Object.freeze(installed), artifacts: Object.freeze(artifacts) });
-}
-function cronArtifact(nativeId, body) {
-    const parsed = extractCronInvocation(body);
-    const owner = parsed ? schedulerLogicalBindingOwner(nativeId, parsed.invocation) : undefined;
-    const artifact = parsed
-        ? {
-            nativeId,
-            ...(owner !== undefined ? { bindingId: owner } : {}),
-            invocation: Object.freeze([...parsed.invocation]),
-        }
-        : { nativeId };
-    Object.defineProperty(artifact, "fingerprint", { value: normalizeSignature(body) });
-    return artifact;
-}
-function isCronBindingSnapshot(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value.kind === CRON_SNAPSHOT &&
-        typeof value.crontab === "string");
-}
-function buildCronLineParts(task, akmArgv, logDir, contextPath, _target) {
-    const spec = parseSchedule(task.cron, "cron");
-    const cronExpr = translateToCron(spec);
+function buildCronLineParts(task, akmArgv, logDir, environment) {
+    const cronExpr = translateToCron(parseSchedule(task.cron, "cron"));
     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(" ");
+    const argv = buildScheduledInvocation(akmArgv, task.invocation);
+    const variables = scheduledRowEnvironmentEntries(environment);
+    // An assignment prefix: the shell cron hands the line to sets it for this
+    // command only. Only the value is quoted, or the word is not an assignment.
+    const assignments = variables.map(([name, value]) => `${name}=${quoteForCron(value)} `).join("");
+    const cmd = argv.map((part) => quoteForCron(part)).join(" ");
     // #951: truncate (not append) so this bootstrap safety-net file always
-    // holds exactly the latest run's raw output rather than growing forever.
-    // akm's own per-run log (src/tasks/run/task-log.ts) already keeps history.
-    const directLine = `${cronExpr} ${cmd} > ${quoteForCron(logPath)} 2>&1`;
-    if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT) {
+    // holds exactly the latest run's raw output. akm's own per-run log
+    // (src/tasks/run/task-log.ts) keeps history.
+    const directLine = `${cronExpr} ${assignments}${cmd} > ${quoteForCron(logPath)} 2>&1`;
+    if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT)
         return { line: directLine };
-    }
-    const content = cronWrapperScriptContent(invocation.argv);
+    // A command over vixie-cron's MAX_COMMAND is spilled into a short wrapper
+    // script under logDir instead of being truncated or refused.
+    const exports = variables.map(([name, value]) => `export ${name}=${quoteForShellScript(value)}\n`).join("");
+    const content = `#!/bin/sh\n${exports}exec ${argv.map(quoteForShellScript).join(" ")}\n`;
     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;
+export function buildCronLine(task, akmArgv, logDir, environment) {
+    return buildCronLineParts(task, akmArgv, logDir, environment).line;
 }
 /** The crontab line as it appears inside a block — commented when disabled. */
-export function cronBlockBody(cronLine, enabled, executionEvidenceDigest) {
-    const lines = [
-        cronLine,
-        ...(executionEvidenceDigest === undefined
-            ? []
-            : [`# akm:workflow-evidence ${assertSchedulerExecutionEvidenceDigest(executionEvidenceDigest)}`]),
-    ];
-    return (enabled ? lines : lines.map((line) => `${DISABLED_PREFIX}${line}`)).join("\n");
+export function cronBlockBody(cronLine, enabled) {
+    return enabled ? cronLine : `${DISABLED_PREFIX}${cronLine}`;
 }
-export function renderBlock(id, cronLine, enabled, executionEvidenceDigest) {
-    return [BEGIN(id), cronBlockBody(cronLine, enabled, executionEvidenceDigest), END(id)].join("\n");
+export function renderBlock(id, cronLine, enabled) {
+    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.
- */
+/** The akm-owned blocks of a crontab: each id with the raw body between its BEGIN/END markers. */
 export function listBlocks(existing) {
     return parseBlocks(existing).map(({ id, body }) => ({ id, body }));
 }
@@ -345,69 +201,78 @@ function parseBlocks(existing) {
 function malformedBlockError(id) {
     return new ConfigError(`Crontab contains a malformed akm task block for "${id}"; refusing to modify it.`, "INVALID_CONFIG_FILE");
 }
-/**
- * Recover the bundle name from an installed cron block body by reading the
- * `--bundle <bundle>` token embedded in the scheduled `akm task run …`
- * invocation. Returns undefined for the byte-identical primary/default form
- * (no `--bundle`). Bundle slugs never contain whitespace (config-schema
- * `isBundleSlug`), so the quoted token is a single whitespace-delimited field
- * even when cron-quoted — a plain field split recovers it, and
- * the shell-word parser below reverses the quoting.
- */
+/** The `--bundle <bundle>` token of an installed cron body; undefined for the primary/default form. */
 export function extractInstalledTarget(body) {
     return extractCronInvocation(body)?.target;
 }
+/**
+ * Parse an installed cron body: its inline `VAR=value` environment, its
+ * launcher, and its public tail — a current row, a row naming a
+ * `--scheduler-context` descriptor (0.9.0 – 0.9.17-alpha.6), or an older
+ * row with neither (#881). This only ever runs on a body already isolated
+ * between akm's own BEGIN/END markers, so no trust extends to unmarked lines.
+ */
 export function extractCronInvocation(body) {
     const line = body.startsWith(DISABLED_PREFIX) ? body.slice(DISABLED_PREFIX.length) : body;
     const fields = splitCronShellWords(line);
     if (fields.length < 6)
         return undefined;
     let commandStart = 5;
-    while (commandStart < fields.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(fields[commandStart]))
+    const variables = {};
+    for (let field = fields[commandStart]; field !== undefined; field = fields[commandStart]) {
+        const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(field);
+        if (!assignment)
+            break;
+        variables[assignment[1]] = assignment[2];
         commandStart += 1;
-    // #951: newly-installed rows redirect with `>` (truncate); tolerate `>>`
-    // (append) too, since that's what every row written before this change —
-    // including ones a still-running older akm binary installs during a
-    // rolling upgrade — looks like on disk.
+    }
+    // #951: new rows redirect with `>`; rows written before that use `>>`.
     const redirectIndex = fields.findIndex((field, index) => index >= commandStart && (field === ">" || field === ">>"));
     if (redirectIndex === -1)
         return undefined;
-    const tail = fields.slice(commandStart, redirectIndex);
-    const parsed = parseScheduledBindingArgv(tail);
-    if (parsed)
-        return parsed;
-    // Rows written by akm < 0.9.2 (before `--scheduler-context` existed) have
-    // no context argument at all — just the akm argv immediately followed by
-    // the public `task run …` / `workflow run …` tail. `extractCronInvocation`
-    // only ever runs on a body already isolated between this backend's own
-    // `# akm:task … BEGIN/END` sentinels (see `parseBlocks`), so recognizing
-    // this older shape here doesn't extend trust to any unmarked crontab
-    // line — it only lets sync see and reconcile a row akm already owns
-    // instead of treating it as absent and colliding with the still-present
-    // artifact (#881). Guarded on the marker's absence so a row that DOES
-    // carry `--scheduler-context` but fails to parse for some other reason
-    // is never silently reinterpreted as legacy.
-    if (tail.includes(SCHEDULER_CONTEXT_ARG))
+    const parsed = parseScheduledInvocationArgv(fields.slice(commandStart, redirectIndex));
+    if (!parsed)
         return undefined;
-    return extractLegacyCronInvocation(tail);
+    const environment = scheduledRowEnvironmentFrom(variables);
+    return environment ? { ...parsed, environment } : parsed;
 }
-function extractLegacyCronInvocation(tail) {
-    for (let index = 0; index < tail.length - 1; index += 1) {
-        if ((tail[index] === "task" || tail[index] === "workflow") && tail[index + 1] === "run") {
-            const publicInvocation = parsePublicSchedulerInvocation(tail.slice(index));
-            if (!publicInvocation)
-                return undefined;
-            return {
-                binding: tail.slice(0, index),
-                contextPath: "",
-                invocation: publicInvocation.invocation,
-                ...(publicInvocation.target !== undefined ? { target: publicInvocation.target } : {}),
-            };
-        }
+/**
+ * Parse a row spilled into a wrapper script (`sh <script> > <log> 2>&1`):
+ * the script's `export NAME=value` lines and its `exec` argv. Only akm's own
+ * wrapper scripts are read; one that is gone or does not parse leaves the
+ * row unlisted, as any unparsable row is.
+ */
+export function extractCronWrapperInvocation(body, readFile) {
+    const line = body.startsWith(DISABLED_PREFIX) ? body.slice(DISABLED_PREFIX.length) : body;
+    const fields = splitCronShellWords(line);
+    const script = fields[6];
+    if (fields[5] !== "sh" || !script || !path.basename(script).startsWith(CRON_WRAPPER_PREFIX))
+        return undefined;
+    if (fields[7] !== ">" && fields[7] !== ">>")
+        return undefined;
+    let content;
+    try {
+        content = readFile(script);
+    }
+    catch {
+        return undefined;
+    }
+    const variables = {};
+    let parsed;
+    for (const scriptLine of content.split("\n")) {
+        const words = splitCronShellWords(scriptLine);
+        const assignment = words[0] === "export" ? /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(words[1] ?? "") : null;
+        if (assignment)
+            variables[assignment[1]] = assignment[2];
+        else if (words[0] === "exec")
+            parsed = parseScheduledInvocationArgv(words.slice(1));
     }
-    return undefined;
+    if (!parsed)
+        return undefined;
+    const environment = scheduledRowEnvironmentFrom(variables);
+    return environment ? { ...parsed, environment } : parsed;
 }
-/** Reverse {@link quoteForCron} for a single whitespace-free token. */
+/** Reverse {@link quoteForCron}: sh word splitting, where a backslash is literal inside single quotes. */
 function splitCronShellWords(value) {
     const words = [];
     let current = "";
@@ -418,7 +283,7 @@ function splitCronShellWords(value) {
             quoted = !quoted;
             continue;
         }
-        if (char === "\\" && index + 1 < value.length) {
+        if (!quoted && char === "\\" && index + 1 < value.length) {
             current += value[index + 1];
             index += 1;
             continue;
@@ -439,14 +304,10 @@ function splitCronShellWords(value) {
 function normalizeSignature(body) {
     return body
         .split(/\r?\n/)
-        .map((l) => l.trim())
-        .filter((l) => !stripDisabledPrefix(l).startsWith(SOURCE_ENABLED_PREFIX))
-        .filter((l) => l.length > 0)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
         .join("\n");
 }
-function stripDisabledPrefix(line) {
-    return line.startsWith(DISABLED_PREFIX) ? line.slice(DISABLED_PREFIX.length) : line;
-}
 function cronIsDisabled(body) {
     return body.trimStart().startsWith(DISABLED_PREFIX);
 }
@@ -462,17 +323,55 @@ export function removeBlock(existing, id) {
     if (blocks.length === 0)
         return existing;
     const out = lines.filter((_, index) => !blocks.some((block) => index >= block.start && index <= block.end));
-    // Collapse trailing blank lines.
     while (out.length > 0 && out[out.length - 1] === "")
         out.pop();
     return out.join("\n");
 }
+/**
+ * akm's managed environment section: one `PATH=` line directly above the
+ * first akm task block. Cron applies an environment assignment to every
+ * command line after it, which is why the line sits immediately above akm's
+ * own rows rather than at the top of the crontab; it is plain text a person
+ * can edit with `crontab -e`, rewritten on every akm crontab write and
+ * removed together with the last akm task block.
+ */
+export function renderEnvBlock(envPath) {
+    return [ENV_BEGIN, `PATH=${assertCronValue(dedupeSearchPath(envPath))}`, ENV_END].join("\n");
+}
+export function upsertEnvBlock(existing, envPath) {
+    const lines = removeEnvBlock(existing).split(/\r?\n/);
+    const firstBlock = lines.findIndex((line) => BLOCK_RE.test(line));
+    if (!envPath || firstBlock === -1)
+        return lines.join("\n");
+    return [...lines.slice(0, firstBlock), renderEnvBlock(envPath), ...lines.slice(firstBlock)].join("\n");
+}
+export function removeEnvBlock(existing) {
+    const lines = existing.split(/\r?\n/);
+    const start = lines.indexOf(ENV_BEGIN);
+    if (start === -1)
+        return existing;
+    const end = lines.indexOf(ENV_END, start);
+    if (end === -1) {
+        throw new ConfigError("Crontab contains a malformed akm environment section; refusing to modify it.", "INVALID_CONFIG_FILE");
+    }
+    return [...lines.slice(0, start), ...lines.slice(end + 1)].join("\n");
+}
+function dedupeSearchPath(value) {
+    const seen = new Set();
+    const entries = [];
+    for (const entry of value.split(path.delimiter)) {
+        if (entry.length === 0 || seen.has(entry))
+            continue;
+        seen.add(entry);
+        entries.push(entry);
+    }
+    return entries.join(path.delimiter);
+}
 export function toggleBlock(existing, id, enabled) {
     parseBlocks(existing);
-    const lines = existing.split(/\r?\n/);
     const out = [];
     let inBlock = false;
-    for (const line of lines) {
+    for (const line of existing.split(/\r?\n/)) {
         if (!inBlock && line === BEGIN(id)) {
             inBlock = true;
             out.push(line);
@@ -485,15 +384,12 @@ export function toggleBlock(existing, id, enabled) {
         }
         if (inBlock) {
             const isComment = line.startsWith(DISABLED_PREFIX);
-            if (enabled && isComment) {
+            if (enabled && isComment)
                 out.push(line.slice(DISABLED_PREFIX.length));
-            }
-            else if (!enabled && !isComment) {
+            else if (!enabled && !isComment)
                 out.push(`${DISABLED_PREFIX}${line}`);
-            }
-            else {
+            else
                 out.push(line);
-            }
             continue;
         }
         out.push(line);
@@ -529,17 +425,16 @@ function readCrontab(exec) {
     const result = exec.read();
     if (result.status === 0)
         return result.stdout ?? "";
-    // The spawn itself failed to find the binary (ENOENT) — this is the only
-    // case where "install/PATH the crontab binary" is the correct remedy.
+    // The spawn itself failed to find the binary (ENOENT) — the only case
+    // where "install/PATH the crontab binary" is the correct remedy.
     if (result.enoent) {
         throw new ConfigError("crontab -l failed: the `crontab` binary was not found on PATH.", "INVALID_CONFIG_FILE", "Install the `crontab` binary (e.g. cron/cronie/vixie-cron) or add one to PATH.");
     }
     // #910: a nonzero exit that says nothing at all, or whose stderr says
     // "no crontab" (BSD's "no crontab for <user>"; a supercronic-managed PATH
     // shim like OpenPalm's before any spool exists), is cron's own contract
-    // for "empty crontab" — not evidence the binary is missing or broken. A
-    // nonzero exit that DID say something else (a permission refusal) is
-    // reported as what it said, below.
+    // for "empty crontab". A nonzero exit that DID say something else (a
+    // permission refusal) is reported as what it said.
     const stderr = (result.stderr ?? "").trim();
     if (((result.stdout ?? "").trim() === "" && stderr === "") || /no crontab/i.test(stderr))
         return "";
@@ -552,6 +447,7 @@ function writeCrontab(exec, content) {
         hint: "Ensure the `crontab` binary is on PATH and your shell can write the user crontab.",
     });
 }
+/** Write the next crontab; when that fails, put the prior one back before rethrowing. */
 function replaceCrontab(exec, existing, next) {
     try {
         writeCrontab(exec, next);
@@ -568,24 +464,17 @@ function replaceCrontab(exec, existing, next) {
     }
 }
 function defaultCronExec() {
+    const run = (args, input) => {
+        const r = spawnSync("crontab", args, { encoding: "utf8", ...(input !== undefined ? { input } : {}) });
+        return {
+            status: r.status ?? 1,
+            stdout: r.stdout ?? "",
+            stderr: r.stderr ?? "",
+            enoent: r.error?.code === "ENOENT",
+        };
+    };
     return {
-        read() {
-            const r = spawnSync("crontab", ["-l"], { encoding: "utf8" });
-            return {
-                status: r.status ?? 1,
-                stdout: r.stdout ?? "",
-                stderr: r.stderr ?? "",
-                enoent: r.error?.code === "ENOENT",
-            };
-        },
-        write(content) {
-            const r = spawnSync("crontab", ["-"], { encoding: "utf8", input: content });
-            return {
-                status: r.status ?? 1,
-                stdout: r.stdout ?? "",
-                stderr: r.stderr ?? "",
-                enoent: r.error?.code === "ENOENT",
-            };
-        },
+        read: () => run(["-l"]),
+        write: (content) => run(["-"], content),
     };
 }