akm-cli 0.7.5 → 0.8.0-rc1

package/dist/tasks/runner.js

@@ -0,0 +1,432 @@
+/**
+ * `akm tasks run <id>` — what cron / launchd / schtasks invoke at the
+ * scheduled moment.
+ *
+ * Responsibilities:
+ *
+ *   1. Resolve the task file via `resolveAssetPath(stashDir, "task", id)`.
+ *   2. Parse the task document. (Validation runs at `tasks add` /
+ *      `tasks sync` time, not here — at run time we still want to attempt
+ *      execution and surface the actual failure rather than re-fail on a
+ *      validation error that the user already knows about.)
+ *   3. Refuse to run when `enabled === false` (defense-in-depth).
+ *   4. Dispatch by target kind:
+ *        • workflow → `startWorkflowRun(ref, params)`
+ *        • prompt   → `runAgent(profile, prompt, { stdio: "captured" })`
+ *   5. Capture stdout / stderr to `<cacheDir>/tasks/logs/<id>/<ts>.log`.
+ *   6. Write a history row to state.db task_history table.
+ *
+ * Returns a structured result so the CLI handler can shape it for `output()`
+ * and so tests can assert against it without scraping stdout.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { NotFoundError } from "../core/errors";
+import { getTaskLogDir } from "../core/paths";
+import { getTaskHistory, openStateDatabase, queryTaskHistory, upsertTaskHistory } from "../core/state-db";
+import { error } from "../core/warn";
+import { requireAgentProfile, runAgent } from "../integrations/agent";
+import { resolveProcessAgentProfile } from "../integrations/agent/config";
+import { resolveAssetPath } from "../sources/resolve";
+import { startWorkflowRun } from "../workflows/runs";
+import { parseTaskDocument } from "./parser";
+export async function runTask(id, options = {}) {
+    const stashDir = options.stashDir ?? resolveStashDir();
+    const runAgentImpl = options.runAgentImpl ?? runAgent;
+    const startWorkflowRunImpl = options.startWorkflowRunImpl ?? startWorkflowRun;
+    const now = options.now ?? (() => new Date());
+    const logDir = options.logDir ?? getTaskLogDir();
+    const filePath = await resolveAssetPath(stashDir, "task", id);
+    const markdown = fs.readFileSync(filePath, "utf8");
+    const task = parseTaskDocument({ markdown, filePath, id });
+    const startedAt = now();
+    const startedIso = startedAt.toISOString();
+    const tsSlug = startedIso.replace(/[:.]/g, "-");
+    const taskLogDir = path.join(logDir, id);
+    fs.mkdirSync(taskLogDir, { recursive: true });
+    const logPath = path.join(taskLogDir, `${tsSlug}.log`);
+    if (!task.enabled) {
+        const finishedAt = now();
+        const disabledTarget = task.target.kind === "workflow"
+            ? { kind: "workflow", ref: task.target.ref }
+            : task.target.kind === "command"
+                ? { kind: "prompt", profile: undefined }
+                : { kind: "prompt", profile: task.target.profile };
+        const result = {
+            id,
+            status: "disabled",
+            startedAt: startedIso,
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedAt.getTime(),
+            log: logPath,
+            target: disabledTarget,
+        };
+        fs.writeFileSync(logPath, `[akm tasks] task "${id}" is disabled — skipping run.\n`);
+        appendHistory(result);
+        return result;
+    }
+    if (task.target.kind === "workflow") {
+        return await runWorkflowTask({
+            task,
+            logPath,
+            startedAt,
+            now,
+            startWorkflowRunImpl,
+        });
+    }
+    if (task.target.kind === "command") {
+        return await runCommandTask({ task, logPath, startedAt, now });
+    }
+    // Resolve config once here so runPromptTask does not call loadConfig()
+    // on every dispatch in a batch run (Fix C6).
+    const config = loadConfig();
+    return await runPromptTask({
+        task,
+        stashDir,
+        logPath,
+        startedAt,
+        now,
+        runAgentImpl,
+        agentOptions: options.agentOptions,
+        agentConfig: config.agent,
+        agentTimeoutMs: config.agent?.timeoutMs ?? undefined,
+    });
+}
+// ── command target ──────────────────────────────────────────────────────────
+async function runCommandTask(input) {
+    const { task, logPath, startedAt, now } = input;
+    if (task.target.kind !== "command")
+        throw new Error("invariant: command target");
+    const { cmd } = task.target;
+    const timeoutMs = task.timeoutMs !== undefined ? task.timeoutMs : null;
+    const logLines = [`[akm tasks] task=${task.id} kind=command cmd=${cmd.join(" ")}`];
+    let stdout = "";
+    let stderr = "";
+    let exitCode = null;
+    try {
+        const proc = Bun.spawn(cmd, {
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+        });
+        let timer;
+        let timedOut = false;
+        if (timeoutMs !== null) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    proc.kill("SIGTERM");
+                }
+                catch {
+                    /* ignore */
+                }
+            }, timeoutMs);
+        }
+        const [stdoutBuf, stderrBuf] = await Promise.all([
+            new Response(proc.stdout).text(),
+            new Response(proc.stderr).text(),
+        ]);
+        await proc.exited;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        stdout = stdoutBuf;
+        stderr = stderrBuf;
+        exitCode = proc.exitCode ?? (timedOut ? 143 : 1);
+        if (timedOut) {
+            logLines.push(`timed_out=true timeout_ms=${timeoutMs}`);
+        }
+        logLines.push(`exit_code=${exitCode}`);
+        if (stdout) {
+            logLines.push("--- stdout ---");
+            logLines.push(stdout);
+        }
+        if (stderr) {
+            logLines.push("--- stderr ---");
+            logLines.push(stderr);
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        logLines.push(`spawn_error=${msg}`);
+        exitCode = 1;
+    }
+    fs.writeFileSync(logPath, `${logLines.join("\n")}\n`);
+    const finishedAt = now();
+    const status = exitCode === 0 ? "completed" : "failed";
+    const result = {
+        id: task.id,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: { kind: "prompt", profile: undefined },
+        detail: { exitCode },
+    };
+    appendHistory(result);
+    return result;
+}
+// ── workflow target ─────────────────────────────────────────────────────────
+async function runWorkflowTask(input) {
+    const { task, logPath, startedAt, now, startWorkflowRunImpl } = input;
+    if (task.target.kind !== "workflow")
+        throw new Error("invariant: workflow target");
+    const ref = parseAssetRef(task.target.ref);
+    if (ref.type !== "workflow") {
+        throw new NotFoundError(`Task "${task.id}" workflow target must be a workflow ref (got "${task.target.ref}").`, "WORKFLOW_NOT_FOUND");
+    }
+    let detail;
+    let error;
+    try {
+        detail = await startWorkflowRunImpl(task.target.ref, task.target.params);
+    }
+    catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+    }
+    const finishedAt = now();
+    const status = error ? "failed" : mapWorkflowStatus(detail?.run.status);
+    const log = renderWorkflowLog({ task, detail, error });
+    fs.writeFileSync(logPath, log);
+    const result = {
+        id: task.id,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: { kind: "workflow", ref: task.target.ref },
+        detail: {
+            runId: detail?.run.id,
+            ...(error ? { error: error.message } : {}),
+        },
+    };
+    appendHistory(result);
+    // Don't re-throw on workflow failure: the OS scheduler reads exit codes,
+    // not exceptions, and the CLI maps `status: "failed"` to a non-zero exit
+    // via exitCodeForStatus(). Throwing here would route through the generic
+    // runWithJsonErrors path and lose the structured result/history we just
+    // recorded.
+    return result;
+}
+/**
+ * Map the workflow runtime's status into the task-runner status space.
+ * Workflows can legitimately remain `active` after `startWorkflowRun`
+ * returns (multi-step workflows pause for user input); recording them as
+ * "completed" would be misleading. We preserve "active" as a first-class
+ * task status with exit code 0 — the OS scheduler treats it as success.
+ */
+function mapWorkflowStatus(status) {
+    switch (status) {
+        case "completed":
+        case "blocked":
+        case "failed":
+        case "active":
+            return status;
+        default:
+            return "completed";
+    }
+}
+function renderWorkflowLog(input) {
+    const lines = [];
+    lines.push(`[akm tasks] task=${input.task.id} kind=workflow ref=${input.task.target.ref}`);
+    if (input.detail) {
+        lines.push(`run_id=${input.detail.run.id} status=${input.detail.run.status}`);
+        lines.push(`workflow_title=${input.detail.run.workflowTitle}`);
+    }
+    if (input.error) {
+        lines.push(`error=${input.error.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+// ── prompt target ───────────────────────────────────────────────────────────
+async function runPromptTask(input) {
+    const { task, stashDir, logPath, startedAt, now, runAgentImpl, agentOptions } = input;
+    if (task.target.kind !== "prompt")
+        throw new Error("invariant: prompt target");
+    // Use pre-resolved agent config when available to avoid redundant loadConfig()
+    // calls in batch task runs (Fix C6). Fall back to loadConfig() for callers
+    // that invoke runPromptTask directly without threading config.
+    const agentCfg = input.agentConfig !== undefined ? input.agentConfig : loadConfig().agent;
+    // Resolve the profile for this task. When the task doc specifies a profile,
+    // use it directly. Otherwise fall back to the per-process config for "task"
+    // (agent.processes["task"]), which itself falls back to agent.default.
+    let profile;
+    let processTimeoutMs;
+    if (task.target.profile) {
+        // Task doc explicitly names a profile — honour it directly.
+        profile = requireAgentProfile(agentCfg, task.target.profile);
+    }
+    else {
+        // No per-task profile: use process config for "task" as a fallback.
+        const resolved = resolveProcessAgentProfile("task", agentCfg);
+        profile = resolved.profile;
+        processTimeoutMs = resolved.timeoutMs;
+    }
+    // Task-level timeoutMs (including null = disabled) wins over global config.
+    // Resolution: task.timeoutMs → process entry timeoutMs → input.agentTimeoutMs → agentCfg.timeoutMs.
+    const agentTimeoutMs = task.timeoutMs !== undefined
+        ? task.timeoutMs
+        : processTimeoutMs !== undefined
+            ? processTimeoutMs
+            : input.agentTimeoutMs !== undefined
+                ? input.agentTimeoutMs
+                : agentCfg?.timeoutMs;
+    const promptText = await resolvePromptText(task, stashDir);
+    const result = await runAgentImpl(profile, promptText, {
+        stdio: "captured",
+        timeoutMs: agentTimeoutMs,
+        cwd: stashDir,
+        ...agentOptions,
+    });
+    const finishedAt = now();
+    const log = renderPromptLog({ task, profileName: profile.name, result });
+    fs.writeFileSync(logPath, log);
+    const status = result.ok ? "completed" : "failed";
+    const out = {
+        id: task.id,
+        status,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+        durationMs: finishedAt.getTime() - startedAt.getTime(),
+        log: logPath,
+        target: { kind: "prompt", profile: profile.name },
+        detail: result.ok
+            ? { exitCode: result.exitCode }
+            : { reason: result.reason, error: result.error, exitCode: result.exitCode },
+    };
+    appendHistory(out);
+    return out;
+}
+async function resolvePromptText(task, stashDir) {
+    if (task.target.kind !== "prompt")
+        throw new Error("invariant: prompt target");
+    const src = task.target.source;
+    if (src.kind === "inline")
+        return src.text;
+    if (src.kind === "file") {
+        const taskDir = path.dirname(task.source.path);
+        const filePath = path.isAbsolute(src.path) ? src.path : path.resolve(taskDir, src.path);
+        if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+            throw new NotFoundError(`Prompt file not found: ${filePath}`, "FILE_NOT_FOUND");
+        }
+        return fs.readFileSync(filePath, "utf8");
+    }
+    // asset
+    const ref = parseAssetRef(src.ref);
+    const assetPath = await resolveAssetPath(stashDir, ref.type, ref.name);
+    return fs.readFileSync(assetPath, "utf8");
+}
+function renderPromptLog(input) {
+    const lines = [];
+    lines.push(`[akm tasks] task=${input.task.id} kind=prompt profile=${input.profileName}`);
+    lines.push(`ok=${input.result.ok} exit_code=${input.result.exitCode ?? "null"} duration_ms=${input.result.durationMs}`);
+    if (!input.result.ok) {
+        lines.push(`reason=${input.result.reason ?? ""} error=${input.result.error ?? ""}`);
+    }
+    if (input.result.stdout) {
+        lines.push("--- agent stdout ---");
+        lines.push(input.result.stdout);
+    }
+    if (input.result.stderr) {
+        lines.push("--- agent stderr ---");
+        lines.push(input.result.stderr);
+    }
+    return `${lines.join("\n")}\n`;
+}
+// ── history ─────────────────────────────────────────────────────────────────
+function appendHistory(result) {
+    try {
+        const db = openStateDatabase();
+        try {
+            upsertTaskHistory(db, {
+                task_id: result.id,
+                status: result.status,
+                started_at: result.startedAt,
+                completed_at: result.finishedAt,
+                failed_at: result.status === "failed" ? result.finishedAt : null,
+                log_path: result.log,
+                target_kind: result.target.kind,
+                target_ref: result.target.kind === "workflow" ? result.target.ref : null,
+                metadata_json: JSON.stringify({
+                    durationMs: result.durationMs,
+                    detail: result.detail ?? null,
+                    profile: result.target.kind === "prompt" ? result.target.profile : undefined,
+                }),
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (err) {
+        error(`[akm] task history DB write failed: ${String(err)}`);
+    }
+}
+export function readTaskHistory(options = {}) {
+    const db = openStateDatabase();
+    try {
+        let rows;
+        if (options.id) {
+            const row = getTaskHistory(db, options.id);
+            rows = row ? [taskHistoryRowToResult(row)] : [];
+        }
+        else {
+            rows = queryTaskHistory(db, {}).map(taskHistoryRowToResult);
+        }
+        rows.sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+        if (options.limit !== undefined && options.limit >= 0) {
+            return rows.slice(0, options.limit);
+        }
+        return rows;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Convert a `TaskHistoryRow` from state.db back to a `TaskRunResult` shape
+ * that callers of `readTaskHistory()` expect.
+ */
+function taskHistoryRowToResult(row) {
+    let meta = {};
+    try {
+        meta = JSON.parse(row.metadata_json);
+    }
+    catch {
+        // ignore corrupt JSON
+    }
+    const target = row.target_kind === "workflow"
+        ? { kind: "workflow", ref: row.target_ref ?? "" }
+        : { kind: "prompt", profile: meta.profile };
+    return {
+        id: row.task_id,
+        status: row.status,
+        startedAt: row.started_at,
+        finishedAt: row.completed_at ?? row.failed_at ?? row.started_at,
+        durationMs: meta.durationMs ?? 0,
+        log: row.log_path ?? "",
+        target,
+        ...(meta.detail !== undefined ? { detail: meta.detail } : {}),
+    };
+}
+/**
+ * The exit code surfaced to the OS scheduler. Mapped from {@link TaskRunStatus}
+ * so cron / launchd / schtasks see a useful return value.
+ */
+export function exitCodeForStatus(status) {
+    switch (status) {
+        case "completed":
+            return 0;
+        case "active":
+            return 0;
+        case "blocked":
+            return 1;
+        case "failed":
+            return 1;
+        case "disabled":
+            return 0;
+    }
+}

package/dist/tasks/schedule.js

@@ -0,0 +1,208 @@
+/**
+ * Cross-platform schedule parsing and translation.
+ *
+ * Users always type cron-style expressions:
+ *
+ *   • `m h dom mon dow`   — five-field cron (UNIX minute/hour/dom/mon/dow)
+ *   • `@hourly` `@daily` `@weekly` `@monthly`
+ *
+ * Each {@link ScheduleSpec} can then be translated to:
+ *
+ *   • a verbatim cron line (Linux backend),
+ *   • a launchd plist `<StartCalendarInterval>` / `<StartInterval>` (macOS),
+ *   • Task Scheduler XML triggers (Windows).
+ *
+ * The shared subset is `*`, single integers, `*\/N`, plus the `@hourly /
+ * @daily / @weekly / @monthly` aliases. Patterns outside that — multi-value
+ * lists, ranges, step values other than `*\/N`, day-of-month AND
+ * day-of-week combinations — are rejected with a {@link UsageError}.
+ *
+ * Cron is the most permissive of the three backends; some patterns it
+ * accepts (e.g. `@hourly` = `0 * * * *`) have no clean schtasks primitive.
+ * Validation runs against the *active* backend, so a task authored on
+ * Linux may fail to translate when copied to macOS/Windows. `tasks sync`
+ * re-validates against the local backend and surfaces any incompatibility.
+ */
+import { UsageError } from "../core/errors";
+const ALIAS_TO_CRON = {
+    "@hourly": "0 * * * *",
+    "@daily": "0 0 * * *",
+    "@midnight": "0 0 * * *",
+    "@weekly": "0 0 * * 0",
+    "@monthly": "0 0 1 * *",
+};
+const FIELD_LIMITS = {
+    minute: { min: 0, max: 59 },
+    hour: { min: 0, max: 23 },
+    dom: { min: 1, max: 31 },
+    month: { min: 1, max: 12 },
+    dow: { min: 0, max: 6 },
+};
+const SUPPORTED_HINT = "Supported subset: `*`, single integers (`5`), and step-on-star (`*/N`). " +
+    "Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`. " +
+    "Lists, ranges, and named days/months are not supported.";
+export function parseSchedule(input, backend) {
+    const cron = expandAlias(input);
+    const fields = parseCronFields(cron, input);
+    const spec = { raw: input, cron, fields };
+    // Validate translatability for the active backend so the caller does not
+    // silently accept expressions that backend cannot run. Note: cron is the
+    // most permissive of the three (e.g. `@hourly` is `0 * * * *` which has
+    // no clean schtasks primitive), so a task authored on Linux may not be
+    // portable to macOS/Windows. `tasks sync` on the destination platform
+    // re-runs this with the local backend and will surface any incompatibility.
+    if (backend === "launchd")
+        translateToLaunchd(spec);
+    if (backend === "schtasks")
+        translateToSchtasks(spec);
+    return spec;
+}
+function expandAlias(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new UsageError("Schedule is empty.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const lower = trimmed.toLowerCase();
+    if (lower in ALIAS_TO_CRON)
+        return ALIAS_TO_CRON[lower];
+    return trimmed;
+}
+function parseCronFields(cron, original) {
+    const parts = cron.split(/\s+/);
+    if (parts.length !== 5) {
+        throw new UsageError(`Invalid schedule "${original}": expected 5 fields, got ${parts.length}. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE");
+    }
+    const [m, h, dom, mon, dow] = parts;
+    return {
+        minute: parseField(m, "minute", FIELD_LIMITS.minute, original),
+        hour: parseField(h, "hour", FIELD_LIMITS.hour, original),
+        dom: parseField(dom, "day-of-month", FIELD_LIMITS.dom, original),
+        month: parseField(mon, "month", FIELD_LIMITS.month, original),
+        dow: parseField(dow, "day-of-week", FIELD_LIMITS.dow, original),
+    };
+}
+function parseField(raw, name, limit, original) {
+    if (raw === "*")
+        return { kind: "star" };
+    const stepMatch = raw.match(/^\*\/(\d+)$/);
+    if (stepMatch) {
+        const step = Number(stepMatch[1]);
+        // Step must be ≥1 and ≤ the field's range size, not just `max`. For
+        // 1-based fields like day-of-month (1-31) and month (1-12) the previous
+        // `max + 1` bound let invalid steps like `*/32` or `*/13` slip through.
+        const range = limit.max - limit.min + 1;
+        if (!Number.isInteger(step) || step <= 0 || step > range) {
+            throw new UsageError(`Invalid ${name} step "${raw}" in schedule "${original}". ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE");
+        }
+        return { kind: "step", step };
+    }
+    if (/^\d+$/.test(raw)) {
+        const value = Number(raw);
+        if (value < limit.min || value > limit.max) {
+            throw new UsageError(`Invalid ${name} value "${raw}" in schedule "${original}" (allowed ${limit.min}-${limit.max}).`, "INVALID_FLAG_VALUE");
+        }
+        return { kind: "value", value };
+    }
+    throw new UsageError(`Unsupported ${name} expression "${raw}" in schedule "${original}". ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE");
+}
+// ── Backend translators ─────────────────────────────────────────────────────
+/** Verbatim cron line, alias-expanded. */
+export function translateToCron(spec) {
+    return spec.cron;
+}
+export function translateToLaunchd(spec) {
+    const f = spec.fields;
+    // `*/N` minute (everything else `*`) → StartInterval = N*60 seconds.
+    if (f.minute.kind === "step" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { intervalSeconds: f.minute.step * 60 };
+    }
+    // `*/N` hour → StartInterval = N*3600.
+    if (f.minute.kind === "value" &&
+        f.minute.value === 0 &&
+        f.hour.kind === "step" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { intervalSeconds: f.hour.step * 3600 };
+    }
+    // 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
+    // calendar dict — reject those.
+    const calendar = {};
+    rejectStepInsideCalendar(f.minute, "minute", spec);
+    rejectStepInsideCalendar(f.hour, "hour", spec);
+    rejectStepInsideCalendar(f.dom, "day-of-month", spec);
+    rejectStepInsideCalendar(f.month, "month", spec);
+    rejectStepInsideCalendar(f.dow, "day-of-week", spec);
+    if (f.minute.kind === "value")
+        calendar.Minute = f.minute.value;
+    if (f.hour.kind === "value")
+        calendar.Hour = f.hour.value;
+    if (f.dom.kind === "value")
+        calendar.Day = f.dom.value;
+    if (f.month.kind === "value")
+        calendar.Month = f.month.value;
+    if (f.dow.kind === "value")
+        calendar.Weekday = f.dow.value;
+    // launchd's CalendarInterval requires at least one specific key. If every
+    // field is `*` the schedule has no anchor and we'd need a StartInterval
+    // instead — treat this as "every minute".
+    if (Object.keys(calendar).length === 0) {
+        return { intervalSeconds: 60 };
+    }
+    return { calendar };
+}
+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.");
+    }
+}
+export function translateToSchtasks(spec) {
+    const f = spec.fields;
+    // `*/N` minute → MINUTE, every N.
+    if (f.minute.kind === "step" &&
+        f.hour.kind === "star" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { kind: "minute", everyMinutes: f.minute.step };
+    }
+    // `0 */N * * *` → HOURLY, every N.
+    if (f.minute.kind === "value" &&
+        f.minute.value === 0 &&
+        f.hour.kind === "step" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "star") {
+        return { kind: "hour", everyHours: f.hour.step };
+    }
+    // `M H * * *` → DAILY at H:M.
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "value" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        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.
+    if (f.minute.kind === "value" &&
+        f.hour.kind === "value" &&
+        f.dom.kind === "star" &&
+        f.month.kind === "star" &&
+        f.dow.kind === "value") {
+        return {
+            kind: "weekly",
+            atHour: f.hour.value,
+            atMinute: f.minute.value,
+            daysOfWeek: [f.dow.value],
+        };
+    }
+    throw new UsageError(`Schedule "${spec.raw}" cannot be expressed as a Windows Task Scheduler trigger. ${SUPPORTED_HINT}`, "INVALID_FLAG_VALUE", "Use one of: */N minutes, every N hours (0 */N * * *), daily at HH:MM, or weekly on a single weekday.");
+}
+/** Human-readable summary used by `tasks doctor`. */
+export const SCHEDULE_SUPPORTED_SUBSET_HINT = SUPPORTED_HINT;

package/dist/tasks/schema.js

@@ -0,0 +1,13 @@
+/**
+ * Task asset schema. A task pairs a cron-style schedule with exactly one of:
+ *
+ *   • a workflow target  — invoked via `startWorkflowRun()`
+ *   • a prompt target    — invoked via `runAgent()` against the configured
+ *                          agent harness (e.g. `opencode run`)
+ *   • a command target   — invoked directly via `Bun.spawn()`, no AI agent
+ *
+ * Tasks are stored as markdown files at `<stash>/tasks/<id>.md`. The
+ * frontmatter holds the schedule and target; for inline-prompt tasks the
+ * markdown body is the prompt text.
+ */
+export const TASK_SCHEMA_VERSION = 1;