happy-stacks 0.3.0 → 0.5.0

package/README.md

@@ -4,28 +4,42 @@ Run [**Happy**](https://happy.engineering/) locally and access it remotely and s
 
 ## What is Happy?
 
-Happy is an UI/CLI stack (server + web UI + CLI + daemon) who let you monitor and interact with Claude Code, Codex and Gemini sessions from your mobile, a web UI and/or a desktop app.
+Happy is an UI/CLI stack (server + web UI + CLI + daemon) who let you monitor and interact with Claude Code, Codex and Gemini sessions from your mobile, from a web UI and/or from a desktop app.
 
 ## What is Happy Stacks?
 
 happy-stacks is a guided installer + local orchestration CLI for Happy.
 
-If you only want to **self-host Happy**, start with the **Self-host** section below.
+If you only want to **use Happy** and self-host it on your computer, start with the **Self-host** section below.
 If you want to **develop Happy** (worktrees, multiple stacks, upstream PR workflows), see the **Development** section further down.
 
 ## Self-host Happy (install + run)
 
-### Step 1: Setup
-
-Recommended:
+### Quickstart
 
 ```bash
 npx happy-stacks setup --profile=selfhost
 ```
 
-`setup` can optionally start Happy and guide you through authentication.
+Follow the guided instructions to install Happy and launch it.
+
+### Daily use
+
+#### Configure provider API keys for the daemon
 
-### Step 2: Start Happy
+If you want the daemon to have access to provider API keys (for example OpenAI), you can set them so they are automatically loaded when the daemon starts:
+
+```bash
+happys env set OPENAI_API_KEY=sk-...
+```
+
+Then restart so the daemon picks up the new environment:
+
+```bash
+happys start --restart
+```
+
+### Start Happy
 
 Starts the local server, CLI daemon, and serves the pre-built UI.
 
@@ -33,9 +47,9 @@ Starts the local server, CLI daemon, and serves the pre-built UI.
 happys start
 ```
 
-### Step 3 (first run only): authenticate
+### Authentication
 
-On a **fresh machine** (or any new stack), the daemon needs to authenticate once before it can register a “machine”.
+On a **fresh machine**, the daemon needs to authenticate once before it can register a “machine”.
 
 ```bash
 happys auth login
@@ -47,17 +61,16 @@ If you want a quick diagnosis:
 happys auth status
 ```
 
-### Step 4: Enable Tailscale Serve (recommended for mobile/remote)
+### Enable Tailscale Serve (recommended for mobile/remote)
 
 ```bash
 happys tailscale enable
 happys tailscale url
 ```
 
-### Step 5: Mobile access
+### Mobile access
 
-Make sure Tailscale is [installed and running]
-([https://tailscale.com/kb/1347/installation](https://tailscale.com/kb/1347/installation)) on your 
+Make sure Tailscale is [installed and running](https://tailscale.com/kb/1347/installation) on your 
 phone, then either:
 
 - Open the URL from `happys tailscale url` on your phone and “Add to Home Screen”, or
@@ -69,36 +82,21 @@ Details (secure context, phone instructions, automation knobs): `[docs/remote-ac
 
 ## Development (worktrees, stacks, contributor workflows)
 
+If you want to **develop Happy** (worktrees, multiple stacks, upstream PR workflows), you can install Happy Stacks for development with:
+
 ### Setup (guided)
 
 ```bash
 npx happy-stacks setup --profile=dev
 ```
 
-### Developing from a cloned repo
+During setup, you’ll be asked where to store your **workspace** (the folder that will contain `components/` and `components/.worktrees/`).
+You can also set it non-interactively:
 
 ```bash
-git clone https://github.com/leeroybrun/happy-stacks.git
-cd happy-stacks
-
-node ./bin/happys.mjs setup --profile=dev
+npx happy-stacks setup --profile=dev --workspace-dir=~/Development/happy
 ```
 
-Notes:
-
-- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is the recommended UX (same underlying scripts).
-- To make the installed `~/.happy-stacks/bin/happys` shim (LaunchAgents / SwiftBar) run your local checkout without publishing to npm, set:
-
-  ```bash
-  echo 'HAPPY_STACKS_CLI_ROOT_DIR=/path/to/your/happy-stacks-checkout' >> ~/.happy-stacks/.env
-  ```
-
-  Or (recommended) persist it via init:
-
-  ```bash
-  happys init --cli-root-dir=/path/to/your/happy-stacks-checkout
-  ```
-
 ### Why this exists
 
 - **Automated setup**: `happys setup` + `happys start` gets the whole stack up and running.
@@ -150,6 +148,7 @@ More details + automation: `[docs/remote-access.md](docs/remote-access.md)`.
 - **Scripts**: `scripts/*.mjs` (bootstrap/dev/start/build/stacks/worktrees/service/tailscale/mobile)
 - **Components**: `components/*` (each is its own Git repo)
 - **Worktrees**: `components/.worktrees/<component>/<owner>/<branch...>`
+- **CWD-scoped commands**: if you run `happys test/typecheck/lint` from inside a component checkout/worktree and omit components, it runs just that component; `happys build/dev/start` also prefer the checkout you’re currently inside.
 
 Components:
 
@@ -198,6 +197,12 @@ happys stack pr pr123 \
   --dev
 ```
 
+Optional: enable Expo dev-client for mobile reviewers (reuses the same Expo dev server; no second Metro process):
+
+```bash
+happys stack pr pr123 --happy=123 --happy-cli=456 --dev --mobile
+```
+
 Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
 
 ```bash
@@ -226,12 +231,16 @@ npx happy-stacks setup-pr \
   --happy-cli=https://github.com/slopus/happy-cli/pull/456
 ```
 
-Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
+Optional: enable Expo dev-client for mobile reviewers (works with both default `--dev` and `--start`):
 
 ```bash
-SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
-npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
-rm -rf "$SANDBOX"
+npx happy-stacks setup-pr --happy=123 --happy-cli=456 --mobile
+```
+
+Optional: run it in a self-contained sandbox folder (auto-cleaned):
+
+```bash
+npx happy-stacks review-pr --happy=123 --happy-cli=456
 ```
 
 Short form (PR numbers):
@@ -316,12 +325,20 @@ Details: `[docs/menubar.md](docs/menubar.md)`.
 #### Mobile iOS dev (optional)
 
 ```bash
-happys mobile --help
-happys mobile --json
+# Install the shared "Happy Stacks Dev" dev-client app on your iPhone:
+happys mobile-dev-client --install
+
+# Install an isolated per-stack app (Release config, unique bundle id + scheme):
+happys stack mobile:install <stack> --name="Happy (<stack>)"
 ```
 
 Details: `[docs/mobile-ios.md](docs/mobile-ios.md)`.
 
+#### Reviewing PRs in an isolated sandbox
+
+- **Unique hostname per run (default)**: `happys review-pr` generates a unique stack name by default, which results in a unique `happy-<stack>.localhost` hostname. This prevents browser storage collisions when the sandbox is deleted between runs.
+- **Reuse an existing sandbox**: if a previous run preserved a sandbox (e.g. `--keep-sandbox` or a failure in verbose mode), re-running `happys review-pr` offers an interactive choice to reuse it (keeping the same hostname + on-disk auth), or create a fresh sandbox.
+
 #### Tauri desktop app (optional)
 
 ```bash
@@ -338,7 +355,7 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
   - (advanced) `happys bootstrap --interactive` (component installer wizard)
 - **Run**:
   - `happys start` (production-like; serves built UI via server-light)
-  - `happys dev` (dev; Expo web dev server for UI)
+  - `happys dev` (dev; Expo dev server for UI, optional dev-client via `--mobile`)
 - **Server flavor**:
   - `happys srv status`
   - `happys srv use --interactive`
@@ -352,7 +369,10 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
   - `happys stack dev <name>` / `happys stack start <name>`
   - `happys stack edit <name> --interactive`
   - `happys stack wt <name> -- use --interactive`
+  - `happys stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-ref=<ref>]`
   - `happys stack migrate`
+- **Reviews (local diff review)**:
+  - `happys review [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>]`
 - **Menu bar (SwiftBar)**:
   - `happys menubar install`
 
@@ -379,6 +399,15 @@ Notes:
 
 - Canonical env prefix is `HAPPY_STACKS_*` (legacy `HAPPY_LOCAL_*` still works).
 - Canonical stack storage is `~/.happy/stacks` (legacy `~/.happy/local` is still supported).
+- To edit per-stack environment variables (including provider keys like `OPENAI_API_KEY`), use:
+
+  ```bash
+  happys stack env <stack> set KEY=VALUE
+  happys stack env <stack> unset KEY
+  happys stack env <stack> get KEY
+  happys stack env <stack> list
+  ```
+
 - **Repo env templates**:
   - **Use `.env.example` as the canonical template** (copy it to `.env` if you’re running this repo directly).
   - If an LLM tool refuses to read/edit `.env.example` due to safety restrictions, **do not create an `env.example` workaround**—instead, ask the user to apply the change manually.
@@ -405,3 +434,27 @@ Notes:
 - To explicitly allow those for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1` (still recommended to clean up after).
 
 For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.
+
+### Developing Happy Stacks itself
+
+```bash
+git clone https://github.com/leeroybrun/happy-stacks.git
+cd happy-stacks
+
+node ./bin/happys.mjs setup --profile=dev
+```
+
+Notes:
+
+- In a cloned repo, `pnpm <script>` still works, but `happys <command>` is the recommended UX (same underlying scripts).
+- To make the installed `~/.happy-stacks/bin/happys` shim (LaunchAgents / SwiftBar) run your local checkout without publishing to npm, set:
+
+```bash
+echo 'HAPPY_STACKS_CLI_ROOT_DIR=/path/to/your/happy-stacks-checkout' >> ~/.happy-stacks/.env
+```
+
+Or (recommended) persist it via init:
+
+```bash
+happys init --cli-root-dir=/path/to/your/happy-stacks-checkout
+```

package/bin/happys.mjs

@@ -9,6 +9,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli/cli_registry.mjs';
 import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
+import { resolveStackEnvPath } from '../scripts/utils/paths/paths.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
@@ -110,6 +111,42 @@ function stripGlobalOpt(argv, { name, aliases = [] }) {
   return { value: '', argv };
 }
 
+function applyVerbosityIfRequested(argv) {
+  // Global verbosity:
+  // - supports -v/-vv/-vvv anywhere before/after the command
+  // - supports --verbose and --verbose=N
+  //
+  // We set HAPPY_STACKS_VERBOSE (0-3) and strip these args so downstream scripts don't need to support them.
+  let level = Number.isFinite(Number(process.env.HAPPY_STACKS_VERBOSE)) ? Number(process.env.HAPPY_STACKS_VERBOSE) : null;
+  let next = [];
+  for (const a of argv) {
+    if (a === '-v' || a === '-vv' || a === '-vvv') {
+      const n = a.length - 1;
+      level = Math.max(level ?? 0, n);
+      continue;
+    }
+    if (a === '--verbose') {
+      level = Math.max(level ?? 0, 1);
+      continue;
+    }
+    if (a.startsWith('--verbose=')) {
+      const raw = a.slice('--verbose='.length).trim();
+      const n = Number(raw);
+      if (Number.isFinite(n)) {
+        level = Math.max(level ?? 0, Math.max(0, Math.min(3, Math.floor(n))));
+      } else {
+        level = Math.max(level ?? 0, 1);
+      }
+      continue;
+    }
+    next.push(a);
+  }
+  if (level != null) {
+    process.env.HAPPY_STACKS_VERBOSE = String(Math.max(0, Math.min(3, Math.floor(level))));
+  }
+  return next;
+}
+
 function applySandboxDirIfRequested(argv) {
   const explicit = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
   const { value, argv: nextArgv } = stripGlobalOpt(argv, { name: '--sandbox-dir', aliases: ['--sandbox'] });
@@ -117,6 +154,8 @@ function applySandboxDirIfRequested(argv) {
   if (!raw) return { argv: nextArgv, enabled: false };
 
   const sandboxDir = expandHome(raw);
+  const allowGlobalRaw = (process.env.HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL ?? '').trim().toLowerCase();
+  const allowGlobal = allowGlobalRaw === '1' || allowGlobalRaw === 'true' || allowGlobalRaw === 'yes' || allowGlobalRaw === 'y';
   // Keep all state under one folder that can be deleted to reset completely.
   const canonicalHomeDir = join(sandboxDir, 'canonical');
   const homeDir = join(sandboxDir, 'home');
@@ -124,23 +163,76 @@ function applySandboxDirIfRequested(argv) {
   const runtimeDir = join(sandboxDir, 'runtime');
   const storageDir = join(sandboxDir, 'storage');
 
+  // Sandbox isolation MUST win over any pre-exported Happy Stacks env vars.
+  // Otherwise sandbox runs can accidentally read/write "real" machine state.
+  //
+  // Keep only a tiny set of sandbox-safe globals; everything else should be driven by flags
+  // and stack env files inside the sandbox.
+  const preserved = new Map();
+  const keepKeys = [
+    'HAPPY_STACKS_VERBOSE',
+    'HAPPY_STACKS_INVOKED_CWD',
+    'HAPPY_STACKS_SANDBOX_DIR',
+    'HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL',
+    'HAPPY_STACKS_UPDATE_CHECK',
+    'HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS',
+    'HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS',
+  ];
+  for (const k of keepKeys) {
+    if (process.env[k] != null && String(process.env[k]).trim() !== '') {
+      preserved.set(k, process.env[k]);
+    }
+  }
+  for (const k of Object.keys(process.env)) {
+    if (k.startsWith('HAPPY_STACKS_') || k.startsWith('HAPPY_LOCAL_')) {
+      delete process.env[k];
+      continue;
+    }
+    // Also clear unprefixed Happy vars; sandbox commands should compute these from stack state.
+    if (k === 'HAPPY_HOME_DIR' || k === 'HAPPY_SERVER_URL' || k === 'HAPPY_WEBAPP_URL') {
+      delete process.env[k];
+    }
+  }
+  for (const [k, v] of preserved.entries()) {
+    process.env[k] = v;
+  }
+
   process.env.HAPPY_STACKS_SANDBOX_DIR = sandboxDir;
   process.env.HAPPY_STACKS_CLI_ROOT_DISABLE = '1'; // never re-exec into a user's "real" install when sandboxing
 
-  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = process.env.HAPPY_STACKS_CANONICAL_HOME_DIR ?? canonicalHomeDir;
-  process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR = process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR ?? process.env.HAPPY_STACKS_CANONICAL_HOME_DIR;
-
-  process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? homeDir;
-  process.env.HAPPY_LOCAL_HOME_DIR = process.env.HAPPY_LOCAL_HOME_DIR ?? process.env.HAPPY_STACKS_HOME_DIR;
-
-  process.env.HAPPY_STACKS_WORKSPACE_DIR = process.env.HAPPY_STACKS_WORKSPACE_DIR ?? workspaceDir;
-  process.env.HAPPY_LOCAL_WORKSPACE_DIR = process.env.HAPPY_LOCAL_WORKSPACE_DIR ?? process.env.HAPPY_STACKS_WORKSPACE_DIR;
-
-  process.env.HAPPY_STACKS_RUNTIME_DIR = process.env.HAPPY_STACKS_RUNTIME_DIR ?? runtimeDir;
-  process.env.HAPPY_LOCAL_RUNTIME_DIR = process.env.HAPPY_LOCAL_RUNTIME_DIR ?? process.env.HAPPY_STACKS_RUNTIME_DIR;
-
-  process.env.HAPPY_STACKS_STORAGE_DIR = process.env.HAPPY_STACKS_STORAGE_DIR ?? storageDir;
-  process.env.HAPPY_LOCAL_STORAGE_DIR = process.env.HAPPY_LOCAL_STORAGE_DIR ?? process.env.HAPPY_STACKS_STORAGE_DIR;
+  // In sandbox mode, we MUST force all state directories into the sandbox, even if the user
+  // exported HAPPY_STACKS_* in their shell. Otherwise sandbox runs can accidentally read/write
+  // "real" machine state (breaking isolation).
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = canonicalHomeDir;
+  process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR = canonicalHomeDir;
+
+  process.env.HAPPY_STACKS_HOME_DIR = homeDir;
+  process.env.HAPPY_LOCAL_HOME_DIR = homeDir;
+
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = workspaceDir;
+  process.env.HAPPY_LOCAL_WORKSPACE_DIR = workspaceDir;
+
+  process.env.HAPPY_STACKS_RUNTIME_DIR = runtimeDir;
+  process.env.HAPPY_LOCAL_RUNTIME_DIR = runtimeDir;
+
+  process.env.HAPPY_STACKS_STORAGE_DIR = storageDir;
+  process.env.HAPPY_LOCAL_STORAGE_DIR = storageDir;
+
+  // Sandbox default: disallow global side effects unless explicitly opted in.
+  // This keeps sandbox runs fast, deterministic, and isolated.
+  if (!allowGlobal) {
+    // Network-y UX (background update checks) are not useful in a temporary sandbox.
+    process.env.HAPPY_STACKS_UPDATE_CHECK = '0';
+    process.env.HAPPY_STACKS_UPDATE_CHECK_INTERVAL_MS = '0';
+    process.env.HAPPY_STACKS_UPDATE_NOTIFY_INTERVAL_MS = '0';
+
+    // Never auto-enable or reset Tailscale Serve in sandbox.
+    // (Tailscale is global machine state; sandbox runs must not touch it.)
+    process.env.HAPPY_LOCAL_TAILSCALE_SERVE = '0';
+    process.env.HAPPY_STACKS_TAILSCALE_SERVE = '0';
+    process.env.HAPPY_LOCAL_TAILSCALE_RESET_ON_EXIT = '0';
+    process.env.HAPPY_STACKS_TAILSCALE_RESET_ON_EXIT = '0';
+  }
 
   return { argv: nextArgv, enabled: true };
 }
@@ -248,8 +340,16 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
 function main() {
   const cliRootDir = getCliRootDir();
   const initialArgv = process.argv.slice(2);
-  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(initialArgv);
+  const argv0 = applyVerbosityIfRequested(initialArgv);
+  const { argv, enabled: sandboxed } = applySandboxDirIfRequested(argv0);
   void sandboxed;
+
+  // Preserve the original working directory across re-exec to the CLI root so commands can infer
+  // component/worktree context even when the actual scripts run with cwd=cliRootDir.
+  if (!(process.env.HAPPY_STACKS_INVOKED_CWD ?? '').trim()) {
+    process.env.HAPPY_STACKS_INVOKED_CWD = process.cwd();
+  }
+
   maybeReexecToCliRoot(cliRootDir);
 
   // If the user passed only flags (common via `npx happy-stacks --help`),
@@ -278,8 +378,50 @@ function main() {
     return runNodeScript(cliRootDir, targetCmd.scriptRelPath, helpArgs);
   }
 
-  const resolved = resolveHappysCommand(cmd);
+  let resolved = resolveHappysCommand(cmd);
   if (!resolved) {
+    // Stack shorthand:
+    // If the first token is not a known command, but it *is* an existing stack name,
+    // treat `happys <stack> <command> ...` as `happys stack <command> <stack> ...`.
+    const stackName = cmd;
+    const { envPath } = resolveStackEnvPath(stackName, process.env);
+    const stackExists = existsSync(envPath);
+    if (stackExists) {
+      const cmdIdx = rest.findIndex((a) => !a.startsWith('-'));
+      if (cmdIdx < 0) {
+        if (rest.includes('--help') || rest.includes('-h')) {
+          const stackCmd = resolveHappysCommand('stack');
+          if (!stackCmd || stackCmd.kind !== 'node') {
+            console.error('[happys] internal error: missing stack command');
+            process.exit(1);
+          }
+          return runNodeScript(cliRootDir, stackCmd.scriptRelPath, ['--help']);
+        }
+        console.error(`[happys] missing command after stack name: ${stackName}`);
+        console.error('');
+        console.error('Try one of:');
+        console.error(`  happys ${stackName} env list`);
+        console.error(`  happys ${stackName} dev`);
+        console.error(`  happys ${stackName} start`);
+        console.error('');
+        console.error('Equivalent long form:');
+        console.error(`  happys stack <command> ${stackName} ...`);
+        process.exit(1);
+      }
+
+      const stackSubcmd = rest[cmdIdx];
+      const preFlags = rest.slice(0, cmdIdx);
+      const post = rest.slice(cmdIdx + 1);
+      const stackArgs = [stackSubcmd, stackName, ...preFlags, ...post];
+
+      resolved = resolveHappysCommand('stack');
+      if (!resolved || resolved.kind !== 'node') {
+        console.error('[happys] internal error: missing stack command');
+        process.exit(1);
+      }
+      return runNodeScript(cliRootDir, resolved.scriptRelPath, stackArgs);
+    }
+
     console.error(`[happys] unknown command: ${cmd}`);
     console.error('');
     console.error(usage());

package/docs/codex-mcp-resume.md

@@ -0,0 +1,130 @@
+# Codex MCP resume (experimental) — Happy integration spec
+
+This document describes how to integrate an **experimental** Codex MCP server fork
+that can **resume sessions from rollout JSONL** after restarts/crashes.
+
+## Goals
+
+- Allow Happy to use a Codex MCP server that supports **resume-from-rollout**.
+- Keep the feature **opt-in** and **safe by default** (pinned versions, clear UI).
+- Avoid requiring users to replace their global `codex` install.
+
+## Non-goals
+
+- Replacing OpenAI’s `@openai/codex` installation for general CLI usage.
+- Auto-updating to “latest” without user opt-in.
+
+## Key facts (implementation reality)
+
+- `codex-mcp-server` is **not** a thin wrapper around a user-installed `codex` binary.
+  It embeds Codex core and runs threads internally.
+- Therefore, when Happy uses this MCP server, the “engine” for those sessions is
+  the forked Codex Rust core shipped with the MCP server build.
+
+## Distribution model (recommended)
+
+Ship the MCP server as an npm package that bundles native binaries:
+
+- **npm package**: `@leeroy/codex-mcp-resume`
+- **binary launcher**: `npx -y @leeroy/codex-mcp-resume@<pinned-version>`
+- **native payload**: `vendor/<targetTriple>/codex-mcp-server/codex-mcp-server[.exe]`
+
+This mirrors how upstream Codex ships platform binaries via npm.
+
+## Versioning + updates
+
+### Pinned by Happy (default)
+
+- Happy pins an exact semver (example): `0.84.0-resume.123.a1`
+- Happy invokes:
+  - `npx -y @leeroy/codex-mcp-resume@0.84.0-resume.123.a1`
+
+**Update path**: users get new MCP builds when they update Happy (or when Happy updates the pin).
+
+### Optional “auto-update experimental tools” (opt-in)
+
+If you want faster iteration:
+
+- Happy uses `@latest` or a dedicated dist-tag (e.g. `resume`)
+- This should be opt-in, clearly labeled “may break”.
+
+## Happy-side feature flag / settings
+
+### Setting name (proposed)
+
+- **Config**: `experimental.codexMcpResume = true|false`
+- **Env override** (optional): `HAPPY_EXPERIMENTAL_CODEX_MCP_RESUME=1`
+
+### UX (proposed)
+
+- Settings → Experimental → “Use Codex MCP resume fork”
+- Subtext: “Runs a separate MCP server shipped by Happy; may differ from your global Codex install.”
+
+## Process + wiring
+
+### 1) Resolve the MCP server command
+
+When feature enabled, Happy should register an MCP server entry equivalent to:
+
+```toml
+[mcp_servers.codex_resume]
+command = "npx"
+args = ["-y", "@leeroy/codex-mcp-resume@0.84.0-resume.123.a1"]
+```
+
+Notes:
+- The MCP server is stdio-based; Happy should spawn it and speak MCP JSON-RPC over stdin/stdout.
+- Use `-y` to make it non-interactive.
+- Ensure Happy’s environment does **not** leak secrets in logs.
+
+### 2) Decide the Codex “home” used for sessions
+
+Session restoration depends on reading rollout JSONL files.
+
+Two viable modes:
+
+- **Shared home (recommended for seamless resume)**:
+  - Run with the user’s default Codex home (usually `~/.codex`), so the MCP server sees the same rollouts.
+- **Happy-managed home (more isolated)**:
+  - Provide a separate home (e.g. `~/.happy/codex`) but then “resume existing Codex sessions” won’t work unless you import/migrate.
+
+If you need an explicit home, pass env vars when spawning the MCP server:
+
+- `CODEX_HOME=<path>`
+
+### 3) Tool usage from Happy
+
+Happy should call MCP tools:
+
+- **Start new session**: `tools/call name="codex"` with desired config (model, cwd, approval_policy/sandbox, etc).
+- **Continue session**: `tools/call name="codex-reply"` with `{ threadId, prompt }`.
+
+The forked MCP server handles:
+
+- in-memory threads normally
+- on restart/crash: “resume thread” by reading rollout history
+
+### 4) Concurrency expectations
+
+Happy may issue multiple `codex-reply` calls concurrently (UI retries, double-submit, etc).
+The MCP server should serialize per-thread reply/resume to avoid event-stream races.
+
+## CI + publishing requirements (for maintainers)
+
+The fork’s CI should:
+
+- build `codex-mcp-server` for macOS/Linux/Windows (arm64 + x64 where relevant)
+- pack those into an npm tarball
+- publish via npm trusted publishing (OIDC)
+
+## What Happy devs need to implement (checklist)
+
+- Add a feature flag + settings surface (opt-in).
+- Add MCP server registry entry for `codex_resume` (command: `npx`, args pinned).
+- Decide and document which Codex home dir is used (shared vs isolated).
+- Route Codex session creation + reply calls through the selected MCP server.
+- Add telemetry/logging that records:
+  - selected MCP server (default vs resume fork)
+  - package version (pinned version string)
+  - threadId for correlation (no prompt contents)
+