@bridge_gpt/mcp-server 0.1.16 → 0.2.0

package/build/schedule-run.js

@@ -0,0 +1,951 @@
+/**
+ * `schedule-run` — local-only cross-platform scheduler subcommand for the
+ * packaged `@bridge_gpt/mcp-server` CLI (BAPI-327, Phase B of the Full Automation
+ * v1 epic BAPI-325).
+ *
+ *   npx -y @bridge_gpt/mcp-server schedule-run <create|list|cancel|doctor> [flags]
+ *
+ * At a chosen time T it fires, on the user's machine:
+ *   <claude> -p '/full-automation --scheduled-at <T> --idea-file <abs> [--auto]'
+ * via an OS-native one-shot unit (launchd / Task Scheduler / systemd-user / at).
+ *
+ * Strictly local: NO Bridge API HTTP calls, NO database/server-side state. All
+ * schedule state lives under `~/.bridge-gpt/schedules/`. The structure mirrors
+ * `start-tickets.ts`: a hand-rolled parser, an injectable command/runtime deps
+ * boundary, and discriminated parse/result types — no new runtime npm deps.
+ */
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { pathApiForPlatform, selectSchedulerBackend, getSchedulerBackendByName, getSchedulerBackendsForPlatform, unsupportedSchedulerPlatformMessage, } from "./scheduler-backends/index.js";
+import { ensureScheduleDirectories, getSchedulePaths, writeScheduleMetadata, readScheduleMetadata, listScheduleMetadata, deleteScheduleMetadata, } from "./schedule-store.js";
+import { getAgentLauncher, formatValidAgentLauncherNames } from "./agent-launchers/index.js";
+import { resolveCommandOnPath } from "./agent-launchers/claude.js";
+/**
+ * Default deps backed by real subprocesses / process state. Subprocess execution
+ * uses `execFile` (list-based, never `shell: true`) and supports
+ * `RunCommandOptions.input` by writing to the child's stdin — required by the
+ * `at` backend, which pipes its heredoc script.
+ */
+export function createDefaultScheduleRunDeps() {
+    const runCommand = (file, args, options) => new Promise((resolve) => {
+        const child = execFile(file, args, {
+            cwd: options?.cwd,
+            env: options?.env ?? process.env,
+            maxBuffer: 64 * 1024 * 1024,
+            encoding: "utf-8",
+        }, (error, stdout, stderr) => {
+            const exitCode = error && typeof error.code === "number"
+                ? error.code
+                : error
+                    ? 1
+                    : 0;
+            resolve({ stdout: stdout ?? "", stderr: stderr ?? "", exitCode });
+        });
+        if (options?.input !== undefined && child.stdin) {
+            child.stdin.write(options.input);
+            child.stdin.end();
+        }
+    });
+    return {
+        runCommand,
+        platform: process.platform,
+        env: process.env,
+        cwd: process.cwd(),
+        execPath: process.execPath,
+        homeDir: process.env.HOME ?? process.env.USERPROFILE ?? "",
+        now: () => Date.now(),
+    };
+}
+/** Return true only for a zero exit code. */
+export function commandSucceeded(result) {
+    return result.exitCode === 0;
+}
+const VALID_BACKEND_NAMES = [
+    "launchd",
+    "task-scheduler",
+    "systemd-user",
+    "at-fallback",
+];
+/** Safe schedule id / unit-name pattern. */
+const SCHEDULE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+/** User-facing usage text for `schedule-run`. */
+export function getScheduleRunUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server schedule-run <create|list|cancel|doctor> [flags]",
+        "",
+        "Schedules a local, one-shot Claude full-automation run at a chosen time using",
+        "an OS-native scheduler (launchd / Task Scheduler / systemd-user / at). Schedules",
+        "are stored locally under ~/.bridge-gpt/schedules/ and are never sent to a server.",
+        "",
+        "create:",
+        '  schedule-run create --at "<datetime>" --idea-file <path> [flags]',
+        "  schedule-run create --in <duration> --idea-file <path> [flags]",
+        "",
+        "create flags:",
+        '  --at "<datetime>"        ISO-8601 time to run (mutually exclusive with --in)',
+        "  --in <duration>          Run after a duration, e.g. 30m, 4h, 1d (mutually exclusive with --at)",
+        "  --idea-file <path>       REQUIRED absolute or relative path to the idea file",
+        "  --agent claude           Agent to launch (only 'claude' is supported in v1)",
+        "  --repo-path <path>       Working directory for the run (default: current directory)",
+        "  --auto                   Forward --auto to /full-automation (default)",
+        "  --no-auto                Do not forward --auto",
+        "  --dry-run                Print the generated unit + invocation without creating anything",
+        "  --id <id>                Override the auto-generated schedule id (mainly for tests)",
+        "",
+        "list flags:",
+        "  --id <id>                Filter to a single schedule id",
+        "  --agent <name>           Filter by agent",
+        "  --backend <name>         Filter by backend (launchd|task-scheduler|systemd-user|at-fallback)",
+        "  --json                   Emit JSON instead of a table",
+        "",
+        "cancel:",
+        "  cancel <id>              Cancel by positional id",
+        "  cancel --id <id>         Cancel by --id flag",
+        "  --agent <name>           Only cancel when the recorded agent matches",
+        "  --backend <name>         Only cancel when the recorded backend matches",
+        "",
+        "doctor:",
+        "  Read-only diagnostics: platform support, backend candidate order, scheduler",
+        "  availability, and whether claude/npx resolve on PATH. Creates nothing.",
+        "",
+        "  -h, --help               Show this help",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+/** Internal: a flag that expects a following value. */
+function takeValue(argv, index, arg, flag) {
+    if (arg.startsWith(`${flag}=`)) {
+        return { value: arg.slice(`${flag}=`.length), nextIndex: index };
+    }
+    if (index + 1 >= argv.length) {
+        return { error: `${flag} requires a value.` };
+    }
+    return { value: argv[index + 1], nextIndex: index + 1 };
+}
+function matchesFlag(arg, flag) {
+    return arg === flag || arg.startsWith(`${flag}=`);
+}
+/** Parse `create` args. */
+export function parseScheduleCreateArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getScheduleRunUsage() };
+    }
+    let at;
+    let inDuration;
+    let ideaFile;
+    let agent = "claude";
+    let repoPath;
+    let id;
+    let sawAutoApprove = false;
+    let sawNoAutoApprove = false;
+    let dryRun = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (matchesFlag(arg, "--at")) {
+            const r = takeValue(argv, i, arg, "--at");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            at = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--in")) {
+            const r = takeValue(argv, i, arg, "--in");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            inDuration = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--idea-file")) {
+            const r = takeValue(argv, i, arg, "--idea-file");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            ideaFile = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--agent")) {
+            const r = takeValue(argv, i, arg, "--agent");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (!getAgentLauncher(r.value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --agent value: '${r.value}'. Only ${formatValidAgentLauncherNames()} is supported in v1.`,
+                };
+            }
+            agent = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--repo-path")) {
+            const r = takeValue(argv, i, arg, "--repo-path");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            repoPath = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--id")) {
+            const r = takeValue(argv, i, arg, "--id");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            id = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg === "--auto") {
+            sawAutoApprove = true;
+            continue;
+        }
+        if (arg === "--no-auto") {
+            sawNoAutoApprove = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        return {
+            status: "error",
+            message: `Unexpected positional argument: '${arg}'. create takes only flags.`,
+        };
+    }
+    if (Boolean(at) === Boolean(inDuration)) {
+        return {
+            status: "error",
+            message: "create requires exactly one of --at or --in.",
+        };
+    }
+    if (!ideaFile) {
+        return { status: "error", message: "create requires --idea-file <path>." };
+    }
+    if (sawAutoApprove && sawNoAutoApprove) {
+        return {
+            status: "error",
+            message: "--auto and --no-auto are mutually exclusive.",
+        };
+    }
+    if (id !== undefined && !SCHEDULE_ID_PATTERN.test(id)) {
+        return {
+            status: "error",
+            message: `Invalid --id value: '${id}'. Ids must match ${SCHEDULE_ID_PATTERN.source} ` +
+                "(start alphanumeric; letters, digits, '_' and '-'; max 64 chars).",
+        };
+    }
+    return {
+        status: "ok",
+        subcommand: "create",
+        options: {
+            at,
+            in: inDuration,
+            ideaFile,
+            agent,
+            repoPath,
+            autoApprove: !sawNoAutoApprove,
+            dryRun,
+            id,
+        },
+    };
+}
+/** Parse `list` args. */
+export function parseScheduleListArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getScheduleRunUsage() };
+    }
+    let id;
+    let agent;
+    let backend;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (matchesFlag(arg, "--id")) {
+            const r = takeValue(argv, i, arg, "--id");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            id = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--agent")) {
+            const r = takeValue(argv, i, arg, "--agent");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (!getAgentLauncher(r.value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --agent filter: '${r.value}'. Valid: ${formatValidAgentLauncherNames()}.`,
+                };
+            }
+            agent = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--backend")) {
+            const r = takeValue(argv, i, arg, "--backend");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (!VALID_BACKEND_NAMES.includes(r.value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --backend filter: '${r.value}'. Valid: ${VALID_BACKEND_NAMES.join(", ")}.`,
+                };
+            }
+            backend = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        return {
+            status: "error",
+            message: `Unexpected positional argument: '${arg}'. list takes only flags.`,
+        };
+    }
+    return { status: "ok", subcommand: "list", options: { id, agent, backend, json } };
+}
+/** Parse `cancel` args (one id via positional or --id, never both/multiple). */
+export function parseScheduleCancelArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getScheduleRunUsage() };
+    }
+    let positionalId;
+    let flagId;
+    let agent;
+    let backend;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (matchesFlag(arg, "--id")) {
+            const r = takeValue(argv, i, arg, "--id");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (flagId !== undefined) {
+                return { status: "error", message: "cancel accepts only one --id." };
+            }
+            flagId = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--agent")) {
+            const r = takeValue(argv, i, arg, "--agent");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            agent = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (matchesFlag(arg, "--backend")) {
+            const r = takeValue(argv, i, arg, "--backend");
+            if ("error" in r)
+                return { status: "error", message: r.error };
+            if (!VALID_BACKEND_NAMES.includes(r.value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --backend filter: '${r.value}'. Valid: ${VALID_BACKEND_NAMES.join(", ")}.`,
+                };
+            }
+            backend = r.value;
+            i = r.nextIndex;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        if (positionalId !== undefined) {
+            return { status: "error", message: "cancel accepts only one schedule id." };
+        }
+        positionalId = arg;
+    }
+    if (positionalId !== undefined && flagId !== undefined) {
+        return {
+            status: "error",
+            message: "cancel accepts a positional id OR --id, not both.",
+        };
+    }
+    const id = positionalId ?? flagId;
+    if (!id) {
+        return { status: "error", message: "cancel requires a schedule id (positional or --id)." };
+    }
+    return { status: "ok", subcommand: "cancel", options: { id, agent, backend } };
+}
+/** Parse `doctor` args (read-only; only --json / help). */
+export function parseScheduleDoctorArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getScheduleRunUsage() };
+    }
+    let json = false;
+    for (const arg of argv) {
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        return {
+            status: "error",
+            message: `Unexpected positional argument: '${arg}'. doctor takes no positional arguments.`,
+        };
+    }
+    return { status: "ok", subcommand: "doctor", options: { json } };
+}
+/** Top-level parser: honor help first, require a valid subcommand, dispatch. */
+export function parseScheduleRunArgs(argv) {
+    // Help before any other validation, even with later unknown flags.
+    if (argv.length === 0) {
+        return {
+            status: "error",
+            message: "Missing subcommand. Expected one of: create, list, cancel, doctor.",
+        };
+    }
+    const [subcommand, ...rest] = argv;
+    if (subcommand === "-h" || subcommand === "--help") {
+        return { status: "help", usage: getScheduleRunUsage() };
+    }
+    switch (subcommand) {
+        case "create":
+            return parseScheduleCreateArgs(rest);
+        case "list":
+            return parseScheduleListArgs(rest);
+        case "cancel":
+            return parseScheduleCancelArgs(rest);
+        case "doctor":
+            return parseScheduleDoctorArgs(rest);
+        default:
+            return {
+                status: "error",
+                message: `Unknown subcommand '${subcommand}'. Expected one of: create, list, cancel, doctor.`,
+            };
+    }
+}
+/** Parse `--at` as ISO-8601 and normalize to `Date.toISOString()`. */
+export function parseRunAtIso(value) {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return { ok: false, error: `Invalid --at datetime: '${value}'. Expected an ISO-8601 timestamp.` };
+    }
+    return { ok: true, iso: date.toISOString() };
+}
+/** Parse a positive `<n><m|h|d>` duration relative to the injected clock. */
+export function parseDurationFromNow(value, nowMs) {
+    const match = value.match(/^(\d+)([mhd])$/);
+    if (!match) {
+        return {
+            ok: false,
+            error: `Invalid --in duration: '${value}'. Use a positive number followed by m, h, or d (e.g. 30m, 4h, 1d).`,
+        };
+    }
+    const amount = Number(match[1]);
+    if (amount <= 0) {
+        return { ok: false, error: `Invalid --in duration: '${value}'. Duration must be positive.` };
+    }
+    const unitMs = match[2] === "m" ? 60_000 : match[2] === "h" ? 3_600_000 : 86_400_000;
+    return { ok: true, iso: new Date(nowMs + amount * unitMs).toISOString() };
+}
+/** Resolve an absolute path against the platform path API and deps.cwd. */
+function resolveAbsolute(p, deps) {
+    const pathApi = pathApiForPlatform(deps.platform);
+    return pathApi.isAbsolute(p) ? pathApi.normalize(p) : pathApi.resolve(deps.cwd, p);
+}
+/**
+ * Resolve and validate create inputs, baking the PATH-trap values. Validates
+ * that the idea file exists and is a file and the repo path exists and is a
+ * directory BEFORE attempting binary resolution. Captures `env_path` exactly
+ * from the injected env (`PATH` then `Path`); resolves node/npx/claude against
+ * that baked PATH; builds the locked invocation (never with `--cwd`).
+ */
+export async function resolveScheduleCreateInput(options, runAtIso, deps) {
+    const ideaFile = resolveAbsolute(options.ideaFile, deps);
+    const repoPath = resolveAbsolute(options.repoPath ?? deps.cwd, deps);
+    try {
+        const ideaStat = await fs.stat(ideaFile);
+        if (!ideaStat.isFile()) {
+            return { ok: false, error: `--idea-file is not a file: ${ideaFile}` };
+        }
+    }
+    catch {
+        return { ok: false, error: `--idea-file does not exist: ${ideaFile}` };
+    }
+    try {
+        const repoStat = await fs.stat(repoPath);
+        if (!repoStat.isDirectory()) {
+            return { ok: false, error: `--repo-path is not a directory: ${repoPath}` };
+        }
+    }
+    catch {
+        return { ok: false, error: `--repo-path does not exist: ${repoPath}` };
+    }
+    const envPath = deps.env.PATH ?? deps.env.Path ?? "";
+    const nodePath = deps.execPath;
+    const launcher = getAgentLauncher(options.agent);
+    if (!launcher) {
+        return {
+            ok: false,
+            error: `Unsupported agent: '${options.agent}'. Valid: ${formatValidAgentLauncherNames()}.`,
+        };
+    }
+    const claudePath = await launcher.resolveBinary(envPath, deps);
+    if (!claudePath) {
+        return {
+            ok: false,
+            error: `Could not resolve the '${launcher.capability.command}' binary on the baked PATH.`,
+        };
+    }
+    // npx is resolved best-effort (v1 invokes claude directly); empty when absent.
+    const npxPath = (await resolveCommandOnPath("npx", envPath, deps)) ?? "";
+    const invocation = launcher.buildInvocation(claudePath, {
+        runAtIso,
+        ideaFile,
+        autoApprove: options.autoApprove,
+    });
+    const id = options.id ?? randomUUID();
+    const paths = getSchedulePaths(id, deps.homeDir, deps.platform);
+    return {
+        ok: true,
+        resolved: {
+            id,
+            runAtIso,
+            agent: options.agent,
+            ideaFile,
+            repoPath,
+            envPath,
+            nodePath,
+            npxPath,
+            claudePath,
+            invocation,
+            paths: {
+                schedulesDir: paths.schedulesDir,
+                logsDir: paths.logsDir,
+                stdoutPath: paths.stdoutPath,
+                stderrPath: paths.stderrPath,
+            },
+        },
+    };
+}
+/** Build the local-only schedule metadata from resolved inputs + backend result. */
+export function buildScheduleMetadata(resolved, createResult, createdAtIso) {
+    return {
+        id: resolved.id,
+        run_at_iso: resolved.runAtIso,
+        backend: createResult.backend,
+        unit_path: createResult.unitPath,
+        unit_paths: createResult.unitPaths,
+        backend_job_id: createResult.backendJobId,
+        agent: resolved.agent,
+        idea_file: resolved.ideaFile,
+        repo_path: resolved.repoPath,
+        created_at: createdAtIso,
+        env_path: resolved.envPath,
+        node_path: resolved.nodePath,
+        npx_path: resolved.npxPath,
+        claude_path: resolved.claudePath,
+        invocation: resolved.invocation,
+        logs: { stdout: resolved.paths.stdoutPath, stderr: resolved.paths.stderrPath },
+    };
+}
+/** Compute the run time (exactly one of --at / --in already validated). */
+function resolveRunAtIso(options, deps) {
+    if (options.at !== undefined) {
+        return parseRunAtIso(options.at);
+    }
+    const nowMs = deps.now ? deps.now() : Date.now();
+    return parseDurationFromNow(options.in, nowMs);
+}
+/**
+ * Orchestrate a create. Dry-run selects the primary backend and returns
+ * artifacts WITHOUT creating directories or writing metadata. Real create:
+ * resolve → ensure directories → backend.create → write metadata only after
+ * backend success; if metadata persistence fails after a native unit/job was
+ * created, attempt a best-effort backend cancel before returning a failure.
+ */
+export async function orchestrateScheduleCreate(options, deps) {
+    const runAt = resolveRunAtIso(options, deps);
+    if (!runAt.ok)
+        return { ok: false, error: runAt.error };
+    const resolvedResult = await resolveScheduleCreateInput(options, runAt.iso, deps);
+    if (!resolvedResult.ok)
+        return { ok: false, error: resolvedResult.error };
+    const resolved = resolvedResult.resolved;
+    const createdAtIso = new Date(deps.now ? deps.now() : Date.now()).toISOString();
+    const metadataPath = getSchedulePaths(resolved.id, deps.homeDir, deps.platform).metadataPath;
+    // For a real create, reject a colliding/unreadable existing schedule BEFORE
+    // probing scheduler availability or creating anything (fail fast, no side
+    // effects). Without this, `schtasks /Create /F` would replace the prior task
+    // and writeScheduleMetadata would overwrite the prior <id>.json, losing it.
+    // A missing file reads as null (proceed); a present-but-unreadable file
+    // (malformed JSON, EACCES, …) is surfaced as a controlled error rather than
+    // being swallowed and silently overwritten — mirroring how
+    // orchestrateScheduleList surfaces malformed metadata instead of ignoring it.
+    if (!options.dryRun) {
+        let existing;
+        try {
+            existing = await readScheduleMetadata(resolved.id, deps.homeDir, deps.platform);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                error: `Could not read existing schedule metadata for id '${resolved.id}' at ${metadataPath}: ${msg}. ` +
+                    "Resolve or remove it before creating.",
+            };
+        }
+        if (existing) {
+            return {
+                ok: false,
+                error: `A schedule with id '${resolved.id}' already exists (${metadataPath}). ` +
+                    "Cancel it first (schedule-run cancel <id>) or choose a different --id.",
+            };
+        }
+    }
+    const selection = await selectSchedulerBackend(deps, options.dryRun);
+    if (!selection.ok)
+        return { ok: false, error: selection.error };
+    const backend = selection.backend;
+    const createInput = {
+        deps,
+        id: resolved.id,
+        runAtIso: resolved.runAtIso,
+        invocation: resolved.invocation,
+        repoPath: resolved.repoPath,
+        ideaFile: resolved.ideaFile,
+        envPath: resolved.envPath,
+        nodePath: resolved.nodePath,
+        npxPath: resolved.npxPath,
+        claudePath: resolved.claudePath,
+        paths: resolved.paths,
+        dryRun: options.dryRun,
+    };
+    if (options.dryRun) {
+        const createResult = await backend.create(createInput);
+        if (!createResult.ok) {
+            return { ok: false, error: createResult.error ?? "Backend dry-run failed." };
+        }
+        const metadata = buildScheduleMetadata(resolved, createResult, createdAtIso);
+        return { ok: true, dryRun: true, metadata, metadataPath, createResult };
+    }
+    await ensureScheduleDirectories(deps.homeDir, deps.platform);
+    const createResult = await backend.create(createInput);
+    if (!createResult.ok) {
+        return { ok: false, error: createResult.error ?? "Scheduler backend create failed." };
+    }
+    const metadata = buildScheduleMetadata(resolved, createResult, createdAtIso);
+    try {
+        await writeScheduleMetadata(metadata, deps.homeDir, deps.platform);
+    }
+    catch (error) {
+        // Native unit/job exists but we can't persist metadata — roll back the unit.
+        await backend.cancel({ deps, metadata }).catch(() => undefined);
+        return {
+            ok: false,
+            error: `Created the native ${createResult.backend} unit but failed to persist schedule metadata ` +
+                `(${error instanceof Error ? error.message : String(error)}); attempted to cancel the native unit.`,
+        };
+    }
+    return { ok: true, dryRun: false, metadata, metadataPath, createResult };
+}
+/** Format a create result for display (dry-run prints artifacts verbatim). */
+export function formatScheduleCreateResult(result) {
+    if (!result.ok)
+        return `Error: ${result.error}`;
+    const m = result.metadata;
+    const lines = [];
+    lines.push(result.dryRun ? "[dry-run] schedule-run create preview" : "Schedule created.");
+    lines.push(`  id:           ${m.id}`);
+    lines.push(`  backend:      ${m.backend}`);
+    lines.push(`  run at:       ${m.run_at_iso}`);
+    lines.push(`  agent:        ${m.agent}`);
+    lines.push(`  metadata:     ${result.metadataPath}${result.dryRun ? " (not written in dry-run)" : ""}`);
+    lines.push(`  repo path:    ${m.repo_path}`);
+    lines.push(`  idea file:    ${m.idea_file}`);
+    lines.push(`  stdout log:   ${m.logs.stdout}`);
+    lines.push(`  stderr log:   ${m.logs.stderr}`);
+    lines.push(`  baked PATH:   ${m.env_path}`);
+    lines.push(`  node:         ${m.node_path}`);
+    lines.push(`  npx:          ${m.npx_path}`);
+    lines.push(`  claude:       ${m.claude_path}`);
+    lines.push(`  invocation:   ${[m.invocation.exe, ...m.invocation.args].join(" ")}`);
+    if (m.unit_paths.length > 0) {
+        lines.push(`  unit paths:   ${m.unit_paths.join(", ")}`);
+    }
+    if (result.dryRun) {
+        for (const artifact of result.createResult.artifacts) {
+            lines.push("");
+            lines.push(`----- ${artifact.kind}: ${artifact.path} -----`);
+            lines.push(artifact.content);
+        }
+    }
+    return lines.join("\n");
+}
+/** Apply id/agent/backend filters consistently. */
+export function filterScheduleMetadata(rows, filters) {
+    return rows.filter((row) => {
+        if (filters.id !== undefined && row.id !== filters.id)
+            return false;
+        if (filters.agent !== undefined && row.agent !== filters.agent)
+            return false;
+        if (filters.backend !== undefined && row.backend !== filters.backend)
+            return false;
+        return true;
+    });
+}
+/** Read local metadata, reconcile each backend group with native state. */
+export async function orchestrateScheduleList(options, deps) {
+    const rows = await listScheduleMetadata(deps.homeDir, deps.platform);
+    const warnings = [];
+    const valid = [];
+    for (const row of rows) {
+        if (row.ok) {
+            valid.push(row.metadata);
+        }
+        else {
+            warnings.push(`Skipping malformed schedule metadata ${row.path}: ${row.error}`);
+        }
+    }
+    const filtered = filterScheduleMetadata(valid, {
+        id: options.id,
+        agent: options.agent,
+        backend: options.backend,
+    });
+    // Group by backend so each backend's list() is called once with its rows.
+    const byBackend = new Map();
+    for (const row of filtered) {
+        const group = byBackend.get(row.backend) ?? [];
+        group.push(row);
+        byBackend.set(row.backend, group);
+    }
+    const entries = [];
+    for (const [backendName, recorded] of byBackend) {
+        const backend = getSchedulerBackendByName(backendName);
+        if (!backend) {
+            for (const metadata of recorded) {
+                entries.push({ metadata, status: "backend-unavailable", detail: "unknown backend" });
+            }
+            continue;
+        }
+        const groupEntries = await backend.list({ deps, recorded });
+        entries.push(...groupEntries);
+    }
+    // Stable order by id for deterministic output.
+    entries.sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+    return { entries, warnings };
+}
+/** Format a list report as a table (or JSON when requested). */
+export function formatScheduleListResult(report, json) {
+    if (json) {
+        // Wrap as { entries, warnings } so malformed-metadata warnings are not lost
+        // for consumers piping `schedule-run list --json` into tooling.
+        return JSON.stringify({
+            entries: report.entries.map((e) => ({
+                id: e.metadata.id,
+                run_at: e.metadata.run_at_iso,
+                backend: e.metadata.backend,
+                agent: e.metadata.agent,
+                status: e.status,
+                unit_path: e.metadata.unit_path,
+            })),
+            warnings: report.warnings,
+        }, null, 2);
+    }
+    const lines = [];
+    for (const w of report.warnings)
+        lines.push(`Warning: ${w}`);
+    if (report.entries.length === 0) {
+        lines.push("No schedules found.");
+        return lines.join("\n");
+    }
+    lines.push(["ID", "RUN_AT", "BACKEND", "AGENT", "STATUS", "UNIT_PATH"].join("  "));
+    for (const e of report.entries) {
+        lines.push([
+            e.metadata.id,
+            e.metadata.run_at_iso,
+            e.metadata.backend,
+            e.metadata.agent,
+            e.status,
+            e.metadata.unit_path ?? "-",
+        ].join("  "));
+    }
+    return lines.join("\n");
+}
+/** Cancel a schedule by id (with optional agent/backend filters). */
+export async function orchestrateScheduleCancel(options, deps) {
+    const metadata = await readScheduleMetadata(options.id, deps.homeDir, deps.platform);
+    if (!metadata) {
+        return { ok: false, notFound: true, error: `No schedule found with id '${options.id}'.` };
+    }
+    if (options.agent !== undefined && metadata.agent !== options.agent) {
+        return {
+            ok: false,
+            notFound: true,
+            error: `Schedule '${options.id}' does not match agent filter '${options.agent}'.`,
+        };
+    }
+    if (options.backend !== undefined && metadata.backend !== options.backend) {
+        return {
+            ok: false,
+            notFound: true,
+            error: `Schedule '${options.id}' does not match backend filter '${options.backend}'.`,
+        };
+    }
+    const backend = getSchedulerBackendByName(metadata.backend);
+    if (!backend) {
+        return { ok: false, error: `Unknown backend '${metadata.backend}' recorded for '${options.id}'.` };
+    }
+    const cancelResult = await backend.cancel({ deps, metadata });
+    if (!cancelResult.ok) {
+        return { ok: false, error: cancelResult.error ?? "Backend cancel failed." };
+    }
+    // Stale or removed both delete local metadata; logs are preserved by the store.
+    await deleteScheduleMetadata(options.id, deps.homeDir, deps.platform);
+    return {
+        ok: true,
+        id: options.id,
+        backend: metadata.backend,
+        nativeRemoved: cancelResult.nativeRemoved,
+        stale: cancelResult.stale,
+        metadataRemoved: true,
+    };
+}
+/** Format a cancel result. */
+export function formatScheduleCancelResult(result) {
+    if (!result.ok)
+        return `Error: ${result.error}`;
+    return [
+        `Schedule '${result.id}' canceled.`,
+        `  backend:          ${result.backend}`,
+        `  native removed:   ${result.nativeRemoved ? "yes" : `no${result.stale ? " (stale)" : ""}`}`,
+        `  metadata removed: ${result.metadataRemoved ? "yes" : "no"}`,
+        "  logs:             preserved",
+    ].join("\n");
+}
+/** Read-only diagnostics: platform support, backend order/availability, binaries. */
+export async function orchestrateScheduleDoctor(deps) {
+    const platformResult = getSchedulerBackendsForPlatform(deps.platform);
+    const envPath = deps.env.PATH ?? deps.env.Path ?? "";
+    const claudeResolved = Boolean(await resolveCommandOnPath("claude", envPath, deps));
+    const npxResolved = Boolean(await resolveCommandOnPath("npx", envPath, deps));
+    if (!platformResult.ok) {
+        return {
+            platform: deps.platform,
+            platformSupported: false,
+            candidateBackends: [],
+            backendAvailability: [],
+            claudeResolved,
+            npxResolved,
+            unsupportedMessage: platformResult.error,
+        };
+    }
+    const candidateBackends = platformResult.backends.map((b) => b.name);
+    const backendAvailability = [];
+    for (const backend of platformResult.backends) {
+        backendAvailability.push({ backend: backend.name, available: await backend.isAvailable(deps) });
+    }
+    return {
+        platform: deps.platform,
+        platformSupported: true,
+        candidateBackends,
+        backendAvailability,
+        claudeResolved,
+        npxResolved,
+    };
+}
+/** Format the doctor report (table or JSON). */
+export function formatScheduleDoctorReport(report, json) {
+    if (json)
+        return JSON.stringify(report, null, 2);
+    const lines = [
+        "schedule-run doctor (read-only diagnostics)",
+        `Platform: ${report.platform}`,
+    ];
+    if (!report.platformSupported) {
+        lines.push(report.unsupportedMessage ?? unsupportedSchedulerPlatformMessage(report.platform));
+    }
+    else {
+        lines.push(`Candidate backends (in order): ${report.candidateBackends.join(", ")}`);
+        for (const a of report.backendAvailability) {
+            lines.push(`  ${a.available ? "AVAILABLE  " : "UNAVAILABLE"} ${a.backend}`);
+        }
+    }
+    lines.push(`claude on PATH: ${report.claudeResolved ? "yes" : "no"}`);
+    lines.push(`npx on PATH:    ${report.npxResolved ? "yes" : "no"}`);
+    return lines.join("\n");
+}
+/**
+ * CLI entry for `schedule-run`. Returns a numeric process exit code. Help → 0;
+ * parser/validation errors → 1 (printed with usage to stderr); create/list/
+ * cancel/doctor dispatch otherwise. Unexpected errors are caught at this
+ * boundary, logged internally to stderr, and surfaced to the user sanitized.
+ */
+export async function runScheduleRunCli(argv, overrides = {}) {
+    const log = overrides.log ?? ((m) => console.log(m));
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    const parsed = parseScheduleRunArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        errorLog(`Error: ${parsed.message}`);
+        errorLog("");
+        errorLog(getScheduleRunUsage());
+        return 1;
+    }
+    const deps = overrides.deps ?? createDefaultScheduleRunDeps();
+    try {
+        switch (parsed.subcommand) {
+            case "create": {
+                const result = await orchestrateScheduleCreate(parsed.options, deps);
+                if (!result.ok) {
+                    errorLog(formatScheduleCreateResult(result));
+                    return 1;
+                }
+                log(formatScheduleCreateResult(result));
+                return 0;
+            }
+            case "list": {
+                const report = await orchestrateScheduleList(parsed.options, deps);
+                log(formatScheduleListResult(report, parsed.options.json));
+                return 0;
+            }
+            case "cancel": {
+                const result = await orchestrateScheduleCancel(parsed.options, deps);
+                if (!result.ok) {
+                    errorLog(formatScheduleCancelResult(result));
+                    return 1;
+                }
+                log(formatScheduleCancelResult(result));
+                return 0;
+            }
+            case "doctor": {
+                const report = await orchestrateScheduleDoctor(deps);
+                log(formatScheduleDoctorReport(report, parsed.options.json));
+                return report.platformSupported ? 0 : 1;
+            }
+        }
+    }
+    catch (error) {
+        // Log the internal detail to stderr for local diagnostics, but surface a
+        // sanitized message as the primary user-facing error.
+        const detail = error instanceof Error ? error.message : String(error);
+        errorLog(`Internal error: ${detail}`);
+        errorLog("Error: schedule-run failed unexpectedly. See the message above for local diagnostics.");
+        return 1;
+    }
+    // Unreachable: the switch is exhaustive over the parsed subcommands.
+    return 1;
+}