trackqa 0.0.0-stage → 0.1.0

package/dist/tools/trackqa-connect/src/clients/codex-verify.js

@@ -0,0 +1,110 @@
+import { createInterface } from 'node:readline';
+import { spawnProcess, clientEnvironment } from "../process.js";
+import { ConnectorError, requireValue, TOKEN, tools } from "../core.js";
+// Adapted from the existing Codex pilot app-server check. No model turn, code
+// upload, synthetic project assumptions, finding submission or direct DB access.
+export async function verifyCodex(executable, codexHome, setup, token, signal, spawnFn = spawnProcess, timeoutMs = 30_000) {
+    requireValue(TOKEN.test(token), 'token_invalid');
+    const env = { ...clientEnvironment(codexHome), [setup.envVar]: token };
+    token = '';
+    const table = `mcp_servers={${setup.serverName}={url="${setup.endpoint}",bearer_token_env_var="${setup.envVar}",startup_timeout_sec=15,tool_timeout_sec=10,enabled_tools=[${tools.map(name => `"${name}"`).join(',')}]}}`;
+    const child = spawnFn(executable, ['app-server', '--stdio', '-c', table, '-c', 'plugins={}', '-c', 'analytics.enabled=false'], { env, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    delete env[setup.envVar];
+    let sequence = 0, bytes = 0, stage = 'initialization', stopped = false, authorization = null;
+    const pending = new Map();
+    const fail = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        for (const promise of pending.values())
+            promise.reject(new ConnectorError('verification_failed'));
+        pending.clear();
+        child.kill();
+    };
+    child.on('error', fail);
+    child.on('exit', fail);
+    for (const stream of [child.stdin, child.stdout, child.stderr])
+        stream?.on('error', fail);
+    for (const stream of [child.stdout, child.stderr])
+        stream?.on('data', (chunk) => { bytes += chunk.length; if (bytes > 1_048_576)
+            fail(); });
+    const lines = createInterface({ input: child.stdout });
+    lines.on('error', fail);
+    let startupError = false;
+    lines.on('line', (line) => {
+        if (stopped)
+            return;
+        try {
+            const message = JSON.parse(line);
+            if (message.method === 'mcpServer/startupStatus/updated' && message.params?.name === setup.serverName && message.params.error)
+                startupError = true;
+            const promise = pending.get(message.id);
+            if (!promise)
+                return;
+            pending.delete(message.id);
+            if (message.error)
+                promise.reject(new ConnectorError('verification_failed'));
+            else
+                promise.resolve(message.result);
+        }
+        catch {
+            fail();
+        }
+    });
+    const timer = setTimeout(fail, timeoutMs);
+    signal?.addEventListener('abort', fail, { once: true });
+    const rpc = (method, params = {}) => new Promise((resolve, reject) => {
+        if (stopped || signal?.aborted) {
+            reject(new ConnectorError('interrupted'));
+            return;
+        }
+        const id = ++sequence;
+        pending.set(id, { resolve, reject });
+        child.stdin.write(JSON.stringify({ id, method, params }) + '\n');
+    });
+    try {
+        await rpc('initialize', { clientInfo: { name: 'trackqa_connect', version: '0.1.0' } });
+        child.stdin.write(JSON.stringify({ method: 'initialized', params: {} }) + '\n');
+        const config = await rpc('config/read');
+        const servers = config?.config?.mcp_servers;
+        requireValue(servers && Object.keys(servers).length === 1 && servers[setup.serverName]?.url === setup.endpoint, 'verification_failed');
+        const thread = await rpc('thread/start', { cwd: process.cwd(), ephemeral: true, approvalPolicy: 'never', sandbox: 'read-only' });
+        requireValue(typeof thread?.thread?.id === 'string', 'verification_failed');
+        const threadId = thread.thread.id;
+        stage = 'discovery';
+        const result = await rpc('mcpServerStatus/list', { threadId, serverName: setup.serverName, detail: 'toolsAndAuthOnly', limit: 1 });
+        const server = result?.data?.find((item) => item.name === setup.serverName);
+        requireValue(server && !server.toolsError && !startupError, 'verification_failed');
+        const names = Object.values(server.tools ?? {}).map((tool) => tool.name);
+        requireValue(names.length === tools.length && tools.every(name => names.includes(name)), 'verification_failed');
+        const call = async (tool) => {
+            const result = await rpc('mcpServer/tool/call', { threadId, server: setup.serverName, tool, arguments: {} });
+            requireValue(!result?.isError, 'verification_failed');
+            return result.structuredContent ?? JSON.parse(result.content?.find((item) => item.type === 'text')?.text ?? 'null');
+        };
+        stage = 'connection_status';
+        const status = await call('trackqa_connection_status');
+        requireValue(status?.project_id === setup.projectId && status.database_connected === true && status.finding_submission === true && status.issue_writes_allowed === false, 'verification_failed');
+        authorization = true;
+        stage = 'project_scope';
+        const projects = await call('trackqa_list_projects');
+        requireValue(projects?.projects?.length === 1 && projects.projects[0].id === setup.projectId, 'verification_failed');
+        return { authorized: true, verified: true, code: 'verified' };
+    }
+    catch {
+        return { authorized: authorization, verified: false, code: signal?.aborted ? 'interrupted' : `verification_${stage}_failed` };
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', fail);
+        lines.close();
+        child.stdin?.end();
+        if (child.exitCode === null) {
+            await new Promise(resolve => {
+                const force = setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 1500);
+                child.once('exit', () => { clearTimeout(force); resolve(); });
+                child.kill();
+            });
+        }
+    }
+}

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

@@ -0,0 +1,191 @@
+import { realpath, stat, readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { capture, clientEnvironment, foreground } from "../process.js";
+import { ConnectorError, requireValue } from "../core.js";
+import { verifyCodex } from "./codex-verify.js";
+export function trustedLocation(file, home = os.homedir(), platform = process.platform, cwd = process.cwd()) {
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    const normalized = paths.resolve(file).toLowerCase();
+    const within = (root) => normalized.startsWith(paths.resolve(root).toLowerCase() + paths.sep);
+    if (!paths.isAbsolute(file) || within(cwd) || normalized === paths.resolve(cwd).toLowerCase())
+        return false;
+    if (platform === 'win32') {
+        if (paths.basename(file).toLowerCase() !== 'codex.exe')
+            return false;
+        const programFiles = process.env.ProgramFiles ?? 'C:\\Program Files';
+        return within(programFiles) || within(paths.join(home, 'AppData', 'Local', 'Programs'))
+            || within(paths.join(home, '.codex', 'bin'))
+            || ['.vscode', '.vscode-insiders', '.antigravity-ide'].some(editor => {
+                const base = paths.join(home, editor, 'extensions');
+                return within(base) && /^openai\.chatgpt-[^\\/]+[\\/]bin[\\/]/i.test(paths.relative(base, file));
+            });
+    }
+    return ['/usr/bin', '/usr/local/bin', '/opt', paths.join(home, '.local', 'bin'), paths.join(home, '.codex', 'bin')].some(within);
+}
+export function editorBundled(file) {
+    return /\/\.(?:vscode(?:-insiders)?|antigravity-ide)\/extensions\/openai\.chatgpt-[^/]+\/bin\//i.test(file.replaceAll('\\', '/'));
+}
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export async function checkExecutable(file) {
+    requireValue(path.isAbsolute(file) && trustedLocation(file), 'executable_untrusted');
+    const canonical = await realpath(file);
+    requireValue(trustedLocation(canonical) && (process.platform !== 'win32' || path.resolve(canonical).toLowerCase() === path.resolve(file).toLowerCase()), 'executable_untrusted');
+    const info = await stat(canonical);
+    requireValue(info.isFile() && (process.platform === 'win32' || !(info.mode & 0o022)), 'executable_untrusted');
+    return { path: canonical, sha256: sha(await readFile(canonical)) };
+}
+export async function detectCodex(codexHome, explicit, env = process.env, run = capture, inspect = checkExecutable) {
+    const candidates = explicit ? [explicit] : (env.PATH ?? '').split(path.delimiter).filter(folder => path.isAbsolute(folder))
+        .map(folder => path.join(folder, process.platform === 'win32' ? 'codex.exe' : 'codex'));
+    if (!explicit && env.PATH && process.platform === 'win32') {
+        candidates.push(path.join(os.homedir(), '.codex', 'bin', 'codex.exe'));
+        // Known publisher paths only: do not recursively scan arbitrary workspaces.
+        for (const editor of ['.vscode', '.vscode-insiders', '.antigravity-ide']) {
+            const folder = path.join(os.homedir(), editor, 'extensions');
+            const extensions = await readdir(folder).catch(() => []);
+            for (const extension of extensions.filter(name => /^openai\.chatgpt-[A-Za-z0-9.-]+$/.test(name)).sort().reverse()) {
+                candidates.push(path.join(folder, extension, 'bin', `windows-${process.arch === 'arm64' ? 'aarch64' : 'x86_64'}`, 'codex.exe'));
+            }
+        }
+    }
+    const childEnv = clientEnvironment(codexHome, env);
+    // Prefer an installed native CLI over an editor's partial package. Explicit
+    // selections are respected; never silently replace the executable requested.
+    const ordered = explicit ? candidates : [...new Map(candidates.map(file => [process.platform === 'win32' ? file.toLowerCase() : file, file])).values()]
+        .sort((a, b) => Number(editorBundled(a)) - Number(editorBundled(b)));
+    let fallback;
+    let unsupported;
+    for (const candidate of ordered) {
+        let executable;
+        try {
+            executable = await inspect(candidate);
+        }
+        catch {
+            if (explicit)
+                throw new ConnectorError('executable_untrusted');
+            continue;
+        }
+        try {
+            const version = /^codex-cli (\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)\s*$/.exec((await run(executable.path, ['--version'], childEnv)).trim())?.[1];
+            requireValue(version, 'client_unsupported');
+            // Capabilities, rather than an invented version threshold, determine support.
+            for (const [args, expected] of [
+                [['mcp', 'add', '--help'], ['--url', '--bearer-token-env-var']],
+                [['mcp', 'get', '--help'], ['--json']], [['mcp', 'list', '--help'], ['--json']],
+                [['mcp', 'remove', '--help'], ['NAME']],
+            ]) {
+                const help = await run(executable.path, args, childEnv);
+                requireValue(expected.every(flag => help.includes(flag)), 'client_unsupported');
+            }
+            const help = await run(executable.path, ['--help'], childEnv);
+            let foregroundMode = editorBundled(executable.path) ? 'unsupported' : 'direct';
+            if (/--no-daemon\b/.test(help)) {
+                // Help must both advertise the option and accept it. Do not optimistically
+                // retry a failed interactive session with a second credentialed process.
+                foregroundMode = 'unsupported';
+                try {
+                    await run(executable.path, ['--no-daemon', '--help'], childEnv);
+                    foregroundMode = 'no-daemon';
+                }
+                catch { /* Clear pre-auth diagnostic below. */ }
+            }
+            let appServer = false;
+            try {
+                appServer = /app.server/.test(await run(executable.path, ['app-server', '--stdio', '--help'], childEnv));
+            }
+            catch { /* Manual verification remains available. */ }
+            requireValue(sha(await readFile(executable.path)) === executable.sha256, 'executable_changed');
+            const detected = { ...executable, version, appServer, foregroundMode };
+            if (foregroundMode !== 'unsupported' || explicit)
+                return detected;
+            fallback ??= detected; // Status/disconnect must remain usable for recovery.
+        }
+        catch (error) {
+            if (explicit || (error instanceof ConnectorError && error.code === 'executable_changed'))
+                throw error;
+            unsupported = error;
+        }
+    }
+    if (fallback)
+        return fallback;
+    if (unsupported)
+        throw unsupported;
+    throw new ConnectorError('client_not_found');
+}
+export function fingerprint(value) {
+    const stable = (item) => Array.isArray(item) ? item.map(stable) : item && typeof item === 'object'
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => [key, stable(value)])) : item;
+    return sha(Buffer.from(JSON.stringify(stable(value))));
+}
+export function matchesEntry(value, setup) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    const transport = entry.transport;
+    return entry.name === setup.serverName && entry.enabled === true && transport?.type === 'streamable_http'
+        && transport.url === setup.endpoint && transport.bearer_token_env_var === setup.envVar
+        && !Object.keys(transport.http_headers ?? {}).length && !Object.keys(transport.env_http_headers ?? {}).length;
+}
+export function codexAdapter(executable, codexHome, run = capture, environment = process.env, launchForeground = foreground) {
+    const env = clientEnvironment(codexHome, environment);
+    async function assertIntegrity() { requireValue(sha(await readFile(executable.path)) === executable.sha256, 'executable_changed'); }
+    async function command(args) { await assertIntegrity(); return run(executable.path, args, env); }
+    async function entry(setup) {
+        let rows;
+        try {
+            rows = JSON.parse(await command(['mcp', 'list', '--json']));
+        }
+        catch {
+            throw new ConnectorError('configuration_unreadable');
+        }
+        requireValue(Array.isArray(rows) && rows.every(row => typeof row.name === 'string'), 'configuration_unreadable');
+        if (!rows.some(row => row.name === setup.serverName))
+            return null;
+        try {
+            return JSON.parse(await command(['mcp', 'get', setup.serverName, '--json']));
+        }
+        catch {
+            throw new ConnectorError('configuration_unreadable');
+        }
+    }
+    return {
+        executable, codexHome, entry,
+        async install(setup) {
+            requireValue(await entry(setup) === null, 'configuration_conflict');
+            await command(['mcp', 'add', setup.serverName, '--url', setup.endpoint, '--bearer-token-env-var', setup.envVar]);
+            const installed = await entry(setup);
+            requireValue(matchesEntry(installed, setup), 'installation_unconfirmed');
+            return fingerprint(installed);
+        },
+        async remove(setup, hash) {
+            const installed = await entry(setup);
+            if (installed === null)
+                return;
+            requireValue(hash && matchesEntry(installed, setup) && fingerprint(installed) === hash, 'configuration_changed');
+            await command(['mcp', 'remove', setup.serverName]);
+            requireValue(await entry(setup) === null, 'removal_unconfirmed');
+        },
+        async launch(setup, token, signal) {
+            requireValue(executable.foregroundMode === 'no-daemon' || executable.foregroundMode === 'direct', 'client_foreground_unsupported');
+            await assertIntegrity();
+            const childEnv = { ...env, [setup.envVar]: token };
+            token = '';
+            try {
+                const running = launchForeground(executable.path, childEnv, signal, undefined, executable.foregroundMode === 'no-daemon' ? ['--no-daemon'] : []);
+                delete childEnv[setup.envVar]; // spawn has copied the environment into the child.
+                await running;
+            }
+            finally {
+                delete childEnv[setup.envVar];
+            }
+        },
+        async verify(setup, token, signal) {
+            await assertIntegrity();
+            if (!executable.appServer)
+                return { authorized: null, verified: false, code: 'manual_verification_required' };
+            return verifyCodex(executable.path, codexHome, setup, token, signal);
+        },
+    };
+}

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

@@ -0,0 +1,141 @@
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { ConnectorError, requireValue } from "../core.js";
+import { fingerprint } from "./codex.js";
+import { commitWindowsSettings } from "./gemini-windows.js";
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function parseGeminiSettings(bytes) {
+    requireValue(bytes.length <= 1_048_576, 'configuration_unreadable');
+    try {
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        const value = JSON.parse(text);
+        requireValue(object(value) && (value.mcpServers === undefined || (object(value.mcpServers) && Object.values(value.mcpServers).every(object))), 'configuration_unreadable');
+        // JSON.parse accepts duplicate keys and unrepresentable numbers. Reject
+        // these rather than silently losing unrelated data during serialization.
+        const tokens = text.match(/"(?:[^"\\]|\\.)*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}[\]:,]/g) ?? [];
+        let index = 0;
+        const visit = (depth) => {
+            requireValue(depth <= 64, 'configuration_unreadable');
+            const token = tokens[index++];
+            if (token === '{') {
+                const keys = new Set();
+                while (tokens[index] !== '}') {
+                    const key = JSON.parse(tokens[index++]);
+                    requireValue(!keys.has(key), 'configuration_unreadable');
+                    keys.add(key);
+                    index++;
+                    visit(depth + 1);
+                    if (tokens[index] !== ',')
+                        break;
+                    index++;
+                }
+                index++;
+            }
+            else if (token === '[') {
+                while (tokens[index] !== ']') {
+                    visit(depth + 1);
+                    if (tokens[index] !== ',')
+                        break;
+                    index++;
+                }
+                index++;
+            }
+            else if (/^-?\d/.test(token)) {
+                const number = Number(token);
+                requireValue(Number.isFinite(number) && (!Number.isInteger(number) || Number.isSafeInteger(number)), 'configuration_unreadable');
+            }
+        };
+        visit(0);
+        return value;
+    }
+    catch {
+        throw new ConnectorError('configuration_unreadable');
+    }
+}
+async function directory(home, create = false) {
+    requireValue(path.isAbsolute(home), 'configuration_location_untrusted');
+    const dir = path.join(home, '.gemini');
+    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;
+        if (create) {
+            await mkdir(dir, { mode: 0o700 });
+            return directory(home);
+        }
+    }
+    return dir;
+}
+async function snapshot(file) {
+    let info;
+    try {
+        info = await lstat(file, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { exists: false, hash: null, identity: '', bytes: null, value: {} };
+        throw new ConnectorError('configuration_unreadable');
+    }
+    requireValue(info.isFile() && !info.isSymbolicLink() && info.nlink === 1n && info.size <= 1048576n, 'configuration_unreadable');
+    const identity = (stat) => [stat.dev, stat.ino, stat.mtimeNs, stat.ctimeNs, stat.size, stat.mode].join(':');
+    const handle = await open(file, 'r');
+    try {
+        requireValue(identity(await handle.stat({ bigint: true })) === identity(info), 'configuration_changed');
+        const bytes = await handle.readFile();
+        requireValue(identity(await handle.stat({ bigint: true })) === identity(info), 'configuration_changed');
+        return { exists: true, hash: sha(bytes), identity: identity(info), bytes, value: parseGeminiSettings(bytes) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readGeminiSettings(home) {
+    return (await snapshot(path.join(await directory(home), 'settings.json'))).value;
+}
+export const geminiHeader = (setup) => `Bearer \${${setup.envVar}}`;
+export function geminiEntry(setup) {
+    requireValue(/^trackqa_[A-Za-z0-9_]+$/.test(setup.serverName) && /^TRACKQA_[A-Z0-9_]+$/.test(setup.envVar), 'configuration_conflict');
+    return { url: setup.endpoint, type: 'http', headers: { Authorization: geminiHeader(setup) } };
+}
+export function matchesGeminiEntry(value, setup) {
+    if (!object(value) || !object(value.headers))
+        return false;
+    const legacy = value.httpUrl === setup.endpoint && value.url === undefined && (value.type === undefined || value.type === 'http');
+    const current = value.url === setup.endpoint && value.type === 'http' && value.httpUrl === undefined;
+    return (legacy || current) && value.command === undefined && value.trust !== true
+        && Object.keys(value.headers).length === 1 && value.headers.Authorization === geminiHeader(setup)
+        && Object.keys(value).every(key => ['httpUrl', 'url', 'type', 'headers', 'timeout', 'description', 'trust'].includes(key));
+}
+// Optimistic checks + an advisory lock for cooperating writers, NOT a filesystem
+// compare-and-swap. Non-cooperating editors must be closed during setup/cleanup.
+export async function editGeminiSettings(home, setup, operation, hash = null, commit = commitWindowsSettings) {
+    const ownedEntry = geminiEntry(setup);
+    const dir = await directory(home), file = path.join(dir, 'settings.json');
+    const before = await snapshot(file), existing = (before.value.mcpServers ?? {});
+    if (operation === 'remove' && !Object.hasOwn(existing, setup.serverName))
+        return null;
+    if (operation === 'install')
+        requireValue(!Object.hasOwn(existing, setup.serverName), 'configuration_conflict');
+    else
+        requireValue(hash && matchesGeminiEntry(existing[setup.serverName], setup) && fingerprint(existing[setup.serverName]) === hash, 'configuration_changed');
+    const entries = { ...existing };
+    if (operation === 'install')
+        entries[setup.serverName] = ownedEntry;
+    else
+        delete entries[setup.serverName];
+    const updated = { ...before.value, mcpServers: entries };
+    const bytes = Buffer.from(JSON.stringify(updated, null, 2) + '\n');
+    parseGeminiSettings(bytes);
+    await directory(home, true);
+    const current = await snapshot(file);
+    requireValue(current.exists === before.exists && current.identity === before.identity && current.hash === before.hash, 'configuration_changed');
+    await commit(file, { exists: before.exists, hash: before.hash }, bytes);
+    const after = await snapshot(file);
+    requireValue(after.hash === sha(bytes), 'configuration_write_uncertain');
+    return operation === 'install' ? fingerprint(entries[setup.serverName]) : null;
+}

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

@@ -0,0 +1,14 @@
+import { tools } from "../core.js";
+// A native `mcp list` result is NOT tool discovery or a successful read call.
+// Gemini has no verified equivalent of Codex's model-free app-server tool API.
+export function geminiVerification() {
+    return { authorized: null, verified: false, code: 'manual_verification_required' };
+}
+export function geminiInstructions(setup) {
+    return `Gemini CLI availability and token-free installation passed. Client-side discovery: not verified. Authenticated reads: not verified. Gemini account sign-in is separate from TrackQA. In Gemini 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 /quit for cleanup. These manual checks are not machine-verified; the connector will keep its result unverified.`;
+}
+export function assessGeminiDiscovery(names) {
+    const discovered = tools.filter(name => names.includes(name));
+    return { discovered, complete: names.length === tools.length && new Set(names).size === tools.length && discovered.length === tools.length,
+        authenticatedReadsVerified: false };
+}

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

@@ -0,0 +1,134 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { ConnectorError } from "../core.js";
+// Static script only: configuration bytes go over stdin, never command args.
+// Windows PowerShell 5.1/.NET File.Replace preserves the destination DACL.
+export const windowsSettingsScript = String.raw `
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+$code = 'configuration_write_failed'
+$lock = $null; $stream = $null; $temp = $null; $backup = $null; $ownsLock = $false
+function Hash-Bytes([byte[]]$bytes) {
+  $sha = [Security.Cryptography.SHA256]::Create()
+  try { return ([BitConverter]::ToString($sha.ComputeHash($bytes))).Replace('-', '').ToLowerInvariant() }
+  finally { $sha.Dispose() }
+}
+function ACL-Key($acl) {
+  $raw = [Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(), 0)
+  # ReplaceFile may add the informational AUTO_INHERITED flag even to a
+  # protected DACL. Compare every ACE, owner, group and protection flag; ignore
+  # only that bit, which does not add permissions or enable inheritance.
+  $flags = [int]$raw.ControlFlags -band (-bnot [int][Security.AccessControl.ControlFlags]::DiscretionaryAclAutoInherited)
+  $raw.SetFlags([Security.AccessControl.ControlFlags]$flags)
+  return $raw.GetSddlForm([Security.AccessControl.AccessControlSections]::All)
+}
+function Private-File([string]$file) {
+  $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User
+  $acl = [Security.AccessControl.FileSecurity]::new()
+  $acl.SetOwner($sid); $acl.SetAccessRuleProtection($true, $false)
+  foreach ($identity in @($sid, [Security.Principal.SecurityIdentifier]::new('S-1-5-18'), [Security.Principal.SecurityIdentifier]::new('S-1-5-32-544'))) {
+    $acl.AddAccessRule([Security.AccessControl.FileSystemAccessRule]::new($identity, [Security.AccessControl.FileSystemRights]::FullControl, [Security.AccessControl.AccessControlType]::Allow))
+  }
+  return [IO.FileStream]::new($file, [IO.FileMode]::CreateNew, [Security.AccessControl.FileSystemRights]::FullControl, [IO.FileShare]::None, 4096, [IO.FileOptions]::WriteThrough, $acl)
+}
+function Check-Original {
+  if ([IO.File]::Exists($file) -ne $request.exists) { throw 'conflict' }
+  if ($request.exists) {
+    $info = [IO.FileInfo]::new($file)
+    if (($info.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'conflict' }
+    if ((Hash-Bytes ([IO.File]::ReadAllBytes($file))) -cne $request.hash) { throw 'conflict' }
+    if ($null -ne $originalAcl -and (ACL-Key ([IO.File]::GetAccessControl($file))) -cne (ACL-Key $originalAcl)) { throw 'conflict' }
+    if ($null -ne $stamp -and ($info.CreationTimeUtc.Ticks.ToString() + ':' + $info.LastWriteTimeUtc.Ticks.ToString()) -cne $stamp) { throw 'conflict' }
+  }
+}
+try {
+  $request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $file = [IO.Path]::GetFullPath([string]$request.file)
+  $dir = [IO.Path]::GetDirectoryName($file)
+  if ([IO.Path]::GetFileName($file) -cne 'settings.json' -or ([IO.File]::GetAttributes($dir) -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'conflict' }
+  $lockPath = [IO.Path]::Combine($dir, '.trackqa-settings.lock')
+  try { $lock = Private-File $lockPath; $ownsLock = $true } catch { $code = 'configuration_busy'; throw }
+  $pidBytes = [Text.Encoding]::UTF8.GetBytes($PID.ToString()); $lock.Write($pidBytes, 0, $pidBytes.Length); $lock.Flush($true)
+  $originalAcl = $null; $stamp = $null
+  Check-Original
+  if ($request.exists) {
+    $originalAcl = [IO.File]::GetAccessControl($file)
+    $info = [IO.FileInfo]::new($file)
+    $stamp = $info.CreationTimeUtc.Ticks.ToString() + ':' + $info.LastWriteTimeUtc.Ticks.ToString()
+  }
+  $suffix = [Guid]::NewGuid().ToString('N')
+  $temp = [IO.Path]::Combine($dir, '.trackqa-settings-' + $suffix + '.tmp')
+  $backup = [IO.Path]::Combine($dir, '.trackqa-settings-recovery-' + $suffix + '.bak')
+  $bytes = [Convert]::FromBase64String($request.bytes)
+  $stream = Private-File $temp
+  try { $stream.Write($bytes, 0, $bytes.Length); $stream.Flush($true) } finally { $stream.Dispose(); $stream = $null }
+  Check-Original
+  # Commit point: no delete/truncate fallback and no automatic retry.
+  if ($request.exists) { [IO.File]::Replace($temp, $file, $backup, $false) }
+  else { [IO.File]::Move($temp, $file) }
+  if ((Hash-Bytes ([IO.File]::ReadAllBytes($file))) -cne (Hash-Bytes $bytes)) { $code = 'configuration_write_uncertain'; throw 'postcheck' }
+  if ($request.exists) {
+    if ((Hash-Bytes ([IO.File]::ReadAllBytes($backup))) -cne $request.hash -or (ACL-Key ([IO.File]::GetAccessControl($file))) -cne (ACL-Key $originalAcl)) {
+      $code = 'configuration_write_uncertain'; throw 'postcheck'
+    }
+  }
+  if ([IO.File]::Exists($backup)) { [IO.File]::Delete($backup) }
+  $code = 'ok'
+} catch {
+  if ($_.Exception.Message -eq 'conflict') { $code = 'configuration_changed' }
+  if ($null -ne $backup -and [IO.File]::Exists($backup)) {
+    # Restore only to an absent destination using a no-clobber move. Never
+    # overwrite a file that another writer may have created or edited.
+    if (-not [IO.File]::Exists($file)) {
+      try { [IO.File]::Move($backup, $file) } catch { $code = 'configuration_write_uncertain' }
+    } else { $code = 'configuration_write_uncertain' }
+  }
+} finally {
+  if ($null -ne $stream) { $stream.Dispose() }
+  if ($null -ne $temp -and [IO.File]::Exists($temp)) {
+    try { [IO.File]::Delete($temp) } catch { $code = 'configuration_write_uncertain' }
+  }
+  if ($null -ne $lock) { $lock.Dispose() }
+  if ($ownsLock) { try { [IO.File]::Delete($lockPath) } catch { $code = 'configuration_write_uncertain' } }
+}
+[Console]::Out.Write($code)
+`;
+export async function commitWindowsSettings(file, expected, bytes, spawnFn = spawn, timeoutMs = 15_000) {
+    if (process.platform !== 'win32')
+        throw new ConnectorError('client_unsupported');
+    const shell = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    await new Promise((resolve, reject) => {
+        const env = {};
+        for (const key of ['SystemRoot', 'WINDIR', 'TEMP', 'TMP'])
+            if (process.env[key])
+                env[key] = process.env[key];
+        const child = spawnFn(shell, ['-NoProfile', '-NonInteractive', '-Command', windowsSettingsScript], { env, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
+        let output = '', size = 0, settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code === 'ok')
+                resolve();
+            else {
+                child.kill();
+                reject(new ConnectorError(['configuration_busy', 'configuration_changed', 'configuration_write_failed'].includes(code) ? code : 'configuration_write_uncertain'));
+            }
+        };
+        const timer = setTimeout(() => finish('configuration_write_uncertain'), timeoutMs);
+        child.on('error', () => finish('configuration_write_uncertain'));
+        for (const stream of [child.stdin, child.stdout, child.stderr])
+            stream?.on('error', () => finish('configuration_write_uncertain'));
+        for (const stream of [child.stdout, child.stderr])
+            stream?.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > 4096)
+                    finish('configuration_write_uncertain');
+                else if (stream === child.stdout)
+                    output += chunk.toString('utf8');
+            });
+        child.on('close', code => finish(code === 0 ? output.trim() : 'configuration_write_uncertain'));
+        child.stdin.end(JSON.stringify({ file, ...expected, bytes: bytes.toString('base64') }));
+    });
+}