@bridge_gpt/mcp-server 0.1.16 → 0.1.17

package/build/schedule-store.js

@@ -0,0 +1,132 @@
+/**
+ * Local-only schedule metadata storage (BAPI-327).
+ *
+ * Schedules live entirely under `~/.bridge-gpt/schedules/` on the user's machine
+ * and are NEVER mirrored to the Bridge server. One pretty-printed JSON file per
+ * schedule id holds the metadata; stdout/stderr land in `logs/<id>.{out,err}`.
+ *
+ * All paths are rooted at the injected `homeDir` (never `os.homedir()` directly)
+ * and built with the platform path API, so the store is fully unit-testable for
+ * any OS from any host and never touches the real home directory in tests.
+ */
+import { promises as fs } from "node:fs";
+import { pathApiForPlatform } from "./scheduler-backends/types.js";
+/**
+ * Build the schedule root from the injected home directory and platform path
+ * API: `~/.bridge-gpt/schedules` on POSIX, `%USERPROFILE%\.bridge-gpt\schedules`
+ * on Windows.
+ */
+export function getScheduleRoot(homeDir, platform) {
+    const pathApi = pathApiForPlatform(platform);
+    return pathApi.join(homeDir, ".bridge-gpt", "schedules");
+}
+/** Return the metadata + log paths for a schedule id under the schedule root. */
+export function getSchedulePaths(id, homeDir, platform) {
+    const pathApi = pathApiForPlatform(platform);
+    const schedulesDir = getScheduleRoot(homeDir, platform);
+    const logsDir = pathApi.join(schedulesDir, "logs");
+    return {
+        schedulesDir,
+        logsDir,
+        metadataPath: pathApi.join(schedulesDir, `${id}.json`),
+        stdoutPath: pathApi.join(logsDir, `${id}.out`),
+        stderrPath: pathApi.join(logsDir, `${id}.err`),
+    };
+}
+/**
+ * Create only the schedules directory and the logs directory. Must NOT be called
+ * by dry-run code paths — dry-run never touches the filesystem.
+ */
+export async function ensureScheduleDirectories(homeDir, platform) {
+    const pathApi = pathApiForPlatform(platform);
+    const schedulesDir = getScheduleRoot(homeDir, platform);
+    const logsDir = pathApi.join(schedulesDir, "logs");
+    await fs.mkdir(schedulesDir, { recursive: true });
+    await fs.mkdir(logsDir, { recursive: true });
+}
+/**
+ * Persist one pretty-printed JSON file per schedule id with a trailing newline.
+ * Called only AFTER the scheduler backend successfully creates the unit/job.
+ */
+export async function writeScheduleMetadata(metadata, homeDir, platform) {
+    const { metadataPath } = getSchedulePaths(metadata.id, homeDir, platform);
+    await fs.writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+}
+/** Read and parse a single schedule metadata JSON file; `null` when missing. */
+export async function readScheduleMetadata(id, homeDir, platform) {
+    const { metadataPath } = getSchedulePaths(id, homeDir, platform);
+    let raw;
+    try {
+        raw = await fs.readFile(metadataPath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    return JSON.parse(raw);
+}
+/**
+ * Read every `*.json` metadata file from the schedule root. Malformed JSON is
+ * surfaced as a controlled parse-error row (never silently swallowed); a missing
+ * schedule directory yields an empty list, but any other filesystem error
+ * (e.g. EACCES) propagates rather than masquerading as "no schedules".
+ */
+export async function listScheduleMetadata(homeDir, platform) {
+    const pathApi = pathApiForPlatform(platform);
+    const schedulesDir = getScheduleRoot(homeDir, platform);
+    let entries;
+    try {
+        entries = await fs.readdir(schedulesDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const rows = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const id = entry.slice(0, -".json".length);
+        const fullPath = pathApi.join(schedulesDir, entry);
+        let raw;
+        try {
+            raw = await fs.readFile(fullPath, "utf-8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue; // raced delete
+            throw error;
+        }
+        try {
+            const metadata = JSON.parse(raw);
+            rows.push({ ok: true, id, metadata, path: fullPath });
+        }
+        catch (error) {
+            rows.push({
+                ok: false,
+                id,
+                path: fullPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * Delete the schedule metadata JSON file after a successful or stale cancel. The
+ * local log files (`logs/<id>.out|.err`) are deliberately left in place for
+ * post-run inspection.
+ */
+export async function deleteScheduleMetadata(id, homeDir, platform) {
+    const { metadataPath } = getSchedulePaths(id, homeDir, platform);
+    try {
+        await fs.unlink(metadataPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}

package/build/scheduler-backends/at-fallback.js

@@ -0,0 +1,144 @@
+import { formatEnvExportsForGeneratedUnit, posixShellQuote } from "./escaping.js";
+/** Virtual artifact path for the script piped to `at` (never written to disk). */
+export const AT_STDIN_ARTIFACT_PATH = "<at-stdin>";
+/** Convert an ISO timestamp to the `YYYYMMDDHHMM` form required by `at -t`. */
+export function formatAtTimestamp(runAtIso) {
+    const d = new Date(runAtIso);
+    const pad = (n) => String(n).padStart(2, "0");
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `${pad(d.getHours())}${pad(d.getMinutes())}`);
+}
+/** Render the script piped into `at`. */
+export function renderAtScript(input) {
+    const exports = formatEnvExportsForGeneratedUnit({
+        envPath: input.envPath,
+        nodePath: input.nodePath,
+        npxPath: input.npxPath,
+        claudePath: input.claudePath,
+        ideaFile: input.ideaFile,
+        repoPath: input.repoPath,
+    });
+    const command = [input.invocation.exe, ...input.invocation.args]
+        .map((part) => posixShellQuote(part))
+        .join(" ");
+    return [
+        "#!/bin/sh",
+        exports,
+        `cd ${posixShellQuote(input.repoPath)}`,
+        `${command} >>${posixShellQuote(input.paths.stdoutPath)} 2>>${posixShellQuote(input.paths.stderrPath)}`,
+        "",
+    ].join("\n");
+}
+/**
+ * Parse an `at` job id from common stdout/stderr forms; `null` when absent.
+ * Anchored to the start of a line so a stray earlier "job" word can't be
+ * mistaken for the job line, and (defensively, should `at` ever print more than
+ * one) the LAST `job <id> at …` line wins.
+ */
+export function parseAtJobId(stdout, stderr) {
+    const combined = `${stdout}\n${stderr}`;
+    const matches = [...combined.matchAll(/^job\s+(\d+)\s+at\b/gim)];
+    return matches.length > 0 ? matches[matches.length - 1][1] : null;
+}
+/** Whether both `at` and `atq` resolve (used by isAvailable). */
+async function atToolsResolvable(deps) {
+    const at = await deps.runCommand("which", ["at"]);
+    if (at.exitCode !== 0)
+        return false;
+    const atq = await deps.runCommand("which", ["atq"]);
+    return atq.exitCode === 0;
+}
+/** Create the Linux `at` fallback backend. */
+export function createAtFallbackBackend() {
+    return {
+        name: "at-fallback",
+        async isAvailable(deps) {
+            if (deps.platform !== "linux")
+                return false;
+            return atToolsResolvable(deps);
+        },
+        async create(input) {
+            const script = renderAtScript(input);
+            const artifact = {
+                path: AT_STDIN_ARTIFACT_PATH,
+                content: script,
+                kind: "at-script",
+            };
+            if (input.dryRun) {
+                return {
+                    ok: true,
+                    backend: "at-fallback",
+                    unitPath: null,
+                    unitPaths: [],
+                    backendJobId: null,
+                    artifacts: [artifact],
+                };
+            }
+            const timestamp = formatAtTimestamp(input.runAtIso);
+            const result = await input.deps.runCommand("at", ["-t", timestamp], { input: script });
+            if (result.exitCode !== 0) {
+                return {
+                    ok: false,
+                    backend: "at-fallback",
+                    unitPath: null,
+                    unitPaths: [],
+                    backendJobId: null,
+                    artifacts: [artifact],
+                    error: `at scheduling failed: ${(result.stderr || result.stdout).trim()}`,
+                };
+            }
+            const jobId = parseAtJobId(result.stdout, result.stderr);
+            if (!jobId) {
+                return {
+                    ok: false,
+                    backend: "at-fallback",
+                    unitPath: null,
+                    unitPaths: [],
+                    backendJobId: null,
+                    artifacts: [artifact],
+                    error: "Could not parse an at job id from the scheduler output.",
+                };
+            }
+            return {
+                ok: true,
+                backend: "at-fallback",
+                unitPath: null,
+                unitPaths: [],
+                backendJobId: jobId,
+                artifacts: [artifact],
+            };
+        },
+        async list(input) {
+            const atq = await input.deps.runCommand("atq", []);
+            if (atq.exitCode !== 0) {
+                return input.recorded.map((metadata) => ({
+                    metadata,
+                    status: "backend-unavailable",
+                    detail: "atq unavailable",
+                }));
+            }
+            const liveJobIds = new Set(atq.stdout
+                .split(/\r?\n/)
+                .map((line) => line.trim().match(/^(\d+)\b/)?.[1])
+                .filter((id) => Boolean(id)));
+            return input.recorded.map((metadata) => {
+                const jobId = metadata.backend_job_id;
+                const active = jobId !== null && liveJobIds.has(jobId);
+                return {
+                    metadata,
+                    status: active ? "active" : "stale",
+                    detail: active ? `at job ${jobId}` : "at job not queued",
+                };
+            });
+        },
+        async cancel(input) {
+            const jobId = input.metadata.backend_job_id;
+            if (!jobId) {
+                return { ok: true, nativeRemoved: false, stale: true };
+            }
+            const result = await input.deps.runCommand("atrm", [jobId]);
+            const nativeRemoved = result.exitCode === 0;
+            return { ok: true, nativeRemoved, stale: !nativeRemoved };
+        },
+    };
+}

package/build/scheduler-backends/escaping.js

@@ -0,0 +1,113 @@
+/**
+ * Escaping / quoting helpers shared by every scheduler backend (BAPI-327).
+ *
+ * Generated unit content is attacker-adjacent: idea-file paths, repo paths, and
+ * prompts flow into plist XML, Windows `.cmd` wrappers, systemd unit directives,
+ * and `at` heredoc scripts. Each target has a different quoting grammar, so each
+ * gets a dedicated helper. Every helper first rejects NUL bytes — a NUL can
+ * truncate a generated file mid-write and silently drop a security-relevant
+ * suffix — via {@link assertNoNul}.
+ */
+/** All baked PATH-trap environment variable names, in a stable order. */
+export const BAKED_ENV_VAR_NAMES = [
+    "PATH",
+    "BRIDGE_GPT_NODE",
+    "BRIDGE_GPT_NPX",
+    "BRIDGE_GPT_CLAUDE",
+    "BRIDGE_GPT_IDEA_FILE",
+    "BRIDGE_GPT_REPO_PATH",
+];
+/**
+ * Reject any generated value containing a NUL byte. NUL can prematurely
+ * terminate a C-string when a unit file is parsed by the OS scheduler, silently
+ * dropping the rest of the value. The `label` names the offending field so the
+ * error is actionable.
+ */
+export function assertNoNul(value, label) {
+    if (value.includes("\0")) {
+        throw new Error(`Refusing to generate scheduler content: ${label} contains a NUL byte, which is not allowed.`);
+    }
+}
+/** Escape a string for use inside a launchd plist `<string>` value. */
+export function xmlEscape(value) {
+    assertNoNul(value, "xml value");
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Quote a value as a single POSIX shell argument (single-quote form). Empty
+ * strings and strings with spaces become a quoted token; embedded single quotes
+ * use the canonical close/escape/reopen `'\''` form. Used by the `at` heredoc.
+ */
+export function posixShellQuote(value) {
+    assertNoNul(value, "posix shell value");
+    if (value === "")
+        return "''";
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Quote a value for a Windows command line (a single argument inside a `.cmd`
+ * wrapper). Wraps in double quotes and escapes embedded double quotes the
+ * cmd-compatible way. Always quoting keeps paths/prompts with spaces intact.
+ */
+export function windowsCmdQuote(value) {
+    assertNoNul(value, "windows cmd value");
+    // Within double quotes, cmd treats "" as a literal quote.
+    return `"${value.replace(/"/g, '""')}"`;
+}
+/**
+ * Escape a value to be assigned via `set "KEY=value"` in a `.cmd` wrapper. The
+ * `set "KEY=..."` quoted form already neutralises `& | < > ^`, but a literal `%`
+ * still triggers variable expansion, so it is doubled to `%%`. A double quote
+ * would close the `set` quoting, so it is dropped/escaped to keep the line safe.
+ */
+export function escapeWindowsCmdSetValue(value) {
+    assertNoNul(value, "windows cmd set value");
+    return value.replace(/%/g, "%%").replace(/"/g, "");
+}
+/**
+ * Quote a value for a systemd unit directive (e.g. `ExecStart=`, `Environment=`,
+ * `WorkingDirectory=`). systemd accepts double-quoted tokens with C-style
+ * backslash escaping for embedded backslashes and quotes. Empty strings render
+ * as an explicit empty quoted token.
+ */
+export function systemdQuote(value) {
+    assertNoNul(value, "systemd value");
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `"${escaped}"`;
+}
+/**
+ * Build the ordered baked PATH-trap env entries from explicit, schedule-time
+ * values — never `process.env`. Each value is NUL-checked. This is the single
+ * source every backend uses so PATH, BRIDGE_GPT_NODE, BRIDGE_GPT_NPX,
+ * BRIDGE_GPT_CLAUDE, BRIDGE_GPT_IDEA_FILE, and BRIDGE_GPT_REPO_PATH are baked
+ * consistently across launchd / Task Scheduler / systemd / at.
+ */
+export function bakedEnvEntries(env) {
+    const entries = [
+        ["PATH", env.envPath],
+        ["BRIDGE_GPT_NODE", env.nodePath],
+        ["BRIDGE_GPT_NPX", env.npxPath],
+        ["BRIDGE_GPT_CLAUDE", env.claudePath],
+        ["BRIDGE_GPT_IDEA_FILE", env.ideaFile],
+        ["BRIDGE_GPT_REPO_PATH", env.repoPath],
+    ];
+    for (const [key, value] of entries) {
+        assertNoNul(value, key);
+    }
+    return entries;
+}
+/**
+ * Render the baked env as POSIX `export KEY='value'` lines (used by the `at`
+ * heredoc script). Values come only from {@link bakedEnvEntries}; no value is
+ * ever read from the ambient process environment.
+ */
+export function formatEnvExportsForGeneratedUnit(env) {
+    return bakedEnvEntries(env)
+        .map(([key, value]) => `export ${key}=${posixShellQuote(value)}`)
+        .join("\n");
+}

package/build/scheduler-backends/index.js

@@ -0,0 +1,72 @@
+import { createLaunchdBackend } from "./launchd.js";
+import { createTaskSchedulerBackend } from "./task-scheduler.js";
+import { createSystemdUserBackend } from "./systemd-user.js";
+import { createAtFallbackBackend } from "./at-fallback.js";
+export * from "./types.js";
+const LAUNCHD = createLaunchdBackend();
+const TASK_SCHEDULER = createTaskSchedulerBackend();
+const SYSTEMD_USER = createSystemdUserBackend();
+const AT_FALLBACK = createAtFallbackBackend();
+const SUPPORTED_PLATFORMS = ["darwin", "win32", "linux"];
+/** Controlled message for an unsupported `process.platform`. */
+export function unsupportedSchedulerPlatformMessage(platform) {
+    return (`Unsupported platform '${platform}'. schedule-run supports ` +
+        `${SUPPORTED_PLATFORMS.join(", ")}.`);
+}
+/** Return the backend instance for a specific name, or `null` when unknown. */
+export function getSchedulerBackendByName(name) {
+    switch (name) {
+        case "launchd":
+            return LAUNCHD;
+        case "task-scheduler":
+            return TASK_SCHEDULER;
+        case "systemd-user":
+            return SYSTEMD_USER;
+        case "at-fallback":
+            return AT_FALLBACK;
+        default:
+            return null;
+    }
+}
+/** Return the ordered candidate backends for a platform (or unsupported). */
+export function getSchedulerBackendsForPlatform(platform) {
+    switch (platform) {
+        case "darwin":
+            return { ok: true, backends: [LAUNCHD] };
+        case "win32":
+            return { ok: true, backends: [TASK_SCHEDULER] };
+        case "linux":
+            return { ok: true, backends: [SYSTEMD_USER, AT_FALLBACK] };
+        default:
+            return { ok: false, error: unsupportedSchedulerPlatformMessage(platform) };
+    }
+}
+/**
+ * Select the scheduler backend for a create.
+ *
+ * For dry-run, return the platform's PRIMARY backend without probing tool
+ * availability — previewing a unit must not depend on installed schedulers. For
+ * real creates, return the first backend whose `isAvailable` resolves true
+ * (Linux prefers systemd-user, then at-fallback). Returns a controlled error
+ * (never throws) for unsupported platforms or when nothing is available.
+ */
+export async function selectSchedulerBackend(deps, dryRun) {
+    const platformResult = getSchedulerBackendsForPlatform(deps.platform);
+    if (!platformResult.ok) {
+        return { ok: false, error: platformResult.error };
+    }
+    const candidates = platformResult.backends;
+    if (dryRun) {
+        return { ok: true, backend: candidates[0] };
+    }
+    for (const backend of candidates) {
+        if (await backend.isAvailable(deps)) {
+            return { ok: true, backend };
+        }
+    }
+    return {
+        ok: false,
+        error: `No available scheduler backend for platform '${deps.platform}'. ` +
+            `Tried: ${candidates.map((b) => b.name).join(", ")}.`,
+    };
+}

package/build/scheduler-backends/launchd.js

@@ -0,0 +1,216 @@
+/**
+ * macOS launchd backend (BAPI-327).
+ *
+ * Generates and installs a one-shot LaunchAgent plist that fires the baked
+ * Claude invocation at a single calendar minute via `StartCalendarInterval`.
+ *
+ * Drift policy: the plist omits `RunAtLoad` as defense-in-depth (it avoids an
+ * immediate run when the agent is reloaded at login), but this is NOT a true
+ * no-late-fire guarantee — launchd still fires a missed `StartCalendarInterval`
+ * event on the next wake. Unlike systemd `Persistent=false` / Task Scheduler,
+ * launchd has no OS-level "skip if missed" knob, so the authoritative staleness
+ * guard is the baked `--scheduled-at <T>` value in the prompt, which
+ * `/full-automation` (Phase C) checks before running. The working directory is
+ * set by the `WorkingDirectory` key, not a Claude flag. `ProgramArguments` is a
+ * string array (no shell concatenation).
+ */
+import { promises as fs } from "node:fs";
+import { pathApiForPlatform } from "./types.js";
+import { bakedEnvEntries, xmlEscape } from "./escaping.js";
+/** launchd label for a schedule id. */
+export function launchdLabelForId(id) {
+    return `com.bridge-gpt.full-automation.${id}`;
+}
+/** `~/Library/LaunchAgents/<label>.plist` for a schedule id. */
+export function launchdPlistPathForId(id, homeDir) {
+    const pathApi = pathApiForPlatform("darwin");
+    return pathApi.join(homeDir, "Library", "LaunchAgents", `${launchdLabelForId(id)}.plist`);
+}
+/** Convert an ISO timestamp to local launchd calendar fields (minute precision). */
+export function startCalendarIntervalFromIso(runAtIso) {
+    const date = new Date(runAtIso);
+    return {
+        Year: date.getFullYear(),
+        Month: date.getMonth() + 1, // launchd months are 1-12
+        Day: date.getDate(),
+        Hour: date.getHours(),
+        Minute: date.getMinutes(),
+    };
+}
+/** UID used by `launchctl` domain targets; falls back to the process UID. */
+function resolveUid(deps) {
+    const fromEnv = deps.env.UID;
+    if (fromEnv && /^\d+$/.test(fromEnv))
+        return fromEnv;
+    const procUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    return procUid !== undefined ? String(procUid) : "501";
+}
+/** Render a valid one-shot launchd plist. */
+export function renderLaunchdPlist(input) {
+    const label = launchdLabelForId(input.id);
+    const cal = startCalendarIntervalFromIso(input.runAtIso);
+    const env = bakedEnvEntries({
+        envPath: input.envPath,
+        nodePath: input.nodePath,
+        npxPath: input.npxPath,
+        claudePath: input.claudePath,
+        ideaFile: input.ideaFile,
+        repoPath: input.repoPath,
+    });
+    const programArgs = [input.invocation.exe, ...input.invocation.args]
+        .map((arg) => `    <string>${xmlEscape(arg)}</string>`)
+        .join("\n");
+    const envEntries = env
+        .map(([key, value]) => `    <key>${xmlEscape(key)}</key>\n    <string>${xmlEscape(value)}</string>`)
+        .join("\n");
+    // No run-at-load key (defense-in-depth: avoids an immediate run on agent
+    // reload). This does NOT stop a missed StartCalendarInterval from firing on
+    // wake — staleness is enforced by `/full-automation --scheduled-at` (Phase C).
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "  <key>Label</key>",
+        `  <string>${xmlEscape(label)}</string>`,
+        "  <key>StartCalendarInterval</key>",
+        "  <dict>",
+        `    <key>Year</key><integer>${cal.Year}</integer>`,
+        `    <key>Month</key><integer>${cal.Month}</integer>`,
+        `    <key>Day</key><integer>${cal.Day}</integer>`,
+        `    <key>Hour</key><integer>${cal.Hour}</integer>`,
+        `    <key>Minute</key><integer>${cal.Minute}</integer>`,
+        "  </dict>",
+        "  <key>EnvironmentVariables</key>",
+        "  <dict>",
+        envEntries,
+        "  </dict>",
+        "  <key>ProgramArguments</key>",
+        "  <array>",
+        programArgs,
+        "  </array>",
+        "  <key>WorkingDirectory</key>",
+        `  <string>${xmlEscape(input.repoPath)}</string>`,
+        "  <key>StandardOutPath</key>",
+        `  <string>${xmlEscape(input.paths.stdoutPath)}</string>`,
+        "  <key>StandardErrorPath</key>",
+        `  <string>${xmlEscape(input.paths.stderrPath)}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+/** Create the macOS launchd scheduler backend. */
+export function createLaunchdBackend() {
+    return {
+        name: "launchd",
+        async isAvailable(deps) {
+            return deps.platform === "darwin";
+        },
+        async create(input) {
+            const plistPath = launchdPlistPathForId(input.id, input.deps.homeDir);
+            const content = renderLaunchdPlist(input);
+            const artifact = { path: plistPath, content, kind: "launchd-plist" };
+            if (input.dryRun) {
+                return {
+                    ok: true,
+                    backend: "launchd",
+                    unitPath: plistPath,
+                    unitPaths: [plistPath],
+                    backendJobId: null,
+                    artifacts: [artifact],
+                };
+            }
+            // ~/Library/LaunchAgents may not exist yet for a fresh user account.
+            await fs.mkdir(pathApiForPlatform("darwin").dirname(plistPath), { recursive: true });
+            await fs.writeFile(plistPath, content, "utf-8");
+            const uid = resolveUid(input.deps);
+            const result = await input.deps.runCommand("launchctl", [
+                "bootstrap",
+                `gui/${uid}`,
+                plistPath,
+            ]);
+            if (result.exitCode !== 0) {
+                // Don't leave an orphaned plist behind when bootstrap fails.
+                await fs.unlink(plistPath).catch(() => undefined);
+                return {
+                    ok: false,
+                    backend: "launchd",
+                    unitPath: plistPath,
+                    unitPaths: [plistPath],
+                    backendJobId: null,
+                    artifacts: [artifact],
+                    error: `launchctl bootstrap failed: ${(result.stderr || result.stdout).trim()}`,
+                };
+            }
+            return {
+                ok: true,
+                backend: "launchd",
+                unitPath: plistPath,
+                unitPaths: [plistPath],
+                backendJobId: null,
+                artifacts: [artifact],
+            };
+        },
+        async list(input) {
+            const uid = resolveUid(input.deps);
+            const entries = [];
+            for (const metadata of input.recorded) {
+                const plistPath = metadata.unit_path ?? launchdPlistPathForId(metadata.id, input.deps.homeDir);
+                let exists = true;
+                try {
+                    await fs.access(plistPath);
+                }
+                catch {
+                    exists = false;
+                }
+                if (!exists) {
+                    entries.push({ metadata, status: "stale", detail: "plist missing" });
+                    continue;
+                }
+                const label = launchdLabelForId(metadata.id);
+                const printed = await input.deps.runCommand("launchctl", ["print", `gui/${uid}/${label}`]);
+                entries.push({
+                    metadata,
+                    status: printed.exitCode === 0 ? "active" : "stale",
+                    detail: printed.exitCode === 0 ? "loaded" : "plist present but not loaded",
+                });
+            }
+            return entries;
+        },
+        async cancel(input) {
+            const uid = resolveUid(input.deps);
+            const label = launchdLabelForId(input.metadata.id);
+            const plistPath = input.metadata.unit_path ?? launchdPlistPathForId(input.metadata.id, input.deps.homeDir);
+            let plistExisted = true;
+            try {
+                await fs.access(plistPath);
+            }
+            catch {
+                plistExisted = false;
+            }
+            // bootout is best-effort: an already-unloaded label returns non-zero, which
+            // is treated as stale-but-cancelable rather than a hard failure.
+            const bootout = await input.deps.runCommand("launchctl", [
+                "bootout",
+                `gui/${uid}/${label}`,
+            ]);
+            if (plistExisted) {
+                try {
+                    await fs.unlink(plistPath);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        return { ok: false, nativeRemoved: false, stale: false, error: String(error) };
+                    }
+                }
+            }
+            const nativeRemoved = bootout.exitCode === 0;
+            return {
+                ok: true,
+                nativeRemoved,
+                stale: !plistExisted || !nativeRemoved,
+            };
+        },
+    };
+}