premanmcp 0.9.0 → 0.10.0

package/bin/runner.js

@@ -0,0 +1,880 @@
+/**
+ * `preman runner` — execute PreMan's queued coding-agent jobs on this machine.
+ *
+ * The backend has had a complete local-runner protocol for a while
+ * (`docs/LOCAL_AGENT_RUNNER.md`): pair once, hold an outbound SSE stream, get
+ * leased jobs, report started/progress/complete under a fencing token. Only the
+ * desktop app spoke it, which meant a terminal-first user could be fully
+ * connected and still have PreMan unable to *do* anything — every fix was a
+ * suggestion waiting for someone to paste it into an agent.
+ *
+ * This is the same protocol from the CLI, so `preman connect` can leave behind a
+ * machine that runs work instead of one that only reports it. The desktop app
+ * stays a valid second runner; the server picks whichever device is online.
+ *
+ * Non-negotiables carried over from the desktop implementation:
+ *   - The stream is outbound. No inbound port, tunnel, or editor plugin.
+ *   - A job is refused if its agent or project path is not the one this runner
+ *     paired with. The server chooses the path; a queued job cannot widen it.
+ *   - Process exit never resolves a job. Only a completion callback holding the
+ *     current lease does.
+ *   - The runner token is separate from the pm_live_ key, stored 0600, and never
+ *     placed in a child process's environment.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  CREDENTIALS_DIR,
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  makeArgs,
+  resolveApiKey,
+} from "./shared.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const RUNNER_STATE_FILE = path.join(CREDENTIALS_DIR, "runner.json");
+export const RUNNER_PID_FILE = path.join(CREDENTIALS_DIR, "runner.pid");
+export const RUNNER_LOG_FILE = path.join(CREDENTIALS_DIR, "runner.log");
+
+// Matches docs/LOCAL_AGENT_RUNNER.md — the backend's TTLs are the contract, not
+// a preference. Runner online TTL is 45s, unstarted lease 60s, running lease a
+// renewable 90s, so heartbeat and renewal both have to beat those windows.
+const HEARTBEAT_MS = 20_000;
+const LEASE_RENEW_MS = 45_000;
+const PROGRESS_MS = 20_000;
+const RECONNECT_MIN_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+const AGENT_TIMEOUT_MS = Number(process.env.PREMAN_RUNNER_TIMEOUT_MS) || 30 * 60_000;
+const AGENT_TIMEOUT_CAP_MS = 60 * 60_000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const SUMMARY_CAP = 20_000;
+const ERROR_CAP = 4_000;
+
+/**
+ * What this runner promises the job matcher.
+ *
+ * `find_online_runner` filters on these keys, so a runner that does not advertise
+ * the telemetry and manifest capabilities is skipped with `runner_update_required`
+ * — it is not a hint, it is the routing condition.
+ */
+export const RUNNER_CAPABILITIES = {
+  tool_call_telemetry_v1: true,
+  tool_fact_manifest_v1: true,
+  transport: "cli",
+  client: "premanmcp",
+};
+
+export class RunnerError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+const AGENT_IDS = new Set(["claude_code", "cursor", "codex"]);
+
+export function normalizeAgentId(value) {
+  const raw = String(value || "").trim().toLowerCase().replace(/[\s-]+/g, "_");
+  if (raw === "claude" || raw === "claudecode") return "claude_code";
+  if (raw === "openai_codex") return "codex";
+  return AGENT_IDS.has(raw) ? raw : "";
+}
+
+// ── Local state ─────────────────────────────────────────────────────────
+
+function ensureDir() {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+}
+
+export function readRunnerState() {
+  try {
+    const raw = readFileSync(RUNNER_STATE_FILE, "utf8").trim();
+    if (!raw) return null;
+    const state = JSON.parse(raw);
+    return state && typeof state.runner_token === "string" ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveRunnerState(state) {
+  ensureDir();
+  writeFileSync(RUNNER_STATE_FILE, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(RUNNER_STATE_FILE, 0o600);
+  return state;
+}
+
+export function clearRunnerState() {
+  rmSync(RUNNER_STATE_FILE, { force: true });
+}
+
+/**
+ * A device identity that survives restarts but not a different project.
+ *
+ * Registration replaces the previous runner with the same device_id, so reusing
+ * one per (host, project) keeps repeated `preman connect` runs from piling up
+ * dead runner rows the matcher still has to walk.
+ */
+export function deviceId(projectPath) {
+  const seed = `${os.hostname()}::${path.resolve(projectPath)}`;
+  return `cli-${createHash("sha256").update(seed).digest("hex").slice(0, 32)}`;
+}
+
+export function packageVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+    return String(pkg.version || "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function readPid() {
+  try {
+    const pid = Number(readFileSync(RUNNER_PID_FILE, "utf8").trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function runnerIsAlive(pid = readPid()) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Registration ────────────────────────────────────────────────────────
+
+/**
+ * Pair and register, returning the saved runner state.
+ *
+ * The pair code is single-use and shared with the MCP check-in path, so this
+ * mints its own rather than reusing whatever `connect` put in the agent's config
+ * — that one is spent the moment the agent calls `preman_status`.
+ */
+export async function registerRunner(args, { agent, projectPath, label = "", apiKey = "" } = {}) {
+  const agentId = normalizeAgentId(agent);
+  if (!agentId) throw new RunnerError(`unknown agent: ${agent}`, 2);
+  const token = apiKey || resolveApiKey(args);
+  if (!token) {
+    throw new RunnerError(`No PreMan credentials. Run '${cliInvocation()} connect' first.`, 2);
+  }
+  const project = path.resolve(projectPath || process.cwd());
+
+  const pairing = await callBackendJson(args, "PUT", "/workbench/coding-agent", {
+    token,
+    json: { agent: agentId, project_path: project, start_pairing: true },
+  });
+  if (!pairing.ok) {
+    throw new RunnerError(
+      `could not start pairing (${pairing.status_code} ${pairing.detail || ""})`.trim()
+    );
+  }
+  const pairCode = String(pairing.pair_code || "");
+  if (!pairCode) throw new RunnerError("PreMan did not return a pair code");
+
+  const registered = await callBackendJson(
+    args,
+    "POST",
+    "/workbench/coding-agent/local-runners/register",
+    {
+      json: {
+        pair_code: pairCode,
+        device_id: deviceId(project),
+        label: label || `${os.hostname()} (${path.basename(project)})`,
+        agent: agentId,
+        project_path: project,
+        project_name: path.basename(project),
+        platform: `${process.platform}-${process.arch}`,
+        app_version: packageVersion(),
+        capabilities: RUNNER_CAPABILITIES,
+      },
+    }
+  );
+  if (!registered.ok) {
+    throw new RunnerError(
+      `could not register the runner (${registered.status_code} ${registered.detail || ""})`.trim()
+    );
+  }
+
+  return saveRunnerState({
+    runner_id: String(registered.runner?.id || ""),
+    runner_token: String(registered.runner_token || ""),
+    agent: agentId,
+    project_path: project,
+    project_name: path.basename(project),
+    backend_url: backendUrl(args),
+    device_id: deviceId(project),
+    workspace_id: String(registered.runner?.workspace_id || ""),
+    registered_at: new Date().toISOString(),
+  });
+}
+
+// ── Agent invocation ────────────────────────────────────────────────────
+
+/**
+ * How to run one job with each agent, non-interactively.
+ *
+ * Permissions are the only interesting choice here. A fix task exists to change
+ * files, so edits are accepted; everything beyond that stays behind
+ * `PREMAN_RUNNER_FULL_ACCESS=1`, because "PreMan can run arbitrary commands on my
+ * laptop unattended" has to be a decision someone made on purpose.
+ */
+export function agentCommand(agent, prompt, { fullAccess = false } = {}) {
+  if (agent === "claude_code") {
+    const args = ["-p", prompt, "--output-format", "stream-json", "--verbose"];
+    if (fullAccess) args.push("--dangerously-skip-permissions");
+    else args.push("--permission-mode", "acceptEdits");
+    return { bin: "claude", args, stream: "claude-json" };
+  }
+  if (agent === "cursor") {
+    return { bin: "cursor-agent", args: ["-p", prompt], stream: "text" };
+  }
+  if (agent === "codex") {
+    const args = ["exec"];
+    if (fullAccess) args.push("--full-auto");
+    args.push(prompt);
+    return { bin: "codex", args, stream: "text" };
+  }
+  return null;
+}
+
+export function onPath(binary) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [binary], {
+    stdio: "ignore",
+  });
+  return probe.status === 0;
+}
+
+function sanitizeId(value, cap) {
+  return String(value || "")
+    .replace(/[^A-Za-z0-9_.:-]/g, "_")
+    .slice(0, cap);
+}
+
+/**
+ * Collect the attempt's tool identities from Claude Code's stream-json output.
+ *
+ * The completion manifest is what the backend meters, and it must be the unique
+ * set for this attempt — including identities already acknowledged mid-run — so
+ * this keys by tool_use id and upgrades a `started` to `completed` rather than
+ * emitting the same identity twice.
+ */
+export function createToolEventCollector() {
+  const events = new Map();
+  let sessionId = "";
+
+  function note(id, name, phase) {
+    const eventId = sanitizeId(id, 500);
+    if (!eventId) return;
+    const existing = events.get(eventId);
+    if (existing) {
+      if (phase === "completed") existing.phase = "completed";
+      if (name && !existing.tool_name) existing.tool_name = sanitizeId(name, 100);
+      return;
+    }
+    const event = { event_id: eventId, phase };
+    const toolName = sanitizeId(name, 100);
+    if (toolName) event.tool_name = toolName;
+    events.set(eventId, event);
+  }
+
+  return {
+    ingestLine(line) {
+      const trimmed = String(line || "").trim();
+      if (!trimmed.startsWith("{")) return;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        return;
+      }
+      if (!sessionId && typeof parsed.session_id === "string") sessionId = parsed.session_id;
+      const content = parsed?.message?.content;
+      if (!Array.isArray(content)) return;
+      for (const block of content) {
+        if (block?.type === "tool_use") note(block.id, block.name, "started");
+        else if (block?.type === "tool_result") note(block.tool_use_id, "", "completed");
+      }
+    },
+    manifest() {
+      return [...events.values()];
+    },
+    count() {
+      return events.size;
+    },
+    sessionId() {
+      return sessionId;
+    },
+  };
+}
+
+/** Frame `text/event-stream` bytes into (event, data) pairs. */
+export function createSseParser(onEvent) {
+  let buffer = "";
+  return function push(chunk) {
+    buffer += chunk;
+    let boundary = buffer.indexOf("\n\n");
+    while (boundary !== -1) {
+      const frame = buffer.slice(0, boundary);
+      buffer = buffer.slice(boundary + 2);
+      let event = "message";
+      const data = [];
+      for (const line of frame.split("\n")) {
+        if (line.startsWith("event:")) event = line.slice(6).trim();
+        else if (line.startsWith("data:")) data.push(line.slice(5).trim());
+      }
+      if (data.length) {
+        let payload;
+        try {
+          payload = JSON.parse(data.join("\n"));
+        } catch {
+          payload = { raw: data.join("\n") };
+        }
+        onEvent(event, payload);
+      }
+      boundary = buffer.indexOf("\n\n");
+    }
+  };
+}
+
+/**
+ * Why this runner must not touch a job.
+ *
+ * Empty string means "run it". The server picked the path at pairing time; a job
+ * naming a different one is either stale or an attempt to widen filesystem
+ * access, and both get the same answer.
+ */
+export function jobRefusal(state, job) {
+  const jobAgent = normalizeAgentId(job?.agent);
+  if (jobAgent && jobAgent !== state.agent) {
+    return `job targets ${jobAgent}, this runner is registered for ${state.agent}`;
+  }
+  const wanted = job?.payload?.project_path;
+  if (wanted && path.resolve(String(wanted)) !== path.resolve(state.project_path)) {
+    return `job targets ${wanted}, this runner is registered for ${state.project_path}`;
+  }
+  if (!String(job?.prompt || "").trim()) return "job carries no prompt";
+  return "";
+}
+
+function currentBranch(cwd) {
+  const probe = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const branch = probe.status === 0 ? probe.stdout.trim() : "";
+  return branch && branch !== "HEAD" ? branch.slice(0, 500) : "";
+}
+
+/**
+ * The child's environment: inherited minus our own secrets.
+ *
+ * The runner token and the pm_live_ key both authorize far more than a coding
+ * agent needs, and an agent that can read them can leak them into a commit.
+ */
+function childEnv() {
+  const env = { ...process.env };
+  for (const key of ["PREMAN_API_KEY", "PREMAN_RUNNER_TOKEN", "PREMAN_PAIR_CODE"]) {
+    delete env[key];
+  }
+  return env;
+}
+
+// ── Job execution ───────────────────────────────────────────────────────
+
+function nowMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+
+/** POST a runner callback. Never throws — a lost callback is retried or fenced. */
+async function callback(args, state, route, body, log) {
+  try {
+    const result = await callBackendJson(args, "POST", route, {
+      token: state.runner_token,
+      json: body,
+    });
+    if (!result.ok) log(`callback ${route} -> ${result.status_code} ${result.detail || ""}`);
+    return result;
+  } catch (error) {
+    log(`callback ${route} failed: ${error.message}`);
+    return { ok: false, status_code: 0 };
+  }
+}
+
+export async function executeJob(args, state, job, { log = () => {}, fullAccess = false } = {}) {
+  const lease = String(job.lease_token || "");
+  const jobRoute = `/workbench/coding-agent/local-runner/jobs/${job.id}`;
+  if (!lease) {
+    log(`job ${job.id} arrived without a lease token; ignoring`);
+    return { ok: false, reason: "no_lease" };
+  }
+
+  const refusal = jobRefusal(state, job);
+  if (refusal) {
+    log(`refusing job ${job.id}: ${refusal}`);
+    await callback(
+      args,
+      state,
+      `${jobRoute}/complete`,
+      {
+        lease_token: lease,
+        ok: false,
+        error: refusal.slice(0, ERROR_CAP),
+        attempt_count: Math.max(1, Number(job.attempt_count) || 1),
+        tool_events: [],
+        tool_call_count: 0,
+        metadata: { transport: "cli", refused: true },
+      },
+      log
+    );
+    return { ok: false, reason: "refused" };
+  }
+
+  const spec = agentCommand(state.agent, String(job.prompt), { fullAccess });
+  if (!spec || !onPath(spec.bin)) {
+    const detail = `${spec ? spec.bin : state.agent} is not installed on this machine`;
+    log(`cannot run job ${job.id}: ${detail}`);
+    await callback(
+      args,
+      state,
+      `${jobRoute}/complete`,
+      {
+        lease_token: lease,
+        ok: false,
+        error: detail,
+        attempt_count: Math.max(1, Number(job.attempt_count) || 1),
+        tool_events: [],
+        tool_call_count: 0,
+        metadata: { transport: "cli", agent_missing: true },
+      },
+      log
+    );
+    return { ok: false, reason: "agent_missing" };
+  }
+
+  const started = await callback(args, state, `${jobRoute}/started`, { lease_token: lease }, log);
+  if (!started.ok) return { ok: false, reason: "not_leased" };
+  // The server increments the attempt on `started`, and the manifest is scoped to
+  // that attempt, so its number has to come from the response we just got.
+  const attemptCount = Math.max(1, Number(started.job?.attempt_count) || Number(job.attempt_count) || 1);
+
+  const collector = createToolEventCollector();
+  const timeoutMs = Math.min(AGENT_TIMEOUT_MS, AGENT_TIMEOUT_CAP_MS);
+  const t0 = nowMs();
+  let bytes = 0;
+  let truncated = false;
+  const chunks = [];
+  let pending = "";
+
+  const child = spawn(spec.bin, spec.args, {
+    cwd: state.project_path,
+    env: childEnv(),
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  function absorb(text) {
+    if (bytes < MAX_OUTPUT_BYTES) {
+      const room = MAX_OUTPUT_BYTES - bytes;
+      const slice = text.length > room ? text.slice(0, room) : text;
+      chunks.push(slice);
+      bytes += slice.length;
+      if (slice.length < text.length) truncated = true;
+    } else {
+      truncated = true;
+    }
+    if (spec.stream !== "claude-json") return;
+    pending += text;
+    let newline = pending.indexOf("\n");
+    while (newline !== -1) {
+      collector.ingestLine(pending.slice(0, newline));
+      pending = pending.slice(newline + 1);
+      newline = pending.indexOf("\n");
+    }
+  }
+
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", absorb);
+  child.stderr?.on("data", absorb);
+
+  const renew = setInterval(() => {
+    callback(args, state, `${jobRoute}/lease`, { lease_token: lease }, log);
+  }, LEASE_RENEW_MS);
+  const progress = setInterval(() => {
+    callback(
+      args,
+      state,
+      `${jobRoute}/progress`,
+      {
+        lease_token: lease,
+        stage: "running",
+        message: `${spec.bin} running for ${Math.round((nowMs() - t0) / 1000)}s`,
+        activity: [
+          {
+            id: "agent",
+            label: `${spec.bin} (${collector.count()} tool calls)`.slice(0, 160),
+            state: "active",
+            elapsed_ms: nowMs() - t0,
+          },
+        ],
+      },
+      log
+    );
+  }, PROGRESS_MS);
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    setTimeout(() => child.kill("SIGKILL"), 5_000).unref?.();
+  }, timeoutMs);
+
+  const exit = await new Promise((resolve) => {
+    child.on("error", (error) => resolve({ code: null, error }));
+    child.on("close", (code, signal) => resolve({ code, signal }));
+  });
+
+  clearInterval(renew);
+  clearInterval(progress);
+  clearTimeout(timer);
+  if (pending) collector.ingestLine(pending);
+
+  const output = chunks.join("");
+  const ok = !timedOut && !exit.error && exit.code === 0;
+  const summary = output.slice(-SUMMARY_CAP) || undefined;
+  const error = ok
+    ? undefined
+    : (timedOut
+        ? `agent timed out after ${Math.round(timeoutMs / 1000)}s`
+        : exit.error
+          ? exit.error.message
+          : `${spec.bin} exited with code ${exit.code}${exit.signal ? ` (${exit.signal})` : ""}`
+      ).slice(0, ERROR_CAP);
+
+  const sessionId = collector.sessionId();
+  const complete = await callback(
+    args,
+    state,
+    `${jobRoute}/complete`,
+    {
+      lease_token: lease,
+      ok,
+      summary,
+      error,
+      exit_code: typeof exit.code === "number" ? exit.code : undefined,
+      branch: currentBranch(state.project_path) || undefined,
+      agent_session_id: sessionId || undefined,
+      attempt_count: attemptCount,
+      tool_events: collector.manifest(),
+      tool_call_count: collector.count(),
+      metadata: {
+        transport: "cli",
+        agent_bin: spec.bin,
+        duration_ms: nowMs() - t0,
+        output_truncated: truncated,
+      },
+    },
+    log
+  );
+
+  log(`job ${job.id} ${ok ? "completed" : "failed"} in ${Math.round((nowMs() - t0) / 1000)}s`);
+  return { ok, delivered: complete.ok, reason: ok ? "" : error };
+}
+
+// ── Event loop ──────────────────────────────────────────────────────────
+
+function defaultLog(message) {
+  process.stdout.write(`[preman runner] ${new Date().toISOString()} ${message}\n`);
+}
+
+/**
+ * Hold the stream and run what it leases, until stopped.
+ *
+ * `once` and `stopWhen` are how a bounded run ends; a real one ends on a signal.
+ * Every terminal SSE reason has its own handling because they mean different
+ * things: `replaced` and `revoked` must not reconnect, `reconnect` must.
+ */
+export async function runnerLoop(
+  args,
+  state,
+  { log = defaultLog, once = false, stopWhen = null, fullAccess = false } = {}
+) {
+  let stopped = false;
+  let busy = false;
+  let jobsRun = 0;
+  let backoff = RECONNECT_MIN_MS;
+  const eventsUrl = new URL(
+    "workbench/coding-agent/local-runner/events",
+    `${state.backend_url || backendUrl(args)}/`
+  );
+
+  const heartbeat = setInterval(async () => {
+    // Reported honestly because the matcher prefers idle runners: a busy device
+    // claiming to be idle wins work it will only sit on until the lease expires.
+    const result = await callBackendJson(args, "POST", "/workbench/coding-agent/local-runner/heartbeat", {
+      token: state.runner_token,
+      json: { state: busy ? "busy" : "idle" },
+    });
+    if (result.status_code === 401) {
+      log("runner registration is no longer active; stopping");
+      stopped = true;
+    }
+  }, HEARTBEAT_MS);
+
+  try {
+    while (!stopped && !(stopWhen && stopWhen())) {
+      let response;
+      try {
+        response = await fetch(eventsUrl, {
+          headers: { Authorization: `Bearer ${state.runner_token}`, Accept: "text/event-stream" },
+        });
+      } catch (error) {
+        log(`stream failed: ${error.message}; retrying in ${Math.round(backoff / 1000)}s`);
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+        continue;
+      }
+
+      if (response.status === 401) {
+        log("runner token was revoked; re-pair with `preman runner register`");
+        clearRunnerState();
+        return { stopped: true, jobsRun, reason: "revoked" };
+      }
+      if (!response.ok || !response.body) {
+        log(`stream answered ${response.status}; retrying in ${Math.round(backoff / 1000)}s`);
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+        continue;
+      }
+
+      backoff = RECONNECT_MIN_MS;
+      const queue = [];
+      let terminal = "";
+      const push = createSseParser((event, data) => {
+        if (event === "connected") log(`connected as runner ${data.runner_id || state.runner_id}`);
+        else if (event === "job") queue.push(data);
+        else if (event === "revoked" || event === "replaced") terminal = event;
+        else if (event === "reconnect") terminal = "reconnect";
+      });
+
+      const decoder = new TextDecoder();
+      try {
+        for await (const chunk of response.body) {
+          push(decoder.decode(chunk, { stream: true }));
+          while (queue.length) {
+            const job = queue.shift();
+            log(`leased job ${job.id}`);
+            busy = true;
+            try {
+              await executeJob(args, state, job, { log, fullAccess });
+            } finally {
+              busy = false;
+            }
+            jobsRun += 1;
+            if (once || (typeof stopWhen === "function" && stopWhen())) {
+              terminal = "done";
+              break;
+            }
+          }
+          if (terminal) break;
+        }
+      } catch (error) {
+        log(`stream dropped: ${error.message}`);
+      }
+
+      if (terminal === "revoked") {
+        log("runner was revoked; re-pair with `preman runner register`");
+        clearRunnerState();
+        return { stopped: true, jobsRun, reason: "revoked" };
+      }
+      if (terminal === "replaced") {
+        log("another runner replaced this one; stopping");
+        return { stopped: true, jobsRun, reason: "replaced" };
+      }
+      if (terminal === "done") return { stopped: true, jobsRun, reason: "done" };
+      if (!stopped) await sleep(RECONNECT_MIN_MS);
+    }
+  } finally {
+    clearInterval(heartbeat);
+  }
+
+  return { stopped: true, jobsRun, reason: "stopped" };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function goOffline(args, state, log = defaultLog) {
+  await callback(args, state, "/workbench/coding-agent/local-runner/offline", {}, log);
+}
+
+// ── Command ─────────────────────────────────────────────────────────────
+
+export const RUNNER_HELP = `
+Runner options:
+  runner start [--background]   Hold the job stream and run queued work here
+  runner register [--agent a]   Pair this machine as a runner (connect does this)
+  runner status                 Report whether the local runner is running
+  runner stop                   Stop the background runner and go offline
+  --agent <name>                claude-code | cursor | codex
+  --path <dir>                  Project the runner is bound to. Defaults to cwd
+  --once                        Run one job, then exit
+  --full-access                 Let the agent run commands, not just edit files
+`;
+
+/** Start the daemon detached, so a terminal can be closed without killing it. */
+export function startBackground(commandArgs) {
+  ensureDir();
+  // 0600 like everything else under ~/.preman: nothing in here is a credential
+  // today, and that is not a property to leave depending on future log lines.
+  const log = openSync(RUNNER_LOG_FILE, "a", 0o600);
+  const passthrough = commandArgs.filter((value) => value !== "--background");
+  const child = spawn(
+    process.execPath,
+    [path.join(__dirname, "cli.js"), "runner", "start", ...passthrough],
+    { detached: true, stdio: ["ignore", log, log] }
+  );
+  child.unref();
+  writeFileSync(RUNNER_PID_FILE, `${child.pid}\n`, { mode: 0o600 });
+  return { pid: child.pid, log: RUNNER_LOG_FILE };
+}
+
+async function startForeground(args, commandArgs) {
+  let state = readRunnerState();
+  if (!state) {
+    const agent = normalizeAgentId(args.value("--agent", "")) || "";
+    if (!agent) {
+      throw new RunnerError(
+        `This machine is not paired as a runner yet. Run '${cliInvocation()} runner register --agent claude-code'.`,
+        2
+      );
+    }
+    state = await registerRunner(args, { agent, projectPath: args.value("--path", process.cwd()) });
+  }
+
+  const log = defaultLog;
+  log(`runner ${state.runner_id} · ${state.agent} · ${state.project_path}`);
+  ensureDir();
+  writeFileSync(RUNNER_PID_FILE, `${process.pid}\n`, { mode: 0o600 });
+
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    log(`${signal}: going offline`);
+    await goOffline(args, state, log);
+    rmSync(RUNNER_PID_FILE, { force: true });
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+  try {
+    const result = await runnerLoop(args, state, {
+      log,
+      once: args.has("--once"),
+      fullAccess: args.has("--full-access") || process.env.PREMAN_RUNNER_FULL_ACCESS === "1",
+    });
+    log(`stopped after ${result.jobsRun} job(s): ${result.reason}`);
+  } finally {
+    if (!shuttingDown) {
+      await goOffline(args, state, log);
+      rmSync(RUNNER_PID_FILE, { force: true });
+    }
+  }
+}
+
+export async function runnerCommand(commandArgs = []) {
+  const sub = commandArgs.find((value) => !value.startsWith("-")) || "status";
+  const args = makeArgs(commandArgs);
+
+  if (sub === "register") {
+    const agent = normalizeAgentId(args.value("--agent", ""));
+    if (!agent) throw new RunnerError("pass --agent claude-code|cursor|codex", 2);
+    const state = await registerRunner(args, {
+      agent,
+      projectPath: args.value("--path", process.cwd()),
+    });
+    process.stdout.write(
+      `Runner paired: ${state.runner_id}\n` +
+        `  agent: ${state.agent}\n  project: ${state.project_path}\n\n` +
+        `Start it: ${cliInvocation()} runner start --background\n`
+    );
+    return state;
+  }
+
+  if (sub === "start") {
+    if (args.has("--background")) {
+      if (runnerIsAlive()) {
+        process.stdout.write(`Runner already running (pid ${readPid()}).\n`);
+        return { state: "running", pid: readPid() };
+      }
+      const started = startBackground(commandArgs.filter((value) => value !== "start"));
+      process.stdout.write(
+        `Runner started in the background (pid ${started.pid}).\n  log: ${started.log}\n`
+      );
+      return started;
+    }
+    await startForeground(args, commandArgs);
+    return { state: "stopped" };
+  }
+
+  if (sub === "status") {
+    const state = readRunnerState();
+    const pid = readPid();
+    const alive = runnerIsAlive(pid);
+    if (!state) {
+      process.stdout.write(
+        `Local runner: not paired\n  Pair it: ${cliInvocation()} runner register --agent claude-code\n`
+      );
+      return { state: "unpaired" };
+    }
+    process.stdout.write(
+      `Local runner: ${alive ? `running (pid ${pid})` : "paired, not running"}\n` +
+        `  agent: ${state.agent}\n` +
+        `  project: ${state.project_path}\n` +
+        `  runner id: ${state.runner_id}\n` +
+        (alive ? `  log: ${RUNNER_LOG_FILE}\n` : `  Start it: ${cliInvocation()} runner start --background\n`)
+    );
+    return { state: alive ? "running" : "paired", pid };
+  }
+
+  if (sub === "stop") {
+    const pid = readPid();
+    const state = readRunnerState();
+    if (!runnerIsAlive(pid)) {
+      if (state) await goOffline(args, state, () => {});
+      rmSync(RUNNER_PID_FILE, { force: true });
+      process.stdout.write("Runner was not running.\n");
+      return { state: "stopped" };
+    }
+    process.kill(pid, "SIGTERM");
+    // The daemon reports itself offline on SIGTERM; this only covers the case
+    // where it dies before that callback lands.
+    for (let i = 0; i < 20 && runnerIsAlive(pid); i += 1) await sleep(250);
+    if (runnerIsAlive(pid)) process.kill(pid, "SIGKILL");
+    if (state) await goOffline(args, state, () => {});
+    rmSync(RUNNER_PID_FILE, { force: true });
+    process.stdout.write(`Runner stopped (pid ${pid}).\n`);
+    return { state: "stopped", pid };
+  }
+
+  throw new RunnerError(`unknown runner subcommand: ${sub}${RUNNER_HELP}`, 2);
+}