projmux 0.9.0 → 0.10.1

package/docs/legacy-diagnostics-inventory.md

@@ -0,0 +1,23 @@
+# Legacy diagnostics inventory
+
+This is the Phase 6 file/surface inventory. `Keep`, `Deprecate candidate`, and
+`Remove candidate` are review classifications, not runtime changes. Nothing in
+this phase removes, renames, ignores, or changes an environment variable, log,
+CLI, config action, output format, permission, or retention contract.
+
+| Surface | Producer / reader files | Current consumer and data boundary | Candidate and rationale | Separate follow-up |
+| --- | --- | --- | --- | --- |
+| `PROJMUX_USAGE_DEBUG` | `internal/app/usagecmd/usage.go`; adapter contract in `internal/core/usage/registry.go` and safe token helper in `internal/core/usage/adapters/claude/claude.go` | `projmux status usage` operator stderr; documented by `AGENTS.md`, `docs/configuration.md`, and `docs/usage-tracking.md`; `internal/app/usagecmd/usage_test.go` fixes the opt-in behavior; adapter errors are otherwise swallowed on the status hot path | **Keep.** Usage adapters are not adopted by the common journal and this opt-in stderr is the only immediate adapter failure consumer. | No removal follow-up. Re-evaluate only with a separately scoped usage diagnostics adoption. |
+| `PROJMUX_SESSIONSTATE_DEBUG` | read/output gate in `internal/app/tmux.go` | Operator/automation stderr for a quiet autosave error; documented in `docs/configuration.md`; tests in `internal/app/tmux_test.go` cover popup environment propagation | **Deprecate candidate.** Phase 3 already records the same quiet autosave failure as a closed common error, but scripts may consume stderr. | Yes: announce deprecation, audit scripts, and remove only in a breaking PR after a compatibility window. |
+| `PROJMUX_FOCUS_DEBUG` | read/output gate in `internal/app/focus.go` | Operator stderr one-line raw target/session/window/pane/socket/client/source/kind; documented in `AGENTS.md`, `docs/cli.md`, `docs/configuration.md`, `docs/operational-diagnostics.md`, and the maintained test list in `docs/agent-workflow.md`; `internal/app/focus_test.go` fixes the byte contract | **Deprecate candidate.** Phase 4 common focus events are safer for support, but the raw routing line remains a distinct local troubleshooting consumer. | Yes: publish safe replacement guidance and remove only through a breaking deprecation roadmap. |
+| `PROJMUX_NATIVE_DEBUG_LOG` | `internal/ui/picker/backend.go` and `colorgrid.go` append native picker actions/query/value/errors; `internal/app/tmux.go` inherits it into popup environments | Developer-selected file path; popup inheritance is covered in `internal/app/tmux_test.go`; no public CLI/support reader, retention bound, or privacy redaction | **Remove candidate.** The opt-in trace can contain user query/value/error text and is not bounded. Current behavior remains intact because a safe bounded replacement and migration notice are outside Phase 6. | Yes: design a bounded private picker trace or common closed events, document migration, then ship removal as breaking. |
+| bounded `ai-ingest.log` | Codex producer `internal/app/ai_ingest_codex.go`; Claude producer `internal/app/ai_ingest_claude.go`; Antigravity producer `internal/app/ai_ingest_antigravity.go`; tmux-bell producer plus shared `appendAIIngestLog`, path, cap, and trim in `internal/app/ai_ingest.go`; common projection in `internal/app/ai_ingest_diagnostics.go` | Detailed CLI reader `internal/app/ai_ingest.go` (`projmux ai ingest log`); count-only support reader `internal/app/diagnostics_report.go`; docs consumers `docs/cli.md`, `docs/hooks.md`, `docs/configuration.md`, `docs/operational-diagnostics.md`, and the maintained test list in `docs/agent-workflow.md`; `internal/app/ai_ingest_test.go`, `internal/app/ai_ingest_diagnostics_test.go`, `internal/app/diagnostics_report_test.go`, and `test/integration/linux-smoke.sh` cover retention/consumer/corrupt/permission behavior | **Deprecate candidate.** Phase 5 common events cover anomalous classification, but intentionally omit normal state/notify/quiet/dedupe detail and all identity. Removing the file now would break the detailed CLI consumer and measured parity. | Yes: define whether detailed normal-state diagnostics remain a product requirement, migrate or retire `ai ingest log` and support counts, announce a compatibility window, then use a breaking PR. |
+
+The separate host resource status path is not a legacy debug surface:
+`internal/app/status.go` invokes `internal/systemstatus.Sampler` for
+`projmux status resources`. It owns only host aggregate display/cache behavior,
+not pane/project attribution, and emits zero common resource events. The Phase
+6 Resource Inspector owner is `internal/app/resources.go` →
+`internal/app/resources_collector_linux.go` →
+`internal/integrations/tmux.ListResourcePanes` plus
+`internal/integrations/procfsresources.Collector`.

package/docs/native-picker.md

@@ -0,0 +1,103 @@
+# Native Picker
+
+The native picker is the product picker for every interactive selection flow.
+There is no runtime backend selection, saved picker selector, or external
+picker process. `internal/ui/picker` owns the interaction contract and
+`internal/ui/projmuxpicker` owns its visual composition.
+
+## Product Contract
+
+| Area | Behavior | Primary evidence |
+| --- | --- | --- |
+| Items and results | Structured items keep display labels, stable values, optional search text, multi-line metadata, and action results separate. `internal/ui/pickercompat` maps older internal option/result shapes into this contract; it is not a runtime backend. | `TestPickerOptionsFromCompatPickerMapsCandidatesWhenEntriesAreEmpty`; `TestPickerOptionsFromCompatPickerPreservesTheme` |
+| Search | Lower-case queries are case-insensitive, uppercase queries are case-sensitive, hidden values remain searchable when no explicit search key exists, explicit search-key lists preserve caller order, and simple rows receive fuzzy ranking and match highlighting. | `TestFilterItemsUsesSmartCase`; `TestFilterItemsSearchesHiddenValueWhenNoSearchKey`; `TestFilterItemsPreservesSearchKeyOrder`; `TestFilterItemsRanksBetterMatchesFirst` |
+| Navigation | Up/Down, Ctrl-J/Ctrl-N, and Ctrl-K/Ctrl-P wrap selection; PageUp/PageDown and Home/End clamp or jump; empty lists remain safe. Ctrl-N and Ctrl-P remain real navigation keys unless a caller claims the key as a custom action. | `TestNativeInteractiveSupportsControlNavigationKeys`; `TestNativeInteractiveWrapsPreviousNavigationKeys`; `TestNativeInteractiveWrapsNextNavigationKeys`; `TestNativeInteractiveNavigationKeysAreNoopForEmptyList`; `TestNativeInteractiveJumpNavigationRemainsClamped` |
+| Editing | Left/Right, Ctrl-A/E, Delete, Backspace, Ctrl-U/W, printable input, accept-query mode, and a visible query cursor are supported. | `TestNativeInteractiveEditsTypedQueryAtCursor`; `TestNativeInteractiveSupportsQueryLineEditingKeys`; `TestNativeInteractiveCtrlUDeletesBeforeCursor`; `TestNativeRunnerAcceptsTypedQuery` |
+| Actions | Enter accepts, shared close actions abort, printable/control expect keys return stable action keys, command actions can refresh previews, and mutable actions can update items without restarting the picker. | `TestNativeRunnerUsesSharedCloseActions`; `TestNativeInteractiveSupportsPrintableExpectKeys`; `TestNativeInteractiveRunsCustomActionCommandAndRefreshes`; `TestNativeInteractiveCustomActionMutatesItemsAndRefreshes` |
+| Deferred state | Deferred and event-triggered updates preserve query and selection by value, can repeat, and may explicitly choose a new focus value. | `TestNativeInteractiveDeferredUpdateTriggerRefreshesRepeatedly`; switch and notify sidebar mutable-refresh app tests |
+| Preview | Popup previews use a right split, sidebar previews use a bottom split, control bytes and tabs are normalized before clipping, and preview scrolling/cycling rerenders in place. | `TestNativeInteractiveRendersWidePreviewBesideList`; `TestNativeInteractiveRendersDownPreviewBelowList`; `TestRenderSplitPreviewRowsNormalizesPreviewTabsBeforeTruncating`; `TestNativeInteractiveRendersPreviewOffset` |
+| Mouse | SGR mouse input focuses on primary down, follows drag, accepts on matching release, and scrolls with the wheel. | `TestNativeInteractiveSelectsOnMouseRelease`; `TestNativeInteractiveMouseDragFollowsSelection`; `TestNativeInteractiveSupportsMouseWheelSelection` |
+| Lifecycle | Interactive runs use the alternate screen, synchronized/coalesced frame updates, controlling-TTY fallback, and deterministic reader cleanup. | `TestNativeInteractiveUsesAlternateScreen`; `TestNativeInteractiveWrapsRedrawsInSynchronizedUpdates`; picker/setup lifecycle tests in `docs/agent-workflow.md` |
+
+## Rendering And Popup Chrome
+
+The renderer owns rounded frames, optional titlebars and chips, search/header
+separators, footer placement, selected-row styling, proportional scrollbars,
+multi-line gaps, preview geometry, ANSI restoration, and terminal-cell width for
+CJK text, emoji, and combining marks. Frame-owned cells inherit the effective
+theme's `surface` and `chrome_foreground` values, including padding after
+embedded resets.
+
+Picker popups are always borderless tmux popups (`display-popup -B`) so the
+native renderer owns the visible frame. The popup body receives a per-command
+style derived from the effective theme; no global popup, pane, window, shell,
+or status style is mutated. Project sidebars use a `20%` width with a `40`
+column minimum, notification sidebars use `24%` with a `64` column minimum,
+and both reserve the two statusbar rows when client height is known.
+
+Primary evidence includes `TestAppRunTmuxPopupToggleUsesBorderlessNativePopup`,
+`TestAppRunTmuxPopupToggleUsesNativePopupBodyStyleFromGlobalTheme`,
+`TestBuildPopupToggleAppliesNativeBodyStyle`,
+`TestSessionizerSidebarWidthUsesCompactMinimum`,
+`TestNotifySidebarWidthUsesProductContract`, and
+`TestSidebarPopupHeightLeavesStatusbarRows`.
+
+## Fuzzy Scoring Provenance
+
+The native fuzzy scorer intentionally follows the fzf V2 dynamic-scoring
+algorithm for the maintained reference cases in `internal/ui/picker/backend_test.go`.
+`TestFuzzyScoreMatchesFZFV2ReferenceScores` and
+`TestFuzzyScoreRejectsFZFV2ReferenceNonMatches` are provenance fixtures; keep
+their expected scores stable when changing filtering internals.
+
+## Retired Artifact Contract
+
+The retired picker selector environment variable and saved selector filename
+are not runtime inputs. Their presence must not cause lookup, file reads,
+warnings, deletion, rewriting, propagation to child popups, or any change to
+the native path. There is deliberately no alias, migration, or stale-value
+cleanup behavior.
+
+Coverage is split by boundary:
+
+- `TestRunNativePickerOptionDoesNotObserveRetiredBackendArtifacts` guards the
+  direct picker path, fails if the retired env name is queried, and verifies a
+  stale file is neither deleted nor replaced.
+- `TestAppRunSwitchUsesNativePickerWithoutBackendLookup` guards the ordinary
+  switch flow.
+- `TestAppRunTmuxPopupToggleIgnoresRetiredBackendArtifacts` and
+  `TestBuildPopupTogglePropagatesNativePickerEnvironmentWithoutRetiredBackend`
+  guard popup chrome and child-environment construction.
+- `test/e2e/linux-smoke.sh` launches the ordinary attached-client Settings
+  popup with stale env/file values, completes the recorder flow, verifies the
+  file inode/content are unchanged, and rejects visible compatibility output.
+
+## Removed PoC Coverage Mapping
+
+The retired standalone dependency sandbox and focused smoke duplicated product
+coverage or tested a dependency policy that no longer exists. Its valid
+behavior assertions remain covered as follows:
+
+| Removed focused assertion | Maintained coverage |
+| --- | --- |
+| Settings and Labs render through the native picker | `TestSettingsUsesNativePicker`; `TestSettingsHubKeepsLabsSectionWithoutRetiredPickerChoices`; ordinary attached-client Settings recorder in `test/e2e/linux-smoke.sh` |
+| Search chrome, smart-case filtering, native frame ownership, and full-height rendering | `TestNativeInteractiveSeparatesSearchHeaderFromList`; `TestFilterItemsUsesSmartCase`; `TestNativeInteractiveRendersBorderFrame`; `TestNativeInteractiveUsesAvailableHeightForSimpleLists` |
+| AI Settings maps a typed selection to the saved mode | `TestAISettingsPickerSetsSelectedMode`; native picker option/result mapping tests |
+| Switch popup/sidebar filtering, selection, preview cycling, and initial focus | `TestAppRunSwitchDefaultsToPopupAndOpensSelectedSession`; `TestSwitchCommandSupportsSidebarUI`; preview cycle and initial-position tests in `internal/app/switch_test.go` |
+| Sessions popup filtering, selection, and preview cycling | `TestAppRunSessionsDefaultsToPopupAndOpensSelectedSession`; session popup preview/cycle tests in `internal/app/session_popup_test.go` |
+| Notification sidebar navigation and mutable actions | `TestNotifySidebarUsesNativePicker`; notify sidebar ack/clear/deferred-refresh app tests |
+| Launch-key close behavior and Ctrl-N/Ctrl-P navigation | `TestNativeInteractiveClosesOnMatchingLaunchCloseKey`; `TestNativeInteractiveSupportsControlNavigationKeys`; empty-list and wrap tests |
+| Mouse selection and alternate-screen restoration | native mouse and lifecycle tests listed above |
+| Generated shell config and the Alt-1 project-sidebar popup path | `TestShellWritesAppConfigAndRunsIsolatedTmux`; `TestAppRunTmuxPopupToggleOpensStandaloneSidebar`; popup frame/body-style tests listed above |
+| Stale selector values do not affect the product | retained and strengthened in the unit/app/e2e negative coverage listed in the previous section |
+
+The dependency-absence assertion is now a source-residue property rather than
+a separate container scenario: production code contains no selector, resolver,
+saved-selector access, propagation, or external picker launch path.
+
+## Maintenance
+
+Update this document and the maintained list in
+[`docs/agent-workflow.md`](agent-workflow.md) whenever picker behavior changes
+coverage level, gains a new product flow, or changes input/render/action
+semantics.

package/docs/operational-diagnostics.md

@@ -2,15 +2,19 @@
 
 Projmux records a small local-only operational journal so command failures and
 state changes can be inspected after the originating process exits. It does
-not upload the journal, create support archives, contact an issue tracker, or
-provide a background telemetry service.
+not upload the journal, contact an issue tracker, or provide a background
+telemetry service. A support archive is created only by an explicit
+`projmux diagnostics report` invocation and is never transmitted.
 
 ## Safe event contract
 
 Each JSONL record has a closed schema: `at`, `level`, `component`, `event`,
 `result`, `duration_ms`, `run_id`, `version`, `mux_backend`, and optional
 allowlisted `command`, `subcommand`, `kind`, and sanitized `message`. There is
-no generic metadata map.
+no generic metadata map. Runtime lifecycle records add only closed
+`operation` and `code` enums. The allowed operations are session create,
+attach, switch, kill, and tmux apply; codes are stable failure/health
+classifications and never carry routing identity or subprocess details.
 
 Command and subcommand names come from static allowlists. Unknown argv values,
 paths, flags, and arguments are dropped. Messages have control/format
@@ -25,6 +29,158 @@ pane captures/output/title/topic/content, transcripts, raw hook payloads,
 configuration secrets, or arbitrary environment values. Phase 0 also does not
 add session/window/pane or other routing identifiers.
 
+One explicit state-changing command owns at most one lifecycle pair. Its
+`lifecycle.start` and `lifecycle.outcome` share the process `run_id`, and a
+composite create-then-attach/switch flow keeps the first real mutation as its
+operation instead of recording nested outcomes. Lifecycle ownership replaces
+the generic top-level `command.outcome`; it never duplicates it. Start/outcome
+append failures are ignored and do not change the command result.
+
+Session State mutations use one outcome-only `session-state.outcome` record
+per selected attempt. The closed operations are `session-state.save`,
+`session-state.autosave`, `session-state.restore`, and `session-state.delete`;
+an error uses only the matching `.failed` code, `kind=runtime`, and an empty
+message. Optional sources are limited to `manual`, `settings-latest`,
+`settings-named`, `autosave`, `startup-latest`, `startup-named`, and `prune`.
+Successful save and actual startup restore outcomes contain only exact
+non-negative `window_count`, `pane_count`, `shell_recipe_count`,
+`agent_recipe_count`, and `startup_recipe_count` aggregates. Successful delete
+contains only `item_count`; errors contain no counts. Snapshot paths/content,
+project paths, pane cwd/commands, snapshot names, and agent or conversation
+identifiers are never projected.
+
+Direct and popup save, Settings latest/named save, direct and Settings delete,
+deduplicated prune delete, and actual latest/named project-startup replay own
+these outcomes. Preview, dry-run, and nested store/replay calls do not.
+Autosave success and disabled, not-due, or fresh no-ops always write zero
+records; a real autosave failure writes exactly one error even when `--quiet`
+preserves its historical successful exit. Session State logical ownership
+suppresses a generic top-level outcome even when journal append fails. An
+actual restore may also produce its runtime lifecycle pair with the same run
+ID; the lifecycle pair and Session State terminal outcome describe different
+contracts and are not duplicates.
+
+Notify and focus transitions use the same process `run_id` and add only closed
+`transition`, `disposition`, `provider`, `category`, and `route` enums. Notify
+transitions are `enqueue` and `delivery`; focus uses `request`. Enqueue records
+distinguish queued, stable-ID deduplicated, and failed outcomes. Delivery
+records distinguish delivered, dedupe/visibility/setting suppression, and
+failed outcomes across the external sender hook, WSL Toast and fallback, and
+Linux `notify-send` routes. Focus request records distinguish focused,
+notify-only, session-only, window-only, and failed outcomes. Failure codes are
+closed stage classifications and messages stay empty.
+
+Provider and category values are projected through fixed allowlists. Unknown
+values become `other`; arbitrary provider payloads and notification metadata
+cannot extend the event schema. Notification summary/body, tag/group, terminal
+title/topic, paths, queue or routing IDs, UUIDs, and AI/conversation/session
+identifiers are never recorded. The notifier sender owns one terminal delivery
+outcome after fallback selection, so failed intermediate WSL adapters do not
+produce duplicate records when a later route succeeds.
+
+One process writes at most one copy of an identical safe notify/focus tuple.
+This fixes repeated stable-ID queue replacement, desktop dedupe, visible-pane
+suppression, and reconcile hot paths to a finite per-run volume; the journal's
+existing size/retention cap remains the cross-process bound. Explicit `notify
+push` and `focus` outcomes logically replace the generic top-level
+`command.outcome`, including when append fails. Secondary automatic enqueue or
+delivery events do not claim an unrelated outer command. A successful focus
+that switches a tmux client may coexist with the shipped runtime
+`session.switch` lifecycle pair under the same run ID: the pair describes the
+tmux mutation, while `focus.transition` describes the request-level result.
+
+AI watcher and hook-ingest diagnostics use the same process `run_id` and add
+only closed `provider`, `ai_kind`, `ai_result`, and `failure` enums. The event
+families are `ai.watcher.transition` and `ai.ingest.outcome`. Watcher provider
+is the generic `ai`; ingest providers are `codex`, `claude`, `antigravity`, or
+`tmux-bell`. Each provider accepts only its own closed semantic-kind catalog;
+for example, `tmux-bell` can only emit `bell`, while watcher events can only use
+the generic `ai` provider and `watcher` kind. Provider event names are projected
+into semantic kinds such as `prompt`, `permission`, `stop`, `notification`,
+`tool`, `session`, `compact`, `subagent`, `teammate`, `statusline`, `invocation`,
+`lifecycle`, `bell`, `payload`, or `unknown`. A raw or future event name can
+therefore be diagnosed as `unknown` but can never extend the journal schema.
+
+One watcher process emits at most one `started` transition, one terminal
+`pane-gone` or `hook-active` transition, and one copy of each distinct safe
+failure tuple. The existing observable launch seam uses only
+`watcher-launch-failed`; status application remains the pre-existing
+best-effort operation and does not claim to expose swallowed tmux write errors.
+The terminal watcher event logically replaces its generic top-level outcome,
+including when append fails.
+The polling loop does not record snapshots, observed titles, captures, pane
+state, or a record per iteration.
+
+Hook ingest projects only anomalies: invalid/read/oversized payloads, unmatched
+or invalid targets, unsupported event classification, and terminal route
+failure. Route failures are limited to the observable bell queue/store and
+Antigravity explicit-response seams. Identical safe anomaly tuples are
+coalesced per process. Successful state, notification, quiet, and bell-dedupe
+traffic emits zero common AI events. Notify enqueue/delivery remains owned by
+the Phase 4 notify recorder, so ingest does not add a second AI success outcome
+or claim a secondary notify outcome. An ingest failure owns the top-level error
+logically before its best-effort append, preventing a duplicate generic
+`command.outcome`.
+
+The common AI event never contains the raw hook payload or event name, prompt,
+transcript, tool name/input/output, notification summary/body, pane content,
+cwd/path/command/title/topic, tmux target, queue ID, provider conversation or
+session identifier, UUID, or arbitrary reason/error string. `failure` is a
+stage enum, not `error.Error()`.
+
+Resource attribution diagnostics use `component=resource` and the single
+`resource.sampler.outcome` family. The Resource Inspector lifecycle is the
+only writer: its Linux collector owns tmux inventory, project-root discovery,
+and procfs attribution, while its refresh gate owns derived staleness. The
+closed `source` values are `sampler`, `tmux-inventory`, `project-discovery`,
+and `refresh`; the closed `resource_result` values are `unavailable`,
+`partial`, `stale`, `error`, and `scan-budget-exceeded`. `failure` is limited
+to the matching safe stage enum. Impossible source/result/failure combinations
+are rejected.
+
+The lifecycle's existing overlap and trigger-drop counters remain UI-only
+refresh feedback and do not create an operational event by themselves. When
+the retained last-complete sample crosses the stale boundary, the refresh
+owner records the single coalesced `stale` transition instead.
+
+Normal warming/ready samples, periodic samples, successful automatic/manual
+refreshes, and the separate host-only `projmux status resources` sampler emit
+zero common resource events. The two-second Resource Inspector lifecycle budget
+measures inventory, discovery, and procfs collection together. Tmux inventory
+and procfs observe its context directly. Project discovery does not currently
+accept a context, so an overrun is classified as budget-exceeded when discovery
+returns rather than being preempted; making that seam cancellable is a separate
+follow-up. Budget exhaustion preserves the established unavailable UI/CLI
+result and adds only the safe budget tuple. A persistent identical anomaly
+emits once. Recovery is silent and resets that transition, so a later re-entry
+emits once again. Journal append failure does not affect snapshot selection,
+popup refresh, stdout/stderr, or exit status.
+
+No resource event contains CPU or memory values, PID/process counts, process
+command/cwd/title, project/session/window/pane identifiers, socket/TTY,
+attribution details, snapshot status text, arbitrary errors, paths, UUIDs, or
+privacy seeds. Partial and stale outcomes are info-level and remain in the
+private local journal only. Unavailable, collection/inventory/discovery error,
+and scan-budget outcomes are error-level, so the explicit support report may
+include their closed enums after hashing run/version correlation. The report's
+existing error-only projection omits partial/stale and never exports metrics or
+identity.
+
+The diagnostics package exposes a typed `ReadRuntimeHealth` projection for
+read-only Doctor consumers. It reports the fixed `tmux` backend, latest
+socket/apply state, and a bounded tail/count of safe failures using only
+`Store.ReadOnly`; it does not create, chmod, lock, truncate, apply, restart, or
+repair anything. Doctor schema 2 consumes that seam for its `logs` findings
+and adds one fixed-argv, one-second `tmux -L projmux show-options` probe for
+actual socket/config health. The probe neither generates nor applies config.
+Its captured output is capped at 4 KiB. Doctor reads only a pre-existing
+regular generated config (at most 1 MiB) without following symlinks, and the
+shared read-only journal seam rejects non-regular inputs and files above 5 MiB.
+These conditions degrade to typed findings rather than blocking or repairing
+the source. Windows ACL privacy is reported as unverified because `os.FileMode`
+cannot prove it; a separate finding preserves the metadata-only writability
+result, and Doctor does not modify ACLs.
+
 ## Storage and retention
 
 The path is
@@ -54,9 +210,13 @@ arm`, `attention clear`, `attention window`, `tmux autosave-session-state`, and
 to the journal; an error from any of them still records exactly one safe error
 outcome. Explicit user mutations such as `attention toggle` retain their
 state-changing success record. Direct top-level help and explicit preview-only intents (`upgrade
---dry-run`, `update apply --dry-run`, `doctor --install-missing --dry-run`, AI
-integration dry-runs, and the currently preview-only session restore) are also
-read-only. Multi-mode commands such as AI status/topic, doctor install,
+--dry-run`, `update apply --dry-run`, AI integration dry-runs, and the
+currently preview-only session restore) are also read-only. Doctor is a stricter
+boundary: successes and errors never append to this journal, so diagnostics do
+not make its filesystem contract self-defeating. Support report success and
+errors likewise never append; its strict reader shares the viewer's tolerant
+decoder but never creates/locks/chmods/repairs/truncates the source journal.
+Multi-mode commands such as AI status/topic,
 terminal apply, snapshot delete, update check, and welcome popup inspect only
 allowlisted mode/flag names; boolean `=false` values retain mutation-capable
 classification, and no flag values are ever recorded. Help-looking tokens
@@ -76,5 +236,52 @@ viewer read is excluded from success logging, so inspection does not create a
 recursion loop.
 
 The older bounded `ai-ingest.log` and subsystem-specific `PROJMUX_*_DEBUG`
-surfaces retain their current paths, formats, and behavior. They are not
-migrated by this foundation.
+surfaces retain their current paths, formats, and behavior. Phase 6 deliberately
+keeps the legacy producer and both existing consumers: `projmux ai ingest log`
+still reads the legacy JSONL bytes, and `diagnostics report` still emits its
+allowlisted source/result count summary. Legacy append failure remains
+best-effort and independent of common-journal append failure.
+
+The measured migration parity is:
+
+| Legacy `ai-ingest.log` result | Common operational projection |
+| --- | --- |
+| parse error with no classified event | `payload / failed / payload-invalid` |
+| bell queue/store or Antigravity response route error | allowlisted semantic kind / `failed / route-failed` |
+| no matching pane | allowlisted semantic kind / `ignored / target-unmatched` |
+| pane-not-found bell target | `bell / ignored / target-unmatched` |
+| unknown event recorded as quiet | `unknown / ignored / unsupported-event` |
+| normal `state`, `notify`, known `quiet`, or `deduped` | zero common AI events; existing state/notify owner remains authoritative |
+| stdin read or payload-size rejection before the legacy append seam | common-only `payload-read` or `payload-oversized`; no legacy row existed |
+| blank `ai ingest bell` CLI target rejected before the legacy append seam | common-only `bell / ignored / target-invalid`; exit semantics unchanged |
+
+This is a dual-run migration seam, not a deprecation. Operators who need the
+legacy detailed local view can keep using `ai ingest log`; support archives
+remain count-only for that file. The common journal is the safe correlated
+source for watcher lifecycle and anomalous ingest classification. The file is
+a documented **Deprecate candidate**, not deprecated behavior in this release:
+common diagnostics cover anomalies but not the legacy detailed normal-state
+consumer. Any deprecation/removal requires a separate breaking roadmap with
+consumer migration.
+
+`PROJMUX_FOCUS_DEBUG` remains available with its existing one-line byte
+contract. Focus diagnostics share its request classification seam, but do not
+copy the debug line's raw target, session/window/pane, socket, client, source,
+or kind values into the journal. It is a documented **Deprecate candidate**
+because the common focus transition is the safe support path; its raw routing
+byte contract remains unchanged until a separate breaking deprecation.
+
+The complete file/surface inventory and decisions are maintained in
+[legacy-diagnostics-inventory.md](legacy-diagnostics-inventory.md). These are
+candidates only; Phase 6 removes, renames, ignores, or changes none of them.
+
+## Explicit support report
+
+`projmux diagnostics report [--output <path>]` previews and then atomically
+publishes a private local `tar.gz`; see [cli.md](cli.md#diagnostics). The
+manifest records report schema version 2, `default-hash-v1` redaction, every
+included entry, and stable missing/corrupt/permission omission reasons. Doctor
+JSON schema version 2 and the bounded operations decoder are reused rather than
+duplicated. AI ingest contributes count-only allowlisted source/result rows,
+never raw legacy lines. Existing output files survive collisions and partial
+temporary archives are removed.

package/docs/pr-guideline.md

@@ -24,7 +24,7 @@ feat(ai): add codex split picker keybinding
 fix(ai): prepend agent bin dir to PATH so node-managed CLIs find node
 docs(readme): drop Releases and Configuration sections
 chore: bump release-please manifest to 0.3.0
-refactor(picker): collapse duplicate fzf bootstrap code
+refactor(picker): simplify native picker bootstrap code
 ```
 
 Rules:

package/docs/resource-attribution.md

@@ -48,6 +48,13 @@ maps, SQLite, protobuf, or remote telemetry.
 - Snapshot state is `warming`, `ready`, `partial`, or `unavailable`. Bounded
   diagnostics contain scan duration and sampled/skipped/race/permission counts,
   plus identity/delta quality counts; they contain no user payload.
+- The interactive lifecycle has a two-second total budget matching its
+  non-overlapping cadence. Tmux inventory and procfs observe the context
+  directly. Project discovery is included in elapsed-budget classification but
+  its current interface is not cancellable, so an overrun is recognized only
+  when discovery returns. Budget exhaustion remains an unavailable snapshot;
+  it never exposes a partially mutating result. Context-aware project discovery
+  is a separate follow-up.
 
 ## Measurements
 
@@ -90,11 +97,18 @@ The opt-in read-only test below observes an existing socket and emits counts
 only. It neither captures pane content nor reads process command lines.
 
 ```text
-PROJMUX_RESOURCE_TMUX_SOCKET=projmux go test \
+PROJMUX_RESOURCE_TMUX_SOCKET=projmux \
+PROJMUX_RESOURCE_EXPECT_PROJECT_ROOT=/path/to/project go test \
   -run TestResourceAttributionRealTmuxReadOnlySmoke -v \
   ./internal/integrations/tmux
 ```
 
+When `PROJMUX_RESOURCE_EXPECT_PROJECT_ROOT` is set, the smoke additionally
+requires at least one blank explicit anchor to resolve from its pane current
+path and requires the resulting project bucket to contain a pane. Output stays
+bounded to the expected project path and aggregate counts; it does not emit
+session names, pane content, prompts, transcripts, or process command lines.
+
 2026-08-12 result: `panes=8`, `pane_pid_eq_sid=8`, `missing_pids=0`,
 `attributed_processes=13`, `escaped_boundary=0`, `sampled=474`, `skipped=0`,
 `race=0`, `permission=0`, `status=ready`. A separate tmux format-only count
@@ -119,6 +133,18 @@ PROJMUX_RESOURCE_TRANSIENT_SMOKE=1 go test \
 The pane shell remained attributed while its real `setsid` child was counted
 at the escaped/Other boundary, without reading the child command line.
 
+The current-path fallback itself has a separate isolated real-tmux smoke. It
+starts with inherited `TMUX`/`TMUX_PANE` removed, uses a dedicated
+`TMUX_TMPDIR` plus `-L` socket, verifies the actual socket path is below that
+temporary root before exact cleanup, and confirms the blank tmux project
+option remains blank after in-memory attribution:
+
+```text
+PROJMUX_RESOURCE_PROJECT_FALLBACK_SMOKE=1 go test \
+  -run TestResourceProjectFallbackTransientSmoke -v \
+  ./internal/integrations/tmux
+```
+
 ## Phase 1 inspector
 
 The popup retains warming/partial/unavailable and overage states, renders RSS
@@ -127,6 +153,53 @@ samples when it closes. Its non-overlapping default cadence is two seconds;
 Ctrl-R shares the same scan gate. Selection and query survive refresh by stable
 row identity, while a vanished row clamps to the nearest valid neighbor.
 Display labels use label → agent topic → known interactive shell → raw title,
-but those values never become ownership keys. Unsupported platforms show an
-unavailable reason, not zero metrics. PSS, non-Linux collectors, process-list
-drill-down, history, and resource mutation remain outside this contract.
+but those values never become ownership keys. Pane rows and detail reuse that
+identity plus the tmux current command, PID/SID, pane id, and TTY; pane rows
+show attributed process counts while project/window rows retain pane counts.
+Right/Enter move forward, Left moves back (and is a root no-op), and Esc closes
+at every depth. Unsupported platforms show an unavailable reason, not zero
+metrics. PSS, non-Linux collectors, process-list drill-down, history, and
+resource mutation remain outside this contract.
+
+Host and attributed CPU/memory use the same semantic classifier as the live
+statusbar: CPU is normal below 70%, warning at 70–89.9%, and critical at 90%
+or above; memory is normal below 75%, warning at 75–89.9%, and critical at 90%
+or above. Values retain the resolved semantic role but omit visible severity
+words. Unknown is rendered as `--`, never as zero; Sample lifecycle and
+freshness remain explicit text.
+
+The first paint is a non-actionable warming surface. Completed samples report
+age and fresh/stale state; partial and overage callouts stay bounded to counts
+and aggregate values. Empty and gone scopes are read-only and explain what the
+latest complete sample can no longer open. Automatic refresh runs every two
+seconds; Ctrl-R reports in-progress state while retaining the last complete
+sample. Both paths preserve scope, breadcrumb, query, selection, and the row
+order last computed by Tab. The default order is Name; Tab computes CPU,
+Memory, or Name once from the current sample, while later refreshes update row
+values without silently moving focus. Native synchronized frame diffs repaint
+only changed rows and update state/footer chrome together.
+
+The Resource Inspector lifecycle projects only unavailable, partial, stale,
+collection/inventory/discovery error, and scan-budget transitions into the
+private bounded operations journal. A persistent identical transition is
+coalesced until silent recovery; normal samples and refreshes emit nothing.
+The statusbar's separate host-only sampler also emits nothing. Resource events
+never contain the metrics, PID/process data, tmux/project identity, paths,
+titles, commands, snapshot reasons, or arbitrary error strings described by
+this UI model. See [operational-diagnostics.md](operational-diagnostics.md).
+
+The live summary is a fixed five-row bottom dock below the search/list surface:
+one renderer-owned theme-aware divider, then Host, Attributed, Coverage, and
+Sample. It does not scroll or filter with rows. Coverage owns the non-drillable
+Other or current-scope empty/gone explanation; bounded partial/overage details
+stay on Sample. The action footer remains below the dock with its own chrome
+boundary, so diagnostic values and key hints never share a role. The 80x24
+layout retains a navigable list viewport without clipping, border bleed, or a
+second dock divider.
+
+Project rows label project paths explicitly. The two attribution buckets keep
+their stable core keys but display `No project match` and `Multiple project
+matches` with bounded explanations. Pane primary identity follows the shared
+label → agent-only AI topic → interactive shell → raw title resolver; pane id,
+process id, and TTY remain labeled secondary details and stable keys are
+unchanged.

package/docs/session-restore.md

@@ -137,3 +137,21 @@ longer accepts startup selector flags for session-state restore. It always
 follows the normal empty attach path after resolving the target app session name
 and startup directory. Use `Settings > Session State > Sidebar startup picker` for
 interactive Latest snapshot / Named snapshot / Empty session selection.
+
+## Operational diagnostics
+
+Selected Session State mutations leave one local, best-effort terminal outcome
+in the bounded operational journal. Manual and popup save, Project Settings
+latest/named save, manual/Settings/prune delete, and actual project-startup
+latest/named replay are covered. Restore preview and `--dry-run` remain
+read-only. Successful autosave, disabled/not-due/fresh autosave no-ops, and
+nested snapshot store/replay calls do not write an outcome; an actual autosave
+failure writes one safe error even under `--quiet`.
+
+The outcome contains only a closed operation/source and aggregate window,
+pane, recipe, or deleted-item counts. It never contains a snapshot or project
+path, snapshot content/name, pane cwd/command, agent resume/conversation/session
+ID, or arbitrary metadata. Diagnostics append failure never changes save,
+restore, delete, or quiet-autosave behavior. See
+[operational-diagnostics.md](operational-diagnostics.md) for the complete event
+schema and retention/privacy contract.

package/docs/settings-ia.md

@@ -71,11 +71,11 @@ view-first layout:
   desktop AI notification collapse window. It stores integer seconds and shows
   the effective source; `PROJMUX_TMUX_NOTIFY_DEDUPE_SECONDS` remains the top
   override. The tmux bell fallback keeps its fixed 5 second window.
-- `Settings > Notifications > Delivery sources` shows Codex hooks, Claude, and
-  tmux producer diagnostics, the effective desktop sender override state, and
-  copyable install/remove/dry-run commands. Settings copies command text only;
-  it does not install or remove external notify wiring. The legacy Codex notify
-  source is intentionally omitted from Settings.
+- `Settings > Notifications > Delivery sources` shows Codex, Claude,
+  Antigravity, and tmux producer diagnostics, the effective desktop sender
+  override state, and copyable install/remove/dry-run commands. Settings copies
+  command text only; it does not install or remove external notify wiring. The
+  legacy Codex notify source is intentionally omitted from Settings.
 - `Settings > Notifications > Hook quiet policy` shows Codex/Claude hook
   runtime action values and writes only
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/ai-hook-actions.json`. It does not
@@ -85,8 +85,8 @@ view-first layout:
   `${XDG_CONFIG_HOME:-$HOME/.config}/projmux/sidebar-startup-picker`.
 - `Settings > Labs` contains only Live system resources and Project Hooks.
   Keybindings live at `Settings > Keybindings`; Labs has no visible or hidden
-  keybindings redirect. Native is the only picker backend, so Labs does not
-  render picker source/backend information.
+  keybindings redirect. The native picker is the product picker, so Labs does
+  not render picker source information.
 - `Settings > Labs > Live system resources` is a direct global on/off toggle
   for the macOS/Linux/WSL lower-status-row `CPU N%  MEM N%` segment. It defaults
   off, updates live tmux state when toggled, and renders unavailable on
@@ -97,7 +97,8 @@ view-first layout:
 - `Settings > Labs > Project Hooks` is overview-first. The Labs root opens the
   overview, and the on/off mutation rows live one level deeper.
 - `Settings > AI Settings` is view-first. The root contains `Default split
-  mode`; the detail contains the `Claude`, `Codex`, and `Shell` choices.
+  mode`, `Enabled agents`, and `Resume picker`; the default-mode detail contains
+  the `Claude`, `Codex`, `Antigravity`, `Shell`, and `Selective` choices.
 - `Settings > Project > Project recipe` is the functional label for
   `.projmux/config.toml`. Search still matches `config.toml` as an alias.
 - `Settings > Project > Project recipe` is view-first. The root contains section
@@ -117,7 +118,7 @@ view-first layout:
   visible as warnings and fall back to `en-US`.
 - Global root descriptions keep ownership explicit: Appearance owns language,
   AI badge style, and status/notification icon decoration; Theme owns presets,
-  color tokens, and font hints. About describes only the surface it retains.
+  and color tokens. About describes only the surface it retains.
 - `Settings > About` is intentionally compact: Version, Source, update
   status/actions (including Latest, Update state, Installer, and Release notes
   when available), Welcome, and Quit. It does not reproduce static key,