akm-cli 0.9.17-alpha.6 → 0.9.17-alpha.8

package/dist/storage/repositories/index-entries-repository.js

@@ -21,6 +21,7 @@ import { buildSearchText } from "../../indexer/search/search-fields.js";
 import { sha256Hex } from "../../runtime.js";
 import { ENTRY_COLUMNS, rowToIndexedEntry } from "./index-entry-mapper.js";
 import { deleteFtsEntries, replaceFtsEntry } from "./index-fts-repository.js";
+import { deleteEntryLinks, replaceEntryLinks } from "./index-links-repository.js";
 import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
 import { deleteEntryVectors } from "./index-vec-repository.js";
 // ── Entry operations ────────────────────────────────────────────────────────
@@ -36,9 +37,9 @@ function embedHash(entry) {
  * Insert or update one canonical entry and all synchronously derived search
  * state. Returns the stable row id.
  *
- * The entries row, FTS projection, and stale-vector invalidation commit as one
- * SQLite transaction. Callers therefore cannot publish an entry and forget a
- * second FTS maintenance step.
+ * The entries row, FTS projection, declared links, and stale-vector
+ * invalidation commit as one SQLite transaction. Callers therefore cannot
+ * publish an entry and forget a second FTS or links maintenance step.
  */
 export function upsertEntry(db, filePath, entry, provenance, contentHash) {
     // Hot path during indexing — cache prepared statements per database
@@ -59,6 +60,7 @@ export function upsertEntry(db, filePath, entry, provenance, contentHash) {
         if (previous?.id === result.id && previous.embed_hash !== hash)
             deleteEntryVectors(db, result.id);
         replaceFtsEntry(db, result.id, entry, hasMarkdownFragmentContent(entry) ? (getMarkdownFragmentContent(entry) ?? null) : undefined);
+        replaceEntryLinks(db, result.id, entry, provenance);
         return result.id;
     };
     // Always enter the driver's transaction wrapper. Both supported SQLite
@@ -258,8 +260,10 @@ export function rekeyEntryInPlace(db, opts) {
         }
         if (row.embed_hash !== hash)
             deleteEntryVectors(db, row.id);
-        if (document)
+        if (document) {
             replaceFtsEntry(db, row.id, document, hasMarkdownFragmentContent(document) ? (getMarkdownFragmentContent(document) ?? null) : undefined);
+            replaceEntryLinks(db, row.id, document, { bundleId: opts.sourceName, conceptId: opts.newRef });
+        }
         else
             deleteFtsEntries(db, [row.id]);
     })();
@@ -396,9 +400,11 @@ function deleteRelatedRows(db, ids, options = {}) {
     if (ids.length === 0)
         return;
     const numericIds = ids.map((r) => r.id);
-    // FTS is part of the canonical mutation boundary, not a caller-maintained
-    // dirty queue. Delete it before the parent row inside this transaction.
+    // FTS and declared links are part of the canonical mutation boundary, not a
+    // caller-maintained dirty queue. Delete them before the parent row inside
+    // this transaction.
     deleteFtsEntries(db, numericIds);
+    deleteEntryLinks(db, numericIds);
     // Process in chunks to stay within SQLITE_MAX_VARIABLE_NUMBER
     for (let i = 0; i < numericIds.length; i += SQLITE_CHUNK_SIZE) {
         const chunk = numericIds.slice(i, i + SQLITE_CHUNK_SIZE);

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

@@ -11,6 +11,10 @@
  * touching embeddings, utility scores, graph rows, or the LLM enrichment
  * cache. A newer layout is refused, naming the upgrade.
  */
+// 26: declared links (#935) live in `asset_links`, one row per link, owned by
+// the entry that declares it. The writable opener derives them in place from
+// each entry's stored `document_json` (`migrateToDeclaredLinks`,
+// index-schema.ts); releases before 26 did not store them.
 // 25: vectors live only in `embeddings`; the sqlite-vec mirror `entries_vec`
 // is dropped (`dropVecMirror`, index-schema.ts), and so is the fragment FTS
 // table `entry_fragments_fts`, which search no longer reads. `entries` keeps
@@ -21,7 +25,7 @@
 // 23 and earlier stored a second copy of every indexed field in FTS5's own
 // content shadow tables. `ensureFtsLayout` (index-schema.ts) rebuilds the FTS
 // tables from the stored entries when it finds the older layout.
-export const CANONICAL_INDEX_DB_VERSION = 25;
+export const CANONICAL_INDEX_DB_VERSION = 26;
 export const CANONICAL_ENTRY_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS entries (
     id            INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -47,6 +51,19 @@ export const CANONICAL_ENTRY_SCHEMA_SQL = `
     entry_id INTEGER PRIMARY KEY REFERENCES entries(id) ON DELETE CASCADE,
     safe_markdown TEXT NOT NULL
   );
+
+  -- Declared links (#935). dst_bundle NULL: the declaring entry's own bundle.
+  CREATE TABLE IF NOT EXISTS asset_links (
+    entry_id    INTEGER NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+    ord         INTEGER NOT NULL,
+    kind        TEXT NOT NULL,
+    raw         TEXT NOT NULL,
+    dst_bundle  TEXT,
+    dst_concept TEXT NOT NULL,
+    PRIMARY KEY (entry_id, ord)
+  ) WITHOUT ROWID;
+
+  CREATE INDEX IF NOT EXISTS idx_asset_links_dst ON asset_links(dst_concept);
 `;
 // The FTS table is contentless: FTS5 keeps only the inverted index, and a row
 // is addressed by its rowid (`entries_fts.rowid = entries.id`, see

package/dist/storage/repositories/index-links-repository.js

@@ -0,0 +1,143 @@
+// 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/.
+/**
+ * `index.db` declared-links repository (#935): owns every SQL statement
+ * against `asset_links`.
+ *
+ * A row belongs to the entry that declares the link and is written, replaced
+ * and deleted with that entry (`upsertEntry`, `deleteRelatedRows`). A target
+ * is stored as `dst_bundle` (NULL for a short ref, meaning the declaring
+ * entry's own bundle) plus `dst_concept`; whether it exists is a join on
+ * `entries.item_ref` at read time, so a target indexed later resolves with
+ * no rewrite of its citer and a bundle rename carries short refs along.
+ *
+ * A memory target whose own file is gone resolves to its `.derived` child, the
+ * reachability rule lint applies (#882): consolidation keeps the distilled
+ * child after the parent is pruned.
+ */
+import { declaredLinks } from "../../indexer/links/declared-links.js";
+import { tableExists } from "./index-entry-schema.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+const statementsByDb = new WeakMap();
+function statements(db) {
+    const existing = statementsByDb.get(db);
+    if (existing)
+        return existing;
+    const created = {
+        deleteForEntry: db.prepare("DELETE FROM asset_links WHERE entry_id = ?"),
+        insert: db.prepare("INSERT INTO asset_links (entry_id, ord, kind, raw, dst_bundle, dst_concept) VALUES (?, ?, ?, ?, ?, ?)"),
+    };
+    statementsByDb.set(db, created);
+    return created;
+}
+/** Replace one entry's declared links with the ones its document names, inside the caller's transaction. */
+export function replaceEntryLinks(db, entryId, document, owner) {
+    const { deleteForEntry, insert } = statements(db);
+    deleteForEntry.run(entryId);
+    declaredLinks(document, owner).forEach((link, ord) => {
+        insert.run(entryId, ord, link.kind, link.raw, link.bundle ?? null, link.conceptId);
+    });
+}
+/** Delete the declared links of entries that are being removed. */
+export function deleteEntryLinks(db, entryIds) {
+    for (let i = 0; i < entryIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = entryIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        db.prepare(`DELETE FROM asset_links WHERE entry_id IN (${chunk.map(() => "?").join(",")})`).run(...chunk);
+    }
+}
+/**
+ * Derive every entry's links from its stored `document_json`, replacing
+ * whatever the table held — the in-place migration to layout 26, which needs
+ * no file read. An entry whose JSON does not parse keeps no links until it is
+ * next indexed.
+ */
+export function rebuildAllEntryLinks(db) {
+    db.exec("DELETE FROM asset_links");
+    const page = db.prepare("SELECT id, bundle_id, concept_id, document_json FROM entries WHERE id > ? ORDER BY id LIMIT 500");
+    let afterId = -1;
+    for (;;) {
+        const rows = page.all(afterId);
+        if (rows.length === 0)
+            break;
+        afterId = rows[rows.length - 1].id;
+        for (const row of rows) {
+            let document;
+            try {
+                document = JSON.parse(row.document_json);
+            }
+            catch {
+                continue;
+            }
+            replaceEntryLinks(db, row.id, document, { bundleId: row.bundle_id, conceptId: row.concept_id });
+        }
+    }
+}
+/**
+ * The id of the entry a link row resolves to, or NULL: the exact target, else
+ * (for a memory) its `.derived` child, never the declaring entry itself.
+ * Expects `l` (the link) and `o` (its owner) in scope.
+ */
+const TARGET_ID_SQL = `COALESCE(
+    (SELECT id FROM entries WHERE item_ref = COALESCE(l.dst_bundle, o.bundle_id) || '//' || l.dst_concept),
+    (SELECT id FROM entries
+      WHERE item_ref = COALESCE(l.dst_bundle, o.bundle_id) || '//' || l.dst_concept || '.derived'
+        AND substr(l.dst_concept, 1, 9) = 'memories/' AND id <> o.id))`;
+/**
+ * The declared links of the entry `itemRef`, both ways: `outgoing` in stored
+ * order (unresolved targets carry only `raw`), `incoming` from every other
+ * entry that names it, ordered by kind then source. An index that predates
+ * the table (an older layout served as-is) has none.
+ */
+export function readEntryLinks(db, itemRef) {
+    if (!tableExists(db, "asset_links"))
+        return { outgoing: [], incoming: [] };
+    const owner = db.prepare("SELECT id, bundle_id, concept_id FROM entries WHERE item_ref = ?").get(itemRef);
+    if (!owner)
+        return { outgoing: [], incoming: [] };
+    const outgoing = db
+        .prepare(`SELECT l.kind AS kind, l.raw AS raw, t.bundle_id AS bundleId, t.concept_id AS conceptId, t.type AS type
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+         LEFT JOIN entries t ON t.id = ${TARGET_ID_SQL}
+        WHERE l.entry_id = ?
+        ORDER BY l.ord`)
+        .all(owner.id);
+    // A `.derived` memory also receives the links that name its parent when the
+    // parent is not indexed (the resolution rule above).
+    const parentConcept = owner.concept_id.startsWith("memories/") && owner.concept_id.endsWith(".derived")
+        ? owner.concept_id.slice(0, -".derived".length)
+        : owner.concept_id;
+    const incoming = db
+        .prepare(`SELECT l.kind AS kind, o.bundle_id AS bundleId, o.concept_id AS conceptId, o.type AS type
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+        WHERE l.dst_concept IN (?, ?) AND COALESCE(l.dst_bundle, o.bundle_id) = ? AND o.id <> ?
+          AND ${TARGET_ID_SQL} = ?
+        ORDER BY l.kind, o.item_ref`)
+        .all(owner.concept_id, parentConcept, owner.bundle_id, owner.id, owner.id);
+    return {
+        outgoing: outgoing.map((row) => row.conceptId === null
+            ? { kind: row.kind, raw: row.raw }
+            : {
+                kind: row.kind,
+                bundleId: row.bundleId ?? undefined,
+                conceptId: row.conceptId,
+                type: row.type ?? undefined,
+            }),
+        incoming,
+    };
+}
+/** Stored links per kind with how many name a target that is not indexed; empty when the index has none. */
+export function countLinksByKind(db) {
+    if (!tableExists(db, "asset_links"))
+        return {};
+    const rows = db
+        .prepare(`SELECT l.kind AS kind, COUNT(*) AS total, SUM(${TARGET_ID_SQL} IS NULL) AS unresolved
+         FROM asset_links l
+         JOIN entries o ON o.id = l.entry_id
+        GROUP BY l.kind
+        ORDER BY l.kind`)
+        .all();
+    return Object.fromEntries(rows.map((row) => [row.kind, { total: row.total, unresolved: row.unresolved }]));
+}

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

@@ -18,11 +18,13 @@
  * ({@link newerIndexLayoutError}).
  */
 import { createRequire } from "node:module";
+import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
 import { sha256Hex } from "../../runtime.js";
 import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, entriesFtsDdl, isContentlessFtsDdl, missingEntryColumns, readTableSql, supportsContentlessDelete, tableExists, } from "./index-entry-schema.js";
 import { rebuildFts } from "./index-fts-repository.js";
+import { rebuildAllEntryLinks } from "./index-links-repository.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 export const DB_VERSION = CANONICAL_INDEX_DB_VERSION;
@@ -34,6 +36,8 @@ export const VACUUM_PENDING_META = "vacuumPending";
  * compares it; the index layout version gates the graph tables' shape.
  */
 export const GRAPH_SCHEMA_VERSION = 4;
+/** The layout that added declared links (`asset_links`, #935). */
+const DECLARED_LINKS_LAYOUT = 26;
 /**
  * The refusal for an index a newer akm wrote. Readers and the writable opener
  * both raise it: a newer layout may lack tables or columns this release reads
@@ -170,6 +174,7 @@ function ensureEntriesLayout(db) {
         for (const table of [
             "entries_fts",
             "entry_fragments",
+            "asset_links",
             "embeddings",
             "utility_scores_scoped",
             "utility_scores",
@@ -249,6 +254,25 @@ function ensureFtsLayout(db) {
         rebuildFts(db);
     })();
 }
+/**
+ * Layout 26 stores declared links (#935). Every relation an older layout
+ * indexed already sits in `document_json`, so the links are derived from there
+ * in place, with no file read. The exception is a workflow's step targets and
+ * a task's target, which no earlier layout stored: the directories holding
+ * workflows and tasks lose their incremental cursor, so the next `akm index`
+ * re-reads those and nothing else. One transaction.
+ */
+function migrateToDeclaredLinks(db) {
+    db.transaction(() => {
+        rebuildAllEntryLinks(db);
+        const rows = db
+            .prepare("SELECT DISTINCT file_path FROM entries WHERE type IN ('workflow', 'task')")
+            .all();
+        const forget = db.prepare("DELETE FROM index_dir_state WHERE dir_path = ?");
+        for (const dir of new Set(rows.map((row) => path.dirname(row.file_path))))
+            forget.run(dir);
+    })();
+}
 function tableHasColumn(db, table, column) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();
     return columns.some((existing) => existing.name === column);
@@ -368,6 +392,9 @@ export function ensureSchema(db) {
     if (!hadFragmentSource && tableExists(db, "entries")) {
         db.exec("DELETE FROM index_dir_state");
     }
+    if (storedVersion > 0 && storedVersion < DECLARED_LINKS_LAYOUT && tableExists(db, "entries")) {
+        migrateToDeclaredLinks(db);
+    }
     // Migrating an existing layout drops tables and columns; the next `akm index`
     // VACUUMs the pages they leave free (`vacuumIndexDb`, indexer.ts), since a
     // writable open may run inside a caller's transaction, where VACUUM cannot.

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

@@ -385,6 +385,10 @@ export function getStateProposal(db, id, stashDir) {
     const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
     return row ? proposalRowToProposal(row) : undefined;
 }
+/** `(ref, source)` of every proposal, any status, in one stash: no payload is read. */
+export function listProposalRefSources(db, stashDir) {
+    return db.prepare("SELECT ref, source FROM proposals WHERE stash_dir = ?").all(stashDir);
+}
 /**
  * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
  * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —

package/dist/tasks/backends/cron.js

@@ -7,9 +7,14 @@
 // its other lines untouched:
 //
 //     # akm:task <id> BEGIN
-//     [SCHED] /abs/akm --scheduler-context <descriptor> task run <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 -`. Every mutation is one read → modify the akm blocks (and the
 // `# akm:env` PATH header) → one write, with the prior crontab restored when
@@ -32,13 +37,14 @@
 // 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 { schedulerBindingNativeId, schedulerLogicalBindingId } from "../scheduler-binding.js";
-import { buildScheduledBindingInvocation, parsePublicSchedulerInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, SCHEDULER_CONTEXT_ARG, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.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`;
@@ -55,9 +61,8 @@ export function CRON_BACKEND(options = {}) {
     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));
-    const lineFor = (task, opts) => buildCronLineParts(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath);
+    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) {
@@ -92,7 +97,7 @@ export function CRON_BACKEND(options = {}) {
         list() {
             const rows = [];
             for (const { id, body } of listBlocks(readCrontab(exec))) {
-                const parsed = extractCronInvocation(body);
+                const parsed = extractCronInvocation(body) ?? extractCronWrapperInvocation(body, readFile);
                 if (!parsed)
                     continue;
                 rows.push({
@@ -102,9 +107,8 @@ export function CRON_BACKEND(options = {}) {
                     signature: normalizeSignature(body),
                     ...(parsed.target !== undefined ? { target: parsed.target } : {}),
                     binding: parsed.binding,
-                    // A pre-0.9.2 row has no descriptor of its own (#881); it reads as
-                    // the current one so ownership resolves and sync rewrites it.
-                    contextPath: parsed.contextPath || defaultContextPath,
+                    ...(parsed.contextPath !== undefined ? { contextPath: parsed.contextPath } : {}),
+                    ...(parsed.environment !== undefined ? { environment: parsed.environment } : {}),
                     invocation: parsed.invocation,
                 });
             }
@@ -117,21 +121,26 @@ export function CRON_BACKEND(options = {}) {
         },
     };
 }
-function buildCronLineParts(task, akmArgv, logDir, contextPath) {
+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. akm's own per-run log
     // (src/tasks/run/task-log.ts) keeps history.
-    const directLine = `${cronExpr} ${cmd} > ${quoteForCron(logPath)} 2>&1`;
+    const directLine = `${cronExpr} ${assignments}${cmd} > ${quoteForCron(logPath)} 2>&1`;
     if (Buffer.byteLength(directLine, "utf8") <= PORTABLE_CRON_LINE_LIMIT)
         return { line: directLine };
     // A command over vixie-cron's MAX_COMMAND is spilled into a short wrapper
     // script under logDir instead of being truncated or refused.
-    const content = `#!/bin/sh\nexec ${invocation.argv.map(quoteForShellScript).join(" ")}\n`;
+    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`;
@@ -142,8 +151,8 @@ function quoteForShellScript(part) {
         return part;
     return `'${part.replace(/'/g, `'\\''`)}'`;
 }
-export function buildCronLine(task, akmArgv, logDir, contextPath) {
-    return buildCronLineParts(task, akmArgv, logDir, contextPath).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) {
@@ -196,46 +205,74 @@ function malformedBlockError(id) {
 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: 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 have no `--scheduler-context` argument at
-    // all — the akm argv is followed directly by the public `task run …` /
-    // `workflow run …` tail (#881). This only ever runs on a body already
-    // isolated between akm's own BEGIN/END markers, so recognizing the older
-    // shape extends no trust to unmarked crontab lines. A row that DOES carry
-    // the marker but fails to parse is never reinterpreted as legacy.
-    if (tail.includes(SCHEDULER_CONTEXT_ARG))
+    const parsed = parseScheduledInvocationArgv(fields.slice(commandStart, redirectIndex));
+    if (!parsed)
         return undefined;
-    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 } : {}),
-            };
-        }
+    const environment = scheduledRowEnvironmentFrom(variables);
+    return environment ? { ...parsed, environment } : parsed;
+}
+/**
+ * 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);
     }
-    return undefined;
+    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));
+    }
+    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 = "";
@@ -246,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;

package/dist/tasks/backends/launchd.js

@@ -17,7 +17,9 @@
  *     when the user is logged out should be installed as system Daemons,
  *     which is out of scope.
  *   • launchd strips the environment; the syncing shell's PATH goes into the
- *     plist's `EnvironmentVariables` so task bodies find the same binaries.
+ *     plist's `EnvironmentVariables` so task bodies find the same binaries,
+ *     next to the AKM directory environment the row sets (see
+ *     `src/tasks/scheduler-invocation.ts`).
  *
  * Tests inject a fake exec + filesystem so the backend can be unit-tested
  * without touching the host launchctl.
@@ -33,7 +35,7 @@ import { warn } from "../../core/warn.js";
 import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { schedulerBindingNativeId, schedulerLogicalBindingId } from "../scheduler-binding.js";
-import { buildScheduledBindingInvocation, parseScheduledBindingArgv, resolveScheduledTaskContext, schedulerContextDescriptor, schedulerContextPath, } from "../scheduler-invocation.js";
+import { buildScheduledInvocation, parseScheduledInvocationArgv, scheduledRowEnvironmentEntries, scheduledRowEnvironmentFrom, } from "../scheduler-invocation.js";
 import { escapeXml, nodeExec, nodeFs, runOrThrow } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";
 const LAUNCHD_AKM_LABEL_RE = /^com\.akm\.task\.[A-Za-z0-9._-]{1,1024}$/u;
@@ -43,9 +45,7 @@ export function LAUNCHD_BACKEND(options = {}) {
     const agentsDir = options.agentsDir ?? defaultAgentsDir();
     const logDir = options.logDir ?? getTaskLogDir();
     const akmArgv = options.akmArgv ?? resolveAkmInvocation().argv;
-    const scheduledContext = options.scheduledContext ?? resolveScheduledTaskContext();
     const envPath = options.envPath === false ? undefined : typeof options.envPath === "string" ? options.envPath : process.env.PATH;
-    const defaultContextPath = schedulerContextPath(schedulerContextDescriptor(scheduledContext));
     const plistPath = (nativeId) => path.join(agentsDir, `${LAUNCHD_LABEL_PREFIX}${nativeId}.plist`);
     const label = (nativeId) => `${LAUNCHD_LABEL_PREFIX}${nativeId}`;
     const target = (nativeId) => `gui/${exec.uid()}/${label(nativeId)}`;
@@ -59,7 +59,7 @@ export function LAUNCHD_BACKEND(options = {}) {
         isOk: (r) => r.status === 0 || isServiceNotFoundResult(r),
         message: (r) => `launchctl bootout failed (exit ${r.status}): ${r.stderr || r.stdout || "no output"}.`,
     });
-    const xmlFor = (task, opts) => buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.contextPath ?? defaultContextPath, envPath);
+    const xmlFor = (task, opts) => buildPlistXml(task, [...(opts?.binding ?? akmArgv)], logDir, opts?.environment, envPath);
     return {
         name: "launchd",
         install(task, opts) {
@@ -130,7 +130,8 @@ export function LAUNCHD_BACKEND(options = {}) {
                     signature: launchdFingerprint(raw, enabled, loaded),
                     ...(parsed.target !== undefined ? { target: parsed.target } : {}),
                     binding: parsed.binding,
-                    contextPath: parsed.contextPath,
+                    ...(parsed.contextPath !== undefined ? { contextPath: parsed.contextPath } : {}),
+                    ...(parsed.environment !== undefined ? { environment: parsed.environment } : {}),
                     invocation: parsed.invocation,
                 });
             }
@@ -150,7 +151,16 @@ export function extractPlistInvocation(xml) {
     if (!block)
         return undefined;
     const args = [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => decodeXmlEntities(m[1]));
-    return parseScheduledBindingArgv(args);
+    const parsed = parseScheduledInvocationArgv(args);
+    if (!parsed)
+        return undefined;
+    const variables = {};
+    const dict = xml.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/)?.[1] ?? "";
+    for (const entry of dict.matchAll(/<key>([^<]*)<\/key>\s*<string>([\s\S]*?)<\/string>/g)) {
+        variables[decodeXmlEntities(entry[1])] = decodeXmlEntities(entry[2]);
+    }
+    const environment = scheduledRowEnvironmentFrom(variables);
+    return environment ? { ...parsed, environment } : parsed;
 }
 function decodeXmlEntities(value) {
     return value
@@ -161,22 +171,25 @@ function decodeXmlEntities(value) {
         .replaceAll("&amp;", "&");
 }
 // ── XML builder (exported for tests) ────────────────────────────────────────
-function renderPlistEnvironment(envPath) {
-    if (!envPath)
+function renderPlistEnvironment(envPath, environment) {
+    const variables = [
+        ...(envPath ? [["PATH", envPath]] : []),
+        ...scheduledRowEnvironmentEntries(environment),
+    ];
+    if (variables.length === 0)
         return "";
     return [
         "  <key>EnvironmentVariables</key>",
         "  <dict>",
-        "    <key>PATH</key>",
-        `    <string>${escapeXml(envPath)}</string>`,
+        ...variables.flatMap(([name, value]) => [`    <key>${name}</key>`, `    <string>${escapeXml(value)}</string>`]),
         "  </dict>",
         "",
     ].join("\n");
 }
-export function buildPlistXml(task, akmArgv, logDir, contextPath, envPath) {
+export function buildPlistXml(task, akmArgv, logDir, environment, envPath) {
     const trigger = translateToLaunchd(parseSchedule(task.cron, "launchd"));
-    const invocation = buildScheduledBindingInvocation(akmArgv, contextPath, task.invocation);
-    const programArgs = invocation.argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
+    const argv = buildScheduledInvocation(akmArgv, task.invocation);
+    const programArgs = argv.map((a) => `      <string>${escapeXml(a)}</string>`).join("\n");
     const nativeId = schedulerBindingNativeId(task);
     const logPath = path.join(logDir, `${nativeId}.log`);
     const xml = launchdTemplate
@@ -184,7 +197,7 @@ export function buildPlistXml(task, akmArgv, logDir, contextPath, envPath) {
         .replace("{{LABEL}}", LAUNCHD_LABEL_PREFIX + escapeXml(nativeId))
         .replace("{{PROGRAM_ARGS}}", programArgs)
         .replaceAll("{{LOG_PATH}}", escapeXml(logPath))
-        .replace("{{ENV_VARS}}", renderPlistEnvironment(envPath))
+        .replace("{{ENV_VARS}}", () => renderPlistEnvironment(envPath, environment))
         .replace("{{TRIGGER_XML}}", renderLaunchdTrigger(trigger));
     for (const char of xml) {
         const code = char.codePointAt(0) ?? 0;