rea-agents 2.2.0 → 2.4.0

package/README.md

@@ -262,7 +262,7 @@ Uninstall preserves Hopper, Node.js, evidence, captures, external evidence roots
 | Inspect or decompile one part of an app from the Terminal        | `rea analyze` or `rea decompile`                                          |
 | Validate, canonicalize, or compare Evidence v2 bundles           | `rea evidence-import`, `rea evidence-export`, or `rea compare`            |
 | Run or resume a persistent two-version artifact analysis         | `rea investigate-versions`                                                |
-| Map a local JavaScript/Electron application without executing it | `rea analyze-javascript-application`                                      |
+| Map a local JavaScript/Electron application without executing it | `rea analyze PATH --approved` or `rea analyze-javascript-application`     |
 | Reuse immutable analysis results without relaunching a provider  | Pass `--snapshot /approved/path/analysis.json` to a deep-analysis command |
 | Import source as historical reference                            | `rea import-reference-source`                                             |
 | Capture or compare controlled process behavior                   | `rea capture-process` or `rea compare-process-captures`                   |
@@ -276,9 +276,21 @@ rea evidence-import /absolute/path/to/evidence/bundle.json
 rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
 rea compare /absolute/path/to/evidence/left.json /absolute/path/to/evidence/right.json
 rea investigate-versions /absolute/path/to/releases/v1 /absolute/path/to/releases/v2 /absolute/path/to/evidence/releases.json --yes --workspace-name releases
+rea analyze /absolute/path/to/releases/app.asar --approved --json
 rea analyze-javascript-application /absolute/path/to/releases/app.asar --approved --json
 ```
 
+For a directory or `.asar`, generic `rea analyze` automatically selects the
+static JavaScript application provider when neither `--provider` nor
+`--snapshot` is supplied. The dedicated command remains available for explicit
+format and resource-limit controls. Both routes require `--approved` and an
+administrator-approved investigation input root.
+
+If REA is registered with an MCP client, run approved `rea setup` while the
+explicit investigation-root variable is set, then restart that client. Setup
+copies this non-secret policy into the managed registration; changing the shell
+environment alone cannot update an already-running MCP process.
+
 `investigate-versions` inventories both versions, checkpoints their observed
 Evidence, derives an artifact comparison, and records a changed-behavior report.
 Both input paths must resolve beneath `REA_INVESTIGATION_INPUT_ROOTS_JSON`;
@@ -364,12 +376,12 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 | Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                                                                                                                          |
 | Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery                                                                                                                   |
 | Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                                                                                                                             |
-| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree                                                                                                                        |
+| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA/MSIX/AppX, and ASAR inventory; explicitly selected extraction into an absent owned tree                                                                                                              |
 | Managed PE/CLI            |     8 | PE/CLI identity, metadata members, CIL hashes, P/Invoke/native-boundary declarations and verification, application-graph projection, decompiler reconstruction import, token remapping, runtime-correlation plans, and version comparison |
 | Browser observation       |     8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence                                                                                                          |
 | Electron analysis         |     4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation                                                                                                                  |
-| Application workflows     |     7 | bounded cross-layer traces, unique-only version matching, approved Linux-isolated extracted-module replay, managed-runtime characterization, and reconstruction coverage closure                                                          |
-| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                                                   |
+| Application workflows     |     9 | bounded cross-layer traces, unique-only version matching, static export return-shape comparison, approved Linux-isolated extracted-module replay, managed-runtime characterization, and reconstruction coverage closure                   |
+| Workspace and observation |    19 | target lifecycle, Evidence v2 bundles, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                          |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
@@ -384,7 +396,7 @@ REA is already useful for native application, browser, and Electron investigatio
 - Validate and canonically serialize a provider-neutral [JavaScript Application Graph v1](docs/javascript-application-graph.md) spanning packages, ASAR entries, Electron roles, JavaScript/source-map entities, browser/runtime instances, IPC, endpoints, storage, and native add-ons. This shipped domain contract performs no extraction or I/O by itself.
 - Reconstruct bounded static package, entrypoint, Webpack/Rspack module, import, worker, endpoint, storage, source-map, BrowserWindow, preload, contextBridge, IPC, utility-process, and native-add-on structure from an approved local directory or ASAR through `analyze_javascript_application` or `rea analyze-javascript-application`. The AST-only [application service](docs/javascript-artifact-reconstruction.md) never executes bootstrap code, pairs only unique exact literal IPC channels, and reports dynamic or ambiguous channels as unresolved.
 - Reconcile that static graph with existing passive web or Electron Evidence through `reconcile_javascript_runtime` or `rea reconcile-javascript-runtime`. Exact captured bytes outrank caller-declared file/URL mappings; target, frame, script, worker, cache, and asset ambiguity stays explicit, source-map authority stays separate, and a module resident in an observed bundle is never reported as executed. See [JavaScript static/runtime reconciliation](docs/javascript-runtime-reconciliation.md).
-- Trace a literal route, string, API, IPC channel, module, or native export through authenticated application Evidence with explicit traversal bounds, then hand exact native artifact digests and requested exports to retained Ghidra or Hopper Evidence without automatic provider switching. Compare application versions using unique-only digest, source-map, structural, and semantic tiers; duplicate, incomplete, and truncated matches stay unknown. See [cross-layer JavaScript application workflows](docs/javascript-application-workflows.md).
+- Trace a literal route, string, API, IPC channel, module, or native export through authenticated application Evidence with explicit traversal bounds, then hand exact native artifact digests and requested exports to retained Ghidra or Hopper Evidence without automatic provider switching. Compare application versions using unique-only digest, source-map, structural, and semantic tiers; compare one exact JavaScript export's static return shapes through unique literal discriminants and bounded JSON Pointer changes. Duplicate, dynamic, incomplete, and truncated facts stay unknown. See [cross-layer JavaScript application workflows](docs/javascript-application-workflows.md).
 - Classify PE/CLI managed artifacts with `inspect_managed_artifact` / `rea inspect-managed-artifact`, inspect bounded metadata members, signatures, raw CIL hashes, limited decoded-instruction-tuple v1 hashes, separately reported exception regions, call edges, and field-access anchors with `inspect_managed_members` / `rea inspect-managed-members`, inventory declared ModuleRef/ImplMap/PInvoke and non-IL method boundary indicators with `inspect_managed_native_boundaries` / `rea inspect-managed-native-boundaries`, then compare two authenticated member observations with `compare_managed_members` / `rea compare-managed-members`. `verify_managed_native_boundaries` / `rea verify-managed-native-boundaries` checks managed P/Invoke declarations against authenticated native export or function Evidence while keeping verified, inferred, contradicted, and unresolved states distinct. The comparison treats build-local tokens as build-local and uses unique decoded-CIL/signature and structural method-shape tiers, never names alone; the v1 tuple hash does not itself resolve tokens or fully commit control flow. `project_managed_application_graph` / `rea project-managed-application-graph` projects authenticated managed artifact/member/native-boundary Evidence into the existing application graph for cross-layer feature tracing. `import_managed_reconstruction` / `rea import-managed-reconstruction` admits user-supplied decompiler C#/IL/pseudocode as analyst inference only after exact artifact SHA-256, MVID, signature, and the shipped v1 decoded-IL commitment match. Separately, `plan_managed_runtime_correlation` / `rea plan-managed-runtime-correlation` can admit a default-disabled, permission-gated runtime-correlation plan locked to the same build evidence. These paths never load the assembly, resolve CLR dependencies, execute target code, run a decompiler, or translate managed tokens into native addresses; full normalized-CIL v2 semantics, native-body bridge mapping, and an actual runtime executor remain future managed-code contracts.
 - Configure `REA_ILSPY_CMD_PATH=/absolute/path/to/ilspycmd` only when you want
   doctor and `verify:managed` to inspect a bring-your-own ILSpy command as a
@@ -397,6 +409,7 @@ REA is already useful for native application, browser, and Electron investigatio
 - Export and import evidence bundles across sessions.
 - Persist automatic cross-version artifact runs as canonical, lock-protected workspaces with tamper-evident revision commitments.
 - Capture approved PTY scenarios as Process Capture v4 Evidence, including committed run manifests, raw and rendered terminal frames, scripted interactions, descendant settlement, named filesystem checkpoints, deterministic command shims, and loopback HTTP/WebSocket exchanges.
+- Validate finite replay machines without launching a target through `run_replay_machine` or `rea run-replay-machine`; ordered events return typed decisions, actions, captured aliases, transition journals, final state, and exact limit use without echoing request or captured values.
 - Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence.
 - Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns.
 - Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence.
@@ -425,7 +438,7 @@ rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json
 
 All eight browser tools expose the same Evidence v2 contracts over CLI and MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. Query values, credentials, cookies, authorization headers, storage values, and raw JSON or WebSocket values are never retained. Separately approved captures can retain bounded redacted console primitives, value-free JSON/WebSocket shapes, script sources, accessibility text, or screenshot pixels. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model.
 
-Exact package, tool-family, provider, setup-client, public schema-version, and CLI facts are generated from source in [`docs/product-catalog.json`](docs/product-catalog.json). `npm run docs:check` verifies that this catalog, the narrative documentation, TypeDoc, and generated schemas have not drifted.
+Exact package, tool-family, provider, setup-client, public schema-version, and CLI facts are generated from source in [`docs/product-catalog.json`](docs/product-catalog.json). PR CI verifies this catalog, narrative documentation, generated schemas, and a clean TypeDoc render.
 
 ## Roadmap
 
@@ -466,7 +479,7 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@2.2.0", "mcp"]
+      "args": ["-y", "rea-agents@2.4.0", "mcp"]
     }
   }
 }
@@ -572,8 +585,15 @@ operations still work. An explicit unknown, unavailable, or unsupported
 provider fails with candidate IDs, stable rejection codes, and actionable local
 diagnostics. `binary_session`, `rea providers`, and `rea capabilities` expose
 the authoritative `analysis_provider_candidates` and
-`analysis_provider_binding` fields. Reopening the same target without a selector
-keeps its binding; runtime failure never selects another provider silently.
+`analysis_provider_binding` fields. Each open target also has an
+`analysis_run.run_id` allocated before provider startup. When dynamic providers
+start, `analysis_run.process_lineage` changes from `not_observed` to `snapshots`
+and retains one provider-attributed, token-verified observation per started
+provider. Each observation carries `observed_at` and remains `unavailable` or
+`verified`; a verified empty descendant list is distinct from both. Snapshots
+describe bounded observations, not current live state or historical absence.
+Reopening same target without a selector keeps its binding; runtime failure
+never selects another provider silently.
 Ghidra can appear as an available, target-compatible candidate after doctor
 validates its exact installation. Its capability list contains the 18 admitted
 read-only inventory and function-analysis operations; selecting it still does
@@ -705,13 +725,40 @@ Any agent that can run a local MCP server can use the manual configuration. Setu
 
 ## Development
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, tests, and release instructions. Generated API documentation is available under [`docs/api`](docs/api/index.html).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, architecture, tests, and release instructions. PR CI publishes generated API documentation as the `api-docs` workflow artifact.
 
 `npm run verify:agent` runs brandless native, JavaScript-application, managed,
 and browser prompts through a real local Codex CLI. Its JSON report measures
 natural MCP use, first-tool routing, repeated calls, actual Codex token usage,
 completion quality, and explicit treatment of authority and unknowns.
 
+`npm run evidence:generate` regenerates the managed conformance manifest and
+Evidence v2 completion ledger from live verifier output. `npm run
+evidence:check` reruns the verifier and fails when artifacts, scenarios,
+providers, schemas, claim counts, Evidence IDs, or the bundled skill have
+drifted. Unsupported claims remain explicit and never count as passes.
+Verifier JSON reports include an ephemeral `verifier_run` UUID allocated before
+the verifier performs work and inherited by its child processes through
+`REA_PROCESS_RUN_ID`. The final report includes the verifier and parent PIDs
+plus `process_lineage` and its ISO `observed_at` timestamp: POSIX verifiers
+report a token-verified, point-in-time launcher process group and live
+descendants, while platforms without an owned
+lineage primitive report `status: "unavailable"` and a reason. An empty verified
+descendant list means no child was live during the final observation; it does
+not claim the verifier launched no children earlier. Nested verifier entrypoints
+in the same process reuse its UUID; each new verifier process replaces any
+inherited parent token with a fresh run identity.
+Generated completion commitments deliberately exclude this per-execution
+identity, so check mode remains deterministic while live reports remain
+attributable.
+
+Owned Hopper shutdown logs retain the launcher PID, process-group ID, cleanup
+status, and whether a verified group signal was required. They omit the run
+token and unexpected exception text. The real-Hopper verifier also starts an
+unrelated `Hopper`-named sentinel in a distinct process group and fails unless
+that process survives every session close; the sentinel is removed only by the
+verifier after the survival check.
+
 ## Project links
 
 [npm](https://www.npmjs.com/package/rea-agents) · [Issues](https://github.com/morluto/rea/issues) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [Hopper](https://www.hopperapp.com/) · [Ghidra](https://github.com/NationalSecurityAgency/ghidra)

package/dist/application/ApplicationWorkflowEvidenceResolver.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { compareApplicationVersionsRequestSchema, compareJavaScriptExportShapesRequestSchema, traceApplicationFeatureRequestSchema, traceJavaScriptSemanticsRequestSchema, } from "../contracts/applicationWorkflowInputContracts.js";
+import { AnalysisInputError } from "../domain/errors.js";
+import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { compareApplicationVersionsInputSchema } from "../domain/javascriptApplicationVersionComparisonSchemas.js";
+import { compareJavaScriptExportShapesInputSchema } from "../domain/javascriptExportShapeComparisonSchemas.js";
+import { traceApplicationFeatureInputSchema } from "../domain/javascriptFeatureTraceSchemas.js";
+import { traceJavaScriptSemanticsInputSchema } from "../domain/javascriptSemanticTraceSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { resolveEvidenceReferences, } from "./EvidenceReferenceResolver.js";
+const APPLICATION_GRAPH_IDENTITIES = [
+    {
+        operation: "analyze_javascript_application",
+        predicate: "rea.javascript-application-analysis/v1",
+    },
+    {
+        operation: "analyze_javascript_application",
+        predicate: "rea.javascript-application-analysis/v2",
+    },
+    {
+        operation: "reconcile_javascript_runtime",
+        predicate: "rea.javascript-runtime-reconciliation/v1",
+    },
+    {
+        operation: "project_managed_application_graph",
+        predicate: "rea.managed-application-graph/v1",
+    },
+];
+/** Parse and resolve one trace adapter request into its canonical domain input. */
+export const resolveTraceApplicationFeatureRequest = (input, lookup) => {
+    const parsed = traceApplicationFeatureRequestSchema.safeParse(input);
+    return parsed.success
+        ? resolveTraceApplicationFeatureRequestValidated(parsed.data, lookup)
+        : invalid("trace_application_feature", parsed.error, input);
+};
+/** Resolve a trace request already parsed by the caller-facing contract. */
+export const resolveTraceApplicationFeatureRequestValidated = (input, lookup) => {
+    const application = input.application === undefined
+        ? resolveEvidenceReferences(lookup, input.application_evidence_id === undefined
+            ? []
+            : [input.application_evidence_id], APPLICATION_GRAPH_IDENTITIES)
+        : ok([input.application]);
+    if (!application.ok)
+        return application;
+    const native = resolveEvidenceReferences(lookup, input.native_observation_evidence_ids);
+    if (!native.ok)
+        return native;
+    const raw = {
+        application: application.value[0],
+        native_observations: [...input.native_observations, ...native.value],
+        seed: input.seed,
+        direction: input.direction,
+        limits: input.limits,
+    };
+    const parsed = traceApplicationFeatureInputSchema.safeParse(raw);
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("trace_application_feature", parsed.error, raw);
+};
+/** Parse and resolve one semantic trace adapter request. */
+export const resolveTraceJavaScriptSemanticsRequest = (input, lookup) => {
+    const parsed = traceJavaScriptSemanticsRequestSchema.safeParse(input);
+    return parsed.success
+        ? resolveTraceJavaScriptSemanticsRequestValidated(parsed.data, lookup)
+        : invalid("trace_javascript_semantics", parsed.error, input);
+};
+/** Resolve a semantic trace request already parsed by its public contract. */
+export const resolveTraceJavaScriptSemanticsRequestValidated = (input, lookup) => {
+    const application = input.application === undefined
+        ? resolveEvidenceReferences(lookup, input.application_evidence_id === undefined
+            ? []
+            : [input.application_evidence_id], APPLICATION_GRAPH_IDENTITIES)
+        : ok([input.application]);
+    if (!application.ok)
+        return application;
+    const raw = { application: application.value[0], query: input.query };
+    const parsed = traceJavaScriptSemanticsInputSchema.safeParse(raw);
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("trace_javascript_semantics", parsed.error, raw);
+};
+/** Parse and resolve one comparison adapter request into canonical input. */
+export const resolveCompareApplicationVersionsRequest = (input, lookup) => {
+    const parsed = compareApplicationVersionsRequestSchema.safeParse(input);
+    return parsed.success
+        ? resolveCompareApplicationVersionsRequestValidated(parsed.data, lookup)
+        : invalid("compare_application_versions", parsed.error, input);
+};
+/** Resolve a comparison request parsed by the caller-facing contract. */
+export const resolveCompareApplicationVersionsRequestValidated = (input, lookup) => {
+    const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+    if (!left.ok)
+        return left;
+    const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+    if (!right.ok)
+        return right;
+    const leftNative = resolveEvidenceReferences(lookup, input.left_native_observation_evidence_ids);
+    if (!leftNative.ok)
+        return leftNative;
+    const rightNative = resolveEvidenceReferences(lookup, input.right_native_observation_evidence_ids);
+    if (!rightNative.ok)
+        return rightNative;
+    const raw = {
+        left: left.value,
+        right: right.value,
+        left_native_observations: [
+            ...input.left_native_observations,
+            ...leftNative.value,
+        ],
+        right_native_observations: [
+            ...input.right_native_observations,
+            ...rightNative.value,
+        ],
+        limits: input.limits,
+        ...(input.unknown_registry_approved === undefined
+            ? {}
+            : { unknown_registry_approved: input.unknown_registry_approved }),
+    };
+    const parsed = compareApplicationVersionsInputSchema.safeParse(raw);
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("compare_application_versions", parsed.error, raw);
+};
+/** Parse and resolve an export-shape adapter request into canonical input. */
+export const resolveCompareJavaScriptExportShapesRequest = (input, lookup) => {
+    const parsed = compareJavaScriptExportShapesRequestSchema.safeParse(input);
+    return parsed.success
+        ? resolveCompareJavaScriptExportShapesRequestValidated(parsed.data, lookup)
+        : invalid("compare_javascript_export_shapes", parsed.error, input);
+};
+/** Resolve an export-shape request already parsed by the adapter contract. */
+export const resolveCompareJavaScriptExportShapesRequestValidated = (input, lookup) => {
+    const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+    if (!left.ok)
+        return left;
+    const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+    if (!right.ok)
+        return right;
+    const raw = {
+        left: left.value,
+        right: right.value,
+        left_module_path: input.left_module_path,
+        left_export_name: input.left_export_name,
+        right_module_path: input.right_module_path,
+        right_export_name: input.right_export_name,
+        limits: input.limits,
+        ...(input.unknown_registry_approved === undefined
+            ? {}
+            : { unknown_registry_approved: input.unknown_registry_approved }),
+    };
+    const parsed = compareJavaScriptExportShapesInputSchema.safeParse(raw);
+    return parsed.success
+        ? ok(parsed.data)
+        : invalid("compare_javascript_export_shapes", parsed.error, raw);
+};
+const graphEvidence = (evidence, evidenceId, lookup) => {
+    if (evidence !== undefined)
+        return ok(evidence);
+    const resolved = resolveEvidenceReferences(lookup, evidenceId === undefined ? [] : [evidenceId], APPLICATION_GRAPH_IDENTITIES);
+    return resolved.ok ? ok(resolved.value[0]) : resolved;
+};
+const invalid = (operation, cause, input) => err(new AnalysisInputError(operation, undefined, projectInputIssues(cause.issues, input)));

package/dist/application/ArtifactExtraction.js

@@ -140,7 +140,11 @@ const createReader = async (path, format) => {
         return new DirectoryArtifactReader(path);
     if (format === "asar")
         return new AsarArtifactReader(path);
-    if (format === "ipa" || format === "apk" || format === "zip")
+    if (format === "ipa" ||
+        format === "apk" ||
+        format === "msix" ||
+        format === "appx" ||
+        format === "zip")
         return new ZipArtifactReader(path, format);
     if (format === "mach-o")
         return new MachOSliceArtifactReader(path);

package/dist/application/ArtifactGraphConstruction.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { extname } from "node:path";
 import canonicalize from "canonicalize";
+import { zipPackageFormatForPath } from "../domain/zipPackageFormat.js";
 /** Index the first occurrence for each canonical logical path. */
 export const indexOccurrencesByPath = (occurrences) => {
     const byPath = new Map();
@@ -74,7 +74,7 @@ export const createRootNode = (input) => createArtifactNode({
         }),
     size: input.digest?.bytes ?? 0,
     kind: input.directory ||
-        ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(input.format)
+        ["zip", "ipa", "apk", "msix", "appx", "asar", "dmg", "pkg"].includes(input.format)
         ? "container"
         : classifyArtifactPath(input.path).kind,
     format: input.format,
@@ -174,7 +174,7 @@ export const classifyArtifactPath = (path) => {
         return { kind: "javascript", format: "javascript-bundle" };
     if (lower.endsWith(".asar"))
         return { kind: "container", format: "asar" };
-    const archiveFormat = archiveFormatForExtension(extname(lower));
+    const archiveFormat = zipPackageFormatForPath(lower);
     if (archiveFormat !== undefined)
         return { kind: "container", format: archiveFormat };
     if (/\.framework(?:\/|$)/u.test(lower))
@@ -251,16 +251,4 @@ const relationFor = (path) => {
         return "embeds";
     return "contains";
 };
-const archiveFormatForExtension = (extension) => {
-    switch (extension) {
-        case ".zip":
-            return "zip";
-        case ".ipa":
-            return "ipa";
-        case ".apk":
-            return "apk";
-        default:
-            return undefined;
-    }
-};
 const depth = (path) => path.split("/").length;

package/dist/application/ArtifactInventory/classify.js

@@ -1,8 +1,12 @@
 import { open } from "node:fs/promises";
 import { classifyArtifactPath } from "../ArtifactGraphConstruction.js";
+import { zipPackageFormatForPath } from "../../domain/zipPackageFormat.js";
 const classifyContainerExtension = (path) => {
     const lower = path.toLowerCase();
-    for (const format of ["asar", "ipa", "apk", "zip", "dmg", "pkg"])
+    const zipPackage = zipPackageFormatForPath(lower);
+    if (zipPackage !== undefined)
+        return zipPackage;
+    for (const format of ["asar", "dmg", "pkg"])
         if (lower.endsWith(`.${format}`))
             return format;
     return undefined;

package/dist/application/ArtifactInventory/reader.js

@@ -11,6 +11,8 @@ export const createReader = async (path, format, nativeMount, signal) => {
         case "zip":
         case "ipa":
         case "apk":
+        case "msix":
+        case "appx":
             return new ZipArtifactReader(path, format);
         case "asar":
             return new AsarArtifactReader(path);

package/dist/application/BinarySession.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { analysisProfilesEqual, } from "../domain/analysisProfile.js";
 import { AnalysisCancelledError, ProviderAdapterError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
@@ -116,7 +117,8 @@ export class BinarySession extends BinarySessionRecords {
             const previous = this.#active;
             this.#active = undefined;
             await previous?.client.close();
-            const client = route.createClient(target);
+            const runId = randomUUID();
+            const client = route.createClient(target, { runId });
             const started = await client.execute("health", {}, options);
             if (!started.ok) {
                 await client.close();
@@ -134,6 +136,7 @@ export class BinarySession extends BinarySessionRecords {
                 profile,
                 compatibility: structuredClone(compatibility),
                 route,
+                runId,
             };
             this.#clearRuntimeAvailability();
             if (profile === null)
@@ -172,6 +175,8 @@ export class BinarySession extends BinarySessionRecords {
             route: this.#currentRoute(),
             router: this.#providerRouter,
             runtimeAvailability: this.#runtimeAvailability,
+            runId: this.#active?.runId,
+            runtimeLineageSnapshots: this.#active?.client.runtimeLineageSnapshots?.() ?? [],
         });
     }
     /** Return the immutable artifact identity captured before its provider started. */
@@ -300,7 +305,8 @@ export class BinarySession extends BinarySessionRecords {
     async #restore(previous) {
         if (previous === undefined)
             return;
-        const client = previous.route.createClient(previous.target);
+        const runId = randomUUID();
+        const client = previous.route.createClient(previous.target, { runId });
         const started = await client.execute("health", {});
         if (started.ok)
             this.#active = {
@@ -309,6 +315,7 @@ export class BinarySession extends BinarySessionRecords {
                 profile: previous.profile,
                 compatibility: previous.compatibility,
                 route: previous.route,
+                runId,
             };
         else
             await client.close();

package/dist/application/BinarySessionStatus.js

@@ -1,5 +1,5 @@
 /** Project internal provider routing state into the caller-visible session status. */
-export const binarySessionStatus = ({ target, route, router, runtimeAvailability, }) => {
+export const binarySessionStatus = ({ target, route, router, runtimeAvailability, runId, runtimeLineageSnapshots, }) => {
     const configuredProvider = router.configuredIdentity();
     const provider = providerSummary(configuredProvider);
     const providers = router.providerIdentities(route).map(providerSummary);
@@ -35,6 +35,12 @@ export const binarySessionStatus = ({ target, route, router, runtimeAvailability
         capabilities,
         analysis_provider_binding: analysisProviderBinding,
         analysis_provider_candidates: analysisProviderCandidates,
+        analysis_run: runId === undefined
+            ? null
+            : {
+                run_id: runId,
+                process_lineage: processLineageStatus(runtimeLineageSnapshots),
+            },
     };
     return target === undefined
         ? { open: false, ...common }
@@ -49,10 +55,43 @@ export const binarySessionStatus = ({ target, route, router, runtimeAvailability
         };
 };
 const providerSummary = ({ id, name, version, }) => ({ id, name, version });
+const processLineageStatus = (snapshots) => snapshots.length === 0
+    ? { status: "not_observed" }
+    : {
+        status: "snapshots",
+        snapshots: snapshots
+            .slice()
+            .sort((left, right) => left.provider.id.localeCompare(right.provider.id))
+            .map(({ provider, observation }) => ({
+            provider: providerSummary(provider),
+            observation: observation.status === "unavailable"
+                ? {
+                    status: observation.status,
+                    observed_at: observation.observedAt,
+                    launcher_pid: observation.launcherPid,
+                    process_group_id: observation.processGroupId,
+                    reason: observation.reason,
+                }
+                : {
+                    status: observation.status,
+                    observed_at: observation.observedAt,
+                    schema_version: observation.lineage.schemaVersion,
+                    launcher_pid: observation.lineage.launcherPid,
+                    launcher_parent_pid: observation.lineage.launcherParentPid,
+                    process_group_id: observation.lineage.processGroupId,
+                    descendants: observation.lineage.descendants.map(({ pid, parentPid, processGroupId }) => ({
+                        pid,
+                        parent_pid: parentPid,
+                        process_group_id: processGroupId,
+                    })),
+                },
+        })),
+    };
 const capabilityStatus = (descriptor) => ({
     operation: descriptor.operation,
     available: descriptor.available,
     reason: descriptor.reason,
+    availability_code: descriptor.availabilityCode ?? null,
     input_contract_version: descriptor.inputContractVersion,
     output_contract_version: descriptor.outputContractVersion,
     pagination: descriptor.pagination,

package/dist/application/CapabilityInventory.js

@@ -8,6 +8,7 @@ const statusSchema = z.object({
         operation: z.string(),
         available: z.boolean(),
         reason: z.string().nullable(),
+        availability_code: z.string().nullable().optional(),
     })),
 });
 const ENHANCED_REQUIREMENTS = {
@@ -35,7 +36,14 @@ const ENHANCED_REQUIREMENTS = {
 /** Build stable per-operation availability without hiding familiar tools. */
 export const buildCapabilityInventory = (sessionStatus, policy) => {
     const status = statusSchema.parse(sessionStatus);
-    const descriptors = new Map(status.capabilities.map((descriptor) => [descriptor.operation, descriptor]));
+    const descriptors = new Map(status.capabilities.map((descriptor) => [
+        descriptor.operation,
+        {
+            available: descriptor.available,
+            reason: descriptor.reason,
+            availability_code: descriptor.availability_code ?? null,
+        },
+    ]));
     return TOOL_CONTRACTS.map((contract) => {
         const availability = availabilityFor({
             name: contract.name,
@@ -62,6 +70,9 @@ export const buildCapabilityInventory = (sessionStatus, policy) => {
     }).sort((left, right) => left.name.localeCompare(right.name));
 };
 const availabilityFor = (context) => {
+    const javascriptApplication = javascriptApplicationAvailability(context);
+    if (javascriptApplication !== null)
+        return javascriptApplication;
     const policyDecision = policyAvailability(context);
     if (policyDecision !== null)
         return policyDecision;
@@ -70,6 +81,18 @@ const availabilityFor = (context) => {
         return targetDecision;
     return providerAvailability(context);
 };
+const javascriptApplicationAvailability = ({ name, policy, }) => {
+    if (name === "analyze_javascript_application")
+        return policy.investigationInputRoots === 0
+            ? {
+                reason: "policy_disabled",
+                remediation: "Configure an exact REA_INVESTIGATION_INPUT_ROOTS_JSON root in the MCP registration, then restart the registered MCP server or client.",
+            }
+            : { reason: "available", remediation: null };
+    return name === "reconcile_javascript_runtime"
+        ? { reason: "available", remediation: null }
+        : null;
+};
 const policyAvailability = ({ name, kind, policy, }) => {
     if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
         return {
@@ -142,7 +165,7 @@ const providerAvailability = ({ descriptors, kind, name, }) => {
             remediation: "Install or configure a provider that declares this operation.",
         };
     if (!descriptor.available &&
-        descriptor.reason?.toLowerCase().includes("require macos") === true)
+        descriptor.availability_code === "unsupported_host")
         return {
             reason: "unsupported_host",
             remediation: descriptor.reason,
@@ -172,7 +195,7 @@ const composedAvailability = (name, descriptors) => {
         .find((descriptor) => descriptor?.available === false);
     if (unavailable !== undefined)
         return {
-            reason: unavailable.reason?.toLowerCase().includes("require macos") === true
+            reason: unavailable.availability_code === "unsupported_host"
                 ? "unsupported_host"
                 : "provider_unavailable",
             remediation: unavailable.reason ?? "Choose another target or configured provider.",

package/dist/application/CommandShimReplay.js

@@ -27,7 +27,7 @@ const shellQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
  * would make an unmatched dependency call look authoritative. Unmatched and
  * exhausted routes therefore fail visibly and remain part of the capture.
  */
-export const startCommandShimReplay = async (scenario, temporaryRoot, started) => {
+export const startCommandShimReplay = async (scenario, temporaryRoot, started, recordEvent = () => undefined) => {
     const binPath = join(temporaryRoot, "shims");
     await mkdir(binPath);
     const runnerPath = join(temporaryRoot, "shim-runner.mjs");
@@ -62,9 +62,10 @@ export const startCommandShimReplay = async (scenario, temporaryRoot, started) =
                     : "matched";
             if (events.length >= scenario.limits.protocol_events)
                 truncated = true;
-            else
+            else {
+                const index = events.length;
                 events.push({
-                    sequence: events.length,
+                    sequence: index,
                     at_ms: Math.max(0, Date.now() - started),
                     command: invocation.command,
                     route_index: routeIndex !== undefined && routeIndex >= 0 ? routeIndex : null,
@@ -72,6 +73,8 @@ export const startCommandShimReplay = async (scenario, temporaryRoot, started) =
                     working_directory: invocation.working_directory,
                     outcome,
                 });
+                recordEvent("shim_events", index);
+            }
             if (outcome !== "matched" || route === undefined) {
                 response.writeHead(409).end();
                 return;

package/dist/application/CompositeProvider.js

@@ -51,13 +51,13 @@ export class CompositeProvider {
             ? Promise.resolve(ok({ profile: null, compatibility: {} }))
             : resolve.call(this.#profileProvider, target, options);
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         const clients = new Map();
         const clientFor = (provider) => {
             const existing = clients.get(provider);
             if (existing !== undefined)
                 return existing;
-            const created = provider.createClient(target, profile?.provider.id === provider.identity().id ? profile : undefined);
+            const created = provider.createClient(target, profile?.provider.id === provider.identity().id ? profile : undefined, context);
             clients.set(provider, created);
             return created;
         };
@@ -77,6 +77,9 @@ export class CompositeProvider {
                     ? Promise.resolve(err(new AnalysisCapabilityUnavailableError(this.#identity.id, operation, "operation is not declared by this provider set")))
                     : clientFor(provider).execute(operation, parameters, options);
             },
+            runtimeLineageSnapshots: () => [...clients.values()]
+                .flatMap((client) => client.runtimeLineageSnapshots?.() ?? [])
+                .sort((left, right) => left.provider.id.localeCompare(right.provider.id)),
             close: async () => {
                 await Promise.allSettled([...clients.values()].map(async (client) => client.close()));
             },