@valescoagency/runway 0.10.0 → 0.11.0

package/README.md

@@ -8,13 +8,15 @@ 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.
 
-## Five commands
+## Seven 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 run` | Drain a Linear queue. For each `Todo` issue: branch, agent works, sub-agent reviews, PR opens (or `ready-for-human` label). Run **whenever you want a batch of work done**. |
+| `runway 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. |
 | `runway upgrade-repo` | Re-render the cwd repo's runway scaffold against the current vendored templates. Use after a runway version bump that changed the Dockerfile or template shape — `init` writes them, `upgrade-repo` keeps them current without re-prompting for op:// values. |
 
@@ -39,10 +41,12 @@ or use `--check` for a CI dry-run that exits 1 on drift.
 ## Architecture
 
 ```
-Linear (Todo, team=VA)
+Linear (label=ready-for-agent, team=VA)
   ↓ poll
 runway (this CLI, on your Mac, run from inside the target repo)
   ↓ for each issue
+  │   removeLabel(ready-for-agent)   # claim signal — VA-423; skip
+  │                                  # if already absent (lost race)
   │   sandcastle.run({ agent: claudeCode, sandbox: docker, cwd: process.cwd(), ... })
   │     iter 1 → IMPL: DONE | IMPL: BLOCKED — <reason> | IMPL: CONTINUE
   │     iter 2 → same, with previous iteration's summary injected
@@ -54,7 +58,9 @@ runway (this CLI, on your Mac, run from inside the target repo)
   │     sandcastle.run({ ..., prompt: review template })
   │     → REVIEW: APPROVED  | REVIEW: REJECTED — <reason>
   │
-  ├── approved  → git push → gh pr create → Linear "In Review"
+  ├── approved  → git push → gh pr create  (Linear's GitHub integration
+  │                                          auto-transitions: PR open
+  │                                          → In Progress, merge → Done)
   └── rejected  → Linear comment with reason, then `ready-for-human` label
   ↓ next issue
 
@@ -153,6 +159,48 @@ varlock run --schema /path/to/runway/.env.schema -- runway --max 3
 Without varlock, runway falls back to plain `process.env` and
 sandcastle reads `.sandcastle/.env` per its docs.
 
+## Signed agent commits (optional)
+
+Runway can sign every commit the agent produces so the PR lands on
+GitHub with a **Verified** badge. Off by default; opt in per target
+repo by populating four extra refs in `.env.schema`.
+
+Setup (one-time per bot):
+
+1. Generate an Ed25519 SSH signing keypair for the runway agent:
+
+   ```bash
+   ssh-keygen -t ed25519 -C "runway-agent" -N "" -f ~/.ssh/runway_bot
+   ```
+
+2. Store the keypair plus the bot's git identity in 1Password under
+   `op://<vault>/runway-signing-ssh`:
+
+   | field     | value                                      |
+   |-----------|--------------------------------------------|
+   | `private` | contents of `~/.ssh/runway_bot`            |
+   | `public`  | contents of `~/.ssh/runway_bot.pub`        |
+   | `name`    | the bot's git `user.name` (e.g. `Runway Agent`) |
+   | `email`   | the bot's git `user.email` (must match the GitHub agent account) |
+
+3. Register the public key as a **Signing Key** on the GitHub
+   account that owns the agent's `GH_TOKEN` (this is what makes
+   GitHub render Verified — both Authentication and Signing Keys
+   are managed under Settings → SSH and GPG keys).
+
+4. Uncomment the four `RUNWAY_SIGNING_*` lines at the bottom of
+   `.env.schema` (the file `runway init --tier=2` wrote at your repo
+   root). The lines come pre-filled with `op://` references
+   matching the layout above.
+
+Validate with `runway doctor`: the **Environment / agent commit
+signing** check goes from `warn (off)` to `ok` once all four refs
+are declared. Tear down by re-commenting the four lines — runway
+falls back to plain unsigned commits.
+
+Design rationale + future migration path (GitHub App identity) is in
+[`docs/adr/0003-agent-commit-signing.md`](docs/adr/0003-agent-commit-signing.md).
+
 ## Install
 
 ```bash
@@ -167,9 +215,7 @@ export LINEAR_API_KEY=lin_api_...
 # export RUNWAY_LINEAR_TEAM=VA
 # export RUNWAY_LINEAR_PROJECT=<project-id-or-slug>   # optional, scopes queue to one project
 # export RUNWAY_BASE_BRANCH=master                    # optional, overrides auto-detected default branch
-# export RUNWAY_READY_STATUS="Todo"
-# export RUNWAY_IN_PROGRESS_STATUS="In Progress"
-# export RUNWAY_IN_REVIEW_STATUS="In Review"
+# export RUNWAY_READY_LABEL="ready-for-agent"
 # export RUNWAY_HITL_LABEL="ready-for-human"
 # export RUNWAY_MAX_ITERATIONS=5
 # export RUNWAY_COMMENT_AUTHOR_ALLOWLIST="Reviewer Bot,Jane Reviewer"
@@ -182,14 +228,33 @@ export LINEAR_API_KEY=lin_api_...
 #   Linear identities.
 ```
 
-`RUNWAY_HITL_LABEL` defaults to `ready-for-human`, matching the
-[Flightplan](https://github.com/valescoagency/flightplan) canonical
-state-label vocabulary (`needs-triage`, `needs-info`,
-`ready-for-agent`, `ready-for-human`, `wontfix`) that Bedrock and
-other Valesco repos use. Override the env var if your workspace uses
-a different label. `runway doctor` validates that the configured
-team, workflow states, and HITL label all exist before any agent run
-— misconfiguration surfaces immediately instead of mid-drain.
+Runway uses two labels from the
+[Flightplan](https://github.com/valescoagency/flightplan) v1.1.0
+state-label contract:
+
+- `RUNWAY_READY_LABEL` (default `ready-for-agent`) marks an issue as
+  "ready for the agent to pick up." Runway's drain queue filters by
+  this label, **not** by workflow status — Linear's GitHub integration
+  auto-mutates status when a PR cross-references an issue, which would
+  drain a status-gated queue silently every time someone mentioned the
+  issue from a PR. Labels are immune to that integration. Runway
+  removes the label on pickup as the claim signal: the gateway returns
+  whether the label was actually present at write time, and a runner
+  that loses the claim race (label was already absent) skips the issue
+  cleanly without posting a pickup comment or pushing an agent branch.
+  Linear's API has no label-level compare-and-swap, so two runners
+  that both read the labels before either has written can still both
+  proceed — the design assumes the predominant operator pattern of a
+  single drain instance running sequentially.
+- `RUNWAY_HITL_LABEL` (default `ready-for-human`) is applied when the
+  agent or reviewer can't finish, AND when a run fails outright.
+  Runway never re-applies the ready label on failure — terminal
+  failures shouldn't retry indefinitely. The operator triages and
+  re-applies `ready-for-agent` manually if the failure was transient.
+
+`runway doctor` validates that the configured team and both labels
+exist before any agent run — misconfiguration surfaces immediately
+instead of mid-drain.
 
 ### From source (development)
 
@@ -247,18 +312,17 @@ runway --help
 `runway` (no subcommand) is an alias for `runway run` for back-compat.
 
 `--max N` bounds **attempts**, not successes. Every issue picked up
-counts as one attempt, whether it ends in a PR, a `needs-human` label,
-or a revert-to-`Todo` after an infrastructure failure. An issue
-reverted in this invocation will not be re-picked in the same
-invocation — re-run runway after fixing the underlying config to retry
-it.
+counts as one attempt, whether it ends in a PR, a `ready-for-human`
+label, or an infrastructure-error flag. An issue picked up in this
+invocation will not be re-picked in the same invocation — the
+pickup-time `removeLabel(ready-for-agent)` plus a same-invocation
+seen-set guard keep the drain from looping on it.
 
 The CLI exits with 0 even if some issues hit HITL or errored — those
 are normal outcomes. Every run prints a per-issue verdict trail on
 exit (`APPROVED → PR opened <url>` / `HITL <reason>` /
-`REVERTED → Todo <reason>` / `INFRA_ERROR <reason>`) so you can scan
-results without opening Linear; the same content also lives on the
-issue as a Linear comment.
+`INFRA_ERROR <reason>`) so you can scan results without opening Linear;
+the same content also lives on the issue as a Linear comment.
 
 ## Linear conventions
 
@@ -267,20 +331,36 @@ Runway picks up issues that are:
 - in team `RUNWAY_LINEAR_TEAM` (default `VA`)
 - (optionally) in project `RUNWAY_LINEAR_PROJECT` (override per-run
   with `runway run --project=<id-or-slug-or-name>`; unset = team-wide)
-- in workflow state `RUNWAY_READY_STATUS` (default `Todo`)
-
-It transitions them through:
-
-- `In Progress` while the agent is running (specifically: once the
-  agent has committed to its branch — startup failures before any
-  commits revert the issue back to `Todo` rather than stranding it)
-- `In Review` when the PR opens
-- (label `ready-for-human`) if the agent or reviewer can't finish *after*
-  the agent has committed real work
-
-These names are configurable per env var; the queries match by name so
-your Linear workspace's actual state names need to line up with what
-you set.
+- carrying label `RUNWAY_READY_LABEL` (default `ready-for-agent`,
+  the flightplan v1.1.0 contract — see VA-423)
+- not carrying `RUNWAY_HITL_LABEL` (default `ready-for-human`)
+- not blocked by a non-terminal `blocks` relation
+- **without any child sub-issues** — parent PRDs and umbrella tickets
+  are skipped. The right unit of agent work is the leaf ticket, not
+  the parent that spans it. If your ticket's scope is bigger than one
+  PR, file children for the individual deliverables and let runway
+  pick those up instead.
+
+Workflow status (`Triage` / `Todo` / `In Progress` / etc.) is **not**
+part of the queue contract: Linear's GitHub integration auto-mutates
+status whenever a PR cross-references the issue, which would drain a
+status-gated queue silently every time someone mentioned the issue
+from a PR.
+
+What runway does on each pickup:
+
+- removes the `ready-for-agent` label (claim signal — takes the
+  issue out of the next drain's queue; a runner that finds the
+  label already gone skips the issue without doing visible work)
+- comments and works the issue on `agent/<id>`
+- on approve, pushes the branch, opens the PR; Linear's GitHub
+  integration then auto-transitions the issue (`In Progress` on PR
+  open, `Done` on merge via the `Closes <issue>` line in the PR body)
+- on reject / HITL / startup failure / mid-run crash, applies
+  `ready-for-human`. Runway never re-applies `ready-for-agent` on
+  failure — terminal failures shouldn't retry indefinitely; the
+  operator triages and re-applies the label manually if the cause
+  was transient.
 
 ## Write-path policy
 
@@ -329,8 +409,7 @@ can see what an agent run can and can't touch (e.g. `impl policy:
 Runway auto-detects the repo's default branch at the start of every
 `runway run` by reading `origin/HEAD` (with `git remote show origin`
 as a fallback for fresh clones). That branch is used for diffing the
-agent's work, counting commits when deciding whether a startup
-failure should revert to `Todo`, and as the `--base` for the PR.
+agent's work and as the `--base` for the PR.
 
 Set `RUNWAY_BASE_BRANCH=<name>` to override detection — useful when
 you want runway to target a release branch instead of the default, or
@@ -380,6 +459,76 @@ the issue gets the HITL label and a comment with the reviewer's reason.
 The reviewer is intentionally adversarial — its job is to find reasons
 NOT to ship, not to rubber-stamp.
 
+## Dashboard
+
+`runway run` emits OpenTelemetry traces + logs for every drain. The
+operations dashboard projects those into a local SQLite db and serves
+a single-page web UI for browsing recent runs, drilling into per-issue
+timelines, and filtering by outcome / drain / date range. Binds to
+`127.0.0.1` only — no auth, no LAN exposure by default.
+
+### v2: `runway dash` (recommended)
+
+```bash
+# Bring up the dashboard from any directory — no runway clone required.
+runway dash up
+
+# In another shell, point runway run at it:
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+runway run
+
+# Open http://localhost:3001/ in a browser.
+
+# Tail the container logs.
+runway dash logs --follow
+
+# Tear down (volume + history preserved).
+runway dash stop
+
+# Tear down AND drop history.
+runway dash stop --purge
+```
+
+`runway dash up` pulls `ghcr.io/valescoagency/runway-dashboard:latest`,
+creates a named volume (`runway-dashboard-data`) for the SQLite db,
+and runs a detached container. Repeated `runway dash up` calls are
+idempotent: an already-running container stays as-is, a stopped one
+is started, otherwise a fresh container is created.
+
+Override the image with `--image=…` or `RUNWAY_DASHBOARD_IMAGE`; the
+ports with `--otlp-port=…` / `--dashboard-port=…`. Forward Linear
+sync by exporting `LINEAR_API_KEY` (and optionally
+`LINEAR_POLL_INTERVAL_SECONDS`, `RUNWAY_LINEAR_TEAM`,
+`RUNWAY_READY_LABEL`) before `runway dash up` — the CLI passes them
+through to the container without echoing the value through argv.
+
+### v1: docker-compose (for hacking on the dashboard itself)
+
+The runway repo also ships a `docker-compose.yml` that builds the
+dashboard locally from `Dockerfile.dashboard`. Use this when you're
+developing the dashboard code and want to iterate without publishing
+an image:
+
+```bash
+git clone https://github.com/ValescoAgency/runway && cd runway
+docker compose up           # builds + runs the local image
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+### Migrating from compose to `runway dash`
+
+1. `docker compose down` (in the runway repo).
+2. `runway dash up` (anywhere).
+
+The default named volume is different (`runway-dashboard-data` vs
+compose's `runway-data`), so history doesn't carry over automatically.
+To preserve it, copy the volume contents before switching:
+
+```bash
+docker run --rm -v runway-data:/from -v runway-dashboard-data:/to \
+  alpine sh -c 'cp -a /from/. /to/'
+```
+
 ## What's deliberately missing in v1
 
 - Parallel runs (one issue at a time)
@@ -392,7 +541,7 @@ These are tractable, just not v1.
 
 ## Status
 
-0.10.0 — production-shaped and dogfooded against live Linear queues.
+0.11.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

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
+import { dashCommand, printDashUsage } from "./commands/dash.js";
 import { doctorCommand, printDoctorUsage } from "./commands/doctor.js";
 import { initCommand, printInitUsage } from "./commands/init.js";
+import { reviewCommand, printReviewUsage } from "./commands/review.js";
 import { runCommand, printRunUsage } from "./commands/run.js";
 import { upgradeCommand, printUpgradeUsage } from "./commands/upgrade.js";
 import { upgradeRepoCommand, printUpgradeRepoUsage, } from "./commands/upgrade-repo.js";
 const SUBCOMMANDS = [
+    {
+        name: "dash",
+        summary: "Operate the runway operations dashboard (up / logs / stop).",
+        run: dashCommand,
+        help: printDashUsage,
+    },
     {
         name: "doctor",
         summary: "Read-only preflight: tooling, env, repo state, agent image.",
@@ -17,6 +25,12 @@ const SUBCOMMANDS = [
         run: initCommand,
         help: printInitUsage,
     },
+    {
+        name: "review",
+        summary: "Run an IRA retrospective pass (run / drain / weekly).",
+        run: reviewCommand,
+        help: printReviewUsage,
+    },
     {
         name: "run",
         summary: "Drain a Linear queue against the cwd repo (default verb).",

package/dist/commands/dash.js

@@ -0,0 +1,324 @@
+import { execa } from "execa";
+/**
+ * VA-393 (dashboard slice 8): `runway dash` subcommand. Wraps
+ * `docker run` so users can operate the dashboard from any
+ * runway-using project without cloning the runway repo or maintaining
+ * a docker-compose file.
+ *
+ * Three verbs:
+ *   up     pull the published image and run it as a detached
+ *          container (`runway-dashboard`) with loopback ports and a
+ *          named volume for the SQLite db.
+ *   logs   stream `docker logs` for the container (`--follow` toggles
+ *          `-f`; default tails recent output without following).
+ *   stop   stop and `rm` the container. The named volume stays so
+ *          history survives across restarts; explicit `--purge` drops
+ *          the volume too.
+ *
+ * Defaults to the `:latest` tag published by `.github/workflows/dashboard-image.yml`.
+ * Override via `--image` or the `RUNWAY_DASHBOARD_IMAGE` env var.
+ *
+ * Verb-agnostic env passthrough: when set in the caller's environment,
+ * `LINEAR_API_KEY`, `LINEAR_POLL_INTERVAL_SECONDS`, `RUNWAY_LINEAR_TEAM`,
+ * `RUNWAY_READY_LABEL` are forwarded into the container via `-e`.
+ * Absent → the container falls back to the same defaults as
+ * `docker-compose.yml` (Linear sync disabled, etc.).
+ */
+const DEFAULT_IMAGE = "ghcr.io/valescoagency/runway-dashboard:latest";
+const DEFAULT_CONTAINER_NAME = "runway-dashboard";
+const DEFAULT_VOLUME_NAME = "runway-dashboard-data";
+const DEFAULT_OTLP_PORT = "4318";
+const DEFAULT_DASHBOARD_PORT = "3001";
+/**
+ * Linear sync envs we forward when present. Kept narrow on purpose —
+ * the dashboard reads its own env at boot and we don't want a stray
+ * shell variable leaking into the container.
+ */
+const FORWARDED_ENV_KEYS = [
+    "LINEAR_API_KEY",
+    "LINEAR_POLL_INTERVAL_SECONDS",
+    "RUNWAY_LINEAR_TEAM",
+    "RUNWAY_READY_LABEL",
+];
+export function printDashUsage() {
+    console.log(`runway dash — operate the runway operations dashboard
+
+Wraps \`docker run\` so the dashboard works from any runway-using
+project without cloning the runway repo. The published image is
+${DEFAULT_IMAGE}; override via --image or RUNWAY_DASHBOARD_IMAGE.
+
+USAGE
+  runway dash up   [--image=…] [--otlp-port=N] [--dashboard-port=N]
+  runway dash logs [--follow]
+  runway dash stop [--purge]
+
+VERBS
+  up     Pull and start the dashboard as a detached container
+         (\`${DEFAULT_CONTAINER_NAME}\`). Ports publish to 127.0.0.1
+         only; a named volume (\`${DEFAULT_VOLUME_NAME}\`) persists
+         the SQLite db across runs.
+  logs   Stream container logs (\`docker logs ${DEFAULT_CONTAINER_NAME}\`).
+         Pass --follow to tail with -f.
+  stop   Stop and remove the container. The named volume stays unless
+         --purge is passed.
+
+OPTIONS
+  --image=REF         Override the dashboard image reference.
+                      Default: ${DEFAULT_IMAGE} (env: RUNWAY_DASHBOARD_IMAGE).
+  --otlp-port=N       Host port for the OTLP receiver. Default: ${DEFAULT_OTLP_PORT}.
+  --dashboard-port=N  Host port for the dashboard UI. Default: ${DEFAULT_DASHBOARD_PORT}.
+  --follow, -f        (logs) Tail container logs with -f.
+  --purge             (stop) Also remove the named volume (deletes history).
+  --help, -h          Show this help.
+
+LINEAR SYNC (optional)
+  When LINEAR_API_KEY is set in the caller's environment, \`runway dash
+  up\` forwards it into the container so the dashboard polls Linear and
+  surfaces the Todo queue. LINEAR_POLL_INTERVAL_SECONDS,
+  RUNWAY_LINEAR_TEAM, and RUNWAY_READY_LABEL are forwarded too when
+  set. Absent → the dashboard runs without Linear surfaces.
+
+OTEL EXPORTER
+  Point \`runway run\` at the dashboard by exporting:
+    OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:${DEFAULT_OTLP_PORT}
+`);
+}
+export function parseDashArgs(argv) {
+    if (argv.length === 0) {
+        throw new Error("missing verb — expected one of: up, logs, stop. Run `runway dash --help`.");
+    }
+    const [verbRaw, ...rest] = argv;
+    if (verbRaw === "--help" || verbRaw === "-h") {
+        printDashUsage();
+        process.exit(0);
+    }
+    if (verbRaw !== "up" && verbRaw !== "logs" && verbRaw !== "stop") {
+        throw new Error(`unknown verb "${verbRaw}" — expected one of: up, logs, stop.`);
+    }
+    const verb = verbRaw;
+    let image;
+    let otlpPort;
+    let dashboardPort;
+    let follow = false;
+    let purge = false;
+    for (const arg of rest) {
+        if (arg === "--help" || arg === "-h") {
+            printDashUsage();
+            process.exit(0);
+        }
+        else if (arg.startsWith("--image=")) {
+            image = arg.slice("--image=".length);
+        }
+        else if (arg.startsWith("--otlp-port=")) {
+            otlpPort = arg.slice("--otlp-port=".length);
+        }
+        else if (arg.startsWith("--dashboard-port=")) {
+            dashboardPort = arg.slice("--dashboard-port=".length);
+        }
+        else if (arg === "--follow" || arg === "-f") {
+            follow = true;
+        }
+        else if (arg === "--purge") {
+            purge = true;
+        }
+        else {
+            throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    return { verb, image, otlpPort, dashboardPort, follow, purge };
+}
+/**
+ * Resolve effective options by layering CLI flags over env vars over
+ * built-in defaults. The resolved shape is pure data so tests can
+ * assert on the command we'd hand to docker without invoking it.
+ */
+export function resolveDashOptions(parsed, env = process.env) {
+    const image = parsed.image ?? env.RUNWAY_DASHBOARD_IMAGE ?? DEFAULT_IMAGE;
+    const otlpPort = parsed.otlpPort ?? env.OTLP_PORT ?? DEFAULT_OTLP_PORT;
+    const dashboardPort = parsed.dashboardPort ?? env.DASHBOARD_PORT ?? DEFAULT_DASHBOARD_PORT;
+    return {
+        verb: parsed.verb,
+        image,
+        containerName: DEFAULT_CONTAINER_NAME,
+        volumeName: DEFAULT_VOLUME_NAME,
+        otlpPort,
+        dashboardPort,
+        follow: parsed.follow,
+        purge: parsed.purge,
+    };
+}
+/**
+ * Build the `docker run` argv for `runway dash up`. Extracted so
+ * tests can assert the bindings (loopback prefixes, named volume,
+ * forwarded env vars) without spawning docker. Caller decides how to
+ * execute the args.
+ */
+export function buildDockerRunArgs(opts, env = process.env) {
+    const args = [
+        "run",
+        "--detach",
+        "--name",
+        opts.containerName,
+        "--restart",
+        "unless-stopped",
+        // VA-393: host-side bindings stay on 127.0.0.1 by default so the
+        // dashboard is unreachable from the LAN. Container-side stays
+        // 0.0.0.0 because the Dockerfile sets DASHBOARD_HOST=0.0.0.0 so
+        // Docker's port-forward can reach the listener.
+        "-p",
+        `127.0.0.1:${opts.dashboardPort}:${opts.dashboardPort}`,
+        "-p",
+        `127.0.0.1:${opts.otlpPort}:${opts.otlpPort}`,
+        "-v",
+        `${opts.volumeName}:/data`,
+        "-e",
+        `DASHBOARD_PORT=${opts.dashboardPort}`,
+        "-e",
+        `OTLP_PORT=${opts.otlpPort}`,
+    ];
+    // VA-393: forward Linear-sync env keys when set in the caller's
+    // environment. We pass each key with no value so docker reads the
+    // current process env — that way the key never echoes through the
+    // shell history.
+    for (const key of FORWARDED_ENV_KEYS) {
+        if (env[key] !== undefined && env[key] !== "") {
+            args.push("-e", key);
+        }
+    }
+    args.push(opts.image);
+    return args;
+}
+export async function dashCommand(argv) {
+    const parsed = parseDashArgs(argv);
+    const opts = resolveDashOptions(parsed);
+    await ensureDockerAvailable();
+    switch (opts.verb) {
+        case "up":
+            await dashUp(opts);
+            return;
+        case "logs":
+            await dashLogs(opts);
+            return;
+        case "stop":
+            await dashStop(opts);
+            return;
+    }
+}
+/**
+ * Surface a clear error when docker isn't on PATH or the daemon isn't
+ * reachable, instead of letting an opaque ENOENT bubble. `docker info`
+ * is the canonical "is the daemon up?" probe.
+ */
+async function ensureDockerAvailable() {
+    try {
+        await execa("docker", ["info"], { stdio: "ignore" });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            throw new Error("docker not found on PATH. Install Docker Desktop (or Podman with a `docker` shim) and retry.");
+        }
+        throw new Error("docker daemon not reachable (`docker info` failed). Start Docker and retry.");
+    }
+}
+async function dashUp(opts) {
+    // If a container with this name already exists (running or stopped),
+    // print a helpful hint instead of letting docker error with a
+    // "container already in use" diagnostic. Up-on-running is a no-op.
+    const existing = await containerState(opts.containerName);
+    if (existing === "running") {
+        console.log(`[runway dash] container ${opts.containerName} already running.`);
+        await printAccessHints(opts);
+        return;
+    }
+    if (existing === "stopped") {
+        console.log(`[runway dash] container ${opts.containerName} exists but is stopped — starting it.`);
+        await execa("docker", ["start", opts.containerName], {
+            stdio: "inherit",
+        });
+        await printAccessHints(opts);
+        return;
+    }
+    console.log(`[runway dash] pulling ${opts.image}`);
+    try {
+        await execa("docker", ["pull", opts.image], { stdio: "inherit" });
+    }
+    catch {
+        throw new Error(`failed to pull ${opts.image}. ` +
+            "If the image is private, run `docker login ghcr.io` first.");
+    }
+    const args = buildDockerRunArgs(opts);
+    console.log(`[runway dash] starting container ${opts.containerName}`);
+    await execa("docker", args, { stdio: "inherit" });
+    await printAccessHints(opts);
+}
+async function dashLogs(opts) {
+    const args = ["logs"];
+    if (opts.follow)
+        args.push("-f");
+    args.push(opts.containerName);
+    try {
+        await execa("docker", args, { stdio: "inherit" });
+    }
+    catch (err) {
+        const e = err;
+        // SIGINT during `docker logs -f` returns a non-zero exit; treat
+        // it as a clean operator-driven cancel rather than a failure.
+        if (opts.follow && e.signal === "SIGINT")
+            return;
+        throw err;
+    }
+}
+async function dashStop(opts) {
+    const state = await containerState(opts.containerName);
+    if (state === "absent") {
+        console.log(`[runway dash] container ${opts.containerName} is not present — nothing to stop.`);
+    }
+    else {
+        if (state === "running") {
+            await execa("docker", ["stop", opts.containerName], {
+                stdio: "inherit",
+            });
+        }
+        await execa("docker", ["rm", opts.containerName], { stdio: "inherit" });
+    }
+    if (opts.purge) {
+        console.log(`[runway dash] --purge: removing volume ${opts.volumeName}`);
+        try {
+            await execa("docker", ["volume", "rm", opts.volumeName], {
+                stdio: "inherit",
+            });
+        }
+        catch {
+            console.log(`[runway dash] volume ${opts.volumeName} not present (already removed).`);
+        }
+    }
+    else {
+        console.log(`[runway dash] volume ${opts.volumeName} kept — pass --purge to delete history.`);
+    }
+}
+/**
+ * `docker inspect` reports `.State.Status` (`running`, `exited`,
+ * `created`, etc.) when the container exists, and exits non-zero
+ * otherwise. We collapse the status set to three buckets.
+ */
+async function containerState(name) {
+    try {
+        const { stdout } = await execa("docker", [
+            "inspect",
+            "--format",
+            "{{.State.Status}}",
+            name,
+        ]);
+        return stdout.trim() === "running" ? "running" : "stopped";
+    }
+    catch {
+        return "absent";
+    }
+}
+async function printAccessHints(opts) {
+    console.log("");
+    console.log(`[runway dash] dashboard:  http://localhost:${opts.dashboardPort}`);
+    console.log(`[runway dash] OTLP endpoint: http://localhost:${opts.otlpPort} (set as OTEL_EXPORTER_OTLP_ENDPOINT)`);
+    console.log("[runway dash] stop with: runway dash stop");
+}