CLI-first runtime, SDK-ready surface

Use it from the shell or embed it in your tooling.

Deadpool Runner wraps a command, captures failures, asks an ACP client to repair the repo, and retries until the command passes, repeats the same failure, or exhausts the configured budget.

See SDK Usage View Repository

Part of Run Suite. GitHub Pages is published from the committed docs/ directory after CI passes.

Install

vp add @arcqdev/deadpool-runner

Use npm i -g @arcqdev/deadpool-runner if you want the global dpr command.

1. Run

Wrap the real command

Keep your normal test, build, or check command unchanged and let Deadpool Runner own the retry loop.

2. Repair

Feed the ACP client context

Each failure includes captured output plus per-run artifacts written under ~/.deadpool-runner/runs/.

3. Stop cleanly

Respect real limits

The loop exits on success, retry exhaustion, or a repeat-failure critique that decides the fix is stuck.

CLI

Use the command runner directly

Good for local workflows, CI helpers, or wrapper scripts.

Quick start

dpr -- vp test

dpr --retries 3 --prompt "Vite+ package, fix root causes" -- vp check

dpr --config ./deadpool-runner.config.ts

Config file

import { defineDeadpoolRunnerConfig } from "@arcqdev/deadpool-runner";

export default defineDeadpoolRunnerConfig({
  command: ["vp", "test"],
  retries: 5,
  initialPrompt: "Fix the actual regression, not the assertion.",
  acpClient: {
    name: "codex",
    model: "gpt-5.4",
    fullAuto: true,
  },
  critique: {
    enabled: true,
    repeatFailureLimit: 1,
    acpClient: {
      sandbox: "read-only",
      fullAuto: false,
    },
  },
});
SDK

Embed the retry loop in your own code

The package now exposes a first-class programmatic entrypoint.

High-level API

import { runDeadpoolRunner } from "@arcqdev/deadpool-runner";

const result = await runDeadpoolRunner({
  cwd: process.cwd(),
  command: ["vp", "test"],
  retries: 2,
  initialPrompt: "TypeScript package. Keep fixes minimal.",
  acpClient: {
    name: "codex",
    model: "gpt-5.4",
    sandbox: "workspace-write",
  },
});

if (result.code !== 0) {
  throw new Error(`Repair loop failed with exit code ${result.code}`);
}

Advanced runner injection

import { createRunner } from "@arcqdev/deadpool-runner";

const runner = createRunner({
  runCommand: async (command, options) => {
    return {
      code: 0,
      signal: null,
      stdout: "ok\n",
      stderr: "",
      combinedOutput: "ok\n",
    };
  },
});

await runner.run({
  command: ["vp", "test"],
});
Custom ACP Clients

Register your own repair backend

The registry is public so SDK consumers can plug in other ACP implementations.

import {
  registerACPClient,
  runDeadpoolRunner,
  type ACPClient,
  type ACPClientConfig,
} from "@arcqdev/deadpool-runner";

registerACPClient("internal-agent", (config?: ACPClientConfig): ACPClient => ({
  name: "internal-agent",
  async fixFailure(context) {
    console.log("repairing", context.command, "with", config?.model ?? "default");
    return { summary: "Applied internal-agent repair." };
  },
}));

await runDeadpoolRunner({
  command: ["vp", "test"],
  acpClient: {
    name: "internal-agent",
    model: "my-internal-model",
  },
});
CLI Flags

Common options

Flag Usage
--retries <n> Set the max fix attempts after the initial failure.
--prompt <text> Send additional repository context to the fixer.
--cwd, --repo Run against another working directory.
--client, --model Pick the ACP backend and model.
--sandbox Choose read-only, workspace-write, or danger-full-access.
--max-output-chars Trim the trailing failure output sent to the fixer.
--verbose Stream ACP client logs during repair attempts.
Operational Notes

Repeat-failure critique and deployment

The critique loop is enabled by default and stops early when the same failure repeats too many times. CI and GitHub Pages deployment live in the same workflow so the site only publishes after validation passes.