# PR catalog (draft, feature-first)

Generated: 2026-01-25  
Source of truth for commit mapping: `docs/commit-audits/happy/leeroy-wip.commit-index.json`

## Principles

- PRs are organized by **final feature/final fix** (not by infra layering).
- Within a PR, we keep **useful commit granularity**, but we **squash “evolution noise”** (fixups/reverts/follow-ups) so the rewritten history represents the final correct state.
- Translations/a11y/tests should generally be **folded into the feature PR** that uses them, unless we intentionally do a single early i18n sweep to reduce conflict surface.

## Proposed PRs (draft)

Notes:
- PRs are listed in **numeric order** for scanning. The *rewrite execution order* lives in `docs/commit-audits/happy/leeroy-wip.rewrite-status.tsv`.
- Unless we explicitly decide otherwise, **i18n/a11y/tests are folded into the owning feature PR** (i.e. `translationHandling=in-feature-pr` in the TSV).

### PR01 — Foundations / DevX

- Goal: repo/tooling hygiene that would otherwise leak into every PR.
- Includes: deps/test infra, small typecheck fixes, runtime helpers (e.g. Bun spawn compatibility), minor logging/diagnostic gating.
- Excludes: user-facing features (should live in their owning PRs).

### PR02 — UI modal/overlay/popover system (native + web) + Expo web modal behavior

- Goal: one coherent modal/overlay system, including the Expo web modal behavior restoration.
- Includes: overlay portals, modal primitives, popovers/dropdowns, WebAlertModal hardening, Expo web modal plumbing + expo-router pin/patch where required.
- Excludes: non-overlay list/primitives (PR38) and feature screens (they stay in their feature PRs).

### PR03 — i18n foundation sweep (optional)

- Goal: reduce conflict surface by landing shared translation keys early (only if we decide it’s worth it).
- Includes: “shared keys” that are otherwise touched by many PRs.
- Excludes: feature-specific strings (prefer folding into owning feature PRs).
- Note: if we run PR03, later PRs must not re-add those keys (they should only consume them).

### PR04 — Auth + storage scoping

- Goal: auth persistence + scoped storage roots (baseline for reliable multi-feature storage).
- Includes: token storage persistence hardening, storage root scoping, and related migrations/compat glue.
- Excludes: feature-specific persistence semantics (PR05/PR28/etc).

### PR05 — Persistence / drafts

- Goal: final-state persistence primitives (draft modes, invariants, write semantics).
- Includes: draft mode validation/clamping and persistence invariants that aren’t tied to a single feature UI.
- Excludes: feature-layer persistence (resume, queue, wizard) that should live with its feature.

### PR06 — Settings: API keys + experiments + settings screens

- Goal: settings surfaces that don’t belong to a single feature PR.
- Includes: API key management UI, experiments toggles, settings screen structure, settings parsing robustness.
- Excludes: secrets/vault UX (PR09) and profiles/env UX (PR07/PR08).

### PR07 — Env var templates + preview/resolution end-to-end

- Goal: env var template parsing + preview/resolution UX (final state).
- Includes: template parsing/formatting, preview modal behaviors, remote resolution correctness/safety.
- Excludes: profiles selection UX (PR08) and secrets-backed requirements (PR09).

### PR08 — Profiles feature

- Goal: profiles end-to-end (final state).
- Includes: profile CRUD UX, env var selection UX within profiles, profile model helpers.
- Excludes: core env-template parsing (PR07) and secrets/vault storage primitives (PR09).

### PR09 — Secrets / vault

- Goal: secrets end-to-end: SecretString/sealing, tolerant parsing, redaction, and secrets UX.
- Includes: secret storage model + UI, validation, tolerant parsing + “keep valid entries” behavior, redaction/visibility hardening.
- Excludes: generic API-key settings UX (PR06) unless a surface is explicitly migrated to secrets.

### PR10 — Permission framework (Claude/cloud baseline)

- Goal: baseline permission mode types/mapping + persistence/arbitration + Claude/cloud UX.
- Includes: permission mode modeling, storage/persistence, default UX flows, correctness tests.
- Excludes: agent-specific allowlists/approvals for Codex/Gemini (PR11/PR32).

### PR11 — Agent permissions (Codex/Gemini): permission modes + allowlists

- Goal: agent-specific permission behavior: Codex/Gemini permission wiring + per-session allowlists + shell approval hardening.
- Includes: per-session allowlist policy + persistence/wiring for agents beyond Claude, and related UX correctness.
- Excludes: Codex execpolicy approvals and MCP elicitation UI (PR32).

### PR12 — Tool interaction: AskUserQuestion + ExitPlan native handling

- Goal: end-to-end tool UX for AskUserQuestion + ExitPlan with correct `interaction.respond` plumbing.
- Includes: tool views, respond payload wiring, permission-id guardrails, submit/retry UX.
- Excludes: generalized tool-call normalization/specialized renderers (PR39).

### PR13 — MessageQueueV1 + Pending messages (end-to-end)

- Goal: pending-message queue as a final feature (no separate “fix PRs” for follow-ups).
- Includes: queue semantics, pending/discard/send-now correctness, pending UI (indicator/modal) and tests.
- Excludes: generic sync transport reliability not specific to the queue (PR27).

### PR14 — Capabilities end-to-end (protocol + wiring + reliability)

- Goal: checklist-based capabilities protocol plus required caching/reliability fixes.
- Includes: protocol definition + wiring, cache correctness, failure/backoff semantics specific to capabilities.
- Excludes: preview-env (PR15) and generic transport parsing (PR27).

### PR15 — preview-env end-to-end

- Goal: preview-env RPC as a coherent final feature.
- Includes: key validation (lowercase/prototype-safe), RPC handlers, tests.
- Excludes: env-template UI/pickers (PR07/PR08).

### PR16 — Daemon reliability (ownership + reattach/restart safety)

- Goal: stack-safe daemon management and reattach semantics (no cross-stack killing).
- Includes: process ownership checks, reattach/restart logic, PID safety, related tests.
- Excludes: terminal IO behavior (PR31) and tmux feature work (PR18).

### PR17 — CLI reliability (socket/metadata waiters + reconnection + backoff)

- Goal: CLI-side reliability (waiter cleanup, reconnection correctness, backoff semantics).
- Includes: waiter lifecycle, retry/backoff correctness, metadata/socket coordination fixes.
- Excludes: queue semantics (PR13) and capabilities protocol (PR14) except where explicitly coupled.

### PR18 — TMUX end-to-end (headless sessions + attach + settings)

- Goal: tmux as a final feature (headless sessions + attach flows + settings).
- Includes: tmux parsing/targeting correctness, spawn/socket path handling, attach instructions, tmux settings/persistence.
- Excludes: generic terminal switching/signal forwarding (PR31) and Claude-specific switching UX (PR20).

### PR19 — Resume end-to-end (inactive resume + session lifecycle)

- Goal: resume UX + RPCs + daemon plumbing (Claude + Codex).
- Includes: inactive-session resume flows, resume wiring, related session lifecycle correctness, i18n/a11y for resume UX.
- Excludes: Claude transcript/scanner improvements not strictly required for resume (PR20).

### PR20 — Claude session reliability (switching + transcript/scanner + local runner)

- Goal: Claude-specific reliability improvements beyond resume and beyond generic terminal IO.
- Includes: cloud/local switching reliability, transcript/scanner correctness, local runner argument correctness.
- Excludes: tmux-specific work (PR18) and generic terminal IO/signal forwarding (PR31).

### PR21 — Codex MCP tool-call result correctness

- Goal: correctness for Codex MCP tool-call results (e.g. preserve falsy Ok/Err outputs).
- Includes: strict correctness fixes for tool-call result parsing/serialization.
- Excludes: Codex approvals + elicitation (PR32) and generalized tool normalization (PR39).

### PR22 — Server-light flavor (variant + schema/prisma sync)

- Goal: add a lightweight server flavor/variant as a first-class supported mode.
- Includes: SQLite flavor/variant implementation, migrations/schema sync strategy, prisma centralization (if kept together).
- Excludes: UI serving/public file serving (PR23) and S3 validation (PR24).

### PR23 — Server: optionally serve UI + public files safely

- Goal: “serve UI from server” correctness + hardening.
- Includes: missing UI bundle/index handling, public file path normalization/encoding safety, safe 404 vs 500 behavior.
- Excludes: server-light flavor internals (PR22).

### PR24 — Storage: S3 env + bucket validation

- Goal: fail-fast storage configuration validation for S3/Minio.
- Includes: env validation, bucket existence checks, hardening/tests.
- Excludes: unrelated storage/persistence features (PR04/PR05).

### PR25 — Misc small UX polish (only if it stays small)

- Goal: keep tiny isolated UX fixes from ballooning other PRs.
- Includes: only changes that are truly isolated and do not meaningfully alter a feature’s core behavior.
- Rule: if it touches a feature PR’s core surfaces, fold it into that feature PR instead.

### PR26 — New session wizard end-to-end (wizard + pick flows + machine selection)

- Goal: new-session as a cohesive final feature.
- Includes: wizard extraction/flow, pick screens, machine selection UX, correctness fixes and tests for the wizard flow.
- Excludes: generic UI primitives (PR02/PR38) and profiles/env/secrets foundations (PR07/PR08/PR09).

### PR27 — Sync robustness (transport/error parsing + backoff semantics)

- Goal: sync layer reliability not specific to queue/capabilities.
- Includes: JSON parsing guards, disconnect handling, invalidate-and-await safety, debounce/backoff correctness (sync layer).
- Excludes: queue semantics (PR13) and capabilities protocol behavior (PR14).

### PR28 — Model modes (per-session selection + persistence)

- Goal: per-session model mode correctness: clamping/validation + persistence + UI alignment.
- Includes: persistence format + migrations, UI defaults, safety checks/tests.
- Excludes: agent selection/registry (PR37) unless directly tied to model modes.

### PR29 — Sessions & message list UX

- Goal: session/message browsing UX and reliability.
- Includes: inactive grouping/unread indicators, archive/kill robustness, message list conveniences.
- Excludes: resume semantics (PR19) and pending queue UI (PR13).

### PR30 — Agent error surfaces (Codex/Gemini)

- Goal: make agent failures user-visible/actionable and testable.
- Includes: error surfaces in session UI, shared formatting helpers, targeted tests.
- Excludes: approvals/elicitation flows (PR32) and tool-view UX (PR12/PR39).

### PR31 — Terminal switching reliability (remote↔local)

- Goal: make remote↔local terminal switching deterministic and safe (non-tmux specific).
- Includes: input handling, buffered stdin draining, child signal forwarding, terminal session lifecycle correctness.
- Excludes: tmux feature work (PR18) and Claude transcript/scanner work (PR20).

### PR32 — Codex approvals + MCP tool interactions (execpolicy + elicitation)

- Goal: end-to-end support for Codex execpolicy approvals and MCP elicitation/tool interaction wiring.
- Includes: approvals UI decision + payload plumbing, MCP tool-call begin/end surfacing, bridge runner compatibility (`process.execPath`).
- Excludes: pure tool-call result correctness (PR21) and generalized tool normalization (PR39).

### PR33 — Codex special commands (/clear session reset)

- Goal: make Codex special commands deterministic and safe.
- Includes: treat `/clear` as a session boundary that resets Codex session state (and adjacent correctness).
- Excludes: broader Codex integrations (PR32/PR19).

### PR35 — Friends: UX + reliability

- Goal: keep all “friends” UX/reliability improvements together.
- Includes: stable search error codes, localization, and follow-up UX fixes for the friends surface.
- Excludes: other session/message UX (PR29).

### PR36 — ACP agents end-to-end (runtimes + replay + tool normalization)

- Goal: treat ACP-backed agents as first-class backends.
- Includes: CLI runtimes/transport wiring, replay capture/import, normalization needed for ACP events.
- Excludes: generic tool normalization that applies across all agents (PR39) unless shared.

### PR37 — Agent registry end-to-end (selection + settings + UX helpers)

- Goal: typed agent registry in the Expo app and coherent agent selection.
- Includes: enabled agents, picker options, capability/resume option helpers, CLI warnings surfaced in app UX.
- Excludes: capabilities protocol itself (PR14).

### PR38 — UI list primitives + pending UI polish

- Goal: list/row primitives to make session/settings UIs consistent.
- Includes: ItemGroup/list row primitives, dividers/titles/actions primitives, non-modal list UX helpers.
- Excludes: modal/overlay system (PR02) and queue semantics (PR13).

### PR39 — Tool UX: normalization + specialized views + tracing

- Goal: normalize agent tool-call shapes and render them consistently in the UI, with tracing/fixtures for debugging/regressions.
- Includes: normalization helpers, specialized tool renderers, robust fallback views, tool-trace extraction/fixtures.
- Excludes: AskUserQuestion/ExitPlan end-to-end wiring (PR12), unless a shared renderer is used.