@bridge_gpt/mcp-server 0.2.49 → 0.2.50

package/build/schedule-run.js

@@ -1,1300 +0,0 @@
-/**
- * `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, createHash } from "node:crypto";
-import { pathApiForPlatform, selectSchedulerBackend, getSchedulerBackendByName, getSchedulerBackendsForPlatform, unsupportedSchedulerPlatformMessage, } from "./scheduler-backends/index.js";
-import { ensureScheduleDirectories, getSchedulePaths, writeScheduleMetadata, readScheduleMetadata, listScheduleMetadata, deleteScheduleMetadata, appendScheduleRunEvent, } from "./schedule-store.js";
-import { getAgentLauncher, formatValidAgentLauncherNames } from "./agent-launchers/index.js";
-import { resolveCommandOnPath } from "./agent-launchers/claude.js";
-import { discoverCommandCatalog, resolveSchedulableCommand, validateCommandArgv, } from "./command-catalog.js";
-import { buildTargetCommandLine } from "./scheduled-prompt.js";
-import { MCP_PACKAGE_NAME } from "./mcp-identity.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(),
-        // The packaged CLI entry is argv[1]; the trigger invocation re-enters it as
-        // `node <cliEntryPath> schedule-run _execute <id>`.
-        cliEntryPath: process.argv[1],
-        // Best-effort: a Bridge credential is considered resolvable when BAPI_API_KEY
-        // is present in the environment. Never reads or returns the value itself.
-        bridgeCredentialResolved: () => Boolean(process.env.BAPI_API_KEY),
-    };
-}
-/** Return true only for a zero exit code. */
-export function commandSucceeded(result) {
-    return result.exitCode === 0;
-}
-/**
- * Detect a CLI entry path that lives inside a transient npx cache directory
- * (`~/.npm/_npx/<hash>/…` on POSIX, `…\npm-cache\_npx\<hash>\…` on Windows).
- * Such an entry can be garbage-collected before a future schedule fires, which
- * would make the trigger shim `node <gone-path>` fail with ENOENT. Matched on the
- * `_npx` path segment so it is independent of the surrounding cache root.
- */
-export function isTransientNpxEntryPath(entryPath) {
-    if (!entryPath)
-        return false;
-    return /[\\/]_npx[\\/]/.test(entryPath);
-}
-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 ${MCP_PACKAGE_NAME} schedule-run <create|list|cancel|doctor> [flags]`,
-        "",
-        "Schedules a local, one-shot run of ANY Bridge slash-command automation (from",
-        "the repo's .claude/commands/*.md catalog) 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 --in 2h --command review-ticket -- BAPI-999",
-        '  schedule-run create --at "<datetime>" --command start-tickets -- BAPI-1 BAPI-2',
-        "  legacy: schedule-run create --in 2h --idea-file <path>",
-        "",
-        "All tokens after a bare -- are the structured argv passed to the command.",
-        "",
-        "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)",
-        "  --command <name>         Discovered .claude/commands command to schedule",
-        "  --idea-file <path>       Legacy: schedule /full-automation with this idea file",
-        "  --agent <name>           Agent to launch (claude [default] or cursor-agent)",
-        "  --repo-path <path>       Working directory + command catalog root (default: cwd)",
-        "  --auto                   Run hands-off; gate proceeds even when firing late",
-        "  --no-auto                Late runs halt without executing (headless-safe default)",
-        "  --dry-run                Print the generated unit + prompt + 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. Everything after the FIRST bare `--` is the structured
- * command argv (passed through verbatim, never re-tokenized); scheduler flags are
- * parsed only before that delimiter. `--idea-file` without `--command` implies
- * the legacy `full-automation` command.
- */
-export function parseScheduleCreateArgs(argv) {
-    // Split on the first bare "--". Help is honored only from the scheduler-flag
-    // side; tokens after "--" belong to the delegated command verbatim.
-    const delimIndex = argv.indexOf("--");
-    const schedulerArgs = delimIndex === -1 ? argv : argv.slice(0, delimIndex);
-    const commandArgs = delimIndex === -1 ? [] : argv.slice(delimIndex + 1);
-    if (schedulerArgs.includes("-h") || schedulerArgs.includes("--help")) {
-        return { status: "help", usage: getScheduleRunUsage() };
-    }
-    let at;
-    let inDuration;
-    let commandName;
-    let ideaFile;
-    let agent = "claude";
-    let repoPath;
-    let id;
-    let sawAutoApprove = false;
-    let sawNoAutoApprove = false;
-    let dryRun = false;
-    for (let i = 0; i < schedulerArgs.length; i++) {
-        const arg = schedulerArgs[i];
-        if (matchesFlag(arg, "--at")) {
-            const r = takeValue(schedulerArgs, 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(schedulerArgs, i, arg, "--in");
-            if ("error" in r)
-                return { status: "error", message: r.error };
-            inDuration = r.value;
-            i = r.nextIndex;
-            continue;
-        }
-        if (matchesFlag(arg, "--command")) {
-            const r = takeValue(schedulerArgs, i, arg, "--command");
-            if ("error" in r)
-                return { status: "error", message: r.error };
-            commandName = r.value;
-            i = r.nextIndex;
-            continue;
-        }
-        if (matchesFlag(arg, "--idea-file")) {
-            const r = takeValue(schedulerArgs, 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(schedulerArgs, 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}'. Valid: ${formatValidAgentLauncherNames()}.`,
-                };
-            }
-            agent = r.value;
-            i = r.nextIndex;
-            continue;
-        }
-        if (matchesFlag(arg, "--repo-path")) {
-            const r = takeValue(schedulerArgs, 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(schedulerArgs, 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 flags before '--'; ` +
-                "put command arguments after '--'.",
-        };
-    }
-    if (Boolean(at) === Boolean(inDuration)) {
-        return {
-            status: "error",
-            message: "create requires exactly one of --at or --in.",
-        };
-    }
-    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).",
-        };
-    }
-    // Legacy compatibility: --idea-file without --command implies full-automation.
-    // --idea-file with any OTHER command is rejected (it only applies to that path).
-    if (ideaFile !== undefined) {
-        if (commandName === undefined) {
-            commandName = "full-automation";
-        }
-        else if (commandName !== "full-automation") {
-            return {
-                status: "error",
-                message: `--idea-file is only valid for legacy full-automation scheduling, not --command '${commandName}'. ` +
-                    "Pass command arguments after '--' instead.",
-            };
-        }
-    }
-    if (commandName === undefined) {
-        return {
-            status: "error",
-            message: "create requires --command <name> (or legacy --idea-file <path>).",
-        };
-    }
-    return {
-        status: "ok",
-        subcommand: "create",
-        options: {
-            at,
-            in: inDuration,
-            commandName,
-            commandArgs,
-            ideaFile,
-            agent,
-            repoPath,
-            autoApprove: !sawNoAutoApprove,
-            autoApproveExplicit: sawAutoApprove || sawNoAutoApprove,
-            dryRun,
-            id,
-        },
-    };
-}
-/** Parse the hidden `_execute <id>` shim args (exactly one valid schedule id). */
-export function parseScheduleExecuteArgs(argv) {
-    const positionals = argv.filter((a) => !a.startsWith("-"));
-    const flags = argv.filter((a) => a.startsWith("-"));
-    if (flags.length > 0) {
-        return { status: "error", message: `_execute takes no flags (got ${flags.join(", ")}).` };
-    }
-    if (positionals.length !== 1) {
-        return { status: "error", message: "_execute requires exactly one schedule id." };
-    }
-    const id = positionals[0];
-    if (!SCHEDULE_ID_PATTERN.test(id)) {
-        return { status: "error", message: `Invalid schedule id: '${id}'.` };
-    }
-    return { status: "ok", subcommand: "_execute", options: { 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);
-        // Hidden internal shim the OS unit invokes; intentionally absent from usage.
-        case "_execute":
-            return parseScheduleExecuteArgs(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);
-}
-/**
- * Collect read-only prerequisite/auth readiness for the selected create input.
- * Returns presence/readiness booleans only — it never reads or returns secret
- * values (CURSOR_API_KEY / Bridge credential material).
- */
-export function collectScheduleRunPrereqStatus(input) {
-    return {
-        agentBinaryResolved: input.agentBinaryResolved,
-        repoPathExists: input.repoPathExists,
-        cursorApiKeyPresent: Boolean(input.deps.env.CURSOR_API_KEY),
-        bridgeCredentialResolved: input.deps.bridgeCredentialResolved?.() ?? Boolean(input.deps.env.BAPI_API_KEY),
-    };
-}
-/**
- * Resolve and validate generic create inputs. Resolves the repo path first and
- * validates it is a directory; discovers the `.claude/commands` catalog under it;
- * resolves and validates the requested command (rejecting unknown /
- * `schedulable: false` / malformed); validates structured argv against the
- * command's schema; resolves the agent binary on the baked PATH; builds the agent
- * invocation via the launcher and the trigger invocation for the `_execute` shim.
- * The legacy `--idea-file` path is converted to structured `["--idea-file", abs]`
- * args for `full-automation`. Installs nothing — orchestration owns side effects.
- */
-export async function resolveScheduleCreateInput(options, runAtIso, deps) {
-    const launcher = getAgentLauncher(options.agent);
-    if (!launcher) {
-        return {
-            ok: false,
-            error: `Unsupported agent: '${options.agent}'. Valid: ${formatValidAgentLauncherNames()}.`,
-        };
-    }
-    const commandName = options.commandName;
-    if (!commandName) {
-        return { ok: false, error: "create requires a command (--command or legacy --idea-file)." };
-    }
-    // Resolve + validate the repo path (command-catalog root) BEFORE discovery.
-    const repoPath = resolveAbsolute(options.repoPath ?? deps.cwd, deps);
-    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}` };
-    }
-    // Build the structured command argv. Legacy --idea-file is validated and turned
-    // into ["--idea-file", <abs>] (full-automation only; enforced by the parser).
-    let commandArgs = options.commandArgs;
-    let legacyIdeaFile;
-    if (options.ideaFile !== undefined) {
-        const ideaFile = resolveAbsolute(options.ideaFile, 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}` };
-        }
-        legacyIdeaFile = ideaFile;
-        commandArgs = ["--idea-file", ideaFile];
-    }
-    // Discover the command catalog under the resolved repo and resolve the command.
-    const catalog = await discoverCommandCatalog(repoPath, deps.platform, deps.commandCatalogFsDeps);
-    const resolvedCommand = resolveSchedulableCommand(catalog, commandName);
-    if (!resolvedCommand.ok)
-        return { ok: false, error: resolvedCommand.error };
-    const command = resolvedCommand.command;
-    // Validate the structured argv against the command's schema (or passthrough).
-    const validation = validateCommandArgv(commandArgs, command.argumentSchema);
-    if (!validation.ok) {
-        return { ok: false, error: `Invalid arguments for '${commandName}': ${validation.error}` };
-    }
-    const normalizedArgv = validation.normalizedArgv;
-    const envPath = deps.env.PATH ?? deps.env.Path ?? "";
-    const nodePath = deps.execPath;
-    const agentPath = await launcher.resolveBinary(envPath, deps);
-    if (!agentPath) {
-        return {
-            ok: false,
-            error: `Could not resolve the '${launcher.capability.command}' binary on the baked PATH.`,
-        };
-    }
-    // npx is resolved best-effort; empty when absent.
-    const npxPath = (await resolveCommandOnPath("npx", envPath, deps)) ?? "";
-    const id = options.id ?? randomUUID();
-    const agentInvocation = launcher.buildInvocation(agentPath, {
-        scheduleId: id,
-        runAtIso,
-        commandName,
-        args: normalizedArgv,
-        autoApprove: options.autoApprove,
-        repoPath,
-        commandFilePath: command.filePath,
-        commandBody: command.body,
-        schema: command.argumentSchema,
-    });
-    const cliEntryPath = deps.cliEntryPath ?? process.argv[1] ?? "";
-    const triggerInvocation = {
-        exe: nodePath,
-        args: [cliEntryPath, "schedule-run", "_execute", id],
-    };
-    const commandBodyHash = createHash("sha256").update(command.body, "utf-8").digest("hex");
-    const warnings = [];
-    if (command.interactive && !options.autoApproveExplicit) {
-        warnings.push(`Command '${commandName}' has an interactive step but --auto/--no-auto was not specified; ` +
-            "a headless scheduled run may hang waiting for confirmation. Pass --auto to run hands-off.");
-    }
-    if (isTransientNpxEntryPath(cliEntryPath)) {
-        warnings.push(`The scheduled run re-enters this CLI at '${cliEntryPath}', which is inside an npx cache ` +
-            "directory. npx caches can be pruned before a future schedule fires, which would make the " +
-            `run fail with ENOENT. Install the CLI persistently (e.g. \`npm i -g ${MCP_PACKAGE_NAME}\`) ` +
-            "and schedule with the installed binary so the trigger path stays stable.");
-    }
-    const paths = getSchedulePaths(id, deps.homeDir, deps.platform);
-    return {
-        ok: true,
-        resolved: {
-            id,
-            runAtIso,
-            agent: options.agent,
-            command: commandName,
-            args: normalizedArgv,
-            commandFilePath: command.filePath,
-            commandBodyHash,
-            autoApprove: options.autoApprove,
-            repoPath,
-            legacyIdeaFile,
-            envPath,
-            nodePath,
-            npxPath,
-            agentPath,
-            agentInvocation,
-            triggerInvocation,
-            renderedPrompt: agentInvocation.prompt,
-            schema: command.argumentSchema,
-            paths: {
-                schedulesDir: paths.schedulesDir,
-                logsDir: paths.logsDir,
-                stdoutPath: paths.stdoutPath,
-                stderrPath: paths.stderrPath,
-            },
-            warnings,
-            prereq: collectScheduleRunPrereqStatus({
-                agent: options.agent,
-                agentBinaryResolved: Boolean(agentPath),
-                repoPathExists: true,
-                deps,
-            }),
-        },
-    };
-}
-/**
- * Build the local-only schedule metadata from resolved inputs + backend result.
- * Writes the generalized fields plus legacy compatibility aliases (`invocation`,
- * `claude_path`, `idea_file`) so old readers and full-automation records keep
- * working. Run history is initialized with a `created` event.
- */
-export function buildScheduleMetadata(resolved, createResult, createdAtIso) {
-    return {
-        id: resolved.id,
-        run_at_iso: resolved.runAtIso,
-        scheduled_at: resolved.runAtIso,
-        backend: createResult.backend,
-        unit_path: createResult.unitPath,
-        unit_paths: createResult.unitPaths,
-        backend_job_id: createResult.backendJobId,
-        agent: resolved.agent,
-        agent_path: resolved.agentPath,
-        command: resolved.command,
-        args: resolved.args,
-        command_file: resolved.commandFilePath,
-        command_body_hash: resolved.commandBodyHash,
-        auto_approve: resolved.autoApprove,
-        repo_path: resolved.repoPath,
-        created_at: createdAtIso,
-        env_path: resolved.envPath,
-        node_path: resolved.nodePath,
-        npx_path: resolved.npxPath,
-        // Legacy alias retained for full-automation/claude records.
-        claude_path: resolved.agent === "claude" ? resolved.agentPath : undefined,
-        idea_file: resolved.legacyIdeaFile,
-        invocation: resolved.agentInvocation,
-        agent_invocation: resolved.agentInvocation,
-        trigger_invocation: resolved.triggerInvocation,
-        run_history: [{ status: "created", at: createdAtIso }],
-        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,
-        triggerInvocation: resolved.triggerInvocation,
-        agentInvocation: resolved.agentInvocation,
-        command: resolved.command,
-        args: resolved.args,
-        agent: resolved.agent,
-        repoPath: resolved.repoPath,
-        envPath: resolved.envPath,
-        nodePath: resolved.nodePath,
-        npxPath: resolved.npxPath,
-        agentPath: resolved.agentPath,
-        legacyIdeaFile: resolved.legacyIdeaFile,
-        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, resolved };
-    }
-    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);
-    // Append the `scheduled` event only after the backend created a real OS job.
-    const scheduledAtIso = new Date(deps.now ? deps.now() : Date.now()).toISOString();
-    metadata.run_history = [...(metadata.run_history ?? []), { status: "scheduled", at: scheduledAtIso }];
-    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, resolved };
-}
-/** Format a prereq status block (presence/readiness only, never secret values). */
-function formatPrereqStatus(agent, prereq) {
-    const lines = [
-        `  agent binary: ${prereq.agentBinaryResolved ? "resolved" : "MISSING"}`,
-        `  repo path:    ${prereq.repoPathExists ? "exists" : "MISSING"}`,
-    ];
-    if (agent === "cursor-agent") {
-        lines.push(`  CURSOR_API_KEY set: ${prereq.cursorApiKeyPresent ? "yes" : "no"}`);
-    }
-    else {
-        lines.push(`  Bridge credential: ${prereq.bridgeCredentialResolved ? "resolved" : "not resolved"}`);
-    }
-    return lines;
-}
-/**
- * Format a create result for display. Real create and dry-run both show the
- * delegated command, normalized args, schedule time, agent, repo path, metadata
- * path, agent binary, trigger invocation, agent invocation argv, and the rendered
- * target command line. Dry-run additionally prints the full concatenated prompt,
- * the prerequisite/auth status (secret-free), and the backend artifacts.
- */
-export function formatScheduleCreateResult(result) {
-    if (!result.ok)
-        return `Error: ${result.error}`;
-    const m = result.metadata;
-    const r = result.resolved;
-    const targetCommandLine = buildTargetCommandLine({
-        commandName: r.command,
-        args: r.args,
-        scheduledAt: r.runAtIso,
-        autoApprove: r.autoApprove,
-        schema: r.schema,
-    });
-    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(`  command:          ${r.command}`);
-    lines.push(`  args:             ${r.args.length > 0 ? r.args.join(" ") : "(none)"}`);
-    lines.push(`  run at:           ${m.run_at_iso}`);
-    lines.push(`  agent:            ${m.agent}`);
-    lines.push(`  auto-approve:     ${m.auto_approve ? "yes" : "no"}`);
-    lines.push(`  metadata:         ${result.metadataPath}${result.dryRun ? " (not written in dry-run)" : ""}`);
-    lines.push(`  repo path:        ${m.repo_path}`);
-    if (m.idea_file)
-        lines.push(`  idea file:        ${m.idea_file}`);
-    lines.push(`  stdout log:       ${m.logs.stdout}`);
-    lines.push(`  stderr log:       ${m.logs.stderr}`);
-    lines.push(`  agent binary:     ${r.agentPath}`);
-    lines.push(`  target command:   ${targetCommandLine}`);
-    lines.push(`  trigger invocation: ${[r.triggerInvocation.exe, ...r.triggerInvocation.args].join(" ")}`);
-    lines.push(`  agent invocation:   ${[r.agentInvocation.exe, ...r.agentInvocation.args].join(" ")}`);
-    if (m.unit_paths.length > 0) {
-        lines.push(`  unit paths:       ${m.unit_paths.join(", ")}`);
-    }
-    for (const warning of r.warnings) {
-        lines.push(`  warning:          ${warning}`);
-    }
-    if (result.dryRun) {
-        lines.push("");
-        lines.push("prerequisites (secret-free):");
-        lines.push(...formatPrereqStatus(r.agent, r.prereq));
-        lines.push("");
-        lines.push("----- rendered prompt -----");
-        lines.push(r.renderedPrompt);
-        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 };
-}
-/** Derive the displayed command (legacy rows show `full-automation`). */
-export function scheduleCommandLabel(m) {
-    if (m.command)
-        return m.command;
-    if (m.idea_file)
-        return "full-automation";
-    return "(unknown)";
-}
-/** Latest run-history status, or empty string when no history is recorded. */
-export function latestRunStatus(m) {
-    const h = m.run_history;
-    return h && h.length > 0 ? h[h.length - 1].status : "";
-}
-/** 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,
-                command: scheduleCommandLabel(e.metadata),
-                args: e.metadata.args ?? [],
-                scheduled_at: e.metadata.scheduled_at ?? e.metadata.run_at_iso,
-                run_at: e.metadata.run_at_iso,
-                backend: e.metadata.backend,
-                agent: e.metadata.agent,
-                native_status: e.status,
-                latest_run_status: latestRunStatus(e.metadata),
-                run_history: e.metadata.run_history ?? [],
-                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", "COMMAND", "RUN_AT", "BACKEND", "AGENT", "NATIVE", "LATEST", "UNIT_PATH"].join("  "));
-    for (const e of report.entries) {
-        lines.push([
-            e.metadata.id,
-            scheduleCommandLabel(e.metadata),
-            e.metadata.run_at_iso,
-            e.metadata.backend,
-            e.metadata.agent,
-            e.status,
-            latestRunStatus(e.metadata) || "-",
-            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." };
-    }
-    // Best-effort: record a `canceled` event before deleting metadata. This is
-    // primarily useful if deletion later fails, or if cancellation is refactored
-    // to retain records; a failure here must not mask a successful native cancel.
-    const canceledAtIso = new Date(deps.now ? deps.now() : Date.now()).toISOString();
-    await appendScheduleRunEvent(options.id, { status: "canceled", at: canceledAtIso }, deps.homeDir, deps.platform).catch(() => undefined);
-    // 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, both agent
- * binaries, and secret-free auth readiness for each agent. Stays zero-argument
- * and environment-oriented — command-specific prompt rendering belongs to
- * `create --dry-run`, never here.
- */
-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 cursorResolved = Boolean(await resolveCommandOnPath("cursor-agent", envPath, deps));
-    const npxResolved = Boolean(await resolveCommandOnPath("npx", envPath, deps));
-    const cursorApiKeyPresent = Boolean(deps.env.CURSOR_API_KEY);
-    const bridgeCredentialResolved = deps.bridgeCredentialResolved?.() ?? Boolean(deps.env.BAPI_API_KEY);
-    if (!platformResult.ok) {
-        return {
-            platform: deps.platform,
-            platformSupported: false,
-            candidateBackends: [],
-            backendAvailability: [],
-            claudeResolved,
-            cursorResolved,
-            npxResolved,
-            cursorApiKeyPresent,
-            bridgeCredentialResolved,
-            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,
-        cursorResolved,
-        npxResolved,
-        cursorApiKeyPresent,
-        bridgeCredentialResolved,
-    };
-}
-/** Format the doctor report (table or JSON). Never prints secret values. */
-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(`cursor-agent on PATH:  ${report.cursorResolved ? "yes" : "no"}`);
-    lines.push(`npx on PATH:           ${report.npxResolved ? "yes" : "no"}`);
-    lines.push(`CURSOR_API_KEY set:    ${report.cursorApiKeyPresent ? "yes" : "no"}`);
-    lines.push(`Bridge credential:     ${report.bridgeCredentialResolved ? "resolved" : "not resolved"}`);
-    return lines.join("\n");
-}
-/** Current time as ISO from the injectable clock. */
-function nowIso(deps) {
-    return new Date(deps.now ? deps.now() : Date.now()).toISOString();
-}
-/**
- * The hidden `_execute <id>` shim the OS unit runs at fire time (BAPI-351). It
- * reads the local schedule metadata, validates the stored agent invocation,
- * records a `started` event, spawns the agent via the list-based `runCommand`
- * boundary (NEVER a shell string) with the schedule's cwd + baked env, forwards
- * the agent's stdout/stderr to its own streams (so existing OS log redirection
- * captures them), then records `completed`/`failed` and returns the agent's exit
- * code. Run-history writes are best-effort and never mask the agent's exit code;
- * env values (including any secrets) are never printed.
- */
-export async function orchestrateScheduleExecute(options, deps, io) {
-    const metadata = await readScheduleMetadata(options.id, deps.homeDir, deps.platform);
-    if (!metadata) {
-        return { ok: false, exitCode: 1, error: `No schedule found with id '${options.id}'.` };
-    }
-    const agentInvocation = metadata.agent_invocation ?? metadata.invocation;
-    if (!agentInvocation || !agentInvocation.exe) {
-        await appendScheduleRunEvent(options.id, { status: "failed", at: nowIso(deps), message: "missing agent_invocation" }, deps.homeDir, deps.platform).catch(() => undefined);
-        return { ok: false, exitCode: 1, error: `Schedule '${options.id}' has no agent invocation to run.` };
-    }
-    await appendScheduleRunEvent(options.id, { status: "started", at: nowIso(deps) }, deps.homeDir, deps.platform).catch(() => undefined);
-    // Child env: base env + baked PATH + schedule-context variables. No secrets are
-    // synthesized here; only values already present in metadata/env are forwarded.
-    const env = { ...deps.env };
-    if (metadata.env_path) {
-        env.PATH = metadata.env_path;
-        if (deps.platform === "win32")
-            env.Path = metadata.env_path;
-    }
-    env.BRIDGE_GPT_SCHEDULE_ID = metadata.id;
-    if (metadata.command)
-        env.BRIDGE_GPT_COMMAND = metadata.command;
-    if (metadata.args)
-        env.BRIDGE_GPT_COMMAND_ARGS_JSON = JSON.stringify(metadata.args);
-    if (metadata.repo_path)
-        env.BRIDGE_GPT_REPO_PATH = metadata.repo_path;
-    if (metadata.agent)
-        env.BRIDGE_GPT_AGENT = metadata.agent;
-    if (metadata.agent_path)
-        env.BRIDGE_GPT_AGENT_PATH = metadata.agent_path;
-    if (metadata.idea_file)
-        env.BRIDGE_GPT_IDEA_FILE = metadata.idea_file;
-    let result;
-    try {
-        result = await deps.runCommand(agentInvocation.exe, agentInvocation.args, {
-            cwd: metadata.repo_path,
-            env,
-        });
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        await appendScheduleRunEvent(options.id, { status: "failed", at: nowIso(deps), message: `agent launch failed: ${msg}` }, deps.homeDir, deps.platform).catch(() => undefined);
-        return { ok: false, exitCode: 1, error: `Failed to launch agent: ${msg}` };
-    }
-    if (result.stdout)
-        io.writeStdout(result.stdout);
-    if (result.stderr)
-        io.writeStderr(result.stderr);
-    if (result.exitCode === 0) {
-        await appendScheduleRunEvent(options.id, { status: "completed", at: nowIso(deps), exit_code: 0 }, deps.homeDir, deps.platform).catch(() => undefined);
-        return { ok: true, exitCode: 0 };
-    }
-    await appendScheduleRunEvent(options.id, { status: "failed", at: nowIso(deps), exit_code: result.exitCode }, deps.homeDir, deps.platform).catch(() => undefined);
-    return { ok: false, exitCode: result.exitCode };
-}
-/**
- * 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;
-            }
-            case "_execute": {
-                const io = {
-                    writeStdout: overrides.writeStdout ?? ((chunk) => process.stdout.write(chunk)),
-                    writeStderr: overrides.writeStderr ?? ((chunk) => process.stderr.write(chunk)),
-                };
-                const result = await orchestrateScheduleExecute(parsed.options, deps, io);
-                if (!result.ok && result.error) {
-                    errorLog(`Error: ${result.error}`);
-                }
-                return result.exitCode;
-            }
-        }
-    }
-    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;
-}