@zq-silk/yui 0.2.0 → 0.4.2

package/dist/doctor/doctor.js

@@ -1,35 +1,131 @@
-import { accessSync, constants, existsSync, lstatSync } from "node:fs";
-import { join } from "node:path";
-import { configuredAgentToDefinition } from "../agent/agent.js";
-import { inspectAgentCapabilities } from "../executor/agentAdapter.js";
+import { accessSync, constants, existsSync, lstatSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
+import { operationalAgentEnvironment } from "../agent/launchEnvironment.js";
+import { inspectAgentCapabilities, resolveAgentAdapter } from "../executor/agentAdapter.js";
+import { inspectCodexLaunchConfig } from "../executor/codexConfigConflict.js";
+import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { compileRoleSessionContext } from "../context/roleSessionContext.js";
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
-import { FileTaskStore, resolveYuiHome, STORAGE_STATE_FILE } from "../storage/taskStore.js";
+import { resolveYuiHome, STORAGE_STATE_FILE } from "../storage/taskStore.js";
+import { createProductionStorageRegistry, openCompatibleFileTaskStore, validateCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
+import { classifyHome } from "../storage/upgrade/homeClassification.js";
+import { latestStorageVersionState } from "../storage/upgrade/recordVersions.js";
 import { CommandExecutionError } from "../tmux/commandExecutor.js";
+import { EPHEMERAL_DOMAIN_GRACE_MS, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
+/**
+ * The storage-relevant doctor checks, in the order they are produced. Post-update
+ * verification (P1-3) keys off exactly these: a green `yui doctor` for the update
+ * flow means every one of these is `ok`. Tool/agent checks are diagnostic only
+ * and never block an update.
+ */
+export const STORAGE_DOCTOR_CHECK_NAMES = Object.freeze([
+    "storage schema",
+    "storage compatibility",
+    "storage state"
+]);
+/**
+ * Classify the storage checks into a machine-readable health verdict. This is the
+ * canonical, parseable signal the update post-verify consumes (P1-3): storage is
+ * healthy only when schema, compatibility, and state are all `ok`. Any
+ * `unsupported` (version mismatch / needs-new-version), `invalid` (corrupted /
+ * unreadable), or `missing` (uninitialized) storage check is blocking — even
+ * though `yui doctor` itself exits 0.
+ */
+export function summarizeStorageHealth(checks) {
+    const names = new Set(STORAGE_DOCTOR_CHECK_NAMES);
+    const blocking = checks.filter((check) => names.has(check.name) && check.status !== "ok");
+    return { healthy: blocking.length === 0, blocking };
+}
+/** Build the full machine-readable doctor report (checks + storage health). */
+export function buildDoctorReport(env, executor, storageOptions = {}) {
+    const inspection = inspectDoctor(env, executor, storageOptions);
+    return {
+        checks: inspection.checks,
+        storage: summarizeStorageHealth(inspection.checks),
+        review: inspection.review
+    };
+}
 /** Runs the read-only FileTaskStore diagnostics used by `yui doctor`. */
-export function runDoctorCommand(args, env, executor) {
+export function runDoctorCommand(args, env, executor, storageOptions = {}) {
     if (args.length !== 0)
         throw usageError("Doctor usage: yui doctor");
-    return renderDoctor(getDoctorChecks(env, executor));
+    const inspection = inspectDoctor(env, executor, storageOptions);
+    return renderDoctor(inspection.checks, inspection.review);
+}
+export function getDoctorChecks(env, executor, storageOptions = {}) {
+    return inspectDoctor(env, executor, storageOptions).checks;
 }
-export function getDoctorChecks(env, executor) {
+function inspectDoctor(env, executor, storageOptions = {}) {
     const home = resolveYuiHome(env);
     const homeCheck = checkHome(home);
     const schema = readSchema(home);
-    const schemaCheck = checkSchema(schema);
-    const storage = inspectState(home, homeCheck, schema);
-    return [
-        homeCheck,
-        schemaCheck,
-        storage.check,
+    const compatibility = inspectCompatibility(home, homeCheck, schema, storageOptions);
+    const schemaCheck = checkSchema(schema, compatibility);
+    const storage = inspectState(home, homeCheck, schema, compatibility);
+    const domain = checkEphemeralDomain(home);
+    const toolChecks = [
         checkExecutable("git", env.YUI_GIT_BIN ?? "git", ["--version"], executor),
-        checkExecutable("tmux", env.YUI_TMUX_BIN ?? "tmux", ["-V"], executor),
-        ...storage.agents.flatMap((agent) => checkAgent(agent, executor))
+        checkExecutable("tmux", env.YUI_TMUX_BIN ?? "tmux", ["-V"], executor)
     ];
+    const agentChecks = storage.agents.flatMap((agent) => checkAgent(agent, executor, env));
+    const review = inspectReview({ ...storage.review, home }, agentChecks, env);
+    return {
+        checks: [
+            homeCheck,
+            schemaCheck,
+            compatibility.check,
+            storage.check,
+            ...(domain === undefined ? [] : [domain]),
+            ...toolChecks,
+            ...agentChecks,
+            ...review.checks
+        ],
+        review: review.report
+    };
 }
-export function renderDoctor(checks) {
-    return `Yui doctor\n${renderTable("Checks", [
+function checkEphemeralDomain(home) {
+    const identity = readEphemeralDomainIdentity(home);
+    if (identity.status === "absent")
+        return undefined;
+    if (identity.status === "invalid" || identity.identity === undefined) {
+        return {
+            name: "ephemeral domain",
+            status: "invalid",
+            detail: "runtime/domain.json is invalid; recreate the isolated test domain."
+        };
+    }
+    const host = readLinuxProcessStartIdentity(identity.identity.hostPid);
+    if (host === identity.identity.hostProcessStartIdentity) {
+        return {
+            name: "ephemeral domain",
+            status: "ok",
+            detail: `active host=${identity.identity.hostPid}:${host} token=${identity.identity.token.slice(0, 12)}`
+        };
+    }
+    if (host === undefined && existsSync(`/proc/${identity.identity.hostPid}`)) {
+        return {
+            name: "ephemeral domain",
+            status: "invalid",
+            detail: "host process is present but its start identity is unreadable; keep the domain protected and retry."
+        };
+    }
+    const ageMs = Math.max(0, Date.now() - Date.parse(identity.identity.createdAt));
+    return {
+        name: "ephemeral domain",
+        status: ageMs >= EPHEMERAL_DOMAIN_GRACE_MS ? "missing" : "invalid",
+        detail: ageMs >= EPHEMERAL_DOMAIN_GRACE_MS
+            ? "host is expired; run yui controller cleanup --all or wait for Controller recovery."
+            : "host identity is unavailable; bounded grace is still in progress."
+    };
+}
+export function renderDoctor(checks, review) {
+    const reviewLine = review === undefined
+        ? ""
+        : `Reviewer: ${review.status} (${review.detail})\n`;
+    return `Yui doctor\n${reviewLine}${renderTable("Checks", [
         { header: "Check", minWidth: 8, maxWidth: 28 },
         { header: "Status", minWidth: 7, maxWidth: 11 },
         { header: "Detail", minWidth: 12, maxWidth: 88 }
@@ -63,7 +159,7 @@ function readSchema(home) {
         return { status: "read-error", detail: errorMessage(error) };
     }
 }
-function checkSchema(state) {
+function checkSchema(state, compatibility) {
     switch (state.status) {
         case "uninitialized":
             return { name: "storage schema", status: "missing", detail: "run yui setup" };
@@ -74,6 +170,15 @@ function checkSchema(state) {
                 detail: `current=${state.currentVersion} latest=${state.latestVersion}`
             };
         case "unsupported":
+            if (compatibility.storageStatus === "compatible-old"
+                && compatibility.check.status === "ok") {
+                return {
+                    name: "storage schema",
+                    status: "ok",
+                    detail: `current=${state.currentVersion} latest=${state.latestVersion} `
+                        + `direction=${state.direction}; compatible-old validated`
+                };
+            }
             return {
                 name: "storage schema",
                 status: "unsupported",
@@ -85,20 +190,134 @@ function checkSchema(state) {
             return { name: "storage schema", status: "invalid", detail: state.detail };
     }
 }
-function inspectState(home, homeCheck, schema) {
+/**
+ * The four-state storage compatibility check: USABLE / MIGRATABLE /
+ * NEEDS_NEW_VERSION / CORRUPTED. This complements the raw "storage schema" check
+ * with the migration framework's verdict, so a user sees whether a Home can be
+ * used as-is, upgraded with `yui upgrade`, needs a newer release, or is damaged.
+ * Doctor uses the same explicit production registry as `yui upgrade`; tests
+ * may inject a synthetic registry so the same classification and validation
+ * path proves compatible-old behavior. Missing paths fail closed, and
+ * CORRUPTED is reserved for structural or reference failure.
+ */
+function inspectCompatibility(home, homeCheck, schema, storageOptions) {
+    const name = "storage compatibility";
+    if (homeCheck.status !== "ok") {
+        return { check: { name, status: homeCheck.status, detail: homeCheck.detail } };
+    }
+    if (schema.status === "uninitialized") {
+        return { check: { name, status: "missing", detail: "run yui setup" } };
+    }
+    if (schema.status === "read-error") {
+        return { check: { name, status: "invalid", detail: schema.detail } };
+    }
+    let classification;
+    let resolvedStorageOptions;
+    try {
+        resolvedStorageOptions = {
+            registry: storageOptions.registry ?? createProductionStorageRegistry(),
+            latest: storageOptions.latest ?? latestStorageVersionState()
+        };
+        classification = classifyHome({
+            home,
+            registry: resolvedStorageOptions.registry,
+            latest: resolvedStorageOptions.latest
+        });
+    }
+    catch (error) {
+        return { check: { name, status: "invalid", detail: errorMessage(error) } };
+    }
+    const storageStatus = classification.classification.status;
+    if (storageStatus === "compatible-old") {
+        try {
+            validateCompatibleFileTaskStore(home, resolvedStorageOptions);
+        }
+        catch (error) {
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: {
+                    name,
+                    status: "invalid",
+                    detail: `unsupported compatible-old shape: ${errorMessage(error)}`
+                }
+            };
+        }
+    }
+    const versions = `layout=${classification.layoutVersion ?? "?"}/${classification.latestLayoutVersion}`
+        + ` aggregate=${classification.aggregateVersion ?? "?"}/${classification.latestAggregateVersion}`;
+    const incompatible = classification.incompatibleComponent === undefined
+        ? ""
+        : ` incompatibleComponent=${classification.incompatibleComponent}`;
+    switch (storageStatus) {
+        case "current":
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: { name, status: "ok", detail: `current (USABLE) ${versions}` }
+            };
+        case "compatible-old":
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: {
+                    name,
+                    status: "ok",
+                    detail: `compatible-old (COMPATIBLE) ${versions}; ordinary commands are supported`
+                }
+            };
+        case "migration-required":
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: {
+                    name,
+                    status: "ok",
+                    detail: `migration-required (MIGRATABLE) ${versions}; run yui update when Sessions are clear`
+                }
+            };
+        case "unsupported": {
+            const unsupported = classification.classification;
+            return {
+                storageStatus,
+                storageOptions: resolvedStorageOptions,
+                check: unsupported.verdict === "CORRUPTED"
+                    ? {
+                        name,
+                        status: "invalid",
+                        detail: `unsupported (CORRUPTED): ${unsupported.detail}`
+                    }
+                    : {
+                        name,
+                        status: "unsupported",
+                        detail: `unsupported (NEEDS_NEW_VERSION) ${versions}${incompatible}; ` +
+                            `${unsupported.blocker.reason}`
+                    }
+            };
+        }
+    }
+}
+function inspectState(home, homeCheck, schema, compatibility) {
     if (homeCheck.status !== "ok") {
         return blockedStorage(homeCheck.status, homeCheck.detail);
     }
     if (schema.status === "uninitialized") {
         return blockedStorage("missing", "run yui setup");
     }
-    if (schema.status === "unsupported") {
-        return blockedStorage("unsupported", `current=${schema.currentVersion} latest=${schema.latestVersion}`);
-    }
     if (schema.status === "invalid")
         return blockedStorage("invalid", schema.detail);
     if (schema.status === "read-error")
         return blockedStorage("invalid", schema.detail);
+    if (compatibility.check.status !== "ok") {
+        return blockedStorage(compatibility.check.status, storageBlockerDetail(compatibility.check));
+    }
+    if (compatibility.storageStatus !== "current"
+        && compatibility.storageStatus !== "compatible-old") {
+        return blockedStorage("unsupported", compatibility.check.detail);
+    }
+    if (compatibility.storageOptions === undefined) {
+        return blockedStorage("invalid", "Storage compatibility options were not resolved.");
+    }
     const statePath = join(home, STORAGE_STATE_FILE);
     if (!existsSync(statePath))
         return blockedStorage("missing", "run yui setup");
@@ -108,7 +327,7 @@ function inspectState(home, homeCheck, schema) {
             return blockedStorage("invalid", `${STORAGE_STATE_FILE} must be a regular file.`);
         }
         accessSync(statePath, constants.R_OK);
-        const store = new FileTaskStore(home);
+        const store = openCompatibleFileTaskStore(home, compatibility.storageOptions);
         const config = store.getConfig();
         const agents = store.listConfiguredAgents();
         const tasks = store.listTasks();
@@ -120,17 +339,424 @@ function inspectState(home, homeCheck, schema) {
                 status: "ok",
                 detail: `readable agents=${agents.length} tasks=${tasks.length} roles=${roleCount} globalRoles=${globalRoles.length} defaultAgent=${config.defaultAgent ?? "none"}`
             },
-            agents
+            agents,
+            review: {
+                storageReady: true,
+                storageDetail: "state.json is readable",
+                ...(config.review === undefined ? {} : { policy: config.review }),
+                ...(config.review === undefined
+                    ? {}
+                    : {
+                        role: store.getGlobalRole(config.review.roleName),
+                        agent: (() => {
+                            const role = store.getGlobalRole(config.review.roleName);
+                            return role === null
+                                ? null
+                                : store.getConfiguredAgent(role.activeAgentId);
+                        })()
+                    })
+            }
         };
     }
     catch (error) {
         return blockedStorage("invalid", errorMessage(error));
     }
 }
+function storageBlockerDetail(check) {
+    const corruptionPrefix = "unsupported (CORRUPTED): ";
+    return check.status === "invalid" && check.detail.startsWith(corruptionPrefix)
+        ? `Invalid state.json: ${check.detail.slice(corruptionPrefix.length)}`
+        : check.detail;
+}
 function blockedStorage(status, detail) {
     return {
         check: { name: "storage state", status, detail },
-        agents: []
+        agents: [],
+        review: {
+            storageReady: false,
+            storageDetail: detail
+        }
+    };
+}
+function inspectReview(source, agentChecks, environment) {
+    if (!source.storageReady) {
+        const raw = source.home === undefined
+            ? null
+            : inspectRawReview(source.home, source.storageDetail);
+        if (raw !== null)
+            return raw;
+        return {
+            report: {
+                status: "misconfigured",
+                providerNative: "unverified",
+                detail: `Review configuration unavailable: ${source.storageDetail}`
+            },
+            checks: [{
+                    name: "review policy",
+                    status: "invalid",
+                    detail: `unavailable: ${source.storageDetail}`
+                }]
+        };
+    }
+    const policy = source.policy;
+    if (policy === undefined) {
+        return {
+            report: {
+                status: "disabled",
+                providerNative: "unverified",
+                detail: "Review policy is disabled; no Reviewer dispatch is scheduled."
+            },
+            checks: [{
+                    name: "review policy",
+                    status: "ok",
+                    detail: "disabled"
+                }]
+        };
+    }
+    const checks = [{
+            name: "review policy",
+            status: "ok",
+            detail: `role=${policy.roleName} trigger=${policy.trigger}`
+        }];
+    const role = source.role ?? null;
+    if (role === null) {
+        checks.push({
+            name: "reviewer role",
+            status: "missing",
+            detail: `Global Role not found: ${policy.roleName}.`
+        });
+        return reviewMisconfigured(policy, checks, `Reviewer Role is missing: ${policy.roleName}.`);
+    }
+    checks.push({
+        name: "reviewer role",
+        status: "ok",
+        detail: `name=${role.name} activeAgent=${role.activeAgentId}`
+    });
+    const binding = role.agentBindings[role.activeAgentId];
+    if (binding === undefined) {
+        checks.push({
+            name: "reviewer binding",
+            status: "missing",
+            detail: `active Agent binding is missing: ${role.activeAgentId}.`
+        });
+        return reviewMisconfigured(policy, checks, "Reviewer active Agent binding is missing.", role);
+    }
+    checks.push({
+        name: "reviewer binding",
+        status: "ok",
+        detail: `agent=${binding.agentId} adapter=${binding.adapterId}`
+    });
+    const agent = source.agent ?? null;
+    if (agent === null) {
+        checks.push({
+            name: "reviewer agent",
+            status: "missing",
+            detail: `Configured Agent not found: ${binding.agentId}.`
+        });
+        return reviewMisconfigured(policy, checks, `Reviewer Agent is missing: ${binding.agentId}.`, role, binding.agentId, binding.adapterId);
+    }
+    checks.push({
+        name: "reviewer agent",
+        status: "ok",
+        detail: `id=${agent.id} adapter=${agent.adapterId} command=${agent.command}`
+    });
+    if (agent.adapterId !== binding.adapterId) {
+        checks.push({
+            name: "reviewer adapter",
+            status: "invalid",
+            detail: `binding adapter=${binding.adapterId} does not match Agent adapter=${agent.adapterId}.`
+        });
+        return reviewMisconfigured(policy, checks, "Reviewer adapter identity does not match its Agent binding.", role, agent.id, agent.adapterId, agent.command);
+    }
+    let adapter;
+    try {
+        adapter = resolveAgentAdapter(agent.adapterId);
+        checks.push({
+            name: "reviewer adapter",
+            status: "ok",
+            detail: `adapter=${adapter.id} nativeSession=${adapter.capabilities.nativeSessionDiscovery}`
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "reviewer adapter",
+            status: "unsupported",
+            detail: errorMessage(error)
+        });
+        return reviewMisconfigured(policy, checks, `Reviewer adapter is unavailable: ${errorMessage(error)}`, role, agent.id, agent.adapterId, agent.command);
+    }
+    const commandCheck = agentChecks.find((check) => check.name === `agent:${agent.id}:command`);
+    const capabilityCheck = agentChecks.find((check) => check.name === `agent:${agent.id}:capability`);
+    checks.push({
+        name: "reviewer command",
+        status: commandCheck?.status ?? "invalid",
+        detail: commandCheck === undefined
+            ? `No command inspection was recorded for ${agent.id}.`
+            : commandCheck.detail
+    });
+    checks.push({
+        name: "reviewer capability",
+        status: capabilityCheck?.status ?? "invalid",
+        detail: capabilityCheck === undefined
+            ? `No capability inspection was recorded for ${agent.id}.`
+            : capabilityCheck.detail
+    });
+    const launch = checkReviewerLaunch(agent, role, binding, adapter, environment, source.home);
+    checks.push(launch);
+    const dispatch = checkReviewerDispatch(policy, role, binding, agent, launch, commandCheck, capabilityCheck);
+    checks.push(dispatch);
+    const failedCheck = checks.find((check) => check.status !== "ok");
+    if (failedCheck !== undefined) {
+        return reviewMisconfigured(policy, checks, `${failedCheck.name}: ${failedCheck.detail}`, role, agent.id, agent.adapterId, agent.command);
+    }
+    return {
+        report: {
+            status: "ready",
+            policy,
+            roleName: role.name,
+            activeAgentId: agent.id,
+            adapterId: agent.adapterId,
+            command: agent.command,
+            providerNative: "unverified",
+            detail: "Static Reviewer configuration and exact dispatch prerequisites are ready; provider-native acceptance is unverified."
+        },
+        checks
+    };
+}
+/**
+ * Preserve a bounded Reviewer diagnosis when another malformed record prevents
+ * FileTaskStore from opening. This is read-only evidence, never a compatibility
+ * path: the storage check remains invalid and the review projection cannot be
+ * reported as ready from unvalidated bytes.
+ */
+function inspectRawReview(home, storageDetail) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(home, STORAGE_STATE_FILE), "utf8"));
+        if (!isRecord(parsed) || !isRecord(parsed.config))
+            return null;
+        const rawPolicy = parsed.config.review;
+        if (!isRecord(rawPolicy)
+            || typeof rawPolicy.roleName !== "string"
+            || typeof rawPolicy.trigger !== "string") {
+            return {
+                report: {
+                    status: "misconfigured",
+                    providerNative: "unverified",
+                    detail: `Storage state is invalid; Review policy is unavailable: ${storageDetail}`
+                },
+                checks: [{
+                        name: "review policy",
+                        status: "invalid",
+                        detail: `storage state invalid: ${storageDetail}`
+                    }]
+            };
+        }
+        const policy = {
+            roleName: rawPolicy.roleName,
+            trigger: rawPolicy.trigger
+        };
+        const roles = isRecord(parsed.globalRoles) ? parsed.globalRoles : {};
+        const roleValue = roles[policy.roleName];
+        if (!isRecord(roleValue)) {
+            return rawReviewMisconfigured(policy, storageDetail, [{
+                    name: "review policy",
+                    status: "ok",
+                    detail: `role=${policy.roleName} trigger=${policy.trigger}`
+                }, {
+                    name: "reviewer role",
+                    status: "missing",
+                    detail: `Global Role not found: ${policy.roleName}.`
+                }]);
+        }
+        const roleName = typeof roleValue.name === "string" ? roleValue.name : policy.roleName;
+        const activeAgentId = typeof roleValue.activeAgentId === "string"
+            ? roleValue.activeAgentId
+            : "";
+        const checks = [{
+                name: "review policy",
+                status: "ok",
+                detail: `role=${policy.roleName} trigger=${policy.trigger}`
+            }, {
+                name: "reviewer role",
+                status: "ok",
+                detail: `name=${roleName} activeAgent=${activeAgentId || "missing"}`
+            }];
+        const bindings = isRecord(roleValue.agentBindings) ? roleValue.agentBindings : {};
+        const bindingValue = activeAgentId.length === 0 ? undefined : bindings[activeAgentId];
+        if (!isRecord(bindingValue)) {
+            checks.push({
+                name: "reviewer binding",
+                status: "missing",
+                detail: `active Agent binding is missing: ${activeAgentId || "unknown"}.`
+            });
+            return rawReviewMisconfigured(policy, storageDetail, checks, roleName, activeAgentId || undefined);
+        }
+        const bindingAgentId = typeof bindingValue.agentId === "string"
+            ? bindingValue.agentId
+            : activeAgentId;
+        const adapterId = typeof bindingValue.adapterId === "string"
+            ? bindingValue.adapterId
+            : "unknown";
+        checks.push({
+            name: "reviewer binding",
+            status: "ok",
+            detail: `agent=${bindingAgentId} adapter=${adapterId}`
+        });
+        const configuredAgents = isRecord(parsed.configuredAgents)
+            ? parsed.configuredAgents
+            : {};
+        const agentValue = configuredAgents[bindingAgentId];
+        if (!isRecord(agentValue)) {
+            checks.push({
+                name: "reviewer agent",
+                status: "missing",
+                detail: `Configured Agent not found: ${bindingAgentId}.`
+            });
+            return rawReviewMisconfigured(policy, storageDetail, checks, roleName, bindingAgentId, adapterId);
+        }
+        checks.push({
+            name: "reviewer agent",
+            status: "invalid",
+            detail: `Storage state is invalid; configured Agent ${bindingAgentId} cannot be validated.`
+        });
+        return rawReviewMisconfigured(policy, storageDetail, checks, roleName, bindingAgentId, adapterId, typeof agentValue.command === "string" ? agentValue.command : undefined);
+    }
+    catch {
+        return null;
+    }
+}
+function rawReviewMisconfigured(policy, storageDetail, checks, roleName, activeAgentId, adapterId, command) {
+    return {
+        report: {
+            status: "misconfigured",
+            policy,
+            ...(roleName === undefined ? {} : { roleName }),
+            ...(activeAgentId === undefined ? {} : { activeAgentId }),
+            ...(adapterId === undefined ? {} : { adapterId }),
+            ...(command === undefined ? {} : { command }),
+            providerNative: "unverified",
+            detail: `Storage state is invalid; ${checks.at(-1)?.detail ?? storageDetail}`
+        },
+        checks
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function reviewMisconfigured(policy, checks, detail, role, activeAgentId, adapterId, command) {
+    return {
+        report: {
+            status: "misconfigured",
+            policy,
+            roleName: role?.name ?? policy.roleName,
+            ...(activeAgentId === undefined ? {} : { activeAgentId }),
+            ...(adapterId === undefined ? {} : { adapterId }),
+            ...(command === undefined ? {} : { command }),
+            providerNative: "unverified",
+            detail
+        },
+        checks
+    };
+}
+function checkReviewerLaunch(agent, role, binding, adapter, environment, home) {
+    try {
+        const workspace = role.workspace;
+        if (!isAbsolute(workspace)) {
+            return {
+                name: "reviewer launch",
+                status: "invalid",
+                detail: "Reviewer Role workspace must be absolute."
+            };
+        }
+        const metadata = lstatSync(workspace);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+            return {
+                name: "reviewer launch",
+                status: "invalid",
+                detail: "Reviewer Role workspace must be an existing real directory."
+            };
+        }
+        const definition = configuredAgentToDefinition(agent);
+        const launchEnvironment = resolveDoctorAgentEnvironment(definition, environment);
+        const effective = resolveEffectiveLaunch({ role, purpose: "execution" });
+        const agentWorkspace = effective.workspace.entries.length === 1
+            ? effective.workspace.entries[0].path
+            : effective.workspace.root;
+        const codexConfig = adapter.id === "codex"
+            ? inspectCodexLaunchConfig({
+                environment: launchEnvironment,
+                workspace: agentWorkspace,
+                profile: binding.config.adapterId === "codex" ? binding.config.profile : undefined,
+                trustWorkspace: true
+            })
+            : undefined;
+        if (codexConfig?.notify.status === "configured") {
+            return {
+                name: "reviewer launch",
+                status: "invalid",
+                detail: "Codex notify is already configured by "
+                    + `${codexConfig.notify.source}; Yui requires exclusive ownership of the structured `
+                    + "notify callback and refuses to replace or be replaced by native configuration."
+            };
+        }
+        const reviewerContext = adapter.id === "codex"
+            ? compileRoleSessionContext(home, role, { scope: "global" }, { purpose: "review" })
+            : undefined;
+        const compiled = adapter.compileNew({
+            agent: definition,
+            config: binding.config,
+            workspace: agentWorkspace,
+            sessionTitle: "reviewer",
+            ...(reviewerContext === undefined
+                ? {}
+                : {
+                    developerInstructions: reviewerContext.developerInstructions,
+                    skills: reviewerContext.skills,
+                    codexDeveloperInstructions: codexConfig?.developerInstructions
+                })
+        });
+        if (compiled.argv.length === 0)
+            throw new Error("compiled launch argv is empty");
+        return {
+            name: "reviewer launch",
+            status: "ok",
+            detail: `adapter=${adapter.id} strategy=${compiled.sessionStrategy} command=${agent.command}`
+        };
+    }
+    catch (error) {
+        return {
+            name: "reviewer launch",
+            status: "invalid",
+            detail: errorMessage(error)
+        };
+    }
+}
+function checkReviewerDispatch(_policy, role, binding, agent, launch, command, capability) {
+    if (role.defaultAccess !== "write") {
+        return {
+            name: "reviewer dispatch",
+            status: "invalid",
+            detail: "Reviewer Role must retain write access for an isolated ReviewRound workspace."
+        };
+    }
+    if (binding.agentId !== agent.id) {
+        return {
+            name: "reviewer dispatch",
+            status: "invalid",
+            detail: `active binding Agent id does not match configured Agent: ${binding.agentId}/${agent.id}.`
+        };
+    }
+    if (launch.status !== "ok" || command?.status !== "ok" || capability?.status !== "ok") {
+        return {
+            name: "reviewer dispatch",
+            status: "invalid",
+            detail: "Reviewer exact dispatch is blocked until command, capability, and launch checks are ok."
+        };
+    }
+    return {
+        name: "reviewer dispatch",
+        status: "ok",
+        detail: "static exact dispatch prerequisites confirmed; no Session or model was launched."
     };
 }
 function checkExecutable(name, command, args, executor) {
@@ -150,11 +776,13 @@ function checkExecutable(name, command, args, executor) {
         };
     }
 }
-function checkAgent(agent, executor) {
+function checkAgent(agent, executor, environment) {
     let snapshot;
     try {
-        snapshot = inspectAgentCapabilities(configuredAgentToDefinition(agent), {
-            run: (command, args) => runAgentProbe(executor, command, args)
+        const definition = configuredAgentToDefinition(agent);
+        const launchEnvironment = resolveDoctorAgentEnvironment(definition, environment);
+        snapshot = inspectAgentCapabilities(definition, {
+            run: (command, args) => runAgentProbe(executor, command, args, launchEnvironment)
         });
     }
     catch (error) {
@@ -184,13 +812,22 @@ function checkAgent(agent, executor) {
         {
             name: `agent:${agent.id}:capability`,
             status,
-            detail: `start resume interrupt nativeSession=${snapshot.lifecycle.nativeSessionDiscovery} fields=${available}/${degraded}/${unavailable}`
+            detail: [
+                `start resume interrupt nativeSession=${snapshot.lifecycle.nativeSessionDiscovery}`,
+                `preInputReady=${snapshot.lifecycle.preInputReadiness.status}`,
+                `fields=${available}/${degraded}/${unavailable}`,
+                ...snapshot.warnings.map((warning) => `warning=${warning}`)
+            ].join(" ")
         }
     ];
 }
-function runAgentProbe(executor, command, args) {
+function runAgentProbe(executor, command, args, environment) {
     try {
-        return { status: 0, stdout: executor.run(command, [...args]), stderr: "" };
+        return {
+            status: 0,
+            stdout: executor.run(command, [...args], { environment }),
+            stderr: ""
+        };
     }
     catch (error) {
         const missing = isMissingCommand(error);
@@ -205,6 +842,18 @@ function runAgentProbe(executor, command, args) {
         };
     }
 }
+/**
+ * Resolve the complete environment used by FileRoleLaunchPlanner for an Agent.
+ * Doctor probes must inspect the same command resolution context as a native
+ * launch; inheriting the Doctor process PATH would allow a shell-installed
+ * command to mask a missing configured binding.
+ */
+function resolveDoctorAgentEnvironment(agent, environment) {
+    return {
+        ...operationalAgentEnvironment(agent.adapterId, environment),
+        ...resolveAgentEnvironment(agent, environment)
+    };
+}
 function isMissingCommand(error) {
     return error instanceof CommandExecutionError
         ? error.code === "COMMAND_NOT_FOUND"