feat: implement Codencer v2 local self-host path (#2)

* feat: implement Codencer v2 local self-host path

Implement the full v2 local/self-host bridge path in this session:

- harden the local daemon with explicit repo-root targeting, stable instance identity,
  manifest-backed discovery, truthful runtime compatibility reporting, artifact content
  retrieval, run reconciliation, and gate lifecycle closure
- add the outbound connector with persistent Ed25519 identity, enrollment, signed
  challenge/response session auth, reconnect/heartbeat behavior, explicit instance
  sharing, and a narrow allowlisted proxy to the local daemon
- add the self-host relay with sqlite-backed connector/enrollment state, planner
  auth scopes, connector session tracking, planner-facing /api/v2 routes, audit
  persistence, and resource routing hints
- add the relay MCP surface with codencer.* tools on /mcp, keeping /mcp/call as
  a compatibility path while preserving relay auth and instance scoping
- rewrite operator-facing architecture, security, connector, relay, self-host, and
  MCP docs to match current runtime truth, add WSL/Windows/Antigravity topology
  guidance, and record the v2 work in the changelog

Verification performed:
- go test ./internal/app ./internal/service ./internal/connector ./internal/relay ./internal/mcp -count=1
- go test ./... -count=1

Known alpha limitations remain explicit in docs: best-effort abort, opportunistic
relay routing for previously unseen resource IDs, bounded artifact transport, and
static self-host auth.

* chore: clean and harden Codencer v2 alpha surfaces

Remove tracked local build output and collapse duplicate public command entrypoints by deleting the legacy connector and relayd mains and keeping codencer-connectord and codencer-relayd as the canonical binaries. Update build ignores and the Makefile so local command artifacts are not recommitted and duplicate bin targets are not produced.

Tighten daemon async dispatch and abort handling by moving background step submission onto RunService.DispatchStepAsync, reusing that path for retry dispatch, and making abort report success only when the active step actually reaches cancelled. Fail closed when no execution was registered or when adapter cancellation is not confirmed, and cover the immediate-abort race with focused service tests.

Clarify MCP hierarchy and public surfaces by marking the daemon-local /mcp/call endpoint as a legacy local compatibility/admin bridge, keeping the relay MCP as the canonical remote integration surface, and adding explicit surface headers to distinguish the two.

Bring runtime truth and docs back into alignment across README, relay, connector, self-host, MCP, and v2 contract notes so the repo now documents the actual alpha-grade guarantees and limitations: no raw shell, no arbitrary filesystem browsing, narrow remote routing, best-effort abort, bounded artifact transport, and static self-host auth.

Verification: gofmt -w on touched Go files; go test ./internal/service ./internal/app ./internal/relay ./internal/connector ./internal/mcp -count=1; go test ./... -count=1

* chore: finalize alpha cleanup and repo truth pass

Remove committed extension dependency and build artifacts by deleting extension/node_modules and extension/out while keeping the extension manifests and source.

Unify repo version/status truth on v0.2.0-alpha across the Makefile, runtime version string, public docs, validation scenario assets, and extension metadata.

Tighten publication-facing wording so relay MCP remains the canonical remote surface, daemon-local MCP stays clearly local compatibility/admin only, and adapter/readiness claims defer to runtime compatibility instead of stale static support labels.

Harden local runtime behavior with nanosecond attempt IDs, safer worktree reclamation for reused run branches, and clearer abort error wording when cancellation cannot be confirmed.

Fix and stabilize service tests by isolating validation worktree tests from the real checkout and correcting the success provenance adapter so it reports completion instead of hanging the suite.

Verification: go test ./internal/app ./internal/connector ./internal/relay ./internal/mcp -count=1; go test ./internal/service -count=1; go test ./... -count=1

* feat: complete Codencer v2 self-host alpha path

Finalize the current v2 implementation for practical daily self-use
without changing the core bridge-not-brain architecture.

Daemon hardening:
- fail closed for aborts against paused_for_gate runs and only report
  success when the active step really reaches cancelled
- tighten restart recovery to restore evidence-backed terminal/gated
  states and move ambiguous active work to needs_manual_attention
- add local read routes for gate metadata and artifact metadata by id
- make log and artifact selection deterministic across multiple attempts
- remove repo-root fallback/path leaks and harden worktree cleanup on
  provisioning and adapter start failures

Connector completion:
- add persisted local connector status snapshots with session state,
  heartbeat/error fields, and shared instance ids
- add codencer-connectord status --json for offline operator inspection
- keep explicit sharing only and extend the allowlist narrowly for safe
  relay route probing of artifact and gate metadata

Relay completion:
- add relay admin/status endpoints for status, connectors, and recent audit
- resolve step/artifact/gate routes deterministically by probing only
  authorized online shared instances when route hints are missing
- persist discovered route hints and keep ambiguous or offline lookups
  fail-closed

Relay MCP and operator flow:
- update relay MCP resource tools to use deterministic routing without
  requiring prior observation of resource ids
- add a practical self-host smoke script and broker build target
- sync README and operator docs to the current alpha-grade runtime truth,
  including canonical binaries, relay MCP hierarchy, bootstrap-only
  enrollment_secret wording, and honest abort/auth limitations

Verification performed:
- go test ./internal/app ./internal/service ./internal/storage/sqlite -count=1
- go test ./internal/connector ./internal/relay ./internal/mcp ./cmd/codencer-connectord -count=1
- go test ./... -count=1
- go build ./cmd/orchestratord ./cmd/orchestratorctl ./cmd/codencer-connectord ./cmd/codencer-relayd
- (cd cmd/broker && go build ./...)
- make build
- live self-host smoke path against local daemon + relay + connector

* Finish practical v2 self-host path

* Finish practical v2 delta hardening

* Add cloud control plane alpha foundation

* Deepen cloud runtime control plane

* Harden cloud control plane alpha

* Finalize beta tracks and confirm v0.2.0-beta

This commit lands the full beta-finalization program for the current
Codencer repository and promotes the repo-wide release truth from
v0.2.0-alpha to v0.2.0-beta.

It includes the completed work across the frozen beta workstreams:

- cloud self-host finalization
  - close tenant-scope and token-revocation gaps
  - harden cloud runtime HTTP and cloud MCP parity
  - strengthen composed cloud runtime, MCP, and SDK proof
- relay/runtime connector finalization
  - fix share --instance-id so shared state cannot drift into unroutable
    fake-shared entries
  - harden connector re-advertise and stale session pruning
  - keep relay HTTP and relay MCP scoped and behaviorally aligned
- local core finalization
  - fix the local same-run wait/finalization race
  - stabilize retry/result lifecycle truth
  - make legacy v1/local parity smoke repeatable
- planner/client integration finalization
  - freeze the public compatibility matrix to proven vs expected vs
    compatibility-only claims
  - package relay/cloud MCP guidance and client examples
- provider connector finalization
  - preserve repeated webhook history as append-only event storage
  - enforce Jira webhook deferment truthfully
  - enrich provider action and audit logs
- release engineering and public testability
  - add explicit repo-level verification entrypoints
  - improve public tester routing and self-host documentation
  - keep deployment packaging and Docker compose proof aligned with repo
    truth
- final beta confirmation
  - rerun the frozen verification matrix
  - rerun Docker-backed cloud stack proof on a live Docker daemon host
  - add the durable beta confirmation report
  - update public and internal release surfaces to v0.2.0-beta

Public truth after this commit:
- Codencer is beta for the supported local, self-host relay/runtime,
  self-host cloud, planner/client, and provider tracks
- compatibility-only and deferred surfaces remain explicitly outside the
  beta promise
- non-blocking linker warning noise remains documented but does not block
  the beta claim

Verification performed:
- make build-supported
- make verify-beta
- make cloud-stack-smoke
- detached temporary worktree overlay:
  make build-supported && make verify-beta
- make verify-beta-docker

* Preserve beta confirmation docs for merge

* Finalize beta launch docs, walkthroughs, and public CI

Rewrite the README around the durable execution record and planner-to-executor bridge while preserving the v0.2.0-beta status block, quickstart commands, and beta track table.

Restructure setup docs into a platform hub, add dedicated macOS, Windows, WSL, and remote VPS walkthroughs, and consolidate scattered limits into docs/KNOWN_LIMITATIONS.md.

Add planner-side MCP walkthroughs for ChatGPT, Claude Desktop/claude.ai, and Gemini CLI plus minimal example JSON files, keeping ChatGPT and Claude compatibility-only and Gemini expected-only.

Add operator-facing v0.2.0-beta release notes and cross-platform public-testability workflows for macOS and Windows, with Windows scoped truthfully to agent-broker build coverage while BG-011 remains a known secondary-surface test failure.

Author: lookmanrays

.github/workflows/public-testability-macos.yml

@@ -0,0 +1,45 @@
+name: Public Testability (macOS)
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-macos:
+    runs-on: macos-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Cache Go build and module directories
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/Library/Caches/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Install macOS verification prerequisites
+        run: |
+          brew update
+          brew install jq docker docker-compose
+          mkdir -p ~/.docker/cli-plugins
+          ln -sf "$(brew --prefix docker-compose)/bin/docker-compose" ~/.docker/cli-plugins/docker-compose
+          docker compose version
+
+      - name: Build supported beta-track binaries
+        run: make build-supported
+
+      - name: Run supported public verification
+        run: make verify-beta

.github/workflows/public-testability-windows.yml

@@ -0,0 +1,60 @@
+name: Public Testability (Windows)
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-windows-broker:
+    runs-on: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Cache Go build and module directories
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/go/pkg/mod
+            ~/AppData/Local/go-build
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Install GNU Make
+        shell: pwsh
+        run: choco install make -y
+
+      - name: Verify make availability
+        shell: bash
+        run: make --version
+
+      - name: Build Windows agent-broker only
+        shell: bash
+        run: make build-broker
+
+      - name: Run nested broker tests (BG-011 still secondary and allowed to fail)
+        id: broker_tests
+        continue-on-error: true
+        shell: bash
+        working-directory: cmd/broker
+        run: go test ./...
+
+      - name: Report nested broker test status
+        if: always()
+        shell: bash
+        run: |
+          if [ "${{ steps.broker_tests.outcome }}" = "success" ]; then
+            echo "Nested cmd/broker tests passed in this run."
+          else
+            echo "BG-011 remains open: nested cmd/broker tests still fail, so the workflow only enforces the documented Windows claim that agent-broker builds on windows-latest."
+          fi

.github/workflows/public-testability.yml

@@ -0,0 +1,32 @@
+name: Public Testability
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Install CGO build prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends build-essential
+
+      - name: Build supported beta-track binaries
+        run: make build-supported
+
+      - name: Run supported public verification
+        run: ./scripts/verify_beta.sh

.gitignore

@@ -1,8 +1,20 @@
 # Build artifacts
 bin/
+node_modules/
+extension/out/
 orchestratorctl
 !cmd/orchestratorctl/
 !cmd/orchestratorctl/*.go
+/cmd/broker/agent-broker
+/cmd/broker/agent-broker.exe
+/cmd/codencer-connectord/codencer-connectord
+/cmd/codencer-connectord/codencer-connectord.exe
+/cmd/codencer-relayd/codencer-relayd
+/cmd/codencer-relayd/codencer-relayd.exe
+/cmd/orchestratord/orchestratord
+/cmd/orchestratord/orchestratord.exe
+/cmd/orchestratorctl/orchestratorctl
+/cmd/orchestratorctl/orchestratorctl.exe
 *.test
 *.out
 service.test

AGENTS.md

@@ -9,9 +9,10 @@ You are a principal engineer implementing a production-oriented local orchestrat
 
 ## General rules
 - follow the docs strictly
+- treat current code, tests, and smoke results as release truth when historical docs disagree
 - implement one phase at a time
 - do not widen scope
-- do not add cloud
+- do not add new cloud product scope; existing self-host cloud control-plane code is in scope for truthful maintenance
 - do not skip tests
 - do not skip docs when behavior changes
 - do not bypass service boundaries

CHANGELOG.md

@@ -7,17 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0-beta] - 2026-04-23
+
 ### Added
+- Self-hostable v2 relay path with:
+  - stable daemon instance identity and manifest-backed discovery
+  - outbound authenticated connector sessions with explicit shared-instance allowlists
+  - self-host relay planner API, enrollment token flow, audit persistence, and relay-side MCP tools
+- Cloud control-plane self-host surface with `codencer-cloudd`, `codencer-cloudctl`, and `codencer-cloudworkerd`, plus bootstrap/status/org/workspace/project/token/install/event/audit flows.
+- Cloud installation enable/disable routes and matching `cloudctl install enable|disable` subcommands.
+- Truthful cloud docs and smoke guidance for the bootstrap and control-plane path.
 - **OpenClaw (acpx) Adapter**: 🧪 Experimental support for OpenClaw-compatible executors via the standardized ACP bridge.
 - Official sequential wrapper examples for bash/zsh, PowerShell, and Python under `examples/automation/`.
 - Wrapper-friendly sample task lists and prompt/task inputs for ordered execution.
 - New `scripts/smoke_test_v1.sh` for verifying all 6 primary submission modes.
+- Public beta tester guide in `docs/BETA_TESTING.md` with exact local, relay, cloud, planner/client, and provider test-track entrypoints.
+- `make build-supported`, `make verify-beta`, and `make verify-beta-docker` as explicit repo-level verification entrypoints for the supported tracks.
+- Planner-client walkthroughs for ChatGPT, Claude Desktop plus `claude.ai`, and Gemini CLI under `docs/mcp/integrations/`.
+- Per-platform setup walkthroughs for macOS, Windows plus `agent-broker`, WSL, and remote VPS dev-server layouts.
+- Consolidated operator boundary reference in `docs/KNOWN_LIMITATIONS.md`.
+- Operator-facing beta launch notes in `docs/RELEASE_NOTES_v0.2.0-beta.md`.
+- Cross-platform public-testability CI on `macos-latest` and `windows-latest`.
 
 ### Changed
-- **Unified v1 Documentation Truth-Pass**: Cleaned and synchronized all public-facing docs (README, AI Guide, Runbook, Automation) for 100% alignment with the CLI contract.
+- Adopted `v0.2.0-beta` as the truthful build/version string for the current v2 local/self-host beta repo state.
+- Rewrote operator-facing v2 docs to match the implemented local/self-host path and current runtime truth.
+- Clarified that the relay is the public remote HTTP/MCP surface and the daemon-local `/mcp/call` endpoint is only a local compatibility/admin surface.
+- Documented current self-host beta boundaries explicitly: best-effort abort, bounded artifact transport, static-token auth, and relay routing that now probes only authorized online shared instances before failing closed.
+- Removed duplicate public connector/relay binary surfaces in favor of the canonical `codencer-connectord` and `codencer-relayd` entrypoints.
+- Tightened abort reporting so Codencer only reports success when the active step really reaches `cancelled`.
+- Removed committed extension dependency/build output directories and kept only the extension manifests plus source.
+- Added relay admin/status routes, connector local status snapshots, and a practical self-host smoke flow for daily operator use.
+- **Unified Documentation Truth-Pass**: Cleaned and synchronized current public-facing docs (README, AI Guide, Runbook, Automation) for alignment with the implemented CLI and relay surfaces.
 - Expanded automation documentation to make the shell-planner story explicit and machine-oriented.
 - Clarified that ordered task execution in v1 is wrapper-based and not a native workflow engine.
 - Hardened smoke/example guidance around strict JSON parsing and machine-safe CLI usage.
+- Clarified the public test-track boundaries so local, relay/runtime, cloud, planner/client, and provider testing route to the right docs without mixing surfaces.
+- Parameterized the Docker cloud image build version through the compose environment instead of hardcoding it only inside the Dockerfile.
 
 ## [0.1.0-beta] - 2026-03-28
 
@@ -49,3 +75,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ---
 
 [0.1.0-beta]: https://github.com/lookmanrays/codencer/releases/tag/v0.1.0-beta
+[0.2.0-beta]: https://github.com/lookmanrays/codencer/releases/tag/v0.2.0-beta

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Codencer
 
-Thank you for your interest in contributing to Codencer! As a **Public Beta (v0.1.0-beta)** project, we are actively looking for feedback on our orchestration protocols, CLI ergonomics, and adapter reliability.
+Thank you for your interest in contributing to Codencer! As an **open-source beta (`v0.2.0-beta`)** project, we are actively looking for feedback on the current local/self-host execution path, CLI ergonomics, and adapter reliability.
 
 ## 🏛 The Relay Philosophy
 Before contributing, please remember that Codencer is a **Defensive Relay**, not a "Brain." We prioritize:

Makefile

@@ -1,10 +1,39 @@
+VERSION ?= v0.2.0-beta
+LDFLAGS := -X agent-bridge/internal/app.Version=$(VERSION)
+
 all: lint test build
 
+build-supported: build build-cloud build-mcp-sdk-smoke
+
 build:
+	@mkdir -p bin
 	@echo "==> Building orchestratord..."
-	@go build -ldflags "-X agent-bridge/internal/app.Version=v1.0-release-candidate" -o bin/orchestratord ./cmd/orchestratord
+	@go build -ldflags "$(LDFLAGS)" -o bin/orchestratord ./cmd/orchestratord
 	@echo "==> Building orchestratorctl..."
-	@go build -ldflags "-X agent-bridge/internal/app.Version=v1.0-release-candidate" -o bin/orchestratorctl ./cmd/orchestratorctl
+	@go build -ldflags "$(LDFLAGS)" -o bin/orchestratorctl ./cmd/orchestratorctl
+	@echo "==> Building codencer-connectord..."
+	@go build -ldflags "$(LDFLAGS)" -o bin/codencer-connectord ./cmd/codencer-connectord
+	@echo "==> Building codencer-relayd..."
+	@go build -ldflags "$(LDFLAGS)" -o bin/codencer-relayd ./cmd/codencer-relayd
+
+build-cloud:
+	@mkdir -p bin
+	@echo "==> Building codencer-cloudctl..."
+	@go build -ldflags "$(LDFLAGS)" -o bin/codencer-cloudctl ./cmd/codencer-cloudctl
+	@echo "==> Building codencer-cloudd..."
+	@go build -ldflags "$(LDFLAGS)" -o bin/codencer-cloudd ./cmd/codencer-cloudd
+	@echo "==> Building codencer-cloudworkerd..."
+	@go build -ldflags "$(LDFLAGS)" -o bin/codencer-cloudworkerd ./cmd/codencer-cloudworkerd
+
+build-broker:
+	@mkdir -p bin
+	@echo "==> Building agent-broker (nested module)..."
+	@cd cmd/broker && go build -o ../../bin/agent-broker ./...
+
+build-mcp-sdk-smoke:
+	@mkdir -p bin
+	@echo "==> Building mcp-sdk-smoke (official MCP SDK proof helper)..."
+	@go build -o bin/mcp-sdk-smoke ./cmd/mcp-sdk-smoke
 
 test:
 	@echo "==> Running tests..."
@@ -116,6 +145,38 @@ smoke: build
 	@echo "==> Running automated smoke test..."
 	@./scripts/smoke_test.sh
 
+self-host-smoke: build
+	@echo "==> Running self-host relay/connector smoke test..."
+	@./scripts/self_host_smoke.sh
+
+self-host-smoke-all: build build-mcp-sdk-smoke
+	@echo "==> Running self-host relay/connector smoke test with all optional scenarios..."
+	@SMOKE_SCENARIOS=all ./scripts/self_host_smoke.sh
+
+self-host-smoke-mcp: build build-mcp-sdk-smoke
+	@echo "==> Running self-host relay/connector smoke test with MCP coverage..."
+	@SMOKE_SCENARIOS=status,audit,mcp,mcp-sdk ./scripts/self_host_smoke.sh
+
+cloud-smoke: build-cloud
+	@echo "==> Running cloud control-plane smoke test..."
+	@./scripts/cloud_smoke.sh
+
+cloud-stack-config:
+	@ENV_FILE=deploy/cloud/.env; \
+	if [ ! -f "$$ENV_FILE" ]; then ENV_FILE=deploy/cloud/.env.example; fi; \
+	echo "==> Validating docker compose cloud stack with $$ENV_FILE..."; \
+	docker compose --env-file "$$ENV_FILE" -f deploy/cloud/docker-compose.yml config > /dev/null
+
+cloud-stack-smoke:
+	@echo "==> Running docker-compose cloud stack smoke test..."
+	@./deploy/cloud/smoke.sh
+
+verify-beta: build-supported
+	@./scripts/verify_beta.sh
+
+verify-beta-docker: build-supported
+	@./scripts/verify_beta.sh --docker
+
 validate: build
 	@echo "==> Running Codex validation scenario (Internal Version Bump)..."
 	@./bin/orchestratorctl run start validation-run-01 validation-project || true