projmux 0.15.1 → 0.15.3

package/docs/architecture.md

@@ -1008,10 +1008,14 @@ tmux transport mirror:
   recovery route.
 - `rename pane` changes `Pane.metadata.name` and its `@projmux_pane_label`
   mirror only. It never writes the raw tmux `pane_title`.
-- `rename window` is the explicit stable-identity path: it changes only
-  `Window.metadata.name`, its root-scoped same-kind name reservation, and the
-  exact live `@projmux_window_name` transport mirror. It does not change tmux
-  `window_name`.
+- `rename window` is the explicit stable-identity path: it changes
+  `Window.metadata.name`, its root-scoped same-kind name reservation, the exact
+  live `@projmux_window_name` transport mirror and, when the invocation has a
+  proven runtime route, the tmux tab `window_name` through the canonical
+  `rename-window -t @N -- <name>` -- the same argv shape the rename key and the
+  Window menu Rename item go through. With no route it stays Registry-only and
+  says on stderr that the tab did not converge. It never changes
+  `metadata.displayName`.
 - `rename project` likewise writes only `Project.metadata.name` and the exact
   live session's `@projmux_project_name`; it never renames the tmux session.
   `rebind project` preserves the Project uid and session name while updating
@@ -1906,7 +1910,10 @@ Resource-first create:
   touched.
 - **Everything is detached.** No create path issues `switch-client`,
   `select-window`, `select-pane`, or `attach-session`. `focus pane` and
-  `-o pane-id` are how a caller ends up in the new pane.
+  `-o pane-id` are how a caller ends up in the new pane. One exception: the
+  human intent route `internal tmux window-create` (`window.create` key, Window
+  menu New At End) moves exactly the pressing client to the new Window after
+  its create commits; public `create` stays detached.
 - **Focus is navigation-only.** `focus project|window|pane` reads live tmux
   inventory and may move an existing client, but has no Registry store and
   issues no session/Window/Pane creation, identity-marker, rename, respawn, or
@@ -2004,9 +2011,11 @@ Selector and the implicit active target:
 
 Projmux keeps visible naming separate from source metadata:
 
-- **User pane label** is persistent pane-scoped metadata stored in
-  `@projmux_pane_label`. The Rename Pane action sets or clears only this field;
-  it does not write the AI topic or raw pane title.
+- **User pane label** is pane-scoped metadata stored in `@projmux_pane_label`,
+  the live mirror of the Pane's Registry `metadata.name`. The Rename Pane action
+  renames the Registry Pane through the same owner as `rename pane`, which
+  writes this mirror; an empty response changes nothing, and the action never
+  writes the AI topic or raw pane title.
 - **Pane border label** is the primary visible pane name. In the app tmux
   config and native previews it resolves to user pane label first, agent AI
   topic second, known interactive shell command (`zsh`, `bash`, `fish`, `sh`,

package/docs/claude-coordination-endpoints.md

@@ -127,6 +127,22 @@ failure before any byte is a non-ambiguous `provider-write-zero`; partial bytes,
 a write error after bytes, or a lost helper response is ambiguous and has
 `autoResend=false`. A complete write plus helper return is only a transport
 handoff, not proof that Claude parsed, displayed, processed, or answered it.
+Push content has no length cap of its own: only the 8192-byte serialized
+auth+user frame bounds it, and a size excess ends as
+`provider-frame-too-large: frameBytes=N limitBytes=8192` with zero provider
+bytes; the reply tool argv body stays at 4096 bytes.
+
+`agent message send` applies the same budget to a Claude target before
+acceptance, for plain sends and `--reply-to` alike. The sender renders the
+content with the helper's renderer, once with its own executable and once with
+the fixed executable phrase, keeps the longer frame, and counts an assumed
+48-byte auth token; it never reads a messaging token. A frame over 8192 bytes
+exits nonzero with `provider-frame-too-large: frameBytes=N limitBytes=8192`
+before any receipt is stored or the helper is called. Codex targets are not
+pre-checked. A helper started before this rule still caps push content at 4096
+bytes and fails a larger body with `provider-frame-invalid-content`; the
+sender's receipt then names the rendered content bytes and asks to re-activate
+(restart) the target Agent.
 
 The frozen frame is closed to Claude Code `2.1.263`. A different provider
 version, helper replacement, provider restart, registration replacement, or
@@ -208,6 +224,26 @@ real-provider observation is opt-in through
 `scripts/agent-dialogue-live-canary.sh`; each version-stress row must qualify
 independently.
 
+`TestClaudeDialogueStreamReplaysObservedFrameCorpus` pins the reply-only
+validator's verdict on preserved real frame shapes. Neither it nor L20 proves
+installed-provider compatibility, value drift (the corpus keeps top-level key
+shape with placeholder values), or acceptance of unknown frames and fields (the
+closed vocabulary rejects them by design). L20 replays every corpus item whose
+verdict is `drop` through the production reply-only validator: the Claude
+fixture reads the corpus at run time from `PROJMUX_FAKE_CLAUDE_OBSERVED_FRAMES`,
+emits each dropped side frame with its key set unchanged after init and before
+its startup result, and the scenario requires the emitted names to equal the
+corpus drop set. Those frames are key-shape placeholders, not model output. L20
+does not emit the two recorded real shapes that are rejected today:
+`result-success-25-keys` (the result allowlist lacks `origin`) and
+`system-init-allowlist-diff` (the init allowlist lacks `memory_paths` and
+`terminal_slash_commands`). Shapes without preserved evidence are gaps, not
+items, so neither the corpus nor L20 exercises them: `command_lifecycle` keys
+and values, a non-null assistant `context_management`, `system`
+`thinking_tokens`, hook and user `tool_result` frames, the exact real init key
+set, every nested value, `rate_limit_event` envelope keys beyond `type` and
+`rate_limit_info`, and the lost earlier shape inventories.
+
 Provider sources: [SessionStart and Stop hooks](https://code.claude.com/docs/en/hooks)
 and [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging).
 

package/docs/cli-guide.md

@@ -252,8 +252,27 @@ The contract:
 `create window|pane|agent|<provider>` is resource-backed on every spelling.
 There is no mode flag and no second parser: the same argv means the same thing
 whether or not `--project` is present, and `-w`, `--create-window`, `--pane`,
-`--selector`, `--placement`, `--name`, `--label`, `--cwd`, `--add-dir`, `-o`,
-and the `--` payload all reach the same parser either way.
+`--selector`, `--placement`, `--cwd-from`, `--name`, `--label`, `-o`, and the
+`--` payload all reach the same parser either way. `--cwd` and `--add-dir` are
+provider create flags: they are defined on `create agent` and the three provider
+shortcuts, not on `create window` or `create pane`.
+
+`--cwd-from project|pane` selects where the new split starts. `project` (the
+default) starts it in the owner Project root. `pane` starts it in the active
+Pane's live directory while that directory is inside the owner Project root, and
+otherwise starts it in the root and says so in one stderr line; it never
+refuses. The flag cannot be combined with `--cwd`, which names an Agent working
+directory outright.
+
+On the CLI the flag is the only input: `create pane`, `create agent`, and the
+provider shortcuts never read `[ai] split_cwd_from`, so with no `--cwd-from`
+they always start in the owner Project root, whatever the global or project
+config says. A CLI result is determined by its arguments, and scripts must not
+change behavior because someone changed a Settings value. That config (and the
+`AI > New splits start in` Settings row that writes it) only decides splits
+started from the UI -- keybinding splits, the launcher, the resume picker's new
+row, and the Pane menu -- in the order flag > project config > global config >
+default. See [configuration.md](configuration.md).
 
 The scope resolves in two branches:
 
@@ -339,7 +358,10 @@ they name `--project` as the fix:
   gone — a `recoverable` runtime is reported, never adopted.
 
 Every create is **detached**: no create moves the client. Use `focus pane` or
-`-o pane-id` when you want to end up in the new pane. A natural create validates
+`-o pane-id` when you want to end up in the new pane. One exception: the human
+intent route `internal tmux window-create` (the `window.create` key and the
+Window menu New At End) moves the pressing client to the new Window after its
+create commits; public `create` stays detached. A natural create validates
 the inherited exact route and Pane containment. An explicit resource scope
 binds the selected app resource route without letting unrelated inherited
 `TMUX`/`TMUX_PANE` choose or change the resource target; exact Project plus
@@ -376,10 +398,16 @@ The generated `MouseDown3Pane` menu treats its Horizontal Split, Vertical
 Split, and Kill entries as Projmux resource actions. Both splits pass the exact
 clicked pane through the popup-origin anchor above and reach the same canonical
 `create pane` materializer as the CLI, so the new pane receives a Registry uid.
-Kill resolves that anchor's mirrored uid and reaches canonical `delete pane`,
-including its printed delete result. The menu never falls back to a raw tmux
-mutation when either route refuses. The reason is displayed on the exact client
-that opened the menu instead of being lost as a `run-shell` exit code.
+Kill on a pane with `@projmux_pane_uid` resolves that anchor's mirrored uid and
+reaches canonical `delete pane`, including its printed delete result; a pane
+without the mirror runs tmux's own `kill-pane` instead of being refused. The
+menu never falls back to a raw tmux mutation when either route refuses. The
+reason is displayed on the exact client that opened the menu instead of being
+lost as a `run-shell` exit code. The app config's `prefix >` and
+`M-MouseDown3Pane` Pane menus follow the same rules, and its `prefix <`,
+`MouseDown3Status`, and `M-MouseDown3Status` Window menus route Kill on a
+mirrored Window to canonical `delete window`; see
+[Managed menus](keybindings.md#managed-menus).
 
 tmux Respawn has no equivalent in the current resource model: it preserves the
 same pane handle, layout, Registry uid, and original command, while canonical
@@ -389,15 +417,40 @@ menu therefore omits Respawn entirely and does not expose a refusal handler or
 invent a replace operation. User-authored tmux bindings remain outside this
 managed-menu contract.
 
+#### Managed close keys
+
+The generated app config routes tmux's `prefix x` and `prefix &` through the
+same resource routes whenever the target carries a Registry identity mirror.
+`prefix x` on a Pane with `@projmux_pane_uid` confirms on the exact client, then
+runs the Pane menu Kill route above: canonical `delete pane` with an
+`intentional` termination receipt. The Agent that owned the Pane stays in the
+Registry as Offline with a `deleted` exit, which Continue never replays.
+`prefix &` on a Window with
+`@projmux_window_uid` confirms, then runs `internal tmux window-delete`, which is
+canonical `delete window` on that exact Window; a Project's last Window leaves a
+zero-Window Project. A refusal is shown on that client and never falls back to
+a raw kill. A target without the mirror keeps tmux's stock `confirm-before`
+prompt and kill, with no Registry write. See
+[Managed close keys](keybindings.md#managed-close-keys) for changing or
+disabling the keys.
+
 ### Rename and rebind live convergence
 
 `rename project|window|pane` commits the selected Registry `metadata.name` and
-then updates only its exact UID-bound live transport field:
+then updates only its exact UID-bound live transport fields:
 
 - Project: `@projmux_project_name` (never the tmux session name)
-- Window: `@projmux_window_name` (never tmux `window_name`)
+- Window: `@projmux_window_name` and the tmux tab `window_name` (never
+  `displayName`)
 - Pane: `@projmux_pane_label` (never raw `pane_title`)
 
+The Window tab converges only when the invocation has a proven runtime route,
+which is what running inside the projmux tmux runtime gives it. Outside one the
+rename is Registry-only: it exits zero and prints one line on stderr saying the
+tab still shows the old name until a rename runs inside that runtime. There is
+no flag for either behavior; the next time that Window is materialized from the
+Registry, the tab carries the committed name.
+
 `rename agent` changes only the Agent's stable root-scoped `metadata.name`.
 It does not change the Agent topic, provider, lifecycle state, or managed Pane
 name/title. `create agent` derives the managed Pane's name from the Agent's
@@ -537,7 +590,9 @@ generated `pane-exited` hook. The supervisor must have durably journaled a
 same-generation `normal` receipt, the hook must name the exact `%N` Pane and
 the owner Window must carry its exact last-positive `$N/@N` binding on the same
 socket, and fresh preflight plus locked observations must still resolve the
-same Registry owner chain. A non-last Pane is removed while its directly owning
+same Registry owner chain. This includes Windows re-materialized by Project
+start/Continue topology replay: the replay records each Window it materializes
+with its live `$N/@N` in the same commit. A non-last Pane is removed while its directly owning
 Agent is retained Offline with its conversation identity. For a last Pane, that evidence is retained until a
 matching `window-unlinked` hook removes the Window; a final Project Window also
 removes its Window descendants while retaining the exact Project uid, root,
@@ -2021,6 +2076,8 @@ projmux internal tmux popup-sessions
 projmux internal tmux popup-preview <session>
 projmux internal tmux rebalance-panes
 projmux internal tmux rename-pane <pane> <label>
+projmux internal tmux window-rename --client <key> --anchor <%pane> (--name-stdin | -- <name>)
+projmux internal tmux pane-rename   --client <key> --anchor <%pane> (--name-stdin | -- <name>)
 projmux internal tmux print-config     [--bin <path>]
 projmux internal tmux print-app-config [--bin <path>]
 projmux internal tmux install     [--bin <path>] [--config <path>] [--include <path>]
@@ -2034,10 +2091,18 @@ accepted by `popup-toggle` mirror the historical sessionizer surface:
 `notify-sidebar`, `recent-windows`, `resource-inspector`, `ai-split-picker-right`,
 `ai-split-picker-down`, `ai-split-resume-right`, `ai-split-resume-down`,
 `ai-split-settings`.
-`rename-pane` sets only the pane-scoped user label
-`@projmux_pane_label`; an empty label clears the option. It does not change the
-raw tmux pane title, AI topic, or AI topic manual-ownership flag. The canonical
-keybinding action id is `rename-pane-label`. The retired `rename-pane-topic`
+`rename-pane` is a label-only helper: it sets only the pane-scoped
+`@projmux_pane_label`, and an empty label clears the option. It does not change
+the Registry Pane name, so the next Continue restores that name, and it does not
+change the raw tmux pane title, AI topic, or AI topic manual-ownership flag. No
+generated binding uses it.
+`window-rename` and `pane-rename` are the generated rename routes behind the
+`rename-window` and `rename-pane-label` keybinding actions and the Window menu
+Rename item. They resolve the anchor Pane to its exact Registry Window or Pane
+and rename it through the same owner as `projmux rename window|pane`, then
+report one line to the client. The generated bindings pass the prompt response
+with `--name-stdin` inside a quoted here-document; see
+[keybindings.md](keybindings.md#rename-keys) for the input rules. The retired `rename-pane-topic`
 keymap action is no longer accepted: replace a stale
 `[bindings.rename-pane-topic]` table with `[bindings.rename-pane-label]`.
 The `projmux agent topic set/clear` commands keep

package/docs/cli.md

@@ -39,7 +39,7 @@ Root parser bridges outside the route graph are censused from their parser token
 
 Every route declares one allowed-effect record over seven independent resource axes. A pipe separates conditional success outcomes; preflight refusal remains zero-effect. `domain-effect=null` means the route has no typed extension beyond this resource tuple.
 
-The machine-readable manifest contains 190 route-effect records, including hidden plumbing that the public route sections omit.
+The machine-readable manifest contains 191 route-effect records, including hidden plumbing that the public route sections omit.
 
 | Axis | Closed vocabulary |
 | --- | --- |
@@ -75,7 +75,7 @@ projmux <command> [args...]
 | [`projmux notification`](#projmux-notification) | canonical | Manage pending notification workflow state |
 | [`projmux open`](#projmux-open) | canonical | Open a Project runtime and move the current client to it |
 | [`projmux pin`](#projmux-pin) | canonical | Manage pinned project directories |
-| [`projmux prune`](#projmux-prune) | canonical | Prune stale Projects and snapshots |
+| [`projmux prune`](#projmux-prune) | canonical | Prune stale Projects, Agents, and snapshots |
 | [`projmux quit`](#projmux-quit) | shortcut | Quit the app-owned projmux tmux runtime |
 | [`projmux reconcile`](#projmux-reconcile) | canonical | Preview or repair Registry and exact tmux resource drift |
 | [`projmux rebind`](#projmux-rebind) | canonical | Rebind a Project to a new absolute root without moving files |
@@ -761,7 +761,7 @@ Subcommands:
 
 | Route | Summary |
 | --- | --- |
-| [`projmux agent message send`](#projmux-agent-message-send) | Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane) |
+| [`projmux agent message send`](#projmux-agent-message-send) | Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt |
 | [`projmux agent message status`](#projmux-agent-message-status) | Read a payload-free broker delivery receipt |
 | [`projmux agent message qualify`](#projmux-agent-message-qualify) | Explicitly qualify one exact Claude target using owned current-version isolation evidence and one marker push |
 
@@ -769,7 +769,7 @@ Canonical spelling: `projmux agent message send`, `projmux agent message status`
 
 #### `projmux agent message send`
 
-Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane)
+Submit bounded peer coordination; --source selects a source Agent anchor, not caller authentication (default: active Pane); exits nonzero after printing a failed, refused, expired, or stale receipt
 
 Selectorless authority: `explicit-target` — the route or caller must name the exact target.
 
@@ -1215,10 +1215,10 @@ Allowed effects:
 ```
 projmux create project --root <absolute-path> [--name <name>] [--label key=value]... [-o <mode>]
 projmux create window [--project <ref> | -p <ref>] [--name <name>] [--label key=value]... [-o <mode>] [-- <payload>]
-projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [-o <mode>] [-- <payload>]
-projmux create claude|antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
+projmux create claude|antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--create-window] [--all-windows | --primary-window] [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 projmux create notification --text <s> --target <SESSION[:WINDOW[.PANE]]> [--socket <s>]
 projmux create snapshot
 ```
@@ -1308,7 +1308,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create pane [--project <ref> | -p <ref>] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1331,7 +1331,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create agent --provider <provider> [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1396,7 +1396,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create codex [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--interactive-only] [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1419,7 +1419,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create claude [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -1442,7 +1442,7 @@ Allowed effects:
 - `domain-effect=null`
 
 ```
-projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [-o <mode>] [-- <payload>]
+projmux create antigravity [--project <ref> | -p <ref>] [--cwd <path>] [--add-dir <path>]... [--window <ref> | -w <ref>]... [--pane <ref>]... [--selector key=value]... [--create-window] [--all-windows | --primary-window] [--name <name>] [--label key=value]... [--placement right|down] [--cwd-from project|pane] [-o <mode>] [-- <payload>]
 ```
 
 Output modes (`-o`): `uid`, `name`, `ref`, `metadata`, `json`, `pane-id`, `none`, `receipt`
@@ -2600,7 +2600,7 @@ projmux pin project list|add|remove|toggle|clear
 
 ## `projmux prune`
 
-Prune stale Projects and snapshots
+Prune stale Projects, Agents, and snapshots
 
 Selectorless authority: `refusal` — there is no safe selectorless action; refuse before output or mutation.
 
@@ -2618,16 +2618,39 @@ Allowed effects:
 ```
 projmux prune snapshot [--older-than <duration>]
 projmux prune project --missing --older-than <duration> [--yes]
+projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
 ```
 
 Subcommands:
 
 | Route | Summary |
 | --- | --- |
+| [`projmux prune agent`](#projmux-prune-agent) | Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected |
 | [`projmux prune project`](#projmux-prune-project) | Delete Projects whose spec.root has been missing for a bounded age |
 | [`projmux prune snapshot`](#projmux-prune-snapshot) | Inspect or delete preserved session snapshots (canonical spelling) |
 
-Canonical spelling: `projmux prune project`, `projmux prune snapshot`
+Canonical spelling: `projmux prune agent`, `projmux prune project`, `projmux prune snapshot`
+
+### `projmux prune agent`
+
+Delete Offline or Failed Agents past a bounded age whose session ref or managed Panes are gone; live Panes and Running Agents are never selected
+
+Selectorless authority: `explicit-fan-out` — the route spelling is an intentional global or whole-set opt-in.
+
+Allowed effects:
+
+- `identity=removed`
+- `address=released`
+- `topology=removed`
+- `desired-state=removed`
+- `runtime=unchanged`
+- `focus=unchanged`
+- `cardinality=zero-or-more`
+- `domain-effect=null`
+
+```
+projmux prune agent --older-than <duration> [--no-session-ref] [--no-pane] [--exclude <agent-ref>]... [--yes]
+```
 
 ### `projmux prune project`
 
@@ -2847,7 +2870,7 @@ Subcommands:
 | Route | Summary |
 | --- | --- |
 | [`projmux rename project`](#projmux-rename-project) | Rename a Projmux Project resource; with no selector inside tmux, the active Project |
-| [`projmux rename window`](#projmux-rename-window) | Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window |
+| [`projmux rename window`](#projmux-rename-window) | Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession, no selector means the active Window, and the tmux tab is renamed with it |
 | [`projmux rename pane`](#projmux-rename-pane) | Rename a Projmux Pane resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Pane; does not change tmux pane_title |
 | [`projmux rename agent`](#projmux-rename-agent) | Rename an Agent stable resource name within the active Project or ControlSession without changing its topic, provider, or managed Pane |
 
@@ -2880,7 +2903,7 @@ Output modes (`-o`): `receipt`, `none`
 
 ### `projmux rename window`
 
-Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession and no selector means the active Window
+Rename a Projmux Window resource; inside tmux a reference resolves within the active Project or ControlSession, no selector means the active Window, and the tmux tab is renamed with it
 
 Selectorless authority: `natural-omitted` — omission resolves one predictable current resource or documented contextual read/scope; any selector replaces it.
 

package/docs/configuration.md

@@ -342,6 +342,7 @@ success = "#5faf87"
 action_required = "#ffaf00"
 pane_active_bg = "default"
 focus = "#00ffff"
+provenance = "#ff8700"
 ```
 
 `text_primary` controls primary content text in native terminal-rendered UI.
@@ -360,6 +361,13 @@ active-pane background tint, and `focus` is the active-pane border color. Each
 of these is a public token: leave it unset to keep the historical built-in
 color, or set it to repaint the matching chrome.
 
+`provenance` is the compact usage label color for a provider row whose numbers
+came from a fallback data source rather than its authoritative one (today: a
+Codex row outside a healthy app-server). It is independent of `warning` and
+`critical`, which stay reserved for usage thresholds, and of the ordinary AI
+label color; the fallback value is orange. See `docs/usage-tracking.md` for what
+the label looks like and `docs/theme-palette.md` for the preset contract.
+
 Supported presets are `projmux`, `high-contrast`, `blue-hour`, `carbon-violet`,
 `daylight`, `ember`, `forest`, and `rose`. `daylight` is the fully-light
 preset; the others are dark. Preset colors paint projmux chrome only (status
@@ -517,6 +525,63 @@ desktop intent for both app-server and hook-fallback authority. Existing
 runtime override exists, take precedence only while hook fallback is current;
 they are never inferred or copied into the semantic policy store.
 
+## Split Start Directory
+
+New splits start in the owner Project root. `[ai] split_cwd_from = "pane"`
+starts UI splits in the active Pane's live directory instead, while that
+directory is inside the owner Project root. Settings exposes the same value as
+`AI > New splits start in` (`Project root` / `Current Pane directory`); choosing
+one writes only the global `[ai] split_cwd_from`.
+
+Config paths (global and project both honored):
+
+```text
+~/.config/projmux/config.toml      # global
+<project>/.projmux/config.toml     # project
+```
+
+Schema:
+
+```toml
+[ai]
+split_cwd_from = "project" # project|pane; where a new shell or Agent split starts
+```
+
+Resolution depends on who starts the split.
+
+**CLI** (`create pane`, `create agent`, and the provider shortcuts) — the flag
+only:
+
+1. `--cwd-from project|pane`
+2. otherwise `project`
+
+The CLI opens no config file for this decision. A CLI result is determined by
+its arguments, so scripts and automation keep starting in the Project root when
+someone changes this setting.
+
+**UI** (keybinding splits, the launcher, the resume picker's new row, and the
+Pane menu) — the config tiers:
+
+1. an explicit per-call value (flag)
+2. project `[ai] split_cwd_from`, read from the owner Project root
+3. global/user `[ai] split_cwd_from`
+4. built-in default (`project`)
+
+There is no environment override, and an unknown value skips its own tier. The
+project tier is always read from the owner Project root, so where a Pane sits
+never changes which config decides. The Settings row shows the UI result and the
+tier that decided it (`project`, `global`, or `default`).
+
+With `pane` selected, the active Pane is the origin of the split: the Pane a
+keybinding ran in, the Pane a right-click menu was opened on, or the anchor Pane
+a CLI create resolved. Its live directory is used only when it is inside the
+owner Project root. `$HOME`, another registered Project tree, a directory that no
+longer exists, and an unreadable directory all start in the Project root and
+report one line naming the reason and that root — on stderr for a CLI create
+with `--cwd-from pane`, and as one client message for a split started from the
+UI. A split is never refused for this reason. `--cwd` on `create agent` still
+names the Agent working directory outright and ignores this setting.
+
 ## AI Resume Picker
 
 The Agent resume picker lists the most recent

package/docs/heterogeneous-dialogue-canary.md

@@ -337,3 +337,31 @@ The selectorless E2E remains the single deterministic L20 scenario. Actual
 active-tool/human overlap, multiple ordinary requests, same-UID recovery and
 installed smoke remain separate unverified evidence. They are not run by this
 qualification-plus-one-idle transaction and are not inferred from its result.
+
+`TestClaudeDialogueStreamReplaysObservedFrameCorpus` replays the preserved
+Claude Code 2.1.263 frame shapes through the reply-only validator and fails when
+a recorded verdict moves. Neither it nor L20 proves:
+
+- compatibility with the installed provider, which only this canary observes;
+- value drift, because the corpus keeps top-level key shape and fills values
+  with placeholders;
+- acceptance of unknown frames or fields, which the closed vocabulary rejects
+  by design.
+
+L20 replays every corpus item whose verdict is `drop` through the production
+reply-only validator. Its Claude fixture reads the corpus at run time, emits each
+dropped side frame with its key set unchanged after init and before its startup
+result, and the scenario requires the emitted names to equal the corpus drop
+set. Those frames are key-shape placeholders, not model output. L20 does not
+emit the recorded real shapes the validator rejects today:
+
+- `result-success-25-keys`: the result allowlist lacks `origin`;
+- `system-init-allowlist-diff`: the init allowlist lacks `memory_paths` and
+  `terminal_slash_commands`.
+
+Shapes without preserved evidence are gaps, not corpus items, so neither the
+corpus nor L20 exercises them: `command_lifecycle`
+keys and values; a non-null assistant `context_management` value; `system`
+`thinking_tokens` frames; hook and user `tool_result` frames; the exact real init
+key set; nested values of every frame; `rate_limit_event` envelope keys beyond
+`type` and `rate_limit_info`; and earlier shape inventories, which were lost.