@tiangong-ai/cli 0.0.31 → 0.0.33

package/dist/research/workspace/setup.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { chmod, link, lstat, open, readFile, rm } from "node:fs/promises";
+import { chmod, link, lstat, open, readFile, realpath, 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";
@@ -30,10 +30,10 @@ const BRAVE_PROFILE_SKILLS = {
 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 root = await resolveResearchSetupWorkspacePath(input.workspace);
     const scope = input.scope ?? "project";
     const agents = normalizeAgents(input.agents ?? ["codex"]);
+    const agentRoutes = normalizeAgentRoutes(input.agentRoutes);
     if (!input.confirmNetworkDownloads &&
         input.skillIds.length + BRAVE_PROFILE_SKILLS[input.evidenceProfile].length) {
         throw setupError({
@@ -88,6 +88,18 @@ export async function createResearchSetupPlan(input) {
     const selected = resolveSetupSkills([
         ...new Set([...BRAVE_PROFILE_SKILLS[input.evidenceProfile], ...input.skillIds]),
     ]);
+    const producerInstallTarget = agentRoutes.producerAgent === "codex" ? "codex" : "claude-code";
+    if (selected.some((skill) => skill.role === "orchestrator") &&
+        !agents.includes(producerInstallTarget)) {
+        throw setupError({
+            code: "RESEARCH_SETUP_SELECTION_INVALID",
+            step: "selection",
+            reason: `The native ${agentRoutes.producerAgent} producer requires the orchestrator Skill in its project Skill root.`,
+            minimumAction: `Include ${producerInstallTarget} in --agents, or choose the other native producer.`,
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
     if (selected.some((skill) => skill.role === "evidence-capability") && !agents.includes("codex")) {
         throw setupError({
             code: "RESEARCH_SETUP_SELECTION_INVALID",
@@ -102,7 +114,6 @@ export async function createResearchSetupPlan(input) {
     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)
@@ -433,11 +444,11 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
         });
         state = await updateSetupState(root, {
             ...state,
-            status: report.readiness === "READY"
-                ? "ready"
-                : report.readiness === "PARTIALLY_READY"
+            status: report.researchReadiness === "BLOCKED"
+                ? "blocked"
+                : report.overallReadiness === "PARTIALLY_READY"
                     ? "partially-ready"
-                    : "blocked",
+                    : "ready",
             currentStep: null,
             completedSteps: [...new Set([...state.completedSteps, "doctor"])],
         });
@@ -691,41 +702,85 @@ export async function doctorResearchSetup(workspace, options = {}) {
             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() === "win32") {
+        const production = plan.workspace.mode === "production-research";
+        checks.push({
+            id: "platform-sandbox",
+            category: "runtime",
+            scope: "research-core",
+            status: production ? "fail" : "warn",
+            detail: production
+                ? "Production research execution is unsupported on Windows because no approved capsule sandbox is available."
+                : "Windows can inspect and smoke-test setup state, but native research execution requires an approved macOS or Linux capsule sandbox.",
+            minimumAction: production
+                ? "Run production research on macOS with sandbox-exec or Linux with Bubblewrap."
+                : "Use macOS or Linux before switching this workspace to production-research mode.",
+            blocking: production,
+            requiredFor: production ? ["setup", "research-core"] : [],
+        });
+    }
+    else {
+        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");
+        });
+    }
+    checks.push({
+        id: "agent.native-producer",
+        category: "agent",
+        scope: "research-core",
+        status: "pass",
+        detail: `Producer work is bound to the current interactive ${plan.agentRoutes.producerAgent} host; setup will not launch it as a child process.`,
+        minimumAction: null,
+        blocking: true,
+        requiredFor: ["setup", "research-core"],
+    });
+    const reviewerCommand = plan.agentRoutes.reviewerAgent;
+    await setupDoctorCheck(checks, `agent.${reviewerCommand}.reviewer`, "agent", async () => {
+        const result = await runner({
+            command: reviewerCommand,
+            args: ["--version"],
+            cwd: root,
+            environment: agentDoctorEnvironment(environment),
+            timeoutMs: 30_000,
+        });
+        if (result.exitCode !== 0)
+            throw new Error(`${reviewerCommand} is not executable`);
+        return `${reviewerCommand} reviewer CLI is executable (${sanitizeResearchText(result.stdout.trim()).slice(0, 160)}).`;
+    });
+    await setupDoctorCheck(checks, "agent-route-config", "agent", async () => {
+        const config = await loadWorkspaceConfig(root);
+        if (config.producer.executionMode !== "native-host" ||
+            config.reviewer.executionMode !== "headless-cli" ||
+            config.producer.agent === config.reviewer.agent) {
+            throw new Error("Workspace must bind producer=native-host and reviewer=headless-cli on different agent families.");
         }
-        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.";
+        if (config.mode === "production-research" &&
+            (!config.producer.model ||
+                !config.reviewer.model ||
+                !config.producer.pricing ||
+                !config.reviewer.pricing)) {
+            throw new Error("Production agent models and reviewed pricing are incomplete.");
         }
-        throw new Error("Research execution is unsupported on this platform");
+        return `${config.producer.agent}(native-host) -> ${config.reviewer.agent}(headless-cli).`;
     });
-    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) {
@@ -802,10 +857,15 @@ export async function doctorResearchSetup(workspace, options = {}) {
     }
     await appendDependencyChecks(checks, selected, runner, root, environment);
     let capabilityDoctor = null;
+    const blockingBeforeLive = checks
+        .map((check) => normalizeSetupDoctorCheck(check, selected))
+        .filter((check) => check.blocking && check.status === "fail")
+        .map((check) => check.id);
+    const runRequiredLive = options.live === true && blockingBeforeLive.length === 0;
     if (selected.some((skill) => skill.role === "evidence-capability")) {
         try {
             capabilityDoctor = await doctorExternalCapabilities(root, {
-                live: options.live === true,
+                live: runRequiredLive,
                 fetcher,
                 sleeper,
             });
@@ -829,7 +889,20 @@ export async function doctorResearchSetup(workspace, options = {}) {
             });
         }
     }
-    if (options.live) {
+    if (options.live === true && !runRequiredLive) {
+        checks.push({
+            id: "live.required-capabilities.skipped",
+            category: "live-check",
+            scope: "evidence",
+            status: "fail",
+            detail: "Required live capability probes were not started because a static blocking prerequisite failed.",
+            minimumAction: "Resolve the static blocking prerequisites, then rerun live doctor checks.",
+            blocking: true,
+            requiredFor: ["setup", "research-core"],
+            skippedBecause: blockingBeforeLive.join(", "),
+        });
+    }
+    if (runRequiredLive) {
         await appendCompanionLiveChecks(checks, {
             plan,
             selected,
@@ -839,13 +912,45 @@ export async function doctorResearchSetup(workspace, options = {}) {
             allowSyntheticUnstructureUpload: options.allowSyntheticUnstructureUpload === true,
         });
     }
+    else if (options.live === true &&
+        selected.some((skill) => ["input-preprocessor", "acquisition-adapter", "post-closure-authoring"].includes(skill.role))) {
+        checks.push({
+            id: "live.optional-components.skipped",
+            category: "live-check",
+            status: "warn",
+            detail: "Optional component diagnostics were skipped after a static blocking prerequisite failed.",
+            minimumAction: "Resolve the blocking prerequisites before retrying optional diagnostics.",
+            blocking: false,
+            requiredFor: [],
+            skippedBecause: blockingBeforeLive.join(", "),
+        });
+    }
     let workspaceDoctor = null;
+    const blockingPrerequisiteFailures = checks
+        .map((check) => normalizeSetupDoctorCheck(check, selected))
+        .filter((check) => check.blocking && check.status === "fail")
+        .map((check) => check.id);
+    const runAgentSmoke = options.agentSmoke === true && blockingPrerequisiteFailures.length === 0;
+    if (options.agentSmoke === true && !runAgentSmoke) {
+        checks.push({
+            id: "agent-reviewer-smoke.skipped",
+            category: "agent",
+            scope: "review",
+            status: "fail",
+            detail: "The paid reviewer smoke was not started because a zero/low-cost blocking prerequisite failed.",
+            minimumAction: "Resolve the listed blocking prerequisites, then rerun the explicitly confirmed reviewer smoke.",
+            blocking: true,
+            requiredFor: ["setup", "research-core"],
+            skippedBecause: blockingPrerequisiteFailures.join(", "),
+        });
+    }
     try {
         workspaceDoctor = await doctorResearchWorkspace(root, {
-            agentSmoke: options.agentSmoke === true,
-            capabilitySmoke: options.live === true,
+            agentSmoke: runAgentSmoke,
+            capabilitySmoke: runRequiredLive,
             environment,
             capabilityFetcher: fetcher,
+            ...(capabilityDoctor === null ? {} : { capabilityDoctorResult: capabilityDoctor }),
             ...(options.executor === undefined ? {} : { executor: options.executor }),
         });
         const requiredRuntimeChecks = options.agentSmoke === true || options.live === true;
@@ -888,9 +993,16 @@ export async function doctorResearchSetup(workspace, options = {}) {
                 : `Run tiangong-ai research setup doctor --live --workspace ${root} --json after reviewing quota impact.`,
         });
     }
-    const readiness = checks.some((check) => check.status === "fail")
+    const scopedChecks = checks.map((check) => normalizeSetupDoctorCheck(check, selected));
+    const researchReadiness = scopedChecks.some((check) => check.blocking && check.status === "fail")
         ? "BLOCKED"
-        : checks.some((check) => check.status === "warn")
+        : "READY";
+    const preprocessingReadiness = setupDomainReadiness(scopedChecks, "preprocessing");
+    const acquisitionReadiness = setupDomainReadiness(scopedChecks, "acquisition");
+    const authoringReadiness = setupDomainReadiness(scopedChecks, "authoring");
+    const overallReadiness = researchReadiness === "BLOCKED"
+        ? "BLOCKED"
+        : scopedChecks.some((check) => check.status !== "pass")
             ? "PARTIALLY_READY"
             : "READY";
     const setupSecrets = [
@@ -908,14 +1020,19 @@ export async function doctorResearchSetup(workspace, options = {}) {
         planSha256: plan.planSha256,
         checkedAt: new Date().toISOString(),
         mode: options.live ? "live" : "static",
-        readiness,
-        checks,
+        readiness: researchReadiness,
+        researchReadiness,
+        preprocessingReadiness,
+        acquisitionReadiness,
+        authoringReadiness,
+        overallReadiness,
+        checks: scopedChecks,
         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,
+            pass: scopedChecks.filter((check) => check.status === "pass").length,
+            warn: scopedChecks.filter((check) => check.status === "warn").length,
+            fail: scopedChecks.filter((check) => check.status === "fail").length,
         },
     }, setupSecrets);
     await writeJsonAtomic(paths.setupReport, report);
@@ -1206,10 +1323,20 @@ function assertPlanMatchesCatalog(plan) {
     }
 }
 function validAgentRoutes(value) {
-    const allowed = new Set(["producerModel", "reviewerModel", "producerPricing", "reviewerPricing"]);
+    const allowed = new Set([
+        "producerAgent",
+        "reviewerAgent",
+        "producerModel",
+        "reviewerModel",
+        "producerPricing",
+        "reviewerPricing",
+    ]);
     if (Object.keys(value).some((key) => !allowed.has(key)))
         return false;
-    if (!(value.producerModel === null || typeof value.producerModel === "string") ||
+    if ((value.producerAgent !== "codex" && value.producerAgent !== "claude") ||
+        (value.reviewerAgent !== "codex" && value.reviewerAgent !== "claude") ||
+        value.producerAgent === value.reviewerAgent ||
+        !(value.producerModel === null || typeof value.producerModel === "string") ||
         !(value.reviewerModel === null || typeof value.reviewerModel === "string")) {
         return false;
     }
@@ -1318,13 +1445,39 @@ function normalizedCredentialSources(selected, supplied) {
         .sort((left, right) => left.id.localeCompare(right.id));
 }
 function normalizeAgentRoutes(value) {
+    const producerAgent = normalizeAgentKind(value?.producerAgent ?? "codex", "producer");
+    const reviewerAgent = normalizeAgentKind(value?.reviewerAgent ?? (producerAgent === "codex" ? "claude" : "codex"), "reviewer");
+    if (producerAgent === reviewerAgent) {
+        throw setupError({
+            code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+            step: "agent-route",
+            reason: "The native producer and independent reviewer must use different agent families.",
+            minimumAction: "Choose Codex + Claude Code in either producer/reviewer order.",
+            retryCommand: "tiangong-ai research setup plan --help",
+            exitCode: 2,
+        });
+    }
     return {
+        producerAgent,
+        reviewerAgent,
         producerModel: normalizeNullableIdentifier(value?.producerModel),
         reviewerModel: normalizeNullableIdentifier(value?.reviewerModel),
         producerPricing: normalizePricing(value?.producerPricing),
         reviewerPricing: normalizePricing(value?.reviewerPricing),
     };
 }
+function normalizeAgentKind(value, label) {
+    if (value === "codex" || value === "claude")
+        return value;
+    throw setupError({
+        code: "RESEARCH_SETUP_AGENT_ROUTE_INVALID",
+        step: "agent-route",
+        reason: `${label} agent must be codex or claude.`,
+        minimumAction: "Choose Codex or Claude Code and keep the reviewer on the other family.",
+        retryCommand: "tiangong-ai research setup plan --help",
+        exitCode: 2,
+    });
+}
 function normalizePricing(value) {
     if (value === undefined || value === null)
         return null;
@@ -1474,33 +1627,29 @@ async function ensureSetupWorkspace(plan) {
     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 }),
-        },
+        producer: setupAgentRoute(config.producer, plan.agentRoutes.producerAgent, "native-host", plan.agentRoutes.producerModel, plan.agentRoutes.producerPricing),
+        reviewer: setupAgentRoute(config.reviewer, plan.agentRoutes.reviewerAgent, "headless-cli", plan.agentRoutes.reviewerModel, plan.agentRoutes.reviewerPricing),
     };
     await writeJsonAtomic(paths.config, updated);
 }
+function setupAgentRoute(current, agent, executionMode, plannedModel, plannedPricing) {
+    const sameAgent = current.agent === agent;
+    return {
+        agent,
+        executionMode,
+        binary: agent === "codex" ? "codex" : "claude",
+        model: plannedModel ?? (sameAgent ? current.model : null),
+        effort: sameAgent ? (current.effort ?? "low") : "low",
+        ...(agent === "codex" ? { verbosity: sameAgent ? (current.verbosity ?? "low") : "low" } : {}),
+        ...((plannedPricing ?? (sameAgent ? current.pricing : undefined)) === undefined
+            ? {}
+            : { pricing: plannedPricing ?? current.pricing }),
+    };
+}
 async function inspectSelectedInstallations(plan, selected, _environment) {
     const results = [];
     for (const agent of plan.install.agents) {
@@ -2161,6 +2310,12 @@ async function runAcademicPaperCompanion(input) {
     }
     const result = results[0];
     if (execution.exitCode !== 0 || result.success !== true) {
+        const sourcesTried = Array.isArray(result.sources_tried)
+            ? result.sources_tried
+                .filter((source) => typeof source === "string")
+                .map((source) => sanitizeResearchText(source).slice(0, 100))
+            : [];
+        const adapterError = sanitizeResearchRecord(isObject(result.error) ? result.error : {});
         if (result.success === false &&
             isObject(result.browser_handoff) &&
             result.file === null &&
@@ -2170,7 +2325,7 @@ async function runAcademicPaperCompanion(input) {
                 skillId: input.skill.id,
                 skillTreeSha256: input.skill.expectedTreeSha256,
                 querySha256: sha256Text(doi ?? title),
-                sourcesTried: Array.isArray(result.sources_tried) ? result.sources_tried : [],
+                sourcesTried,
                 artifactCommitted: false,
             });
             return {
@@ -2181,20 +2336,32 @@ async function runAcademicPaperCompanion(input) {
                 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 : {}),
+                sourcesTried,
+                error: adapterError,
                 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.",
             };
         }
+        const adapterCode = typeof adapterError.code === "string"
+            ? sanitizeResearchText(adapterError.code).trim().slice(0, 100)
+            : "unknown-adapter-error";
+        const adapterMessage = typeof adapterError.message === "string"
+            ? sanitizeResearchText(adapterError.message).trim().slice(0, 500)
+            : "";
         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) ||
+            reason: `The pinned paper adapter failed (${adapterCode}; exit status ${execution.exitCode}).`,
+            minimumAction: adapterMessage ||
+                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,
+            diagnostics: {
+                adapterError,
+                sourcesTried,
+                artifactCommitted: false,
+            },
         });
     }
     const artifactPath = requireContainedArtifactPath(result.file, outputDirectory, "file");
@@ -2565,6 +2732,84 @@ async function archiveSetupGeneration(root) {
     }
     return prior.planSha256;
 }
+function normalizeSetupDoctorCheck(check, selected) {
+    const componentIds = check.componentIds ?? setupCheckComponentIds(check, selected);
+    const scope = check.scope ?? setupCheckScope(check, selected, componentIds);
+    const blocking = check.blocking ?? ["research-core", "evidence", "review"].includes(scope);
+    return {
+        ...check,
+        scope,
+        componentIds,
+        requiredFor: check.requiredFor ??
+            (blocking
+                ? ["setup", "research-core"]
+                : componentIds.map((componentId) => `component:${componentId}`)),
+        blocking,
+        componentGate: check.componentGate ?? check.id !== "live.semantic-scholar",
+    };
+}
+function setupCheckComponentIds(check, selected) {
+    if (check.id === "live.semantic-scholar")
+        return ["tiangong.academic-paper-download"];
+    if (check.id === "live.tiangong-unstructure") {
+        return ["tiangong.document-granular-decompose"];
+    }
+    if (check.id.startsWith("skill.")) {
+        return selected.filter((skill) => check.id.endsWith(`.${skill.id}`)).map((skill) => skill.id);
+    }
+    if (check.id.startsWith("setting.")) {
+        const id = check.id.slice("setting.".length);
+        const setting = RESEARCH_SETUP_SETTINGS.find((candidate) => candidate.id === id);
+        return selected
+            .filter((skill) => setting?.requiredBy.includes(skill.id))
+            .map((skill) => skill.id);
+    }
+    if (check.id.startsWith("credential.")) {
+        const id = check.id.slice("credential.".length);
+        const credential = RESEARCH_SETUP_CREDENTIALS.find((candidate) => candidate.id === id);
+        return selected
+            .filter((skill) => credential?.requiredBy.includes(skill.id))
+            .map((skill) => skill.id);
+    }
+    if (check.id.startsWith("dependency.")) {
+        const id = check.id.slice("dependency.".length);
+        return selected
+            .filter((skill) => skill.dependencies.some((item) => item.id === id))
+            .map((skill) => skill.id);
+    }
+    return [];
+}
+function setupCheckScope(check, selected, componentIds) {
+    if (check.id === "live.semantic-scholar")
+        return "acquisition";
+    if (check.id === "live.tiangong-unstructure")
+        return "preprocessing";
+    if (check.category === "evidence-capability" || check.id.includes("capability")) {
+        return "evidence";
+    }
+    if (check.category === "agent" || check.id.includes("attestation"))
+        return "review";
+    const roles = componentIds
+        .map((id) => selected.find((skill) => skill.id === id)?.role)
+        .filter((role) => Boolean(role));
+    if (roles.includes("evidence-capability"))
+        return "evidence";
+    if (roles.includes("input-preprocessor"))
+        return "preprocessing";
+    if (roles.includes("acquisition-adapter"))
+        return "acquisition";
+    if (roles.includes("post-closure-authoring"))
+        return "authoring";
+    return "research-core";
+}
+function setupDomainReadiness(checks, scope) {
+    const matching = checks.filter((check) => check.scope === scope);
+    if (matching.length === 0)
+        return "NOT_REQUIRED";
+    if (matching.some((check) => check.blocking && check.status === "fail"))
+        return "BLOCKED";
+    return matching.some((check) => check.status !== "pass") ? "DEGRADED" : "READY";
+}
 function requireAbsoluteWorkspace(value) {
     if (!value || !isAbsolute(value) || /[\0\r\n]/.test(value)) {
         throw setupError({
@@ -2578,9 +2823,25 @@ function requireAbsoluteWorkspace(value) {
     }
     return resolve(value);
 }
-async function assertWorkspaceDirectory(root) {
+export async function resolveResearchSetupWorkspacePath(value, options = {}) {
+    const root = requireAbsoluteWorkspace(value);
     const info = await lstat(root).catch(() => undefined);
-    if (!info?.isDirectory() || info.isSymbolicLink()) {
+    if (info) {
+        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,
+            });
+        }
+        const canonicalRoot = await realpath(root);
+        await assertNoSymlinkedExistingPath(canonicalRoot);
+        return canonicalRoot;
+    }
+    if (!options.allowMissingLeaf) {
         throw setupError({
             code: "RESEARCH_SETUP_WORKSPACE_INVALID",
             step: "workspace",
@@ -2590,7 +2851,24 @@ async function assertWorkspaceDirectory(root) {
             exitCode: 2,
         });
     }
-    await assertNoSymlinkedExistingPath(root);
+    const requestedParent = dirname(root);
+    const canonicalParent = await realpath(requestedParent).catch(() => undefined);
+    const parentInfo = canonicalParent
+        ? await lstat(canonicalParent).catch(() => undefined)
+        : undefined;
+    if (!canonicalParent || !parentInfo?.isDirectory() || parentInfo.isSymbolicLink()) {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_INVALID",
+            step: "workspace",
+            reason: "The parent of a new setup workspace must exist as a regular directory.",
+            minimumAction: `Create the parent directory explicitly, then retry with --workspace ${root}.`,
+            retryCommand: "tiangong-ai research setup --help",
+            exitCode: 2,
+        });
+    }
+    const canonicalRoot = join(canonicalParent, basename(root));
+    await assertNoSymlinkedExistingPath(canonicalRoot);
+    return canonicalRoot;
 }
 function normalizedWorkspaceName(value) {
     const normalized = value.trim();
@@ -2995,15 +3273,36 @@ async function appendDependencyChecks(checks, selected, runner, root, environmen
 async function appendCompanionLiveChecks(checks, input) {
     if (input.selected.some((skill) => skill.id === "tiangong.academic-paper-download")) {
         await appendSemanticScholarLiveCheck(checks, input);
+        const semanticScholar = checks.findLast((check) => check.id === "live.semantic-scholar");
+        checks.push({
+            id: "companion.tiangong.academic-paper-download",
+            category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
+            status: semanticScholar?.status === "pass" ? "pass" : "warn",
+            detail: semanticScholar?.status === "pass"
+                ? "OA resolver diagnostics: Unpaywall=unknown, Semantic Scholar=ready, arXiv=unknown; the deterministic resolver order is unchanged."
+                : "OA resolver diagnostics: Unpaywall=unknown, Semantic Scholar=degraded, arXiv=unknown. The adapter remains available and actual acquisition will stop or request explicit browser handoff only after its ordered OA sources are exhausted.",
+            minimumAction: semanticScholar?.status === "pass"
+                ? null
+                : "Retry the resolver diagnostic later or configure its optional key; unrelated research remains authorized and no standalone evidence fallback is permitted.",
+            blocking: false,
+            componentGate: false,
+            requiredFor: ["component:tiangong.academic-paper-download"],
+        });
     }
     if (input.selected.some((skill) => skill.id === "tiangong.document-granular-decompose")) {
         if (!input.allowSyntheticUnstructureUpload) {
             checks.push({
                 id: "live.tiangong-unstructure",
                 category: "live-check",
+                scope: "preprocessing",
+                componentIds: ["tiangong.document-granular-decompose"],
                 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.",
+                blocking: false,
+                componentGate: true,
             });
         }
         else {
@@ -3068,9 +3367,13 @@ async function appendSemanticScholarLiveCheck(checks, input) {
             checks.push({
                 id: "live.semantic-scholar",
                 category: "live-check",
+                scope: "acquisition",
+                componentIds: ["tiangong.academic-paper-download"],
                 status: "fail",
                 detail: "Semantic Scholar returned a redirect; credential-bearing redirects are not followed.",
-                minimumAction: "Verify the fixed Semantic Scholar endpoint and network policy, then rerun setup doctor; do not fall back to a standalone source wrapper.",
+                minimumAction: "Verify the fixed Semantic Scholar endpoint and network policy before relying on that resolver; do not fall back to a standalone evidence wrapper.",
+                blocking: false,
+                componentGate: false,
                 diagnostics: {
                     code: "PROVIDER_REDIRECT_REJECTED",
                     executionMode: "setup-doctor",
@@ -3090,13 +3393,17 @@ async function appendSemanticScholarLiveCheck(checks, input) {
             checks.push({
                 id: "live.semantic-scholar",
                 category: "live-check",
+                scope: "acquisition",
+                componentIds: ["tiangong.academic-paper-download"],
                 status: "fail",
                 detail: sanitizeResearchText(`Semantic Scholar live check returned HTTP ${response.status}${detail ? `: ${detail}` : ""}.`, apiKey ? [apiKey] : []),
                 minimumAction: rateLimited
-                    ? `Wait for the provider quota window${retryAfterSeconds === null ? "" : ` (Retry-After ${retryAfterSeconds}s)`}, then rerun setup doctor. The production workflow remains blocked and must not downgrade to standalone search.`
+                    ? `Wait for the provider quota window${retryAfterSeconds === null ? "" : ` (Retry-After ${retryAfterSeconds}s)`}, then rerun this optional resolver diagnostic. Unrelated research remains available and must not downgrade to standalone search.`
                     : authenticationFailure
                         ? "Replace or remove the optional Semantic Scholar API key, verify provider entitlement, and rerun setup doctor; do not expose the key in output."
-                        : "Verify Semantic Scholar availability and the fixed API contract, then rerun setup doctor; do not downgrade the research workflow.",
+                        : "Verify Semantic Scholar availability and the fixed API contract before relying on that resolver; do not downgrade the research workflow.",
+                blocking: false,
+                componentGate: false,
                 diagnostics: {
                     code: authenticationFailure
                         ? "PROVIDER_AUTHENTICATION_FAILED"
@@ -3116,20 +3423,28 @@ async function appendSemanticScholarLiveCheck(checks, input) {
         checks.push({
             id: "live.semantic-scholar",
             category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
             status: "pass",
             detail: apiKey
                 ? "Semantic Scholar accepted the configured optional API key."
                 : "Semantic Scholar public API is reachable without an optional API key.",
             minimumAction: null,
+            blocking: false,
+            componentGate: false,
         });
     }
     catch (error) {
         checks.push({
             id: "live.semantic-scholar",
             category: "live-check",
+            scope: "acquisition",
+            componentIds: ["tiangong.academic-paper-download"],
             status: "fail",
             detail: sanitizeResearchText(error instanceof Error ? error.message : String(error), apiKey ? [apiKey] : []),
-            minimumAction: "Restore provider connectivity, then rerun setup doctor; the production workflow must remain blocked instead of using a standalone fallback.",
+            minimumAction: "Restore provider connectivity before relying on Semantic Scholar; unrelated research remains available and no standalone fallback is authorized.",
+            blocking: false,
+            componentGate: false,
             diagnostics: {
                 code: "PROVIDER_TRANSPORT_FAILED",
                 executionMode: "setup-doctor",