rea-agents 6.5.0 → 6.7.0

package/dist/application/ClientConfigurationPublication.js

@@ -0,0 +1,167 @@
+import { constants } from "node:fs";
+import { link, lstat, mkdtemp, open, realpath, rename, } from "node:fs/promises";
+import { basename, dirname, join, sep } from "node:path";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { OwnedStagedOutput } from "../filesystem/OwnedStagedOutput.js";
+import { RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { readRegularFileTextSnapshot } from "./RegularFileRead.js";
+import { ClientConfigurationPublicationFailure } from "./ClientConfigurationCleanup.js";
+/** The exact staged file retained through publication, verification and recovery. */
+export class ClientConfigurationPublication {
+    path;
+    contents;
+    owner;
+    staging;
+    cleanup;
+    constructor(path, contents, owner, staging, cleanup) {
+        this.path = path;
+        this.contents = contents;
+        this.owner = owner;
+        this.staging = staging;
+        this.cleanup = cleanup;
+    }
+    static async write(path, contents, previous, mode) {
+        const parent = await realpath(dirname(path));
+        const destination = join(parent, basename(path));
+        const input = await selectedConfiguration(destination, previous);
+        const directory = await mkdtemp(`${parent}${sep}.rea-config-`);
+        const staging = await OwnedStagedOutput.create(directory);
+        const cleanup = new AnalysisCleanupLease(() => staging.close(), [directory]);
+        try {
+            const stagedPath = `${directory}${sep}content`;
+            const owner = new OwnedFileHandle(await open(stagedPath, constants.O_RDWR |
+                constants.O_CREAT |
+                constants.O_EXCL |
+                (constants.O_NONBLOCK ?? 0) |
+                (constants.O_NOFOLLOW ?? 0), 0o600));
+            staging.setFile(owner);
+            await owner.handle.writeFile(contents, { encoding: "utf8" });
+            const created = await owner.handle.stat();
+            if (input !== undefined &&
+                (input.uid !== created.uid || input.gid !== created.gid))
+                await owner.handle.chown(input.uid, input.gid);
+            await owner.handle.chmod(mode ?? (input?.mode ?? 0o600) & 0o7777);
+            await owner.handle.sync();
+            if ((await owner.handle.stat()).ino === 0)
+                throw new RegularFileChangedError(stagedPath);
+            await staging.assertReadyForPublication(stagedPath);
+            await assertSelectedConfiguration(destination, input);
+            if (input === undefined) {
+                // An exclusive link cannot overwrite a file created after absence was checked.
+                await link(stagedPath, destination);
+            }
+            else {
+                // The destination is explicit: rename never follows its final symlink.
+                await rename(stagedPath, destination);
+                staging.recordPublishedRename();
+            }
+            return new ClientConfigurationPublication(destination, contents, owner, staging, cleanup);
+        }
+        catch (cause) {
+            await releaseStaging(path, staging, cleanup, { kind: "failed", cause });
+            throw cause;
+        }
+    }
+    /** Keep all publication resources owned through the complete operation. */
+    async verify(operation) {
+        let outcome;
+        try {
+            outcome = { kind: "completed", value: await operation() };
+        }
+        catch (cause) {
+            outcome = { kind: "failed", cause };
+        }
+        await releaseStaging(this.path, this.staging, this.cleanup, outcome);
+        if (outcome.kind === "failed")
+            throw outcome.cause;
+        return outcome.value;
+    }
+    async assertCurrent() {
+        const owned = await this.owner.handle.stat();
+        const named = await lstat(this.path);
+        if (owned.ino === 0 ||
+            named.isSymbolicLink() ||
+            !sameRegularFileState(owned, named))
+            throw new RegularFileChangedError(this.path);
+    }
+    /** State checks do not exclude a concurrent writer to the same inode. */
+    async restore(original) {
+        if (original === undefined)
+            throw new Error("First-run configuration recovery requires manual removal; pathname deletion cannot prove ownership");
+        const handle = this.owner.handle;
+        const before = await handle.stat();
+        const named = await lstat(this.path);
+        if (before.ino === 0 ||
+            !before.isFile() ||
+            named.isSymbolicLink() ||
+            !sameRegularFileState(before, named) ||
+            !(await this.#hasPublishedBytes(handle)) ||
+            !sameRegularFileState(before, await handle.stat()) ||
+            !sameRegularFileState(before, await lstat(this.path)))
+            throw new RegularFileChangedError(this.path);
+        const bytes = Buffer.from(original, "utf8");
+        for (let position = 0; position < bytes.length;) {
+            const { bytesWritten } = await handle.write(bytes, position, bytes.length - position, position);
+            if (bytesWritten === 0)
+                throw new Error("Configuration restoration made no write progress");
+            position += bytesWritten;
+        }
+        await handle.truncate(bytes.length);
+        if (!sameRegularFileState(await handle.stat(), await lstat(this.path)))
+            throw new RegularFileChangedError(this.path);
+    }
+    async #hasPublishedBytes(handle) {
+        const expected = Buffer.from(this.contents, "utf8");
+        if ((await handle.stat()).size !== expected.length)
+            return false;
+        const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, expected.length));
+        for (let position = 0; position < expected.length;) {
+            const { bytesRead } = await handle.read(chunk, 0, Math.min(chunk.length, expected.length - position), position);
+            if (bytesRead === 0 ||
+                !chunk
+                    .subarray(0, bytesRead)
+                    .equals(expected.subarray(position, position + bytesRead)))
+                return false;
+            position += bytesRead;
+        }
+        return true;
+    }
+}
+const selectedConfiguration = async (path, previous) => {
+    let selected;
+    try {
+        selected = await readRegularFileTextSnapshot(path, { symlinks: "reject" });
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+            throw cause;
+    }
+    if (selected?.text !== previous || selected?.state.ino === 0)
+        throw new RegularFileChangedError(path);
+    return selected?.state;
+};
+const assertSelectedConfiguration = async (path, selected) => {
+    let current;
+    try {
+        current = await lstat(path);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+            throw cause;
+    }
+    if (selected === undefined
+        ? current !== undefined
+        : current === undefined ||
+            current.isSymbolicLink() ||
+            !sameRegularFileState(selected, current))
+        throw new RegularFileChangedError(path);
+};
+const releaseStaging = async (path, staging, cleanup, outcome) => {
+    try {
+        await cleanup.release();
+    }
+    catch (cause) {
+        throw new ClientConfigurationPublicationFailure(path, outcome, cause, { kind: "staged-output", resource: staging.directory, output: staging }, cleanup);
+    }
+};

package/dist/application/ClientRegistrationEnvironment.js

@@ -10,6 +10,17 @@ import { dshDocument } from "./DshCordisPatch.js";
 export const clientRegistrationEnvironment = (parsed, overrides = {}, validation = "effective") => {
     if (parsed?.dialect === "dsh")
         return dshDocument(parsed.document).environment(overrides, validation);
+    const details = clientRegistrationEnvironmentDetails(parsed, overrides, validation);
+    return details.ok ? ok(details.value.values) : details;
+};
+/** Retain original strings and the parser-owned timeout facts. */
+export const clientRegistrationEnvironmentDetails = (parsed, overrides = {}, validation = "effective", resolveProviderRequestBudget) => {
+    if (parsed?.dialect === "dsh") {
+        const environment = dshDocument(parsed.document).environment(overrides, validation);
+        if (!environment.ok)
+            return environment;
+        return validatedDetails(environment.value, validation, resolveProviderRequestBudget);
+    }
     const key = parsed?.dialect === "opencode" || parsed?.dialect === "opencode_v2"
         ? "environment"
         : "env";
@@ -32,10 +43,29 @@ export const clientRegistrationEnvironment = (parsed, overrides = {}, validation
     // Validate known settings with the runtime's parser, but retain the original
     // string overrides, including unknown client-specific keys and no defaults.
     const environment = { ...existing.data, ...overrides };
+    return validatedDetails(environment, validation, resolveProviderRequestBudget);
+};
+const validatedDetails = (environment, validation, resolveProviderRequestBudget) => {
     const validated = validation === "fragment"
         ? parseEnvironmentValues(environment)
         : parseEnvironment(environment);
     if (!validated.ok)
         return validated;
-    return ok(Object.fromEntries(Object.entries(environment).sort(([left], [right]) => compareUnicodeCodePoints(left, right))));
+    const providerRequestBudget = resolveProviderRequestBudget?.(validated.value.REA_ANALYSIS_PROVIDER, environment) ?? ok(undefined);
+    if (!providerRequestBudget.ok)
+        return providerRequestBudget;
+    return ok({
+        values: Object.fromEntries(Object.entries(environment).sort(([left], [right]) => compareUnicodeCodePoints(left, right))),
+        timeoutInputs: {
+            analysisProvider: validated.value.REA_ANALYSIS_PROVIDER,
+            ghidraStartupTimeoutMs: validated.value.REA_GHIDRA_STARTUP_TIMEOUT_MS,
+            hopperStartupTimeoutMs: validated.value.REA_HOPPER_STARTUP_TIMEOUT_MS,
+            ...(validated.value.REA_JEB_MCP_TIMEOUT_MS === undefined
+                ? {}
+                : { jebMcpTimeoutMs: validated.value.REA_JEB_MCP_TIMEOUT_MS }),
+            ...(providerRequestBudget.value === undefined
+                ? {}
+                : { providerRequestTimeoutMs: providerRequestBudget.value }),
+        },
+    });
 };

package/dist/application/ClientRegistrationIdentity.js

@@ -1,11 +1,14 @@
-import { isAbsolute, resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { normalizeEntrypointPath } from "../process/CurrentEntrypointPath.js";
 import { valid } from "semver";
 import { PRODUCT_IDENTITY } from "../identity.js";
 /** Read one variable; Windows variable names are case-insensitive. */
 const environmentValue = (environment, name, platform) => {
     if (platform !== "win32")
         return environment[name];
-    const key = Object.keys(environment).find((candidate) => candidate.toLowerCase() === name);
+    const target = name.toLowerCase();
+    const key = Object.keys(environment).findLast((candidate) => candidate.toLowerCase() === target);
     return key === undefined ? undefined : environment[key];
 };
 /** Identify the package runner that launched this process, if any. */
@@ -64,55 +67,67 @@ const isOwnedPackageReference = (packageReference) => {
     return (packageReference.startsWith(versionPrefix) &&
         valid(packageReference.slice(versionPrefix.length)) !== null);
 };
-/** Classify only what the command and current executable identity establish. */
+/** Compare entrypoint paths without turning failed resolution into a foreign identity. */
+const entrypointIdentity = (candidate, current) => {
+    if (!isAbsolute(candidate) || !isAbsolute(current))
+        return "unknown";
+    if (candidate === current)
+        return "owned";
+    try {
+        return realpathSync.native(candidate) === realpathSync.native(current)
+            ? "owned"
+            : "foreign";
+    }
+    catch {
+        return "unknown";
+    }
+};
+/** A direct launcher may be a native executable or a Node shebang script. */
+const directEntrypointIdentity = (candidate, current) => {
+    const nativeIdentity = entrypointIdentity(candidate, current);
+    const scriptPath = normalizeEntrypointPath(candidate);
+    if (scriptPath === candidate)
+        return nativeIdentity;
+    // A shebang can pass the original spelling to Node, which selects its script
+    // lexically. Without executing the launcher, divergent interpretations are unknown.
+    return scriptPath !== undefined &&
+        entrypointIdentity(scriptPath, current) === nativeIdentity
+        ? nativeIdentity
+        : "unknown";
+};
+/** Classify the command once; uncertainty never grants positive ownership. */
 export const classifyClientRegistrationCommand = (command, currentCommandPath) => {
     const packageReference = clientRegistrationPackageReference(command);
     if (packageReference !== undefined)
-        return isOwnedClientRegistrationCommand(command, currentCommandPath)
-            ? "owned"
-            : "foreign";
+        return isOwnedPackageReference(packageReference) ? "owned" : "foreign";
     const currentPathAvailable = currentCommandPath !== undefined && currentCommandPath.length > 0;
-    const nodeScript = command.length === 3 && command[2] === "mcp";
-    if (nodeScript) {
-        if (!isAbsolute(command[0] ?? "") ||
-            !isAbsolute(command[1] ?? "") ||
+    if (command.length === 3 && command[2] === "mcp") {
+        const interpreter = command[0] ?? "";
+        const entrypoint = command[1] ?? "";
+        if (!isAbsolute(interpreter) ||
+            !isAbsolute(entrypoint) ||
             !currentPathAvailable)
             return "unknown";
-        return isOwnedClientRegistrationCommand(command, currentCommandPath)
-            ? "owned"
-            : "foreign";
+        const interpreterIdentity = entrypointIdentity(interpreter, process.execPath);
+        if (interpreterIdentity !== "owned")
+            return interpreterIdentity;
+        // Node selects its script from normalized argv; executable paths use native
+        // traversal semantics, where symlink/.. can denote a different file.
+        const selectedEntrypoint = normalizeEntrypointPath(entrypoint);
+        return selectedEntrypoint === undefined
+            ? "unknown"
+            : entrypointIdentity(selectedEntrypoint, currentCommandPath);
     }
     if (command.length === 2 && command[1] === "mcp") {
         const executable = command[0] ?? "";
         if (executable === PRODUCT_IDENTITY.cliBinary)
             return "owned";
-        const relativePathLike = !isAbsolute(executable) && /[./\\]/u.test(executable);
-        if (relativePathLike || (isAbsolute(executable) && !currentPathAvailable))
+        if (isAbsolute(executable))
+            return currentPathAvailable
+                ? directEntrypointIdentity(executable, currentCommandPath)
+                : "unknown";
+        if (/[./\\]/u.test(executable))
             return "unknown";
     }
-    if (isOwnedClientRegistrationCommand(command, currentCommandPath))
-        return "owned";
     return "foreign";
 };
-export const isOwnedClientRegistrationCommand = (command, currentCommandPath) => {
-    if (currentCommandPath !== undefined &&
-        currentCommandPath.length > 0 &&
-        command.length === 3 &&
-        command[2] === "mcp" &&
-        isAbsolute(command[0] ?? "") &&
-        isAbsolute(command[1] ?? "") &&
-        resolve(command[0] ?? "") === resolve(process.execPath) &&
-        resolve(command[1] ?? "") === currentCommandPath)
-        return true;
-    if (command.length === 2 && command[1] === "mcp") {
-        const executable = command[0] ?? "";
-        if (executable === PRODUCT_IDENTITY.cliBinary ||
-            (isAbsolute(executable) &&
-                currentCommandPath !== undefined &&
-                currentCommandPath.length > 0 &&
-                resolve(executable) === currentCommandPath))
-            return true;
-    }
-    const packageReference = clientRegistrationPackageReference(command);
-    return (packageReference !== undefined && isOwnedPackageReference(packageReference));
-};

package/dist/application/ClientRegistrationStatus.js

@@ -1,22 +1,31 @@
 import { readClientPolicyBlock } from "./GeminiClientSettings.js";
 import { readEffectiveClientRegistrationConfiguration } from "./ClientConfigurationFiles.js";
 import { clientServerForcedEnabled, clientServerListedDisabled, effectiveClientServer, } from "./ClientConfigurationDocument.js";
-import { access } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { lstat } from "node:fs/promises";
+import { err, ok } from "../domain/result.js";
+import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { valid } from "semver";
+import { RegularFileCleanupFailure } from "./RegularFileRead.js";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
-import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
+import { MCP_STARTUP_POLICY, mcpProviderDeadlineAllowanceMs, recommendedMcpToolTimeoutMs, recommendedMcpToolTimeoutSeconds, } from "../mcpStartupPolicy.js";
 import { clientRegistrationPackageReference, classifyClientRegistrationCommand, packageRunnerRegistrationCommand, } from "./ClientRegistrationIdentity.js";
 import { clientEvidencePaths, manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 import { dshDocument } from "./DshCordisPatch.js";
+import { clientRegistrationEnvironmentDetails } from "./ClientRegistrationEnvironment.js";
+const tomlTimeoutSchema = z.union([
+    z.number().positive(),
+    z.bigint().positive(),
+]);
 const registrationSchema = z
     .object({
     command: z.string().min(1),
     args: z.array(z.string()).default([]),
-    startup_timeout_sec: z.number().positive().optional(),
+    // TOML keeps integers beyond the safe Number range exact as bigint.
+    startup_timeout_sec: tomlTimeoutSchema.optional(),
+    tool_timeout_sec: tomlTimeoutSchema.optional(),
     startupTimeoutMs: z.number().positive().optional(),
     toolTimeoutMs: z.number().positive().optional(),
     type: z.string().optional(),
@@ -29,7 +38,9 @@ const registrationSchema = z
     .passthrough();
 /** Project diagnostics from the same inspection used to select maintenance. */
 export const readClientRegistrationStatuses = async (home, currentCommandPath = CURRENT_ENTRYPOINT_PATH, options = {}) => (await readClientRegistrationInspections(home, currentCommandPath, options)).map(({ status }) => status);
-/** Parse effective registrations and their client-specific activation once. */
+/** Parse effective registrations and their client-specific activation once.
+ * A supplied scope retains failed cleanup; otherwise transfer its exact failure.
+ */
 export const readClientRegistrationInspections = async (home, currentCommandPath = CURRENT_ENTRYPOINT_PATH, options = {}) => {
     const inspections = [];
     const record = (status, activation = "unknown") => {
@@ -46,7 +57,18 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
             });
             continue;
         }
-        if (!(await clientEvidencePresent(client)))
+        const presence = await clientEvidencePresent(client);
+        if (!presence.ok) {
+            record({
+                client: client.name,
+                config_path: presence.error.path,
+                command: [],
+                state: "invalid",
+                remediation: presence.error.detail,
+            });
+            continue;
+        }
+        if (!presence.value)
             continue;
         const manualRemediation = manualRegistrationRemediation(client.name);
         if (client.format === "unsupported") {
@@ -64,6 +86,9 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
         try {
             const configuration = await readEffectiveClientRegistrationConfiguration(client, options.resources);
             if (!configuration.ok) {
+                if (options.resources === undefined &&
+                    configuration.error.cleanupFailure !== undefined)
+                    throw configuration.error.cleanupFailure;
                 record({
                     client: client.name,
                     config_path: configuration.error.path,
@@ -81,6 +106,9 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
             }
             const policy = await readClientPolicyBlock(client, parsed, undefined, options.resources);
             if (!policy.ok) {
+                if (options.resources === undefined &&
+                    policy.error.cleanupFailure !== undefined)
+                    throw policy.error.cleanupFailure;
                 record({
                     client: client.name,
                     config_path: configPath,
@@ -118,6 +146,20 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
                 }
                 : client;
             const registration = parseRegistration(raw, effectiveClient);
+            const registrationEnvironment = client.name === "kimi" || client.name === "codex"
+                ? clientRegistrationEnvironmentDetails(parsed, {}, "effective", options.resolveProviderRequestBudget)
+                : undefined;
+            if (registrationEnvironment !== undefined &&
+                !registrationEnvironment.ok) {
+                record({
+                    client: client.name,
+                    config_path: configPath,
+                    command: [],
+                    state: "invalid",
+                    remediation: registrationEnvironment.error.message,
+                });
+                continue;
+            }
             const command = [
                 registration.command,
                 ...registration.args,
@@ -127,7 +169,15 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
             const packageVersion = exactRegisteredPackageVersion(packageReference);
             const packageVersionDrift = packageVersion !== undefined &&
                 packageVersion !== PRODUCT_IDENTITY.packageVersion;
-            const alignment = registrationAligned(registration, effectiveClient, currentCommandPath, options.platform ?? process.platform);
+            const alignment = registrationAligned({
+                registration,
+                client: effectiveClient,
+                currentCommandPath,
+                platform: options.platform ?? process.platform,
+                kimiInputSchemaProfileSelected: registrationEnvironment?.ok === true &&
+                    registrationEnvironment.value.values.REA_MCP_INPUT_SCHEMA_PROFILE !==
+                        undefined,
+            });
             record(configuredStatus(effectiveClient, command, alignment === "unknown"
                 ? "unknown"
                 : activation === "enabled" &&
@@ -142,9 +192,14 @@ export const readClientRegistrationInspections = async (home, currentCommandPath
                     ? packageVersionRemediation(packageReference ?? "", client)
                     : alignment === "unknown"
                         ? unknownEntryPointRemediation()
-                        : undefined), packageReference), activation);
+                        : undefined), packageReference, registrationEnvironment?.ok === true
+                ? timeoutAdvisory(client, registration, registrationEnvironment.value.timeoutInputs)
+                : undefined), activation);
         }
         catch (cause) {
+            if (options.resources === undefined &&
+                cause instanceof RegularFileCleanupFailure)
+                throw cause;
             record(unavailableStatus(client, isMissing(cause) ? "missing" : "invalid", selectedConfigPath));
         }
     }
@@ -158,21 +213,26 @@ const registrationActivation = (registration, client, parsed) => (client.format
     clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
     ? "disabled"
     : "enabled";
-const registrationAligned = (registration, client, currentCommandPath, platform) => {
+const registrationAligned = ({ registration, client, currentCommandPath, platform, kimiInputSchemaProfileSelected, }) => {
     const command = [registration.command, ...registration.args];
     const identity = classifyClientRegistrationCommand(command, currentCommandPath);
     if (identity === "unknown")
         return "unknown";
     if (identity === "foreign")
         return "stale";
-    if ((client.name === "codex" || client.name === "grok_build") &&
+    if (client.name === "grok_build" &&
         registration.startup_timeout_sec !==
             MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)
         return "stale";
+    if (client.name === "codex" &&
+        (registration.startup_timeout_sec === undefined ||
+            registration.tool_timeout_sec === undefined))
+        return "stale";
     if (client.name === "kimi" &&
-        (registration.startupTimeoutMs !==
-            MCP_STARTUP_POLICY.kimiStartupTimeoutMs ||
-            registration.toolTimeoutMs !== MCP_STARTUP_POLICY.kimiToolTimeoutMs))
+        (registration.startupTimeoutMs === undefined ||
+            registration.toolTimeoutMs === undefined))
+        return "stale";
+    if (client.name === "kimi" && !kimiInputSchemaProfileSelected)
         return "stale";
     if ((client.format === "kimi" ||
         client.format === "omp" ||
@@ -199,23 +259,12 @@ const registrationAligned = (registration, client, currentCommandPath, platform)
             command.every((argument, index) => argument === expected[index]));
     }))
         return "aligned";
-    if (currentCommandPath !== undefined &&
-        currentCommandPath.length > 0 &&
-        command.length === 3 &&
-        command[2] === "mcp" &&
-        isAbsolute(command[0] ?? "") &&
-        isAbsolute(command[1] ?? "") &&
-        resolve(command[0] ?? "") === resolve(process.execPath) &&
-        resolve(command[1] ?? "") === currentCommandPath)
-        return "aligned";
-    if (currentCommandPath !== undefined &&
-        currentCommandPath.length > 0 &&
-        command.length === 2 &&
-        command[1] === "mcp" &&
-        isAbsolute(command[0] ?? "") &&
-        resolve(command[0] ?? "") === currentCommandPath)
-        return "aligned";
-    return "stale";
+    // Other owned package references remain stale until pinned to this version.
+    if (clientRegistrationPackageReference(command) !== undefined)
+        return "stale";
+    // The identity owner already established an exact direct launcher match.
+    // A bare command still depends on the client's PATH, so cannot prove alignment.
+    return isAbsolute(command[0] ?? "") ? "aligned" : "stale";
 };
 const parseRegistration = (value, client) => {
     if (client.format === "dsh")
@@ -264,8 +313,8 @@ const remediation = (client) => {
     const name = client.displayName ?? client.name;
     return `Quit ${name} fully, run rea setup to refresh this registration, then start ${name} again. A running ${name} can rewrite its configuration from memory and drop the registration.`;
 };
-const unknownEntryPointRemediation = () => "The existing registration was retained because its executable identity cannot be verified. Run the installed REA CLI or a supported package runner, then rerun rea doctor; no registration was changed.";
-const configuredStatus = (client, command, state, policyRemediation, packageReference) => state === "aligned"
+const unknownEntryPointRemediation = () => "The existing registration was retained because its executable identity cannot be verified. Check the registered launcher path, symlink targets and access permissions. Run the installed REA CLI or a supported package runner, then rerun rea doctor; no registration was changed.";
+const configuredStatus = (client, command, state, policyRemediation, packageReference, advisory) => state === "aligned"
     ? {
         client: client.name,
         config_path: client.configPath,
@@ -275,6 +324,7 @@ const configuredStatus = (client, command, state, policyRemediation, packageRefe
             : { package_reference: packageReference }),
         state,
         remediation: null,
+        ...(advisory === undefined ? {} : { advisory }),
     }
     : {
         client: client.name,
@@ -286,6 +336,32 @@ const configuredStatus = (client, command, state, policyRemediation, packageRefe
         state,
         remediation: policyRemediation ?? remediation(client),
     };
+const timeoutAdvisory = (client, registration, timeoutInputs) => {
+    const toolTimeout = client.name === "kimi"
+        ? registration.toolTimeoutMs
+        : client.name === "codex"
+            ? registration.tool_timeout_sec
+            : undefined;
+    if (toolTimeout === undefined)
+        return undefined;
+    const providerAllowance = mcpProviderDeadlineAllowanceMs(timeoutInputs);
+    const isKimi = client.name === "kimi";
+    // A bigint is beyond the safe Number range, so rounding cannot cross the allowance.
+    const toolTimeoutMs = Number(toolTimeout) * (isKimi ? 1 : 1000);
+    if (toolTimeoutMs >= providerAllowance)
+        return undefined;
+    const setting = isKimi ? "toolTimeoutMs" : "tool_timeout_sec";
+    const currentValue = isKimi
+        ? `${String(toolTimeout)} ms`
+        : `${String(toolTimeout)} seconds`;
+    const recommendedValue = isKimi
+        ? `${String(recommendedMcpToolTimeoutMs(timeoutInputs))} ms`
+        : `${String(recommendedMcpToolTimeoutSeconds(timeoutInputs))} seconds`;
+    const headroom = isKimi
+        ? `${String(MCP_STARTUP_POLICY.toolOperationHeadroomMs)} ms`
+        : `${String(MCP_STARTUP_POLICY.toolOperationHeadroomMs / 1000)} seconds`;
+    return `The configured ${setting} (${currentValue}) is shorter than REA's known provider allowance (${String(providerAllowance)} ms), so provider startup or an upstream request may exceed this client deadline. REA recommends ${setting} = ${recommendedValue} to cover that allowance plus ${headroom} of operation headroom; this additional headroom is a recommendation, not a guarantee for every analysis.`;
+};
 const exactRegisteredPackageVersion = (packageReference) => {
     if (packageReference === undefined)
         return undefined;
@@ -303,23 +379,22 @@ const unavailableStatus = (client, state, configPath = client.configPath) => ({
     state,
     remediation: remediation(client),
 });
+/** Entry presence is independent of whether its target can currently be read. */
 const clientEvidencePresent = async (client) => {
-    for (const path of clientEvidencePaths(client))
-        if (await exists(path))
-            return true;
-    return false;
-};
-const exists = async (path) => {
-    if (path === undefined)
-        return false;
-    try {
-        await access(path);
-        return true;
-    }
-    catch (cause) {
-        // best-effort cleanup: optional registration probing; absence means unregistered.
-        void cause;
-        return false;
+    let unavailable;
+    for (const path of clientEvidencePaths(client)) {
+        try {
+            await lstat(path);
+            return ok(true);
+        }
+        catch (cause) {
+            if (!isMissing(cause))
+                unavailable ??= {
+                    path,
+                    detail: `Client configuration evidence at ${path} could not be inspected: ${cause instanceof Error ? cause.message : String(cause)}. Check file permissions and rerun rea doctor.`,
+                };
+        }
     }
+    return unavailable === undefined ? ok(false) : err(unavailable);
 };
 const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";