Make control mode, queries, and workspaces deterministic

.github/CONTRIBUTING.md

@@ -25,12 +25,43 @@ from `global-json-file` and calls `dotnet` directly, so a workflow file never
 carries the prefix.
 
 The validators are Python and run through [uv](https://docs.astral.sh/uv/).
-There is no Python project file — each script carries its own PEP 723 header.
+There is no Python project file — each script carries its own PEP 723 header,
+and a script with dependencies carries a `.lock` beside it so the gate resolves
+the same versions every run:
+
+```console
+$ uv lock --script eng/run_tests.py
+```
+
+Run the engineering tests through that locked runner rather than naming pytest
+on the command line, which resolves whatever released that morning:
+
+```console
+$ uv run --locked --script eng/run_tests.py
+```
+
+Nine of those tests read a pinned revision of the Python library. Point
+`LIBTMUX_PYTHON_REPOSITORY` at a checkout of
+[tmux-python/libtmux](https://github.com/tmux-python/libtmux) that contains it,
+or they fail saying which revision they wanted.
 
 You also need a real `tmux`, version 3.2a or newer. The suite drives one
 rather than mocking it, because this library's job is being right about tmux
 and only tmux can say whether it is.
 
+Name that tmux explicitly when the machine has more than one:
+
+```console
+$ export LIBTMUX_TMUX=/usr/local/bin/tmux
+```
+
+Without it the tests spawn whatever `tmux` their own `PATH` resolves, while a
+command they send into a pane resolves it again through that pane's
+interactive shell. A version-matrix install earlier on the interactive `PATH`
+makes those two different binaries, and a client cannot talk to a server of
+another version. What you see is `tmux_run` timing out with no exit status,
+which reads as a library bug rather than as two tmuxes.
+
 ## Own your tmux socket root
 
 Give this repository a socket root of its own before running anything:
@@ -141,6 +172,12 @@ $ mise exec -- dotnet pack \
 $ uv run python eng/parity/inspect_packages.py
 ```
 
+```console
+$ mise exec -- dotnet restore \
+    tests/LibTmux.PackageConsumer/LibTmux.PackageConsumer.csproj \
+    --configfile tests/NuGet.config
+```
+
 ```console
 $ mise exec -- dotnet run \
     --project tests/LibTmux.PackageConsumer/LibTmux.PackageConsumer.csproj \
@@ -149,27 +186,40 @@ $ mise exec -- dotnet run \
     --no-restore
 ```
 
+```console
+$ mise exec -- dotnet restore \
+    tests/LibTmux.AotSmoke/LibTmux.AotSmoke.csproj \
+    --runtime linux-x64 \
+    --configfile tests/NuGet.config
+```
+
 ```console
 $ mise exec -- dotnet publish \
     tests/LibTmux.AotSmoke/LibTmux.AotSmoke.csproj \
     --configuration Release \
     --framework net10.0 \
-    --runtime linux-x64
+    --runtime linux-x64 \
+    --no-restore
 ```
 
-`LibTmux.PackageConsumer` is deliberately absent from `LibTmux.slnx`. It exists
-to prove the packaged artifact rather than a project reference, so it restores
-and runs standalone.
+`LibTmux.PackageConsumer` and `LibTmux.AotSmoke` are deliberately absent from
+`LibTmux.slnx`. Both restore the packed artifacts rather than project
+references, so they run only after `dotnet pack`.
 
 ### Validators that read documents, not the build
 
-Five checks run against documents rather than code, which is what makes them
-easy to forget locally:
+Eight checks run against documents rather than code, which is what makes them
+easy to forget locally. They are listed here in the order
+[`dotnet.yml`](workflows/dotnet.yml) runs them:
 
 ```console
 $ uv run python eng/parity/verify_public_api.py
 ```
 
+```console
+$ uv run python eng/parity/render_public_api.py --check
+```
+
 ```console
 $ uv run python eng/parity/verify_capabilities.py
 ```
@@ -178,6 +228,14 @@ $ uv run python eng/parity/verify_capabilities.py
 $ uv run python eng/parity/verify_workflows.py
 ```
 
+```console
+$ uv run python eng/parity/verify_tmux_versions.py
+```
+
+```console
+$ uv run python eng/docs/render_api_reference.py --check
+```
+
 ```console
 $ uv run python eng/docs/sync_snippets.py --check
 ```
@@ -186,6 +244,15 @@ $ uv run python eng/docs/sync_snippets.py --check
 $ uv run eng/mcp/dump_tools.py --check
 ```
 
+The two renderers hold `docs/api/README.md` and `docs/public-api.md` to the
+documents they are generated from. Adding a public member without recording it
+fails `render_api_reference.py --check` and nothing before it, so run the whole
+list rather than the first few.
+
+`render_api_reference.py` reads the XML documentation the compiler emitted, so
+build before running it. Against stale output it reports a difference that is
+not there.
+
 `sync_snippets.py --check` is the one that catches a hand-edited example. It
 compares each published block against the region it was quoted from and fails
 on any difference, so bring a change across rather than typing it into the
@@ -208,23 +275,31 @@ The engineering scripts have tests of their own:
 $ uv run --with pytest --with tomlkit python -m pytest eng --quiet
 ```
 
-### NU1004, which is not a dependency problem
+### AOT restore ownership
 
-Publishing ahead of time names a runtime identifier, and restore then writes
-one into the lock file of every project in that graph — including the
-library's, where the section is empty because no package resolves differently.
-That is why `src/LibTmux` and `src/LibTmux.Generators` declare
-`RuntimeIdentifiers`: without it the lock files disagree with the projects and
-the *next* `restore --locked-mode` fails with NU1004, which reads like a
-dependency problem and is not one.
+Only `LibTmux.AotSmoke` names a runtime identifier. The libraries and their
+lock files stay portable because the smoke project consumes their packages
+instead of adding its runtime to their project graph. The smoke project has no
+checked-in lock: its package inputs keep the development version while their
+bytes change with each commit. CI combines a clean package cache with
+`tests/NuGet.config` source mapping so it cannot substitute a stale or public
+package.
 
-Adding a platform to the matrix means adding its identifier there and
-regenerating:
+A local machine has neither. The version never changes between packs, so a
+restore prefers whatever `0.0.0-alpha.9` the global cache already holds and the
+freshly packed bytes are ignored. Evict them before running either gate:
 
 ```console
-$ mise exec -- dotnet restore LibTmux.slnx --force-evaluate
+$ rm -rf ~/.nuget/packages/libtmux{,.query.json,.workspace}/0.0.0-alpha.9
 ```
 
+Skipping that runs last week's library against this week's dependants, which
+surfaces as a `TypeLoadException` naming an internal type rather than as
+anything that looks like a stale package.
+
+Adding a platform means adding its identifier to `LibTmux.AotSmoke` and adding
+the matching standalone restore and publish to the workflow.
+
 ### The other workflows
 
 [`dotnet-tmux.yml`](workflows/dotnet-tmux.yml) builds each supported tmux from
@@ -292,16 +367,26 @@ either of those changes what a user sees on their own screen.
 **A behaviour change needs a test against a real tmux.** This library's job is
 being right about tmux, and only tmux can say whether it is.
 
+**A new tmux version starts in the manifest.**
+[`eng/tmux/versions.json`](../eng/tmux/versions.json) decides which versions
+this repository supports. The workflow matrix, both build scripts, the runtime
+constants and every README repeat that list, and
+`eng/parity/verify_tmux_versions.py` names each one that has not caught up:
+
+```console
+$ uv run python eng/parity/verify_tmux_versions.py
+```
+
 **A version-dependent behaviour needs a row in the ledger.** Anything that
-differs between 3.2a and 3.7b goes through the capability model, and each
+differs between 3.2a and 3.7c goes through the capability model, and each
 difference names the test that proves it in
 [`docs/parity/version-deltas.json`](../docs/parity/version-deltas.json).
 
-**A public API addition needs five edits, and each will tell you.** The Roslyn
-analyzer baseline (`PublicAPI.Unshipped.txt`), the type and its members in
-`docs/public-api.json`, its values if it is an enum, and its owning component
-in `eng/parity/verify_production_plan.py`. They fail independently and by name;
-follow the errors.
+**A public API addition changes both enforced contracts.** Update the Roslyn
+analyzer baseline (`PublicAPI.Unshipped.txt`) and the type and member records in
+`docs/public-api.json`, including explicit enum values. If the addition maps a
+Python symbol, update its row in `docs/parity/parity-ledger.json`. The validators
+report each missing contract independently.
 
 **A documented example is compiled, and a `csharp run` block is executed
 against a live tmux.** `ReadmeExampleTests` compiles every C# block in the
@@ -470,13 +555,17 @@ $ uv run python eng/parity/reconcile_versions.py \
 
 Commit the bundle and the rewritten `version-deltas.json` together, because the
 fingerprint is of the tree that commit produces. A tmux build takes about forty
-seconds here and the matrix runs the suite fourteen times, so budget half an
+seconds here and the matrix runs the suite sixteen times, so budget half an
 hour.
 
 ## Compatibility
 
-tmux **3.2a through 3.7b**, on **net8.0** and **net10.0**, on Linux and macOS.
-Windows is unsupported. The packages are trim- and ahead-of-time-safe.
+Stable tmux **3.2a and newer**, on **net8.0** and **net10.0**. The required
+Linux matrix covers 3.2a through 3.7c; the advisory macOS lane uses the current
+Homebrew tmux. Windows is unsupported. The `LibTmux` core package is trim- and
+ahead-of-time-analyzer gated and has a Linux NativeAOT execution smoke test.
+Optional packages make narrower compatibility claims in their project files
+and package READMEs.
 
 During alpha the public API can change in any release with no deprecation
 period, so a consumer pins an exact version. Widening the supported range means

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -20,7 +20,7 @@ body:
     attributes:
       label: tmux version
       description: The output of `tmux -V`.
-      placeholder: tmux 3.7b
+      placeholder: tmux 3.7c
     validations:
       required: true
   - type: dropdown

.github/workflows/dotnet-tmux.yml

@@ -34,7 +34,7 @@ jobs:
       # readable when the other lanes still run.
       fail-fast: false
       matrix:
-        tmux: ['3.2a', '3.3a', '3.4', '3.5', '3.6', '3.7a', '3.7b']
+        tmux: ['3.2a', '3.3a', '3.4', '3.5', '3.6', '3.7a', '3.7b', '3.7c']
         framework: ['net8.0', 'net10.0']
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/dotnet.yml

@@ -84,8 +84,11 @@ jobs:
         # Reaching the library through the package is the point: a missing
         # assembly or a wrong target framework is invisible from inside the
         # repository.
+        env:
+          NUGET_PACKAGES: ${{ runner.temp }}/libtmux-package-consumer
         run: |
-          dotnet restore tests/LibTmux.PackageConsumer/LibTmux.PackageConsumer.csproj
+          dotnet restore tests/LibTmux.PackageConsumer/LibTmux.PackageConsumer.csproj \
+            --configfile tests/NuGet.config
           for framework in net8.0 net10.0; do
             dotnet run \
               --project tests/LibTmux.PackageConsumer/LibTmux.PackageConsumer.csproj \
@@ -96,16 +99,21 @@ jobs:
 
       - name: Ahead-of-time smoke test
         # Trim and ahead-of-time warnings are only complete once something is
-        # published that way and run. This publishes where the closure tests
-        # below look for it, which is the default location rather than one
-        # this job picked.
+        # published that way and run. The isolated cache and mapped source make
+        # this a test of the packages above rather than the project graph.
+        env:
+          NUGET_PACKAGES: ${{ runner.temp }}/libtmux-aot-smoke
         run: |
           sudo apt-get install --yes clang zlib1g-dev
+          dotnet restore tests/LibTmux.AotSmoke/LibTmux.AotSmoke.csproj \
+            --runtime linux-x64 \
+            --configfile tests/NuGet.config
           for framework in net8.0 net10.0; do
             dotnet publish tests/LibTmux.AotSmoke/LibTmux.AotSmoke.csproj \
               --configuration Release \
               --framework "${framework}" \
-              --runtime linux-x64
+              --runtime linux-x64 \
+              --no-restore
             "tests/LibTmux.AotSmoke/bin/Release/${framework}/linux-x64/native/LibTmux.AotSmoke"
           done
 
@@ -155,6 +163,7 @@ jobs:
           uv run python eng/parity/render_public_api.py --check
           uv run python eng/parity/verify_capabilities.py
           uv run python eng/parity/verify_workflows.py
+          uv run python eng/parity/verify_tmux_versions.py
           uv run python eng/docs/render_api_reference.py --check
           uv run python eng/docs/sync_snippets.py --check
           uv run eng/mcp/dump_tools.py --check
@@ -168,10 +177,11 @@ jobs:
       - name: Engineering tests
         env:
           LIBTMUX_PYTHON_REPOSITORY: ${{ runner.temp }}/python-libtmux
-        # tomlkit is what mcp_swap edits Codex and Grok configs with, so its
-        # tests need it too. There is no Python project file here to declare
-        # it in — the scripts carry their own PEP 723 headers.
-        run: uv run --with pytest --with tomlkit python -m pytest eng --quiet
+        # Naming pytest and tomlkit on the command line resolved whatever
+        # released that morning, so an unrelated release could turn this red.
+        # The runner declares them in its own PEP 723 header and pins them in
+        # the lock beside it; --locked refuses to run against a stale one.
+        run: uv run --locked --script eng/run_tests.py --quiet
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         # A run that failed before packing has nothing to upload, and saying so
@@ -203,12 +213,8 @@ jobs:
           tmux -V
 
       - name: Restore
-        # Locked mode is off here, and omitting --locked-mode is not enough to
-        # do that: Directory.Build.props turns RestoreLockedMode on whenever CI
-        # is set. The lock files are generated for the Linux runtime identifier
-        # this repository publishes ahead of time, so a macOS restore resolves
-        # osx-arm64 and NU1004s against them -- which is the lock files being
-        # right about Linux, not a dependency problem.
+        # Directory.Build.props enables locked mode in CI. This advisory macOS
+        # lane opts out; the required Linux lanes remain the lock-file gate.
         run: dotnet restore LibTmux.slnx -p:RestoreLockedMode=false
 
       - name: Build