projmux 0.16.0 → 0.16.1

package/docs/keybindings.md

@@ -233,8 +233,12 @@ per-launch model or effort row.
 
 `window.create` (v0 id `new-window`) and the Window menu's New At End decide the
 new Window's first Pane before the Window exists, following the saved launch
-default -- the same setting the saved-default split key reads (Settings > AI
-Settings, stored in `$XDG_CONFIG_HOME/projmux/tmux-ai-split-mode`). The order is:
+default. That default is the TUI file
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/tmux-ai-split-mode` (Settings > AI
+Settings, the same setting the saved-default split key reads) when it holds a
+valid mode, then the central `ai-new-window-mode`, then `selective`; see
+[New AI Window Default](configuration.md#new-ai-window-default). The create
+then runs in this order:
 
 1. Ask. A picker mode opens its picker on the Pane the key was pressed in; a
    provider mode and `shell` are already the answer and open nothing.
@@ -249,7 +253,7 @@ The client therefore never sees a shell Pane that is about to be replaced.
 | --- | --- |
 | `shell` | the shell Pane the create made; nothing else runs |
 | `claude`, `codex`, `antigravity` | exactly that Agent Pane, with no picker |
-| `selective` (also the unset default) | whatever the `Alt-7` picker chose: that Agent Pane, or the shell Pane for the shell row; its `resume` row opens the resume session list in the same popup |
+| `selective` (also the default when neither `tmux-ai-split-mode` nor `ai-new-window-mode` holds a valid mode) | whatever the `Alt-7` picker chose: that Agent Pane, or the shell Pane for the shell row; its `resume` row opens the resume session list in the same popup |
 | `resume` | whatever the resume picker chose, on the same terms |
 
 Cancelling the picker creates nothing: no Window, and the client stays where it
@@ -605,14 +609,14 @@ still required before ordinary mutation.
 To roll v2 back to the immediately previous v1 file, restore its pre-v2 backup:
 
 ```sh
-cp ~/.config/projmux/keymap.toml.pre-v2-<digest>.bak ~/.config/projmux/keymap.toml
+cp "${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml.pre-v2-<digest>.bak" "${XDG_CONFIG_HOME:-$HOME/.config}/projmux/keymap.toml"
 ```
 
 For a keymap that entered migration as v0, restore the established pre-v1
 backup **before** installing a projmux that predates versioned keymaps:
 
 ```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"
 ```
 
 A projmux that predates this schema reads `schema_version` as an unsupported

package/docs/npm-distribution.md

@@ -14,6 +14,10 @@ this package layout:
 | `@projmux/darwin-x64` | `darwin/amd64` `bin/projmux` |
 | `@projmux/darwin-arm64` | `darwin/arm64` `bin/projmux` |
 
+Each platform package also carries `THIRD_PARTY_NOTICES`, the license notices
+of the Go runtime and the Go modules its binary links. The root package has no
+binary and no notices.
+
 The shim sets `PROJMUX_INSTALLER=npm` before executing the real binary so
 `projmux update status` and the Settings About screen can present
 npm-specific guidance. npm is only an update/install source label here; the

package/docs/operational-diagnostics.md

@@ -16,8 +16,15 @@ no generic metadata map. Runtime lifecycle records add only closed
 attach, switch, kill, and config apply; codes are stable failure/health
 classifications and never carry routing identity or subprocess details.
 
-Command and subcommand names come from static allowlists. Unknown argv values,
-paths, flags, and arguments are dropped. Messages have control/format
+Command and subcommand names come from static allowlists. The allowlist covers
+every route of the CLI route graph, `internal <namespace>` included, and its
+direct child subcommand; a sweep test over the graph enforces this. Routes
+covered only for this purpose gain error attribution: whether a success is
+recorded still follows the state-changing rules below. An alias records the
+canonical child name (`get project` records `get projects`). Unknown argv stays
+unnamed, and argv values, paths, flags, and arguments are dropped. A log written
+by a newer binary may carry names an older reader does not know; that reader
+skips those lines. Messages have control/format
 characters removed, whitespace normalized, the current home path abbreviated
 to `~`, and length capped at 512 Unicode code points. Top-level outcomes never
 copy `error.Error()` into the journal: their message is one of three stable,
@@ -36,6 +43,59 @@ operation instead of recording nested outcomes. Lifecycle ownership replaces
 the generic top-level `command.outcome`; it never duplicates it. Start/outcome
 append failures are ignored and do not change the command result.
 
+The `lifecycle.outcome` of `operation=tmux.apply` (`config apply` and the
+hidden `internal tmux apply`) also carries a step and Registry lock
+breakdown. It is measurement only: the apply's steps, their order, its
+stdout, stderr, exit status, rollback, and every lock boundary are exactly
+as without it. The record is appended after the apply route returned, so
+after every Registry lock it took was released, and a journal failure
+changes nothing about the apply. Only closed names and integers are added;
+every other event family, including `lifecycle.outcome` of any other
+operation and `lifecycle.start`, rejects each of these fields.
+
+- One `step_<name>_ms` field per apply step the apply entered, in order:
+  `step_keymap_migration_ms` (keymap migration),
+  `step_hook_file_migration_ms` (managed agent hook file migration),
+  `step_retired_file_reclaim_ms` (retired snapshot, Codex generation, and
+  sidebar startup file reclaim and the status bar default seed),
+  `step_route_bind_ms` (binding to the exact live app server),
+  `step_bell_hook_migration_ms` (managed tmux bell hook migration),
+  `step_config_write_ms` (writing the generated config),
+  `step_key_sequence_retire_ms` (retiring recorded key sequence state),
+  `step_source_file_ms` (the route guard and `source-file`),
+  `step_route_marker_ms` (the logical socket marker),
+  `step_exhausted_replay_ms` (replaying retry-exhausted clean exits), and
+  `step_converge_ms` (the controller convergence). A step the apply did not
+  enter -- `--no-reload`, no live server, or an earlier failure -- is absent.
+  Steps are measured on the same clock as `duration_ms`, start no earlier
+  than it, and do not overlap; each opens where the previous one closes, so
+  the few statements between two steps count toward the earlier one. Each is
+  rounded down to whole milliseconds, and `sum(step ms) <= duration_ms`
+  always holds on disk: a step set that would exceed it is dropped whole.
+- `lock_acquisition_count`, `lock_wait_total_ms`, and `lock_held_total_ms`
+  total every Registry lock acquisition the apply made while it ran, whatever
+  site made it, with the wait and hold the Registry Store measured for
+  `registry.lock.acquisition`. They are present whenever the breakdown is,
+  and zero when the apply took no lock.
+- `longest_lock_kind`, `longest_lock_step`, `longest_lock_wait_ms`, and
+  `longest_lock_held_ms` describe the one released acquisition that held the
+  lock longest. The kind is the Registry transaction it belonged to:
+  `preexisting-dead-agent`, `control-targets`, `mirror-recovery`,
+  `binding-converge`, `lifecycle-reconcile`, `session-lower`, or `other` for
+  an acquisition no site named. The step is the apply step it ran in, or
+  `other` outside every step. All four are absent when no acquisition held
+  the lock, and the longest wait and hold never exceed the totals.
+- `longest_lock_observe_ms`, `longest_lock_plan_ms`, `longest_lock_commit_ms`,
+  and `longest_lock_store_write_ms` split that hold: live tmux reads and
+  their classification, plan and reconcile computation, Registry and tmux
+  writes inside the transaction, and from the transaction's callback
+  returning to the release being observed (normalize, validate, the durable
+  write, the unlock). A phase the transaction did not mark is absent, and the
+  grant and the Store's locked read before the first mark are left
+  unattributed. `sum(phase ms) <= longest_lock_held_ms` always holds on disk:
+  a breakdown that would exceed the hold is dropped whole and the rest of the
+  longest lock is kept.
+
 Project lifecycle operator diagnostics also keep plans mutually exclusive:
 `stop`, `close-window`, `delete-project`, and `fresh` are distinct operation
 classes. Startup and unregister failures print the closed action, failing
@@ -66,10 +126,11 @@ and the UI new Window, including one whose answer is an Agent), `pane`
 (`create pane`, the split UI's shell Pane, and the pane-menu split), `agent`
 (`create agent` and the split UI's Agent Pane, including a resume-picker
 pick, which creates a new Agent), or `resume` (`agent resume`, including the
-resume `agent persona` runs). A successful transaction is `info`/`success`;
+resume `agent relaunch` runs). A successful transaction is `info`/`success`;
 a failed one, including one that was rolled back, is `error`/`error` with
 `kind=runtime`, so the support report's existing error-only projection
-carries it. The record adds only two timings:
+carries it. The record adds two timings and, inside the lock hold, their
+breakdown:
 
 - `duration_ms` runs from entering the create transaction to its return. It
   includes the runtime route bind, the wait for the Registry lock, the time
@@ -85,14 +146,212 @@ carries it. The record adds only two timings:
   excludes the wait for the lock and the Registry read before the mutation
   starts. It is absent when the transaction failed before it entered the
   mutation, and `0 <= lock_held_ms <= duration_ms` always holds.
+- Six phase fields split `lock_held_ms` into the stages of the mutation, in
+  order, each starting where the previous one ended:
+  `phase_guard_ms` (the ownership guards' preflight against tmux),
+  `phase_first_reconcile_ms` (the reconcile pass before the create's own
+  writes), `phase_operation_ms` (the create itself: tmux splits and mirrors,
+  the Registry edit, and for an Agent the supervised child spawn),
+  `phase_second_reconcile_ms` (the reconcile pass after those writes),
+  `phase_reprove_ms` (the re-proof of any route identity the transaction
+  reused), and `phase_store_write_ms` (from the mutation callback returning
+  to the Registry update returning: normalize, validate, the durable write,
+  the unlock, and anything the store does after the unlock before it
+  returns). A phase the transaction never reached, because an earlier stage
+  failed, is absent; the store-write phase is present whenever the mutation
+  was entered. The phases appear only with `lock_held_ms`, and
+  `sum(phase ms) <= lock_held_ms` always holds on disk: a breakdown that
+  would exceed the hold (a clock that went backwards) is dropped whole.
+- `spawn_to_release_ms` is written for `agent` and `resume` only. It runs
+  from the first supervised child spawn -- the split that starts the managed
+  Pane's supervisor returning that Pane -- to the Registry update returning:
+  how much of the child's own Registry lock budget the creator consumed
+  before the child could take the lock. It is absent when no supervised
+  child was spawned, and `0 <= spawn_to_release_ms <= lock_held_ms` always
+  holds.
 
 The record is appended after the transaction returns, so never while the
 Registry lock is held, and a journal failure never changes the create's
 result, exit status, stdout, or stderr. It does not replace the invocation's
 `command.outcome`, and it does not count guard reads or time individual
 guards. The generated Window rename also runs through the same transaction
-and is not recorded, because it is not a create. Every other event family
-rejects `lock_held_ms` and the `create` component.
+and is not recorded, because it is not a create. Every event family other
+than `create.outcome` rejects the `create` component, the six phase fields,
+and `spawn_to_release_ms`; every family other than `create.outcome` and
+`registry.lock.acquisition` rejects `lock_held_ms`.
+
+Registry lock acquisitions use `component=registry` and
+`event=registry.lock.acquisition`. Every acquisition of the Registry mutation
+lock -- a Registry read, update, convergent update, schema migration, or
+admission barrier -- is measured, and one record is written for an
+acquisition that waited at least one second, held the lock at least one
+second, or timed out; every other acquisition writes nothing. The record is
+appended after the lock is released (or after the acquisition gave up), under
+the invocation's `run_id`, and it is best effort: a journal failure, or any
+failure in the recorder, never changes the Registry operation's result or
+the bytes it wrote. When a create's own acquisition is recorded, that append
+runs after the unlock but before the Registry update returns, so its cost
+falls inside that create's `lock_held_ms` and `phase_store_write_ms`. The
+record carries only:
+
+- `command` and `subcommand`: the invocation's catalog command, classified
+  like `command.outcome` and absent for an unclassified invocation. No argv
+  value, prompt, flag, path, pid, or process name is recorded.
+- `operation`: the Registry entry point that took the lock, one of `update`,
+  `update-convergent`, `load`, `migrate`, or `admission-barrier`.
+- `wait_ms`: from just before the acquisition to the grant, or to giving up.
+- `lock_held_ms`: from the grant to just after the release; present only when
+  the lock was held.
+- `duration_ms`: always exactly `wait_ms + lock_held_ms`.
+- `result`, `level`, `kind`, and `code`: a held and released lock whose work
+  succeeded is `success` with no kind or code, at level `info`, or `warn` when
+  it held the lock for five seconds or more. A held lock whose work failed
+  (a refused callback, a failed validation or write) is `error`/`error`,
+  `kind=runtime`, `code=registry.mutation.failed`. A deadline timeout is
+  `error`/`error`, `kind=runtime`, `code=registry.lock.timeout`, and any other
+  acquisition failure is `code=registry.lock.acquire-failed`; neither carries
+  `lock_held_ms`.
+
+`warn` is used by this event alone, and every other event family rejects
+`wait_ms`, the `registry` component, and level `warn`. `diagnostics log
+--level warn` selects these records; the support report's error-only
+projection carries the `error` ones.
+
+A Registry lock timeout error names the process the lock marker records as
+holder, when that process is observed running, by the leading command words
+of its `/proc/<pid>/cmdline`: the program's base name followed by the words
+after it while they look like catalog command words (a lowercase letter, then
+lowercase letters, digits, and hyphens), stopping at the first flag, `--`,
+uid, path, number, or prompt, and at four words in all -- for example
+`holder: pid 1234 (projmux create agent), running`. When the command line
+cannot be read or yields no word, the kernel process name is used, and when
+that cannot be read either, the command is reported as unavailable.
+
+An accepted `agent message send` whose Claude source Agent's registered
+Claude process is not an ancestor of the sender writes one `component=agent`,
+`event=agent.message.foreign-source` `info`/`success` record. It adds only the
+opaque source `agent_uid` (`agent-…`) and its `pane_uid` (`pane-…`); the
+provider session id, process ids, and environment shown in the stderr warning
+are never recorded, and every family other than the two `agent` events below
+rejects `agent_uid` and the `agent` component. A journal failure never changes
+the send.
+
+The Claude messaging endpoint registration writes `component=agent`,
+`event=agent.claude.registration` records. The chain is the SessionStart hook
+`internal claude-endpoint-register`, which builds a bootstrap and starts the
+detached helper `internal claude-endpoint-helper`; the helper claims and
+records the registration in one Registry transaction and becomes Ready. Every
+refusal along it, the helper's Ready, and the end of a Ready helper's serving
+loop each write one record. A record carries only:
+
+- `source`: the process that wrote it, `hook` or `helper`.
+- `code`: `claude.registration.<reason>`, one reason of the closed table
+  below. A reason the table does not list, or does not allow for that source,
+  drops the record.
+- `result`, `level`, and `kind`: a refusal before Ready is
+  `error`/`error`, `kind=runtime`. `ready` and the `ended-*` reasons are
+  `info`/`success` with no kind: the registration ran, and the `ended-*`
+  reason says how its lifetime ended.
+- `duration_ms`: from that process's route entry to the append.
+- `agent_uid` (`agent-…`) and `pane_uid` (`pane-…`): only once the Agent and
+  Pane matched the Registry, and omitted when not strictly shaped. The hook
+  sets them from the provider process check onward, once its bootstrap matched
+  the Pane and its Agent against the Registry, and for every helper start
+  refusal. The helper sets them only after its producer check passed: the
+  bootstrap then provably came from the live hook that made that Registry
+  match, so its UIDs are the Registry-matched ones.
+
+The provider session id, the registration nonce (`registrationGeneration`),
+the messaging token and socket path, lease and coordination socket paths,
+process ids and start identities, argv, error text, and the working directory
+are never recorded.
+
+| code (`claude.registration.…`) | source | where |
+| --- | --- | --- |
+| `hook-arguments-present` | hook | the hook route got arguments |
+| `registry-path-invalid` | hook | the activation Registry path is set but not the exact shape |
+| `registry-unreadable` | hook, helper | the hook's Registry read failed, or the helper's read after its claim |
+| `hook-input-unreadable` | hook | stdin failed to read or exceeded 64 KiB |
+| `payload-not-session-start` | hook | the payload is not a parsable `SessionStart` |
+| `pane-binding-mismatch` | hook | the Pane, activation generation, or Claude process binding does not match |
+| `agent-mismatch` | hook | the Pane's Agent is not the running Claude Agent that owns it |
+| `provider-process-mismatch` | hook | the hook's parent is not the bound Claude process |
+| `messaging-credential-invalid` | hook | the messaging socket or token is missing or malformed |
+| `session-id-embeds-credential` | hook | the session id contains the token or socket |
+| `messaging-socket-unavailable` | hook, helper | the messaging socket failed inspection |
+| `nonce-unavailable` | hook | no registration nonce could be generated |
+| `authority-invalid` | hook, helper | the registration authority is not valid |
+| `hook-identity-unavailable` | hook | the hook's own process identity is unavailable |
+| `reply-tool-policy-unavailable` | hook | the reply tool policy could not be captured |
+| `helper-executable-unavailable` | hook | the running binary could not be located |
+| `helper-bootstrap-unavailable` | hook | the bootstrap could not be encoded |
+| `helper-ack-pipe-unavailable` | hook | the acknowledgement pipe could not be created |
+| `helper-start-failed` | hook | the helper process did not start |
+| `helper-admission-unconfirmed` | hook | no acknowledgement arrived before the 3s deadline or EOF |
+| `helper-arguments-invalid` | helper | the helper got arguments or inherited a messaging credential variable |
+| `helper-ack-missing` | helper | fd 3 is absent |
+| `helper-ack-not-pipe` | helper | fd 3 is not a pipe |
+| `helper-input-unreadable` | helper | stdin failed to read, exceeded 64 KiB, or is not a bootstrap |
+| `producer-mismatch` | helper | the parent is not the hook that built the bootstrap |
+| `bootstrap-invalid` | helper | the bootstrap Registry path or token is invalid |
+| `helper-identity-unavailable` | helper | the helper's own process identity is unavailable |
+| `lease-unavailable` | helper | the private lease directory, socket, or its mode could not be set up |
+| `coordination-unavailable` | helper | the coordination listener could not be opened |
+| `lease-owner-unavailable` | helper | the lease owner receipt could not be written |
+| `provider-process-gone` | helper | in the transaction, the Claude process is gone |
+| `claim-refused-activation` | helper | in the transaction, the activation is no longer this helper's claim target |
+| `claim-refused-competing` | helper | in the transaction, the same registration generation carries another session or lease |
+| `claim-refused-newer` | helper | in the transaction, a newer SessionStart claimed another generation |
+| `lock-timeout` | helper | the transaction gave up on the Registry lock deadline |
+| `lock-acquire-failed` | helper | the transaction never ran for any other Store reason (the one fallback, below) |
+| `registry-degraded` | helper | the Store refused the transaction on a degraded Registry |
+| `registry-write-failed` | helper | the transaction's validation or durable write failed |
+| `route-mismatch` | helper | the recorded route does not resolve to this registration |
+| `dialogue-broker-unavailable` | helper | the dialogue broker could not start |
+| `reply-tool-gate-unavailable` | helper | the reply tool gate could not be built |
+| `stale-before-ack` | helper | the registration stopped being current before the acknowledgement |
+| `ready` | helper | the acknowledgement byte was written |
+| `ended-context-done` | helper | the serving loop's context ended |
+| `ended-not-current` | helper | the serving loop found the registration no longer current |
+| `ended-accept-failed` | helper | the lease listener failed |
+
+A Claude session projmux did not launch writes nothing. The user-wide
+SessionStart hook still runs for it, but with no activation Registry path set
+at all (`PMX_INTERNAL_CLAUDE_REGISTRY_PATH` empty or unset) it is outside any
+managed activation: the hook stops with the closed reason `unmanaged-session`,
+which the recorder drops and every reader rejects, so it is never journaled
+at any level. A set but malformed path is still `registry-path-invalid`. A
+nested unmanaged Claude that inherited a managed Pane's activation environment
+is refused as `provider-process-mismatch`, because its parent is not the bound
+Claude process; that record names the managed Pane's `agent_uid` and
+`pane_uid`, whose activation environment it inherited.
+
+`lock-acquire-failed` is the one fallback of the transaction's
+classification: the claim callback never ran, and the Store error is neither
+a lock timeout nor a degraded Registry. That is a failed lock acquisition, or
+a locked Registry read or recovery inspection failure the Store did not
+classify as degraded. A failure after the callback ran is always
+`registry-write-failed`.
+
+The hook writes at most one record, and only once its attempt is over: at a
+refusal before it started the helper, or after its acknowledgement wait
+returned, which is `helper-admission-unconfirmed` or a start refusal. It never
+appends between starting the helper and the helper's producer check, and a
+confirmed admission writes nothing from the hook because the helper writes
+`ready`. The helper writes `ready` exactly once, right after the
+acknowledgement byte, and one more record when it returns: the refusal that
+stopped it before Ready, or the `ended-*` reason after it. That last record is
+appended only after the helper closed fd 3, so the hook's EOF never waits on
+the journal. Appends are best effort: a failing or slow journal never changes
+the hook's empty output, its nil result, or the helper's argv, environment,
+and stdin. Every other event family rejects the `hook` and `helper` sources
+and every `claude.registration.*` code.
+
+Both routes are classified as the internal-only commands
+`claude-endpoint-register` and `claude-endpoint-helper`, so the helper's slow
+`registry.lock.acquisition` records carry `command=claude-endpoint-helper`.
+Neither is state-changing and both always return nil, so neither writes a
+`command.outcome`.
 
 projmux no longer emits `session-state.outcome` records. Project snapshots
 were removed, and the retained `internal tmux autosave-session-state` route is
@@ -313,7 +572,11 @@ Classification is intentionally conservative for mutation-capable interactive
 commands: opening session/project/settings/popup flows is treated as changing
 even when a user cancels. Explicit read variants (`internal status`, `list`,
 `get`, config rendering, plain welcome, and the diagnostics viewer) remain
-read-only. The successful automatic hook/poll paths `internal agent-hook ingest`, `attention
+read-only. Read-only classification governs `command.outcome` only: a
+read-only command whose locked Registry read waited for or held the lock for a
+second or more still writes its `registry.lock.acquisition` measurement, except
+Doctor, the support report, and the retired no-write argv, which never append.
+The successful automatic hook/poll paths `internal agent-hook ingest`, `attention
 arm`, `attention clear`, `attention window`, `internal tmux autosave-session-state`, and
 `window record` are also read-only so high-frequency operation does not append
 to the journal; an error from any of them still records exactly one safe error

package/docs/release.md

@@ -34,6 +34,10 @@ then builds the linux/darwin × amd64/arm64 matrix and uploads tarballs to the
 drafted release (`gh release upload --clobber`). `Build Release` depends on the
 aggregate rather than on individual shards.
 
+Each tarball holds the binary, `README.md`, `README-ko.md`, `LICENSE`, and
+`THIRD_PARTY_NOTICES`. The last is generated by `make notices` and committed;
+`make test` fails when it no longer matches what the binary links.
+
 Do not add hardcoded notes back to that workflow. release-please owns the
 notes.
 

package/docs/replacement-contract.md

@@ -400,6 +400,12 @@ platform with no executable link to read declines to drain rather than draining
 on a guess: `defaultProjmuxImageReplaced` answers false on darwin, and the
 absence is stated by this table's `unsupported-platform` row.
 
+A native observer whose first bind receives a drain refusal leaves the Pane on
+hook fallback and keeps retrying that exact Agent and thread. It writes no
+composite authority until a current broker binding opens. When the old broker
+finishes its accepted work and exits, the observer can bind to the replacement
+and publish authority; messages remain refused while the binding is absent.
+
 ### The install pass
 
 `projmux internal install-replace` runs as a step of `make install`, immediately

package/docs/repo-layout.md

@@ -21,6 +21,7 @@ projmux/
     state/
     tools/
       gendocs/
+      gennotices/
     ui/
       picker/
       pickercompat/
@@ -40,6 +41,8 @@ projmux/
 - `internal/core` contains product behavior that should be testable without tmux.
 - `internal/tools/gendocs` is a build-time `main` package, not part of the shipped
   binary. `make docs` runs it to regenerate `docs/cli.md` from the command manifest.
+- `internal/tools/gennotices` is a build-time `main` package too. `make notices` runs it
+  to regenerate `THIRD_PARTY_NOTICES` from the modules `./cmd/projmux` links.
 - `internal/integrations/tmux` should be the only place that knows tmux command strings and output formats.
 - `internal/ui/picker` and `internal/ui/projmuxpicker` own native picker behavior.
 - `internal/ui/pickercompat` is an internal compatibility option/result shape for older app call sites. It is not a runtime backend; product code should route through the native picker.

package/docs/resource-attribution.md

@@ -145,6 +145,10 @@ PROJMUX_RESOURCE_PROJECT_FALLBACK_SMOKE=1 go test \
   ./internal/integrations/tmux
 ```
 
+`PROJMUX_REAL_TMUX_STRICT=1` also turns on both isolated smokes, and the CI
+Unit Tests job sets it, so they run there and a missing tmux fails them
+instead of skipping. The read-only smoke above stays opt-in.
+
 ## Phase 1 inspector
 
 The popup retains warming/partial/unavailable and overage states, renders RSS

package/docs/session-restore.md

@@ -17,9 +17,12 @@ registered Project is not asked: it opens fresh, which registers it.
   the exact old Project UID and its Window/Pane/Agent counts. Declining returns
   to the startup rows and writes nothing. It does not archive or retain the old
   generation. Its new Window's first Pane follows the saved launch default
-  (`tmux-ai-split-mode`), exactly as a Window created from the UI does: the
-  choice is made before anything is cleared. The first open of an unregistered
-  root, which resolves to the same fresh start, behaves the same.
+  (`tmux-ai-split-mode`, then the central `ai-new-window-mode`, then
+  `selective`; see
+  [New AI Window Default](configuration.md#new-ai-window-default)), exactly as
+  a Window created from the UI does: the choice is made before anything is
+  cleared. The first open of an unregistered root, which resolves to the same
+  fresh start, behaves the same.
 
 Esc/cancel returns to Projects; it is not an action row. Picker failure falls
 back to the non-destructive `Continue project` action.
@@ -77,10 +80,11 @@ each successful result has exactly one Project claiming the root.
 The saved launch default is used only when the open carries the exact client
 that pressed the row. The order is:
 
-1. Ask. A picker mode (`selective`, the unset default, or `resume`) opens its
-   picker on the Pane the row was pressed in, before the old layout is cleared
-   or the new Session exists; a provider mode and `shell` are already the
-   answer and open nothing.
+1. Ask. A picker mode (`selective`, the default when neither
+   `tmux-ai-split-mode` nor `ai-new-window-mode` holds a valid mode, or
+   `resume`) opens its picker on the Pane the row was pressed in, before the
+   old layout is cleared or the new Session exists; a provider mode and
+   `shell` are already the answer and open nothing.
 2. Clear the layout and create the new Session with its one shell Pane.
 3. Fill it: an Agent answer is created in that Window first, and the shell is
    then removed through the canonical Pane delete.

package/docs/statusbar.md

@@ -51,10 +51,11 @@ row 1  [#S]  #{pane_current_path}  <git>  CPU 12%  MEM 41%   %H:%M
   mouse-target context resolves the clicked window directly. All
   other ranges fall through to `run-shell projmux internal statusbar click
   ...`, which dispatches by range id. The in-config short-circuit
-  is required because `#{mouse_window}` is empty for window-list
-  clicks on tmux 3.4+, so a `run-shell` handler can't recover the
-  target after the fact — the Go dispatcher's
-  `isWindowListRangeToken` fallback is now defense-in-depth only.
+  is required because tmux has no format variable for the clicked
+  window: it is only reachable through tmux's internal mouse target
+  (`-t =`), which does not survive `run-shell`, so a handler can't
+  recover the target after the fact — the Go dispatcher's
+  `window|<idx>` index path is defense-in-depth only.
   Each window tab reserves a one-cell live pane attention prefix from
   `projmux attention window #{window_id}` before the index. AI panes use the
   semantic `@projmux_ai_badge_kind` first: approval/input-required panes use
@@ -72,11 +73,12 @@ row 1  [#S]  #{pane_current_path}  <git>  CPU 12%  MEM 41%   %H:%M
   response-complete live badge, including stale `@projmux_ai_state=waiting`
   fallback state; action-required and in-progress live badges remain visible.
   Window-list badges and app pane-border badges use the same semantic priority,
-  with display style controlled by Settings > Appearance > AI badge style and persisted in
-  `~/.config/projmux/ai-badge-style`. The default is `dot`; `emoji` renders
-  `⏳` for approval/input-required, `✅` for response-complete, and `🔄` for
-  in-progress. `off` (also accepted as `minimal` when read from disk) preserves
-  the same spacing without drawing a marker.
+  with display style controlled by Settings > Appearance > AI badge style and
+  persisted in `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-badge-style`.
+  The default is `dot`; `emoji` renders `⏳` for approval/input-required,
+  `✅` for response-complete, and `🔄` for in-progress. `off` (also accepted as
+  `minimal` when read from disk) preserves the same spacing without drawing a
+  marker.
   The session, pwd, and git segments on this row are wrapped
   in `#[range=user|<id>]` ranges and dispatched through the projmux
   handler. The standalone config also wraps the right-side `projmux`
@@ -244,11 +246,12 @@ A single tmux bind handles both lines:
 ```tmux
 bind-key -n MouseDown1Status if-shell -F "#{==:#{mouse_status_range},window}" \
   { select-window -t = } \
-  { run-shell "'<projmux>' internal statusbar click \"#{mouse_status_range}\" --client \"#{client_tty}\" --mouse-window \"#{mouse_window}\"" }
+  { run-shell "'<projmux>' internal statusbar click \"#{mouse_status_range}\" --client \"#{client_tty}\"" }
 ```
 
 `MouseDown1Status` fires from any line of a multi-line status bar with
-`#{mouse_status_range}` resolving to the range under the cursor.
+`#{mouse_status_range}` resolving to the range under the cursor. The click
+command passes only `#{mouse_status_range}` and `#{client_tty}`.
 
 ## Usage element drop order
 
@@ -403,10 +406,11 @@ Internal notify commands use `NotifySidebar:*` IDs in `keymap.toml`; runtime
 footers render key guides from the merged keymap and prefer the default alias
 when it is still configured.
 
-Empty `#{mouse_status_range}` (a click on whitespace) falls through to
-`select-window -t @<mouse_window>` when `--mouse-window` is non-empty,
-otherwise it is a no-op. Unknown user range ids are non-specialized
-placeholder surfaces and no-op until a handler is wired into the dispatcher.
+Empty `#{mouse_status_range}` (a click on whitespace) is a no-op. Unknown
+user range ids are non-specialized placeholder surfaces and no-op until a
+handler is wired into the dispatcher. `--mouse-window <v>` is accepted for
+compatibility with bindings generated by older releases (live on a running
+tmux server until `projmux config apply`) and ignored.
 
 ## Keyboard chord
 
@@ -474,14 +478,14 @@ git-provider, or bell icon), or `emoji`. Git branch decoration follows
 fox-style mark, and other remotes use a generic git branch mark. Saving
 visibility or Resources regenerates the app/standalone config and source-loads
 the generated app config when Settings is running inside tmux. The legacy
-`~/.config/projmux/statusbar-decoration` and
+`${XDG_CONFIG_HOME:-$HOME/.config}/projmux/statusbar-decoration` and
 `@projmux_statusbar_decoration` remain fallback defaults for older configs.
 Settings > Theme controls the bottom status bar background through
 `status_background`; `surface` controls popup and native frame backgrounds.
 
-Resources uses `~/.config/projmux/live-resources` as its single saved enabled
-state; there is no separate Resources visibility file or duplicate toggle. CPU
-sampling state is an internal,
+Resources uses `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/live-resources` as
+its single saved enabled state; there is no separate Resources visibility file
+or duplicate toggle. CPU sampling state is an internal,
 atomically replaced file under `${XDG_STATE_HOME:-~/.local/state}/projmux/`
 and is not a user-edited setting.