docs(installation): limit REA to one project or agent profile

Document existing Claude Code profile and per-project installation workflows, including scoped maintenance, backups, caller metadata and Windows commands. Clarify authentication storage and the filesystem/network restrictions required for enforced separation.

Validated 68 boundary tests, docs checks, formatting, typecheck/lint and two real REA setup dry-runs with zero applied actions or profile writes. Native Claude sessions, PowerShell execution and enforcement policies were not tested. Setup automation remains separate in #2187.

Co-authored-by: William Blair <60581672+williamblair333@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

docs/client-configuration.md

@@ -294,7 +294,11 @@ the first native server into an empty table, it copies the fallback's
 `mcpServers` entries into the native table so they keep loading, and leaves
 the fallback file untouched. Existing REA environment overrides are preserved
 when refreshing its command. A malformed or unreadable fallback file fails setup instead of
-being silently suppressed; repair or remove it and rerun. ZCode disables a
+being silently suppressed; repair or remove it and rerun. Uninstall removes an
+REA-owned `rea` entry from both the native table and the fallback, backing up
+each changed file, so an emptied native table cannot load a leftover fallback
+registration; other fallback servers, settings and a foreign `rea` entry are
+kept. ZCode disables a
 server with `enable: false` on its entry; doctor reports such a registration
 as stale, and rerunning setup removes the flag to repair it. Native configuration
 uses strict JSON; setup refuses comments, trailing commas and a BOM rather than

docs/installation.md

@@ -129,6 +129,150 @@ Setup pins package-runner MCP registrations to the exact installed REA version,
 installs the matching skill and on-demand references in the same plan, and adds
 `startup_timeout_sec = 30` for Codex and Grok Build.
 
+## Limit REA to one project or agent profile
+
+Setup registers REA for the whole client. For Claude Code it writes
+`mcpServers.rea` in `~/.claude.json` and installs the bundled skill under
+`~/.claude/skills`, so every project that Claude Code opens can call REA. To
+offer REA's tools only where they're wanted, use one of the routes below.
+
+Both routes control which sessions discover REA's MCP server and skill. They
+leave shell commands, filesystem access and network access available. An agent
+under the same OS account can run `rea` from `PATH` or `npx` and read other
+profiles and REA output. For clean-room separation, use an implementation
+environment with filesystem and network restrictions that prevent reading or
+fetching REA, the target and analysis output, including through shared
+installations and package registries. A separate account or container must
+enforce those restrictions.
+
+For Claude Code, check existing default-profile state before choosing either
+route. Setup is additive: a previous user-level REA registration and personal
+skill remain active in other projects. Back up the default configuration and
+REA skill first, then, with `CLAUDE_CONFIG_DIR` unset, remove the REA user
+registration with `claude mcp remove --scope user rea` and remove the known
+REA-installed `~/.claude/skills/reverse-engineer-anything` directory. Preserve
+unrelated registrations and skills. `rea uninstall` applies to other clients
+as well, so it is broader than this Claude-only migration.
+
+**A separate Claude Code profile.** Claude Code keeps settings, skills and session
+history under `CLAUDE_CONFIG_DIR`. Setup follows the same
+variable: it writes the registration to `$CLAUDE_CONFIG_DIR/.claude.json` and
+the skill to `$CLAUDE_CONFIG_DIR/skills`.
+
+```bash
+CLAUDE_CONFIG_DIR=~/.claude-rea npx rea-agents setup --client claude_code
+CLAUDE_CONFIG_DIR=~/.claude-rea claude
+```
+
+A new profile may need authentication. Console sign-ins without an API key are
+stored outside `CLAUDE_CONFIG_DIR`; see
+[Claude Code authentication](https://code.claude.com/docs/en/authentication#log-in-with-multiple-accounts).
+Sessions started without the variable use the default profile's registration,
+skill and history.
+
+Inline assignments apply only to that command. Keep the same prefix for every
+profile check, setup rerun, update, or removal; bare commands use the current
+environment and can otherwise inspect or recreate default-profile state:
+
+```bash
+CLAUDE_CONFIG_DIR=~/.claude-rea claude mcp list
+CLAUDE_CONFIG_DIR=~/.claude-rea npx rea-agents doctor --client claude_code --skill --json
+CLAUDE_CONFIG_DIR=~/.claude-rea npx -y rea-agents@latest setup --client claude_code --dry-run
+```
+
+After reviewing an update plan, rerun that same prefixed setup command without
+`--dry-run` and approve its exact changes. Profile removal likewise needs the
+prefix on `claude mcp remove --scope user rea` and any `rea uninstall` command;
+keep the broader client scope of uninstall in mind. Restart the selected
+profile after changing its pinned registration.
+
+`claude mcp remove` removes only the registration. To remove REA from this
+profile without running the broader uninstall flow, first back up the profile's
+REA-managed skill directory, then remove
+`$CLAUDE_CONFIG_DIR/skills/reverse-engineer-anything` as well. Keep other skills
+in the profile intact.
+
+The commands above use POSIX shell assignment syntax. In native Windows
+PowerShell, select the profile for the whole setup/launch/check session and
+restore the previous selection afterward:
+
+```powershell
+$previousClaudeConfigDir = $env:CLAUDE_CONFIG_DIR
+try {
+  $env:CLAUDE_CONFIG_DIR = Join-Path $HOME ".claude-rea"
+  npx rea-agents setup --client claude_code
+  claude mcp list
+  npx rea-agents doctor --client claude_code --skill --json
+  npx -y rea-agents@latest setup --client claude_code --dry-run
+  # After reviewing the plan, repeat setup without --dry-run and approve it.
+  claude
+  # Profile removal, when intended, also belongs inside this selected scope:
+  # claude mcp remove --scope user rea
+} finally {
+  if ($null -eq $previousClaudeConfigDir) {
+    Remove-Item Env:CLAUDE_CONFIG_DIR -ErrorAction SilentlyContinue
+  } else {
+    $env:CLAUDE_CONFIG_DIR = $previousClaudeConfigDir
+  }
+}
+```
+
+Use PowerShell for these Windows examples rather than pasting POSIX assignments
+into cmd.exe. Keep profile updates, readiness checks and removal inside the
+same selected environment; the `finally` block restores the previous profile
+or unsets the variable when it was absent.
+
+**One project.** Install without configuring Claude Code: use the curl
+installer's `--no-setup`, or run setup only for other clients. Then register
+REA from the project directory at Claude Code's local scope.
+
+This route uses the default Claude profile. Keep `CLAUDE_CONFIG_DIR` unset for
+the entire local lifecycle: registration, backup, listing, version replacement
+and removal. In POSIX shells run `unset CLAUDE_CONFIG_DIR`; in PowerShell run
+`Remove-Item Env:CLAUDE_CONFIG_DIR -ErrorAction SilentlyContinue` before these
+commands. Record an existing selection first if you intend to restore it after
+finishing. The configuration path below is the default profile's
+`~/.claude.json`; a different active profile uses its own config root instead.
+
+Register with the variable unset:
+
+<!-- x-release-please-start-version -->
+
+```bash
+claude mcp add --scope local rea -- npx -y rea-agents@6.4.0 mcp
+```
+
+On native Windows, use the same project directory and wrap the package-runner
+shim so the stdio client can launch it:
+
+```powershell
+claude mcp add --scope local rea -- cmd.exe /d /c npx -y rea-agents@6.4.0 mcp
+```
+
+<!-- x-release-please-end -->
+
+Local scope stores the entry under that directory's path in `~/.claude.json`,
+so other projects don't load it. This route doesn't install the bundled skill.
+Avoid `--scope project`, which writes `.mcp.json` into the repository where it
+can be committed or copied. `rea doctor` and `rea uninstall` read only the
+user-level entry, so they don't report or remove a local-scope registration;
+remove it with `claude mcp remove --scope local rea` from the same directory.
+`rea update` doesn't refresh it either, so it stays on the version it names.
+To move it to a newer release, first back up the project entry in
+`~/.claude.json` and record its environment and other metadata. In particular,
+preserve caller-selected overrides such as `REA_MCP_INPUT_SCHEMA_PROFILE` and
+`REA_MCP_MAX_RESPONSE_BYTES`. Run `claude mcp remove --scope local rea` from the
+same directory, then recreate it with the platform-appropriate command above
+and the new version. Reapply every recorded environment value with Claude
+Code's `mcp add --env NAME=value` options and restore any other retained entry
+metadata before restarting the project session. Removal and re-addition do not
+preserve these values automatically. Running setup for Claude Code instead
+would add a user-level entry for every project.
+
+Check the separate profile with the prefixed `claude mcp list` above and compare
+with the default profile with `CLAUDE_CONFIG_DIR` unset. For local scope, run
+`claude mcp list` from the selected project and again from another project.
+
 ## Check readiness for your task
 
 Run `rea doctor` when you need diagnosis. It reads host prerequisites and agent

scripts/verify-windows-native-inspection.mjs

@@ -1,11 +1,12 @@
 import assert from "node:assert/strict";
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import {
+  access,
   copyFile,
   mkdir,
   mkdtemp,
+  readFile,
   readdir,
-  rmdir,
   rm,
   stat,
   symlink,
@@ -54,7 +55,7 @@ try {
     join(workspace, "dist", "windows", "WindowsNativeLoader.js"),
   ).href;
   const source = `import assert from 'node:assert/strict';
-import {existsSync,mkdirSync,readdirSync,renameSync,statSync} from 'node:fs';
+import {existsSync,mkdirSync,readFileSync,readdirSync,renameSync,statSync,writeFileSync} from 'node:fs';
 import {join} from 'node:path';
 import {systemWindowsNativeAuthority} from ${JSON.stringify(loader)};
 const temp=process.env.TEMP;
@@ -64,46 +65,61 @@ assert.equal(first.retryable,true);
 assert.match(first.reason,/Delete owned object by handle failed.*Win32 5/s);
 const [name,...extra]=readdirSync(temp);assert.ok(name);assert.equal(extra.length,0);
 const path=join(temp,name);const identity=statSync(path,{bigint:true});
-// Ownership follows the retained NTFS handle even when the directory moves.
-// A replacement at its old pathname must remain caller-owned.
-const moved=path+'-renamed';renameSync(path,moved);
-assert.equal(statSync(moved,{bigint:true}).ino,identity.ino);
+// Delete sharing permits rename; ownership follows the retained NTFS handle.
+writeFileSync(join(path,'owned-child.txt'),'owned child');
+const renamed=path+'-renamed';renameSync(path,renamed);
+const moved=statSync(renamed,{bigint:true});
+assert.equal(moved.dev,identity.dev);assert.equal(moved.ino,identity.ino);
 mkdirSync(path);const replacement=statSync(path,{bigint:true});
 assert.notEqual(replacement.ino,identity.ino);
+const sentinel=join(path,'unrelated.txt');writeFileSync(sentinel,'unrelated replacement');
 if(process.argv[2]!=='teardown'){
  const second=systemWindowsNativeAuthority();assert.equal(second.available,true);
- assert.equal(existsSync(moved),false);
+ assert.equal(existsSync(renamed),false);
  assert.deepEqual(readdirSync(temp),[name]);
+ assert.equal(readFileSync(sentinel,'utf8'),'unrelated replacement');
  assert.equal(statSync(path,{bigint:true}).ino,replacement.ino);
  assert.equal(systemWindowsNativeAuthority(),second);
 }
-console.log(JSON.stringify({mode:process.argv[2],firstFailed:true,retainedOwner:true,inode:identity.ino.toString(),replacementName:name,replacementInode:replacement.ino.toString()}));
+console.log(JSON.stringify({mode:process.argv[2],firstFailed:true,retainedOwner:true,name,renamed,device:identity.dev.toString(),inode:identity.ino.toString(),replacementInode:replacement.ino.toString()}));
 `;
   const fixture = join(workspace, "probe.mjs");
   await writeFile(fixture, source);
   for (const mode of ["retry", "teardown"]) {
     const temp = join(workspace, mode);
     await mkdir(temp);
-    const observed = JSON.parse(
-      execFileSync(process.execPath, [fixture, mode], {
+    const child = spawnSync(process.execPath, [fixture, mode], {
       encoding: "utf8",
       timeout: 20_000,
       windowsHide: true,
       env: { ...process.env, TEMP: temp, TMP: temp },
-      }),
-    );
-    assert.equal(observed.retainedOwner, true);
-    assert.deepEqual(await readdir(temp), [observed.replacementName]);
-    const replacement = join(temp, observed.replacementName);
+    });
+    if (child.error !== undefined) throw child.error;
+    assert.equal(child.status, 0, child.stderr);
     assert.equal(
-      (await stat(replacement, { bigint: true })).ino.toString(),
-      observed.replacementInode,
+      child.stderr,
+      "",
+      "Native environment teardown reported a cleanup failure",
+    );
+    const observed = JSON.parse(child.stdout);
+    assert.equal(observed.mode, mode);
+    assert.equal(observed.firstFailed, true);
+    assert.equal(observed.retainedOwner, true);
+    await assert.rejects(access(observed.renamed), { code: "ENOENT" });
+    assert.deepEqual(await readdir(temp), [observed.name]);
+    const replacement = join(temp, observed.name);
+    const identity = await stat(replacement, { bigint: true });
+    assert.equal(identity.dev.toString(), observed.device);
+    assert.equal(identity.ino.toString(), observed.replacementInode);
+    assert.notEqual(identity.ino.toString(), observed.inode);
+    assert.deepEqual(await readdir(replacement), ["unrelated.txt"]);
+    assert.equal(
+      await readFile(join(replacement, "unrelated.txt"), "utf8"),
+      "unrelated replacement",
     );
-    await rmdir(replacement);
-    assert.deepEqual(await readdir(temp), []);
   }
   process.stdout.write(
-    `${JSON.stringify({ ok: true, controlledDispositionFailure: true, retainedOwner: true, renamedOwnerCleanup: true, replacementPreserved: true, retryRecovers: true, successfulAdmissionCached: true, environmentTeardownCleansProbe: true, issue1701HostCauseReproduced: false })}\n`,
+    `${JSON.stringify({ ok: true, controlledDispositionFailure: true, retainedOwner: true, renamedOwnerCleansChildren: true, unrelatedReplacementPreserved: true, retryRecovers: true, successfulAdmissionCached: true, environmentTeardownCleansProbe: true, issue1701HostCauseReproduced: false })}\n`,
   );
 } finally {
   await rm(workspace, { recursive: true, force: true });

src/application/ClientConfigurationDocument.ts

@@ -167,7 +167,7 @@ export const parseZcodeFallbackConfiguration = (
         ? {}
         : requireObject(document.mcpServers, "ZCode fallback mcpServers"),
     serversPath: ["mcpServers"],
-    dialect: "json",
+    dialect: "zcode_fallback",
     legacyServers: {},
   };
 };
@@ -183,6 +183,7 @@ export const parseClientConfiguration = (
   if (format === undefined || format === "unsupported")
     throw new TypeError("client does not have a supported MCP config format");
   // DeepSeek Harness stores a Cordis patch list, not a server table.
+  if (format === "zcode_fallback") return parseZcodeFallbackConfiguration(text);
   if (format === "dsh") return parseDshCordisDocument(text);
   const document = parseDocument(text, format);
   const serversKey = clientConfigurationServersKey(format);

src/application/ReferenceSourceImport.ts

@@ -12,7 +12,7 @@ import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.j
 import type { AnalysisCleanupObservation } from "../domain/analysisErrorBase.js";
 import { readReferenceSource } from "../reference/ReferenceSourceReader.js";
 import type {
-  ReferenceSourceEntryKind,
+  ReferenceSourceExclusionKind,
   ReferenceSourceRead,
   ReferenceSourceReaderError,
 } from "../reference/ReferenceSourceReaderTypes.js";
@@ -111,7 +111,8 @@ const deriveInventoryState = (
       entry.limitations.length > 0 ||
       (entry.kind === "file" && entry.content_state !== "hashed") ||
       (entry.kind === "directory" && entry.tree_state !== "enumerated") ||
-      (entry.kind === "symlink" && entry.target_state !== "internal"),
+      (entry.kind === "symlink" && entry.target_state !== "internal") ||
+      entry.kind === "unknown",
   );
   if (partialEntry) return "partial";
   const partialRelationship = input.relationships.some(
@@ -142,11 +143,24 @@ const createShouldExclude =
     exclusions: HistoricalSourceGraphInput["exclusions"],
     secrets: PreparedReferenceSourceImport["secrets"],
     ignored: PreparedReferenceSourceImport["ignored"],
-  ): ((path: string, kind: ReferenceSourceEntryKind) => boolean) =>
+  ): ((path: string, kind: ReferenceSourceExclusionKind) => boolean) =>
   (path, kind) => {
-    const patternPath = kind === "directory" ? `${path}/` : path;
-    const secretMatch = secrets.test(patternPath);
-    if (secretMatch.ignored) {
+    // An entry of unknown kind may be a directory, so directory-only rules
+    // must still exclude it; this fails closed for caller-marked secrets.
+    const patternPaths =
+      kind === "directory"
+        ? [`${path}/`]
+        : kind === "unknown"
+          ? [path, `${path}/`]
+          : [path];
+    const firstMatch = (matcher: typeof secrets) => {
+      const results = patternPaths.map((patternPath) =>
+        matcher.test(patternPath),
+      );
+      return results.find(({ ignored }) => ignored) ?? results[0];
+    };
+    const secretMatch = firstMatch(secrets);
+    if (secretMatch?.ignored === true) {
       if (!secretMatch.rule)
         throw new Error(`Ignored secret path has no matching rule: ${path}`);
       exclusions.push({
@@ -156,8 +170,8 @@ const createShouldExclude =
       });
       return true;
     }
-    const match = ignored.test(patternPath);
-    if (!match.ignored) return false;
+    const match = firstMatch(ignored);
+    if (match?.ignored !== true) return false;
     if (!match.rule)
       throw new Error(`Ignored path has no matching rule: ${path}`);
     const reason = match.rule.mark;

src/application/ReferenceSourceImportEntries.ts

@@ -45,6 +45,8 @@ const entryRecoveryGuidance = (
     return "This directory could not be read. Check its permissions, then try again.";
   if (entry.kind === "symlink")
     return "This symbolic link could not be read safely. Check the link and its permissions, then try again.";
+  if (entry.kind === "unknown")
+    return "This entry's type could not be determined. Check the parent directory and try again.";
   return "This file could not be read. Check its permissions, then try again.";
 };
 
@@ -73,6 +75,13 @@ const failedEntry = (
       classifications,
       limitations: [limitation],
     };
+  if (entry.kind === "unknown")
+    return {
+      path: entry.path,
+      kind: "unknown",
+      classifications: ["unknown"],
+      limitations: [limitation],
+    };
   return {
     path: entry.path,
     kind: "file",

src/application/SupportedClients.ts

@@ -47,6 +47,7 @@ export interface SetupClient {
     | "pi"
     | "kimi"
     | "hermes"
+    | "zcode_fallback"
     | "zcode"
     | "dsh"
     | "unsupported";

src/application/Uninstall.ts

@@ -231,12 +231,21 @@ export const systemUninstallHost = (
       const clients = supportedClients(home, platform, environment);
       redirection = appDataRedirection(clients);
       return Promise.resolve(
-        clients.flatMap((client) =>
-          uninstallConfigPaths(client).map((configPath) => ({
+        clients.flatMap((client) => [
+          ...uninstallConfigPaths(client).map((configPath) => ({
             ...client,
             configPath,
           })),
-        ),
+          ...(client.zcodeFallbackPath === undefined
+            ? []
+            : [
+                {
+                  ...client,
+                  configPath: client.zcodeFallbackPath,
+                  format: "zcode_fallback" as const,
+                },
+              ]),
+        ]),
       );
     },
     inspectClient: async (client) => {

src/domain/referenceSourceGraph.test.ts

@@ -259,6 +259,30 @@ describe("historical source graph", () => {
 });
 
 describe("partial historical source graphs", () => {
+  it("keeps unknown-entry diagnostics outside the root commitment", () => {
+    const base = graphInput();
+    base.inventory_state = "partial";
+    base.entries[2] = {
+      path: "src/package.json",
+      kind: "unknown",
+      classifications: ["unknown"],
+      limitations: ["Permission denied at /private/first"],
+    };
+    const graph = createHistoricalSourceGraph(base);
+    const changedMessage = structuredClone(base);
+    changedMessage.entries[2] = {
+      path: "src/package.json",
+      kind: "unknown",
+      classifications: ["unknown"],
+      limitations: ["Permission denied at /private/second"],
+    };
+    const revised = createHistoricalSourceGraph(changedMessage);
+    expect(revised.root_sha256).toBe(graph.root_sha256);
+    expect(computeHistoricalSourceGraphSha256(revised)).not.toBe(
+      computeHistoricalSourceGraphSha256(graph),
+    );
+  });
+
   it("keeps an unreadable symlink target unknown and out of root identity", () => {
     const base = graphInput();
     base.inventory_state = "partial";

src/domain/referenceSourceGraph.ts

@@ -111,6 +111,10 @@ const sourceEntrySchema = z.union([
   sourceFileSchema,
   sourceDirectorySchema,
   sourceSymlinkSchema,
+  z.strictObject({
+    ...entryBaseShape,
+    kind: z.literal("unknown"),
+  }),
 ]);
 
 const sourceRelationshipSchema = z.strictObject({
@@ -361,7 +365,8 @@ const checkCompleteInventory = (
       entry.limitations.length > 0 ||
       (entry.kind === "file" && entry.content_state !== "hashed") ||
       (entry.kind === "directory" && entry.tree_state !== "enumerated") ||
-      (entry.kind === "symlink" && entry.target_state !== "internal"),
+      (entry.kind === "symlink" && entry.target_state !== "internal") ||
+      entry.kind === "unknown",
   );
   const partialRelationship = graph.relationships.some(
     ({ parse_state, resolution }) =>
@@ -478,6 +483,11 @@ const rootCommitment = (
           target: entry.target,
           target_state: entry.target_state,
         };
+      case "unknown":
+        return {
+          kind: entry.kind,
+          path: entry.path,
+        };
     }
   }),
   exclusions,

src/domain/referenceSourceSummary.test.ts

@@ -81,6 +81,26 @@ describe("committed historical-source summaries", () => {
     expect(graph).toEqual(original);
   });
 
+  it("counts entries of unknown kind separately from symlinks", () => {
+    const graph = createHistoricalSourceGraph(
+      input([
+        {
+          path: "deep",
+          kind: "unknown",
+          classifications: ["unknown"],
+          limitations: ["lstat: ENAMETOOLONG"],
+        },
+      ]),
+    );
+    expect(createHistoricalSourceSummary(graph, 1).counts).toMatchObject({
+      entries: 1,
+      files: 0,
+      directories: 0,
+      symlinks: 0,
+      unknown: 1,
+    });
+  });
+
   it("sums known bytes losslessly beyond the JSON safe integer range", () => {
     const graph = createHistoricalSourceGraph(
       input(

src/domain/referenceSourceSummary.ts

@@ -29,6 +29,7 @@ export const createHistoricalSourceSummary = (
     files: 0,
     directories: 0,
     symlinks: 0,
+    unknown: 0,
     relationships: graph.relationships.length,
     parse_failures: graph.parse_failures.length,
     exclusions: graph.exclusions.length,
@@ -59,7 +60,8 @@ export const createHistoricalSourceSummary = (
     } else if (entry.kind === "directory") {
       counts.directories += 1;
       treeStates[entry.tree_state] += 1;
-    } else counts.symlinks += 1;
+    } else if (entry.kind === "symlink") counts.symlinks += 1;
+    else counts.unknown += 1;
     // Canonical entries already use Unicode code-point order; filtering preserves it.
     if (entry.path.split("/").length <= outlineDepth)
       outline.push(outlineEntry(entry));

src/reference/ReferenceSourceReaderEntries.ts

@@ -25,7 +25,7 @@ import {
 import type {
   PendingDirectory,
   ReferenceSourceEntry,
-  ReferenceSourceEntryKind,
+  ReferenceSourceExclusionKind,
   ReferenceSourceResult,
   TraversalState,
 } from "./ReferenceSourceReaderTypes.js";
@@ -201,6 +201,13 @@ const processEntry = async (
   const metadata = await readMetadata(absolute);
   if (isAborted(state.signal)) return { ok: false, error: cancelled() };
   if (!metadata.ok) {
+    const excluded = applyExclusion(state.shouldExclude, path, "unknown");
+    if (!excluded.ok)
+      return {
+        ok: false,
+        error: failure("io", "Reference source exclusion check failed"),
+      };
+    if (excluded.value) return { ok: true, value: undefined };
     state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
     return { ok: true, value: undefined };
   }
@@ -371,10 +378,10 @@ const readSymlinkTarget = async (
 
 const applyExclusion = (
   shouldExclude:
-    | ((path: string, kind: ReferenceSourceEntryKind) => boolean)
+    | ((path: string, kind: ReferenceSourceExclusionKind) => boolean)
     | undefined,
   path: string,
-  kind: ReferenceSourceEntryKind,
+  kind: ReferenceSourceExclusionKind,
 ): { readonly ok: true; readonly value: boolean } | { readonly ok: false } => {
   try {
     return { ok: true, value: shouldExclude?.(path, kind) === true };

src/reference/ReferenceSourceReaderErrors.ts

@@ -29,6 +29,9 @@ const FILESYSTEM_ERROR_CODES = new Set([
   "EISDIR",
   "ELOOP",
   "EMFILE",
+  // A traversed child can exceed the platform's absolute path limit even
+  // though the selected root and every component are valid.
+  "ENAMETOOLONG",
   "ENFILE",
   "ENOENT",
   "ENOTDIR",
@@ -44,6 +47,8 @@ export const filesystemFailureDetail = (
 ): string | undefined => {
   if (!(cause instanceof Error)) return undefined;
   const code: unknown = Reflect.get(cause, "code");
+  if (code === "ENAMETOOLONG")
+    return `${operation}: ENAMETOOLONG (entry path exceeds the operating system path limit)`;
   return typeof code === "string" && FILESYSTEM_ERROR_CODES.has(code)
     ? `${operation}: ${cause.message}`
     : undefined;

src/reference/ReferenceSourceReaderTypes.ts

@@ -10,11 +10,17 @@ export type ReferenceSourceEntryKind =
   | "symlink"
   | "other";
 
+/**
+ * Kind offered to exclusion predicates. `unknown` marks an entry whose
+ * metadata could not be read, so its concrete kind cannot be claimed.
+ */
+export type ReferenceSourceExclusionKind = ReferenceSourceEntryKind | "unknown";
+
 export interface ReferenceSourceReaderOptions {
   readonly signal?: AbortSignal;
   readonly shouldExclude?: (
     path: string,
-    kind: ReferenceSourceEntryKind,
+    kind: ReferenceSourceExclusionKind,
   ) => boolean;
 }
 
@@ -84,7 +90,7 @@ export type TraversalState = {
   readonly signal?: AbortSignal;
   readonly shouldExclude?: (
     path: string,
-    kind: ReferenceSourceEntryKind,
+    kind: ReferenceSourceExclusionKind,
   ) => boolean;
   readonly entries: ReferenceSourceEntry[];
   readonly pending: PendingDirectory[];

tests/boundary/filesystem/referenceSourceFailureDetails.test.ts

@@ -133,3 +133,88 @@ describe("reference import native entry failure details", () => {
     ).toMatchObject({ kind: "file", content_state: "hashed", limitations: [] });
   });
 });
+
+describe("reference import paths beyond the platform limit", () => {
+  it.skipIf(process.platform === "win32")(
+    "reports an entry beyond the absolute path limit as an I/O failure",
+    async () => {
+      const root = await createTestTempDirectory("rea-import-deep-path-");
+      await writeFile(join(root, "kept.txt"), "k");
+      // Relative creation lets the tree exceed PATH_MAX (1024 on macOS, 4096
+      // on Linux) while each 200-byte component stays below NAME_MAX.
+      const deepTree = (action: "create" | "remove") =>
+        promisify(execFile)(process.execPath, [
+          "-e",
+          `const fs = require("node:fs");
+          const names = Array.from({ length: 24 }, (_, i) => "d" + String(i).padStart(2, "0") + "x".repeat(197));
+          process.chdir(${JSON.stringify(root)});
+          if (${JSON.stringify(action)} === "create") {
+            for (const name of names) { fs.mkdirSync(name); process.chdir(name); }
+            fs.writeFileSync("deep.txt", "d");
+          } else {
+            for (const name of names) process.chdir(name);
+            fs.rmSync("deep.txt");
+            for (const name of [...names].reverse()) { process.chdir(".."); fs.rmdirSync(name); }
+          }`,
+        ]);
+      await deepTree("create");
+      try {
+        const read = await readReferenceSource(root);
+        if (!read.ok) throw new Error(read.error.message);
+        expect(read.value.entries).toContainEqual(
+          expect.objectContaining({ path: "kept.txt", status: "read" }),
+        );
+        const failed = read.value.entries.find(
+          (entry) => entry.status === "failed",
+        );
+        expect(failed).toMatchObject({
+          status: "failed",
+          code: "io",
+          message: expect.stringContaining("ENAMETOOLONG"),
+        });
+        const filteredRead = await readReferenceSource(root, {
+          shouldExclude: (path, kind) =>
+            path === failed?.path && kind === "directory",
+        });
+        if (!filteredRead.ok) throw new Error(filteredRead.error.message);
+        expect(
+          filteredRead.value.entries.find(
+            (entry) => entry.path === failed?.path,
+          ),
+        ).toMatchObject({ status: "failed", kind: "unknown", code: "io" });
+        const imported = await importTree(root);
+        if (!imported.ok) throw new Error(imported.error.message);
+        expect(imported.value.entries).toContainEqual(
+          expect.objectContaining({
+            path: "kept.txt",
+            content_state: "hashed",
+          }),
+        );
+        const deep = imported.value.entries.find(
+          (entry) => entry.path === failed?.path,
+        );
+        expect(deep?.limitations.join(" ")).toContain(
+          failed?.status === "failed" ? failed.message : "missing failure",
+        );
+        // A directory-only secret rule still applies when the kind is unknown.
+        const secretPattern = `${failed?.path ?? "missing"}/`;
+        const secret = await importReferenceSource({
+          root,
+          caller: "native-entry-failure-detail-test",
+          policy: { secretPatterns: [secretPattern] },
+        });
+        if (!secret.ok) throw new Error(secret.error.message);
+        expect(
+          secret.value.entries.some(({ path }) => path === failed?.path),
+        ).toBe(false);
+        expect(secret.value.exclusions).toContainEqual({
+          path: failed?.path,
+          reason: "configured-secret",
+          pattern: secretPattern,
+        });
+      } finally {
+        await deepTree("remove");
+      }
+    },
+  );
+});

tests/boundary/filesystem/zcodeClientConfiguration.test.ts

@@ -13,7 +13,10 @@ import {
 } from "../../../src/application/SetupClientConfiguration.js";
 import { skillDestinations } from "../../../src/application/SetupSkill.js";
 import { supportedClients } from "../../../src/application/SupportedClients.js";
-import { systemUninstallHost } from "../../../src/application/Uninstall.js";
+import {
+  runUninstall,
+  systemUninstallHost,
+} from "../../../src/application/Uninstall.js";
 import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
 import { clearClientLocationEnvironment } from "../../fixtures/clientEnvironment.js";
 
@@ -257,6 +260,91 @@ describe("ZCode .agents fallback preservation", () => {
   });
 });
 
+describe("ZCode fallback uninstall", () => {
+  const owned = { command: command[0], args: command.slice(1) };
+  const writeFallback = async (home: string, servers: object) => {
+    await mkdir(join(home, ".agents"), { recursive: true });
+    const text = `${JSON.stringify({ ui: { keep: true }, mcpServers: servers }, null, 2)}\n`;
+    await writeFile(fallbackPath(home), text);
+    return text;
+  };
+
+  it.each(["comment", "trailing-comma", "bom"])(
+    "fails closed on strict fallback syntax: %s",
+    async (mode) => {
+      const { home } = await zcodeClient();
+      const valid = await writeFallback(home, {
+        rea: owned,
+        other: { command: "other-server" },
+      });
+      const original =
+        mode === "comment"
+          ? `// unsupported comment\n${valid}`
+          : mode === "bom"
+            ? `\uFEFF${valid}`
+            : valid.replace(/\}\s*$/u, ",}");
+      await writeFile(fallbackPath(home), original);
+      const result = await runUninstall(false, systemUninstallHost(home));
+      expect(result.items).toContainEqual(
+        expect.objectContaining({ name: "zcode", status: "failed" }),
+      );
+      expect(await readFile(fallbackPath(home), "utf8")).toBe(original);
+      await expect(
+        readFile(`${fallbackPath(home)}.rea.backup`),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+    },
+  );
+
+  it("removes the REA-owned fallback entry with the native registration", async () => {
+    const { home, client } = await zcodeClient();
+    await writeFile(
+      client.configPath,
+      JSON.stringify({ mcp: { servers: { rea: owned } } }),
+    );
+    const original = await writeFallback(home, {
+      rea: owned,
+      other: { command: "other-server" },
+    });
+
+    const result = await runUninstall(false, systemUninstallHost(home));
+
+    expect(result.status).toBe("complete");
+    expect(result.items.find(({ name }) => name === "zcode")?.status).toBe(
+      "removed",
+    );
+    const native = JSON.parse(await readFile(client.configPath, "utf8"));
+    expect(native.mcp.servers).toEqual({});
+    const fallback = JSON.parse(await readFile(fallbackPath(home), "utf8"));
+    expect(fallback).toEqual({
+      ui: { keep: true },
+      mcpServers: { other: { command: "other-server" } },
+    });
+    expect(await readFile(`${fallbackPath(home)}.rea.backup`, "utf8")).toBe(
+      original,
+    );
+  });
+
+  it("removes a fallback-only REA entry and keeps a foreign rea entry", async () => {
+    for (const [servers, expected] of [
+      [{ rea: owned }, {}],
+      [
+        { rea: { command: "someone-else" } },
+        { rea: { command: "someone-else" } },
+      ],
+    ] as const) {
+      const { home } = await zcodeClient();
+      await writeFallback(home, servers);
+
+      expect(
+        (await runUninstall(false, systemUninstallHost(home))).status,
+      ).toBe("complete");
+      expect(
+        JSON.parse(await readFile(fallbackPath(home), "utf8")).mcpServers,
+      ).toEqual(expected);
+    }
+  });
+});
+
 describe("ZCode fallback admission", () => {
   it.each([{ PORT: 123 }, { REA_MCP_INPUT_SCHEMA_PROFILE: "unknown" }])(
     "refuses malformed fallback REA environment %j before native writes",