projmux 0.12.2 → 0.13.0

package/docs/upgrading.md

@@ -44,15 +44,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

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.0",
   "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.0",
+    "@projmux/linux-arm64": "0.13.0",
+    "@projmux/darwin-x64": "0.13.0",
+    "@projmux/darwin-arm64": "0.13.0"
   }
 }