@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/src/host/rpc-executor.ts

@@ -0,0 +1,299 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import type {
+  AgentStepExecutor,
+  AgentStepRequest,
+  AgentStepSubmission,
+} from "../workflows/types.js";
+import type { HostProcessRegistry } from "./processes.js";
+import { RPC_SUBMISSION_PREFIX } from "./rpc-bridge.js";
+
+// Production resolves the compiled .js; tests and dev checkouts load the .ts
+// source, which pi compiles itself when loading extensions.
+const BRIDGE_PATH = ["./rpc-bridge.js", "./rpc-bridge.ts"]
+  .map((candidate) => fileURLToPath(new URL(candidate, import.meta.url)))
+  .find((candidate) => fs.existsSync(candidate));
+const ABORT_GRACE_MS = 3_000;
+
+type StepSubmission = {
+  action: "submit";
+  step: string;
+  attempt: string;
+  output: unknown;
+};
+
+export type RpcStepExecutorOptions = {
+  cwd: string;
+  registry: HostProcessRegistry;
+  /** Absolute path to the pi binary; defaults to the installed `pi`. */
+  piBin?: string;
+  /** Extra environment for the child; the host's environment is inherited. */
+  env?: Record<string, string>;
+  /** Extra pi arguments, for example a model override. */
+  piArgs?: string[];
+};
+
+/**
+ * Runs agent steps in a headless `pi --mode rpc` child. One child serves one
+ * workflow run. The rpc-bridge extension inside the child registers the
+ * `workflow` tool and reports submissions over stderr; this executor
+ * validates them through `request.accept` and re-prompts on rejection, so
+ * the model sees the same tool contract as an in-session run.
+ */
+export class RpcStepExecutor implements AgentStepExecutor {
+  private readonly options: RpcStepExecutorOptions;
+  private child: ChildProcess | null = null;
+  private childExited: { code: number | null; signal: string | null } | null = null;
+  private stderrBuffer = "";
+  private submissions: StepSubmission[] = [];
+  private submissionWaiters: Array<() => void> = [];
+  private stdoutBuffer = "";
+
+  constructor(options: RpcStepExecutorOptions) {
+    this.options = options;
+  }
+
+  async runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission> {
+    this.ensureStarted();
+    let prompt = request.prompt;
+    for (;;) {
+      throwIfAborted(signal);
+      const submission = await this.promptForSubmission(prompt, request, signal);
+      const accepted = await request.accept(submission.output);
+      if (accepted.ok) {
+        return { output: accepted.value };
+      }
+      prompt = [
+        `The workflow rejected your submission for step ${JSON.stringify(request.contract.nodeId)}:`,
+        accepted.error,
+        "",
+        "Call the `workflow` tool again with a corrected output.",
+      ].join("\n");
+    }
+  }
+
+  /** Stop the child's whole process group, then unregister it. */
+  async close(): Promise<void> {
+    const child = this.child;
+    this.child = null;
+    if (child === null) {
+      return;
+    }
+    const pid = child.pid;
+    if (this.childExited === null) {
+      try {
+        child.stdin?.end();
+      } catch {
+        // The pipe may already be closed.
+      }
+      // The child spawns in its own group; tool calls can leave
+      // grandchildren that leader-only signals would orphan forever.
+      if (pid !== undefined) {
+        killGroup(pid, "SIGTERM");
+      } else {
+        child.kill("SIGTERM");
+      }
+      const exited = await waitForExit(child, ABORT_GRACE_MS);
+      if (!exited) {
+        if (pid !== undefined) {
+          killGroup(pid, "SIGKILL");
+        } else {
+          child.kill("SIGKILL");
+        }
+      }
+    }
+    if (pid !== undefined) {
+      this.options.registry.unregister(pid);
+    }
+  }
+
+  private currentExit(): { code: number | null; signal: string | null } | null {
+    return this.childExited;
+  }
+
+  private ensureStarted(): void {
+    if (this.child !== null) {
+      const exited = this.currentExit();
+      if (exited !== null) {
+        throw new Error(
+          `Headless pi session exited (code ${exited.code}, signal ${exited.signal})`,
+        );
+      }
+      return;
+    }
+    if (BRIDGE_PATH === undefined) {
+      throw new Error("The pi-workflows rpc-bridge extension is missing from this installation");
+    }
+    const piBin = this.options.piBin ?? "pi";
+    const child = spawn(
+      piBin,
+      [
+        "--mode",
+        "rpc",
+        "--no-session",
+        // Isolation is required: an installed pi-workflows extension would
+        // otherwise load beside the bridge, register a competing workflow
+        // tool, and start its own resume and controller workers.
+        "--no-extensions",
+        "-e",
+        BRIDGE_PATH,
+        ...(this.options.piArgs ?? []),
+      ],
+      {
+        cwd: this.options.cwd,
+        env: { ...process.env, ...this.options.env },
+        stdio: ["pipe", "pipe", "pipe"],
+        // Own process group: the host kills groups, never individual PIDs,
+        // so a killed host cannot leave an orphaned agent working.
+        detached: true,
+      },
+    );
+    this.child = child;
+    if (child.pid !== undefined) {
+      this.options.registry.register(child.pid);
+    }
+    child.on("exit", (code, signal) => {
+      this.childExited = { code, signal };
+      if (child.pid !== undefined) {
+        this.options.registry.unregister(child.pid);
+      }
+      this.wakeSubmissionWaiters();
+    });
+    // A failed spawn (missing binary, EACCES) emits error instead of exit;
+    // without a listener it would crash the host as an uncaught exception.
+    child.on("error", (error) => {
+      this.childExited = { code: null, signal: error.message };
+      this.wakeSubmissionWaiters();
+    });
+    child.stdin?.on("error", () => {
+      // Writes racing child exit surface asynchronously as EPIPE; the step
+      // fails through the exit path instead of an uncaught stream error.
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      this.stderrBuffer += chunk.toString("utf8");
+      const lines = this.stderrBuffer.split("\n");
+      this.stderrBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (!line.startsWith(RPC_SUBMISSION_PREFIX)) {
+          continue;
+        }
+        try {
+          const parsed = JSON.parse(line.slice(RPC_SUBMISSION_PREFIX.length)) as StepSubmission;
+          if (
+            parsed.action === "submit" &&
+            typeof parsed.step === "string" &&
+            typeof parsed.attempt === "string"
+          ) {
+            this.submissions.push(parsed);
+          }
+        } catch {
+          // A malformed marker line is ignored; the step times out instead.
+        }
+      }
+      this.wakeSubmissionWaiters();
+    });
+    // stdout carries the RPC event stream. The submission channel is stderr,
+    // so stdout is only drained to keep the pipe from blocking.
+    child.stdout?.on("data", (chunk: Buffer) => {
+      this.stdoutBuffer = (this.stdoutBuffer + chunk.toString("utf8")).slice(-64 * 1024);
+    });
+  }
+
+  private async promptForSubmission(
+    prompt: string,
+    request: AgentStepRequest,
+    signal: AbortSignal,
+  ): Promise<StepSubmission> {
+    const child = this.child;
+    if (child === null || this.childExited !== null) {
+      throw new Error("Headless pi session is not running");
+    }
+    const matching = this.takeMatchingSubmission(request);
+    if (matching !== undefined) {
+      return matching;
+    }
+    child.stdin?.write(`${JSON.stringify({ type: "prompt", message: prompt })}\n`);
+    for (;;) {
+      throwIfAborted(signal);
+      const exited = this.currentExit();
+      if (exited !== null) {
+        throw new Error(`Headless pi session exited mid-step (code ${exited.code})`);
+      }
+      const found = this.takeMatchingSubmission(request);
+      if (found !== undefined) {
+        return found;
+      }
+      await new Promise<void>((resolve, reject) => {
+        const waiter = () => {
+          signal.removeEventListener("abort", onAbort);
+          resolve();
+        };
+        const onAbort = () => {
+          this.sendAbortQuietly();
+          reject(signal.reason ?? new Error("Workflow step aborted"));
+        };
+        this.submissionWaiters.push(waiter);
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+    }
+  }
+
+  private takeMatchingSubmission(request: AgentStepRequest): StepSubmission | undefined {
+    const index = this.submissions.findIndex(
+      (candidate) =>
+        candidate.step === request.contract.nodeId &&
+        candidate.attempt === request.contract.attemptId,
+    );
+    return index === -1 ? undefined : (this.submissions.splice(index, 1)[0] as StepSubmission);
+  }
+
+  private sendAbortQuietly(): void {
+    try {
+      this.child?.stdin?.write(`${JSON.stringify({ type: "abort" })}\n`);
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  private wakeSubmissionWaiters(): void {
+    const waiters = this.submissionWaiters;
+    this.submissionWaiters = [];
+    for (const waiter of waiters) {
+      waiter();
+    }
+  }
+}
+
+function killGroup(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pid, signal);
+    return;
+  } catch {
+    // Group signals are unsupported here; the leader still needs it.
+  }
+  try {
+    process.kill(pid, signal);
+  } catch {
+    // Already gone.
+  }
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) {
+    throw (signal.reason as unknown) ?? new Error("Workflow step aborted");
+  }
+}
+
+async function waitForExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return true;
+  }
+  return await new Promise<boolean>((resolve) => {
+    const timer = setTimeout(() => resolve(false), timeoutMs);
+    child.once("exit", () => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}

package/src/host/runner.ts

@@ -0,0 +1,406 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  ControllerManager,
+  loadDiscoveredControllers,
+  projectControllerStorePath,
+  SqliteControllerStore,
+  WorkflowEngineScheduler,
+  type WorkflowRunQueueRecord,
+} from "../controllers/index.js";
+import type { JsonObject } from "../controllers/types.js";
+import { WorkflowEngine } from "../workflows/engine.js";
+import {
+  ClaimLostError,
+  errorMessage,
+  isClaimLostError,
+  WorkflowSourceChangedError,
+} from "../workflows/errors.js";
+import { hashWorkflowSource, loadWorkflowFile, resolveWorkflowRef } from "../workflows/loader.js";
+import { WorkflowRunStore } from "../workflows/store.js";
+import type { WorkflowDefinition } from "../workflows/types.js";
+import { HostProcessRegistry } from "./processes.js";
+import { RpcStepExecutor } from "./rpc-executor.js";
+
+const CLAIM_POLL_MS = 2_000;
+const RUN_CLAIM_LEASE_MS = 30_000;
+const RUN_CLAIM_RENEW_MS = 10_000;
+
+export type WorkflowHostOptions = {
+  cwd: string;
+  runnerId?: string;
+  /** Explicit store path; defaults to the project-scoped controller store. */
+  storeFile?: string;
+  /** Explicit run-bundle root; defaults to the shared runs directory. */
+  runsDir?: string;
+  registry?: HostProcessRegistry;
+  piArgs?: string[];
+  /** Extra environment for headless children (for example a test provider). */
+  env?: Record<string, string>;
+  /** Poll interval for the claim loop; tests use a faster cadence. */
+  claimPollMs?: number;
+  onLog?: (message: string) => void;
+};
+
+/**
+ * The always-on runner: claims parked workflow runs and reconciles durable
+ * controllers without a Pi session. Conversation nodes execute in headless
+ * `pi --mode rpc` children. Everything the host does is recoverable: claims
+ * expire, bundles fence stale writers, and child processes are reaped by
+ * the next host.
+ */
+export class WorkflowHost {
+  private readonly options: WorkflowHostOptions;
+  private readonly runnerId: string;
+  private readonly registry: HostProcessRegistry;
+  private readonly store: SqliteControllerStore;
+  private readonly childRunStore: WorkflowRunStore;
+  private manager: ControllerManager | null = null;
+  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly activeRuns = new Map<string, Promise<void>>();
+  private readonly schedulerExecutors = new Map<WorkflowEngine, RpcStepExecutor>();
+  /** Runs whose resume refused (edited source); skipped until a host restart. */
+  private readonly skippedRuns = new Set<string>();
+  private stopping = false;
+
+  private readonly stateDir: string;
+
+  constructor(options: WorkflowHostOptions) {
+    this.options = options;
+    this.runnerId = options.runnerId ?? `host-${randomUUID().slice(0, 8)}`;
+    this.store = new SqliteControllerStore(
+      options.storeFile ?? projectControllerStorePath(options.cwd),
+    );
+    this.stateDir = path.dirname(this.store.filePath);
+    this.registry = options.registry ?? new HostProcessRegistry(this.stateDir);
+    this.childRunStore = new WorkflowRunStore(
+      options.runsDir ?? process.env.PI_WORKFLOWS_RUNS_DIR ?? undefined,
+    );
+  }
+
+  private log(message: string): void {
+    this.options.onLog?.(message);
+  }
+
+  /** Take the advisory lock, reap orphans, and start claiming. */
+  async start(): Promise<void> {
+    // The lock comes first: a second host must refuse before touching the
+    // children registry, or it would kill the live host's child processes
+    // as supposed orphans.
+    acquireHostLock(this.stateDir, this.runnerId, this.options.cwd);
+    const reaped = this.registry.reapOrphans();
+    if (reaped.length > 0) {
+      this.log(`reaped ${reaped.length} orphaned headless session(s): ${reaped.join(", ")}`);
+    }
+
+    const definitions = await loadDiscoveredControllers({ cwd: this.options.cwd });
+    if (definitions.length > 0) {
+      const scheduler = new WorkflowEngineScheduler({
+        store: this.childRunStore,
+        resolveWorkflow: async (name) => {
+          const resolved = await resolveWorkflowRef(name, { cwd: this.options.cwd });
+          const workflow = await loadWorkflowFile(resolved.path);
+          return { workflow };
+        },
+        createEngine: () => {
+          const executor = new RpcStepExecutor({
+            cwd: this.options.cwd,
+            registry: this.registry,
+            ...(this.options.piArgs !== undefined ? { piArgs: this.options.piArgs } : {}),
+            ...(this.options.env !== undefined ? { env: this.options.env } : {}),
+          });
+          const engine = new WorkflowEngine({ executor, store: this.childRunStore });
+          this.schedulerExecutors.set(engine, executor);
+          return engine;
+        },
+        disposeEngine: async (engine) => {
+          const executor = this.schedulerExecutors.get(engine);
+          if (executor !== undefined) {
+            this.schedulerExecutors.delete(engine);
+            await executor.close();
+          }
+        },
+      });
+      this.manager = new ControllerManager({
+        store: this.store,
+        controllers: definitions,
+        workflowScheduler: scheduler,
+      });
+      this.manager.start();
+      this.log(`controller workers started for ${definitions.length} controller(s)`);
+    }
+
+    this.pollTimer = setInterval(() => {
+      this.claimOnce();
+    }, this.options.claimPollMs ?? CLAIM_POLL_MS);
+    this.pollTimer.unref?.();
+    this.claimOnce();
+    this.log(`host ${this.runnerId} watching ${this.options.cwd}`);
+  }
+
+  /** Drain: stop claiming, park in-flight runs, stop controllers, kill children. */
+  async stop(): Promise<void> {
+    if (this.stopping) {
+      return;
+    }
+    this.stopping = true;
+    if (this.pollTimer !== null) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+    const pending = [...this.activeRuns.values()];
+    for (const run of this.parkedEngines.splice(0)) {
+      run();
+    }
+    await Promise.allSettled(pending);
+    await this.manager?.stop().catch(() => undefined);
+    for (const executor of this.schedulerExecutors.values()) {
+      await executor.close().catch(() => undefined);
+    }
+    this.schedulerExecutors.clear();
+    this.registry.killAll();
+    releaseHostLock(this.stateDir, this.runnerId);
+    this.store.close();
+  }
+
+  private readonly parkedEngines: Array<() => void> = [];
+
+  private claimOnce(): void {
+    if (this.stopping || this.activeRuns.size > 0) {
+      return;
+    }
+    let claimed: WorkflowRunQueueRecord | undefined;
+    try {
+      claimed = this.store.claimNextWorkflowRun({
+        runnerId: this.runnerId,
+        claimToken: randomUUID(),
+        leaseMs: RUN_CLAIM_LEASE_MS,
+        excludeRunIds: [...this.skippedRuns],
+      });
+    } catch (error) {
+      // Store contention or corruption must not kill the host's loop.
+      this.log(`claim failed, retrying shortly: ${errorMessage(error)}`);
+      return;
+    }
+    if (claimed === undefined) {
+      return;
+    }
+    const task = this.runClaimed(claimed).finally(() => {
+      this.activeRuns.delete(claimed.runId);
+    });
+    this.activeRuns.set(claimed.runId, task);
+  }
+
+  private async runClaimed(record: WorkflowRunQueueRecord): Promise<void> {
+    const claimToken = record.claimToken as string;
+    const runId = record.runId;
+    this.log(`resuming ${record.workflowRef} run ${runId}`);
+    let workflow: WorkflowDefinition;
+    let workflowHash: string;
+    try {
+      workflow = await loadWorkflowFile(record.workflowPath);
+      workflowHash = await hashWorkflowSource(record.workflowPath);
+    } catch (error) {
+      await this.failUnresumable(record, claimToken, errorMessage(error));
+      return;
+    }
+    if (this.stopping) {
+      // The drain started during setup: park before anything executes.
+      try {
+        this.store.parkWorkflowRun({ runId, claimToken });
+      } catch {
+        // Best-effort.
+      }
+      return;
+    }
+
+    const store = this.store;
+    const fence = () => {
+      if (!store.verifyWorkflowRunClaim({ runId, claimToken })) {
+        throw new ClaimLostError(runId);
+      }
+    };
+    const fencedStore = new WorkflowRunStore(this.childRunStore.outputRoot, {
+      fenceProvider: () => fence,
+    });
+    const executor = new RpcStepExecutor({
+      cwd: this.options.cwd,
+      registry: this.registry,
+      ...(this.options.piArgs !== undefined ? { piArgs: this.options.piArgs } : {}),
+      ...(this.options.env !== undefined ? { env: this.options.env } : {}),
+    });
+    const engine = new WorkflowEngine({ executor, store: fencedStore });
+    const parkEngine = () => engine.park();
+    this.parkedEngines.push(parkEngine);
+
+    const renewTimer = setInterval(() => {
+      try {
+        if (!store.renewWorkflowRunClaim({ runId, claimToken, leaseMs: RUN_CLAIM_LEASE_MS })) {
+          engine.cancel();
+        }
+      } catch {
+        // Transient store errors leave fencing to decide ownership.
+      }
+    }, RUN_CLAIM_RENEW_MS);
+    renewTimer.unref?.();
+
+    this.recordEvent(runId, record.workflowRef, "resumed", { runnerId: this.runnerId });
+    try {
+      const result = await engine.resumeRun(workflow, runId, { workflowHash });
+      clearInterval(renewTimer);
+      if (result.state.status === "running") {
+        // Parked again mid-drain: leave it claimable for the next runner.
+        this.store.parkWorkflowRun({ runId, claimToken });
+        this.recordEvent(runId, record.workflowRef, "parked", {});
+        this.log(`parked ${record.workflowRef} run ${runId}`);
+        return;
+      }
+      this.store.completeWorkflowRun({ runId, claimToken });
+      this.recordEvent(runId, record.workflowRef, result.state.status, {
+        ...(result.state.error !== undefined ? { error: result.state.error } : {}),
+        ...(result.state.waitingOn !== undefined ? { waitingOn: result.state.waitingOn } : {}),
+      });
+      this.log(`${record.workflowRef} run ${runId} ${result.state.status}`);
+    } catch (error) {
+      clearInterval(renewTimer);
+      if (isClaimLostError(error)) {
+        this.log(`run ${runId} continues under another runner`);
+        return;
+      }
+      if (error instanceof WorkflowSourceChangedError) {
+        // Edited source is a refusal, not a failure: keep the run claimable
+        // for a later fix, and stop spinning on it for this host's lifetime.
+        try {
+          this.store.parkWorkflowRun({ runId, claimToken });
+        } catch {
+          // Best-effort.
+        }
+        this.skippedRuns.add(runId);
+        this.recordEvent(runId, record.workflowRef, "parked", {
+          reason: "workflow source changed",
+        });
+        this.log(
+          `run ${runId} skipped: workflow source changed; revert or force-resume it, then restart the host`,
+        );
+        return;
+      }
+      await this.failUnresumable(record, claimToken, errorMessage(error));
+    } finally {
+      const index = this.parkedEngines.indexOf(parkEngine);
+      if (index !== -1) {
+        this.parkedEngines.splice(index, 1);
+      }
+      await executor.close().catch(() => undefined);
+    }
+  }
+
+  private async failUnresumable(
+    record: WorkflowRunQueueRecord,
+    claimToken: string,
+    message: string,
+  ): Promise<void> {
+    let actualStatus: string | undefined;
+    let heldClaim = false;
+    try {
+      // The interruption write obeys the same fencing rule as every other
+      // bundle write: without a live claim, the current owner decides.
+      heldClaim = this.store.verifyWorkflowRunClaim({ runId: record.runId, claimToken });
+      if (heldClaim) {
+        const bundle = await this.childRunStore.markRunInterrupted(record.runId, message);
+        actualStatus = bundle?.state.status;
+      }
+    } catch {
+      // The bundle may be unreadable; the queue row still needs closure.
+    }
+    try {
+      this.store.completeWorkflowRun({ runId: record.runId, claimToken });
+    } catch {
+      // Best-effort.
+    }
+    if (!heldClaim) {
+      // Another runner owns the run; its owner reports from here.
+      this.log(`run ${record.runId} continues under another runner`);
+      return;
+    }
+    // Report the bundle's real terminal state when the interruption was a
+    // no-op (the bundle was already waiting or completed), so the feed
+    // stays truthful for sessions syncing from it.
+    if (actualStatus !== undefined && actualStatus !== "failed") {
+      this.recordEvent(record.runId, record.workflowRef, actualStatus, {});
+    } else {
+      this.recordEvent(record.runId, record.workflowRef, "failed", { error: message });
+    }
+    this.log(`run ${record.runId} cannot resume: ${message}`);
+  }
+
+  private recordEvent(runId: string, workflowRef: string, type: string, payload: JsonObject): void {
+    try {
+      this.store.recordRunEvent({ runId, workflowRef, type, payload, runnerId: this.runnerId });
+    } catch {
+      // The event feed is best-effort.
+    }
+  }
+}
+
+function hostLockPath(stateDir: string): string {
+  return path.join(stateDir, "host.lock");
+}
+
+/**
+ * The advisory lock guards host-versus-host only: the embedded runner in a
+ * Pi session does not take it. A second host refuses to start while the
+ * recorded PID is alive.
+ */
+function acquireHostLock(stateDir: string, runnerId: string, cwd: string): void {
+  const lockPath = hostLockPath(stateDir);
+  const existing = readLock(lockPath);
+  if (existing !== null && existing.runnerId !== runnerId && isAlive(existing.pid)) {
+    throw new Error(
+      `Another workflow host (pid ${existing.pid}, ${existing.runnerId}) is already running for ${cwd}`,
+    );
+  }
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(
+    lockPath,
+    `${JSON.stringify({ pid: process.pid, runnerId, startedAt: new Date().toISOString() })}\n`,
+    { encoding: "utf8", mode: 0o600 },
+  );
+}
+
+function releaseHostLock(stateDir: string, runnerId: string): void {
+  const lockPath = hostLockPath(stateDir);
+  const existing = readLock(lockPath);
+  if (existing?.runnerId !== runnerId) {
+    return;
+  }
+  try {
+    fs.rmSync(lockPath);
+  } catch {
+    // Already gone.
+  }
+}
+
+function readLock(lockPath: string): { pid: number; runnerId: string } | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8")) as {
+      pid?: unknown;
+      runnerId?: unknown;
+    };
+    if (typeof parsed.pid !== "number" || typeof parsed.runnerId !== "string") {
+      return null;
+    }
+    return { pid: parsed.pid, runnerId: parsed.runnerId };
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}