@valescoagency/runway 0.14.3 → 0.16.0

package/README.md

@@ -8,13 +8,14 @@ coding-agent runs, then **drain** a Linear queue against it. Wraps
 inside Docker), [varlock](https://varlock.dev) + 1Password for
 zero-secrets-at-rest, and the `gh` CLI for PR creation.
 
-## Seven commands
+## Eight commands
 
 | | |
 |---|---|
 | `runway dash` | Bring up the operations dashboard (`up` / `logs` / `stop`). Wraps the published `ghcr.io/valescoagency/runway-dashboard` image so any runway-using project can run the dashboard without cloning runway. Ports bind to `127.0.0.1` only. |
 | `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 planner` | Run the planner daemon — a long-running host process that will own cross-PR shepherding and queue selection per [ADR 0004](docs/adr/0004-planner-daemon-architecture.md). VA-472 epic in flight; VA-473 ships the foreground scaffold (`runway planner run` boots a tick loop, no capabilities wired yet). |
 | `runway review` | Run an IRA retrospective pass. `runway review run --drain <trace-id> --issue <id>` grades one issue-process post-drain — loads the captured agent + reviewer reports from the dashboard, fetches hindsight (PR merge state, human review-thread comments, Linear follow-ups in the past 48h), pulls rolling norms for the issue's category (last 30 drains, via the VA-399 read-model), asks an Anthropic model for a structured `Run Review` with absolute + relative grading axes, writes it to a `runway-meta` Linear project + the dashboard's `meta_reviews` table. Scheduler-agnostic; usually invoked from cron or GitHub Actions ~18h after a drain. The drain-age delay is enforced by `RUNWAY_REVIEW_DELAY_HOURS` (default 18, constrained to the 12–24h band) — pass `--force` to override for one-off operator bypass. **`runway review drain --id <trace-id>`** (VA-406) grades a whole drain: reads every per-issue Run Review for the drain, asks the model for a structured `Drain Review` covering composition / sequencing / cross-issue patterns, files it in `runway-meta`. When the model marks a finding `severity: critical` (drain-unsafe or captured-data-lost), the IRA also escalates a `Bug` + `runway-meta-promoted` issue into the runway-repo project (set `RUNWAY_REPO_PROJECT_NAME` to scope by project; otherwise team-level). The Drain Review fires automatically in-process the moment every Run Review for a drain has landed — manual invocation is for scheduled / catch-up runs. |
 | `runway run` | Drain a Linear queue. For each issue carrying the `ready-for-agent` label: 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. |
@@ -218,6 +219,18 @@ export LINEAR_API_KEY=lin_api_...
 # export RUNWAY_READY_LABEL="ready-for-agent"
 # export RUNWAY_HITL_LABEL="ready-for-human"
 # export RUNWAY_MAX_ITERATIONS=5
+# VA-482: the four RUNWAY_SHEPHERD_* env vars have been retired.
+#   Mergeability / CI / reviewer-feedback work now flows through the
+#   `runway planner` daemon (capabilities VA-477..479). Boot the
+#   planner separately (`runway planner run`) and configure it with
+#   the RUNWAY_PLANNER_* env vars; the planner reads from the
+#   dashboard's SQLite file and emits OTLP back to the dashboard.
+# export RUNWAY_PR_REVIEWER_BOT_LOGIN="runway-reviewer-bot"
+#   VA-463 / VA-479: GitHub login of the adversarial PR-reviewer
+#   agent. Consumed by the planner's reviewer dispatcher to
+#   distinguish bot CHANGES-REQUESTED comments from human feedback
+#   (the latter routes through the LLM interpretation path).
+#   Unset → every comment lands on the human-feedback path.
 # export RUNWAY_COMMENT_AUTHOR_ALLOWLIST="Reviewer Bot,Jane Reviewer"
 #   optional, comma-separated Linear user names whose comments on a
 #   re-queued issue surface as "Review feedback from prior attempts"
@@ -541,7 +554,7 @@ These are tractable, just not v1.
 
 ## Status
 
-0.14.3 — production-shaped and dogfooded against live Linear queues.
+0.15.0 — 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/cli.js

@@ -2,6 +2,7 @@
 import { dashCommand, printDashUsage } from "./commands/dash.js";
 import { doctorCommand, printDoctorUsage } from "./commands/doctor.js";
 import { initCommand, printInitUsage } from "./commands/init.js";
+import { plannerCommand, printPlannerUsage } from "./commands/planner.js";
 import { reviewCommand, printReviewUsage } from "./commands/review.js";
 import { runCommand, printRunUsage } from "./commands/run.js";
 import { upgradeCommand, printUpgradeUsage } from "./commands/upgrade.js";
@@ -25,6 +26,12 @@ const SUBCOMMANDS = [
         run: initCommand,
         help: printInitUsage,
     },
+    {
+        name: "planner",
+        summary: "Run the planner daemon (queue selection + PR shepherding).",
+        run: plannerCommand,
+        help: printPlannerUsage,
+    },
     {
         name: "review",
         summary: "Run an IRA retrospective pass (run / drain / weekly).",

package/dist/commands/planner.js

@@ -0,0 +1,265 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Deferred, Effect, Layer, Logger, Runtime } from "effect";
+import { ConfigLive, ConfigTag } from "../config.js";
+import { installSignalHandlers, makeHealthReader, makePlannerLoop, makePlannerState, } from "../planner.js";
+import { PLANNER_CAPABILITY_MODE_CHANGED_LOG, PLANNER_RECOMMENDATION_ACCEPTED_LOG, PLANNER_RECOMMENDATION_REJECTED_LOG, } from "../dashboard/projector.js";
+import { createGithubGateway } from "../github.js";
+import { startPlannerHttpServer, } from "../planner-http.js";
+import { makeAnthropicCommentInterpreter } from "../planner-reviewer.js";
+import { createPlannerReadClient } from "../planner-storage.js";
+import { TelemetryLive } from "../telemetry.js";
+export function printPlannerUsage() {
+    console.log(`runway planner — long-running daemon for queue selection and PR shepherding
+
+Sub-1 scaffold (VA-473): boots the tick loop with no capabilities wired.
+Capabilities arrive in VA-474..VA-482 per ADR 0004.
+
+USAGE
+  runway planner run
+
+VERBS
+  run    Boot the planner in the foreground. Emits a planner.tick
+         heartbeat each RUNWAY_PLANNER_TICK_SECONDS. SIGINT / SIGTERM
+         triggers graceful shutdown (OTLP flush, then exit).
+
+OPTIONS
+  --help, -h    Show this help.
+
+ENDPOINTS (VA-475 / VA-481)
+  GET  /planner/health                                liveness probe
+  GET  /planner/recommendations[?status=&limit=N]     list (status: proposed|accepted|rejected|all)
+  GET  /planner/recommendations/:id                   single
+  POST /planner/recommendations/:id/accept            emits accepted
+  POST /planner/recommendations/:id/reject            emits rejected (requires { reason })
+  GET  /planner/actions[?status=]                     list (status: started|completed|failed|all)
+  GET  /planner/capabilities                          per-capability modes (VA-481)
+  PUT  /planner/capabilities/:capability              body { mode: "manual"|"suggest"|"auto" }
+
+  Auth is network-layer (Tailscale ACLs). Same-origin-only CORS —
+  browsers at a different origin are rejected; route through the
+  dashboard's backend.
+
+ENVIRONMENT
+  RUNWAY_PLANNER_TICK_SECONDS   default 30 — tick cadence.
+  RUNWAY_PLANNER_HOST           default 127.0.0.1 — HTTP bind host.
+                                Set to a tailnet IP to expose the API
+                                across your Tailscale network.
+  RUNWAY_PLANNER_PORT           default 3002 — HTTP bind port.
+  RUNWAY_PLANNER_SQLITE_PATH    optional — path to the dashboard's
+                                SQLite file (the planner opens it
+                                read-only). When unset, GET endpoints
+                                return 503; POST endpoints still emit
+                                OTLP (the dashboard validates on
+                                receive).
+
+  LINEAR_API_KEY                required (planner reads the queue).
+  OTEL_EXPORTER_OTLP_ENDPOINT   optional — when set, planner emissions
+                                stream to the dashboard's OTLP receiver.
+
+SUPERVISION
+  Mac mini operators: install the bundled launchd plist at
+    ~/Library/LaunchAgents/com.valescoagency.runway-planner.plist
+  (template ships at templates/com.valescoagency.runway-planner.plist
+  in the runway package) and run \`launchctl load\` once. launchd
+  restarts the planner on crash and on login.
+
+REFERENCES
+  ADR 0004 — Planner daemon architecture.
+  Epic VA-472 — Planner daemon (replatform shepherd).
+`);
+}
+export function parsePlannerArgs(argv) {
+    if (argv.length === 0) {
+        throw new Error("missing verb — expected `run`. Run `runway planner --help`.");
+    }
+    const [verbRaw, ...rest] = argv;
+    if (verbRaw === "--help" || verbRaw === "-h") {
+        printPlannerUsage();
+        process.exit(0);
+    }
+    if (verbRaw !== "run") {
+        throw new Error(`unknown verb "${verbRaw}" — expected \`run\`. Run \`runway planner --help\`.`);
+    }
+    for (const arg of rest) {
+        if (arg === "--help" || arg === "-h") {
+            printPlannerUsage();
+            process.exit(0);
+        }
+        throw new Error(`unknown argument: ${arg}`);
+    }
+    return { verb: "run" };
+}
+export async function plannerCommand(argv) {
+    parsePlannerArgs(argv);
+    const LoggerLive = process.env.RUNWAY_JSON_LOGS === "1"
+        ? Logger.replace(Logger.defaultLogger, Logger.jsonLogger)
+        : Layer.empty;
+    const MainLayer = Layer.mergeAll(ConfigLive, TelemetryLive, LoggerLive);
+    const program = Effect.gen(function* () {
+        const config = yield* ConfigTag;
+        yield* Effect.logInfo(`[runway planner] boot host=${config.plannerHost} port=${config.plannerPort} tick=${config.plannerTickSeconds}s sqlite=${config.plannerSqlitePath ?? "(unset — GET endpoints will 503)"}`);
+        const shutdownSignal = yield* Deferred.make();
+        yield* installSignalHandlers(shutdownSignal);
+        const stateRef = yield* makePlannerState(Date.now());
+        // Capture the current runtime so the HTTP request handlers (which
+        // are non-Effect functions) can fire-and-forget OTLP log emissions
+        // through the same TelemetryLive layer the loop uses.
+        const runtime = yield* Effect.runtime();
+        const runFork = Runtime.runFork(runtime);
+        const emitter = makeDecisionEmitter(runFork);
+        // Open the read-only SQLite client when configured. Absent path
+        // is non-fatal — the daemon stays useful for POST endpoints (the
+        // dashboard validates against its own storage on receive); GET
+        // endpoints will return 503 with a clear remediation message.
+        const readClient = yield* Effect.acquireRelease(Effect.sync(() => config.plannerSqlitePath
+            ? createPlannerReadClient({ sqlitePath: config.plannerSqlitePath })
+            : null), (client) => Effect.sync(() => client?.close()));
+        const httpServer = yield* Effect.acquireRelease(Effect.promise(() => startPlannerHttpServer({
+            host: config.plannerHost,
+            port: config.plannerPort,
+            readClient,
+            getHealth: makeHealthReader(stateRef, packageVersion()),
+            emitter,
+        })), (server) => Effect.promise(() => server.close()));
+        yield* Effect.logInfo(`[runway planner] http listening on ${config.plannerHost}:${httpServer.port}`);
+        // VA-476: queue-selection capability is wired when we have a
+        // SQLite read client. Absent → tick body skips it (the daemon
+        // still serves /planner/health and the POST endpoints, just no
+        // recommendations get proposed).
+        //
+        // VA-477: mergeability capability needs both the SQLite read
+        // client AND a `baseBranch` configured. Without baseBranch the
+        // rebase-target is unknown, so the capability is dormant rather
+        // than rebasing against a guessed default.
+        const nowNano = () => String(Date.now() * 1_000_000);
+        const capabilities = readClient
+            ? {
+                queueSelection: {
+                    readClient,
+                    readyLabel: config.readyLabel,
+                    now: nowNano,
+                },
+                // VA-480: drain spawn doesn't need baseBranch — it just
+                // shells out to `runway run --target` which resolves its
+                // own base branch. Wire it whenever the read client is
+                // available so queue-selection accepts can complete the
+                // recommendation → action lifecycle regardless of whether
+                // shepherd capabilities are configured.
+                drain: {
+                    readClient,
+                    cwd: process.cwd(),
+                    now: nowNano,
+                },
+                ...(config.baseBranch
+                    ? {
+                        mergeability: {
+                            readClient,
+                            github: createGithubGateway(),
+                            config,
+                            cwd: process.cwd(),
+                            baseBranch: config.baseBranch,
+                            now: nowNano,
+                        },
+                        // VA-478: CI capability shares the same gating
+                        // (SQLite + baseBranch) so all per-PR shepherd
+                        // capabilities light up or stay dark together.
+                        ci: {
+                            readClient,
+                            github: createGithubGateway(),
+                            config,
+                            cwd: process.cwd(),
+                            baseBranch: config.baseBranch,
+                            now: nowNano,
+                        },
+                        // VA-479: reviewer capability. LLM interpreter is
+                        // wired only when ANTHROPIC_API_KEY is in the env;
+                        // absent → verbatim-comment fallback (operator sees
+                        // the raw body in evidence).
+                        reviewer: {
+                            readClient,
+                            github: createGithubGateway(),
+                            config,
+                            cwd: process.cwd(),
+                            baseBranch: config.baseBranch,
+                            interpretComment: process.env.ANTHROPIC_API_KEY
+                                ? makeAnthropicCommentInterpreter({
+                                    apiKey: process.env.ANTHROPIC_API_KEY,
+                                })
+                                : undefined,
+                            now: nowNano,
+                        },
+                    }
+                    : {}),
+            }
+            : {};
+        yield* makePlannerLoop(shutdownSignal, stateRef, capabilities);
+    }).pipe(Effect.scoped, Effect.provide(MainLayer));
+    await Effect.runPromise(program);
+    console.log("[runway planner] shutdown complete");
+    process.exit(0);
+}
+/**
+ * VA-475: turn the captured Effect runtime into a synchronous emitter
+ * the HTTP handlers can call without re-entering Effect.gen. Each
+ * call schedules a single log emission on the runtime; the
+ * TelemetryLive layer flushes it through the OTLP exporter to the
+ * dashboard's projector.
+ */
+export function makeDecisionEmitter(runFork) {
+    return {
+        emitAccepted: ({ recommendationId, source, reason, timestampUnixNano }) => {
+            const attrs = {
+                recommendationId,
+                source,
+            };
+            if (reason)
+                attrs.reason = reason;
+            runFork(Effect.logInfo(PLANNER_RECOMMENDATION_ACCEPTED_LOG).pipe(Effect.annotateLogs(attrs), 
+            // Force the log timestamp so the dashboard projector sees
+            // the operator-perceived decision moment, not the OTLP
+            // emit moment (close in practice; explicit is clearer).
+            Effect.annotateLogs({ timestampUnixNano })));
+        },
+        emitRejected: ({ recommendationId, source, reason, timestampUnixNano }) => {
+            runFork(Effect.logInfo(PLANNER_RECOMMENDATION_REJECTED_LOG).pipe(Effect.annotateLogs({
+                recommendationId,
+                source,
+                reason,
+                timestampUnixNano,
+            })));
+        },
+        emitCapabilityModeChanged: ({ capability, mode, updatedBy, timestampUnixNano, }) => {
+            runFork(Effect.logInfo(PLANNER_CAPABILITY_MODE_CHANGED_LOG).pipe(Effect.annotateLogs({
+                capability,
+                mode,
+                updatedBy,
+                timestampUnixNano,
+            })));
+        },
+    };
+}
+/**
+ * Resolve `package.json#version` for the health endpoint. Reads
+ * synchronously at boot — runtime cost is one stat + parse. Cached
+ * after first call.
+ */
+let cachedVersion = null;
+function packageVersion() {
+    if (cachedVersion !== null)
+        return cachedVersion;
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf8"));
+        cachedVersion = String(pkg.version ?? "unknown");
+    }
+    catch (err) {
+        // Surface the read failure to stderr so an operator running the
+        // foreground daemon can see what's wrong; the "unknown" fallback
+        // keeps the health endpoint usable.
+        console.error("[runway planner] could not resolve package version:", err instanceof Error ? err.message : String(err));
+        cachedVersion = "unknown";
+    }
+    return cachedVersion;
+}

package/dist/commands/run.js

@@ -87,6 +87,23 @@ export function parseRunArgs(argv) {
             }
             opts.reviewRetries = n;
         }
+        else if (a === "--target") {
+            const v = argv[i + 1];
+            if (!v)
+                throw new Error("--target requires a Linear issue identifier");
+            if (!/^[A-Z]+-\d+$/.test(v)) {
+                throw new Error(`--target must be a Linear issue identifier like VA-123, got "${v}"`);
+            }
+            opts.target = v;
+            i += 1;
+        }
+        else if (a?.startsWith("--target=")) {
+            const v = a.slice("--target=".length);
+            if (!/^[A-Z]+-\d+$/.test(v)) {
+                throw new Error(`--target must be a Linear issue identifier like VA-123, got "${v}"`);
+            }
+            opts.target = v;
+        }
         else if (a === "--help" || a === "-h") {
             printRunUsage();
             process.exit(0);
@@ -129,6 +146,15 @@ OPTIONS
                   and re-runs review. N caps the extra impl+review
                   pairs per drain pickup. 0 disables retries entirely.
                   Overrides RUNWAY_REVIEW_RETRIES. Default: 1.
+  --target VA-NNN
+                  Restrict the drain to one Linear issue. Skips the
+                  FIFO pick and claims this identifier instead. Used
+                  by the planner daemon (VA-480) when accepting a
+                  queue-selection recommendation; manual operators
+                  can also use it to re-attempt a specific issue
+                  without picking up everything else in the queue.
+                  Fails fast if the issue isn't currently in the
+                  ready queue.
   --help, -h      Show this help.
 
 ENVIRONMENT
@@ -212,20 +238,26 @@ export async function runCommand(argv) {
         });
         const linear = createLinearGateway(config, linearLimiter);
         const github = createGithubGateway();
-        return yield* drainQueue({ config, linear, github, cwd }, { max: opts.max, allowPaths: opts.allowPaths });
+        return yield* drainQueue({ config, linear, github, cwd }, { max: opts.max, allowPaths: opts.allowPaths, target: opts.target });
     }).pipe(Effect.scoped, Effect.provide(MainLayer));
     const result = await Effect.runPromise(program);
     console.log(`[runway] done — attempts=${result.attempts} opened=${result.opened} hitl=${result.hitl} errored=${result.errored} skipped=${result.skipped}`);
+    // VA-480: when `--target` was specified but no issue was attempted,
+    // the target wasn't in the ready queue. Surface as a non-zero
+    // exit so the planner's drain-spawn dispatcher routes the action
+    // to `action.failed` instead of `action.completed`. The drainQueue
+    // Effect already logged the warning; this is the exit-code half.
+    const targetMissed = opts.target !== undefined && result.attempts === 0;
     // Single-line, parser-friendly completion marker. Background
     // watchers (Claude Code's `run_in_background` bash task, CI,
     // scripts) can grep for `[runway:exit]` instead of guessing
     // whether the drain is still in flight.
-    console.log(`[runway:exit] status=success attempts=${result.attempts} opened=${result.opened} hitl=${result.hitl} errored=${result.errored} skipped=${result.skipped}`);
+    console.log(`[runway:exit] status=${targetMissed ? "target_not_in_queue" : "success"} attempts=${result.attempts} opened=${result.opened} hitl=${result.hitl} errored=${result.errored} skipped=${result.skipped}`);
     // Hard exit so any lingering handle (OTel BatchSpanProcessor's
     // interval when OTEL_EXPORTER_OTLP_ENDPOINT is set, a Docker
     // stream Sandcastle left open, etc.) can't keep the process — and
     // the background task that launched it — alive after the drain is
     // logically done. By this point `Effect.scoped` has already torn
     // down its finalizers.
-    process.exit(0);
+    process.exit(targetMissed ? 1 : 0);
 }

package/dist/config.js

@@ -45,6 +45,28 @@ const configEffect = EConfig.all({
     metaFilterThresholdsJson: EConfig.option(EConfig.string("RUNWAY_META_FILTER_THRESHOLDS")),
     runwayRepoProjectName: EConfig.option(EConfig.string("RUNWAY_REPO_PROJECT_NAME")),
     metaWeeklyModel: EConfig.option(EConfig.string("RUNWAY_META_WEEKLY_MODEL")),
+    // VA-482: inline shepherd is retired — the four `RUNWAY_SHEPHERD_*`
+    // env vars (ENABLED / POLL_INTERVAL_SECONDS / MAX_ITERATIONS /
+    // MAX_WALL_SECONDS) are intentionally removed. Their work moved to
+    // the long-running `runway planner` daemon (capabilities VA-477..479)
+    // which has its own tick + budget knobs (`RUNWAY_PLANNER_*`).
+    // `RUNWAY_PR_REVIEWER_BOT_LOGIN` is preserved because the planner's
+    // reviewer dispatcher still consumes it.
+    prReviewerBotLogin: EConfig.option(EConfig.string("RUNWAY_PR_REVIEWER_BOT_LOGIN")),
+    // VA-473: planner daemon scaffold. Tick cadence + bind address for
+    // the long-running process. No capabilities wired yet — these
+    // values are consumed by `runway planner run` (heartbeat loop) and
+    // by the HTTP listener wired in VA-475.
+    plannerTickSeconds: EConfig.integer("RUNWAY_PLANNER_TICK_SECONDS").pipe(EConfig.withDefault(30), EConfig.validate({
+        message: "RUNWAY_PLANNER_TICK_SECONDS must be a positive integer",
+        validation: (n) => n > 0,
+    })),
+    plannerHost: EConfig.string("RUNWAY_PLANNER_HOST").pipe(EConfig.withDefault("127.0.0.1")),
+    plannerPort: EConfig.integer("RUNWAY_PLANNER_PORT").pipe(EConfig.withDefault(3002), EConfig.validate({
+        message: "RUNWAY_PLANNER_PORT must be a positive integer",
+        validation: (n) => n > 0 && n < 65536,
+    })),
+    plannerSqlitePath: EConfig.option(EConfig.string("RUNWAY_PLANNER_SQLITE_PATH")),
 }).pipe(Effect.map((raw) => ({
     linearApiKey: raw.linearApiKey,
     opServiceAccountToken: Option.getOrUndefined(raw.opServiceAccountToken),
@@ -66,6 +88,11 @@ const configEffect = EConfig.all({
     metaFilterThresholds: parseMetaFilterThresholdsJson(Option.getOrUndefined(raw.metaFilterThresholdsJson)),
     runwayRepoProjectName: Option.getOrUndefined(raw.runwayRepoProjectName),
     metaWeeklyModel: Option.getOrUndefined(raw.metaWeeklyModel),
+    prReviewerBotLogin: Option.getOrUndefined(raw.prReviewerBotLogin),
+    plannerTickSeconds: raw.plannerTickSeconds,
+    plannerHost: raw.plannerHost,
+    plannerPort: raw.plannerPort,
+    plannerSqlitePath: Option.getOrUndefined(raw.plannerSqlitePath),
 })));
 /**
  * VA-359: Context tag for the resolved RunwayConfig. Provided by

package/dist/dashboard/projector.js

@@ -148,6 +148,183 @@ function strArrayAttr(v) {
  * in lock-step with `orchestrator.ts`.
  */
 export const DRAIN_STARTED_LOG = "drain.started";
+/**
+ * VA-474: log body strings the planner daemon emits for its six
+ * event types (ADR 0004 § Writer model). Kept in lock-step with the
+ * planner's `Effect.logInfo` call sites — drift between projector
+ * and planner means events stop projecting into the read-model.
+ */
+export const PLANNER_RECOMMENDATION_PROPOSED_LOG = "planner.recommendation.proposed";
+export const PLANNER_RECOMMENDATION_ACCEPTED_LOG = "planner.recommendation.accepted";
+export const PLANNER_RECOMMENDATION_REJECTED_LOG = "planner.recommendation.rejected";
+export const PLANNER_ACTION_STARTED_LOG = "planner.action.started";
+export const PLANNER_ACTION_COMPLETED_LOG = "planner.action.completed";
+export const PLANNER_ACTION_FAILED_LOG = "planner.action.failed";
+/**
+ * VA-481: emitted by the planner's HTTP PUT /planner/capabilities/:capability
+ * handler when an operator (or the planner's auto-promotion logic)
+ * changes a capability's mode (manual / suggest / auto). The dashboard
+ * projects each event into the `planner_capability_modes` table; the
+ * planner reads the table on every tick so toggles take effect on
+ * the next iteration without a daemon restart.
+ */
+export const PLANNER_CAPABILITY_MODE_CHANGED_LOG = "planner.capability.mode_changed";
+export const PLANNER_CAPABILITY_MODES = new Set([
+    "manual",
+    "suggest",
+    "auto",
+]);
+const PLANNER_CAPABILITIES = new Set([
+    "queue-selection",
+    "shepherd-mergeability",
+    "shepherd-ci",
+    "shepherd-reviewer",
+]);
+/**
+ * VA-474: scan an OTLP logs payload for the six planner-event
+ * markers. Records that fail validation (missing required
+ * attribute, unknown capability, unparseable `evidence`) are
+ * dropped — the projector never crashes on a bad payload, but it
+ * also never fabricates fields the emitter didn't send.
+ */
+export function extractPlannerMarkers(payload) {
+    const out = [];
+    for (const rl of payload.resourceLogs ?? []) {
+        for (const sl of rl.scopeLogs ?? []) {
+            for (const rec of sl.logRecords ?? []) {
+                const body = rec.body?.stringValue;
+                if (!body || !body.startsWith("planner."))
+                    continue;
+                const ts = rec.timeUnixNano ?? rec.observedTimeUnixNano;
+                if (!ts)
+                    continue;
+                const attrs = attributesToStringMap(rec.attributes);
+                if (body === PLANNER_RECOMMENDATION_PROPOSED_LOG) {
+                    const recommendationId = attrs.recommendationId;
+                    const capability = attrs.capability;
+                    const target = attrs.target;
+                    const summary = attrs.summary;
+                    if (!recommendationId ||
+                        !capability ||
+                        !PLANNER_CAPABILITIES.has(capability) ||
+                        !target ||
+                        !summary) {
+                        continue;
+                    }
+                    let evidence = {};
+                    const rawEvidence = attrs.evidence;
+                    if (rawEvidence) {
+                        try {
+                            const parsed = JSON.parse(rawEvidence);
+                            if (parsed &&
+                                typeof parsed === "object" &&
+                                !Array.isArray(parsed)) {
+                                evidence = parsed;
+                            }
+                        }
+                        catch {
+                            // Malformed evidence JSON is non-fatal — emit with {}
+                            // so the recommendation still lands.
+                        }
+                    }
+                    out.push({
+                        kind: "recommendation.proposed",
+                        recommendationId,
+                        capability: capability,
+                        target,
+                        summary,
+                        evidence,
+                        autoApproveEligible: attrs.autoApproveEligible === "true",
+                        timestampUnixNano: ts,
+                    });
+                }
+                else if (body === PLANNER_RECOMMENDATION_ACCEPTED_LOG ||
+                    body === PLANNER_RECOMMENDATION_REJECTED_LOG) {
+                    const recommendationId = attrs.recommendationId;
+                    const source = attrs.source;
+                    if (!recommendationId ||
+                        (source !== "operator" && source !== "auto")) {
+                        continue;
+                    }
+                    const status = body === PLANNER_RECOMMENDATION_ACCEPTED_LOG
+                        ? "accepted"
+                        : "rejected";
+                    out.push({
+                        kind: status === "accepted"
+                            ? "recommendation.accepted"
+                            : "recommendation.rejected",
+                        recommendationId,
+                        status,
+                        source,
+                        reason: attrs.reason ?? null,
+                        timestampUnixNano: ts,
+                    });
+                }
+                else if (body === PLANNER_ACTION_STARTED_LOG) {
+                    const actionId = attrs.actionId;
+                    const capability = attrs.capability;
+                    const target = attrs.target;
+                    if (!actionId ||
+                        !capability ||
+                        !PLANNER_CAPABILITIES.has(capability) ||
+                        !target) {
+                        continue;
+                    }
+                    out.push({
+                        kind: "action.started",
+                        actionId,
+                        recommendationId: attrs.recommendationId ?? null,
+                        capability: capability,
+                        target,
+                        timestampUnixNano: ts,
+                    });
+                }
+                else if (body === PLANNER_ACTION_COMPLETED_LOG) {
+                    const actionId = attrs.actionId;
+                    const outcome = attrs.outcome;
+                    if (!actionId || !outcome)
+                        continue;
+                    out.push({
+                        kind: "action.completed",
+                        actionId,
+                        outcome,
+                        timestampUnixNano: ts,
+                    });
+                }
+                else if (body === PLANNER_ACTION_FAILED_LOG) {
+                    const actionId = attrs.actionId;
+                    const error = attrs.error;
+                    if (!actionId || !error)
+                        continue;
+                    out.push({
+                        kind: "action.failed",
+                        actionId,
+                        error,
+                        timestampUnixNano: ts,
+                    });
+                }
+                else if (body === PLANNER_CAPABILITY_MODE_CHANGED_LOG) {
+                    const capability = attrs.capability;
+                    const mode = attrs.mode;
+                    if (!capability ||
+                        !PLANNER_CAPABILITIES.has(capability) ||
+                        !mode ||
+                        !PLANNER_CAPABILITY_MODES.has(mode)) {
+                        continue;
+                    }
+                    out.push({
+                        kind: "capability.mode_changed",
+                        capability: capability,
+                        mode: mode,
+                        updatedBy: attrs.updatedBy ?? "operator",
+                        timestampUnixNano: ts,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
 /**
  * VA-455: scan an OTLP logs payload for `drain.started` markers.
  * Each match becomes an `ActiveDrainMarker` carrying the drain's