@valescoagency/runway 0.3.0 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ zero-secrets-at-rest, and the `gh` CLI for PR creation.
 |---|---|
 | `runway doctor` | Read-only preflight diagnostic: host tooling, env vars, repo state, and the agent docker image. Use when something stopped working and you want a sanity report. `--json` for CI / scripted health checks. |
 | `runway init` | Scaffold the cwd repo for runway: write `.sandcastle/Dockerfile` + (tier 2) `.env.schema` with op:// references. Run **once per target repo**. |
-| `runway run` | Drain a Linear queue. For each `Todo` issue: branch, agent works, sub-agent reviews, PR opens (or `needs-human` label). Run **whenever you want a batch of work done**. |
+| `runway run` | Drain a Linear queue. For each `Todo` issue: branch, agent works, sub-agent reviews, PR opens (or `ready-for-human` label). Run **whenever you want a batch of work done**. |
 | `runway upgrade` | Update the runway CLI itself: `git pull` the local clone, `pnpm install`, typecheck. `--check` for a dry-run, `--force` to override dirty/branch refusals. |
 | `runway upgrade-repo` | Re-render the cwd repo's runway scaffold against the current vendored templates. Use after a runway version bump that changed the Dockerfile or template shape — `init` writes them, `upgrade-repo` keeps them current without re-prompting for op:// values. |
 
@@ -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 "needs-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
@@ -161,10 +170,19 @@ export LINEAR_API_KEY=lin_api_...
 # export RUNWAY_READY_STATUS="Todo"
 # export RUNWAY_IN_PROGRESS_STATUS="In Progress"
 # export RUNWAY_IN_REVIEW_STATUS="In Review"
-# export RUNWAY_HITL_LABEL="needs-human"
+# export RUNWAY_HITL_LABEL="ready-for-human"
 # export RUNWAY_MAX_ITERATIONS=5
 ```
 
+`RUNWAY_HITL_LABEL` defaults to `ready-for-human`, matching the
+[Flightplan](https://github.com/valescoagency/flightplan) canonical
+state-label vocabulary (`needs-triage`, `needs-info`,
+`ready-for-agent`, `ready-for-human`, `wontfix`) that Bedrock and
+other Valesco repos use. Override the env var if your workspace uses
+a different label. `runway doctor` validates that the configured
+team, workflow states, and HITL label all exist before any agent run
+— misconfiguration surfaces immediately instead of mid-drain.
+
 ### From source (development)
 
 ```bash
@@ -214,15 +232,25 @@ Skip a single hook invocation with `LEFTHOOK=0 git commit …` (or
 ```bash
 cd /path/to/the/repo/you/want/agents/working/on
 runway run             # drain the entire ready queue
-runway run --max 3     # process at most 3 issues then exit
+runway run --max 3     # attempt at most 3 issues then exit
 runway --help
 ```
 
 `runway` (no subcommand) is an alias for `runway run` for back-compat.
 
+`--max N` bounds **attempts**, not successes. Every issue picked up
+counts as one attempt, whether it ends in a PR, a `needs-human` label,
+or a revert-to-`Todo` after an infrastructure failure. An issue
+reverted in this invocation will not be re-picked in the same
+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 `needs-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
 
@@ -239,13 +267,55 @@ It transitions them through:
   agent has committed to its branch — startup failures before any
   commits revert the issue back to `Todo` rather than stranding it)
 - `In Review` when the PR opens
-- (label `needs-human`) if the agent or reviewer can't finish *after*
+- (label `ready-for-human`) if the agent or reviewer can't finish *after*
   the agent has committed real work
 
 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
@@ -261,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
@@ -290,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/doctor.js

@@ -2,6 +2,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { execa } from "execa";
 import { detectBaseBranch } from "../git.js";
+import { loadPolicy } from "../policy.js";
+import { loadConfig } from "../config.js";
+import { validateLinearConfig } from "../linear.js";
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -87,12 +90,14 @@ export async function doctorCommand(argv) {
         sections.push(await checkEnvironment(tierForToolingChecks, cwd, repo));
         sections.push(await checkRepoState(cwd, repo));
         sections.push(await checkDockerImage(cwd));
+        sections.push(await checkLinearConfig());
     }
     else {
         // Push placeholder skipped sections so JSON output stays well-shaped.
         sections.push(skippedSection("Environment"));
         sections.push(skippedSection("Repo state"));
         sections.push(skippedSection("Docker image"));
+        sections.push(skippedSection("Linear configuration"));
     }
     // Render
     if (opts.json) {
@@ -102,8 +107,14 @@ export async function doctorCommand(argv) {
         renderText(sections, tier, initialised, opts.detailed);
     }
     // Exit code: required-check failures = 1.
-    // Sections 1, 2, 4 are "required"; section 3 (repo state) is informational.
-    const requiredSections = [sections[0], sections[1], sections[3]];
+    // Required: 0 host tooling, 1 environment, 3 docker image, 4 Linear
+    // config. Section 2 (repo state) is informational.
+    const requiredSections = [
+        sections[0],
+        sections[1],
+        sections[3],
+        sections[4],
+    ];
     const failed = requiredSections.some((s) => s?.ran && [...s.checks.values()].some((c) => c.status === "fail"));
     process.exit(failed ? 1 : 0);
 }
@@ -321,6 +332,23 @@ async function checkEnvironment(tier, cwd, repo) {
             });
         }
     }
+    // VA-352: surface the active impl-pass write-path policy so the
+    // operator can see whether an agent run can touch CI workflows, etc.
+    try {
+        const policy = loadPolicy(cwd);
+        checks.set("policy", {
+            status: "ok",
+            label: "impl policy",
+            detail: `${policy.source} (${policy.forbiddenPaths.length} forbidden path${policy.forbiddenPaths.length === 1 ? "" : "s"})`,
+        });
+    }
+    catch (err) {
+        checks.set("policy", {
+            status: "fail",
+            label: "impl policy",
+            detail: errMsg(err),
+        });
+    }
     return { title: "Environment", checks, ran: true };
 }
 function envSet(name, missingStatus) {
@@ -445,6 +473,51 @@ async function checkDockerImage(cwd) {
                 detail: imageUser ? `User=${imageUser}` : `User unset (root); host=${expected}`,
             });
         }
+        // VA-351: container readiness — pnpm on PATH + HOME/cache env
+        // baked in. Cheap one-shot run; fails fast if the image is stale.
+        try {
+            const probe = await execa("docker", [
+                "run",
+                "--rm",
+                imageName,
+                "bash",
+                "-lc",
+                'set -e; which pnpm >/dev/null && printf "HOME=%s\\nXDG_CACHE_HOME=%s\\nTURBO_CACHE_DIR=%s\\n" "$HOME" "$XDG_CACHE_HOME" "$TURBO_CACHE_DIR"',
+            ], { reject: false });
+            const out = probe.stdout ?? "";
+            const missing = [];
+            if (probe.exitCode !== 0)
+                missing.push("pnpm");
+            if (!/^HOME=\/home\/agent\s*$/m.test(out))
+                missing.push("HOME");
+            if (!/^XDG_CACHE_HOME=\/home\/agent\/.cache\s*$/m.test(out)) {
+                missing.push("XDG_CACHE_HOME");
+            }
+            if (!/^TURBO_CACHE_DIR=\/tmp\/turbo-cache\s*$/m.test(out)) {
+                missing.push("TURBO_CACHE_DIR");
+            }
+            if (missing.length === 0) {
+                checks.set("container_ready", {
+                    status: "ok",
+                    label: "container readiness",
+                    detail: "pnpm on PATH; HOME, XDG_CACHE_HOME, TURBO_CACHE_DIR set",
+                });
+            }
+            else {
+                checks.set("container_ready", {
+                    status: "warn",
+                    label: "container readiness",
+                    detail: `missing or wrong inside container: ${missing.join(", ")} — rebuild via \`runway upgrade-repo && docker build .sandcastle -t ${imageName}\``,
+                });
+            }
+        }
+        catch (err) {
+            checks.set("container_ready", {
+                status: "warn",
+                label: "container readiness",
+                detail: `probe failed: ${errMsg(err)}`,
+            });
+        }
     }
     catch (err) {
         checks.set("image_present", {
@@ -455,6 +528,134 @@ async function checkDockerImage(cwd) {
     }
     return { title: "Docker image", checks, ran: true };
 }
+// ---------------------------------------------------------------------------
+// Section: Linear configuration (VA-354)
+// ---------------------------------------------------------------------------
+/**
+ * Validate that the team, workflow states, and HITL label `runway run`
+ * would use actually exist on the Linear workspace. Without this,
+ * misconfiguration only surfaces deep inside a long agent run — too
+ * late to fix without losing the work.
+ */
+async function checkLinearConfig() {
+    const checks = new Map();
+    // The config loader's only hard requirement is LINEAR_API_KEY; the
+    // rest defaults. If the key is missing, the Environment section
+    // already fails — surface a skip here rather than re-failing.
+    if (!process.env.LINEAR_API_KEY) {
+        checks.set("linear_config", {
+            status: "skip",
+            label: "Linear config",
+            detail: "LINEAR_API_KEY unset — skipped",
+        });
+        return { title: "Linear configuration", checks, ran: true };
+    }
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        checks.set("linear_config", {
+            status: "fail",
+            label: "Linear config",
+            detail: `failed to load runway config: ${errMsg(err)}`,
+        });
+        return { title: "Linear configuration", checks, ran: true };
+    }
+    let result;
+    try {
+        result = await validateLinearConfig(config);
+    }
+    catch (err) {
+        checks.set("linear_api", {
+            status: "fail",
+            label: "Linear API",
+            detail: `validation request failed: ${errMsg(err)}`,
+        });
+        return { title: "Linear configuration", checks, ran: true };
+    }
+    if (result.team.kind === "missing") {
+        checks.set("team", {
+            status: "fail",
+            label: `team ${config.linearTeam}`,
+            detail: `Linear team key "${result.team.key}" not found — set RUNWAY_LINEAR_TEAM`,
+        });
+        // States/labels are skipped when the team missing; surface
+        // explicitly so the user knows they weren't checked.
+        checks.set("states", {
+            status: "skip",
+            label: "workflow states",
+            detail: "skipped (team missing)",
+        });
+        checks.set("hitl_label", {
+            status: "skip",
+            label: "HITL label",
+            detail: "skipped (team missing)",
+        });
+        return { title: "Linear configuration", checks, ran: true };
+    }
+    checks.set("team", {
+        status: "ok",
+        label: `team ${config.linearTeam}`,
+        detail: `id=${result.team.id}`,
+    });
+    for (const [key, configured, state] of [
+        ["ready_state", config.readyStatus, result.readyStatus],
+        ["in_progress_state", config.inProgressStatus, result.inProgressStatus],
+        ["in_review_state", config.inReviewStatus, result.inReviewStatus],
+    ]) {
+        if (state.kind === "ok") {
+            checks.set(key, {
+                status: "ok",
+                label: `workflow state "${configured}"`,
+                detail: "present",
+            });
+        }
+        else if (state.kind === "skipped") {
+            checks.set(key, {
+                status: "skip",
+                label: `workflow state "${configured}"`,
+                detail: state.reason,
+            });
+        }
+        else {
+            checks.set(key, {
+                status: "fail",
+                label: `workflow state "${configured}"`,
+                detail: `not found on team; available: ${formatList(state.available)}`,
+            });
+        }
+    }
+    if (result.hitlLabel.kind === "ok") {
+        checks.set("hitl_label", {
+            status: "ok",
+            label: `HITL label "${config.hitlLabel}"`,
+            detail: "present",
+        });
+    }
+    else if (result.hitlLabel.kind === "skipped") {
+        checks.set("hitl_label", {
+            status: "skip",
+            label: `HITL label "${config.hitlLabel}"`,
+            detail: result.hitlLabel.reason,
+        });
+    }
+    else {
+        checks.set("hitl_label", {
+            status: "fail",
+            label: `HITL label "${config.hitlLabel}"`,
+            detail: `not found on team — set RUNWAY_HITL_LABEL or create the label. Available: ${formatList(result.hitlLabel.available)}`,
+        });
+    }
+    return { title: "Linear configuration", checks, ran: true };
+}
+function formatList(items) {
+    if (items.length === 0)
+        return "(none)";
+    if (items.length <= 8)
+        return items.join(", ");
+    return `${items.slice(0, 8).join(", ")}, …(+${items.length - 8} more)`;
+}
 /**
  * Sanitize the cwd's basename the same way sandcastle's `defaultImageName`
  * does: lowercase, replace any char outside `[a-z0-9_.-]` with `-`, fall

package/dist/commands/run.js

@@ -1,9 +1,21 @@
-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) => {
+        const paths = raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (paths.length === 0) {
+            throw new Error("--allow-paths requires at least one glob");
+        }
+        opts.allowPaths = [...(opts.allowPaths ?? []), ...paths];
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
         if (a === "--max" || a === "-n") {
@@ -27,6 +39,16 @@ export function parseRunArgs(argv) {
         else if (a?.startsWith("--project=")) {
             opts.project = a.slice("--project=".length);
         }
+        else if (a === "--allow-paths") {
+            const v = argv[i + 1];
+            if (!v)
+                throw new Error("--allow-paths requires a value");
+            collectAllow(v);
+            i += 1;
+        }
+        else if (a?.startsWith("--allow-paths=")) {
+            collectAllow(a.slice("--allow-paths=".length));
+        }
         else if (a === "--help" || a === "-h") {
             printRunUsage();
             process.exit(0);
@@ -45,10 +67,18 @@ USAGE
   runway run [--max N]
 
 OPTIONS
-  --max, -n N     Process at most N issues then exit. Default: drain queue.
+  --max, -n N     Attempt at most N issues then exit (counts every
+                  attempt — success, HITL, or revert-to-Todo).
+                  Default: drain queue.
   --project ID    Scope the queue to a single Linear project under the
                   team. Accepts project UUID, slug, or name. Overrides
                   RUNWAY_LINEAR_PROJECT. Default: team-wide.
+  --allow-paths GLOBS
+                  Comma-separated globs removed from the impl policy's
+                  forbidden-paths list for this invocation only.
+                  Example: --allow-paths='.github/workflows/**' lets
+                  the agent touch CI for issues whose AC require it.
+                  Repeatable; pairs with .runway/policy.yml.
   --help, -h      Show this help.
 
 ENVIRONMENT
@@ -62,7 +92,7 @@ ENVIRONMENT
   RUNWAY_READY_STATUS         default "Todo"
   RUNWAY_IN_PROGRESS_STATUS   default "In Progress"
   RUNWAY_IN_REVIEW_STATUS     default "In Review"
-  RUNWAY_HITL_LABEL           default "needs-human"
+  RUNWAY_HITL_LABEL           default "ready-for-human"
   RUNWAY_MAX_ITERATIONS       default 5
 `);
 }
@@ -70,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 });
-    console.log(`[runway] done — processed=${result.processed} opened=${result.opened} hitl=${result.hitl} errored=${result.errored}`);
+    // 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,65 +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"),
-    hitlLabel: z.string().default("needs-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);
 }