@valescoagency/runway 0.14.3 → 0.16.0

package/dist/dashboard/server.js

@@ -1,12 +1,21 @@
 import { createServer } from "node:http";
 import { createLinearAdapter, startLinearSync, } from "./linear-sync.js";
 import { createEventBus } from "./events.js";
-import { extractActiveDrainMarkers, projectLogs, projectPayload, } from "./projector.js";
+import { extractActiveDrainMarkers, extractPlannerMarkers, projectLogs, projectPayload, } from "./projector.js";
 import { createStorage, } from "./storage.js";
-import { META_REVIEW_PAGE_SIZE, renderDetailView, renderIssueProcessRows, renderListView, renderLogsSection, renderMetaReviewDetailView, renderMetaReviewListView, } from "./views.js";
+import { META_REVIEW_PAGE_SIZE, renderDetailView, renderIssueProcessRows, renderListView, renderLogsSection, renderMetaReviewDetailView, renderMetaReviewListView, renderPlannerPanel, } from "./views.js";
 // VA-389: phase spans we surface on the detail page's timeline.
 // Anything else stays in raw_spans for debugging but isn't rendered.
-const DETAIL_PHASE_NAMES = ["review", "pushBranch", "openPullRequest"];
+const DETAIL_PHASE_NAMES = [
+    "review",
+    "pushBranch",
+    "openPullRequest",
+    // VA-460 → VA-482: legacy `shepherd` span surfaced inline by the
+    // retired post-finalize loop. Kept in the allowlist so historical
+    // traces (issue_processes rows written before VA-482) still
+    // render their fourth phase row; new traces never emit it.
+    "shepherd",
+];
 const ISSUE_DETAIL_RE = /^\/issue\/([^/?#]+)\/([^/?#]+)\/?$/;
 // VA-387: canonical detail route. `:id` is the issue process span_id;
 // the lookup falls back to the (trace_id, span_id) pair only for
@@ -143,6 +152,35 @@ async function handle(req, res, storage, linearEnabled, linearWorkspace, events)
         handleAggregates(res, storage);
         return;
     }
+    // VA-481: planner panel — recommendations + capability modes.
+    if (method === "GET" && (url === "/planner" || url.startsWith("/planner?"))) {
+        handlePlannerPanel(res, storage);
+        return;
+    }
+    // VA-481: proxy routes that forward to the Tailscale-gated planner
+    // HTTP API. Browser forms POST to the dashboard's same-origin path;
+    // the dashboard server-side forwards to RUNWAY_PLANNER_BASE_URL so
+    // the planner's same-origin CORS guard is satisfied. The
+    // dashboard never inspects request bodies beyond passthrough — the
+    // planner remains the source of truth.
+    const pathOnly = url.split("?")[0] ?? "";
+    if (method === "POST") {
+        const acceptMatch = pathOnly.match(/^\/planner-actions\/recommendations\/([^/]+)\/accept$/);
+        if (acceptMatch) {
+            await handlePlannerProxy(req, res, `/planner/recommendations/${encodeURIComponent(acceptMatch[1] ?? "")}/accept`, "POST");
+            return;
+        }
+        const rejectMatch = pathOnly.match(/^\/planner-actions\/recommendations\/([^/]+)\/reject$/);
+        if (rejectMatch) {
+            await handlePlannerProxy(req, res, `/planner/recommendations/${encodeURIComponent(rejectMatch[1] ?? "")}/reject`, "POST");
+            return;
+        }
+        const capMatch = pathOnly.match(/^\/planner-actions\/capabilities\/([a-z-]+)$/i);
+        if (capMatch) {
+            await handlePlannerProxy(req, res, `/planner/capabilities/${encodeURIComponent(capMatch[1] ?? "")}`, "PUT");
+            return;
+        }
+    }
     if (method === "GET" && url === "/healthz") {
         res.writeHead(200, { "content-type": "text/plain" });
         res.end("ok");
@@ -247,6 +285,71 @@ async function handleOtlpLogs(req, res, storage, events) {
     for (const m of extractActiveDrainMarkers(payload)) {
         storage.markDrainActive(m);
     }
+    // VA-482: the inline shepherd's three lifecycle markers
+    // (shepherd.iteration.start / iteration.end / ended) are gone —
+    // the planner emits `planner.action.*` for the same shape of work
+    // via the capability dispatchers (VA-477..479).
+    // VA-474: planner event markers — six log bodies cover the
+    // recommendation lifecycle (proposed / accepted / rejected) and
+    // the action lifecycle (started / completed / failed). All five
+    // storage writers are idempotent on their primary keys; an OTLP
+    // retry or duplicate delivery is a no-op.
+    for (const m of extractPlannerMarkers(payload)) {
+        switch (m.kind) {
+            case "recommendation.proposed":
+                storage.recordPlannerRecommendationProposed({
+                    recommendationId: m.recommendationId,
+                    capability: m.capability,
+                    target: m.target,
+                    summary: m.summary,
+                    evidence: m.evidence,
+                    autoApproveEligible: m.autoApproveEligible,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+            case "recommendation.accepted":
+            case "recommendation.rejected":
+                storage.recordPlannerRecommendationDecision({
+                    recommendationId: m.recommendationId,
+                    status: m.status,
+                    source: m.source,
+                    reason: m.reason,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+            case "action.started":
+                storage.recordPlannerActionStarted({
+                    actionId: m.actionId,
+                    recommendationId: m.recommendationId,
+                    capability: m.capability,
+                    target: m.target,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+            case "action.completed":
+                storage.recordPlannerActionCompleted({
+                    actionId: m.actionId,
+                    outcome: m.outcome,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+            case "action.failed":
+                storage.recordPlannerActionFailed({
+                    actionId: m.actionId,
+                    error: m.error,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+            case "capability.mode_changed":
+                storage.recordPlannerCapabilityModeChange({
+                    capability: m.capability,
+                    mode: m.mode,
+                    updatedBy: m.updatedBy,
+                    timestampUnixNano: m.timestampUnixNano,
+                });
+                break;
+        }
+    }
     for (const r of projectLogs(payload)) {
         storage.appendLogRecord(r);
         // VA-391: the SSE detail-pane stream live-tails the Logs section
@@ -380,6 +483,8 @@ function handleListView(req, res, storage, linearEnabled, linearWorkspace) {
     // `drains` row). `null` becomes the "Idle — no active drain"
     // state in views.
     const activeDrain = storage.getActiveDrain();
+    // VA-465 → VA-482: the inline shepherd sub-strip is retired; per-PR
+    // state now lives in the planner panel at `/planner`.
     const html = renderListView({
         rows,
         linearEnabled,
@@ -536,6 +641,132 @@ function handleAggregates(res, storage) {
     res.writeHead(200, { "content-type": "application/json" });
     res.end(JSON.stringify({ view: "evaluator_aggregates_v1", rows }));
 }
+const KNOWN_PLANNER_CAPABILITIES = [
+    { capability: "queue-selection" },
+    { capability: "shepherd-mergeability" },
+    { capability: "shepherd-ci" },
+    { capability: "shepherd-reviewer" },
+];
+/**
+ * VA-481: forward an operator-initiated POST/PUT from the dashboard
+ * UI to the planner's HTTP API. The dashboard runs as a separate
+ * process; making the call server-side preserves the planner's
+ * same-origin CORS guard without an allowlist. Body is parsed from
+ * the operator's HTML form (urlencoded `reason=...` for reject,
+ * `mode=...` for capability toggle) and re-serialized as JSON for
+ * the planner. On success/202 from the planner, the dashboard 303s
+ * back to `/planner` so the operator sees the refreshed list.
+ */
+async function handlePlannerProxy(req, res, plannerPath, method) {
+    const baseUrl = process.env.RUNWAY_PLANNER_BASE_URL ?? "http://127.0.0.1:3002";
+    // Parse the form body — content-type may be application/json (api)
+    // or application/x-www-form-urlencoded (form submit).
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+        // Match the planner's 64 KiB cap so a giant body doesn't OOM.
+        const total = chunks.reduce((s, c) => s + c.length, 0);
+        if (total > 64 * 1024) {
+            res.writeHead(413, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: { code: "payload_too_large", message: "body too large" } }));
+            return;
+        }
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    const ct = String(req.headers["content-type"] ?? "").toLowerCase();
+    let bodyJson;
+    if (ct.includes("application/x-www-form-urlencoded")) {
+        const params = new URLSearchParams(raw);
+        const obj = {};
+        for (const [k, v] of params.entries()) {
+            if (v.length > 0)
+                obj[k] = v;
+        }
+        bodyJson = JSON.stringify(obj);
+    }
+    else if (raw.length === 0) {
+        bodyJson = "{}";
+    }
+    else {
+        bodyJson = raw; // assume JSON; let planner validate
+    }
+    let upstream;
+    try {
+        upstream = await fetch(`${baseUrl}${plannerPath}`, {
+            method,
+            headers: { "content-type": "application/json" },
+            body: bodyJson,
+        });
+    }
+    catch (err) {
+        res.writeHead(502, { "content-type": "application/json" });
+        res.end(JSON.stringify({
+            error: {
+                code: "planner_unreachable",
+                message: err instanceof Error ? err.message : String(err),
+            },
+        }));
+        return;
+    }
+    // Form submissions expect a 303 redirect back to the panel. JSON
+    // clients (curl / fetch from a script) get the planner's status
+    // mirrored verbatim. The dashboard distinguishes via the
+    // `Accept` header — browser form posts default to text/html.
+    const accept = String(req.headers.accept ?? "").toLowerCase();
+    const wantsRedirect = accept.includes("text/html") &&
+        upstream.status >= 200 &&
+        upstream.status < 400;
+    if (wantsRedirect) {
+        res.writeHead(303, { Location: "/planner" });
+        res.end();
+        return;
+    }
+    const upstreamBody = await upstream.text();
+    res.writeHead(upstream.status, {
+        "content-type": upstream.headers.get("content-type") ?? "application/json",
+    });
+    res.end(upstreamBody);
+}
+function handlePlannerPanel(res, storage) {
+    const explicit = storage.listPlannerCapabilityModes();
+    const byCap = new Map(explicit.map((r) => [r.capability, r]));
+    const capabilities = KNOWN_PLANNER_CAPABILITIES.map((c) => {
+        const row = byCap.get(c.capability);
+        return row
+            ? {
+                capability: row.capability,
+                mode: row.mode,
+                updatedUnixNano: row.updatedUnixNano,
+                updatedBy: row.updatedBy,
+            }
+            : {
+                capability: c.capability,
+                mode: "suggest",
+                updatedUnixNano: null,
+                updatedBy: null,
+            };
+    });
+    const recommendations = storage
+        .getRecentPlannerRecommendations(20)
+        .map((r) => ({
+        recommendationId: r.recommendationId,
+        capability: r.capability,
+        target: r.target,
+        summary: r.summary,
+        status: r.status,
+        autoApproveEligible: r.autoApproveEligible,
+        proposedUnixNano: r.proposedUnixNano,
+        decidedBy: r.decidedBy,
+    }));
+    const plannerBaseUrl = process.env.RUNWAY_PLANNER_BASE_URL ?? "http://127.0.0.1:3002";
+    const html = renderPlannerPanel({
+        capabilities,
+        recommendations,
+        plannerBaseUrl,
+    });
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+}
 /**
  * VA-407: GET `/meta-reviews` — paginated list view of meta_reviews
  * rows. `?kind=<kind>` narrows to one kind; `?page=N` is 1-based and

package/dist/dashboard/storage.js

@@ -159,6 +159,88 @@ const SCHEMA = `
 
   CREATE INDEX IF NOT EXISTS idx_meta_reviews_kind_created
     ON meta_reviews(kind, created_at DESC);
+
+  -- VA-465: per-PR shepherding state surfaced as a sub-card under the
+  -- active-drain card. One row per (trace_id, pr_number); the watcher
+  -- loop may iterate multiple times per PR before exiting. State
+  -- transitions acting -> ready/merged/hitl; the latter three are
+  -- terminal and set ended_unix_nano. The projector's three
+  -- shepherd.* log markers feed this table; the list view reads
+  -- getActiveShepherding(traceId) (non-terminal rows only).
+  CREATE TABLE IF NOT EXISTS shepherding_prs (
+    trace_id TEXT NOT NULL,
+    pr_number INTEGER NOT NULL,
+    subscription TEXT,
+    iteration INTEGER,
+    max_iterations INTEGER,
+    state TEXT NOT NULL,
+    description TEXT,
+    started_unix_nano TEXT NOT NULL,
+    last_seen_unix_nano TEXT NOT NULL,
+    ended_unix_nano TEXT,
+    inserted_at TEXT NOT NULL DEFAULT (datetime('now')),
+    PRIMARY KEY (trace_id, pr_number)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_shepherding_prs_trace_active
+    ON shepherding_prs(trace_id, ended_unix_nano);
+
+  -- VA-474: planner-daemon event projections (ADR 0004). Two
+  -- read-projections written exclusively by handleOtlpLogs, one
+  -- per top-level event class. The planner itself never writes
+  -- here — these tables exist on the dashboard side of the OTLP
+  -- boundary.
+  --
+  -- evidence_json round-trips JSON; auto_approve_eligible is a
+  -- 0/1 INTEGER. decided_* are NULL while status='proposed'.
+  CREATE TABLE IF NOT EXISTS planner_recommendations (
+    recommendation_id TEXT PRIMARY KEY,
+    capability TEXT NOT NULL,
+    target TEXT NOT NULL,
+    summary TEXT NOT NULL,
+    evidence_json TEXT NOT NULL DEFAULT '{}',
+    status TEXT NOT NULL,
+    proposed_unix_nano TEXT NOT NULL,
+    decided_unix_nano TEXT,
+    decided_by TEXT,
+    decision_reason TEXT,
+    auto_approve_eligible INTEGER NOT NULL DEFAULT 0,
+    inserted_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_planner_recommendations_status
+    ON planner_recommendations(status, proposed_unix_nano);
+
+  -- recommendation_id is nullable because an action could in
+  -- principle fire without a prior recommendation (e.g. operator-
+  -- triggered direct invocation in VA-475). v1 callers always set
+  -- it; the column shape leaves room for the looser case.
+  CREATE TABLE IF NOT EXISTS planner_actions (
+    action_id TEXT PRIMARY KEY,
+    recommendation_id TEXT,
+    capability TEXT NOT NULL,
+    target TEXT NOT NULL,
+    status TEXT NOT NULL,
+    started_unix_nano TEXT NOT NULL,
+    ended_unix_nano TEXT,
+    outcome TEXT,
+    error TEXT,
+    inserted_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_planner_actions_status
+    ON planner_actions(status, started_unix_nano);
+
+  -- VA-481: per-capability mode (manual / suggest / auto). One row
+  -- per capability; defaults to 'suggest' on first observation. The
+  -- planner reads this table on every tick to decide whether to
+  -- propose, auto-accept, or stay silent for a given capability.
+  CREATE TABLE IF NOT EXISTS planner_capability_modes (
+    capability TEXT PRIMARY KEY,
+    mode TEXT NOT NULL,
+    updated_unix_nano TEXT NOT NULL,
+    updated_by TEXT NOT NULL
+  );
 `;
 const DEFAULT_AGGREGATE_WINDOW = 30;
 /**
@@ -673,6 +755,219 @@ export function createStorage(path, opts = {}) {
     const markDrainActive = (m) => {
         markActiveDrainStmt.run(m.traceId, m.spanId, m.startTimeUnixNano, m.lastSeenUnixNano);
     };
+    // VA-465: shepherd-state prepared statements.
+    //
+    // `markShepherdIterationStartStmt` inserts on first iteration or
+    // updates an existing row to bump the iteration / subscription /
+    // description / last_seen. The CONFLICT branch only overwrites
+    // when (a) the row isn't already terminated AND (b) the incoming
+    // timestamp is newer than the stored last_seen — protects against
+    // out-of-order batch arrival.
+    const markShepherdIterationStartStmt = db.prepare(`
+    INSERT INTO shepherding_prs (
+      trace_id, pr_number, subscription, iteration, max_iterations,
+      state, description, started_unix_nano, last_seen_unix_nano
+    ) VALUES (?, ?, ?, ?, ?, 'acting', ?, ?, ?)
+    ON CONFLICT (trace_id, pr_number) DO UPDATE SET
+      subscription = excluded.subscription,
+      iteration = excluded.iteration,
+      max_iterations = COALESCE(excluded.max_iterations, shepherding_prs.max_iterations),
+      state = 'acting',
+      description = excluded.description,
+      last_seen_unix_nano = excluded.last_seen_unix_nano
+    WHERE shepherding_prs.ended_unix_nano IS NULL
+      AND CAST(shepherding_prs.last_seen_unix_nano AS INTEGER)
+        < CAST(excluded.last_seen_unix_nano AS INTEGER)
+  `);
+    // `markShepherdIterationEndStmt` bumps last_seen + description on
+    // a row that exists. UPDATE-only (no INSERT) — an end without a
+    // start is dropped silently.
+    const markShepherdIterationEndStmt = db.prepare(`
+    UPDATE shepherding_prs
+    SET description = ?, last_seen_unix_nano = ?
+    WHERE trace_id = ? AND pr_number = ?
+      AND ended_unix_nano IS NULL
+      AND CAST(last_seen_unix_nano AS INTEGER) < CAST(? AS INTEGER)
+  `);
+    // `markShepherdEndedStmt` terminates the row. The CASE WHEN guard
+    // protects against a stale end-marker arriving after a fresher
+    // start (which can happen with batched OTLP flushes).
+    const markShepherdEndedStmt = db.prepare(`
+    INSERT INTO shepherding_prs (
+      trace_id, pr_number, state, started_unix_nano,
+      last_seen_unix_nano, ended_unix_nano
+    ) VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT (trace_id, pr_number) DO UPDATE SET
+      state = excluded.state,
+      last_seen_unix_nano = excluded.last_seen_unix_nano,
+      ended_unix_nano = excluded.ended_unix_nano
+    WHERE shepherding_prs.ended_unix_nano IS NULL
+      OR CAST(shepherding_prs.ended_unix_nano AS INTEGER)
+        < CAST(excluded.ended_unix_nano AS INTEGER)
+  `);
+    const getActiveShepherdingStmt = db.prepare(`
+    SELECT
+      trace_id, pr_number, subscription, iteration, max_iterations,
+      state, description, started_unix_nano, last_seen_unix_nano,
+      ended_unix_nano
+    FROM shepherding_prs
+    WHERE trace_id = ? AND ended_unix_nano IS NULL
+    ORDER BY CAST(started_unix_nano AS INTEGER) ASC
+  `);
+    const markShepherdIterationStart = (m) => {
+        markShepherdIterationStartStmt.run(m.traceId, m.prNumber, m.subscription, m.iteration, m.maxIterations, m.description, m.timestampUnixNano, m.timestampUnixNano);
+    };
+    const markShepherdIterationEnd = (m) => {
+        markShepherdIterationEndStmt.run(m.detail, m.timestampUnixNano, m.traceId, m.prNumber, m.timestampUnixNano);
+    };
+    const markShepherdEnded = (m) => {
+        // VA-465: only `merged` terminates the row (sets ended_unix_nano
+        // → excluded from getActiveShepherding). `ready` and `hitl`
+        // leave ended_unix_nano NULL so the sub-strip continues to
+        // render them as "ready, awaiting human merge" / "HITL — needs
+        // human attention" rows while the drain is still active. The
+        // rows naturally disappear when the drain ends, since the list
+        // view only queries getActiveShepherding when activeDrain is
+        // non-null.
+        const endedNano = m.outcome === "merged" ? m.timestampUnixNano : null;
+        markShepherdEndedStmt.run(m.traceId, m.prNumber, m.outcome, m.timestampUnixNano, m.timestampUnixNano, endedNano);
+    };
+    // VA-474: planner-daemon event projections. Five write methods
+    // (proposed / decision / action-started / action-completed /
+    // action-failed) all guarded for idempotency so OTLP retries +
+    // planner restarts can't corrupt state.
+    const insertPlannerRecommendationStmt = db.prepare(`
+    INSERT INTO planner_recommendations (
+      recommendation_id, capability, target, summary, evidence_json,
+      status, proposed_unix_nano, auto_approve_eligible
+    ) VALUES (?, ?, ?, ?, ?, 'proposed', ?, ?)
+    ON CONFLICT (recommendation_id) DO NOTHING
+  `);
+    const updatePlannerRecommendationDecisionStmt = db.prepare(`
+    UPDATE planner_recommendations
+    SET status = ?,
+        decided_unix_nano = ?,
+        decided_by = ?,
+        decision_reason = ?
+    WHERE recommendation_id = ? AND status = 'proposed'
+  `);
+    const insertPlannerActionStmt = db.prepare(`
+    INSERT INTO planner_actions (
+      action_id, recommendation_id, capability, target, status,
+      started_unix_nano
+    ) VALUES (?, ?, ?, ?, 'started', ?)
+    ON CONFLICT (action_id) DO NOTHING
+  `);
+    const updatePlannerActionCompletedStmt = db.prepare(`
+    UPDATE planner_actions
+    SET status = 'completed',
+        ended_unix_nano = ?,
+        outcome = ?
+    WHERE action_id = ? AND status = 'started'
+  `);
+    const updatePlannerActionFailedStmt = db.prepare(`
+    UPDATE planner_actions
+    SET status = 'failed',
+        ended_unix_nano = ?,
+        error = ?
+    WHERE action_id = ? AND status = 'started'
+  `);
+    const getRecentPlannerRecommendationsStmt = db.prepare(`
+    SELECT
+      recommendation_id, capability, target, summary, evidence_json,
+      status, proposed_unix_nano, decided_unix_nano, decided_by,
+      decision_reason, auto_approve_eligible
+    FROM planner_recommendations
+    ORDER BY CAST(proposed_unix_nano AS INTEGER) DESC
+    LIMIT ?
+  `);
+    const getPlannerRecommendationStmt = db.prepare(`
+    SELECT
+      recommendation_id, capability, target, summary, evidence_json,
+      status, proposed_unix_nano, decided_unix_nano, decided_by,
+      decision_reason, auto_approve_eligible
+    FROM planner_recommendations
+    WHERE recommendation_id = ?
+  `);
+    const getActivePlannerActionsStmt = db.prepare(`
+    SELECT
+      action_id, recommendation_id, capability, target, status,
+      started_unix_nano, ended_unix_nano, outcome, error
+    FROM planner_actions
+    WHERE status = 'started'
+    ORDER BY CAST(started_unix_nano AS INTEGER) ASC
+  `);
+    const recordPlannerRecommendationProposed = (m) => {
+        insertPlannerRecommendationStmt.run(m.recommendationId, m.capability, m.target, m.summary, JSON.stringify(m.evidence ?? {}), m.timestampUnixNano, m.autoApproveEligible ? 1 : 0);
+    };
+    const recordPlannerRecommendationDecision = (m) => {
+        updatePlannerRecommendationDecisionStmt.run(m.status, m.timestampUnixNano, m.source, m.reason, m.recommendationId);
+    };
+    const recordPlannerActionStarted = (m) => {
+        insertPlannerActionStmt.run(m.actionId, m.recommendationId, m.capability, m.target, m.timestampUnixNano);
+    };
+    const recordPlannerActionCompleted = (m) => {
+        updatePlannerActionCompletedStmt.run(m.timestampUnixNano, m.outcome, m.actionId);
+    };
+    const recordPlannerActionFailed = (m) => {
+        updatePlannerActionFailedStmt.run(m.timestampUnixNano, m.error, m.actionId);
+    };
+    // VA-481: capability-mode upsert. The WHERE clause ensures a stale
+    // marker doesn't clobber a newer mode change.
+    const upsertCapabilityModeStmt = db.prepare(`
+    INSERT INTO planner_capability_modes
+      (capability, mode, updated_unix_nano, updated_by)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT (capability) DO UPDATE SET
+      mode = excluded.mode,
+      updated_unix_nano = excluded.updated_unix_nano,
+      updated_by = excluded.updated_by
+    WHERE CAST(planner_capability_modes.updated_unix_nano AS INTEGER)
+      < CAST(excluded.updated_unix_nano AS INTEGER)
+  `);
+    const listCapabilityModesStmt = db.prepare(`
+    SELECT capability, mode, updated_unix_nano, updated_by
+    FROM planner_capability_modes
+  `);
+    const recordPlannerCapabilityModeChange = (m) => {
+        upsertCapabilityModeStmt.run(m.capability, m.mode, m.timestampUnixNano, m.updatedBy);
+    };
+    const listPlannerCapabilityModes = () => {
+        const rows = listCapabilityModesStmt.all();
+        return rows.map((r) => ({
+            capability: String(r.capability ?? ""),
+            mode: String(r.mode ?? "suggest"),
+            updatedUnixNano: String(r.updated_unix_nano ?? ""),
+            updatedBy: String(r.updated_by ?? "operator"),
+        }));
+    };
+    const getRecentPlannerRecommendations = (limit = 50) => {
+        const rows = getRecentPlannerRecommendationsStmt.all(limit);
+        return rows.map(rowToPlannerRecommendation);
+    };
+    const getPlannerRecommendation = (recommendationId) => {
+        const row = getPlannerRecommendationStmt.get(recommendationId);
+        return row ? rowToPlannerRecommendation(row) : undefined;
+    };
+    const getActivePlannerActions = () => {
+        const rows = getActivePlannerActionsStmt.all();
+        return rows.map(rowToPlannerAction);
+    };
+    const getActiveShepherding = (traceId) => {
+        const rows = getActiveShepherdingStmt.all(traceId);
+        return rows.map((r) => ({
+            traceId: r.trace_id,
+            prNumber: r.pr_number,
+            subscription: r.subscription,
+            iteration: r.iteration,
+            maxIterations: r.max_iterations,
+            state: r.state,
+            description: r.description,
+            startedUnixNano: r.started_unix_nano,
+            lastSeenUnixNano: r.last_seen_unix_nano,
+            endedUnixNano: r.ended_unix_nano,
+        }));
+    };
     const saveIssueProcess = (p) => {
         insertIssueProcess.run(p.traceId, p.spanId, p.parentSpanId, p.issueIdentifier, p.issueId, p.issueTitle, 
         // VA-387: labels round-trip as a JSON array string. Keeping them
@@ -950,6 +1245,20 @@ export function createStorage(path, opts = {}) {
         appendLogRecord,
         streamLogsFor,
         getActiveDrain,
+        markShepherdIterationStart,
+        markShepherdIterationEnd,
+        markShepherdEnded,
+        getActiveShepherding,
+        recordPlannerRecommendationProposed,
+        recordPlannerRecommendationDecision,
+        recordPlannerActionStarted,
+        recordPlannerActionCompleted,
+        recordPlannerActionFailed,
+        recordPlannerCapabilityModeChange,
+        listPlannerCapabilityModes,
+        getRecentPlannerRecommendations,
+        getPlannerRecommendation,
+        getActivePlannerActions,
         saveMetaReview,
         listMetaReviews,
         countMetaReviews,
@@ -964,6 +1273,51 @@ export function createStorage(path, opts = {}) {
 function asInt(n) {
     return n === null || n === undefined ? null : n;
 }
+// VA-474: planner_recommendations row → PlannerRecommendationRow.
+// `evidence_json` round-trips JSON; malformed JSON collapses to {}
+// rather than crashing the read path (an emitter bug shouldn't take
+// the dashboard down).
+function rowToPlannerRecommendation(row) {
+    let evidence = {};
+    const raw = row.evidence_json;
+    if (typeof raw === "string" && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                evidence = parsed;
+            }
+        }
+        catch {
+            // Drop to default {} on malformed JSON.
+        }
+    }
+    return {
+        recommendationId: String(row.recommendation_id ?? ""),
+        capability: String(row.capability ?? ""),
+        target: String(row.target ?? ""),
+        summary: String(row.summary ?? ""),
+        evidence,
+        status: String(row.status ?? "proposed"),
+        proposedUnixNano: String(row.proposed_unix_nano ?? ""),
+        decidedUnixNano: nullableStr(row.decided_unix_nano),
+        decidedBy: nullableStr(row.decided_by),
+        decisionReason: nullableStr(row.decision_reason),
+        autoApproveEligible: Number(row.auto_approve_eligible ?? 0) === 1,
+    };
+}
+function rowToPlannerAction(row) {
+    return {
+        actionId: String(row.action_id ?? ""),
+        recommendationId: nullableStr(row.recommendation_id),
+        capability: String(row.capability ?? ""),
+        target: String(row.target ?? ""),
+        status: String(row.status ?? "started"),
+        startedUnixNano: String(row.started_unix_nano ?? ""),
+        endedUnixNano: nullableStr(row.ended_unix_nano),
+        outcome: nullableStr(row.outcome),
+        error: nullableStr(row.error),
+    };
+}
 function rowToIssueProcess(row) {
     const r = row;
     return {