feat(manager): dashboard UI + batch testing + launcher

.github/workflows/dev-version-bump.yml

@@ -0,0 +1,170 @@
+name: Dev version bump
+
+# When a release publishes, open a pull request that moves `dev` past the published
+# version. Without this, `dev` keeps carrying a version that is at or behind a released
+# one, and `tests/release-version-line.test.ts` fails on `dev` and on every pull request
+# opened against it - inherited red a contributor cannot fix from their own diff.
+#
+# That has been repaired by hand four times: 32529c2b2, e4a85d134, 076ad3036, befcac3e1.
+# The second of those ADDED the detector and two more repairs followed it, so more
+# visibility was never the missing piece; a prepared change was.
+#
+# WHAT THIS DOES NOT DO. It does not push to `dev`. It opens a pull request and a human
+# merges it, because ruleset `Protect dev` requires an approving review and code-owner
+# sign-off that a bot cannot supply. Until that merge the red persists. This converts a
+# forgotten chore into a queued, reviewable change - not into an automatic repair.
+#
+# A `release` event resolves this workflow file from the repository DEFAULT branch
+# (`main`), not from `dev` - the same trap documented in cleanup-closed-pr-branches.yml.
+# So merging this file to `dev` installs it but arms nothing; it first fires after an
+# ordinary dev -> main promotion carries it there.
+#
+# There is deliberately no `workflow_dispatch`: a branch-selected manual run executes
+# THAT branch body with `contents: write`. Re-drive a missed run by running
+# `bun scripts/bump-dev-version.ts <released> package.json` locally and opening the pull
+# request normally.
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+concurrency:
+  group: dev-version-bump
+  cancel-in-progress: false
+
+jobs:
+  open-bump-pr:
+    runs-on: ubuntu-latest
+    permissions:
+      # Push the new codex/dev-version-* branch. Ruleset `Protect dev` covers only
+      # refs/heads/dev, so the bump branch is unprotected and this token cannot
+      # bypass dev review. It is the ruleset that keeps this job off dev, not the
+      # permission name.
+      contents: write
+      # Open the pull request.
+      pull-requests: write
+    steps:
+      - name: Checkout dev
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          ref: dev
+          # Tags are load-bearing, not decoration: the freeness gate below is a bun
+          # test that reads the local tag set, and release-version-line.test.ts
+          # returns EARLY on an empty set. A shallow checkout would make that gate
+          # silently vacuous instead of failing loudly.
+          fetch-depth: 0
+          # Do NOT set persist-credentials: false here as the read-only workflows do.
+          # This job has to push its bump branch.
+
+      # The repository-owned composite action, not a hand-pinned setup-bun SHA: it
+      # resolves the Bun version from package.json so the runtime SOT stays in one
+      # place. An independently pinned action here would drift from every other job.
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Decide the version dev should carry
+        id: decide
+        env:
+          RELEASED_VERSION: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          bun scripts/bump-dev-version.ts "${RELEASED_VERSION}" package.json
+
+      - name: Prove the chosen version is unused
+        if: ${{ steps.decide.outputs.changed == 'true' }}
+        # The script decides the candidate from the released version SHAPE, which is all
+        # a pure function can see. Whether that candidate is actually FREE is a property
+        # of the tag set, so it is settled here by the detector that already owns the
+        # question. If this fails, no pull request is opened and the job goes red asking
+        # for a human decision - which is the correct outcome, not a fallback.
+        run: bun test tests/release-version-line.test.ts
+
+      - name: Open the bump pull request
+        if: ${{ steps.decide.outputs.changed == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NEXT_VERSION: ${{ steps.decide.outputs.version }}
+          RELEASED_VERSION: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+
+          branch="codex/dev-version-${NEXT_VERSION}"
+
+          # Idempotent: a second publish, a re-run, or a manual repair must not turn a
+          # successful release into a red job.
+          #
+          # Check the PULL REQUEST as well as the branch, not just the branch. A security
+          # review caught that: an open bump pull request whose head branch was deleted
+          # leaves the branch check passing, so the job would recreate the branch and then
+          # fail on `gh pr create` with "already exists" — turning a successful release red
+          # for a repair that was already queued.
+          open_prs="$(gh pr list --base dev --head "${branch}" --state open --json number --jq 'length')"
+          if [ "${open_prs}" != "0" ]; then
+            echo "::notice::a bump pull request for ${branch} is already open; nothing to do"
+            exit 0
+          fi
+
+          # An existing branch is NOT terminal. If a previous run pushed the branch and then
+          # failed at `gh pr create`, exiting here would leave the repair permanently unqueued
+          # while every rerun reports success - the exact failure mode a reviewer caught. So
+          # reuse the branch and fall through to pull-request creation instead.
+          if git ls-remote --exit-code --heads origin "${branch}" >/dev/null 2>&1; then
+            echo "::notice::${branch} exists without an open pull request; validating it"
+            git fetch origin "${branch}"
+
+            # Fail closed on unexpected content. The branch carries the bot's own one-line
+            # bump, so anything else on it means a human or another job is using that name and
+            # this job must not push to it or open a pull request from it.
+            changed_files="$(git diff --name-only "origin/dev...origin/${branch}")"
+            if [ "${changed_files}" != "package.json" ]; then
+              echo "::error::${branch} touches unexpected files: ${changed_files:-<none>}"
+              exit 1
+            fi
+            branch_version="$(git show "origin/${branch}:package.json" | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).version")"
+            if [ "${branch_version}" != "${NEXT_VERSION}" ]; then
+              echo "::error::${branch} carries ${branch_version}, expected ${NEXT_VERSION}"
+              exit 1
+            fi
+            git checkout -B "${branch}" "origin/${branch}"
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git checkout -b "${branch}"
+            git add package.json
+            git commit -m "fix(release): move dev to ${NEXT_VERSION} after ${RELEASED_VERSION}"
+            git push origin "${branch}"
+          fi
+
+          gh pr create \
+            --base dev \
+            --head "${branch}" \
+            --title "fix(release): move dev to ${NEXT_VERSION} after ${RELEASED_VERSION}" \
+            --body "$(cat <<BODY
+          ## Summary
+
+          \`${RELEASED_VERSION}\` published, so \`dev\` would otherwise keep a version at or
+          behind a released one and \`tests/release-version-line.test.ts\` would fail on
+          \`dev\` and on every pull request opened against it. This moves \`dev\` to
+          \`${NEXT_VERSION}\`.
+
+          Opened automatically by \`.github/workflows/dev-version-bump.yml\`. The same
+          repair was previously done by hand in 32529c2b2, e4a85d134, 076ad3036, and
+          befcac3e1.
+
+          ## Verification
+
+          \`bun test tests/release-version-line.test.ts\` ran against this exact tree
+          before the pull request was opened; the workflow refuses to open one if the
+          chosen version collides with a published release.
+
+          ## Checklist
+
+          - [x] Scope stays focused and avoids unrelated cleanup.
+          - [x] Docs or release notes were updated when needed.
+          - [x] Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.
+          BODY
+          )"

MAINTAINERS.md

@@ -73,6 +73,21 @@ when a maintainer steps down.
 - Direct pushes are reserved for maintainer-owned integration work, urgent repairs, or incident
   recovery. The same CI and documentation requirements still apply.
 - Promotion from `dev` to `main` and npm releases is maintainer-controlled.
+- **Closing out a release includes moving `dev`'s version line forward.** A published
+  release leaves `dev` carrying a version at or behind it, and
+  `tests/release-version-line.test.ts` then fails on `dev` and on every pull request
+  opened against it — red that contributors inherit and cannot fix from their own diff.
+  This was repaired by hand four times (`32529c2b2`, `e4a85d134`, `076ad3036`,
+  `befcac3e1`) before it was automated.
+
+  `.github/workflows/dev-version-bump.yml` now opens that bump as a pull request when a
+  release publishes. Merging it is part of closing the release; a bot cannot, because
+  `Protect dev` requires an approving review and code-owner sign-off. Two caveats worth
+  knowing: the workflow runs from the DEFAULT branch, so it only fires once it has been
+  promoted to `main`; and a pull request opened with `GITHUB_TOKEN` does not start
+  `pull_request` workflows, so the bump pull request arrives without CI. To re-drive a
+  missed run by hand: `bun scripts/bump-dev-version.ts <released-version> package.json`,
+  then open the pull request normally.
 
 ## The retired `dev2-go` line
 

Start-OpenCodex.cmd

@@ -0,0 +1,13 @@
+@echo off
+setlocal
+
+powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "%~dp0Start-OpenCodex.ps1" %*
+set "launcher_exit=%ERRORLEVEL%"
+
+if not "%launcher_exit%"=="0" (
+  echo.
+  echo OpenCodex could not be started. Review the error above.
+  pause
+)
+
+exit /b %launcher_exit%

Start-OpenCodex.ps1

@@ -0,0 +1,140 @@
+[CmdletBinding()]
+param(
+  [ValidateRange(1, 65535)]
+  [int]$Port = 10100,
+
+  [ValidateRange(1, 120)]
+  [int]$StartupTimeoutSeconds = 30,
+
+  [switch]$NoBrowser
+)
+
+$ErrorActionPreference = "Stop"
+$repoRoot = $PSScriptRoot
+$dashboardUrl = "http://127.0.0.1:$Port/"
+$healthUrl = "${dashboardUrl}healthz"
+$logDirectory = Join-Path $repoRoot ".tmp"
+$stdoutLog = Join-Path $logDirectory "launcher.out.log"
+$stderrLog = Join-Path $logDirectory "launcher.err.log"
+
+function Get-OpenCodexHealth {
+  try {
+    $response = Invoke-RestMethod -Uri $healthUrl -Method Get -TimeoutSec 2
+    if ($response.service -eq "opencodex" -and $response.status -eq "ok") {
+      return $response
+    }
+  }
+  catch {
+    return $null
+  }
+
+  return $null
+}
+
+function Open-Dashboard {
+  if (-not $NoBrowser) {
+    Start-Process $dashboardUrl
+  }
+}
+
+function Test-IsLocalCheckoutProcess {
+  param([Parameter(Mandatory = $true)][int]$ProcessId)
+
+  try {
+    $runningProcess = Get-CimInstance Win32_Process -Filter "ProcessId=$ProcessId"
+    if ($null -eq $runningProcess) {
+      return $false
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($runningProcess.ExecutablePath) -and
+        $runningProcess.ExecutablePath.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
+      return $true
+    }
+
+    if ([string]::IsNullOrWhiteSpace($runningProcess.CommandLine)) {
+      return $false
+    }
+
+    $expectedEntryPoint = Join-Path $repoRoot "src\cli\index.ts"
+    return $runningProcess.CommandLine.IndexOf($expectedEntryPoint, [StringComparison]::OrdinalIgnoreCase) -ge 0
+  }
+  catch {
+    return $false
+  }
+}
+
+$localBunExecutable = Join-Path $repoRoot "node_modules\bun\bin\bun.exe"
+$bunApplication = Get-Command bun.exe -CommandType Application -ErrorAction SilentlyContinue
+if (Test-Path -LiteralPath $localBunExecutable) {
+  $bunExecutable = $localBunExecutable
+}
+elseif ($null -ne $bunApplication) {
+  $bunExecutable = $bunApplication.Source
+}
+else {
+  throw "Bun was not found. Install Bun from https://bun.sh, then run this launcher again."
+}
+
+if (-not (Test-Path -LiteralPath (Join-Path $repoRoot "node_modules"))) {
+  throw "Dependencies are missing. Open PowerShell in '$repoRoot', run 'bun install', then try again."
+}
+
+$existingHealth = Get-OpenCodexHealth
+if ($null -ne $existingHealth) {
+  if (Test-IsLocalCheckoutProcess -ProcessId $existingHealth.pid) {
+    Write-Host "This OpenCodex checkout is already running on port $Port (PID $($existingHealth.pid))."
+    Open-Dashboard
+    exit 0
+  }
+
+  Write-Host "A different OpenCodex installation is using port $Port (PID $($existingHealth.pid))."
+  Write-Host "Stopping it before starting this checkout..."
+  & $bunExecutable run src/cli/index.ts stop
+  if ($LASTEXITCODE -ne 0) {
+    throw "The existing OpenCodex instance could not be stopped safely."
+  }
+
+  $stopDeadline = (Get-Date).AddSeconds(15)
+  do {
+    Start-Sleep -Milliseconds 250
+    $existingHealth = Get-OpenCodexHealth
+  } while ($null -ne $existingHealth -and (Get-Date) -lt $stopDeadline)
+
+  if ($null -ne $existingHealth) {
+    throw "The previous OpenCodex instance is still using port $Port."
+  }
+}
+
+New-Item -ItemType Directory -Path $logDirectory -Force | Out-Null
+
+Write-Host "Starting OpenCodex on port $Port..."
+$process = Start-Process `
+  -FilePath $bunExecutable `
+  -ArgumentList @("run", "src/cli/index.ts", "start", "--port", "$Port") `
+  -WorkingDirectory $repoRoot `
+  -WindowStyle Hidden `
+  -RedirectStandardOutput $stdoutLog `
+  -RedirectStandardError $stderrLog `
+  -PassThru
+
+$deadline = (Get-Date).AddSeconds($StartupTimeoutSeconds)
+do {
+  Start-Sleep -Milliseconds 250
+  $process.Refresh()
+
+  $health = Get-OpenCodexHealth
+  if ($null -ne $health) {
+    if (-not (Test-IsLocalCheckoutProcess -ProcessId $health.pid)) {
+      throw "Port $Port became healthy, but it belongs to a different OpenCodex installation."
+    }
+    Write-Host "OpenCodex is ready at $dashboardUrl (PID $($health.pid))."
+    Open-Dashboard
+    exit 0
+  }
+
+  if ($process.HasExited) {
+    throw "OpenCodex stopped during startup (exit code $($process.ExitCode)). See '$stderrLog'."
+  }
+} while ((Get-Date) -lt $deadline)
+
+throw "OpenCodex did not become ready within $StartupTimeoutSeconds seconds. See '$stderrLog'."