@valescoagency/runway 0.13.0 → 0.14.1

package/README.md

@@ -541,7 +541,7 @@ These are tractable, just not v1.
 
 ## Status
 
-0.13.0 — production-shaped and dogfooded against live Linear queues.
+0.14.1 — production-shaped and dogfooded against live Linear queues.
 The end-to-end pipeline (init → run → review → PR) is stable; surface
 may still shift as the orchestrator's policy and iteration mechanics
 mature. See [CHANGELOG.md](./CHANGELOG.md) for per-release detail.

package/dist/dashboard/projector.js

@@ -52,6 +52,10 @@ function projectDrain(span) {
         spanId: span.spanId,
         startTimeUnixNano: span.startTimeUnixNano,
         endTimeUnixNano: span.endTimeUnixNano,
+        // VA-455: an ended drain's "last activity" is its end time —
+        // the storage layer keeps last_seen monotonic, so setting it
+        // here ensures the value never regresses below the real end.
+        lastSeenUnixNano: span.endTimeUnixNano,
         attempts: numAttr(m["runway.drain.attempts"]),
         opened: numAttr(m["runway.drain.opened"]),
         hitl: numAttr(m["runway.drain.hitl"]),
@@ -137,6 +141,53 @@ function numAttr(v) {
 function strArrayAttr(v) {
     return Array.isArray(v) ? v : [];
 }
+/**
+ * VA-455: the canonical body string runway emits at the top of the
+ * `drainQueue` span. The projector matches on this exact value to
+ * decide which log records become active-drain markers — keep them
+ * in lock-step with `orchestrator.ts`.
+ */
+export const DRAIN_STARTED_LOG = "drain.started";
+/**
+ * VA-455: scan an OTLP logs payload for `drain.started` markers.
+ * Each match becomes an `ActiveDrainMarker` carrying the drain's
+ * trace_id, the drainQueue span_id, and the log timestamp. The
+ * storage layer's `markDrainActive` upserts a `drains` row on each
+ * marker so the dashboard's active-drain card lights up within ~1s
+ * of `runway run` starting, instead of waiting for the first
+ * `processIssue` span to end.
+ *
+ * Records missing trace_id, span_id, or a timestamp are dropped —
+ * we won't fabricate any of those, and a drain.started marker
+ * without them has nothing useful to bind.
+ */
+export function extractActiveDrainMarkers(payload) {
+    const out = [];
+    for (const rl of payload.resourceLogs ?? []) {
+        for (const sl of rl.scopeLogs ?? []) {
+            for (const rec of sl.logRecords ?? []) {
+                if (rec.body?.stringValue !== DRAIN_STARTED_LOG)
+                    continue;
+                const traceId = rec.traceId?.trim();
+                if (!traceId)
+                    continue;
+                const spanId = rec.spanId?.trim();
+                if (!spanId)
+                    continue;
+                const ts = rec.timeUnixNano ?? rec.observedTimeUnixNano;
+                if (!ts)
+                    continue;
+                out.push({
+                    traceId,
+                    spanId,
+                    startTimeUnixNano: ts,
+                    lastSeenUnixNano: ts,
+                });
+            }
+        }
+    }
+    return out;
+}
 /**
  * VA-388: project an OTLP logs payload into `LogRecordRow`s. Records
  * without a trace_id are dropped — every Effect log emitted under

package/dist/dashboard/server.js

@@ -1,7 +1,7 @@
 import { createServer } from "node:http";
 import { createLinearAdapter, startLinearSync, } from "./linear-sync.js";
 import { createEventBus } from "./events.js";
-import { projectLogs, projectPayload } from "./projector.js";
+import { extractActiveDrainMarkers, projectLogs, projectPayload, } from "./projector.js";
 import { createStorage, } from "./storage.js";
 import { META_REVIEW_PAGE_SIZE, renderDetailView, renderIssueProcessRows, renderListView, renderLogsSection, renderMetaReviewDetailView, renderMetaReviewListView, } from "./views.js";
 // VA-389: phase spans we surface on the detail page's timeline.
@@ -239,6 +239,14 @@ async function handleOtlpLogs(req, res, storage, events) {
         writeError(res, 400, "invalid_json", asMessage(err));
         return;
     }
+    // VA-455: surface in-flight drains the moment the runway process
+    // emits its `drain.started` log marker — well before the first
+    // processIssue span ends. `markDrainActive` is no-op when the
+    // drain has already closed, so reordering across OTLP retries is
+    // safe.
+    for (const m of extractActiveDrainMarkers(payload)) {
+        storage.markDrainActive(m);
+    }
     for (const r of projectLogs(payload)) {
         storage.appendLogRecord(r);
         // VA-391: the SSE detail-pane stream live-tails the Logs section

package/dist/dashboard/storage.js

@@ -1,4 +1,11 @@
 import { DatabaseSync } from "node:sqlite";
+/**
+ * VA-455: how stale a drain's last_seen can be before getActiveDrain
+ * treats it as crashed and hides it. Runway emits a heartbeat log
+ * every 30s while drainQueue is active; 90s gives 3× headroom so a
+ * single dropped heartbeat doesn't toggle the dashboard card.
+ */
+export const ACTIVE_DRAIN_STALENESS_NANOS = 90n * 1000000000n;
 /**
  * VA-406: named constants for the `meta_reviews.kind` alphabet.
  * Used by the IRA passes when stamping rows + by gateway queries
@@ -23,11 +30,17 @@ export const META_RUN_REVIEW_COMPLETION_KINDS = [
     META_REVIEW_KIND.FAILED,
 ];
 const SCHEMA = `
+  -- VA-455: end_time_unix_nano is nullable so an "active drain" row
+  -- inserted by the drain.started log marker can exist before the
+  -- drainQueue span has actually ended. last_seen_unix_nano carries
+  -- the most recent log record's timestamp for the trace so the
+  -- dashboard's active-drain query can age out crashed drains.
   CREATE TABLE IF NOT EXISTS drains (
     trace_id TEXT NOT NULL,
     span_id TEXT NOT NULL,
     start_time_unix_nano TEXT NOT NULL,
-    end_time_unix_nano TEXT NOT NULL,
+    end_time_unix_nano TEXT,
+    last_seen_unix_nano TEXT,
     attempts INTEGER,
     opened INTEGER,
     hitl INTEGER,
@@ -165,6 +178,59 @@ const DEFAULT_AGGREGATE_WINDOW = 30;
  * of `hitl_escape_rate` — a review rejection routes to HITL, so both
  * rates count the same row.
  */
+/**
+ * VA-455: relax the `end_time_unix_nano TEXT NOT NULL` constraint on
+ * pre-VA-455 `drains` tables so the log-driven active-drain row can
+ * land with end_time = NULL. SQLite has no `ALTER COLUMN`, so the
+ * idiomatic move is a rebuild — guarded by PRAGMA so fresh installs
+ * (which already created the new schema) skip the work.
+ */
+function relaxDrainsEndTimeNotNull(db) {
+    const cols = db
+        .prepare("PRAGMA table_info('drains')")
+        .all();
+    const endTime = cols.find((c) => c.name === "end_time_unix_nano");
+    if (!endTime || endTime.notnull === 0)
+        return;
+    // Single transaction so the `drains` name is never absent from the
+    // schema between DROP and RENAME — concurrent readers (none today,
+    // but cheap insurance) keep seeing the old table until COMMIT.
+    db.prepare("BEGIN").run();
+    try {
+        db.prepare(`CREATE TABLE drains_v2 (
+        trace_id TEXT NOT NULL,
+        span_id TEXT NOT NULL,
+        start_time_unix_nano TEXT NOT NULL,
+        end_time_unix_nano TEXT,
+        last_seen_unix_nano TEXT,
+        attempts INTEGER,
+        opened INTEGER,
+        hitl INTEGER,
+        errored INTEGER,
+        status_code INTEGER,
+        status_message TEXT,
+        inserted_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (trace_id, span_id)
+      )`).run();
+        db.prepare(`INSERT INTO drains_v2 (
+        trace_id, span_id, start_time_unix_nano, end_time_unix_nano,
+        last_seen_unix_nano, attempts, opened, hitl, errored,
+        status_code, status_message, inserted_at
+      )
+      SELECT
+        trace_id, span_id, start_time_unix_nano, end_time_unix_nano,
+        last_seen_unix_nano, attempts, opened, hitl, errored,
+        status_code, status_message, inserted_at
+      FROM drains`).run();
+        db.prepare("DROP TABLE drains").run();
+        db.prepare("ALTER TABLE drains_v2 RENAME TO drains").run();
+        db.prepare("COMMIT").run();
+    }
+    catch (err) {
+        db.prepare("ROLLBACK").run();
+        throw err;
+    }
+}
 function aggregatesViewDdl(windowDrains) {
     // windowDrains is the only spot we interpolate rather than
     // parameter-bind (CREATE VIEW can't take params). Coerce to a
@@ -299,6 +365,10 @@ export function createStorage(path, opts = {}) {
         // filtering. Old rows decode to "" — the poller only filters on
         // known type values so pre-migration rows behave unchanged.
         `ALTER TABLE linear_snapshots ADD COLUMN status_type TEXT`,
+        // VA-455: per-trace heartbeat timestamp for the log-driven active
+        // drain query (see SCHEMA above for semantics). Older DBs need
+        // the column added in-place.
+        `ALTER TABLE drains ADD COLUMN last_seen_unix_nano TEXT`,
     ]) {
         try {
             db.exec(sql);
@@ -308,6 +378,12 @@ export function createStorage(path, opts = {}) {
             // dashboard boot ran the same migration.
         }
     }
+    // VA-455: SQLite has no `ALTER COLUMN`, so relaxing the original
+    // `end_time_unix_nano TEXT NOT NULL` constraint on legacy DBs
+    // requires a table-rebuild. Only fire when PRAGMA reports the
+    // column is still NOT NULL — fresh installs go through the new
+    // SCHEMA above and skip this branch.
+    relaxDrainsEndTimeNotNull(db);
     // VA-399: install the evaluator-facing read-model view after the
     // base tables exist (and after VA-387's column migrations above),
     // but before any prepared statement is created — a
@@ -317,17 +393,58 @@ export function createStorage(path, opts = {}) {
     const insertDrain = db.prepare(`
     INSERT INTO drains (
       trace_id, span_id, start_time_unix_nano, end_time_unix_nano,
+      last_seen_unix_nano,
       attempts, opened, hitl, errored, status_code, status_message
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT (trace_id, span_id) DO UPDATE SET
       start_time_unix_nano = excluded.start_time_unix_nano,
       end_time_unix_nano = excluded.end_time_unix_nano,
+      last_seen_unix_nano = excluded.last_seen_unix_nano,
       attempts = excluded.attempts,
       opened = excluded.opened,
       hitl = excluded.hitl,
       errored = excluded.errored,
       status_code = excluded.status_code,
       status_message = excluded.status_message
+  `);
+    // VA-455: insert (or refresh last_seen on) the active-drain row
+    // when runway emits its `drain.started` log marker. ON CONFLICT
+    // guards against two cases:
+    //   1. The drainQueue span has already ended (end_time NOT NULL)
+    //      — a late-arriving marker can't reanimate a closed drain,
+    //      so we leave the row untouched.
+    //   2. Repeated markers (shouldn't happen, but if they do we just
+    //      bump last_seen forward; monotonic via the MAX comparison).
+    const markActiveDrainStmt = db.prepare(`
+    INSERT INTO drains (
+      trace_id, span_id, start_time_unix_nano,
+      end_time_unix_nano, last_seen_unix_nano,
+      attempts, opened, hitl, errored,
+      status_code, status_message
+    ) VALUES (?, ?, ?, NULL, ?, 0, 0, 0, 0, NULL, NULL)
+    ON CONFLICT (trace_id, span_id) DO UPDATE SET
+      last_seen_unix_nano = excluded.last_seen_unix_nano
+    WHERE drains.end_time_unix_nano IS NULL
+      AND (
+        drains.last_seen_unix_nano IS NULL
+        OR CAST(drains.last_seen_unix_nano AS INTEGER)
+           < CAST(excluded.last_seen_unix_nano AS INTEGER)
+      )
+  `);
+    // VA-455: every log record carrying a trace_id pushes that
+    // trace's active drain's last_seen forward, so the active-drain
+    // query can age out crashed drains. UPDATE-only (never inserts)
+    // so a stray log record from a trace without a `drain.started`
+    // marker doesn't fabricate an active drain.
+    const bumpDrainLastSeenStmt = db.prepare(`
+    UPDATE drains
+    SET last_seen_unix_nano = ?
+    WHERE trace_id = ?
+      AND end_time_unix_nano IS NULL
+      AND (
+        last_seen_unix_nano IS NULL
+        OR CAST(last_seen_unix_nano AS INTEGER) < CAST(? AS INTEGER)
+      )
   `);
     const insertIssueProcess = db.prepare(`
     INSERT INTO issue_processes (
@@ -439,33 +556,64 @@ export function createStorage(path, opts = {}) {
            project_id, project_name, status_type
     FROM linear_snapshots
   `);
-    // VA-391: "active drain" = a trace_id with one or more
-    // issue_processes rows but no row in `drains`. The drain span
-    // hasn't been emitted yet (BatchSpanProcessor flushes on end), so
-    // we infer in-flight by the absence of the parent. Earliest
-    // start_time across the trace's issue_processes is the drain
-    // start; the counters slice by outcome_kind. LIMIT 1 picks the
-    // most-recently-started in-flight drain — v1 only runs one drain
-    // at a time but the SQL is robust to a future parallel mode.
+    // VA-391 + VA-455: "active drain" comes from two paths today.
+    //
+    //  (a) VA-455 log-driven: a `drains` row with end_time NULL and a
+    //      fresh `last_seen_unix_nano` (within the staleness window).
+    //      runway emits `Effect.logInfo("drain.started")` at the top
+    //      of the drainQueue span; the projector recognises that body
+    //      and inserts the row via `markDrainActive`. Subsequent log
+    //      records bump last_seen.
+    //
+    //  (b) VA-391 legacy fallback: a trace_id with issue_processes
+    //      rows but no `drains` row at all. Kept so dashboards running
+    //      against pre-VA-455 runway binaries still light up — once
+    //      the first processIssue ends.
+    //
+    // The two paths are mutually exclusive by construction (path (a)
+    // writes a `drains` row, which excludes the trace from path (b)).
+    // Among candidates, most-recently-started wins; v1 only runs one
+    // drain at a time but the SQL is robust to a future parallel mode.
+    //
+    // Bind param: the staleness floor in unix-nanos as a TEXT-encoded
+    // integer. Pass `String(BigInt(Date.now()) * 1_000_000n - staleness)`
+    // at call time so the query stays a static prepared statement.
     const getActiveDrainStmt = db.prepare(`
-    WITH active AS (
-      SELECT trace_id
+    WITH active_candidates AS (
+      SELECT
+        trace_id,
+        start_time_unix_nano AS started_at_unix_nano
+      FROM drains
+      WHERE end_time_unix_nano IS NULL
+        AND last_seen_unix_nano IS NOT NULL
+        AND CAST(last_seen_unix_nano AS INTEGER) > CAST(? AS INTEGER)
+
+      UNION ALL
+
+      SELECT
+        trace_id,
+        CAST(MIN(CAST(start_time_unix_nano AS INTEGER)) AS TEXT)
+          AS started_at_unix_nano
       FROM issue_processes
       WHERE trace_id NOT IN (SELECT trace_id FROM drains)
       GROUP BY trace_id
-      ORDER BY MIN(CAST(start_time_unix_nano AS INTEGER)) DESC
+    ),
+    chosen AS (
+      SELECT trace_id, started_at_unix_nano
+      FROM active_candidates
+      ORDER BY CAST(started_at_unix_nano AS INTEGER) DESC
       LIMIT 1
     )
     SELECT
-      ip.trace_id,
-      MIN(ip.start_time_unix_nano) AS started_at_unix_nano,
-      COUNT(*) AS issue_count,
-      SUM(CASE WHEN ip.outcome_kind = 'opened'  THEN 1 ELSE 0 END) AS opened_count,
-      SUM(CASE WHEN ip.outcome_kind = 'hitl'    THEN 1 ELSE 0 END) AS hitl_count,
-      SUM(CASE WHEN ip.outcome_kind = 'errored' THEN 1 ELSE 0 END) AS errored_count
-    FROM issue_processes ip
-    WHERE ip.trace_id = (SELECT trace_id FROM active)
-    GROUP BY ip.trace_id
+      c.trace_id,
+      c.started_at_unix_nano,
+      COUNT(ip.span_id) AS issue_count,
+      COALESCE(SUM(CASE WHEN ip.outcome_kind = 'opened'  THEN 1 ELSE 0 END), 0) AS opened_count,
+      COALESCE(SUM(CASE WHEN ip.outcome_kind = 'hitl'    THEN 1 ELSE 0 END), 0) AS hitl_count,
+      COALESCE(SUM(CASE WHEN ip.outcome_kind = 'errored' THEN 1 ELSE 0 END), 0) AS errored_count
+    FROM chosen c
+    LEFT JOIN issue_processes ip ON ip.trace_id = c.trace_id
+    GROUP BY c.trace_id, c.started_at_unix_nano
   `);
     const insertLogRecord = db.prepare(`
     INSERT INTO log_records (
@@ -507,7 +655,15 @@ export function createStorage(path, opts = {}) {
     ORDER BY CAST(timestamp_unix_nano AS INTEGER) ASC, span_id ASC
   `);
     const saveDrain = (d) => {
-        insertDrain.run(d.traceId, d.spanId, d.startTimeUnixNano, d.endTimeUnixNano, asInt(d.attempts), asInt(d.opened), asInt(d.hitl), asInt(d.errored), asInt(d.statusCode), d.statusMessage);
+        insertDrain.run(d.traceId, d.spanId, d.startTimeUnixNano, d.endTimeUnixNano, d.lastSeenUnixNano, asInt(d.attempts), asInt(d.opened), asInt(d.hitl), asInt(d.errored), asInt(d.statusCode), d.statusMessage);
+    };
+    // VA-455: log-marker-driven insert for in-flight drains. Called
+    // from server.ts when `projectLogs` surfaces a `drain.started`
+    // record (see `extractActiveDrainMarkers`). The first call lands
+    // the row with end_time NULL; subsequent calls (or any log on the
+    // trace flowing through `appendLogRecord`) push last_seen forward.
+    const markDrainActive = (m) => {
+        markActiveDrainStmt.run(m.traceId, m.spanId, m.startTimeUnixNano, m.lastSeenUnixNano);
     };
     const saveIssueProcess = (p) => {
         insertIssueProcess.run(p.traceId, p.spanId, p.parentSpanId, p.issueIdentifier, p.issueId, p.issueTitle, 
@@ -647,10 +803,20 @@ export function createStorage(path, opts = {}) {
         Object.keys(r.attributes).length === 0
             ? null
             : JSON.stringify(r.attributes));
+        // VA-455: piggy-back on every log record to keep the trace's
+        // active-drain row "alive" — drives the staleness TTL in
+        // getActiveDrain. No-op when no active drain exists for the
+        // trace (UPDATE matches zero rows).
+        bumpDrainLastSeenStmt.run(r.timestampUnixNano, r.traceId, r.timestampUnixNano);
     };
     const streamLogsFor = (traceId) => listLogsByTrace.all(traceId).map(rowToLogRecord);
     const getActiveDrain = () => {
-        const row = getActiveDrainStmt.get();
+        // VA-455: staleness floor — drains whose most recent log record
+        // is older than this no longer count as active. Matches the 30s
+        // heartbeat cadence on the runway side with a 3× safety margin
+        // so a single dropped heartbeat doesn't toggle the card to Idle.
+        const stalenessFloorNanos = BigInt(Date.now()) * 1000000n - ACTIVE_DRAIN_STALENESS_NANOS;
+        const row = getActiveDrainStmt.get(String(stalenessFloorNanos));
         if (!row || row.trace_id == null)
             return null;
         return {
@@ -758,6 +924,7 @@ export function createStorage(path, opts = {}) {
     };
     return {
         saveDrain,
+        markDrainActive,
         saveIssueProcess,
         saveAgentIteration,
         saveRawSpan,

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { Effect } from "effect";
+import { Duration, Effect, Schedule } from "effect";
 import { detectBaseBranch, pruneStaleAgentBranch } from "./git.js";
 import { loadPolicy } from "./policy.js";
 import { flagHitl, handleProcessFailure } from "./hitl.js";
@@ -41,6 +41,19 @@ export function assertSandcastleInitialised(cwd) {
 export const drainQueue = (deps, opts = {}) => Effect.gen(function* () {
     const { config, linear } = deps;
     const max = opts.max ?? Number.POSITIVE_INFINITY;
+    // VA-455: announce the drain to the dashboard before any other
+    // work. The log carries the drainQueue span's trace_id/span_id
+    // (we're already inside `Effect.withSpan("drainQueue")`), and the
+    // dashboard's projector matches on the literal body string —
+    // keep it in lock-step with `DRAIN_STARTED_LOG` in projector.ts.
+    yield* Effect.logInfo("drain.started");
+    // VA-455: keep the dashboard's "still alive" signal warm during
+    // long impl/review phases. `Effect.fork` ties the heartbeat fiber
+    // to this gen's lifetime, so it's interrupted automatically when
+    // drainQueue completes (success, failure, or interrupt). The 30s
+    // cadence matches `ACTIVE_DRAIN_STALENESS_NANOS / 3` on the
+    // dashboard so a single dropped flush doesn't toggle the card.
+    yield* Effect.fork(Effect.logInfo("drain.heartbeat").pipe(Effect.repeat(Schedule.spaced(Duration.seconds(30)))));
     // 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).

package/dist/repo-upgrade.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { AUTH_MODE_ENV_VAR, TEMPLATES_DIR, } from "./scaffolder.js";
 import { buildAgentImage } from "./scaffolder-image.js";
@@ -80,7 +80,36 @@ export function parseOpRefs(schema, opts) {
 // ---------------------------------------------------------------------------
 // Render: Dockerfile
 // ---------------------------------------------------------------------------
-function renderDockerfile(cwd, tier, opts, enforceManualEditGuard) {
+/**
+ * VA-466: read every historical snapshot under `templates/history/`
+ * that matches the base Dockerfile naming pattern, flatten them to
+ * the set of lines that have ever shipped as canonical content.
+ *
+ * Files are named `Dockerfile.claude-code.base.v<n>` (where `<n>` is
+ * the runway version that owned that exact content). The detector
+ * doesn't care about version ordering — it just needs the union of
+ * lines so a target Dockerfile rendered at any prior version doesn't
+ * trigger false-positive "manual edit" reports.
+ *
+ * Missing or empty `history/` directory returns an empty list — both
+ * are valid states (a fresh checkout that hasn't accumulated history
+ * yet, or a tier-1 repo whose template never changed).
+ */
+function historicalBaseTemplateLines() {
+    const historyDir = join(TEMPLATES_DIR, "history");
+    if (!existsSync(historyDir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(historyDir)) {
+        if (!name.startsWith("Dockerfile.claude-code.base"))
+            continue;
+        const contents = readFileSync(join(historyDir, name), "utf8");
+        for (const line of contents.split("\n"))
+            out.push(line);
+    }
+    return out;
+}
+export function renderDockerfile(cwd, tier, opts, enforceManualEditGuard) {
     const dockerfilePath = join(cwd, ".sandcastle", "Dockerfile");
     const before = readFileSync(dockerfilePath, "utf8");
     const base = readFileSync(join(TEMPLATES_DIR, "Dockerfile.claude-code.base"), "utf8");
@@ -98,8 +127,22 @@ function renderDockerfile(cwd, tier, opts, enforceManualEditGuard) {
     }
     // Detect manual user edits: any line in `before` that isn't in the
     // expected re-rendered output is foreign. Warn loudly unless --force.
+    //
+    // VA-466: expectedLines unions the current template with every
+    // historical canonical template snapshot under `templates/history/`.
+    // Without this, a target repo's Dockerfile rendered by an older
+    // runway version flags every cross-version line delta as a "manual
+    // edit" — false-positive that forces operators to pass `--force`
+    // and lose the detector's real signal. Each release that mutates
+    // `Dockerfile.claude-code.base` snapshots the prior version into
+    // `templates/history/Dockerfile.claude-code.base.v<n>` BEFORE the
+    // edit lands; the detector unions all of them so any line that
+    // ever shipped as canonical stays trusted.
     if (before !== after && !opts.force && enforceManualEditGuard) {
         const expectedLines = new Set(after.split("\n"));
+        for (const line of historicalBaseTemplateLines()) {
+            expectedLines.add(line);
+        }
         const foreign = before
             .split("\n")
             .filter((l) => l.trim().length && !expectedLines.has(l));

package/dist/review.js

@@ -79,7 +79,14 @@ export const runReviewPass = (issue, deps, branch) => Effect.gen(function* () {
             sandbox: docker({ env: dockerEnv(config) }),
             cwd,
             prompt: reviewPrompt,
-            branchStrategy: { type: "head" },
+            // VA-456: review must check out the impl agent's branch
+            // explicitly. The previous `{ type: "head" }` inherited
+            // whatever branch the operator happened to be on in the
+            // main checkout — when that wasn't `branch`, the reviewer
+            // saw a working tree that didn't reconcile with the diff in
+            // its prompt and stalled silently until sandcastle's idle
+            // timeout fired (10 min of dead air, then INFRA_ERROR).
+            branchStrategy: { type: "branch", branch },
             maxIterations: 1,
             name: `review-${issue.identifier}`,
         });

package/dist/sandcastle.js

@@ -1,5 +1,55 @@
 import { run } from "@ai-hero/sandcastle";
 import { Effect, Redacted } from "effect";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * VA-454: when sandcastle throws, its `Error.message` is opaque
+ * (`claude-code exited with code 1:` with no body — the colon is
+ * literal, the stderr text goes only to the log file). To stop
+ * operators from having to hunt `.sandcastle/logs/` for the real
+ * cause on every failure, we read the tail of the most-recently
+ * modified log file in the project's `.sandcastle/logs/` directory
+ * and append it to the error message.
+ *
+ * Tail is read by capping the byte window (cheap on huge logs) and
+ * then trimming to the last `maxLines`. A missing directory or a
+ * read error degrades silently — the error path must not be the
+ * source of a NEW error.
+ */
+const SANDCASTLE_LOG_TAIL_LINES = 20;
+const SANDCASTLE_LOG_TAIL_MAX_BYTES = 16 * 1024;
+export function readLatestSandcastleLogTail(cwd, maxLines = SANDCASTLE_LOG_TAIL_LINES) {
+    try {
+        const dir = join(cwd, ".sandcastle", "logs");
+        const entries = readdirSync(dir);
+        let newestPath = null;
+        let newestMtime = -Infinity;
+        for (const name of entries) {
+            if (!name.endsWith(".log"))
+                continue;
+            const path = join(dir, name);
+            const mtime = statSync(path).mtimeMs;
+            if (mtime > newestMtime) {
+                newestMtime = mtime;
+                newestPath = path;
+            }
+        }
+        if (!newestPath)
+            return null;
+        const size = statSync(newestPath).size;
+        const offset = Math.max(0, size - SANDCASTLE_LOG_TAIL_MAX_BYTES);
+        const buf = readFileSync(newestPath);
+        // Trim trailing newline BEFORE splitting so a `…line 200\n` file
+        // doesn't yield an empty final element that eats one slot in the
+        // `slice(-maxLines)` window.
+        const tail = buf.subarray(offset).toString("utf8").replace(/\n+$/, "");
+        const lines = tail.split("\n");
+        return lines.slice(-maxLines).join("\n");
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * VA-358: thin Effect wrapper around `sandcastle.run`. The agent run
  * happens inside Docker — sandcastle doesn't (yet) expose a kill
@@ -12,9 +62,18 @@ import { Effect, Redacted } from "effect";
  */
 export const runSandcastle = (args) => Effect.tryPromise({
     try: () => run(args),
-    catch: (err) => ({
-        message: err instanceof Error ? err.message : String(err),
-    }),
+    catch: (err) => {
+        const base = err instanceof Error ? err.message : String(err);
+        // VA-454: append the tail of the most-recent `.sandcastle/logs/`
+        // file so the operator sees the real cause (e.g. "Invalid API
+        // key · Fix external API key") on the same line as the
+        // INFRA_ERROR — instead of having to scroll back to the run-
+        // start banner for the log path and open it.
+        const tail = readLatestSandcastleLogTail(args.cwd ?? process.cwd());
+        return {
+            message: tail ? `${base}\n${tail}` : base,
+        };
+    },
 });
 /**
  * Env vars to inject into every sandcastle container. Today this is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valescoagency/runway",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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": {

package/templates/Dockerfile.claude-code.base

@@ -49,19 +49,29 @@ ENV HOME=/home/agent
 ENV XDG_CACHE_HOME=/home/agent/.cache
 ENV TURBO_CACHE_DIR=/tmp/turbo-cache
 ENV pnpm_config_cache=/home/agent/.cache/pnpm
+# VA-457: pin corepack's data dir under the agent's cache. `corepack
+# prepare` below runs as root (before the USER switch), so without
+# COREPACK_HOME it would write the cached pnpm tarball to /root's
+# default and the agent UID couldn't read it. Anything that resolves
+# `pnpm` through the corepack shim after `USER` — git hooks invoked
+# by lefthook in particular — then fails or hangs trying to refetch.
+ENV COREPACK_HOME=/home/agent/.cache/corepack
 
 # 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/pnpm /tmp/turbo-cache \
+RUN mkdir -p /home/agent/.cache /home/agent/.cache/pnpm /home/agent/.cache/corepack /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`.
+# `corepack use`. COREPACK_HOME is set above so the data dir lands
+# under /home/agent/.cache/corepack; the trailing chown re-asserts
+# agent ownership over the files root just wrote there.
 RUN corepack enable \
- && corepack prepare pnpm@11.1.1 --activate
+ && corepack prepare pnpm@11.1.1 --activate \
+ && chown -R $AGENT_UID:$AGENT_GID /home/agent/.cache/corepack
 
 USER ${AGENT_UID}:${AGENT_GID}
 

package/templates/history/Dockerfile.claude-code.base.v0.13.0

@@ -0,0 +1,79 @@
+# Canonical claude-code Dockerfile — vendored from
+# @ai-hero/sandcastle's InitService.ts (CLAUDE_CODE_DOCKERFILE constant).
+# Kept here so `runway init` can write it directly, without invoking
+# `sandcastle init` (which has interactive prompts that hang in
+# non-TTY environments like CI / Mac Mini cron).
+#
+# Drift policy: when sandcastle bumps its claude-code Dockerfile,
+# refresh this file. The diff should be tiny — runway's tier 2 layer
+# patches AFTER this base, so adopters re-run `runway init --force`
+# to roll forward.
+
+FROM node:24-bookworm
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  git \
+  curl \
+  jq \
+  && rm -rf /var/lib/apt/lists/*
+
+# Build-args for UID/GID alignment: defaults match the host user's
+# UID/GID at build time so image-built files and bind-mounted files
+# share an owner without runtime chown.
+ARG AGENT_UID=1000
+ARG AGENT_GID=1000
+
+# Rename the base image's "node" user to "agent" and align UID/GID.
+#
+# Divergence from sandcastle's stock Dockerfile: stock runs
+# `groupmod -g $AGENT_GID node` unconditionally, which fails on macOS
+# hosts where the host GID is 20 (`staff`) — Debian's `dialout` group
+# already has GID 20, and `groupmod` refuses to assign a duplicate
+# GID. We guard with `getent group` so groupmod only runs if the
+# target GID is unused; if it's already taken, we point the agent
+# user at the pre-existing group via `usermod -g <gid>` and the
+# image still works (the in-image group name is irrelevant — only the
+# numeric GID matters for bind-mount permissions).
+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 pnpm_config_cache=/home/agent/.cache/pnpm
+
+# 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/pnpm /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@11.1.1 --activate
+
+USER ${AGENT_UID}:${AGENT_GID}
+
+# Install Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+
+# Add Claude to PATH
+ENV PATH="/home/agent/.local/bin:$PATH"
+
+WORKDIR /home/agent
+
+# In worktree sandbox mode, Sandcastle bind-mounts the git worktree at
+# the sandbox repo dir and overrides the working directory to that dir
+# at container start.
+ENTRYPOINT ["sleep", "infinity"]