projmux 0.12.2 → 0.13.1

package/docs/troubleshooting.md

@@ -0,0 +1,157 @@
+# Troubleshooting
+
+Start with read-only diagnostics:
+
+```sh
+projmux doctor
+```
+
+`doctor` never installs packages, rewrites configuration, or changes a tmux
+server. Run a remediation command only after reviewing the finding that
+recommended it. For the operational journal's privacy and retention contract,
+see [Operational Diagnostics](operational-diagnostics.md).
+
+## App socket marker migration
+
+Projmux 0.13 and newer require two server-global markers before an ordinary
+command may mutate the app tmux server:
+
+- `@projmux_app=1` declares app ownership.
+- `@projmux_socket_name=<name>` declares the logical `-L <name>` route.
+
+An app server started by a pre-0.13 release can still be live with the first
+marker and no logical marker. In that partial state, `shell`, attach, and
+materialization commands fail closed and print the exact recovery command.
+For the default app socket, run:
+
+```sh
+projmux config apply --socket projmux
+```
+
+This explicit apply keeps the live server and its sessions, binds `-L projmux`
+to one absolute socket path and server PID, sources the generated config,
+writes the missing logical marker, and verifies both markers against the same
+server generation. Ordinary commands do not write the marker. Apply also
+refuses a foreign server, a different existing logical marker, an alias/path
+mismatch, or PID drift; do not replace the refusal with a raw `tmux set-option`
+command.
+
+For a non-default socket, use the exact name printed by the failing command:
+
+```sh
+projmux config apply --socket <name>
+```
+
+Then retry the original command.
+
+## Diagnostic sequence
+
+Use this order so each step remains read-only until you deliberately run the
+recovery command:
+
+```sh
+projmux doctor --section runtime --verbose
+projmux diagnostics log
+tmux -L projmux show-options -gqv @projmux_app
+tmux -L projmux show-options -gqv @projmux_socket_name
+tmux -L projmux display-message -p -F '#{socket_path} #{pid}'
+```
+
+Replace `projmux` in all three tmux commands with the exact logical socket name
+you are diagnosing. Expected healthy marker output is `1` and that same socket
+name. The final read records the physical socket/PID pair for comparison; it
+does not grant authority or repair anything.
+
+The marker-specific Doctor codes map to these actions:
+
+| Code | Meaning | Remediation |
+| --- | --- | --- |
+| `runtime.route-marker.missing` | App-owned live server has no logical marker, normally after a pre-0.13 live-server upgrade. | Run the exact `projmux config apply --socket <name>` printed by the failing ordinary command, then retry it. |
+| `runtime.route-marker.mismatch` | The app-owned server declares a different logical route. | Do not overwrite it. Inspect the diagnostic sequence and confirm which `-L` route owns the server. |
+| `runtime.route-marker.unreadable` | Doctor could reach the socket but could not read one or both ownership markers. | Inspect `projmux diagnostics log`, tmux/socket permissions, and the exact marker reads. Do not apply until the read failure is understood. |
+
+Other runtime Doctor codes use bounded remediation identifiers in text and
+JSON:
+
+| Code family | Remediation |
+| --- | --- |
+| `runtime.socket.unreachable` | Start the app with `projmux shell`; if a server should already exist, inspect the exact socket first. |
+| `runtime.socket.probe-failed`, `runtime.backend.unknown` | Inspect `projmux diagnostics log` and the operational journal. |
+| `runtime.config.generated-missing`, `runtime.config.generated-invalid` | Run `projmux config apply --socket <name>` after confirming the target server. |
+| `runtime.config.generated-unreadable` | Inspect config and directory permissions before applying. |
+| `runtime.config.applied-stale` | Run the exact config apply command to reload the generated config. |
+| `runtime.config.applied-unknown` | Start or identify the app runtime before attempting a reload. |
+| `logs.*` | Follow the finding's `inspect-state-permissions`, `inspect-log-permissions`, or `inspect-operational-journal` remediation. |
+| `registry.materialize.*` | Inspect the reported Registry topology. Doctor is read-only and does not repair it. |
+
+Informational `*.ready`, `*.current`, `*.reachable`, `*.none`, `*.clean`, and
+`*.audited` codes need no remediation. JSON exposes the same `code` and
+`remediation` values as verbose text.
+
+## Codex app-server install topology
+
+Start with the read-only integration report:
+
+```sh
+projmux doctor --section integrations --verbose
+```
+
+The `Codex app-server` result keeps four readiness axes separate:
+
+- `Endpoint readiness` says whether the existing endpoint is ready, dead, or
+  failed with a bounded reason.
+- `running executable` plus the sanitized version fields distinguish a proven
+  managed executable from unknown identity and current from skewed versions.
+- `manager ownership` comes only from the official daemon backend result; an
+  absent or unclear result is never guessed from endpoint health.
+- `remote control` independently reports disabled, connecting, connected,
+  errored, unsupported, unavailable, or unknown.
+
+`Source`/`reason`, `App-server probe`, `install capability`, and `lifecycle`
+remain separate supporting fields. A ready endpoint therefore does not hide an
+unmanaged process or version skew.
+
+`external-cli-only` means the ordinary Codex CLI executable is present, but
+the canonical managed payload needed by `codex app-server daemon start` was not
+observed. It does not mean the ordinary CLI is unsupported and does not prove
+who owns a running process.
+
+An explicit native action refuses a ready unmanaged or version-skewed endpoint.
+The refusal reports `shared-clients-disconnect`: replacing this shared process
+can interrupt every attached Codex client. For a managed skew, confirm the
+interruption and run `codex app-server daemon restart`. For an unmanaged
+endpoint, close every sharing client, stop the process through the operator
+that owns it, then run `codex app-server daemon start`. Projmux never performs
+those stop/restart steps or invents an ownership-specific kill command.
+
+If native app-server features are needed, review the
+[official Codex CLI installation options](https://learn.chatgpt.com/docs/codex/cli)
+and install or repair the managed standalone payload. Then rerun Doctor. Do not
+copy binaries, create symlinks in the Codex home, or edit the control socket as
+a diagnostic workaround. Doctor, Settings, and support-report collection never
+start the daemon or modify the installation.
+
+## Incomplete npm install
+
+If the npm shim exits before Projmux starts with:
+
+```text
+projmux: unsupported or incomplete npm install for <platform>/<arch>.
+Expected optional dependency @projmux/<platform>-<arch> to provide bin/projmux.
+```
+
+the platform-specific optional package is missing. This can happen when npm
+reuses stale package metadata or optional dependencies were disabled. Because
+the Go binary is absent, `projmux doctor` cannot run yet. Re-resolve the current
+release and its optional dependency:
+
+```sh
+npm cache verify
+npm install -g projmux@latest --include=optional
+projmux version
+projmux doctor
+```
+
+If the same error remains, remove the incomplete global package, refresh npm's
+package metadata, and reinstall. Do not copy a binary from another platform.
+GitHub Release and source alternatives are documented in [Install](install.md).

package/docs/upgrading.md

@@ -1,5 +1,11 @@
 # Upgrading
 
+If an older live app server refuses ordinary commands after upgrading, or npm
+cannot resolve the platform optional dependency, follow
+[Troubleshooting](troubleshooting.md). The canonical marker recovery is the
+exact `projmux config apply --socket <name>` printed by the refusal; ordinary
+runtime commands never backfill missing markers.
+
 projmux has two update surfaces:
 
 - `projmux shell` reads the cached release status before opening the app. When
@@ -25,7 +31,9 @@ projmux update apply
 Use `--dry-run` to see the planned action and `--no-apply` to skip reloading
 the live tmux config after the binary changes. `--no-apply` suppresses live
 tmux access only; the new binary still migrates the keymap schema and
-marker-owned provider files, then writes the generated config. See
+marker-owned provider files, then writes the generated config. It finishes by
+printing `projmux config apply --socket projmux` as the explicit live
+convergence still required before ordinary mutation. See
 [Keymap schema migration](#keymap-schema-migration) and
 [Managed Agent hook producer migration](#managed-agent-hook-producer-migration).
 
@@ -44,15 +52,253 @@ still requires an explicit `PROJMUX_INSTALLER=github-release`.
 
 ## Behavior Changes
 
+### Registry schema v2 final Window anchors
+
+The unreleased intermediate schema-v2 Window field `primaryPaneRef` has been
+replaced by the final v2 shape:
+
+- `anchorPaneRef` is required and names a same-Window shell or managed Agent
+  Pane.
+- `defaultShellPaneRef` is optional; when present it names a direct
+  Window-owned shell Pane.
+
+The on-disk `schemaVersion` remains `2` because the intermediate shape was not
+published. A schema-v1 Registry migrates directly to these fields. An
+intermediate-v2 Registry is identified by raw field presence and normalized
+under the Registry lock. The migration publishes an exact mode-0600 backup and
+a checksum/repair report before staging and atomically replacing the Registry.
+Mixed legacy/final fields, mixed Window authorities, dangling or cross-Window
+anchors, and invalid default shells fail closed without changing the source.
+Repeating migration on final-v2 is a byte-level no-op.
+
+The final writer never emits `primaryPaneRef`. A matching intermediate
+pre-release validator therefore sees final-v2 as invalid because its required
+legacy authority is absent. Not every old read surface necessarily runs that
+validator: an old command may ignore the new fields and return a partial view.
+That is evidence of incompatibility, not permission to proceed. Operators must
+refuse a binary-only downgrade before installation and must not permit the old
+binary to write final-v2 bytes. To roll back during the prerelease window, stop
+the final writer, restore the exact pre-normalization Registry backup, and
+restore the matching intermediate binary as a pair. Snapshots are not migration
+or rollback inputs and are never rewritten by this normalization.
+
+Rollback rehearsal is byte-oriented: record the backup path, mode, SHA-256,
+and matching pre-release binary revision; stop every final-v2 writer; atomically
+restore those exact intermediate-v2 bytes; verify their checksum; install the
+recorded matching binary; then run its read-only validation before permitting a
+write. Installing only the intermediate binary while leaving final-v2 Registry
+bytes in place is deliberately rejected and is not a rollback procedure.
+
+### `create` is resource-backed on every spelling
+
+**Breaking.** `create pane`, `create agent`, and the `create
+codex|claude|antigravity` shortcuts no longer have two product models behind the
+presence of `--project`. Previously an invocation *with* `--project` created
+Registry resources and materialized them detached, while an invocation *without*
+it ran a runtime-only split of the current tmux window that created no Projmux
+resource and moved the client. That second model is gone.
+
+What changes for an existing invocation:
+
+| Invocation | Before | Now |
+| --- | --- | --- |
+| `create codex --placement right` inside a managed Project | Runtime-only split of the current tmux window; no Registry resource; the client followed the new pane | Creates an Agent and its managed Pane below the **active managed Project's active Window**, anchored on the active Pane, materialized detached; the client does not move |
+| `create codex -w hi --create-window` | `flag provided but not defined: -w` | Creates Window `hi` under the active managed Project, then the Agent and its managed Pane inside it |
+| `create pane --placement down` inside a managed Project | Runtime-only shell split | Creates a Pane resource below the active Window and splits it detached |
+| Any `create` inside Home, a control session, an unattributed or foreign pane | Runtime-only split | Exit `2` naming `--project`, with zero Registry writes and zero tmux mutations |
+| Any `create` from outside tmux with no `--project` | Runtime-only split against the default server | Exit `2` naming `--project`; no server is probed |
+| Any `create` with an explicit `--project` | Resource-backed | Unchanged |
+| `create pane -o uid\|name\|ref\|metadata\|json` with no `--project` | Exit `2` saying the compatibility split creates no resource | Works: the projections resolve the created resource |
+
+Two consequences are worth calling out:
+
+- **The client no longer follows the new pane.** Every create is detached. Use
+  `projmux focus pane uid:<uid>` — or `-o pane-id` and your own `select-pane` —
+  when you want to move there.
+- **Panes created this way are now managed.** They appear in `get panes`,
+  in the primary navigation surface, and in `reconcile resources`. Nothing
+  adopts the runtime-only panes created by older releases; they stay visible in
+  the Runtime diagnostics surface and are never imported automatically.
+
+The default keybindings whose bodies are `create codex|claude|pane --placement
+right|down` keep their spelling and their "split where I am" meaning, and now
+produce Registry resources. `internal agent-pane launch-default` — the saved
+default split mode, bound to Ctrl-Shift-R/L in the terminal adapters — kept its
+spelling and its meaning, and now produces the same Registry resources: see
+[Every split surface is Registry-first](#every-split-surface-is-registry-first).
+
+The generated tmux config changed shape to support that. Every projmux
+`run-shell` binding is now rendered as `run-shell "TMUX_PANE=#{pane_id} <bin>
+..."`, because tmux exports `$TMUX` to a `run-shell` child but never
+`$TMUX_PANE`, and without the exact pane a binding cannot tell where it was
+pressed. `projmux config apply` — which `make install` and `projmux update
+apply` run for you — rewrites the generated file. If you hand-copied a projmux
+`run-shell` line into your own `~/.tmux.conf`, add the same prefix.
+
+If you need a raw, unmanaged tmux split, use tmux itself (`split-window`).
+projmux does not spell that as a resource verb.
+
+### Every split surface is Registry-first
+
+The saved-default split binding, the `Alt-7` provider picker, and the resume
+picker used to open a pane by calling tmux's `split-window` directly. Those panes
+were runtime-only: no uid, no owner Window, no Agent row, and no row in `get
+panes` or the primary navigation surface. They now go through the same canonical
+`create` route the `create codex|claude|pane` bindings and typed commands use, so
+every pane a Projmux surface opens is a managed resource.
+
+What changes for you:
+
+- **Panes from the picker and the saved default are managed.** They appear in
+  `get panes`, `get agents`, the primary navigation surface, and `reconcile
+  resources`, and they are deleted with `projmux delete pane|agent`. Panes those
+  surfaces created in older releases are not adopted; they stay visible in the
+  Runtime diagnostics surface.
+- **A launch needs a resolvable Project.** These surfaces create resources, so
+  they follow [Create scope](cli-guide.md#create-scope) like any other create. A
+  UI action taken outside a managed Project fails with the same
+  `pass --project <ref>` guidance instead of opening an unmanaged pane.
+- **The legacy `ai split` route is gone**, along with its `--agent`,
+  `--force-agent`, and `--print-pane-id` flags. The `ai` root itself was retired
+  earlier; nothing reaches that handler now. Automation that wants the new pane's
+  handle uses `-o pane-id` on a canonical create — see
+  [AI Agent Shortcuts](ai-agent-shortcuts.md).
+- **The AI title watcher no longer starts automatically.** The canonical create
+  route never started it, and these surfaces now behave the same way. Pane
+  titles, topics, and status come from provider hooks and from `projmux agent
+  topic`. `projmux internal agent-hook watch-title` still exists for the hook
+  contract.
+
+If you need a raw, unmanaged tmux split, use tmux itself (`split-window`).
+
+### One lifecycle trigger route
+
+The generated tmux config used to install two lifecycle routes: `internal tmux
+reconcile-bindings` on `after-new-window`/`after-split-window`, and `internal tmux
+release-dead-agent-panes` on `pane-exited`/`after-kill-pane`. Both answered the
+same question with a different subset of one reconciliation, so a pane exit
+inside a session that had also just gained a window paid for two registry
+transactions to reach the state one pass reaches.
+
+All four hooks now invoke one hidden route, `internal tmux converge
+--socket-path <path> --session <id> --reason <config-apply|runtime-created|runtime-exited>`,
+and so does `projmux config apply`. At most one convergence worker runs per exact
+tmux server, so a burst of hooks costs one pass instead of one per event. Which
+hooks each config installs is unchanged: the app config carries all four, and the
+standalone snippet carries the two pane-exit hooks only, so a raw `new-window` in
+a session projmux does not own still stays unmanaged.
+
+`projmux config apply` — which `make install` and `projmux update apply` run for
+you — rewrites the generated file. A tmux server still holding config from an
+older binary keeps invoking the two retired routes, which now fail; the hooks
+guard every invocation with `>/dev/null 2>&1`, so nothing surfaces, and the next
+`config apply` replaces them. If you hand-copied a projmux `set-hook` line into
+your own `~/.tmux.conf`, re-copy it from `projmux config render standalone`.
+
+### Discovery no longer registers Projects
+
+**Breaking.** A directory found under a discovery root used to become a Registry
+Project on its own. Any mutation route ran a reconcile prelude that walked the
+configured workdirs and registered every child it did not recognize, so a single
+`projmux create pane` in one repository could add a Project for every sibling
+directory beside it. Scanning a directory is now a scan and nothing else.
+
+Three collections, three authorities:
+
+| Thing | What it is | What it is not |
+| --- | --- | --- |
+| Workdirs / `PROJMUX_MANAGED_ROOTS` / `PROJMUX_PROJDIR` | Scan roots to look inside | Not a statement that anything inside them is a Project |
+| A discovered child | An unregistered candidate | Not managed identity, however often it is scanned |
+| A Registry Project | Managed identity, with a stable uid | Not derived from a path, a name, or a scan |
+
+What registers a Project now:
+
+```sh
+projmux create project --root /abs/path/to/repo
+```
+
+…or opening that one candidate from the Projects sidebar, which performs the same
+registration for that exact path. Both are idempotent: a root an existing Project
+already claims writes nothing at all. Sibling candidates under the same discovery
+root stay unregistered.
+
+What changes for an existing invocation:
+
+| Invocation | Before | Now |
+| --- | --- | --- |
+| `create window --project <name>` where `<name>` is a discovered-but-unregistered directory | The reconcile prelude registered it (and every other discovered child) first, then the create succeeded | Exits non-zero naming the exact `--root` to register, or open it once from the sidebar |
+| Any mutation route, with N children under a scan root | Up to N Projects appeared | Zero Projects appear |
+| `switch open <unregistered directory>` | Opened a session; the Project appeared later, as a side effect of some unrelated mutation | Registers that one path, then opens it exactly as before |
+
+If you relied on the old behavior to populate the Registry, register the roots
+you actually want once:
+
+```sh
+for root in ~/src/*; do projmux create project --root "$root"; done
+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:
+
+```text
+projmux-pins v2
+project proj-kwo4qozry2sr2ycij2g45zyvam
+candidate /home/dev/src/scratch
+```
+
+A `project` pin references a Registry Project uid; its displayed root and name
+are projected from the Registry on every read, so the pin survives a rebind, a
+rename, and a missing root. A `candidate` pin references a path that no Project
+claims and stays a path.
+
+Nothing migrates behind your back. Reads project a pre-v2 file in memory, so the
+sidebar looks the same before and after; the file is rewritten only when you ask:
+
+```sh
+projmux pin project migrate --dry-run   # report only
+projmux pin project migrate             # store the typed form
+```
+
+Per line, migration has exactly three outcomes:
+
+| Registry Projects claiming the path | Result |
+| --- | --- |
+| exactly one | becomes that Project's `project <uid>` pin |
+| none | stays a `candidate <path>` pin |
+| two or more | the **entire** migration is refused; the pin file and the Registry keep their bytes, and the message names the repair |
+
+Repair an ambiguous pin with `projmux rebind project` so one Project claims the
+path, or pin the Project you meant directly with `projmux pin project add
+uid:<uid>`, then re-run the migration. A corrupt file, or one written by a newer
+projmux, is refused rather than partially read.
+
+`pin project add|remove|toggle <dir>` is unchanged in argv and now resolves to a
+typed pin under the same rule (one Project → managed, none → candidate, more than
+one → refused). `pin project list` gained a kind column and a `--kind
+project|candidate` filter; the first mutation after an upgrade migrates the file
+first, so it can refuse for the reasons above.
+
+Settings > Projects shows the three collections separately: **Additional
+discovery roots** (scan roots), **Pinned Projects** (managed, by uid, with rebind
+and unpin), and **Candidate Pins** (unregistered paths, with register and unpin).
+On Windows the discovery roots stay OS-native paths; drive-letter, case, and
+separator differences are folded only when matching a candidate or migrating a
+legacy pin, never to mint or merge a Project uid.
+
 ### Legacy compatibility routes removed
 
 This release removes the human-facing compatibility argv and old
 pre-namespace internal aliases listed in the [retirement ledger](legacy-cli-retirement.md).
-Removed public argv exits 2 with its exact canonical replacement, no stdout,
-and no side effect. Removed internal aliases (`tmux`, `status`, `statusbar`,
-`preview`, `session-popup`, `key-broker`, and `popup-wait-key`) are unknown
-top-level commands and exit 1. Use `internal ...` for generated plumbing and
-`config render|apply` for public configuration work.
+Rejected compatibility argv below a surviving mixed root exits 2 with its exact
+canonical replacement, no stdout, and no side effect. Fully removed human roots
+(`current`, `kill`, `notify`, `sessions`, `session-state`, `tag`, `upgrade`, and
+`usage`) and removed internal aliases (`tmux`, `status`, `statusbar`, `preview`,
+`session-popup`, `key-broker`, and `popup-wait-key`) are unknown top-level
+commands and exit 1. Use `internal ...` for generated plumbing and `config
+render|apply` for public configuration work.
 
 The mixed roots retain only `attach project`, `focus project|window|pane`, `pin
 project`, and `prune project|snapshot`. Shortcuts and singular/plural resource
@@ -300,10 +546,17 @@ npm install -g projmux
 For npm-managed installs, `projmux update apply` runs:
 
 ```sh
+<current-projmux> config apply --bin <published-projmux> --socket projmux
 npm install -g projmux@latest
 projmux config apply
 ```
 
+The first apply must succeed before npm publication begins. The final apply is
+post-publication verification by the new binary. Go, GitHub Release, and source
+`make install` use the same pre-converge → publish → verify contract. A failed
+pre-apply prevents publication; a publication or verification failure returns
+non-zero and prints the exact `projmux config apply --socket projmux` recovery.
+
 `npm install -g projmux@latest` is used instead of `npm update -g projmux`
 because `npm update -g` honors the installed semver range and frequently
 refuses to move a global install across a newer minor/major release, leaving it
@@ -326,9 +579,10 @@ projmux update apply --no-apply  # migrate + write config, skip the live reload
 projmux update apply --dry-run   # print the steps only
 ```
 
-`projmux update apply` reinstalls via `go install`, atomically replaces the active
-file, and reapplies the live tmux config so a running `-L projmux` server picks
-up new bindings without a restart.
+`projmux update apply` first converges the live route with the current binary
+and exact eventual executable path, reinstalls via `go install`, then reapplies
+with the published binary so a running `-L projmux` server picks up new bindings
+without a restart.
 
 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
@@ -347,8 +601,9 @@ PROJMUX_PROJDIR="/main/repos:/secondary/repos" projmux update apply
 
 When `PROJMUX_INSTALLER=github-release`, `projmux update apply` downloads the
 latest matching `projmux_<version>_<goos>_<goarch>.tar.gz` asset from GitHub
-Releases, extracts the binary, atomically replaces the current executable, and
-then runs the new binary's `projmux config apply` — or `config apply --no-reload`
+Releases, extracts the binary, converges the exact live route, atomically
+replaces the current executable, and then runs the new binary's
+`projmux config apply` — or `config apply --no-reload`
 when `--no-apply` is set, so the keymap schema migration still happens.
 
 Set the installer explicitly if you manage a release binary outside npm or Go:

package/docs/usage-tracking.md

@@ -75,7 +75,31 @@ floor.
 
 ### Codex (`internal/core/usage/adapters/codex`)
 
-Local rollout JSONL parser. No network calls.
+The native Codex app-server account API is primary:
+
+- An explicit `projmux agent usage` request reuses the app-server
+  ensure-ready lifecycle, then opens one initialized official stdio-proxy
+  connection and calls `account/rateLimits/read` with a bounded deadline.
+  Automatic HUD refreshes probe/read an already-running daemon but do not gain
+  daemon-start authority.
+- When `rateLimitsByLimitId` is present it is the authoritative multi-bucket
+  view; the backward-compatible `rateLimits` mirror is not duplicated. Each
+  bucket preserves its map key, nullable `limitId`, nullable `limitName`,
+  primary/secondary slot, percentage, nullable reset, and nullable cadence.
+  `300` and `10080` minutes project to `5h` and `weekly`. Missing or unknown
+  positive cadences remain lossless `quota` rows instead of disappearing.
+- `account/rateLimits/updated` is merged sparsely into the just-read native
+  snapshot during one bounded event-settle window. Null account metadata does
+  not clear a prior label or identity. The event-refreshed rows then use the
+  same Manager throttle, replace, store, and last-known-good path as a read.
+- Validation is row-level. A malformed bucket/window is dropped with a bounded,
+  field-only warning while valid siblings remain native. Native and rollout
+  rows are never combined in one invocation.
+
+When app-server is unavailable, unsupported, disconnected, timed out, or the
+account exposes no supported rate-limit bucket (including API-key-style
+accounts), the adapter invokes the existing newest-rollout collector exactly
+once without attempting login, logout, token refresh, or config writes:
 
 - Walks `${HOME}/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl`
   newest-first by mtime (NOT filename — Dropbox-synced rollouts can
@@ -99,8 +123,10 @@ Local rollout JSONL parser. No network calls.
   dropped and reported rather than projected as a genuine `0%`.
 
 Codex shares the manager's default `30s` throttle (no
-`ThrottleHinter`). It does not implement `BackoffStater` — local-only
-read.
+`ThrottleHinter`) and does not implement `BackoffStater`. A successful
+rollout fallback row records `source=rollout` plus the closed fallback reason.
+If neither lane produces rows, Manager preserves the previous source/value and
+adds a closed `stale_reason` to the last-known-good row.
 
 ### Antigravity (`internal/core/usage/adapters/antigravity`)
 
@@ -163,13 +189,17 @@ For `--model all`, calls `Manager.Collect` (or `ForceCollect` with
 Enabled agents, filters by window, and renders the tab-aligned table:
 
 ```
-MODEL        WINDOW                 PCT  RESETS_AT                 RESET_IN  STALE
+MODEL        WINDOW                 PCT  RESETS_AT                 RESET_IN  STALE  SOURCE      REASON
+codex        5h/codex · General     12%  2026-05-07T14:00:00+09:00 -         app-server
 claude       5h                     80%  2026-05-07T14:00:00+09:00 -
 antigravity  quota/gemini-weekly    6%   2026-07-06T16:50:32+09:00 560580s
 claude       quota/group-redacted · Model Redacted Alpha  38%  2031-02-03T15:05:06+09:00  -  *
 ```
 
-`STALE` is `*` when `now - UpdatedAt > 10m`. A `--json` payload returns
+`SOURCE`/`REASON` are included when source-aware rows are present. Native
+Codex rows report `app-server`; fresh rollout fallback and retained
+last-known-good rows report their closed fallback/stale reasons. `STALE` is
+`*` when `now - UpdatedAt > 10m`. A `--json` payload returns
 the `Snapshot` array; if any adapter is in backoff, the wrapper
 `{snapshots, backoff: {model: {until, consecutive}}}` is emitted
 instead. A backoff note is appended to the human table:
@@ -215,6 +245,17 @@ excluded; only its aggregate official `5h` and `weekly` rows reach the HUD.
 The Settings provider list consumes `aiprovider.UsageSupported()` order, but a
 window toggle exists only when this same projection seam declares it. A future
 provider or an opaque bucket cannot manufacture a window row.
+For native Codex multi-bucket rows, the exact `codex` bucket wins the HUD
+projection, then the legacy empty bucket, then lexical bucket order. The HUD
+compact identity is derived from that same row: a healthy authoritative
+`app-server` row is simply `Codex`, a fresh rollout row is
+`Codex [fallback]`, and a retained last-known-good row is `Codex [stale]`.
+Blank, malformed, or future non-stale provenance also fails conservatively to
+the existing `[fallback]` identity rather than looking native or expanding the
+compact vocabulary. The exact raw source and closed fallback/stale reason stay
+in `agent usage --model codex` table/JSON output and in
+`projmux diagnostics log --component usage`; compact labels never replace
+those fields.
 
 Settings > Appearance > Status Bar > Agent Usage HUD can hide the whole HUD,
 a provider, or one supported window. Parent off states preserve child saved
@@ -250,8 +291,10 @@ The `~` / `~~` markers are the legacy stale vocabulary, carried inside the
 indicator while the age text is still rendered and glued to the label once the
 drop order has shed it. Staleness stays muted however far the segment has
 degraded: warning and critical colors are reserved for usage thresholds, not
-cache age. Codex opts out of the indicator because the rollout file is always
-near-current (no throttle gap to report).
+cache age. A healthy Codex row does not need a cosmetic age indicator, while a
+retained Codex last-known-good row opts in and carries the compact `[stale]`
+identity. Its exact closed stale reason remains available on the full table,
+JSON, and diagnostics surfaces.
 
 The statusbar usage **popup**'s sync line is a different surface with a
 different meaning (last successful collect, 60s amber threshold) and is
@@ -284,10 +327,13 @@ When a collection fails, the failure is visible in three places:
    projmux diagnostics log --component usage --tail 20
    ```
 
-   The row carries the provider and a closed failure enum and nothing else:
+   The row carries the provider and closed source/failure enums and nothing else:
    `collect-failed` (whole-adapter failure, `level=error`) or `rows-skipped`
-   (partial failure, `level=info`). A successful collection writes no row at
-   all. Identical `(provider, failure)` tuples are recorded at most once per
+   (partial failure, `level=info`). 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
+   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
    repeating failure cannot flood the bounded journal. Journal writes are
    best-effort and never change what the usage command returns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.12.2",
+  "version": "0.13.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.12.2",
-    "@projmux/linux-arm64": "0.12.2",
-    "@projmux/darwin-x64": "0.12.2",
-    "@projmux/darwin-arm64": "0.12.2"
+    "@projmux/linux-x64": "0.13.1",
+    "@projmux/linux-arm64": "0.13.1",
+    "@projmux/darwin-x64": "0.13.1",
+    "@projmux/darwin-arm64": "0.13.1"
   }
 }