rea-agents 6.3.0 → 6.5.0

package/dist/application/EnhancedTools.js

@@ -2,20 +2,27 @@ import { z } from "zod";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
-import { addressDistance, functionDossierSchema, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
+import { addressDistance, functionDossierSchema, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, parseSegmentImageBase, } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, } from "../domain/symbolAnalysis.js";
 import { inspectNativeDispatch } from "./native/NativeDispatchMetadataInspection.js";
 import { traceNativeValues } from "./native/NativeValueTrace.js";
 import { traceNativeUiAction } from "./native/NativeUiActionTrace.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
 import { invalidEnhancedInput, } from "./EnhancedToolTypes.js";
 import { resolveAnalysisDocument } from "./AnalysisDocument.js";
 import { traceCallPath } from "./CallPathTracing.js";
 import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
 import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
 import { projectNativeApiInspection } from "./native/NativeApiInspection.js";
+const isAnalysisCancellation = (error) => error._tag === "AnalysisCancelledError";
+const firstAnalysisCancellation = (results) => {
+    for (const result of results)
+        if (!result.ok && isAnalysisCancellation(result.error))
+            return result.error;
+    return undefined;
+};
 /**
  * Composes direct provider operations into bounded reverse-engineering tools.
  * Direct callers use `execute`; adapters that own validation use
@@ -115,9 +122,9 @@ export class EnhancedTools {
             case "inspect_native_api":
                 return this.#inspectNativeApi(call.input, signal);
             case "trace_feature":
-                return traceLiteralFeature((name, arguments_, operationSignal) => this.#call(name, arguments_, operationSignal), call.input, signal);
+                return traceLiteralFeature((name, arguments_, operationSignal) => this.#call(name, arguments_, operationSignal), (name, arguments_, operationSignal) => this.#observe(name, arguments_, operationSignal), call.input, signal);
             case "trace_call_path":
-                return traceCallPath((name, arguments_, operationSignal) => this.#call(name, arguments_, operationSignal), call.input, signal);
+                return traceCallPath((name, arguments_, operationSignal, selectorOrigin) => this.#call(name, arguments_, operationSignal, selectorOrigin), (name, arguments_, operationSignal, selectorOrigin) => this.#observe(name, arguments_, operationSignal, selectorOrigin), call.input, signal);
             case "trace_native_values":
                 return traceNativeValues(this.analysis, call.input, signal);
             case "trace_native_ui_action": {
@@ -178,36 +185,27 @@ export class EnhancedTools {
         return names.ok ? ok(discoverObjcProtocols(names.value)) : names;
     }
     async #batchDecompile(addresses, signal) {
-        const items = await Promise.all(addresses.map(async (address) => {
-            const resolved = await resolveProcedureAddress(this.#call.bind(this), address, signal);
-            const procedure = resolved.ok
-                ? await this.#batchProcedureIdentity(resolved.value, signal)
-                : {
-                    status: "unknown",
-                    error: projectAnalysisError(resolved.error),
-                };
-            const result = await this.#call("procedure_pseudo_code", { procedure: resolved.ok ? resolved.value : address }, signal);
-            if (!result.ok)
-                return {
-                    address,
-                    procedure,
-                    status: "error",
-                    error: projectAnalysisError(result.error),
-                };
-            if (typeof result.value !== "string" || result.value.length === 0)
-                return {
-                    address,
-                    procedure,
-                    status: "error",
-                    error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
-                };
-            return {
-                address,
-                procedure,
-                status: "ok",
-                pseudocode: result.value,
-            };
+        const resolutions = await Promise.all(addresses.map(async (address) => {
+            const result = await resolveProcedureAddress(this.#call.bind(this), address, signal);
+            return { address, result };
         }));
+        const resolutionCancellation = firstAnalysisCancellation(resolutions.map(({ result }) => result));
+        if (resolutionCancellation !== undefined)
+            return err(resolutionCancellation);
+        const identities = await this.#batchIdentities(resolutions, signal);
+        const ready = [];
+        for (const identity of identities) {
+            if (!identity.ok)
+                return err(identity.error);
+            ready.push(identity.value);
+        }
+        const decompilations = await this.#batchPseudocode(ready, signal);
+        const items = [];
+        for (const decompilation of decompilations) {
+            if (!decompilation.ok)
+                return err(decompilation.error);
+            items.push(decompilation.value);
+        }
         const succeeded = items.filter(({ status }) => status === "ok").length;
         return ok({
             items,
@@ -216,11 +214,62 @@ export class EnhancedTools {
             failed: items.length - succeeded,
         });
     }
+    async #batchIdentities(resolutions, signal) {
+        return Promise.all(resolutions.map(async ({ address, result }) => {
+            if (!result.ok)
+                return ok({
+                    address,
+                    providerProcedure: address,
+                    procedure: {
+                        status: "unknown",
+                        error: projectAnalysisError(result.error),
+                    },
+                });
+            const identity = await this.#batchProcedureIdentity(result.value, signal);
+            return identity.ok
+                ? ok({
+                    address,
+                    providerProcedure: result.value,
+                    procedure: identity.value,
+                })
+                : err(identity.error);
+        }));
+    }
+    async #batchPseudocode(ready, signal) {
+        return Promise.all(ready.map(async ({ address, procedure, providerProcedure }) => {
+            const result = await this.#call("procedure_pseudo_code", { procedure: providerProcedure }, signal, procedure.status === "resolved" ? "provider" : undefined);
+            if (!result.ok && isAnalysisCancellation(result.error))
+                return err(result.error);
+            const item = !result.ok
+                ? {
+                    address,
+                    procedure,
+                    status: "error",
+                    error: projectAnalysisError(result.error),
+                }
+                : typeof result.value !== "string" || result.value.length === 0
+                    ? {
+                        address,
+                        procedure,
+                        status: "error",
+                        error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
+                    }
+                    : {
+                        address,
+                        procedure,
+                        status: "ok",
+                        pseudocode: result.value,
+                    };
+            return ok(item);
+        }));
+    }
     async #batchProcedureIdentity(address, signal) {
         const observed = await this.#call("address_name", { address }, signal);
+        if (!observed.ok && isAnalysisCancellation(observed.error))
+            return err(observed.error);
         const named = observed.ok &&
             (typeof observed.value === "string" || observed.value === null);
-        return {
+        return ok({
             status: "resolved",
             address,
             name: named ? observed.value : null,
@@ -231,17 +280,23 @@ export class EnhancedTools {
                         ? new AnalysisOutputError("address_name", "provider returned an invalid entry label")
                         : observed.error),
                 }),
-        };
+        });
     }
     async #callGraph(input, signal) {
         const relation = input.direction === "forward" ? "callees" : "callers";
         const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
-        const resolved = await resolveProcedureAddress(this.#call.bind(this), input.address, signal);
+        const limitations = new Set();
+        const resolved = await this.#observe("procedure_address", { procedure: input.address }, signal);
         if (!resolved.ok)
             return resolved;
-        const discovered = new Set([resolved.value]);
+        for (const limitation of resolved.value.limitations)
+            limitations.add(limitation);
+        const startAddress = resolved.value.result;
+        if (typeof startAddress !== "string" || startAddress.length === 0)
+            return err(new AnalysisOutputError("procedure_address", "provider returned no canonical procedure address"));
+        const discovered = new Set([startAddress]);
         const queue = [
-            { address: resolved.value, depth: 0 },
+            { address: startAddress, depth: 0 },
         ];
         let queueIndex = 0;
         const graph = {};
@@ -251,8 +306,10 @@ export class EnhancedTools {
                 continue;
             const level = String(current.depth);
             graph[level] ??= [];
-            const result = await this.#call(tool, { procedure: current.address }, signal);
+            const result = await this.#observe(tool, { procedure: current.address }, signal, "provider");
             if (!result.ok) {
+                if (isAnalysisCancellation(result.error))
+                    return result;
                 graph[level].push({
                     address: current.address,
                     status: "error",
@@ -260,7 +317,7 @@ export class EnhancedTools {
                 });
                 continue;
             }
-            const related = parseRelatedAddresses(result.value, relation);
+            const related = parseRelatedAddresses(result.value.result, relation);
             if (!related.ok) {
                 graph[level].push({
                     address: current.address,
@@ -269,10 +326,37 @@ export class EnhancedTools {
                 });
                 continue;
             }
+            for (const limitation of result.value.limitations)
+                limitations.add(limitation);
+            const reportedCoverage = result.value.relationshipCoverage;
+            const coverage = reportedCoverage ?? {
+                status: "unknown",
+                reason: "Provider did not report relationship coverage.",
+            };
+            const relationshipLimitations = reportedCoverage === undefined
+                ? [
+                    ...result.value.limitations,
+                    "Provider did not report relationship coverage.",
+                ]
+                : [
+                    ...(reportedCoverage.status === "partial"
+                        ? reportedCoverage.limitations
+                        : reportedCoverage.status === "unknown"
+                            ? [reportedCoverage.reason]
+                            : []),
+                    ...("diagnostics" in reportedCoverage
+                        ? reportedCoverage.diagnostics
+                        : []),
+                ];
+            const nodeLimitations = [...new Set(relationshipLimitations)].sort(compareUnicodeCodePoints);
             graph[level].push({
                 address: current.address,
                 status: "ok",
                 calls: [...related.value],
+                relationship_coverage: coverage,
+                ...(nodeLimitations.length === 0
+                    ? {}
+                    : { limitations: nodeLimitations }),
             });
             for (const address of related.value) {
                 if (!discovered.has(address)) {
@@ -281,7 +365,10 @@ export class EnhancedTools {
                 }
             }
         }
-        return ok(graph);
+        return ok({
+            graph,
+            limitations: [...limitations].sort(compareUnicodeCodePoints),
+        });
     }
     async #analyzeSwiftTypes(input, signal) {
         const procedures = await this.#allAddressed("list_procedures", signal);
@@ -332,14 +419,17 @@ export class EnhancedTools {
             this.#call("list_procedures", {}, signal),
             this.#call("list_strings", {}, signal),
         ]);
-        if (!segmentsResult.ok)
+        if (!segmentsResult.ok &&
+            !(segmentsResult.error instanceof AnalysisCapabilityUnavailableError))
             return segmentsResult;
         if (!proceduresResult.ok)
             return proceduresResult;
         if (!stringsResult.ok)
             return stringsResult;
-        const segments = parseSegments(segmentsResult.value);
-        if (!segments.ok)
+        const segments = segmentsResult.ok
+            ? parseSegments(segmentsResult.value)
+            : undefined;
+        if (segments !== undefined && !segments.ok)
             return segments;
         const procedureCount = parseListCount(proceduresResult.value, "procedures");
         if (!procedureCount.ok)
@@ -347,15 +437,26 @@ export class EnhancedTools {
         const stringCount = parseListCount(stringsResult.value, "strings");
         if (!stringCount.ok)
             return stringCount;
+        const observedSegments = segments?.ok ? segments.value : undefined;
+        const imageBase = observedSegments === undefined
+            ? undefined
+            : parseSegmentImageBase(observedSegments);
         return ok({
             document: document.value,
-            segments: segments.value.map(({ name, start, end }) => ({
-                name,
-                start,
-                end,
-                length: addressDistance(start, end),
-            })),
-            segment_count: segments.value.length,
+            ...(imageBase === undefined ? {} : { image_base: imageBase }),
+            ...(observedSegments === undefined
+                ? {}
+                : {
+                    segments: observedSegments.map(({ name, start, end, image_base, address_space }) => ({
+                        name,
+                        start,
+                        end,
+                        length: addressDistance(start, end),
+                        ...(image_base === undefined ? {} : { image_base }),
+                        ...(address_space === undefined ? {} : { address_space }),
+                    })),
+                    segment_count: observedSegments.length,
+                }),
             procedure_count: procedureCount.value,
             string_count: stringCount.value,
         });
@@ -371,13 +472,22 @@ export class EnhancedTools {
             ? ok(parsed.data.map(({ address, value: name }) => ({ address, name })))
             : err(new AnalysisOutputError(tool, "provider returned an invalid inventory"));
     }
-    async #call(name, arguments_, signal) {
+    async #call(name, arguments_, signal, selectorOrigin) {
+        const execution = await this.#observe(name, arguments_, signal, selectorOrigin);
+        return execution.ok ? ok(execution.value.result) : execution;
+    }
+    async #observe(name, arguments_, signal, selectorOrigin) {
         if (isAborted(signal))
             return err(new AnalysisCancelledError(name));
-        const execution = await this.analysis.execute(name, arguments_, signal === undefined ? {} : { signal });
+        const execution = await this.analysis.execute(name, arguments_, {
+            ...(signal === undefined ? {} : { signal }),
+            ...(selectorOrigin === undefined ? {} : { selectorOrigin }),
+        });
+        if (!execution.ok)
+            return execution;
         if (isAborted(signal))
             return err(new AnalysisCancelledError(name));
-        return execution.ok ? ok(execution.value.result) : execution;
+        return execution;
     }
 }
 const isAborted = (signal) => signal?.aborted === true;

package/dist/application/EvidenceBundleCommands.js

@@ -1,37 +1,55 @@
-import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
-import {} from "../domain/analysisErrorBase.js";
+import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
 import { compareBundles } from "../domain/bundleComparison.js";
-import { EvidenceLedger } from "./investigation/EvidenceLedger.js";
-import { readEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
-/** Validate and merge one bundle using the session Evidence ledger. */
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { readEvidenceBundle, readImmutableEvidenceBundle, writeEvidenceBundle, } from "./EvidenceBundleFiles.js";
+/** Validate a standalone bundle and report its complete record/revision counts. */
 export const importEvidenceBundleCommand = async (path) => {
     const loaded = await readEvidenceBundle(path);
     if (!loaded.ok)
         return loaded;
-    const ledger = createLedger();
-    const imported = ledger.import(loaded.value);
-    return imported.ok
-        ? ok({
-            imported: imported.value.recordsAdded,
-            unknowns_added: imported.value.unknownsAdded,
-            total: ledger.export().records.length,
-        })
-        : imported;
+    return ok({
+        imported: loaded.value.records.length,
+        unknowns_added: loaded.value.unknowns.length,
+        total: loaded.value.records.length,
+    });
 };
 /** Validate a source bundle and atomically export canonical bytes. */
 export const exportEvidenceBundleCommand = async (sourcePath, outputPath, overwrite) => {
-    const loaded = await readEvidenceBundle(sourcePath);
+    // The sealed snapshot lets the writer reuse this authentication.
+    const loaded = await readImmutableEvidenceBundle(sourcePath);
     if (!loaded.ok)
         return loaded;
-    return projectWrite(loaded.value, await writeEvidenceBundle(loaded.value, outputPath, overwrite));
+    const resources = new ArtifactResourceScope();
+    const written = await writeEvidenceBundle(loaded.value, outputPath, overwrite, resources);
+    if (written.ok)
+        return projectWrite(loaded.value, written);
+    let cleanupSucceeded = false;
+    try {
+        await resources.close();
+        cleanupSucceeded = true;
+    }
+    catch {
+        // The original error cause retains the same staged-output owner for diagnostics.
+    }
+    if (cleanupSucceeded &&
+        written.error instanceof EvidenceFileError &&
+        written.error.published) {
+        return projectWrite(loaded.value, {
+            ok: true,
+            value: written.error.published,
+        });
+    }
+    return written;
 };
 /** Compare two validated canonical Evidence bundles without session state. */
 export const compareEvidenceBundlesCommand = async (input) => {
+    // Sealed snapshots let comparison and its bundle digests reuse this
+    // authentication instead of re-validating every record twice more.
     const [left, right] = await Promise.all([
-        readEvidenceBundle(input.leftPath),
-        readEvidenceBundle(input.rightPath),
+        readImmutableEvidenceBundle(input.leftPath),
+        readImmutableEvidenceBundle(input.rightPath),
     ]);
     if (!left.ok)
         return left;
@@ -46,7 +64,6 @@ export const compareEvidenceBundlesCommand = async (input) => {
         }));
     }
 };
-const createLedger = () => new EvidenceLedger();
 const projectWrite = (bundle, written) => written.ok
     ? ok({
         path: written.value.path,

package/dist/application/EvidenceBundleFiles.js

@@ -1,23 +1,45 @@
-import { describeEvidenceBundleFailure, describeValidationFailure, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { resolve } from "node:path";
+import { describeEvidenceBundleFailure, describeValidationFailure, parseImmutableEvidenceBundle, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { err, ok } from "../domain/result.js";
 import { AnalysisCancelledError, } from "../domain/analysisErrorCore.js";
 import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
 import { bufferedJsonParts, canonicalJsonParts, } from "../domain/jsonSerialization.js";
 import { readJsonFile, writeTextParts } from "./JsonFiles.js";
+import { RegularFileCleanupFailure } from "./RegularFileRead.js";
 /** Read and validate an evidence bundle at the caller-supplied path. */
-export const readEvidenceBundle = async (path) => {
-    const loaded = await readJsonFile(path);
+export const readEvidenceBundle = (path, signal, resources) => readBundle(path, parseEvidenceBundle, signal, resources);
+/** Read an authenticated immutable snapshot for a subsequent session import. */
+export const readImmutableEvidenceBundle = (path, signal, resources) => readBundle(path, parseImmutableEvidenceBundle, signal, resources);
+const readBundle = async (path, parseBundle, signal, resources) => {
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("import_evidence_bundle"));
+    const loaded = await readJsonFile(path, signal, resources).catch((cause) => {
+        // A failed close transfers a live handle owner; preserve that failure.
+        if (signal?.aborted === true &&
+            !(cause instanceof RegularFileCleanupFailure))
+            return err(new AnalysisCancelledError("import_evidence_bundle", { cause }));
+        throw cause;
+    });
     if (!loaded.ok)
         return loaded;
+    if (signal?.aborted)
+        return err(new AnalysisCancelledError("import_evidence_bundle"));
     let bundle;
     try {
-        bundle = parseEvidenceBundle(loaded.value);
+        bundle = parseBundle(loaded.value);
     }
     catch (cause) {
+        const failure = describeEvidenceBundleFailure(loaded.value, cause);
+        if (failure.kind === "single-record")
+            return err(new EvidenceFileError("read", "wrong-kind", {
+                path: resolve(path),
+                cause,
+                userMessage: failure.message,
+            }));
         return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
             cause,
-            userMessage: describeEvidenceBundleFailure(loaded.value, cause),
+            userMessage: failure.message,
         }));
     }
     for (const record of bundle.records) {
@@ -36,7 +58,7 @@ export const readEvidenceBundle = async (path) => {
     return ok(bundle);
 };
 /** Atomically write deterministic evidence JSON at the caller-supplied path. */
-export const writeEvidenceBundle = async (bundle, path, overwrite, signal) => {
+export const writeEvidenceBundle = async (bundle, path, overwrite, resources, signal) => {
     if (signal?.aborted === true)
         return err(new AnalysisCancelledError("export_evidence_bundle"));
     let checked;
@@ -48,7 +70,7 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, signal) => {
             cause,
         }));
     }
-    return writeTextParts(bufferedJsonParts(canonicalJsonParts(checked)), path, overwrite, signal === undefined
+    return writeTextParts(bufferedJsonParts(canonicalJsonParts(checked)), path, overwrite, resources, signal === undefined
         ? undefined
         : { signal, operation: "export_evidence_bundle" });
 };

package/dist/application/FunctionAnalysisEvidence.js

@@ -24,6 +24,9 @@ export const executeFunctionAnalysisEvidence = async (analysis, parameters, targ
         rawResult: observation.rawResult,
         limitations: observation.limitations,
         locations: observation.locations,
+        ...(observation.relationshipCoverage === undefined
+            ? {}
+            : { relationshipCoverage: observation.relationshipCoverage }),
         ...(observation.analysisProfile === undefined
             ? {}
             : { analysisProfile: observation.analysisProfile }),

package/dist/application/GeminiClientSettings.js

@@ -0,0 +1,151 @@
+import { realpath, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { stripComments } from "jsonc-parser";
+import { z } from "zod";
+import { err, ok } from "../domain/result.js";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { npxRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { clientConfigurationValuesEqual, clientRegistrationEntry, geminiServerPolicyBlock, parseGeminiMcpPolicy, } from "./ClientConfigurationDocument.js";
+import { readConfigurationFile, readConfigurationText, } from "./ClientConfigurationFiles.js";
+const folderTrustSchema = z
+    .object({
+    security: z
+        .object({
+        folderTrust: z
+            .object({ enabled: z.boolean().optional() })
+            .passthrough()
+            .optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+const trustRulesSchema = z.record(z.string(), z.enum(["TRUST_FOLDER", "TRUST_PARENT", "DO_NOT_TRUST"]));
+const sourceFailure = (path, cause) => ({
+    kind: "malformed",
+    path,
+    detail: `Gemini settings in ${path} are malformed: ${cause instanceof Error ? cause.message : String(cause)}`,
+});
+// Gemini resolves symlinks when possible and compares macOS/Windows paths without case.
+const normalizedPath = async (path, platform) => {
+    const physical = await realpath(path).catch(() => path);
+    const absolute = resolve(physical).replaceAll("\\", "/");
+    return platform === "win32" || platform === "darwin"
+        ? absolute.toLowerCase()
+        : absolute;
+};
+const workspaceTrusted = async (settings, sources, resources) => {
+    let enabled = true;
+    for (const { path, document } of sources) {
+        const parsed = folderTrustSchema.safeParse(document.document);
+        if (!parsed.success)
+            return err(sourceFailure(path, parsed.error));
+        enabled = parsed.data.security?.folderTrust?.enabled ?? enabled;
+    }
+    if (settings.trustOverride !== undefined)
+        return ok(settings.trustOverride);
+    if (!enabled)
+        return ok(true);
+    const text = await readConfigurationText(settings.trustedFoldersPath, resources);
+    if (!text.ok)
+        return text;
+    if (text.value === undefined)
+        return ok(false);
+    let rules;
+    try {
+        // Gemini strips comments, but rejects trailing commas, BOMs and invalid trust levels.
+        rules = trustRulesSchema.parse(JSON.parse(stripComments(text.value)));
+    }
+    catch (cause) {
+        return err(sourceFailure(settings.trustedFoldersPath, cause));
+    }
+    const workspace = await normalizedPath(settings.workspaceDirectory, settings.platform);
+    let longest = -1;
+    let trusted = false;
+    for (const [path, level] of Object.entries(rules)) {
+        const effective = await normalizedPath(level === "TRUST_PARENT" ? dirname(path) : path, settings.platform);
+        if ((workspace === effective ||
+            workspace.startsWith(effective.endsWith("/") ? effective : `${effective}/`)) &&
+            path.length > longest) {
+            longest = path.length;
+            trusted = level !== "DO_NOT_TRUST";
+        }
+    }
+    return ok(trusted);
+};
+/** Check effective Gemini scopes while preserving their authority and source identity. */
+export const readClientPolicyBlock = async (client, userDocument, desiredRegistration, resources) => {
+    if (client.name !== "gemini_cli" || client.geminiSettings === undefined)
+        return ok(undefined);
+    const settings = client.geminiSettings;
+    const sources = [];
+    const higher = [];
+    for (const path of [
+        settings.defaultsPath,
+        client.configPath,
+        settings.systemPath,
+    ]) {
+        const parsed = path === client.configPath && userDocument !== undefined
+            ? ok(userDocument)
+            : await readConfigurationFile(path, "json", resources);
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value !== undefined)
+            sources.push({ path, document: parsed.value });
+    }
+    const workspace = await normalizedPath(settings.workspaceDirectory, settings.platform);
+    const home = await normalizedPath(dirname(dirname(client.configPath)), settings.platform);
+    if (workspace !== home) {
+        const path = resolve(settings.workspaceDirectory, ".gemini", "settings.json");
+        // Only ENOENT proves absence; preserve other metadata failures as unreadable.
+        const present = await stat(path).then(() => ok(true), (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT"
+            ? ok(false)
+            : err({
+                kind: "unreadable",
+                path,
+                detail: `Configuration ${path} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`,
+            }));
+        if (!present.ok)
+            return present;
+        const includeWorkspace = present.value
+            ? await workspaceTrusted(settings, sources, resources)
+            : ok(false);
+        if (!includeWorkspace.ok)
+            return includeWorkspace;
+        if (includeWorkspace.value) {
+            const document = await readConfigurationFile(path, "json", resources);
+            if (!document.ok)
+                return document;
+            if (document.value !== undefined) {
+                const source = { path, document: document.value };
+                const systemIndex = sources.findIndex((item) => item.path === settings.systemPath);
+                sources.splice(systemIndex < 0 ? sources.length : systemIndex, 0, source);
+                higher.push(source);
+            }
+        }
+    }
+    const system = sources.find(({ path }) => path === settings.systemPath);
+    if (system !== undefined)
+        higher.push(system);
+    const policies = [];
+    for (const { path, document } of sources) {
+        try {
+            policies.push(parseGeminiMcpPolicy(document));
+        }
+        catch (cause) {
+            return err(sourceFailure(path, cause));
+        }
+    }
+    const policy = geminiServerPolicyBlock(policies, PRODUCT_IDENTITY.mcpServerKey);
+    if (policy !== undefined)
+        return ok(`${policy} Settings sources: ${sources.map(({ path }) => path).join(", ")}.`);
+    // mcpServers uses shallow merge: the entire same-name definition is replaced.
+    const override = higher.findLast(({ document }) => Object.hasOwn(document.servers, PRODUCT_IDENTITY.mcpServerKey));
+    const desired = desiredRegistration ??
+        userDocument?.servers[PRODUCT_IDENTITY.mcpServerKey] ??
+        clientRegistrationEntry("json", npxRegistrationCommand(), {});
+    if (override !== undefined &&
+        !clientConfigurationValuesEqual(override.document.servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return ok(`Gemini mcpServers.${PRODUCT_IDENTITY.mcpServerKey} in ${override.path} overrides the user registration. Review that settings file before rerunning setup; REA does not modify system or workspace settings.`);
+    return ok(undefined);
+};