rea-agents 1.7.0 → 2.1.0

package/dist/server/toolInputValidation.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { AnalysisInputError, } from "../domain/errors.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { err, ok } from "../domain/result.js";
+import { closeObjectSchemas } from "./toolRegistrationOptions.js";
+/** Parse one MCP request exactly once and retain only schema-owned correction data. */
+export const safeParseToolInput = (schema, input, operation) => {
+    const unknownIssues = unknownArgumentIssues(schema, input);
+    if (unknownIssues.length > 0)
+        return err(new AnalysisInputError(operation, undefined, unknownIssues));
+    const parsed = schema.safeParse(input);
+    return parsed.success
+        ? ok(parsed.data)
+        : err(new AnalysisInputError(operation, undefined, projectInputIssues(parsed.error.issues, input)));
+};
+const schemaCache = new WeakMap();
+const unknownArgumentIssues = (schema, input) => {
+    let jsonSchema = schemaCache.get(schema);
+    if (jsonSchema === undefined) {
+        const converter = schema["~standard"].jsonSchema?.input;
+        if (converter === undefined)
+            throw new TypeError("Tool input schema does not expose Standard JSON Schema");
+        jsonSchema = closeObjectSchemas(converter({ target: "draft-2020-12" }));
+        schemaCache.set(schema, jsonSchema);
+    }
+    return scanUnknownArguments(input, jsonSchema, jsonSchema, []);
+};
+const scanUnknownArguments = (value, schema, root, path) => {
+    const resolved = resolveSchema(schema, root);
+    if (Array.isArray(value)) {
+        const items = objectValue(resolved.items);
+        return items === undefined
+            ? []
+            : value.flatMap((item, index) => scanUnknownArguments(item, items, root, [...path, index]));
+    }
+    if (!isObject(value))
+        return [];
+    const variants = schemaVariants(resolved, root);
+    const properties = Object.fromEntries(variants.flatMap((variant) => Object.entries(objectValue(variant.properties) ?? {})));
+    const closed = variants.length > 0 &&
+        variants.every((variant) => variant.additionalProperties !== true &&
+            !isObject(variant.additionalProperties));
+    const issues = [];
+    for (const [key, child] of Object.entries(value)) {
+        const propertySchema = objectValue(properties[key]);
+        if (propertySchema === undefined) {
+            if (closed)
+                issues.push({ path: [...path, key], reason: "unknown_argument" });
+            continue;
+        }
+        issues.push(...scanUnknownArguments(child, propertySchema, root, [...path, key]));
+    }
+    return issues;
+};
+const schemaVariants = (schema, root) => {
+    const resolved = resolveSchema(schema, root);
+    const variants = [resolved.oneOf, resolved.anyOf, resolved.allOf]
+        .flatMap((value) => (Array.isArray(value) ? value : []))
+        .flatMap((value) => {
+        const object = objectValue(value);
+        return object === undefined ? [] : schemaVariants(object, root);
+    });
+    if (variants.length > 0)
+        return variants;
+    return resolved.type === "object" || isObject(resolved.properties)
+        ? [resolved]
+        : [];
+};
+const resolveSchema = (schema, root) => {
+    const reference = schema.$ref;
+    if (typeof reference !== "string" || !reference.startsWith("#/$defs/"))
+        return schema;
+    const definition = objectValue(objectValue(root.$defs)?.[reference.slice(8)]);
+    return definition === undefined ? schema : definition;
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const objectValue = (value) => isObject(value) ? value : undefined;

package/dist/server/toolRegistrationOptions.js

@@ -1,7 +1,182 @@
+import { z } from "zod";
 /** Project the public contract fields accepted by MCP tool registration. */
 export const toolRegistrationOptions = (contract) => ({
+    title: contract.title,
     description: contract.description,
-    inputSchema: contract.inputSchema,
-    outputSchema: contract.outputSchema,
+    inputSchema: advertisedInputSchema(contract.inputSchema),
+    outputSchema: advertisedOutputSchema(contract.outputSchema),
     annotations: contract.annotations,
 });
+/**
+ * Advertise the exact Zod contract while leaving validation to REA's adapter.
+ * The SDK otherwise converts validation failures to text-only JSON-RPC errors
+ * before REA can return its stable structured error envelope.
+ */
+const advertisedInputSchema = (schema) => ({
+    "~standard": {
+        version: 1,
+        vendor: "rea",
+        validate: (input) => ({ value: input }),
+        jsonSchema: {
+            input: () => describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
+            output: () => describeProperties(closeObjectSchemas(inputJsonSchema(schema))),
+        },
+    },
+});
+const advertisedOutputSchema = (schema) => {
+    const standard = schema["~standard"];
+    const converter = standard.jsonSchema?.output;
+    if (converter === undefined)
+        throw new TypeError("Tool output schema does not expose Standard JSON Schema");
+    return {
+        "~standard": {
+            ...standard,
+            jsonSchema: {
+                input: () => describeRootProperties(closeObjectSchemas(converter({ target: "draft-2020-12" }))),
+                output: () => describeRootProperties(closeObjectSchemas(converter({ target: "draft-2020-12" }))),
+            },
+        },
+    };
+};
+const inputJsonSchema = (schema) => {
+    const converter = schema["~standard"].jsonSchema?.input;
+    if (converter === undefined)
+        throw new TypeError("Tool input schema does not expose Standard JSON Schema");
+    return converter({ target: "draft-2020-12" });
+};
+/** Close fixed-shape JSON Schema objects while preserving explicit maps. */
+export const closeObjectSchemas = (value) => {
+    const closed = Object.fromEntries(Object.entries(value).map(([key, child]) => [key, closeSchemaValue(child)]));
+    return value.type === "object" &&
+        isObject(value.properties) &&
+        value.additionalProperties === undefined
+        ? { ...closed, additionalProperties: false }
+        : closed;
+};
+const closeSchemaValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(closeSchemaValue);
+    if (!isObject(value))
+        return value;
+    return closeObjectSchemas(value);
+};
+const describeProperties = (value) => Object.fromEntries(Object.entries(value).map(([key, child]) => {
+    if (key !== "properties" || typeof child !== "object" || child === null)
+        return [key, describeValue(child)];
+    return [
+        key,
+        Object.fromEntries(Object.entries(child).map(([property, schema]) => [
+            property,
+            isObject(schema) && typeof schema.description !== "string"
+                ? {
+                    ...describeProperties(schema),
+                    description: fallbackPropertyDescription(property),
+                }
+                : describeValue(schema),
+        ])),
+    ];
+}));
+const describeValue = (value) => {
+    if (Array.isArray(value))
+        return value.map(describeValue);
+    return isObject(value) ? describeProperties(value) : value;
+};
+const describeRootProperties = (value) => {
+    const properties = value.properties;
+    if (!isObject(properties))
+        return { ...value };
+    return {
+        ...value,
+        properties: Object.fromEntries(Object.entries(properties).map(([property, schema]) => [
+            property,
+            isObject(schema) && typeof schema.description !== "string"
+                ? {
+                    ...schema,
+                    description: fallbackPropertyDescription(property),
+                }
+                : schema,
+        ])),
+    };
+};
+const PROPERTY_DESCRIPTIONS = {
+    addresses: "Ordered provider-normalized procedure addresses to analyze.",
+    approved: "Explicit operator approval to perform this operation.",
+    after: "The later or right-hand observation to compare.",
+    before: "The earlier or left-hand observation to compare.",
+    boundary_id: "Exact reconstruction boundary identifier to evaluate.",
+    case_sensitive: "Whether text matching distinguishes uppercase and lowercase.",
+    cdp_endpoint: "Approved literal loopback Chrome DevTools Protocol endpoint.",
+    comment: "Exact analyst comment text to write.",
+    comparisons: "Validated comparison Evidence records to aggregate.",
+    coverage: "Exact reconstruction-coverage commitment to verify.",
+    detail: "Requested response detail level.",
+    direction: "Direction in which to traverse or compare relationships.",
+    document: "Exact provider document or program identity.",
+    error: "Structured, caller-actionable error when the operation fails.",
+    evidence: "Evidence v2 record produced by this operation.",
+    evidence_id: "Stable identifier of the recorded Evidence v2 observation.",
+    evidence_uri: "Session resource URI for the recorded Evidence v2 observation.",
+    executable: "Approved absolute path of the executable to run.",
+    format: "Declared input artifact format.",
+    name: "Exact name used by this operation.",
+    pattern: "Text or bounded pattern used to filter matching results.",
+    phase: "Current plan or execution phase of the operation.",
+    plan: "Content-bound execution plan and its approval commitment.",
+    query: "Non-empty feature or text query to investigate.",
+    question: "Concrete unresolved question to retain for later investigation.",
+    result: "Primary structured result returned by this operation.",
+    left: "Left-hand input used for comparison or differential execution.",
+    limit: "Maximum number of results to return in this page.",
+    limits: "Bounded resource-consumption and result-size limits for this operation.",
+    mode: "Operation mode that selects the requested behavior.",
+    offset: "Zero-based index of the first result to return.",
+    overwrite: "Whether an existing destination may be replaced.",
+    path: "Local filesystem path used by this operation.",
+    provider_id: "Exact deep-analysis provider ID, or automatic selection when omitted.",
+    right: "Right-hand input used for comparison or differential execution.",
+    schema_version: "Version of this structured result schema.",
+    source_evidence: "Evidence records supporting the prepared source transformation.",
+    status: "Current lifecycle or verification status.",
+    summary: "Concise evidence-backed summary of the result.",
+    symbols: "Ordered bounded Swift symbols to demangle.",
+    target_id: "Exact authorized CDP target identifier.",
+    unknown_id: "Exact residual-unknown identifier.",
+    unknown_registry_approved: "Explicit approval to record bounded residual uncertainty in the session registry.",
+    workspace_path: "Approved local path of the persistent investigation workspace.",
+};
+const fallbackPropertyDescription = (property) => {
+    const explicit = PROPERTY_DESCRIPTIONS[property];
+    if (explicit !== undefined)
+        return explicit;
+    const words = property.replaceAll("_", " ");
+    if (property.endsWith("_approved"))
+        return `Explicit operator approval for ${words.slice(0, -9)}.`;
+    if (property.endsWith("_offset"))
+        return `Zero-based index of the first ${words.slice(0, -7)} to return.`;
+    if (property.endsWith("_limit"))
+        return `Maximum number of ${words.slice(0, -6)} entries to return.`;
+    if (property.startsWith("max_"))
+        return `Maximum permitted ${words.slice(4)} for this operation.`;
+    if (property.startsWith("include_"))
+        return `Whether to include ${words.slice(8)} in the result.`;
+    if (property.startsWith("expected_"))
+        return `Expected ${words.slice(9)} used to reject stale or mismatched input.`;
+    if (property.endsWith("_sha256"))
+        return `Exact SHA-256 digest of ${words.slice(0, -7)}.`;
+    if (property.endsWith("_evidence_id"))
+        return `Exact Evidence v2 identifier for the ${words.slice(0, -12)} observation.`;
+    if (property.endsWith("_evidence_ids"))
+        return `Ordered Evidence v2 identifiers for the ${words.slice(0, -13)} observations.`;
+    if (property.endsWith("_path"))
+        return `Local filesystem path for ${words.slice(0, -5)}.`;
+    if (property.endsWith("_uri"))
+        return `Canonical URI for ${words.slice(0, -4)}.`;
+    if (property.endsWith("_bytes"))
+        return `Bounded byte count for ${words.slice(0, -6)}.`;
+    if (property.endsWith("_root") || property.endsWith("_roots"))
+        return `Approved canonical filesystem ${words}.`;
+    if (property.startsWith("is_") || property.startsWith("has_"))
+        return `Whether ${words}.`;
+    return `Value for ${words}.`;
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/server/toolResult.js

@@ -9,43 +9,65 @@ export const toCallToolResult = (result, contract, options = {}) => result.ok
     : errorResult(result.error);
 const errorResult = (error) => {
     const projected = projectAnalysisError(error);
+    const structuredContent = { error: projected };
     return {
         content: [
             {
                 type: "text",
-                text: projected.message,
+                text: JSON.stringify(structuredContent),
             },
         ],
-        structuredContent: { error: projected },
+        structuredContent,
         isError: true,
     };
 };
 const successResult = (value, contract, options) => {
-    const candidate = contract.kind === "session" ? { result: value } : value;
+    const candidate = compactEvidence(value) ??
+        (contract.kind === "session" ? { result: value } : value);
     const parsed = contract.outputSchema.safeParse(candidate);
     if (!parsed.success) {
+        const structuredContent = {
+            error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
+        };
         return {
             content: [
                 {
                     type: "text",
-                    text: "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
+                    text: JSON.stringify(structuredContent),
                 },
             ],
-            structuredContent: {
-                error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
-            },
+            structuredContent,
             isError: true,
         };
     }
     return {
         content: [
-            { type: "text", text: formatValue(value) },
+            { type: "text", text: JSON.stringify(parsed.data) },
             ...evidenceResourceLinks(value, contract.kind === "session" ||
                 options.evidenceResourcesAvailable === true),
+            ...(options.resourceLinks ?? []).map((resource) => ({
+                type: "resource_link",
+                ...resource,
+                mimeType: "application/json",
+            })),
         ],
         structuredContent: candidate,
     };
 };
+const compactEvidence = (value) => {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.evidence_id !== "string" ||
+        !/^ev_[a-f0-9]{64}$/u.test(value.evidence_id) ||
+        !("normalized_result" in value))
+        return undefined;
+    return {
+        result: value.normalized_result,
+        evidence_id: value.evidence_id,
+        evidence_uri: `rea://evidence/${value.evidence_id}`,
+    };
+};
 const evidenceResourceLinks = (value, available) => {
     if (!available ||
         typeof value !== "object" ||
@@ -64,12 +86,3 @@ const evidenceResourceLinks = (value, available) => {
         },
     ];
 };
-const formatValue = (value) => {
-    if (value === null)
-        return "OK";
-    if (typeof value === "string")
-        return value;
-    if (typeof value === "object")
-        return JSON.stringify(value, null, 2);
-    return String(value);
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.7.0",
+  "version": "2.1.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,8 @@
   },
   "type": "module",
   "bin": {
-    "rea": "scripts/rea.mjs"
+    "rea": "scripts/rea.mjs",
+    "rea-agents": "scripts/rea.mjs"
   },
   "engines": {
     "node": "^22.19.0 || >=24.11.0"
@@ -42,17 +43,17 @@
     "bridge/hopper_bridge.py",
     "bridge/ghidra/ReaGhidraBridge.java",
     "scripts/rea.mjs",
-    "scripts/prepare-node-pty.mjs",
-    "scripts/rebuild-native.mjs",
     "scripts/hopper-demo-x11.py",
     "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "prebuild": "node scripts/generate-package-metadata.mjs",
+    "deps:check": "node scripts/check-dependency-install.mjs",
+    "prebuild": "npm run deps:check && node scripts/generate-package-metadata.mjs",
     "build": "tsc -p tsconfig.build.json",
     "postbuild": "node scripts/record-build-cache.mjs",
+    "precheck": "npm run deps:check",
     "check": "npm run typecheck && npm run lint && npm run format:check && npm run docs:check && npm test",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -64,7 +65,6 @@
     "scan:todos": "node scripts/scan-todos.mjs",
     "start": "node scripts/rea.mjs mcp",
     "pretest": "npm run build",
-    "postinstall": "node scripts/prepare-node-pty.mjs",
     "test": "vitest run",
     "pretest:coverage": "npm run build",
     "test:coverage": "vitest run --coverage.enabled --coverage.provider=v8",
@@ -73,19 +73,28 @@
     "typecheck": "tsc --noEmit",
     "verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",
     "verify:ghidra": "npm run build && node scripts/verify-real-ghidra.mjs",
+    "verify:ghidra:windows": "npm run build && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs",
     "verify:browser": "npm run build && node scripts/verify-real-browser.mjs",
+    "verify:javascript-runtime": "npm run build && node scripts/verify-local-javascript-runtime.mjs",
+    "verify:application-workflows": "npm run build && node scripts/verify-local-application-workflows.mjs",
+    "verify:managed": "npm run build && node scripts/verify-managed-conformance.mjs",
+    "verify:replay": "npm run build && node scripts/verify-real-javascript-replay.mjs",
     "verify:hopper:linux": "npm run build && node scripts/verify-real-hopper-linux.mjs",
     "verify:setup:linux": "npm run build && node scripts/verify-linux-setup-e2e.mjs",
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",
+    "build:ghidra-windows-fixture": "node scripts/create-ghidra-windows-fixture.mjs",
     "verify:fixtures": "npm run build:fixtures && node scripts/verify-conformance-fixtures.mjs",
     "verify:package": "npm run build && node scripts/verify-package.mjs",
+    "verify:package:windows": "npm run build && node scripts/verify-windows-package.mjs",
+    "probe:windows-capabilities": "npm run build && node scripts/windows-capabilities.mjs",
     "verify:published": "node scripts/verify-published-package.mjs",
     "config:print": "node scripts/print-mcp-config.mjs",
-    "docs:generate": "npm run build && node scripts/generate-product-catalog.mjs && typedoc && node scripts/generate-error-schema.mjs",
-    "docs:check": "node scripts/generate-package-metadata.mjs --check && npm run build && node scripts/generate-product-catalog.mjs --check && node scripts/check-doc-facts.mjs && node scripts/check-typedoc.mjs && node scripts/generate-error-schema.mjs --check",
+    "docs:generate": "npm run build && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && typedoc && node scripts/generate-error-schema.mjs",
+    "docs:check": "node scripts/generate-package-metadata.mjs --check && npm run build && node scripts/generate-skill-metadata.mjs --check && node scripts/generate-product-catalog.mjs --check && node scripts/check-doc-facts.mjs && node scripts/check-typedoc.mjs && node scripts/generate-error-schema.mjs --check",
     "docs:error-schema": "npm run build && node scripts/generate-error-schema.mjs",
-    "prepare": "npm run build && husky",
-    "rebuild:native": "node scripts/rebuild-native.mjs"
+    "prepack": "npm run deps:check && node scripts/generate-skill-metadata.mjs --check",
+    "prepublishOnly": "npm run deps:check && node scripts/generate-skill-metadata.mjs --check",
+    "prepare": "npm run build && husky"
   },
   "lint-staged": {
     "*.{ts,mjs,json,md,yml,yaml}": "prettier --write",
@@ -94,8 +103,10 @@
   "dependencies": {
     "@babel/parser": "8.0.4",
     "@babel/types": "8.0.4",
+    "@clack/prompts": "1.7.0",
     "@electron/asar": "4.2.0",
     "@jridgewell/trace-mapping": "0.3.31",
+    "@lydell/node-pty": "1.1.0",
     "@modelcontextprotocol/server": "2.0.0-beta.4",
     "@xterm/addon-serialize": "0.14.0",
     "@xterm/headless": "6.0.0",
@@ -107,7 +118,6 @@
     "ignore": "7.0.6",
     "incur": "0.4.13",
     "isomorphic-git": "1.38.7",
-    "node-pty": "1.1.0",
     "pino": "9.14.0",
     "plist": "5.0.0",
     "semver": "7.8.5",
@@ -133,8 +143,5 @@
     "typedoc": "0.28.20",
     "typescript": "5.9.3",
     "vitest": "4.1.10"
-  },
-  "allowScripts": {
-    "node-pty@1.1.0": true
   }
 }

package/scripts/rea.mjs

@@ -5,7 +5,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // Route production MCP before importing Incur. Incur owns registration helpers
-// such as `mcp add`, while only dist/main.js may serve the 78-tool stdio server.
+// such as `mcp add`, while only dist/main.js may serve the stdio tool catalog.
 const args = process.argv.slice(2);
 const { default: packageJson } = await import("../package.json", {
   with: { type: "json" },

package/skills/{rea-analysis → reverse-engineer-anything}/SKILL.md

@@ -1,9 +1,10 @@
 ---
-name: rea-analysis
-description: Reverse engineer apps and websites with REA. Explore how features work, then build a version tailored to your project.
+name: reverse-engineer-anything
+description: Reverse engineer native, Electron/JavaScript, and web application artifacts or runtimes with REA. Connect static artifacts to passive runtime evidence, explain how features work, and build a version tailored to the user's project. Skip REA setup for ordinary source-repository architecture analysis.
 metadata:
-  version: "14"
-  tool_count: 78
+  version: "22"
+  tool_count: 95
+  catalog_digest: "e0c341749f488a869b62ab9b48c9236c60c91317ac60c8427f12a830cb900ae0"
 ---
 
 # REA
@@ -35,19 +36,87 @@ Electron `file://` pages use `list_electron_targets` and
 filesystem-root authority. Never claim that Electron inspection invoked IPC,
 evaluated renderer JavaScript, navigated, or escaped an approved root.
 
+For an operator-supplied ASAR or extracted JavaScript/Electron application, use
+`analyze_javascript_application` after the operator configures its canonical
+root in `REA_INVESTIGATION_INPUT_ROOTS_JSON`; every call still requires
+`approved: true`. Source-map contents require the independent
+`source_map_read_approved` flag. Treat BrowserWindow preferences, preload and
+contextBridge surfaces, IPC registrations, utility processes, and native
+binding requests as static syntax observations. Treat only a unique exact
+literal IPC channel match as an inferred pairing; keep dynamic and ambiguous
+channels unresolved. A requested `.node` member is not a verified binary export.
+Never claim that this workflow executed application code or observed runtime
+registration, reachability, defaults, or policy enforcement.
+
+When static application Evidence and passive `inspect_web_page` or
+`inspect_electron_page` Evidence already exist, use
+`reconcile_javascript_runtime` to map capture-scoped targets, frames, scripts,
+and workers onto the static graph. Supply exactly one `application` layer and
+add separately analyzed `cache` or `assets` layers only when relevant. Use
+explicit file-root or URL-prefix mappings for relocated runtime paths; mappings
+are inference inputs and never broaden CDP or filesystem authority. Prefer
+approved captured-source digest identity, report path/digest disagreement as a
+mismatch, preserve ambiguity, and never call a module executed merely because
+its containing bundle was observed. Keep source-map authority separate. This
+tool maps JavaScript graph entities; `correlate_static_and_runtime` remains the
+separate workflow for explicit cross-version comparison hypotheses.
+
+Use `trace_application_feature` on authenticated static or reconciled
+application Evidence to follow one literal node ID, route, string, API, IPC
+channel, module, or native export. Choose an explicit direction and bounds.
+Preserve every graph authority in the returned subgraph. A native handoff means
+only that the exact artifact digest and requested export frontier are known;
+link Ghidra or Hopper Evidence only on exact subject digest, and never claim the
+workflow opened a provider or verified a requested export by itself.
+
+Use `compare_application_versions` after analyzing both versions independently.
+Accept only its unique digest, source-map, structural-fingerprint, or non-module
+semantic matches. Never use module ordinals or minified names as persistent
+identity, and never promote an ambiguous candidate to a match. Report added or
+removed only when opposite-side coverage is complete; otherwise report unknown.
+Use `unknown_registry_approved: true` only after approval to retain unresolved
+version matches. For local operator-provided artifacts, the packaged
+`verify:application-workflows` command reports digests and coverage without
+printing source text.
+
+Use `run_controlled_replay` only for operator-selected extracted JavaScript
+modules when the separate `javascript_replay` policy is enabled. First call
+`mode: plan`; review the exact module, stub, runtime, sandbox, case, limit, and
+policy commitments. Execute only with `approved: true` and that exact
+`plan_digest`. Prefer explicit cases plus the parser, sanitizer, or clipboard
+boundary generator. A right manifest produces a derived differential result.
+Treat return values, exceptions, denials, limits, and crashes as observations
+of the isolated experiment with `controlled-replay` authority—not facts about
+the real application. Never substitute passive browser/Electron permission,
+Process Capture, or an in-process `vm` run. Reproducer export requires its own
+literal approval and `evidence_write` authority after sandbox cleanup.
+
 ## Understand the request
 
 Identify the app and what the user wants to understand or build. Do not ask for information they already provided.
 
+First decide whether REA evidence is needed. When the complete source repository
+is available and the request is ordinary source-level architecture, code-flow,
+or implementation analysis, use normal repository tools and skip REA readiness,
+setup, and binary-provider commands. Use REA only when the request needs evidence
+from a binary, package, built artifact, decompilation, passive application
+runtime, controlled replay, or comparison against behavior not established by
+the available source. If the source is available but the requested claim still
+depends on built or runtime behavior, explain that distinction and continue with
+the relevant REA workflow.
+
 If the app is missing, ask which app they want to reverse engineer. If the app is known but the goal is unclear, ask what they want to understand or build, and offer to start with an overview. Never require the user to supply a program path, address, architecture, or reverse-engineering terminology.
 
 Notes is only a documentation example. Never select an app unless the user names it or confirms it.
 
 ## Ensure REA is ready
 
-1. Run `npx -y rea-agents doctor`.
+Run this section only after the request-routing decision establishes that REA
+evidence is needed.
+
+1. Run `npx -y rea-agents@latest doctor`.
 2. If setup is needed, tell the user REA needs to install its local binary-analysis tools. Do not lead with implementation details or assume the user knows reverse-engineering products.
-3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents setup --yes`.
+3. Before installing external software, obtain approval and identify what will be installed. If deeper analysis needs Hopper, describe it as REA's local analysis engine and note that it is a separate Mac app with its own license. Then run `npx -y rea-agents@latest setup --yes`.
 4. If macOS or an installer requests human input, tell the user exactly what needs attention. After they finish, rerun setup and doctor.
 5. If setup registers a new MCP server, tell the user to restart their agent to load all REA tools. Direct CLI commands remain available before restart.
 

package/scripts/prepare-node-pty.mjs

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-
-import { chmod, lstat } from "node:fs/promises";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-if (process.platform !== "win32") {
-  const require = createRequire(import.meta.url);
-  const packageRoot = dirname(
-    require.resolve("node-pty/package.json", {
-      paths: [dirname(fileURLToPath(import.meta.url))],
-    }),
-  );
-  const helperPath = join(
-    packageRoot,
-    "prebuilds",
-    `${process.platform}-${process.arch}`,
-    "spawn-helper",
-  );
-
-  try {
-    const helper = await lstat(helperPath);
-    if (!helper.isFile() || helper.isSymbolicLink()) {
-      throw new Error("node-pty spawn helper is not a regular file");
-    }
-    await chmod(helperPath, helper.mode | 0o111);
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      // Source builds place their correctly-modeled helper under build/Release.
-    } else {
-      throw error;
-    }
-  }
-}

package/scripts/rebuild-native.mjs

@@ -1,22 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from "node:child_process";
-
-const npm = process.platform === "win32" ? "npm.cmd" : "npm";
-const child = spawn(npm, ["rebuild", "node-pty"], {
-  stdio: "inherit",
-  env: { ...process.env, npm_config_build_from_source: "true" },
-});
-
-child.once("error", (error) => {
-  console.error(`Unable to rebuild node-pty: ${error.message}`);
-  process.exitCode = 1;
-});
-child.once("exit", (code, signal) => {
-  if (signal !== null) {
-    console.error(`node-pty rebuild terminated by ${signal}`);
-    process.exitCode = 1;
-    return;
-  }
-  process.exitCode = code ?? 1;
-});