happy-stacks 0.6.12 → 0.6.13

package/docs/commit-audits/happy/pr-desc.working-document.md

@@ -0,0 +1,536 @@
+
+# Not Dead Yet Release
+
+## 🚀 Executive Summary
+
+This release represents a fundamental architectural shift to support and improve **Local-First** deployments and **Robust Agentic Workflows**. We have introduced a SQLite-backed "Server Light" flavor (no Docker needed anymore to run Happy Server), a persistent Pending Message Queue, and a standardized Capabilities Protocol.
+
+For Agents, we have unified the **ACP (Agent Control Protocol)** backend, adding runtimes for **Codex ACP**, **OpenCode ACP**, and **Auggie ACP** (experimental, experiment-gated), while hardening the **Claude** local/remote bridge. Security is significantly upgraded with a **Secrets Vault**, **PID-safe Daemon**, and **Permission Mode restoration** that follows session history across devices.
+
+## 🙏 Special Thanks
+
+This PR additionally includes and ports work from:
+
+*   **@54m** — Session Sharing (UI + server): [slopus/happy#356](https://github.com/slopus/happy/pull/356), [slopus/happy-server#25](https://github.com/slopus/happy-server/pull/25)
+*   **@OrdinarySF** — Codex approvals + MCP tooling: [slopus/happy#299](https://github.com/slopus/happy/pull/299), [slopus/happy-cli#102](https://github.com/slopus/happy-cli/pull/102), [slopus/happy-cli#101](https://github.com/slopus/happy-cli/pull/101)
+*   **@fberlakovich** — Claude signal forwarding: [slopus/happy-cli#127](https://github.com/slopus/happy-cli/pull/127)
+*   **@jiogallardy** and **@cruzanstx** — Claude runner reliability: [slopus/happy-cli#139](https://github.com/slopus/happy-cli/pull/139), [slopus/happy-cli#120](https://github.com/slopus/happy-cli/pull/120)
+*   **@zkytech** — Codex `/clear` handling: [slopus/happy-cli#72](https://github.com/slopus/happy-cli/pull/72)
+
+## How to try it
+
+```
+npx --yes happy-stacks@latest review-pr \
+  --happy=https://github.com/slopus/happy/pull/487 \
+  --no-mobile \
+  --keep-sandbox \
+  --verbose \
+  -- --bind=loopback
+```
+
+## WIP / not fully tested yet / not fully finished yet
+
+This branch/PR is not finalized yet, but can still be used/reviewed/tested already. Other changes will be pushed as they are finalized.
+
+- **ACP resume:** ACP providers resume features and capability detection have not been fully tested yet
+- **Tool rendering:** full normalization and rendering improvements are still WIP
+- **Message queue UI polishing:** some improvements and UI/UX are WIP
+- **Installable deps UI display + checking:** experimental installable dependencies (codex-mcp fork & codex-acp) display & detection will be improved a bit in the new session screens
+- **Sessions sharing UI:** some improvements and UI/UX are WIP
+- **Multi-provider permissions session allowlist:** the Claude sessions' permissions allowlists have been improved and extended to all other providers, but not fully tested yet
+- **Friends sharing:** not tested yet
+- **Deep review:** in progress
+
+---
+
+## 🏗 Core Architecture
+
+### 1. Server Light (SQLite & Local Files)
+We have introduced a "Light" server flavor designed for local-only use, removing the dependency on Docker (Postgres/Minio) for personal usage.
+*   **Dual Flavor Entrypoints:** The server now boots in either `'full'` (Postgres/S3) or `'light'` (SQLite/Local FS) mode.
+*   **SQLite Infrastructure:** Added dynamic Prisma client generation for SQLite (`schema:sync`), atomic write-ahead DB handling, and baseline migrations.
+*   **SQLite env correctness:** sqlite DB URLs are formed via proper `file:///...` URLs (URL-escaped), and light flavor validates `PORT` fallbacks and normalizes public paths across platforms.
+*   **Migration reliability:** light migration scripts validate `HAPPY_SERVER_LIGHT_DATA_DIR` (trim/require) and centralize the deploy plan args; light entrypoint does not exit after start.
+*   **Master secret race hardening:** light flavor master secret file creation is atomic (exclusive create + EEXIST read-back), preventing corruption when multiple processes start concurrently.
+*   **Local Files Backend:** In "Light" mode, public files (avatars, attachments) are served directly from `~/.happy/server-light/files` via a secured `/files/*` route.
+*   **Public file URL hardening:** strict path normalization rejects traversal/absolute/drive-letter/null bytes; URL generation encodes each path segment (`encodeURIComponent`) so `#`/`?` cannot be interpreted as fragment/query.
+*   **Schema sync + Prisma centralization:** a unified `schema:sync` generator produces the SQLite schema and enum exports (with `--check` drift tests), and server code centralizes Prisma init/types with a fail-fast `db` proxy.
+*   **Integrated UI Serving:** The server can optionally serve the frontend static bundle (handling SPA routing fallbacks), enabling single-process deployments.
+
+### 2. Pending MessageQueue V1 (Metadata-Backed)
+We replaced the ephemeral socket-based pending queue with a persistent, encrypted queue stored in session metadata.
+*   **Source of Truth:** The pending queue is stored in `session.metadata.messageQueueV1`. This ensures queue state survives server restarts and synchronizes perfectly across devices.
+*   **CAS Updates:** Enqueue/dequeue operations use `update-metadata` with version checking (Compare-And-Swap) to prevent race conditions.
+*   **Submit Modes:** message sending is driven by `settings.sessionMessageSendMode` (`agent_queue|interrupt|server_pending`). The default `agent_queue` mode chooses `server_pending` automatically when queue support exists and the agent is busy/offline/not-ready or controlled by the terminal (so we never “lose” input that cannot be injected safely).
+*   **Transcript Recovery:** The CLI observes the server-echoed message (by stable `localId`) before clearing `messageQueueV1.inFlight`, preventing loss if the CLI crashes between emit and server persistence.
+*   **Discard tracking:** queued items can be discarded into `messageQueueV1Discarded`, and committed transcript messages can be marked discarded via `discardedCommittedMessageLocalIds` (UI dims and labels discarded bubbles).
+*   **Fail-closed parsing:** invalid persisted queue shapes (e.g. malformed `inFlight`) are rejected so corrupted state doesn’t partially apply.
+*   **Optimistic “thinking” UX:** the app sets a short-lived `optimisticThinkingAt` marker when sending/enqueueing so sessions reflect activity immediately, then clears it once the server reports `thinking: true`.
+*   **Pending UI:** the “Pending messages” indicator/modal is a derived view of `messageQueueV1` (queue + inFlight + discarded). Actions like “send now”, discard, and delete are performed via metadata updates, with fail-closed ordering so send failures never delete items.
+
+### 3. Capabilities Protocol
+Machine introspection has been standardized into a flexible **Capabilities Protocol**, replacing ad-hoc RPCs. This allows to easily detect what is currently installed on the user's computer and surface clear options
+*   **Checklist-based Discovery:** The UI requests capabilities via `capabilities.detect` (e.g., checking for "new-session" requirements or "resume" support).
+*   **Protocol surface:** `capabilities.describe` / `capabilities.detect` / `capabilities.invoke` support checklist-driven discovery (e.g. `new-session`, `machine-details`, `resume.codex`) and user-initiated install/upgrade operations.
+*   **Unified Snapshot:** The daemon returns a comprehensive snapshot of installed tools (Claude, Codex, Gemini, Tmux, OpenCode) and their versions/status.
+*   **ACP probing:** capabilities detection covers ACP backends (including Codex ACP dependency checks) so the UI can gate “new session” and “resume” flows on actual machine support.
+*   **Dependency Management:** The protocol supports checking and installing helper binaries (like the `codex-mcp-resume` bridge) into a managed prefix (e.g. `~/.happy/tools/codex-mcp-resume`).
+    *   The app maintains an installable-deps registry used by Machine/New Session screens (e.g. Codex MCP resume + Codex ACP).
+*   **Machine-level UX:** machine screens/pickers can surface detected CLI status (with caching + stale-while-revalidate refresh and safe timeouts) so users can quickly diagnose “tool missing / not logged in / daemon too old” states.
+*   **Hook timestamp stability:** `useCLIDetection` now produces a stable timestamp even when loaded snapshots lack `checkedAt`, avoiding UI flapping; covered by fake-timer tests.
+*   **Cache reliability:** capabilities caches transition to `error` on detection throws (avoids “stuck loading” states while preserving any previous snapshot).
+*   **Cache race hardening:** capabilities cache updates are guarded by in-flight tokens so late/stale requests cannot overwrite newer loaded results; covered by a dedicated race regression test.
+*   **Probe robustness + UX polish:** ACP probes fail closed with normalized error shapes and hardened termination semantics; installable deps UI strings/dropdowns are localized and update badges use semver comparison; Gemini config loading is ESM-safe.
+*   **Diagnostics details:** `detect-cli` is daemon-side (PATH scan, no login shell) and can include best-effort `version` and optional `isLoggedIn` probes (plus `tmux`), guarded by timeouts so it never blocks core flows.
+    *   Version parsing is tolerant (scans combined stdout+stderr, not just the first line) to reduce false “unknown version” states.
+*   **Probe tuning:** tuned `tmux` version probe timeouts (e.g. 1.5s) to reduce false negatives on slow hosts.
+*   **Shared protocol contracts:** `@happy/protocol` defines shared daemon↔app contracts (RPC result shapes/error codes, checklist helpers, socket RPC event typing) so the CLI/daemon and Expo app stay in sync without copy/paste drift.
+
+---
+
+## 🤖 Agents & Runtimes
+
+### ACP providers (OpenCode + Auggie)
+*   **OpenCode ACP:** a first-class ACP-backed agent runtime with consistent tool rendering/lifecycle semantics (see ACP runtime notes below). Vendor resume support is not available yet (see Known Issues).
+*   **Auggie ACP (experimental):** an ACP-backed agent runtime that is experiment-gated in the app, with per-session spawn options (e.g. an indexing toggle) surfaced through the UI and persisted in session state.
+
+### Agent catalog (Expo + CLI)
+*   **Shared agent ids + manifest:** `@happy/agents` provides canonical `AgentId` and shared agent metadata used across the Expo app and CLI (resume gating, connect targets, and stable identifier mapping).
+*   **Expo catalog facade:** the app uses a single catalog entrypoint (`expo-app/sources/agents/catalog.ts`) backed by per-agent providers (`expo-app/sources/agents/providers/*`) so agent UI behavior/copy/capability wiring is centralized and testable.
+*   **CLI backend catalog:** agent-specific logic lives under `cli/src/backends/<agentId>/**` and is composed via `cli/src/backends/catalog.ts` to drive CLI subcommands, detection snapshots, capability/checklist contributions, daemon spawn hooks, and ACP backend factories.
+*   **Extensibility:** adding a new agent is primarily “add catalog/provider/backend entries”, rather than editing many unrelated screens/commands/rpc handlers; this reduces wiring churn and makes integrations easier to review.
+
+### ACP runtimes (Codex + OpenCode + Auggie)
+ACP runtimes support multiple ACP-backed agents with consistent UI semantics.
+*   **New runtimes:** full runtime support for **Codex ACP**, **OpenCode ACP**, and **Auggie ACP**, including transport wiring and session id management.
+*   **Tool Normalization:** Implemented a normalization layer that standardizes tool events (calls/results) across different backends, ensuring consistent rendering in the UI.
+*   **Replay Support:** Added infrastructure to capture and import ACP session history for debugging and regression testing.
+    *   Includes replay capture/import helpers and `loadSession` support on the CLI side, plus slash-command publishing for ACP backends.
+*   **Slash commands:** when ACP backends report available commands, they are published into session metadata so the UI can surface slash-command affordances consistently across agents.
+*   **Task lifecycle edges:** CLI runtimes emit durable ACP lifecycle events (`task_started`, `task_complete`, `turn_aborted`) with stable task ids so the UI can render agent “thinking/task” boundaries consistently across backends.
+    *   CLI agent entrypoint aligns subcommands/startup flags across backends (OpenCode wiring, Codex/Gemini argument alignment, and `--permission-mode-updated-at` parsing), and supports `--existing-session` and vendor `--resume` where applicable.
+    *   ACP stdio is hardened: stdin write failures propagate (not silently swallowed) and stdin drain is guarded to avoid hangs (including “synchronous drain” edge cases in Node stream adapters).
+
+### Claude Reliability & Switching
+Significant hardening of the Claude local/remote runner.
+*   **Hook-Mode Continuity:** The runner now preserves the `transcript_path` reported by hook scripts. This allows switching between Remote and Local modes without losing session context.
+    *   Tests cover the `transcriptPath` surface to prevent regressions.
+*   **Switch preflight:** switching waits briefly for hook session/transcript info (with a visible status message) to avoid switching with missing sessionId/transcriptPath.
+*   **Fork safety on resume:** when starting local from an existing session, the runner clears stale session info until the new hook data arrives; if spawn fails before the forked session is reported, it restores the previous sessionId/transcriptPath so remote mode can still resume it.
+*   **Transcript availability UX:** when attaching to a fresh local session before its transcript file exists, the CLI emits a clear session status message and the scanner begins streaming automatically once the transcript appears (avoids “blank” remote sessions).
+*   **Resume validation robustness:** remote resume attempts continue even if transcript validation has not passed yet, avoiding false-negative context loss during fast switching/initialization.
+*   **Signal Forwarding:** The CLI now correctly forwards OS signals (`SIGINT`, `SIGTERM`, `SIGHUP`) to the underlying Claude binary, preventing orphaned processes.
+    *   Forwarding is hardened to avoid orphan lifecycle events and to re-raise forwarded signals where appropriate (reduces “stuck running” and exit-code confusion).
+    *   _Credit:_ Thanks to @fberlakovich — commits ported into the monorepo from [slopus/happy-cli#127](https://github.com/slopus/happy-cli/pull/127).
+*   **Switching Idempotency:** The `switch` RPC is idempotent and does not thrash mode state under repeated calls.
+*   **Remote→local switch safety:** when switching to local mode while messages are queued/pending, the terminal prompts with a preview and requires explicit confirmation.
+    *   If confirmed, queued/pending items are discarded in session metadata (so they can be recovered/reviewed later from the app’s discarded/pending UI) and the switch proceeds.
+    *   If declined, the switch is canceled and remote mode continues (no surprising “silent” state changes).
+*   **Remote↔local switching reliability (non-tmux):** hardened the Claude remote-mode Ink UI and teardown to prevent terminal corruption/buffered-input leaks (deterministic key handling incl. `Ctrl+T`, raw-mode reset + brief stdin drain after Ink unmount, and non-async input handlers with cancellable timeouts).
+*   **Scanner + CLI flag correctness:** session scanning tolerates consumer callback exceptions; Claude local-runner treats `-c` as `--continue` for session control detection; and remote runner handles `--resume/-r` with or without an id (without id resumes the most recent valid UUID session for the project).
+*   **Config dir robustness:** `CLAUDE_CONFIG_DIR` overrides are trimmed so accidental whitespace doesn’t create wrong paths.
+*   **Local runner robustness:** orders `claudeArgs` last for slash-command correctness, forwards OS signals to spawned local children, and treats abort errors as expected (reduces spurious “process error” noise).
+    *   _Credit:_ Thanks to @jiogallardy and @cruzanstx — commits ported into the monorepo from [slopus/happy-cli#139](https://github.com/slopus/happy-cli/pull/139) and [slopus/happy-cli#120](https://github.com/slopus/happy-cli/pull/120).
+*   **AskUserQuestion / ExitPlanMode tools:** the app completes these Claude tool interactions via the existing session `permission` RPC.
+    *   AskUserQuestion attaches structured `answers` keyed by the question text when supported; otherwise it falls back to denying the tool call and sending a normal user message with the same content so older agents can proceed.
+    *   ExitPlanMode uses allow/deny without injecting extra chat messages, and denial can include a free-text “request changes” reason that Claude can use to revise the plan in-place. Tool UIs require a `permission.id`, fail-closed when missing, and show localized errors on submit failures.
+
+### Codex Approvals & MCP Interaction
+*   **ExecPolicy Amendments:** Added native UI support for Codex's "Always allow this command" flow. The approval decision is passed via the permission system with the specific command amendment payload.
+    *   _Credit:_ Thanks to @OrdinarySF — commits ported into the monorepo from [slopus/happy#299](https://github.com/slopus/happy/pull/299) and [slopus/happy-cli#102](https://github.com/slopus/happy-cli/pull/102).
+*   **Tool ID Alignment:** Permission requests and cached amendments are now strictly keyed by the **MCP Tool Call ID** to prevent mismatches.
+*   **MCP result correctness:** Codex MCP tool results preserve falsy `{ Ok: ... }` / `{ Err: ... }` outputs (no lossy `||` fallthrough), with unit tests.
+    *   Tool correlation prefers stable `call_id` where available, reducing “wrong tool result attached” edge cases.
+*   **MCP tool calls surfaced:** Codex `mcp_tool_call_begin` / `mcp_tool_call_end` events are surfaced into the transcript as tool calls/results (prefixed `mcp__...`) for consistent UI rendering.
+*   **MCP bridge reliability:** the Happy MCP bridge is launched via `process.execPath` (node/bun) to avoid relying on `.mjs` executable bits across runtimes.
+    *   _Credit:_ Thanks to @OrdinarySF — commits ported into the monorepo from [slopus/happy-cli#101](https://github.com/slopus/happy-cli/pull/101).
+*   **MCP transport safety:** Codex MCP server detection is more tolerant of version output (`codex` vs `codex-cli`, optional `v` prefix) and avoids printing full elicitation payloads to stdout (debug-only, redacted logging instead).
+*   **Tool tracing (debugging):** CLI can emit JSONL tool traces and includes a fixture extractor script for building stable tool/permission fixtures from traces.
+    *   Tracing includes permission request/response events and is broadened for more tool surfaces (while keeping metadata wakeup safety).
+
+---
+
+## 🛡️ Permissions & Safety
+
+### Persistent Permission State
+*   **Message-Derived Restoration:** Permission modes (e.g., "Read-Only", "Safe-Yolo") are now inferred from the **last user message** in the transcript. This ensures that permission state follows the session history accurately across devices, even if local state is lost.
+*   **Arbitration:** Permission changes are arbitrated using server-aligned timestamps to prevent race conditions when multiple devices update the mode simultaneously.
+*   **Default Permissions:** Users can now define default permission modes per Agent Type (e.g., default to "Read-Only" for Codex but "Plan" for Claude) in their profile settings.
+*   **Cross-agent normalization:** permission modes are normalized/clamped per agent and mapped across flavors (Claude ↔ Codex/Gemini) so switching agent types preserves intent instead of silently falling back to incompatible modes.
+*   **Carry mode across remote↔local:** sessions track `lastPermissionMode`, and local spawns/threading update CLI args so switching local/remote does not drop the active policy.
+*   **Permission mode options helper:** centralized per-agent mode lists/labels/icons and normalization to prevent UI drift between agents (descriptions are still hardcoded English where used).
+*   **Mode cycling correctness:** keyboard/UI cycling is clamped to the active agent’s valid modes so users can’t get “stuck” on an invalid mode.
+*   **Per-session allowlists (Codex/Gemini):** CLI persists “always allow” tool approvals per session using a stable tool identifier and a hardened shell command allowlist, with focused unit tests.
+*   **Metadata-published mode:** the CLI publishes `permissionMode` (+ `permissionModeUpdatedAt`) into session metadata at session creation and on changes (Claude/Codex/Gemini), so the UI can seed state even before the first app-originated message meta exists.
+*   **No-op stability:** permission mode updates do **not** bump `permissionModeUpdatedAt` unless the effective mode actually changed (prevents “latest wins” churn overriding real user selections).
+
+### Secrets Vault
+*   **Encrypted Storage:** credentials and sensitive env vars are sealed in `SecretString` containers before persistence. Plaintext values are never stored in settings.
+*   **Requirement Resolution:** A new `SecretRequirementModal` resolves missing secrets at spawn time, allowing users to provide "session-only" keys in memory ("Enter Once") or select from the vault.
+    *   Secret requirement UX is modularized and can be used via a dedicated picker route in the New Session flow.
+*   **UI Privacy:** Env var cards enforce masking (`***`) for vault-backed values.
+*   **Inline add UX:** saved secrets (and env vars) can be added inline via an expander with Cancel/Save actions (reduces modal churn; covered by tests).
+*   **Saved Secrets + bindings:** secrets are stored as **Saved Secrets** and can be bound per profile/env var (profile → env var → secret id). Drafts never persist plaintext; session-only values are encrypted before draft persistence.
+*   **Tolerant parsing:** one malformed saved secret no longer wipes other valid secrets (invalid entries are dropped individually; regression test included).
+
+### Daemon Process Safety
+*   **Strict Reattach:** The daemon persists "session markers" to disk. On restart, it only re-adopts processes if the **PID and Command Hash** match exactly.
+*   **Safe Kills:** The daemon verifies process identity before sending SIGTERM, preventing accidental killing of reused PIDs.
+*   **Cross-stack safety:** marker adoption and webhook updates are gated by `HAPPY_HOME_DIR` so a daemon never reattaches or kills sessions from another stack.
+
+---
+
+## 🖥️ Terminal & Session Management
+
+### Inactive Session Resume
+Users can now reconnect to stopped or crashed sessions.
+*   **Resume Flow:** The UI offers a "Resume" action for inactive sessions.
+*   **Codex Resume:** Implemented via a `codex-mcp-resume` bridge that re-hydrates session context using MCP.
+*   **Experimental gating (Codex):** Codex resume is disabled by default and requires explicit enablement (UI experiment + per-spawn flag), plus daemon-side gating (fail-closed) so we never “silently” resume Codex without user intent.
+*   **Resume server install/status (Codex):** machines can report/install the Codex resume MCP server into a Happy-owned prefix (with logged installs + version/status reporting, Windows-aware binary checks).
+    *   The install spec is explicit/user-provided (default is empty) so we don’t ship fork-specific defaults as global behavior.
+    *   Codex resume install/update/reinstall modals are localized in both Machine and New Session screens and share consistent success/error framing (including `deps.*` status strings).
+*   **Local session persistence:** the machine persists a per-session file under `HAPPY_HOME_DIR/sessions/<happySessionId>.json` (metadata, agentState, versions) to make reattach/resume possible.
+*   **Resume plumbing (Happy session resume):** the UI calls a `resume-session` RPC and securely provides the **session encryption key** so the daemon can reconnect to the existing Happy session (`--existing-session <happySessionId>`). This path is intentionally UI-only (a CLI user cannot resume an existing Happy session without the key).
+*   **Safer resume flow:** resume avoids passing message payloads via spawn env; instead the UI enqueues the user message first (pending/metadata queue), then requests a spawn-only resume so the agent drains staged messages normally.
+*   **Vendor resume (CLI-supported):** the CLI supports resuming *vendor* sessions inside **new Happy sessions** via `--resume <vendorSessionId>` where supported (Claude baseline; Codex is experimental and gated; OpenCode currently falls back because its ACP backend lacks `loadSession`).
+*   **New-session resume:** New Session supports selecting a resume id (capability-gated), persists it in the New Session draft, and includes it in the spawn payload when supported.
+*   **Resume request shape hardening:** UI resume no longer requires passing an `agentSessionId`; resume is keyed by Happy session id + agent type so vendor-id derivation happens on the machine/daemon side.
+*   **Capability-gated resume UX:** resume affordances are gated by machine capabilities/agent registry (per agent type) and the session UI surfaces clearer inactive/offline/pending notices during resume workflows.
+    *   Resume capability helpers use the agent registry and include vendor resume-id lookup helpers; temp session data is typed to `AgentId` to reduce agent-type mismatches.
+*   **Offline resume safety:** offline/continue tooling uses a safer `offlineSessionStub` (EventEmitter-based, aligned to the real client surface) to avoid “missing method/event” crashes.
+
+### Tmux & Headless Support
+*   **Headless Mode:** Support for spawning "headless" sessions via `happy-cli --tmux`.
+*   **Attach Tooling:** New `happy attach` command handles identifying and attaching to running tmux sessions.
+*   **Security:** Fixed path traversal vulnerabilities in terminal attachment metadata filenames (`encodeURIComponent` for session filenames) and blocks unsafe legacy fallback reads when `sessionId` contains path separators.
+*   **Attach metadata:** CLI records per-session terminal metadata (requested mode, fallback reason, tmux target/tmpDir) and persists local attach info atomically once a session ID exists (Codex/Gemini/Claude parity).
+*   **TMUX correctness:** targeting/parsing is hardened (prefers `TMUX_PANE`, rejects invalid target injection, correct kill-window targeting) with focused tests.
+*   **TMUX instance isolation:** supports per-instance socket paths (`-S <socket>`) and passes `TMUX_TMPDIR` via the tmux command environment (not conflated with socket path), with deterministic session selection and opt-in integration tests.
+*   **Tmux reliability:** tmux spawn/attach is hardened (including retrying `new-window` on index conflicts) and avoids attach/spawn edge cases that could desync terminal state.
+*   **Daemon tmux spawn:** daemon accepts terminal spawn options, supports tmux spawn + isolated servers, strips legacy `TMUX_*` env from agent env, and passes internal runtime flags to surface fallback reasons when tmux is unavailable.
+*   **Headless argv validation:** headless tmux argv validation fails closed on missing/invalid `--happy-starting-mode` values.
+
+### General Improvements
+*   **Remote-Only Agents display in terminal:** we have made it clearer in the CLI when starting remote-only agents (Codex, OpenCode, Gemini), so that users are not confused anymore as to why they cannot send messages using the terminal to those agents.
+*   **`happy connect` clarifications:** we also made it clearer which providers currently supports `happy connect` and which ones are not wired into Happy yet (only connection work, but then it's not effectively used anywhere yet), to reduce confusion with `happy connect claude` and `happy connect codex` not changing the authentication of the CLI yet.
+
+---
+
+## 🤝 Session Sharing (Friends + Public Links)
+
+Happy sessions can be shared securely with other users, either directly (friends-only) or via a public view-only link.
+
+*   **Direct sharing (friends-only):** a session owner/admin can share a session with friends and assign an access level (`view`, `edit`, `admin`). Shared sessions appear in the session list with clear indicators.
+    *   Sharing management is restricted to the session owner/admin (non-admin recipients cannot manage shares).
+    *   The session view enforces access levels (e.g. view-only disables sending/agent input).
+*   **Public share links (view-only):** a session owner can create a public link with optional expiry and max-uses limits.
+    *   Public share access is always view-only for safety.
+    *   Links can require explicit consent before access when detailed access logging is enabled.
+*   **Key handling + privacy:** the session data encryption key is wrapped for sharing:
+    *   For direct sharing, the client encrypts the session DEK for the recipient using their published content public key (verified against the recipient’s signing key binding).
+    *   For public links, the client generates a token and encrypts the session DEK using that token; the server stores only a hash of the token (not the token itself).
+*   **Realtime updates:** share changes (direct shares and public links) emit realtime events so owners/recipients see updates promptly without a full refresh.
+*   **Feature gating:** the server exposes `/v1/features` so the app can detect whether session sharing/public sharing/content keys are supported and adjust UI accordingly.
+*   **Credit:** Thanks to @54m [slopus/happy#356](https://github.com/slopus/happy/pull/356) (UI) and [slopus/happy-server#25](https://github.com/slopus/happy-server/pull/25) (server) — this PR ports those changes into the monorepo and applies additional fixes/hardening.
+
+## 💅 UI & UX Improvements
+
+### New Session Wizard
+*   **Complete Rewrite:** The creation flow is now a route-based wizard (`NewSessionWizard`) with dedicated pickers for Machine, Path, and Profile.
+*   **Profile 2.0:** Migrated profiles to be purely environment-variable based (removing legacy provider configs).
+*   **Pre-flight Checks:** The wizard runs `preview-env` to ensure the selected machine meets the profile's requirements before spawning.
+*   **Picker/navigation stability:** picker screens avoid inline `Stack.Screen` options and pick flows were stabilized to reduce “stale selection / wrong route params” issues; wizard can pre-visualize the selected machine for faster verification.
+*   **Web + resume UX polish:** on web, the new-session wizard is presented in a `BaseModal` with an explicit header/close; Codex resume “not installed” dialogs are localized and route users to the Machine screen to install/inspect the resume server.
+*   **Wizard polish:** Codex resume banner strings in the wizard are localized and wizard sections use shared header-row primitives for consistency.
+*   **Draft persistence + pick flows:** wizard state is persisted before navigating to picker/edit screens, so leaving the wizard doesn’t reset inputs; selections are returned via route params (not global callback plumbing).
+*   **Resume pick reliability:** resume session id selection is persisted in new-session drafts and paste-from-clipboard is hardened (safe fallback when clipboard reads fail).
+*   **iOS navigation reliability:** picker and profile-edit screens are also presented as iOS `containedModal` (with explicit back buttons) so they never render “behind” the wizard modal.
+*   **Recent/favorites UX:** added recent machines/paths helpers and more deterministic favorites/search behavior in picker screens (with feature toggles for picker-search UX).
+*   **Agent compatibility correctness:** when the profile changes, the wizard clamps agent type to supported backends and maps permission modes across agents rather than resetting blindly.
+*   **Secrets + terminal integration:** the wizard resolves required secrets via the secrets/vault flow (machine env presence checks, saved-secret bindings, or “enter once”), and passes terminal/tmux spawn options into session creation (including tmux warnings when requested but not detected).
+*   **Performance hardening:** draft/settings writes are debounced and often deferred via `InteractionManager.runAfterInteractions` on native to keep iOS taps/animations responsive.
+
+### UI Primitives & Polish
+*   **Unified Overlay System:** Introduced `Popover` and `OverlayPortal` to handle floating UI consistently on Web (Radix-based) and Native.
+*   **Modal Fixes:** Fixed iOS touch-blocking on stacked modals and restored Expo Web modal behavior (enables `EXPO_UNSTABLE_WEB_MODAL=1`, pins/patches `expo-router`, and ensures patches apply in both hoisted and non-hoisted installs).
+    *   Also pins `libsodium-wrappers` to a compatible version and aligns patch-package directories so the Expo-router patch is applied reliably.
+*   **List + row-action primitives:** added a shared `SearchHeader`, refactored `SearchableListSelector` grouping/search placement, and added inline row actions with an overflow menu modal (plus click-through guards).
+*   **List/pending polish:** added reusable item-group row-position/title primitives and refined list/pending UI for more consistent layout/behavior (with targeted divider/row tests).
+*   **Unsaved-changes prompts:** added a reusable “discard/save/keep editing” alert helper used by picker-friendly edit screens.
+*   **Popover + portal overlays:** added `OverlayPortalHost`/`OverlayPortalProvider` and a `Popover` primitive with web/native portal support, spotlight/backdrop options, and a `ModalPortalTargetProvider` for correct web focus/stacking inside modals.
+*   **Popover hardening:** improved web anchor measurement (DOM `getBoundingClientRect()` fallback + retries) and iOS portal pointerEvents to prevent invisible/click-through overlay failures.
+    *   Web popover positioning accounts for scroll offsets and uses a dedicated portal target + more robust measurement to avoid “misplaced overlays” during scroll/resize.
+*   **Scroll edge indicators:** list edge indicators are shown without fades when appropriate (improves discoverability without relying on subtle animations).
+*   **WebAlertModal safety:** ensures an empty `buttons: []` config still renders a default `OK` button (prevents non-dismissible alert modals).
+*   **Overlay action reliability:** improved “close-then-act” behavior for row-action menus (`InteractionManager` with timeout fallback) so actions aren’t delayed indefinitely under continuous interactions.
+*   **i18n hygiene:** many previously hard-coded UI literals (including error alerts and permission/microphone prompts) are now translated via `t(...)` keys; tooling was added to help find remaining untranslated literals.
+*   **Specialized Tool Views:** Added optimized renderers for common tools (Bash, ReadFile, Grep) and structured ACP results.
+    *   Tool views handle additional ACP shapes (e.g. diff items and “read” aliases) and can infer pending permissions from tool-call surfaces to keep the transcript state consistent.
+*   **Error Surfacing:** Agent errors (Codex/Gemini quota, MCP failures) are now surfaced as visible status messages in the transcript.
+    *   Includes formatted “status” events forwarded from CLI runtimes so Codex/Gemini startup/stream/tool failures are actionable (not silent hangs).
+    *   Includes follow-up polish for Codex MCP startup failures and Gemini quota reset formatting (regression-tested).
+*   **Input + editor polish:** prompt input adapts to keyboard height on native and env-var editor cards were refined for clearer editing ergonomics.
+
+---
+
+## 🛠️ Foundations & DevX
+
+*   **Test Harness:** Root scripts validate the full monorepo surface (expo-app + cli + server) via `happys test/typecheck`. Added **Vitest stubs** for Expo/React Native modules to enable fast Node-based unit testing of UI logic.
+*   **Test deps alignment:** updated `react-test-renderer` to stay aligned with the repo’s React version (prevents subtle test renderer mismatches).
+*   **Expo iOS build stability:** patched `@more-tech/react-native-libsodium` podspec evaluation so `pod install` doesn’t fail when `folly_version` is undefined (falls back to `RCT-Folly` when needed).
+*   **Expo install + web runtime stability:** deterministic `expo-app` postinstall that reliably runs `patch-package` even when hoisted; includes libsodium-wrappers patching plus a web adapter that forces the CJS build to avoid Metro parsing failures from ESM/top-level `await`.
+    *   Also runs patching from both repo root and `expo-app/` so patches apply for hoisted deps *and* non-hoisted deps (e.g. `expo-router`).
+    *   Postinstall includes verification that critical patches (e.g. `expo-router`) were actually applied, failing fast when patching silently didn’t happen.
+*   **App variant hardening:** added opt-in overrides (`EXPO_APP_NAME`, `EXPO_APP_BUNDLE_ID`, `EXPO_APP_SCHEME`) and safe fallbacks when `APP_ENV` is unknown (prevents undefined config values, reduces multi-install collisions).
+*   **Test determinism:** defines `__DEV__ = false` in Vitest so dev-gated code paths behave predictably under unit tests.
+*   **Unistyles Migration:** Migrated the entire codebase (`expo-app`) from `StyleSheet` to `react-native-unistyles` for consistent theming.
+    *   Includes a guard test to enforce “no `StyleSheet` imports from `react-native`” and prevent regressions.
+*   **Repo commit conventions:** added Conventional Commits guidelines for tooling (Copilot commit instructions).
+*   **Workspace hygiene:** ignores `.project` artifacts and adds naming-conventions documentation used by tooling/agents.
+*   **i18n Sweep + tooling:** refactored i18n types to be derived from `translations/en.ts`, expanded locale dictionaries for new surfaces, and added scripts to compare translation coverage and scan for likely-untranslated literals (with follow-up parsing fixes for file kinds and `:` in literal grouping keys).
+    *   Adds device locale helpers (shared + native) used by the text/runtime layer when selecting the best locale.
+*   **Production log hygiene:** gated noisy detection/realtime debug logs behind `__DEV__` (keeps errors as errors; avoids incidental message/metadata logging).
+*   **Log Redaction:** Hardened CLI logging to redact env vars and secrets from debug output.
+
+---
+
+## 📦 Appendix: Additional Details
+
+Additional implementation details and edge-case hardening notes that didn’t fit cleanly in the high-level sections above.
+
+### Auth & Storage Scoping
+
+*   **Auth token persistence hardening (web):** `tokenStorage` no longer throws on malformed `localStorage` JSON; `setItem/removeItem` failures return `false` (quota/security errors handled).
+*   **CLI auth ergonomics:** `happy auth login --no-open` (and `HAPPY_NO_BROWSER_OPEN`) skips auto-opening a browser for login; unit-tested.
+*   **Scoped native storage:** storage keys (and selected MMKV ids) are scope-qualified via `EXPO_PUBLIC_HAPPY_STORAGE_SCOPE` to prevent cross-stack/worktree state bleed on device.
+*   **Unauthenticated route guard:** app layout redirects unauthenticated users off protected routes (public allowlist is explicit) to prevent flashes of protected screens.
+    *   Includes a follow-up fix to avoid React hooks-order violations in the redirect path (regression-tested).
+*   **Auth failure surfacing:** raw message parsing tolerates `usage.service_tier: null` so messages/events aren’t dropped on schema failures (helps keep auth/401 failures visible).
+
+### Settings, Profiles, and Requirements
+
+*   **Settings parsing hardening:** tolerant per-field parsing so one invalid field doesn’t reset everything; invalid profiles are filtered individually instead of failing the whole settings object.
+*   **Profile shape migration:** legacy provider config objects are normalized into `environmentVariables` entries (e.g. `OPENAI_*`, `ANTHROPIC_*`, `AZURE_OPENAI_*`, `TOGETHER_*`); non-persistable fields (e.g. `startupBashScript`, `tmuxConfig.updateEnvironment`) are dropped from the persisted GUI profile model.
+*   **Settings sync convergence:** added “always write” `replaceSettings(settings, version)` to converge after server/account switching or server-side resets (used to prevent version mismatch retry loops).
+*   **Env var templates:** added parse/format support for `${VAR}`, `${VAR:-fallback}`, `${VAR:=fallback}` and bash-like empty-string fallback semantics.
+*   **Profiles:** profiles are now centered on env-var requirements/selection (with supporting UX + built-in profile gating fixes).
+*   **`preview-env` end-to-end:** UI prefers daemon-computed “effective spawn env” (supports `extraEnv` expansion + secrets policy `none|redacted|full` + per-key sensitivity metadata); falls back to *non-sensitive only* bash probing when unsupported (node-backed JSON protocol when available; robust unset sentinel parsing; avoids pulling secret-like values into UI memory). Daemon handler validates key names and caps requests; sensitive-key detection is heuristic with an overridable (safe-fallback) regex.
+    *   `preview-env` accepts lowercase keys and explicitly blocks prototype-pollution keys (`__proto__` / `constructor` / `prototype`), using `Object.create(null)` to avoid inherited properties.
+*   **Model modes:** per-session model-mode persistence + UI allowlisting/clamping (invalid model modes cannot be written from the session UI; persisted maps are filtered to an allowlist).
+*   **Experiments + agent-input customization:** settings gained per-experiment toggles (preserving legacy “master experiments” behavior) and new agent-input layout/density controls.
+    *   The master “experiments” toggle also controls Codex resume enablement (so disabling experiments disables `expCodexResume`).
+*   **Session settings consolidation:** message-send policy and tmux preferences are unified under session settings (`sessionMessageSendMode`, `sessionUseTmux`, etc.) with migrations/aliases for legacy keys and routes.
+    *   Settings list items are localized (e.g. the Session settings row title/subtitle), and Spanish experiment subtitles are fully translated.
+*   **Credential requirements resolver:** profiles can declare required secret env vars / machine-login requirements; UI preflights readiness via `preview-env` and provides a resolver modal (use machine env, select a saved credential, or enter once for session-only use).
+
+### Sessions UX
+
+*   **Message list quality-of-life:** unread badges, inactive-session grouping, archive fallback behavior when kill RPCs aren’t available, and small transcript/message conveniences (e.g. copy-to-clipboard for message blocks).
+    *   Unread state is cross-device: read markers are stored in encrypted session metadata (`readStateV1`) and updated on focus/blur with debounced writes.
+    *   Path display is safer: avoids false “under home” matches when formatting paths relative to `homeDir`. Session list formatting consistently shows `~`-prefixed home-relative paths.
+*   **Session rename:** session info screen supports renaming by updating encrypted session metadata via `update-metadata` (version-checked), with a prompt-based UX.
+*   **Agent-visible errors:** improved surfacing of agent failures (Codex/Gemini quotas/MCP failures) as explicit transcript status, not silent failures.
+    *   Session-level error fallbacks and profile-info modal copy are localized (avoids hard-coded English “Error / failed to …” messages).
+*   **Codex runtime correctness:** Codex ignores per-message model overrides; permission-mode changes restart Codex sessions with explicit context drop (no automatic resume attempt), and mode hashing ignores `model` to avoid spurious restarts.
+*   **Codex/Gemini readiness:** prime `agentStateVersion` immediately after session creation so UI readiness flips true without requiring an `update-state` event.
+
+### CLI / Sync / Daemon reliability
+
+*   **Daemon ownership gating:** reattach/restart safety based on persisted per-PID “session markers” under `HAPPY_HOME_DIR`, strict PID classification, and process-command-hash verification; avoids unsafe cross-process interactions and PID reuse hazards.
+    *   Resume requests are idempotent (avoid duplicate processes), and the daemon maintains per-session attach files/metadata merges to support safe reattach and clearer session startup behavior.
+    *   The daemon reports and persists session termination (including keeping sessions tracked until exit) so the app/CLI can present accurate session end state.
+*   **Atomic daemon state persistence:** daemon state reads are schema-validated (Zod) and retried on transient errors; writes are atomic (tmp + rename, with Windows fallbacks and tmp cleanup).
+    *   Includes a retry path for `ENOENT` when the daemon state file appears shortly after startup (race hardening; regression-tested).
+*   **Refactor + opt-in integration tests (daemon):** extracted `pidSafety`/`reattach` helpers and added opt-in “real process” integration tests gated by `HAPPY_CLI_DAEMON_REATTACH_INTEGRATION=1` for validating PID hashing + marker adoption on the host OS.
+*   **CLI reconnection correctness:** waiter lifecycle cleanup, reconnection/backoff hardening, and metadata/socket coordination fixes.
+    *   Includes a fix where `waitForMetadataUpdate()` resolves `false` on socket disconnect and always cleans up listeners (prevents hanging awaiters; tested).
+*   **Capabilities cache race hardening:** prevents late/stale overlapping prefetches from overwriting newer loaded snapshots (token-guarded updates; race regression test).
+*   **Runtime support (daemon subprocesses):** daemon-spawned subprocess invocation supports `node` or `bun` (selectable) with tested invocation building; missing entrypoints surface a clear error instead of failing silently.
+*   **Sync robustness:** transport parsing guards + disconnect/await safety for reliability in flaky connectivity scenarios (kept separate from MessageQueueV1 semantics).
+    *   Includes a fix to ensure `invalidateAndAwait()` never hangs forever when the sync command throws (awaiters resolve; retries are bounded; tests included).
+    *   Failures are counted consistently even under custom backoff implementations (`failuresCount` increments per attempt; tests de-flaked by stubbing jitter).
+    *   Metadata waiters are hardened against lost wakeups and abort races, avoiding “hang forever” edge cases under concurrent message/pending events.
+*   **RPC compatibility signal:** server returns a structured `errorCode=RPC_METHOD_NOT_AVAILABLE` (while preserving legacy message strings) so the app can do reliable back-compat fallbacks without brittle string matching.
+*   **Sync perf + crash-safety:** debounced pending settings persistence with flush-on-background to avoid losing last-second toggles; added a de-duped `refreshMachinesThrottled` helper to prevent network churn.
+*   **Error parsing hardening:** guards JSON parsing for non-JSON error bodies (e.g. GitHub OAuth config 400 and disconnect 404s) and preserves correct `HappyError(kind/status)` typing.
+*   **Spawn safety boundaries:** GUI-spawned sessions do not inherit the CLI’s active profile implicitly; profile env injection is opt-in from the caller (prevents surprising env leakage).
+*   **Profile identity propagation:** `profileId` is threaded through daemon spawn into session metadata (identity only; separate from env var contents), enabling consistent UI display across devices.
+*   **Log redaction (daemon/CLI):** spawn logs no longer print tokens or env var values; doctor output masks `${VAR:-default}` / `${VAR:=default}` templates to avoid leaking embedded secrets.
+*   **Offline buffering restored:** CLI socket sends rely on socket.io buffering when disconnected (with tests), instead of refusing to emit while offline.
+*   **Spawn env flexibility:** spawn RPC accepts arbitrary env var maps (typed as `Record<string,string>`) to keep GUI/CLI interoperable as provider keys evolve.
+    *   Spawn env inputs are sanitized (including prototype-pollution defenses) before use to reduce risk from untrusted keys.
+*   **CLI profile schema alignment:** CLI persistence drops legacy provider config objects and migrates them into env vars at parse-time (preserves data; env-var based profiles are the single source of truth).
+*   **Legacy tmuxConfig removal:** CLI profile schema removes deprecated `tmuxConfig` and stops exporting tmux env vars from profiles (terminal behavior is driven by explicit terminal spawn options).
+
+### Server hardening beyond “Server Light”
+
+*   **Serve UI from server:** hardened optional static UI serving and SPA fallback behavior; improved missing bundle/index handling (404 vs 500), including in SPA error handlers.
+*   **Public files safety:** strict path normalization and segment-wise URL encoding in file serving routes (rejects traversal/absolute/drive-letter input; encodes `#`/`?` safely).
+*   **Storage validation (S3/Minio):** fail-fast env validation and bucket existence checks (validates `S3_PORT` range and errors if the bucket does not exist).
+
+### Misc
+
+*   **Codex `/clear` handling:** treat `/clear` as a session boundary so Codex session state resets deterministically.
+    *   _Credit:_ Thanks to @zkytech — commits ported into the monorepo from [slopus/happy-cli#72](https://github.com/slopus/happy-cli/pull/72).
+*   **Friends UX/reliability:** follow-up hardening for friends surfaces (e.g., stable error handling/search behaviors, localized search failure messaging via stable error codes).
+    *   Friends/Inbox routes are experiment-gated (with hooks + settings toggle) so access/routing is consistent when the feature is disabled.
+
+---
+
+## ✅ Test Plan (what maintainers should validate)
+
+This is the suggested “high-signal” manual test checklist for the master PR:
+
+*   **Server Light:** boot light flavor, create sessions, verify SQLite persistence, verify local-files/public-file serving, verify optional UI serving (SPA routes + missing bundle handling).
+*   **MessageQueueV1:** queue messages while agent is busy/offline, resume connectivity, verify CAS semantics prevent duplication, verify in-flight removal happens only after delivery confirmation.
+*   **Capabilities + `preview-env`:** verify capability detection for key tools (Claude/Codex/Gemini/Tmux/OpenCode), verify `preview-env` detects missing requirements and wizard shows actionable preflight errors.
+*   **Session Sharing:** share a session with a friend, verify access levels (`view/edit/admin`) and enforcement (view-only disables send), verify realtime updates on share changes, create/rotate/disable a public link (expiry/max-uses), verify consent-required flows, and verify `/share/[token]` viewing works as expected.
+*   **Secrets Vault:** create/select secrets, verify masking/redaction (no plaintext persistence), verify requirement modal supports “enter once” vs vault selection.
+*   **Permissions:** verify default mode per agent, verify mode restoration from transcript across device restart, verify agent-specific allowlists/approvals (Codex/Gemini), verify AskUserQuestion/ExitPlan flows complete via the session `permission` RPC (including answers-on-permission where supported).
+*   **Resume:** resume inactive sessions end-to-end (Claude + Codex), verify no transcript loss, verify terminal/runner state is rehydrated correctly.
+*   **Terminal/TMUX:** headless tmux session spawn, attach to existing sessions, verify targeting correctness, verify switching local↔remote without orphaned processes.
+*   **UI primitives:** overlays/popovers/modals on iOS + web (especially stacked modal touch behavior + Expo web modal behavior).
+
+---
+
+## 🔗 GitHub Issue Crosswalk (happy + happy-cli)
+
+This is a conservative, audit-driven mapping between GitHub issues and the changes described above.
+
+(Scan date: 2026-01-26; audit base: `upstream/main` vs `leeroy-wip`)
+
+**Legend**
+- **Likely addressed/implemented**: strong match + direct code changes in `leeroy-wip` that plausibly resolve the issue.
+- **Partially addressed / needs validation**: PR improves the area, but does not obviously guarantee a full fix.
+- **Related (unverified)**: same surface area; included for reviewer context only.
+- **Already in upstream (PR refines)**: feature existed on `upstream/main`; changes here are refinements (scoping, hardening, polish).
+
+### Server selection & self-hosting (server URL + deployment/docs)
+- **Already in upstream (PR refines):** slopus/happy#51, slopus/happy#340
+- **Partially addressed / needs validation:** slopus/happy#142, slopus/happy#246, slopus/happy#284, slopus/happy#381, slopus/happy#420, slopus/happy#463
+- **Related (unverified):** slopus/happy#415, slopus/happy#421, slopus/happy#54, slopus/happy#472, slopus/happy-cli#14, slopus/happy-cli#31
+
+### MessageQueueV1 / pending-message reliability
+- **Likely addressed/implemented:** slopus/happy#260, slopus/happy#349
+- **Partially addressed / needs validation:** slopus/happy#261, slopus/happy#297, slopus/happy#405, slopus/happy#474
+
+### Inactive session resume
+- **Likely addressed/implemented:** slopus/happy#23, slopus/happy#98, slopus/happy#147, slopus/happy#353, slopus/happy#426, slopus/happy#437
+- **Related (unverified):** slopus/happy#73, slopus/happy-cli#10
+
+### Claude reliability (switching + terminal state restoration)
+- **Likely addressed/implemented:** slopus/happy#301, slopus/happy#304
+- **Partially addressed / needs validation:** slopus/happy#90, slopus/happy#430, slopus/happy#424, slopus/happy#46, slopus/happy#425
+- **Related (unverified):** slopus/happy#123, slopus/happy#422, slopus/happy#423, slopus/happy#443, slopus/happy#379, slopus/happy-cli#11
+
+### Codex MCP / approvals / tool-call correctness
+- **Likely addressed/implemented:** slopus/happy#167, slopus/happy#207, slopus/happy-cli#39
+- **Partially addressed / needs validation:** slopus/happy#157, slopus/happy#158, slopus/happy#164, slopus/happy#181, slopus/happy#445, slopus/happy#447, slopus/happy#470
+- **Related (unverified):** slopus/happy#146, slopus/happy#139, slopus/happy#247, slopus/happy-cli#43
+
+### Permission modes / YOLO / approval state persistence
+- **Likely addressed/implemented:** slopus/happy#29, slopus/happy#446
+- **Partially addressed / needs validation:** slopus/happy#206, slopus/happy-cli#150, slopus/happy#371, slopus/happy#350
+- **Related (unverified):** slopus/happy#375, slopus/happy#225, slopus/happy#146, slopus/happy#365, slopus/happy#469, slopus/happy-cli#147, slopus/happy#227
+
+### ACP agent expansion (Codex ACP + OpenCode ACP + Auggie ACP + agent catalog)
+- **Likely addressed/implemented (OpenCode):** slopus/happy#265, slopus/happy#344, slopus/happy#394, slopus/happy#477
+- **Likely addressed/implemented (Auggie, experimental):** slopus/happy#133
+- **Partially addressed / needs validation (broader ACP roadmap items):** slopus/happy#217, slopus/happy#267
+
+### Slash commands (Claude + ACP)
+- **Partially addressed / needs validation:** slopus/happy#14, slopus/happy#203
+- **Related (unverified):** slopus/happy#182
+
+### Models / Gemini availability
+- **Partially addressed / needs validation:** slopus/happy#176, slopus/happy-cli#146, slopus/happy#471
+
+### Daemon process safety (reattach/ownership gating) + service requests
+- **Partially addressed / needs validation:** slopus/happy#175, slopus/happy#191
+- **Related (unverified):** slopus/happy#433, slopus/happy#434
+
+### Auth / linking / backups
+- **Likely addressed/implemented:** slopus/happy#19
+- **Partially addressed / needs validation:** slopus/happy#399, slopus/happy#400, slopus/happy#80, slopus/happy#387
+- **Related (unverified):** slopus/happy#92
+
+### Secrets / logging / path safety
+- **Likely addressed/implemented:** slopus/happy-cli#44
+- **Related (unverified):** slopus/happy-cli#46, slopus/happy#336, slopus/happy#416
+
+### New Session Wizard + machine/endpoint selection
+- **Partially addressed / needs validation:** slopus/happy#315, slopus/happy#57
+
+### Sessions UX (unread/rename/notifications/deep linking)
+- **Partially addressed / needs validation:** slopus/happy#102, slopus/happy#305, slopus/happy#209, slopus/happy#435, slopus/happy#462, slopus/happy#86, slopus/happy-cli#28, slopus/happy#362, slopus/happy#368
+
+### Terminal/TMUX & headless attach
+- **Partially addressed / needs validation:** slopus/happy#195, slopus/happy#204
+
+### Tool UX (specialized renderers + native interaction routing)
+- **Related (unverified):** slopus/happy#128, slopus/happy#8
+
+---
+
+## 🧾 Upstream Open PRs Cross-check (double-verified)
+
+Scan date: **2026-01-26** (open PRs in `slopus/happy`, `slopus/happy-cli`, and `slopus/happy-server`).
+
+Verification method: sampled added/removed diff lines from each PR (via GitHub `pulls/<n>/files` patches) and checked whether those lines are present/absent in the monorepo branch `slopus/tmp/leeroy-wip` (file paths mapped to `expo-app/…`, `cli/…`, and `server/…`).
+
+- `PORTED`: we intentionally extracted/ported this PR into the monorepo and added explicit credits elsewhere in this PR description.
+- `VERIFIED`: strong evidence the PR’s changes are already present (or superseded) in `leeroy-wip`.
+- `PROBABLE`: meaningful overlap, but not tight enough to claim superseded without a quick human spot-check.
+
+PRs without sufficient evidence are intentionally omitted to avoid false positives.
+
+### slopus/happy
+
+#### PORTED (credited above)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy#299](https://github.com/slopus/happy/pull/299) | feat: add execpolicy approval option for Codex | @OrdinarySF | checks 61; add 93%; remove 78%; missingFiles 1 |
+| [slopus/happy#356](https://github.com/slopus/happy/pull/356) | feat: session sharing UI (friends + public links) | @54m | ported into monorepo; see Session Sharing section |
+
+#### VERIFIED (likely superseded)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy#345](https://github.com/slopus/happy/pull/345) | Add copy-to-clipboard button to message blocks | @leeroybrun | checks 14; add 100%; remove 100%; missingFiles 0 |
+
+#### PROBABLE (review)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy#372](https://github.com/slopus/happy/pull/372) | Fix possible issues introduced by #272 | @leeroybrun | checks 1407; add 83%; remove 81%; missingFiles 9 |
+| [slopus/happy#388](https://github.com/slopus/happy/pull/388) | fix: stabilize PR272 new-session UX, profiles gating, and env safety | @leeroybrun | checks 1840; add 82%; remove 88%; missingFiles 15 |
+
+### slopus/happy-cli
+
+#### PORTED (credited above)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy-cli#72](https://github.com/slopus/happy-cli/pull/72) | feat: handle /clear command as session reset in codex | @zkytech | checks 15; add 92%; remove 0%; missingFiles 0 |
+| [slopus/happy-cli#101](https://github.com/slopus/happy-cli/pull/101) | fix: use runtime execPath for MCP bridge | @OrdinarySF | checks 30; add 39%; remove 58%; missingFiles 0 |
+| [slopus/happy-cli#102](https://github.com/slopus/happy-cli/pull/102) | feat(codex): support execpolicy approvals and MCP tool calls | @OrdinarySF | checks 63; add 59%; remove 96%; missingFiles 1 |
+| [slopus/happy-cli#120](https://github.com/slopus/happy-cli/pull/120) | fix(cli): improve abort error handling to reduce spurious error messages | @cruzanstx | checks 14; add 100%; remove 100%; missingFiles 0 |
+| [slopus/happy-cli#127](https://github.com/slopus/happy-cli/pull/127) | fix: forward signals to child process in binary launcher | @fberlakovich | checks 12; add 25%; remove —; missingFiles 0 |
+| [slopus/happy-cli#139](https://github.com/slopus/happy-cli/pull/139) | fix: move claudeArgs to end of args array for slash command support | @jiogallardy | checks 6; add 100%; remove 0%; missingFiles 0 |
+
+#### PROBABLE (review)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy-cli#123](https://github.com/slopus/happy-cli/pull/123) | Fix possible issues introduced by #107 | @leeroybrun | checks 413; add 81%; remove 75%; missingFiles 8 |
+| [slopus/happy-cli#134](https://github.com/slopus/happy-cli/pull/134) | fix: stabilize PR107 tmux spawn, offline buffering, and bun runtime | @leeroybrun | checks 414; add 81%; remove 76%; missingFiles 9 |
+
+### slopus/happy-server
+
+#### PORTED (credited above)
+
+| PR | Title | Author | Evidence |
+| --- | --- | --- | --- |
+| [slopus/happy-server#25](https://github.com/slopus/happy-server/pull/25) | feat: session sharing API/server support | @54m | ported into monorepo; see Session Sharing section |

package/docs/happy-development.md

@@ -131,7 +131,9 @@ See: `docs/server-flavors.md`.
   - Prefer `happys stack <stack> ...` commands (typecheck/lint/build/test/dev/start).
   - To run `happy-cli` against a specific stack: `happys stack happy <stack> -- <happy args...>` (stack shorthand: `happys <stack> happy ...`).
 - **Do not “kill all daemons”**
-  - Multiple stack daemons are expected. Stop stacks explicitly (`happys stack stop …` or `happys stop …`).
+  - Multiple stack daemons are expected.
+  - If you use stack daemon **identities** (`--identity=<name>`), multiple daemons for the *same stack* can also be intentional.
+  - Stop stacks explicitly (`happys stack stop …` or `happys stop …`), or stop a specific daemon identity (`happys stack daemon <stack> stop --identity=<name>`).
 - **Main stack safety**
   - Avoid repointing `main` stack component dirs to worktrees. Use a new stack.
   - `happys wt use …` will warn/refuse for `main` unless you pass `--force`.
@@ -748,6 +750,21 @@ Login (interactive):
 happys stack auth <stack> login
 ```
 
+Multiple accounts on one stack (optional): use an identity and disable auto browser open so you can choose the
+browser profile/account you authenticate as:
+
+```bash
+happys stack auth <stack> login --identity=account-a --no-open
+happys stack auth <stack> login --identity=account-b --no-open
+```
+
+Start/stop a specific identity daemon:
+
+```bash
+happys stack daemon <stack> start --identity=account-a
+happys stack daemon <stack> stop  --identity=account-a
+```
+
 Non-interactive repair (copy credentials + seed accounts from `main`):
 
 ```bash