@beastmode-develeap/beastmode 0.1.150 → 0.1.152

package/dist/index.js

@@ -2652,7 +2652,7 @@ var init_migrator = __esm({
 
 // src/engine/bridge.ts
 function generateDaemonConfig(factoryConfig, projectConfig, factoryPath) {
-  const pipeline = factoryConfig.pipeline;
+  const pipeline2 = factoryConfig.pipeline;
   const models = factoryConfig.models;
   const resilience = factoryConfig.resilience;
   const cost = factoryConfig.cost;
@@ -2720,9 +2720,9 @@ function generateDaemonConfig(factoryConfig, projectConfig, factoryPath) {
     },
     verification: {
       enabled: true,
-      satisfaction_threshold: pipeline.satisfaction_threshold,
+      satisfaction_threshold: pipeline2.satisfaction_threshold,
       timeout_minutes: 30,
-      prod_accept_floor: pipeline.prod_accept_floor
+      prod_accept_floor: pipeline2.prod_accept_floor
     },
     review: {
       enabled: humanGates.pr_review !== "disabled",
@@ -2745,8 +2745,8 @@ function generateDaemonConfig(factoryConfig, projectConfig, factoryPath) {
       build_timeout_seconds: 600
     },
     convergence: {
-      max_iterations: pipeline.max_iterations,
-      fail_fast_threshold: pipeline.fail_fast_threshold,
+      max_iterations: pipeline2.max_iterations,
+      fail_fast_threshold: pipeline2.fail_fast_threshold,
       infra_retry_max: 3,
       max_precheck_retries: 2
     },
@@ -4343,7 +4343,7 @@ You are currently scoped to project "${scope}". Focus your answers on this proje
   async function runViaCli(session, content, scope = "factory") {
     session.busy = true;
     try {
-      const { spawn: spawn3 } = await import("child_process");
+      const { spawn: spawn4 } = await import("child_process");
       let boardContext = "";
       try {
         const boardUrl = getBoardUrl(session.factoryPath);
@@ -4435,7 +4435,7 @@ Respond concisely. Continue the conversation naturally.`;
         spawnCmd = "claude";
         spawnArgs = claudeArgs;
       }
-      const child = spawn3(spawnCmd, spawnArgs, {
+      const child = spawn4(spawnCmd, spawnArgs, {
         cwd: session.factoryPath,
         env: {
           ...process.env,
@@ -11401,8 +11401,8 @@ async function runMigrate(opts) {
   }
   let worktreeOutput = "";
   try {
-    const { execSync: execSync11 } = await import("child_process");
-    worktreeOutput = execSync11("git worktree list", {
+    const { execSync: execSync12 } = await import("child_process");
+    worktreeOutput = execSync12("git worktree list", {
       cwd,
       encoding: "utf-8",
       timeout: 5e3
@@ -11575,14 +11575,14 @@ async function runPipeline(projectName, opts) {
   const daemonConfig = generateDaemonConfig(factoryConfig, projectConfig, factoryDir);
   writeFileSync22(daemonConfigPath, JSON.stringify(daemonConfig, null, 2), "utf-8");
   info(`Generated daemon config at: ${daemonConfigPath}`);
-  const { execSync: execSync11 } = await import("child_process");
+  const { execSync: execSync12 } = await import("child_process");
   let pythonAvailable = false;
   try {
-    execSync11("python --version", { timeout: 5e3, encoding: "utf-8" });
+    execSync12("python --version", { timeout: 5e3, encoding: "utf-8" });
     pythonAvailable = true;
   } catch {
     try {
-      execSync11("python3 --version", { timeout: 5e3, encoding: "utf-8" });
+      execSync12("python3 --version", { timeout: 5e3, encoding: "utf-8" });
       pythonAvailable = true;
     } catch {
     }
@@ -11610,8 +11610,8 @@ async function runPipeline(projectName, opts) {
   }
   const cmd = buildDaemonCommand(null, daemonConfigPath);
   info(`Spawning daemon: ${cmd.command} ${cmd.args.join(" ")}`);
-  const { spawn: spawn3 } = await import("child_process");
-  const child = spawn3(cmd.command, cmd.args, {
+  const { spawn: spawn4 } = await import("child_process");
+  const child = spawn4(cmd.command, cmd.args, {
     stdio: "inherit",
     cwd: factoryDir,
     env: {
@@ -11735,16 +11735,16 @@ async function runDaemon(opts) {
     console.log(JSON.stringify(daemonConfig, null, 2));
     return;
   }
-  const { execSync: execSync11 } = await import("child_process");
+  const { execSync: execSync12 } = await import("child_process");
   let pythonCmd = "python";
   let pythonAvailable = false;
   try {
-    execSync11("python --version", { timeout: 5e3, encoding: "utf-8" });
+    execSync12("python --version", { timeout: 5e3, encoding: "utf-8" });
     pythonAvailable = true;
     pythonCmd = "python";
   } catch {
     try {
-      execSync11("python3 --version", { timeout: 5e3, encoding: "utf-8" });
+      execSync12("python3 --version", { timeout: 5e3, encoding: "utf-8" });
       pythonAvailable = true;
       pythonCmd = "python3";
     } catch {
@@ -11762,8 +11762,8 @@ async function runDaemon(opts) {
   info(`Starting daemon: ${pythonCmd} ${cmd.args.join(" ")}`);
   console.log();
   const pidFile = join28(bmDir, "daemon.pid");
-  const { spawn: spawn3 } = await import("child_process");
-  const child = spawn3(pythonCmd, cmd.args, {
+  const { spawn: spawn4 } = await import("child_process");
+  const child = spawn4(pythonCmd, cmd.args, {
     stdio: "inherit",
     cwd: factoryDir,
     env: {
@@ -11783,8 +11783,8 @@ async function runDaemon(opts) {
   const exitCode = await new Promise((resolvePromise) => {
     child.on("exit", (code) => {
       try {
-        const { unlinkSync: unlinkSync6 } = __require("fs");
-        unlinkSync6(pidFile);
+        const { unlinkSync: unlinkSync7 } = __require("fs");
+        unlinkSync7(pidFile);
       } catch {
       }
       resolvePromise(code ?? 1);
@@ -12422,7 +12422,7 @@ var updateCommand = new Command22("update").description("Pull latest BeastMode i
 // src/cli/commands/runner-cmd.ts
 init_display();
 import { Command as Command23 } from "commander";
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { resolve as resolve20 } from "path";
 
 // src/cli/github-runners.ts
@@ -12473,6 +12473,10 @@ async function listRunners(config) {
   const url = runnersUrl(config.owner, config.repo);
   return githubFetch(url, config.token);
 }
+async function deleteRunner(config, runnerId) {
+  const url = `${runnersUrl(config.owner, config.repo)}/${runnerId}`;
+  await githubFetch(url, config.token, "DELETE");
+}
 function resolveGitHubConfig() {
   const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
   if (!token) {
@@ -12493,7 +12497,13 @@ function resolveGitHubConfig() {
 // src/cli/runner-helpers.ts
 import { execSync as execSync10, spawn, spawnSync as spawnSync5 } from "child_process";
 import { promises as fs } from "fs";
+import { join as join31 } from "path";
 init_display();
+async function writeRunnerMeta(dir, meta) {
+  await fs.mkdir(dir, { recursive: true });
+  const path = join31(dir, "runner-meta.json");
+  await fs.writeFile(path, JSON.stringify(meta, null, 2) + "\n", "utf-8");
+}
 function resolveRepoSlug() {
   let rawUrl;
   try {
@@ -12617,6 +12627,20 @@ async function startRunnerContainer(opts) {
     );
   }
 }
+async function removeEnvEntries(keys, envPath = ".env") {
+  let existing = "";
+  try {
+    existing = await fs.readFile(envPath, "utf-8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    return;
+  }
+  const lines = existing.split("\n");
+  const filtered = lines.filter(
+    (line) => !keys.some((key) => line.startsWith(`${key}=`))
+  );
+  await fs.writeFile(envPath, filtered.join("\n"), "utf-8");
+}
 async function writeEnvEntries(entries, envPath = ".env") {
   let existing = "";
   try {
@@ -12669,15 +12693,326 @@ function setupStep(text) {
   info(text);
 }
 
-// src/cli/workflow-switcher.ts
+// src/cli/native-runner.ts
+import {
+  execSync as execSync11,
+  spawn as spawn2,
+  spawnSync as spawnSync6
+} from "child_process";
 import {
+  createWriteStream,
   existsSync as existsSync33,
   mkdirSync as mkdirSync20,
-  readFileSync as readFileSync31,
   unlinkSync as unlinkSync5,
   writeFileSync as writeFileSync27
 } from "fs";
-import { dirname as dirname8, join as join31 } from "path";
+import { homedir as homedir4 } from "os";
+import { join as join32, dirname as dirname8 } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+init_display();
+var RUNNER_VERSION = "2.322.0";
+function detectPlatform() {
+  const platform3 = process.platform;
+  if (platform3 === "win32") {
+    throw new Error(
+      "--native is not supported on Windows. Use Docker or WSL."
+    );
+  }
+  if (platform3 !== "linux" && platform3 !== "darwin") {
+    throw new Error(
+      `--native is not supported on ${platform3}. Use Docker instead.`
+    );
+  }
+  const arch = process.arch;
+  if (arch !== "x64" && arch !== "arm64") {
+    throw new Error(
+      `Unsupported architecture: ${arch}. GitHub runners support x64 and arm64.`
+    );
+  }
+  return { os: platform3, arch };
+}
+function runnerDownloadUrl(os, arch) {
+  const ghOs = os === "darwin" ? "osx" : "linux";
+  return `https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-${ghOs}-${arch}-${RUNNER_VERSION}.tar.gz`;
+}
+async function downloadAndExtractRunner(installDir, os, arch) {
+  const runShPath = join32(installDir, "run.sh");
+  if (existsSync33(runShPath)) {
+    info(
+      `Runner binary already present at ${runShPath} \u2014 skipping download.`
+    );
+    if (os === "darwin") {
+      spawnSync6("xattr", ["-c", "-r", installDir], { stdio: "ignore" });
+    }
+    return;
+  }
+  const url = runnerDownloadUrl(os, arch);
+  const tarball = join32(installDir, "runner.tar.gz");
+  setupStep(
+    `Downloading GitHub Actions runner v${RUNNER_VERSION} (${os}/${arch})...`
+  );
+  const resp = await fetch(url);
+  if (!resp.ok || !resp.body) {
+    throw new Error(
+      `Failed to download runner: HTTP ${resp.status} from ${url}`
+    );
+  }
+  await pipeline(
+    Readable.fromWeb(resp.body),
+    createWriteStream(tarball)
+  );
+  setupStep("Extracting runner...");
+  try {
+    execSync11("tar -xzf runner.tar.gz", { cwd: installDir, stdio: "ignore" });
+  } catch (err) {
+    throw new Error(
+      `Failed to extract runner archive: ${err?.message ?? String(err)}`
+    );
+  }
+  try {
+    unlinkSync5(tarball);
+  } catch {
+  }
+  if (os === "darwin") {
+    setupStep("Removing macOS Gatekeeper quarantine attribute...");
+    warn(
+      "macOS Gatekeeper quarantine: running xattr -c -r on runner binaries."
+    );
+    warn(
+      "This is required because macOS quarantines downloaded executables."
+    );
+    spawnSync6("xattr", ["-c", "-r", installDir], { stdio: "ignore" });
+  }
+}
+async function configureRunner(installDir, repoUrl, token, name, labels) {
+  setupStep("Configuring runner...");
+  const args = [
+    "--url",
+    repoUrl,
+    "--token",
+    token,
+    "--name",
+    name,
+    "--labels",
+    labels.join(","),
+    "--unattended",
+    "--replace"
+  ];
+  const result = spawnSync6(join32(installDir, "config.sh"), args, {
+    cwd: installDir,
+    stdio: ["ignore", "inherit", "pipe"],
+    encoding: "utf-8"
+  });
+  if (result.error && result.error.code === "ENOENT") {
+    throw new Error(
+      `Runner configuration failed: config.sh not found at ${installDir}/config.sh.`
+    );
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").replace(token, "<REDACTED>");
+    throw new Error(
+      `Runner configuration failed (exit ${result.status}): ${stderr}`
+    );
+  }
+}
+function startRunnerForeground(installDir) {
+  setupStep("Starting runner in foreground mode (Ctrl+C to stop)...");
+  info("The runner will stop when this terminal closes.");
+  if (process.platform === "darwin") {
+    warn(
+      "macOS pitfall: if the terminal session disconnects, the runner dies."
+    );
+    warn(
+      "Use --service to install as a launchd agent for persistent operation."
+    );
+  }
+  spawn2(join32(installDir, "run.sh"), [], {
+    cwd: installDir,
+    stdio: "inherit"
+  });
+}
+function systemdUnitContent(installDir, name) {
+  return `[Unit]
+Description=GitHub Actions Runner (${name})
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=${installDir}
+ExecStart=${installDir}/run.sh
+Restart=on-failure
+RestartSec=5
+KillSignal=SIGTERM
+TimeoutStopSec=30
+
+[Install]
+WantedBy=default.target
+`;
+}
+async function installSystemdService(installDir, name) {
+  const unitName = `beastmode-runner-${name}.service`;
+  const unitDir = join32(homedir4(), ".config", "systemd", "user");
+  mkdirSync20(unitDir, { recursive: true });
+  writeFileSync27(
+    join32(unitDir, unitName),
+    systemdUnitContent(installDir, name),
+    "utf-8"
+  );
+  try {
+    execSync11("systemctl --user daemon-reload", { stdio: "inherit" });
+    execSync11(`systemctl --user enable --now ${unitName}`, {
+      stdio: "inherit"
+    });
+  } catch (err) {
+    throw new Error(
+      `systemd user-service install failed: ${err?.message ?? String(err)}. Ensure systemd --user is available (some minimal Linux containers don't ship it).`
+    );
+  }
+  success(`Installed and started systemd user service: ${unitName}`);
+  info(`  Check status: systemctl --user status ${unitName}`);
+  info(`  View logs:    journalctl --user -u ${unitName} -f`);
+}
+function launchdPlistContent(installDir, name) {
+  const label = `com.beastmode.runner.${name}`;
+  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>${label}</string>
+  <key>WorkingDirectory</key>
+  <string>${installDir}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${installDir}/run.sh</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${installDir}/logs/stdout.log</string>
+  <key>StandardErrorPath</key>
+  <string>${installDir}/logs/stderr.log</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+async function installLaunchdService(installDir, name) {
+  const label = `com.beastmode.runner.${name}`;
+  const plistPath2 = join32(
+    homedir4(),
+    "Library",
+    "LaunchAgents",
+    `${label}.plist`
+  );
+  mkdirSync20(dirname8(plistPath2), { recursive: true });
+  mkdirSync20(join32(installDir, "logs"), { recursive: true });
+  writeFileSync27(plistPath2, launchdPlistContent(installDir, name), "utf-8");
+  try {
+    execSync11(`launchctl load ${plistPath2}`, { stdio: "inherit" });
+  } catch (err) {
+    throw new Error(
+      `launchd agent install failed: ${err?.message ?? String(err)}.`
+    );
+  }
+  success(`Installed and loaded launchd agent: ${label}`);
+  info(`  Check status: launchctl list | grep ${label}`);
+  info(`  View logs:    tail -f ${installDir}/logs/stdout.log`);
+  warn("macOS pitfall: launchd agents only run while the user is logged in.");
+  warn(
+    "If you reboot without auto-login, the runner won't start until you log in."
+  );
+  warn("For headless servers, use a LaunchDaemon (requires root) instead.");
+}
+async function installRunnerService(installDir, name, os) {
+  if (os === "linux") {
+    await installSystemdService(installDir, name);
+  } else {
+    await installLaunchdService(installDir, name);
+  }
+}
+async function nativeRunnerSetup(opts) {
+  if (opts.service !== void 0 && !opts.native) {
+    throw new Error(
+      "--service requires --native. The Docker runner always runs as a container service."
+    );
+  }
+  const { os: platformOs, arch } = detectPlatform();
+  if (platformOs === "darwin") {
+    header("Native Runner Setup (macOS)");
+    warn(
+      "macOS has several pitfalls for self-hosted runners. Read the warnings below carefully."
+    );
+  } else {
+    header("Native Runner Setup (Linux)");
+  }
+  const ghConfig = resolveGitHubConfig();
+  const repoSlug = opts.repo ?? resolveRepoSlug();
+  const installDir = join32(homedir4(), ".beastmode", "runners", opts.name);
+  if (opts.dryRun) {
+    info(
+      `[dry-run] Would install native runner '${opts.name}' for repo ${repoSlug}`
+    );
+    info(`[dry-run] Platform: ${platformOs}/${arch}`);
+    info(`[dry-run] Install dir: ${installDir}`);
+    info(`[dry-run] Mode: ${opts.service ? "service" : "foreground"}`);
+    return;
+  }
+  mkdirSync20(installDir, { recursive: true });
+  setupStep("Generating registration token via GitHub API...");
+  const { token: regToken } = await createRegistrationToken(ghConfig);
+  await downloadAndExtractRunner(installDir, platformOs, arch);
+  const repoUrl = `https://github.com/${ghConfig.owner}/${ghConfig.repo}`;
+  await configureRunner(installDir, repoUrl, regToken, opts.name, [
+    "self-hosted",
+    opts.label
+  ]);
+  await writeEnvEntries({
+    RUNNER_REPO_URL: repoUrl,
+    RUNNER_TOKEN: regToken,
+    RUNNER_NAME: opts.name,
+    RUNNER_MODE: "native"
+  });
+  await writeRunnerMeta(installDir, {
+    name: opts.name,
+    mode: "native",
+    platform: platformOs,
+    arch,
+    installDir,
+    service: opts.service ?? false,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  if (opts.service) {
+    await installRunnerService(installDir, opts.name, platformOs);
+  } else {
+    startRunnerForeground(installDir);
+  }
+  setupStep("Waiting for runner to appear online on GitHub (timeout 60s)...");
+  await pollUntilOnline(ghConfig, opts.name, 6e4);
+  success(
+    `Runner '${opts.name}' registered and online (native/${platformOs}).`
+  );
+}
+
+// src/cli/workflow-switcher.ts
+import {
+  existsSync as existsSync34,
+  mkdirSync as mkdirSync21,
+  readFileSync as readFileSync31,
+  unlinkSync as unlinkSync6,
+  writeFileSync as writeFileSync28
+} from "fs";
+import { dirname as dirname9, join as join33 } from "path";
 var TARGET_LABEL = "[self-hosted, beastmode]";
 var TARGET_WORKFLOWS = [
   ".github/workflows/test.yml",
@@ -12716,8 +13051,8 @@ function restoreRunsOn(content, originals) {
   return newLines.join("\n");
 }
 async function switchWorkflows(projectDir) {
-  const statePath = join31(projectDir, STATE_FILE);
-  if (existsSync33(statePath)) {
+  const statePath = join33(projectDir, STATE_FILE);
+  if (existsSync34(statePath)) {
     return { alreadySwitched: true, files: [] };
   }
   const state = {
@@ -12727,8 +13062,8 @@ async function switchWorkflows(projectDir) {
   };
   const resultFiles = [];
   for (const relPath of TARGET_WORKFLOWS) {
-    const absPath = join31(projectDir, relPath);
-    if (!existsSync33(absPath)) {
+    const absPath = join33(projectDir, relPath);
+    if (!existsSync34(absPath)) {
       throw new Error(`Workflow file not found: ${relPath}`);
     }
     const content = readFileSync31(absPath, "utf-8");
@@ -12736,17 +13071,17 @@ async function switchWorkflows(projectDir) {
     if (originals.length === 0) {
       throw new Error(`No runs-on found in ${relPath}`);
     }
-    writeFileSync27(absPath, newContent, "utf-8");
+    writeFileSync28(absPath, newContent, "utf-8");
     state.files.push({ relativePath: relPath, originals });
     resultFiles.push({ relativePath: relPath, jobCount: originals.length });
   }
-  mkdirSync20(dirname8(statePath), { recursive: true });
-  writeFileSync27(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+  mkdirSync21(dirname9(statePath), { recursive: true });
+  writeFileSync28(statePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
   return { alreadySwitched: false, files: resultFiles };
 }
 async function restoreWorkflows(projectDir) {
-  const statePath = join31(projectDir, STATE_FILE);
-  if (!existsSync33(statePath)) {
+  const statePath = join33(projectDir, STATE_FILE);
+  if (!existsSync34(statePath)) {
     return { nothingToRestore: true, files: [] };
   }
   const state = JSON.parse(
@@ -12754,27 +13089,32 @@ async function restoreWorkflows(projectDir) {
   );
   const resultFiles = [];
   for (const fileState of state.files) {
-    const absPath = join31(projectDir, fileState.relativePath);
-    if (!existsSync33(absPath)) {
+    const absPath = join33(projectDir, fileState.relativePath);
+    if (!existsSync34(absPath)) {
       throw new Error(`Workflow file not found: ${fileState.relativePath}`);
     }
     const content = readFileSync31(absPath, "utf-8");
     const newContent = restoreRunsOn(content, fileState.originals);
-    writeFileSync27(absPath, newContent, "utf-8");
+    writeFileSync28(absPath, newContent, "utf-8");
     resultFiles.push({
       relativePath: fileState.relativePath,
       jobCount: fileState.originals.length
     });
   }
-  unlinkSync5(statePath);
+  unlinkSync6(statePath);
   return { nothingToRestore: false, files: resultFiles };
 }
 
 // src/cli/commands/runner-cmd.ts
 var runnerCommand = new Command23("runner").description("Manage self-hosted GitHub Actions runners");
 async function runnerSetupAction(opts) {
+  if (opts.service !== void 0 && !opts.native) {
+    throw new Error(
+      "--service requires --native. The Docker runner always runs as a container service."
+    );
+  }
   if (opts.native) {
-    warn("--native is not implemented yet (Story 5)");
+    await nativeRunnerSetup(opts);
     return;
   }
   const ghConfig = resolveGitHubConfig();
@@ -12815,11 +13155,19 @@ async function runnerSetupAction(opts) {
   await pollUntilOnline(ghConfig, opts.name, 6e4);
   setupStep("Adding runner to docker-compose...");
   await composeUpRunner();
+  await writeRunnerMeta(".beastmode", {
+    name: opts.name,
+    mode: "docker",
+    platform: process.platform,
+    arch: process.arch,
+    service: true,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
   success(`Runner '${opts.name}' registered and online.`);
 }
 async function composeUpRunner() {
   await new Promise((resolve21, reject) => {
-    const child = spawn2(
+    const child = spawn3(
       "docker",
       ["compose", "--profile", "runner", "up", "-d", "runner"],
       { stdio: ["ignore", "inherit", "inherit"] }
@@ -12836,14 +13184,160 @@ async function composeUpRunner() {
     });
   });
 }
-runnerCommand.command("setup").description("Set up a self-hosted GitHub Actions runner").option("--repo <owner/repo>", "GitHub repo for runner registration").option("--name <name>", "Container + runner name", "beastmode-runner").option("--label <label>", "Additional runner label", "beastmode").option("--dry-run", "Print what would happen without mutating state").option("--native", "Use native install instead of Docker").action(async (opts) => {
-  await runnerSetupAction(opts);
+runnerCommand.command("setup").description("Set up a self-hosted GitHub Actions runner").option("--repo <owner/repo>", "GitHub repo for runner registration").option("--name <name>", "Container + runner name", "beastmode-runner").option("--label <label>", "Additional runner label", "beastmode").option("--dry-run", "Print what would happen without mutating state").option(
+  "--native",
+  "Use native runner binary instead of Docker (downloads actions/runner)"
+).option(
+  "--service",
+  "Install as background service (systemd/launchd). Requires --native."
+).action(async (opts) => {
+  try {
+    await runnerSetupAction(opts);
+  } catch (err) {
+    error(err?.message ? String(err.message) : String(err));
+    process.exitCode = 1;
+  }
 });
-runnerCommand.command("status").description("Show runner status (container + GitHub registration)").action(() => {
-  warn("runner status is not implemented yet (Story 3)");
+async function runnerStatusAction(opts) {
+  const container = await findContainerByName(opts.name);
+  const containerStatus = container ? container.status : null;
+  let ghRunner = null;
+  let ghError = null;
+  try {
+    const ghConfig = resolveGitHubConfig();
+    const list = await listRunners(ghConfig);
+    ghRunner = list.runners.find((r) => r.name === opts.name) ?? null;
+  } catch (err) {
+    ghError = err?.message ? String(err.message) : String(err);
+  }
+  if (opts.json) {
+    const result = {
+      name: opts.name,
+      container: { found: !!container, status: containerStatus }
+    };
+    if (ghRunner) {
+      result.github = {
+        registered: true,
+        id: ghRunner.id,
+        status: ghRunner.status,
+        busy: ghRunner.busy,
+        os: ghRunner.os,
+        labels: ghRunner.labels.map((l) => l.name)
+      };
+    } else if (ghError) {
+      result.github = { registered: null, error: ghError };
+    } else {
+      result.github = {
+        registered: false,
+        id: null,
+        status: null,
+        busy: null,
+        os: null,
+        labels: []
+      };
+    }
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  header(`Runner Status: ${opts.name}`);
+  if (container && containerIsHealthy(container)) {
+    success(`Container: ${container.status}`);
+  } else if (container) {
+    error(`Container: ${container.status}`);
+  } else {
+    error("Container: not found");
+  }
+  if (ghRunner) {
+    const busySuffix = ghRunner.busy ? " \u2014 busy" : "";
+    if (ghRunner.status === "online") {
+      success(`GitHub: online (id: ${ghRunner.id})${busySuffix}`);
+    } else {
+      warn(`GitHub: ${ghRunner.status} (id: ${ghRunner.id})${busySuffix}`);
+    }
+    info(`Labels: ${ghRunner.labels.map((l) => l.name).join(", ")}`);
+    info(`OS: ${ghRunner.os}`);
+    info(`Busy: ${ghRunner.busy ? "yes" : "no"}`);
+  } else if (ghError) {
+    warn(`GitHub: could not reach API (${ghError})`);
+  } else {
+    error("GitHub: not registered");
+  }
+}
+async function runnerRemoveAction(opts) {
+  header(`Removing runner: ${opts.name}`);
+  let ghDeregistrationFailed = false;
+  let ghWarning = null;
+  try {
+    const ghConfig = resolveGitHubConfig();
+    const list = await listRunners(ghConfig);
+    const runner = list.runners.find((r) => r.name === opts.name);
+    if (!runner) {
+      ghWarning = "not registered (nothing to deregister)";
+    } else {
+      if (runner.busy && !opts.force) {
+        warn(`Runner '${opts.name}' is currently busy (running a job).`);
+        info("Use --force to remove anyway.");
+        return;
+      }
+      try {
+        await deleteRunner(ghConfig, runner.id);
+        success(`Deregistered from GitHub (runner id: ${runner.id})`);
+      } catch (err) {
+        ghDeregistrationFailed = true;
+        ghWarning = `deregistration failed: ${err?.message ?? String(err)}`;
+      }
+    }
+  } catch (err) {
+    ghDeregistrationFailed = true;
+    ghWarning = err?.message ? String(err.message) : String(err);
+  }
+  if (ghWarning) {
+    warn(`GitHub: ${ghWarning}`);
+  }
+  let containerWarning = null;
+  try {
+    const container = await findContainerByName(opts.name);
+    if (!container) {
+      containerWarning = "not found (nothing to remove)";
+    } else {
+      try {
+        await removeContainer(opts.name);
+        success("Container removed");
+      } catch (err) {
+        containerWarning = err?.message ? String(err.message) : String(err);
+      }
+    }
+  } catch (err) {
+    containerWarning = err?.message ? String(err.message) : String(err);
+  }
+  if (containerWarning) {
+    warn(`Container: ${containerWarning}`);
+  }
+  await removeEnvEntries(["RUNNER_REPO_URL", "RUNNER_TOKEN", "RUNNER_NAME"]);
+  success(".env entries cleaned (RUNNER_REPO_URL, RUNNER_TOKEN, RUNNER_NAME)");
+  if (ghDeregistrationFailed) {
+    warn(
+      `Runner '${opts.name}' partially removed (GitHub deregistration failed).`
+    );
+  } else {
+    success(`Runner '${opts.name}' fully removed.`);
+  }
+}
+runnerCommand.command("status").description("Show runner status (container + GitHub registration)").option("--name <name>", "Container + runner name", "beastmode-runner").option("--json", "Output machine-readable JSON").action(async (opts) => {
+  try {
+    await runnerStatusAction(opts);
+  } catch (err) {
+    error(err.message);
+    process.exitCode = 1;
+  }
 });
-runnerCommand.command("remove").description("Remove the runner (container + GitHub deregistration)").action(() => {
-  warn("runner remove is not implemented yet (Story 3)");
+runnerCommand.command("remove").description("Remove the runner (container + GitHub deregistration)").option("--name <name>", "Container + runner name", "beastmode-runner").option("--force", "Remove even if the runner is busy").action(async (opts) => {
+  try {
+    await runnerRemoveAction(opts);
+  } catch (err) {
+    error(err.message);
+    process.exitCode = 1;
+  }
 });
 runnerCommand.command("switch-workflows").description("Switch workflow runs-on to self-hosted runner").option("--project-dir <path>", "Project root directory", process.cwd()).action(async (opts) => {
   const projectDir = resolve20(opts.projectDir);