@valescoagency/runway 0.1.1 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # runway
 
+[![npm version](https://img.shields.io/npm/v/@valescoagency/runway?logo=npm)](https://www.npmjs.com/package/@valescoagency/runway) [![License](https://img.shields.io/npm/l/@valescoagency/runway)](https://github.com/ValescoAgency/runway/blob/master/LICENSE) [![CI status](https://img.shields.io/github/actions/workflow/status/ValescoAgency/runway/release.yml?label=release)](https://github.com/ValescoAgency/runway/actions/workflows/release.yml) [![Provenance](https://img.shields.io/badge/provenance-signed-blue?logo=sigstore)](https://www.npmjs.com/package/@valescoagency/runway)
+
 A small CLI for two jobs: **scaffold** a target repo for autonomous
 coding-agent runs, then **drain** a Linear queue against it. Wraps
 [Sandcastle](https://github.com/mattpocock/sandcastle) (Claude Code
@@ -75,7 +77,9 @@ runway init \
 (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
@@ -116,6 +120,7 @@ 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_READY_STATUS="Todo"
 # export RUNWAY_IN_PROGRESS_STATUS="In Progress"
 # export RUNWAY_IN_REVIEW_STATUS="In Review"
@@ -155,13 +160,18 @@ 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

package/dist/commands/doctor.js

@@ -232,6 +232,16 @@ async function checkGhAuth() {
 function checkEnvironment(tier) {
     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)`,
+    });
     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"));

package/dist/commands/init.js

@@ -35,8 +35,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.

package/dist/commands/run.js

@@ -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,15 @@ 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_READY_STATUS         default "Todo"
   RUNWAY_IN_PROGRESS_STATUS   default "In Progress"
   RUNWAY_IN_REVIEW_STATUS     default "In Review"
@@ -52,10 +66,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/config.js

@@ -25,6 +25,14 @@ 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(),
     readyStatus: z.string().default("Todo"),
     inProgressStatus: z.string().default("In Progress"),
     inReviewStatus: z.string().default("In Review"),
@@ -36,6 +44,7 @@ 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,
         readyStatus: process.env.RUNWAY_READY_STATUS,
         inProgressStatus: process.env.RUNWAY_IN_PROGRESS_STATUS,
         inReviewStatus: process.env.RUNWAY_IN_REVIEW_STATUS,

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

@@ -43,12 +43,30 @@ 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, 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 };
@@ -113,6 +131,22 @@ async function flagHitl(issue, deps, reason) {
     await linear.applyLabel(issue.id, config.hitlLabel);
     await linear.comment(issue.id, `Runway flagged for human review: ${reason}`);
 }
+/**
+ * Whether the agent branch has any commits beyond `main`. 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, branch) {
+    try {
+        const { stdout } = await execa("git", ["rev-list", "--count", `main..${branch}`], { cwd: repoPath, reject: false });
+        return Number.parseInt(stdout.trim(), 10) > 0;
+    }
+    catch {
+        return false;
+    }
+}
 async function captureDiff(repoPath, branch) {
     const { stdout } = await execa("git", ["diff", `main...${branch}`], {
         cwd: repoPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valescoagency/runway",
-  "version": "0.1.1",
+  "version": "0.2.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": {
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "prompts",
     "templates",
     "LICENSE",
     "README.md"

package/prompts/implement.md

@@ -0,0 +1,37 @@
+You are an autonomous coding agent working on a single Linear issue.
+
+# Issue
+
+**{{ISSUE_IDENTIFIER}} — {{ISSUE_TITLE}}**
+
+{{ISSUE_DESCRIPTION}}
+
+# Repository context
+
+You are operating inside a clean checkout of the target repository on a
+fresh branch named `agent/{{ISSUE_IDENTIFIER}}`. Branch off `main`.
+
+# What done looks like
+
+1. Code changes that satisfy the issue body.
+2. All existing tests still pass. Run them: `!`pnpm test 2>&1 | tail -40``.
+3. New tests for any new behavior, where it's reasonable to add them.
+4. Lint / typecheck clean: `!`pnpm typecheck 2>&1 | tail -20`` and
+   `!`pnpm lint 2>&1 | tail -20``.
+5. A clear commit message in conventional-commits style describing the
+   change. The commit body should reference the Linear issue ID
+   (`Refs {{ISSUE_IDENTIFIER}}`).
+
+# Working style
+
+- Read before writing. Skim related files. Match existing patterns.
+- Surgical changes. Touch only what the issue requires.
+- If the issue is ambiguous and you can't make a reasonable judgment
+  call, stop and explain what's missing in your final message — runway
+  will route to a human.
+- Never modify `.github/workflows/**`, `.env*`, `*.pem`, `*.key`,
+  `pnpm-lock.yaml` (unless the task is a dep bump), or `.sandcastle/**`.
+
+# Stop conditions
+
+When all five "done" criteria pass, stop. Don't keep polishing.

package/prompts/review.md

@@ -0,0 +1,45 @@
+You are an adversarial code reviewer. You did NOT write this code; your
+job is to find reasons it should NOT ship.
+
+# Issue the change claims to address
+
+**{{ISSUE_IDENTIFIER}} — {{ISSUE_TITLE}}**
+
+{{ISSUE_DESCRIPTION}}
+
+# The diff
+
+```
+{{DIFF}}
+```
+
+# Commits
+
+```
+{{COMMITS}}
+```
+
+# Your job
+
+Score the change against these axes. For each, give a brief verdict
+(`PASS` / `CONCERN` / `BLOCK`) and one to two sentences of reasoning.
+
+1. **Addresses the issue** — does the diff actually solve what was asked?
+2. **Surgical** — only touched what was needed; no scope creep, no
+   "drive-by" refactors.
+3. **Tests** — new behavior covered; existing tests still meaningful.
+4. **Safety** — no secret leakage, no dangerous defaults, no protected
+   paths touched (workflows, env files, keys, lockfiles for non-dep work).
+5. **Clarity** — commit messages and code are readable.
+
+# Output format
+
+End your response with EXACTLY one of these two lines, alone, no other
+text on the line:
+
+    REVIEW: APPROVED
+    REVIEW: REJECTED — <one-line reason>
+
+If you output `REVIEW: REJECTED`, the agent will get one more iteration
+to address your concerns. Be specific about what to fix. Don't reject
+for nits.

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

@@ -14,19 +14,17 @@
 #
 # 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`.
+#
+# 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_API_KEY=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"')