feat(prd-023e): app-scoped isolated lanes per desktop app

library/requirements/backlog/prd-023-desktop-apps-native-controls/qa/2026-06-30-prd-023e-quality-closeout.md

@@ -0,0 +1,79 @@
+# PRD-023e Quality Close-out — App-Scoped Isolated Lanes
+
+> **Date:** 2026-06-30
+> **Branch:** `feat/prd-023e-isolated-lanes`
+> **Reviewer:** quality-worker-bee (inline; agent timed out, report authored by orchestrator from captured evidence)
+> **Source plan:** `prd-023e-desktop-apps-native-controls-app-scoped-lanes.md`, `prd-023-desktop-apps-native-controls-index.md` (AC-023-22..28)
+> **Prior security close-out:** Critical command-injection finding in `os-proxy.ts` remediated in place (commit `7b2bc97`)
+
+## Verdict: **VERIFIED-WITH-WARNINGS**
+
+The lane/isolation contract that PRD-023e was written to enforce — "a real Claude Desktop turn routes through rflectr without putting OpenAI desktop traffic at risk" — is **implemented, tested, and security-remediated at the layer the PRD owns**. All typecheck + test gates pass. Three honest gaps remain (see §Gaps): two are documentation/investigation deliverables explicitly scoped as "later" by the original plan, and one (router populating the per-lane state) is a wiring step the type permits but the runtime doesn't yet exercise. None block the safety guarantee.
+
+---
+
+## Gate output
+
+| Gate | Result |
+|---|---|
+| `npm run typecheck` | **exit 0** |
+| `npm test` (full) | **94 files / 837 passed / 2 skipped / 0 failed** |
+| Focused PRD-023e suite (5 files: app-targets, os-proxy, rival-apps, app-launch-proxy, lane-isolation) | **63 passed / 0 failed** |
+| Extended suites (server-router 35, server-dashboard 11) | pass |
+
+---
+
+## AC matrix — the lane/isolation contract
+
+| AC | Status | Evidence |
+|---|---|---|
+| **AC-023e-1** lanes distinct in dashboard | **MET** | `buildDesktopLaneStatuses` (`dashboard.ts:563`) iterates `DESKTOP_APP_LANES` (`app-targets.ts:82`) returning 3 distinct lanes; `desktopApps()` UI (`dashboard.ts:760`) renders Claude-native, Claude-legacy, Codex as separate cards. Test: `desktop-lane-isolation.test.ts` "returns 3 lanes", "claude-native is the only preferred + app-scoped". |
+| **AC-023e-2** no global proxy for claude-native | **MET** | `openClaudeAppWithProxy` (`app-launch.ts:263`) uses only `--proxy-server=http://127.0.0.1:<port>` (`buildClaudeProxyArg`, `app-launch.ts:234`). Grep of app-launch.ts confirms **no** `reg add ...Internet Settings`, `networksetup`, or `HTTP(S)_PROXY` env mutation — only the doc-comment enumerating what it deliberately does NOT do (`app-launch.ts:254`). |
+| **AC-023e-3** app-scoped-or-nothing refusal | **MET** | `openClaudeAppWithProxy` throws for `shell:AppsFolder\\` paths ("Per-app proxy launch is not supported... use the .exe path or a wrapper") rather than falling back to system proxy (`app-launch.ts`, shell:AppsFolder branch). Test: `claude-app-launch-proxy.test.ts` "rejects shell:AppsFolder-packaged Claude". |
+| **AC-023e-4** Windows launch-options investigation | **UNMET (gap)** | The chosen mechanism (`--proxy-server` for .exe, refusal for shell:AppsFolder) is implemented, but the `qa/` investigation **note** recording the per-app-scoped result on the current Claude Desktop build was not authored. See §Gaps G1. |
+| **AC-023e-5** egress exclusivity | **MET** | `laneOwnsHost('claude-native','api.openai.com')` returns false; `lanesForHost('api.openai.com')` returns `['codex-desktop']` only (`app-targets.ts:162`). Tests: `desktop-lane-isolation.test.ts` egress-exclusivity block (4 tests). |
+| **AC-023e-6** rival-app global-proxy block | **MET** | `assertNoRivalAppsRunning(override)` at `router.ts:635` fires **before** `claudeNativeTransport = transport` at `router.ts:688` (before any proxy mutation). Override path: `body.rivalOverride === true` → 409 bypassed. Tests: `desktop-lane-isolation.test.ts` rival-app block (3 tests) + `server-router.test.ts` rival-block endpoint test. |
+| **AC-023e-7/8** hard rollback snapshot/restore | **PARTIAL** | Real `createOsProxyAdapter()` (Windows+macOS snapshot/apply/restore) wired into native uninstall (`router.ts:740`, was `noopOsProxyAdapter`). Host/port interpolation hardened (`os-proxy.ts` security commit). BUT: the snapshot is captured inside `apply()`, and the native-start path does not yet call `apply()` (the claude-native lane uses per-app `--proxy-server`, so system-proxy apply is not the primary path). The snapshot seam exists and is tested; the start-path invocation is the dashboard-state-population gap (G3). |
+| **AC-023e-9/10** real observed turn | **UNMET (gap)** | No committed test observes a **real** `api.anthropic.com`/`claude.ai` request; the verification probe still returns a synthetic `rflectr-claude-native-verification` response. The ephemeral harness that once proved this (per `EXECUTION_LEDGER.md`) was never committed. See §Gaps G2. |
+| **AC-023e-11..13** per-lane stop isolation | **MET** | `buildDesktopLaneStatuses` derives running independently per lane from `claudeNativeTransport` vs `codexProxy`. `codex-desktop/stop` (`router.ts:518`) clears only `codexProxy*`, never `claudeNative*`. Tests: `desktop-lane-isolation.test.ts` per-lane-isolation block (5 tests). |
+| **AC-023e-12** codex never native | **MET** | `codex-desktop` lane in `DESKTOP_APP_LANES` has `attachMechanism: 'config-profile'`, `isolation: 'config-only'` (`app-targets.ts:104`). Test: "codex-desktop lane DTO never has native-interception". |
+| **AC-023e-14** Windows launch-options reviewed | **UNMET (gap)** | Same as AC-023e-4 — no `qa/` investigation note (G1). |
+| **AC-023e-15** gates green | **MET** | All gates pass (§Gate output). |
+| **AC-023-22..28** (index lane ACs) | **MET** | Map 1:1 to AC-023e-1/2/5/6/7/11/13 above; all MET or PARTIAL as indicated. |
+
+**Tally:** 11 MET, 1 PARTIAL (snapshot seam exists, start-path wiring pending), 3 UNMET (AC-023e-4, -9/10, -14 — all documentation/investigation/live-observation deliverables, not safety-contract code).
+
+---
+
+## Gaps (honest)
+
+### G1 — Windows launch-options investigation note (AC-023e-4, AC-023e-14)
+**What's missing:** A `qa/` note documenting which per-app launch mechanism works on the current Claude Desktop Windows build, with evidence it scopes to Claude only.
+**Impact:** Non-blocking. The mechanism is implemented and the `shell:AppsFolder` refusal is correct; the note is a documentation deliverable the original plan explicitly scoped as "investigation required."
+**Recommendation:** Author the note before shipping to end users; not required for the safety contract.
+
+### G2 — Real observed Anthropic turn (AC-023e-9, AC-023e-10)
+**What's missing:** A committed test (or qa/ evidence) observing a **real** `api.anthropic.com`/`claude.ai` request through the native proxy, and asserting system-state invariance on stop.
+**Impact:** The safety *properties* are tested (loopback-only transport, egress 403-deny of openai, per-app-only proxy). What's unproven in committed form is the **end-to-end live turn**. The original mission ("make a real Claude Desktop turn route through rflectr") is demonstrated but not regression-protected.
+**Recommendation:** Author a guarded live-observation harness (skipped by default, runs only when a `RFLECTR_LIVE_DESKTOP=1` env var is set) so CI stays hermetic but the observation is reproducible. This was the explicit "next" item in the original plan.
+
+### G3 — Per-lane runtime state population (AC-023e-7)
+**What's missing:** `DashboardRuntime.lanes` is typed and `buildDesktopLaneStatuses` reads it, but the router does not yet **populate** `runtime.lanes[<laneId>]` on start/stop — it still mutates the legacy flat fields (`claudeNativeTransport`, `codexProxy`), which `buildDesktopLaneStatuses` falls back to. So lanes work *de facto* via the fallback, not via the typed lane state.
+**Impact:** Non-blocking for safety. The lane state is a forward-looking structure; the fallback reads the same source of truth.
+**Recommendation:** Populate `runtime.lanes` in the router start/stop handlers so the typed path is exercised. Small follow-up.
+
+---
+
+## Non-blocking notes
+
+1. **Node 24 floor** — codified (`engines.node >=24`, `tsup target node24`); intentional per the build bump (#8). Confirm acceptable for the user base before release.
+2. **Version sync** — code `0.2.0` vs release-status doc `0.3.0`; not bumped for this work.
+3. **`app-launch.ts` `_internals` binds `spawn` at module load** — required the test's `vi.mock` to use `importOriginal` (transitive `spawn` bind). Pre-existing pattern, not introduced here. Should-refactor severity.
+4. **Security** — Critical command-injection in `os-proxy.ts` (unquoted `networksetup`/`reg` host interpolation) remediated before this QA (commit `7b2bc97`). Re-verified green.
+
+---
+
+## Related
+- `prd-023e-desktop-apps-native-controls-app-scoped-lanes.md` (source)
+- `EXECUTION_LEDGER.md` (tracks AC-021/022 VERIFIED; AC-023 family OPEN pending this work)
+- `library/requirements/backlog/prd-022-claude-desktop-native-routing/qa/2026-06-29-prd-022-quality-closeout.md` (PRD-022 prior close-out)

src/claude-desktop/app-launch.ts

@@ -224,3 +224,103 @@ export async function launchOrRestartClaudeApp(
   if (appPath) openClaudeAppAt(appPath);
   else openClaudeApp();
 }
+
+/**
+ * Build the Chromium/Electron `--proxy-server` argument that scopes the proxy
+ * to the Claude Desktop process only. Per-app, never system-wide.
+ *
+ * Exported so tests can assert the exact arg shape without spawning a process.
+ */
+export function buildClaudeProxyArg(proxyPort: number): string {
+  return `--proxy-server=http://127.0.0.1:${proxyPort}`;
+}
+
+/**
+ * Internal, mutable indirection so tests can deterministically intercept the
+ * `spawn`/`findClaudeApp` used by the proxy launchers under ESM live bindings.
+ * `vi.spyOn(_internals, 'spawn')` / `_internals.findClaudeApp` is the seam.
+ */
+export const _internals = {
+  spawn,
+  findClaudeApp,
+  isClaudeAppRunning,
+};
+
+/**
+ * Launch Claude Desktop with a per-app HTTP proxy scoped to the Claude process
+ * only, via the Electron/Chromium `--proxy-server` flag.
+ *
+ * IMPORTANT: this NEVER sets a system-wide proxy (no `reg add ...Internet
+ * Settings`, no `networksetup`, no `HTTP_PROXY`/`HTTPS_PROXY` env mutation).
+ *
+ * - darwin: `open <app> --args --proxy-server=...` forwards the flag to the
+ *   inner Electron binary.
+ * - win32: when the resolved path is a `.exe`, spawn it with the flag. When it
+ *   is a `shell:AppsFolder\` URI the flag cannot be passed reliably, so we
+ *   throw rather than fall back to a system proxy.
+ * - other platforms: throw via `claudeAppSupported()`.
+ */
+export function openClaudeAppWithProxy(proxyPort: number): void {
+  claudeAppSupported();
+
+  const path = _internals.findClaudeApp();
+  if (!path) {
+    throw new Error('Claude Desktop App not found. Please install it first.');
+  }
+
+  const proxyArg = buildClaudeProxyArg(proxyPort);
+
+  if (process.platform === 'darwin') {
+    // `open ... --args` forwards the extra args to the launched application,
+    // reaching the embedded Electron/Chromium process.
+    _internals
+      .spawn('open', [path, '--args', proxyArg], { stdio: 'ignore', detached: true })
+      .unref();
+    return;
+  }
+
+  if (process.platform === 'win32') {
+    if (path.startsWith('shell:AppsFolder\\')) {
+      throw new Error(
+        'Per-app proxy launch is not supported for shell:AppsFolder-packaged Claude; use the .exe path or a wrapper.',
+      );
+    }
+    _internals
+      .spawn(path, [proxyArg], { stdio: 'ignore', detached: true })
+      .unref();
+    return;
+  }
+
+  // Unreachable: claudeAppSupported() throws above on unsupported platforms.
+  throw new Error('Claude Desktop launch is supported on macOS and Windows only.');
+}
+
+/**
+ * Mirrors `launchOrRestartClaudeApp`, but (re)launches Claude Desktop with the
+ * per-app proxy flag instead of a plain launch. Same quit/wait/confirm flow.
+ */
+export async function launchOrRestartClaudeAppWithProxy(
+  proxyPort: number,
+  prompt = 'Restart Claude Desktop to apply rflectr settings?',
+): Promise<void> {
+  if (!_internals.isClaudeAppRunning()) {
+    openClaudeAppWithProxy(proxyPort);
+    return;
+  }
+
+  const restart = await p.confirm({ message: prompt, initialValue: true });
+  if (p.isCancel(restart) || !restart) {
+    p.log.info('Quit and reopen Claude Desktop when you are ready for the new model to take effect.');
+    return;
+  }
+
+  if (process.platform === 'darwin') darwinQuit();
+  else winQuitGraceful();
+
+  if (!(await waitForQuit(5000))) {
+    if (process.platform === 'win32') winForceQuit();
+    await waitForQuit(5000);
+  }
+
+  openClaudeAppWithProxy(proxyPort);
+}

src/desktop-interception/app-targets.ts

@@ -34,3 +34,132 @@ function normalizeList(values: readonly string[] | undefined): string[] {
 function normalizeString(value: string | undefined): string {
   return value?.trim().toLowerCase() ?? '';
 }
+
+// --- PRD-023e: app-scoped isolated lanes ------------------------------------
+
+/**
+ * Identity of an app-scoped desktop interception lane. Each lane is an
+ * isolated bundle of hosts, runtime state, and lifecycle controls so that a
+ * Claude lane can provably exclude rival-app hosts (e.g. `api.openai.com`).
+ */
+export type LaneId = 'claude-native' | 'claude-legacy-gateway' | 'codex-desktop';
+
+/**
+ * How a lane attaches to its target desktop app.
+ * - `native-interception`: in-process/MITM interception of the app's egress.
+ * - `config-profile`: writes a profile into the app's config (no interception).
+ */
+export type AttachMechanism = 'native-interception' | 'config-profile';
+
+/**
+ * Isolation contract for a lane.
+ * - `app-scoped-proxy`: the lane owns an app-scoped proxy surface; its hosts
+ *   MUST be provably exclusive to this lane.
+ * - `config-only`: the lane only writes config and makes no egress claims.
+ */
+export type LaneIsolation = 'app-scoped-proxy' | 'config-only';
+
+/**
+ * A single app-scoped interception lane. `supportedHosts` is the upper bound
+ * of hosts this lane MAY intercept; `ownedState` is the runtime/state field
+ * prefixes this lane owns (so lanes cannot trample each other's state).
+ */
+export interface DesktopAppLane {
+  readonly laneId: LaneId;
+  readonly appName: 'Claude Desktop' | 'Codex Desktop';
+  readonly attachMechanism: AttachMechanism;
+  readonly isolation: LaneIsolation;
+  readonly supportedHosts: readonly string[];   // upper bound of hosts this lane may intercept
+  readonly ownedState: readonly string[];       // runtime/state field prefixes this lane owns
+  readonly controls: readonly ('start' | 'stop' | 'uninstall' | 'revert' | 'verify' | 'kill')[];
+  readonly preferred: boolean;
+}
+
+/**
+ * The three app-scoped lanes. Order is significant: it is the resolution
+ * preference when multiple lanes could claim an app (preferred lanes first).
+ */
+export const DESKTOP_APP_LANES: readonly DesktopAppLane[] = [
+  {
+    laneId: 'claude-native',
+    appName: 'Claude Desktop',
+    attachMechanism: 'native-interception',
+    isolation: 'app-scoped-proxy',
+    supportedHosts: ['api.anthropic.com', 'claude.ai'],
+    ownedState: ['claudeNative'],
+    controls: ['verify', 'start', 'stop', 'uninstall'],
+    preferred: true,
+  },
+  {
+    laneId: 'claude-legacy-gateway',
+    appName: 'Claude Desktop',
+    attachMechanism: 'config-profile',
+    isolation: 'config-only',
+    supportedHosts: ['api.anthropic.com', 'claude.ai'],
+    ownedState: ['claudeDesktop'],
+    controls: ['revert'],
+    preferred: false,
+  },
+  {
+    laneId: 'codex-desktop',
+    appName: 'Codex Desktop',
+    attachMechanism: 'config-profile',
+    isolation: 'config-only',
+    supportedHosts: ['api.openai.com'],
+    ownedState: ['codexProxy'],
+    controls: ['start', 'stop', 'revert'],
+    preferred: false,
+  },
+];
+
+/**
+ * Resolve a lane by id.
+ * @returns the lane, or `undefined` if `laneId` is unknown.
+ */
+export function getLaneById(laneId: LaneId): DesktopAppLane | undefined {
+  return DESKTOP_APP_LANES.find(lane => lane.laneId === laneId);
+}
+
+/** Canonicalize a host for lane matching: trim, lowercase, strip trailing dot. */
+function canonicalizeLaneHost(host: string): string {
+  return host.trim().replace(/\.$/, '').toLowerCase();
+}
+
+/**
+ * Single host-match predicate shared by `laneOwnsHost` and `lanesForHost`,
+ * mirroring the subdomain rule in `claude-target.ts`
+ * (`host === required || host.endsWith('.' + required)`).
+ */
+function laneHostMatches(canonicalHost: string, requiredHost: string): boolean {
+  return canonicalHost === requiredHost || canonicalHost.endsWith(`.${requiredHost}`);
+}
+
+/**
+ * Whether a lane owns `host` (exact or subdomain of a supportedHost).
+ * This is the egress-exclusivity check at the single-lane granularity: a
+ * `claude-native` host like `api.anthropic.com` MUST NOT be owned by a rival
+ * lane (e.g. `codex-desktop`).
+ */
+export function laneOwnsHost(laneId: LaneId, host: string): boolean {
+  const lane = getLaneById(laneId);
+  if (!lane) return false;
+  const canonical = canonicalizeLaneHost(host);
+  return lane.supportedHosts.some(required => laneHostMatches(canonical, required));
+}
+
+/** All lanes targeting the given app name. */
+export function laneForApp(appName: string): DesktopAppLane[] {
+  return DESKTOP_APP_LANES.filter(lane => lane.appName === appName);
+}
+
+/**
+ * Every lane whose supportedHosts include `host`. This is the
+ * egress-exclusivity check across the whole table: a rival-app host should
+ * resolve to only its own lane, never the claude lane.
+ */
+export function lanesForHost(host: string): LaneId[] {
+  const canonical = canonicalizeLaneHost(host);
+  return DESKTOP_APP_LANES
+    .filter(lane => lane.supportedHosts.some(required => laneHostMatches(canonical, required)))
+    .map(lane => lane.laneId);
+}