@tiangong-ai/cli 0.0.23 → 0.0.25

package/dist/research/workspace/setup.js

@@ -0,0 +1,3000 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmod, link, lstat, open, readFile, rm } from "node:fs/promises";
+import { hostname, homedir, platform } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { CliError } from "../../errors.js";
+import { loadCapabilityDeclarations } from "./capabilities.js";
+import { inspectResearchContext } from "./context.js";
+import { inspectCapabilityCredentialEnvironment, setCapabilityCredentialFromEnvironment, } from "./credentials.js";
+import { configureExternalSkillProfile, configureTiangongSciCapability, doctorExternalCapabilities, EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE, } from "./external-skills.js";
+import { appendJournalEvent } from "./journal.js";
+import { configuredResearchSecrets, isSensitiveEnvironmentName, sanitizeResearchRecord, sanitizeResearchText, } from "./sanitization.js";
+import { inspectResearchSetupCatalog, RESEARCH_SETUP_CREDENTIALS, RESEARCH_SETUP_INSTALLER, RESEARCH_SETUP_SETTINGS, RESEARCH_SETUP_SKILLS, resolveSetupSkills, setupSkill, setupSource, setupTargetRoot, } from "./setup-catalog.js";
+import { acquireFileLock, canonicalJson, ensureDirectory, fileSize, hashRegularTree, isObject, pathExists, readJsonFile, sha256File, sha256Text, workspacePaths, writeJsonAtomic, writeTextAtomic, } from "./storage.js";
+import { packageVersion } from "./constants.js";
+import { doctorResearchWorkspace, initializeResearchWorkspace, loadWorkspaceConfig, } from "./workspace.js";
+const BRAVE_PROFILE_SKILLS = {
+    none: [],
+    [EXTERNAL_SKILL_PROFILE]: ["brave.web-search", "brave.news-search"],
+    [EXTERNAL_SKILL_CONTEXT_PROFILE]: ["brave.web-search", "brave.news-search", "brave.llm-context"],
+    [EXTERNAL_SKILL_MEDIA_PROFILE]: [
+        "brave.web-search",
+        "brave.news-search",
+        "brave.llm-context",
+        "brave.images-search",
+        "brave.videos-search",
+    ],
+};
+const ADAPTER_ENV_KEY = "TIANGONG_RESEARCH_ADAPTER_CREDENTIALS_JSON";
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+export async function createResearchSetupPlan(input) {
+    const root = requireAbsoluteWorkspace(input.workspace);
+    await assertWorkspaceDirectory(root);
+    const scope = input.scope ?? "project";
+    const agents = normalizeAgents(input.agents ?? ["codex"]);
+    if (!input.confirmNetworkDownloads &&
+        input.skillIds.length + BRAVE_PROFILE_SKILLS[input.evidenceProfile].length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CONFIRMATION_REQUIRED",
+            step: "plan",
+            reason: "Pinned source and npm downloads were not explicitly confirmed.",
+            minimumAction: "Review the catalog and pass the explicit network-download confirmation.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    if (scope === "global" && !input.confirmGlobalMutation) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CONFIRMATION_REQUIRED",
+            step: "plan",
+            reason: "Global Skill installation requires a separate explicit confirmation.",
+            minimumAction: "Prefer project scope, or explicitly confirm global mutation.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    if (input.agentSmoke && !input.confirmAgentSmokeCost) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CONFIRMATION_REQUIRED",
+            step: "plan",
+            reason: "Agent smoke checks may consume provider quota and were not confirmed.",
+            minimumAction: "Confirm agent-smoke cost, or defer the smoke check.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    if (input.allowSyntheticUnstructureUpload && !input.liveChecks) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CONFIRMATION_REQUIRED",
+            step: "plan",
+            reason: "Synthetic Unstructure upload can be authorized only as part of explicit live checks.",
+            minimumAction: "Enable live checks as well, or omit the synthetic-upload authorization.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    if (input.mode === "production-research" && input.evidenceProfile === "none") {
+        throw setupError({
+            code: "RESEARCH_SETUP_SELECTION_INVALID",
+            step: "selection",
+            reason: "Production research requires an independent public-internet evidence profile.",
+            minimumAction: `Choose ${EXTERNAL_SKILL_PROFILE} or a broader explicit profile.`,
+            retryCommand: "tiangong-ai research setup catalog --json",
+            exitCode: 2,
+        });
+    }
+    const selected = resolveSetupSkills([
+        ...new Set([...BRAVE_PROFILE_SKILLS[input.evidenceProfile], ...input.skillIds]),
+    ]);
+    if (selected.some((skill) => skill.role === "evidence-capability") && !agents.includes("codex")) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SELECTION_INVALID",
+            step: "selection",
+            reason: "Evidence capabilities must be copied to the Codex-compatible .agents/skills root.",
+            minimumAction: "Include codex in --agents for any evidence-capability selection.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    validateEvidenceProfileSelection(input.evidenceProfile, selected);
+    validateLicenseAcceptances(selected, input.acceptedLicenseIds);
+    const settings = normalizedSettings(selected, input.settings ?? {});
+    const credentialSources = normalizedCredentialSources(selected, input.credentialEnvironment ?? {});
+    const agentRoutes = normalizeAgentRoutes(input.agentRoutes);
+    const targets = plannedInstallTargets(root, scope, agents, input.environment ?? process.env, input.targetRoots);
+    const selectedSources = [...new Set(selected.map((skill) => skill.sourceId))]
+        .map(setupSource)
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const unsigned = {
+        schemaVersion: 1,
+        kind: "tiangong-research-setup-plan",
+        planId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        cli: { package: "@tiangong-ai/cli", version: packageVersion() },
+        workspace: {
+            path: root,
+            name: normalizedWorkspaceName(input.name ?? basename(root)),
+            mode: input.mode,
+        },
+        install: {
+            scope,
+            agents,
+            mode: "copy",
+            installer: RESEARCH_SETUP_INSTALLER,
+            targets,
+        },
+        selection: {
+            evidenceProfile: input.evidenceProfile,
+            skillIds: selected.map((skill) => skill.id),
+        },
+        sources: selectedSources.map((source) => ({
+            id: source.id,
+            repository: source.repository,
+            locator: source.locator,
+            immutableRef: source.immutableRef,
+        })),
+        skills: selected.map((skill) => ({
+            id: skill.id,
+            skillName: skill.skillName,
+            sourceId: skill.sourceId,
+            sourceRelativePath: skill.sourceRelativePath,
+            expectedTreeSha256: skill.expectedTreeSha256,
+            role: skill.role,
+            licenseId: skill.license.id,
+        })),
+        acceptedLicenses: selected.map((skill) => ({
+            skillId: skill.id,
+            licenseId: skill.license.id,
+            accepted: true,
+        })),
+        credentialSources,
+        settings,
+        agentRoutes,
+        checks: {
+            live: input.liveChecks === true,
+            allowSyntheticUnstructureUpload: input.allowSyntheticUnstructureUpload === true,
+            agentSmoke: input.agentSmoke === true,
+        },
+        confirmations: {
+            networkDownloads: true,
+            globalMutation: scope === "global",
+            agentSmokeCost: input.agentSmoke === true,
+        },
+        mutations: setupMutations(root, targets, selected, credentialSources),
+    };
+    const plan = {
+        ...unsigned,
+        planSha256: sha256Text(canonicalJson(unsigned)),
+    };
+    const paths = workspacePaths(root);
+    await ensureDirectory(paths.control);
+    const release = await acquireFileLock(paths.setupLock, setupLockPayload(plan.planSha256));
+    try {
+        if ((await pathExists(paths.setupPlan)) && !input.replacePlan) {
+            throw setupError({
+                code: "RESEARCH_SETUP_PLAN_EXISTS",
+                step: "plan",
+                reason: "A setup plan already exists and was not replaced implicitly.",
+                minimumAction: "Inspect setup status, then explicitly request plan replacement if appropriate.",
+                retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                exitCode: 3,
+            });
+        }
+        const priorPlanSha256 = (await pathExists(paths.setupPlan))
+            ? await archiveSetupGeneration(root)
+            : null;
+        await writeJsonAtomic(paths.setupPlan, plan, 0o444);
+        await writeJsonAtomic(paths.setupState, initialSetupState(plan.planSha256));
+        if (priorPlanSha256 && (await pathExists(paths.marker))) {
+            await appendJournalEvent(paths.journal, "research.setup.plan.replaced", "workspace", {
+                priorPlanSha256,
+                planSha256: plan.planSha256,
+            }).catch(() => undefined);
+        }
+    }
+    finally {
+        await release();
+    }
+    return plan;
+}
+export async function loadAndVerifyResearchSetupPlan(planPath) {
+    const plan = await loadHashVerifiedResearchSetupPlan(planPath);
+    if (plan.cli.version !== packageVersion()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CLI_DRIFT",
+            step: "plan-validation",
+            reason: `Plan requires @tiangong-ai/cli@${plan.cli.version}; active version is ${packageVersion()}.`,
+            minimumAction: "Use the plan's exact CLI version or generate a new plan and review its changes.",
+            retryCommand: "tiangong-ai --version",
+            exitCode: 3,
+        });
+    }
+    assertPlanMatchesCatalog(plan);
+    return plan;
+}
+async function loadHashVerifiedResearchSetupPlan(planPath) {
+    if (!isAbsolute(planPath)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_PLAN_INVALID",
+            step: "plan-validation",
+            reason: "Setup plan path must be absolute.",
+            minimumAction: "Pass the absolute setup-plan.json path.",
+            retryCommand: "tiangong-ai research setup apply --help",
+            exitCode: 2,
+        });
+    }
+    const info = await lstat(planPath).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_PLAN_INVALID",
+            step: "plan-validation",
+            reason: "Setup plan must be a regular non-symlink file.",
+            minimumAction: "Restore the immutable plan file at an absolute path.",
+            retryCommand: "tiangong-ai research setup status --json",
+            exitCode: 2,
+        });
+    }
+    const raw = await readJsonFile(planPath, "Research setup plan");
+    const plan = parseResearchSetupPlan(raw);
+    const { planSha256: _hash, ...unsigned } = plan;
+    const expected = sha256Text(canonicalJson(unsigned));
+    if (plan.planSha256 !== expected) {
+        throw setupError({
+            code: "RESEARCH_SETUP_PLAN_TAMPERED",
+            step: "plan-validation",
+            reason: "Setup plan hash does not match its content.",
+            minimumAction: "Discard the changed plan and create a new reviewed plan.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 3,
+        });
+    }
+    return plan;
+}
+export async function createResearchSetupUpgradePlan(input) {
+    const root = requireAbsoluteWorkspace(input.workspace);
+    if (!input.confirmUpgrade) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CONFIRMATION_REQUIRED",
+            step: "upgrade-plan",
+            reason: "Setup upgrade plan generation requires an explicit confirmation.",
+            minimumAction: "Run update --check, review current catalog licenses and pins, then pass --confirm-upgrade.",
+            retryCommand: `tiangong-ai research setup update --check --workspace ${root} --json`,
+            exitCode: 2,
+        });
+    }
+    const prior = await loadHashVerifiedResearchSetupPlan(workspacePaths(root).setupPlan);
+    const selected = resolveSetupSkills(prior.selection.skillIds);
+    validateLicenseAcceptances(selected, input.acceptedLicenseIds);
+    return createResearchSetupPlan({
+        workspace: root,
+        name: prior.workspace.name,
+        mode: prior.workspace.mode,
+        evidenceProfile: prior.selection.evidenceProfile,
+        skillIds: prior.selection.skillIds.filter((id) => !BRAVE_PROFILE_SKILLS[prior.selection.evidenceProfile].includes(id)),
+        scope: prior.install.scope,
+        agents: prior.install.agents,
+        acceptedLicenseIds: input.acceptedLicenseIds,
+        credentialEnvironment: Object.fromEntries(prior.credentialSources.map((credential) => [credential.id, credential.fromEnvironment])),
+        settings: prior.settings,
+        agentRoutes: prior.agentRoutes,
+        liveChecks: prior.checks.live,
+        allowSyntheticUnstructureUpload: prior.checks.allowSyntheticUnstructureUpload,
+        agentSmoke: prior.checks.agentSmoke,
+        confirmNetworkDownloads: true,
+        confirmGlobalMutation: prior.install.scope === "global",
+        confirmAgentSmokeCost: prior.checks.agentSmoke,
+        replacePlan: true,
+        targetRoots: Object.fromEntries(prior.install.targets.map((target) => [target.agent, target.root])),
+        ...(input.environment === undefined ? {} : { environment: input.environment }),
+    });
+}
+export async function applyResearchSetupPlan(planPath, options = {}) {
+    const plan = await loadAndVerifyResearchSetupPlan(resolve(planPath));
+    const root = plan.workspace.path;
+    const paths = workspacePaths(root);
+    const environment = options.environment ?? process.env;
+    const runner = sanitizingSetupRunner(options.runner ?? runSetupCommand, setupSecretValues(plan, environment));
+    const release = await acquireFileLock(paths.setupLock, setupLockPayload(plan.planSha256));
+    let state = await loadSetupState(root, plan.planSha256);
+    state = await updateSetupState(root, {
+        ...state,
+        status: "applying",
+        attempts: state.attempts + 1,
+        currentStep: "workspace",
+        lastError: null,
+    });
+    try {
+        await ensureSetupWorkspace(plan);
+        await configureAgentRoutes(plan);
+        state = await completeSetupStep(root, state, "workspace");
+        state = await startSetupStep(root, state, "credential-preflight");
+        await assertRequiredCredentialPreflight(plan, environment);
+        state = await completeSetupStep(root, state, "credential-preflight");
+        state = await startSetupStep(root, state, "installation-preflight");
+        const selected = plan.selection.skillIds.map(setupSkill);
+        const installInspection = await inspectSelectedInstallations(plan, selected, environment);
+        const unsafe = installInspection.filter((item) => item.status === "drifted" || item.status === "blocked");
+        if (unsafe.length) {
+            throw setupError({
+                code: "RESEARCH_SETUP_INSTALL_DESTINATION_UNSAFE",
+                step: "installation-preflight",
+                reason: `Existing install destinations are unsafe or drifted: ${unsafe
+                    .map((item) => `${item.agent}:${item.skillId}`)
+                    .join(", ")}.`,
+                minimumAction: "Review the existing directories. The setup CLI will not overwrite, delete, or choose between ambiguous Skill bytes.",
+                retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                exitCode: 3,
+            });
+        }
+        state = await completeSetupStep(root, state, "installation-preflight");
+        const missing = installInspection.filter((item) => item.status === "missing");
+        if (missing.length) {
+            state = await startSetupStep(root, state, "source-checkout");
+            await verifyInstallerPackage(runner, root, installerEnvironment(environment));
+            const requiredSourceIds = [
+                ...new Set(missing.map((item) => setupSkill(item.skillId).sourceId)),
+            ].sort();
+            const sourceDirectories = new Map();
+            for (const sourceId of requiredSourceIds) {
+                sourceDirectories.set(sourceId, await ensureSetupSourceCheckout(plan, sourceId, runner, installerEnvironment(environment)));
+            }
+            state = await completeSetupStep(root, state, "source-checkout");
+            state = await startSetupStep(root, state, "skill-install");
+            for (const agent of plan.install.agents) {
+                const missingForAgent = missing.filter((item) => item.agent === agent);
+                const sourceIds = [
+                    ...new Set(missingForAgent.map((item) => setupSkill(item.skillId).sourceId)),
+                ].sort();
+                for (const sourceId of sourceIds) {
+                    const skills = missingForAgent
+                        .map((item) => setupSkill(item.skillId))
+                        .filter((skill) => skill.sourceId === sourceId)
+                        .sort((left, right) => left.id.localeCompare(right.id));
+                    await installSetupSkills({
+                        plan,
+                        agent,
+                        skills,
+                        sourceDirectory: sourceDirectories.get(sourceId),
+                        runner,
+                        environment: installerEnvironmentForTarget(plan, agent, environment),
+                    });
+                }
+            }
+            const verified = await inspectSelectedInstallations(plan, selected, environment);
+            const incomplete = verified.filter((item) => item.status !== "installed");
+            if (incomplete.length) {
+                throw setupError({
+                    code: "RESEARCH_SETUP_INSTALL_VERIFICATION_FAILED",
+                    step: "skill-install",
+                    reason: `The installer exited but ${incomplete.length} destination(s) did not match the reviewed hashes.`,
+                    minimumAction: "Inspect the reported destination status. File existence alone is not accepted as installation success.",
+                    retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                    exitCode: 3,
+                });
+            }
+            state = await completeSetupStep(root, state, "skill-install");
+        }
+        else {
+            state = await completeSetupStep(root, state, "skill-install");
+        }
+        state = await startSetupStep(root, state, "capability-configuration");
+        await configureSelectedCapabilities(plan, environment);
+        state = await completeSetupStep(root, state, "capability-configuration");
+        state = await startSetupStep(root, state, "settings");
+        await writeJsonAtomic(paths.setupConfig, {
+            schemaVersion: 1,
+            planSha256: plan.planSha256,
+            settings: plan.settings,
+            selectedSkillIds: plan.selection.skillIds,
+            updatedAt: new Date().toISOString(),
+        });
+        state = await completeSetupStep(root, state, "settings");
+        state = await startSetupStep(root, state, "credentials");
+        await configurePlanCredentials(plan, environment);
+        state = await completeSetupStep(root, state, "credentials");
+        await appendJournalEvent(paths.journal, "research.setup.applied", "workspace", {
+            planSha256: plan.planSha256,
+            selectedSkillIds: plan.selection.skillIds,
+            sourcePins: plan.sources.map((source) => ({
+                id: source.id,
+                immutableRef: source.immutableRef,
+            })),
+            installer: {
+                package: plan.install.installer.package,
+                version: plan.install.installer.version,
+                npmIntegrity: plan.install.installer.npmIntegrity,
+            },
+            configuredCredentialIds: plan.credentialSources.map((credential) => credential.id),
+        });
+        if (options.skipDoctor) {
+            state = await updateSetupState(root, {
+                ...state,
+                status: "partially-ready",
+                currentStep: null,
+            });
+            return { schemaVersion: 1, plan, state, report: null };
+        }
+        state = await startSetupStep(root, state, "doctor");
+        const report = await doctorResearchSetup(root, {
+            live: plan.checks.live,
+            allowSyntheticUnstructureUpload: plan.checks.allowSyntheticUnstructureUpload,
+            agentSmoke: plan.checks.agentSmoke,
+            environment,
+            runner,
+            ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }),
+            ...(options.sleeper === undefined ? {} : { sleeper: options.sleeper }),
+        });
+        state = await updateSetupState(root, {
+            ...state,
+            status: report.readiness === "READY"
+                ? "ready"
+                : report.readiness === "PARTIALLY_READY"
+                    ? "partially-ready"
+                    : "blocked",
+            currentStep: null,
+            completedSteps: [...new Set([...state.completedSteps, "doctor"])],
+        });
+        return { schemaVersion: 1, plan, state, report };
+    }
+    catch (error) {
+        const failure = setupFailure(error, state.currentStep ?? "apply", root);
+        state = await updateSetupState(root, {
+            ...state,
+            status: "blocked",
+            currentStep: null,
+            lastError: failure,
+        });
+        if (error instanceof CliError)
+            throw error;
+        throw setupError({
+            code: failure.code,
+            step: failure.step,
+            reason: failure.reason,
+            minimumAction: failure.minimumAction,
+            retryCommand: failure.retryCommand,
+            exitCode: 3,
+        });
+    }
+    finally {
+        await release();
+    }
+}
+export async function inspectResearchSetupStatus(workspace, environment = process.env) {
+    const root = requireAbsoluteWorkspace(resolve(workspace));
+    const paths = workspacePaths(root);
+    const plan = await loadAndVerifyResearchSetupPlan(paths.setupPlan);
+    const state = await loadSetupState(root, plan.planSha256);
+    const selected = plan.selection.skillIds.map(setupSkill);
+    const installations = await inspectSelectedInstallations(plan, selected, environment);
+    const report = (await pathExists(paths.setupReport))
+        ? await readJsonFile(paths.setupReport, "Research setup report")
+        : null;
+    return {
+        schemaVersion: 1,
+        workspace: root,
+        plan: {
+            planId: plan.planId,
+            planSha256: plan.planSha256,
+            cliVersion: plan.cli.version,
+            mode: plan.workspace.mode,
+            scope: plan.install.scope,
+            agents: plan.install.agents,
+            selectedSkillIds: plan.selection.skillIds,
+        },
+        state,
+        installations,
+        report,
+        next: state.status === "blocked" && state.lastError
+            ? state.lastError
+            : state.status === "ready"
+                ? null
+                : {
+                    minimumAction: "Run setup doctor and resolve every reported missing readiness item.",
+                    retryCommand: `tiangong-ai research setup doctor --workspace ${root} --json`,
+                },
+    };
+}
+export async function setResearchSetupCredentialFromEnvironment(input) {
+    const root = requireAbsoluteWorkspace(input.workspace);
+    const plan = await loadAndVerifyResearchSetupPlan(workspacePaths(root).setupPlan);
+    const selected = selectedCredentialDefinitions(plan);
+    const credential = selected.find((candidate) => candidate.id === input.credentialId);
+    if (!credential) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_INVALID",
+            step: "credentials",
+            reason: `Credential is not declared by the selected setup plan: ${input.credentialId}.`,
+            minimumAction: "Inspect the setup catalog and selected plan credential IDs.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 2,
+        });
+    }
+    assertEnvironmentName(input.environmentName);
+    const value = input.environment[input.environmentName];
+    if (typeof value !== "string" || Buffer.byteLength(value, "utf8") < credential.minimumUtf8Bytes) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_INVALID",
+            step: "credentials",
+            reason: `Credential source environment variable is missing or too short: ${input.environmentName}.`,
+            minimumAction: "Set the owner environment variable, then retry this exact credential step.",
+            retryCommand: `tiangong-ai research setup credential set --id ${credential.id} --from-env ${input.environmentName} --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    if (credential.storage === "broker") {
+        const declarations = await loadCapabilityDeclarations(root);
+        await setCapabilityCredentialFromEnvironment({
+            root,
+            capabilities: declarations.capabilities,
+            credentialId: credential.id,
+            environmentName: input.environmentName,
+            environment: input.environment,
+        });
+    }
+    else {
+        await setAdapterCredential(root, selected, credential.id, value);
+    }
+    await appendJournalEvent(workspacePaths(root).journal, "research.setup.credential.configured", "workspace", {
+        credentialId: credential.id,
+        sourceEnvironmentNameSha256: sha256Text(input.environmentName),
+        storage: credential.storage,
+    });
+    return {
+        schemaVersion: 1,
+        workspace: root,
+        credentialId: credential.id,
+        configured: true,
+        storage: credential.storage,
+        outputPolicy: "value-is-never-emitted",
+    };
+}
+export async function runResearchSetupCompanion(input, options = {}) {
+    const root = requireAbsoluteWorkspace(input.workspace);
+    const plan = await loadAndVerifyResearchSetupPlan(workspacePaths(root).setupPlan);
+    if (!plan.selection.skillIds.includes(input.skillId)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_NOT_SELECTED",
+            step: "companion-preflight",
+            reason: `The immutable setup plan did not select ${input.skillId}.`,
+            minimumAction: "Create and apply an explicit replacement setup plan that selects this companion Skill.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    const skill = setupSkill(input.skillId);
+    if (skill.role !== "input-preprocessor" && skill.role !== "acquisition-adapter") {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_ROLE_INVALID",
+            step: "companion-preflight",
+            reason: `${skill.id} is not an input-preprocessor or acquisition-adapter.`,
+            minimumAction: "Use evidence capabilities through the research broker and authoring Skills only after closure.",
+            retryCommand: `tiangong-ai research setup catalog --workspace ${root} --json`,
+            exitCode: 2,
+        });
+    }
+    const skillDirectory = await verifiedCompanionSkillDirectory(plan, skill);
+    const credentialDefinitions = selectedCredentialDefinitions(plan).filter((definition) => skill.credentialIds.includes(definition.id));
+    const credentials = await loadAdapterCredentials(root, selectedCredentialDefinitions(plan));
+    const environment = options.environment ?? process.env;
+    const runner = sanitizingSetupRunner(options.runner ?? runSetupCommand, [
+        ...setupSecretValues(plan, environment),
+        ...credentials.values(),
+    ]);
+    return input.skillId === "tiangong.document-granular-decompose"
+        ? runDocumentGranularCompanion({
+            root,
+            plan,
+            skill,
+            skillDirectory,
+            credentialDefinitions,
+            credentials,
+            input,
+            environment,
+            runner,
+        })
+        : runAcademicPaperCompanion({
+            root,
+            plan,
+            skill,
+            skillDirectory,
+            credentials,
+            input,
+            environment,
+            runner,
+        });
+}
+export async function doctorResearchSetup(workspace, options = {}) {
+    const root = requireAbsoluteWorkspace(resolve(workspace));
+    const environment = options.environment ?? process.env;
+    const fetcher = options.fetcher ?? fetch;
+    const sleeper = options.sleeper ?? sleep;
+    const paths = workspacePaths(root);
+    const plan = await loadAndVerifyResearchSetupPlan(paths.setupPlan);
+    const runner = sanitizingSetupRunner(options.runner ?? runSetupCommand, setupSecretValues(plan, environment));
+    const checks = [];
+    await setupDoctorCheck(checks, "workspace", "workspace", async () => {
+        const context = await inspectResearchContext(root);
+        if (context.role !== "workspace")
+            throw new Error(`workspace role is ${context.role}`);
+        return `Workspace is initialized in ${plan.workspace.mode} mode.`;
+    });
+    await setupDoctorCheck(checks, "node", "runtime", async () => {
+        const major = Number(process.versions.node.split(".")[0]);
+        if (major !== 24)
+            throw new Error(`Node ${process.versions.node} does not satisfy >=24 <25`);
+        return `Node ${process.versions.node} matches the CLI runtime baseline.`;
+    });
+    for (const command of ["git", "npx"]) {
+        await setupDoctorCheck(checks, command, "runtime", async () => {
+            const result = await runner({
+                command,
+                args: ["--version"],
+                cwd: root,
+                environment: installerEnvironment(environment),
+                timeoutMs: 15_000,
+            });
+            if (result.exitCode !== 0)
+                throw new Error(`${command} is not executable`);
+            return `${command} is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 120)}).`;
+        });
+    }
+    await setupDoctorCheck(checks, "platform-sandbox", "runtime", async () => {
+        if (platform() === "darwin") {
+            const info = await lstat("/usr/bin/sandbox-exec").catch(() => undefined);
+            if (!info?.isFile())
+                throw new Error("/usr/bin/sandbox-exec is unavailable");
+            return "macOS sandbox-exec is available.";
+        }
+        if (platform() === "linux") {
+            const result = await runner({
+                command: "bwrap",
+                args: ["--version"],
+                cwd: root,
+                environment: installerEnvironment(environment),
+                timeoutMs: 15_000,
+            });
+            if (result.exitCode !== 0)
+                throw new Error("Bubblewrap is unavailable");
+            return "Linux Bubblewrap is available.";
+        }
+        throw new Error("Research execution is unsupported on this platform");
+    });
+    for (const command of ["codex", "claude"]) {
+        await setupDoctorCheck(checks, `agent.${command}`, "agent", async () => {
+            const result = await runner({
+                command,
+                args: ["--version"],
+                cwd: root,
+                environment: agentDoctorEnvironment(environment),
+                timeoutMs: 30_000,
+            });
+            if (result.exitCode !== 0)
+                throw new Error(`${command} is not executable`);
+            return `${command} is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 160)}).`;
+        });
+    }
+    const selected = plan.selection.skillIds.map(setupSkill);
+    const installations = await inspectSelectedInstallations(plan, selected, environment);
+    for (const installation of installations) {
+        checks.push({
+            id: `skill.${installation.agent}.${installation.skillId}`,
+            category: "skill-installation",
+            status: installation.status === "installed" ? "pass" : "fail",
+            detail: installation.detail,
+            minimumAction: installation.status === "installed"
+                ? null
+                : "Restore the pinned Skill bytes; setup will not overwrite a drifted or symlinked directory.",
+        });
+    }
+    for (const setting of requiredSettingsForSkills(selected)) {
+        const configured = plan.settings[setting.id];
+        checks.push({
+            id: `setting.${setting.id}`,
+            category: "configuration",
+            status: configured ? "pass" : setting.required ? "fail" : "warn",
+            detail: configured
+                ? "Declared non-secret setting is configured."
+                : "Setting is not configured.",
+            minimumAction: configured
+                ? null
+                : `Create a reviewed replacement plan with the ${setting.id} setting.`,
+        });
+    }
+    let brokerCredentialStatus = null;
+    try {
+        const declarations = await loadCapabilityDeclarations(root);
+        brokerCredentialStatus = await inspectCapabilityCredentialEnvironment(root, declarations.capabilities);
+    }
+    catch (error) {
+        checks.push({
+            id: "credential.broker-store",
+            category: "credential",
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+            minimumAction: "Repair the owner-only broker credential file, then rerun setup doctor.",
+        });
+    }
+    let adapterCredentials = new Map();
+    try {
+        adapterCredentials = await loadAdapterCredentials(root, selectedCredentialDefinitions(plan));
+    }
+    catch (error) {
+        checks.push({
+            id: "credential.adapter-store",
+            category: "credential",
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+            minimumAction: "Repair the owner-only adapter credential file, then rerun setup doctor.",
+        });
+    }
+    for (const credential of selectedCredentialDefinitions(plan)) {
+        const configured = credential.storage === "broker"
+            ? (brokerCredentialStatus?.configuredIds.includes(credential.id) ?? false)
+            : adapterCredentials.has(credential.id);
+        checks.push({
+            id: `credential.${credential.id}`,
+            category: "credential",
+            status: configured ? "pass" : credential.required ? "fail" : "warn",
+            detail: configured
+                ? "Credential is present in an owner-only store; its value was not emitted."
+                : "Credential is not configured.",
+            minimumAction: configured
+                ? null
+                : `Run research setup credential set --id ${credential.id} --from-env <OWNER_ENV_NAME> --workspace ${root}.`,
+        });
+    }
+    await appendDependencyChecks(checks, selected, runner, root, environment);
+    let capabilityDoctor = null;
+    if (selected.some((skill) => skill.role === "evidence-capability")) {
+        try {
+            capabilityDoctor = await doctorExternalCapabilities(root, {
+                live: options.live === true,
+                fetcher,
+                sleeper,
+            });
+            checks.push({
+                id: "capabilities",
+                category: "evidence-capability",
+                status: capabilityDoctor.status === "ready" ? "pass" : "fail",
+                detail: `${capabilityDoctor.capabilities.length} capability declaration(s); mode=${capabilityDoctor.mode}.`,
+                minimumAction: capabilityDoctor.status === "ready"
+                    ? null
+                    : "Resolve the exact static or live capability failures; no provider fallback is performed.",
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: "capabilities",
+                category: "evidence-capability",
+                status: "fail",
+                detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+                minimumAction: "Apply the reviewed capability configuration, then rerun the exact static or live check.",
+            });
+        }
+    }
+    if (options.live) {
+        await appendCompanionLiveChecks(checks, {
+            plan,
+            selected,
+            adapterCredentials,
+            fetcher,
+            sleeper,
+            allowSyntheticUnstructureUpload: options.allowSyntheticUnstructureUpload === true,
+        });
+    }
+    else {
+        checks.push({
+            id: "live-provider-checks",
+            category: "live-check",
+            status: "warn",
+            detail: "Live provider checks were not requested.",
+            minimumAction: `Run tiangong-ai research setup doctor --live --workspace ${root} --json after reviewing quota impact.`,
+        });
+    }
+    let workspaceDoctor = null;
+    try {
+        workspaceDoctor = await doctorResearchWorkspace(root, {
+            agentSmoke: options.agentSmoke === true,
+            capabilitySmoke: options.live === true,
+            environment,
+            capabilityFetcher: fetcher,
+        });
+        checks.push({
+            id: "production-runtime",
+            category: "research-runtime",
+            status: workspaceDoctor.status === "ready" ? "pass" : "warn",
+            detail: `Workspace doctor reported ${workspaceDoctor.status}.`,
+            minimumAction: workspaceDoctor.status === "ready"
+                ? null
+                : "Configure explicit production models/pricing and run the separately confirmed agent/capability smoke checks.",
+        });
+    }
+    catch (error) {
+        checks.push({
+            id: "production-runtime",
+            category: "research-runtime",
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+            minimumAction: "Repair workspace runtime state, then rerun setup doctor.",
+        });
+    }
+    const readiness = checks.some((check) => check.status === "fail")
+        ? "BLOCKED"
+        : checks.some((check) => check.status === "warn")
+            ? "PARTIALLY_READY"
+            : "READY";
+    const setupSecrets = [
+        ...new Set([
+            ...configuredResearchSecrets(environment),
+            ...plan.credentialSources
+                .map((credential) => environment[credential.fromEnvironment])
+                .filter((value) => typeof value === "string" && value.length >= 8),
+            ...adapterCredentials.values(),
+        ]),
+    ];
+    const report = sanitizeResearchRecord({
+        schemaVersion: 1,
+        workspace: root,
+        planSha256: plan.planSha256,
+        checkedAt: new Date().toISOString(),
+        mode: options.live ? "live" : "static",
+        readiness,
+        checks,
+        capabilityDoctor,
+        workspaceDoctor,
+        summary: {
+            pass: checks.filter((check) => check.status === "pass").length,
+            warn: checks.filter((check) => check.status === "warn").length,
+            fail: checks.filter((check) => check.status === "fail").length,
+        },
+    }, setupSecrets);
+    await writeJsonAtomic(paths.setupReport, report);
+    return report;
+}
+export async function retryResearchSetup(input) {
+    const root = requireAbsoluteWorkspace(resolve(input.workspace));
+    const paths = workspacePaths(root);
+    const plan = await loadAndVerifyResearchSetupPlan(paths.setupPlan);
+    const state = await loadSetupState(root, plan.planSha256);
+    if (!state.lastError || state.lastError.step !== input.step) {
+        throw setupError({
+            code: "RESEARCH_SETUP_RETRY_INVALID",
+            step: "retry",
+            reason: `Requested retry step does not match the recorded failure (${state.lastError?.step ?? "none"}).`,
+            minimumAction: "Inspect setup status and retry only the exact recorded failed step.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 2,
+        });
+    }
+    if (input.clearStaleLock)
+        await clearStaleSetupLock(root);
+    await appendJournalEvent(paths.journal, "research.setup.retry.requested", "workspace", {
+        planSha256: plan.planSha256,
+        step: input.step,
+        priorErrorCode: state.lastError.code,
+    }).catch(() => undefined);
+    return applyResearchSetupPlan(paths.setupPlan, input.options);
+}
+export async function checkResearchSetupUpdates(workspace, environment = process.env) {
+    const root = requireAbsoluteWorkspace(resolve(workspace));
+    const plan = await loadHashVerifiedResearchSetupPlan(workspacePaths(root).setupPlan);
+    const catalog = await inspectResearchSetupCatalog({
+        selectedPath: root,
+        scope: plan.install.scope,
+        agents: plan.install.agents,
+        environment,
+    });
+    const drift = [];
+    for (const planned of plan.skills) {
+        const current = RESEARCH_SETUP_SKILLS.find((skill) => skill.id === planned.id);
+        if (!current) {
+            drift.push({ skillId: planned.id, status: "removed" });
+        }
+        else if (current.expectedTreeSha256 !== planned.expectedTreeSha256) {
+            drift.push({
+                skillId: planned.id,
+                status: "catalog-updated",
+                plannedTreeSha256: planned.expectedTreeSha256,
+                currentTreeSha256: current.expectedTreeSha256,
+            });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        workspace: root,
+        checkedAt: new Date().toISOString(),
+        updateAvailable: drift.length > 0 || plan.cli.version !== packageVersion(),
+        cliVersionDrift: plan.cli.version === packageVersion()
+            ? null
+            : { planned: plan.cli.version, active: packageVersion() },
+        drift,
+        currentInstaller: RESEARCH_SETUP_INSTALLER,
+        catalog,
+        policy: {
+            automaticUpdate: false,
+            floatingUpdate: false,
+            minimumAction: drift.length
+                ? "Use the newer CLI to create and review a replacement immutable plan; upgrade never runs a floating skills update."
+                : "No catalog migration is required. Installed tree drift is reported separately by setup status/doctor.",
+        },
+    };
+}
+export async function clearStaleSetupLock(workspace) {
+    const root = requireAbsoluteWorkspace(resolve(workspace));
+    const lockPath = workspacePaths(root).setupLock;
+    const info = await lstat(lockPath).catch(() => undefined);
+    if (!info)
+        return;
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_LOCK_INVALID",
+            step: "retry",
+            reason: "Setup lock is not a regular file.",
+            minimumAction: "Inspect the lock path manually; it will not be removed automatically.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(await readFile(lockPath, "utf8"));
+    }
+    catch {
+        payload = null;
+    }
+    if (isObject(payload) && payload.hostname === hostname() && typeof payload.pid === "number") {
+        try {
+            process.kill(payload.pid, 0);
+            throw setupError({
+                code: "RESEARCH_SETUP_LOCK_ACTIVE",
+                step: "retry",
+                reason: `Setup lock belongs to live process ${payload.pid}.`,
+                minimumAction: "Wait for the active setup process to finish; do not clear its lock.",
+                retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                exitCode: 3,
+            });
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            const code = error.code;
+            if (code !== "ESRCH")
+                throw error;
+        }
+    }
+    await rm(lockPath);
+}
+function parseResearchSetupPlan(value) {
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        value.kind !== "tiangong-research-setup-plan" ||
+        typeof value.planId !== "string" ||
+        typeof value.createdAt !== "string" ||
+        !isObject(value.cli) ||
+        value.cli.package !== "@tiangong-ai/cli" ||
+        typeof value.cli.version !== "string" ||
+        !isObject(value.workspace) ||
+        typeof value.workspace.path !== "string" ||
+        typeof value.workspace.name !== "string" ||
+        (value.workspace.mode !== "smoke-test" && value.workspace.mode !== "production-research") ||
+        !isObject(value.install) ||
+        (value.install.scope !== "project" && value.install.scope !== "global") ||
+        value.install.mode !== "copy" ||
+        !Array.isArray(value.install.agents) ||
+        value.install.agents.some((agent) => agent !== "codex" && agent !== "claude-code") ||
+        !isObject(value.install.installer) ||
+        !Array.isArray(value.install.targets) ||
+        value.install.targets.some((target) => !isObject(target) ||
+            (target.agent !== "codex" && target.agent !== "claude-code") ||
+            typeof target.root !== "string" ||
+            !isAbsolute(target.root)) ||
+        new Set(value.install.agents).size !== value.install.agents.length ||
+        value.install.targets.length !== value.install.agents.length ||
+        !isObject(value.selection) ||
+        !validEvidenceProfile(value.selection.evidenceProfile) ||
+        !Array.isArray(value.selection.skillIds) ||
+        value.selection.skillIds.some((id) => typeof id !== "string") ||
+        !Array.isArray(value.sources) ||
+        value.sources.some((source) => !isObject(source) ||
+            typeof source.id !== "string" ||
+            typeof source.repository !== "string" ||
+            typeof source.locator !== "string" ||
+            typeof source.immutableRef !== "string" ||
+            !/^[0-9a-f]{40}$/.test(source.immutableRef)) ||
+        !Array.isArray(value.skills) ||
+        value.skills.some((skill) => !isObject(skill) ||
+            typeof skill.id !== "string" ||
+            typeof skill.skillName !== "string" ||
+            typeof skill.sourceId !== "string" ||
+            typeof skill.sourceRelativePath !== "string" ||
+            typeof skill.expectedTreeSha256 !== "string" ||
+            !/^[0-9a-f]{64}$/.test(skill.expectedTreeSha256) ||
+            ![
+                "evidence-capability",
+                "input-preprocessor",
+                "acquisition-adapter",
+                "post-closure-authoring",
+            ].includes(String(skill.role)) ||
+            typeof skill.licenseId !== "string") ||
+        !Array.isArray(value.acceptedLicenses) ||
+        value.acceptedLicenses.some((license) => !isObject(license) ||
+            typeof license.skillId !== "string" ||
+            typeof license.licenseId !== "string" ||
+            license.accepted !== true) ||
+        !Array.isArray(value.credentialSources) ||
+        value.credentialSources.some((credential) => !isObject(credential) ||
+            typeof credential.id !== "string" ||
+            typeof credential.fromEnvironment !== "string" ||
+            (credential.storage !== "broker" && credential.storage !== "adapter")) ||
+        !isObject(value.settings) ||
+        Object.values(value.settings).some((item) => typeof item !== "string") ||
+        !isObject(value.agentRoutes) ||
+        !validAgentRoutes(value.agentRoutes) ||
+        !isObject(value.checks) ||
+        typeof value.checks.live !== "boolean" ||
+        typeof value.checks.allowSyntheticUnstructureUpload !== "boolean" ||
+        typeof value.checks.agentSmoke !== "boolean" ||
+        (value.checks.allowSyntheticUnstructureUpload === true && value.checks.live !== true) ||
+        !isObject(value.confirmations) ||
+        value.confirmations.networkDownloads !== true ||
+        typeof value.confirmations.globalMutation !== "boolean" ||
+        typeof value.confirmations.agentSmokeCost !== "boolean" ||
+        !Array.isArray(value.mutations) ||
+        value.mutations.some((mutation) => !isObject(mutation) ||
+            typeof mutation.step !== "string" ||
+            typeof mutation.target !== "string" ||
+            typeof mutation.reason !== "string") ||
+        typeof value.planSha256 !== "string" ||
+        !/^[0-9a-f]{64}$/.test(value.planSha256)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_PLAN_INVALID",
+            step: "plan-validation",
+            reason: "Setup plan has an unsupported schema or field type.",
+            minimumAction: "Create a new plan with the active CLI and review it before applying.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return value;
+}
+function assertPlanMatchesCatalog(plan) {
+    const selected = resolveSetupSkills(plan.selection.skillIds);
+    if (canonicalJson(plan.selection.skillIds) !== canonicalJson(selected.map((skill) => skill.id))) {
+        throw planCatalogDrift("Skill selection order or duplicates");
+    }
+    if (plan.workspace.path !== requireAbsoluteWorkspace(plan.workspace.path) ||
+        plan.workspace.name !== normalizedWorkspaceName(plan.workspace.name) ||
+        (plan.workspace.mode === "production-research" && plan.selection.evidenceProfile === "none")) {
+        throw planCatalogDrift("workspace identity or mode");
+    }
+    validateEvidenceProfileSelection(plan.selection.evidenceProfile, selected);
+    if (canonicalJson(plan.install.installer) !== canonicalJson(RESEARCH_SETUP_INSTALLER)) {
+        throw planCatalogDrift("installer identity");
+    }
+    const expectedSources = [...new Set(selected.map((skill) => skill.sourceId))]
+        .map(setupSource)
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((source) => ({
+        id: source.id,
+        repository: source.repository,
+        locator: source.locator,
+        immutableRef: source.immutableRef,
+    }));
+    if (canonicalJson(plan.sources) !== canonicalJson(expectedSources)) {
+        throw planCatalogDrift("source pins");
+    }
+    const expectedSkills = selected.map((skill) => ({
+        id: skill.id,
+        skillName: skill.skillName,
+        sourceId: skill.sourceId,
+        sourceRelativePath: skill.sourceRelativePath,
+        expectedTreeSha256: skill.expectedTreeSha256,
+        role: skill.role,
+        licenseId: skill.license.id,
+    }));
+    if (canonicalJson(plan.skills) !== canonicalJson(expectedSkills)) {
+        throw planCatalogDrift("Skill identities or tree hashes");
+    }
+    const expectedLicenses = selected.map((skill) => ({
+        skillId: skill.id,
+        licenseId: skill.license.id,
+        accepted: true,
+    }));
+    if (canonicalJson(plan.acceptedLicenses) !== canonicalJson(expectedLicenses)) {
+        throw planCatalogDrift("license acceptance bindings");
+    }
+    const expectedSettings = normalizedSettings(selected, plan.settings);
+    if (canonicalJson(plan.settings) !== canonicalJson(expectedSettings)) {
+        throw planCatalogDrift("settings");
+    }
+    const expectedCredentialSources = normalizedCredentialSources(selected, Object.fromEntries(plan.credentialSources.map((item) => [item.id, item.fromEnvironment])));
+    if (canonicalJson(plan.credentialSources) !== canonicalJson(expectedCredentialSources)) {
+        throw planCatalogDrift("credential source bindings");
+    }
+    if (canonicalJson(plan.agentRoutes) !== canonicalJson(normalizeAgentRoutes(plan.agentRoutes))) {
+        throw planCatalogDrift("agent routes");
+    }
+    if (canonicalJson(plan.install.agents) !== canonicalJson(normalizeAgents(plan.install.agents))) {
+        throw planCatalogDrift("agent selection order or duplicates");
+    }
+    const expectedTargets = plannedInstallTargets(plan.workspace.path, plan.install.scope, plan.install.agents, process.env, Object.fromEntries(plan.install.targets.map((target) => [target.agent, target.root])));
+    if (canonicalJson(plan.install.targets) !== canonicalJson(expectedTargets)) {
+        throw planCatalogDrift("install targets");
+    }
+    if ((plan.install.scope === "global") !== plan.confirmations.globalMutation) {
+        throw planCatalogDrift("global mutation confirmation");
+    }
+    if (plan.checks.agentSmoke !== plan.confirmations.agentSmokeCost) {
+        throw planCatalogDrift("agent smoke confirmation");
+    }
+    const expectedMutations = setupMutations(plan.workspace.path, plan.install.targets, selected, plan.credentialSources);
+    if (canonicalJson(plan.mutations) !== canonicalJson(expectedMutations)) {
+        throw planCatalogDrift("declared mutations");
+    }
+}
+function validAgentRoutes(value) {
+    const allowed = new Set(["producerModel", "reviewerModel", "producerPricing", "reviewerPricing"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return false;
+    if (!(value.producerModel === null || typeof value.producerModel === "string") ||
+        !(value.reviewerModel === null || typeof value.reviewerModel === "string")) {
+        return false;
+    }
+    return validNullablePricing(value.producerPricing) && validNullablePricing(value.reviewerPricing);
+}
+function validNullablePricing(value) {
+    if (value === null)
+        return true;
+    if (!isObject(value))
+        return false;
+    const keys = [
+        "inputUsdPerMillionTokens",
+        "cachedInputUsdPerMillionTokens",
+        "outputUsdPerMillionTokens",
+    ];
+    return (Object.keys(value).length === keys.length &&
+        keys.every((key) => typeof value[key] === "number" &&
+            Number.isFinite(value[key]) &&
+            value[key] >= 0));
+}
+function validateEvidenceProfileSelection(profile, selected) {
+    const actual = selected
+        .filter((skill) => skill.sourceId === "brave-search-skills")
+        .map((skill) => skill.id)
+        .sort();
+    const expected = [...BRAVE_PROFILE_SKILLS[profile]].sort();
+    if (canonicalJson(actual) !== canonicalJson(expected)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SELECTION_INVALID",
+            step: "selection",
+            reason: `Brave evidence selection does not exactly match profile ${profile}.`,
+            minimumAction: "Choose one named evidence profile; do not construct a silent partial provider fallback.",
+            retryCommand: "tiangong-ai research setup catalog --json",
+            exitCode: 2,
+        });
+    }
+}
+function validateLicenseAcceptances(selected, acceptedLicenseIds) {
+    const accepted = new Set(acceptedLicenseIds);
+    const missing = selected.filter((skill) => !accepted.has(skill.license.id));
+    if (missing.length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_LICENSE_NOT_ACCEPTED",
+            step: "license",
+            reason: `Explicit license review is missing for: ${missing.map((skill) => skill.id).join(", ")}.`,
+            minimumAction: "Review each pinned license URL and explicitly accept only the Skills you choose to install.",
+            retryCommand: "tiangong-ai research setup catalog --json",
+            exitCode: 2,
+        });
+    }
+}
+function normalizedSettings(selected, supplied) {
+    const definitions = requiredSettingsForSkills(selected);
+    const allowed = new Set(definitions.map((setting) => setting.id));
+    const unknown = Object.keys(supplied).filter((id) => !allowed.has(id));
+    if (unknown.length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SETTING_INVALID",
+            step: "configuration",
+            reason: `Settings are not declared by selected Skills: ${unknown.join(", ")}.`,
+            minimumAction: "Use only the setting IDs reported by setup catalog.",
+            retryCommand: "tiangong-ai research setup catalog --json",
+            exitCode: 2,
+        });
+    }
+    const normalized = {};
+    for (const setting of definitions) {
+        const candidate = supplied[setting.id]?.trim() || setting.defaultValue;
+        if (!candidate) {
+            if (setting.required) {
+                throw setupError({
+                    code: "RESEARCH_SETUP_SETTING_REQUIRED",
+                    step: "configuration",
+                    reason: `Required non-secret setting is missing: ${setting.id}.`,
+                    minimumAction: `Provide ${setting.id} in the reviewed setup settings object.`,
+                    retryCommand: "tiangong-ai research setup plan --help",
+                    exitCode: 2,
+                });
+            }
+            continue;
+        }
+        validateSetupSetting(setting.id, setting.validation, candidate);
+        normalized[setting.id] = candidate;
+    }
+    return Object.fromEntries(Object.entries(normalized).sort(([left], [right]) => left.localeCompare(right)));
+}
+function normalizedCredentialSources(selected, supplied) {
+    const definitions = credentialDefinitionsForSkills(selected);
+    const allowed = new Map(definitions.map((credential) => [credential.id, credential]));
+    const unknown = Object.keys(supplied).filter((id) => !allowed.has(id));
+    if (unknown.length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_INVALID",
+            step: "credentials",
+            reason: `Credential IDs are not declared by selected Skills: ${unknown.join(", ")}.`,
+            minimumAction: "Use only credential IDs reported by setup catalog.",
+            retryCommand: "tiangong-ai research setup catalog --json",
+            exitCode: 2,
+        });
+    }
+    return Object.entries(supplied)
+        .map(([id, fromEnvironment]) => {
+        assertEnvironmentName(fromEnvironment);
+        return { id, fromEnvironment, storage: allowed.get(id).storage };
+    })
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+function normalizeAgentRoutes(value) {
+    return {
+        producerModel: normalizeNullableIdentifier(value?.producerModel),
+        reviewerModel: normalizeNullableIdentifier(value?.reviewerModel),
+        producerPricing: normalizePricing(value?.producerPricing),
+        reviewerPricing: normalizePricing(value?.reviewerPricing),
+    };
+}
+function normalizePricing(value) {
+    if (value === undefined || value === null)
+        return null;
+    const numbers = [
+        value.inputUsdPerMillionTokens,
+        value.cachedInputUsdPerMillionTokens,
+        value.outputUsdPerMillionTokens,
+    ];
+    if (numbers.some((item) => typeof item !== "number" || !Number.isFinite(item) || item < 0)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+            step: "agent-route",
+            reason: "Agent pricing must use finite non-negative USD-per-million-token values.",
+            minimumAction: "Provide current reviewed provider pricing or defer production readiness.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return value;
+}
+function normalizeNullableIdentifier(value) {
+    if (value === undefined || value === null || !value.trim())
+        return null;
+    const normalized = value.trim();
+    if (normalized.length > 200 || /[\r\n\0]/.test(normalized)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+            step: "agent-route",
+            reason: "Agent model identifier is malformed.",
+            minimumAction: "Use an exact provider model identifier without control characters.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return normalized;
+}
+function normalizeAgents(values) {
+    const agents = [...new Set(values)];
+    if (agents.length === 0 || agents.some((agent) => agent !== "codex" && agent !== "claude-code")) {
+        throw setupError({
+            code: "RESEARCH_SETUP_AGENT_INVALID",
+            step: "selection",
+            reason: "Setup agents must be an explicit non-empty subset of codex and claude-code.",
+            minimumAction: "Choose codex, claude-code, or both.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return agents.sort();
+}
+function plannedInstallTargets(workspace, scope, agents, environment, overrides) {
+    const unknownOverride = Object.keys(overrides ?? {}).find((agent) => agent !== "codex" && agent !== "claude-code");
+    if (unknownOverride) {
+        throw setupError({
+            code: "RESEARCH_SETUP_TARGET_INVALID",
+            step: "selection",
+            reason: `Unknown install target agent: ${unknownOverride}.`,
+            minimumAction: "Use only the target roots bound to codex or claude-code.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    const canonicalWorkspace = resolve(workspace);
+    const targets = agents.map((agent) => {
+        const supplied = overrides?.[agent];
+        const target = resolve(supplied ?? setupTargetRoot({ workspace, scope, agent, environment }));
+        const globalBase = agent === "codex" ? dirname(dirname(target)) : dirname(target);
+        const installerCompatibleGlobalTarget = scope !== "global" ||
+            (globalBase !== dirname(globalBase) &&
+                target ===
+                    (agent === "codex" ? join(globalBase, ".agents", "skills") : join(globalBase, "skills")));
+        if (!isAbsolute(target) ||
+            target === resolve(target, sep) ||
+            /[\0\r\n]/.test(target) ||
+            (scope === "project" && target !== setupTargetRoot({ workspace, scope: "project", agent })) ||
+            !installerCompatibleGlobalTarget ||
+            (scope === "global" &&
+                (target === canonicalWorkspace || target.startsWith(`${canonicalWorkspace}${sep}`)))) {
+            throw setupError({
+                code: "RESEARCH_SETUP_TARGET_INVALID",
+                step: "selection",
+                reason: `Install target is incompatible with ${scope} scope for ${agent}.`,
+                minimumAction: "Use project scope for workspace-local copies, or an explicit global agent home outside the workspace.",
+                retryCommand: "tiangong-ai research setup plan --help",
+                exitCode: 2,
+            });
+        }
+        return { agent, root: target };
+    });
+    if (new Set(targets.map((target) => target.root)).size !== targets.length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_TARGET_CONFLICT",
+            step: "selection",
+            reason: "Multiple selected agents resolve to the same install root.",
+            minimumAction: "Choose distinct agent homes or install for only one agent.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return targets;
+}
+function plannedTargetRoot(plan, agent) {
+    const target = plan.install.targets.find((candidate) => candidate.agent === agent);
+    if (!target)
+        throw planCatalogDrift(`missing install target for ${agent}`);
+    return target.root;
+}
+function validEvidenceProfile(value) {
+    return Object.hasOwn(BRAVE_PROFILE_SKILLS, String(value));
+}
+function planCatalogDrift(label) {
+    return setupError({
+        code: "RESEARCH_SETUP_PLAN_CATALOG_DRIFT",
+        step: "plan-validation",
+        reason: `Setup plan ${label} does not match the active immutable catalog.`,
+        minimumAction: "Generate and review a replacement plan; the CLI will not reinterpret an old plan.",
+        retryCommand: "tiangong-ai research setup update --check --json",
+        exitCode: 3,
+    });
+}
+async function ensureSetupWorkspace(plan) {
+    const context = await inspectResearchContext(plan.workspace.path);
+    if (context.role === "workspace") {
+        const config = await loadWorkspaceConfig(plan.workspace.path);
+        if (config.mode !== plan.workspace.mode) {
+            throw setupError({
+                code: "RESEARCH_SETUP_WORKSPACE_CONFLICT",
+                step: "workspace",
+                reason: `Existing workspace mode ${config.mode} differs from plan mode ${plan.workspace.mode}.`,
+                minimumAction: "Create a new reviewed plan for the existing mode or choose a different empty directory.",
+                retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+                exitCode: 3,
+            });
+        }
+        return;
+    }
+    if (context.role !== "setup" && context.role !== "unmanaged") {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_INVALID",
+            step: "workspace",
+            reason: `Target context is ${context.role}.`,
+            minimumAction: "Use an empty regular directory or repair the reported partial workspace state.",
+            retryCommand: `tiangong-ai research context inspect --path ${plan.workspace.path} --json`,
+            exitCode: 3,
+        });
+    }
+    await initializeResearchWorkspace(plan.workspace.path, plan.workspace.name, plan.workspace.mode);
+}
+async function configureAgentRoutes(plan) {
+    if (!plan.agentRoutes.producerModel &&
+        !plan.agentRoutes.reviewerModel &&
+        !plan.agentRoutes.producerPricing &&
+        !plan.agentRoutes.reviewerPricing) {
+        return;
+    }
+    const paths = workspacePaths(plan.workspace.path);
+    const config = await loadWorkspaceConfig(plan.workspace.path);
+    const updated = {
+        ...config,
+        producer: {
+            ...config.producer,
+            ...(plan.agentRoutes.producerModel === null ? {} : { model: plan.agentRoutes.producerModel }),
+            ...(plan.agentRoutes.producerPricing === null
+                ? {}
+                : { pricing: plan.agentRoutes.producerPricing }),
+        },
+        reviewer: {
+            ...config.reviewer,
+            ...(plan.agentRoutes.reviewerModel === null ? {} : { model: plan.agentRoutes.reviewerModel }),
+            ...(plan.agentRoutes.reviewerPricing === null
+                ? {}
+                : { pricing: plan.agentRoutes.reviewerPricing }),
+        },
+    };
+    await writeJsonAtomic(paths.config, updated);
+}
+async function inspectSelectedInstallations(plan, selected, _environment) {
+    const results = [];
+    for (const agent of plan.install.agents) {
+        const root = plannedTargetRoot(plan, agent);
+        const boundary = plan.install.scope === "project"
+            ? plan.workspace.path
+            : agent === "codex"
+                ? dirname(dirname(dirname(root)))
+                : dirname(dirname(root));
+        await assertNoSymlinkedExistingPath(root, boundary);
+        for (const skill of selected) {
+            const path = join(root, skill.skillName);
+            if (!(await pathExists(path))) {
+                results.push({
+                    skillId: skill.id,
+                    skillName: skill.skillName,
+                    agent,
+                    path,
+                    status: "missing",
+                    observedTreeSha256: null,
+                    detail: "Skill is not installed.",
+                });
+                continue;
+            }
+            try {
+                const info = await lstat(path);
+                if (!info.isDirectory() || info.isSymbolicLink()) {
+                    results.push({
+                        skillId: skill.id,
+                        skillName: skill.skillName,
+                        agent,
+                        path,
+                        status: "blocked",
+                        observedTreeSha256: null,
+                        detail: "Install destination is not a regular non-symlink directory.",
+                    });
+                    continue;
+                }
+                const observedTreeSha256 = await hashRegularTree(path);
+                results.push({
+                    skillId: skill.id,
+                    skillName: skill.skillName,
+                    agent,
+                    path,
+                    status: observedTreeSha256 === skill.expectedTreeSha256
+                        ? "installed"
+                        : "drifted",
+                    observedTreeSha256,
+                    detail: observedTreeSha256 === skill.expectedTreeSha256
+                        ? "Installed bytes match the reviewed tree hash."
+                        : "Installed bytes differ from the reviewed tree hash.",
+                });
+            }
+            catch (error) {
+                results.push({
+                    skillId: skill.id,
+                    skillName: skill.skillName,
+                    agent,
+                    path,
+                    status: "blocked",
+                    observedTreeSha256: null,
+                    detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+                });
+            }
+        }
+    }
+    return results;
+}
+async function verifyInstallerPackage(runner, cwd, environment) {
+    const result = await runner({
+        command: "npm",
+        args: [
+            "view",
+            `skills@${RESEARCH_SETUP_INSTALLER.version}`,
+            "version",
+            "dist.integrity",
+            "gitHead",
+            "--json",
+        ],
+        cwd,
+        environment,
+        timeoutMs: 60_000,
+    });
+    if (result.exitCode !== 0) {
+        throw commandFailure("installer-verification", "npm", result, cwd, environment);
+    }
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch {
+        value = null;
+    }
+    if (!isObject(value) ||
+        value.version !== RESEARCH_SETUP_INSTALLER.version ||
+        value["dist.integrity"] !== RESEARCH_SETUP_INSTALLER.npmIntegrity ||
+        value.gitHead !== RESEARCH_SETUP_INSTALLER.gitHead) {
+        throw setupError({
+            code: "RESEARCH_SETUP_INSTALLER_INTEGRITY_FAILED",
+            step: "installer-verification",
+            reason: "npm registry metadata did not match the pinned installer version and integrity.",
+            minimumAction: "Stop and inspect the registry/source metadata; do not bypass installer verification.",
+            retryCommand: `npm view skills@${RESEARCH_SETUP_INSTALLER.version} version dist.integrity gitHead --json`,
+            exitCode: 3,
+        });
+    }
+}
+async function ensureSetupSourceCheckout(plan, sourceId, runner, environment) {
+    const source = plan.sources.find((candidate) => candidate.id === sourceId);
+    if (!source)
+        throw planCatalogDrift(`missing source ${sourceId}`);
+    const checkout = join(workspacePaths(plan.workspace.path).setupSources, `${source.id}-${source.immutableRef.slice(0, 12)}`);
+    await assertNoSymlinkedExistingPath(dirname(checkout), plan.workspace.path);
+    if (!(await pathExists(checkout))) {
+        await ensureDirectory(workspacePaths(plan.workspace.path).setupSources);
+        await runChecked(runner, "git", ["init", "--quiet", checkout], plan.workspace.path, environment, "source-checkout");
+        await runChecked(runner, "git", ["-C", checkout, "remote", "add", "origin", source.locator], plan.workspace.path, environment, "source-checkout");
+    }
+    const info = await lstat(checkout);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SOURCE_INVALID",
+            step: "source-checkout",
+            reason: `Source checkout is not a regular non-symlink directory: ${source.id}.`,
+            minimumAction: "Inspect the source cache; setup will not replace or follow it.",
+            retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+            exitCode: 3,
+        });
+    }
+    let origin = await runner({
+        command: "git",
+        args: ["-C", checkout, "remote", "get-url", "origin"],
+        cwd: plan.workspace.path,
+        environment,
+        timeoutMs: 30_000,
+    });
+    if (origin.exitCode !== 0) {
+        const incompleteHead = await runner({
+            command: "git",
+            args: ["-C", checkout, "rev-parse", "HEAD"],
+            cwd: plan.workspace.path,
+            environment,
+            timeoutMs: 30_000,
+        });
+        if (incompleteHead.exitCode === 0) {
+            throw setupError({
+                code: "RESEARCH_SETUP_SOURCE_DRIFT",
+                step: "source-verification",
+                reason: `Existing source checkout has a commit but no reviewed origin: ${source.id}.`,
+                minimumAction: "Use a new empty source cache path; the CLI will not adopt this checkout.",
+                retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+                exitCode: 3,
+            });
+        }
+        await runChecked(runner, "git", ["-C", checkout, "remote", "add", "origin", source.locator], plan.workspace.path, environment, "source-checkout");
+        origin = await runChecked(runner, "git", ["-C", checkout, "remote", "get-url", "origin"], plan.workspace.path, environment, "source-verification");
+    }
+    if (origin.stdout.trim() !== source.locator) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SOURCE_DRIFT",
+            step: "source-verification",
+            reason: `Source checkout identity differs from the reviewed plan: ${source.id}.`,
+            minimumAction: "Use a new empty source cache path; do not update or rewrite the existing checkout in place.",
+            retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+            exitCode: 3,
+        });
+    }
+    let head = await runner({
+        command: "git",
+        args: ["-C", checkout, "rev-parse", "HEAD"],
+        cwd: plan.workspace.path,
+        environment,
+        timeoutMs: 30_000,
+    });
+    if (head.exitCode !== 0) {
+        // A process may have been interrupted after git init/remote-add. Resume only
+        // that exact incomplete checkout; never rewrite a checkout with a valid,
+        // different HEAD.
+        await runChecked(runner, "git", ["-C", checkout, "fetch", "--depth", "1", "origin", source.immutableRef], plan.workspace.path, environment, "source-checkout", 180_000);
+        await runChecked(runner, "git", ["-C", checkout, "checkout", "--quiet", "--detach", "FETCH_HEAD"], plan.workspace.path, environment, "source-checkout");
+        head = await runChecked(runner, "git", ["-C", checkout, "rev-parse", "HEAD"], plan.workspace.path, environment, "source-verification");
+    }
+    if (head.stdout.trim().toLowerCase() !== source.immutableRef) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SOURCE_DRIFT",
+            step: "source-verification",
+            reason: `Source checkout identity differs from the reviewed plan: ${source.id}.`,
+            minimumAction: "Use a new empty source cache path; do not update or rewrite the existing checkout in place.",
+            retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+            exitCode: 3,
+        });
+    }
+    for (const skill of plan.skills.filter((candidate) => candidate.sourceId === source.id)) {
+        const sourcePath = resolve(checkout, skill.sourceRelativePath);
+        if (!sourcePath.startsWith(`${resolve(checkout)}${sep}`))
+            throw planCatalogDrift("source path");
+        const observedTreeSha256 = await hashRegularTree(sourcePath);
+        if (observedTreeSha256 !== skill.expectedTreeSha256) {
+            throw setupError({
+                code: "RESEARCH_SETUP_SOURCE_HASH_MISMATCH",
+                step: "source-verification",
+                reason: `Pinned source bytes failed the reviewed tree hash for ${skill.id}.`,
+                minimumAction: "Stop and inspect the immutable source; do not install mismatched bytes.",
+                retryCommand: `tiangong-ai research setup update --check --workspace ${plan.workspace.path} --json`,
+                exitCode: 3,
+            });
+        }
+    }
+    return checkout;
+}
+async function installSetupSkills(input) {
+    if (!input.skills.length)
+        return;
+    const args = [
+        "--yes",
+        `skills@${RESEARCH_SETUP_INSTALLER.version}`,
+        "add",
+        input.sourceDirectory,
+        "--skill",
+        ...input.skills.map((skill) => skill.skillName),
+        "--agent",
+        input.agent,
+        "--yes",
+        "--copy",
+        ...(input.plan.install.scope === "global" ? ["--global"] : []),
+    ];
+    const result = await input.runner({
+        command: "npx",
+        args,
+        cwd: input.plan.workspace.path,
+        environment: input.environment,
+        timeoutMs: 5 * 60_000,
+    });
+    if (result.exitCode !== 0) {
+        throw commandFailure("skill-install", "npx", result, input.plan.workspace.path, input.environment);
+    }
+}
+async function configureSelectedCapabilities(plan, _environment) {
+    if (plan.selection.evidenceProfile === "none" &&
+        !plan.selection.skillIds.includes("tiangong.kb-sci-search")) {
+        return;
+    }
+    const codexRoot = plannedTargetRoot(plan, "codex");
+    if (plan.selection.evidenceProfile !== "none") {
+        await configureExternalSkillProfile({
+            workspace: plan.workspace.path,
+            profile: plan.selection.evidenceProfile,
+            skillRoot: codexRoot,
+        });
+    }
+    if (plan.selection.skillIds.includes("tiangong.kb-sci-search")) {
+        const skill = setupSkill("tiangong.kb-sci-search");
+        const source = setupSource(skill.sourceId);
+        await configureTiangongSciCapability({
+            workspace: plan.workspace.path,
+            skillPath: join(codexRoot, skill.skillName),
+            source: {
+                type: "git",
+                locator: source.locator,
+                immutableRef: source.immutableRef,
+                expectedTreeSha256: skill.expectedTreeSha256,
+                license: "MIT",
+                catalogId: "first-party.tiangong.kb-sci-search",
+            },
+            endpoint: plan.settings["tiangong.sci.endpoint"],
+            ...(plan.settings["tiangong.sci.region"] === undefined
+                ? {}
+                : { region: plan.settings["tiangong.sci.region"] }),
+        });
+    }
+}
+async function configurePlanCredentials(plan, environment) {
+    for (const credential of plan.credentialSources) {
+        const definition = RESEARCH_SETUP_CREDENTIALS.find((candidate) => candidate.id === credential.id);
+        if (!definition ||
+            Buffer.byteLength(environment[credential.fromEnvironment] ?? "", "utf8") <
+                definition.minimumUtf8Bytes) {
+            // Credential preflight already proved that an owner-only stored value is
+            // available. Do not require the source environment to remain populated.
+            continue;
+        }
+        await setResearchSetupCredentialFromEnvironment({
+            workspace: plan.workspace.path,
+            credentialId: credential.id,
+            environmentName: credential.fromEnvironment,
+            environment,
+        });
+    }
+}
+async function assertRequiredCredentialPreflight(plan, environment) {
+    const definitions = selectedCredentialDefinitions(plan);
+    let adapterCredentials = new Map();
+    try {
+        adapterCredentials = await loadAdapterCredentials(plan.workspace.path, definitions);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+    }
+    let configuredBrokerIds = new Set();
+    try {
+        const declarations = await loadCapabilityDeclarations(plan.workspace.path);
+        const status = await inspectCapabilityCredentialEnvironment(plan.workspace.path, declarations.capabilities);
+        configuredBrokerIds = new Set(status.configuredIds);
+    }
+    catch {
+        // A first apply has not configured capability declarations yet. The
+        // reviewed plan's environment mapping remains the only accepted source.
+    }
+    const failures = [];
+    for (const definition of definitions) {
+        const planned = plan.credentialSources.find((candidate) => candidate.id === definition.id);
+        const stored = definition.storage === "broker"
+            ? configuredBrokerIds.has(definition.id)
+            : adapterCredentials.has(definition.id);
+        const supplied = planned !== undefined &&
+            Buffer.byteLength(environment[planned.fromEnvironment] ?? "", "utf8") >=
+                definition.minimumUtf8Bytes;
+        if ((!planned && definition.required && !stored) || (planned && !supplied && !stored)) {
+            failures.push({
+                id: definition.id,
+                environmentName: planned?.fromEnvironment ?? null,
+            });
+        }
+    }
+    if (failures.length) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_PREFLIGHT_FAILED",
+            step: "credential-preflight",
+            reason: `Required or explicitly selected credentials are unavailable: ${failures
+                .map((failure) => failure.id)
+                .join(", ")}.`,
+            minimumAction: `Set the reviewed owner environment variables before any download (${failures
+                .map((failure) => `${failure.id}=${failure.environmentName ?? "<mapping-required>"}`)
+                .join(", ")}), then retry this exact step.`,
+            retryCommand: `tiangong-ai research setup retry --step credential-preflight --workspace ${plan.workspace.path} --json`,
+            exitCode: 3,
+        });
+    }
+}
+function selectedCredentialDefinitions(plan) {
+    return credentialDefinitionsForSkills(plan.selection.skillIds.map(setupSkill));
+}
+function credentialDefinitionsForSkills(selected) {
+    const ids = new Set(selected.flatMap((skill) => skill.credentialIds));
+    return RESEARCH_SETUP_CREDENTIALS.filter((credential) => ids.has(credential.id)).sort((left, right) => left.id.localeCompare(right.id));
+}
+function requiredSettingsForSkills(selected) {
+    const ids = new Set(selected.flatMap((skill) => skill.settingIds));
+    return RESEARCH_SETUP_SETTINGS.filter((setting) => ids.has(setting.id)).sort((left, right) => left.id.localeCompare(right.id));
+}
+async function verifiedCompanionSkillDirectory(plan, skill) {
+    const candidates = [...plan.install.targets].sort((left, right) => {
+        if (left.agent === "codex" && right.agent !== "codex")
+            return -1;
+        if (right.agent === "codex" && left.agent !== "codex")
+            return 1;
+        return left.agent.localeCompare(right.agent);
+    });
+    for (const target of candidates) {
+        const directory = join(target.root, skill.skillName);
+        const info = await lstat(directory).catch(() => undefined);
+        if (!info?.isDirectory() || info.isSymbolicLink())
+            continue;
+        if ((await hashRegularTree(directory)) === skill.expectedTreeSha256)
+            return directory;
+    }
+    throw setupError({
+        code: "RESEARCH_SETUP_COMPANION_INSTALL_INVALID",
+        step: "companion-preflight",
+        reason: `${skill.id} is missing, symlinked, or does not match the reviewed tree hash.`,
+        minimumAction: "Run setup status and apply the immutable plan; never execute a drifted companion tree.",
+        retryCommand: `tiangong-ai research setup status --workspace ${plan.workspace.path} --json`,
+        exitCode: 3,
+    });
+}
+async function runDocumentGranularCompanion(input) {
+    const sourcePath = requireAbsoluteCompanionPath(input.input.inputPath, "--input");
+    const destination = requireAbsoluteCompanionPath(input.input.outputPath, "--output");
+    if (sourcePath === destination) {
+        throw companionPathError(input.root, "Input and output paths must be different.");
+    }
+    const sourceInfo = await requireRegularCompanionFile(input.root, sourcePath, "input");
+    if (sourceInfo.size <= 0) {
+        throw companionPathError(input.root, "The input file is empty.");
+    }
+    await requireNewCompanionDestination(input.root, destination);
+    const sourceSha256 = await sha256File(sourcePath);
+    const tokenDefinition = input.credentialDefinitions.find((definition) => definition.id === "tiangong.unstructure.auth-token");
+    const token = input.credentials.get("tiangong.unstructure.auth-token");
+    if (!tokenDefinition || !token) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_MISSING",
+            step: "companion-preflight",
+            reason: "The selected document adapter has no configured authorization credential.",
+            minimumAction: "Use research setup credential set with an owner environment variable, then retry.",
+            retryCommand: `tiangong-ai research setup credential set --id tiangong.unstructure.auth-token --from-env <OWNER_ENV_NAME> --workspace ${input.root} --json`,
+            exitCode: 3,
+        });
+    }
+    const endpoint = input.plan.settings["tiangong.unstructure.base-url"];
+    if (!endpoint) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SETTING_MISSING",
+            step: "companion-preflight",
+            reason: "The immutable setup plan has no Tiangong Unstructure base URL.",
+            minimumAction: "Create a replacement setup plan with the required HTTPS base URL.",
+            retryCommand: `tiangong-ai research setup status --workspace ${input.root} --json`,
+            exitCode: 3,
+        });
+    }
+    const script = join(input.skillDirectory, "scripts", "mineru_fulltext_extract.py");
+    await requireRegularCompanionFile(input.root, script, "adapter script");
+    const temporary = join(dirname(destination), `.${basename(destination)}.${process.pid}.${randomUUID()}.part`);
+    const timeoutSeconds = normalizedCompanionTimeout(input.input.timeoutSeconds, 600, 3_600);
+    const childEnvironment = companionEnvironment(input.environment);
+    childEnvironment.UNSTRUCTURED_AUTH_TOKEN = token;
+    childEnvironment.UNSTRUCTURED_API_BASE_URL = endpoint;
+    const provider = input.plan.settings["tiangong.unstructure.provider"];
+    const model = input.plan.settings["tiangong.unstructure.model"];
+    if (provider)
+        childEnvironment.UNSTRUCTURED_PROVIDER = provider;
+    if (model)
+        childEnvironment.UNSTRUCTURED_MODEL = model;
+    let destinationLinked = false;
+    let committed = false;
+    try {
+        await runChecked(input.runner, "python3", [script, "--file", sourcePath, "--output", temporary, "--timeout", String(timeoutSeconds)], input.root, childEnvironment, "companion-document-extract", (timeoutSeconds + 30) * 1_000);
+        if ((await sha256File(sourcePath)) !== sourceSha256 ||
+            (await fileSize(sourcePath)) !== sourceInfo.size) {
+            throw setupError({
+                code: "RESEARCH_SETUP_COMPANION_INPUT_CHANGED",
+                step: "companion-document-extract",
+                reason: "The source document changed while preprocessing was running.",
+                minimumAction: "Retry with a stable, immutable input file.",
+                retryCommand: `tiangong-ai research setup companion run --help`,
+                exitCode: 3,
+            });
+        }
+        const outputInfo = await requireRegularCompanionFile(input.root, temporary, "temporary output");
+        if (outputInfo.size <= 0 || outputInfo.size > 128 * 1024 * 1024) {
+            throw setupError({
+                code: "RESEARCH_SETUP_COMPANION_OUTPUT_INVALID",
+                step: "companion-document-extract",
+                reason: "The extracted full text is empty or exceeds the 128 MiB adapter limit.",
+                minimumAction: "Inspect the source and service response, then retry with a bounded document.",
+                retryCommand: `tiangong-ai research setup companion run --help`,
+                exitCode: 3,
+            });
+        }
+        await requireNewCompanionDestination(input.root, destination);
+        await link(temporary, destination).catch((error) => {
+            throw setupError({
+                code: "RESEARCH_SETUP_COMPANION_COMMIT_FAILED",
+                step: "companion-document-commit",
+                reason: `The no-overwrite atomic output commit failed (${sanitizeResearchText(error instanceof Error ? error.message : String(error))}).`,
+                minimumAction: "Choose a new explicit output path on the same filesystem and retry; existing files are never replaced.",
+                retryCommand: `tiangong-ai research setup companion run --help`,
+                exitCode: 3,
+            });
+        });
+        destinationLinked = true;
+        await chmod(destination, 0o600).catch(async (error) => {
+            await rm(destination, { force: true });
+            destinationLinked = false;
+            throw error;
+        });
+        const outputSha256 = await sha256File(destination);
+        await appendJournalEvent(workspacePaths(input.root).journal, "research.setup.companion.document.completed", "workspace", {
+            planSha256: input.plan.planSha256,
+            skillId: input.skill.id,
+            skillTreeSha256: input.skill.expectedTreeSha256,
+            sourceRef: setupSource(input.skill.sourceId).immutableRef,
+            input: { sha256: sourceSha256, bytes: sourceInfo.size },
+            output: { sha256: outputSha256, bytes: outputInfo.size },
+        });
+        committed = true;
+        return {
+            schemaVersion: 1,
+            kind: "research-setup-companion-result",
+            status: "complete",
+            workspace: input.root,
+            skillId: input.skill.id,
+            role: input.skill.role,
+            input: { path: sourcePath, sha256: sourceSha256, bytes: sourceInfo.size },
+            output: { path: destination, sha256: outputSha256, bytes: outputInfo.size },
+            provenance: companionProvenance(input.plan, input.skill),
+            next: "Admit the exact output path as a declared research input; preprocessing does not itself admit evidence.",
+        };
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (destinationLinked && !committed) {
+            await rm(destination, { force: true }).catch(() => undefined);
+        }
+    }
+}
+async function runAcademicPaperCompanion(input) {
+    const outputDirectory = requireAbsoluteCompanionPath(input.input.outputDirectory, "--out");
+    const outputInfo = await lstat(outputDirectory).catch(() => undefined);
+    if (!outputInfo?.isDirectory() || outputInfo.isSymbolicLink()) {
+        throw companionPathError(input.root, "--out must be an existing regular non-symlink directory.");
+    }
+    const doi = input.input.doi?.trim();
+    const title = input.input.title?.trim();
+    if (Boolean(doi) === Boolean(title)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_ARGUMENT_INVALID",
+            step: "companion-preflight",
+            reason: "Academic paper acquisition requires exactly one of --doi or --title.",
+            minimumAction: "Provide one exact paper identifier and retry.",
+            retryCommand: `tiangong-ai research setup companion run --help`,
+            exitCode: 2,
+        });
+    }
+    if ((input.input.author || input.input.year !== undefined) && !title) {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_ARGUMENT_INVALID",
+            step: "companion-preflight",
+            reason: "--author and --year may be used only together with --title.",
+            minimumAction: "Provide --title, or remove the disambiguation options.",
+            retryCommand: `tiangong-ai research setup companion run --help`,
+            exitCode: 2,
+        });
+    }
+    if (input.input.year !== undefined &&
+        (!Number.isInteger(input.input.year) || input.input.year < 1000 || input.input.year > 9999)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_ARGUMENT_INVALID",
+            step: "companion-preflight",
+            reason: "--year must be a four-digit integer.",
+            minimumAction: "Correct the publication year and retry.",
+            retryCommand: `tiangong-ai research setup companion run --help`,
+            exitCode: 2,
+        });
+    }
+    const script = join(input.skillDirectory, "scripts", "fetch.py");
+    await requireRegularCompanionFile(input.root, script, "adapter script");
+    const timeoutSeconds = normalizedCompanionTimeout(input.input.timeoutSeconds, 30, 600);
+    const args = [script];
+    if (doi)
+        args.push(doi);
+    else
+        args.push("--title", title);
+    if (input.input.author)
+        args.push("--author", input.input.author);
+    if (input.input.year !== undefined)
+        args.push("--year", String(input.input.year));
+    args.push("--out", outputDirectory, "--format", "json", "--timeout", String(timeoutSeconds));
+    const childEnvironment = companionEnvironment(input.environment);
+    const semanticScholarKey = input.credentials.get("semantic-scholar.api-key");
+    if (semanticScholarKey)
+        childEnvironment.SEMANTIC_SCHOLAR_API_KEY = semanticScholarKey;
+    const unpaywallEmail = input.plan.settings["unpaywall.contact-email"];
+    if (unpaywallEmail)
+        childEnvironment.UNPAYWALL_EMAIL = unpaywallEmail;
+    const execution = await input.runner({
+        command: "python3",
+        args,
+        cwd: input.root,
+        environment: childEnvironment,
+        timeoutMs: (timeoutSeconds + 60) * 4 * 1_000,
+    });
+    const envelope = parseCompanionJson(execution.stdout, input.root, "academic-paper-download");
+    const results = isObject(envelope.data) && Array.isArray(envelope.data.results) ? envelope.data.results : [];
+    if (results.length !== 1 || !isObject(results[0])) {
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_OUTPUT_INVALID",
+            step: "companion-paper-download",
+            reason: "The pinned paper adapter did not return exactly one structured result.",
+            minimumAction: "Verify the pinned Python dependencies and rerun setup doctor.",
+            retryCommand: `tiangong-ai research setup doctor --workspace ${input.root} --json`,
+            exitCode: 3,
+        });
+    }
+    const result = results[0];
+    if (execution.exitCode !== 0 || result.success !== true) {
+        if (result.success === false &&
+            isObject(result.browser_handoff) &&
+            result.file === null &&
+            result.manifest === null) {
+            await appendJournalEvent(workspacePaths(input.root).journal, "research.setup.companion.paper.handoff-required", "workspace", {
+                planSha256: input.plan.planSha256,
+                skillId: input.skill.id,
+                skillTreeSha256: input.skill.expectedTreeSha256,
+                querySha256: sha256Text(doi ?? title),
+                sourcesTried: Array.isArray(result.sources_tried) ? result.sources_tried : [],
+                artifactCommitted: false,
+            });
+            return {
+                schemaVersion: 1,
+                kind: "research-setup-companion-result",
+                status: "browser-handoff-required",
+                workspace: input.root,
+                skillId: input.skill.id,
+                role: input.skill.role,
+                artifactCommitted: false,
+                sourcesTried: Array.isArray(result.sources_tried) ? result.sources_tried : [],
+                error: sanitizeResearchRecord(isObject(result.error) ? result.error : {}),
+                provenance: companionProvenance(input.plan, input.skill),
+                next: "Automatic legal OA sources were exhausted. Follow the installed academic-paper-download browser-handoff reference explicitly; no browser is launched or selected automatically.",
+            };
+        }
+        throw setupError({
+            code: "RESEARCH_SETUP_COMPANION_COMMAND_FAILED",
+            step: "companion-paper-download",
+            reason: `The pinned paper adapter exited with status ${execution.exitCode}.`,
+            minimumAction: sanitizeResearchText(execution.stderr).trim().slice(0, 500) ||
+                "Inspect the structured adapter error and verify its pinned Python dependencies.",
+            retryCommand: `tiangong-ai research setup doctor --workspace ${input.root} --json`,
+            exitCode: 3,
+        });
+    }
+    const artifactPath = requireContainedArtifactPath(result.file, outputDirectory, "file");
+    const manifestPath = requireContainedArtifactPath(result.manifest, outputDirectory, "manifest");
+    const artifactInfo = await requireRegularCompanionFile(input.root, artifactPath, "PDF artifact");
+    const manifestInfo = await requireRegularCompanionFile(input.root, manifestPath, "PDF manifest");
+    if (artifactInfo.size <= 0 || artifactInfo.size > 100 * 1024 * 1024) {
+        throw companionArtifactError(input.root, "The committed PDF size is outside the adapter limit.");
+    }
+    const artifactSha256 = await sha256File(artifactPath);
+    if (result.sha256 !== artifactSha256 || result.size !== artifactInfo.size) {
+        throw companionArtifactError(input.root, "The result metadata does not bind the committed PDF bytes.");
+    }
+    const manifest = await readJsonFile(manifestPath, "Paper manifest");
+    if (manifest.schema_version !== "academic-paper-download.artifact.v2" ||
+        manifest.file !== artifactPath ||
+        manifest.sha256 !== artifactSha256 ||
+        manifest.size !== artifactInfo.size) {
+        throw companionArtifactError(input.root, "The manifest does not bind the exact committed PDF.");
+    }
+    await verifyPdfEnvelope(artifactPath, artifactInfo.size, input.root);
+    const manifestSha256 = await sha256File(manifestPath);
+    await appendJournalEvent(workspacePaths(input.root).journal, "research.setup.companion.paper.completed", "workspace", {
+        planSha256: input.plan.planSha256,
+        skillId: input.skill.id,
+        skillTreeSha256: input.skill.expectedTreeSha256,
+        sourceRef: setupSource(input.skill.sourceId).immutableRef,
+        querySha256: sha256Text(doi ?? title),
+        source: typeof manifest.source === "string" ? manifest.source : null,
+        artifact: { sha256: artifactSha256, bytes: artifactInfo.size },
+        manifest: { sha256: manifestSha256, bytes: manifestInfo.size },
+    });
+    return {
+        schemaVersion: 1,
+        kind: "research-setup-companion-result",
+        status: "complete",
+        workspace: input.root,
+        skillId: input.skill.id,
+        role: input.skill.role,
+        artifact: { path: artifactPath, sha256: artifactSha256, bytes: artifactInfo.size },
+        manifest: { path: manifestPath, sha256: manifestSha256, bytes: manifestInfo.size },
+        source: typeof manifest.source === "string" ? manifest.source : null,
+        provenance: companionProvenance(input.plan, input.skill),
+        validation: [
+            "pinned-adapter-pypdf",
+            "pdf-header",
+            "pdf-eof",
+            "size",
+            "sha256",
+            "atomic-artifact-and-manifest",
+        ],
+        next: "Admit the exact PDF or a derived hash-bound view as a declared research input.",
+    };
+}
+function companionEnvironment(source) {
+    const result = installerEnvironment(source);
+    delete result.CI;
+    return result;
+}
+function normalizedCompanionTimeout(value, defaultValue, maximum) {
+    const resolved = value ?? defaultValue;
+    if (!Number.isInteger(resolved) || resolved < 1 || resolved > maximum) {
+        throw new CliError(`Companion timeout must be an integer from 1 to ${maximum} seconds.`, {
+            code: "RESEARCH_SETUP_COMPANION_ARGUMENT_INVALID",
+            exitCode: 2,
+        });
+    }
+    return resolved;
+}
+function requireAbsoluteCompanionPath(value, label) {
+    if (!value || !isAbsolute(value) || resolve(value) !== value) {
+        throw new CliError(`${label} must be an absolute canonical path.`, {
+            code: "RESEARCH_SETUP_COMPANION_PATH_INVALID",
+            exitCode: 2,
+        });
+    }
+    return value;
+}
+async function requireRegularCompanionFile(root, path, label) {
+    const info = await lstat(path).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw companionPathError(root, `The ${label} must be a regular non-symlink file.`);
+    }
+    return info;
+}
+async function requireNewCompanionDestination(root, destination) {
+    const parentInfo = await lstat(dirname(destination)).catch(() => undefined);
+    if (!parentInfo?.isDirectory() || parentInfo.isSymbolicLink()) {
+        throw companionPathError(root, "The output parent must be an existing regular directory.");
+    }
+    if (await pathExists(destination)) {
+        throw companionPathError(root, "The explicit output path already exists and will not be replaced.");
+    }
+    const dangling = await lstat(destination).catch(() => undefined);
+    if (dangling) {
+        throw companionPathError(root, "The explicit output path is occupied, including by a symlink.");
+    }
+}
+function requireContainedArtifactPath(value, root, label) {
+    if (typeof value !== "string" || !isAbsolute(value) || resolve(value) !== value) {
+        throw companionArtifactError(root, `The adapter returned an invalid ${label} path.`);
+    }
+    const rel = relative(root, value);
+    if (!rel || rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) {
+        throw companionArtifactError(root, `The adapter returned a ${label} outside --out.`);
+    }
+    return value;
+}
+function parseCompanionJson(stdout, root, label) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (isObject(parsed))
+            return parsed;
+    }
+    catch {
+        // Fall through to the structured error below without echoing untrusted output.
+    }
+    throw setupError({
+        code: "RESEARCH_SETUP_COMPANION_OUTPUT_INVALID",
+        step: "companion-output",
+        reason: `${label} did not emit one valid JSON object.`,
+        minimumAction: "Verify the pinned Skill tree and its locked dependencies, then retry.",
+        retryCommand: `tiangong-ai research setup doctor --workspace ${root} --json`,
+        exitCode: 3,
+    });
+}
+async function verifyPdfEnvelope(path, size, root) {
+    const handle = await open(path, "r");
+    try {
+        const header = Buffer.alloc(5);
+        await handle.read(header, 0, 5, 0);
+        const tailLength = Math.min(8_192, size);
+        const tail = Buffer.alloc(tailLength);
+        await handle.read(tail, 0, tailLength, size - tailLength);
+        if (header.toString("ascii") !== "%PDF-" || !tail.includes(Buffer.from("%%EOF"))) {
+            throw companionArtifactError(root, "The committed artifact failed PDF envelope validation.");
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+function companionProvenance(plan, skill) {
+    return {
+        planSha256: plan.planSha256,
+        sourceId: skill.sourceId,
+        sourceRef: setupSource(skill.sourceId).immutableRef,
+        skillTreeSha256: skill.expectedTreeSha256,
+    };
+}
+function companionPathError(root, reason) {
+    return setupError({
+        code: "RESEARCH_SETUP_COMPANION_PATH_INVALID",
+        step: "companion-preflight",
+        reason,
+        minimumAction: "Use explicit regular paths with no symlink at the input, output, or parent.",
+        retryCommand: `tiangong-ai research setup companion run --help`,
+        exitCode: 2,
+    });
+}
+function companionArtifactError(root, reason) {
+    return setupError({
+        code: "RESEARCH_SETUP_COMPANION_ARTIFACT_INVALID",
+        step: "companion-paper-verify",
+        reason,
+        minimumAction: "Do not admit the file. Inspect the pinned adapter environment and rerun acquisition to a clean directory.",
+        retryCommand: `tiangong-ai research setup doctor --workspace ${root} --json`,
+        exitCode: 3,
+    });
+}
+async function loadAdapterCredentials(root, definitions) {
+    const path = workspacePaths(root).setupAdapterEnv;
+    if (!(await pathExists(path)))
+        return new Map();
+    const info = await lstat(path).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+            step: "credentials",
+            reason: "Adapter credential store must be a regular non-symlink file.",
+            minimumAction: "Repair the owner-only adapter credential store; do not follow or replace a symlink.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+            step: "credentials",
+            reason: "Adapter credential store must have owner-only permissions.",
+            minimumAction: `Run chmod 600 on ${path}, then retry doctor.`,
+            retryCommand: `tiangong-ai research setup doctor --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    if (info.size > 64 * 1024) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+            step: "credentials",
+            reason: "Adapter credential store exceeds the supported size.",
+            minimumAction: "Remove unrelated material from the credential store.",
+            retryCommand: `tiangong-ai research setup doctor --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    const content = await readFile(path, "utf8");
+    const lines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"));
+    if (lines.length !== 1 || !lines[0].startsWith(`${ADAPTER_ENV_KEY}=`)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+            step: "credentials",
+            reason: "Adapter credential store has unsupported keys or duplicate configuration.",
+            minimumAction: "Use research setup credential set to create the supported owner-only format.",
+            retryCommand: `tiangong-ai research setup credential set --help`,
+            exitCode: 3,
+        });
+    }
+    let value;
+    try {
+        value = JSON.parse(lines[0].slice(ADAPTER_ENV_KEY.length + 1));
+    }
+    catch {
+        value = null;
+    }
+    if (!isObject(value)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+            step: "credentials",
+            reason: "Adapter credential JSON is invalid.",
+            minimumAction: "Use research setup credential set to rewrite the owner-only store.",
+            retryCommand: `tiangong-ai research setup credential set --help`,
+            exitCode: 3,
+        });
+    }
+    const allowed = new Map(definitions.map((definition) => [definition.id, definition]));
+    const result = new Map();
+    for (const [id, credentialValue] of Object.entries(value)) {
+        const definition = allowed.get(id);
+        if (!definition ||
+            typeof credentialValue !== "string" ||
+            Buffer.byteLength(credentialValue, "utf8") < definition.minimumUtf8Bytes) {
+            throw setupError({
+                code: "RESEARCH_SETUP_CREDENTIAL_STORE_INVALID",
+                step: "credentials",
+                reason: `Adapter credential entry is undeclared or invalid: ${id}.`,
+                minimumAction: "Create a new setup plan or repair credentials through the supported command.",
+                retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                exitCode: 3,
+            });
+        }
+        result.set(id, credentialValue);
+    }
+    return result;
+}
+async function setAdapterCredential(root, definitions, credentialId, value) {
+    const configured = await loadAdapterCredentials(root, definitions);
+    configured.set(credentialId, value);
+    const serialized = Object.fromEntries([...configured.entries()].sort(([left], [right]) => left.localeCompare(right)));
+    await writeTextAtomic(workspacePaths(root).setupAdapterEnv, `${ADAPTER_ENV_KEY}=${JSON.stringify(serialized)}\n`, 0o600);
+}
+function initialSetupState(planSha256) {
+    return {
+        schemaVersion: 1,
+        planSha256,
+        status: "pending",
+        currentStep: null,
+        completedSteps: [],
+        attempts: 0,
+        updatedAt: new Date().toISOString(),
+        lastError: null,
+    };
+}
+async function loadSetupState(root, planSha256) {
+    const path = workspacePaths(root).setupState;
+    if (!(await pathExists(path)))
+        return initialSetupState(planSha256);
+    const value = await readJsonFile(path, "Research setup state");
+    if (!isObject(value) ||
+        value.schemaVersion !== 1 ||
+        value.planSha256 !== planSha256 ||
+        !["pending", "applying", "partially-ready", "ready", "blocked"].includes(String(value.status)) ||
+        !(value.currentStep === null || typeof value.currentStep === "string") ||
+        !Array.isArray(value.completedSteps) ||
+        value.completedSteps.some((step) => typeof step !== "string") ||
+        typeof value.attempts !== "number" ||
+        !Number.isInteger(value.attempts) ||
+        typeof value.updatedAt !== "string" ||
+        !(value.lastError === null || isObject(value.lastError))) {
+        throw setupError({
+            code: "RESEARCH_SETUP_STATE_INVALID",
+            step: "state",
+            reason: "Setup state is malformed or belongs to a different plan.",
+            minimumAction: "Inspect the immutable plan and state; do not continue from unbound state.",
+            retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+            exitCode: 3,
+        });
+    }
+    return value;
+}
+async function updateSetupState(root, state) {
+    const next = sanitizeResearchRecord({
+        ...state,
+        updatedAt: new Date().toISOString(),
+    });
+    await writeJsonAtomic(workspacePaths(root).setupState, next);
+    return next;
+}
+async function startSetupStep(root, state, step) {
+    return updateSetupState(root, { ...state, status: "applying", currentStep: step });
+}
+async function completeSetupStep(root, state, step) {
+    return updateSetupState(root, {
+        ...state,
+        status: "applying",
+        currentStep: null,
+        completedSteps: [...new Set([...state.completedSteps, step])],
+    });
+}
+async function archiveSetupGeneration(root) {
+    const paths = workspacePaths(root);
+    const prior = await loadHashVerifiedResearchSetupPlan(paths.setupPlan);
+    const archiveRoot = join(paths.control, "setup-history", prior.planSha256);
+    await assertNoSymlinkedExistingPath(dirname(archiveRoot), root);
+    await ensureDirectory(archiveRoot);
+    const files = [
+        [paths.setupPlan, "setup-plan.json"],
+        [paths.setupState, "setup-state.json"],
+        [paths.setupReport, "setup-report.json"],
+    ];
+    for (const [source, name] of files) {
+        if (!(await pathExists(source)))
+            continue;
+        const sourceInfo = await lstat(source);
+        if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink()) {
+            throw setupError({
+                code: "RESEARCH_SETUP_ARCHIVE_INVALID",
+                step: "upgrade-plan",
+                reason: `Setup generation file is not a regular non-symlink file: ${name}.`,
+                minimumAction: "Inspect the current generation before creating an upgrade plan.",
+                retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                exitCode: 3,
+            });
+        }
+        const destination = join(archiveRoot, name);
+        const content = await readFile(source, "utf8");
+        if (await pathExists(destination)) {
+            const destinationInfo = await lstat(destination);
+            if (!destinationInfo.isFile() ||
+                destinationInfo.isSymbolicLink() ||
+                (await readFile(destination, "utf8")) !== content) {
+                throw setupError({
+                    code: "RESEARCH_SETUP_ARCHIVE_INVALID",
+                    step: "upgrade-plan",
+                    reason: `Existing setup history does not match the generation being archived: ${name}.`,
+                    minimumAction: "Stop and audit setup-history; the CLI will not overwrite it.",
+                    retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+                    exitCode: 3,
+                });
+            }
+            continue;
+        }
+        await writeTextAtomic(destination, content, 0o444);
+    }
+    return prior.planSha256;
+}
+function requireAbsoluteWorkspace(value) {
+    if (!value || !isAbsolute(value) || /[\0\r\n]/.test(value)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_INVALID",
+            step: "workspace",
+            reason: "Setup workspace must be an explicit absolute path.",
+            minimumAction: "Choose or create an absolute workspace directory, then retry.",
+            retryCommand: "tiangong-ai research setup --help",
+            exitCode: 2,
+        });
+    }
+    return resolve(value);
+}
+async function assertWorkspaceDirectory(root) {
+    const info = await lstat(root).catch(() => undefined);
+    if (!info?.isDirectory() || info.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_INVALID",
+            step: "workspace",
+            reason: "Setup workspace must exist as a regular non-symlink directory.",
+            minimumAction: `Create the directory explicitly, then retry with --workspace ${root}.`,
+            retryCommand: "tiangong-ai research setup --help",
+            exitCode: 2,
+        });
+    }
+    await assertNoSymlinkedExistingPath(root);
+}
+function normalizedWorkspaceName(value) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 100 || /[\u0000-\u001f]/.test(normalized)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_NAME_INVALID",
+            step: "workspace",
+            reason: "Workspace name must contain 1-100 printable characters.",
+            minimumAction: "Choose a short printable workspace name.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+    return normalized;
+}
+function assertEnvironmentName(value) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(value)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_CREDENTIAL_INVALID",
+            step: "credentials",
+            reason: "Credential source must be the name of one environment variable.",
+            minimumAction: "Use a variable name such as BRAVE_API_KEY; never put the credential value in CLI arguments.",
+            retryCommand: "tiangong-ai research setup credential set --help",
+            exitCode: 2,
+        });
+    }
+}
+function validateSetupSetting(id, validation, value) {
+    let valid = false;
+    if (validation === "https-url") {
+        try {
+            const url = new URL(value);
+            valid =
+                url.protocol === "https:" &&
+                    !url.username &&
+                    !url.password &&
+                    !url.hash &&
+                    !url.search &&
+                    url.hostname.length > 0;
+        }
+        catch {
+            valid = false;
+        }
+    }
+    else if (validation === "email") {
+        valid =
+            value.length <= 254 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) && !/[\r\n\0]/.test(value);
+    }
+    else {
+        valid =
+            value.length <= 200 && /^[A-Za-z0-9][A-Za-z0-9._:/+-]*$/.test(value) && !value.includes("..");
+    }
+    if (!valid) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SETTING_INVALID",
+            step: "configuration",
+            reason: `Setup setting failed ${validation} validation: ${id}.`,
+            minimumAction: `Provide a non-secret ${validation} value for ${id}; URLs may not contain credentials, queries, or fragments.`,
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
+}
+function setupMutations(root, targets, selected, credentialSources) {
+    const mutations = [
+        {
+            step: "workspace",
+            target: workspacePaths(root).control,
+            reason: "Initialize or verify the auditable research workspace control plane.",
+        },
+    ];
+    for (const target of targets) {
+        for (const skill of selected) {
+            mutations.push({
+                step: "skill-install",
+                target: join(target.root, skill.skillName),
+                reason: `Copy pinned ${skill.id} bytes for ${target.agent}.`,
+            });
+        }
+    }
+    if (selected.some((skill) => skill.role === "evidence-capability")) {
+        mutations.push({
+            step: "capability-configuration",
+            target: workspacePaths(root).capabilityDeclarations,
+            reason: "Declare and lock the explicitly selected evidence capabilities.",
+        });
+    }
+    if (credentialSources.some((credential) => credential.storage === "broker")) {
+        mutations.push({
+            step: "credentials",
+            target: workspacePaths(root).env,
+            reason: "Store selected broker credentials in the owner-only workspace environment file.",
+        });
+    }
+    if (credentialSources.some((credential) => credential.storage === "adapter")) {
+        mutations.push({
+            step: "credentials",
+            target: workspacePaths(root).setupAdapterEnv,
+            reason: "Store selected companion-adapter credentials in an owner-only file.",
+        });
+    }
+    return mutations.sort((left, right) => `${left.step}\0${left.target}`.localeCompare(`${right.step}\0${right.target}`));
+}
+function setupLockPayload(planSha256) {
+    return {
+        schemaVersion: 1,
+        operation: "research.setup",
+        planSha256,
+        pid: process.pid,
+        hostname: hostname(),
+        acquiredAt: new Date().toISOString(),
+    };
+}
+async function assertNoSymlinkedExistingPath(path, boundary) {
+    const target = resolve(path);
+    const policyRoot = boundary === undefined ? dirname(target) : resolve(boundary);
+    if (boundary !== undefined &&
+        target !== policyRoot &&
+        !target.startsWith(`${policyRoot}${sep}`)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_PATH_INVALID",
+            step: "path-validation",
+            reason: "Setup target escapes its reviewed workspace boundary.",
+            minimumAction: "Use a target contained by the selected workspace.",
+            retryCommand: "tiangong-ai research setup status --json",
+            exitCode: 3,
+        });
+    }
+    const relativeParts = target.slice(policyRoot.length).split(sep).filter(Boolean);
+    let current = policyRoot;
+    for (const part of ["", ...relativeParts]) {
+        if (part)
+            current = join(current, part);
+        const info = await lstat(current).catch((error) => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (!info)
+            continue;
+        if (info.isSymbolicLink()) {
+            throw setupError({
+                code: "RESEARCH_SETUP_SYMLINK_BLOCKED",
+                step: "path-validation",
+                reason: `Setup will not follow a symbolic link in a mutation path: ${current}.`,
+                minimumAction: "Choose a regular directory path or inspect and remove the indirection manually.",
+                retryCommand: "tiangong-ai research setup status --json",
+                exitCode: 3,
+            });
+        }
+        if (current !== target && !info.isDirectory()) {
+            throw setupError({
+                code: "RESEARCH_SETUP_PATH_INVALID",
+                step: "path-validation",
+                reason: `A setup mutation path has a non-directory parent: ${current}.`,
+                minimumAction: "Choose a regular directory path and retry.",
+                retryCommand: "tiangong-ai research setup status --json",
+                exitCode: 3,
+            });
+        }
+    }
+}
+function installerEnvironment(source) {
+    const result = {};
+    const exact = new Set([
+        "PATH",
+        "HOME",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "LANG",
+        "LC_ALL",
+        "SHELL",
+        "USER",
+        "LOGNAME",
+        "HTTP_PROXY",
+        "HTTPS_PROXY",
+        "ALL_PROXY",
+        "NO_PROXY",
+        "http_proxy",
+        "https_proxy",
+        "all_proxy",
+        "no_proxy",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+        "NODE_EXTRA_CA_CERTS",
+        "CODEX_HOME",
+        "CLAUDE_CONFIG_DIR",
+        "VIRTUAL_ENV",
+    ]);
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value !== "string")
+            continue;
+        if ((exact.has(key) || key.startsWith("LC_")) && !isSensitiveEnvironmentName(key)) {
+            result[key] = value;
+        }
+    }
+    result.PATH ??= process.env.PATH ?? "/usr/bin:/bin";
+    result.HOME ??= homedir();
+    result.DO_NOT_TRACK = "1";
+    result.CI = "1";
+    result.npm_config_yes = "true";
+    result.npm_config_update_notifier = "false";
+    result.npm_config_fund = "false";
+    result.npm_config_audit = "false";
+    return result;
+}
+function installerEnvironmentForTarget(plan, agent, source) {
+    const result = installerEnvironment(source);
+    if (plan.install.scope !== "global")
+        return result;
+    const target = plannedTargetRoot(plan, agent);
+    if (agent === "codex") {
+        // skills@1.5.22 treats Codex as a universal agent and installs globally to
+        // $HOME/.agents/skills, independently of CODEX_HOME.
+        result.HOME = dirname(dirname(target));
+        delete result.CODEX_HOME;
+    }
+    else {
+        // The upstream installer resolves Claude Code's global target from
+        // CLAUDE_CONFIG_DIR/skills when that variable is present.
+        result.CLAUDE_CONFIG_DIR = dirname(target);
+    }
+    return result;
+}
+function agentDoctorEnvironment(source) {
+    const result = installerEnvironment(source);
+    delete result.CI;
+    return result;
+}
+function setupSecretValues(plan, environment) {
+    return [
+        ...new Set([
+            ...configuredResearchSecrets(environment),
+            ...plan.credentialSources
+                .map((credential) => environment[credential.fromEnvironment])
+                .filter((value) => typeof value === "string" && value.length >= 8),
+        ]),
+    ];
+}
+function sanitizingSetupRunner(runner, secrets) {
+    return async (input) => {
+        const result = await runner(input);
+        return {
+            exitCode: result.exitCode,
+            stdout: sanitizeResearchText(result.stdout, secrets),
+            stderr: sanitizeResearchText(result.stderr, secrets),
+        };
+    };
+}
+async function runSetupCommand(input) {
+    return new Promise((resolvePromise) => {
+        const secrets = configuredResearchSecrets(input.environment);
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let truncated = false;
+        let settled = false;
+        let timedOut = false;
+        const child = spawn(input.command, input.args, {
+            cwd: input.cwd,
+            env: input.environment,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const capture = (existing, chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remaining = MAX_COMMAND_OUTPUT_BYTES - existing.length;
+            if (remaining <= 0) {
+                truncated = true;
+                return existing;
+            }
+            if (bytes.length > remaining)
+                truncated = true;
+            return Buffer.concat([existing, bytes.subarray(0, remaining)]);
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdout = capture(stdout, chunk);
+            if (truncated)
+                child.kill("SIGTERM");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr = capture(stderr, chunk);
+            if (truncated)
+                child.kill("SIGTERM");
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, input.timeoutMs);
+        timer.unref();
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const suffix = timedOut
+                ? "\n[command timed out]"
+                : truncated
+                    ? "\n[command output limit exceeded]"
+                    : "";
+            resolvePromise({
+                exitCode: timedOut || truncated ? 124 : exitCode,
+                stdout: sanitizeResearchText(stdout.toString("utf8"), secrets),
+                stderr: sanitizeResearchText(`${stderr.toString("utf8")}${suffix}`, secrets),
+            });
+        };
+        child.on("error", (error) => {
+            stderr = capture(stderr, error.message);
+            finish(127);
+        });
+        child.on("close", (code) => finish(code ?? 1));
+    });
+}
+async function runChecked(runner, command, args, cwd, environment, step, timeoutMs = 60_000) {
+    const result = await runner({ command, args, cwd, environment, timeoutMs });
+    if (result.exitCode !== 0)
+        throw commandFailure(step, command, result, cwd, environment);
+    return result;
+}
+function commandFailure(step, command, result, root, environment) {
+    const diagnostic = sanitizeResearchText(result.stderr || result.stdout, configuredResearchSecrets(environment))
+        .trim()
+        .slice(0, 1_000);
+    return setupError({
+        code: "RESEARCH_SETUP_COMMAND_FAILED",
+        step,
+        reason: `${command} exited with status ${result.exitCode}.`,
+        minimumAction: diagnostic
+            ? `Resolve the reported command failure (${diagnostic}), then retry the recorded step.`
+            : "Resolve the command availability or network failure, then retry the recorded step.",
+        retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+        exitCode: 3,
+    });
+}
+async function setupDoctorCheck(checks, id, category, callback) {
+    try {
+        checks.push({
+            id,
+            category,
+            status: "pass",
+            detail: sanitizeResearchText(await callback()),
+            minimumAction: null,
+        });
+    }
+    catch (error) {
+        checks.push({
+            id,
+            category,
+            status: "fail",
+            detail: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+            minimumAction: `Resolve ${id}, then rerun research setup doctor.`,
+        });
+    }
+}
+async function appendDependencyChecks(checks, selected, runner, root, environment) {
+    const dependencies = [
+        ...new Map(selected
+            .flatMap((skill) => skill.dependencies)
+            .map((dependency) => [dependency.id, dependency])).values(),
+    ].sort((left, right) => left.id.localeCompare(right.id));
+    for (const dependency of dependencies) {
+        if (dependency.kind === "manual") {
+            checks.push({
+                id: `dependency.${dependency.id}`,
+                category: "dependency",
+                status: "warn",
+                detail: `${dependency.requirement}; setup intentionally does not install or resolve it.`,
+                minimumAction: dependency.minimumAction,
+            });
+            continue;
+        }
+        await setupDoctorCheck(checks, `dependency.${dependency.id}`, "dependency", async () => {
+            if (dependency.id === "python-3.10") {
+                const result = await runner({
+                    command: "python3",
+                    args: ["--version"],
+                    cwd: root,
+                    environment: installerEnvironment(environment),
+                    timeoutMs: 15_000,
+                });
+                if (result.exitCode !== 0)
+                    throw new Error(dependency.minimumAction);
+                const versionText = `${result.stdout} ${result.stderr}`;
+                const match = versionText.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
+                if (!match || Number(match[1]) < 3 || (Number(match[1]) === 3 && Number(match[2]) < 10)) {
+                    throw new Error(`Detected ${versionText.trim() || "unknown Python version"}; ${dependency.requirement} is required.`);
+                }
+                return `${versionText.trim()} satisfies ${dependency.requirement}.`;
+            }
+            if (dependency.id === "academic-paper-download:pypdf") {
+                const result = await runner({
+                    command: "python3",
+                    args: ["-c", "import importlib.metadata as m; print(m.version('pypdf'))"],
+                    cwd: root,
+                    environment: installerEnvironment(environment),
+                    timeoutMs: 15_000,
+                });
+                const observed = result.stdout.trim();
+                if (result.exitCode !== 0 || observed !== "6.14.2") {
+                    throw new Error(`${dependency.requirement} is not active in the selected python3 environment.`);
+                }
+                return `${dependency.requirement} is active.`;
+            }
+            throw new Error(`No automatic dependency check is declared for ${dependency.id}. ${dependency.minimumAction}`);
+        });
+    }
+}
+async function appendCompanionLiveChecks(checks, input) {
+    void input.sleeper;
+    if (input.selected.some((skill) => skill.id === "tiangong.academic-paper-download")) {
+        await setupDoctorCheck(checks, "live.semantic-scholar", "live-check", async () => {
+            const apiKey = input.adapterCredentials.get("semantic-scholar.api-key");
+            const headers = new Headers({ Accept: "application/json" });
+            if (apiKey)
+                headers.set("x-api-key", apiKey);
+            const response = await input.fetcher("https://api.semanticscholar.org/graph/v1/paper/search?query=reproducible%20research&limit=1&fields=paperId", {
+                method: "GET",
+                headers,
+                redirect: "manual",
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (response.status >= 300 && response.status < 400) {
+                throw new Error("Semantic Scholar returned a redirect; credential-bearing redirects are not followed.");
+            }
+            if (!response.ok) {
+                const detail = await boundedResponseText(response, 2_000, apiKey ? [apiKey] : []);
+                throw new Error(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`);
+            }
+            await response.body?.cancel().catch(() => undefined);
+            return apiKey
+                ? "Semantic Scholar accepted the configured optional API key."
+                : "Semantic Scholar public API is reachable without an optional API key.";
+        });
+    }
+    if (input.selected.some((skill) => skill.id === "tiangong.document-granular-decompose")) {
+        if (!input.allowSyntheticUnstructureUpload) {
+            checks.push({
+                id: "live.tiangong-unstructure",
+                category: "live-check",
+                status: "warn",
+                detail: "Synthetic document upload was not explicitly authorized, so no document was sent.",
+                minimumAction: "Rerun setup doctor with the separate synthetic-upload confirmation after reviewing service cost and data policy.",
+            });
+        }
+        else {
+            await setupDoctorCheck(checks, "live.tiangong-unstructure", "live-check", async () => {
+                const baseUrl = input.plan.settings["tiangong.unstructure.base-url"];
+                const token = input.adapterCredentials.get("tiangong.unstructure.auth-token");
+                if (!baseUrl || !token)
+                    throw new Error("Unstructure URL or owner-only credential is missing.");
+                const form = new FormData();
+                form.set("file", new Blob([syntheticPdfText()], { type: "application/pdf" }), "tiangong-setup-doctor.pdf");
+                const provider = input.plan.settings["tiangong.unstructure.provider"];
+                const model = input.plan.settings["tiangong.unstructure.model"];
+                if (provider)
+                    form.set("provider", provider);
+                if (model)
+                    form.set("model", model);
+                const response = await input.fetcher(`${baseUrl.replace(/\/+$/, "")}/mineru_with_images?return_txt=true`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+                    body: form,
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(120_000),
+                });
+                if (response.status >= 300 && response.status < 400) {
+                    throw new Error("Unstructure returned a redirect; Authorization is never forwarded.");
+                }
+                if (!response.ok) {
+                    const detail = await boundedResponseText(response, 2_000, [token]);
+                    throw new Error(`Unstructure live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`);
+                }
+                await response.body?.cancel().catch(() => undefined);
+                return "Unstructure accepted and processed the explicitly authorized synthetic PDF.";
+            });
+        }
+    }
+}
+async function boundedResponseText(response, maximumBytes, secrets) {
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (bytes < maximumBytes) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            const remaining = maximumBytes - bytes;
+            const chunk = next.value.subarray(0, remaining);
+            chunks.push(chunk);
+            bytes += chunk.length;
+            if (next.value.length > remaining)
+                break;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    return sanitizeResearchText(Buffer.concat(chunks).toString("utf8"), secrets)
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function syntheticPdfText() {
+    const objects = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 300 144] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>",
+        "<< /Length 53 >>\nstream\nBT /F1 12 Tf 36 72 Td (Tiangong setup doctor) Tj ET\nendstream",
+        "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ];
+    let pdf = "%PDF-1.4\n";
+    const offsets = [0];
+    for (let index = 0; index < objects.length; index += 1) {
+        offsets.push(Buffer.byteLength(pdf, "ascii"));
+        pdf += `${index + 1} 0 obj\n${objects[index]}\nendobj\n`;
+    }
+    const xref = Buffer.byteLength(pdf, "ascii");
+    pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`;
+    for (const offset of offsets.slice(1)) {
+        pdf += `${String(offset).padStart(10, "0")} 00000 n \n`;
+    }
+    pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
+    return pdf;
+}
+function setupFailure(error, fallbackStep, root) {
+    if (error instanceof CliError && isObject(error.details)) {
+        const details = sanitizeResearchRecord(error.details);
+        return {
+            code: error.code,
+            step: typeof details.step === "string" ? details.step : fallbackStep,
+            reason: typeof details.reason === "string" ? details.reason : sanitizeResearchText(error.message),
+            minimumAction: typeof details.minimumAction === "string"
+                ? details.minimumAction
+                : "Resolve the reported setup error and retry the exact recorded step.",
+            retryCommand: typeof details.retryCommand === "string"
+                ? details.retryCommand
+                : `tiangong-ai research setup status --workspace ${root} --json`,
+        };
+    }
+    return {
+        code: "RESEARCH_SETUP_UNEXPECTED_FAILURE",
+        step: fallbackStep,
+        reason: sanitizeResearchText(error instanceof Error ? error.message : String(error)),
+        minimumAction: "Inspect the sanitized setup status, correct the failure, and retry the exact recorded step.",
+        retryCommand: `tiangong-ai research setup status --workspace ${root} --json`,
+    };
+}
+function setupError(input) {
+    const details = sanitizeResearchRecord({
+        step: input.step,
+        reason: input.reason,
+        minimumAction: input.minimumAction,
+        retryCommand: input.retryCommand,
+    });
+    return new CliError(sanitizeResearchText(input.reason), {
+        code: input.code,
+        exitCode: input.exitCode,
+        details,
+    });
+}
+//# sourceMappingURL=setup.js.map