akm-cli 0.9.10 → 0.9.12

package/dist/tasks/prepare/script-capture.js

@@ -33,17 +33,49 @@ const SCRIPT_INTERPRETERS = Object.freeze({
     ".kt": "kotlin",
     ".kts": "kotlin",
 });
-export function scriptInterpreter(extension, ref) {
-    const interpreter = SCRIPT_INTERPRETERS[extension];
+const SHEBANG_INTERPRETERS = [
+    [/^(bash|sh|zsh|dash|ksh)$/, "sh"],
+    [/^python[0-9.]*$/, "python"],
+    [/^ruby$/, "ruby"],
+    [/^perl$/, "perl"],
+    [/^php$/, "php"],
+    [/^lua$/, "lua"],
+    [/^node$/, "node"],
+];
+function interpreterFromShebang(bytes) {
+    if (!bytes || bytes.length < 2 || bytes[0] !== 0x23 || bytes[1] !== 0x21)
+        return undefined;
+    const newline = bytes.indexOf(0x0a);
+    const lineBytes = newline === -1 ? bytes.subarray(2) : bytes.subarray(2, newline);
+    const tokens = Buffer.from(lineBytes).toString("utf8").trim().split(/\s+/).filter(Boolean);
+    const [first, second] = tokens;
+    const named = first?.split("/").pop() === "env" ? second : first?.split("/").pop();
+    if (!named)
+        return undefined;
+    for (const [pattern, interpreter] of SHEBANG_INTERPRETERS) {
+        if (pattern.test(named))
+            return interpreter;
+    }
+    return undefined;
+}
+function nodeStripsTypeScript() {
+    const features = process.features;
+    return Boolean(features?.typescript);
+}
+export function scriptInterpreter(extension, ref, bytes) {
+    const interpreter = SCRIPT_INTERPRETERS[extension] ?? (extension === "" ? interpreterFromShebang(bytes) : undefined);
     if (!interpreter) {
         throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} has no closed runtime interpreter for extension ${JSON.stringify(extension)}.`, "TASK_TARGET_UNSUPPORTED");
     }
     if (interpreter !== "bun")
         return interpreter;
-    if (!process.versions.bun) {
-        throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} requires Bun for ${extension} execution, but this runtime cannot provide it.`, "TASK_TARGET_UNSUPPORTED");
+    if (process.versions.bun) {
+        return isBunStandaloneMain() ? "bun-standalone" : "bun";
+    }
+    if (extension === ".js" || (extension === ".ts" && nodeStripsTypeScript())) {
+        return "node";
     }
-    return isBunStandaloneMain() ? "bun-standalone" : "bun";
+    throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} requires Bun for ${extension} execution, but this runtime cannot provide it.`, "TASK_TARGET_UNSUPPORTED");
 }
 export function captureDirectoryIdentity(bundleRoot, workingDirectory) {
     try {
@@ -69,7 +101,7 @@ export function captureScriptTarget(ref, file, bundleRoot, readFile) {
     const bytes = Uint8Array.from(raw);
     const cwdIdentity = captureDirectoryIdentity(bundleRoot);
     return Object.freeze({
-        interpreter: scriptInterpreter(extension, ref),
+        interpreter: scriptInterpreter(extension, ref, bytes),
         extension,
         bytesBase64: Buffer.from(bytes).toString("base64"),
         byteLength: bytes.byteLength,

package/dist/tasks/schedule.js

@@ -15,10 +15,13 @@
  *   • a launchd plist `<StartCalendarInterval>` / `<StartInterval>` (macOS),
  *   • Task Scheduler XML triggers (Windows).
  *
- * The shared subset is `*`, single integers, `*\/N`, `A-B/N`, plus the `@hourly /
- * @daily / @weekly / @monthly` aliases. Patterns outside that — multi-value
- * lists, plain ranges, day-of-month AND
- * day-of-week combinations — are rejected with a {@link UsageError}.
+ * The shared subset is `*`, single integers, `*\/N`, `A-B`, `A-B/N`, comma
+ * lists, three-letter day/month names (`MON`, `JAN`) and name ranges
+ * (`MON-FRI`), plus the `@hourly / @daily / @weekly / @monthly / @yearly /
+ * @annually / @reboot` aliases. Day-of-month AND day-of-week combined in the
+ * same expression are rejected with a {@link UsageError} — cron gives that
+ * combination OR semantics no other backend can express portably, and it is
+ * genuinely ambiguous to a person reading the schedule back.
  *
  * Cron is the most permissive of the three backends; some patterns it
  * accepts (e.g. `@hourly` = `0 * * * *`) have no clean schtasks primitive.
@@ -33,7 +36,58 @@ const ALIAS_TO_CRON = {
     "@midnight": "0 0 * * *",
     "@weekly": "0 0 * * 0",
     "@monthly": "0 0 1 * *",
+    "@yearly": "0 0 1 1 *",
+    "@annually": "0 0 1 1 *",
 };
+/**
+ * vixie-cron's one true nickname with no 5-field equivalent — it fires once at
+ * daemon startup, not on a recurring calendar boundary. Passed straight
+ * through, unexpanded, on the cron backend (a real crontab line is just
+ * `@reboot <command>`); launchd and schtasks have no "run at boot" trigger in
+ * the vocabulary this module targets, so those backends reject it.
+ */
+const REBOOT_ALIAS = "@reboot";
+/** Placeholder fields for the `@reboot` `ScheduleSpec` — never read: cron's translator emits `spec.cron` verbatim, and launchd/schtasks refuse `@reboot` before touching `fields`. */
+const REBOOT_FIELDS = {
+    minute: { kind: "star" },
+    hour: { kind: "star" },
+    dom: { kind: "star" },
+    month: { kind: "star" },
+    dow: { kind: "star" },
+};
+const DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+/**
+ * Substitute three-letter day-of-week / month names (and name ranges, e.g.
+ * `MON-FRI`) with their numeric cron equivalents, case-insensitively, so the
+ * existing numeric grammar below (value / range / list) parses the result
+ * unchanged. Tokens that are not recognized names pass through untouched —
+ * they are numbers already, or genuinely invalid and left for the numeric
+ * parsers to reject with their own message.
+ */
+function substituteNamedTokens(raw, fieldName) {
+    const names = fieldName === "month" ? MONTH_NAMES : DOW_NAMES;
+    const offset = fieldName === "month" ? 1 : 0;
+    const indexOf = (token) => {
+        const idx = names.indexOf(token.toLowerCase());
+        return idx === -1 ? undefined : idx + offset;
+    };
+    return raw
+        .split(",")
+        .map((part) => {
+        const rangeMatch = part.match(/^([A-Za-z]{3})-([A-Za-z]{3})$/);
+        if (rangeMatch) {
+            const start = indexOf(rangeMatch[1]);
+            const end = indexOf(rangeMatch[2]);
+            if (start !== undefined && end !== undefined)
+                return `${start}-${end}`;
+            return part;
+        }
+        const single = /^[A-Za-z]{3}$/.test(part) ? indexOf(part) : undefined;
+        return single !== undefined ? String(single) : part;
+    })
+        .join(",");
+}
 const FIELD_LIMITS = {
     minute: { min: 0, max: 59 },
     hour: { min: 0, max: 23 },
@@ -41,10 +95,17 @@ const FIELD_LIMITS = {
     month: { min: 1, max: 12 },
     dow: { min: 0, max: 6 },
 };
-const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), steps (`*/N`, `A-B/N`), and comma lists (`7,37`). " +
-    "Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`. " +
-    "Plain ranges and named days/months are not supported.";
+const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), ranges (`A-B`), steps (`*/N`, `A-B/N`), and comma lists " +
+    "(`7,37`). Day-of-week and month fields also accept three-letter names and name ranges (`MON`, `MON-FRI`, " +
+    "`JAN`). Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`/`@annually`, `@reboot` (cron only).";
 export function parseSchedule(input, backend) {
+    const trimmed = input.trim();
+    if (trimmed.toLowerCase() === REBOOT_ALIAS) {
+        if (backend !== "cron") {
+            throw new UsageError(`Schedule "${input}" (@reboot, run once at startup) has no ${backend === "launchd" ? "macOS launchd" : "Windows Task Scheduler"} equivalent this release expresses. Use a cron-backed install, or rewrite the task with a recurring schedule.`, "INVALID_FLAG_VALUE");
+        }
+        return { raw: input, cron: REBOOT_ALIAS, fields: REBOOT_FIELDS };
+    }
     const cron = expandAlias(input);
     const fields = parseCronFields(cron, input);
     const spec = { raw: input, cron, fields };
@@ -84,7 +145,8 @@ function parseCronFields(cron, original) {
         dow: parseField(dow, "day-of-week", FIELD_LIMITS.dow, original),
     };
 }
-function parseField(raw, name, limit, original) {
+function parseField(rawInput, name, limit, original) {
+    const raw = name === "month" || name === "day-of-week" ? substituteNamedTokens(rawInput, name) : rawInput;
     if (raw === "*")
         return { kind: "star" };
     const stepMatch = raw.match(/^\*\/(\d+)$/);
@@ -109,6 +171,19 @@ function parseField(raw, name, limit, original) {
         }
         return { kind: "rangeStep", start, end, step };
     }
+    // Plain range, no step: `A-B` (e.g. `1-5` for Mon-Fri, `1-5` for the first
+    // five days of the month). Represented as a `rangeStep` with `step: 1` so
+    // every downstream consumer (verbatim cron passthrough, launchd/schtasks
+    // expansion) reuses the exact same handling a stepped range already gets.
+    const rangeMatch = raw.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+        const start = Number(rangeMatch[1]);
+        const end = Number(rangeMatch[2]);
+        if (start < limit.min || end > limit.max || start > end) {
+            throw new UsageError(`Invalid ${name} range "${raw}" in schedule "${original}" (allowed ${limit.min}-${limit.max}).`, "INVALID_FLAG_VALUE");
+        }
+        return { kind: "rangeStep", start, end, step: 1 };
+    }
     if (/^\d+$/.test(raw)) {
         const value = Number(raw);
         if (value < limit.min || value > limit.max) {
@@ -161,6 +236,42 @@ export function translateToLaunchd(spec) {
             })),
         };
     }
+    // A day-of-week or month range/list (`1-5` for Mon-Fri, `1,3,5`) has no
+    // single-dict launchd primitive either, but — unlike a step — it names a
+    // small, closed set of concrete values, so it genuinely IS expressible: one
+    // calendar dict per (month, weekday) combination, same trick as the
+    // minute/hour step expansion above. Only attempted when the remaining
+    // fields are already single values or `*`; anything else (e.g. a minute
+    // step combined with a weekday range) falls through to the generic path
+    // below, where `rejectStepInsideCalendar` reports the field it actually
+    // cannot express.
+    const dowValues = expandListLikeField(f.dow, FIELD_LIMITS.dow);
+    const monthValues = expandListLikeField(f.month, FIELD_LIMITS.month);
+    const remainingFieldsAreSimple = (f.minute.kind === "value" || f.minute.kind === "star") &&
+        (f.hour.kind === "value" || f.hour.kind === "star") &&
+        (f.dom.kind === "value" || f.dom.kind === "star");
+    if ((dowValues || monthValues) && remainingFieldsAreSimple) {
+        const base = {};
+        if (f.minute.kind === "value")
+            base.Minute = f.minute.value;
+        if (f.hour.kind === "value")
+            base.Hour = f.hour.value;
+        if (f.dom.kind === "value")
+            base.Day = f.dom.value;
+        const months = monthValues ?? (f.month.kind === "value" ? [f.month.value] : [undefined]);
+        const weekdays = dowValues ?? (f.dow.kind === "value" ? [f.dow.value] : [undefined]);
+        const calendars = [];
+        for (const month of months) {
+            for (const weekday of weekdays) {
+                calendars.push({
+                    ...base,
+                    ...(month !== undefined ? { Month: month } : {}),
+                    ...(weekday !== undefined ? { Weekday: weekday } : {}),
+                });
+            }
+        }
+        return { calendars };
+    }
     // Otherwise build a calendar dict from concrete values. launchd treats any
     // omitted key as "every value", so a `*` field translates to "no key".
     // Exception: launchd does not support arbitrary step values inside a
@@ -199,12 +310,21 @@ function expandFieldValues(field, limit) {
         values.push(value);
     return values;
 }
+/** Discrete values named by a `list` or (stepless) `rangeStep` field; `null` for anything else (`*`, `value`, `step`). */
+function expandListLikeField(field, limit) {
+    if (field.kind === "list")
+        return field.values;
+    if (field.kind === "rangeStep")
+        return expandFieldValues(field, limit);
+    return null;
+}
 function rejectStepInsideCalendar(field, name, spec) {
     if (field.kind === "step") {
         throw new UsageError(`Schedule "${spec.raw}" uses step (${name} = */N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either restrict the step to the minute or hour field only, or rewrite the schedule with concrete values.");
     }
     if (field.kind === "rangeStep") {
-        throw new UsageError(`Schedule "${spec.raw}" uses range-step (${name} = A-B/N) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Restrict the range-step to the minute or hour field, or rewrite the schedule with a concrete value.");
+        const shape = field.step === 1 ? "A-B" : "A-B/N";
+        throw new UsageError(`Schedule "${spec.raw}" uses a range (${name} = ${shape}) in a position macOS launchd cannot express. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Restrict the range to the minute, hour, day-of-week, or month field, or rewrite the schedule with a concrete value.");
     }
     if (field.kind === "list") {
         throw new UsageError(`Schedule "${spec.raw}" uses comma list (${name} = a,b,...) which macOS launchd cannot express as a single trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Either install one task per list element, or rewrite the schedule with a step (`*/N`) or single value.");
@@ -286,20 +406,41 @@ export function translateToSchtasks(spec) {
         f.dow.kind === "star") {
         return { kind: "daily", atHour: f.hour.value, atMinute: f.minute.value };
     }
-    // `M H * * D` → WEEKLY at H:M on day D.
+    // `M H * * D` → WEEKLY at H:M on day(s) D — a single day, a plain range
+    // (`1-5`, e.g. from `MON-FRI`), or a comma list all name a small closed set
+    // of weekdays that Task Scheduler's native `<DaysOfWeek>` already takes as
+    // a set, so no expansion into multiple triggers is needed.
     if (f.minute.kind === "value" &&
         f.hour.kind === "value" &&
         f.dom.kind === "star" &&
         f.month.kind === "star" &&
-        f.dow.kind === "value") {
+        (f.dow.kind === "value" || f.dow.kind === "list" || f.dow.kind === "rangeStep")) {
+        const daysOfWeek = f.dow.kind === "value" ? [f.dow.value] : expandListLikeField(f.dow, FIELD_LIMITS.dow);
         return {
             kind: "weekly",
             atHour: f.hour.value,
             atMinute: f.minute.value,
-            daysOfWeek: [f.dow.value],
+            daysOfWeek,
         };
     }
-    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: minute steps/range-steps, fixed-minute hour steps/range-steps, hourly, daily, or weekly on a single weekday.");
+    // `M H D * *` / `M H D m *` → MONTHLY at H:M on day(s)-of-month D, in the
+    // given month(s) m (or every month when `m` is `*`). Task Scheduler's
+    // `ScheduleByMonth` trigger takes both as native sets, same as `ScheduleByWeek`
+    // above.
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "value" &&
+        (f.dom.kind === "value" || f.dom.kind === "list") &&
+        (f.month.kind === "star" || f.month.kind === "value" || f.month.kind === "list") &&
+        f.dow.kind === "star") {
+        const daysOfMonth = f.dom.kind === "value" ? [f.dom.value] : f.dom.values;
+        const months = f.month.kind === "star"
+            ? Array.from({ length: 12 }, (_, i) => i + 1)
+            : f.month.kind === "value"
+                ? [f.month.value]
+                : f.month.values;
+        return { kind: "monthly", atHour: f.hour.value, atMinute: f.minute.value, daysOfMonth, months };
+    }
+    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: minute steps/range-steps, fixed-minute hour steps/range-steps, hourly, daily, weekly on one or more weekdays, or monthly on one or more days-of-month.");
 }
 function minuteValuesTrigger(minutes, spec) {
     if (minutes.length > MAX_SCHTASKS_TRIGGERS) {

package/dist/tasks/scheduler-sync.js

@@ -323,27 +323,9 @@ async function compileTaskSources(input, collector, out, failures) {
             });
             const document = projectTaskSourceV4(parsed.v4);
             const qualifiedRef = makeBundleRef(input.bundleName, conceptId);
-            // P2b Lane B (spec docs/plans/specs/p2b-input-bindings.md §4.4, rows
-            // B-50/F-B2): validate each v4 schedule entry's inputs against the
-            // task's OWN declared contract WITH DEFAULTS APPLIED — the same
-            // applyInputDefaults + validateInputs pair akm task run uses
-            // (src/tasks/run/load-task.ts). parseTaskSource's own parse-time check
-            // (task-source-v4.ts's parseScheduleEntry) already rejects an
-            // unknown/malformed entry against the RAW supplied values; this is a
-            // deliberate second, independent gate over the DEFAULTED view — the
-            // exact set of values the compiled invocation below actually delivers
-            // — so a violation fails HERE, recorded as a task failure at sync,
-            // rather than surfacing for the first time when the scheduler fires
-            // the compiled invocation.
-            const contract = parsed.v4.inputs ?? {};
-            for (const scheduleEntry of parsed.v4.schedule) {
-                const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
-                const errors = validateInputs(contract, defaultedInputs);
-                if (errors.length > 0) {
-                    throw new UsageError(`Task ${JSON.stringify(qualifiedRef)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
-                        `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
-                }
-            }
+            // See assertTaskScheduleInputsSatisfyContract's own docblock (below in
+            // this file) for why this second, defaults-applied gate exists.
+            assertTaskScheduleInputsSatisfyContract(parsed.v4, qualifiedRef);
             await prepareTaskV3Execution(document, {
                 taskId: id,
                 taskRef: qualifiedRef,
@@ -380,16 +362,60 @@ async function compileTaskSources(input, collector, out, failures) {
                     inputs: schedule.inputs,
                 })),
             });
-            for (const binding of sourceBindings) {
-                parseSchedule(binding.cron, input.backend);
-                out.push(binding);
-            }
+            assertTaskScheduleCronValid(parsed.v4, input.backend);
+            out.push(...sourceBindings);
         }
         catch (cause) {
             failures.push(taskFailure(sourcePath, qualifiedRefForFailure, cause));
         }
     }
 }
+/**
+ * P2b Lane B (spec §4.4, rows B-50/F-B2): validate every v4 `schedule:`
+ * entry's `inputs` against the task's OWN declared contract WITH DEFAULTS
+ * APPLIED — the same `applyInputDefaults` + `validateInputs` pair
+ * `akm task run` uses (`src/tasks/run/load-task.ts`). `parseTaskSource`'s
+ * own parse-time check (`task-source-v4.ts`'s `parseScheduleEntry`) already
+ * rejects an unknown/malformed entry against the RAW supplied values; this
+ * is a deliberate second, independent gate over the DEFAULTED view — the
+ * exact set of values a compiled invocation actually delivers — so a
+ * violation fails HERE, recorded as a task failure at sync, rather than
+ * surfacing for the first time when the scheduler fires the invocation.
+ *
+ * Extracted so `akm task validate` can run the IDENTICAL gate
+ * over a bare file path without a second, potentially-diverging copy of
+ * this check. `refLabel` is only the text embedded in the thrown message —
+ * `compileTaskSources` passes its bundle-qualified ref; `akm task validate`,
+ * which never resolves a bundle for a bare file, passes the file path.
+ */
+export function assertTaskScheduleInputsSatisfyContract(v4, refLabel) {
+    const contract = v4.inputs ?? {};
+    for (const scheduleEntry of v4.schedule) {
+        const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
+        const errors = validateInputs(contract, defaultedInputs);
+        if (errors.length > 0) {
+            throw new UsageError(`Task ${JSON.stringify(refLabel)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
+                `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
+        }
+    }
+}
+/**
+ * Validate every v4 `schedule:` entry's `cron` against the active scheduler
+ * backend's dialect (`parseSchedule`, `./schedule.ts`) — cron is the most
+ * permissive of the three backends, so a task authored on Linux can carry a
+ * cron expression launchd/schtasks cannot translate; `compileTaskSources`
+ * re-checks against the LOCAL backend on every sync rather than trusting
+ * whatever backend the file was authored against.
+ *
+ * Extracted alongside {@link assertTaskScheduleInputsSatisfyContract}
+ * so `akm task validate` shares this exact gate instead of a second copy
+ * that could silently drift from what `akm task sync` actually enforces.
+ */
+export function assertTaskScheduleCronValid(v4, backend) {
+    for (const scheduleEntry of v4.schedule) {
+        parseSchedule(scheduleEntry.cron, backend);
+    }
+}
 async function compileWorkflowSources(input, collector, out, evidence, failures) {
     if (input.adapterId !== "akm" && input.adapterId !== "akm-workflow")
         return;

package/dist/tasks/source/task-source-v3-frozen.js

@@ -377,7 +377,6 @@ export function parseTaskV3Document(value, options) {
         if (own(input, "with"))
             sourceError(ctx, ["with"], "is legal only with uses.");
         const run = stringField(input.run, ctx, ["run"], { nonempty: true });
-        noGithubExpression(run, ctx, ["run"]);
         let shell;
         if (own(input, "shell")) {
             const rawShell = stringField(input.shell, ctx, ["shell"], { nonempty: true });

package/dist/tasks/source/task-source-v4.js

@@ -259,7 +259,6 @@ function parseTarget(input, ctx) {
     if (own(input, "with"))
         sourceError(ctx, ["with"], "is legal only with uses: akm/command; declare typed inputs: instead.");
     const run = stringField(input.run, ctx, ["run"], { nonempty: true });
-    noGithubExpression(run, ctx, ["run"]);
     let shell;
     if (own(input, "shell")) {
         const rawShell = stringField(input.shell, ctx, ["shell"], { nonempty: true });

package/dist/workflows/exec/child-workflow.js

@@ -250,9 +250,8 @@ async function driveChildRun(input, childRow) {
         // (dispatchJournaledAttempt awaits this call with no try of its own),
         // so an uncaught throw here escaped all the way into the scheduler and
         // was silently swallowed (R1, above). Reachable causes include the
-        // child's own LeaseHeartbeat.assertAlive() firing mid-drive, a Lane B
-        // UsageError out of the child's own completeWorkflowStep (e.g.
-        // WORKFLOW_OUTPUT_INVALID), requireExecutableWorkflowPlan rejecting a
+        // child's own LeaseHeartbeat.assertAlive() firing mid-drive,
+        // requireExecutableWorkflowPlan rejecting a
         // tampered child plan_json, and the child's status changing between
         // this function's own step 5 read and the drive's internal
         // getNextWorkflowStep re-read — none of which match

package/dist/workflows/exec/dispatch-redaction.js

@@ -15,21 +15,23 @@
  * @module workflows/exec/dispatch-redaction
  */
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
+import { lookupApiKeyFileValue } from "../../integrations/agent/engine-resolution.js";
 /**
  * Every exact value that must never survive into the journal from ONE frozen
  * dispatch: the resolved `env` bindings injected into the child, the selected
- * engine's (and its SDK fallback's) credential env values, and any
- * `envPassthrough` value the redaction policy does not consider safe to expose.
+ * engine's (and its SDK fallback's) credential — an env value, or a
+ * file-backed one (#905) — and any `envPassthrough` value the redaction
+ * policy does not consider safe to expose.
  *
  * Shared by the unit path and the gate-judge path. There is deliberately ONE
  * collector: a second, parallel implementation is exactly how a dispatch path
  * silently loses the scrub.
  *
- * The credential values are read from `process.env` AT CALL TIME, so a caller
- * must collect no earlier than the dispatch whose outcome it scrubs. A snapshot
- * taken when the dispatch was merely *planned* can predate a credential the
- * dispatch then resolves live, leaving the exact value it must remove out of
- * the set.
+ * The credential values are read from `process.env` (or disk, for a file-
+ * backed one) AT CALL TIME, so a caller must collect no earlier than the
+ * dispatch whose outcome it scrubs. A snapshot taken when the dispatch was
+ * merely *planned* can predate a credential the dispatch then resolves live,
+ * leaving the exact value it must remove out of the set.
  */
 export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
     const values = new Set([...Object.values(env ?? {}), ...(dispatch.sensitiveValues ?? [])]);
@@ -42,6 +44,13 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            // #905: file-backed credential — best-effort read, never throws, so a
+            // broken apiKeyFile is reported by the real dispatch, not this collector.
+            if (runner.apiKeyFile) {
+                const value = lookupApiKeyFileValue(runner.apiKeyFile);
+                if (value)
+                    values.add(value);
+            }
             return;
         }
         for (const name of runner.profile.envPassthrough ?? []) {
@@ -55,6 +64,11 @@ export function collectWorkflowDispatchSensitiveValues(dispatch, env) {
                 if (value)
                     values.add(value);
             }
+            if (runner.fallbackApiKeyFile) {
+                const value = lookupApiKeyFileValue(runner.fallbackApiKeyFile);
+                if (value)
+                    values.add(value);
+            }
         }
     };
     addCredential(dispatch.runner);

package/dist/workflows/exec/exec-unit.js

@@ -220,10 +220,9 @@ function truncationNote(read) {
  * The captured stdout, with an unmistakable truncation block appended when the
  * retention cap discarded part of it.
  *
- * Same idiom, same reason as `WORKFLOW_EVIDENCE_TRUNCATED_MARKER`
- * (`runtime/runs.ts`): truncated data must never be mistakable for complete
- * data. The block names both byte counts, so a reader can see exactly how much
- * is missing rather than inferring it from a suspiciously round length.
+ * Truncated data must never be mistakable for complete data. The block names
+ * both byte counts, so a reader can see exactly how much is missing rather
+ * than inferring it from a suspiciously round length.
  */
 function markTruncatedStdout(result) {
     const read = result.stdoutRead;

package/dist/workflows/exec/run-workflow.js

@@ -36,6 +36,10 @@ export async function runWorkflowSteps(options) {
     let target = options.target;
     let params = options.params;
     let parameterFlags = options.parameterFlags;
+    // `--new` only applies to the FIRST resolution of `target` (a ref); every
+    // retry re-targets the run id `startWorkflowRun` already created, so it is
+    // cleared alongside `params`/`parameterFlags` below (#919).
+    let newRun = options.newRun;
     let remainingRetries = options.maxRetries ?? 0;
     let remainingSteps = options.maxSteps;
     const executed = [];
@@ -51,6 +55,7 @@ export async function runWorkflowSteps(options) {
             target,
             ...(params !== undefined ? { params } : { params: undefined }),
             ...(parameterFlags !== undefined ? { parameterFlags } : { parameterFlags: undefined }),
+            newRun,
             ...(remainingSteps !== undefined ? { maxSteps: remainingSteps } : { maxSteps: undefined }),
         }, liveEvidence);
         executed.push(...result.executed);
@@ -72,12 +77,14 @@ export async function runWorkflowSteps(options) {
         target = result.run.id;
         params = undefined;
         parameterFlags = undefined;
+        newRun = undefined;
         remainingRetries -= 1;
     }
 }
 async function runWorkflowAttempt(options, liveEvidence) {
     const next = await getNextWorkflowStep(options.target, options.params, {
         parameterFlags: options.parameterFlags,
+        newRun: options.newRun,
     });
     // Version/canonical/hash validation precedes every executable mutation,
     // including lease acquisition. Historical rows remain inspectable/abandonable.
@@ -137,8 +144,14 @@ async function runWorkflowAttempt(options, liveEvidence) {
         const result = await withWorkflowRunsConnection(() => driveRun(options, next, leaseHolder, heartbeat, liveEvidence));
         // Creation-time notices reach the caller only here: the run row has no
         // warnings column, and a later invocation of the same run must stay silent
-        // about a decision it did not make. `driveRun` never sets `warnings`.
-        return next.startWarnings?.length ? { ...result, warnings: next.startWarnings } : result;
+        // about a decision it did not make. `driveRun` never sets `warnings` or
+        // `resumed` — both are properties of THIS resolution of `target`, not of
+        // the run row (#919).
+        return {
+            ...result,
+            ...(next.resumed ? { resumed: true } : {}),
+            ...(next.startWarnings?.length ? { warnings: next.startWarnings } : {}),
+        };
     }
     finally {
         heartbeat?.stop();
@@ -639,14 +652,10 @@ async function driveRun(options, initial, leaseHolder, heartbeat,
 /**
  * The COMPLETE in-memory evidence of every step THIS call has completed,
  * keyed by step id, preferred over the re-read row when the downstream scope
- * is rebuilt below. The spine rows are re-read between steps, and
- * `clipStepEvidenceForPersistence` (runtime/runs.ts) may have replaced an
- * over-cap artifact with a truncation envelope on the way in — a bound on ONE
- * SQLite row, not on what a run may promote (the exec per-pipe cap alone
- * retains 8 MiB). Preferring the live value keeps the persistence bound
- * invisible to the run that produced it. A LATER `akm workflow run` starts
- * with an empty map and reads the rows, where a reference into a truncated
- * artifact fails loudly by name (`isTruncatedEvidence`).
+ * is rebuilt below — avoiding a re-parse of a row this same invocation just
+ * wrote (step artifacts are persisted whole, so the two values agree; this
+ * is purely an avoided round trip, not a correctness dependency). A LATER
+ * `akm workflow run` starts with an empty map and reads the rows directly.
  *
  * Only steps some OTHER step's references NAME are stored (`referencedStepIds`
  * — the set-time filter): a step nothing downstream reads has no consumer to