@valescoagency/runway 0.3.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
 ```
 
@@ -161,10 +161,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,14 +223,21 @@ 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
+are normal outcomes. Check Linear for the `ready-for-human` label and the
 per-issue comments for what happened.
 
 ## Linear conventions
@@ -239,7 +255,7 @@ 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

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

@@ -4,6 +4,16 @@ import { createGithubGateway } from "../github.js";
 import { assertSandcastleInitialised, drainQueue, } from "../orchestrator.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 +37,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 +65,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 +90,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
 `);
 }
@@ -80,6 +108,6 @@ export async function runCommand(argv) {
         ? `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}`);
+    const result = await drainQueue({ config, linear, github, cwd }, { max: opts.max, allowPaths: opts.allowPaths });
+    console.log(`[runway] done — attempts=${result.attempts} opened=${result.opened} hitl=${result.hitl} errored=${result.errored}`);
 }

package/dist/config.js

@@ -46,7 +46,13 @@ const ConfigSchema = z.object({
     readyStatus: z.string().default("Todo"),
     inProgressStatus: z.string().default("In Progress"),
     inReviewStatus: z.string().default("In Review"),
-    hitlLabel: z.string().default("needs-human"),
+    // VA-354: default to the Flightplan canonical state label
+    // `ready-for-human`. The previous default (`needs-human`) doesn't
+    // exist on Flightplan-aligned Linear workspaces (the common case
+    // for Valesco repos), and `linear.applyLabel` failures cascaded
+    // into the substantive rejection reason being lost. Workspaces that
+    // use a different label override via `RUNWAY_HITL_LABEL`.
+    hitlLabel: z.string().default("ready-for-human"),
     maxIterations: z.coerce.number().int().positive().default(5),
 });
 export function loadConfig() {

package/dist/linear.js

@@ -104,3 +104,44 @@ export function createLinearGateway(config) {
         },
     };
 }
+export async function validateLinearConfig(config) {
+    const client = new LinearClient({ apiKey: config.linearApiKey });
+    const teams = await client.teams({
+        filter: { key: { eq: config.linearTeam } },
+    });
+    const team = teams.nodes[0];
+    if (!team) {
+        return {
+            team: { kind: "missing", key: config.linearTeam },
+            readyStatus: { kind: "skipped", reason: "team missing" },
+            inProgressStatus: { kind: "skipped", reason: "team missing" },
+            inReviewStatus: { kind: "skipped", reason: "team missing" },
+            hitlLabel: { kind: "skipped", reason: "team missing" },
+        };
+    }
+    const states = await client.workflowStates({
+        filter: { team: { id: { eq: team.id } } },
+    });
+    const stateNames = states.nodes.map((s) => s.name);
+    const checkState = (want) => stateNames.includes(want)
+        ? { kind: "ok", name: want }
+        : { kind: "missing", name: want, available: stateNames };
+    const labels = await client.issueLabels({
+        filter: { team: { id: { eq: team.id } } },
+    });
+    const labelNames = labels.nodes.map((l) => l.name);
+    const hitlLabel = labelNames.includes(config.hitlLabel)
+        ? { kind: "ok", name: config.hitlLabel }
+        : {
+            kind: "missing",
+            name: config.hitlLabel,
+            available: labelNames.slice(0, 50),
+        };
+    return {
+        team: { kind: "ok", id: team.id },
+        readyStatus: checkState(config.readyStatus),
+        inProgressStatus: checkState(config.inProgressStatus),
+        inReviewStatus: checkState(config.inReviewStatus),
+        hitlLabel,
+    };
+}

package/dist/orchestrator.js

@@ -3,9 +3,25 @@ import { join } from "node:path";
 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 { buildIterationSummary, implementVars, loadImplementPrompt, loadReviewPrompt, renderPrompt, reviewVars, tailOfMessage, } from "./prompts.js";
 import { detectBaseBranch } from "./git.js";
-const REVIEW_VERDICT_RE = /^REVIEW:\s*(APPROVED|REJECTED)(?:\s+—\s+(.*))?$/m;
+import { loadPolicy } from "./policy.js";
+// VA-353: review verdict marker. Global flag because sandcastle
+// appends wrapper output ("Agent stopped", "Capturing session",
+// "Reached max iterations (1).", "Run complete: …") AFTER the agent's
+// final message — so the marker is rarely the last line. We scan
+// every line-start match and keep the LAST one, which is the most
+// recent agent verdict. Standalone-line: ^…$ with /m anchors prevent
+// mid-prose matches like "the reviewer should output REVIEW: APPROVED
+// when…".
+const REVIEW_VERDICT_RE = /^REVIEW:\s*(APPROVED|REJECTED)(?:\s+—\s+(.*))?$/gm;
+// VA-350: impl-pass termination contract. Last `IMPL:` marker line in
+// the agent's output wins (most recent iteration's verdict). DONE →
+// proceed to review; BLOCKED → HITL with reason; CONTINUE or missing →
+// fall through (back-compat). The trailing reason after `—` is
+// captured for BLOCKED.
+const IMPL_VERDICT_RE = /^IMPL:\s*(DONE|BLOCKED|CONTINUE)(?:\s+—\s+(.*))?$/gm;
+const IMPL_COMPLETION_SIGNALS = ["IMPL: DONE", "IMPL: BLOCKED"];
 /**
  * Confirms the cwd looks like a sandcastle-initialised repo. If not,
  * we error early with a clear message rather than letting Sandcastle
@@ -24,7 +40,7 @@ export function assertSandcastleInitialised(cwd) {
 export async function drainQueue(deps, opts = {}) {
     const { config, linear } = deps;
     const max = opts.max ?? Number.POSITIVE_INFINITY;
-    let processed = 0;
+    let attempts = 0;
     let opened = 0;
     let hitl = 0;
     let errored = 0;
@@ -33,19 +49,33 @@ export async function drainQueue(deps, opts = {}) {
     // 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 policy = loadPolicy(deps.cwd, { allowPathsOverride: opts.allowPaths });
+    console.log(`[runway] policy: ${policy.source}`);
+    const runDeps = { ...deps, baseBranch, policy };
+    // VA-344: never re-pick an issue in the same invocation, even if
+    // VA-342 reverted it to `Todo`. Without this, a deterministic
+    // startup failure (broken .env.schema, missing image, expired token)
+    // would loop on the same issue until --max was exhausted.
+    const seen = new Set();
+    const outcomes = [];
+    while (attempts < max) {
         const queue = await linear.fetchReady();
-        if (queue.length === 0)
+        const issue = queue.find((i) => !seen.has(i.id));
+        if (!issue)
             break;
-        const issue = queue[0];
+        seen.add(issue.id);
+        attempts += 1;
         try {
-            const verdict = await processIssue(issue, runDeps);
-            processed += 1;
-            if (verdict === "opened")
+            const result = await processIssue(issue, runDeps);
+            if (result.kind === "opened")
                 opened += 1;
-            if (verdict === "hitl")
+            if (result.kind === "hitl")
                 hitl += 1;
+            outcomes.push({
+                identifier: issue.identifier,
+                kind: result.kind,
+                detail: result.detail,
+            });
         }
         catch (err) {
             errored += 1;
@@ -53,30 +83,44 @@ export async function drainQueue(deps, opts = {}) {
             // 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".
+            // to the ready state and skip the HITL 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);
+            const errDetail = err instanceof Error ? err.message : String(err);
             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\`\`\``)
+                    .comment(issue.id, `Runway hit a startup failure before the agent produced any commits — reverting to \`${config.readyStatus}\` for retry:\n\n\`\`\`\n${errDetail}\n\`\`\``)
                     .catch(() => undefined);
+                outcomes.push({
+                    identifier: issue.identifier,
+                    kind: "reverted",
+                    detail: errDetail,
+                });
             }
             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);
+                // VA-355: comment first with the substantive reason, label
+                // second (best-effort). If we labeled first and the label
+                // didn't exist (Flightplan workspaces hitting the
+                // `needs-human` default — see VA-354), the orchestrator's
+                // catch would never get to the reason and the operator would
+                // see an infrastructure error in Linear with no clue what
+                // the agent actually found.
+                await flagHitl(issue, runDeps, `Runway hit an unrecoverable error and flagged for human review: ${errDetail}`);
+                outcomes.push({
+                    identifier: issue.identifier,
+                    kind: "errored",
+                    detail: errDetail,
+                });
             }
         }
     }
-    return { processed, opened, hitl, errored };
+    printExitSummary(outcomes);
+    return { attempts, opened, hitl, errored, outcomes };
 }
 async function processIssue(issue, deps) {
     const { config, linear, github, cwd, baseBranch } = deps;
@@ -84,21 +128,64 @@ async function processIssue(issue, deps) {
     await linear.transition(issue.id, config.inProgressStatus);
     await linear.comment(issue.id, `Runway picked up this issue. Branch: \`${branch}\`.`);
     // 1. Implementation pass.
-    const implementPrompt = renderPrompt(await loadImplementPrompt(), implementVars(issue));
-    const implementResult = await run({
-        agent: claudeCode("claude-opus-4-6"),
-        sandbox: docker({
-            env: dockerEnv(config),
-        }),
-        cwd,
-        prompt: implementPrompt,
-        branchStrategy: { type: "branch", branch },
-        maxIterations: config.maxIterations,
-        name: `impl-${issue.identifier}`,
-    });
-    if (implementResult.commits.length === 0) {
-        await flagHitl(issue, deps, "Agent produced no commits — the issue may need clarification or human input.");
-        return "hitl";
+    //
+    // VA-349 + VA-350: run iterations one at a time so we can (a) inject
+    // a summary of the previous iteration into the next prompt — no more
+    // "I'll start by understanding the current state of the repository"
+    // 5x per issue — and (b) break early on IMPL: DONE/BLOCKED parsed
+    // from our own code rather than relying on sandcastle's substring
+    // completionSignal.
+    const implementTemplate = await loadImplementPrompt();
+    const maxIters = Math.max(1, config.maxIterations);
+    let prevSummary = "";
+    let implementResult;
+    let implVerdict = { kind: "missing" };
+    for (let iter = 1; iter <= maxIters; iter += 1) {
+        const implementPrompt = renderPrompt(implementTemplate, implementVars(issue, {
+            previousIterations: prevSummary,
+            policy: deps.policy,
+        }));
+        implementResult = await run({
+            agent: claudeCode("claude-opus-4-6"),
+            sandbox: docker({
+                env: dockerEnv(config),
+            }),
+            cwd,
+            prompt: implementPrompt,
+            branchStrategy: { type: "branch", branch },
+            maxIterations: 1,
+            completionSignal: [...IMPL_COMPLETION_SIGNALS],
+            name: `impl-${issue.identifier}-iter-${iter}`,
+        });
+        implVerdict = parseImplVerdict(implementResult);
+        if (implVerdict.kind === "done" || implVerdict.kind === "blocked")
+            break;
+        // CONTINUE / missing — build the summary that the NEXT iteration
+        // will see at the top of its prompt.
+        const commits = await captureCommitLog(cwd, baseBranch, branch).catch(() => "");
+        prevSummary = buildIterationSummary({
+            iterationsRun: iter,
+            commits,
+            finalMessageTail: tailOfMessage(implementResult.stdout ?? ""),
+        });
+    }
+    // implementResult is set after the first iteration. The `!` is safe
+    // because maxIters >= 1.
+    const finalResult = implementResult;
+    // VA-350: BLOCKED short-circuits straight to HITL — no reviewer pass
+    // for a self-declared blocker.
+    if (implVerdict.kind === "blocked") {
+        const reason = `Implementation pass blocked: ${implVerdict.reason}`;
+        await flagHitl(issue, deps, reason);
+        return { kind: "hitl", detail: reason };
+    }
+    if (implVerdict.kind === "missing") {
+        console.warn(`[runway] ${issue.identifier}: impl agent ended without an IMPL: marker after ${maxIters} iteration(s); proceeding to review for back-compat.`);
+    }
+    if (finalResult.commits.length === 0) {
+        const reason = "Agent produced no commits — the issue may need clarification or human input.";
+        await flagHitl(issue, deps, reason);
+        return { kind: "hitl", detail: reason };
     }
     // 2. Review pass — read-only-ish, just looking at the diff.
     const diff = await captureDiff(cwd, baseBranch, branch);
@@ -117,8 +204,9 @@ async function processIssue(issue, deps) {
     });
     const verdict = parseReviewVerdict(reviewResult);
     if (verdict.kind === "rejected") {
-        await flagHitl(issue, deps, `Sub-agent review rejected: ${verdict.reason}`);
-        return "hitl";
+        const reason = `Sub-agent review rejected: ${verdict.reason}`;
+        await flagHitl(issue, deps, reason);
+        return { kind: "hitl", detail: reason };
     }
     // 3. Push + PR.
     await github.pushBranch(cwd, branch);
@@ -132,12 +220,78 @@ async function processIssue(issue, deps) {
     });
     await linear.transition(issue.id, config.inReviewStatus);
     await linear.comment(issue.id, `Runway opened a PR for review: ${prUrl}`);
-    return "opened";
+    return { kind: "opened", detail: prUrl };
 }
+/**
+ * VA-355: comment is the load-bearing artifact, label is metadata.
+ * Post the comment FIRST so the substantive reason lands on the issue
+ * even if the label apply later fails (Flightplan workspaces hitting
+ * the `needs-human` default, transient Linear errors, etc.). On full
+ * failure (comment didn't even post), dump the reason to stderr with
+ * a clear banner so the operator sees it terminal-side.
+ */
 async function flagHitl(issue, deps, reason) {
     const { config, linear } = deps;
-    await linear.applyLabel(issue.id, config.hitlLabel);
-    await linear.comment(issue.id, `Runway flagged for human review: ${reason}`);
+    const body = `Runway flagged for human review: ${reason}`;
+    let commentPosted = false;
+    try {
+        await linear.comment(issue.id, body);
+        commentPosted = true;
+    }
+    catch (err) {
+        console.error(`[runway] ${issue.identifier}: failed to post HITL comment:`, errMsg(err));
+    }
+    try {
+        await linear.applyLabel(issue.id, config.hitlLabel);
+    }
+    catch (err) {
+        const detail = errMsg(err);
+        console.error(`[runway] ${issue.identifier}: failed to apply HITL label "${config.hitlLabel}":`, detail);
+        if (commentPosted) {
+            // Best-effort follow-up note; the real reason is already on the
+            // issue from the first comment.
+            await linear
+                .comment(issue.id, `Note: could not apply \`${config.hitlLabel}\` label — please apply it manually. (${detail})`)
+                .catch(() => undefined);
+        }
+    }
+    if (!commentPosted) {
+        // Last resort: the operator at least sees the reason in their
+        // terminal, even with Linear entirely unreachable.
+        process.stderr.write([
+            "",
+            `===== REJECTION REASON FOLLOWS (${issue.identifier}) =====`,
+            reason,
+            "===== END REJECTION REASON =====",
+            "",
+            "",
+        ].join("\n"));
+    }
+}
+function errMsg(err) {
+    if (err instanceof Error)
+        return err.message.split("\n")[0] ?? err.message;
+    return String(err);
+}
+/**
+ * VA-355: render a per-issue verdict trail at the end of the drain so
+ * the operator can scan results without opening Linear. Skipped when
+ * no issues were attempted.
+ */
+function printExitSummary(outcomes) {
+    if (outcomes.length === 0)
+        return;
+    console.log("\n[runway] per-issue outcomes:");
+    for (const o of outcomes) {
+        const tag = o.kind === "opened"
+            ? "APPROVED → PR opened"
+            : o.kind === "hitl"
+                ? "HITL"
+                : o.kind === "reverted"
+                    ? "REVERTED → Todo"
+                    : "INFRA_ERROR";
+        console.log(`  ${o.identifier}  ${tag}  ${o.detail}`);
+    }
 }
 /**
  * Whether the agent branch has any commits beyond `base`. Used by the
@@ -166,25 +320,59 @@ async function captureCommitLog(repoPath, base, branch) {
     const { stdout } = await execa("git", ["log", "--oneline", `${base}..${branch}`], { cwd: repoPath });
     return stdout;
 }
+/**
+ * Pulls the last `IMPL:` marker line out of the agent's output. The
+ * orchestrator uses this to distinguish a clean completion (DONE) from
+ * a self-declared block (BLOCKED — reason) from a multi-iteration
+ * in-progress signal (CONTINUE). A missing marker is treated as
+ * CONTINUE-with-warning for back-compat.
+ */
+export function parseImplVerdict(result) {
+    const text = stringifyResult(result);
+    // Take the LAST match — later iterations override earlier ones if
+    // the agent emitted multiple markers across an iteration loop.
+    const matches = [...text.matchAll(IMPL_VERDICT_RE)];
+    const last = matches[matches.length - 1];
+    if (!last)
+        return { kind: "missing" };
+    if (last[1] === "DONE")
+        return { kind: "done" };
+    if (last[1] === "CONTINUE")
+        return { kind: "continue" };
+    return {
+        kind: "blocked",
+        reason: last[2]?.trim() || "no reason given",
+    };
+}
 /**
  * Sandcastle's `RunResult` shape varies by version; defensively dig out
  * the last assistant message text. We only need to match the
  * `REVIEW: APPROVED` / `REVIEW: REJECTED — …` line at the tail.
  */
-function parseReviewVerdict(result) {
+/**
+ * VA-353: parse the reviewer's final `REVIEW: APPROVED` /
+ * `REVIEW: REJECTED — <reason>` marker. Scans the agent's combined
+ * stdout for *all* matches and returns the LAST one, since sandcastle
+ * appends its own wrapper output ("Agent stopped", "Capturing
+ * session", "Reached max iterations (N).", "Run complete: …") after
+ * the agent's final message. A missing marker is itself a rejection —
+ * a reviewer pass that didn't terminate cleanly is not trustworthy.
+ */
+export function parseReviewVerdict(result) {
     const text = stringifyResult(result);
-    const match = text.match(REVIEW_VERDICT_RE);
-    if (!match) {
+    const matches = [...text.matchAll(REVIEW_VERDICT_RE)];
+    const last = matches[matches.length - 1];
+    if (!last) {
         return {
             kind: "rejected",
             reason: "review output did not contain a REVIEW: verdict line",
         };
     }
-    if (match[1] === "APPROVED")
+    if (last[1] === "APPROVED")
         return { kind: "approved", reason: "" };
     return {
         kind: "rejected",
-        reason: match[2]?.trim() || "no reason given",
+        reason: last[2]?.trim() || "no reason given",
     };
 }
 function stringifyResult(result) {
@@ -192,6 +380,15 @@ function stringifyResult(result) {
         return result;
     if (result && typeof result === "object") {
         const r = result;
+        // VA-353: sandcastle's RunResult carries the combined agent output
+        // on `stdout`. Prefer it — falling through to JSON.stringify (the
+        // old behavior) replaces real newlines with `\n` escapes and
+        // breaks `^…$/m` line anchoring, which is the exact reason the
+        // reviewer's verdict was being silently dropped for issues like
+        // VA-312 tonight. The iterations/output fallbacks remain for
+        // back-compat with older shapes and inline test fixtures.
+        if (typeof r.stdout === "string" && r.stdout.length > 0)
+            return r.stdout;
         if (r.iterations?.length) {
             return r.iterations
                 .map((i) => i.output ?? i.text ?? "")

package/dist/policy.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+/**
+ * VA-352: per-repo + per-run write-path policy for the impl agent.
+ *
+ * Defaults are conservative — secrets and sandbox-internals are always
+ * denied. Repos that need agents to touch CI workflows (the common
+ * case) opt in by creating `.runway/policy.yml` with `allowedPaths`,
+ * or by passing `--allow-paths=` for a single invocation.
+ *
+ * The policy is reflected back to the agent in the rendered prompt
+ * (`prompts/implement.md`'s "Working style" denylist sentence) so the
+ * sentence the agent sees matches what runway will enforce at review
+ * time. Enforcement itself (refusing to push a PR that touches a
+ * denied path) lives in the reviewer pass — out of scope for this
+ * change; the goal here is that the agent gets a correct denylist
+ * and surfaces `IMPL: BLOCKED` when an AC requires a denied path.
+ */
+export const DEFAULT_FORBIDDEN_PATHS = [
+    ".github/workflows/**",
+    ".env*",
+    "*.pem",
+    "*.key",
+    "pnpm-lock.yaml",
+    ".sandcastle/**",
+];
+const PolicyFileSchema = z.object({
+    allowedPaths: z.array(z.string()).optional(),
+    forbiddenPaths: z.array(z.string()).optional(),
+});
+const POLICY_RELATIVE_PATH = join(".runway", "policy.yml");
+/**
+ * Resolve the effective policy for `cwd`. Reads `.runway/policy.yml`
+ * when present, layers it on top of the conservative defaults, then
+ * applies any `--allow-paths` CLI override.
+ */
+export function loadPolicy(cwd, opts = {}) {
+    const sources = [];
+    let forbidden = new Set(DEFAULT_FORBIDDEN_PATHS);
+    const policyPath = join(cwd, POLICY_RELATIVE_PATH);
+    if (existsSync(policyPath)) {
+        sources.push(POLICY_RELATIVE_PATH);
+        const raw = readFileSync(policyPath, "utf8");
+        const parsed = PolicyFileSchema.parse(parseYaml(raw) ?? {});
+        if (parsed.forbiddenPaths) {
+            forbidden = new Set(parsed.forbiddenPaths);
+        }
+        for (const allow of parsed.allowedPaths ?? [])
+            forbidden.delete(allow);
+    }
+    else {
+        sources.push("defaults");
+    }
+    if (opts.allowPathsOverride?.length) {
+        for (const allow of opts.allowPathsOverride)
+            forbidden.delete(allow);
+        sources.push("--allow-paths");
+    }
+    return {
+        forbiddenPaths: [...forbidden],
+        source: sources.join(" + "),
+    };
+}
+/**
+ * Render the bullet sentence the impl prompt shows the agent. Stable
+ * formatting so a missing path is visible in a diff.
+ */
+export function renderForbiddenPathsBullet(policy) {
+    if (policy.forbiddenPaths.length === 0) {
+        return "- (No write-path restrictions for this repo. Use judgment.)";
+    }
+    const quoted = policy.forbiddenPaths.map((p) => `\`${p}\``).join(", ");
+    return `- Never modify ${quoted}. If the issue's acceptance criteria require modifying one of these paths, **stop and emit \`IMPL: BLOCKED — issue requires modifying <path>, which working-style policy forbids\`** — do not silently skip the work.`;
+}

package/dist/prompts.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { renderForbiddenPathsBullet } from "./policy.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Prompts ship with the runway package, NOT in the target repo's
 // .sandcastle/. Runway substitutes {{KEY}} placeholders before passing
@@ -22,13 +23,55 @@ export async function loadReviewPrompt() {
 export function renderPrompt(template, vars) {
     return template.replace(/\{\{(\w+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
 }
-export function implementVars(issue) {
+export function implementVars(issue, opts = {}) {
     return {
         ISSUE_IDENTIFIER: issue.identifier,
         ISSUE_TITLE: issue.title,
         ISSUE_DESCRIPTION: issue.description || "(no description)",
+        // VA-349: empty for iteration 1, a structured summary for 2+.
+        PREVIOUS_ITERATIONS: opts.previousIterations ?? "",
+        // VA-352: render the working-style denylist from the active policy
+        // so the agent never sees a hardcoded list that diverges from what
+        // runway actually enforces.
+        POLICY_FORBIDDEN_BULLET: opts.policy
+            ? renderForbiddenPathsBullet(opts.policy)
+            : "",
     };
 }
+/**
+ * VA-349: build the "## Previous iterations" block that gets prepended
+ * to iteration N+1's prompt. Carries the agent's commit log and the
+ * tail of its final message so the next iteration doesn't re-explore
+ * the repo from scratch.
+ */
+export function buildIterationSummary(args) {
+    const { iterationsRun, commits, finalMessageTail } = args;
+    return [
+        "## Previous iterations",
+        "",
+        `You have already completed ${iterationsRun} iteration(s) on this issue.`,
+        "Do **not** re-explore the repository — pick up where the last iteration left off.",
+        "",
+        "### Commits so far on this branch",
+        "",
+        "```",
+        commits.trim() || "(no commits yet)",
+        "```",
+        "",
+        "### Tail of the last iteration's final message",
+        "",
+        "```",
+        finalMessageTail.trim() || "(no output captured)",
+        "```",
+        "",
+    ].join("\n");
+}
+/** Keep the tail of an iteration's stdout small enough to fit alongside the prompt. */
+export function tailOfMessage(stdout, maxChars = 2000) {
+    if (stdout.length <= maxChars)
+        return stdout;
+    return `…(earlier output truncated)\n${stdout.slice(-maxChars)}`;
+}
 export function reviewVars(args) {
     return {
         ISSUE_IDENTIFIER: args.issue.identifier,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valescoagency/runway",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -42,6 +42,7 @@
     "@ai-hero/sandcastle": "^0.5.10",
     "@linear/sdk": "^41.0.0",
     "execa": "^9.5.2",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/prompts/implement.md

@@ -6,6 +6,8 @@ You are an autonomous coding agent working on a single Linear issue.
 
 {{ISSUE_DESCRIPTION}}
 
+{{PREVIOUS_ITERATIONS}}
+
 # Repository context
 
 You are operating inside a clean checkout of the target repository on a
@@ -29,9 +31,51 @@ fresh branch named `agent/{{ISSUE_IDENTIFIER}}`. Branch off `main`.
 - 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/**`.
+{{POLICY_FORBIDDEN_BULLET}}
 
 # Stop conditions
 
 When all five "done" criteria pass, stop. Don't keep polishing.
+
+# Termination contract — REQUIRED
+
+End **every** response with exactly one of these markers, on its own
+line, as the **last non-empty line** of your message. Nothing after it.
+
+- `IMPL: DONE` — all five "done" criteria are met. The reviewer pass
+  will run next; no further iterations are needed.
+- `IMPL: BLOCKED — <one-line reason>` — you cannot proceed without
+  human input (issue is ambiguous, requires a decision outside the
+  agent's purview, conflicts with a working-style constraint, hits a
+  permission wall, etc.). Runway will route the issue to a human with
+  your reason attached and will not run the reviewer pass.
+- `IMPL: CONTINUE` — you made progress but the work isn't done yet.
+  Runway will run another iteration so you can pick up where you left
+  off.
+
+Examples:
+
+```
+…all tests pass, typecheck clean, lint clean. Commit pushed.
+
+IMPL: DONE
+```
+
+```
+…the issue's acceptance criteria require modifying
+`.github/workflows/release.yml`, which the working-style policy
+forbids. Cannot proceed.
+
+IMPL: BLOCKED — issue requires CI workflow changes that working-style policy forbids
+```
+
+```
+…added the migration and the RLS policy. Tests for the policy
+helper still need to be written next iteration.
+
+IMPL: CONTINUE
+```
+
+The marker is parsed mechanically by runway. A missing or malformed
+marker is treated as `CONTINUE` for back-compat, but **always** emit
+one explicitly — silent completions waste budget on re-exploration.

package/templates/Dockerfile.claude-code.base

@@ -39,6 +39,30 @@ RUN if ! getent group $AGENT_GID >/dev/null; then \
       groupmod -g $AGENT_GID node; \
     fi \
  && usermod -u $AGENT_UID -g $AGENT_GID -d /home/agent -m -l agent node
+
+# VA-351: bake the container env up front so agents don't manually
+# work around host-path leaks, missing pnpm, or unset HOME on every
+# iteration. Without these, every agent run repeats the same
+# corepack/TURBO_CACHE_DIR/HOME setup commands — see VA-312's run log
+# for the receipts.
+ENV HOME=/home/agent
+ENV XDG_CACHE_HOME=/home/agent/.cache
+ENV TURBO_CACHE_DIR=/tmp/turbo-cache
+ENV npm_config_cache=/home/agent/.cache/npm
+
+# Pre-create cache dirs with agent ownership so the first pnpm/turbo
+# run doesn't have to chown them. Both are inside paths the agent owns
+# anyway; this just makes them exist.
+RUN mkdir -p /home/agent/.cache /home/agent/.cache/npm /tmp/turbo-cache \
+ && chown -R $AGENT_UID:$AGENT_GID /home/agent/.cache /tmp/turbo-cache
+
+# Bake pnpm via corepack at build time so `pnpm` is on PATH inside the
+# container before any agent command runs. Pin a default; target repos
+# can override at runtime via `packageManager` in package.json +
+# `corepack use`.
+RUN corepack enable \
+ && corepack prepare pnpm@10.0.0 --activate
+
 USER ${AGENT_UID}:${AGENT_GID}
 
 # Install Claude Code CLI