@valescoagency/runway 0.4.0 → 0.5.0

package/README.md

@@ -44,14 +44,23 @@ Linear (Todo, team=VA)
 runway (this CLI, on your Mac, run from inside the target repo)
   ↓ for each issue
   │   sandcastle.run({ agent: claudeCode, sandbox: docker, cwd: process.cwd(), ... })
+  │     iter 1 → IMPL: DONE | IMPL: BLOCKED — <reason> | IMPL: CONTINUE
+  │     iter 2 → same, with previous iteration's summary injected
+  │     …
   │   → branch agent/<issue-id>, commits, tests
   │
-  │   sandcastle.run({ ..., prompt: review template })
-  │   → REVIEW: APPROVED  | REVIEW: REJECTED — <reason>
+  │   if BLOCKED → HITL (skip review)
+  │   else:
+  │     sandcastle.run({ ..., prompt: review template })
+  │     → REVIEW: APPROVED  | REVIEW: REJECTED — <reason>
   │
   ├── approved  → git push → gh pr create → Linear "In Review"
-  └── rejected  → Linear label "ready-for-human", comment with reason
+  └── rejected  → Linear comment with reason, then `ready-for-human` label
   ↓ next issue
+
+[runway] per-issue outcomes:
+  VA-312  APPROVED → PR opened  https://github.com/.../pull/42
+  VA-313  HITL                  Sub-agent review rejected: TOCTOU race in …
 ```
 
 ## Prerequisites
@@ -237,8 +246,11 @@ invocation — re-run runway after fixing the underlying config to retry
 it.
 
 The CLI exits with 0 even if some issues hit HITL or errored — those
-are normal outcomes. Check Linear for the `ready-for-human` label and the
-per-issue comments for what happened.
+are normal outcomes. Every run prints a per-issue verdict trail on
+exit (`APPROVED → PR opened <url>` / `HITL <reason>` /
+`REVERTED → Todo <reason>` / `INFRA_ERROR <reason>`) so you can scan
+results without opening Linear; the same content also lives on the
+issue as a Linear comment.
 
 ## Linear conventions
 
@@ -262,6 +274,48 @@ These names are configurable per env var; the queries match by name so
 your Linear workspace's actual state names need to line up with what
 you set.
 
+## Write-path policy
+
+Runway tells the impl agent which paths it must **not** write to. By
+default the denylist is:
+
+```
+.github/workflows/**   .env*   *.pem   *.key   pnpm-lock.yaml   .sandcastle/**
+```
+
+When an issue's acceptance criteria require modifying a forbidden path,
+the agent is instructed to emit `IMPL: BLOCKED — issue requires
+modifying <path>, which working-style policy forbids` rather than
+silently skipping the work. Runway routes those to HITL with the
+reason attached.
+
+Two layers of override:
+
+**Per repo** — drop a `.runway/policy.yml` in the target repo root:
+
+```yaml
+# Grants write access to specific paths from the default denylist.
+allowedPaths:
+  - .github/workflows/**
+
+# Or replace the denylist entirely (use with care).
+# forbiddenPaths:
+#   - .env*
+#   - "*.pem"
+```
+
+**Per invocation** — comma-separated globs, removed from the effective
+denylist for one `runway run`:
+
+```bash
+runway run --allow-paths='.github/workflows/**'
+runway run --allow-paths='.github/workflows/**,scripts/ci/*.sh'
+```
+
+`runway doctor` surfaces the active policy under Environment so you
+can see what an agent run can and can't touch (e.g. `impl policy:
+.runway/policy.yml + --allow-paths (5 forbidden paths)`).
+
 ## Base branch
 
 Runway auto-detects the repo's default branch at the start of every
@@ -277,6 +331,30 @@ when `origin/HEAD` isn't set and you don't want to run
 resolved base branch (detected or overridden) in its Environment
 section.
 
+## Implementation pass
+
+The impl agent runs in a Sandcastle container with
+[`prompts/implement.md`](prompts/implement.md). It iterates up to
+`RUNWAY_MAX_ITERATIONS` times (default 5) and must end every iteration
+with one of:
+
+```
+IMPL: DONE
+IMPL: BLOCKED — <one-line reason>
+IMPL: CONTINUE
+```
+
+- `DONE` → runway stops the loop and runs the sub-agent reviewer.
+- `BLOCKED — <reason>` → runway routes the issue to HITL with the
+  reason attached; the reviewer pass does **not** run.
+- `CONTINUE` → runway runs another iteration (up to `maxIterations`).
+
+Between iterations, runway prepends a `## Previous iterations` block
+to the next prompt — running commit log + tail of the last iteration's
+final message — so the agent doesn't re-explore the repository from
+scratch every time. Converged issues typically exit after 1–2
+iterations.
+
 ## Sub-agent review
 
 Every implementation run is followed by a fresh Sandcastle run with
@@ -306,4 +384,7 @@ These are tractable, just not v1.
 
 ## Status
 
-v0.1 — scaffold complete, untested against a live queue.
+0.5.0 — production-shaped and dogfooded against live Linear queues.
+The end-to-end pipeline (init → run → review → PR) is stable; surface
+may still shift as the orchestrator's policy and iteration mechanics
+mature. See [CHANGELOG.md](./CHANGELOG.md) for per-release detail.

package/dist/commands/run.js

@@ -1,7 +1,9 @@
-import { loadConfig } from "../config.js";
+import { Effect, Layer, Logger, RateLimiter } from "effect";
+import { ConfigLive, ConfigTag } from "../config.js";
 import { createLinearGateway } from "../linear.js";
 import { createGithubGateway } from "../github.js";
 import { assertSandcastleInitialised, drainQueue, } from "../orchestrator.js";
+import { TelemetryLive } from "../telemetry.js";
 export function parseRunArgs(argv) {
     const opts = {};
     const collectAllow = (raw) => {
@@ -98,16 +100,41 @@ export async function runCommand(argv) {
     const opts = parseRunArgs(argv);
     const cwd = process.cwd();
     assertSandcastleInitialised(cwd);
-    const baseConfig = loadConfig();
-    const config = opts.project
-        ? { ...baseConfig, linearProject: opts.project }
-        : baseConfig;
-    const linear = createLinearGateway(config);
-    const github = createGithubGateway();
-    const scope = config.linearProject
-        ? `team ${config.linearTeam} / project ${config.linearProject}`
-        : `team ${config.linearTeam}`;
-    console.log(`[runway] draining queue from ${scope} (status="${config.readyStatus}") against ${cwd}`);
-    const result = await drainQueue({ config, linear, github, cwd }, { max: opts.max, allowPaths: opts.allowPaths });
+    // VA-358 / VA-359: a single `Effect.runPromise` at the CLI
+    // boundary. Composed layers:
+    //
+    // - `ConfigLive` (VA-359) resolves every env var via Effect's
+    //   `Config` module. Secrets (LINEAR_API_KEY,
+    //   OP_SERVICE_ACCOUNT_TOKEN) are `Redacted<string>` and won't
+    //   appear in `Effect.log` output or stringified errors.
+    // - `Logger.jsonLogger` is wired when `RUNWAY_JSON_LOGS=1` so the
+    //   operator can pipe runway's output to a log aggregator.
+    // - `TelemetryLive` (VA-358) is env-conditional — only wires the
+    //   OTLP exporter when `OTEL_EXPORTER_OTLP_ENDPOINT` is set.
+    // - Linear `RateLimiter` (folded in from VA-357): conservative
+    //   30/minute, built inside `Effect.scoped` so its internals are
+    //   torn down on program exit.
+    const LoggerLive = process.env.RUNWAY_JSON_LOGS === "1"
+        ? Logger.replace(Logger.defaultLogger, Logger.jsonLogger)
+        : Layer.empty;
+    const MainLayer = Layer.mergeAll(ConfigLive, TelemetryLive, LoggerLive);
+    const program = Effect.gen(function* () {
+        const baseConfig = yield* ConfigTag;
+        const config = opts.project
+            ? { ...baseConfig, linearProject: opts.project }
+            : baseConfig;
+        const scope = config.linearProject
+            ? `team ${config.linearTeam} / project ${config.linearProject}`
+            : `team ${config.linearTeam}`;
+        yield* Effect.logInfo(`draining queue from ${scope} (status="${config.readyStatus}") against ${cwd}`);
+        const linearLimiter = yield* RateLimiter.make({
+            limit: 30,
+            interval: "1 minute",
+        });
+        const linear = createLinearGateway(config, linearLimiter);
+        const github = createGithubGateway();
+        return yield* drainQueue({ config, linear, github, cwd }, { max: opts.max, allowPaths: opts.allowPaths });
+    }).pipe(Effect.scoped, Effect.provide(MainLayer));
+    const result = await Effect.runPromise(program);
     console.log(`[runway] done — attempts=${result.attempts} opened=${result.opened} hitl=${result.hitl} errored=${result.errored}`);
 }

package/dist/config.js

@@ -1,71 +1,57 @@
-import { z } from "zod";
+import { Config as EConfig, Context, Effect, Layer, Option, } from "effect";
 /**
- * Runway runtime config. Loaded from process.env at startup. We fail
- * fast if a required value is missing — no point starting the loop and
- * blowing up halfway through an issue.
- *
- * Notable absences vs. typical agent runners:
- *   - No ANTHROPIC_API_KEY here. Sandcastle reads it from the target
- *     repo's `.sandcastle/.env` per its own conventions.
- *   - No GH_TOKEN here. We use the `gh` CLI for PR creation; if the
- *     user is logged in (`gh auth status`), it Just Works. If they
- *     aren't, `gh pr create` errors out with a clear message — no need
- *     for runway to second-guess.
- *   - No RUNWAY_TARGET_REPO. Runway runs from inside the target repo
- *     (`process.cwd()`), the same way `sandcastle run` does.
+ * VA-359: Effect.Config program that reads every var from
+ * `process.env`, applies defaults, and yields a typed `RunwayConfig`.
+ * The `Option<T>` returns from `Config.option(...)` are flattened to
+ * `T | undefined` in the final shape so consumers don't have to
+ * import `Option` everywhere.
+ */
+const configEffect = EConfig.all({
+    linearApiKey: EConfig.redacted("LINEAR_API_KEY"),
+    opServiceAccountToken: EConfig.option(EConfig.redacted("OP_SERVICE_ACCOUNT_TOKEN")),
+    linearTeam: EConfig.string("RUNWAY_LINEAR_TEAM").pipe(EConfig.withDefault("VA")),
+    linearProject: EConfig.option(EConfig.string("RUNWAY_LINEAR_PROJECT")),
+    baseBranch: EConfig.option(EConfig.string("RUNWAY_BASE_BRANCH")),
+    readyStatus: EConfig.string("RUNWAY_READY_STATUS").pipe(EConfig.withDefault("Todo")),
+    inProgressStatus: EConfig.string("RUNWAY_IN_PROGRESS_STATUS").pipe(EConfig.withDefault("In Progress")),
+    inReviewStatus: EConfig.string("RUNWAY_IN_REVIEW_STATUS").pipe(EConfig.withDefault("In Review")),
+    hitlLabel: EConfig.string("RUNWAY_HITL_LABEL").pipe(EConfig.withDefault("ready-for-human")),
+    maxIterations: EConfig.integer("RUNWAY_MAX_ITERATIONS").pipe(EConfig.withDefault(5), EConfig.validate({
+        message: "RUNWAY_MAX_ITERATIONS must be a positive integer",
+        validation: (n) => n > 0,
+    })),
+}).pipe(Effect.map((raw) => ({
+    linearApiKey: raw.linearApiKey,
+    opServiceAccountToken: Option.getOrUndefined(raw.opServiceAccountToken),
+    linearTeam: raw.linearTeam,
+    linearProject: Option.getOrUndefined(raw.linearProject),
+    baseBranch: Option.getOrUndefined(raw.baseBranch),
+    readyStatus: raw.readyStatus,
+    inProgressStatus: raw.inProgressStatus,
+    inReviewStatus: raw.inReviewStatus,
+    hitlLabel: raw.hitlLabel,
+    maxIterations: raw.maxIterations,
+})));
+/**
+ * VA-359: Context tag for the resolved RunwayConfig. Provided by
+ * `ConfigLive` at the top of every CLI entry point; consumed by
+ * `yield* ConfigTag` inside Effect.gen.
+ */
+export class ConfigTag extends Context.Tag("RunwayConfig")() {
+}
+/**
+ * Layer that resolves env vars once and makes the result available
+ * via `ConfigTag` for the rest of the program.
+ */
+export const ConfigLive = Layer.effect(ConfigTag, configEffect);
+/**
+ * Sync helper for non-Effect callers (`runway doctor` early
+ * validation, the `runway run` CLI bootstrap before it enters
+ * Effect-land). `Effect.runSync` throws a `FiberFailure` carrying
+ * the `ConfigError` on a missing/invalid env var — the caller's
+ * existing `catch (err) { … errMsg(err) … }` shape rendered the
+ * Zod issue the same way it'll now render the Effect ConfigError.
  */
-const ConfigSchema = z.object({
-    linearApiKey: z.string().min(1, "LINEAR_API_KEY required"),
-    /**
-     * Optional. If present, forwarded into the sandcastle container so
-     * the in-container varlock + 1Password-CLI shim can resolve agent
-     * secrets at run time. If absent, the container falls back to
-     * sandcastle's normal `.sandcastle/.env` flow. See
-     * docs/secrets-with-varlock.md.
-     */
-    opServiceAccountToken: z.string().optional(),
-    linearTeam: z.string().default("VA"),
-    /**
-     * Optional. Scopes the `runway run` queue to a single project under
-     * `linearTeam`. Resolved by Linear project ID, slug, or name. When
-     * unset, runway drains every `Todo` issue on the team (legacy
-     * behavior). Source: `RUNWAY_LINEAR_PROJECT` env var or
-     * `--project` CLI flag on `runway run`.
-     */
-    linearProject: z.string().optional(),
-    /**
-     * Optional. Override the auto-detected base branch — the branch
-     * runway diffs against, opens PRs against, and uses to count
-     * agent-branch commits. Source: `RUNWAY_BASE_BRANCH` env var. When
-     * unset, runway resolves the default branch from `origin/HEAD` at
-     * orchestrator startup. Set this when the repo's default branch is
-     * not on the origin (rare) or when you want to target a release
-     * branch instead.
-     */
-    baseBranch: z.string().optional(),
-    readyStatus: z.string().default("Todo"),
-    inProgressStatus: z.string().default("In Progress"),
-    inReviewStatus: z.string().default("In Review"),
-    // VA-354: default to the Flightplan canonical state label
-    // `ready-for-human`. The previous default (`needs-human`) doesn't
-    // exist on Flightplan-aligned Linear workspaces (the common case
-    // for Valesco repos), and `linear.applyLabel` failures cascaded
-    // into the substantive rejection reason being lost. Workspaces that
-    // use a different label override via `RUNWAY_HITL_LABEL`.
-    hitlLabel: z.string().default("ready-for-human"),
-    maxIterations: z.coerce.number().int().positive().default(5),
-});
 export function loadConfig() {
-    return ConfigSchema.parse({
-        linearApiKey: process.env.LINEAR_API_KEY,
-        opServiceAccountToken: process.env.OP_SERVICE_ACCOUNT_TOKEN,
-        linearTeam: process.env.RUNWAY_LINEAR_TEAM,
-        linearProject: process.env.RUNWAY_LINEAR_PROJECT,
-        baseBranch: process.env.RUNWAY_BASE_BRANCH,
-        readyStatus: process.env.RUNWAY_READY_STATUS,
-        inProgressStatus: process.env.RUNWAY_IN_PROGRESS_STATUS,
-        inReviewStatus: process.env.RUNWAY_IN_REVIEW_STATUS,
-        hitlLabel: process.env.RUNWAY_HITL_LABEL,
-        maxIterations: process.env.RUNWAY_MAX_ITERATIONS,
-    });
+    return Effect.runSync(configEffect);
 }

package/dist/git.js

@@ -1,4 +1,15 @@
-import { execa } from "execa";
+import { Data, Effect } from "effect";
+import { runExecaScoped } from "./subprocess.js";
+/**
+ * VA-358: thin typed error for `detectBaseBranch`. We don't model
+ * every git failure mode — the orchestrator just wants to know "did
+ * we get a branch name back?" If not, surface a single error so the
+ * caller can fail fast with a helpful message. As a `Data.TaggedError`
+ * it's an Error instance, so vitest's `.rejects.toThrow(/regex/)`
+ * works the same as before this refactor.
+ */
+export class BaseBranchDetectionFailed extends Data.TaggedError("BaseBranchDetectionFailed") {
+}
 /**
  * Resolve the default branch name of the cwd repo. Tries
  * `git symbolic-ref` against `origin/HEAD` first (fast, works on any
@@ -6,36 +17,39 @@ import { execa } from "execa";
  * `git remote show origin` (slower, hits the network but works on
  * fresh clones that never had `origin/HEAD` set locally).
  *
- * Throws if neither path resolves a branch name — better to fail
- * fast at orchestrator startup than to crash mid-diff with a stale
- * "ambiguous argument" git error.
+ * VA-358: now an Effect so the orchestrator program can stay in
+ * Effect-land end-to-end. Subprocess kills propagate via
+ * `runExecaScoped` if the orchestrator fiber is interrupted.
  */
-export async function detectBaseBranch(repoPath) {
-    // Fast path: local symbolic ref. Returns e.g. `origin/main` or `origin/master`.
-    try {
-        const { stdout, exitCode } = await execa("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: repoPath, reject: false });
-        if (exitCode === 0) {
-            const name = stdout.trim().replace(/^origin\//, "");
-            if (name)
-                return name;
-        }
+export const detectBaseBranch = (repoPath) => Effect.gen(function* () {
+    // Fast path: local symbolic ref. Returns e.g. `origin/main`.
+    const symbolic = yield* runExecaScoped("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], { cwd: repoPath, reject: false }, (err) => new BaseBranchDetectionFailed({
+        message: err instanceof Error ? err.message : String(err),
+    })).pipe(Effect.either);
+    if (symbolic._tag === "Right" && symbolic.right.exitCode === 0) {
+        // execa's `stdout` type is a union (encoding-dependent). We don't
+        // change `encoding`, so it's `string` at runtime — narrow here
+        // rather than fighting the generic types upstream.
+        const raw = symbolic.right.stdout;
+        const out = typeof raw === "string" ? raw : "";
+        const name = out.trim().replace(/^origin\//, "");
+        if (name)
+            return name;
     }
-    catch {
-        // fall through to remote-show fallback
-    }
-    // Slow path: ask the remote. Output line looks like `  HEAD branch: master`.
-    try {
-        const { stdout } = await execa("git", ["remote", "show", "origin"], {
-            cwd: repoPath,
-        });
-        const match = stdout.match(/^\s*HEAD branch:\s*(\S+)\s*$/m);
+    // Slow path: ask the remote. Output line: `  HEAD branch: master`.
+    const remoteShow = yield* runExecaScoped("git", ["remote", "show", "origin"], { cwd: repoPath }, (err) => new BaseBranchDetectionFailed({
+        message: err instanceof Error ? err.message : String(err),
+    })).pipe(Effect.either);
+    if (remoteShow._tag === "Right") {
+        const raw = remoteShow.right.stdout;
+        const out = typeof raw === "string" ? raw : "";
+        const match = out.match(/^\s*HEAD branch:\s*(\S+)\s*$/m);
         if (match?.[1])
             return match[1];
     }
-    catch {
-        // fall through to error
-    }
-    throw new Error(`Could not detect the default branch of ${repoPath}. ` +
-        `Set RUNWAY_BASE_BRANCH explicitly, or run ` +
-        `\`git remote set-head origin --auto\` to populate origin/HEAD.`);
-}
+    return yield* Effect.fail(new BaseBranchDetectionFailed({
+        message: `Could not detect the default branch of ${repoPath}. ` +
+            `Set RUNWAY_BASE_BRANCH explicitly, or run ` +
+            `\`git remote set-head origin --auto\` to populate origin/HEAD.`,
+    }));
+});

package/dist/github.js

@@ -1,4 +1,70 @@
+import { Data, Effect, Schedule } from "effect";
 import { execa } from "execa";
+// VA-356: typed error ADT for the GitHub gateway. `GhCliMissing` is
+// its own branch so the orchestrator (and `runway doctor`) can show
+// an install hint instead of an opaque ENOENT. Push and PR failures
+// are split because retry semantics differ — re-pushing the same
+// branch is idempotent, re-running `gh pr create` after a partial
+// failure can create duplicate PRs.
+export class GhCliMissing extends Data.TaggedError("GhCliMissing") {
+}
+export class PushFailed extends Data.TaggedError("PushFailed") {
+}
+export class PrCreateFailed extends Data.TaggedError("PrCreateFailed") {
+}
+// VA-357: a hung `gh` or `git` subprocess becomes a typed timeout.
+// Step 3 (VA-358) is where we add scoped subprocess cleanup; here the
+// Effect's fiber gets interrupted but the underlying child may still
+// be running. We accept that limitation for Step 2.
+export class GithubTimeout extends Data.TaggedError("GithubTimeout") {
+}
+// VA-357: same jittered exponential shape as the Linear policy.
+export const githubRetrySchedule = Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5)), Schedule.jittered);
+/**
+ * VA-357: timeout + optional retry policy for a GitHub call. Unlike
+ * Linear (where all methods are idempotent reads or idempotent
+ * updates), GitHub differs by method:
+ *
+ * - `push` is idempotent (re-pushing the same SHA is a no-op) ⇒ retry
+ *   on timeout.
+ * - `gh pr create` is NOT idempotent — a retry after a partial failure
+ *   can create a duplicate PR. Just bound it with a timeout, no
+ *   retries.
+ *
+ * The caller picks the policy by passing a `retryOn` predicate (or
+ * omitting it for timeout-only).
+ */
+export const applyGithubPolicy = (effect, opts) => {
+    const withTimeout = effect.pipe(Effect.timeoutFail({
+        duration: `${opts.timeoutMs} millis`,
+        onTimeout: () => new GithubTimeout({
+            call: opts.call,
+            afterMs: opts.timeoutMs,
+            message: `${opts.call} timed out after ${opts.timeoutMs}ms`,
+        }),
+    }));
+    if (!opts.retryOn)
+        return withTimeout;
+    return withTimeout.pipe(Effect.retry({
+        schedule: githubRetrySchedule,
+        while: opts.retryOn,
+    }));
+};
+function isCommandMissing(err) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    if (e.code === "ENOENT")
+        return true;
+    return /\bcommand not found\b|: not found/i.test(e.message);
+}
+function execaStderr(err) {
+    if (err && typeof err === "object" && "stderr" in err) {
+        const s = err.stderr;
+        return typeof s === "string" ? s : "";
+    }
+    return "";
+}
 /**
  * `gh` CLI-backed gateway. Runway runs on a host with `gh` authenticated
  * (via `GH_TOKEN` or the user's keychain login); we don't reimplement
@@ -6,29 +72,78 @@ import { execa } from "execa";
  */
 export function createGithubGateway() {
     return {
-        async pushBranch(repoPath, branch) {
-            await execa("git", ["push", "-u", "origin", branch], {
-                cwd: repoPath,
-                stdio: "inherit",
+        pushBranch(repoPath, branch) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    await execa("git", ["push", "-u", "origin", branch], {
+                        cwd: repoPath,
+                        stdio: "inherit",
+                    });
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `git not found on PATH: ${err instanceof Error ? err.message : String(err)}`,
+                        });
+                    }
+                    return new PushFailed({
+                        branch,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `push failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `pushBranch(${branch})`,
+                // `git push` can be slow for large branches on slow networks.
+                timeoutMs: 60_000,
+                // Push is idempotent; retry on timeout only. We don't retry
+                // PushFailed because a real failure (auth, conflict) won't
+                // resolve itself.
+                retryOn: (err) => err._tag === "GithubTimeout",
             });
         },
-        async openPullRequest({ repoPath, branch, base, issue, body }) {
-            const title = `${issue.identifier}: ${issue.title}`;
-            const { stdout } = await execa("gh", [
-                "pr",
-                "create",
-                "--base",
-                base,
-                "--head",
-                branch,
-                "--title",
-                title,
-                "--body",
-                body,
-            ], { cwd: repoPath });
-            // `gh pr create` prints the URL on the last line.
-            const url = stdout.trim().split("\n").at(-1) ?? "";
-            return url;
+        openPullRequest({ repoPath, branch, base, issue, body }) {
+            return applyGithubPolicy(Effect.tryPromise({
+                try: async () => {
+                    const title = `${issue.identifier}: ${issue.title}`;
+                    const { stdout } = await execa("gh", [
+                        "pr",
+                        "create",
+                        "--base",
+                        base,
+                        "--head",
+                        branch,
+                        "--title",
+                        title,
+                        "--body",
+                        body,
+                    ], { cwd: repoPath });
+                    // `gh pr create` prints the URL on the last line.
+                    return stdout.trim().split("\n").at(-1) ?? "";
+                },
+                catch: (err) => {
+                    if (isCommandMissing(err)) {
+                        return new GhCliMissing({
+                            message: `gh CLI not found on PATH — install https://cli.github.com (${err instanceof Error ? err.message : String(err)})`,
+                        });
+                    }
+                    return new PrCreateFailed({
+                        branch,
+                        stderr: execaStderr(err),
+                        message: err instanceof Error
+                            ? err.message
+                            : `gh pr create failed: ${String(err)}`,
+                    });
+                },
+            }), {
+                call: `openPullRequest(${branch})`,
+                timeoutMs: 30_000,
+                // No retry: gh pr create is NOT idempotent — a partial
+                // success on the previous attempt could leave a PR behind,
+                // and a retry would create a duplicate.
+            });
         },
     };
 }