@tiangong-ai/cli 0.0.32 → 0.0.34

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, mkdir, open, readFile, readdir, realpath, rename, 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";
@@ -13,8 +13,11 @@ 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, verifyResearchSetupRuntimeContract, } from "./setup-catalog.js";
 import { acquireFileLock, canonicalJson, ensureDirectory, fileSize, hashRegularTree, isObject, pathExists, REGULAR_TREE_HASH_ALGORITHM, readJsonFile, sha256File, sha256Text, workspacePaths, writeJsonAtomic, writeTextAtomic, } from "./storage.js";
-import { packageVersion } from "./constants.js";
+import { packageRoot, packageVersion, RESEARCH_PACKAGE_NAME } from "./constants.js";
+import { exactResearchCliCommand, pinResearchCliCommand, researchSetupApplyCommand, researchSetupRetryCommand, } from "./setup-invocation.js";
 import { doctorResearchWorkspace, initializeResearchWorkspace, loadWorkspaceConfig, } from "./workspace.js";
+const RECOVERY_SKILL_NAME = "tiangong-auto-research-recovery";
+const RECOVERY_SHIM_MARKER = ".tiangong-recovery-shim.json";
 const BRAVE_PROFILE_SKILLS = {
     none: [],
     [EXTERNAL_SKILL_PROFILE]: ["brave.web-search", "brave.news-search"],
@@ -30,8 +33,7 @@ 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);
@@ -330,6 +332,11 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
         state = await startSetupStep(root, state, "credentials");
         await configurePlanCredentials(plan, environment);
         state = await completeSetupStep(root, state, "credentials");
+        if (plan.selection.skillIds.includes("tiangong.auto-research")) {
+            state = await startSetupStep(root, state, "recovery-shim");
+            await installResearchSetupRecoveryShims(plan);
+            state = await completeSetupStep(root, state, "recovery-shim");
+        }
         state = await startSetupStep(root, state, "installation-preflight");
         const selected = plan.selection.skillIds.map(setupSkill);
         const installInspection = await inspectSelectedInstallations(plan, selected, environment);
@@ -356,7 +363,12 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
             ].sort();
             const sourceDirectories = new Map();
             for (const sourceId of requiredSourceIds) {
-                sourceDirectories.set(sourceId, await ensureSetupSourceCheckout(plan, sourceId, runner, installerEnvironment(environment)));
+                try {
+                    sourceDirectories.set(sourceId, await ensureSetupSourceCheckout(plan, sourceId, runner, installerEnvironment(environment)));
+                }
+                catch (error) {
+                    throw await annotateSetupSourceCheckoutFailure(error, plan, sourceId);
+                }
             }
             state = await completeSetupStep(root, state, "source-checkout");
             state = await startSetupStep(root, state, "skill-install");
@@ -397,6 +409,11 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
         else {
             state = await completeSetupStep(root, state, "skill-install");
         }
+        if (plan.selection.skillIds.includes("tiangong.auto-research")) {
+            state = await startSetupStep(root, state, "recovery-shim-cleanup");
+            await removeResearchSetupRecoveryShims(plan);
+            state = await completeSetupStep(root, state, "recovery-shim-cleanup");
+        }
         state = await startSetupStep(root, state, "capability-configuration");
         await configureSelectedCapabilities(plan, environment);
         await reconcilePlanCredentialStores(plan);
@@ -479,12 +496,31 @@ export async function applyResearchSetupPlan(planPath, options = {}) {
     }
 }
 export async function inspectResearchSetupStatus(workspace, environment = process.env) {
-    const root = requireAbsoluteWorkspace(resolve(workspace));
+    const requestedRoot = requireAbsoluteWorkspace(resolve(workspace));
+    const requestedPaths = workspacePaths(requestedRoot);
+    const plan = await loadAndVerifyResearchSetupPlan(requestedPaths.setupPlan);
+    const canonicalRequestedRoot = await realpath(requestedRoot).catch(() => requestedRoot);
+    if (canonicalRequestedRoot !== plan.workspace.path) {
+        throw setupError({
+            code: "RESEARCH_SETUP_WORKSPACE_INVALID",
+            step: "workspace",
+            reason: "The setup plan is bound to a different canonical workspace path.",
+            minimumAction: "Run setup status against the exact workspace recorded in the setup plan.",
+            retryCommand: researchSetupApplyCommand({
+                version: plan.cli.version,
+                planPath: workspacePaths(plan.workspace.path).setupPlan,
+            }),
+            exitCode: 2,
+        });
+    }
+    const root = plan.workspace.path;
     const paths = workspacePaths(root);
-    const plan = await loadAndVerifyResearchSetupPlan(paths.setupPlan);
-    const state = await loadSetupState(root, plan.planSha256);
+    const storedState = await loadSetupState(root, plan.planSha256);
+    const state = setupStateForOutput(storedState, plan, root);
     const selected = plan.selection.skillIds.map(setupSkill);
     const installations = await inspectSelectedInstallations(plan, selected, environment);
+    const credentialReadiness = await inspectSetupCredentialReadiness(plan);
+    const provenance = await inspectSetupProvenance(plan, installations, environment);
     const report = (await pathExists(paths.setupReport))
         ? await readJsonFile(paths.setupReport, "Research setup report")
         : null;
@@ -502,16 +538,420 @@ export async function inspectResearchSetupStatus(workspace, environment = proces
         },
         state,
         installations,
+        credentialReadiness,
+        provenance,
         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`,
-                },
+        next: setupNextAction(plan, state, root),
+    };
+}
+function setupStateForOutput(state, plan, root) {
+    if (!state.lastError)
+        return state;
+    return {
+        ...state,
+        lastError: {
+            ...state.lastError,
+            retryCommand: researchSetupRetryCommand({
+                version: plan.cli.version,
+                workspace: root,
+                step: state.lastError.step,
+            }),
+        },
+    };
+}
+function setupNextAction(plan, state, root) {
+    if (state.status === "ready")
+        return null;
+    if (state.status === "pending") {
+        return {
+            action: "apply",
+            minimumAction: "Apply the reviewed immutable setup plan.",
+            retryCommand: researchSetupApplyCommand({
+                version: plan.cli.version,
+                planPath: workspacePaths(root).setupPlan,
+            }),
+        };
+    }
+    if (state.status === "blocked" && state.lastError) {
+        return {
+            action: "retry",
+            minimumAction: state.lastError.minimumAction,
+            retryCommand: state.lastError.retryCommand,
+        };
+    }
+    if (state.status === "applying") {
+        return {
+            action: "inspect",
+            minimumAction: "Inspect the active setup attempt; do not start a competing apply.",
+            retryCommand: exactResearchCliCommand(["research", "setup", "status", "--workspace", root, "--json"], plan.cli.version),
+        };
+    }
+    return {
+        action: "doctor",
+        minimumAction: "Run setup doctor and resolve every reported missing readiness item.",
+        retryCommand: exactResearchCliCommand(["research", "setup", "doctor", "--workspace", root, "--json"], plan.cli.version),
+    };
+}
+async function inspectSetupCredentialReadiness(plan) {
+    const definitions = selectedCredentialDefinitions(plan);
+    const brokerIds = definitions
+        .filter((definition) => definition.storage === "broker")
+        .map((definition) => definition.id);
+    const configuredBroker = new Set((await loadCapabilityCredentialMapForIds(plan.workspace.path, brokerIds, {
+        ignoreUndeclared: true,
+    })).keys());
+    const configuredAdapter = await loadAdapterCredentials(plan.workspace.path, definitions, {
+        ignoreUndeclared: true,
+    });
+    const configuredIds = definitions
+        .filter((definition) => definition.storage === "broker"
+        ? configuredBroker.has(definition.id)
+        : configuredAdapter.has(definition.id))
+        .map((definition) => definition.id)
+        .sort();
+    const configured = new Set(configuredIds);
+    return {
+        valuesEmitted: false,
+        configuredIds,
+        missingRequiredIds: definitions
+            .filter((definition) => definition.required && !configured.has(definition.id))
+            .map((definition) => definition.id)
+            .sort(),
+        scopes: [
+            ...new Set(definitions
+                .filter((definition) => configured.has(definition.id))
+                .map((definition) => definition.storage)),
+        ].sort(),
+    };
+}
+async function inspectSetupProvenance(plan, installations, environment) {
+    const orchestratorSelected = plan.selection.skillIds.includes("tiangong.auto-research");
+    const orchestratorInstallations = installations
+        .filter((installation) => installation.skillId === "tiangong.auto-research")
+        .map((installation) => ({
+        agent: installation.agent,
+        path: installation.path,
+        status: installation.status,
+        observedTreeSha256: installation.observedTreeSha256,
+    }));
+    return {
+        effectiveCli: {
+            packageName: RESEARCH_PACKAGE_NAME,
+            packageVersion: packageVersion(),
+            packageRoot: packageRoot(),
+            invocationMode: "exact-npx",
+            commandPrefix: exactResearchCliCommand([], plan.cli.version),
+        },
+        ambientCli: await findAmbientExecutable(environment, "tiangong-ai"),
+        ambientSkillConflicts: await inspectAmbientProjectSkillConflicts(plan, environment),
+        recoveryShims: await inspectResearchSetupRecoveryShims(plan),
+        selectedOrchestrator: orchestratorSelected
+            ? {
+                skillId: "tiangong.auto-research",
+                scope: plan.install.scope,
+                preferredPath: orchestratorInstallations.find((installation) => installation.status === "installed")
+                    ?.path ?? null,
+                installations: orchestratorInstallations,
+            }
+            : null,
+    };
+}
+function recoveryShimPath(plan, agent) {
+    return join(setupTargetRoot({
+        workspace: plan.workspace.path,
+        scope: "project",
+        agent,
+    }), RECOVERY_SKILL_NAME);
+}
+function recoveryShimMarker(plan, agent) {
+    return {
+        schemaVersion: 1,
+        kind: "tiangong-auto-research-recovery-shim",
+        planSha256: plan.planSha256,
+        cliVersion: plan.cli.version,
+        workspace: plan.workspace.path,
+        agent,
+    };
+}
+function recoveryShimInstructions(marker) {
+    const inspectCommand = exactResearchCliCommand(["research", "context", "inspect", "--path", marker.workspace, "--json"], marker.cliVersion);
+    const statusCommand = exactResearchCliCommand(["research", "setup", "status", "--workspace", marker.workspace, "--json"], marker.cliVersion);
+    return `---
+name: ${RECOVERY_SKILL_NAME}
+description: Recovery-only routing for an explicitly reviewed Tiangong Auto Research setup that is pending, applying, or blocked. Use when a research request occurs under this workspace before the full project orchestrator is installed. Never use for research execution or standalone evidence search.
+---
+
+# Tiangong Auto Research recovery-only shim
+
+This CLI-generated Skill is bound to setup plan \`${marker.planSha256}\`. It exists only
+until the full external \`tiangong-auto-research\` Skill matches its reviewed tree hash.
+
+Never run research or standalone evidence from this shim. Do not read, copy, print, or
+edit credentials, setup state, locks, manifests, or the immutable plan.
+
+First run the exact-version read-only preflight:
+
+\`\`\`bash
+${inspectCommand}
+\`\`\`
+
+If the context is managed, inspect the structured setup state:
+
+\`\`\`bash
+${statusCommand}
+\`\`\`
+
+For \`pending\` or \`blocked\`, execute only the returned \`setup.next.retryCommand\`.
+For \`applying\`, report the active step and do not start a competing apply. Stop after
+reporting any new blocker. Never fall through to a global Skill, ambient CLI, or
+standalone provider credential.
+`;
+}
+function serializedRecoveryShimMarker(marker) {
+    return `${JSON.stringify(marker, null, 2)}\n`;
+}
+async function inspectRecoveryShim(path, workspace, agent, expectedPlanSha256) {
+    const info = await lstat(path).catch(() => undefined);
+    if (!info)
+        return { status: "missing", marker: null };
+    if (!info.isDirectory() || info.isSymbolicLink())
+        return { status: "blocked", marker: null };
+    try {
+        const entries = (await readdir(path)).sort();
+        if (canonicalJson(entries) !== canonicalJson([RECOVERY_SHIM_MARKER, "SKILL.md"].sort())) {
+            return { status: "drifted", marker: null };
+        }
+        const markerPath = join(path, RECOVERY_SHIM_MARKER);
+        const skillPath = join(path, "SKILL.md");
+        const [markerInfo, skillInfo, markerText, skillText] = await Promise.all([
+            lstat(markerPath),
+            lstat(skillPath),
+            readFile(markerPath, "utf8"),
+            readFile(skillPath, "utf8"),
+        ]);
+        if (!markerInfo.isFile() ||
+            markerInfo.isSymbolicLink() ||
+            !skillInfo.isFile() ||
+            skillInfo.isSymbolicLink()) {
+            return { status: "blocked", marker: null };
+        }
+        const value = JSON.parse(markerText);
+        if (!isObject(value) ||
+            value.schemaVersion !== 1 ||
+            value.kind !== "tiangong-auto-research-recovery-shim" ||
+            typeof value.planSha256 !== "string" ||
+            !/^[0-9a-f]{64}$/.test(value.planSha256) ||
+            typeof value.cliVersion !== "string" ||
+            !/^\d+\.\d+\.\d+$/.test(value.cliVersion) ||
+            value.workspace !== workspace ||
+            value.agent !== agent) {
+            return { status: "drifted", marker: null };
+        }
+        const marker = value;
+        if (markerText !== serializedRecoveryShimMarker(marker) ||
+            skillText !== recoveryShimInstructions(marker)) {
+            return { status: "drifted", marker: null };
+        }
+        return {
+            status: marker.planSha256 === expectedPlanSha256 ? "installed" : "stale",
+            marker,
+        };
+    }
+    catch {
+        return { status: "blocked", marker: null };
+    }
+}
+async function writeRecoveryShimDirectory(path, marker) {
+    const temporary = join(dirname(path), `.${RECOVERY_SKILL_NAME}.${process.pid}.${randomUUID()}.tmp`);
+    await mkdir(temporary, { mode: 0o700 });
+    try {
+        await writeTextAtomic(join(temporary, "SKILL.md"), recoveryShimInstructions(marker), 0o444);
+        await writeTextAtomic(join(temporary, RECOVERY_SHIM_MARKER), serializedRecoveryShimMarker(marker), 0o444);
+        return temporary;
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        throw error;
+    }
+}
+async function installResearchSetupRecoveryShims(plan) {
+    for (const agent of plan.install.agents) {
+        const path = recoveryShimPath(plan, agent);
+        const parent = dirname(path);
+        await assertNoSymlinkedExistingPath(parent, plan.workspace.path);
+        await ensureDirectory(parent);
+        await assertNoSymlinkedExistingPath(parent, plan.workspace.path);
+        const inspection = await inspectRecoveryShim(path, plan.workspace.path, agent, plan.planSha256);
+        if (inspection.status === "installed")
+            continue;
+        if (inspection.status === "drifted" || inspection.status === "blocked") {
+            throw setupError({
+                code: "RESEARCH_SETUP_RECOVERY_SHIM_UNSAFE",
+                step: "recovery-shim",
+                reason: `The recovery Skill destination is not an exact CLI-owned shim for ${agent}.`,
+                minimumAction: "Review the reported project Skill directory. Setup will not overwrite or delete ambiguous bytes.",
+                retryCommand: exactResearchCliCommand(["research", "setup", "status", "--workspace", plan.workspace.path, "--json"], plan.cli.version),
+                exitCode: 3,
+            });
+        }
+        const temporary = await writeRecoveryShimDirectory(path, recoveryShimMarker(plan, agent));
+        try {
+            if (inspection.status === "missing") {
+                await rename(temporary, path);
+            }
+            else {
+                const backup = `${path}.${process.pid}.${randomUUID()}.previous`;
+                await rename(path, backup);
+                try {
+                    await rename(temporary, path);
+                    await rm(backup, { recursive: true, force: true });
+                }
+                catch (error) {
+                    if (!(await pathExists(path)))
+                        await rename(backup, path).catch(() => undefined);
+                    throw error;
+                }
+            }
+        }
+        catch (error) {
+            await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+    }
+}
+async function removeResearchSetupRecoveryShims(plan) {
+    for (const agent of plan.install.agents) {
+        const path = recoveryShimPath(plan, agent);
+        const inspection = await inspectRecoveryShim(path, plan.workspace.path, agent, plan.planSha256);
+        if (inspection.status === "missing")
+            continue;
+        if (inspection.status !== "installed") {
+            throw setupError({
+                code: "RESEARCH_SETUP_RECOVERY_SHIM_UNSAFE",
+                step: "recovery-shim-cleanup",
+                reason: `The recovery Skill changed before verified cleanup for ${agent}.`,
+                minimumAction: "Review the recovery Skill directory. Setup removes only its exact plan-bound generated bytes.",
+                retryCommand: exactResearchCliCommand(["research", "setup", "status", "--workspace", plan.workspace.path, "--json"], plan.cli.version),
+                exitCode: 3,
+            });
+        }
+        await rm(path, { recursive: true, force: false });
+    }
+}
+async function inspectResearchSetupRecoveryShims(plan) {
+    if (!plan.selection.skillIds.includes("tiangong.auto-research"))
+        return [];
+    const results = [];
+    for (const agent of plan.install.agents) {
+        const path = recoveryShimPath(plan, agent);
+        const inspection = await inspectRecoveryShim(path, plan.workspace.path, agent, plan.planSha256);
+        if (inspection.status === "missing")
+            continue;
+        results.push({
+            agent,
+            path,
+            status: inspection.status === "stale" ? "drifted" : inspection.status,
+            planSha256: inspection.marker?.planSha256 ?? null,
+            cliVersion: inspection.marker?.cliVersion ?? null,
+            recoveryOnly: true,
+        });
+    }
+    return results;
+}
+async function inspectAmbientProjectSkillConflicts(plan, environment) {
+    if (plan.install.scope !== "project")
+        return [];
+    const conflicts = [];
+    for (const agent of plan.install.agents) {
+        const globalRoot = setupTargetRoot({
+            workspace: plan.workspace.path,
+            scope: "global",
+            agent,
+            environment,
+        });
+        for (const skillId of plan.selection.skillIds) {
+            const skill = setupSkill(skillId);
+            const path = join(globalRoot, skill.skillName);
+            const info = await lstat(path).catch(() => undefined);
+            if (!info)
+                continue;
+            let status = "blocked";
+            let observedTreeSha256 = null;
+            if (info.isDirectory() && !info.isSymbolicLink()) {
+                try {
+                    observedTreeSha256 = await hashRegularTree(path);
+                    status = observedTreeSha256 === skill.expectedTreeSha256 ? "matching" : "drifted";
+                }
+                catch {
+                    status = "blocked";
+                }
+            }
+            conflicts.push({
+                skillId: skill.id,
+                skillName: skill.skillName,
+                agent,
+                path,
+                status,
+                observedTreeSha256,
+                expectedTreeSha256: skill.expectedTreeSha256,
+                unmanagedPathCliFallback: await containsUnmanagedPathCliFallback(path),
+                ignoredByProjectScope: true,
+            });
+        }
+    }
+    return conflicts;
+}
+async function containsUnmanagedPathCliFallback(root) {
+    const state = { inspectedFiles: 0 };
+    const inspectDirectory = async (directory, depth) => {
+        if (depth > 4 || state.inspectedFiles >= 100)
+            return false;
+        const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (await inspectDirectory(path, depth + 1))
+                    return true;
+                continue;
+            }
+            if (!entry.isFile() || !/\.(?:c?js|mjs|py|sh)$/.test(entry.name))
+                continue;
+            state.inspectedFiles += 1;
+            const info = await lstat(path).catch(() => undefined);
+            if (!info?.isFile() || info.isSymbolicLink() || info.size > 256 * 1024)
+                continue;
+            const content = await readFile(path, "utf8").catch(() => "");
+            if (content.includes("TIANGONG_AI_CLI:-tiangong-ai"))
+                return true;
+        }
+        return false;
     };
+    return inspectDirectory(root, 0);
+}
+async function findAmbientExecutable(environment, executable) {
+    const pathValue = environment.PATH;
+    if (!pathValue)
+        return null;
+    const suffixes = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
+    for (const directory of pathValue.split(process.platform === "win32" ? ";" : ":")) {
+        if (!directory)
+            continue;
+        for (const suffix of suffixes) {
+            const candidate = join(directory, `${executable}${suffix}`);
+            const info = await lstat(candidate).catch(() => undefined);
+            if (!info || (!info.isFile() && !info.isSymbolicLink()))
+                continue;
+            const resolved = await realpath(candidate).catch(() => undefined);
+            if (!resolved)
+                continue;
+            const resolvedInfo = await lstat(resolved).catch(() => undefined);
+            if (resolvedInfo?.isFile() && !resolvedInfo.isSymbolicLink())
+                return { path: resolved, ignoredByExactInvocation: true };
+        }
+    }
+    return null;
 }
 export async function setResearchSetupCredentialFromEnvironment(input) {
     const root = requireAbsoluteWorkspace(input.workspace);
@@ -795,6 +1235,26 @@ export async function doctorResearchSetup(workspace, options = {}) {
                 : "Restore the pinned Skill bytes; setup will not overwrite a drifted or symlinked directory.",
         });
     }
+    const provenance = await inspectSetupProvenance(plan, installations, environment);
+    for (const conflict of provenance.ambientSkillConflicts) {
+        const projectInstallation = installations.find((installation) => installation.agent === conflict.agent && installation.skillId === conflict.skillId);
+        const projectInstalled = projectInstallation?.status === "installed";
+        checks.push({
+            id: `skill-scope.${conflict.agent}.${conflict.skillId}`,
+            category: "skill-installation",
+            scope: "research-core",
+            componentIds: [conflict.skillId],
+            status: projectInstalled ? "warn" : "fail",
+            detail: projectInstalled
+                ? `A global same-name Skill exists at ${conflict.path}, but the verified project copy is authoritative and the global copy is ignored.`
+                : `SKILL_SCOPE_FALLBACK_UNSAFE: the project copy is not verified while a global same-name Skill exists at ${conflict.path}${conflict.unmanagedPathCliFallback ? " and contains an unmanaged PATH CLI fallback" : ""}.`,
+            minimumAction: projectInstalled
+                ? "Remove or update the ignored global copy during separate owner-approved maintenance if it is no longer needed."
+                : "Resume the exact setup plan until the project Skill matches its reviewed tree; do not use the global fallback.",
+            blocking: !projectInstalled,
+            requiredFor: projectInstalled ? [] : ["setup", "research-core"],
+        });
+    }
     for (const setting of requiredSettingsForSkills(selected)) {
         const configured = plan.settings[setting.id];
         checks.push({
@@ -1762,7 +2222,7 @@ 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)}`);
+    const checkout = setupSourceCheckoutPath(plan, sourceId);
     await assertNoSymlinkedExistingPath(dirname(checkout), plan.workspace.path);
     let createdCheckout = false;
     if (!(await pathExists(checkout))) {
@@ -1875,6 +2335,42 @@ async function ensureSetupSourceCheckout(plan, sourceId, runner, environment) {
     }
     return checkout;
 }
+function setupSourceCheckoutPath(plan, sourceId) {
+    const source = plan.sources.find((candidate) => candidate.id === sourceId);
+    if (!source)
+        throw planCatalogDrift(`missing source ${sourceId}`);
+    return join(workspacePaths(plan.workspace.path).setupSources, `${source.id}-${source.immutableRef.slice(0, 12)}`);
+}
+async function annotateSetupSourceCheckoutFailure(error, plan, sourceId) {
+    if (!(error instanceof CliError) || error.code !== "RESEARCH_SETUP_COMMAND_FAILED")
+        return error;
+    const source = plan.sources.find((candidate) => candidate.id === sourceId);
+    if (!source)
+        return error;
+    const details = isObject(error.details) ? error.details : {};
+    const checkout = setupSourceCheckoutPath(plan, sourceId);
+    return setupError({
+        code: error.code,
+        step: "source-checkout",
+        reason: typeof details.reason === "string" ? details.reason : sanitizeResearchText(error.message),
+        minimumAction: typeof details.minimumAction === "string"
+            ? details.minimumAction
+            : "Resolve the source transport failure, then retry only the recorded source-checkout step.",
+        retryCommand: researchSetupRetryCommand({
+            version: plan.cli.version,
+            workspace: plan.workspace.path,
+            step: "source-checkout",
+        }),
+        exitCode: error.exitCode,
+        diagnostics: {
+            sourceId: source.id,
+            repository: source.repository,
+            immutableRef: source.immutableRef,
+            cacheState: (await pathExists(checkout)) ? "partial" : "absent",
+            safeToRetry: true,
+        },
+    });
+}
 async function configureDeterministicSourceCheckout(checkout, runner, cwd, environment) {
     for (const [key, value] of [
         ["core.autocrlf", "false"],
@@ -2311,6 +2807,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 &&
@@ -2320,7 +2822,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 {
@@ -2331,20 +2833,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");
@@ -2637,7 +3151,14 @@ async function loadSetupState(root, planSha256) {
         typeof value.attempts !== "number" ||
         !Number.isInteger(value.attempts) ||
         typeof value.updatedAt !== "string" ||
-        !(value.lastError === null || isObject(value.lastError))) {
+        !(value.lastError === null ||
+            (isObject(value.lastError) &&
+                typeof value.lastError.code === "string" &&
+                typeof value.lastError.step === "string" &&
+                typeof value.lastError.reason === "string" &&
+                typeof value.lastError.minimumAction === "string" &&
+                typeof value.lastError.retryCommand === "string" &&
+                (value.lastError.diagnostics === undefined || isObject(value.lastError.diagnostics))))) {
         throw setupError({
             code: "RESEARCH_SETUP_STATE_INVALID",
             step: "state",
@@ -2806,9 +3327,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",
@@ -2818,7 +3355,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();
@@ -2890,6 +3444,15 @@ function setupMutations(root, targets, selected) {
             reason: "Initialize or verify the auditable research workspace control plane.",
         },
     ];
+    if (selected.some((skill) => skill.id === "tiangong.auto-research")) {
+        for (const target of targets) {
+            mutations.push({
+                step: "recovery-shim",
+                target: join(setupTargetRoot({ workspace: root, scope: "project", agent: target.agent }), RECOVERY_SKILL_NAME),
+                reason: "Create a plan-bound recovery-only routing Skill until the full external orchestrator is verified.",
+            });
+        }
+    }
     for (const target of targets) {
         for (const skill of selected) {
             mutations.push({
@@ -3466,16 +4029,20 @@ function syntheticPdfText() {
 function setupFailure(error, fallbackStep, root) {
     if (error instanceof CliError && isObject(error.details)) {
         const details = sanitizeResearchRecord(error.details);
+        const step = typeof details.step === "string" ? details.step : fallbackStep;
         return {
             code: error.code,
-            step: typeof details.step === "string" ? details.step : fallbackStep,
+            step,
             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`,
+            retryCommand: researchSetupRetryCommand({
+                version: packageVersion(),
+                workspace: root,
+                step,
+            }),
+            ...(isObject(details.diagnostics) ? { diagnostics: details.diagnostics } : {}),
         };
     }
     return {
@@ -3483,7 +4050,11 @@ function setupFailure(error, fallbackStep, root) {
         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`,
+        retryCommand: researchSetupRetryCommand({
+            version: packageVersion(),
+            workspace: root,
+            step: fallbackStep,
+        }),
     };
 }
 function setupError(input) {
@@ -3491,7 +4062,7 @@ function setupError(input) {
         step: input.step,
         reason: input.reason,
         minimumAction: input.minimumAction,
-        retryCommand: input.retryCommand,
+        retryCommand: pinResearchCliCommand(input.retryCommand),
         ...(input.diagnostics === undefined ? {} : { diagnostics: input.diagnostics }),
     });
     return new CliError(sanitizeResearchText(input.reason), {