@withtruing/companion 0.0.0-stage → 0.13.1

package/dist/codex-cli-caller.js

@@ -0,0 +1,536 @@
+/**
+ * Model-only Codex CLI transport. The companion owns every filesystem read and sends Codex text;
+ * Codex is invoked in a fresh empty directory with every known tool surface disabled.
+ */
+import spawn from 'cross-spawn';
+import { access, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { StringDecoder } from 'node:string_decoder';
+import { assertSingleLineArguments } from './cli-arguments.js';
+import { gitErrorMessage } from './sandbox.js';
+import { stripIntroducedNulls, toCodexStrictSchema } from './strict-schema.js';
+const WALL_CLOCK_TIMEOUT_MS = 10 * 60 * 1000;
+const STDOUT_SAMPLE_CHARS = 200;
+const UNPARSEABLE_LINE_SAMPLE_CHARS = 120;
+const TEMP_DIRECTORY_PREFIX = 'product-console-codex-empty-';
+const TEMP_CLEANUP_MAX_RETRIES = 2;
+const TEMP_CLEANUP_RETRY_DELAY_MS = 50;
+export const CODEX_DISABLED_FEATURES = [
+    'shell_tool',
+    'unified_exec',
+    'view_image',
+    'sleep_tool',
+    'browser_use',
+    'browser_use_external',
+    'computer_use',
+    'in_app_browser',
+    'image_generation',
+    'apps',
+    'plugins',
+    'remote_plugin',
+    'multi_agent',
+    'goals',
+    'hooks',
+    'code_mode_host',
+    'tool_suggest',
+    'skill_search',
+    'personality',
+    'memories',
+    'recommended_plugins',
+    'workspace_dependencies',
+    'in_app_local_automation',
+    'skill_mcp_dependency_install',
+];
+/** A Codex version bump requires re-verifying that each model still routes all local tools
+ * through code mode and fails closed when code_mode_host is disabled. */
+export const CODEX_CODE_MODE_MODELS = [
+    'gpt-6-astra',
+    'gpt-5.6-sol',
+    'gpt-5.6-terra',
+    'gpt-5.6-luna',
+];
+export const CODEX_CREDENTIAL_ENV_SUBSTRINGS = [
+    'KEY',
+    'TOKEN',
+    'SECRET',
+    'PASSWORD',
+    'PASSWD',
+    'CREDENTIAL',
+    'AUTH',
+];
+/** No credential-shaped parent variable is needed by the child today. */
+export const CODEX_ENVIRONMENT_ALLOWLIST = [];
+function sampleForError(value) {
+    return gitErrorMessage(JSON.stringify(value));
+}
+function promptWriteFailure(error) {
+    const code = error.code ? ` (${error.code})` : '';
+    const wrapped = new Error(`Failed to write the prompt to codex CLI stdin${code}: ${gitErrorMessage(error)}`, { cause: error });
+    wrapped.code = error.code;
+    wrapped.errno = error.errno;
+    wrapped.syscall = error.syscall;
+    return wrapped;
+}
+function terminateChild(child) {
+    if (process.platform === 'win32' && child.pid) {
+        const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        killer.on('error', () => child.kill());
+        return;
+    }
+    child.kill();
+}
+function isWithin(base, candidate) {
+    const relation = relative(resolve(base), resolve(candidate));
+    return relation === '' || (!relation.startsWith('..') && !isAbsolute(relation));
+}
+function occurrences(args, value) {
+    return args.flatMap((argument, index) => argument === value ? [index] : []);
+}
+function samePath(left, right) {
+    const resolvedLeft = resolve(left);
+    const resolvedRight = resolve(right);
+    return process.platform === 'win32'
+        ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase()
+        : resolvedLeft === resolvedRight;
+}
+async function removeTemporaryDirectory(directory, removeDirectory) {
+    try {
+        await removeDirectory(directory, {
+            recursive: true,
+            force: true,
+            maxRetries: TEMP_CLEANUP_MAX_RETRIES,
+            retryDelay: TEMP_CLEANUP_RETRY_DELAY_MS,
+        });
+    }
+    catch (error) {
+        console.warn(`Failed to remove Codex temporary directory ${directory}: ${gitErrorMessage(error)}`);
+    }
+}
+/** Validate the complete safety contract immediately before spawn. */
+export function assertSafeInvocation(args, tempRoot = tmpdir()) {
+    const forbidden = [
+        '--add-dir',
+        '--dangerously-bypass-approvals-and-sandbox',
+        '--approve-for-me',
+        '--full-auto',
+    ];
+    for (const argument of args) {
+        const lower = argument.toLowerCase();
+        if (lower.includes('windows.sandbox')) {
+            throw new Error('Unsafe codex invocation contains forbidden windows.sandbox setting.');
+        }
+        for (const flag of forbidden) {
+            if (lower === flag || lower.startsWith(`${flag}=`)) {
+                throw new Error(`Unsafe codex invocation contains forbidden flag ${flag}.`);
+            }
+        }
+    }
+    const sandboxArguments = args.flatMap((argument, index) => argument === '--sandbox' || argument.startsWith('--sandbox=') ? [index] : []);
+    if (sandboxArguments.length !== 1 || args[sandboxArguments[0]] !== '--sandbox' || args[sandboxArguments[0] + 1] !== 'read-only') {
+        throw new Error('Codex invocation must contain exactly one --sandbox read-only pair.');
+    }
+    const ignoreUserConfigArguments = args.filter((argument) => argument === '--ignore-user-config' || argument.startsWith('--ignore-user-config='));
+    if (ignoreUserConfigArguments.length !== 1 || ignoreUserConfigArguments[0] !== '--ignore-user-config') {
+        throw new Error('Codex invocation must contain exactly one --ignore-user-config flag.');
+    }
+    if (args.at(-1) !== '-') {
+        throw new Error('Codex invocation must use the final - stdin marker and must not contain a positional prompt.');
+    }
+    for (const feature of CODEX_DISABLED_FEATURES) {
+        const present = args.some((argument, index) => argument === '--disable' && args[index + 1] === feature);
+        if (!present)
+            throw new Error(`Codex invocation must disable ${feature}.`);
+    }
+    for (const setting of [
+        'web_search_mode="disabled"',
+        'shell_environment_policy.inherit=core',
+        'project_doc_max_bytes=0',
+    ]) {
+        const present = args.some((argument, index) => argument === '-c' && args[index + 1] === setting);
+        if (!present)
+            throw new Error(`Codex invocation must contain -c ${setting}.`);
+    }
+    const instructions = args.filter((argument) => argument.startsWith('model_instructions_file='));
+    if (instructions.length !== 1 || !args.some((argument, index) => argument === '-c' && args[index + 1] === instructions[0])) {
+        throw new Error('Codex invocation must contain exactly one model_instructions_file setting.');
+    }
+    const cwdIndexes = occurrences(args, '-C');
+    if (cwdIndexes.length !== 1 || !args[cwdIndexes[0] + 1]) {
+        throw new Error('Codex invocation must contain exactly one -C directory.');
+    }
+    const invocationCwd = resolve(args[cwdIndexes[0] + 1]);
+    if (!samePath(dirname(invocationCwd), tempRoot) || !basename(invocationCwd).startsWith(TEMP_DIRECTORY_PREFIX)) {
+        throw new Error(`Codex -C directory must be an immediate child of the OS temporary directory ` +
+            `with a basename starting ${TEMP_DIRECTORY_PREFIX}.`);
+    }
+}
+async function validatedCodexHome(codexHome) {
+    const configured = resolve(codexHome);
+    let canonical = configured;
+    try {
+        canonical = await realpath(configured);
+    }
+    catch {
+        // A first login may create this stable directory.
+    }
+    if (isWithin(tmpdir(), canonical)) {
+        throw new Error(`Refusing CODEX_HOME ${JSON.stringify(configured)} because it resolves under the OS temporary directory; ` +
+            'the companion Codex home must be a stable path so Codex can retain its login and state.');
+    }
+    return configured;
+}
+export function defaultCodexHome() {
+    return join(homedir(), '.product-console-companion', 'codex-home');
+}
+export function buildCodexEnvironment(codexHome) {
+    const allow = new Set(CODEX_ENVIRONMENT_ALLOWLIST);
+    const env = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        const credentialShaped = CODEX_CREDENTIAL_ENV_SUBSTRINGS.some((part) => name.toUpperCase().includes(part));
+        if (!credentialShaped || allow.has(name))
+            env[name] = value;
+    }
+    env.CODEX_HOME = codexHome;
+    return env;
+}
+function assertAllowedModel(model) {
+    if (CODEX_CODE_MODE_MODELS.includes(model))
+        return;
+    throw new Error(`Refusing Codex model ${JSON.stringify(model)}. Allowed models: ${CODEX_CODE_MODE_MODELS.join(', ')}. ` +
+        'Only these models were verified to fail closed when a tool is attempted with code_mode_host disabled.');
+}
+function eventMessage(event) {
+    if (typeof event.message === 'string')
+        return event.message;
+    if (typeof event.error === 'string')
+        return event.error;
+    if (event.error && typeof event.error === 'object') {
+        const message = event.error.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    if (event.item && typeof event.item === 'object') {
+        const message = event.item.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    try {
+        return JSON.stringify(event);
+    }
+    catch {
+        return String(event);
+    }
+}
+function namedCodexFailure(message, codexHome) {
+    if (/401 Unauthorized/i.test(message)) {
+        return new Error(`Codex companion login is missing or expired (401 Unauthorized). Set CODEX_HOME to ` +
+            `"${codexHome}" and run "codex login", then retry.`);
+    }
+    if (/invalid_json_schema/i.test(message) || /HTTP\s*400/i.test(message) && /schema/i.test(message)) {
+        return new Error(`Codex rejected the output schema (invalid_json_schema, HTTP 400). This is a Truing schema defect: ${gitErrorMessage(message)}`);
+    }
+    if (/you(?:'|’)?ve hit your usage limit/i.test(message) ||
+        /usage limit reached/i.test(message) ||
+        /rate limit exceeded/i.test(message) ||
+        /quota exceeded/i.test(message)) {
+        return new Error(`Codex usage limit reached: ${gitErrorMessage(message)}`);
+    }
+    return null;
+}
+function usageFrom(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const usage = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate))
+            usage[key] = candidate;
+    }
+    return Object.keys(usage).length > 0 ? usage : null;
+}
+function toolUseAttempt(type) {
+    return new Error(`CodexToolUseAttempted: Codex attempted a tool (${type}) in a no-tools call; the result was discarded.`);
+}
+export function buildArgs(request, options, cwd, outputPath, schemaPath, instructionsPath) {
+    const args = [
+        'exec',
+        '--json',
+        ...(schemaPath ? ['--output-schema', schemaPath] : []),
+        '-o',
+        outputPath,
+        '--sandbox',
+        'read-only',
+        '--skip-git-repo-check',
+        '--ephemeral',
+        '--color',
+        'never',
+        '--ignore-user-config',
+        '-m',
+        options.model,
+        '-c',
+        `model_reasoning_effort=${request.effort}`,
+        '-c',
+        'project_doc_max_bytes=0',
+        '-c',
+        'web_search_mode="disabled"',
+        '-c',
+        'shell_environment_policy.inherit=core',
+        '-c',
+        `model_instructions_file=${instructionsPath}`,
+        ...CODEX_DISABLED_FEATURES.flatMap((feature) => ['--disable', feature]),
+        '-C',
+        cwd,
+        '-',
+    ];
+    assertSingleLineArguments('codex', args);
+    assertSafeInvocation(args);
+    return args;
+}
+function diagnostic(exitCode, stderrTail, stdoutBytes, stdoutLines, parsedLines, unparseableLines, stdoutFirst, stdoutLast, firstUnparseableLineLength, firstUnparseableLineFirst, firstUnparseableLineLast, typeCounts, toleratedErrorItems, purpose) {
+    const types = [...typeCounts.entries()]
+        .map(([type, count]) => `${gitErrorMessage(type) || '(empty)'}=${count}`)
+        .join(', ') || '(none)';
+    const stdoutSample = stdoutBytes === 0
+        ? '(none)'
+        : `first ${STDOUT_SAMPLE_CHARS} chars=${sampleForError(stdoutFirst)}, last ${STDOUT_SAMPLE_CHARS} chars=${sampleForError(stdoutLast)}`;
+    const unparseableSample = firstUnparseableLineLength === null
+        ? ''
+        : `; first unparseable line: ${firstUnparseableLineLength} chars, first ${UNPARSEABLE_LINE_SAMPLE_CHARS} chars=${sampleForError(firstUnparseableLineFirst)}, last ${UNPARSEABLE_LINE_SAMPLE_CHARS} chars=${sampleForError(firstUnparseableLineLast)}`;
+    return (`codex CLI exited (code ${exitCode}) without a final message — ` +
+        `stderr: ${stderrTail ? gitErrorMessage(stderrTail) : '(none)'}; ` +
+        `stdout: ${stdoutLines} line${stdoutLines === 1 ? '' : 's'} (${parsedLines} JSON, ${unparseableLines} unparseable), ${stdoutBytes} bytes; ` +
+        `types: ${types}; tolerated error items: ${toleratedErrorItems}; purpose: ${gitErrorMessage(purpose)}; ` +
+        `raw stdout: ${stdoutSample}${unparseableSample}`);
+}
+/** Invoke Codex as a model transport. maxTokens is intentionally not passed because codex exec
+ * exposes no enforceable output-token cap; the ten-minute wall-clock timeout is the hard bound. */
+export async function runViaCodex(request, options, 
+/** Test seam; production uses node:fs/promises rm. */
+removeDirectory = rm) {
+    if (request.documentBase64) {
+        throw new Error("This task includes a PDF PRD, which the Codex backend can't read yet. Pair with " +
+            '--backend api-key instead, or re-upload the PRD as .md/.txt/.docx.');
+    }
+    assertAllowedModel(options.model);
+    const codexHome = await validatedCodexHome(options.codexHome ?? defaultCodexHome());
+    const invocationCwd = await mkdtemp(join(tmpdir(), 'product-console-codex-empty-'));
+    let callDir = null;
+    try {
+        callDir = await mkdtemp(join(tmpdir(), 'product-console-codex-call-'));
+        const outputPath = join(callDir, 'last-message.txt');
+        const instructionsPath = join(callDir, 'model-instructions.txt');
+        await writeFile(instructionsPath, request.system, { encoding: 'utf8', mode: 0o600 });
+        let schemaPath = null;
+        let schemaRecord = null;
+        if (request.schema) {
+            const strict = toCodexStrictSchema(request.schema, { enforcedAfter: options.enforcedAfter });
+            schemaRecord = strict.record;
+            schemaPath = join(callDir, 'schema.json');
+            await writeFile(schemaPath, JSON.stringify(strict.schema), { encoding: 'utf8', mode: 0o600 });
+        }
+        const args = buildArgs(request, options, invocationCwd, outputPath, schemaPath, instructionsPath);
+        let stderrTail = '';
+        let timedOut = false;
+        let stdinError = null;
+        let fatalError = null;
+        let turnFailure = '';
+        let usage = null;
+        let toleratedErrorItems = 0;
+        let stdoutBytes = 0;
+        let stdoutLines = 0;
+        let parsedLines = 0;
+        let unparseableLines = 0;
+        let stdoutFirst = '';
+        let stdoutLast = '';
+        let firstUnparseableLineLength = null;
+        let firstUnparseableLineFirst = '';
+        let firstUnparseableLineLast = '';
+        const typeCounts = new Map();
+        const child = spawn('codex', args, {
+            cwd: invocationCwd,
+            env: buildCodexEnvironment(codexHome),
+            windowsHide: true,
+        });
+        const stdoutDecoder = new StringDecoder('utf8');
+        const recordStdout = (text) => {
+            if (!text)
+                return;
+            if (stdoutFirst.length < STDOUT_SAMPLE_CHARS) {
+                stdoutFirst += text.slice(0, STDOUT_SAMPLE_CHARS - stdoutFirst.length);
+            }
+            stdoutLast = (stdoutLast + text).slice(-STDOUT_SAMPLE_CHARS);
+        };
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            recordStdout(stdoutDecoder.write(chunk));
+        });
+        child.stdout.on('end', () => recordStdout(stdoutDecoder.end()));
+        child.stdin.on('error', (error) => {
+            stdinError ??= error;
+            terminateChild(child);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrTail = (stderrTail + chunk.toString()).slice(-2000);
+        });
+        const rl = createInterface({ input: child.stdout });
+        rl.on('line', (line) => {
+            stdoutLines++;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                unparseableLines++;
+                if (firstUnparseableLineLength === null) {
+                    firstUnparseableLineLength = line.length;
+                    firstUnparseableLineFirst = line.slice(0, UNPARSEABLE_LINE_SAMPLE_CHARS);
+                    firstUnparseableLineLast = line.slice(-UNPARSEABLE_LINE_SAMPLE_CHARS);
+                }
+                return;
+            }
+            parsedLines++;
+            const eventType = typeof event.type === 'string' ? event.type : '(missing)';
+            typeCounts.set(eventType, (typeCounts.get(eventType) ?? 0) + 1);
+            if (eventType === 'item.started' || eventType === 'item.completed') {
+                const itemType = event.item && typeof event.item === 'object'
+                    ? event.item.type
+                    : undefined;
+                const classified = typeof itemType === 'string' ? itemType : '(missing)';
+                if (classified === 'error') {
+                    toleratedErrorItems++;
+                }
+                else if (classified !== 'agent_message' && classified !== 'reasoning') {
+                    fatalError ??= toolUseAttempt(classified);
+                    terminateChild(child);
+                }
+            }
+            if (eventType === 'turn.completed')
+                usage = usageFrom(event.usage);
+            if (eventType === 'error' || eventType === 'turn.failed') {
+                const message = eventMessage(event);
+                const named = namedCodexFailure(message, codexHome);
+                if (named) {
+                    fatalError ??= named;
+                    if (/401 Unauthorized/i.test(message))
+                        terminateChild(child);
+                }
+                else if (eventType === 'turn.failed') {
+                    turnFailure = message;
+                }
+            }
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            terminateChild(child);
+        }, options.timeoutMs ?? WALL_CLOCK_TIMEOUT_MS);
+        const exitPromise = new Promise((resolvePromise, reject) => {
+            child.on('error', reject);
+            child.on('close', (code) => resolvePromise(code ?? 1));
+        });
+        try {
+            if (request.stableText)
+                child.stdin.write(`${request.stableText}\n\n`);
+            child.stdin.write(request.text);
+            child.stdin.end();
+        }
+        catch (error) {
+            stdinError ??= error;
+            terminateChild(child);
+        }
+        let exitCode;
+        try {
+            exitCode = await exitPromise;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        options.onDiagnostic?.({ toleratedErrorItems });
+        if (/codex_core::tools::router/i.test(stderrTail) && /(?:spawn|exec_command)/i.test(stderrTail)) {
+            throw toolUseAttempt(/exec_command/i.test(stderrTail) ? 'exec_command' : 'spawn');
+        }
+        if (fatalError)
+            throw fatalError;
+        if (timedOut) {
+            throw new Error(`codex CLI took longer than ${(options.timeoutMs ?? WALL_CLOCK_TIMEOUT_MS) / 60_000} minutes and was killed.`);
+        }
+        let finalText = null;
+        try {
+            finalText = await readFile(outputPath, 'utf8');
+        }
+        catch {
+            // The bounded stream diagnostic below carries the relevant exit context.
+        }
+        const capturedStdinError = stdinError;
+        if (turnFailure) {
+            const named = namedCodexFailure(turnFailure, codexHome);
+            throw named ?? new Error(`Codex turn failed: ${gitErrorMessage(turnFailure)}; ${diagnostic(exitCode, stderrTail, stdoutBytes, stdoutLines, parsedLines, unparseableLines, stdoutFirst, stdoutLast, firstUnparseableLineLength, firstUnparseableLineFirst, firstUnparseableLineLast, typeCounts, toleratedErrorItems, request.purpose)}`);
+        }
+        if (finalText === null || finalText.length === 0) {
+            if (capturedStdinError)
+                throw promptWriteFailure(capturedStdinError);
+            throw new Error(diagnostic(exitCode, stderrTail, stdoutBytes, stdoutLines, parsedLines, unparseableLines, stdoutFirst, stdoutLast, firstUnparseableLineLength, firstUnparseableLineFirst, firstUnparseableLineLast, typeCounts, toleratedErrorItems, request.purpose));
+        }
+        if (capturedStdinError)
+            throw promptWriteFailure(capturedStdinError);
+        if (request.schema) {
+            let result;
+            try {
+                result = JSON.parse(finalText);
+            }
+            catch (error) {
+                throw new Error(`Codex wrote an invalid JSON final message: ${gitErrorMessage(error)}`);
+            }
+            stripIntroducedNulls(result, schemaRecord);
+            finalText = JSON.stringify(result);
+        }
+        options.onUsage?.(usage);
+        return { text: finalText, usage };
+    }
+    finally {
+        await removeTemporaryDirectory(invocationCwd, removeDirectory);
+        if (callDir)
+            await removeTemporaryDirectory(callDir, removeDirectory);
+    }
+}
+export function codexTextModel(options) {
+    return (request) => runViaCodex(request, options);
+}
+/** The reader result contract re-checks allOf/if/then after the reply, so only this path may
+ * remove those three schema keywords for Codex strict-output compatibility. */
+export async function runStructuredModelCallViaCodex(request, options) {
+    const reply = await runViaCodex({
+        purpose: 'investigation',
+        model: request.model,
+        effort: request.effort,
+        maxTokens: request.maxTokens,
+        system: request.system,
+        stableText: '',
+        text: request.prompt,
+        schema: request.schema,
+    }, { ...options, enforcedAfter: ['allOf', 'if', 'then'] });
+    return JSON.parse(reply.text);
+}
+export async function checkCodexLogin(codexHome) {
+    const validatedHome = await validatedCodexHome(codexHome);
+    try {
+        await access(validatedHome);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'not-logged-in';
+        throw error;
+    }
+    return new Promise((resolvePromise) => {
+        const child = spawn('codex', ['login', 'status'], {
+            env: buildCodexEnvironment(validatedHome),
+            windowsHide: true,
+        });
+        child.stdout?.resume();
+        child.stderr?.resume();
+        child.on('error', (error) => {
+            resolvePromise(error.code === 'ENOENT' ? 'not-installed' : 'not-logged-in');
+        });
+        child.on('close', (code) => resolvePromise(code === 0 ? 'logged-in' : 'not-logged-in'));
+    });
+}

package/dist/config.js

@@ -0,0 +1,119 @@
+/** Reads/writes ~/.product-console-companion/config.json. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// Kept on purpose from the old name so existing pairings continue to load after upgrading.
+const CONFIG_DIR = join(homedir(), '.product-console-companion');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+function trimUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+export function normalizeConsoleUrl(url) {
+    const trimmed = trimUrl(url);
+    const parsed = /^([a-z][a-z\d+.-]*):\/\/([^/?#]+)(.*)$/i.exec(trimmed);
+    return parsed ? `${parsed[1].toLowerCase()}://${parsed[2].toLowerCase()}${parsed[3]}` : trimmed;
+}
+export function samePairing(a, b) {
+    return normalizeConsoleUrl(a.url) === normalizeConsoleUrl(b.url) && a.workspaceId === b.workspaceId;
+}
+/** v1 files are adapted in memory and are not rewritten until a mutating operation saves them. */
+export function loadConfig(path = CONFIG_PATH) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if ('pairings' in parsed && Array.isArray(parsed.pairings))
+            return parsed;
+        const legacy = parsed;
+        return {
+            version: 2,
+            pairings: [{
+                    url: trimUrl(legacy.url),
+                    token: legacy.token,
+                    connections: legacy.connections ?? [],
+                    pollWorkspaceTasks: legacy.pollWorkspaceTasks,
+                    workspaceBackend: legacy.workspaceBackend,
+                    codexModel: legacy.codexModel,
+                }],
+            apiKey: legacy.apiKey,
+        };
+    }
+    catch {
+        throw new Error(`${path} exists but isn't valid JSON — fix or delete it, then run "connect" again.`);
+    }
+}
+function save(config, path = CONFIG_PATH) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+export function addConnection(args) {
+    const existing = loadConfig(args.configFile) ?? { version: 2, pairings: [] };
+    for (const pairing of existing.pairings) {
+        pairing.connections = pairing.connections.filter((candidate) => candidate.connectionId !== args.connection.connectionId);
+    }
+    let pairing = existing.pairings.find((candidate) => samePairing(candidate, args));
+    if (!pairing) {
+        pairing = { url: trimUrl(args.url), token: args.token, workspaceId: args.workspaceId, connections: [] };
+        existing.pairings.push(pairing);
+    }
+    pairing.token = args.token;
+    pairing.connections.push(args.connection);
+    const config = {
+        version: 2,
+        pairings: existing.pairings,
+        apiKey: args.apiKey || existing.apiKey,
+    };
+    save(config, args.configFile);
+    return config;
+}
+export function enableWorkspacePolling(args) {
+    const existing = loadConfig(args.configFile) ?? { version: 2, pairings: [] };
+    let pairing = existing.pairings.find((candidate) => samePairing(candidate, args));
+    if (!pairing) {
+        pairing = { url: trimUrl(args.url), token: args.token, workspaceId: args.workspaceId, connections: [] };
+        existing.pairings.push(pairing);
+    }
+    pairing.token = args.token;
+    pairing.pollWorkspaceTasks = true;
+    pairing.workspaceBackend = args.backend || pairing.workspaceBackend;
+    pairing.codexModel = args.backend === 'codex' ? args.codexModel : pairing.codexModel;
+    const config = {
+        version: 2,
+        pairings: existing.pairings,
+        apiKey: args.apiKey || existing.apiKey,
+    };
+    save(config, args.configFile);
+    return config;
+}
+export function recordWorkspaceId(url, token, workspaceId, configFile) {
+    const config = loadConfig(configFile);
+    if (!config)
+        return null;
+    const pairing = config.pairings.find((candidate) => (normalizeConsoleUrl(candidate.url) === normalizeConsoleUrl(url)
+        && candidate.workspaceId === undefined
+        && candidate.token === token));
+    if (!pairing)
+        return config;
+    pairing.workspaceId = workspaceId;
+    save(config, configFile);
+    return config;
+}
+export function removePairing(url, workspaceId, configFile) {
+    const config = loadConfig(configFile);
+    if (!config)
+        return [];
+    const normalized = normalizeConsoleUrl(url);
+    const removed = config.pairings.filter((pairing) => (normalizeConsoleUrl(pairing.url) === normalized
+        && (workspaceId === undefined || pairing.workspaceId === workspaceId)));
+    if (removed.length === 0)
+        return [];
+    config.pairings = config.pairings.filter((pairing) => !removed.includes(pairing));
+    save(config, configFile);
+    return removed;
+}
+export const configPath = CONFIG_PATH;
+/** Where `connect --repo` keeps the companion's own copies: a `repos` folder next to config.json,
+ *  so a test that points configFile at a temp folder gets temp copies too. */
+export function managedReposDir(configFile = CONFIG_PATH) {
+    return join(dirname(configFile), 'repos');
+}