trackqa 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,249 @@
+import { readFile, realpath, lstat, mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+import { capture, foreground } from "../process.js";
+import { ConnectorError, requireValue, TOKEN } from "../core.js";
+import { fingerprint } from "./codex.js";
+import { geminiInstructions, geminiVerification } from "./gemini-verify.js";
+import { editGeminiSettings, readGeminiSettings, parseGeminiSettings, geminiHeader, matchesGeminiEntry } from "./gemini-config.js";
+export { geminiHeader, matchesGeminiEntry } from "./gemini-config.js";
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+export function trustedGeminiLocation(file, home = os.homedir(), platform = process.platform, cwd = process.cwd()) {
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    if (!paths.isAbsolute(file))
+        return false;
+    const normalized = paths.resolve(file).toLowerCase();
+    const inside = (root) => normalized.startsWith(paths.resolve(root).toLowerCase() + paths.sep);
+    if (inside(cwd) || normalized === paths.resolve(cwd).toLowerCase())
+        return false;
+    const roots = platform === 'win32' ? [paths.join(home, 'AppData', 'Roaming', 'npm', 'node_modules', '@google', 'gemini-cli'),
+        paths.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'nodejs', 'node_modules', '@google', 'gemini-cli')]
+        : ['/usr/local/lib/node_modules/@google/gemini-cli', '/usr/lib/node_modules/@google/gemini-cli'];
+    return roots.some(root => inside(root)) && paths.basename(file).toLowerCase().endsWith('.js');
+}
+export async function checkGeminiInstallation(file) {
+    requireValue(trustedGeminiLocation(file), 'executable_untrusted');
+    const canonical = await realpath(file);
+    requireValue(path.resolve(canonical).toLowerCase() === path.resolve(file).toLowerCase() && trustedGeminiLocation(canonical), 'executable_untrusted');
+    let root = path.dirname(canonical), packageFile = '';
+    // The package metadata must identify this exact executable as its gemini bin.
+    for (let i = 0; i < 4; i++, root = path.dirname(root)) {
+        const candidate = path.join(root, 'package.json');
+        try {
+            if (JSON.parse(await readFile(candidate, 'utf8')).name === '@google/gemini-cli') {
+                packageFile = candidate;
+                break;
+            }
+        }
+        catch { /* Keep looking within the allowed root. */ }
+    }
+    requireValue(packageFile, 'client_unsupported');
+    const bytes = await readFile(packageFile), metadata = JSON.parse(bytes.toString('utf8'));
+    const bin = typeof metadata.bin === 'string' ? metadata.bin : metadata.bin?.gemini;
+    requireValue(typeof bin === 'string' && path.resolve(path.dirname(packageFile), bin).toLowerCase() === canonical.toLowerCase()
+        && /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(metadata.version), 'client_unsupported');
+    const nodePath = await realpath(process.execPath);
+    return { path: canonical, sha256: sha(await readFile(canonical)), version: metadata.version, nodePath,
+        nodeHash: sha(await readFile(nodePath)), packageFile, packageHash: sha(bytes), appServer: false, foregroundMode: 'direct' };
+}
+const networkVariables = ['HTTP_PROXY', 'http_proxy', 'HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy', 'NO_PROXY', 'no_proxy', 'NODE_USE_SYSTEM_CA'];
+export function inheritGeminiNetworkEnvironment(child, source) {
+    const env = { ...child };
+    for (const key of networkVariables) {
+        const configured = Object.keys(env).some(name => process.platform === 'win32' ? name.toLowerCase() === key.toLowerCase() : name === key);
+        if (!configured && Object.hasOwn(source, key) && source[key] !== undefined)
+            env[key] = source[key];
+    }
+    return env;
+}
+export function geminiEnvironment(home, source = process.env, interactive = false) {
+    const env = { GEMINI_CLI_HOME: home, NO_COLOR: '1', GEMINI_TELEMETRY_ENABLED: 'false', GEMINI_TELEMETRY_TRACES_ENABLED: 'false' };
+    for (const key of ['PATH', 'PATHEXT', 'SystemRoot', 'WINDIR', 'COMSPEC', 'USERPROFILE', 'HOME', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'TERM', 'COLORTERM', 'LANG', 'LC_ALL'])
+        if (source[key])
+            env[key] = source[key];
+    // Preserve administrator policy overrides, but never ambient MCP tokens,
+    // NODE_OPTIONS/preloads, Supabase credentials or editor attachment variables.
+    for (const key of ['GEMINI_CLI_SYSTEM_SETTINGS_PATH', 'GEMINI_CLI_SYSTEM_DEFAULTS_PATH'])
+        if (source[key])
+            env[key] = source[key];
+    if (interactive)
+        for (const key of ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_CLOUD_PROJECT', 'GOOGLE_CLOUD_LOCATION', 'GOOGLE_APPLICATION_CREDENTIALS'])
+            if (source[key])
+                env[key] = source[key];
+    // Proxy URLs may contain credentials. Keep them only in the child environment;
+    // never log/serialize them or relax TLS verification to accommodate a proxy.
+    return inheritGeminiNetworkEnvironment(env, source);
+}
+async function assertIntegrity(exe) {
+    for (const [file, hash] of [[exe.path, exe.sha256], [exe.nodePath, exe.nodeHash], [exe.packageFile, exe.packageHash]]) {
+        requireValue(await realpath(file) === file && sha(await readFile(file)) === hash, 'executable_changed');
+    }
+}
+async function invoke(exe, args, env, run, cwd) {
+    await assertIntegrity(exe);
+    // Execute the real npm package bin with the existing Node runtime. Never run
+    // a .cmd/.ps1 wrapper through a shell or confuse agy.exe with Gemini CLI.
+    return run(exe.nodePath, [exe.path, ...args], env, undefined, cwd);
+}
+async function settings(home) {
+    return readGeminiSettings(home);
+}
+async function readSettingsFile(file) {
+    try {
+        const info = await lstat(file);
+        requireValue(info.isFile() && !info.isSymbolicLink() && info.size <= 1_048_576, 'configuration_unreadable');
+        const value = parseGeminiSettings(await readFile(file));
+        requireValue(object(value) && (value.mcpServers === undefined || object(value.mcpServers)), 'configuration_unreadable');
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw new ConnectorError('configuration_unreadable');
+    }
+}
+// Gemini documents auto-update as enabled by default. Do not let launching the
+// user's client implicitly upgrade it. No preferences are changed here. Be
+// conservative about workspace/system overrides rather than guessing precedence.
+export async function assertNoAutoUpdate(home, source = process.env, cwd = process.cwd()) {
+    const user = await settings(home);
+    requireValue(object(user.general) && user.general.enableAutoUpdate === false, 'gemini_auto_update_enabled');
+    const system = await readSettingsFile(source.GEMINI_CLI_SYSTEM_SETTINGS_PATH ?? 'C:\\ProgramData\\gemini-cli\\settings.json');
+    const layers = [system];
+    for (let dir = path.resolve(cwd);; dir = path.dirname(dir)) {
+        layers.push(await settings(dir));
+        if (path.dirname(dir) === dir)
+            break;
+    }
+    for (const layer of layers)
+        if (object(layer.general) && layer.general.enableAutoUpdate !== undefined) {
+            requireValue(layer.general.enableAutoUpdate === false, 'gemini_auto_update_enabled');
+        }
+}
+const servers = (value) => (value.mcpServers ?? {});
+export function geminiAddArgs(setup) {
+    return ['mcp', 'add', '--scope', 'user', '--transport', 'http', '--header', `Authorization: ${geminiHeader(setup)}`, setup.serverName, setup.endpoint];
+}
+export const geminiRemoveArgs = (name) => ['mcp', 'remove', '--scope', 'user', name];
+function withoutEntry(value, name) {
+    const rest = { ...servers(value) };
+    delete rest[name];
+    const base = { ...value };
+    delete base.mcpServers;
+    return { ...base, ...(Object.keys(rest).length ? { mcpServers: rest } : {}) };
+}
+// Native behavior and raw-editor safety are measured independently. Native
+// mutation remains confined to this disposable home even if it appears safe.
+export async function probeGemini(exe, run = capture) {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'trackqa-gemini-probe-'));
+    const workspace = path.join(root, 'workspace');
+    try {
+        await mkdir(path.join(root, '.gemini'));
+        await mkdir(workspace);
+        const original = { general: { enableAutoUpdate: false }, ui: { theme: 'Default' }, mcpServers: { unrelated: { httpUrl: 'https://example.invalid/mcp', headers: { Authorization: 'Bearer ${UNRELATED_TOKEN}' } } } };
+        await writeFile(path.join(root, '.gemini', 'settings.json'), JSON.stringify(original));
+        // Nonexistent overrides avoid loading real system settings without trying
+        // to impersonate administrator-owned policy files in a user-writable temp.
+        // The temporary user settings above explicitly disable auto-update.
+        const empty = path.join(root, 'absent-system.json');
+        const env = { ...geminiEnvironment(root), HOME: root, USERPROFILE: root, UNRELATED_TOKEN: 'compatibility-sentinel-not-a-credential', GEMINI_CLI_SYSTEM_SETTINGS_PATH: empty, GEMINI_CLI_SYSTEM_DEFAULTS_PATH: empty };
+        const command = (args) => invoke(exe, args, env, run, workspace);
+        const version = (await command(['--version'])).trim();
+        requireValue(version === exe.version, 'client_unsupported');
+        for (const [args, flags] of [[['mcp', 'add', '--help'], ['--scope', '--transport', '--header']], [['mcp', 'remove', '--help'], ['--scope']], [['mcp', 'list', '--help'], ['list']]]) {
+            const help = await command(args);
+            requireValue(flags.every(flag => help.includes(flag)), 'client_unsupported');
+        }
+        const setup = { projectId: '11111111-1111-4111-8111-111111111111', serverName: 'trackqa_compatibility_probe', envVar: 'TRACKQA_PROBE_TOKEN', endpoint: 'https://example.invalid/mcp' };
+        await command(geminiAddArgs(setup));
+        const installed = await settings(root);
+        requireValue(matchesGeminiEntry(servers(installed)[setup.serverName], setup), 'client_unsupported');
+        const nativeAddPreservesUnrelated = fingerprint(withoutEntry(installed, setup.serverName)) === fingerprint(original);
+        await command(geminiRemoveArgs(setup.serverName));
+        const removed = await settings(root);
+        requireValue(!Object.hasOwn(servers(removed), setup.serverName), 'client_unsupported');
+        const nativeRemovePreservesUnrelated = fingerprint(removed) === fingerprint(withoutEntry(installed, setup.serverName));
+        const rawHome = path.join(root, 'raw-editor');
+        await mkdir(path.join(rawHome, '.gemini'), { recursive: true });
+        await writeFile(path.join(rawHome, '.gemini', 'settings.json'), JSON.stringify(original));
+        const hash = await editGeminiSettings(rawHome, setup, 'install');
+        const rawInstalled = await settings(rawHome);
+        requireValue(matchesGeminiEntry(servers(rawInstalled)[setup.serverName], setup)
+            && fingerprint(withoutEntry(rawInstalled, setup.serverName)) === fingerprint(original), 'installation_unconfirmed');
+        await editGeminiSettings(rawHome, setup, 'remove', hash);
+        requireValue(fingerprint(await settings(rawHome)) === fingerprint(original), 'removal_unconfirmed');
+        return { nativeAddPreservesUnrelated, nativeRemovePreservesUnrelated, generatedHttpEntry: true, literalHeader: true, rawEditorPreservesUnrelated: true, rawEditorRemoval: true };
+    }
+    catch (error) {
+        if (error instanceof ConnectorError && error.code === 'executable_changed')
+            throw error;
+        throw new ConnectorError('gemini_compatibility_unverified');
+    }
+    finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+export async function detectGemini(explicit, source = process.env, run = capture, inspect = checkGeminiInstallation) {
+    const prefixes = [...new Set([...(source.PATH ?? '').split(path.delimiter), source.APPDATA ? path.join(source.APPDATA, 'npm') : '', path.join(source.ProgramFiles ?? 'C:\\Program Files', 'nodejs')])].filter(folder => path.isAbsolute(folder));
+    const candidates = explicit ? [explicit] : prefixes.map(folder => path.join(folder, 'node_modules', '@google', 'gemini-cli', 'dist', 'index.js'));
+    let incompatible = false;
+    for (const file of candidates) {
+        let exe;
+        try {
+            exe = await inspect(file);
+        }
+        catch (error) {
+            if (explicit)
+                throw error instanceof ConnectorError ? error : new ConnectorError('executable_untrusted');
+            if (error instanceof ConnectorError && error.code === 'client_unsupported')
+                incompatible = true;
+            continue;
+        }
+        try {
+            return { ...exe, capabilities: await probeGemini(exe, run) };
+        }
+        catch (error) {
+            if (explicit || (error instanceof ConnectorError && error.code === 'executable_changed'))
+                throw error;
+            incompatible = true;
+        }
+    }
+    throw new ConnectorError(incompatible ? 'gemini_compatibility_unverified' : 'client_not_found');
+}
+export function geminiAdapter(exe, home, run = capture, source = process.env, launchForeground = foreground) {
+    // Retain the injected runner for the detection/probe API, never user writes.
+    void run;
+    const entry = async (setup) => servers(await settings(home))[setup.serverName] ?? null;
+    return {
+        client: 'gemini', label: 'Gemini', configurationHome: home, executable: exe, entry, matches: matchesGeminiEntry,
+        installPreview: () => 'Scoped user settings JSON editor; private flushed temporary file and Windows replacement; no native add/remove on real settings',
+        manualInstructions: geminiInstructions,
+        async prepare() { await assertNoAutoUpdate(home, source); },
+        async install(setup) {
+            await assertIntegrity(exe);
+            return (await editGeminiSettings(home, setup, 'install'));
+        },
+        async remove(setup, hash) {
+            await editGeminiSettings(home, setup, 'remove', hash);
+        },
+        async verify() { return geminiVerification(); },
+        async launch(setup, token, signal) {
+            requireValue(TOKEN.test(token), 'token_invalid');
+            await assertNoAutoUpdate(home, source);
+            requireValue(matchesGeminiEntry(await entry(setup), setup), 'configuration_changed');
+            await assertIntegrity(exe);
+            const childEnv = { ...geminiEnvironment(home, source, true), [setup.envVar]: token };
+            token = '';
+            try {
+                const running = launchForeground(exe.nodePath, childEnv, signal, undefined, [exe.path]);
+                delete childEnv[setup.envVar];
+                await running;
+            }
+            finally {
+                delete childEnv[setup.envVar];
+            }
+        },
+    };
+}

package/dist/tools/trackqa-connect/src/clients/vscode-copilot-lifecycle.js

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { ConnectorError, requireValue, TOKEN } from "../core.js";
+import { copilotEnvironment, copilotLaunchArgs } from "./vscode-copilot.js";
+import { copilotPaths, copilotPayloads, readCopilotSession } from "./vscode-copilot-session.js";
+import { readVSCodeFile, safeVSCodeDirectory, writeVSCodeFile } from "./vscode-session.js";
+async function verify(exe) {
+    requireValue(!await lstat(path.join(exe.installation, 'data')).catch(e => { if (e.code === 'ENOENT')
+        return null; throw e; }), 'executable_untrusted');
+    for (const input of [{ path: exe.path, sha256: exe.sha256 }, ...exe.inputs]) {
+        requireValue(input.path.toLowerCase().startsWith(path.resolve(exe.installation).toLowerCase() + path.sep), 'executable_untrusted');
+        await safeVSCodeDirectory(path.dirname(input.path));
+        const stat = await lstat(input.path);
+        requireValue(stat.isFile() && !stat.isSymbolicLink() && (await realpath(input.path)).toLowerCase() === input.path.toLowerCase()
+            && createHash('sha256').update(await readFile(input.path)).digest('hex') === input.sha256, 'executable_changed');
+    }
+}
+export const copilotRuntime = { spawn, verify };
+export async function startCopilotSession(exe, home, setup, options = {}) {
+    const files = copilotPaths(home, setup);
+    const mode = options.credential === undefined ? 'token-free' : 'session';
+    requireValue(!options.signal?.aborted, 'interrupted');
+    requireValue(options.credential === undefined || TOKEN.test(options.credential), 'token_invalid');
+    requireValue(await readCopilotSession(home, setup, mode), 'configuration_changed');
+    return startPreparedCopilotSession(exe, {
+        files, settings: copilotPayloads(setup, mode).settings, args: copilotLaunchArgs(home, setup),
+        env: copilotEnvironment(home, setup, options.source), envVar: setup.envVar,
+    }, options);
+}
+// Shared process primitive, called only after the production or separate local
+// test validator has verified configuration ownership and expected bytes.
+export async function startPreparedCopilotSession(exe, profile, options = {}) {
+    const runtime = options.runtime ?? copilotRuntime, { files } = profile;
+    requireValue(!options.signal?.aborted, 'interrupted');
+    requireValue((await readVSCodeFile(files.settings))?.equals(profile.settings)
+        && !await readVSCodeFile(files.process), 'configuration_changed');
+    requireValue((await readdir(files.extensions)).every(name => ['extensions.json', '.obsolete'].includes(name)), 'configuration_changed');
+    for (const [name, expected] of [['extensions.json', '[]'], ['.obsolete', '{}']]) {
+        const content = await readVSCodeFile(path.join(files.extensions, name));
+        try {
+            requireValue(!content || JSON.stringify(JSON.parse(content.toString('utf8'))) === expected, 'configuration_changed');
+        }
+        catch {
+            throw new ConnectorError('configuration_changed');
+        }
+    }
+    await runtime.verify(exe);
+    // Exclusive single-use receipt: an old GUI may survive Disconnect. Never reuse
+    // its environment/profile or remove its runtime data based on launcher exit.
+    await writeVSCodeFile(files.launched, Buffer.from('{"owner":"TrackQA Copilot single-use launch v1"}\n'));
+    const env = { ...profile.env };
+    if (options.credential)
+        env[profile.envVar] = options.credential;
+    let child;
+    try {
+        child = runtime.spawn(exe.path, profile.args, { env, cwd: files.root, windowsHide: false, stdio: 'ignore' });
+    }
+    catch {
+        throw new ConnectorError('client_launch_failed');
+    }
+    finally {
+        delete env[profile.envVar];
+        options.credential = undefined;
+    }
+    let exited = false, failure;
+    let complete;
+    const stopped = new Promise(resolve => { complete = resolve; });
+    child.once('error', () => { failure = new ConnectorError('client_launch_failed'); complete(); });
+    child.once('exit', code => { exited = true; if (code !== 0)
+        failure = new ConnectorError('client_exit_failed'); complete(); });
+    return {
+        launcherStatus: () => exited ? 'exit-observed' : 'unconfirmed',
+        async waitForDisconnect(request, signal) {
+            const prompt = new AbortController();
+            let interrupted;
+            const interruption = new Promise(resolve => { interrupted = resolve; });
+            const abort = () => { interrupted(); };
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            try {
+                await Promise.race([stopped, interruption, Promise.resolve().then(() => request(prompt.signal))]);
+                requireValue(!signal?.aborted, 'interrupted');
+                if (failure)
+                    throw failure;
+            }
+            finally {
+                prompt.abort();
+                signal?.removeEventListener('abort', abort);
+                // No descendant discovery, ownership adoption, shutdown RPC or kill.
+                child.unref();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,115 @@
+import { lstat, mkdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { requireValue, setupFor, UUID } from "../core.js";
+import { fingerprint } from "./codex.js";
+import { readVSCodeFile, safeVSCodeDirectory, writeVSCodeFile } from "./vscode-session.js";
+export const freshCopilotHome = (base) => path.join(base, 'runs', randomUUID());
+export function copilotRecoveryHome(base, home) {
+    const relative = path.relative(base, home).split(path.sep);
+    requireValue(path.isAbsolute(home) && (path.resolve(home) === path.resolve(base)
+        || relative.length === 2 && relative[0] === 'runs' && UUID.test(relative[1])), 'configuration_home_mismatch');
+    return home;
+}
+export function copilotPaths(home, setup) {
+    requireValue(path.isAbsolute(home) && UUID.test(setup.projectId)
+        && fingerprint(setup) === fingerprint(setupFor(setup.projectId, 'vscode-copilot')), 'configuration_location_untrusted');
+    const root = path.join(home, setup.projectId), user = path.join(root, 'user-data'), isolatedHome = path.join(root, 'home');
+    return { root, user, home: isolatedHome, extensions: path.join(root, 'extensions'), temp: path.join(isolatedHome, 'Temp'),
+        copilot: path.join(root, 'copilot'), shared: path.join(root, 'shared-data'), owner: path.join(root, 'owner.json'),
+        process: path.join(root, 'process.json'), launched: path.join(root, 'launch.json'), settings: path.join(user, 'User', 'settings.json'),
+        localMcp: path.join(user, 'User', 'mcp.json'), mcp: path.join(root, 'copilot', 'mcp-config.json') };
+}
+export const copilotEntry = (setup) => ({ type: 'http', url: setup.endpoint,
+    headers: { Authorization: `Bearer \${${setup.envVar}}` } });
+const bytes = (value) => Buffer.from(JSON.stringify(value, null, 2) + '\n');
+export function copilotPayloads(setup, mode = 'session') {
+    requireValue(['session', 'token-free'].includes(mode), 'configuration_conflict');
+    return {
+        owner: bytes({ owner: 'TrackQA Connect VS Code Copilot client-managed v1', client: 'vscode-copilot', projectId: setup.projectId, mode }),
+        mcp: bytes({ mcpServers: mode === 'token-free' ? {} : { [setup.serverName]: copilotEntry(setup) } }),
+        settings: bytes({ 'update.mode': 'none', 'extensions.autoUpdate': 'off', 'extensions.autoCheckUpdates': false,
+            'telemetry.telemetryLevel': 'off', 'workbench.startupEditor': 'none', 'window.restoreWindows': 'none',
+            'window.title': 'TrackQA Copilot - ${activeEditorShort}' }),
+    };
+}
+async function owned(home, setup, mode) {
+    const files = copilotPaths(home, setup);
+    try {
+        await safeVSCodeDirectory(home);
+        await safeVSCodeDirectory(files.root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    requireValue((await readVSCodeFile(files.owner))?.equals(copilotPayloads(setup, mode).owner), 'configuration_conflict');
+    return files;
+}
+async function configuration(home, setup, mode) {
+    const files = await owned(home, setup, mode);
+    if (!files)
+        return null;
+    for (const dir of [files.user, path.dirname(files.settings), files.extensions, files.home, files.temp, files.copilot, files.shared])
+        await safeVSCodeDirectory(dir);
+    // A second registration source is unexpected, including a link or directory.
+    requireValue(!await lstat(files.localMcp).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; }), 'configuration_conflict');
+    return files;
+}
+export async function readCopilotSession(home, setup, mode = 'session') {
+    const files = await configuration(home, setup, mode);
+    if (!files)
+        return null;
+    const content = await readVSCodeFile(files.mcp);
+    if (!content)
+        return null;
+    requireValue(content.equals(copilotPayloads(setup, mode).mcp), 'configuration_changed');
+    return mode === 'token-free' ? { mcpServers: {} } : copilotEntry(setup);
+}
+export async function installCopilotSession(home, setup, mode = 'session') {
+    const files = copilotPaths(home, setup), payload = copilotPayloads(setup, mode);
+    await safeVSCodeDirectory(home, true);
+    try {
+        await mkdir(files.root, { mode: 0o700 });
+        await writeVSCodeFile(files.owner, payload.owner);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        await owned(home, setup, mode);
+    }
+    await safeVSCodeDirectory(files.root);
+    requireValue(!await readVSCodeFile(files.process), 'copilot_process_unconfirmed');
+    requireValue(!await readVSCodeFile(files.launched), 'configuration_conflict');
+    for (const file of [files.settings, files.mcp, files.localMcp]) {
+        requireValue(!await lstat(file).catch(error => { if (error.code === 'ENOENT')
+            return null; throw error; }), 'configuration_conflict');
+    }
+    for (const dir of [files.user, path.dirname(files.settings), files.extensions, files.home, files.temp, files.copilot, files.shared,
+        path.join(files.home, 'AppData', 'Roaming'), path.join(files.home, 'AppData', 'Local')])
+        await safeVSCodeDirectory(dir, true);
+    await writeVSCodeFile(files.settings, payload.settings);
+    await writeVSCodeFile(files.mcp, payload.mcp);
+    return fingerprint(mode === 'token-free' ? { mcpServers: {} } : copilotEntry(setup));
+}
+export async function removeCopilotSession(home, setup, hash, mode = 'session') {
+    const files = await configuration(home, setup, mode);
+    if (!files)
+        return;
+    // Offline foundation cannot establish that a recorded runtime has stopped.
+    // Never retire its evidence based on editor exit or an empty PID list alone.
+    requireValue(!await readVSCodeFile(files.process), 'copilot_process_unconfirmed');
+    requireValue(hash === null || hash === fingerprint(mode === 'token-free' ? { mcpServers: {} } : copilotEntry(setup)), 'configuration_changed');
+    await removeOwnedCopilotConfiguration(files.mcp, copilotPayloads(setup, mode).mcp);
+    // Preserve the owner marker, runtime data and any unexpected files. No tree deletion.
+}
+// Both validators establish ownership first. Keep removal identical for hosted
+// sessions and the loopback test fixture, without accepting a different schema.
+export async function removeOwnedCopilotConfiguration(file, expected) {
+    const content = await readVSCodeFile(file);
+    requireValue(!content || content.equals(expected), 'configuration_changed');
+    if (content)
+        await unlink(file);
+}

package/dist/tools/trackqa-connect/src/clients/vscode-copilot.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import { ConnectorError } from "../core.js";
+import { fingerprint } from "./codex.js";
+import { copilotEntry, copilotPaths, installCopilotSession, readCopilotSession, removeCopilotSession } from "./vscode-copilot-session.js";
+import { startCopilotSession } from "./vscode-copilot-lifecycle.js";
+export function copilotEnvironment(home, setup, source = process.env) {
+    const files = copilotPaths(home, setup), clean = {};
+    for (const key of ['PATH', 'PATHEXT', 'SystemRoot', 'SystemDrive', 'WINDIR', 'COMSPEC', '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']) {
+        if (source[key] !== undefined)
+            clean[key] = source[key];
+    }
+    return { ...clean, HOME: files.home, USERPROFILE: files.home, APPDATA: path.join(files.home, 'AppData', 'Roaming'),
+        LOCALAPPDATA: path.join(files.home, 'AppData', 'Local'), TEMP: files.temp, TMP: files.temp,
+        COPILOT_HOME: files.copilot, VSCODE_DISABLE_TELEMETRY: '1' };
+}
+export function copilotLaunchArgs(home, setup) {
+    const files = copilotPaths(home, setup);
+    return ['--new-window', '--user-data-dir', files.user, '--extensions-dir', files.extensions, '--shared-data-dir', files.shared,
+        '--skip-welcome', '--skip-release-notes', '--disable-updates', '--disable-telemetry', '--sync', 'off',
+        '--use-inmemory-secretstorage', '--log', 'warning'];
+}
+const unavailable = () => { throw new ConnectorError('copilot_runtime_unverified'); };
+export function vscodeCopilotAdapter(exe, home, controls) {
+    let launcherStatus = 'not observed';
+    return {
+        client: 'vscode-copilot', label: 'VS Code Copilot', configurationHome: home, executable: exe,
+        entry: setup => readCopilotSession(home, setup), matches: (value, setup) => fingerprint(value) === fingerprint(copilotEntry(setup)),
+        installPreview: setup => `Private portable MCP configuration: ${copilotPaths(home, setup).mcp}. Session-only; native acceptance pending.`,
+        prepare: async () => unavailable(),
+        install: setup => installCopilotSession(home, setup),
+        remove: async (setup, hash) => {
+            try {
+                await removeCopilotSession(home, setup, hash);
+            }
+            finally {
+                controls?.report(`Editor launcher: ${launcherStatus}. Copilot runtime termination: UNVERIFIED. Use File > Exit in only TrackQA Copilot to exit normally. Runtime profile data is preserved.`);
+            }
+        },
+        manualInstructions: setup => `In only TrackQA Copilot, use native Copilot MCP controls to start ${setup.serverName} and inspect its tools. GitHub/model sign-in is separate. Stop on unexpected permissions. No automatic tool approval. Keep the CLI open; type disconnect here to revoke access. Configuration and editor startup do not prove connectivity.`,
+        verify: async () => {
+            unavailable();
+            return { authorized: null, verified: false, code: 'manual_verification_required' };
+        },
+        launch: async (setup, token, signal) => {
+            unavailable(); // Remains blocked until separately approved synthetic acceptance.
+            if (!controls)
+                throw new ConnectorError('usage');
+            const session = await startCopilotSession(exe, home, setup, { credential: token, signal });
+            token = '';
+            try {
+                await session.waitForDisconnect(controls.requestDisconnect, signal);
+            }
+            finally {
+                launcherStatus = session.launcherStatus();
+            }
+        },
+    };
+}

package/dist/tools/trackqa-connect/src/clients/vscode-process.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { open, unlink } from 'node:fs/promises';
+import { capture } from "../process.js";
+import { ConnectorError, requireValue } from "../core.js";
+import { readVSCodeFile, writeVSCodeFile } from "./vscode-session.js";
+const shell = () => path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+const quote = (value) => "'" + value.replaceAll("'", "''") + "'";
+const helperEnvironment = () => Object.fromEntries(['SystemRoot', 'WINDIR', 'TEMP', 'TMP'].filter(k => process.env[k]).map(k => [k, process.env[k]]));
+export async function codeProcesses(user) {
+    requireValue(process.platform === 'win32', 'client_unsupported');
+    const command = `$dir=${quote(user)}; @(Get-CimInstance Win32_Process -Filter "Name = 'Code.exe'" -ErrorAction Stop | ForEach-Object { [pscustomobject]@{pid=[int]$_.ProcessId;created=$_.CreationDate.ToUniversalTime().ToString('o');owned=[bool]($_.CommandLine -and $_.CommandLine.Contains($dir))} }) | ConvertTo-Json -Compress`;
+    try {
+        const raw = await capture(shell(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], helperEnvironment());
+        const rows = raw.trim() ? JSON.parse(raw) : [];
+        requireValue(Array.isArray(rows) && rows.length < 1000 && rows.every(row => Number.isSafeInteger(row.pid) && row.pid > 0 && typeof row.created === 'string' && typeof row.owned === 'boolean'), 'vscode_process_unconfirmed');
+        return rows;
+    }
+    catch {
+        throw new ConnectorError('vscode_process_unconfirmed');
+    }
+}
+async function closeOwnedWindow(user, process) {
+    // No forced process/tree kill. Recheck identity and the private user-data path.
+    const command = `$p=Get-CimInstance Win32_Process -Filter ${quote('ProcessId = ' + process.pid)} -ErrorAction Stop; if ($p -and $p.Name -ceq 'Code.exe' -and $p.CreationDate.ToUniversalTime().ToString('o') -ceq ${quote(process.created)} -and $p.CommandLine.Contains(${quote(user)})) { [void](Get-Process -Id ${process.pid} -ErrorAction Stop).CloseMainWindow() }`;
+    await capture(shell(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], helperEnvironment());
+}
+export const vscodeRuntime = { snapshot: codeProcesses, close: closeOwnedWindow, spawn };
+const identity = (row) => `${row.pid}:${row.created}`;
+async function runRecord(file) {
+    const bytes = await readVSCodeFile(file);
+    if (!bytes)
+        return null;
+    let record;
+    try {
+        record = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new ConnectorError('vscode_process_unconfirmed');
+    }
+    requireValue(record && Object.keys(record).sort().join(',') === 'baseline,phase,version' && record.version === 1
+        && ['launching', 'running'].includes(record.phase) && Array.isArray(record.baseline)
+        && record.baseline.every(row => Object.keys(row).sort().join(',') === 'created,owned,pid' && Number.isSafeInteger(row.pid)
+            && row.pid > 0 && typeof row.created === 'string' && typeof row.owned === 'boolean'), 'vscode_process_unconfirmed');
+    return record;
+}
+export async function settleVSCodeRun(file, user, runtime = vscodeRuntime) {
+    const record = await runRecord(file);
+    if (!record)
+        return;
+    // A crash in the spawn/acknowledgement gap cannot be automatically settled.
+    requireValue(record.phase === 'running', 'vscode_process_unconfirmed');
+    const baseline = new Set(record.baseline.map(identity)), rows = await runtime.snapshot(user);
+    requireValue(rows.every(row => !row.owned && baseline.has(identity(row))), 'vscode_process_unconfirmed');
+    await unlink(file);
+}
+export async function launchVSCode(executable, args, env, user, file, signal, runtime = vscodeRuntime) {
+    requireValue(!signal?.aborted, 'interrupted');
+    const baseline = await runtime.snapshot(user);
+    requireValue(baseline.length < 100 && !baseline.some(row => row.owned), 'vscode_process_unconfirmed');
+    const record = { version: 1, phase: 'launching', baseline };
+    await writeVSCodeFile(file, Buffer.from(JSON.stringify(record)));
+    if (signal?.aborted) {
+        await unlink(file);
+        throw new ConnectorError('interrupted');
+    }
+    let child;
+    try {
+        child = runtime.spawn(executable, args, { env, cwd: path.dirname(user), windowsHide: false, stdio: 'ignore' });
+    }
+    catch {
+        await unlink(file);
+        throw new ConnectorError('client_launch_failed');
+    }
+    // spawn copies the environment synchronously. Never retain its token reference.
+    for (const key of Object.keys(env))
+        if (/^TRACKQA_MCP_/.test(key))
+            delete env[key];
+    let failure, stopping = false, exited = false;
+    let timer;
+    let completeCleanup = () => { };
+    const complete = new Promise(resolve => {
+        const stop = () => {
+            if (stopping || exited)
+                return;
+            stopping = true;
+            void runtime.snapshot(user).then(rows => Promise.all(rows.filter(row => row.pid === child.pid && row.owned && !baseline.some(old => identity(old) === identity(row))).map(row => runtime.close(user, row)))).catch(() => { });
+            timer = setTimeout(() => { failure = new ConnectorError('vscode_process_unconfirmed'); resolve(); }, runtime.graceMs ?? 5000);
+        };
+        signal?.addEventListener('abort', stop, { once: true });
+        child.once('error', () => { exited = true; failure = new ConnectorError('client_launch_failed'); resolve(); });
+        child.once('exit', code => { exited = true; if (code !== 0)
+            failure = new ConnectorError('client_exit_failed'); resolve(); });
+        if (signal?.aborted)
+            stop();
+        completeCleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', stop); };
+    });
+    try {
+        // A partial acknowledgement fails closed on recovery; no token is written.
+        const handle = await open(file, 'r+');
+        try {
+            await handle.truncate(0);
+            await handle.writeFile(JSON.stringify({ ...record, phase: 'running' }));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await complete;
+    }
+    catch {
+        throw new ConnectorError('vscode_process_unconfirmed');
+    }
+    finally {
+        completeCleanup();
+    }
+    // Main-process exit alone is insufficient. Any newly observed Code process
+    // (even an unrelated new instance) makes cleanup uncertain; none is killed.
+    await settleVSCodeRun(file, user, runtime);
+    if (failure)
+        throw failure;
+    requireValue(!signal?.aborted, 'interrupted');
+}