u-chan-secrets 4.0.1 → 5.0.1

package/README.md

@@ -1,10 +1,10 @@
-# U-Chan Secrets V4
+# U-Chan Secrets V5
 
-A local MCP server that signs into approved websites with Bitwarden credentials. A privileged service performs credential entry in an isolated browser and transfers filtered session state into a dedicated user Chrome profile.
+A local MCP server that signs into approved websites with Bitwarden credentials. A privileged service performs credential entry in an isolated browser and transfers filtered session state into a dedicated Chrome or Edge profile.
 
-Version `4.0.0` adds guided Windows/Codex setup, installed-version and browser-target checks, clearer native status, and CLI proposals for scoped login approval. Protocol and protected-state schema remain version 3.
+Version `5.0.0` adds selectable Chrome/Edge desktop destinations and checks approved login evidence before and after session transfer. Chrome remains the default when no browser has been selected. Protocol and protected-state schema remain version 3. Source integration, publication, and installed verification are separate events.
 
-**Verification:** Windows/macOS build and test CI is separate from installed-service security verification. Native process identity, input isolation, permissions, and installation rehearsals remain [release gates](docs/attack-checklist.md). See [validation evidence](docs/superpowers/research/2026-10-29-v3-validation.md) and [SECURITY.md](SECURITY.md).
+**Verification:** Windows/macOS build and test CI is separate from installed-service security verification. Native process identity, input isolation, permissions, and installation rehearsals remain [release gates](docs/attack-checklist.md). See [V5 validation evidence](docs/superpowers/research/2026-10-30-v5-validation.md) and [SECURITY.md](SECURITY.md).
 
 The [Windows V4 rollout](docs/superpowers/research/2026-10-29-v4-rollout.md) records matching service/CLI versions, preserved protected state, real setup and fresh MCP/browser checks. It builds on the tightened V3.0.3 [native closeout](docs/superpowers/research/2026-10-29-v3-windows-closeout.md). macOS runtime remains unverified; source merge, installed verification, and package publication are recorded separately.
 
@@ -18,6 +18,43 @@ The [Windows V4 rollout](docs/superpowers/research/2026-10-29-v4-rollout.md) rec
 
 Windows Hello and Touch ID remain [research only](docs/superpowers/research/2026-10-29-native-approval.md). Linux, general SSO/OAuth, passkeys, and automated CAPTCHA solving are outside V3.
 
+## What V5 adds
+
+### Updating an existing Windows V5 installation to 5.0.1
+
+Run these commands from a normal, non-administrator PowerShell terminal:
+
+```powershell
+npm.cmd install --global u-chan-secrets@5.0.1
+u-chan.cmd update
+u-chan.cmd setup --apply
+u-chan doctor
+```
+
+The signed service update restarts U-Chan and clears its in-memory vault unlock. Run `u-chan unlock` afterward and enter the master password only in the protected prompt. The explicit `.cmd` spelling bootstraps setup when npm's PowerShell launcher is blocked; afterward the short `u-chan` command works. Restart the AI session if setup requests it. Existing browser choice, grants, and vault data remain local; a site's success condition must be approved separately on each installation. Older versions with changed dependencies or native helpers may require the trusted administrator reinstall described below.
+
+Choose your browser from a normal Windows terminal:
+
+```powershell
+u-chan setup --browser edge --json
+u-chan setup --browser edge --apply --replace-existing --start-browser
+u-chan setup --browser chrome --apply --replace-existing --start-browser
+```
+
+The first command inspects the proposed choice. `--apply` saves it in user-side `browser.json` and registers the matching MCP environment through the official Codex CLI. Later commands without `--browser` keep the saved choice; a new installation defaults to Chrome. Browser and Codex configuration backups are retained under their respective `#0 backup` directories. Each user's choice is independent.
+
+Chrome and Edge use separate dedicated profiles. Only one browser owns the configured U-Chan CDP endpoint at a time. When switching, close the previous **dedicated U-Chan instance** and rerun setup; keep your personal browser windows open. U-Chan refuses wrong, unknown, personal-profile, or non-loopback listeners instead of silently attaching, selecting another port/browser, or terminating processes. It does not install browsers or change enterprise debugging policy. The legacy `scripts/start-chrome.ps1` explicitly selects Chrome; `scripts/start-browser.ps1 -Browser edge` selects Edge.
+
+The service independently checks the installed owner's SID and dedicated profile before accessing the Windows destination. It derives that user's AppData paths from the profile registry. Advanced installations with a custom desktop profile root must align the trusted service environment's `U_CHAN_DESKTOP_HOME` with the user-side home; changing only a user-side environment variable does not redirect privileged session transfer.
+
+An approved exact URL or visible selector must match in both the private login context and a new verification tab in the destination browser before `login` returns success. Existing user tabs are left alone. Missing evidence returns `authentication_unconfirmed`; private success with unverified desktop state returns `destination_unconfirmed`. Transfer failure/cancellation can leave partial session state and does not log the browser out. Expired or consumed grants are not refunded.
+
+The private credential-bearing context uses a per-attempt HTTP/CONNECT proxy to block network destinations outside approved hosts, including redirect chains and worker/frame requests. Service workers are disabled. Private Chromium disables HTTP/2 and QUIC so connections cannot coalesce across approved and unapproved origins; HTTP/2-only sites may be unsupported. TLS remains end-to-end with normal browser certificate validation. Some sites requiring third-party resources or external identity providers also remain unsupported; U-Chan does not silently broaden host approval. CAPTCHA, passkey, push approval, or unavailable/rejected TOTP returns `needs_human` with manual sign-in guidance. V5 does not expose or resume the private challenge context, repeat credential submissions, or ask for passwords/codes in AI chat.
+
+A V5 client requires the service's `verified_session_transfer` capability before login and binds the request to its selected browser. Update both CLI and service; an older service is refused before a login attempt is sent. An old client without a browser field retains its legacy Chrome destination. A stale MCP browser environment that conflicts with the saved choice is refused until the AI session restarts. Existing grants and vault data remain compatible. Native macOS runtime and ownership by an already-running AI session remain unverified.
+
+Other MCP clients may set `U_CHAN_BROWSER=edge` (or `chrome`) and the matching loopback `U_CHAN_CDP` in their own registration, then launch the matching dedicated browser. Automatic registration remains Windows/Codex only; setting a desktop environment variable does not change the privileged service's endpoint.
+
 ## What V4 adds
 
 Use a normal, non-administrator terminal after installing the matching trusted service:
@@ -30,12 +67,14 @@ u-chan setup --client codex --apply --replace-existing --start-browser
 
 The first command only inspects. `--apply` adds missing Codex MCP registrations through the official Codex CLI. `--replace-existing` also permits replacement of recognized simple registrations. Existing configuration is backed up under the Codex configuration directory's `#0 backup` before mutation. Compatible enabled registrations retain custom environment, working directory, tool filters, timeouts, and other settings. Incompatible custom registrations, conflicting target overrides, disabled entries, and HTTP transports require manual configuration and remain untouched. Partial failures retain completed changes and the backup; setup never restores an obsolete whole configuration over concurrent edits.
 
-`--start-browser` explicitly starts the dedicated Chrome profile in the background when its endpoint is unhealthy. No startup task is added. Setup refuses elevated execution and known service/desktop browser-target mismatches. It never installs the privileged service or changes UAC. Run `u-chan install` separately from a trusted administrator terminal.
+`--start-browser` explicitly starts the selected dedicated browser profile in the background when its endpoint is unhealthy. No startup task is added. Setup refuses elevated execution and known service/desktop browser-target mismatches. It never installs the privileged service or changes UAC. Run `u-chan install` separately from a trusted administrator terminal.
 
 Setup reports `configured` or `needs_attention`, plus `sharing` and `restartRequired`. `process_configured` means matching process arguments were observed; it does not verify active AI-session ownership. Unobservable sharing remains `unobserved`. Restart the AI session after registration changes. Exit codes: 1 means attention required, 2 means configured with restart required, and 0 means configured without a known restart requirement. A locked vault remains a valid installed state.
 
 Automatic registration supports Codex on Windows only. Configure other clients manually using their documented MCP commands. macOS runtime remains unverified. `doctor` compares the actual CLI and installed service versions, both browser targets, and Windows UAC policy; missing metadata remains unknown. `manage` shows the installed service version and browser status.
 
+On Windows, `setup --apply` also makes the short `u-chan` command work when PowerShell blocks scripts. It moves the recognized npm-generated `u-chan.ps1` launcher into the npm directory's `#0 backup`, leaving `u-chan.cmd` available for PowerShell to resolve automatically. Execution policy and PowerShell profiles are unchanged. Inspection without `--apply` is read-only, and custom launchers are preserved. If the first setup command is blocked, run `u-chan.cmd setup --apply`. Rerun setup after an npm installation or update recreates the PowerShell launcher. Shell results and the backup path appear in the setup JSON report.
+
 Propose a site grant with an explicit success condition:
 
 ```sh
@@ -160,7 +199,7 @@ In Windows PowerShell, use `u-chan.cmd` if execution policy blocks npm's `.ps1`
 | Command | Purpose |
 |---|---|
 | `doctor [--json]` | Read-only diagnostic report and safe next actions |
-| `setup [--client codex] [--apply] [--replace-existing] [--start-browser] [--json]` | Windows desktop inspection and explicit Codex/browser setup |
+| `setup [--client codex] [--browser chrome\|edge] [--apply] [--replace-existing] [--start-browser] [--json]` | Windows desktop inspection and explicit Codex/browser setup |
 | `allow <domain> --login-url <https-url> --item <label> [--once\|--minutes N\|--permanent] [--success-url URL\|--success-selector SELECTOR]` | Propose a scoped grant through protected approval |
 | `manage` | Native status, grant pages, recent activity, lock/unlock, and revocation |
 | `unlock` | Request the protected master-password prompt |

package/dist/cli.js

@@ -14,6 +14,8 @@ import { join } from 'node:path';
 import { configureCodex, isElevated } from './client/codex-setup.js';
 import { runSetup, setupExitCode } from './client/setup.js';
 import { parseAllowArgs } from './client/allow.js';
+import { saveBrowserChoice } from './client/browser-choice.js';
+import { configureWindowsCommand } from './client/windows-command.js';
 const USAGE = 'usage: u-chan install [--mode <easy|hardcore>] [--phrase <phrase>] | uninstall | unlock | lock | mode <easy|hardcore> | import-v1 [path] | audit [limit] | update | doctor [--json] | manage';
 /** import-v1 shows one approval window per entry, each open for up to 2 minutes, one after another. */
 export const IMPORT_PROMPT_MS = 120000;
@@ -28,10 +30,16 @@ function defaultV1Path(env, platform) {
 export async function main(argv, d) {
     const [cmd, arg, ...rest] = argv;
     let call;
+    let diagnosticEnv = d.env;
     const doctor = d.doctor ?? (() => runDoctor({
         platform: d.platform,
         clientVersion: d.clientVersion ?? 'unknown',
-        clientEndpoint: loadConfig(d.env, d.platform).cdpEndpoint,
+        clientEndpoint: loadConfig(diagnosticEnv, d.platform).cdpEndpoint,
+        browser: loadConfig(diagnosticEnv, d.platform).browser,
+        browserIdentity: d.platform === 'win32' ? async () => {
+            const cfg = loadConfig(diagnosticEnv, d.platform);
+            return (await import('./platform/windows/desktop-browser.js')).inspectDesktopBrowser({ endpoint: cfg.cdpEndpoint, browser: cfg.browser, profile: cfg.browserProfile }, diagnosticEnv);
+        } : undefined,
         elevation: d.platform === 'win32' ? async () => (await import('./platform/windows/doctor.js')).checkWindowsUac() : undefined,
         registration: async () => d.platform === 'win32' ? (await import('./platform/windows/doctor.js')).checkWindowsRegistration() : d.platform === 'darwin' ? (await import('./platform/darwin/doctor.js')).checkDarwinRegistration() : 'fail',
         service: async () => {
@@ -43,11 +51,11 @@ export async function main(argv, d) {
                 throw new Error('invalid diagnostics');
             return s;
         },
-        chrome: () => chromeState(loadConfig(d.env, d.platform).cdpEndpoint),
+        chrome: () => chromeState(loadConfig(diagnosticEnv, d.platform).cdpEndpoint),
         playwright: async () => {
             if (d.platform !== 'win32')
                 return 'unknown';
-            const state = await checkPlaywrightNow(process.pid, loadConfig(d.env, d.platform).cdpEndpoint);
+            const state = await checkPlaywrightNow(process.pid, loadConfig(diagnosticEnv, d.platform).cdpEndpoint);
             return state === 'ok' ? 'pass' : state === 'missing' ? 'fail' : 'unknown';
         },
     }));
@@ -71,9 +79,10 @@ export async function main(argv, d) {
     if (cmd === 'setup') {
         const args = argv.slice(1), seen = new Set();
         let valid = true;
+        let browser;
         for (let i = 0; i < args.length; i++) {
             const flag = args[i];
-            if (seen.has(flag) || !['--client', '--apply', '--replace-existing', '--start-browser', '--json'].includes(flag)) {
+            if (seen.has(flag) || !['--client', '--browser', '--apply', '--replace-existing', '--start-browser', '--json'].includes(flag)) {
                 valid = false;
                 break;
             }
@@ -82,31 +91,31 @@ export async function main(argv, d) {
                 valid = false;
                 break;
             }
+            if (flag === '--browser') {
+                const value = args[++i];
+                if (value !== 'chrome' && value !== 'edge') {
+                    valid = false;
+                    break;
+                }
+                ;
+                browser = value;
+            }
         }
         if (!valid || (seen.has('--replace-existing') && !seen.has('--apply'))) {
-            d.err('usage: u-chan setup [--client codex] [--apply] [--replace-existing] [--start-browser] [--json]');
+            d.err('usage: u-chan setup [--client codex] [--browser chrome|edge] [--apply] [--replace-existing] [--start-browser] [--json]');
             return 1;
         }
-        const options = { apply: seen.has('--apply'), replaceExisting: seen.has('--replace-existing'), startBrowser: seen.has('--start-browser') };
-        const endpoint = loadConfig(d.env, d.platform).cdpEndpoint;
+        const options = { apply: seen.has('--apply'), replaceExisting: seen.has('--replace-existing'), startBrowser: seen.has('--start-browser'), ...(browser ? { browser } : {}) };
+        if (browser)
+            diagnosticEnv = { ...d.env, U_CHAN_BROWSER: browser };
+        const cfg = loadConfig(diagnosticEnv, d.platform), endpoint = cfg.cdpEndpoint;
         const r = d.setup ? await d.setup(options) : await runSetup(options, {
-            platform: d.platform, endpoint, elevated: isElevated, doctor,
-            configure: opts => configureCodex({ ...opts, endpoint, ipcEndpoint: defaultEndpoint(d.env, d.platform), nodePath: process.execPath, entryPath: fileURLToPath(new URL('./index.js', import.meta.url)), configDir: d.env.CODEX_HOME ?? join(homedir(), '.codex') }),
+            platform: d.platform, endpoint, browser: cfg.browser, elevated: isElevated, doctor,
+            configureShell: apply => configureWindowsCommand(apply, d.env.PATH ?? d.env.Path ?? ''),
+            selectBrowser: choice => saveBrowserChoice(cfg.browserChoicePath, choice),
+            configure: opts => configureCodex({ ...opts, browser: cfg.browser, endpoint, ipcEndpoint: defaultEndpoint(d.env, d.platform), nodePath: process.execPath, entryPath: fileURLToPath(new URL('./index.js', import.meta.url)), configDir: d.env.CODEX_HOME ?? join(homedir(), '.codex') }),
             startBrowser: () => new Promise(resolve => {
-                execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', fileURLToPath(new URL('../scripts/start-chrome.ps1', import.meta.url)), '-Background'], { timeout: 5000, windowsHide: true, env: d.env, maxBuffer: 65536 }, async (err) => {
-                    if (err) {
-                        resolve(false);
-                        return;
-                    }
-                    for (let i = 0; i < 5; i++) {
-                        if (await chromeState(endpoint, 1000) === 'pass') {
-                            resolve(true);
-                            return;
-                        }
-                        await new Promise(done => setTimeout(done, 300));
-                    }
-                    resolve(false);
-                });
+                execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', fileURLToPath(new URL('../scripts/start-browser.ps1', import.meta.url)), '-Browser', cfg.browser, '-Background'], { timeout: 24000, windowsHide: true, env: diagnosticEnv, maxBuffer: 65536 }, err => resolve(!err));
             }),
         });
         if (seen.has('--json'))

package/dist/client/browser-choice.js

@@ -0,0 +1,49 @@
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { mkdir, rename, writeFile, lstat, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export function browserKind(value) {
+    if (value !== 'chrome' && value !== 'edge')
+        throw new Error('Invalid browser selection; choose chrome or edge.');
+    return value;
+}
+export function readBrowserChoice(file) {
+    try {
+        const info = lstatSync(file), parent = resolve(dirname(file));
+        if (!info.isFile() || info.isSymbolicLink() || realpathSync(parent).toLowerCase() !== parent.toLowerCase())
+            throw new Error('redirected');
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || Array.isArray(value) || Object.keys(value).length !== 1)
+            throw new Error('invalid');
+        return browserKind(value.browser);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new Error('Browser preference could not be read safely; inspect browser.json.');
+    }
+}
+export async function saveBrowserChoice(file, choice) {
+    browserKind(choice);
+    const previous = readBrowserChoice(file);
+    if (previous === choice)
+        return { changed: false };
+    const parent = resolve(dirname(file));
+    await mkdir(parent, { recursive: true, mode: 0o700 });
+    if ((await lstat(parent)).isSymbolicLink() || (await realpath(parent)).toLowerCase() !== parent.toLowerCase())
+        throw new Error('Redirected browser preference directory.');
+    let backupPath;
+    if (previous !== undefined) {
+        const backup = join(parent, '#0 backup');
+        await mkdir(backup, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        if ((await lstat(backup)).isSymbolicLink() || (await realpath(backup)).toLowerCase() !== backup.toLowerCase())
+            throw new Error('Redirected browser backup directory.');
+        backupPath = join(backup, `browser-${randomUUID()}.json`);
+        await writeFile(backupPath, readFileSync(file), { flag: 'wx', mode: 0o600 });
+    }
+    const temporary = join(parent, `browser-${randomUUID()}.tmp`);
+    await writeFile(temporary, JSON.stringify({ browser: choice }) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(temporary, file);
+    return { changed: true, ...(backupPath ? { backupPath } : {}) };
+}

package/dist/client/codex-setup.js

@@ -5,6 +5,7 @@ import { basename, join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { safeCdpOrigin } from '../core/doctor.js';
 import { defaultEndpoint } from '../ipc/endpoint.js';
+import { browserKind } from './browser-choice.js';
 /** Fail closed when privilege inspection is unavailable. Never execute user-owned clients as administrator. */
 export async function isElevated() {
     if (process.platform !== 'win32')
@@ -27,7 +28,9 @@ function simple(entry, name) {
         return false;
     if (t.type !== 'stdio' || typeof t.command !== 'string' || !Array.isArray(t.args) || !t.args.every((a) => typeof a === 'string'))
         return false;
-    if (t.cwd != null || (t.env != null && (typeof t.env !== 'object' || Object.keys(t.env).length > 0)) || (t.env_vars != null && (!Array.isArray(t.env_vars) || t.env_vars.length > 0)))
+    if (t.cwd != null || (t.env_vars != null && (!Array.isArray(t.env_vars) || t.env_vars.length > 0)))
+        return false;
+    if (t.env != null && (typeof t.env !== 'object' || Array.isArray(t.env) || Object.entries(t.env).some(([key, value]) => name !== 'u_chan_secrets' || (key === 'U_CHAN_BROWSER' ? value !== 'chrome' && value !== 'edge' : key === 'U_CHAN_CDP' ? !safeCdpOrigin(value) : true))))
         return false;
     const command = basename(t.command.replaceAll('\\', '/')).toLowerCase();
     if (name === 'u_chan_secrets')
@@ -72,6 +75,8 @@ export async function configureCodex(o, injected) {
     try {
         if (!safeCdpOrigin(o.endpoint) || (o.replaceExisting && !o.apply))
             return result('manual', 'Use a safe loopback browser target and explicit apply flags.');
+        if (o.browser !== undefined)
+            browserKind(o.browser);
         if (await d.elevated())
             return result('unavailable', 'Run setup from a non-administrator desktop terminal.');
         const desired = [
@@ -95,11 +100,12 @@ export async function configureCodex(o, injected) {
                 const name = key.toUpperCase();
                 return name === 'U_CHAN_CDP' ? safeCdpOrigin(env[key]) !== safeCdpOrigin(o.endpoint)
                     : name === 'U_CHAN_IPC' && env[key] !== ipc;
-            })) || (Array.isArray(inherited) && inherited.some(key => typeof key === 'string' && ['U_CHAN_CDP', 'U_CHAN_IPC'].includes(key.toUpperCase())))) {
+            })) || (Array.isArray(inherited) && inherited.some(key => typeof key === 'string' && ['U_CHAN_CDP', 'U_CHAN_IPC', 'U_CHAN_BROWSER'].includes(key.toUpperCase())))) {
                 return result('manual', 'Custom target environment preserved; align browser and service targets manually.');
             }
             if (current?.enabled === true && current.transport?.type === 'stdio'
-                && current.transport.command === entry.command && JSON.stringify(current.transport.args) === JSON.stringify(entry.args))
+                && current.transport.command === entry.command && JSON.stringify(current.transport.args) === JSON.stringify(entry.args)
+                && (entry.name !== 'u_chan_secrets' || o.browser === undefined || (env?.U_CHAN_BROWSER === o.browser && safeCdpOrigin(env?.U_CHAN_CDP) === safeCdpOrigin(o.endpoint))))
                 continue;
             if (!simple(current, entry.name))
                 return result('manual', 'Custom Codex settings preserved; configure this registration manually.');
@@ -127,7 +133,8 @@ export async function configureCodex(o, injected) {
                     return result('unavailable', 'Codex change failed; inspect configuration before retrying.');
                 changed = true;
             }
-            const added = await d.exec(['mcp', 'add', entry.name, '--', entry.command, ...entry.args]);
+            const browserEnv = entry.name === 'u_chan_secrets' && o.browser ? ['--env', `U_CHAN_BROWSER=${o.browser}`, '--env', `U_CHAN_CDP=${safeCdpOrigin(o.endpoint)}`] : [];
+            const added = await d.exec(['mcp', 'add', entry.name, ...browserEnv, '--', entry.command, ...entry.args]);
             if (added.code !== 0)
                 return result('unavailable', 'Codex change failed; completed changes and backup were retained.');
             changed = true;

package/dist/client/setup.js

@@ -2,6 +2,8 @@ import { bounded, safeCdpOrigin } from '../core/doctor.js';
 export async function runSetup(o, d) {
     const r = { version: 1, state: 'needs_attention', sharing: 'unobserved', restartRequired: false, checks: [], actions: [], client: 'unavailable', changed: false };
     const action = (id, message, required = true) => r.actions.push({ id, message, required });
+    if (d.browser || o.browser)
+        r.browser = o.browser ?? d.browser;
     try {
         if (await bounded(d.elevated, true)) {
             action('configure_mcp', 'Run setup from a non-administrator desktop terminal.');
@@ -17,29 +19,44 @@ export async function runSetup(o, d) {
             r.client = 'manual';
             return r;
         }
+        if (d.configureShell) {
+            r.shell = await d.configureShell(o.apply);
+            r.changed = r.shell.changed;
+            action('configure_shell', r.shell.message, !r.shell.ready);
+        }
         if (r.checks.some(c => c.id === 'browser_target' && c.state === 'fail')) {
             r.sharing = 'mismatch';
             action('configure_mcp', 'Align the desktop and service loopback browser targets before applying setup.');
             return r;
         }
-        const configured = await d.configure({ apply: o.apply, replaceExisting: o.replaceExisting });
+        const configured = await d.configure({ apply: o.apply, replaceExisting: o.replaceExisting, ...(o.browser ? { browser: o.browser } : {}) });
         r.client = configured.state;
-        r.changed = configured.changed;
+        r.changed ||= configured.changed;
         r.backupPath = configured.backupPath;
+        r.restartRequired = configured.changed;
+        if (o.browser && o.apply && r.client === 'ready') {
+            if (!d.selectBrowser)
+                throw new Error('browser selection unavailable');
+            const selected = await d.selectBrowser(o.browser);
+            r.browserChanged = selected.changed;
+            r.browserBackupPath = selected.backupPath;
+            r.changed ||= selected.changed;
+            r.restartRequired ||= selected.changed;
+        }
         let attemptedStart = false, started = true;
-        if (o.startBrowser && !r.checks.some(c => c.id === 'chrome' && c.state === 'pass')) {
+        if (o.startBrowser && (!r.checks.some(c => c.id === 'chrome' && c.state === 'pass') || r.checks.some(c => c.id === 'browser_identity' && c.state !== 'pass'))) {
             attemptedStart = true;
-            started = await bounded(d.startBrowser, false, 15000);
+            started = await bounded(d.startBrowser, false, 25000);
         }
         if (r.changed || attemptedStart)
             r.checks = (await d.doctor()).checks;
         const pw = r.checks.find(c => c.id === 'playwright');
         const mismatch = r.checks.some(c => c.id === 'browser_target' && c.state === 'fail');
         r.sharing = mismatch || pw?.state === 'fail' ? 'mismatch' : pw?.state === 'pass' ? 'process_configured' : 'unobserved';
-        r.restartRequired = r.changed || pw?.state === 'fail';
+        r.restartRequired ||= pw?.state === 'fail';
         const ids = { registration: 'install_service', service: 'install_service', ipc: 'install_service',
             version: 'update_service', assets: 'repair_permissions', permissions: 'repair_permissions', service_browser: 'start_browser', chrome: 'start_browser',
-            browser_target: 'configure_mcp', playwright: 'configure_mcp', uac: 'review_uac' };
+            browser_target: 'configure_mcp', browser_identity: 'start_browser', playwright: 'configure_mcp', uac: 'review_uac' };
         for (const c of r.checks)
             if (c.nextAction) {
                 const id = c.id === 'vault' ? c.state === 'pass' ? 'unlock_vault' : 'authenticate_vault' : ids[c.id] ?? 'configure_mcp';
@@ -48,12 +65,12 @@ export async function runSetup(o, d) {
         if (r.client !== 'ready')
             action('configure_mcp', 'Inspect Codex configuration; apply missing registrations explicitly and preserve custom settings.');
         if (!started)
-            action('start_browser', 'Dedicated Chrome did not become reachable; inspect the launcher and run setup again.');
+            action('start_browser', 'Selected dedicated browser is unavailable or mismatched. Close only the previous dedicated U-Chan instance before switching, then run setup again.');
         if (r.restartRequired)
             action('restart_client', 'Restart the AI session to load saved MCP registrations.', false);
         action('configure_mcp', 'Active AI-session browser ownership is unverified; check the current client browser connection.', false);
         const requiredOk = r.checks.length > 0 && r.checks.filter(c => c.required).every(c => c.state === 'pass');
-        if (requiredOk && r.client === 'ready' && started && !mismatch)
+        if (requiredOk && r.client === 'ready' && started && !mismatch && r.shell?.ready !== false)
             r.state = 'configured';
         return r;
     }

package/dist/client/windows-command.js

@@ -0,0 +1,54 @@
+import { lstat, mkdir, readFile, rename, realpath } from 'node:fs/promises';
+import { delimiter, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Let PowerShell resolve the npm .cmd launcher without changing execution policy or loading a profile. */
+export async function configureWindowsCommand(apply, searchPath) {
+    const result = (ready, message) => ({ ready, changed: false, message });
+    try {
+        for (const entry of searchPath.split(delimiter).filter(Boolean)) {
+            const directory = resolve(entry.replace(/^"|"$/g, ''));
+            const script = join(directory, 'u-chan.ps1'), command = join(directory, 'u-chan.cmd');
+            const exists = async (file) => {
+                try {
+                    return await lstat(file);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        return undefined;
+                    throw error;
+                }
+            };
+            const ps = await exists(script), cmd = await exists(command);
+            if (!ps && !cmd)
+                continue;
+            if (!cmd?.isFile() || cmd.isSymbolicLink() || (ps && (!ps.isFile() || ps.isSymbolicLink()))) {
+                return result(false, 'Custom or redirected u-chan launcher preserved; use u-chan.cmd unlock.');
+            }
+            const batch = await readFile(command, 'utf8');
+            if (!batch.includes('"%dp0%\\node_modules\\u-chan-secrets\\dist\\cli.js" %*')) {
+                return result(false, 'Unrecognized u-chan launcher preserved; inspect command installation manually.');
+            }
+            if (!ps)
+                return result(true, 'PowerShell can use the u-chan.cmd launcher as u-chan.');
+            const source = await readFile(script, 'utf8');
+            if (!source.startsWith('#!/usr/bin/env pwsh') || !source.includes('"$basedir/node_modules/u-chan-secrets/dist/cli.js" $args') || !source.trimEnd().endsWith('exit $ret')) {
+                return result(false, 'Custom PowerShell launcher preserved; use u-chan.cmd unlock.');
+            }
+            if (!apply)
+                return result(false, 'Run u-chan.cmd setup --apply to make u-chan work without PowerShell scripts.');
+            if ((await realpath(directory)).toLowerCase() !== directory.toLowerCase())
+                throw new Error('Redirected launcher directory.');
+            const backupDirectory = join(directory, '#0 backup');
+            await mkdir(backupDirectory, { recursive: true });
+            if ((await lstat(backupDirectory)).isSymbolicLink() || (await realpath(backupDirectory)).toLowerCase() !== backupDirectory.toLowerCase())
+                throw new Error('Redirected backup directory.');
+            const backupPath = join(backupDirectory, `u-chan-${randomUUID()}.ps1`);
+            await rename(script, backupPath);
+            return { ready: true, changed: true, backupPath, message: 'PowerShell now uses u-chan.cmd as u-chan; original .ps1 launcher retained in #0 backup.' };
+        }
+        return result(true, 'No npm u-chan launcher found on PATH; source checkout commands remain unchanged.');
+    }
+    catch {
+        return result(false, 'Could not configure the PowerShell command; use u-chan.cmd unlock and inspect launcher permissions.');
+    }
+}

package/dist/core/browser.js

@@ -1,8 +1,27 @@
 import { execFile } from 'node:child_process';
 import { chromium } from 'playwright';
 import { UserFacingError } from './types.js';
+import { isHostAllowed } from './allowlist.js';
+import { waitForLoginSuccess } from './login-success.js';
+import { bounded } from './doctor.js';
 import { abortable } from './abort.js';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Request-stage CDP interception checks each real main-frame redirect without rewriting responses. */
+async function restrictPageNavigation(page, allowed, signal) {
+    const session = await page.context().newCDPSession(page);
+    const { frameTree } = await session.send('Page.getFrameTree');
+    session.on('Fetch.requestPaused', event => {
+        let permit = false;
+        try {
+            permit = event.frameId !== frameTree.frame.id || (!signal?.aborted && allowed(event.request.url));
+        }
+        catch { }
+        void session.send(permit ? 'Fetch.continueRequest' : 'Fetch.failRequest', permit ? { requestId: event.requestId } : { requestId: event.requestId, errorReason: 'BlockedByClient' }).catch(() => { });
+    });
+    // Bypass service workers only on this owned tab; existing registrations and user tabs are unchanged.
+    await session.send('Network.setBypassServiceWorker', { bypass: true });
+    await session.send('Fetch.enable', { patterns: [{ resourceType: 'Document', requestStage: 'Request' }] });
+}
 /** Runs scripts/start-chrome.ps1 (idempotent: it exits early if the port is already open). */
 export const startChromeScript = (scriptPath) => () => new Promise((resolve, reject) => {
     execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath], { timeout: 30000, windowsHide: true }, (err) => (err ? reject(err) : resolve()));
@@ -14,11 +33,18 @@ export class CdpBrowserProvider {
     disconnecting;
     browser;
     connecting;
+    ownedPages = new Set();
+    openingPages = new Set();
     constructor(endpoint, opts = {}) {
         this.endpoint = endpoint;
         this.opts = opts;
     }
-    async getBrowser(autoLaunch) {
+    async getBrowser(autoLaunch, selectedBrowser) {
+        if (this.opts.validate && !await this.opts.validate(selectedBrowser))
+            throw new UserFacingError('selected dedicated browser identity could not be verified', 'browser_unavailable');
+        // Validated service operations reconnect so a browser switch cannot keep using an old cached destination.
+        if (this.opts.validate)
+            await this.disconnect();
         if (this.browser?.isConnected())
             return this.browser;
         this.connecting ??= this.connect(autoLaunch)
@@ -34,9 +60,9 @@ export class CdpBrowserProvider {
         }
         catch {
             if (!autoLaunch || !this.opts.launch)
-                throw new UserFacingError('Chrome is not running — run scripts/start-chrome.ps1');
+                throw new UserFacingError('selected dedicated browser is not running — run u-chan setup --start-browser', 'browser_unavailable');
         }
-        const fail = () => new UserFacingError('could not start Chrome — run scripts/start-chrome.ps1');
+        const fail = () => new UserFacingError('could not start the selected dedicated browser — run u-chan setup --start-browser', 'browser_unavailable');
         await this.opts.launch().catch(() => {
             throw fail();
         });
@@ -53,32 +79,44 @@ export class CdpBrowserProvider {
     }
     disconnect() {
         return this.disconnecting ??= (async () => {
+            await Promise.allSettled([...this.openingPages].map(opening => bounded(() => opening, undefined, 2000)));
+            await Promise.allSettled([...this.ownedPages].map(page => bounded(() => page.close(), undefined, 2000)));
+            this.ownedPages.clear();
             const browser = this.browser ?? await this.connecting?.catch(() => undefined);
             this.browser = undefined;
             // For connectOverCDP, close disconnects this transport, not the user's Chrome process.
             await browser?.close().catch(() => { });
         })().finally(() => { this.disconnecting = undefined; });
     }
-    async withPage(fn, signal) {
-        const browser = await abortable(this.getBrowser(true), signal, () => this.disconnect(), b => b.close());
+    async withPage(fn, signal, selectedBrowser) {
+        const browser = await abortable(this.getBrowser(true, selectedBrowser), signal, () => this.disconnect(), b => b.close());
         const context = browser.contexts()[0];
         if (!context)
-            throw new UserFacingError('Chrome has no default window — open Chrome with scripts/start-chrome.ps1');
-        const page = await abortable(context.newPage(), signal, () => this.disconnect(), p => p.close());
+            throw new UserFacingError('selected dedicated browser has no default context — run u-chan setup --start-browser', 'browser_unavailable');
+        const opening = context.newPage().then(page => { this.ownedPages.add(page); return page; });
+        this.openingPages.add(opening);
+        let page;
+        try {
+            page = await abortable(opening, signal, () => this.disconnect(), p => p.close());
+        }
+        finally {
+            this.openingPages.delete(opening);
+        }
         page.setDefaultTimeout(5000);
         try {
             signal?.throwIfAborted();
             return await abortable(fn(page), signal, () => this.disconnect());
         }
         finally {
-            await abortable(page.close(), signal, () => this.disconnect()).catch(() => { });
+            await bounded(() => page.close(), undefined, 2000);
+            this.ownedPages.delete(page);
         }
     }
-    async withContext(fn, signal) {
-        const browser = await abortable(this.getBrowser(true), signal, () => this.disconnect(), b => b.close());
+    async withContext(fn, signal, selectedBrowser) {
+        const browser = await abortable(this.getBrowser(true, selectedBrowser), signal, () => this.disconnect(), b => b.close());
         const context = browser.contexts()[0];
         if (!context)
-            throw new UserFacingError('Chrome has no default window — open Chrome with scripts/start-chrome.ps1');
+            throw new UserFacingError('selected dedicated browser has no default context — run u-chan setup --start-browser', 'browser_unavailable');
         signal?.throwIfAborted();
         return abortable(fn(context), signal, () => this.disconnect());
     }
@@ -92,16 +130,45 @@ export class CdpBrowserProvider {
         }
     }
 }
-/** Receives a session (cookies + localStorage) into the user's Chrome over CDP. */
+/** Receives filtered session state and checks approved evidence in the user's dedicated browser over CDP. */
 export class CdpSessionTarget {
     provider;
-    constructor(provider) {
+    options;
+    selectedBrowser = 'chrome';
+    constructor(provider, options = {}) {
         this.provider = provider;
+        this.options = options;
+    }
+    async bindBrowser(browser) {
+        if (browser !== 'chrome' && browser !== 'edge')
+            return false;
+        this.selectedBrowser = browser;
+        return true; // The immediately following provider operation validates this exact kind against the native process.
     }
     userAgent(signal) {
-        return this.provider.withPage((page) => page.evaluate(() => navigator.userAgent), signal);
+        return this.provider.withPage((page) => page.evaluate(() => navigator.userAgent), signal, this.selectedBrowser);
     }
     cancel() { return this.provider.disconnect(); }
+    async verify(entry, finalUrl, signal) {
+        if (!entry.success)
+            return false;
+        const allowed = (url) => this.options.hostCheck ? this.options.hostCheck(entry, url) : isHostAllowed(entry, url);
+        const url = 'url' in entry.success ? entry.success.url : finalUrl;
+        if (!allowed(url))
+            return false;
+        try {
+            return await this.provider.withPage(async (page) => {
+                await restrictPageNavigation(page, allowed, signal);
+                await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+                return waitForLoginSuccess(page, entry.success, allowed, signal, this.options.verifyTimeoutMs ?? 15000);
+            }, signal, this.selectedBrowser);
+        }
+        catch {
+            if (signal?.aborted)
+                signal.throwIfAborted();
+            return false;
+        }
+    }
     inject(state, signal) {
         return this.provider.withContext(async (context) => {
             signal?.throwIfAborted();
@@ -110,9 +177,13 @@ export class CdpSessionTarget {
                 signal?.throwIfAborted();
                 if (!o.localStorage.length)
                     continue;
-                const page = await context.newPage();
-                page.setDefaultTimeout(5000);
-                try {
+                await this.provider.withPage(async (page) => {
+                    await restrictPageNavigation(page, url => { try {
+                        return new URL(url).origin === o.origin;
+                    }
+                    catch {
+                        return false;
+                    } }, signal);
                     await page.goto(o.origin, { waitUntil: 'commit' });
                     signal?.throwIfAborted();
                     await page.evaluate(({ origin, items }) => {
@@ -121,11 +192,8 @@ export class CdpSessionTarget {
                         for (const i of items)
                             localStorage.setItem(i.name, i.value);
                     }, { origin: o.origin, items: o.localStorage });
-                }
-                finally {
-                    await page.close().catch(() => { });
-                }
+                }, signal, this.selectedBrowser);
             }
-        }, signal);
+        }, signal, this.selectedBrowser);
     }
 }