trackqa 0.0.0-stage → 0.1.0

package/dist/tools/trackqa-connect/src/auth.js

@@ -0,0 +1,153 @@
+import { createClient } from '@supabase/supabase-js';
+import { readFile } from 'node:fs/promises';
+import { parseEnv } from 'node:util';
+import { googlePkceSignIn, GooglePkceError } from '../../mcp-pilot/google-pkce.mjs';
+import { boundedJson, ConnectorError, requireValue, SUPABASE_URL, UUID } from "./core.js";
+import { fixtureMembershipRoute, fixtureRequestAllowed, fixtureScopeState, observeFixtureResponse } from "./testing/copilot-fixture-scope.js";
+export function isPublicKey(key) {
+    if (/^sb_publishable_[A-Za-z0-9_-]+$/.test(key))
+        return true;
+    try {
+        return JSON.parse(Buffer.from(key.split('.')[1], 'base64url').toString()).role === 'anon';
+    }
+    catch {
+        return false;
+    }
+}
+export async function publicKey(env = process.env) {
+    let value = env.TRACKQA_PUBLIC_KEY ?? env.VITE_SUPABASE_ANON_KEY;
+    // Local development only: read the existing app's public key, never load its
+    // other variables into process.env or pass them to the coding client.
+    if (!value) {
+        for (const file of ['.env.local', '.env']) {
+            try {
+                const text = await readFile(new URL('../../../' + file, import.meta.url), 'utf8');
+                const line = text.split(/\r?\n/).find(line => /^\s*VITE_SUPABASE_ANON_KEY\s*=/.test(line));
+                if (line)
+                    value = parseEnv(line).VITE_SUPABASE_ANON_KEY;
+                if (value)
+                    break;
+            }
+            catch { /* No secret or filesystem error details leave this function. */ }
+        }
+    }
+    requireValue(value && value.length <= 8192 && isPublicKey(value), 'public_key_required');
+    return value;
+}
+// The CLI receives only a checked human API closure. Raw Auth tokens and the SDK
+// client never reach the client adapter or the recovery store.
+export async function withOwner(options, action) {
+    requireValue(isPublicKey(options.key), 'public_key_required');
+    if (options.fixtureScope)
+        fixtureScopeState(options.fixtureScope);
+    const posts = new Set();
+    const send = options.fetch ?? fetch;
+    const authFetch = async (input, init = {}) => {
+        const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+        const method = init.method ?? 'GET';
+        const allowed = method === 'GET' ? url.pathname === '/auth/v1/user' && !url.search
+            : method === 'POST' && ((url.pathname === '/auth/v1/token' && url.search === '?grant_type=pkce')
+                || (url.pathname === '/auth/v1/logout' && url.search === '?scope=local'));
+        requireValue(url.origin === SUPABASE_URL && allowed, 'authentication_failed');
+        if (method === 'POST') {
+            requireValue(!posts.has(url.pathname), 'authentication_failed');
+            posts.add(url.pathname);
+        }
+        let response;
+        try {
+            response = await send(url.href, { ...init, signal: AbortSignal.timeout(10_000), redirect: 'error', credentials: 'omit', cache: 'no-store' });
+        }
+        catch {
+            throw new ConnectorError('authentication_failed');
+        }
+        // Bound error responses too; only the SDK sees their bodies, never output.
+        if (response.status === 204)
+            return new Response(null, { status: 204 });
+        try {
+            const data = await boundedJson(new Response(response.body, { status: 200 }), 65_536);
+            return Response.json(data, { status: response.status, headers: response.headers });
+        }
+        catch {
+            throw new ConnectorError('authentication_failed');
+        }
+        finally {
+            await response.body?.cancel().catch(() => { });
+        }
+    };
+    const memory = new Map();
+    const client = (options.makeClient ?? createClient)(SUPABASE_URL, options.key, {
+        auth: { flowType: 'pkce', persistSession: false, autoRefreshToken: false, detectSessionInUrl: false, debug: false,
+            storage: { getItem: (key) => memory.get(key) ?? null, setItem: (key, value) => { memory.set(key, value); }, removeItem: (key) => { memory.delete(key); } } },
+        db: { retry: false }, global: { fetch: authFetch },
+    });
+    let login;
+    let authenticated = false;
+    let result;
+    let failure;
+    let access = '';
+    try {
+        requireValue(!options.signal?.aborted, 'interrupted');
+        login = await (options.signIn ?? googlePkceSignIn)(client, { signal: options.signal });
+        authenticated = Boolean(login?.data?.session);
+        requireValue(authenticated && !login?.error, 'authentication_failed');
+        const verified = await client.auth.getUser();
+        const user = verified.data?.user;
+        requireValue(!verified.error && user && UUID.test(user.id) && user.id === login?.data?.user?.id, 'identity_unverified');
+        requireValue(!user.factors?.some(factor => factor.status === 'verified'), 'mfa_unsupported');
+        access = login.data.session.access_token;
+        const api = async (route, method = 'GET', body) => {
+            // Fixed project endpoint; no arbitrary targets, redirects or privileged key.
+            const url = new URL(route, SUPABASE_URL);
+            requireValue(url.origin === SUPABASE_URL && !url.username && !url.password && route.startsWith('/rest/v1/'), 'request_failed');
+            const resource = url.pathname.slice('/rest/v1/'.length);
+            requireValue(options.fixtureScope ? fixtureRequestAllowed(options.fixtureScope, user.id, route, method, body) : method === 'GET' ? ['profiles', 'projects', 'project_members', 'mcp_connections'].includes(resource)
+                : method === 'PATCH' ? resource === 'projects' && !!url.searchParams.get('id') && JSON.stringify(body) === '{"mcp_enabled":true}'
+                    : ['rpc/issue_mcp_connection_token', 'rpc/revoke_mcp_connection'].includes(resource), 'request_failed');
+            try {
+                const result = await boundedJson(await send(url.href, { method, headers: { apikey: options.key, Authorization: `Bearer ${access}`, 'Content-Type': 'application/json', Prefer: 'return=representation' },
+                    body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(10_000), redirect: 'error', cache: 'no-store', credentials: 'omit' }));
+                if (options.fixtureScope)
+                    observeFixtureResponse(options.fixtureScope, user.id, route, result);
+                return result;
+            }
+            catch {
+                throw new ConnectorError('request_failed');
+            }
+        };
+        const profile = await api(`/rest/v1/profiles?id=eq.${user.id}&select=id&limit=2`);
+        requireValue(Array.isArray(profile) && profile.length === 1 && profile[0].id === user.id, 'profile_required');
+        const memberships = await api(options.fixtureScope ? fixtureMembershipRoute(user.id) : `/rest/v1/project_members?user_id=eq.${user.id}&role=eq.OWNER&select=project_id,role,project:projects(id,name,key,mcp_enabled,archived)&limit=201`);
+        requireValue(Array.isArray(memberships) && memberships.length <= 200, 'project_selection_unavailable');
+        const projects = memberships.filter(row => row.role === 'OWNER' && UUID.test(row.project_id) && row.project?.id === row.project_id
+            && row.project.archived === false && typeof row.project.mcp_enabled === 'boolean' && typeof row.project.name === 'string' && typeof row.project.key === 'string')
+            .map(row => row.project);
+        requireValue(!options.signal?.aborted, 'interrupted');
+        result = await action({ userId: user.id, api, projects });
+    }
+    catch (error) {
+        failure = error instanceof ConnectorError ? error : error instanceof GooglePkceError ? new ConnectorError(error.code) : new ConnectorError('authentication_failed');
+    }
+    finally {
+        access = '';
+        if (authenticated) {
+            try {
+                if ((await client.auth.signOut({ scope: 'local' })).error)
+                    failure ??= new ConnectorError('signout_unconfirmed');
+            }
+            catch {
+                failure ??= new ConnectorError('signout_unconfirmed');
+            }
+        }
+        if (login?.data.session) {
+            login.data.session.access_token = '';
+            login.data.session.refresh_token = '';
+            login.data.session.provider_token = null;
+            login.data.session.provider_refresh_token = null;
+        }
+        login = undefined;
+        memory.clear(); // Includes any verifier retained after an incomplete exchange.
+    }
+    if (failure)
+        throw failure;
+    return result;
+}

package/dist/tools/trackqa-connect/src/cli.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+import { realpath } from 'node:fs/promises';
+import { publicKey, withOwner } from "./auth.js";
+import { codexAdapter, detectCodex } from "./clients/codex.js";
+import { geminiAdapter, detectGemini } from "./clients/gemini.js";
+import { claudeAdapter, detectClaude } from "./clients/claude.js";
+import { vscodeAdapter, detectVSCode } from "./clients/vscode.js";
+import { vscodeCopilotAdapter } from "./clients/vscode-copilot.js";
+import { copilotRecoveryHome, freshCopilotHome } from "./clients/vscode-copilot-session.js";
+import { recordHome } from "./state.js";
+import { adapterLabel } from "./clients/adapter.js";
+import { ConnectorError, display, parseArgs, requireValue } from "./core.js";
+import { Store } from "./state.js";
+import { connect, disconnect, status } from "./workflow.js";
+export const help = `TrackQA Connect 0.1.0 - Windows, Owner-operated MVP release candidate
+Usage after installing the approved package or local tarball:
+  trackqa connect --client codex
+  trackqa status --client codex
+  trackqa disconnect --client codex
+Intended registry workflow after publication: npx trackqa connect
+Codex CLI: MVP-supported candidate; Windows hosted acceptance passed.
+Gemini CLI and Claude Code: experimental; hosted validation deferred.
+VS Code Local (--client vscode): experimental; hosted read-only acceptance passed.
+VS Code Copilot (--client vscode-copilot): experimental; hosted read-only acceptance passed; ordinary connect remains guarded before authentication.
+Antigravity: deferred; no adapter.
+Optional: --project <project UUID> --codex-path <trusted absolute native executable>
+Gemini optional: --gemini-path <installed @google/gemini-cli package bin .js>
+Claude optional: --claude-path <trusted absolute native claude.exe>
+VS Code optional: --vscode-path <trusted installed absolute Code.exe>; supported family 1.143.x.
+Claude connect only: --claude-only excludes other MCP servers for this session (opt-in).
+No client is selected by default. AI-client accounts are separate from TrackQA sign-in.
+Requires Node >=22.19, Windows, a free localhost callback port 5173 and Google Owner authorization; MFA accounts are unsupported.
+Set TRACKQA_PUBLIC_KEY to the deployment's public anon/publishable key. Never supply a secret or service-role key.
+No bearer token is saved. The existing 90-day token expiry is unchanged; session cleanup attempts and independently verifies revocation.
+Status is local-only: it does not authorize or test a live MCP connection.
+Disconnect may require fresh Google Owner sign-in. Never pass credentials as arguments.`;
+export async function locations(env = process.env, client = 'codex') {
+    const codexHome = env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+    if (client === 'codex')
+        requireValue(path.isAbsolute(codexHome), 'configuration_location_untrusted');
+    const canonical = await realpath(codexHome).catch(() => path.resolve(codexHome));
+    const repo = fileURLToPath(new URL('../../../', import.meta.url));
+    const under = (target, base) => target.toLowerCase() === base.toLowerCase() || target.toLowerCase().startsWith(path.resolve(base).toLowerCase() + path.sep);
+    if (client === 'codex')
+        requireValue(!under(canonical, process.cwd()) && !under(canonical, repo), 'configuration_location_untrusted');
+    const data = process.platform === 'win32' ? env.LOCALAPPDATA : env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state');
+    requireValue(data && path.isAbsolute(data) && !under(data, repo) && !under(data, process.cwd()), 'recovery_unavailable');
+    const geminiHome = env.GEMINI_CLI_HOME ?? os.homedir();
+    const geminiCanonical = await realpath(geminiHome).catch(() => path.resolve(geminiHome));
+    if (client === 'gemini') {
+        requireValue(path.isAbsolute(geminiHome) && !under(geminiCanonical, repo) && !under(geminiCanonical, process.cwd()), 'configuration_location_untrusted');
+        const config = path.join(geminiCanonical, '.gemini');
+        const resolved = await realpath(config).catch(() => config);
+        requireValue(resolved.toLowerCase() === config.toLowerCase(), 'configuration_location_untrusted');
+    }
+    return { codexHome: canonical, geminiHome: geminiCanonical, claudeHome: path.join(data, 'TrackQA-Connect', 'claude-sessions'), vscodeHome: path.join(data, 'TrackQA-Connect', 'vscode-sessions'), vscodeCopilotHome: path.join(data, 'TrackQA-Connect', 'vscode-copilot-sessions'), store: new Store(path.join(data, 'TrackQA-Connect')) };
+}
+const codes = new Set(`usage configuration_busy configuration_write_failed configuration_write_uncertain gemini_auto_update_enabled gemini_compatibility_unverified client_unsupported client_foreground_unsupported client_not_found executable_untrusted executable_changed public_key_required authentication_failed callback_port_in_use callback_unavailable callback_timeout callback_rejected oauth_denied oauth_failed browser_open_failed interrupted identity_unverified profile_required mfa_unsupported owner_required no_eligible_owner_projects project_unavailable project_selection_unavailable request_failed response_invalid response_limit signout_unconfirmed configuration_unreadable configuration_conflict configuration_changed configuration_home_mismatch configuration_location_untrusted installation_unconfirmed removal_unconfirmed recovery_invalid recovery_unavailable existing_connection_recover_first connector_busy_or_stale_lock enablement_unconfirmed issuance_unconfirmed token_invalid cleanup_unconfirmed no_managed_connections client_command_failed client_command_timeout client_response_limit client_launch_failed client_exit_failed verification_initialization_failed verification_discovery_failed verification_connection_status_failed verification_project_scope_failed`.split(' '));
+export function safeCode(error) {
+    if (error instanceof ConnectorError && ['copilot_runtime_unverified', 'copilot_process_unconfirmed'].includes(error.code))
+        return error.code;
+    if (error instanceof ConnectorError && error.code === 'vscode_process_unconfirmed')
+        return error.code;
+    if (error instanceof ConnectorError && codes.has(error.code))
+        return error.code;
+    if (error instanceof Error && error.message === 'connector_busy_or_stale_lock')
+        return error.message;
+    return 'operation_failed';
+}
+export async function main(args = process.argv.slice(2)) {
+    // SDK diagnostics must never leak credential-bearing error objects. Only
+    // our fixed messages go to stdout. The foreground client owns its terminal.
+    const previousConsole = { ...console };
+    for (const name of ['log', 'warn', 'error', 'debug', 'info'])
+        console[name] = () => { };
+    let prompt;
+    let unlock;
+    const stop = new AbortController();
+    const interrupt = () => stop.abort();
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', interrupt);
+    try {
+        const options = parseArgs(args);
+        if (options.command === 'help') {
+            process.stdout.write(help + '\n');
+            return;
+        }
+        const ui = {
+            say(message) { process.stdout.write(message + '\n'); },
+            async confirm(message) {
+                requireValue(process.stdin.isTTY && process.stdout.isTTY, 'usage');
+                requireValue(!stop.signal.aborted, 'interrupted');
+                prompt ??= createInterface({ input: process.stdin, output: process.stdout });
+                return (await prompt.question(message + ' [y/N] ', { signal: stop.signal })).trim().toLowerCase() === 'y';
+            },
+            async choose(message, choices) {
+                requireValue(process.stdin.isTTY && process.stdout.isTTY, 'usage');
+                requireValue(!stop.signal.aborted, 'interrupted');
+                ui.say(message + '\n' + choices.map((choice, index) => `${index + 1}. ${display(choice)}`).join('\n'));
+                prompt ??= createInterface({ input: process.stdin, output: process.stdout });
+                const input = (await prompt.question('Selection (no default): ', { signal: stop.signal })).trim();
+                requireValue(/^[1-9][0-9]*$/.test(input) && Number(input) <= choices.length, 'usage');
+                return Number(input) - 1;
+            },
+        };
+        const client = options.client ?? ['codex', 'gemini', 'claude', 'vscode', 'vscode-copilot'][await ui.choose('Select a client (see validation limits)', ['Codex CLI (MVP-supported candidate)', 'Gemini CLI (experimental; hosted validation deferred)', 'Claude Code (experimental; hosted validation deferred)', 'VS Code Local (experimental; manual activation)', 'VS Code Copilot (experimental; hosted reads passed; connect guarded)'])];
+        const paths = await locations(process.env, client);
+        const copilotControls = {
+            report: ui.say,
+            async requestDisconnect(signal) {
+                requireValue(process.stdin.isTTY && process.stdout.isTTY, 'usage');
+                prompt ??= createInterface({ input: process.stdin, output: process.stdout });
+                while (!signal.aborted) {
+                    const input = await prompt.question('Type disconnect to revoke TrackQA access: ', { signal });
+                    if (input.trim().toLowerCase() === 'disconnect')
+                        return;
+                    ui.say('Enter disconnect to end TrackQA access. No input is logged.');
+                }
+                throw new ConnectorError('interrupted');
+            },
+        };
+        let copilotHome = paths.vscodeCopilotHome;
+        if (client === 'vscode-copilot') {
+            const records = (await paths.store.read()).filter(row => row.client === client && (!options.projectId || row.projectId === options.projectId));
+            if (options.command === 'connect') {
+                requireValue(!(await paths.store.read()).some(row => row.client === client), 'existing_connection_recover_first');
+                copilotHome = freshCopilotHome(paths.vscodeCopilotHome);
+            }
+            else if (options.command === 'status') {
+                const exe = await detectVSCode(options.executable);
+                if (!records.length) {
+                    await status(paths.store, vscodeCopilotAdapter(exe, copilotHome, copilotControls), ui, options.projectId);
+                    return;
+                }
+                for (const record of records)
+                    await status(paths.store, vscodeCopilotAdapter(exe, copilotRecoveryHome(paths.vscodeCopilotHome, recordHome(record)), copilotControls), ui, record.projectId);
+                return;
+            }
+            else {
+                requireValue(records.length, 'no_managed_connections');
+                const record = records.length === 1 ? records[0] : records[await ui.choose('Choose a connection to remove', records.map(row => row.projectId))];
+                options.projectId = record.projectId;
+                copilotHome = copilotRecoveryHome(paths.vscodeCopilotHome, recordHome(record));
+            }
+        }
+        const adapter = client === 'vscode-copilot'
+            ? vscodeCopilotAdapter(await detectVSCode(options.executable), copilotHome, copilotControls)
+            : client === 'vscode'
+                ? vscodeAdapter(await detectVSCode(options.executable), paths.vscodeHome)
+                : client === 'claude'
+                    ? claudeAdapter(await detectClaude(options.executable), paths.claudeHome, process.env, options.claudeOnly)
+                    : client === 'gemini'
+                        ? geminiAdapter(await detectGemini(options.executable), paths.geminiHome)
+                        : codexAdapter(await detectCodex(paths.codexHome, options.executable), paths.codexHome);
+        const executable = adapter.executable;
+        const label = adapterLabel(adapter);
+        if (options.command === 'connect')
+            requireValue(executable.foregroundMode !== 'unsupported', 'client_foreground_unsupported');
+        ui.say(`${label} detected: ${executable.version}. Recovery metadata: ${display(paths.store.root)}`);
+        if (options.command === 'connect')
+            ui.say(client === 'vscode-copilot'
+                ? 'Copilot hosted read-only acceptance passed through the fixture-pinned test entry. Ordinary connect remains guarded; no Owner sign-in or issuance is authorized here.'
+                : client === 'vscode'
+                    ? 'Isolated VS Code Local window; native MCP activation is manual. Close the entire isolated instance for cleanup. Do not use Copilot or provider harnesses. No model account authentication is automated.'
+                    : `Foreground launch: ${executable.foregroundMode === 'no-daemon' ? '--no-daemon (supported by this executable; no shared background server)' : 'direct (no --no-daemon flag advertised; interactive startup is not preverified)'}.`);
+        if (options.command === 'status') {
+            await status(paths.store, adapter, ui, options.projectId);
+            return;
+        }
+        requireValue(process.platform === 'win32', 'client_unsupported');
+        if (options.command === 'connect')
+            await adapter.prepare?.();
+        unlock = await paths.store.lock();
+        const authenticate = async (action) => {
+            requireValue(!stop.signal.aborted, 'interrupted');
+            ui.say('Complete Google sign-in in your system browser. No password or token will be requested in this terminal.');
+            return withOwner({ key: await publicKey(), signal: stop.signal }, action);
+        };
+        if (options.command === 'connect') {
+            if (!await ui.confirm('Continue with Google Owner sign-in?'))
+                return;
+            await authenticate(owner => connect({ owner, adapter, store: paths.store, ui: {
+                    ...ui,
+                    // Close readline before handing stdin to the foreground TUI, otherwise
+                    // it may consume Codex keystrokes. Future prompts reopen it as needed.
+                    say(message) { if (/^Launching (?:Codex|Gemini|Claude Code|VS Code Local)\./.test(message)) {
+                        prompt?.close();
+                        prompt = undefined;
+                    } ui.say(message); },
+                }, projectId: options.projectId, signal: stop.signal }));
+        }
+        else {
+            await disconnect(paths.store, adapter, ui, async (action) => { await authenticate(action); }, options.projectId);
+        }
+    }
+    catch (error) {
+        process.exitCode = 1;
+        const code = stop.signal.aborted ? 'interrupted' : safeCode(error);
+        if (code === 'copilot_runtime_unverified')
+            process.stdout.write('Copilot hosted read-only acceptance passed in the fixture-pinned test. Ordinary connect remains guarded. Launch, Owner authentication and issuance remain blocked here.\n');
+        process.stdout.write(`TrackQA connector stopped: ${code}. No credentials are included in this diagnostic.\n`);
+        if (code === 'cleanup_unconfirmed' || code === 'interrupted')
+            process.stdout.write('Run status and disconnect to inspect nonsecret recovery metadata. An Owner can revoke access in Project Settings > AI Integrations > Manage Connections. Do not assume remote access was removed.\n');
+        if (code === 'configuration_changed')
+            process.stdout.write('The client entry changed after installation. It was preserved. Review only that server entry before removing it manually.\n');
+        if (code === 'vscode_process_unconfirmed')
+            process.stdout.write('VS Code process termination is unconfirmed. Close only the TrackQA Local instance, then run disconnect --client vscode using the same project. Keep process.json and recovery metadata; do not delete them to bypass the check. New unrelated Code processes can also require a conservative refusal. No process was force-killed.\n');
+        if (code === 'configuration_busy')
+            process.stdout.write('Settings are locked by another writer or a stale .trackqa-settings.lock. Close other configuration writers. Remove only a stale lock after confirming its recorded helper PID has exited.\n');
+        if (code === 'configuration_write_failed' || code === 'configuration_write_uncertain')
+            process.stdout.write('Settings replacement failed or its outcome is uncertain. Do not retry automatically. Inspect settings.json and any .trackqa-settings-recovery-*.bak in the selected Gemini home; preserve recovery metadata and compare/merge before restoring anything.\n');
+        if (code === 'client_not_found')
+            process.stdout.write('Selected client was not found in supported installation locations. No installation was attempted. For Gemini supply the existing @google/gemini-cli bin with --gemini-path; agy.exe is not Gemini CLI.\n');
+        if (code === 'client_not_found' && args.includes('claude'))
+            process.stdout.write('Claude Code requires an independently installed native Windows claude.exe; npm shims and Desktop are not selected. Use --claude-path for an existing supported native installation. No login or installation was attempted.\n');
+        if (code === 'gemini_compatibility_unverified')
+            process.stdout.write('Gemini capability or isolated JSON editor checks failed. Native add/remove are never used on real settings. No Owner sign-in or token issuance was attempted.\n');
+        if (code === 'gemini_auto_update_enabled')
+            process.stdout.write('Disable general.enableAutoUpdate using Gemini settings before this connector launches it. Workspace/system overrides must not re-enable it. The connector did not change your preferences or upgrade the client.\n');
+        if (code === 'client_foreground_unsupported')
+            process.stdout.write('This executable supports MCP configuration but has no verified interactive foreground launch mode. Select an existing complete Codex CLI using --codex-path. No installation or interactive retry was attempted; status/disconnect remain available.\n');
+        if (code === 'client_launch_failed' || code === 'client_exit_failed')
+            process.stdout.write('Client foreground startup or exit failed; MCP verification is separate from TUI availability. Review the client diagnostic above and the cleanup result. No automatic relaunch was attempted.\n');
+        if (code === 'connector_busy_or_stale_lock')
+            process.stdout.write('Another session may be running. Inspect connector.lock in the displayed recovery folder. Remove only that lock after independently confirming its recorded process has exited.\n');
+    }
+    finally {
+        prompt?.close();
+        try {
+            await unlock?.();
+        }
+        catch {
+            process.exitCode = 1;
+            process.stdout.write('Recovery lock cleanup unconfirmed; inspect nonsecret connector.lock before another attempt.\n');
+        }
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', interrupt);
+        Object.assign(console, previousConsole);
+    }
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    await main();

package/dist/tools/trackqa-connect/src/clients/adapter.js

@@ -0,0 +1,3 @@
+export const adapterClient = (adapter) => adapter.client ?? 'codex';
+export const adapterHome = (adapter) => adapter.configurationHome ?? adapter.codexHome;
+export const adapterLabel = (adapter) => adapter.label ?? 'Codex';

package/dist/tools/trackqa-connect/src/clients/claude-session.js

@@ -0,0 +1,78 @@
+import { lstat, mkdir, open, realpath, rmdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { ConnectorError, requireValue, setupFor, UUID } from "../core.js";
+import { fingerprint } from "./codex.js";
+import { commitWindowsSettings } from "./gemini-windows.js";
+// Reuse the existing private Windows file writer, not Gemini's settings editor.
+// These files live only in the connector recovery directory, never Claude's home.
+export const claudeEntry = (setup) => ({ type: 'http', url: setup.endpoint, headers: { Authorization: `Bearer \${${setup.envVar}}` } });
+export function claudeSessionPath(home, setup) {
+    requireValue(path.isAbsolute(home) && UUID.test(setup.projectId)
+        && fingerprint(setup) === fingerprint(setupFor(setup.projectId, 'claude')), 'configuration_location_untrusted');
+    return path.join(home, setup.projectId, 'settings.json');
+}
+const payload = (setup) => Buffer.from(JSON.stringify({ mcpServers: { [setup.serverName]: claudeEntry(setup) } }, null, 2) + '\n');
+export const matchesClaudeEntry = (value, setup) => !!value && fingerprint(value) === fingerprint(claudeEntry(setup));
+async function directory(home, setup, create = false) {
+    const file = claudeSessionPath(home, setup);
+    for (const dir of [home, path.dirname(file)]) {
+        if (create)
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+        try {
+            const info = await lstat(dir);
+            requireValue(info.isDirectory() && !info.isSymbolicLink()
+                && (await realpath(dir)).toLowerCase() === path.resolve(dir).toLowerCase(), 'configuration_location_untrusted');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return file;
+}
+export async function readClaudeSession(home, setup) {
+    const file = await directory(home, setup);
+    try {
+        const info = await lstat(file);
+        requireValue(info.isFile() && !info.isSymbolicLink() && info.nlink === 1 && info.size <= 4096, 'configuration_changed');
+        const handle = await open(file, 'r');
+        try {
+            const actual = await handle.stat();
+            requireValue(actual.ino === info.ino && actual.dev === info.dev && actual.size === info.size, 'configuration_changed');
+            const bytes = await handle.readFile();
+            // Exact connector-generated bytes only: no additional servers, JSONC,
+            // duplicate keys, credentials or externally changed entries are accepted.
+            requireValue(bytes.equals(payload(setup)), 'configuration_changed');
+            return claudeEntry(setup);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        if (error instanceof ConnectorError)
+            throw error;
+        throw new ConnectorError('configuration_unreadable');
+    }
+}
+export async function installClaudeSession(home, setup, commit = commitWindowsSettings) {
+    requireValue(await readClaudeSession(home, setup) === null, 'configuration_conflict');
+    const file = await directory(home, setup, true);
+    await commit(file, { exists: false, hash: null }, payload(setup));
+    requireValue(await readClaudeSession(home, setup) !== null, 'installation_unconfirmed');
+    return fingerprint(claudeEntry(setup));
+}
+export async function removeClaudeSession(home, setup, hash) {
+    const entry = await readClaudeSession(home, setup);
+    if (entry === null)
+        return;
+    // A crash after file creation but before journal acknowledgement is recoverable
+    // from the exact token-free payload in this owned, project-specific location.
+    requireValue(hash === null || fingerprint(entry) === hash, 'configuration_changed');
+    const file = claudeSessionPath(home, setup);
+    await unlink(file);
+    await rmdir(path.dirname(file)); // Never recursively delete an unexpected file.
+    requireValue(await readClaudeSession(home, setup) === null, 'removal_unconfirmed');
+}

package/dist/tools/trackqa-connect/src/clients/claude.js

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { capture, foreground } from "../process.js";
+import { ConnectorError, requireValue, TOKEN, tools } from "../core.js";
+import { commitWindowsSettings } from "./gemini-windows.js";
+import { claudeSessionPath, installClaudeSession, matchesClaudeEntry, readClaudeSession, removeClaudeSession } from "./claude-session.js";
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function trustedClaudeLocation(file, home = os.homedir(), platform = process.platform, cwd = process.cwd()) {
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    if (!paths.isAbsolute(file) || paths.basename(file).toLowerCase() !== 'claude.exe' || platform !== 'win32')
+        return false;
+    const within = (root) => paths.resolve(file).toLowerCase().startsWith(paths.resolve(root).toLowerCase() + paths.sep);
+    if (within(cwd) || paths.resolve(file).toLowerCase() === paths.resolve(cwd).toLowerCase())
+        return false;
+    const programFiles = process.env.ProgramFiles ?? 'C:\\Program Files';
+    return [paths.join(home, '.local', 'bin'), paths.join(home, '.local', 'share', 'claude', 'versions'),
+        paths.join(programFiles, 'ClaudeCode')].some(within)
+        || (within(paths.join(programFiles, 'WinGet', 'Packages'))
+            && /^Anthropic\.ClaudeCode_[A-Za-z0-9._-]+[\\/]/.test(paths.relative(paths.join(programFiles, 'WinGet', 'Packages'), file)));
+}
+export async function checkClaudeExecutable(file) {
+    requireValue(trustedClaudeLocation(file), 'executable_untrusted');
+    const canonical = await realpath(file);
+    requireValue(trustedClaudeLocation(canonical), 'executable_untrusted');
+    const info = await lstat(canonical);
+    requireValue(info.isFile() && !info.isSymbolicLink(), 'executable_untrusted');
+    return { path: canonical, sha256: sha(await readFile(canonical)) };
+}
+export function claudeEnvironment(source = process.env) {
+    const env = { DISABLE_AUTOUPDATER: '1', DISABLE_UPDATES: '1' };
+    for (const key of ['PATH', 'PATHEXT', 'SystemRoot', 'SystemDrive', 'WINDIR', 'COMSPEC', 'USERPROFILE', 'HOME', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP',
+        'TERM', 'COLORTERM', 'LANG', 'LC_ALL', 'HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy', 'NO_PROXY', 'no_proxy',
+        'NODE_USE_SYSTEM_CA', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'CLAUDE_CONFIG_DIR', 'CLAUDE_CODE_GIT_BASH_PATH']) {
+        if (source[key] !== undefined)
+            env[key] = source[key];
+    }
+    // Claude manages its own account cache. No ambient provider keys, Owner Auth,
+    // MCP tokens, debug destinations, NODE_OPTIONS or TLS-disable settings pass.
+    return env;
+}
+export async function detectClaude(explicit, source = process.env, run = capture, inspect = checkClaudeExecutable) {
+    const candidates = explicit ? [explicit] : [...new Set([
+            path.join(os.homedir(), '.local', 'bin', 'claude.exe'),
+            ...(source.PATH ?? '').split(path.delimiter).filter(folder => path.isAbsolute(folder)).map(folder => path.join(folder, 'claude.exe')),
+        ])];
+    let incompatible = false;
+    for (const candidate of candidates) {
+        let exe;
+        try {
+            exe = await inspect(candidate);
+        }
+        catch {
+            if (explicit)
+                throw new ConnectorError('executable_untrusted');
+            continue;
+        }
+        // Help/version only, private disposable config, no native add/remove or login.
+        const root = await mkdtemp(path.join(os.tmpdir(), 'trackqa-claude-probe-'));
+        try {
+            const env = { ...claudeEnvironment(source), CLAUDE_CONFIG_DIR: root };
+            const version = /^(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)\s+\(Claude Code\)$/.exec((await run(exe.path, ['--version'], env, undefined, root)).trim())?.[1];
+            requireValue(version, 'client_unsupported');
+            const help = await run(exe.path, ['--help'], env, undefined, root);
+            requireValue(help.includes('--mcp-config'), 'client_unsupported');
+            requireValue(sha(await readFile(exe.path)) === exe.sha256, 'executable_changed');
+            return { ...exe, version, appServer: false, foregroundMode: 'direct', strictMcp: help.includes('--strict-mcp-config') };
+        }
+        catch (error) {
+            if (explicit || (error instanceof ConnectorError && error.code === 'executable_changed'))
+                throw error;
+            incompatible = true;
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    }
+    throw new ConnectorError(incompatible ? 'client_unsupported' : 'client_not_found');
+}
+export const claudeLaunchArgs = (file, strict = false) => ['--mcp-config', file, ...(strict ? ['--strict-mcp-config'] : [])];
+export const claudeVerification = () => ({ authorized: null, verified: false, code: 'manual_verification_required' });
+export function claudeInstructions(setup) {
+    return `Claude Code native header expansion, discovery and authenticated reads are not yet verified. Claude account sign-in is separate from TrackQA. Use /mcp to check this server and exactly these five tools: ${tools.join(', ')}. Call only trackqa_connection_status and trackqa_list_projects; confirm only project ${setup.projectId}. Do not submit a finding. Exit with /exit for revocation and cleanup. Manual observations do not change the connector's unverified result.`;
+}
+export function claudeAdapter(exe, sessionHome, source = process.env, strict = false, launchForeground = foreground, commit = commitWindowsSettings) {
+    requireValue(!strict || exe.strictMcp, 'client_unsupported');
+    const entry = (setup) => readClaudeSession(sessionHome, setup);
+    const integrity = async () => requireValue(await realpath(exe.path) === exe.path && sha(await readFile(exe.path)) === exe.sha256, 'executable_changed');
+    return {
+        client: 'claude', label: 'Claude Code', configurationHome: sessionHome, executable: exe, entry, matches: matchesClaudeEntry,
+        installPreview: setup => `Session-only private token-free file: ${claudeSessionPath(sessionHome, setup)}; --mcp-config${strict ? ' --strict-mcp-config (explicit TrackQA-only session: excludes other configured MCP servers for this session)' : ' (other MCP configuration is preserved and may also load)'}`,
+        manualInstructions: claudeInstructions,
+        async install(setup) { await integrity(); return installClaudeSession(sessionHome, setup, commit); },
+        async remove(setup, hash) { await removeClaudeSession(sessionHome, setup, hash); },
+        async verify() { return claudeVerification(); },
+        async launch(setup, token, signal) {
+            requireValue(TOKEN.test(token), 'token_invalid');
+            requireValue(await entry(setup) !== null, 'configuration_changed');
+            await integrity();
+            const env = { ...claudeEnvironment(source), [setup.envVar]: token };
+            token = '';
+            try {
+                const running = launchForeground(exe.path, env, signal, undefined, claudeLaunchArgs(claudeSessionPath(sessionHome, setup), strict));
+                delete env[setup.envVar];
+                await running;
+            }
+            finally {
+                delete env[setup.envVar];
+            }
+        },
+    };
+}