@valescoagency/runway 0.1.2 → 0.3.0

package/README.md

@@ -61,8 +61,12 @@ runway (this CLI, on your Mac, run from inside the target repo)
 - Node 22+
 - `gh` CLI authenticated against the org that hosts your target repo
 - Linear API key with read+write on the team you're targeting
-- Anthropic API key (set in the **target repo's** `.sandcastle/.env`,
-  not in runway's env — Sandcastle reads it)
+- A Claude Code credential — **either** an Anthropic API key
+  (`sk-ant-api03-…`, pay-per-token) **or** a Pro/Max OAuth token
+  (`sk-ant-oat01-…`, generated via `claude setup-token`). The two are
+  not interchangeable — see "Claude Code auth modes" below. Stored in
+  the **target repo's** `.sandcastle/.env` (tier 1) or 1Password
+  (tier 2); never in runway's own env.
 
 ## One-time setup per target repo
 
@@ -71,13 +75,16 @@ cd /path/to/your/repo
 runway init \
   --op-vault=runway \
   --anthropic-item=anthropic-api-key \
-  --gh-token-item=gh-token
+  --gh-token-item=gh-token \
+  --auth-mode=api-key   # or --auth-mode=oauth for Pro/Max tokens
 ```
 
 (No `--op-account` — runway uses 1Password service-account auth
 (`OP_SERVICE_ACCOUNT_TOKEN`) exclusively, and the token already
 encodes the tenant. `op://` URIs runway writes are
-`op://<vault>/<item>`, not `op://<account>/<vault>/<item>`.)
+`op://<vault>/<item>/credential`, not `op://<account>/<vault>/<item>`.
+The `/credential` field selector is required for `API_CREDENTIAL`
+items, which is the canonical 1Password category for API keys.)
 
 This runs `npx sandcastle init`, patches the generated `.sandcastle/Dockerfile`
 to bake in `varlock` + the 1Password CLI + a `claude` shim, scaffolds
@@ -90,6 +97,37 @@ and no varlock (faster but secrets land on disk).
 
 Architecture walkthrough: [`docs/secrets-with-varlock.md`](docs/secrets-with-varlock.md).
 
+## Claude Code auth modes
+
+Claude Code accepts two distinct credentials, and they are **not
+interchangeable** — passing one as the other yields a generic
+`Invalid API key` inside the container with no useful diagnostic.
+
+| Mode | Env var | Token shape | Source |
+|---|---|---|---|
+| `api-key` (default) | `ANTHROPIC_API_KEY` | `sk-ant-api03-…` | [Anthropic console](https://console.anthropic.com), pay-per-token |
+| `oauth` | `CLAUDE_CODE_OAUTH_TOKEN` | `sk-ant-oat01-…` | `claude setup-token` on your Pro/Max account |
+
+Pick whichever matches what's stored in your 1Password item:
+
+```bash
+runway init --tier=2 --op-vault=runway \
+  --anthropic-item=claude-pro-oauth-token \
+  --gh-token-item=gh-token \
+  --auth-mode=oauth
+```
+
+The `--anthropic-item` flag is the 1Password item name regardless of
+mode; only the env var written into `.env.schema` changes. `runway
+doctor` surfaces the resolved mode under Environment (`claude auth
+mode: oauth (…)`), and fails fast if `.env.schema` ends up with both
+env vars at once.
+
+If you switch modes later, run `runway upgrade-repo` — it extracts
+the existing op:// references, re-renders the template with the new
+mode (detected automatically from the schema), and writes back. You
+do not need to re-pass the op:// flags.
+
 ## Secrets — recommended: varlock + 1Password
 
 If you don't want any secret sitting at rest in any `.env` file,
@@ -118,6 +156,8 @@ Export runway's own env (in your shell rc, or wherever you keep API keys):
 export LINEAR_API_KEY=lin_api_...
 # Optional overrides:
 # export RUNWAY_LINEAR_TEAM=VA
+# export RUNWAY_LINEAR_PROJECT=<project-id-or-slug>   # optional, scopes queue to one project
+# export RUNWAY_BASE_BRANCH=master                    # optional, overrides auto-detected default branch
 # export RUNWAY_READY_STATUS="Todo"
 # export RUNWAY_IN_PROGRESS_STATUS="In Progress"
 # export RUNWAY_IN_REVIEW_STATUS="In Review"
@@ -137,6 +177,38 @@ pnpm link --global      # so `runway` is on your $PATH
 
 `pnpm dev -- <args>` runs the TypeScript source via `tsx` without building, useful while iterating on runway itself.
 
+#### Tests
+
+```bash
+pnpm test          # one-shot run, used by CI
+pnpm test:watch    # watch mode for local iteration
+```
+
+Vitest is the harness; tests live colocated with the source as
+`*.test.ts` files (e.g. `src/git.test.ts` next to `src/git.ts`). CI
+runs `pnpm typecheck && pnpm test` on every PR via
+`.github/workflows/ci.yml`.
+
+When adding logic that has a sharp pass/fail signal, add a test next
+to it. The seed suite covers `parseRunArgs`, `detectBaseBranch`, the
+`parseOpRefs` regex extraction, and the `drainQueue` error-handler
+branches — copy any of those as a shape for new tests.
+
+#### Git hooks (lefthook + commitlint)
+
+Hooks install automatically on `pnpm install` via the `prepare`
+script. What runs and when:
+
+| Hook | Runs | Why |
+|---|---|---|
+| `pre-commit` | `pnpm typecheck` | Catch TS errors before they land on a branch. |
+| `commit-msg` | `pnpm exec commitlint --edit` | Reject non-conventional commit messages (CLAUDE.md convention). |
+| `pre-push` | `pnpm test` | Block pushing red. |
+
+Skip a single hook invocation with `LEFTHOOK=0 git commit …` (or
+`… git push …`). To re-install after editing `lefthook.yml`, run
+`pnpm exec lefthook install -f`.
+
 ## Usage
 
 ```bash
@@ -157,18 +229,38 @@ per-issue comments for what happened.
 Runway picks up issues that are:
 
 - in team `RUNWAY_LINEAR_TEAM` (default `VA`)
+- (optionally) in project `RUNWAY_LINEAR_PROJECT` (override per-run
+  with `runway run --project=<id-or-slug-or-name>`; unset = team-wide)
 - in workflow state `RUNWAY_READY_STATUS` (default `Todo`)
 
 It transitions them through:
 
-- `In Progress` while the agent is running
+- `In Progress` while the agent is running (specifically: once the
+  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
+- (label `needs-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.
 
+## Base branch
+
+Runway auto-detects the repo's default branch at the start of every
+`runway run` by reading `origin/HEAD` (with `git remote show origin`
+as a fallback for fresh clones). That branch is used for diffing the
+agent's work, counting commits when deciding whether a startup
+failure should revert to `Todo`, and as the `--base` for the PR.
+
+Set `RUNWAY_BASE_BRANCH=<name>` to override detection — useful when
+you want runway to target a release branch instead of the default, or
+when `origin/HEAD` isn't set and you don't want to run
+`git remote set-head origin --auto`. `runway doctor` surfaces the
+resolved base branch (detected or overridden) in its Environment
+section.
+
 ## Sub-agent review
 
 Every implementation run is followed by a fresh Sandcastle run with

package/dist/commands/doctor.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { execa } from "execa";
+import { detectBaseBranch } from "../git.js";
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -83,7 +84,7 @@ export async function doctorCommand(argv) {
     const sections = [];
     sections.push(await checkHostTooling(tierForToolingChecks));
     if (initialised || opts.tierOverride !== undefined) {
-        sections.push(checkEnvironment(tierForToolingChecks));
+        sections.push(await checkEnvironment(tierForToolingChecks, cwd, repo));
         sections.push(await checkRepoState(cwd, repo));
         sections.push(await checkDockerImage(cwd));
     }
@@ -113,11 +114,24 @@ function detectRepoState(cwd) {
     const hasDockerfile = existsSync(join(cwd, ".sandcastle", "Dockerfile"));
     const hasSchema = existsSync(join(cwd, ".env.schema"));
     let tier = null;
+    let authMode = null;
+    let hasConflictingAuthVars = false;
     if (hasSchema) {
         try {
             const schema = readFileSync(join(cwd, ".env.schema"), "utf8");
-            if (/ANTHROPIC_API_KEY\s*=\s*exec\(/.test(schema)) {
+            const hasApiKey = /ANTHROPIC_API_KEY\s*=\s*exec\(/.test(schema);
+            const hasOauth = /CLAUDE_CODE_OAUTH_TOKEN\s*=\s*exec\(/.test(schema);
+            if (hasApiKey && hasOauth) {
                 tier = 2;
+                hasConflictingAuthVars = true;
+            }
+            else if (hasApiKey) {
+                tier = 2;
+                authMode = "api-key";
+            }
+            else if (hasOauth) {
+                tier = 2;
+                authMode = "oauth";
             }
             else if (hasDockerfile) {
                 tier = 1;
@@ -130,7 +144,7 @@ function detectRepoState(cwd) {
     else if (hasDockerfile) {
         tier = 1;
     }
-    return { tier, hasDockerfile, hasSchema };
+    return { tier, hasDockerfile, hasSchema, authMode, hasConflictingAuthVars };
 }
 // ---------------------------------------------------------------------------
 // Section: Host tooling
@@ -229,12 +243,83 @@ async function checkGhAuth() {
 // ---------------------------------------------------------------------------
 // Section: Environment
 // ---------------------------------------------------------------------------
-function checkEnvironment(tier) {
+async function checkEnvironment(tier, cwd, repo) {
     const checks = new Map();
     checks.set("LINEAR_API_KEY", envSet("LINEAR_API_KEY", "fail"));
+    // Informational: which Linear scope a `runway run` would use.
+    const team = process.env.RUNWAY_LINEAR_TEAM?.trim() || "VA";
+    const project = process.env.RUNWAY_LINEAR_PROJECT?.trim();
+    checks.set("linear_scope", {
+        status: "ok",
+        label: "linear scope",
+        detail: project
+            ? `team ${team} / project ${project}`
+            : `team ${team} (team-wide — RUNWAY_LINEAR_PROJECT unset)`,
+    });
+    // Informational: which base branch a `runway run` would diff against
+    // and target with PRs. Detection failure here is a real problem —
+    // surface it as a fail so the user knows up front.
+    const override = process.env.RUNWAY_BASE_BRANCH?.trim();
+    if (override) {
+        checks.set("base_branch", {
+            status: "ok",
+            label: "base branch",
+            detail: `${override} (RUNWAY_BASE_BRANCH override)`,
+        });
+    }
+    else {
+        try {
+            const detected = await detectBaseBranch(cwd);
+            checks.set("base_branch", {
+                status: "ok",
+                label: "base branch",
+                detail: `${detected} (detected from origin/HEAD)`,
+            });
+        }
+        catch (err) {
+            checks.set("base_branch", {
+                status: "fail",
+                label: "base branch",
+                detail: errMsg(err),
+            });
+        }
+    }
     if (tier === 2) {
         // Tier 2: needed by varlock to resolve op:// refs in the container.
         checks.set("OP_SERVICE_ACCOUNT_TOKEN", envSet("OP_SERVICE_ACCOUNT_TOKEN", "fail"));
+        // Surface which Claude Code auth env var the .env.schema declares.
+        // ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN aren't
+        // interchangeable; a mismatch between this and what's stored in
+        // 1Password yields a generic "Invalid API key" inside the
+        // container with no useful diagnostic.
+        if (repo.hasConflictingAuthVars) {
+            checks.set("auth_mode", {
+                status: "fail",
+                label: "claude auth mode",
+                detail: ".env.schema declares both ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN — pick one (they are not interchangeable)",
+            });
+        }
+        else if (repo.authMode === "oauth") {
+            checks.set("auth_mode", {
+                status: "ok",
+                label: "claude auth mode",
+                detail: "oauth (CLAUDE_CODE_OAUTH_TOKEN — Pro/Max subscription)",
+            });
+        }
+        else if (repo.authMode === "api-key") {
+            checks.set("auth_mode", {
+                status: "ok",
+                label: "claude auth mode",
+                detail: "api-key (ANTHROPIC_API_KEY — pay-per-token)",
+            });
+        }
+        else {
+            checks.set("auth_mode", {
+                status: "fail",
+                label: "claude auth mode",
+                detail: ".env.schema declares neither ANTHROPIC_API_KEY nor CLAUDE_CODE_OAUTH_TOKEN",
+            });
+        }
     }
     return { title: "Environment", checks, ran: true };
 }

package/dist/commands/init.js

@@ -5,6 +5,10 @@ import { execa } from "execa";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // runway/src/commands/init.ts → runway/templates/
 const TEMPLATES_DIR = join(__dirname, "..", "..", "templates");
+const AUTH_MODE_ENV_VAR = {
+    "api-key": "ANTHROPIC_API_KEY",
+    oauth: "CLAUDE_CODE_OAUTH_TOKEN",
+};
 export function printInitUsage() {
     console.log(`runway init — scaffold a target repo for runway consumption
 
@@ -23,8 +27,18 @@ OPTIONS
   --tier=2            DEFAULT. Adds varlock + 1Password CLI inside the
                       container. Zero secrets at rest.
   --op-vault=NAME     1Password vault name (e.g. "runway"). Required for tier 2.
-  --anthropic-item=N  Item name in the vault that holds ANTHROPIC_API_KEY. Required for tier 2.
+  --anthropic-item=N  Item name in the vault that holds the Claude Code
+                      credential (ANTHROPIC_API_KEY or
+                      CLAUDE_CODE_OAUTH_TOKEN — see --auth-mode).
+                      Required for tier 2.
   --gh-token-item=N   Item name in the vault that holds GH_TOKEN. Required for tier 2.
+  --auth-mode=MODE    How Claude Code authenticates inside the
+                      container. \`api-key\` (default) writes the
+                      ANTHROPIC_API_KEY env var for pay-per-token API
+                      keys (sk-ant-api03-…). \`oauth\` writes
+                      CLAUDE_CODE_OAUTH_TOKEN for Pro/Max
+                      subscription tokens from \`claude setup-token\`
+                      (sk-ant-oat01-…). They are NOT interchangeable.
   --allow-dirty       Skip the "working tree clean" preflight check.
   --force             Overwrite an existing .sandcastle/Dockerfile.
   --skip-build        Don't \`docker build\` the agent image. Faster init,
@@ -35,8 +49,10 @@ NOTE
   No --op-account flag — runway uses 1Password service-account auth
   exclusively (OP_SERVICE_ACCOUNT_TOKEN). The token already encodes
   which 1Password tenant to talk to, so the op:// URI omits the
-  account segment: \`op://<vault>/<item>\` rather than
-  \`op://<account>/<vault>/<item>\`.
+  account segment: \`op://<vault>/<item>/<field>\` rather than
+  \`op://<account>/<vault>/<item>/<field>\`. Runway hard-codes the
+  \`credential\` field, which is the canonical field name on
+  1Password API_CREDENTIAL items.
 
 WHAT THIS COMMAND DOES
   1. Preflight: docker, gh, node, (tier 2) varlock + op CLI, git state.
@@ -61,6 +77,7 @@ function parseInitArgs(argv) {
     let opVault;
     let anthropicItem;
     let ghTokenItem;
+    let authMode = "api-key";
     let allowDirty = false;
     let force = false;
     let skipBuild = false;
@@ -93,6 +110,13 @@ function parseInitArgs(argv) {
         else if (arg.startsWith("--gh-token-item=")) {
             ghTokenItem = arg.slice("--gh-token-item=".length);
         }
+        else if (arg.startsWith("--auth-mode=")) {
+            const v = arg.slice("--auth-mode=".length);
+            if (v !== "api-key" && v !== "oauth") {
+                throw new Error(`--auth-mode must be "api-key" or "oauth", got "${v}"`);
+            }
+            authMode = v;
+        }
         else {
             throw new Error(`unknown argument: ${arg}`);
         }
@@ -114,6 +138,7 @@ function parseInitArgs(argv) {
         opVault,
         anthropicItem,
         ghTokenItem,
+        authMode,
         allowDirty,
         force,
         skipBuild,
@@ -275,12 +300,14 @@ export async function applyVarlockLayer(cwd, opts) {
         writeFileSync(`${schemaPath}.bak`, readFileSync(schemaPath, "utf8"));
     }
     const schemaTemplate = readFileSync(join(TEMPLATES_DIR, ".env.schema.target-repo"), "utf8");
+    const anthropicEnvVar = AUTH_MODE_ENV_VAR[opts.authMode];
     const rendered = schemaTemplate
         .replaceAll("{{OP_VAULT}}", opts.opVault)
         .replaceAll("{{ANTHROPIC_ITEM}}", opts.anthropicItem)
-        .replaceAll("{{GH_TOKEN_ITEM}}", opts.ghTokenItem);
+        .replaceAll("{{GH_TOKEN_ITEM}}", opts.ghTokenItem)
+        .replaceAll("{{ANTHROPIC_ENV_VAR}}", anthropicEnvVar);
     writeFileSync(schemaPath, rendered);
-    console.log(`  ✓ wrote .env.schema (op://${opts.opVault}/...)`);
+    console.log(`  ✓ wrote .env.schema (auth-mode=${opts.authMode}, ${anthropicEnvVar}, op://${opts.opVault}/...)`);
     // 2. Patch Dockerfile.
     const dockerfilePath = join(cwd, ".sandcastle", "Dockerfile");
     if (!existsSync(dockerfilePath)) {
@@ -359,11 +386,12 @@ export async function verify(cwd, opts) {
     if (!existsSync(schemaPath))
         fail(".env.schema missing at repo root (tier 2 requires it)");
     const schema = readFileSync(schemaPath, "utf8");
-    if (!schema.includes("ANTHROPIC_API_KEY="))
-        fail(".env.schema missing ANTHROPIC_API_KEY");
+    const anthropicEnvVar = AUTH_MODE_ENV_VAR[opts.authMode];
+    if (!schema.includes(`${anthropicEnvVar}=`))
+        fail(`.env.schema missing ${anthropicEnvVar} (auth-mode=${opts.authMode})`);
     if (!schema.includes("GH_TOKEN="))
         fail(".env.schema missing GH_TOKEN");
-    ok(".env.schema declares ANTHROPIC_API_KEY + GH_TOKEN");
+    ok(`.env.schema declares ${anthropicEnvVar} + GH_TOKEN`);
     // Inline secret shape check.
     const secretRe = /(sk-ant-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{20,}|lin_api_[A-Za-z0-9]{20,})/;
     if (secretRe.test(schema)) {

package/dist/commands/run.js

@@ -2,7 +2,7 @@ import { loadConfig } from "../config.js";
 import { createLinearGateway } from "../linear.js";
 import { createGithubGateway } from "../github.js";
 import { assertSandcastleInitialised, drainQueue, } from "../orchestrator.js";
-function parseRunArgs(argv) {
+export function parseRunArgs(argv) {
     const opts = {};
     for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
@@ -17,6 +17,16 @@ function parseRunArgs(argv) {
             opts.max = n;
             i += 1;
         }
+        else if (a === "--project") {
+            const v = argv[i + 1];
+            if (!v)
+                throw new Error("--project requires a value");
+            opts.project = v;
+            i += 1;
+        }
+        else if (a?.startsWith("--project=")) {
+            opts.project = a.slice("--project=".length);
+        }
         else if (a === "--help" || a === "-h") {
             printRunUsage();
             process.exit(0);
@@ -36,11 +46,19 @@ USAGE
 
 OPTIONS
   --max, -n N     Process at most N issues then exit. 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.
   --help, -h      Show this help.
 
 ENVIRONMENT
   LINEAR_API_KEY              required
   RUNWAY_LINEAR_TEAM          default "VA"
+  RUNWAY_LINEAR_PROJECT       optional — scope to one project
+  RUNWAY_BASE_BRANCH          optional — override the auto-detected base
+                              branch (the branch runway diffs against
+                              and targets with PRs). Detected from
+                              origin/HEAD when unset.
   RUNWAY_READY_STATUS         default "Todo"
   RUNWAY_IN_PROGRESS_STATUS   default "In Progress"
   RUNWAY_IN_REVIEW_STATUS     default "In Review"
@@ -52,10 +70,16 @@ export async function runCommand(argv) {
     const opts = parseRunArgs(argv);
     const cwd = process.cwd();
     assertSandcastleInitialised(cwd);
-    const config = loadConfig();
+    const baseConfig = loadConfig();
+    const config = opts.project
+        ? { ...baseConfig, linearProject: opts.project }
+        : baseConfig;
     const linear = createLinearGateway(config);
     const github = createGithubGateway();
-    console.log(`[runway] draining queue from team ${config.linearTeam} (status="${config.readyStatus}") against ${cwd}`);
+    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}`);
 }

package/dist/commands/upgrade-repo.js

@@ -27,7 +27,9 @@ OPTIONS
                       lines outside the runway templates (manual edits).
   --op-vault=NAME     Override the 1Password vault. By default, upgrade-repo
                       extracts this from the existing .env.schema.
-  --anthropic-item=N  Override the ANTHROPIC_API_KEY item name.
+  --anthropic-item=N  Override the Claude Code credential item name
+                      (i.e. the ANTHROPIC_API_KEY or
+                      CLAUDE_CODE_OAUTH_TOKEN 1Password item).
   --gh-token-item=N   Override the GH_TOKEN item name.
   --help, -h          Show this help.
 
@@ -118,6 +120,7 @@ export async function upgradeRepoCommand(argv) {
         opVault: "placeholder",
         anthropicItem: "placeholder",
         ghTokenItem: "placeholder",
+        authMode: "api-key",
     };
     await preflight(cwd, preflightOpts);
     // Render new file contents in memory.
@@ -165,6 +168,7 @@ export async function upgradeRepoCommand(argv) {
         opVault: resolved?.opVault ?? "placeholder",
         anthropicItem: resolved?.anthropicItem ?? "placeholder",
         ghTokenItem: resolved?.ghTokenItem ?? "placeholder",
+        authMode: resolved?.authMode ?? "api-key",
     };
     await verify(cwd, verifyOpts);
     console.log(`[runway upgrade-repo] done — tier ${tier} scaffold refreshed`);
@@ -180,8 +184,10 @@ function detectTier(cwd) {
     }
     if (existsSync(schemaPath)) {
         const schema = readFileSync(schemaPath, "utf8");
-        // Tier-2 marker: ANTHROPIC_API_KEY uses the varlock shell-call form.
-        const tier2Marker = new RegExp(`ANTHROPIC_API_KEY\\s*=\\s*${execName()}\\(`);
+        // Tier-2 marker: the Claude Code credential (whichever env var
+        // name the user picked at init time) uses the varlock shell-call
+        // form.
+        const tier2Marker = new RegExp(`(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)\\s*=\\s*${execName()}\\(`);
         if (tier2Marker.test(schema)) {
             return 2;
         }
@@ -197,17 +203,29 @@ function execName() {
 // ---------------------------------------------------------------------------
 // op:// extraction
 // ---------------------------------------------------------------------------
-const ANTHROPIC_RE = new RegExp(`^\\s*ANTHROPIC_API_KEY\\s*=\\s*${execName()}\\(\\s*['"]op read "op://([^/"]+)/([^"]+)"['"]\\s*\\)\\s*$`, "m");
+// Either ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN — capture which
+// it is so upgrade-repo can re-render in the same auth mode.
+const ANTHROPIC_RE = new RegExp(`^\\s*(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)\\s*=\\s*${execName()}\\(\\s*['"]op read "op://([^/"]+)/([^"]+)"['"]\\s*\\)\\s*$`, "m");
 const GH_TOKEN_RE = new RegExp(`^\\s*GH_TOKEN\\s*=\\s*${execName()}\\(\\s*['"]op read "op://([^/"]+)/([^"]+)"['"]\\s*\\)\\s*$`, "m");
 function resolveOpRefs(cwd, opts) {
     const schemaPath = join(cwd, ".env.schema");
     const schema = readFileSync(schemaPath, "utf8");
+    return parseOpRefs(schema, opts);
+}
+/**
+ * Pure schema-string → ResolvedOpRefs parser. Split out from
+ * `resolveOpRefs` so it can be unit-tested without touching the
+ * filesystem. The regex captures + override / vault-mismatch logic
+ * live here; the disk read lives in `resolveOpRefs`.
+ */
+export function parseOpRefs(schema, opts) {
     const anthropicMatch = schema.match(ANTHROPIC_RE);
     const ghTokenMatch = schema.match(GH_TOKEN_RE);
     // Per-field override > extracted > error.
-    const opVault = opts.opVault ?? anthropicMatch?.[1] ?? ghTokenMatch?.[1] ?? null;
-    const anthropicItem = opts.anthropicItem ?? anthropicMatch?.[2] ?? null;
+    const opVault = opts.opVault ?? anthropicMatch?.[2] ?? ghTokenMatch?.[1] ?? null;
+    const anthropicItem = opts.anthropicItem ?? anthropicMatch?.[3] ?? null;
     const ghTokenItem = opts.ghTokenItem ?? ghTokenMatch?.[2] ?? null;
+    const authMode = anthropicMatch?.[1] === "CLAUDE_CODE_OAUTH_TOKEN" ? "oauth" : "api-key";
     if (!opVault || !anthropicItem || !ghTokenItem) {
         throw new Error("could not parse existing .env.schema; pass --op-vault, --anthropic-item, --gh-token-item explicitly to override.");
     }
@@ -217,10 +235,10 @@ function resolveOpRefs(cwd, opts) {
     if (!opts.opVault &&
         anthropicMatch &&
         ghTokenMatch &&
-        anthropicMatch[1] !== ghTokenMatch[1]) {
-        throw new Error(`vault mismatch in .env.schema: ANTHROPIC_API_KEY uses "${anthropicMatch[1]}", GH_TOKEN uses "${ghTokenMatch[1]}". Pass --op-vault to disambiguate.`);
+        anthropicMatch[2] !== ghTokenMatch[1]) {
+        throw new Error(`vault mismatch in .env.schema: ${anthropicMatch[1]} uses "${anthropicMatch[2]}", GH_TOKEN uses "${ghTokenMatch[1]}". Pass --op-vault to disambiguate.`);
     }
-    return { opVault, anthropicItem, ghTokenItem };
+    return { opVault, anthropicItem, ghTokenItem, authMode };
 }
 // ---------------------------------------------------------------------------
 // Render: Dockerfile
@@ -270,15 +288,25 @@ function renderEnvSchema(cwd, resolved) {
     const schemaPath = join(cwd, ".env.schema");
     const before = readFileSync(schemaPath, "utf8");
     const tmpl = readFileSync(join(TEMPLATES_DIR, ".env.schema.target-repo"), "utf8");
+    const anthropicEnvVar = resolved.authMode === "oauth" ? "CLAUDE_CODE_OAUTH_TOKEN" : "ANTHROPIC_API_KEY";
     let body = tmpl
         .replaceAll("{{OP_VAULT}}", resolved.opVault)
         .replaceAll("{{ANTHROPIC_ITEM}}", resolved.anthropicItem)
-        .replaceAll("{{GH_TOKEN_ITEM}}", resolved.ghTokenItem);
-    // Preserve user-added `KEY=<call>(...)` lines for keys other than the two
-    // we own. Match any `KEY = <execName>(` line in the existing schema and
-    // append the whole line if its key isn't ANTHROPIC_API_KEY or GH_TOKEN.
+        .replaceAll("{{GH_TOKEN_ITEM}}", resolved.ghTokenItem)
+        .replaceAll("{{ANTHROPIC_ENV_VAR}}", anthropicEnvVar);
+    // Preserve user-added `KEY=<call>(...)` lines for keys other than the
+    // ones we own. Match any `KEY = <execName>(` line in the existing
+    // schema and append the whole line if its key isn't the active
+    // Claude Code auth var or GH_TOKEN.
     const userExecRe = new RegExp(`^([A-Z_][A-Z0-9_]*)\\s*=\\s*${execName()}\\(`, "gm");
-    const ownedKeys = new Set(["ANTHROPIC_API_KEY", "GH_TOKEN"]);
+    // Both possible auth-mode vars are reserved so a user who switches
+    // modes doesn't end up with the dead one duplicated as a "preserved"
+    // line.
+    const ownedKeys = new Set([
+        "ANTHROPIC_API_KEY",
+        "CLAUDE_CODE_OAUTH_TOKEN",
+        "GH_TOKEN",
+    ]);
     const preservedLines = [];
     for (const match of before.matchAll(userExecRe)) {
         const key = match[1];

package/dist/config.js

@@ -25,6 +25,24 @@ const ConfigSchema = z.object({
      */
     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"),
@@ -36,6 +54,8 @@ export function loadConfig() {
         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,

package/dist/git.js

@@ -0,0 +1,41 @@
+import { execa } from "execa";
+/**
+ * Resolve the default branch name of the cwd repo. Tries
+ * `git symbolic-ref` against `origin/HEAD` first (fast, works on any
+ * clone where the symbolic ref has been set), then falls back to
+ * `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.
+ */
+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;
+        }
+    }
+    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);
+        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.`);
+}

package/dist/github.js

@@ -12,13 +12,13 @@ export function createGithubGateway() {
                 stdio: "inherit",
             });
         },
-        async openPullRequest({ repoPath, branch, issue, body }) {
+        async openPullRequest({ repoPath, branch, base, issue, body }) {
             const title = `${issue.identifier}: ${issue.title}`;
             const { stdout } = await execa("gh", [
                 "pr",
                 "create",
                 "--base",
-                "main",
+                base,
                 "--head",
                 branch,
                 "--title",

package/dist/linear.js

@@ -25,14 +25,39 @@ export function createLinearGateway(config) {
         }
         return team.id;
     }
+    /**
+     * Resolve a project identifier (UUID, slug, or name) to its Linear
+     * project ID. Tries each shape in order so user-facing flags like
+     * `--project=bedrock` work without forcing users to copy the UUID.
+     */
+    async function findProjectId(identifier) {
+        const projects = await client.projects({
+            filter: {
+                or: [
+                    { id: { eq: identifier } },
+                    { slugId: { eq: identifier } },
+                    { name: { eq: identifier } },
+                ],
+            },
+        });
+        const project = projects.nodes[0];
+        if (!project) {
+            throw new Error(`Linear project "${identifier}" not found`);
+        }
+        return project.id;
+    }
     return {
         async fetchReady() {
             const teamId = await findTeamId();
             const readyStateId = await findStateId(teamId, config.readyStatus);
+            const projectId = config.linearProject
+                ? await findProjectId(config.linearProject)
+                : null;
             const issues = await client.issues({
                 filter: {
                     team: { id: { eq: teamId } },
                     state: { id: { eq: readyStateId } },
+                    ...(projectId ? { project: { id: { eq: projectId } } } : {}),
                 },
                 // Stable order: oldest first so the queue drains FIFO.
                 orderBy: "createdAt",

package/dist/orchestrator.js

@@ -4,6 +4,7 @@ import { run, claudeCode } from "@ai-hero/sandcastle";
 import { docker } from "@ai-hero/sandcastle/sandboxes/docker";
 import { execa } from "execa";
 import { implementVars, loadImplementPrompt, loadReviewPrompt, renderPrompt, reviewVars, } from "./prompts.js";
+import { detectBaseBranch } from "./git.js";
 const REVIEW_VERDICT_RE = /^REVIEW:\s*(APPROVED|REJECTED)(?:\s+—\s+(.*))?$/m;
 /**
  * Confirms the cwd looks like a sandcastle-initialised repo. If not,
@@ -27,13 +28,19 @@ export async function drainQueue(deps, opts = {}) {
     let opened = 0;
     let hitl = 0;
     let errored = 0;
+    // Resolve the base branch once at startup so every issue in the
+    // drain sees the same answer (and so a misconfigured repo fails
+    // fast, before we touch any Linear state).
+    const baseBranch = config.baseBranch ?? (await detectBaseBranch(deps.cwd));
+    console.log(`[runway] base branch resolved to "${baseBranch}"`);
+    const runDeps = { ...deps, baseBranch };
     while (processed < max) {
         const queue = await linear.fetchReady();
         if (queue.length === 0)
             break;
         const issue = queue[0];
         try {
-            const verdict = await processIssue(issue, deps);
+            const verdict = await processIssue(issue, runDeps);
             processed += 1;
             if (verdict === "opened")
                 opened += 1;
@@ -43,18 +50,36 @@ export async function drainQueue(deps, opts = {}) {
         catch (err) {
             errored += 1;
             console.error(`[runway] error on ${issue.identifier}:`, err);
-            await linear
-                .applyLabel(issue.id, config.hitlLabel)
-                .catch(() => undefined);
-            await linear
-                .comment(issue.id, `Runway hit an unrecoverable error and flagged for human review:\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\``)
-                .catch(() => undefined);
+            // If the agent crashed before producing any commits (missing
+            // image, varlock validation, container failed to boot, etc.),
+            // it's an infrastructure failure — not a HITL. Revert the issue
+            // to `Todo` and skip the `needs-human` label so the next run
+            // can pick it up cleanly. `In Progress` is reserved for "agent
+            // has committed to the branch".
+            const branch = `agent/${issue.identifier.toLowerCase()}`;
+            const startedRealWork = await hasCommits(deps.cwd, baseBranch, branch);
+            if (!startedRealWork) {
+                await linear
+                    .transition(issue.id, config.readyStatus)
+                    .catch(() => undefined);
+                await linear
+                    .comment(issue.id, `Runway hit a startup failure before the agent produced any commits — reverting to \`${config.readyStatus}\` for retry:\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\``)
+                    .catch(() => undefined);
+            }
+            else {
+                await linear
+                    .applyLabel(issue.id, config.hitlLabel)
+                    .catch(() => undefined);
+                await linear
+                    .comment(issue.id, `Runway hit an unrecoverable error and flagged for human review:\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\``)
+                    .catch(() => undefined);
+            }
         }
     }
     return { processed, opened, hitl, errored };
 }
 async function processIssue(issue, deps) {
-    const { config, linear, github, cwd } = deps;
+    const { config, linear, github, cwd, baseBranch } = deps;
     const branch = `agent/${issue.identifier.toLowerCase()}`;
     await linear.transition(issue.id, config.inProgressStatus);
     await linear.comment(issue.id, `Runway picked up this issue. Branch: \`${branch}\`.`);
@@ -76,8 +101,8 @@ async function processIssue(issue, deps) {
         return "hitl";
     }
     // 2. Review pass — read-only-ish, just looking at the diff.
-    const diff = await captureDiff(cwd, branch);
-    const commitLog = await captureCommitLog(cwd, branch);
+    const diff = await captureDiff(cwd, baseBranch, branch);
+    const commitLog = await captureCommitLog(cwd, baseBranch, branch);
     const reviewPrompt = renderPrompt(await loadReviewPrompt(), reviewVars({ issue, diff, commits: commitLog }));
     const reviewResult = await run({
         agent: claudeCode("claude-opus-4-6"),
@@ -101,6 +126,7 @@ async function processIssue(issue, deps) {
     const prUrl = await github.openPullRequest({
         repoPath: cwd,
         branch,
+        base: baseBranch,
         issue,
         body: prBody,
     });
@@ -113,15 +139,31 @@ async function flagHitl(issue, deps, reason) {
     await linear.applyLabel(issue.id, config.hitlLabel);
     await linear.comment(issue.id, `Runway flagged for human review: ${reason}`);
 }
-async function captureDiff(repoPath, branch) {
-    const { stdout } = await execa("git", ["diff", `main...${branch}`], {
+/**
+ * Whether the agent branch has any commits beyond `base`. Used by the
+ * drain loop to distinguish "agent crashed mid-run, after producing
+ * real work" (→ HITL) from "agent crashed during startup, no work
+ * done" (→ revert to Todo). If the branch doesn't exist or git fails,
+ * treat as "no commits" so we revert rather than strand the issue.
+ */
+async function hasCommits(repoPath, base, branch) {
+    try {
+        const { stdout } = await execa("git", ["rev-list", "--count", `${base}..${branch}`], { cwd: repoPath, reject: false });
+        return Number.parseInt(stdout.trim(), 10) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function captureDiff(repoPath, base, branch) {
+    const { stdout } = await execa("git", ["diff", `${base}...${branch}`], {
         cwd: repoPath,
     });
     // Truncate to keep the review prompt under the model's context budget.
     return stdout.length > 60_000 ? `${stdout.slice(0, 60_000)}\n…(truncated)` : stdout;
 }
-async function captureCommitLog(repoPath, branch) {
-    const { stdout } = await execa("git", ["log", "--oneline", `main..${branch}`], { cwd: repoPath });
+async function captureCommitLog(repoPath, base, branch) {
+    const { stdout } = await execa("git", ["log", "--oneline", `${base}..${branch}`], { cwd: repoPath });
     return stdout;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valescoagency/runway",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Linear-driven orchestrator + scaffolder for coding agents on Sandcastle. `runway init` scaffolds a target repo (sandcastle + varlock + 1Password); `runway run` drains a Linear queue against it; `runway doctor`, `runway upgrade`, `runway upgrade-repo` round out the lifecycle.",
   "license": "MIT",
   "author": {
@@ -45,9 +45,13 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@types/node": "^22.10.0",
+    "lefthook": "^2.1.6",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=22"
@@ -56,9 +60,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/cli.js",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "echo 'lint not configured yet'"
   }
 }

package/templates/.env.schema.target-repo

@@ -14,19 +14,24 @@
 #
 # Note on the op:// shape: with service-account auth (the only mode
 # runway uses), the token already encodes the 1Password tenant, so the
-# URI omits the account segment — `op://<vault>/<item>`, not
-# `op://<account>/<vault>/<item>`.
-
-# @sensitive @required
-ANTHROPIC_API_KEY=exec('op read "op://{{OP_VAULT}}/{{ANTHROPIC_ITEM}}"')
+# URI omits the account segment — `op://<vault>/<item>/<field>`, not
+# `op://<account>/<vault>/<item>/<field>`. For API_CREDENTIAL items
+# (the natural category for API keys), the field is `credential`.
+#
+# Note on Claude Code auth: ANTHROPIC_API_KEY is a pay-per-token API
+# key (sk-ant-api03-…). CLAUDE_CODE_OAUTH_TOKEN is a Pro/Max
+# subscription token from `claude setup-token` (sk-ant-oat01-…). They
+# are NOT interchangeable. Runway init writes whichever the user
+# selected with --auth-mode; see runway's README "Claude Code auth"
+# section for details.
+#
+# To add another secret, copy one of the two live entries below. Do
+# NOT leave a commented-out example block here: varlock parses any
+# `# @decorator` line as a real decorator, and a decorator with no
+# attached config line fails validation ("detached comment block").
 
 # @sensitive @required
-GH_TOKEN=exec('op read "op://{{OP_VAULT}}/{{GH_TOKEN_ITEM}}"')
+{{ANTHROPIC_ENV_VAR}}=exec('op read "op://{{OP_VAULT}}/{{ANTHROPIC_ITEM}}/credential"')
 
-# Add other secrets the agent needs at runtime here. Examples:
-#
-# @sensitive @required
-# OPENAI_API_KEY=exec('op read "op://{{OP_VAULT}}/openai-api-key"')
-#
 # @sensitive @required
-# DATABASE_URL=exec('op read "op://{{OP_VAULT}}/database-url"')
+GH_TOKEN=exec('op read "op://{{OP_VAULT}}/{{GH_TOKEN_ITEM}}/credential"')