@valescoagency/runway 0.2.0 → 0.4.0

package/dist/orchestrator.js

@@ -3,8 +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";
-const REVIEW_VERDICT_RE = /^REVIEW:\s*(APPROVED|REJECTED)(?:\s+—\s+(.*))?$/m;
+import { buildIterationSummary, implementVars, loadImplementPrompt, loadReviewPrompt, renderPrompt, reviewVars, tailOfMessage, } from "./prompts.js";
+import { detectBaseBranch } from "./git.js";
+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
@@ -23,22 +40,42 @@ 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;
-    while (processed < max) {
+    // Resolve the base branch once at startup so every issue in the
+    // drain sees the same answer (and so a misconfigured repo fails
+    // fast, before we touch any Linear state).
+    const baseBranch = config.baseBranch ?? (await detectBaseBranch(deps.cwd));
+    console.log(`[runway] base branch resolved to "${baseBranch}"`);
+    const 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, deps);
-            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;
@@ -46,56 +83,113 @@ 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, branch);
+            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 } = deps;
+    const { config, linear, github, cwd, baseBranch } = deps;
     const branch = `agent/${issue.identifier.toLowerCase()}`;
     await linear.transition(issue.id, config.inProgressStatus);
     await linear.comment(issue.id, `Runway picked up this issue. Branch: \`${branch}\`.`);
     // 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, branch);
-    const commitLog = await captureCommitLog(cwd, branch);
+    const diff = await captureDiff(cwd, baseBranch, branch);
+    const commitLog = await captureCommitLog(cwd, baseBranch, branch);
     const reviewPrompt = renderPrompt(await loadReviewPrompt(), reviewVars({ issue, diff, commits: commitLog }));
     const reviewResult = await run({
         agent: claudeCode("claude-opus-4-6"),
@@ -110,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);
@@ -119,64 +214,165 @@ async function processIssue(issue, deps) {
     const prUrl = await github.openPullRequest({
         repoPath: cwd,
         branch,
+        base: baseBranch,
         issue,
         body: prBody,
     });
     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 `main`. Used by the
+ * Whether the agent branch has any commits beyond `base`. Used by the
  * drain loop to distinguish "agent crashed mid-run, after producing
  * real work" (→ HITL) from "agent crashed during startup, no work
  * done" (→ revert to Todo). If the branch doesn't exist or git fails,
  * treat as "no commits" so we revert rather than strand the issue.
  */
-async function hasCommits(repoPath, branch) {
+async function hasCommits(repoPath, base, branch) {
     try {
-        const { stdout } = await execa("git", ["rev-list", "--count", `main..${branch}`], { cwd: repoPath, reject: false });
+        const { stdout } = await execa("git", ["rev-list", "--count", `${base}..${branch}`], { cwd: repoPath, reject: false });
         return Number.parseInt(stdout.trim(), 10) > 0;
     }
     catch {
         return false;
     }
 }
-async function captureDiff(repoPath, branch) {
-    const { stdout } = await execa("git", ["diff", `main...${branch}`], {
+async function captureDiff(repoPath, base, branch) {
+    const { stdout } = await execa("git", ["diff", `${base}...${branch}`], {
         cwd: repoPath,
     });
     // Truncate to keep the review prompt under the model's context budget.
     return stdout.length > 60_000 ? `${stdout.slice(0, 60_000)}\n…(truncated)` : stdout;
 }
-async function captureCommitLog(repoPath, branch) {
-    const { stdout } = await execa("git", ["log", "--oneline", `main..${branch}`], { cwd: repoPath });
+async function captureCommitLog(repoPath, base, branch) {
+    const { stdout } = await execa("git", ["log", "--oneline", `${base}..${branch}`], { cwd: repoPath });
     return stdout;
 }
+/**
+ * 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) {
@@ -184,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.2.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,12 +42,17 @@
     "@ai-hero/sandcastle": "^0.5.10",
     "@linear/sdk": "^41.0.0",
     "execa": "^9.5.2",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@types/node": "^22.10.0",
+    "lefthook": "^2.1.6",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=22"
@@ -56,9 +61,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && chmod +x dist/cli.js",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "echo 'lint not configured yet'"
   }
 }