@boardwalk-labs/runner 0.1.2

package/dist/contract.js

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+// The Boardwalk runner contract — the canonical payload types between a self-hosted runner
+// machine and the Boardwalk control plane: registration, the assignment offer, claim/lease,
+// and heartbeat. Published from this repo (CONTRACT.md is the prose half); the control plane
+// implements the same schemas.
+//
+// DRAFT until the first tagged release: breaking changes are allowed while the platform
+// implementation lands. After that, this file versions with the package, semver-strictly.
+//
+// Shape of the protocol (revised 2026-07 — credentials moved to CLAIM):
+//   - The POLLED OFFER is credential-free: identity + selector only. A queued assignment
+//     never carries a token that could age out or leak before any runner commits.
+//   - The CLAIM RESPONSE is the only place per-run credentials exist: the run token, the run
+//     API token, the resolved non-secret env, and the org's BYO inference provider registry.
+//   - Everything else about the run (manifest, program artifact + digest, workspace, artifact
+//     prefixes, event stream) is fetched AFTER claim through the run-token'd Runner Control
+//     API — the same broker surface a Boardwalk-hosted worker uses. One contract, hosted and
+//     self-hosted.
+//
+// Security invariants encoded here (see CONTRACT.md §security):
+//   - The registration token registers, nothing else; the standing runner token can only
+//     poll/claim/heartbeat/deregister; org reach exists only in a claim's run token.
+//   - Secrets are NOT in any payload here. They resolve per run through the control plane
+//     with the run token, fail-closed. A BYO provider entry names its auth secret; it never
+//     carries the value.
+//
+// Schema rules (same discipline as @boardwalk-labs/workflow): strict objects — unknown fields are
+// validation errors; union members most-specific-first; types derive from schemas, never
+// hand-written.
+import { z } from "zod";
+// ============================================================================
+// Shared scalars
+// ============================================================================
+const id = z.string().min(1).max(128);
+/** Epoch milliseconds. */
+const epochMs = z.number().int().nonnegative();
+export const runnerOsSchema = z.enum(["linux", "macos", "windows"]);
+export const runnerArchSchema = z.enum(["x64", "arm64"]);
+// ============================================================================
+// Registration — a machine joins a pool
+// ============================================================================
+/**
+ * POST /runner/v1/register, authenticated by the short-lived registration token in the body —
+ * the token IS the credential (single-purpose: it can register, nothing else) and it is BOUND
+ * to a pool at mint, so the request names no pool.
+ */
+export const runnerRegistrationRequestSchema = z.strictObject({
+    registration_token: z.string().min(1),
+    /** Human-readable machine name (shown in the dashboard). */
+    name: z.string().min(1).max(120),
+    /** Extra labels advertised for `runs_on.labels` matching. */
+    labels: z.array(z.string().min(1).max(120)).max(32).default([]),
+    os: runnerOsSchema.optional(),
+    arch: runnerArchSchema.optional(),
+    /** The runner client's own version (for deprecation + compatibility messaging). */
+    runner_version: z.string().min(1).max(64).optional(),
+});
+export const runnerRegistrationResponseSchema = z.strictObject({
+    runner_id: id,
+    /** The pool the (pool-bound) registration token enrolled this runner into. */
+    pool: z.string().min(1).max(120),
+    /**
+     * The runner's standing identity credential: it can poll for assignments, claim, heartbeat,
+     * and deregister — and nothing else. Per-run capability comes only from a claim's run token.
+     */
+    runner_token: z.string().min(1),
+    poll: z.strictObject({
+        url: z.string().url(),
+        /** Suggested poll cadence when no long-poll is held. */
+        interval_seconds: z.number().int().positive().max(300),
+    }),
+});
+// ============================================================================
+// Assignment offer — one run, offered to the pool
+// ============================================================================
+/** The matched `runs_on` selector, echoed so the runner can re-verify it should run this. */
+export const assignmentRunsOnSchema = z.union([
+    z.strictObject({
+        kind: z.literal("self-hosted"),
+        pool: z.string().min(1).max(120),
+        labels: z.array(z.string().min(1).max(120)).optional(),
+    }),
+    // Hosted labels (the hosted worker speaks the same contract).
+    z.string().min(1).max(120),
+]);
+/**
+ * A polled offer is CREDENTIAL-FREE by design: identity + selector only. Committing to it
+ * (claim) is what mints credentials; the run's full context (manifest, program, workspace)
+ * is fetched after claim through the run-token'd Runner Control API.
+ */
+export const assignmentOfferSchema = z.strictObject({
+    assignment_id: id,
+    run_id: id,
+    org_id: id,
+    runs_on: assignmentRunsOnSchema,
+    queued_at: epochMs,
+});
+/**
+ * Long-poll response: at most one offer. `action: "drain"` tells an idle runner to stop
+ * claiming (deregistration/update flow) — control signals are always brokered polls, never
+ * inbound connections to the runner.
+ */
+export const assignmentPollResponseSchema = z.strictObject({
+    assignment: assignmentOfferSchema.nullable(),
+    action: z.literal("drain").optional(),
+});
+// ============================================================================
+// Claim — lease before work; credentials arrive HERE
+// ============================================================================
+/**
+ * One BYO inference provider, as data: the runtime calls the endpoint directly (managed-lane
+ * inference stays brokered; managed providers are never listed). The auth secret resolves by
+ * NAME through the control plane with the run token — the value never rides this payload.
+ */
+export const byoInferenceProviderSchema = z.strictObject({
+    name: z.string().min(1).max(120),
+    /** Adapter kind, e.g. `openai_compatible`, `anthropic`, `bedrock`, `google`. */
+    source: z.string().min(1).max(64),
+    base_url: z.string().nullable(),
+    auth_secret_name: z.string().nullable(),
+});
+/**
+ * POST .../assignments/{assignment_id}/claim (runner-token authed; the bearer identifies the
+ * runner, the URL the assignment — no body). First claim wins; a loser gets a conflict and
+ * polls again. The response is the ONLY payload carrying per-run credentials.
+ */
+export const claimResponseSchema = z.strictObject({
+    lease_id: id,
+    run_id: id,
+    /** Heartbeat before this or the lease expires and the run is recovered elsewhere. */
+    lease_expires_at: epochMs,
+    /**
+     * The runner's ONLY org-reaching credentials, minted at claim and bound to this run:
+     * `run_token` authenticates every Runner Control API call; `api_token` is the run's
+     * auto-injected BOARDWALK_API_KEY (public-API machine principal, manifest-derived scopes).
+     */
+    control_plane: z.strictObject({
+        base_url: z.string().url(),
+        run_token: z.string().min(1),
+        api_token: z.string().min(1),
+    }),
+    /** The run's resolved NON-secret env (manifest literals overlaid by org/environment
+     *  variables). Secrets never ride here — they resolve through the control plane. */
+    env: z.record(z.string(), z.string()),
+    /** The org's BYO inference providers, for runner-direct model calls. */
+    byo_providers: z.array(byoInferenceProviderSchema),
+});
+// ============================================================================
+// Heartbeat — keep the lease, receive control signals
+// ============================================================================
+export const heartbeatPhaseSchema = z.enum(["preparing", "running", "finalizing"]);
+/** The bearer identifies the runner; the body names the held lease. */
+export const heartbeatRequestSchema = z.strictObject({
+    lease_id: id,
+    run_id: id,
+    phase: heartbeatPhaseSchema,
+});
+/**
+ * The heartbeat response is the control channel: cancellation and drain arrive HERE (a
+ * brokered poll), never as an inbound connection to the runner.
+ */
+export const heartbeatResponseSchema = z.strictObject({
+    lease_expires_at: epochMs,
+    /**
+     * `continue` — keep going. `cancel` — stop the run now (the broker records the terminal
+     * state). `drain` — finish the current run, then claim nothing further.
+     */
+    action: z.enum(["continue", "cancel", "drain"]),
+});
+// ============================================================================
+// Terminal status
+// ============================================================================
+// There is deliberately NO pool-level status report: the runner's last word on a run is the
+// run-token'd `finalize` call on the Runner Control API — the same call a hosted worker makes.
+// The control plane closes out the assignment (terminal status, runner back to idle) there.
+// ============================================================================
+// Validation helper
+// ============================================================================
+/** Thrown when a contract payload fails validation. */
+export class ContractValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContractValidationError";
+    }
+}
+/** Parse with a readable multi-issue error (the schemas are strict — unknown fields fail). */
+export function parseContract(schema, payload, what) {
+    const result = schema.safeParse(payload);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.length > 0 ? i.path.join(".") : "(root)"}: ${i.message}`)
+            .join("\n");
+        throw new ContractValidationError(`Invalid ${what}:\n${issues}`);
+    }
+    return result.data;
+}

package/dist/daemon/daemon.d.ts

@@ -0,0 +1,45 @@
+import type { ClaimResponse } from "../contract.js";
+import { type Logger } from "../runtime/support/index.js";
+import type { PoolClient } from "./pool_client.js";
+export interface RunProcessHandle {
+    /** Resolves with the exit code when the run process ends. */
+    wait: () => Promise<number>;
+    /** Ask the process to stop (SIGTERM — the runtime exits and the lease recovers the run). */
+    kill: () => void;
+}
+export interface RunSpawner {
+    (opts: {
+        entry: string;
+        env: Record<string, string>;
+        cwd: string;
+    }): RunProcessHandle;
+}
+export interface DaemonDeps {
+    client: Pick<PoolClient, "poll" | "claim" | "heartbeat">;
+    /** Absolute path to the runtime process entry (dist/runtime/main.js). */
+    runtimeEntry: string;
+    /** Root under which per-run workspaces are created (and always removed). */
+    workDir: string;
+    /** Stable runner identity (stamped as WORKER_ID on run processes). */
+    runnerId: string;
+    spawn: RunSpawner;
+    log?: Logger;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Execute at most one run, then return (CI-friendly). */
+    once?: boolean;
+    /** Test hook: called at the top of each loop iteration. */
+    onIdle?: () => void;
+}
+export interface DaemonController {
+    /** Resolves when the daemon has fully stopped (drained + last run finished). */
+    done: Promise<void>;
+    /** Begin draining: finish the current run (if any), then stop claiming. */
+    drain: () => void;
+}
+/** Env for one run process: the platform contract + the claim's resolved non-secret vars. */
+export declare function runProcessEnv(claim: ClaimResponse, opts: {
+    runnerId: string;
+    workspaceRoot: string;
+}): Record<string, string>;
+export declare function startDaemon(deps: DaemonDeps): DaemonController;

package/dist/daemon/daemon.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// The self-hosted runner daemon (docs/SELF_HOSTED_RUNNERS.md R4): poll → claim → spawn ONE run
+// process → heartbeat while it runs → clean → poll. One run at a time per daemon (concurrency =
+// more daemons/machines); drain (Ctrl-C, admin drain, org toggle off) finishes the current run
+// then stops claiming. The per-run process is the SAME runtime a Boardwalk-hosted worker boots
+// (./runtime/main.js) — the daemon only hands it the claim's credentials + env and a fresh
+// per-run workspace, then tears the workspace down (contract: cleanup "always").
+import { mkdir, rm } from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createLogger } from "../runtime/support/index.js";
+/** Assignment-lease heartbeat cadence — comfortably beats the 300s lease. */
+const HEARTBEAT_MS = 60_000;
+/** Back off this long after a transient poll/claim error (network blip, control-plane deploy). */
+const ERROR_BACKOFF_MS = 10_000;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Env for one run process: the platform contract + the claim's resolved non-secret vars. */
+export function runProcessEnv(claim, opts) {
+    return {
+        // The claim's resolved non-secret env FIRST — the platform contract keys always win.
+        ...claim.env,
+        RUN_ID: claim.run_id,
+        BOARDWALK_CONTROL_PLANE_URL: claim.control_plane.base_url,
+        BOARDWALK_RUN_TOKEN: claim.control_plane.run_token,
+        BOARDWALK_API_KEY: claim.control_plane.api_token,
+        BOARDWALK_TASK_CPU_UNITS: String(os.cpus().length * 1024),
+        // The org's BYO inference providers, as data (plan D7) — consumed by the runtime's direct
+        // model path. Names + endpoints + secret NAMES only; never a credential value.
+        BOARDWALK_BYO_PROVIDERS: JSON.stringify(claim.byo_providers),
+        WORKER_ID: opts.runnerId,
+        WORKSPACE_ROOT: opts.workspaceRoot,
+        // The machine's own PATH/HOME etc. deliberately do NOT flow here: the run gets exactly the
+        // resolved env + platform contract, mirroring the hosted container. The spawner overlays the
+        // minimal process necessities (PATH, HOME=workspace).
+    };
+}
+export function startDaemon(deps) {
+    const log = deps.log ?? createLogger("RunnerDaemon");
+    const sleep = deps.sleep ?? defaultSleep;
+    let draining = false;
+    async function executeClaim(offer, claim) {
+        const runDir = path.join(deps.workDir, "runs", claim.run_id);
+        const workspaceRoot = path.join(runDir, "workspace");
+        await mkdir(workspaceRoot, { recursive: true });
+        const child = deps.spawn({
+            entry: deps.runtimeEntry,
+            env: runProcessEnv(claim, { runnerId: deps.runnerId, workspaceRoot }),
+            cwd: workspaceRoot,
+        });
+        log.info("run_started", { runId: claim.run_id, assignmentId: offer.assignment_id });
+        // Heartbeat while the run process lives. Lease lost ⇒ the control plane recovered the
+        // assignment (we were presumed dead) — stop the process; the run restarts elsewhere.
+        // `cancel` is ALSO delivered to the run process itself (its own CancelWatcher via the run
+        // token), so the daemon doesn't kill on cancel — it lets the runtime finalize cleanly.
+        let exited = false;
+        const heartbeatLoop = (async () => {
+            for (;;) {
+                await sleep(HEARTBEAT_MS);
+                if (exited)
+                    return;
+                try {
+                    const beat = await deps.client.heartbeat(claim.lease_id, claim.run_id, "running");
+                    log.debug("heartbeat", { runId: claim.run_id, action: beat?.action ?? "lease_lost" });
+                    if (exited)
+                        return;
+                    if (beat === null) {
+                        log.warn("assignment_lease_lost", { runId: claim.run_id });
+                        child.kill();
+                        return;
+                    }
+                    if (beat.action === "drain") {
+                        log.info("drain_requested", { runId: claim.run_id });
+                        draining = true;
+                    }
+                }
+                catch (err) {
+                    // Transient heartbeat failure: keep the process running; the next beat retries. The
+                    // lease is 300s and the cadence 60s, so several failures are survivable.
+                    log.warn("heartbeat_failed", {
+                        runId: claim.run_id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        })();
+        const exitCode = await child.wait();
+        exited = true;
+        await heartbeatLoop.catch(() => undefined);
+        log.info("run_finished", { runId: claim.run_id, exitCode });
+        // Contract: cleanup "always". Persistence happened via the workspace store, not local disk.
+        await rm(runDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    const done = (async () => {
+        log.info("daemon_started", { runnerId: deps.runnerId, workDir: deps.workDir });
+        while (!draining) {
+            deps.onIdle?.();
+            try {
+                log.debug("polling", {});
+                const polled = await deps.client.poll();
+                if (polled.action === "drain") {
+                    log.info("drain_requested", {});
+                    break;
+                }
+                const offer = polled.assignment;
+                if (offer === null)
+                    continue; // long-poll came back empty — poll again immediately
+                const claim = await deps.client.claim(offer.assignment_id);
+                if (claim === null)
+                    continue; // another runner won — back to polling
+                await executeClaim(offer, claim);
+                if (deps.once === true)
+                    break;
+            }
+            catch (err) {
+                log.warn("daemon_iteration_failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                await sleep(ERROR_BACKOFF_MS);
+            }
+        }
+        log.info("daemon_stopped", { runnerId: deps.runnerId });
+    })();
+    return {
+        done,
+        drain: () => {
+            draining = true;
+        },
+    };
+}

package/dist/daemon/identity.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const runnerIdentitySchema: z.ZodObject<{
+    runner_id: z.ZodString;
+    runner_token: z.ZodString;
+    control_plane_url: z.ZodString;
+    pool: z.ZodString;
+    org: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    created_at: z.ZodNumber;
+}, z.core.$strict>;
+export type RunnerIdentity = z.infer<typeof runnerIdentitySchema>;
+export declare function defaultIdentityDir(): string;
+export declare function saveIdentity(dir: string, identity: RunnerIdentity): Promise<string>;
+export declare function loadIdentity(dir: string, controlPlaneUrl: string, pool: string): Promise<RunnerIdentity | null>;
+export declare function removeIdentity(dir: string, controlPlaneUrl: string, pool: string): Promise<void>;

package/dist/daemon/identity.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// Persisted runner identity — the standing credential + coordinates a machine keeps between
+// restarts (`runner start` after a reboot skips registration). One JSON file per
+// (control plane, pool), mode 0600: the runner token is a credential.
+import { mkdir, readFile, writeFile, unlink } from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { z } from "zod";
+export const runnerIdentitySchema = z.strictObject({
+    runner_id: z.string().min(1),
+    runner_token: z.string().min(1),
+    control_plane_url: z.string().url(),
+    pool: z.string().min(1),
+    /** Org slug, when known (the one-step CLI flow records it for display). */
+    org: z.string().optional(),
+    name: z.string().min(1),
+    created_at: z.number().int().nonnegative(),
+});
+export function defaultIdentityDir() {
+    return path.join(os.homedir(), ".boardwalk", "runner");
+}
+function identityFile(dir, controlPlaneUrl, pool) {
+    const host = new URL(controlPlaneUrl).host.replace(/[^A-Za-z0-9.-]/g, "_");
+    return path.join(dir, `${host}--${pool}.json`);
+}
+export async function saveIdentity(dir, identity) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const file = identityFile(dir, identity.control_plane_url, identity.pool);
+    await writeFile(file, `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 });
+    return file;
+}
+export async function loadIdentity(dir, controlPlaneUrl, pool) {
+    try {
+        const raw = await readFile(identityFile(dir, controlPlaneUrl, pool), "utf8");
+        const parsed = runnerIdentitySchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function removeIdentity(dir, controlPlaneUrl, pool) {
+    await unlink(identityFile(dir, controlPlaneUrl, pool)).catch(() => undefined);
+}

package/dist/daemon/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./pool_client.js";
+export * from "./identity.js";
+export * from "./daemon.js";

package/dist/daemon/index.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+export * from "./pool_client.js";
+export * from "./identity.js";
+export * from "./daemon.js";

package/dist/daemon/pool_client.d.ts

@@ -0,0 +1,31 @@
+import { type AssignmentPollResponse, type ClaimResponse, type HeartbeatResponse, type RunnerRegistrationRequest, type RunnerRegistrationResponse } from "../contract.js";
+export interface PoolClientConfig {
+    /** Control-plane origin, e.g. https://api.boardwalk.sh */
+    baseUrl: string;
+    /** The standing `bwkr_…` credential (absent only for `register`). */
+    runnerToken?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class PoolClientError extends Error {
+    readonly status: number;
+    readonly operation: string;
+    constructor(status: number, operation: string, message: string);
+}
+export declare class PoolClient {
+    private readonly cfg;
+    private readonly fetchImpl;
+    constructor(cfg: PoolClientConfig);
+    private url;
+    private headers;
+    /** Redeem a registration token (unauthenticated: the token in the body IS the credential). */
+    register(request: RunnerRegistrationRequest): Promise<RunnerRegistrationResponse>;
+    /** Long-poll for ONE credential-free offer (the server holds ~22s). */
+    poll(): Promise<AssignmentPollResponse>;
+    /** Race-safe claim. Null on 409 — another runner won; go back to polling. */
+    claim(assignmentId: string): Promise<ClaimResponse | null>;
+    /** Extend the assignment lease + receive the control signal. Null on 409 — lease lost:
+     *  the control plane recovered the assignment; discard local state. */
+    heartbeat(leaseId: string, runId: string, phase: "preparing" | "running" | "finalizing"): Promise<HeartbeatResponse | null>;
+    /** Permanent removal (decommissioning this machine). */
+    deregister(): Promise<void>;
+}

package/dist/daemon/pool_client.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// HTTP client for the control plane's pool-lease endpoints (runner/CONTRACT.md; the platform
+// serves them at /runner/v1/register + /runner/v1/pool/*). Every response is validated against
+// the published contract schemas — the daemon never trusts wire shapes.
+//
+// Corporate proxies: Node's fetch honors HTTPS_PROXY/https_proxy when the process starts with
+// NODE_USE_ENV_PROXY=1 (the CLI/bin wrappers set it; see the README).
+import { assignmentPollResponseSchema, claimResponseSchema, heartbeatResponseSchema, parseContract, runnerRegistrationResponseSchema, } from "../contract.js";
+export class PoolClientError extends Error {
+    status;
+    operation;
+    constructor(status, operation, message) {
+        super(`${operation} failed (${String(status)}): ${message}`);
+        this.status = status;
+        this.operation = operation;
+        this.name = "PoolClientError";
+    }
+}
+async function errorBody(res) {
+    try {
+        return (await res.text()).slice(0, 500);
+    }
+    catch {
+        return "<unreadable body>";
+    }
+}
+export class PoolClient {
+    cfg;
+    fetchImpl;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    url(path) {
+        return `${this.cfg.baseUrl.replace(/\/$/, "")}${path}`;
+    }
+    headers() {
+        const token = this.cfg.runnerToken;
+        if (token === undefined)
+            throw new Error("PoolClient has no runner token");
+        return { authorization: `Bearer ${token}`, "content-type": "application/json" };
+    }
+    /** Redeem a registration token (unauthenticated: the token in the body IS the credential). */
+    async register(request) {
+        const res = await this.fetchImpl(this.url("/runner/v1/register"), {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(request),
+        });
+        if (res.status !== 201) {
+            throw new PoolClientError(res.status, "register", await errorBody(res));
+        }
+        return parseContract(runnerRegistrationResponseSchema, await res.json(), "registration response");
+    }
+    /** Long-poll for ONE credential-free offer (the server holds ~22s). */
+    async poll() {
+        const res = await this.fetchImpl(this.url("/runner/v1/pool/poll"), {
+            method: "POST",
+            headers: this.headers(),
+            body: "{}",
+        });
+        if (res.status !== 200)
+            throw new PoolClientError(res.status, "poll", await errorBody(res));
+        return parseContract(assignmentPollResponseSchema, await res.json(), "poll response");
+    }
+    /** Race-safe claim. Null on 409 — another runner won; go back to polling. */
+    async claim(assignmentId) {
+        const res = await this.fetchImpl(this.url(`/runner/v1/pool/assignments/${encodeURIComponent(assignmentId)}/claim`), { method: "POST", headers: this.headers(), body: "{}" });
+        if (res.status === 409)
+            return null;
+        if (res.status !== 200)
+            throw new PoolClientError(res.status, "claim", await errorBody(res));
+        return parseContract(claimResponseSchema, await res.json(), "claim response");
+    }
+    /** Extend the assignment lease + receive the control signal. Null on 409 — lease lost:
+     *  the control plane recovered the assignment; discard local state. */
+    async heartbeat(leaseId, runId, phase) {
+        const res = await this.fetchImpl(this.url("/runner/v1/pool/heartbeat"), {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ lease_id: leaseId, run_id: runId, phase }),
+        });
+        if (res.status === 409)
+            return null;
+        if (res.status !== 200) {
+            throw new PoolClientError(res.status, "heartbeat", await errorBody(res));
+        }
+        return parseContract(heartbeatResponseSchema, await res.json(), "heartbeat response");
+    }
+    /** Permanent removal (decommissioning this machine). */
+    async deregister() {
+        const res = await this.fetchImpl(this.url("/runner/v1/pool/deregister"), {
+            method: "POST",
+            headers: this.headers(),
+            body: "{}",
+        });
+        if (res.status !== 204 && res.status !== 200) {
+            throw new PoolClientError(res.status, "deregister", await errorBody(res));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./contract.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+// @boardwalk-labs/runner — the self-hosted runner client (Phase 3).
+//
+// What exists today is the CONTRACT: the canonical registration / assignment / claim /
+// heartbeat / status payload schemas the runner and the Boardwalk control plane agree on.
+// The client implementation (register, poll, execute, stream) lands when Boardwalk self-hosted
+// runners ship; it will consume exactly these types.
+export * from "./contract.js";