@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/cli.js

@@ -0,0 +1,1486 @@
+#!/usr/bin/env node
+import Anthropic from '@anthropic-ai/sdk';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { addConnection, configPath, enableWorkspacePolling, loadConfig, managedReposDir, normalizeConsoleUrl, recordWorkspaceId, removePairing, } from './config.js';
+import { CompanionClient, CompanionHttpError, PairingHttpError, } from './http-client.js';
+import { assertIsRepo, checkRepositoryReadiness, currentCommit, GIT_UNAVAILABLE_MESSAGE, REMOTE_TROUBLESHOOTING_HINT, repositoryIdentity, RepositoryIdentityError, repositoryTopLevel, } from './local-scan.js';
+import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runGenericTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runStructuredModelCall, runVerifyModuleTask } from './api-key-caller.js';
+import { runAnalyseShipmentTaskViaCli, runDesignPromptTaskViaCli, runGenerateSpecBatchTaskViaCli, runGenericTaskViaCli, runProposeNewCapabilitiesTaskViaCli, runProposeSkeletonTaskViaCli, runStructuredModelCallViaCli, runVerifyModuleTaskViaCli } from './claude-cli-caller.js';
+import { spawnClaude } from './claude-binary.js';
+import { checkCodexLogin, CODEX_CODE_MODE_MODELS, codexTextModel, defaultCodexHome, runStructuredModelCallViaCodex } from './codex-cli-caller.js';
+import { formatInvestigationReaderDiagnostic, INVESTIGATION_MODEL, runAndReportInvestigation } from './investigation-reader.js';
+import { anthropicTextModel } from './text-model.js';
+import { MappingFailure, runSurfaceMapping, SURFACE_SEED_MODEL } from './surface-mapper.js';
+import { assertSnapshotReadBoundary, createSandbox } from './sandbox.js';
+import { runGitRangeTask } from './git-range.js';
+import { gitAvailable, githubLabel, interactiveFetch, labelFromCopyPath, ManagedRepoError, managedCopyPath, parseGitHubRepo, prepareManagedCopy, readManagedState, relativeTime, removeManagedCopy, watchManagedCopy, } from './managed-repo.js';
+import { isUsageLimitError, UsageLimitPause } from './usage-limit.js';
+import { acquireInstanceLock, installService, isNpxCachePath, releaseInstanceLock, runDaemon, servicePaths, serviceStatus, startService, stopService, uninstallService, } from './service.js';
+const DEFAULT_CODEX_MODEL = 'gpt-6-astra';
+const SURFACE_MAPPING_UNAVAILABLE_STATUSES = new Set([401, 403, 404, 405]);
+let expectedExitReason = null;
+let unexpectedExitReason = null;
+function asError(reason) {
+    return reason instanceof Error ? reason : new Error(String(reason));
+}
+function surfaceMappingUnavailableStatus(reason) {
+    return reason instanceof CompanionHttpError && SURFACE_MAPPING_UNAVAILABLE_STATUSES.has(reason.status)
+        ? reason.status
+        : null;
+}
+function logFatal(label, reason) {
+    const error = asError(reason);
+    console.error(`${label}: ${error.message}`);
+    console.error(error.stack ?? '(no stack available)');
+    return error;
+}
+function installProcessHandlers() {
+    process.on('uncaughtException', (reason) => {
+        const error = logFatal('FATAL uncaught exception', reason);
+        unexpectedExitReason = `uncaught exception: ${error.message}`;
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        const error = logFatal('FATAL unhandled rejection', reason);
+        unexpectedExitReason = `unhandled rejection: ${error.message}`;
+        process.exit(1);
+    });
+    process.on('exit', (code) => {
+        const timestamp = new Date().toISOString();
+        if (unexpectedExitReason) {
+            const reason = /[.!?]$/.test(unexpectedExitReason) ? unexpectedExitReason : `${unexpectedExitReason}.`;
+            console.error(`[${timestamp}] Companion exited unexpectedly (code ${code}): ${reason} Restart it to keep watching for work.`);
+        }
+        else if (expectedExitReason) {
+            const reason = /[.!?]$/.test(expectedExitReason) ? expectedExitReason : `${expectedExitReason}.`;
+            console.log(`[${timestamp}] Companion exited normally (code ${code}): ${reason}`);
+        }
+        else {
+            console.error(`[${timestamp}] Companion exited unexpectedly (code ${code}) without completing its command. Restart it to keep watching for work.`);
+        }
+    });
+}
+/** A flag with nothing after it (end of argv, or the next token is itself another "--flag") is
+ *  treated as a bare boolean ("true") rather than swallowing the following flag as its value —
+ *  needed for --no-run below. Every existing "--flag value" pair still parses exactly as before. */
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a?.startsWith('--')) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                flags[a.slice(2)] = 'true';
+            }
+            else {
+                flags[a.slice(2)] = next;
+                i++;
+            }
+        }
+    }
+    return flags;
+}
+async function checkClaudeCliAvailable() {
+    return new Promise((resolvePromise) => {
+        const child = spawnClaude(['--version']);
+        let out = '';
+        child.stdout?.on('data', (chunk) => (out += chunk.toString()));
+        child.on('error', () => resolvePromise(null)); // e.g. ENOENT — not installed / not on PATH
+        child.on('close', (code) => resolvePromise(code === 0 ? out.trim() : null));
+    });
+}
+const GIT_MISSING_MESSAGE = 'This needs Git. Install it from https://git-scm.com/downloads, then run this command again.';
+const SIGN_IN_NEEDED_HINT = 'GitHub sign-in needed: run truing signin';
+const RECONNECT_IN_CONSOLE_HINT = 'GitHub sign-in needed: Reconnect GitHub in the Console';
+/** Test-only: lets the CLI tests clone from a local bare repo instead of github.com. origin is
+ *  still recorded as the GitHub URL. Ignored outside NODE_ENV=test. */
+function testCloneUrl(repo) {
+    const base = process.env.NODE_ENV === 'test' ? process.env.PC_TEST_GITHUB_CLONE_BASE : undefined;
+    return base ? `${base.replace(/\/+$/, '')}/${repo.owner}/${repo.name}.git` : undefined;
+}
+const restartHint = 'The companion is already running in the background — run "truing stop" then "truing start" so it picks up this new connection.';
+function logRestartHintIfRunning() {
+    if (serviceStatus().running)
+        console.log(restartHint);
+}
+async function resolveLegacyPairings(url) {
+    const config = loadConfig();
+    if (!config)
+        return;
+    for (const pairing of config.pairings) {
+        if (pairing.workspaceId !== undefined || normalizeConsoleUrl(pairing.url) !== normalizeConsoleUrl(url))
+            continue;
+        try {
+            const identity = await new CompanionClient(pairing.url, pairing.token).whoami();
+            recordWorkspaceId(pairing.url, pairing.token, identity.workspaceId);
+        }
+        catch {
+            // An old token that can no longer be verified remains separate from the new Console entry.
+        }
+    }
+}
+function logConnectedConsoles() {
+    const config = loadConfig();
+    if (!config || config.pairings.length < 2)
+        return;
+    console.log(`This computer is now connected to ${config.pairings.length} Consoles: `
+        + `${config.pairings.map((pairing) => pairing.url).join(' and ')}. Each keeps its own projects.`);
+}
+async function cmdConnect(argv) {
+    const f = parseFlags(argv);
+    const url = f.url?.replace(/\/+$/, '');
+    const token = f.token;
+    const connectionId = f.connection;
+    const apiKey = f['api-key'];
+    const backend = (f.backend || 'api-key');
+    const codexModel = f['codex-model'] || DEFAULT_CODEX_MODEL;
+    const background = f.background === 'true';
+    // Pairing on its own does nothing useful — see cmdRun below — so this defaults to starting
+    // right away, which is what someone following the app's own copy-pasted command wants: one
+    // paste, and it's working. --no-run is the escape hatch for pairing a second/third project
+    // before starting one shared `run` for all of them (see the README's own multi-connection note).
+    // --background takes the other route: it installs/reinstalls the login service instead.
+    const shouldRunAfter = f['no-run'] !== 'true';
+    if (background && !shouldRunAfter) {
+        console.error("--background can't be used together with --no-run.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!url || !token) {
+        console.error('Usage: truing connect --url <your Truing link> --token <publicId.secret> --connection <connectionId> ' +
+            '[--path <folder — defaults to the folder you\'re in right now>] [--remote <name>] [--branch <name>] [--backend api-key|cli|codex] [--api-key <your Anthropic key>] [--codex-model <model>] [--background] [--no-run]\n' +
+            '   or: truing connect --url <your Truing link> --token <publicId.secret> [--path <folder>] [--remote <name>] [--branch <name>] [--no-repo] [--backend api-key|cli|codex] [--api-key <your Anthropic key>] [--codex-model <model>] [--background] [--no-run]\n' +
+            '   or: truing connect --url <your Truing link> --token <publicId.secret> --repo <owner/name> [--branch <name>] [--backend api-key|cli|codex] [--api-key <your Anthropic key>] [--codex-model <model>] [--background] [--no-run]');
+        process.exitCode = 1;
+        return;
+    }
+    let managedRepo = null;
+    if (f.repo !== undefined) {
+        const conflicting = ['path', 'connection', 'no-repo', 'remote'].filter((name) => f[name] !== undefined);
+        if (conflicting.length > 0) {
+            console.error(`--repo can't be used together with ${conflicting.map((name) => `--${name}`).join(', ')}. `
+                + 'Use --repo without them and the companion keeps its own copy of the code.');
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            managedRepo = parseGitHubRepo(f.repo);
+        }
+        catch (error) {
+            console.error(error instanceof ManagedRepoError ? error.message : String(error));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (backend !== 'api-key' && backend !== 'cli' && backend !== 'codex') {
+        console.error(`--backend must be "api-key", "cli", or "codex", got "${backend}"`);
+        process.exitCode = 1;
+        return;
+    }
+    if (f['codex-model'] && !validateCodexModel(codexModel))
+        return;
+    if (managedRepo && !await gitAvailable()) {
+        console.error(GIT_MISSING_MESSAGE);
+        process.exitCode = 1;
+        return;
+    }
+    if (backend === 'codex') {
+        const status = await checkCodexLogin(defaultCodexHome());
+        if (status !== 'logged-in') {
+            logCodexReadiness(status);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (!connectionId) {
+        if (backend === 'cli') {
+            const version = await checkClaudeCliAvailable();
+            if (!version) {
+                console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`Found Claude Code: ${version}`);
+        }
+        const client = new CompanionClient(url, token);
+        let workspaceId;
+        try {
+            ({ workspaceId } = await client.whoami());
+        }
+        catch {
+            console.error('Could not verify the companion token. Double check that you copied the whole token, including the part after the dot.');
+            process.exitCode = 1;
+            return;
+        }
+        let managedPath = null;
+        if (managedRepo) {
+            try {
+                let reconnectMessageShown = false;
+                const label = githubLabel(managedRepo);
+                const copy = await prepareManagedCopy({
+                    repo: managedRepo,
+                    branch: f.branch,
+                    reposDir: managedReposDir(),
+                    cloneUrl: testCloneUrl(managedRepo),
+                    getToken: async () => {
+                        const response = await client.githubToken(label);
+                        if (response.reason === 'github_reconnect_needed' && !reconnectMessageShown) {
+                            reconnectMessageShown = true;
+                            console.error(response.message ?? 'Reconnect GitHub in the Console.');
+                        }
+                        return response.token;
+                    },
+                });
+                managedPath = copy.path;
+                if (copy.fetchOk === false) {
+                    console.error(reconnectMessageShown
+                        ? `Couldn't bring the copy of ${githubLabel(managedRepo)} up to date just now. The companion keeps trying; if it keeps failing, reconnect GitHub in the Console.`
+                        : `Couldn't bring the copy of ${githubLabel(managedRepo)} up to date just now. The companion keeps trying; if it keeps failing, run: truing signin`);
+                }
+            }
+            catch (error) {
+                console.error(error instanceof ManagedRepoError ? error.message : `Couldn't copy ${githubLabel(managedRepo)} from GitHub.`);
+                process.exitCode = 1;
+                return;
+            }
+        }
+        try {
+            await resolveLegacyPairings(url);
+            enableWorkspacePolling({
+                url,
+                token,
+                workspaceId,
+                apiKey: backend === 'codex' ? undefined : apiKey,
+                backend,
+                codexModel: backend === 'codex' && f['codex-model'] ? codexModel : undefined,
+            });
+        }
+        catch {
+            console.error('Could not save the companion configuration. Check that your user account can write its configuration folder.');
+            process.exitCode = 1;
+            return;
+        }
+        const requestedFolder = managedPath ?? resolve(f.path || '.');
+        const topLevel = f['no-repo'] === 'true' ? null : await repositoryTopLevel(requestedFolder);
+        let registered = false;
+        if (topLevel) {
+            try {
+                const { remote, ...identity } = await repositoryIdentity(topLevel, {
+                    remote: managedRepo ? 'origin' : f.remote,
+                    branch: f.branch,
+                });
+                const { connection } = await client.registerConnection(identity);
+                addConnection({
+                    url,
+                    token,
+                    workspaceId,
+                    connection: {
+                        connectionId: connection.id,
+                        repoPath: topLevel,
+                        backend,
+                        codexModel: backend === 'codex' && f['codex-model'] ? codexModel : undefined,
+                        remote,
+                        ...(managedRepo ? { label: githubLabel(managedRepo), managed: true } : {}),
+                    },
+                    apiKey: backend === 'codex' ? undefined : apiKey,
+                });
+                console.log(managedRepo
+                    ? `Connected ${githubLabel(managedRepo)}. The companion keeps its own copy of the code up to date. You never need to open it or pull it.`
+                    : `Connected ${connection.repo} (this folder).`);
+                registered = true;
+            }
+            catch (error) {
+                if (error instanceof RepositoryIdentityError) {
+                    console.error(`${error.code}: ${error.message}`);
+                    console.error(REMOTE_TROUBLESHOOTING_HINT);
+                }
+                else if (error instanceof PairingHttpError) {
+                    console.error(`${error.code}: ${error.message}`);
+                }
+                else {
+                    console.error('registration_failed: Could not register this repository with the console.');
+                }
+            }
+        }
+        else if (f['no-repo'] !== 'true') {
+            console.log("No project folder here — to connect your code, run this same command inside your project's folder.");
+        }
+        if (!registered) {
+            try {
+                await client.recordPairingOutcome('workspace_only');
+            }
+            catch (error) {
+                console.error(error instanceof PairingHttpError
+                    ? `${error.code}: ${error.message}`
+                    : 'pairing_outcome_failed: Setup completion could not be confirmed. Retry this command or return to the console.');
+            }
+            console.log('Connected for workspace tasks only.');
+        }
+        logConnectedConsoles();
+        if (!await finishConnect({ background, shouldRunAfter, safeStartupDiagnostics: true }))
+            process.exitCode = 1;
+        return;
+    }
+    // --path is optional — defaults to wherever this command is actually run from, so "open a
+    // terminal in your project's folder, paste this" just works without typing a path at all.
+    const repoPath = resolve(f.path || '.');
+    try {
+        await assertIsRepo(repoPath);
+    }
+    catch (err) {
+        console.error((err instanceof Error ? err.message : String(err)) + ' Run this from inside your project\'s folder, or pass --path <folder>.');
+        process.exitCode = 1;
+        return;
+    }
+    if (backend === 'cli') {
+        const version = await checkClaudeCliAvailable();
+        if (!version) {
+            console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
+            process.exitCode = 1;
+            return;
+        }
+        console.log(`Found Claude Code: ${version}`);
+    }
+    const client = new CompanionClient(url, token);
+    let workspaceId;
+    try {
+        ({ workspaceId } = await client.whoami());
+    }
+    catch (err) {
+        console.error(`Hmm, that didn't work — could not verify your token against ${url}. Double check you copied the ` +
+            `WHOLE thing, including the part after the dot.`, err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await resolveLegacyPairings(url);
+        addConnection({
+            url,
+            token,
+            workspaceId,
+            connection: {
+                connectionId,
+                repoPath,
+                backend,
+                codexModel: backend === 'codex' && f['codex-model'] ? codexModel : undefined,
+                remote: f.remote,
+            },
+            apiKey: backend === 'codex' ? undefined : apiKey,
+        });
+    }
+    catch {
+        console.error('Could not save the companion configuration. Check that your user account can write its configuration folder.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Connected! This computer will now read this project's code and run AI calls for it. (Saved to ${configPath}.)`);
+    logConnectedConsoles();
+    if (!await finishConnect({ background, shouldRunAfter }))
+        process.exitCode = 1;
+}
+/** How often an idle connection is re-polled when nothing was claimed — a short client-side
+ *  poll, not a server-held long-poll (see the plan's own reasoning: this app has already been
+ *  burned once by a proxy timing out a held-open request). */
+const TEST_POLL_MS = process.env.NODE_ENV === 'test'
+    ? Number(process.env.PC_TEST_COMPANION_POLL_MS)
+    : Number.NaN;
+const IDLE_POLL_MS = Number.isFinite(TEST_POLL_MS) && TEST_POLL_MS > 0 ? TEST_POLL_MS : 5000;
+const REPOSITORY_RECHECK_MS = process.env.NODE_ENV === 'test' && Number.isFinite(TEST_POLL_MS) && TEST_POLL_MS > 0
+    ? TEST_POLL_MS
+    : 60_000;
+export const INVESTIGATION_POLL_BACKOFF_CAP_MS = 5 * 60_000;
+/** How often to extend a claimed task's lease while it's in flight — comfortably inside the
+ *  server's ~2-minute lease window (server/store.ts's LOCAL_TASK_LEASE_MS). */
+const HEARTBEAT_MS = 30_000;
+/** How long to wait before retrying after something escapes the per-operation error handling. */
+const LOOP_RECOVERY_DELAY_MS = 1000;
+/** A quiet proof-of-life while no task is claimed. */
+const IDLE_STATUS_MS = 5 * 60_000;
+export function backendRequirements(backends) {
+    return {
+        needsApiKey: backends.some((backend) => backend === 'api-key'),
+        needsCli: backends.some((backend) => backend === 'cli'),
+    };
+}
+export function createBackendRuntime(config, anthropic, createCodexTextModel = codexTextModel) {
+    let usage = null;
+    const codexOptions = config.backend === 'codex'
+        ? { model: config.codexModel ?? DEFAULT_CODEX_MODEL, codexHome: defaultCodexHome() }
+        : null;
+    // Server task tiers are Claude model names, and there is no evidence they map to ChatGPT-plan
+    // model tiers. Keep one owner-selected Codex model for every task; request effort still passes
+    // through unchanged inside codexTextModel.
+    const textModel = config.backend === 'codex'
+        ? createCodexTextModel({
+            ...codexOptions,
+            onUsage: (callUsage) => {
+                if (!callUsage)
+                    return;
+                usage ??= {};
+                for (const [name, value] of Object.entries(callUsage)) {
+                    usage[name] = (usage[name] ?? 0) + value;
+                }
+            },
+        })
+        : config.backend === 'api-key'
+            ? anthropicTextModel(anthropic)
+            : null;
+    return {
+        backend: config.backend,
+        textModel,
+        codexOptions,
+        takeCodexUsage() {
+            const current = usage;
+            usage = null;
+            return current;
+        },
+    };
+}
+export function codexReadinessLines(status) {
+    if (status === 'not-installed') {
+        return ['This needs the Codex CLI installed first: npm install -g @openai/codex'];
+    }
+    return [
+        'Codex needs a one-time login for the companion\'s own home:',
+        '  Windows PowerShell: New-Item -ItemType Directory -Force "$HOME\\.product-console-companion\\codex-home" | Out-Null; $env:CODEX_HOME="$HOME\\.product-console-companion\\codex-home"; codex login; Remove-Item Env:CODEX_HOME',
+        '  macOS/Linux: mkdir -p "$HOME/.product-console-companion/codex-home" && CODEX_HOME="$HOME/.product-console-companion/codex-home" codex login',
+        'This separate login keeps your own ~/.codex instructions out of the companion\'s calls.',
+    ];
+}
+function logCodexReadiness(status) {
+    for (const line of codexReadinessLines(status))
+        console.error(line);
+}
+function validateCodexModel(model) {
+    if (CODEX_CODE_MODE_MODELS.includes(model))
+        return true;
+    console.error(`--codex-model must be one of: ${CODEX_CODE_MODE_MODELS.join(', ')}; got "${model}". ` +
+        'Only these models were verified to refuse tool use when their tools are switched off.');
+    process.exitCode = 1;
+    return false;
+}
+export function nextInvestigationPollBackoff(consecutiveFailures, succeeded) {
+    const nextFailures = succeeded ? 0 : consecutiveFailures + 1;
+    return {
+        consecutiveFailures: nextFailures,
+        delayMs: nextFailures === 0
+            ? 0
+            : Math.min(IDLE_POLL_MS * (2 ** (nextFailures - 1)), INVESTIGATION_POLL_BACKOFF_CAP_MS),
+    };
+}
+export function buildReadinessReport(connections, backendUnavailable, repositoryReadiness) {
+    return Object.fromEntries(connections.map((connection) => {
+        if (backendUnavailable.has(connection.connectionId)) {
+            return [connection.connectionId, 'backend_unavailable'];
+        }
+        return [
+            connection.connectionId,
+            repositoryReadiness.get(connection.connectionId)?.readiness.state === 'ready'
+                ? 'ready'
+                : 'not_ready',
+        ];
+    }));
+}
+function isUnknownConnectionError(error) {
+    return error instanceof CompanionHttpError
+        && (error.status === 400 || error.status === 404)
+        && /foreign_connection_id|unknown connectionid|connection.*unknown/i.test(error.message);
+}
+export async function reportLoopReadiness(client, report, state, logger = console) {
+    if (!state.enabled || Object.keys(report).length === 0)
+        return 'continue';
+    try {
+        await client.reportReadiness(report);
+    }
+    catch (error) {
+        if (error instanceof CompanionHttpError && error.status === 401)
+            return 'token_rejected';
+        if (isUnknownConnectionError(error)) {
+            const entries = Object.entries(report);
+            if (entries.length === 1) {
+                state.foreignConnectionIds?.add(entries[0][0]);
+                return 'continue';
+            }
+            for (const [connectionId, readiness] of entries) {
+                try {
+                    await client.reportReadiness({ [connectionId]: readiness });
+                }
+                catch (singleError) {
+                    if (singleError instanceof CompanionHttpError && singleError.status === 401)
+                        return 'token_rejected';
+                    if (isUnknownConnectionError(singleError))
+                        state.foreignConnectionIds?.add(connectionId);
+                }
+            }
+            return 'continue';
+        }
+        if (error instanceof CompanionHttpError && (error.status === 404 || error.status === 405)) {
+            const key = `unsupported:${error.status}`;
+            if (!state.loggedErrors.has(key)) {
+                logger.error(`Readiness reporting is not available on this server (HTTP ${error.status}); continuing without it.`);
+                state.loggedErrors.add(key);
+            }
+            state.enabled = false;
+            return 'continue';
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const key = error instanceof CompanionHttpError ? `${error.status}:${message}` : message;
+        if (!state.loggedErrors.has(key)) {
+            logger.error(`Readiness report failed: ${message}`);
+            state.loggedErrors.add(key);
+        }
+    }
+    return 'continue';
+}
+const EXECUTION_FAILURE_REASONS = new Set([
+    'reader_crashed',
+    'budget_exhausted',
+    'backend_incompatible',
+    'contention_timeout',
+    'fetch_failed',
+    'source_identity_unavailable',
+]);
+function investigationResultLog(result, validationRejectedObligationIds) {
+    const outcomeCounts = new Map();
+    const reasonCounts = new Map();
+    for (const assessment of result.assessments) {
+        outcomeCounts.set(assessment.outcome, (outcomeCounts.get(assessment.outcome) ?? 0) + 1);
+        if (assessment.outcome === 'not_established' && assessment.outcomeReason) {
+            reasonCounts.set(assessment.outcomeReason, (reasonCounts.get(assessment.outcomeReason) ?? 0) + 1);
+        }
+    }
+    const outcomes = [...outcomeCounts].map(([outcome, count]) => `${outcome}=${count}`).join(', ');
+    const reasons = [...reasonCounts].map(([reason, count]) => `${reason}=${count}`).join(', ');
+    const assessmentCount = `${result.assessments.length} assessment${result.assessments.length === 1 ? '' : 's'}`;
+    const evidenceCount = `${result.evidence.length} evidence row${result.evidence.length === 1 ? '' : 's'}`;
+    const breakdown = `${outcomes}${reasons ? `; reasons: ${reasons}` : ''}`;
+    const allExecutionFailures = result.assessments.length > 0 && result.assessments.every((assessment) => assessment.outcome === 'not_established'
+        && !!assessment.outcomeReason
+        && EXECUTION_FAILURE_REASONS.has(assessment.outcomeReason));
+    const allValidationRejections = result.assessments.length > 0 && result.assessments.every((assessment) => validationRejectedObligationIds.has(assessment.obligationId));
+    return allValidationRejections
+        ? {
+            level: 'error',
+            message: `  VALIDATION DISAGREEMENT — rejected model answers for all ${assessmentCount}; ${evidenceCount}; outcomes: ${breakdown}`,
+        }
+        : allExecutionFailures
+            ? {
+                level: 'error',
+                message: `  OPERATIONAL FAILURE — reported ${assessmentCount} with ${evidenceCount}; outcomes: ${breakdown}`,
+            }
+            : {
+                level: 'log',
+                message: `  done — reported ${assessmentCount} with ${evidenceCount}; outcomes: ${breakdown}`,
+            };
+}
+export function logInvestigationResult(result, output = console, validationRejectedObligationIds = new Set()) {
+    const outcomeLog = investigationResultLog(result, validationRejectedObligationIds);
+    output[outcomeLog.level](outcomeLog.message);
+}
+export function logInvestigationDiagnostic(diagnostic, output = console) {
+    if (diagnostic.kind === 'model_call_failed' && diagnostic.message.includes('CodexToolUseAttempted')) {
+        output.error(`  TOOL USE BLOCKED — ${diagnostic.message}`);
+        return;
+    }
+    output.error(formatInvestigationReaderDiagnostic(diagnostic));
+}
+export function taskRunnerFor(backend, kind) {
+    if (backend === 'cli') {
+        if (kind === 'verify_module')
+            return runVerifyModuleTaskViaCli;
+        if (kind === 'generate_spec_batch')
+            return runGenerateSpecBatchTaskViaCli;
+        if (kind === 'propose_skeleton')
+            return runProposeSkeletonTaskViaCli;
+        if (kind === 'propose_new_capabilities')
+            return runProposeNewCapabilitiesTaskViaCli;
+        if (kind === 'design_prompt')
+            return runDesignPromptTaskViaCli;
+        if (kind === 'analyse_shipment')
+            return runAnalyseShipmentTaskViaCli;
+        return runGenericTaskViaCli;
+    }
+    if (kind === 'verify_module')
+        return runVerifyModuleTask;
+    if (kind === 'generate_spec_batch')
+        return runGenerateSpecBatchTask;
+    if (kind === 'propose_skeleton')
+        return runProposeSkeletonTask;
+    if (kind === 'propose_new_capabilities')
+        return runProposeNewCapabilitiesTask;
+    if (kind === 'design_prompt')
+        return runDesignPromptTask;
+    if (kind === 'analyse_shipment')
+        return runAnalyseShipmentTask;
+    return runGenericTask;
+}
+export async function runTask(task, runtime, repoPath, connection) {
+    if (task.kind === 'git_range') {
+        if (!connection)
+            return { result: { ok: false, code: 'history_failed' }, filesRead: [] };
+        return runGitRangeTask(task, repoPath, connection);
+    }
+    const runner = taskRunnerFor(runtime.backend, task.kind);
+    const payload = task.payload;
+    if (payload.connectionless === true) {
+        return runtime.backend === 'cli'
+            ? runner(task, repoPath)
+            : runner(runtime.textModel, task, repoPath);
+    }
+    if (typeof payload.snapshotSha !== 'string')
+        throw new Error('snapshot_unavailable');
+    let sandbox;
+    try {
+        sandbox = await createSandbox(repoPath, payload.snapshotSha);
+    }
+    catch {
+        throw new Error('snapshot_unavailable');
+    }
+    if (sandbox.obtainedBy === 'unavailable')
+        throw new Error('snapshot_unavailable');
+    try {
+        await assertSnapshotReadBoundary(sandbox.path);
+    }
+    catch {
+        await sandbox.cleanup();
+        throw new Error('snapshot_unavailable');
+    }
+    try {
+        const outcome = runtime.backend === 'cli'
+            ? await runner(task, sandbox.path)
+            : await runner(runtime.textModel, task, sandbox.path);
+        return { ...outcome, snapshot: { sha: sandbox.resolvedCommit } };
+    }
+    finally {
+        await sandbox.cleanup();
+    }
+}
+function formatCodexUsage(usage) {
+    if (!usage)
+        return 'unavailable';
+    return Object.entries(usage).map(([name, value]) => `${name}=${value}`).join(', ');
+}
+export async function runOneTask(runtime, client, repoPath, task, connection, output = console) {
+    runtime.takeCodexUsage();
+    if (runtime.backend === 'codex') {
+        output.log(`[${new Date().toISOString()}] claimed ${task.kind} task ${task.id} via codex (dollar budget $${task.maxBudgetUsd.toFixed(2)} is not enforced on this backend)`);
+    }
+    else {
+        output.log(`[${new Date().toISOString()}] claimed ${task.kind} task ${task.id} via ${runtime.backend} (budget $${task.maxBudgetUsd.toFixed(2)})`);
+    }
+    const heartbeat = setInterval(() => {
+        void client.heartbeat(task.id).catch((err) => output.error('  heartbeat warning:', err instanceof Error ? err.message : err));
+    }, HEARTBEAT_MS);
+    try {
+        const { result, filesRead, snapshot } = await runTask(task, runtime, repoPath, connection);
+        clearInterval(heartbeat);
+        if (task.kind === 'git_range')
+            await client.reportGitRangeResult(task.id, result);
+        else
+            await client.reportResult(task.id, result, filesRead, snapshot);
+        const done = `  done — reported result (${filesRead.length} file${filesRead.length === 1 ? '' : 's'} read)`;
+        output.log(runtime.backend === 'codex'
+            ? `${done}; token usage: ${formatCodexUsage(runtime.takeCodexUsage())}; dollar budget is not enforced (Codex reports tokens and has no cost cap)`
+            : done);
+        return null;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (runtime.backend === 'codex' && message.includes('CodexToolUseAttempted')) {
+            output.error(`  TOOL USE BLOCKED — ${message}`);
+        }
+        else {
+            output.error('  failed:', message);
+        }
+        try {
+            await client.reportError(task.id, message);
+        }
+        catch (reportErr) {
+            output.error('  could not even report the error back:', reportErr instanceof Error ? reportErr.message : reportErr);
+        }
+        return runtime.backend === 'cli' && isUsageLimitError(err) ? message : null;
+    }
+    finally {
+        clearInterval(heartbeat);
+    }
+}
+export function backendForInvestigation(request, connections) {
+    for (const source of request.requestedSources) {
+        const configured = connections.find((connection) => connection.connectionId === source.connectionId);
+        if (configured)
+            return configured.backend;
+    }
+    // No configured source means pass 0 will abstain before a model call, so this fallback is inert.
+    return 'api-key';
+}
+export function structuredModelCallerForRuntime(runtime, anthropic, callViaCodex = runStructuredModelCallViaCodex) {
+    if (runtime.backend === 'cli')
+        return runStructuredModelCallViaCli;
+    if (runtime.backend === 'codex') {
+        return (request) => callViaCodex(request, runtime.codexOptions);
+    }
+    return (request) => runStructuredModelCall(anthropic, request);
+}
+async function runOneInvestigation(anthropic, client, connections, runtimes, request, output = console) {
+    const backend = backendForInvestigation(request, connections);
+    output.log(`[${new Date().toISOString()}] claimed investigation ${request.investigationId} attempt ${request.attempt} via ${backend} (${request.obligations.length} obligation${request.obligations.length === 1 ? '' : 's'})`);
+    if (Date.now() >= Date.parse(request.claimExpiresAt)) {
+        output.error(`  CLAIM LEASE WARNING: ${request.investigationId} was already expired at ${request.claimExpiresAt}; the result may be rejected.`);
+    }
+    const runtime = request.requestedSources
+        .map((source) => runtimes.get(source.connectionId))
+        .find((candidate) => !!candidate);
+    const baseCallModel = runtime
+        ? structuredModelCallerForRuntime(runtime, anthropic)
+        : (modelRequest) => runStructuredModelCall(anthropic, modelRequest);
+    let usageLimitMessage = null;
+    const callModel = backend === 'cli'
+        ? async (modelRequest) => {
+            if (usageLimitMessage)
+                throw new Error(usageLimitMessage);
+            try {
+                return await baseCallModel(modelRequest);
+            }
+            catch (error) {
+                if (isUsageLimitError(error)) {
+                    usageLimitMessage = error instanceof Error ? error.message : String(error);
+                }
+                throw error;
+            }
+        }
+        : baseCallModel;
+    const validationRejectedObligationIds = new Set();
+    try {
+        const result = await runAndReportInvestigation(request, connections, callModel, async (envelope) => {
+            if (Date.now() >= Date.parse(request.claimExpiresAt)) {
+                output.error(`  CLAIM LEASE WARNING: reading ${request.investigationId} outlived its ${request.claimExpiresAt} lease; attempting the honest result without hiding the expiry.`);
+            }
+            const acknowledgment = await client.reportInvestigationResult(request.investigationId, envelope);
+            if (acknowledgment.status === 'rejected') {
+                throw new Error(acknowledgment.error || acknowledgment.note || 'server rejected the reader result');
+            }
+        }, (diagnostic) => {
+            if (diagnostic.kind === 'validation_rejection') {
+                for (const obligationId of diagnostic.obligationIds) {
+                    validationRejectedObligationIds.add(obligationId);
+                }
+            }
+            logInvestigationDiagnostic(diagnostic, output);
+        }, {
+            backend,
+            model: runtime?.backend === 'codex'
+                ? runtime.codexOptions?.model
+                : INVESTIGATION_MODEL,
+        });
+        logInvestigationResult(result, output, validationRejectedObligationIds);
+    }
+    catch (error) {
+        output.error(`  RESULT NOT DELIVERED for ${request.investigationId} attempt ${request.attempt}; no automatic retry will be made and the claim must expire:`, error instanceof Error ? error.message : error);
+    }
+    return usageLimitMessage;
+}
+async function runOneSurfaceMapping(anthropic, client, connection, runtime, job, output = console) {
+    output.log(`[${new Date().toISOString()}] claimed surface mapping ${job.jobId} attempt ${job.attempt} via ${runtime.backend}`);
+    try {
+        const manifest = await runSurfaceMapping({
+            claim: job,
+            repoPath: connection.repoPath,
+            callModel: structuredModelCallerForRuntime(runtime, anthropic),
+            execution: {
+                backend: runtime.backend,
+                model: runtime.backend === 'codex' ? runtime.codexOptions?.model ?? DEFAULT_CODEX_MODEL : SURFACE_SEED_MODEL,
+            },
+        });
+        let acknowledgment;
+        try {
+            acknowledgment = await client.reportSurfaceMappingResult(job, manifest);
+        }
+        catch (error) {
+            const status = surfaceMappingUnavailableStatus(error);
+            if (status !== null) {
+                output.error(`  automatic mapping result could not be reported (HTTP ${status}); abandoning the job so its lease can expire.`);
+                return null;
+            }
+            throw error;
+        }
+        output.log(`  automatic map ${acknowledgment.mapId} delivered (${manifest.expansion.files.length} files, expansion ${manifest.expansion.status})`);
+        return null;
+    }
+    catch (error) {
+        const usageLimitMessage = runtime.backend === 'cli' && isUsageLimitError(error)
+            ? (error instanceof Error ? error.message : String(error))
+            : null;
+        const report = error instanceof MappingFailure
+            ? { kind: error.kind, code: error.code, detail: error.message }
+            : {
+                kind: 'transient',
+                code: 'mapper_crashed',
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        output.error(`  surface mapping ${job.jobId} failed (${report.code}): ${report.detail}`);
+        try {
+            await client.reportSurfaceMappingError(job, report);
+        }
+        catch (reportError) {
+            const status = surfaceMappingUnavailableStatus(reportError);
+            if (status !== null) {
+                output.error(`  automatic mapping error could not be reported (HTTP ${status}); abandoning the job so its lease can expire.`);
+                return usageLimitMessage;
+            }
+            output.error('  could not report the mapping error:', reportError instanceof Error ? reportError.message : reportError);
+        }
+        return usageLimitMessage;
+    }
+}
+function pairingPrefix(pairing) {
+    try {
+        return `[${new URL(pairing.url).host}]`;
+    }
+    catch {
+        return `[${pairing.url}]`;
+    }
+}
+async function runPairing(pairing, options) {
+    const prefix = options.multiple ? `${pairingPrefix(pairing)} ` : '';
+    const log = (...values) => console.log(prefix + String(values[0] ?? ''), ...values.slice(1));
+    const error = (...values) => console.error(prefix + String(values[0] ?? ''), ...values.slice(1));
+    const warn = (...values) => console.warn(prefix + String(values[0] ?? ''), ...values.slice(1));
+    const client = new CompanionClient(pairing.url, pairing.token);
+    const tokenRejected = () => {
+        error(`The Console at ${pairing.url} no longer accepts this computer's token — stopped working for it. Pair again from that Console to reconnect.`);
+        return 'token_rejected';
+    };
+    if (options.multiple) {
+        let failures = 0;
+        while (!options.shouldStop()) {
+            try {
+                await client.whoami();
+                break;
+            }
+            catch (reason) {
+                if (reason instanceof CompanionHttpError && reason.status === 401)
+                    return tokenRejected();
+                const backoff = nextInvestigationPollBackoff(failures, false);
+                failures = backoff.consecutiveFailures;
+                error(`Could not reach the Console at ${pairing.url} — retrying in ${backoff.delayMs / 1000}s.`);
+                await new Promise((done) => setTimeout(done, backoff.delayMs));
+            }
+        }
+        if (options.shouldStop())
+            return 'stopped';
+    }
+    else {
+        await client.whoami();
+    }
+    const workspaceBackend = pairing.workspaceBackend ?? 'api-key';
+    const activeConnections = pairing.connections.filter((connection) => !options.unavailableConnections.has(connection.connectionId));
+    for (const connection of activeConnections) {
+        if (connection.managed) {
+            const label = connection.label ?? labelFromCopyPath(connection.repoPath);
+            watchManagedCopy(connection.repoPath, label, (message) => error(`[${new Date().toISOString()}] ${message}`), () => client.githubToken(label));
+        }
+    }
+    const runtimes = new Map(activeConnections.map((connection) => [
+        connection.connectionId,
+        createBackendRuntime(connection, options.anthropic),
+    ]));
+    const workspaceRuntime = pairing.pollWorkspaceTasks && (workspaceBackend !== 'codex' || options.codexAvailable)
+        ? createBackendRuntime({ backend: workspaceBackend, codexModel: pairing.codexModel }, options.anthropic)
+        : null;
+    const repositoryReadiness = new Map();
+    for (const connection of activeConnections) {
+        repositoryReadiness.set(connection.connectionId, {
+            readiness: await checkRepositoryReadiness(connection.repoPath),
+            checkedAt: Date.now(),
+        });
+    }
+    if (activeConnections.length !== pairing.connections.length && activeConnections.length > 0) {
+        error('Skipping investigation polling while a configured Codex connection is unavailable, so the companion cannot claim an investigation it cannot run.');
+    }
+    const projectCount = activeConnections.length;
+    const watching = workspaceRuntime
+        ? `${projectCount > 0 ? `${projectCount} project${projectCount === 1 ? '' : 's'} and ` : ''}workspace-level tasks`
+        : `${projectCount} project${projectCount === 1 ? '' : 's'}`;
+    log(`Connected to ${pairing.url}. Watching ${watching}:`);
+    for (const connection of activeConnections) {
+        const readiness = repositoryReadiness.get(connection.connectionId).readiness;
+        if (readiness.state === 'ready') {
+            const sha = await currentCommit(connection.repoPath).catch(() => '(unknown)');
+            log(options.safeStartupDiagnostics
+                ? `  - ${connection.connectionId} @ ${sha.slice(0, 7)} (${connection.backend})`
+                : `  - ${connection.connectionId} → ${connection.repoPath} @ ${sha.slice(0, 7)} (${connection.backend})`);
+        }
+        else {
+            const summary = options.safeStartupDiagnostics
+                ? (readiness.state === 'git_unavailable' ? GIT_UNAVAILABLE_MESSAGE : 'project folder is not ready')
+                : readiness.state === 'repository_missing' ? 'project folder missing' : readiness.reason;
+            log(options.safeStartupDiagnostics
+                ? `  - ${connection.connectionId} (not ready: ${summary}) (${connection.backend})`
+                : `  - ${connection.connectionId} → ${connection.repoPath} (not ready: ${summary}) (${connection.backend})`);
+            if (readiness.state === 'repository_missing') {
+                error(options.safeStartupDiagnostics
+                    ? `[${new Date().toISOString()}] Repository not ready for ${connection.connectionId}.`
+                    : `[${new Date().toISOString()}] Repository not ready for ${connection.connectionId}: ${readiness.reason}`);
+            }
+        }
+    }
+    if (workspaceRuntime)
+        log(`  - workspace-level (connection-less / PRD-only) tasks (${workspaceBackend})`);
+    log('Waiting for work — leave this running. Ctrl+C any time to stop.');
+    let lastIdleStatusAt = Date.now();
+    let investigationPollFailures = 0;
+    let nextInvestigationPollAt = 0;
+    let surfaceMappingPollingEnabled = true;
+    const skippedConnections = new Set();
+    const loggedSkippedConnections = new Set();
+    const readinessReporting = {
+        enabled: true,
+        loggedErrors: new Set(),
+        foreignConnectionIds: skippedConnections,
+    };
+    const skipConnection = (connectionId) => {
+        skippedConnections.add(connectionId);
+        if (loggedSkippedConnections.has(connectionId))
+            return;
+        loggedSkippedConnections.add(connectionId);
+        error(`Project ${connectionId} isn't part of the workspace at ${pairing.url} anymore — skipping it. Run connect again from that project's folder to re-add it.`);
+    };
+    while (!options.shouldStop()) {
+        try {
+            let claimedAny = false;
+            const pollableConnections = activeConnections.filter((connection) => !skippedConnections.has(connection.connectionId));
+            const readyConnections = [];
+            const readinessNow = Date.now();
+            for (const connection of pollableConnections) {
+                if (options.shouldStop())
+                    break;
+                let cached = repositoryReadiness.get(connection.connectionId);
+                if (readinessNow - cached.checkedAt >= REPOSITORY_RECHECK_MS) {
+                    const next = await checkRepositoryReadiness(connection.repoPath);
+                    if (next.state !== cached.readiness.state) {
+                        if (next.state === 'ready') {
+                            log(`[${new Date().toISOString()}] Repository ready for ${connection.connectionId}; resuming repository-aware polling.`);
+                        }
+                        else {
+                            error(options.safeStartupDiagnostics
+                                ? `[${new Date().toISOString()}] Repository not ready for ${connection.connectionId}.`
+                                : `[${new Date().toISOString()}] Repository not ready for ${connection.connectionId}: ${next.reason}`);
+                        }
+                    }
+                    cached = { readiness: next, checkedAt: readinessNow };
+                    repositoryReadiness.set(connection.connectionId, cached);
+                }
+                if (cached.readiness.state === 'ready')
+                    readyConnections.push(connection);
+            }
+            const readinessOutcome = await reportLoopReadiness(client, buildReadinessReport(pollableConnections, options.unavailableConnections, repositoryReadiness), readinessReporting, { error });
+            for (const connectionId of [...skippedConnections])
+                skipConnection(connectionId);
+            if (readinessOutcome === 'token_rejected')
+                return tokenRejected();
+            let usageClaimLimit = options.usageLimitPause.claimLimit();
+            const mayClaim = () => usageClaimLimit === null || usageClaimLimit > 0;
+            const recordCompletedClaim = (usageLimitMessage) => {
+                if (usageClaimLimit !== null)
+                    usageClaimLimit--;
+                if (usageLimitMessage) {
+                    options.usageLimitPause.pause(usageLimitMessage);
+                    usageClaimLimit = 0;
+                }
+            };
+            for (const connection of readyConnections) {
+                if (options.shouldStop() || !mayClaim())
+                    break;
+                if (skippedConnections.has(connection.connectionId))
+                    continue;
+                if (surfaceMappingPollingEnabled) {
+                    try {
+                        const mapping = await client.claimNextSurfaceMapping(connection.connectionId);
+                        if (mapping.job) {
+                            claimedAny = true;
+                            recordCompletedClaim(await runOneSurfaceMapping(options.anthropic, client, connection, runtimes.get(connection.connectionId), mapping.job, { log, error }));
+                        }
+                    }
+                    catch (reason) {
+                        if (reason instanceof CompanionHttpError && reason.status === 401)
+                            return tokenRejected();
+                        if (isUnknownConnectionError(reason)) {
+                            skipConnection(connection.connectionId);
+                            continue;
+                        }
+                        const status = surfaceMappingUnavailableStatus(reason);
+                        if (status !== null) {
+                            error(`Automatic mapping is not available on this server (HTTP ${status}); continuing without it.`);
+                            surfaceMappingPollingEnabled = false;
+                        }
+                        else {
+                            error(`Surface-mapping poll failed for ${connection.connectionId}:`, reason instanceof Error ? reason.message : reason);
+                        }
+                    }
+                }
+                if (!mayClaim() || skippedConnections.has(connection.connectionId))
+                    continue;
+                try {
+                    const claim = await client.claimNext(connection.connectionId);
+                    if (!claim.task)
+                        continue;
+                    claimedAny = true;
+                    recordCompletedClaim(await runOneTask(runtimes.get(connection.connectionId), client, connection.repoPath, claim.task, connection, { log, error }));
+                }
+                catch (reason) {
+                    if (reason instanceof CompanionHttpError && reason.status === 401)
+                        return tokenRejected();
+                    if (isUnknownConnectionError(reason)) {
+                        skipConnection(connection.connectionId);
+                        continue;
+                    }
+                    error(`Poll failed for ${connection.connectionId}:`, reason instanceof Error ? reason.message : reason);
+                }
+            }
+            if (!options.shouldStop() && workspaceRuntime && mayClaim()) {
+                try {
+                    const claim = await client.claimNext();
+                    if (claim.task) {
+                        claimedAny = true;
+                        recordCompletedClaim(await runOneTask(workspaceRuntime, client, process.cwd(), claim.task, undefined, { log, error }));
+                    }
+                }
+                catch (reason) {
+                    if (reason instanceof CompanionHttpError && reason.status === 401)
+                        return tokenRejected();
+                    error('Workspace-level poll failed:', reason instanceof Error ? reason.message : reason);
+                }
+            }
+            const remainingConfigured = pairing.connections.filter((connection) => !skippedConnections.has(connection.connectionId));
+            if (!options.shouldStop() && mayClaim() && readyConnections.length > 0
+                && readyConnections.length === pollableConnections.length
+                && pollableConnections.length === remainingConfigured.length
+                && Date.now() >= nextInvestigationPollAt) {
+                try {
+                    const investigation = await client.claimNextInvestigation();
+                    ({ consecutiveFailures: investigationPollFailures } = nextInvestigationPollBackoff(investigationPollFailures, true));
+                    nextInvestigationPollAt = 0;
+                    if (investigation) {
+                        claimedAny = true;
+                        recordCompletedClaim(await runOneInvestigation(options.anthropic, client, pollableConnections, runtimes, investigation, { log, error }));
+                    }
+                }
+                catch (reason) {
+                    if (reason instanceof CompanionHttpError && reason.status === 401)
+                        return tokenRejected();
+                    const backoff = nextInvestigationPollBackoff(investigationPollFailures, false);
+                    investigationPollFailures = backoff.consecutiveFailures;
+                    nextInvestigationPollAt = Date.now() + backoff.delayMs;
+                    if (investigationPollFailures === 1) {
+                        error('Investigation poll failed:', reason instanceof Error ? reason.message : reason, `Retrying in ${backoff.delayMs / 1000}s.`);
+                    }
+                    else {
+                        warn(`Investigation poll still failing (${investigationPollFailures} consecutive); retrying in ${backoff.delayMs / 1000}s.`);
+                    }
+                }
+            }
+            if (claimedAny) {
+                lastIdleStatusAt = Date.now();
+            }
+            else if (!options.shouldStop()) {
+                const now = Date.now();
+                if (now - lastIdleStatusAt >= IDLE_STATUS_MS) {
+                    log(`[${new Date(now).toISOString()}] still watching — no work claimed.`);
+                    lastIdleStatusAt = now;
+                }
+                await new Promise((done) => setTimeout(done, IDLE_POLL_MS));
+            }
+        }
+        catch (reason) {
+            if (reason instanceof CompanionHttpError && reason.status === 401)
+                return tokenRejected();
+            error('Unexpected run-loop error:', reason instanceof Error ? reason.message : reason);
+            if (!options.shouldStop())
+                await new Promise((done) => setTimeout(done, LOOP_RECOVERY_DELAY_MS));
+        }
+    }
+    log('Stopped.');
+    return 'stopped';
+}
+async function cmdRun(options = {}) {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (error) {
+        if (!options.safeStartupDiagnostics)
+            throw error;
+        console.error('Could not read the companion configuration. Fix or remove the configuration file, then run connect again.');
+        process.exitCode = 1;
+        return;
+    }
+    const runnablePairings = config?.pairings.filter((pairing) => pairing.connections.length > 0 || pairing.pollWorkspaceTasks) ?? [];
+    if (!config || runnablePairings.length === 0) {
+        console.error(options.safeStartupDiagnostics
+            ? 'Nothing is set up yet. Run connect first.'
+            : `Nothing set up yet — ${configPath} is missing or empty. Run "connect" first.`);
+        process.exitCode = 1;
+        return;
+    }
+    const allBackends = runnablePairings.flatMap((pairing) => [
+        ...pairing.connections.map((connection) => connection.backend),
+        ...(pairing.pollWorkspaceTasks ? [pairing.workspaceBackend ?? 'api-key'] : []),
+    ]);
+    const { needsApiKey, needsCli } = backendRequirements(allBackends);
+    const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY;
+    if (needsApiKey && !apiKey) {
+        console.error('No Anthropic API key found. Get one free at console.anthropic.com, then either run '
+            + '"connect" again adding --api-key <your key>, or set it yourself: '
+            + '"set ANTHROPIC_API_KEY=<your key>" (Windows) / "export ANTHROPIC_API_KEY=<your key>" (Mac/Linux), then run "run" again.');
+        process.exitCode = 1;
+        return;
+    }
+    if (needsCli && !await checkClaudeCliAvailable()) {
+        console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
+        process.exitCode = 1;
+        return;
+    }
+    const unavailableConnections = new Set();
+    let codexAvailable = true;
+    if (allBackends.includes('codex')) {
+        const status = await checkCodexLogin(defaultCodexHome());
+        codexAvailable = status === 'logged-in';
+        if (!codexAvailable) {
+            logCodexReadiness(status);
+            for (const pairing of runnablePairings) {
+                for (const connection of pairing.connections) {
+                    if (connection.backend !== 'codex')
+                        continue;
+                    console.error(`Skipping ${connection.connectionId}: Codex is ${status === 'not-installed' ? 'not installed' : 'not logged in'}; no work will be claimed for this connection.`);
+                    unavailableConnections.add(connection.connectionId);
+                }
+                if (pairing.pollWorkspaceTasks && (pairing.workspaceBackend ?? 'api-key') === 'codex') {
+                    console.error(`Skipping workspace-level tasks for ${pairing.url}: Codex is ${status === 'not-installed' ? 'not installed' : 'not logged in'}; no work will be claimed.`);
+                }
+            }
+        }
+    }
+    const anthropic = needsApiKey ? new Anthropic({ apiKey }) : null;
+    const usageLimitPause = new UsageLimitPause();
+    let stopping = false;
+    process.on('SIGINT', () => {
+        if (stopping) {
+            expectedExitReason = 'forced stop after a second Ctrl+C';
+            process.exit(1);
+        }
+        console.log('\nStopping after the current poll — Ctrl+C again to force quit.');
+        expectedExitReason = 'stopped by Ctrl+C';
+        stopping = true;
+    });
+    let activePairings = runnablePairings.length;
+    await Promise.all(runnablePairings.map(async (pairing) => {
+        try {
+            return await runPairing(pairing, {
+                ...options,
+                multiple: runnablePairings.length > 1,
+                anthropic,
+                unavailableConnections,
+                codexAvailable,
+                usageLimitPause,
+                shouldStop: () => stopping,
+            });
+        }
+        catch (reason) {
+            if (runnablePairings.length === 1)
+                throw reason;
+            console.error(`${pairingPrefix(pairing)} The Console at ${pairing.url} stopped because of an unexpected error: ${reason instanceof Error ? reason.message : reason}`);
+            return 'stopped';
+        }
+        finally {
+            activePairings--;
+            if (activePairings === 0 && !stopping) {
+                expectedExitReason = 'every connected Console stopped accepting work';
+            }
+        }
+    }));
+}
+async function cmdRunWithInstance(options = {}) {
+    if (process.env.PRODUCT_CONSOLE_COMPANION_DAEMON_CHILD === '1')
+        return cmdRun(options);
+    const paths = servicePaths();
+    if (!acquireInstanceLock('run', paths)) {
+        console.log('The companion is already running (in the background or another terminal), so this run will exit.');
+        console.log(restartHint);
+        return;
+    }
+    try {
+        await cmdRun(options);
+    }
+    finally {
+        releaseInstanceLock(paths);
+    }
+}
+const defaultFinishConnectDependencies = {
+    status: () => serviceStatus(),
+    stop: () => stopService(),
+    install: (cliPath) => installService({ cliPath }),
+    run: (options) => cmdRunWithInstance(options),
+    isNpxPath: isNpxCachePath,
+    output: console,
+};
+async function reinstallBackgroundService(cliPath, dependencies = defaultFinishConnectDependencies) {
+    const current = dependencies.status();
+    // A reinstall replaces the saved settings; a daemon that is already running would keep the old ones.
+    if (current.running && current.role === 'daemon')
+        await dependencies.stop();
+    return dependencies.install(cliPath);
+}
+/** Finishes a successful pairing without making CLI tests touch the real service or home folder. */
+export async function finishConnect(options, dependencies = defaultFinishConnectDependencies) {
+    if (options.background && !options.shouldRunAfter) {
+        dependencies.output.error("--background can't be used together with --no-run.");
+        return false;
+    }
+    if (options.background) {
+        const cliPath = options.cliPath ?? fileURLToPath(import.meta.url);
+        if (dependencies.isNpxPath(cliPath)) {
+            const windows = (options.platform ?? process.platform) === 'win32';
+            dependencies.output.log('Paired. To keep the companion running in the background, install it once and turn it on:');
+            dependencies.output.log(`${windows ? 'npm.cmd' : 'npm'} install -g @withtruing/companion@latest`);
+            dependencies.output.log(`${windows ? 'truing.cmd' : 'truing'} install`);
+            return true;
+        }
+        try {
+            for (const line of await reinstallBackgroundService(cliPath, dependencies))
+                dependencies.output.log(line);
+            dependencies.output.log('Done. The companion now runs in the background and starts by itself when you sign in to this computer. You can close this window.');
+            return true;
+        }
+        catch (error) {
+            const reason = (error instanceof Error ? error.message : String(error)).replace(/\s*[\r\n]+\s*/g, ' ');
+            dependencies.output.error(reason);
+            dependencies.output.error('Your pairing is saved. Run `truing install` to try again.');
+            return false;
+        }
+    }
+    if (dependencies.status().running)
+        dependencies.output.log(restartHint);
+    if (!options.shouldRunAfter) {
+        dependencies.output.log('Run "truing run" whenever you\'re ready to start.');
+        return true;
+    }
+    dependencies.output.log('Starting now — Ctrl+C any time to stop.\n');
+    await dependencies.run({ safeStartupDiagnostics: options.safeStartupDiagnostics });
+    return true;
+}
+/** Service commands report expected problems (not installed, running from the npx cache) as one
+ *  plain sentence and a non-zero exit, instead of the top-level fatal-error trace. */
+async function withServiceErrors(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+async function cmdInstall() {
+    for (const line of await reinstallBackgroundService(fileURLToPath(import.meta.url)))
+        console.log(line);
+}
+async function cmdStop() {
+    const stopped = await stopService();
+    console.log(stopped
+        ? 'The Truing companion was asked to stop. Automatic startup is still installed.'
+        : 'No running Truing companion was found. Automatic startup is still installed.');
+}
+async function cmdStart() {
+    const status = serviceStatus();
+    if (status.running) {
+        console.log(`The Truing companion is already running (PID ${status.pid}).`);
+        return;
+    }
+    await startService();
+    console.log('The Truing companion was started silently in the background.');
+}
+async function cmdUninstall() {
+    for (const line of await uninstallService())
+        console.log(line);
+}
+async function cmdDisconnect(argv) {
+    const flags = parseFlags(argv);
+    const url = flags.url?.replace(/\/+$/, '');
+    if (!url) {
+        console.error('Usage: truing disconnect --url <your Truing link> [--workspace <workspaceId>]');
+        process.exitCode = 1;
+        return;
+    }
+    const removed = removePairing(url, flags.workspace);
+    if (removed.length === 0) {
+        console.error(`This computer is not connected to ${url}${flags.workspace ? ` for workspace ${flags.workspace}` : ''}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const projectCount = removed.reduce((total, pairing) => total + pairing.connections.length, 0);
+    console.log(`Disconnected from ${url}; removed ${projectCount} project${projectCount === 1 ? '' : 's'}.`);
+    await removeManagedCopies(removed.flatMap((pairing) => pairing.connections));
+    logRestartHintIfRunning();
+}
+/** Deletes the companion's own copies behind removed connections. A copy another remaining
+ *  connection still uses (the same repo connected to a second Console) is kept. Only paths inside
+ *  <config dir>/repos/ are ever deleted, and only for connections marked managed. */
+async function removeManagedCopies(removedConnections) {
+    const reposDir = managedReposDir();
+    const stillUsed = new Set((loadConfig()?.pairings ?? [])
+        .flatMap((pairing) => pairing.connections)
+        .map((connection) => resolve(connection.repoPath).toLowerCase()));
+    const handled = new Set();
+    for (const connection of removedConnections) {
+        if (!connection.managed)
+            continue;
+        const key = resolve(connection.repoPath).toLowerCase();
+        if (stillUsed.has(key) || handled.has(key))
+            continue;
+        handled.add(key);
+        const label = connection.label ?? labelFromCopyPath(connection.repoPath);
+        try {
+            await removeManagedCopy(connection.repoPath, reposDir);
+            console.log(`Removed the companion's copy of ${label}.`);
+        }
+        catch (error) {
+            console.error(error instanceof ManagedRepoError
+                ? error.message
+                : `Couldn't remove the companion's copy of ${label} at ${connection.repoPath}. Stop the companion, then delete that folder.`);
+            process.exitCode = 1;
+        }
+    }
+}
+async function cmdSignin(argv) {
+    const flags = parseFlags(argv);
+    let wanted = null;
+    if (flags.repo !== undefined) {
+        try {
+            wanted = managedCopyPath(managedReposDir(), parseGitHubRepo(flags.repo)).toLowerCase();
+        }
+        catch (error) {
+            console.error(error instanceof ManagedRepoError ? error.message : String(error));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const copies = new Map();
+    for (const pairing of loadConfig()?.pairings ?? []) {
+        const client = new CompanionClient(pairing.url, pairing.token);
+        for (const connection of pairing.connections) {
+            if (!connection.managed)
+                continue;
+            const key = resolve(connection.repoPath).toLowerCase();
+            if (copies.has(key) || (wanted !== null && key !== wanted))
+                continue;
+            const label = connection.label ?? labelFromCopyPath(connection.repoPath);
+            copies.set(key, {
+                repoPath: connection.repoPath,
+                label,
+                getToken: () => client.githubToken(label).then((response) => response.token),
+            });
+        }
+    }
+    if (copies.size === 0) {
+        console.log(wanted === null
+            ? "There's no companion-kept copy of any repo on this computer."
+            : `There's no companion-kept copy of ${flags.repo} on this computer.`);
+        if (wanted !== null)
+            process.exitCode = 1;
+        return;
+    }
+    for (const { repoPath, label, getToken } of copies.values()) {
+        if (!existsSync(repoPath)) {
+            console.log(`The companion's copy of ${label} is missing. Run the connect command for it again.`);
+            process.exitCode = 1;
+            continue;
+        }
+        const outcome = await interactiveFetch(repoPath, getToken);
+        if (outcome.ok) {
+            console.log(`Signed in, ${label} is up to date.`);
+        }
+        else {
+            console.log(`Still can't reach ${label} on GitHub: ${readManagedState(repoPath)?.lastProblem ?? 'Git could not reach GitHub'}`);
+            process.exitCode = 1;
+        }
+    }
+}
+function cmdStatus() {
+    const status = serviceStatus();
+    console.log(`Automatic startup: ${status.installed ? 'installed' : 'not installed'}`);
+    console.log(status.running
+        ? `Companion: running (${status.role ?? 'process'} PID ${status.pid})`
+        : 'Companion: not running');
+    if (status.logLines.length > 0) {
+        console.log('Latest log lines:');
+        for (const line of status.logLines)
+            console.log(`  ${line}`);
+    }
+    else {
+        console.log('Latest log lines: none');
+    }
+    if (status.pairings.length > 0) {
+        console.log('Connected Consoles:');
+        for (const pairing of status.pairings) {
+            const workspace = pairing.workspaceId ? ` (workspace ${pairing.workspaceId.slice(0, 8)}…)` : '';
+            console.log(`  ${pairing.url}${workspace}`);
+            for (const project of pairing.projects) {
+                console.log(`    ${project.connectionId} — ${project.repoPath}`);
+                if (!project.managed)
+                    continue;
+                const state = readManagedState(project.repoPath);
+                console.log(state?.signInNeeded
+                    ? `      ${state.reconnectInConsole ? RECONNECT_IN_CONSOLE_HINT : SIGN_IN_NEEDED_HINT}`
+                    : `      code copy kept up to date by the companion, last updated ${relativeTime(state?.lastUpdatedAt)}`);
+            }
+            if (pairing.workspaceTasks)
+                console.log(`    workspace tasks (${pairing.workspaceTasks.backend})`);
+            if (pairing.projects.length === 0 && !pairing.workspaceTasks)
+                console.log('    (no projects)');
+        }
+    }
+    else {
+        console.log('Connected Consoles: none');
+    }
+    if (!status.running)
+        process.exitCode = 3;
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    if (cmd === 'connect')
+        return cmdConnect(rest);
+    if (cmd === 'disconnect')
+        return withServiceErrors(() => cmdDisconnect(rest));
+    if (cmd === 'run')
+        return cmdRunWithInstance();
+    if (cmd === 'install')
+        return withServiceErrors(cmdInstall);
+    if (cmd === 'daemon')
+        return runDaemon();
+    if (cmd === 'stop')
+        return withServiceErrors(cmdStop);
+    if (cmd === 'start')
+        return withServiceErrors(cmdStart);
+    if (cmd === 'uninstall')
+        return withServiceErrors(cmdUninstall);
+    if (cmd === 'status')
+        return withServiceErrors(cmdStatus);
+    if (cmd === 'signin')
+        return cmdSignin(rest);
+    console.log('Usage: truing <connect|disconnect|run|install|start|stop|status|signin|uninstall> [flags]');
+    console.log('  Connect without a local checkout: truing connect --url <your Truing link> --token <publicId.secret> --repo <owner/name>');
+    process.exitCode = cmd ? 1 : 0;
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    installProcessHandlers();
+    main()
+        .then(() => {
+        expectedExitReason ??= 'command completed';
+    })
+        .catch((reason) => {
+        const error = logFatal('FATAL top-level error', reason);
+        unexpectedExitReason = `top-level error: ${error.message}`;
+        process.exitCode = 1;
+    });
+}