feat(go): ADR-0008 Go runtime line — hot-path, CLI, management parity increments

.github/workflows/ci.yml

@@ -31,6 +31,7 @@ on:
       - "tests/**"
       - "scripts/**"
       - "gui/**"
+      - "go/**"
       - "assets/**"
       - ".gitattributes"
       - ".npmignore"
@@ -179,6 +180,7 @@ jobs:
               - 'tests/**'
               - 'scripts/**'
               - 'gui/**'
+              - 'go/**'
               - 'assets/**'
               - '.gitattributes'
               - '.npmignore'
@@ -282,6 +284,16 @@ jobs:
       - name: Setup project Bun
         uses: ./.github/actions/setup-project-bun
 
+      # The Go sidecar parity test (tests/go-sidecar-parity.test.ts) builds the
+      # sidecar with the local toolchain; whichever shard picks the file up runs
+      # the oracle only when `go` is on PATH. Keep it installed so the oracle
+      # never silently skips in the ordinary suite.
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
       # The GUI install is NOT optional here, however unrelated it looks to a
       # test shard. Several files under tests/ import JSX-bearing modules from
       # gui/src (ProviderRail and friends), and React is declared only in
@@ -380,6 +392,67 @@ jobs:
       - name: Test api usage API
         run: bun test --isolate ./tests/api-usage.test.ts
 
+  # Go sidecar line (ADR-0008): the fresh in-tree Go module plus the differential
+  # oracle that proves the TS health handler and the ocx-sidecar agree on status,
+  # headers, and the normalised body for GET /api/system/health. Runs the Go
+  # toolchain gates (build/vet/test under go/) and then the Bun parity harness
+  # against the binary it builds. The module has no external dependencies, so
+  # module caching is disabled.
+  go:
+    name: go
+    needs: changes
+    if: github.event_name != 'pull_request' || needs.changes.outputs.ci == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      # The sidecar is built static per the ADR-0008 plan (CGO_ENABLED=0); the
+      # parity harness sets the same flag when it builds a throwaway binary.
+      CGO_ENABLED: "0"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project Bun
+        uses: ./.github/actions/setup-project-bun
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
+      - name: Go build
+        run: cd go && go build ./...
+
+      - name: Go vet
+        run: cd go && go vet ./...
+
+      - name: Go test
+        run: cd go && go test ./...
+
+      - name: Cross-compile every release target (CGO_ENABLED=0)
+        # Ticket #8 acceptance: the ocx-sidecar must build static on every
+        # release target (linux/darwin/windows x amd64/arm64), not only the
+        # native platform of this runner. A platform-specific dependency that
+        # leaks cgo (or a build tag mistake) would otherwise surface only at
+        # release time. The loop proves all six combinations produce a binary;
+        # artifacts land in /tmp and are discarded.
+        run: |
+          set -euo pipefail
+          cd go
+          for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
+            os="${target%/*}"; arch="${target#*/}"
+            GOOS="$os" GOARCH="$arch" CGO_ENABLED=0 go build -o "/tmp/ocx-sidecar-$os-$arch" ./cmd/ocx-sidecar
+          done
+
+      - name: Differential oracles
+        run: bun test --timeout 60000 tests/go-sidecar-parity.test.ts tests/go-cli-parity.test.ts
+
   # Everything that is not the suite: type safety, privacy, lint, build, smoke.
   # One runner, once per push. Splitting these across the shards would repeat a
   # fixed couple of minutes four times to save nothing.
@@ -486,6 +559,14 @@ jobs:
       - name: Setup project Bun
         uses: ./.github/actions/setup-project-bun
 
+      # Same rationale as the Linux shards: this lane runs the whole suite,
+      # which includes the Go-sidecar differential oracle.
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
       - name: Install dependencies
         run: |
           bun install --frozen-lockfile
@@ -498,6 +579,14 @@ jobs:
           cd gui
           bun run build
 
+      # Run the two data-plane differentials explicitly before the full-suite
+      # control. The unsharded suite also discovers them, but this named step
+      # makes macOS parity evidence independently visible and stable.
+      - name: Hot-path differential oracles
+        run: >-
+          bun test --timeout 60000
+          tests/go-hotpath-relay.test.ts tests/go-hotpath-seam.test.ts
+
       # Bun 1.3.14 segfaults while reclaiming a Worker at an `--isolate` file
       # boundary: the header shows BALANCED `workers_spawned(N)
       # workers_terminated(N)` and the process dies with exit 133 after the last
@@ -623,6 +712,14 @@ jobs:
       - name: Setup project Bun
         uses: ./.github/actions/setup-project-bun
 
+      - name: Setup Go
+        # The explicit Windows hot-path differential below builds and executes
+        # a native sidecar, so GOOS cross-compilation alone is insufficient.
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
       - name: Install dependencies
         run: |
           bun install --frozen-lockfile
@@ -635,6 +732,14 @@ jobs:
           cd gui
           bun run build
 
+      # This is deliberately separate from the sharded suite: a shard can move
+      # with file ordering, while this named result is the Windows evidence for
+      # byte-identical relay and SSE-seam behaviour against a native sidecar.
+      - name: Hot-path differential oracles
+        run: >-
+          bun test --timeout 60000
+          tests/go-hotpath-relay.test.ts tests/go-hotpath-seam.test.ts
+
       - name: Test
         # --timeout: the Linux batches and the macOS control both pass 60000; this leg was
         # the only one left on Bun's 5s default, and it is the slowest hardware on the board.
@@ -805,7 +910,7 @@ jobs:
     # direct dependencies only, so a failing `select-windows-runner` would
     # otherwise reach this gate as nothing at all while its dependents report
     # `skipped` — which the gate is required to read as a deliberate skip.
-    needs: [changes, select-windows-runner, test, storage-policy, api-usage, gates, platform-macos, platform-windows, keyring-smoke, npm-global-smoke]
+    needs: [changes, select-windows-runner, test, storage-policy, api-usage, go, gates, platform-macos, platform-windows, keyring-smoke, npm-global-smoke]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:

.github/workflows/go-release-artifacts.yml

@@ -0,0 +1,86 @@
+name: Go release artifact scaffold
+
+on:
+  # This workflow deliberately stays outside the release path until #40 proves
+  # that the Go artifact embeds every runtime asset required by a clean host.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: go-release-artifacts-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify-go-runtime:
+    name: verify Go runtime
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
+      - name: Build, vet, and test Go runtime
+        run: |
+          set -euo pipefail
+          cd go
+          CGO_ENABLED=0 go build -buildvcs=false ./...
+          go vet ./...
+          go test ./...
+
+      - name: Smoke test Linux release candidate
+        run: |
+          set -euo pipefail
+          scripts/build-go-release-artifact.sh linux/amd64 .tmp/go-release/linux-amd64
+          .tmp/go-release/linux-amd64/ocx-linux-amd64 --version
+
+  build-release-artifact:
+    name: build ${{ matrix.target }}
+    needs: verify-go-runtime
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: linux/amd64
+            artifact: ocx-linux-amd64
+          - target: linux/arm64
+            artifact: ocx-linux-arm64
+          - target: darwin/amd64
+            artifact: ocx-darwin-amd64
+          - target: darwin/arm64
+            artifact: ocx-darwin-arm64
+          - target: windows/amd64
+            artifact: ocx-windows-amd64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go/go.mod
+          cache: false
+
+      - name: Cross-compile static ocx candidate
+        run: scripts/build-go-release-artifact.sh '${{ matrix.target }}' dist
+
+      - name: Upload candidate
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7

.gitignore

@@ -59,9 +59,8 @@ devlog/**/security-advisory-draft*
 tests/.tmp-*
 .claude/
 
-# Retired Go native-runtime experiment. `go/` is not part of the build, the
-# typecheck, or the test path, and nothing in `src/` imports it. A single file
-# from it (go/internal/cli/config_parity.go) has now been committed by a broad
-# `git add` three separate times and reached `dev` once — see
-# tests/repo-hygiene.test.ts, which fails if any path here becomes tracked again.
-go/
+# Go sidecar line (ADR-0008). `go/` is a tracked in-tree Go module under
+# incremental takeover; only per-machine build output stays ignored so a stray
+# `go build -o bin` cannot be committed. Nothing in `src/` imports `go/` at
+# runtime — the TypeScript server spawns the built binary as a child process.
+go/bin/

AGENTS.md

@@ -16,8 +16,10 @@ Bun-native TypeScript with no separate server compile step.
   `tests/helpers/`, broader scenarios in `tests/e2e-style/`.
 - `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
 - `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
-- `go/` — retired Go native-runtime experiment; kept only where the TypeScript
-  runtime still references it. New work does not go here.
+- `go/` — the Go runtime under incremental takeover (see
+  `docs/adr/0008-go-runtime-incremental-takeover.md`). The retired `dev2-go`
+  port is archived at `lidge-jun/opencodex-go-archive` (tag `archive/dev2-go`)
+  and is reference material only, not a fork.
 - `structure/` — maintainer invariants and architecture notes; read before
   changing shared subsystems.
 - `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
@@ -241,6 +243,20 @@ They are not regressions; do not re-investigate them:
 
 Everything else passes (15480 pass / 16 skip / 5 fail as of 2.35.0).
 
+## Agent skills
+
+### Issue tracker
+
+Issues live in this repo's GitHub Issues; agent-created issues must use the `.github/ISSUE_TEMPLATE/` forms (the `enforce-issue-quality` gate closes freeform issues). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-label vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: root `CONTEXT.md` (when present) plus root `docs/adr/`. See `docs/agents/domain.md`.
+
 ## Issues and pull requests (agents)
 
 Agent-created issues and PRs must use the repository templates. The gates
@@ -282,9 +298,12 @@ than nudged.
   from `dev` (releases, docs deploys). Do not open feature PRs against `main`.
 - `preview` — prerelease train (`x.y.z-preview.*` versions).
 
-Bun-native TypeScript on `dev` is the only runtime line. If native code
-returns, the expectation is an incremental module (for example Rust via N-API)
-landing on `dev`, not a second full-runtime branch.
+Bun-native TypeScript on `dev` is the only runtime line today; it is being
+migrated to Go as an incremental sidecar takeover, per
+`docs/adr/0008-go-runtime-incremental-takeover.md`. The Go sidecar takes over
+routes one at a time behind the TypeScript front door, ending in a single
+static Go binary. The retired `dev2-go` parallel line stays retired — no
+second full-runtime branch is being reopened.
 
 Stacked child pull requests that target another **open** PR's head branch are
 an intentional review workflow, not an alternate integration line. The

MAINTAINERS.md

@@ -98,7 +98,8 @@ and ported under `go/`. That policy is withdrawn as of 2026-07-30.
 The dual-track cost outran its return: the carry backlog never cleared (17
 commits and 9 open `needs-go-port` issues at the time of the decision, against
 594 commits of divergence), and dogfooding the Go runtime kept producing new
-defects. Bun-native TypeScript on `dev` is the single runtime line again.
+defects. Bun-native TypeScript on `dev` was the single runtime line again —
+until ADR-0008 reopened Go work as a sidecar takeover.
 
 - The branch has been deleted from this repository. Its full history is
   published at
@@ -108,9 +109,12 @@ defects. Bun-native TypeScript on `dev` is the single runtime line again.
   issues (#661, #663, #666, #670, #674, #678, #680, #685, #703) were closed as
   not planned, and the `needs-go-port` label no longer exists on the
   repository.
-- Future native work is expected to be an incremental module landing on `dev`
-  (Rust via N-API is the current candidate), not a second integration branch.
-  Reopening a parallel runtime line is an owner decision.
+- Future native work is expected to be an incremental module landing on `dev`,
+  not a second integration branch. At the time of retirement the candidate was
+  Rust via N-API; ADR-0008 supersedes that with a Go runtime reopened as an
+  incremental sidecar takeover — a fresh `go/` codebase, not a fork of this
+  archive and not a parallel line. Reopening a parallel runtime line remains an
+  owner decision. See `docs/adr/0008-go-runtime-incremental-takeover.md`.
 
 ## Maintainer changes