harnery 0.8.0 → 0.10.0

package/src/core/workflow/spawn-claude.ts

@@ -0,0 +1,118 @@
+/**
+ * claude-code spawn adapter: runs one subagent as a headless `claude -p`
+ * subprocess with `--output-format json` and unwraps the result envelope.
+ *
+ * Two hard-won rules from the Phase 1 spike, both load-bearing:
+ *
+ * 1. **Scrub inherited `CLAUDE*` env vars — delete, don't blank.** A workflow
+ *    launched from inside a Claude Code session inherits session env that makes
+ *    the nested CLI exit 1 with empty output. Setting a var to "" still reads
+ *    as set; only deletion works.
+ * 2. **Mark the child as a workflow child instead of disabling hooks.** With
+ *    the host repo's hooks active, the coordination Stop hook blocks a headless
+ *    child for skipping the end-of-turn ritual (observed: num_turns burned on
+ *    re-prompts → error_max_turns). `--settings '{"disableAllHooks":true}'`
+ *    fixes that but also kills the coord capture that makes workflow children
+ *    visible to peers — the point of running them under harnery. So the child
+ *    gets HARNERY_WORKFLOW_CHILD=1 and the stop-hook rule exempts it
+ *    (stop-hook.ts), keeping heartbeats + events on.
+ */
+
+import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { buildChildEnv } from "./child-env.ts";
+import { notFoundError } from "./harnesses.ts";
+import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
+
+interface ClaudeEnvelope {
+  type?: string;
+  subtype?: string;
+  is_error?: boolean;
+  result?: string;
+  session_id?: string;
+  total_cost_usd?: number;
+  errors?: string[];
+}
+
+export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
+  validateHarnessEffort("claude-code", req.effort);
+  const argv = [
+    "claude",
+    "-p",
+    req.prompt,
+    "--output-format",
+    "json",
+    "--max-turns",
+    String(req.maxTurns),
+  ];
+  if (req.model) argv.push("--model", req.model);
+  if (req.effort) argv.push("--effort", req.effort);
+  return { argv };
+}
+
+export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("claude-code"),
+    };
+  }
+  if (raw.exitCode !== 0) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `claude exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
+    };
+  }
+
+  let envelope: ClaudeEnvelope;
+  try {
+    envelope = JSON.parse(raw.stdout) as ClaudeEnvelope;
+  } catch {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `result envelope was not JSON: ${raw.stdout.slice(0, 300)}`,
+    };
+  }
+
+  if (envelope.is_error) {
+    return {
+      ok: false,
+      text: String(envelope.result ?? ""),
+      sessionId: envelope.session_id,
+      costUsd: envelope.total_cost_usd,
+      durationMs: raw.durationMs,
+      error: `harness error (${envelope.subtype ?? "unknown"}): ${(envelope.errors ?? []).join("; ") || "see envelope"}`,
+    };
+  }
+
+  return {
+    ok: true,
+    text: String(envelope.result ?? ""),
+    sessionId: envelope.session_id,
+    costUsd: envelope.total_cost_usd,
+    durationMs: raw.durationMs,
+  };
+}
+
+export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  let invocation: HarnessInvocation;
+  try {
+    invocation = buildClaudeInvocation(req);
+  } catch (error) {
+    return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+  }
+  const r = await exec(invocation.argv, {
+    cwd: req.cwd,
+    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    timeout: req.timeoutMs,
+  });
+  return normalizeClaudeResult({ ...r, durationMs: Date.now() - t0 });
+};

package/src/core/workflow/spawn-codex.ts

@@ -0,0 +1,93 @@
+/**
+ * codex spawn adapter: runs one subagent as a headless `codex exec`
+ * subprocess.
+ *
+ * Contract notes (LIVE-VERIFIED 2026-07-16 against codex-cli 0.144.5: flags
+ * present, schema-gated triage + text stages round-trip via `--harness codex`):
+ * - `codex exec "<prompt>"` is the non-interactive mode.
+ * - The final assistant message is captured via `--output-last-message <file>`
+ *   (a temp file), which is far more drift-tolerant than parsing the
+ *   experimental `--json` JSONL event stream.
+ * - `--skip-git-repo-check` keeps non-repo cwds working; `--sandbox
+ *   workspace-write` matches workflow-stage expectations (children may edit).
+ * - No per-run cost or session-id surface in this mode → both left undefined.
+ * - No max-turns equivalent → `maxTurns` is accepted and ignored (documented
+ *   in the CLI docs page).
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { buildChildEnv } from "./child-env.ts";
+import { notFoundError } from "./harnesses.ts";
+import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
+
+export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): HarnessInvocation {
+  validateHarnessEffort("codex", req.effort);
+  if (!resultFile) throw new Error("codex adapter requires a final-message result file");
+  const argv = [
+    "codex",
+    "exec",
+    req.prompt,
+    "--output-last-message",
+    resultFile,
+    "--skip-git-repo-check",
+    "--sandbox",
+    "workspace-write",
+  ];
+  if (req.model) argv.push("--model", req.model);
+  if (req.effort) argv.push("-c", `model_reasoning_effort=${JSON.stringify(req.effort)}`);
+  return { argv, resultFile };
+}
+
+export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
+  }
+  if (raw.exitCode !== 0) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `codex exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
+    };
+  }
+  return {
+    ok: true,
+    text: (raw.resultFileText ?? raw.stdout).trim(),
+    durationMs: raw.durationMs,
+  };
+}
+
+export const codexSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  const outFile = join(
+    tmpdir(),
+    `harnery-codex-${process.pid}-${randomBytes(4).toString("hex")}.txt`,
+  );
+
+  try {
+    let invocation: HarnessInvocation;
+    try {
+      invocation = buildCodexInvocation(req, outFile);
+    } catch (error) {
+      return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+    }
+    const r = await exec(invocation.argv, {
+      cwd: req.cwd,
+      env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+      timeout: req.timeoutMs,
+    });
+    return normalizeCodexResult({
+      ...r,
+      durationMs: Date.now() - t0,
+      resultFileText: existsSync(outFile) ? readFileSync(outFile, "utf8") : undefined,
+    });
+  } finally {
+    rmSync(outFile, { force: true });
+  }
+};

package/src/core/workflow/spawn-cursor.ts

@@ -0,0 +1,108 @@
+/**
+ * cursor spawn adapter: runs one subagent as a headless `cursor-agent -p`
+ * subprocess with `--output-format json`.
+ *
+ * Contract notes (LIVE-VERIFIED 2026-07-17 against cursor-agent
+ * 2026.07.16-899851b: schema-gated triage + text stages round-trip via
+ * `--harness cursor`, session_id parses from the envelope):
+ * - `cursor-agent -p "<prompt>" --output-format json` prints a single result
+ *   envelope modeled on Claude Code's (`{type: "result", is_error, result,
+ *   session_id, …}`).
+ * - `--trust` is required: headless runs refuse untrusted workspaces (exit 1,
+ *   "Workspace Trust Required") — see the argv comment below.
+ * - Envelope drift guard: when stdout doesn't parse as JSON but the process
+ *   exited 0, the raw stdout is returned as the reply text.
+ * - No per-run cost surface → undefined. No max-turns equivalent → `maxTurns`
+ *   accepted and ignored (documented in the CLI docs page).
+ */
+
+import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
+import { buildChildEnv } from "./child-env.ts";
+import { notFoundError } from "./harnesses.ts";
+import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
+
+interface CursorEnvelope {
+  type?: string;
+  is_error?: boolean;
+  result?: string;
+  session_id?: string;
+}
+
+/** Exported for unit tests (no live binary to test against). */
+export function parseCursorOutput(stdout: string): {
+  text: string;
+  sessionId?: string;
+  isError: boolean;
+} {
+  try {
+    const envelope = JSON.parse(stdout) as CursorEnvelope;
+    return {
+      text: String(envelope.result ?? ""),
+      sessionId: envelope.session_id,
+      isError: Boolean(envelope.is_error),
+    };
+  } catch {
+    return { text: stdout, isError: false };
+  }
+}
+
+export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
+  validateHarnessEffort("cursor", req.effort);
+  // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
+  // "Workspace Trust Required"). Workflow children run in the engine's cwd
+  // deliberately and may edit files — the same posture as the codex adapter's
+  // `--sandbox workspace-write` — so trusting that directory is implied.
+  const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust"];
+  if (req.model) argv.push("--model", req.model);
+  return { argv };
+}
+
+export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
+  }
+  if (raw.exitCode !== 0) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `cursor-agent exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
+    };
+  }
+
+  const parsed = parseCursorOutput(raw.stdout);
+  if (parsed.isError) {
+    return {
+      ok: false,
+      text: parsed.text,
+      sessionId: parsed.sessionId,
+      durationMs: raw.durationMs,
+      error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
+    };
+  }
+  return {
+    ok: true,
+    text: parsed.text,
+    sessionId: parsed.sessionId,
+    durationMs: raw.durationMs,
+  };
+}
+
+export const cursorSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  let invocation: HarnessInvocation;
+  try {
+    invocation = buildCursorInvocation(req);
+  } catch (error) {
+    return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+  }
+
+  const r = await exec(invocation.argv, {
+    cwd: req.cwd,
+    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    timeout: req.timeoutMs,
+  });
+  return normalizeCursorResult({ ...r, durationMs: Date.now() - t0 });
+};

package/src/core/workflow/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+
+import type { BillingMode, BillingProber } from "./billing.ts";
+
+/** JSON-schema *subset* accepted by stage gates (see validate.ts). */
+export interface StageSchema {
+  type: "object" | "array" | "string" | "number" | "boolean";
+  /** type=object */
+  properties?: Record<string, StageSchema>;
+  required?: string[];
+  /** type=array */
+  items?: StageSchema;
+  /** any type: closed value set (compared with ===) */
+  enum?: Array<string | number | boolean>;
+}
+
+export interface AgentOpts {
+  /** Stage gate: when present, the agent's reply must strict-parse as JSON and
+   * validate; the engine retries with the validation error appended, up to
+   * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
+  schema?: StageSchema;
+  /** Model slug passed through to the harness CLI (default: the CLI's default). */
+  model?: string;
+  /** Reasoning effort mapped through the selected harness profile. Unsupported
+   * values fail before the vendor process starts. */
+  effort?: string;
+  /** Attempt ceiling for the schema-retry loop (default 2). */
+  maxAttempts?: number;
+  /** Subprocess timeout ms (default 300_000). */
+  timeoutMs?: number;
+  /** Harness-turn ceiling for the child (default 25; use 1 for pure
+   * classification stages — cheaper and faster). */
+  maxTurns?: number;
+  /** Display label in the journal (default: prompt head). */
+  label?: string;
+  /** Which harness runs this agent (default: the run's default harness).
+   * Mixed-harness workflows are legal: triage on one CLI, deep work on
+   * another. */
+  harness?: HarnessName;
+}
+
+/** Open registry key. The built-in catalog currently contains Claude Code,
+ * Codex, and Cursor; consumers may register another adapter without widening
+ * a package-owned union first. */
+export type HarnessName = string;
+
+/** What a spawn adapter returns for one subagent run. */
+export interface SpawnResult {
+  ok: boolean;
+  /** The model's final reply text (envelope-unwrapped). */
+  text: string;
+  /** Child harness session id when the envelope carries one. */
+  sessionId?: string;
+  costUsd?: number;
+  durationMs: number;
+  /** Populated when ok=false. */
+  error?: string;
+}
+
+export interface SpawnRequest {
+  prompt: string;
+  model?: string;
+  effort?: string;
+  timeoutMs: number;
+  maxTurns: number;
+  cwd: string;
+  /** Run id, stamped into the child env (HARNERY_WORKFLOW_RUN_ID) so the
+   * coord layer can associate child sessions with their workflow run. */
+  runId?: string;
+  /** Scrub all API-key vars from the child env so it can only authenticate
+   * via its stored (subscription) login. See billing.ts. */
+  subscriptionOnly?: boolean;
+}
+
+/** One headless-subagent runner. The engine is adapter-agnostic; claude-code
+ * ships first, codex/cursor land behind the same signature (plan Phase 4). */
+export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
+
+/** The API surface injected into a workflow script's default export. Explicit
+ * injection (no ambient globals): keeps scripts portable and unit-testable. */
+export interface WorkflowContext {
+  /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
+  agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
+  /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
+  parallel: <T>(thunks: Array<() => Promise<T>>) => Promise<Array<T | null>>;
+  /** Declare the current stage (journal + progress grouping). */
+  stage: (title: string) => void;
+  /** Narrate progress (stderr + journal). */
+  log: (message: string) => void;
+}
+
+export interface WorkflowMeta {
+  name: string;
+  description?: string;
+}
+
+/** Loaded script shape: `export const meta` + `export default async (ctx) => …`. */
+export interface WorkflowModule {
+  meta?: WorkflowMeta;
+  default: (ctx: WorkflowContext) => Promise<unknown>;
+}
+
+export interface EngineOpts {
+  /** Repo root whose .harnery/ receives the run journal. */
+  coordRoot: string;
+  /** Spawner registry keyed by harness. A single-harness caller registers one
+   * entry and names it in `defaultHarness`. */
+  spawners: Readonly<Record<HarnessName, Spawner | undefined>>;
+  /** Harness used when an agent() call doesn't name one (default "claude-code"). */
+  defaultHarness?: HarnessName;
+  /** Resume: run id of a prior run whose journal supplies cached results.
+   * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
+   * completed prior agent return the journaled result without spawning. */
+  resumeFrom?: string;
+  /** Total-agent ceiling for the run (default 50): the runaway backstop. */
+  maxAgents?: number;
+  /** Concurrent-subagent cap for parallel() (default 4). */
+  concurrency?: number;
+  /** Working directory children spawn in (default: coordRoot). */
+  cwd?: string;
+  /** Progress sink (default: process.stderr). */
+  onLog?: (line: string) => void;
+  /** Guarantee subscription billing: API-key vars are scrubbed from every
+   * child env, and a harness whose stored login is provably absent fails
+   * loud before spawning. */
+  subscriptionOnly?: boolean;
+  /** Permit the api-key-override billing state (an exported API key silently
+   * shadowing a stored subscription login), which the engine otherwise
+   * refuses. Deliberate key-only hosts don't need this — only the
+   * both-present case does. */
+  allowApiBilling?: boolean;
+  /** Billing-probe override for tests (default: the real probeBilling). */
+  probeBilling?: BillingProber;
+}
+
+export interface RunReport {
+  runId: string;
+  name: string;
+  /** What the script's default export returned. */
+  result: unknown;
+  agentsSpawned: number;
+  /** agent() calls satisfied from the resumeFrom journal without spawning. */
+  agentsCached: number;
+  costUsd: number;
+  durationMs: number;
+  journalPath: string;
+  /** Estimated tokens of repo instructions (CLAUDE.md/AGENTS.md at the child
+   * cwd) that EVERY child cache-writes on spawn — the fixed per-child context
+   * overhead a fan-out multiplies. bytes/4 heuristic; 0 when no such file. */
+  contextTokensPerChildEstimate: number;
+  /** Billing mode per harness actually used this run (probed on first use). */
+  billing: Array<{ harness: HarnessName; mode: BillingMode }>;
+}

package/src/core/workflow/validate.ts

@@ -0,0 +1,75 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+
+import type { StageSchema } from "./types.ts";
+
+export function validateAgainstSchema(value: unknown, schema: StageSchema, path = "$"): string[] {
+  const problems: string[] = [];
+
+  if (schema.enum) {
+    if (!schema.enum.some((v) => v === value)) {
+      problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}, got ${short(value)}`);
+    }
+    return problems; // enum is exhaustive; type check is implied by membership
+  }
+
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [`${path}: expected object, got ${short(value)}`];
+      }
+      const obj = value as Record<string, unknown>;
+      for (const key of schema.required ?? []) {
+        if (!(key in obj)) problems.push(`${path}.${key}: required property missing`);
+      }
+      for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+        if (key in obj) problems.push(...validateAgainstSchema(obj[key], sub, `${path}.${key}`));
+      }
+      return problems;
+    }
+    case "array": {
+      if (!Array.isArray(value)) return [`${path}: expected array, got ${short(value)}`];
+      if (schema.items) {
+        for (const [i, item] of value.entries()) {
+          problems.push(
+            ...validateAgainstSchema(item, schema.items as StageSchema, `${path}[${i}]`),
+          );
+        }
+      }
+      return problems;
+    }
+    case "string":
+    case "number":
+    case "boolean": {
+      if (typeof value !== schema.type) {
+        problems.push(`${path}: expected ${schema.type}, got ${short(value)}`);
+      }
+      return problems;
+    }
+    default:
+      return [`${path}: unsupported schema type ${String((schema as { type?: unknown }).type)}`];
+  }
+}
+
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export function parseStageOutput(text: string): { value?: unknown; error?: string } {
+  const stripped = text
+    .trim()
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/, "");
+  try {
+    return { value: JSON.parse(stripped) };
+  } catch (err) {
+    return { error: `not valid JSON: ${(err as Error).message}` };
+  }
+}
+
+function short(value: unknown): string {
+  const s = JSON.stringify(value);
+  return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}

package/src/lib/browser/client.ts

@@ -74,6 +74,14 @@ export interface BrowserOptions {
    * via this callback (e.g., a Cloudflare-bypass header for specific zones).
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Extra Chromium command-line flags, passed through to Playwright's
+   * `launchPersistentContext` `args`. Used for environment-specific
+   * workarounds — most notably `--disable-gpu` for headed windows under
+   * WSLg (see `./launch-args.ts`). Empty/undefined means Playwright's
+   * defaults only.
+   */
+  launchArgs?: string[];
 }
 
 export interface NavigateResult {
@@ -98,6 +106,14 @@ export interface FailedRequest {
   method: string;
   failure: string;
   resourceType: string;
+  /** HTTP status for kind "http" entries; null for network-level failures. */
+  status: number | null;
+  /** "http" = request completed with a >=400 response; "network" = never completed (DNS, TLS, aborts, tunnel). */
+  kind: "http" | "network";
+  /** True when the entry is the main frame's document response — lets consumers
+   *  distinguish an expected error-page status (a 404 route under test) from a
+   *  broken subresource. */
+  document?: boolean;
 }
 
 export interface Diagnostics {
@@ -137,6 +153,9 @@ export class Browser {
     this.context = await chromium.launchPersistentContext(this.profileDir, {
       headless: !this.opts.headed,
       viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+      ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
+        ? { args: this.opts.launchArgs }
+        : {}),
       ...(this.opts.recordHarPath
         ? { recordHar: { path: this.opts.recordHarPath, mode: "full" as const } }
         : {}),
@@ -192,6 +211,24 @@ export class Browser {
         method: req.method(),
         failure: req.failure()?.errorText ?? "unknown",
         resourceType: req.resourceType(),
+        status: null,
+        kind: "network",
+      });
+    });
+    // HTTP-level failures: `requestfailed` only fires for requests that never
+    // complete (DNS, TLS, aborts), so a script/stylesheet answered with a
+    // 4xx/5xx would otherwise be invisible to failedRequests-based gates.
+    page.on("response", (res) => {
+      if (res.status() < 400) return;
+      const req = res.request();
+      this.failedRequests.push({
+        url: res.url(),
+        method: req.method(),
+        failure: `HTTP ${res.status()}`,
+        resourceType: req.resourceType(),
+        status: res.status(),
+        kind: "http",
+        document: req.resourceType() === "document" && res.frame() === page.mainFrame(),
       });
     });
   }

package/src/lib/browser/index.ts

@@ -12,6 +12,7 @@ export {
   type DevOverlayError,
   type DevOverlayResult,
 } from "./dev-overlay.js";
+export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type {
   OverflowElement,
   OverflowResult,

package/src/lib/browser/launch-args.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Chromium launch-arg helpers for environment-specific workarounds.
+ *
+ * The one that matters today is WSLg: a headed Chromium window renders its
+ * page to a GPU-backed surface that WSLg composites over an RDP stream to the
+ * Windows host. On a range of Windows / GPU-driver / WSLg combinations that
+ * GPU-composited surface never presents, so the window shows in the taskbar
+ * but paints blank — even though the page itself runs fine (JS, navigation,
+ * and DOM all work). Forcing Chromium onto its software compositor with
+ * `--disable-gpu` restores on-screen paint. It only matters for headed mode
+ * (headless never composites to a display) and only under WSL.
+ */
+
+/** True when running under WSL (WSL1 or WSL2). */
+export function isWSL(): boolean {
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Chromium launch flags to make a headed window paint under WSLg. Returns
+ * `["--disable-gpu"]` on WSL, `[]` elsewhere. Callers apply these only for
+ * headed launches. See the module doc for the failure mode.
+ */
+export function wslHeadedLaunchArgs(): string[] {
+  return isWSL() ? ["--disable-gpu"] : [];
+}