@bridge_gpt/mcp-server 0.2.0 → 0.2.1

package/build/schedule-run.js

@@ -16,11 +16,13 @@
  */
 import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHash } 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 { 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";
 /**
  * Default deps backed by real subprocesses / process state. Subprocess execution
  * uses `execFile` (list-based, never `shell: true`) and supports
@@ -55,12 +57,30 @@ export function createDefaultScheduleRunDeps() {
         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",
@@ -78,23 +98,28 @@ export function getScheduleRunUsage() {
         "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.",
+        "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 --at "<datetime>" --idea-file <path> [flags]',
-        "  schedule-run create --in <duration> --idea-file <path> [flags]",
+        "  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)",
-        "  --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",
+        "  --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:",
@@ -132,13 +157,24 @@ function takeValue(argv, index, arg, flag) {
 function matchesFlag(arg, flag) {
     return arg === flag || arg.startsWith(`${flag}=`);
 }
-/** Parse `create` args. */
+/**
+ * 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) {
-    if (argv.includes("-h") || argv.includes("--help")) {
+    // 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;
@@ -146,10 +182,10 @@ export function parseScheduleCreateArgs(argv) {
     let sawAutoApprove = false;
     let sawNoAutoApprove = false;
     let dryRun = false;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
+    for (let i = 0; i < schedulerArgs.length; i++) {
+        const arg = schedulerArgs[i];
         if (matchesFlag(arg, "--at")) {
-            const r = takeValue(argv, i, arg, "--at");
+            const r = takeValue(schedulerArgs, i, arg, "--at");
             if ("error" in r)
                 return { status: "error", message: r.error };
             at = r.value;
@@ -157,15 +193,23 @@ export function parseScheduleCreateArgs(argv) {
             continue;
         }
         if (matchesFlag(arg, "--in")) {
-            const r = takeValue(argv, i, 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(argv, i, arg, "--idea-file");
+            const r = takeValue(schedulerArgs, i, arg, "--idea-file");
             if ("error" in r)
                 return { status: "error", message: r.error };
             ideaFile = r.value;
@@ -173,13 +217,13 @@ export function parseScheduleCreateArgs(argv) {
             continue;
         }
         if (matchesFlag(arg, "--agent")) {
-            const r = takeValue(argv, i, 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}'. Only ${formatValidAgentLauncherNames()} is supported in v1.`,
+                    message: `Invalid --agent value: '${r.value}'. Valid: ${formatValidAgentLauncherNames()}.`,
                 };
             }
             agent = r.value;
@@ -187,7 +231,7 @@ export function parseScheduleCreateArgs(argv) {
             continue;
         }
         if (matchesFlag(arg, "--repo-path")) {
-            const r = takeValue(argv, i, arg, "--repo-path");
+            const r = takeValue(schedulerArgs, i, arg, "--repo-path");
             if ("error" in r)
                 return { status: "error", message: r.error };
             repoPath = r.value;
@@ -195,7 +239,7 @@ export function parseScheduleCreateArgs(argv) {
             continue;
         }
         if (matchesFlag(arg, "--id")) {
-            const r = takeValue(argv, i, arg, "--id");
+            const r = takeValue(schedulerArgs, i, arg, "--id");
             if ("error" in r)
                 return { status: "error", message: r.error };
             id = r.value;
@@ -219,7 +263,8 @@ export function parseScheduleCreateArgs(argv) {
         }
         return {
             status: "error",
-            message: `Unexpected positional argument: '${arg}'. create takes only flags.`,
+            message: `Unexpected positional argument: '${arg}'. create takes flags before '--'; ` +
+                "put command arguments after '--'.",
         };
     }
     if (Boolean(at) === Boolean(inDuration)) {
@@ -228,9 +273,6 @@ export function parseScheduleCreateArgs(argv) {
             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",
@@ -244,21 +286,60 @@ export function parseScheduleCreateArgs(argv) {
                 "(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")) {
@@ -427,6 +508,9 @@ export function parseScheduleRunArgs(argv) {
             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",
@@ -464,24 +548,42 @@ function resolveAbsolute(p, deps) {
     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`).
+ * 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 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}` };
-        }
+    const launcher = getAgentLauncher(options.agent);
+    if (!launcher) {
+        return {
+            ok: false,
+            error: `Unsupported agent: '${options.agent}'. Valid: ${formatValidAgentLauncherNames()}.`,
+        };
     }
-    catch {
-        return { ok: false, error: `--idea-file does not exist: ${ideaFile}` };
+    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()) {
@@ -491,30 +593,75 @@ export async function resolveScheduleCreateInput(options, runAtIso, deps) {
     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 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) {
+    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 (v1 invokes claude directly); empty when absent.
+    // npx is resolved best-effort; empty when absent.
     const npxPath = (await resolveCommandOnPath("npx", envPath, deps)) ?? "";
-    const invocation = launcher.buildInvocation(claudePath, {
+    const id = options.id ?? randomUUID();
+    const agentInvocation = launcher.buildInvocation(agentPath, {
+        scheduleId: id,
         runAtIso,
-        ideaFile,
+        commandName,
+        args: normalizedArgv,
         autoApprove: options.autoApprove,
+        repoPath,
+        commandFilePath: command.filePath,
+        commandBody: command.body,
+        schema: command.argumentSchema,
     });
-    const id = options.id ?? randomUUID();
+    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 @bridge_gpt/mcp-server`) " +
+            "and schedule with the installed binary so the trigger path stays stable.");
+    }
     const paths = getSchedulePaths(id, deps.homeDir, deps.platform);
     return {
         ok: true,
@@ -522,40 +669,71 @@ export async function resolveScheduleCreateInput(options, runAtIso, deps) {
             id,
             runAtIso,
             agent: options.agent,
-            ideaFile,
+            command: commandName,
+            args: normalizedArgv,
+            commandFilePath: command.filePath,
+            commandBodyHash,
+            autoApprove: options.autoApprove,
             repoPath,
+            legacyIdeaFile,
             envPath,
             nodePath,
             npxPath,
-            claudePath,
-            invocation,
+            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. */
+/**
+ * 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,
-        idea_file: resolved.ideaFile,
+        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,
-        claude_path: resolved.claudePath,
-        invocation: resolved.invocation,
+        // 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 },
     };
 }
@@ -621,13 +799,17 @@ export async function orchestrateScheduleCreate(options, deps) {
         deps,
         id: resolved.id,
         runAtIso: resolved.runAtIso,
-        invocation: resolved.invocation,
+        triggerInvocation: resolved.triggerInvocation,
+        agentInvocation: resolved.agentInvocation,
+        command: resolved.command,
+        args: resolved.args,
+        agent: resolved.agent,
         repoPath: resolved.repoPath,
-        ideaFile: resolved.ideaFile,
         envPath: resolved.envPath,
         nodePath: resolved.nodePath,
         npxPath: resolved.npxPath,
-        claudePath: resolved.claudePath,
+        agentPath: resolved.agentPath,
+        legacyIdeaFile: resolved.legacyIdeaFile,
         paths: resolved.paths,
         dryRun: options.dryRun,
     };
@@ -637,7 +819,7 @@ export async function orchestrateScheduleCreate(options, deps) {
             return { ok: false, error: createResult.error ?? "Backend dry-run failed." };
         }
         const metadata = buildScheduleMetadata(resolved, createResult, createdAtIso);
-        return { ok: true, dryRun: true, metadata, metadataPath, createResult };
+        return { ok: true, dryRun: true, metadata, metadataPath, createResult, resolved };
     }
     await ensureScheduleDirectories(deps.homeDir, deps.platform);
     const createResult = await backend.create(createInput);
@@ -645,6 +827,9 @@ export async function orchestrateScheduleCreate(options, deps) {
         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);
     }
@@ -657,33 +842,73 @@ export async function orchestrateScheduleCreate(options, deps) {
                 `(${error instanceof Error ? error.message : String(error)}); attempted to cancel the native unit.`,
         };
     }
-    return { ok: true, dryRun: false, metadata, metadataPath, createResult };
+    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 (dry-run prints artifacts verbatim). */
+/**
+ * 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(`  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(" ")}`);
+    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(", ")}`);
+        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} -----`);
@@ -745,6 +970,19 @@ export async function orchestrateScheduleList(options, deps) {
     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) {
@@ -753,9 +991,15 @@ export function formatScheduleListResult(report, json) {
         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,
             })),
@@ -769,14 +1013,16 @@ export function formatScheduleListResult(report, json) {
         lines.push("No schedules found.");
         return lines.join("\n");
     }
-    lines.push(["ID", "RUN_AT", "BACKEND", "AGENT", "STATUS", "UNIT_PATH"].join("  "));
+    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("  "));
     }
@@ -810,6 +1056,11 @@ export async function orchestrateScheduleCancel(options, deps) {
     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 {
@@ -833,12 +1084,20 @@ export function formatScheduleCancelResult(result) {
         "  logs:             preserved",
     ].join("\n");
 }
-/** Read-only diagnostics: platform support, backend order/availability, binaries. */
+/**
+ * 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,
@@ -846,7 +1105,10 @@ export async function orchestrateScheduleDoctor(deps) {
             candidateBackends: [],
             backendAvailability: [],
             claudeResolved,
+            cursorResolved,
             npxResolved,
+            cursorApiKeyPresent,
+            bridgeCredentialResolved,
             unsupportedMessage: platformResult.error,
         };
     }
@@ -861,10 +1123,13 @@ export async function orchestrateScheduleDoctor(deps) {
         candidateBackends,
         backendAvailability,
         claudeResolved,
+        cursorResolved,
         npxResolved,
+        cursorApiKeyPresent,
+        bridgeCredentialResolved,
     };
 }
-/** Format the doctor report (table or JSON). */
+/** Format the doctor report (table or JSON). Never prints secret values. */
 export function formatScheduleDoctorReport(report, json) {
     if (json)
         return JSON.stringify(report, null, 2);
@@ -881,10 +1146,82 @@ export function formatScheduleDoctorReport(report, json) {
             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"}`);
+    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/
@@ -936,6 +1273,17 @@ export async function runScheduleRunCli(argv, overrides = {}) {
                 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) {