rea-agents 1.4.0 → 1.6.0

package/dist/application/ProcessSampling.js

@@ -1,8 +1,19 @@
 import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { promisify } from "node:util";
+import { readProcessRunId } from "./ProcessOwnership.js";
 const execFileAsync = promisify(execFile);
 const PROC_READ_CONCURRENCY = 64;
+/** Prove that forkpty completed session setup and installed the run token. */
+export const isInitializedPtyRoot = (options) => options.before.pid === options.rootPid &&
+    options.before.process_group_id === options.rootPid &&
+    options.before.session_id === options.rootPid &&
+    options.after.pid === options.rootPid &&
+    options.after.parent_pid === options.before.parent_pid &&
+    options.after.process_group_id === options.rootPid &&
+    options.after.session_id === options.rootPid &&
+    options.after.startTime === options.before.startTime &&
+    options.observedRunId === options.expectedRunId;
 const isExpectedProcReadFailure = (cause) => cause instanceof Error &&
     "code" in cause &&
     (cause.code === "ENOENT" ||
@@ -67,23 +78,58 @@ const readProcessCommand = async (pid, signal) => {
         return handleProcReadFailure(cause);
     }
 };
-const readLinuxChildren = async (pid, signal) => {
-    let text;
-    try {
-        text = await readFile(`/proc/${String(pid)}/task/${String(pid)}/children`, {
-            encoding: "utf8",
-            signal,
-        });
-    }
-    catch (cause) {
-        return handleProcReadFailure(cause);
+const systemLinuxChildrenHost = {
+    async taskIds(pid, signal) {
+        try {
+            signal.throwIfAborted();
+            const entries = await readdir(`/proc/${String(pid)}/task`);
+            signal.throwIfAborted();
+            return entries
+                .filter((entry) => /^\d+$/.test(entry))
+                .map(Number)
+                .filter((taskId) => Number.isSafeInteger(taskId) && taskId > 0)
+                .sort((left, right) => left - right);
+        }
+        catch (cause) {
+            return handleProcReadFailure(cause);
+        }
+    },
+    async children(pid, taskId, signal) {
+        try {
+            return await readFile(`/proc/${String(pid)}/task/${String(taskId)}/children`, { encoding: "utf8", signal });
+        }
+        catch (cause) {
+            return handleProcReadFailure(cause);
+        }
+    },
+};
+/** Read the deduplicated children created by every thread in a Linux process. */
+export const readLinuxChildren = async (pid, signal, host = systemLinuxChildrenHost) => {
+    const taskIds = await host.taskIds(pid, signal);
+    if (taskIds === undefined)
+        return undefined;
+    const children = new Set();
+    let successfulReads = 0;
+    for (let offset = 0; offset < taskIds.length; offset += PROC_READ_CONCURRENCY) {
+        const texts = await Promise.all(taskIds
+            .slice(offset, offset + PROC_READ_CONCURRENCY)
+            .map((taskId) => host.children(pid, taskId, signal)));
+        for (const text of texts) {
+            if (text === undefined)
+                continue;
+            successfulReads += 1;
+            for (const value of text.trim().split(/\s+/)) {
+                if (!/^\d+$/.test(value))
+                    continue;
+                const child = Number(value);
+                if (Number.isSafeInteger(child) && child > 0)
+                    children.add(child);
+            }
+        }
     }
-    return text
-        .trim()
-        .split(/\s+/)
-        .filter((value) => /^\d+$/.test(value))
-        .map(Number)
-        .filter((child) => Number.isSafeInteger(child) && child > 0);
+    return successfulReads === 0
+        ? undefined
+        : [...children].sort((left, right) => left - right);
 };
 const inspectProcess = async (pid, expectedParent, signal, identities) => {
     const before = await readProcessStat(pid, signal);
@@ -179,6 +225,34 @@ const readPsRows = async (signal) => {
         row.parent_pid >= 0)
         .sort((left, right) => left.pid - right.pid);
 };
+const readRootIdentity = async (rootPid, signal) => process.platform === "linux"
+    ? readProcessStat(rootPid, signal)
+    : (await readPsRows(signal)).find(({ pid }) => pid === rootPid);
+const inspectInitializedPtyRoot = async (rootPid, runId, signal) => {
+    const before = await readRootIdentity(rootPid, signal);
+    if (before === undefined ||
+        before.process_group_id !== rootPid ||
+        before.session_id !== rootPid)
+        return undefined;
+    let observedRunId;
+    try {
+        observedRunId = await readProcessRunId(rootPid);
+    }
+    catch {
+        return undefined;
+    }
+    const after = await readRootIdentity(rootPid, signal);
+    if (after === undefined ||
+        !isInitializedPtyRoot({
+            rootPid,
+            expectedRunId: runId,
+            before,
+            observedRunId,
+            after,
+        }))
+        return undefined;
+    return { startTime: after.startTime };
+};
 const samplePs = async (context) => {
     const { rootPid, limit, signal } = context;
     if (limit <= 0)
@@ -242,25 +316,37 @@ const sampleProcesses = async (context) => {
     return samples;
 };
 /** Start bounded process-tree sampling and expose an awaited stop. */
-export const startProcessSampler = (rootPid, started, limit, samples) => {
+export const startProcessSampler = (options) => {
+    const { rootPid, runId, started, limit, samples } = options;
     const identities = new Map();
     const lastObservations = new Map();
     let pending;
     let stopped = false;
     let abortCurrent;
     let partial = false;
+    let rootInitialized = false;
     const sample = () => {
         if (stopped || pending !== undefined)
             return;
         const controller = new AbortController();
         abortCurrent = () => controller.abort();
-        pending = sampleProcesses({
-            rootPid,
-            elapsedMs: Date.now() - started,
-            limit: limit + 1,
-            identities,
-            signal: controller.signal,
-        })
+        pending = (async () => {
+            if (!rootInitialized) {
+                const identity = await inspectInitializedPtyRoot(rootPid, runId, controller.signal);
+                if (identity === undefined)
+                    return [];
+                if (identity.startTime !== undefined)
+                    identities.set(rootPid, identity.startTime);
+                rootInitialized = true;
+            }
+            return sampleProcesses({
+                rootPid,
+                elapsedMs: Date.now() - started,
+                limit: limit + 1,
+                identities,
+                signal: controller.signal,
+            });
+        })()
             .then((values) => {
             for (const value of values) {
                 const observation = JSON.stringify({

package/dist/application/ProjectPermissionStore.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, realpath, stat, unlink, } from "node:fs/promises";
 import { dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { err, ok } from "../domain/result.js";
@@ -8,6 +9,8 @@ const grantSchema = z.object({
     grant_id: z.string().min(1),
     capability: z.enum([
         "process_capture",
+        "browser_observe",
+        "electron_observe",
         "evidence_read",
         "evidence_write",
         "investigation_input",
@@ -22,6 +25,7 @@ const grantSchema = z.object({
     roots: z.array(z.string()),
     executables: z.array(z.string()),
     environment_names: z.array(z.string()),
+    origins: z.array(z.string()).optional(),
     network: z.enum(["none", "loopback", "external"]),
     mount: z.boolean(),
     lifetime: z.literal("project"),
@@ -65,7 +69,15 @@ export const readProjectPermissionStore = async (path, projectRoot) => {
         const metadata = await stat(path);
         if ((metadata.mode & 0o077) !== 0)
             return err(new ProjectPermissionStoreError("not_owner_only"));
-        const parsed = storeSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+        const encoded = await readFile(path, "utf8");
+        let decoded;
+        try {
+            decoded = JSON.parse(encoded);
+        }
+        catch (cause) {
+            return err(new ProjectPermissionStoreError("invalid", { cause }));
+        }
+        const parsed = storeSchema.safeParse(decoded);
         if (!parsed.success ||
             parsed.data.project_id !== project.value.id ||
             parsed.data.project_root !== project.value.root)
@@ -107,4 +119,96 @@ export const writeProjectPermissionStore = async (path, projectRoot, grants) =>
         return err(new ProjectPermissionStoreError("io", { cause }));
     }
 };
-const isNotFound = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+/** Revoke one grant while serializing the complete read-modify-write cycle. */
+export const revokeProjectPermissionGrant = async (path, projectRoot, grantId) => {
+    let lock;
+    try {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const acquired = await acquirePermissionStoreLock(path);
+        if (!acquired.ok)
+            return acquired;
+        lock = acquired.value;
+        const current = await readProjectPermissionStore(path, projectRoot);
+        if (!current.ok)
+            return current;
+        const grants = current.value?.grants ?? [];
+        const retained = grants.filter(({ grant_id }) => grant_id !== grantId);
+        if (retained.length === grants.length)
+            return ok(false);
+        const written = await writeProjectPermissionStore(path, projectRoot, retained);
+        return written.ok ? ok(true) : written;
+    }
+    catch (cause) {
+        return err(new ProjectPermissionStoreError("io", { cause }));
+    }
+    finally {
+        if (lock !== undefined)
+            await releasePermissionStoreLock(lock);
+    }
+};
+const acquirePermissionStoreLock = async (destination) => {
+    const path = `${destination}.lock`;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            return ok(await createPermissionStoreLock(path));
+        }
+        catch (cause) {
+            if (!isAlreadyExists(cause))
+                return err(new ProjectPermissionStoreError("io", { cause }));
+            if (await removeStalePermissionStoreLock(path))
+                continue;
+            if (attempt === 99)
+                return err(new ProjectPermissionStoreError("locked", { cause }));
+            await delay(10);
+        }
+    }
+    return err(new ProjectPermissionStoreError("locked"));
+};
+const createPermissionStoreLock = async (path) => {
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(`${String(process.pid)}\n`, "utf8");
+        await handle.sync();
+        return { path, handle };
+    }
+    catch (cause) {
+        await handle.close().catch(() => undefined);
+        await unlink(path).catch(() => undefined);
+        throw cause;
+    }
+};
+const removeStalePermissionStoreLock = async (path) => {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > 32)
+            return false;
+        const encoded = (await readFile(path, "utf8")).trim();
+        if (!/^[1-9][0-9]{0,9}$/u.test(encoded))
+            return false;
+        if (processIsAlive(Number(encoded)))
+            return false;
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const processIsAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        return errorCode(cause) !== "ESRCH";
+    }
+};
+const releasePermissionStoreLock = async (lock) => {
+    await lock.handle.close().catch(() => undefined);
+    await unlink(lock.path).catch(() => undefined);
+};
+const isNotFound = (cause) => errorCode(cause) === "ENOENT";
+const isAlreadyExists = (cause) => errorCode(cause) === "EEXIST";
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? cause.code
+    : undefined;

package/dist/application/ReferenceSourceImport.js

@@ -1,5 +1,5 @@
 import { isSecretLikePath } from "../domain/referenceSourceClassification.js";
-import { createHistoricalSourceGraph, } from "../domain/referenceSourceGraph.js";
+import { createHistoricalSourceGraph, historicalSourceParseFailureKey, } from "../domain/referenceSourceGraph.js";
 import { err, ok } from "../domain/result.js";
 import { readReferenceSource } from "../reference/ReferenceSourceReader.js";
 import { parseReferenceSourceEntries } from "./ReferenceSourceImportEntries.js";
@@ -38,6 +38,17 @@ const deduplicateRelationships = (relationships) => {
     }
     return result;
 };
+/** Sort parse failures deterministically while retaining distinct reasons. */
+export const normalizeHistoricalSourceParseFailures = (failures) => [...failures]
+    .sort((left, right) => byCodePoint(historicalSourceParseFailureKey(left), historicalSourceParseFailureKey(right)))
+    .filter((value, index, array) => {
+    if (index === 0)
+        return true;
+    const previous = array[index - 1];
+    return (previous === undefined ||
+        historicalSourceParseFailureKey(value) !==
+            historicalSourceParseFailureKey(previous));
+});
 const buildProvenance = (options) => ({
     importer: options.importer ?? "rea-reference-source-import",
     importer_version: options.importerVersion ?? null,
@@ -134,21 +145,7 @@ export const importReferenceSource = async (options) => {
     if (isAborted(options.signal))
         return err(cancelled());
     const uniqueRelationships = deduplicateRelationships(relationships);
-    const uniqueFailures = [...parseFailures]
-        .sort((left, right) => {
-        const byPath = byCodePoint(left.path, right.path);
-        if (byPath !== 0)
-            return byPath;
-        return byCodePoint(left.parser, right.parser);
-    })
-        .filter((value, index, array) => {
-        if (index === 0)
-            return true;
-        const previous = array[index - 1];
-        if (previous === undefined)
-            return true;
-        return value.path !== previous.path || value.parser !== previous.parser;
-    });
+    const uniqueFailures = normalizeHistoricalSourceParseFailures(parseFailures);
     const sortedEntries = [...entries].sort((left, right) => byCodePoint(left.path, right.path));
     const sortedExclusions = sortAndLimit(exclusions, limits.maxEntries);
     const sortedLimitations = [...limitations].sort(byCodePoint);

package/dist/application/ReferenceSourceImportPolicy.js

@@ -4,6 +4,7 @@ import ignore from "ignore";
 import { err, ok } from "../domain/result.js";
 import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, DEFAULT_REFERENCE_SOURCE_LIMITS, } from "./ReferenceSourceImportTypes.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 const failure = (code, message) => ({
     tag: "reference-source-import",
     code,
@@ -29,8 +30,8 @@ const authorizeRoot = async (requestedRoot, approvedRoots) => {
         if (!(await stat(requestedRoot)).isDirectory())
             return err(failure("invalid-root", "Reference source root is not a directory"));
         const canonicalRoot = await realpath(resolve(requestedRoot));
-        for (const approvedRoot of approvedRoots) {
-            const canonicalApproved = await realpath(resolve(approvedRoot));
+        const canonicalApprovedRoots = await canonicalizeConfiguredRoots(approvedRoots.map((approvedRoot) => resolve(approvedRoot)));
+        for (const canonicalApproved of canonicalApprovedRoots) {
             if (withinRoot(canonicalApproved, canonicalRoot))
                 return ok(canonicalRoot);
         }

package/dist/application/Setup.js

@@ -1,4 +1,4 @@
-import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { z } from "zod";
@@ -6,15 +6,16 @@ import writeFileAtomic from "write-file-atomic";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportsNodeVersion } from "../domain/runtimeVersion.js";
+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 import { installMacHopper } from "./MacHopper.js";
 import { configureDetectedClients } from "./SetupClients.js";
 import { supportedClients } from "./SupportedClients.js";
-import { installCanonicalSkill } from "./SetupSkill.js";
+import { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
 import { setupPlan } from "./SetupPlan.js";
 import { setupInstallFailure, } from "./SetupInstallFailure.js";
-export { installCanonicalSkill } from "./SetupSkill.js";
+export { canonicalSkillNeedsInstall, installCanonicalSkill, } from "./SetupSkill.js";
 const registrationCommand = () => process.env.npm_command === "exec"
     ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
     : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
@@ -39,14 +40,10 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     if (unsupported !== undefined)
         return fail(unsupported);
     let hopperPath = await host.hopperPath();
-    const initialDoctor = await host.doctor();
-    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
-        (name === "hopper-demo-runtime" ||
-            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
-    const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
-    const detectedClients = await host.detectedClients();
-    plannedActions = setupPlan(host.platform, installHopper, detectedClients);
-    let approved = options.approved;
+    const discovery = await discoverSetupActions(host, hopperPath);
+    const { detectedClients, installHopper, installSkill } = discovery;
+    plannedActions = discovery.plannedActions;
+    let approved = options.approved || plannedActions.length === 0;
     let interactiveApproval = false;
     if (!approved && confirm !== undefined && !options.structured) {
         interactiveApproval = await confirm(plannedActions);
@@ -86,11 +83,13 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
     });
     if (clientFailure !== undefined)
         return fail(clientFailure);
-    const skill = await host.installSkill();
-    if (skill === "failed")
-        return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
-    if (skill === "installed")
-        appliedActions.push("installed_skill");
+    if (installSkill) {
+        const skill = await host.installSkill();
+        if (skill === "failed")
+            return fail("REA analysis skill could not be installed or verified. Check permissions for `~/.agents/skills`, then rerun setup.");
+        if (skill === "installed")
+            appliedActions.push("installed_skill");
+    }
     const doctor = await host.doctor();
     const remediation = finalSetupRemediation(host.platform, appliedActions.includes("installed_hopper"), doctor.healthy, hopperPath);
     return {
@@ -102,6 +101,32 @@ export const runSetup = async (options, host = systemSetupHost(), confirm) => {
         ...(remediation === undefined ? {} : { remediation }),
     };
 };
+const discoverSetupActions = async (host, hopperPath) => {
+    const initialDoctor = await host.doctor();
+    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+        (name === "hopper-demo-runtime" ||
+            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const installHopper = hopperPath === undefined || linuxHopperRepairNeeded;
+    const [detectedClients, installSkill] = await Promise.all([
+        host.detectedClients(),
+        host.skillNeedsInstall(),
+    ]);
+    const command = registrationCommand();
+    const clients = installHopper
+        ? detectedClients
+        : await filterClientsNeedingConfigure(host, detectedClients, hopperPath, command);
+    const plannedActions = setupPlan(host.platform, installHopper, installSkill, clients);
+    return {
+        installHopper,
+        installSkill,
+        detectedClients: clients,
+        plannedActions,
+    };
+};
+const filterClientsNeedingConfigure = async (host, detectedClients, hopperPath, command) => {
+    const needs = await Promise.all(detectedClients.map((client) => host.clientNeedsConfigure(client, hopperPath, command)));
+    return detectedClients.filter((_, index) => needs[index]);
+};
 const finalSetupRemediation = (platform, installedHopper, healthy, hopperPath) => {
     if (platform === "darwin" && installedHopper)
         return "Open Hopper, choose its demo mode or activate a license, then rerun rea doctor --json.";
@@ -149,6 +174,8 @@ const systemSetupHost = () => {
             : client.format === "toml"
                 ? configureTomlClient(client, hopperPath, command)
                 : configureJsonClient(client, hopperPath, command),
+        clientNeedsConfigure: (client, hopperPath, command) => clientConfigurationAligned(client, hopperPath, command).then((aligned) => !aligned),
+        skillNeedsInstall: () => canonicalSkillNeedsInstall(homedir()),
         installSkill: () => installCanonicalSkill(homedir()),
         doctor: () => runDoctor(undefined, doctorHost),
     };
@@ -168,10 +195,13 @@ export const configureJsonClient = async (client, hopperPath, command = [
     PRODUCT_IDENTITY.packageName,
     "mcp",
 ]) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
     let document = {};
     let original;
     try {
-        original = await readFile(client.configPath, "utf8");
+        original = await readFile(transactionPath, "utf8");
         document = parseObject(original);
     }
     catch (cause) {
@@ -199,7 +229,7 @@ export const configureJsonClient = async (client, hopperPath, command = [
     if (original !== undefined) {
         backupPath = `${client.configPath}.rea.backup`;
         try {
-            await copyFile(client.configPath, backupPath);
+            await copyFile(transactionPath, backupPath);
         }
         catch {
             return { status: "failed", reason: "backup" };
@@ -210,26 +240,26 @@ export const configureJsonClient = async (client, hopperPath, command = [
         [PRODUCT_IDENTITY.mcpServerKey]: desired,
     };
     const encoded = `${JSON.stringify(document, null, 2)}\n`;
-    const temporary = `${client.configPath}.rea.tmp`;
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFile(temporary, encoded, { encoding: "utf8", mode: 0o600 });
-        await rename(temporary, client.configPath);
+        await writeFileAtomic(transactionPath, encoded, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
     }
     catch {
-        await rm(temporary, { force: true }).catch(() => undefined);
         return { status: "failed", reason: "write" };
     }
     try {
-        const readback = parseObject(await readFile(client.configPath, "utf8"));
+        const readback = parseObject(await readFile(transactionPath, "utf8"));
         const value = parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey];
         if (JSON.stringify(value) !== JSON.stringify(desired)) {
-            await restoreConfig(client.configPath, original);
+            await restoreConfig(transactionPath, original);
             return { status: "failed", reason: "readback" };
         }
     }
     catch {
-        await restoreConfig(client.configPath, original);
+        await restoreConfig(transactionPath, original);
         return { status: "failed", reason: "readback" };
     }
     return {
@@ -244,10 +274,13 @@ export const configureTomlClient = async (client, hopperPath, command = [
     PRODUCT_IDENTITY.packageName,
     "mcp",
 ]) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
     let document = {};
     let original;
     try {
-        original = await readFile(client.configPath, "utf8");
+        original = await readFile(transactionPath, "utf8");
         document = objectSchema.parse(parseToml(original));
     }
     catch (cause) {
@@ -274,7 +307,7 @@ export const configureTomlClient = async (client, hopperPath, command = [
     const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
     try {
         if (backupPath !== undefined)
-            await copyFile(client.configPath, backupPath);
+            await copyFile(transactionPath, backupPath);
     }
     catch {
         return { status: "failed", reason: "backup" };
@@ -285,16 +318,16 @@ export const configureTomlClient = async (client, hopperPath, command = [
     };
     try {
         await mkdir(dirname(client.configPath), { recursive: true });
-        await writeFileAtomic(client.configPath, stringifyToml(document), {
+        await writeFileAtomic(transactionPath, stringifyToml(document), {
             encoding: "utf8",
             mode: 0o600,
         });
-        const readback = objectSchema.parse(parseToml(await readFile(client.configPath, "utf8")));
+        const readback = objectSchema.parse(parseToml(await readFile(transactionPath, "utf8")));
         if (JSON.stringify(parseOptionalObject(readback.mcp_servers)[PRODUCT_IDENTITY.mcpServerKey]) !== JSON.stringify(desired))
             throw new Error("TOML readback mismatch");
     }
     catch {
-        await restoreConfig(client.configPath, original);
+        await restoreConfig(transactionPath, original);
         return { status: "failed", reason: "readback" };
     }
     return {
@@ -327,3 +360,29 @@ const restoreConfig = async (path, original) => {
         // The backup remains available for the remediation reported by setup.
     }
 };
+const clientConfigurationDesired = (hopperPath, command) => ({
+    command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+    args: command.slice(1),
+    ...(hopperPath === undefined
+        ? {}
+        : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
+});
+const clientConfigurationAligned = async (client, hopperPath, command) => {
+    const desired = clientConfigurationDesired(hopperPath, command);
+    try {
+        const original = await readFile(client.configPath, "utf8");
+        if (client.format === "toml") {
+            const document = objectSchema.parse(parseToml(original));
+            const servers = parseOptionalObject(document.mcp_servers);
+            return (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
+                JSON.stringify(desired));
+        }
+        const document = parseObject(original);
+        const servers = parseOptionalObject(document.mcpServers);
+        return (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
+            JSON.stringify(desired));
+    }
+    catch {
+        return false;
+    }
+};

package/dist/application/SetupClients.js

@@ -1,19 +1,22 @@
 const failedConfigurationMessage = (reason) => {
+    if (reason === "path")
+        return "Agent configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun setup.";
     if (reason === "backup")
         return "Agent configuration could not be backed up, so no change was made. Check file permissions, then rerun setup.";
     if (reason === "write")
         return "Agent configuration could not be updated. Check file permissions, then rerun setup.";
     return "Agent configuration could not be verified after writing. Repair the configuration file or restore its `.rea.backup`, then rerun setup.";
 };
-/** Configure each detected agent, stopping after the first failed transaction. */
+/** Configure every detected agent and report the first failed transaction. */
 export const configureDetectedClients = async (options) => {
+    let failure;
     for (const client of options.detectedClients) {
         const result = await options.host.configureClient(client, options.hopperPath, options.command);
         options.clients[client.name] = result;
         if (result.status === "failed")
-            return failedConfigurationMessage(result.reason);
-        if (result.status === "configured")
+            failure ??= failedConfigurationMessage(result.reason);
+        else if (result.status === "configured")
             options.appliedActions.push(`configured_${client.name}`);
     }
-    return undefined;
+    return failure;
 };