@valescoagency/runway 0.2.0 → 0.4.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. |
 
@@ -50,7 +50,7 @@ runway (this CLI, on your Mac, run from inside the target repo)
   │   → REVIEW: APPROVED  | REVIEW: REJECTED — <reason>
   │
   ├── approved  → git push → gh pr create → Linear "In Review"
-  └── rejected  → Linear label "needs-human", comment with reason
+  └── rejected  → Linear label "ready-for-human", comment with reason
   ↓ next issue
 ```
 
@@ -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,7 +75,8 @@ 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
@@ -92,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,
@@ -121,13 +157,23 @@ 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"
-# 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
@@ -140,19 +186,58 @@ 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
 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
+are normal outcomes. Check Linear for the `ready-for-human` label and the
 per-issue comments for what happened.
 
 ## Linear conventions
@@ -170,13 +255,28 @@ 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.
 
+## 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,10 @@
 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
 // ---------------------------------------------------------------------------
@@ -83,15 +87,17 @@ 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));
+        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) {
@@ -101,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);
 }
@@ -113,11 +125,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 +155,7 @@ function detectRepoState(cwd) {
     else if (hasDockerfile) {
         tier = 1;
     }
-    return { tier, hasDockerfile, hasSchema };
+    return { tier, hasDockerfile, hasSchema, authMode, hasConflictingAuthVars };
 }
 // ---------------------------------------------------------------------------
 // Section: Host tooling
@@ -229,7 +254,7 @@ 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.
@@ -242,9 +267,87 @@ function checkEnvironment(tier) {
             ? `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",
+            });
+        }
+    }
+    // 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 };
 }
@@ -370,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", {
@@ -380,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/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,
@@ -63,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;
@@ -95,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}`);
         }
@@ -116,6 +138,7 @@ function parseInitArgs(argv) {
         opVault,
         anthropicItem,
         ghTokenItem,
+        authMode,
         allowDirty,
         force,
         skipBuild,
@@ -277,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)) {
@@ -361,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)) {