projmux 0.16.0 → 0.16.1

package/docs/testing.md

@@ -5,25 +5,52 @@ and humans run the same entrypoints.
 
 ## Targets
 
-- `make test` runs the fast Go unit suite. These tests avoid tmux, TTY, GUI,
-  and host shell dependencies.
+- `make test` runs the fast Go unit suite. Apart from the real-tmux tests
+  below, these tests avoid tmux, TTY, GUI, and host shell dependencies.
 - `make vet` runs `go vet ./...`. CI runs it in the Unit Tests job after
   `make test`.
+- The real-tmux Go tests in `internal/app` find tmux through one helper,
+  `requireRealTmux`. Without tmux they skip; `PROJMUX_REAL_TMUX_STRICT=1`
+  turns a missing tmux into a test failure instead, so a run that is meant to
+  exercise real tmux cannot pass by skipping. A new real-tmux test must call
+  the helper rather than its own `exec.LookPath("tmux")` skip, and the source
+  audit `TestRealTmuxSkipIsOwnedByOneHelper` fails on any other skip.
+  The CI Unit Tests job installs tmux and runs
+  `PROJMUX_REAL_TMUX_STRICT=1 make test` with a TMPDIR of at least 100 bytes,
+  so a missing tmux there fails the job instead of skipping those tests.
+  The same switch turns on the isolated real-tmux smokes in
+  `internal/integrations/tmux` and `internal/integrations/metadata`, which
+  otherwise wait for their own opt-in variable.
+- A Go test that opens a unix socket must put it under a short root (the
+  `/tmp` + `os.MkdirTemp` idiom, e.g. codexbroker `newRuntimeDomain`,
+  `internal/app` `shortTempDomain`) rather than `t.TempDir()`, because the
+  socket path has a platform bound (Linux 108B, macOS 104B) and the long CI
+  TMPDIR fails such a test. Real-tmux tests put their `TMUX_TMPDIR` or
+  `tmux -S` root under `os.MkdirTemp("/tmp", …)` the same way, and the
+  liveguard private root, which holds a guarded package's `TMUX_TMPDIR` and
+  `XDG_STATE_HOME`, is made under `/tmp` too. Its owner holds a lock file in
+  that root for its whole life, so a later guarded owner reclaims the roots of
+  killed runs, whose lock is free, and leaves roots without that lock file
+  alone.
 - Picker unit coverage includes the backend-neutral item/action contract,
   native title-focused filtering, numeric selection, and shared close actions.
 - `make test-integration` builds `test/docker/Dockerfile` and runs
   `test/integration/linux-smoke.sh` in Docker. It validates Linux dependency
   discovery, tmux config generation/install, app config reload against a real
-  `tmux` server, and notify queue CRUD.
-- `make test-install-smoke` builds the same Docker image and runs
-  `test/install/smoke.sh`. It validates `make install`, atomic binary
-  replacement into an isolated install dir, pre-publication marker convergence,
-  concurrent legacy/candidate/installed shell and attach consumers, exact
-  server-generation/session preservation, `tmux apply`, and post-install notify
-  reconcile initialization with a fresh HOME/XDG state tree.
+  `tmux` server, and notify queue CRUD. It also runs `test/install/smoke.sh`,
+  so the required `Integration Tests` job covers the install smoke.
+- `make test-install-smoke` builds the same Docker image and runs only
+  `test/install/smoke.sh`, as a local entrypoint. It validates `make install`,
+  atomic binary replacement into an isolated install dir, pre-publication
+  marker convergence, concurrent legacy/candidate/installed shell and attach
+  consumers, exact server-generation/session preservation, `tmux apply` into
+  the resolved `$XDG_CONFIG_HOME/projmux/tmux.conf`, and post-install notify
+  reconcile initialization with a fresh HOME/XDG state tree. It ends with a
+  `>> install smoke passed` line. `make verify` does not repeat it, because
+  `make test-integration` already runs it.
 - `make test-e2e` prepares one attempt-local immutable product binary, then
   runs four isolated Linux real-tmux fixtures plus the Codex lifecycle and npm
-  staging fixtures. The required inventory is `L01`-`L19`, `C01`, and `N01`;
+  staging fixtures. The required inventory is `L01`-`L20`, `C01`, and `N01`;
   every fixture has its own HOME/XDG/tmux/socket/evidence roots and every
   consumer records the same binary SHA. `E2E_SCENARIO=<ID>` selects one exact
   stable scenario for replay.
@@ -61,7 +88,7 @@ and humans run the same entrypoints.
   the full product matrix. The shard target also pins the CI job list to the
   manifest. A deterministic fake-runner start/release barrier proves local
   default overlap is one and explicit parallel overlap is four while both use
-  one immutable binary, the exact 21-scenario inventory, and the same result
+  one immutable binary, the exact 22-scenario inventory, and the same result
   hash. The target also pins one non-fail-fast CI job per shard and per suite,
   each with its own runner, timeout, and uniquely named evidence artifacts, all
   of them required children of the aggregate `Test` gate. It also pins the thin
@@ -70,21 +97,34 @@ and humans run the same entrypoints.
   pending rather than failing, so dropping that job would deadlock merges. The
   tag-triggered Release workflow uses the same four Linux shards and two suite
   selectors on separate runners, then reduces them through the fail-closed
-  `Release E2E Tests` aggregate before `Build Release` starts.
+  `Release E2E Tests` aggregate before `Build Release` starts. `make test`
+  runs `make test-e2e-shards`, so the required Unit Tests job fails on shard
+  contract drift. The live dialogue canary's own contract is
+  `test/agent_dialogue_canary_test.py`, not this target.
+- `make test` also runs the evidence contract (`make e2e-evidence-contract`),
+  `make test-e2e-reliability`, and `make test-e2e-residual-policy`, so the
+  required Unit Tests job fails when any of them does. `make test-e2e-contract`
+  is a local entry point for the admission and evidence halves, both of which
+  `make test` already runs. The reliability contract removes the artifact
+  directory it creates on every exit, and keeps one the caller passes in
+  `PROJMUX_E2E_ARTIFACTS`.
 - `make test-e2e-coverage` validates
   `test/e2e/ags-oedr-manifest.json`: executable scenario markers and shard
-  assignments must match all 21 rows with orphan count zero. A matrix may move
+  assignments must match all 22 rows with orphan count zero. A matrix may move
   out of real-tmux E2E only when its checked-in entry names executable lower
   positive, negative, and fixed-point evidence and retains a real-boundary
   sentinel. The manifest/orphan half is a prerequisite of `make test-e2e`,
   while the referenced lower test runs in both this coverage target and the
-  required unit-test job.
+  required unit-test job, so `make test-e2e-coverage` is a local entry point
+  whose two halves are already enforced.
 - `make security` runs the exact three Security groups in parallel locally:
   Go vulnerability/security, Go static quality, and repository policy.
   `make security-serial` is the parity control and `make security-contract`
-  checks scanner/rule/baseline identity, PR-range/full-history secret scans,
+  checks scanner/rule/baseline identity, PR-range and HEAD-history secret scans,
   cache miss-to-hit convergence, privacy-safe artifacts, and the fail-closed
   aggregate. CI exposes their stable aggregate as `Test`.
+  After adding or removing a Go package, refresh the package-set pin with
+  `make security-pin-refresh` (rule: `AGENTS.md` `## Security`).
 - `make deadcode` runs the focused baseline-contract fixture, then runs
   `go tool deadcode` (pinned via the go.mod tool directive) over the module.
   `.deadcode-allowlist.txt` is exact to current findings: duplicate and stale
@@ -156,7 +196,7 @@ remains inside L17. Its row links creator-Registry admission, journal-path and
 CLOEXEC handshake tests to the immediate-exit integration/E2E markers, and
 also closes the focused fresh-root repeat harness plus the read-only
 owner/queue observation and product-terminal controller marker. These rows add
-no scenario ID: the audit still requires exactly 21 stable scenarios and fails
+no scenario ID: the audit still requires exactly 22 stable scenarios and fails
 closed if either source commit, guarantee set, lower selector, supporting
 marker, or marker-before-pass edge drifts.
 
@@ -168,6 +208,15 @@ value for an explicitly observed cancellation; the shell harness does not
 invent cancellation evidence from a signal whose semantic cause it cannot
 attribute.
 
+`smoke_contract_pass` records `pass` only when the contract shell's own stdout
+and stderr between `smoke_contract_begin` and that call carry no Python
+traceback, even one whose child status was consumed. A traceback ends the
+scenario through the ordinary fail path at the pass line and logs
+`E2E_CONTRACT id=<ID> guard=python-traceback stream=<stream> exception=<last
+exception line>`; there is no exemption list. Output redirected to a file never
+reaches the guard. `make e2e-traceback-guard-contract` pins this, including a
+traceback written while the job log lags behind the pass call.
+
 ## Host-Only Checks
 
 The Docker suites do not replace checks that depend on a real host terminal,
@@ -298,8 +347,9 @@ Observe:
 ```markdown
 Host-only smoke validation:
 
-- Docker-covered checks: `make test-integration`, `make test-install-smoke`,
-  and `make test-e2e` cover portable Linux tmux/config/notify behavior only.
+- Docker-covered checks: `make test-integration` (which includes the install
+  smoke) and `make test-e2e` cover portable Linux tmux/config/notify behavior
+  only.
 - Terminal key delivery: not run / run on <terminal>; `projmux setup --timeout
   10s` showed <result>; `Alt-1..5` app popup smoke <passed/failed/not run>.
 - WSL toast: not run / run on <Windows + WSL distro>; detached-focus smoke

package/docs/theme-palette.md

@@ -9,11 +9,11 @@ semantic role map is `internal/theme/resolve.go`.
 ## Scope
 
 The fallback palette is a semantic token layer. The effective theme is a global
-user theme resolved from `~/.config/projmux/config.toml`, followed by the
-built-in fallback values from `internal/theme/palette.go`. The resolver derives
-a semantic role map (`RenderRoles` for tmux chrome, `ANSIRoles` for native ANSI
-surfaces) from the effective theme, and renderers consume those roles instead of
-bare palette literals.
+user theme resolved from `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml`,
+followed by the built-in fallback values from `internal/theme/palette.go`. The
+resolver derives a semantic role map (`RenderRoles` for tmux chrome, `ANSIRoles`
+for native ANSI surfaces) from the effective theme, and renderers consume those
+roles instead of bare palette literals.
 
 - Native picker truecolor SGR tokens.
 - Native sidebar and chip-strip 256-color SGR tokens.
@@ -124,7 +124,7 @@ Rules:
 
 The effective theme resolves theme fields from:
 
-1. Global `~/.config/projmux/config.toml`
+1. Global `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml`
 2. Built-in fallback preset `projmux`
 
 Rules:

package/docs/tmux-surface-inventory.md

@@ -10,6 +10,7 @@ Primary production sources:
 
 - `internal/integrations/mux/`
 - `internal/integrations/tmux/`
+- `internal/integrations/tmuxexec/`
 - `internal/app/`
 - generated config from `projmux config render standalone`,
   `projmux config render app`, and `projmux shell`
@@ -44,6 +45,18 @@ The boundary is intentionally pragmatic:
 - avoid spreading raw tmux invocation through app packages;
 - avoid introducing an abstraction that only renames a single local call.
 
+Every process projmux starts that may be a tmux command client is started
+through `internal/integrations/tmuxexec`. It adds tmux's `-u` client flag, so
+format output keeps its `\x1f` and `\t` separators and UTF-8 values when the
+caller has no UTF-8 locale (no `LANG`/`LC_*`, or `LC_ALL=C`); without it tmux
+rewrites those bytes to `_`. Clients that take over a terminal
+(`attach-session`, a `new-session` that is not detached) are left as they are.
+`TestTmuxSpawnSitesAreClosed` checks every package whose source holds the
+literal `"tmux"` or that imports a tmux integration package: each process spawn
+there must use that package or be on its closed list of spawns that never run
+tmux. A spawn of the literal `"tmux"` fails in any package. A package that runs
+tmux with neither the literal nor such an import is not checked.
+
 ## Semantic Command Surface
 
 ### Metadata And Inventory

package/docs/upgrading.md

@@ -61,9 +61,9 @@ With nothing left to choose, the setting that turned the screen off is gone.
 
 - Settings > Projects > Project Sidebar > Closed Project startup is removed.
   Project Sidebar keeps its Runtime diagnostics choice.
-- `~/.config/projmux/sidebar-startup-picker` is no longer read. The first
-  `projmux config apply` after upgrading (which `make install` and
-  `projmux update apply` also run) removes it and prints one
+- `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker` is no
+  longer read. The first `projmux config apply` after upgrading (which
+  `make install` and `projmux update apply` also run) removes it and prints one
   `reclaimed retired closed-Project startup setting: removed 1 file` line.
   Only a regular file with that name is removed; a failure is reported and
   never fails the apply, and later applies print nothing.
@@ -105,9 +105,9 @@ projmux no longer installs, reads, or judges the Antigravity `statusLine` in
   prints the `usage unsupported` note; `agent capabilities` reports Antigravity
   usage as unsupported. Working state still follows the official
   `PreInvocation`/`Stop` hooks.
-- Leftover `~/.config/projmux/statusbar-visibility-*antigravity*` files,
-  `<state>/usage/antigravity-*.json` sidecars, and cached Antigravity rows in
-  `snapshots.json` are ignored, not deleted. Doctor JSON no longer has
+- Leftover `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-visibility-*antigravity*`
+  files, `<state>/usage/antigravity-*.json` sidecars, and cached Antigravity
+  rows in `snapshots.json` are ignored, not deleted. Doctor JSON no longer has
   `statusline_config_path`, and the diagnostic is named `Antigravity hooks`.
 
 ### Project snapshots removed
@@ -419,8 +419,9 @@ projmux get projects
 
 ### Pins are typed, and migrate on request
 
-**Breaking.** `~/.config/projmux/pins` held one absolute path per line, which
-could not say whether the path was a Project. It is now a typed envelope:
+**Breaking.** `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/pins` held one absolute
+path per line, which could not say whether the path was a Project. It is now a
+typed envelope:
 
 ```text
 projmux-pins v2
@@ -586,12 +587,12 @@ The deprecated top-level `projmux init` command and its legacy-only
 
 ### Keymap schema migration
 
-`~/.config/projmux/keymap.toml` is now versioned by a root `schema_version`
-marker. A file without one is v0 and uses the action ids projmux has always
-written; `schema_version = 1` uses canonical dotted ids such as
-`window.create` and `project-sidebar.runtime.stop`; `schema_version = 2` keeps
-those ids and adds two-to-four-stroke `sequences`. All versions read — the v0
-spelling of every action stays a permanent read alias.
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml` is now versioned by a
+root `schema_version` marker. A file without one is v0 and uses the action ids
+projmux has always written; `schema_version = 1` uses canonical dotted ids such
+as `window.create` and `project-sidebar.runtime.stop`; `schema_version = 2`
+keeps those ids and adds two-to-four-stroke `sequences`. All versions read — the
+v0 spelling of every action stays a permanent read alias.
 
 The migration needs no command of its own. Every installer path ends by running
 the newly installed binary's `projmux config apply`, which migrates first and only
@@ -616,7 +617,7 @@ fail before the keymap, generated config, or live server changes.
 **Downgrading to a projmux that predates the schema:** restore the backup first.
 
 ```sh
-cp ~/.config/projmux/keymap.toml.pre-v1-<digest>.bak ~/.config/projmux/keymap.toml
+cp "${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml.pre-v1-<digest>.bak" "${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml"
 ```
 
 An older binary reads `schema_version` as an unsupported root key and refuses
@@ -627,7 +628,7 @@ full ordering.
 ### Pane rename keymap action ID removed
 
 The deprecated `rename-pane-topic` keybinding action ID has been removed. If
-`~/.config/projmux/keymap.toml` still contains
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml` still contains
 `[bindings.rename-pane-topic]`, rename that table to
 `[bindings.rename-pane-label]` before running Settings or
 `projmux config apply`. Projmux now rejects the stale table with that exact
@@ -641,7 +642,8 @@ independent fallback.
 ### Theme is now global-only
 
 Theme is a global user preference. The effective theme resolves from the global
-`[theme]` in `~/.config/projmux/config.toml` plus a built-in fallback preset.
+`[theme]` in `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml` plus a
+built-in fallback preset.
 
 If you previously set a `[theme]` section in a project's `.projmux/config.toml`,
 it is now **deprecated and ignored** — it no longer overrides the global theme
@@ -650,11 +652,11 @@ The project `[theme]` keys are left in the file untouched (no warning, no
 removal); they simply have no effect.
 
 To restore your previous look, copy the values into the global
-`~/.config/projmux/config.toml` `[theme]` section, or edit them through
-Settings > Theme. Settings no longer exposes a Project theme editor, and the
-separate Effective theme view has been merged into the Global theme view: each
-token row now shows its resolved value inline, with unset tokens shown as their
-dimmed `(fallback)` value.
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/config.toml` `[theme]` section, or
+edit them through Settings > Theme. Settings no longer exposes a Project theme
+editor, and the separate Effective theme view has been merged into the Global
+theme view: each token row now shows its resolved value inline, with unset
+tokens shown as their dimmed `(fallback)` value.
 
 ### Foreground split
 
@@ -780,7 +782,7 @@ apply refuses and names the path it found — the active executable is left
 untouched. The scratch directory is removed on success and on every failure.
 
 The command reads `PROJMUX_PROJDIR` from the calling shell and memoizes the
-primary path to `~/.config/projmux/projdir`, so the new binary keeps the same
+primary path to `$HOME/.config/projmux/projdir`, so the new binary keeps the same
 project root context as the one it replaces.
 
 To switch the saved project root during the upgrade:

package/docs/usage-tracking.md

@@ -147,6 +147,17 @@ JSON document keyed by adapter, recording:
 - per-adapter `last_collect` timestamp (drives the throttle)
 - per-adapter `Backoff{Until, Consecutive}` (drives the cooldown)
 
+A persistent `.snapshots.json.lock` next to the file serializes every
+read-modify-write across the processes on one machine. The lock is never held
+during an adapter call. Instead, a throttled refresh records `last_collect`
+for the adapters it is about to walk before it calls them, so concurrent
+refreshes collect each adapter once per throttle window. A refresh that cannot
+take the lock within one second walks nothing and fails with a lock-timeout
+error, which the operations journal records as `failure=state-lock-timeout`
+(see [Collection failures](#collection-failures)). A healthy wait takes milliseconds,
+so repeated rows point at a stuck lock holder. The lock does not coordinate
+machines that share a synced directory.
+
 Adapter failures merge over the prior slice rather than replacing it,
 so a 429 keeps the last known good rows visible. A *partial* collect — some
 rows dropped, some kept — still counts as a successful refresh for the models
@@ -334,7 +345,11 @@ When a collection fails, the failure is visible in three places:
    Codex failure. Status codes, paths, upstream bodies, and
    credentials never reach the row. Codex rollout fallback records
    `source=rollout` plus its closed fallback reason; retained data records
-   `source=last-known-good` plus its closed stale reason. A healthy native
+   `source=last-known-good` plus its closed stale reason. A refresh that timed
+   out on the snapshot state lock records one `provider=projmux`
+   `failure=state-lock-timeout` row at `level=error`, without a source: no
+   adapter ran, so no provider owns it, and adapter failures that came with
+   the timeout keep their own rows. A healthy native
    collection writes no row at all. Identical `(provider, source, failure)`
    tuples are recorded at most once per
    process run — the same suppression the notify/focus recorder uses — so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.16.0",
-    "@projmux/linux-arm64": "0.16.0",
-    "@projmux/darwin-x64": "0.16.0",
-    "@projmux/darwin-arm64": "0.16.0"
+    "@projmux/linux-x64": "0.16.1",
+    "@projmux/linux-arm64": "0.16.1",
+    "@projmux/darwin-x64": "0.16.1",
+    "@projmux/darwin-arm64": "0.16.1"
   }
 }