u-chan-secrets 3.0.2 → 4.0.0

package/README.md

@@ -1,11 +1,13 @@
-# U-Chan Secrets V3
+# U-Chan Secrets V4
 
 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.
 
-V3 adds diagnostics, temporary approvals, explicit login outcomes, and a native management window. The source version is `3.0.2`; merging this repository does not publish an npm package or update an installed service.
+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.
 
 **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).
 
+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.
+
 ## What V3 changes
 
 - **Diagnose:** `u-chan doctor` explains service, vault, permission, Chrome, and browser-sharing problems without fetching credentials or repairing configuration.
@@ -16,6 +18,33 @@ V3 adds diagnostics, temporary approvals, explicit login outcomes, and a native
 
 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 V4 adds
+
+Use a normal, non-administrator terminal after installing the matching trusted service:
+
+```powershell
+u-chan setup --json
+u-chan setup --client codex --apply
+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.
+
+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.
+
+Propose a site grant with an explicit success condition:
+
+```sh
+u-chan allow example.com --login-url https://example.com/login --item "Example account" --once --success-url https://example.com/dashboard
+u-chan allow example.com --login-url https://example.com/login --item "Example account" --minutes 30 --success-selector "button[data-action='sign-out']"
+```
+
+The service still requires protected approval. The CLI defaults to one login attempt; timed approvals accept 1–1440 whole minutes, and `--permanent` requests permanent future logins. URL and selector success conditions are mutually exclusive. Without one, login may return `authentication_unconfirmed`; independently verify the signed-in page. Grant expiry does not log out an already transferred browser session.
+
 ## Architecture
 
 ```mermaid
@@ -49,7 +78,7 @@ Install from a trusted shell before granting an AI unrestricted user-account acc
 
 ## Build and install from source
 
-Use the checkout for the V3 source version. Unversioned npm installation can select a different published version; the package metadata in this repository is not proof of npm publication.
+Use a reviewed checkout for the desired source version. Unversioned npm installation can select a different published version; the package metadata in this repository is not proof of npm publication.
 
 ```sh
 git clone https://github.com/anchuwithdeadline/u-chan-secrets.git
@@ -126,9 +155,13 @@ Check the phrase in the genuine protected prompt before entering a password. Nev
 
 The table uses the globally installed `u-chan` spelling; from source use `node dist/cli.js` with the same arguments.
 
+In Windows PowerShell, use `u-chan.cmd` if execution policy blocks npm's `.ps1` shim, for example `u-chan.cmd doctor --json`. No machine execution-policy change is needed.
+
 | 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 |
+| `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 |
 | `lock` | Forget the service's vault session and request vault lock |
@@ -200,6 +233,8 @@ Supported V3 tooling refuses V2 downgrade after migration. Historical V2 adminis
 
 Package updates verify registry signatures and integrity and retain private dependencies. Changed dependencies or native helpers require a trusted administrator reinstall. Expired/exhausted grants and already transferred website sessions are separate from vault lock and upgrade state.
 
+Versions 3.0.0–3.0.2 have an npm signature-verification defect and cannot reliably bootstrap their own update. Install the matching corrected package from a trusted shell, then use the administrator reinstall above. Version 3.0.3 requires SHA-512 integrity and a valid signature from its pinned npm key; unsigned repository-attestation JSON cannot replace that signature. Future signing-key rotation fails closed and requires a trusted verifier upgrade.
+
 For V1 data, use `u-chan import-v1 [path]`: each entry requires protected approval. Retire user-side Bitwarden sessions and the old `bw-session` file through a trusted migration process; never copy them into the service as trusted authorization.
 
 ## Validation and security

package/dist/cli.js

@@ -7,8 +7,13 @@ import { fileURLToPath } from 'node:url';
 import { IpcClient } from './ipc/client.js';
 import { defaultEndpoint } from './ipc/endpoint.js';
 import { MAX_FRAME, encode } from './ipc/protocol.js';
-import { runDoctor, doctorExitCode, checkPlaywrightNow, chromeState, SERVICE_DIAGNOSTIC_TIMEOUT_MS } from './core/doctor.js';
+import { runDoctor, doctorExitCode, checkPlaywrightNow, chromeState, safeVersion, SERVICE_DIAGNOSTIC_TIMEOUT_MS } from './core/doctor.js';
 import { loadConfig } from './core/config.js';
+import { execFile } from 'node:child_process';
+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';
 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;
@@ -25,6 +30,9 @@ export async function main(argv, d) {
     let call;
     const doctor = d.doctor ?? (() => runDoctor({
         platform: d.platform,
+        clientVersion: d.clientVersion ?? 'unknown',
+        clientEndpoint: loadConfig(d.env, d.platform).cdpEndpoint,
+        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 () => {
             const r = await d.connect({ timeoutMs: SERVICE_DIAGNOSTIC_TIMEOUT_MS }).diagnose();
@@ -39,11 +47,74 @@ export async function main(argv, d) {
         playwright: async () => {
             if (d.platform !== 'win32')
                 return 'unknown';
-            const state = await checkPlaywrightNow();
+            const state = await checkPlaywrightNow(process.pid, loadConfig(d.env, d.platform).cdpEndpoint);
             return state === 'ok' ? 'pass' : state === 'missing' ? 'fail' : 'unknown';
         },
     }));
     const printDoctor = (r) => d.out(r.checks.map(c => `${c.state.toUpperCase()} ${c.id}: ${c.message}${c.nextAction ? ' ' + c.nextAction : ''}`).join('\n'));
+    if (cmd === 'allow') {
+        const proposal = parseAllowArgs(argv.slice(1));
+        if (!proposal) {
+            d.err('usage: u-chan allow <domain> --login-url <https-url> --item <label> [--once|--minutes <1..1440>|--permanent] [--success-url <https-url>|--success-selector <selector>]');
+            return 1;
+        }
+        const r = await d.connect({ timeoutMs: 180000 }).requestAllow(proposal.domain, proposal.loginUrl, proposal.item, undefined, proposal.options);
+        if (r.ok) {
+            d.out(r.message);
+            if (!proposal.options.success)
+                d.out('No success condition supplied. Login may return authentication_unconfirmed; independently verify the signed-in page.');
+        }
+        else
+            d.err(r.message);
+        return r.ok ? 0 : 1;
+    }
+    if (cmd === 'setup') {
+        const args = argv.slice(1), seen = new Set();
+        let valid = true;
+        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)) {
+                valid = false;
+                break;
+            }
+            seen.add(flag);
+            if (flag === '--client' && args[++i] !== 'codex') {
+                valid = false;
+                break;
+            }
+        }
+        if (!valid || (seen.has('--replace-existing') && !seen.has('--apply'))) {
+            d.err('usage: u-chan setup [--client codex] [--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 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') }),
+            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);
+                });
+            }),
+        });
+        if (seen.has('--json'))
+            d.out(JSON.stringify(r));
+        else
+            d.out([`Setup: ${r.state}; sharing: ${r.sharing}; restart required: ${r.restartRequired}`, ...r.actions.map(a => a.message), ...(r.backupPath ? ['Configuration backup: ' + r.backupPath] : [])].join('\n'));
+        return setupExitCode(r);
+    }
     if (cmd === 'doctor' && (arg === undefined || arg === '--json') && rest.length === 0) {
         const r = await doctor();
         if (arg === '--json')
@@ -183,7 +254,13 @@ const isEntry = (() => {
     }
 })();
 if (isEntry) {
+    let clientVersion = 'unknown';
+    try {
+        clientVersion = safeVersion(JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version) ?? 'unknown';
+    }
+    catch { }
     const code = await main(process.argv.slice(2), {
+        clientVersion,
         connect: (opts) => new IpcClient(defaultEndpoint(process.env, process.platform), opts),
         env: process.env,
         platform: process.platform,

package/dist/client/allow.js

@@ -0,0 +1,64 @@
+import { buildEntry, clean, normalizeDomain } from '../core/allowlist.js';
+import { validOptions } from '../core/policy.js';
+function https(value) {
+    if (value.length > 2048 || clean(value) !== value)
+        return false;
+    try {
+        const u = new URL(value);
+        return u.protocol === 'https:' && !u.username && !u.password;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseAllowArgs(args) {
+    const [domain, ...flags] = args;
+    if (!domain || domain.length > 253 || clean(domain) !== domain || /[@:/\\?#\s]/.test(domain) || !normalizeDomain(domain))
+        return null;
+    const seen = new Set(), values = new Map();
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (seen.has(flag) || !['--login-url', '--item', '--once', '--permanent', '--minutes', '--success-url', '--success-selector'].includes(flag))
+            return null;
+        seen.add(flag);
+        if (flag === '--once' || flag === '--permanent')
+            continue;
+        const value = flags[++i];
+        if (!value || value.startsWith('--') || clean(value) !== value)
+            return null;
+        values.set(flag, value);
+    }
+    const loginUrl = values.get('--login-url'), item = values.get('--item');
+    if (!loginUrl || !https(loginUrl) || !item?.trim() || item.length > 1000)
+        return null;
+    if (['--once', '--permanent', '--minutes'].filter(f => seen.has(f)).length > 1)
+        return null;
+    if (seen.has('--success-url') && seen.has('--success-selector'))
+        return null;
+    const options = { grant: { kind: 'once' } };
+    if (seen.has('--permanent'))
+        options.grant = { kind: 'permanent' };
+    if (seen.has('--minutes')) {
+        const raw = values.get('--minutes');
+        if (!/^[1-9]\d{0,3}$/.test(raw))
+            return null;
+        options.grant = { kind: 'timed', minutes: Number(raw) };
+    }
+    if (seen.has('--success-url')) {
+        const url = values.get('--success-url');
+        if (!https(url))
+            return null;
+        options.success = { url };
+    }
+    if (seen.has('--success-selector'))
+        options.success = { selector: values.get('--success-selector').trim() };
+    if (!validOptions(options))
+        return null;
+    try {
+        const entry = buildEntry(domain, loginUrl, item);
+        return { domain: entry.domain, loginUrl, item, options };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/client/codex-setup.js

@@ -0,0 +1,140 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, realpath } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { safeCdpOrigin } from '../core/doctor.js';
+import { defaultEndpoint } from '../ipc/endpoint.js';
+/** Fail closed when privilege inspection is unavailable. Never execute user-owned clients as administrator. */
+export async function isElevated() {
+    if (process.platform !== 'win32')
+        return process.getuid?.() === 0;
+    return new Promise(resolve => execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        '([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)'], { timeout: 5000, windowsHide: true, maxBuffer: 1024 }, (err, out) => resolve(!!err || out.trim() !== 'False')));
+}
+function simple(entry, name) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return false;
+    const keys = ['name', 'enabled', 'disabled_reason', 'transport', 'enabled_tools', 'disabled_tools', 'startup_timeout_sec', 'tool_timeout_sec'];
+    if (Object.keys(entry).some(k => !keys.includes(k)) || entry.enabled !== true || entry.disabled_reason != null)
+        return false;
+    for (const key of ['enabled_tools', 'disabled_tools', 'startup_timeout_sec', 'tool_timeout_sec']) {
+        if (entry[key] != null)
+            return false;
+    }
+    const t = entry.transport;
+    if (!t || typeof t !== 'object' || Object.keys(t).some(k => !['type', 'command', 'args', 'env', 'env_vars', 'cwd'].includes(k)))
+        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)))
+        return false;
+    const command = basename(t.command.replaceAll('\\', '/')).toLowerCase();
+    if (name === 'u_chan_secrets')
+        return ['node', 'node.exe'].includes(command) && t.args.length === 1 && /(?:^|[\\/])index\.js$/.test(t.args[0]);
+    return ['npx', 'npx.cmd', 'npx.exe'].includes(command) && /^@playwright\/mcp(?:@[^\s]+)?$/.test(t.args[0] ?? '')
+        && (t.args.length === 1 || (t.args.length === 3 && t.args[1] === '--cdp-endpoint' && !!safeCdpOrigin(t.args[2])));
+}
+async function backup(configDir) {
+    const root = resolve(configDir);
+    const info = await lstat(root);
+    if (!info.isDirectory() || info.isSymbolicLink() || (await realpath(root)).toLowerCase() !== root.toLowerCase())
+        throw new Error('redirected config');
+    const config = join(root, 'config.toml');
+    try {
+        const file = await lstat(config);
+        if (!file.isFile() || file.isSymbolicLink())
+            throw new Error('redirected config');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    const dir = join(root, '#0 backup');
+    await mkdir(dir, { mode: 0o700 }).catch(err => { if (err.code !== 'EEXIST')
+        throw err; });
+    const target = await lstat(dir);
+    if (!target.isDirectory() || target.isSymbolicLink() || (await realpath(dir)).toLowerCase() !== dir.toLowerCase())
+        throw new Error('redirected backup');
+    const path = join(dir, `u-chan-setup-${randomUUID()}.toml`);
+    await copyFile(config, path, constants.COPYFILE_EXCL);
+    await chmod(path, 0o600);
+    return path;
+}
+/** Inspect through the official Codex CLI; never parse or rewrite TOML, or return its contents. */
+export async function configureCodex(o, injected) {
+    let changed = false, backupPath;
+    const result = (state, message) => ({ state, changed, ...(backupPath ? { backupPath } : {}), message });
+    const d = injected ?? { elevated: isElevated, exec: args => new Promise(resolve => {
+            execFile('codex', args, { timeout: 15000, windowsHide: true, maxBuffer: 1024 * 1024, env: { ...process.env, CODEX_HOME: o.configDir } }, (err, stdout, stderr) => resolve({ code: err ? 1 : 0, stdout, stderr }));
+        }) };
+    try {
+        if (!safeCdpOrigin(o.endpoint) || (o.replaceExisting && !o.apply))
+            return result('manual', 'Use a safe loopback browser target and explicit apply flags.');
+        if (await d.elevated())
+            return result('unavailable', 'Run setup from a non-administrator desktop terminal.');
+        const desired = [
+            { name: 'u_chan_secrets', command: o.nodePath, args: [o.entryPath] },
+            { name: 'playwright', command: 'npx', args: ['@playwright/mcp@latest', '--cdp-endpoint', safeCdpOrigin(o.endpoint)] },
+        ];
+        const pending = [];
+        for (const entry of desired) {
+            const r = await d.exec(['mcp', 'get', entry.name, '--json']);
+            if (r.code !== 0) {
+                if (r.stderr.trim().split(/\r?\n/).at(-1) !== `Error: No MCP server named '${entry.name}' found.`)
+                    return result('unavailable', 'Could not inspect Codex registrations.');
+                pending.push({ entry, replace: false });
+                continue;
+            }
+            const current = JSON.parse(r.stdout);
+            const env = current?.transport?.env;
+            const inherited = current?.transport?.env_vars;
+            const ipc = o.ipcEndpoint ?? defaultEndpoint(process.env, process.platform);
+            if ((env && Object.keys(env).some(key => {
+                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())))) {
+                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))
+                continue;
+            if (!simple(current, entry.name))
+                return result('manual', 'Custom Codex settings preserved; configure this registration manually.');
+            pending.push({ entry, replace: true });
+        }
+        if (pending.length === 0)
+            return result('ready', 'Codex registrations match; active session ownership is unverified.');
+        const replaces = pending.some(p => p.replace);
+        if (!o.apply || (replaces && !o.replaceExisting))
+            return result(replaces ? 'needs_update' : 'missing', 'Explicit setup apply is required; replacements also require --replace-existing.');
+        // No whole-file rollback: the official CLI or another process may edit unrelated settings concurrently.
+        try {
+            await lstat(o.configDir);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            await mkdir(o.configDir, { recursive: true, mode: 0o700 });
+        }
+        backupPath = await backup(o.configDir);
+        for (const { entry, replace } of pending) {
+            if (replace) {
+                const removed = await d.exec(['mcp', 'remove', entry.name]);
+                if (removed.code !== 0)
+                    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]);
+            if (added.code !== 0)
+                return result('unavailable', 'Codex change failed; completed changes and backup were retained.');
+            changed = true;
+        }
+        return result('ready', 'Codex registrations saved. Restart the AI session; active ownership remains unverified.');
+    }
+    catch {
+        return result('unavailable', 'Codex setup unavailable; inspect configuration and any retained backup before retrying.');
+    }
+}

package/dist/client/setup.js

@@ -0,0 +1,67 @@
+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 });
+    try {
+        if (await bounded(d.elevated, true)) {
+            action('configure_mcp', 'Run setup from a non-administrator desktop terminal.');
+            return r;
+        }
+        if (!safeCdpOrigin(d.endpoint)) {
+            action('configure_mcp', 'Configure a safe HTTP loopback browser target.');
+            return r;
+        }
+        r.checks = (await d.doctor()).checks;
+        if (d.platform !== 'win32') {
+            action('configure_mcp', 'Automatic setup supports Windows and Codex only; configure other platforms manually.');
+            r.client = 'manual';
+            return r;
+        }
+        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 });
+        r.client = configured.state;
+        r.changed = configured.changed;
+        r.backupPath = configured.backupPath;
+        let attemptedStart = false, started = true;
+        if (o.startBrowser && !r.checks.some(c => c.id === 'chrome' && c.state === 'pass')) {
+            attemptedStart = true;
+            started = await bounded(d.startBrowser, false, 15000);
+        }
+        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';
+        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' };
+        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';
+                action(id, c.nextAction, c.required && c.state !== 'pass');
+            }
+        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.');
+        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)
+            r.state = 'configured';
+        return r;
+    }
+    catch {
+        action('configure_mcp', 'Setup inspection failed; run u-chan doctor and inspect retained configuration changes.');
+        return r;
+    }
+}
+export function setupExitCode(r) {
+    return r.state === 'needs_attention' ? 1 : r.restartRequired ? 2 : 0;
+}

package/dist/core/doctor.js

@@ -5,7 +5,7 @@ const IS_PLAYWRIGHT = /@playwright[\\/]mcp/i;
  * Finds the AI client that launched us (first non-shell ancestor), then checks whether that
  * client's Playwright MCP was started with --cdp-endpoint (i.e. shares our Chrome).
  */
-export function checkPlaywrightCdp(procs, selfPid) {
+export function checkPlaywrightCdp(procs, selfPid, expectedEndpoint) {
     const byPid = new Map(procs.map((p) => [p.pid, p]));
     const ancestors = (pid) => {
         const out = [];
@@ -22,18 +22,26 @@ export function checkPlaywrightCdp(procs, selfPid) {
     const ours = procs.filter((p) => IS_PLAYWRIGHT.test(p.cmd) && ancestors(p.pid).some((a) => a.pid === client.pid));
     if (ours.length === 0)
         return 'not_found';
+    if (expectedEndpoint !== undefined) {
+        const expected = safeCdpOrigin(expectedEndpoint);
+        return expected && ours.every(p => {
+            const matches = [...p.cmd.matchAll(/(?:^|\s)--cdp-endpoint(?:=|\s+)(?:"([^"]*)"|'([^']*)'|([^\s]+))/g)];
+            const match = matches[0];
+            return matches.length === 1 && match && safeCdpOrigin(match[1] ?? match[2] ?? match[3]) === expected;
+        }) ? 'ok' : 'missing';
+    }
     return ours.some((p) => p.cmd.includes('--cdp-endpoint')) ? 'ok' : 'missing';
 }
 const PS_LIST = 'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress';
 /** Lists processes via PowerShell/CIM; returns 'unknown' on any failure. */
-export async function checkPlaywrightNow(selfPid = process.pid) {
+export async function checkPlaywrightNow(selfPid = process.pid, expectedEndpoint) {
     if (process.platform !== 'win32')
         return 'unknown';
     try {
         const stdout = await new Promise((resolve, reject) => execFile('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_LIST], { timeout: 15000, windowsHide: true, maxBuffer: 64 * 1024 * 1024 }, (err, out) => (err ? reject(err) : resolve(String(out)))));
         const raw = JSON.parse(stdout);
         const procs = raw.map((r) => ({ pid: r.ProcessId, ppid: r.ParentProcessId, name: r.Name ?? '', cmd: r.CommandLine ?? '' }));
-        return checkPlaywrightCdp(procs, selfPid);
+        return checkPlaywrightCdp(procs, selfPid, expectedEndpoint);
     }
     catch {
         return 'unknown';
@@ -41,6 +49,21 @@ export async function checkPlaywrightNow(selfPid = process.pid) {
 }
 // Leave room for the service's full native ACL scan and IPC overhead.
 export const SERVICE_DIAGNOSTIC_TIMEOUT_MS = 25000;
+export function safeVersion(value) {
+    return typeof value === 'string' && value.length <= 64 && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value) ? value : undefined;
+}
+export function safeCdpOrigin(value) {
+    if (typeof value !== 'string' || !/^http:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::[1-9]\d{0,4})?\/?$/i.test(value))
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+            && !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash ? url.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function bounded(probe, fallback, timeoutMs = 5000) {
     let timer;
     try {
@@ -54,11 +77,12 @@ export async function bounded(probe, fallback, timeoutMs = 5000) {
     }
 }
 export async function runDoctor(d) {
-    const [registration, service, chrome, playwright] = await Promise.all([
+    const [registration, service, chrome, playwright, elevation] = await Promise.all([
         bounded(d.registration, 'unknown'),
         bounded(d.service, null, SERVICE_DIAGNOSTIC_TIMEOUT_MS),
         bounded(d.chrome, 'unknown'),
         bounded(d.playwright, 'unknown'),
+        bounded(d.elevation ?? (async () => 'unknown'), 'unknown'),
     ]);
     const checks = [];
     const add = (id, state, message, nextAction, required = true) => {
@@ -70,6 +94,17 @@ export async function runDoctor(d) {
     add('service', service ? 'pass' : 'fail', service ? 'Service is reachable.' : 'Service is unreachable.', 'Check service status; run u-chan install if absent.');
     add('ipc', service ? 'pass' : 'unknown', 'Authenticated service connection checked.', 'Check the installed owner account and service.');
     const state = (value) => value === 'pass' || value === 'fail' ? value : 'unknown';
+    if (d.clientVersion !== undefined) {
+        const client = safeVersion(d.clientVersion), installed = safeVersion(service?.serviceVersion);
+        add('version', !client || !installed ? 'unknown' : client === installed ? 'pass' : 'fail', 'CLI and installed service versions checked.', 'Install the matching trusted service package.');
+    }
+    if (d.clientEndpoint !== undefined) {
+        const client = safeCdpOrigin(d.clientEndpoint), installed = safeCdpOrigin(service?.browserEndpoint);
+        add('service_browser', state(service?.browser), 'Service browser endpoint checked.', 'Start dedicated Chrome and check the service browser target.');
+        add('browser_target', !client || !installed ? 'unknown' : client === installed ? 'pass' : 'fail', 'Desktop and service browser targets checked.', 'Align the desktop and service loopback browser targets.');
+    }
+    if (d.platform === 'win32' && d.elevation)
+        add('uac', elevation, 'Windows administrator prompt policy checked.', 'Set UAC to Always notify in Windows settings.');
     add('assets', state(service?.assets), 'Private service assets checked.', 'Repair the installation from a trusted administrator terminal.');
     add('permissions', state(service?.permissions), 'Protected service permissions checked.', 'Repair protected permissions from a trusted administrator terminal.');
     const v = service?.vault;
@@ -91,12 +126,15 @@ export async function commandState(file, args, passes, timeoutMs = 5000) {
         });
     });
 }
-export async function chromeState(endpoint) {
+export async function chromeState(endpoint, timeoutMs = 5000) {
     try {
-        const url = new URL('/json/version', endpoint);
+        const origin = safeCdpOrigin(endpoint);
+        if (!origin)
+            return 'fail';
+        const url = new URL('/json/version', origin);
         if (!['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname) || url.protocol !== 'http:')
             return 'fail';
-        const r = await fetch(url, { signal: AbortSignal.timeout(5000), redirect: 'error' });
+        const r = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
         const json = await r.json();
         return r.ok && typeof json.webSocketDebuggerUrl === 'string' ? 'pass' : 'fail';
     }

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { IpcClient } from './ipc/client.js';
 import { defaultEndpoint } from './ipc/endpoint.js';
 import { checkPlaywrightNow } from './core/doctor.js';
+import { loadConfig } from './core/config.js';
 import { createMcpServer, withPlaywrightStatus } from './mcp/server.js';
 // Thin MCP client: every privileged action goes to the U-Chan service over IPC.
 // stdout is the MCP channel: log only to stderr.
@@ -13,4 +14,4 @@ try {
 }
 catch { }
 const client = new IpcClient(defaultEndpoint(process.env, process.platform));
-await createMcpServer(withPlaywrightStatus(client, checkPlaywrightNow), version).connect(new StdioServerTransport());
+await createMcpServer(withPlaywrightStatus(client, () => checkPlaywrightNow(process.pid, loadConfig(process.env, process.platform).cdpEndpoint)), version).connect(new StdioServerTransport());

package/dist/mcp/server.js

@@ -19,8 +19,8 @@ const INSTRUCTIONS = [
     'If login fails, call status: a locked vault means the user must run u-chan unlock themselves. If login says "needs you", ask the user to sign in by hand.',
 ].join('\n');
 const PLAYWRIGHT_MSG = {
-    ok: 'shared chrome',
-    missing: 'missing --cdp-endpoint (using its own Chrome; restart the AI session)',
+    ok: 'shared chrome process configuration observed; active AI session ownership unverified',
+    missing: 'missing or mismatched --cdp-endpoint (restart the AI session)',
     not_found: 'not found',
     unknown: 'unknown',
 };