projmux 0.7.1 → 0.7.2

package/README-ko.md

@@ -66,6 +66,7 @@ projmux shell
 - `Alt-4`: AI split picker.
 - `Alt-5`: settings.
 - `Alt-6`: project switcher popup.
+- `Alt-7`: AI resume session picker.
 
 전체 key map은 [Terminal Keybindings](docs/keybindings.md)를 참고하세요. 키가
 동작하지 않으면 tmux 밖에서 `projmux setup`을 실행한 뒤,

package/README.md

@@ -74,8 +74,10 @@ Inside the app:
 - `Alt-3` opens Recent Windows.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens settings.
+- `Alt-7` opens the AI resume session picker.
 
-Those five launch keys are the guaranteed zero-config defaults. Add more
+The `Alt-1` through `Alt-5` launch keys are the guaranteed zero-config
+defaults. Add more
 aliases in Settings > Keybindings or `~/.config/projmux/keymap.toml`. If a key
 does not fire, run `projmux setup` outside tmux, then use
 `projmux init [terminal] --apply` for supported terminal delivery fallbacks.

package/docs/agent-workflow.md

@@ -40,7 +40,7 @@
 - `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.
-- `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
+- `make test` also covers direct `projmux ai split --agent <claude|codex|antigravity|shell|selective|resume>` launches, enabled-agent gating for disabled direct launches and disabled saved defaults, `--force-agent` as an explicit direct CLI-only override, selective picker filtering with all-disabled shell fallback guidance, resume picker routing/New delegation/zero-session fallback/Phase 1 fresh fallback contract, config-default preservation, extra args appended to resolved agent executables, managed pane metadata, title watcher startup, layout application, plain shell split behavior, selective picker delegation, invalid direct-agent usage errors, and regressions that direct concrete-agent and saved-default splits create a new pane without probing existing AI pane metadata or selecting an existing pane, including when launched from the current AI pane.
 - `make test` also covers Settings IA regression guards for `send-noti` visibility in Hooks, no nested Project recipe inside Hooks, Project recipe/AI/Labs view-first detail rows, Appearance Path/Git/Notify icon direct off/symbol/emoji preview selection with no Change page, Notifications root/Desktop notifications/Delivery sources relocation, localized Korean Desktop notifications root/detail chrome without visible English residue, Delivery sources command-row clipboard copy, and Labs Project Hooks overview-first rows.
 - `make test` also covers AI desktop notification dedupe precedence (env override > Settings saved value > default), Desktop notifications mode persistence through `desktop-notify-mode`, saved-config precedence over live tmux options, `projmux tmux apply` regeneration of `@projmux_desktop_notify_mode`, configured dedupe-window collapse/send behavior, Settings > Notifications AI dedupe preset/custom rows, explicit notify focus consume rules for selected critical rows and older same-pane non-critical AI cleanup, preservation of critical/permission/stop-failure/external/git/k8s rows during bulk cleanup, OS Toast click-to-focus queue consume, WSL Toast protocol handler hidden-launcher registration with `wsl.exe --exec` URI forwarding, and attention clear paths that do not ack the queue.
 - `make test` also covers AI hook runtime action precedence over catalog defaults, runtime quiet for known Codex notify events, runtime notify for known Claude quiet events, generic in-app-only notify rows for known Codex hook events without specialized handlers, suppression of desktop notification and `send-noti` dispatch on that generic path, separation of runtime hook action from catalog install events, Settings > Notifications hook quiet policy display/write behavior without external install/remove execution, hook desktop notification payload parity with the in-app queue text across the shared OS notification payload, normal/transient OS urgency and expiration for critical AI queue rows, and dormant title/capture fallback gating once a pane is hook-active.

package/docs/ai-agent-shortcuts.md

@@ -66,10 +66,13 @@ without a tail:
 ```sh
 projmux ai split --agent shell right
 projmux ai split --agent selective down
+projmux ai split --agent resume right
 ```
 
 `shell` opens a plain shell split. `selective` opens the existing picker, where
-the user chooses the launch mode interactively.
+the user chooses the launch mode interactively. `resume` opens the current
+project's resume-session picker; when no sessions exist it delegates to the
+same selective picker.
 
 ## Naming Pattern
 
@@ -88,6 +91,8 @@ Concrete examples:
 ```text
 $projmux-codex-right
 $projmux-claude-down
+$projmux-resume-right
+$projmux-resume-down
 ```
 
 For Claude-style slash-command surfaces, names can follow:
@@ -102,6 +107,8 @@ Concrete examples:
 ```text
 /projmux:codex-right
 /projmux:claude-down
+/projmux:resume-right
+/projmux:resume-down
 ```
 
 The same pattern also works for editor commands, launcher actions, shell
@@ -120,6 +127,7 @@ For Codex-style skill surfaces:
 ```text
 $projmux-codex      → projmux ai split --agent codex right
 $projmux-claude     → projmux ai split --agent claude right
+$projmux-resume     → projmux ai split --agent resume right
 ```
 
 For Claude-style slash-command surfaces:
@@ -127,6 +135,7 @@ For Claude-style slash-command surfaces:
 ```text
 /projmux:codex      → projmux ai split --agent codex right
 /projmux:claude     → projmux ai split --agent claude right
+/projmux:resume     → projmux ai split --agent resume right
 ```
 
 Register the bare name as a thin alias of the `*-right` shortcut so that the
@@ -189,6 +198,26 @@ projmux ai split --agent claude down -- <agent flags>
 ```
 ````
 
+Resume picker examples:
+
+```text
+~/.codex/skills/projmux-resume-right/SKILL.md
+~/.codex/skills/projmux-resume-down/SKILL.md
+```
+
+````markdown
+---
+name: projmux-resume-right
+description: Open a projmux-managed AI resume-session picker to the right.
+---
+
+Run this command:
+
+```sh
+projmux ai split --agent resume right
+```
+````
+
 If your tool stores skills as JSON, TOML, or another format, keep the same
 fields conceptually:
 

package/docs/cli.md

@@ -259,10 +259,12 @@ Codex shares the global `30s`). `--json` emits the snapshot array; when
 backoff is active the wrapper `{snapshots, backoff}` object is emitted
 instead.
 
-Antigravity has no supported 5-hour/weekly quota adapter. `--model
-antigravity` renders an explicit unsupported note: the stable Antigravity
-signal is `context-window-only` statusline data, which is not mixed into the
-Claude/Codex quota HUD.
+Antigravity has no 5-hour/weekly quota contract, so it is surfaced
+`context-window-only`: the adapter emits a single `context` window row
+(context-window fullness, no `RESETS_AT`) sourced from the latest
+statusline `context_window` seen via hook ingest. `--model antigravity`
+renders that row; in the HUD it shows as `Antigravity ctx [bar] N%`
+alongside the Claude/Codex quota bars.
 
 ## status
 
@@ -340,8 +342,8 @@ supplied window.
 ## ai
 
 ```
-projmux ai split    [--agent <claude|codex|antigravity|shell|selective>] [--force-agent] [right|down] [-- <extra-arg>...]
-projmux ai picker   --inside <right|down>
+projmux ai split    [--agent <claude|codex|antigravity|shell|selective|resume>] [--force-agent] [right|down] [-- <extra-arg>...]
+projmux ai picker   [--inside] [--shell] [--resume] <right|down>
 projmux ai settings
 projmux ai status   set <thinking|waiting|idle> [--pane <id>]
 projmux ai notify   <reset|notify> [--pane <id>]
@@ -372,7 +374,8 @@ can still render a non-red action-required status badge.
 
 `ai split right|down` uses the configured default split mode. Add
 `--agent claude`, `--agent codex`, `--agent antigravity`, `--agent shell`, or
-`--agent selective` for a one-shot launch without changing that default.
+`--agent selective` for a one-shot launch without changing that default. Add
+`--agent resume` to open the current project's AI resume-session picker.
 Concrete `--agent claude|codex|antigravity` invocations create a new managed
 agent pane every time; existing managed AI panes in the same project/session are
 not selected or reused.
@@ -381,6 +384,11 @@ existing plain shell split. Arguments after `--` are extra arguments appended to
 the resolved `claude`, `codex`, or `agy` executable inside the managed wrapper;
 projmux still sets the context directory, tmux title, AI pane metadata, title
 watcher, and split layout.
+The resume picker lists the newest deduplicated Claude/Codex resume sessions
+for the current project, with `[+ New Session]` pinned first. If there are no
+resume sessions it goes straight to the existing selective picker. Phase 1
+captures the selected `(agent, resume id)` contract but still launches a fresh
+split; actual `claude --resume` / `codex resume` wiring is reserved for Phase 2.
 Settings > AI Settings > Enabled agents controls Claude/Codex/Antigravity launch
 visibility. Disabled agents are hidden from the selective picker and from the
 default-mode picker. A saved default that later becomes disabled fails clearly
@@ -467,9 +475,10 @@ Antigravity notify metadata uses `agent=antigravity`. Phase 3 session-state
 restore is included: Antigravity ingest stores `conversationId` as pane thread
 metadata for matching and as session-state resume metadata. Restore uses
 `agy --conversation <uuid>` when that id is present and UUID-shaped; otherwise
-session-state preview/doctor render `resume unavailable`. Usage quota HUD
-support remains unsupported because the only stable usage signal is
-`context-window-only` statusline data. Transcript contents are not read.
+session-state preview/doctor render `resume unavailable`. The statusline
+`context_window` value is persisted on ingest and surfaced by the usage HUD
+as a `context-window-only` row (Antigravity has no 5h/weekly quota contract).
+Transcript contents are not read.
 
 `ingest bell --pane <pane_id>` is the narrow tmux-bell fallback ingest path.
 It does not require the pane to be AI-managed. Projmux resolves session,
@@ -657,7 +666,8 @@ Helpers tmux's keybindings and the install pipeline call into. Modes
 accepted by `popup-toggle` mirror the historical sessionizer surface:
 `session-popup`, `sessionizer`, `sessionizer-sidebar`,
 `notify-sidebar`, `recent-windows`, `ai-split-picker-right`,
-`ai-split-picker-down`, `ai-split-settings`.
+`ai-split-picker-down`, `ai-split-resume-right`, `ai-split-resume-down`,
+`ai-split-settings`.
 `apply` regenerates the app tmux config and reloads the live `-L projmux`
 server without restarting it. `make install` and `projmux upgrade` invoke it
 after replacing the binary. Settings > Keybindings normally runs the same

package/docs/configuration.md

@@ -328,6 +328,50 @@ warning with the unsupported value and source.
 Project-local locale override is not part of the runtime policy. Locale is a
 user/global preference in this release.
 
+## AI Resume Picker
+
+The AI resume picker (`projmux ai split --agent resume`) lists the most recent
+deduplicated Claude/Codex resume sessions. The number of rows it shows and how
+far below the current directory it scans are both configurable; the defaults are
+30 rows and depth 0 (the current directory only).
+
+Preferred interactive path:
+
+- `Settings > AI Settings > Resume picker`
+
+Config paths (global and project both honored):
+
+```text
+~/.config/projmux/config.toml      # global
+<project>/.projmux/config.toml     # project
+```
+
+Schema:
+
+```toml
+[ai]
+resume_picker_limit = 30 # 1-100; how many recent sessions the picker lists
+resume_scan_depth = 0    # 0-8; include sessions started in cwd child dirs
+```
+
+Resolution priority (each key resolves independently) is:
+
+1. `PROJMUX_AI_RESUME_PICKER_LIMIT` / `PROJMUX_AI_RESUME_SCAN_DEPTH`
+2. project `[ai]` key
+3. global/user `[ai]` key
+4. built-in default (`30` rows, depth `0`)
+
+`resume_picker_limit` is clamped to `1`-`100`; a missing or non-positive value
+falls back to the default. `resume_scan_depth` is clamped to `0`-`8`: depth `0`
+lists only sessions whose recorded working directory matches the current one
+(the historical behavior), while depth `N` also lists sessions started up to `N`
+levels below it — useful from a monorepo or parent directory. The match is a
+path-tree filter on each session's recorded cwd, so parent and sibling
+directories are never included. At depth `>0` the picker adds a relative-cwd
+column (`./`, `./web`, `./api`) so child-directory sessions are easy to tell
+apart. A missing or zero depth is identical to the historical behavior. Settings
+edits write the global config.
+
 ## Environment Variables
 
 | Variable | Purpose |
@@ -337,6 +381,8 @@ user/global preference in this release.
 | `TMUX_SESSIONIZER_ROOTS` | Legacy alias still honored at runtime for managed roots. |
 | `PROJMUX_LOCALE` | UI locale override. `auto` resumes detection; `en-US` and `ko-KR` pin supported locales. Unsupported tags fall back to `en-US` and surface a Settings warning. |
 | `PROJMUX_NOTIFY_HOOK` | External executable that receives AI desktop notifications instead of the built-in Linux/WSL sender. Separate from declarative `[hooks.send-noti]`. |
+| `PROJMUX_AI_RESUME_PICKER_LIMIT` | Overrides the AI resume picker row count (`[ai] resume_picker_limit`). Clamped to 1-100; takes priority over project and global config. |
+| `PROJMUX_AI_RESUME_SCAN_DEPTH` | Overrides the AI resume picker cwd-tree scan depth (`[ai] resume_scan_depth`). Clamped to 0-8; takes priority over project and global config. Depth 0 keeps the exact-cwd behavior. |
 | `PROJMUX_NOTIFY_HOOK_DEPTH` | Internal recursion guard for `send-noti` hooks. Depth `>= 1` suppresses nested hook dispatch while still allowing the queue write itself. |
 | `PROJMUX_NOTIFY_EXPIRE_MS` | AI desktop notification expiration in milliseconds. Defaults to `5000`; unset, zero, negative, and non-numeric values fall back to the default. |
 | `PROJMUX_DESKTOP_NOTIFY_MODE` | OS desktop notification mode override. `none` / `notify` / `raise` (case insensitive). When set, this takes priority over every other resolution rung. The in-app notify queue is not affected. |

package/docs/hooks.md

@@ -634,10 +634,11 @@ include `conversationId`/`conversation_id`, `cwd`, `workspace.path`,
 Antigravity ingest uses `conversationId` as pane thread metadata for matching
 and as session-state resume metadata. Session restore uses
 `agy --conversation <uuid>` only when that id is present and UUID-shaped;
-otherwise preview and doctor render `resume unavailable`. Antigravity usage
-quota HUD support remains unsupported because the stable usage signal is
-`context-window-only` statusline data, not 5-hour/weekly quota data. Raw
-payloads or transcript contents are not stored.
+otherwise preview and doctor render `resume unavailable`. The statusline
+`context_window` percentage is persisted to the usage state dir on ingest so
+the usage HUD can surface it as a `context-window-only` row — Antigravity has
+no 5-hour/weekly quota contract, so no quota bars are emitted. Raw payloads or
+transcript contents are not stored.
 
 ## Ingest Debug Log
 

package/docs/keybindings.md

@@ -2,7 +2,8 @@
 
 projmux is keyboard-driven, but the guaranteed launch contract is small:
 fresh installs bind `Alt-1` through `Alt-5` as plain Meta sequences
-(`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). Other actions remain discoverable in
+(`M-1`..`M-5`, bytes `\x1b1`..`\x1b5`). The AI resume picker ships with an
+editable `Alt-7` default. Other actions remain discoverable in
 Settings > Keybindings. Transport-dependent actions keep their built-in
 transport default key, and Settings can add separate safe tmux plain keys to
 the same action. They are not installed as terminal-specific User-key
@@ -84,6 +85,7 @@ Optional direct keys can be added for actions such as:
 | `RecentWindows:Open` | Recent windows queue across projects |
 | `ProjectSwitcherToggle` | Project switcher popup |
 | `AISplitPickerToggle` | AI split popup picker; pressing again closes the picker popup |
+| `AIResumePickerToggle` | AI resume session picker; default `Alt-7`; pressing again closes the picker popup |
 | `ai-split-right` | Open a new direct AI split to the right |
 | `ai-split-down` | Open a new direct AI split below |
 | `new-window` | New tmux window in the current pane directory |

package/docs/testing.md

@@ -97,6 +97,7 @@ Observe:
 - `Alt-3` opens Recent Windows.
 - `Alt-4` opens the AI split picker.
 - `Alt-5` opens Settings.
+- `Alt-7` opens the AI resume session picker.
 - Pressing the same launch key again closes the popup instead of typing escape
   bytes into the shell or picker input.
 

package/docs/usage-tracking.md

@@ -122,11 +122,12 @@ claude is in backoff, try again in 30m (use --force to bypass)
 
 When no AI agents are enabled, all-model table output contains no
 provider rows and prints a short Settings hint. `--json` returns an
-empty array. Explicit `--model claude` and `--model codex` bypass the
-enabled-agent filter for read-only inspection and collect/render only
-the requested adapter. Explicit `--model antigravity` renders the same
-unsupported/context-window-only note even when Antigravity is disabled, because
-there is no supported Antigravity quota adapter to collect.
+empty array. Explicit `--model claude`, `--model codex` and
+`--model antigravity` bypass the enabled-agent filter for read-only
+inspection and collect/render only the requested adapter. Antigravity
+exposes no 5h/weekly quota, so its adapter reports a single `context`
+window row (context-window fullness, no `RESETS_AT`) sourced from the
+latest statusline `context_window` observed via hook ingest.
 
 ### `projmux status usage`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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.7.1",
-    "@projmux/linux-arm64": "0.7.1",
-    "@projmux/darwin-x64": "0.7.1",
-    "@projmux/darwin-arm64": "0.7.1"
+    "@projmux/linux-x64": "0.7.2",
+    "@projmux/linux-arm64": "0.7.2",
+    "@projmux/darwin-x64": "0.7.2",
+    "@projmux/darwin-arm64": "0.7.2"
   }
 }