Release 2.1.9

.github/workflows/agent-contract.yml

@@ -47,7 +47,11 @@ jobs:
         run: python scripts/refresh_agent_index.py --check
 
       - name: Test and publish framework locally
-        run: ./gradlew test publishToMavenLocal
+        run: |
+          chmod +x gradlew
+          ./gradlew test publishToMavenLocal
 
       - name: Test Maven consumer project
-        run: bash ./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test -Dpkb_browser=CHROME_HEADLESS
+        run: |
+          chmod +x maven-consumer-project/mvnw
+          bash ./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test -Dpkb_browser=CHROME_HEADLESS

AGENTS.md

@@ -69,11 +69,13 @@ Diagnostic lineage is metadata, not part of the execution RunVars. Supply `pkb_i
 Use all relevant evidence rather than trusting one file in isolation:
 
 - Current implementation under `src/main/java` and `src/main/aspectj`
+- Dependency-neutral controller/worker wire contracts under `pickleball-control-protocol`; this module must remain JDK-only
 - Dynamic-control companion source module under `pickleball-control-api`; its classes are bundled into the main `tools.dscode:pickleball` artifact and are not a separate consumer dependency
+- Controller-only Workbench source under `pickleball-workbench`; it may depend on `pickleball-control-protocol` but never on Pickleball core or `pickleball-control-api`
 - Consumer-hosted internal Java checks under `maven-consumer-project/src/test/java`
 - Executable consumer examples under `maven-consumer-project/src/test`
 - `README.md` and the guides under `docs`
-- Build and dependency configuration in `build.gradle`, `settings.gradle`, `pickleball-control-api/build.gradle`, and `maven-consumer-project/pom.xml`
+- Build and dependency configuration in `build.gradle`, `settings.gradle`, `pickleball-control-protocol/build.gradle`, `pickleball-control-api/build.gradle`, `pickleball-workbench/build.gradle`, and `maven-consumer-project/pom.xml`
 - `docs/agent/feature-map.md` for navigation, not as a replacement for source inspection
 
 When implementation, tests, examples, and documentation disagree:
@@ -89,7 +91,9 @@ When implementation, tests, examples, and documentation disagree:
 - `src/main/java` — framework implementation and Cucumber integrations
 - `src/main/aspectj` — AspectJ integrations and weaving behavior
 - `src/main/resources` — framework resources
+- `pickleball-control-protocol` — JDK-only versioned wire records, capability/version constants, request envelopes, and response envelopes shared by core/worker and Workbench; no runtime behavior
 - `pickleball-control-api` — internal companion source module for retry-friendly detached execution, Gherkin utilities, ParsingMap/NodeMap inspection and emulation, and dynamic controller tooling; bundled into the main Pickleball artifact rather than published separately
+- `pickleball-workbench` — controller-only GUI/MCP/synchronization/process client; its executable must contain no Pickleball, Cucumber, Selenium, REST-assured, worker, or behavioral control-API implementation
 - `src/test` — reserved for tests that must run inside the framework build
 - `docs` — detailed user-facing documentation
 - `maven-consumer-project` — executable Maven consumer example
@@ -167,6 +171,16 @@ Internal Java checks should normally live in `maven-consumer-project` and be exe
 
 Tests must cover the requested behavior and meaningful compatibility or edge cases. Do not weaken or delete assertions merely to make a change pass.
 
+For Workbench, control-protocol, worker bridge, launcher, or nested-payload changes, never use `@all` as migration validation. Run only the smallest affected tags (currently `@control-bridge` and/or `@step-override-bridge`) and set `-Dpkb_runvars.pkb_parallel=80` when the focused environment can safely benefit. Preserve this rule in future Workbench plans and handovers.
+
+### Workbench controller-isolation invariant
+
+Pickleball Workbench is the control plane, not a second Pickleball runtime. The only shared Java boundary is `pickleball-control-protocol`. Workbench must not compile against, resolve, shade, load, or execute the root Pickleball project, `tools.dscode:pickleball`, `pickleball-control-api`, the consumer's classes, or runtime libraries such as Cucumber, Selenium, and REST-assured. Never “fix” a Workbench compilation problem by restoring `implementation project(':')`, `pickleballPublishedElements`, a Pickleball Maven dependency, or core shading.
+
+Only the separate consumer worker JVM executes Pickleball. `WorkbenchWorkerManager` must launch `ControlProtocol.WORKER_MAIN_CLASS` by name on the consumer build's captured test-runtime classpath, and must verify the worker PID, Pickleball code source, synchronized version, and absence of the Workbench controller artifact. Commands and state cross the local authenticated versioned protocol, not direct Java calls.
+
+The published Pickleball JAR embeds the completed controller-only Workbench JAR as exactly one opaque payload at `META-INF/pickleball/workbench/pickleball-workbench.jar`. It must not flatten Workbench/MCP classes into the outer runtime, and the nested Workbench must not contain core. The ownership mnemonic is: **Pickleball may contain Workbench; Workbench must not contain Pickleball.**
+
 ## Build and validation
 
 Use Java 21.
@@ -177,13 +191,34 @@ Framework validation:
 ./gradlew test
 ```
 
+Strict controller/artifact validation:
+
+```shell
+./gradlew verifyStrictControllerIsolation :pickleball-workbench:test
+```
+
 Windows:
 
 ```powershell
 .\gradlew.bat test
 ```
 
-For consumer-visible changes, publish the current framework artifact locally and run the Maven consumer:
+Workbench/control-bridge scenario validation must stay focused:
+
+```shell
+./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test -Dpkb_runvars.pkb_browser=CHROME_HEADLESS -Dpkb_runvars.pkb_parallel=80 -Dpkb_runvars.pkb_tags=@control-bridge
+./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test -Dpkb_runvars.pkb_browser=CHROME_HEADLESS -Dpkb_runvars.pkb_parallel=80 -Dpkb_runvars.pkb_tags=@step-override-bridge
+```
+
+Run the two commands sequentially because both scenarios intentionally exercise the process-global bridge bootstrap.
+
+Or use the focused turnkey validator:
+
+```shell
+scripts/agent_validate.sh --workbench
+```
+
+For broad consumer-visible changes outside the Workbench/controller-isolation surface, publish the current framework artifact locally and run the Maven consumer. The focused Workbench rule above takes precedence for that surface:
 
 ```shell
 ./gradlew test publishToMavenLocal
@@ -227,6 +262,7 @@ If a required validation cannot run, state exactly what was not run and why. Nev
 - Do not edit generated build output.
 - Preserve backward compatibility unless the user explicitly approves a breaking change.
 - Dynamic-control additions must remain opt-in: no handler/API call means normal scenario traversal, ParsingMap construction/order, NodeMap references, resolution, and writes retain their pre-control behavior.
+- Workbench changes must preserve strict physical, dependency, process, and classpath isolation; separate JVMs alone are not sufficient.
 - Follow existing code style and patterns before introducing new abstractions.
 - Do not replace executable examples with prose.
 - Never store secrets, credentials, machine-specific paths, or private data in agent instruction files.
@@ -281,6 +317,7 @@ A functionality change is complete only when:
 - Applicable compatibility has been preserved or a breaking change is clearly identified.
 - Relevant consumer-hosted internal Java checks exist and pass.
 - Relevant consumer scenarios exist and pass when applicable.
+- Workbench/core changes retain the neutral protocol boundary, controller-only artifact scan, opaque nested payload, and consumer-owned worker runtime.
 - Documentation matches the resulting behavior.
 - The feature map remains accurate.
 - The generated repository index is current.

BUNDLE-MANIFEST.txt

@@ -1,10 +1,23 @@
-Pickleball 2.1.3 failure-cluster metadata follow-up
+Pickleball 2.1.9 strict Workbench controller isolation
+Target: branch 2.1.9, commit 9c255431f23a4fa48a3615b387610b3367f476af
+
+APPLY:
+Copy every archive entry over the repository root, preserving folder structure.
+No file deletion is required.
+
+NEW:
+pickleball-control-protocol/**
+src/main/java/tools/dscode/launcher/**
+src/test/java/tools/dscode/launcher/**
+pickleball-workbench/src/main/java/tools/dscode/workbench/WorkbenchRuntimeBoundary.java
+pickleball-workbench/src/test/java/tools/dscode/workbench/WorkbenchRuntimeBoundaryTest.java
 
 REPLACE:
-src/main/aspectj/tools/dscode/common/reporting/diagnostic/Diagnostic213CompletionAspect.aj
-maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/Diagnostic213CompletionChecks.java
-docs/diagnostic-reporting.md
-docs/agent/feature-map.md
+Build graph and isolation verification files
+Worker-side bridge and controller-side protocol client files
+Focused Workbench/control-bridge tests
+Human and AI documentation/infrastructure
+Generated repository index and packaged consumer-guidance mirrors
 
 REFERENCE:
 README-APPLY.md

README-APPLY.md

@@ -1,65 +1,74 @@
-# Pickleball 2.1.3 failure-cluster metadata follow-up
+# Pickleball 2.1.9 strict Workbench controller isolation
 
-This bundle is intended to be copied over the repository after the 2.1.3 site-aware failure-signature fix has already been applied.
+This drop-in targets branch `2.1.9` at commit `9c255431f23a4fa48a3615b387610b3367f476af`.
 
-It keeps the verified V2 clustering behavior and adds the sparse metadata an AI/developer needs to understand why two failures are in different clusters without opening dense event logs.
+Copy the archive contents over the project root, preserving paths. Every included project file is a complete replacement or new file. The bundle intentionally requires no file deletion; the obsolete `gradle/pickleball-published-variant.gradle` is replaced by a migration tombstone so a drag-and-drop overlay cannot retain its old build logic.
 
-## Replacement files
+## Result
 
-- `src/main/aspectj/tools/dscode/common/reporting/diagnostic/Diagnostic213CompletionAspect.aj`
-- `maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/Diagnostic213CompletionChecks.java`
-- `docs/diagnostic-reporting.md`
-- `docs/agent/feature-map.md`
+- `pickleball-control-protocol` is a JDK-only module containing protocol versions, capabilities, transport constants, request/response envelopes, and immutable wire records.
+- `pickleball-workbench` depends only on that protocol plus controller libraries. It no longer resolves, imports, shades, loads, or executes Pickleball core or the behavioral control API.
+- Worker-side bridge server/coordinator/bootstrap and all execution behavior remain in Pickleball and run from the consumer project's captured test runtime in a separate JVM.
+- Protocol connection checks require compatible versions/capabilities, distinct controller/worker PIDs, consumer-classpath runtime origin, synchronized Pickleball version, and no Workbench controller on the worker classpath.
+- The root Pickleball JAR embeds one byte-identical controller-only Workbench JAR as opaque bytes at `META-INF/pickleball/workbench/pickleball-workbench.jar`; Workbench/MCP entries are not flattened into the outer runtime.
+- `PickleballWorkbenchLauncher` extracts the embedded payload atomically by SHA-256 beneath `.pickleball/workbench/controller/` and always launches it with `java -jar` in a separate JVM.
+- Artifact, dependency, POM, nested-JAR/service, controller-classpath, worker-origin, launcher, protocol-client, and focused consumer checks enforce the boundary.
+- Canonical human documentation, repository agent guidance, review rules, generated indexes, packaged consumer guidance, and validation scripts describe the same architecture.
 
-All project files in this bundle are full replacements, not patches.
+The permanent ownership rule is: **Pickleball may contain Workbench; Workbench must not contain Pickleball.**
 
-## Resulting failure metadata
+## Validation performed for this handoff
 
-For a structured step failure, the sparse scenario summary and run index now retain:
+Completed in the bundle workspace:
 
-```json
-{
-  "failureSignature": "...",
-  "failureSignatureVersion": 2,
-  "failureSiteKey": "...",
-  "failureSite": {
-    "feature": "features/diagnostic-reporting-validation.feature",
-    "stepLine": 60,
-    "definition": "tools.dscode.coredefinitions.DynamicSteps#executeDynamicStep"
-  }
-}
-```
-
-`clusters.json` carries the same metadata. `DiagnosticRunComparator` keeps it in compact scenario transitions. `DiagnosticIndexRebuilder` preserves it when rebuilding clusters from surviving scenario summaries.
+- `python3 scripts/verify_agent_contract.py`;
+- `python3 scripts/refresh_agent_index.py --check`;
+- `python3 scripts/sync_consumer_guidance.py --check`;
+- `git diff --check` and `bash -n scripts/agent_validate.sh`;
+- JDK compiler probes for the dependency-free protocol, launcher, controller runtime guard, protocol client, worker lifecycle/live-session seam, shared controller service, UI controller, and focused client/launcher tests (using narrow temporary type stubs where third-party libraries were unavailable);
+- a launcher harness covering content-addressed extraction, corrupted-cache repair, and the separate `java -jar` command; and
+- a controller-boundary harness proving the isolated classpath cannot see Pickleball core.
 
-If no structured step site exists, the previous class/message-only signature is preserved and `failureSignatureVersion` is `1`; no fake site metadata is created.
+The workspace provided Java 17 only and could not resolve the Gradle 9.7 distribution or Maven dependencies through its restricted network. Therefore the Java 21 Gradle build, publication, executable/nested-JAR inspection tasks, Workbench unit suite, and Cucumber scenarios were **not executed here and are not claimed as passing**. Run the focused Java 21 commands below after applying the bundle.
 
-## Validate
+## Focused validation
 
-From the Pickleball repository root:
+Use Java 21 and an environment that can resolve the existing Gradle/Maven dependencies:
 
-```powershell
-.\gradlew.bat test publishToMavenLocal
-python scripts/refresh_agent_index.py --check
-python scripts/verify_agent_contract.py
+```bash
+scripts/agent_validate.sh --workbench
 ```
 
-From `maven-consumer-project`, run the consumer-hosted internal checks:
-
-```powershell
-mvn test -Dpkb_tags="@diagnostic-single"
+Equivalent explicit commands:
+
+```bash
+python3 scripts/verify_agent_contract.py
+python3 scripts/refresh_agent_index.py --check
+python3 scripts/sync_consumer_guidance.py --check
+./gradlew verifyStrictControllerIsolation :pickleball-workbench:test publishToMavenLocal
+./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test \
+  -Dpkb_runvars.pkb_browser=CHROME_HEADLESS \
+  -Dpkb_runvars.pkb_parallel=80 \
+  -Dpkb_runvars.pkb_tags=@control-bridge
+./maven-consumer-project/mvnw -f maven-consumer-project/pom.xml -U test \
+  -Dpkb_runvars.pkb_browser=CHROME_HEADLESS \
+  -Dpkb_runvars.pkb_parallel=80 \
+  -Dpkb_runvars.pkb_tags=@step-override-bridge
 ```
 
-Then rerun the focused cluster scenario set:
+Run the two Maven commands sequentially because both scenarios exercise the process-global bridge bootstrap.
 
-```powershell
-mvn test -Dpkb_tags="@diagnostic-cluster-validation" -Dpkb_reportingmode="diagnostic" -Dpkb_reportretention="all" -Dpkb_browser="CHROME_HEADLESS" -Dpkb_investigation_id="diag-213-cluster-metadata" -Dpkb_run_purpose="failure-signature-metadata"
-```
+Do not use `@all` for this migration.
 
-The cluster-validation Maven command is expected to fail because both scenarios intentionally fail.
+## Consumer launch
 
-For each failed scenario, verify `summary.json` and the corresponding `run-index.json` scenario entry contain `failureSignatureVersion`, `failureSiteKey`, and `failureSite`. Verify each `clusters.json` entry contains the same metadata.
+A Maven consumer can launch the matching embedded controller without locating a cache entry or declaring a second version:
 
-The two intentional failures should still have different `failureSignature` and `failureSiteKey` values.
+```bash
+mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java \
+  -Dexec.mainClass=tools.dscode.launcher.PickleballWorkbenchLauncher \
+  -Dexec.classpathScope=test \
+  "-Dexec.args=ui ."
+```
 
-No IntelliJ Cucumber rerun is required for this follow-up; the internal checks validate canonical Maven/IntelliJ feature-source handling and the sparse metadata/rebuild/comparison behavior.
+See `docs/pickleball-workbench.md` for architecture, commands, lifecycle, MCP stdout rules, and verification details.

README.md

@@ -17,11 +17,12 @@ Pickleball also adds:
 - reusable component scenarios and REST or SOAP service-call scenarios;
 - composable execution profiles through `pkb_profile`, controlled execution input through `pkb_runvars`, and deterministic final RunVar output through `pkb_run_profile`;
 - configurable `pkb_configpath` loading with recommended `<config:...>` references and legacy `<configs...>` compatibility;
+- a dependency-matched Workbench controller embedded as an opaque payload, with all Pickleball execution isolated in a separate consumer worker JVM;
 - optional `pkb_reportingmode=diagnostic` evidence capture with lightweight run/scenario indexes, losslessly compressed deep trace evidence, Git/source provenance, structured step/capability metadata, binary screenshots, compact visual fingerprints, failure clustering, cross-run comparison, and configurable evidence retention; and
 - a small consumer setup consisting primarily of the Pickleball dependency and one test runner.
 
 Pickleball remains compatible with standard Cucumber features such as tags, Scenario Outlines, Examples tables, DataTables, DocStrings, hooks, plugins, and custom Java step definitions. Dynamic Pickleball steps and ordinary project-specific Cucumber steps can be used together in the same suite.
 
 The working [`maven-consumer-project`](docs/consumer-project.md) starts a loopback test server during the run. Its scenarios exercise both Selenium against a local HTML test site and service calls against local REST and SOAP endpoints.
 
-[Read the Pickleball documentation](docs/README.md) · [Consumer project guide](docs/consumer-project.md) · [Execution configuration](docs/configuration.md) · [AI run configuration](docs/ai-run-configuration.md) · [Diagnostic lineage metadata](docs/diagnostic-lineage-metadata.md) · [Diagnostic reporting](docs/diagnostic-reporting.md)
+[Read the Pickleball documentation](docs/README.md) · [Pickleball Workbench](docs/pickleball-workbench.md) · [Consumer project guide](docs/consumer-project.md) · [Execution configuration](docs/configuration.md) · [AI run configuration](docs/ai-run-configuration.md) · [Diagnostic lineage metadata](docs/diagnostic-lineage-metadata.md) · [Diagnostic reporting](docs/diagnostic-reporting.md)