rea-agents 2.2.0 → 2.3.0

package/dist/mcpDoctor.js

@@ -0,0 +1,310 @@
+import { Client } from "@modelcontextprotocol/client";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { Formatter } from "incur";
+import { resolve } from "node:path";
+import { CATALOG_IDENTITY, MCP_RESOURCE_CATALOG, MCP_RESOURCE_TEMPLATE_CATALOG, } from "./catalogIdentity.js";
+import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
+import { PRODUCT_IDENTITY } from "./identity.js";
+const DEFAULT_DEADLINE_MS = 20_000;
+const STDERR_LIMIT_BYTES = 64 * 1_024;
+const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"];
+/** Diagnose the actual production stdio adapter with one bounded SDK session. */
+export const runProductionMcpDoctor = async (options) => {
+    const deadline = Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("Production MCP doctor deadline expired")), Math.max(1, deadline - Date.now()));
+    const stderr = boundedStderr();
+    const transport = new TrackedStdioClientTransport({
+        command: options.command,
+        args: [...options.args],
+        cwd: options.cwd,
+        env: targetFreeEnvironment(options.environment),
+        stderr: "pipe",
+    });
+    transport.stderr?.on("data", stderr.append);
+    const client = new Client({ name: "rea-mcp-doctor", version: "1" });
+    try {
+        await client.connect(transport, requestOptions(deadline, controller.signal));
+        return {
+            ...(await inspectProductionMcpSession(client, deadline, controller.signal)),
+            diagnostics: stderr.value(),
+        };
+    }
+    catch (cause) {
+        return {
+            healthy: false,
+            adapter: "production-stdio",
+            server: null,
+            inventory: null,
+            identity: null,
+            request_flow: { tool: "binary_session", ok: false },
+            checks: [
+                {
+                    name: "transport",
+                    ok: false,
+                    detail: errorMessage(cause),
+                },
+            ],
+            diagnostics: stderr.value(),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        await closeMcpChild(client, transport);
+    }
+};
+const inspectProductionMcpSession = async (client, deadline, signal) => {
+    const request = requestOptions(deadline, signal);
+    const [tools, prompts, resources, templates, identity, requestFlow] = await Promise.all([
+        client.listTools(undefined, request),
+        client.listPrompts(undefined, request),
+        client.listResources(undefined, request),
+        client.listResourceTemplates(undefined, request),
+        client.readResource({ uri: "rea://server/identity" }, request),
+        client.callTool({ name: "binary_session", arguments: {} }, request),
+    ]);
+    const inventory = {
+        tools: compareInventory(CATALOG_IDENTITY.tools.map(({ name }) => name), tools.tools.map(({ name }) => name)),
+        prompts: compareInventory(PROMPT_CONTRACTS.map(({ name }) => name), prompts.prompts.map(({ name }) => name)),
+        resources: compareInventory(MCP_RESOURCE_CATALOG.map(({ name }) => name), resources.resources.map(({ name }) => name)),
+        resource_templates: compareInventory(MCP_RESOURCE_TEMPLATE_CATALOG.map(({ name }) => name), templates.resourceTemplates.map(({ name }) => name)),
+    };
+    const observedIdentity = parseIdentityResource(identity.contents);
+    const serverVersion = client.getServerVersion();
+    const protocolVersion = client.getNegotiatedProtocolVersion();
+    const checks = [
+        {
+            name: "initialize",
+            ok: serverVersion?.name === PRODUCT_IDENTITY.mcpServerKey &&
+                serverVersion.version === PRODUCT_IDENTITY.packageVersion &&
+                protocolVersion !== undefined,
+            detail: `${serverVersion?.name ?? "unknown"}@${serverVersion?.version ?? "unknown"}; protocol=${protocolVersion ?? "unknown"}`,
+        },
+        ...Object.entries(inventory).map(([name, comparison]) => inventoryCheck(name, comparison)),
+        {
+            name: "server-identity",
+            ok: observedIdentity.packageVersion === PRODUCT_IDENTITY.packageVersion &&
+                observedIdentity.catalogDigest ===
+                    CATALOG_IDENTITY.digests.combined_sha256,
+            detail: `package=${observedIdentity.packageVersion ?? "missing"}; catalog=${observedIdentity.catalogDigest ?? "missing"}`,
+        },
+        {
+            name: "request-flow",
+            ok: requestFlow.isError !== true,
+            detail: "binary_session target-free request",
+        },
+    ];
+    return {
+        healthy: checks.every(({ ok }) => ok),
+        adapter: "production-stdio",
+        server: {
+            name: serverVersion?.name ?? null,
+            version: serverVersion?.version ?? null,
+            protocol_version: protocolVersion ?? null,
+        },
+        inventory,
+        identity: {
+            expected_package_version: PRODUCT_IDENTITY.packageVersion,
+            observed_package_version: observedIdentity.packageVersion,
+            expected_catalog_digest: CATALOG_IDENTITY.digests.combined_sha256,
+            observed_catalog_digest: observedIdentity.catalogDigest,
+        },
+        request_flow: {
+            tool: "binary_session",
+            ok: requestFlow.isError !== true,
+        },
+        checks,
+    };
+};
+/**
+ * Dispatcher entry for `rea mcp doctor`, kept separate from Incur MCP setup.
+ * @public
+ */
+export const runProductionMcpDoctorCli = async (arguments_, input) => {
+    const parsed = parseOutputArguments(arguments_);
+    if (!parsed.ok)
+        return {
+            output: `${Formatter.format({ code: "VALIDATION_ERROR", message: parsed.message }, parsed.format)}\n`,
+            exitCode: 1,
+        };
+    const result = await runProductionMcpDoctor({
+        command: process.execPath,
+        args: [resolve(input.dispatcherPath), "mcp"],
+        cwd: input.packageRoot,
+        environment: process.env,
+    });
+    return {
+        output: `${Formatter.format(result, parsed.format)}\n`,
+        exitCode: result.healthy ? 0 : 1,
+    };
+};
+/** Compare exact names while retaining actionable mismatch locations. */
+export const compareInventory = (expectedNames, observedNames) => {
+    const expected = new Set(expectedNames);
+    const observed = new Set(observedNames);
+    return {
+        expected: expectedNames.length,
+        observed: observedNames.length,
+        missing: [...expected].filter((name) => !observed.has(name)).sort(),
+        unexpected: [...observed].filter((name) => !expected.has(name)).sort(),
+        duplicates: [...observed]
+            .filter((name) => observedNames.filter((candidate) => candidate === name).length > 1)
+            .sort(),
+    };
+};
+const inventoryCheck = (name, comparison) => ({
+    name: `inventory:${name}`,
+    ok: comparison.expected === comparison.observed &&
+        comparison.missing.length === 0 &&
+        comparison.unexpected.length === 0 &&
+        comparison.duplicates.length === 0,
+    detail: `expected=${String(comparison.expected)} observed=${String(comparison.observed)} missing=${comparison.missing.join(",") || "none"} unexpected=${comparison.unexpected.join(",") || "none"} duplicates=${comparison.duplicates.join(",") || "none"}`,
+});
+const parseIdentityResource = (contents) => {
+    const first = contents.find((candidate) => isRecord(candidate) && typeof candidate.text === "string");
+    if (!isRecord(first) || typeof first.text !== "string")
+        return { packageVersion: null, catalogDigest: null };
+    try {
+        const identity = JSON.parse(first.text);
+        if (!isRecord(identity))
+            return { packageVersion: null, catalogDigest: null };
+        const packageIdentity = identity.package;
+        const catalog = identity.catalog;
+        const digests = isRecord(catalog) ? catalog.digests : undefined;
+        return {
+            packageVersion: isRecord(packageIdentity) && typeof packageIdentity.version === "string"
+                ? packageIdentity.version
+                : null,
+            catalogDigest: isRecord(digests) && typeof digests.combined_sha256 === "string"
+                ? digests.combined_sha256
+                : null,
+        };
+    }
+    catch {
+        return { packageVersion: null, catalogDigest: null };
+    }
+};
+const parseOutputArguments = (arguments_) => {
+    let format = "toon";
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--json") {
+            format = "json";
+            continue;
+        }
+        const inline = argument?.startsWith("--format=")
+            ? argument.slice("--format=".length)
+            : undefined;
+        if (argument === "--format" || inline !== undefined) {
+            const candidate = inline ?? arguments_[index + 1];
+            if (inline === undefined)
+                index += 1;
+            if (!isOutputFormat(candidate))
+                return {
+                    ok: false,
+                    format,
+                    message: `Invalid output format: ${candidate ?? "missing"}`,
+                };
+            format = candidate;
+            continue;
+        }
+        if (argument === "--full-output")
+            continue;
+        return {
+            ok: false,
+            format,
+            message: `Unknown mcp doctor option: ${argument ?? "missing"}`,
+        };
+    }
+    return { ok: true, format };
+};
+const isOutputFormat = (value) => OUTPUT_FORMATS.some((candidate) => candidate === value);
+const requestOptions = (deadline, signal) => ({
+    signal,
+    timeout: Math.max(1, deadline - Date.now()),
+});
+const targetFreeEnvironment = (environment) => {
+    const result = Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+    for (const name of [
+        "HOPPER_TARGET_PATH",
+        "HOPPER_TARGET_KIND",
+        "HOPPER_LOADER_ARGS_JSON",
+    ])
+        delete result[name];
+    return result;
+};
+const boundedStderr = () => {
+    let text = "";
+    let bytes = 0;
+    let truncated = false;
+    return {
+        append(chunk) {
+            const buffer = Buffer.isBuffer(chunk)
+                ? chunk
+                : Buffer.from(String(chunk), "utf8");
+            bytes += buffer.byteLength;
+            const retained = Buffer.byteLength(text, "utf8");
+            if (retained < STDERR_LIMIT_BYTES)
+                text += buffer
+                    .subarray(0, STDERR_LIMIT_BYTES - retained)
+                    .toString("utf8");
+            if (bytes > STDERR_LIMIT_BYTES)
+                truncated = true;
+        },
+        value: () => ({
+            stderr: text,
+            stderr_bytes: bytes,
+            stderr_truncated: truncated,
+        }),
+    };
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+class TrackedStdioClientTransport extends StdioClientTransport {
+    spawnedPid = null;
+    async start() {
+        await super.start();
+        this.spawnedPid = this.pid;
+    }
+}
+const closeMcpChild = async (client, transport) => {
+    const pid = transport.spawnedPid ?? transport.pid;
+    await Promise.allSettled([client.close()]);
+    await Promise.allSettled([transport.close()]);
+    if (pid === null || !(await processExists(pid)))
+        return;
+    await terminateProcess(pid, "SIGTERM");
+    if (await waitForProcessExit(pid, 1_000))
+        return;
+    await terminateProcess(pid, "SIGKILL");
+    await waitForProcessExit(pid, 1_000);
+};
+const terminateProcess = async (pid, signal) => {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ESRCH"))
+            throw cause;
+    }
+};
+const waitForProcessExit = async (pid, timeoutMs) => {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        if (!(await processExists(pid)))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+    } while (Date.now() < deadline);
+    return !(await processExists(pid));
+};
+const processExists = async (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ESRCH")
+            return false;
+        throw cause;
+    }
+};

package/dist/process/ProcessOwnership.js

@@ -44,7 +44,7 @@ export const parseProcessEnvironment = (value) => Object.fromEntries(value
     return [entry.slice(0, separator), entry.slice(separator + 1)];
 }));
 const systemHost = {
-    async listMembers(processGroupId) {
+    async listProcesses() {
         if (process.platform === "win32")
             return [];
         const { stdout } = await execFileAsync("ps", [
@@ -61,8 +61,7 @@ const systemHost = {
             processGroupId: Number(match[3]),
             state: match[4] ?? "",
             command: match[5] ?? "",
-        }))
-            .filter((member) => member.processGroupId === processGroupId);
+        }));
     },
     async environment(pid) {
         if (process.platform === "linux") {
@@ -95,73 +94,140 @@ const systemWindowsProcessTreeHost = {
 };
 /** Read the capture run token currently exposed by one live process. */
 export const readProcessRunId = async (pid, host = systemHost) => (await host.environment(pid)).REA_PROCESS_RUN_ID;
-/**
- * Verify run-token ownership before signaling a POSIX process group.
- *
- * Process IDs and group IDs can be reused. REA therefore re-reads every live
- * member's environment immediately before signaling and fails closed if any
- * member cannot be inspected or lacks the per-capture run token.
- */
+/** Token-validate every rooted POSIX process group before signaling any. */
 export const cleanupOwnedProcessGroup = async (ownership, host = systemHost) => {
-    let members;
+    let processes;
     try {
-        members = await host.listMembers(ownership.processGroupId);
+        processes = liveProcesses(await host.listProcesses());
     }
     catch {
-        return { cleaned: false, reason: "process group could not be inspected" };
+        return { cleaned: false, reason: "process table could not be inspected" };
     }
-    const liveMembers = liveProcessGroupMembers(members);
-    if (liveMembers.length === 0)
+    const plan = await createOwnedCleanupPlan(ownership, processes, host);
+    if ("cleaned" in plan)
+        return plan;
+    let signaled = false;
+    for (const processGroupId of plan.signalOrder) {
+        const revalidation = await revalidateOwnedProcessGroup(processGroupId, ownership, host);
+        if ("cleaned" in revalidation)
+            return revalidation;
+        if (revalidation.empty)
+            continue;
+        try {
+            host.signalGroup(processGroupId, "SIGKILL");
+            signaled = true;
+        }
+        catch (cause) {
+            const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+            if (code !== "ESRCH")
+                return { cleaned: false, reason: "owned process group signal failed" };
+        }
+    }
+    return { cleaned: true, signaled };
+};
+const createOwnedCleanupPlan = async (ownership, processes, host) => {
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    const rootMembers = processes.filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
+    if (launcher === undefined && rootMembers.length === 0)
         return { cleaned: true, signaled: false };
-    const leader = liveMembers.find((member) => member.pid === ownership.leaderPid);
-    if (leader !== undefined) {
-        if (ownership.expectedParentPid !== undefined &&
-            leader.parentPid !== ownership.expectedParentPid)
-            return {
-                cleaned: false,
-                reason: "owned launcher parent identity did not match",
-            };
-        if (ownership.expectedCommand !== undefined &&
-            !commandMatches(leader.command, ownership.expectedCommand))
+    let descendants = [];
+    if (launcher !== undefined) {
+        const identityFailure = launcherIdentityFailure(launcher, ownership);
+        if (identityFailure !== null)
+            return { cleaned: false, reason: identityFailure };
+        descendants = descendantsOf(launcher.pid, processes);
+    }
+    const descendantPids = new Set(descendants.map(({ pid }) => pid));
+    const processGroupIds = new Set([ownership.processGroupId]);
+    for (const descendant of descendants)
+        processGroupIds.add(descendant.processGroupId);
+    for (const processGroupId of processGroupIds) {
+        if (processGroupId === ownership.processGroupId)
+            continue;
+        const groupLeader = processes.find(({ pid, processGroupId: observedGroupId }) => pid === processGroupId && observedGroupId === processGroupId);
+        if (groupLeader === undefined || !descendantPids.has(groupLeader.pid))
             return {
                 cleaned: false,
-                reason: "owned launcher command identity did not match",
+                reason: "descendant process-group leader identity could not be verified",
             };
     }
+    const liveMembers = processes.filter(({ processGroupId }) => processGroupIds.has(processGroupId));
+    const failures = await processOwnershipFailures(liveMembers, ownership.runId, host);
+    if (failures.length > 0)
+        return cleanupValidationFailure(failures);
+    return {
+        signalOrder: [ownership.processGroupId].concat([...processGroupIds]
+            .filter((processGroupId) => processGroupId !== ownership.processGroupId)
+            .sort((left, right) => left - right)),
+    };
+};
+const launcherIdentityFailure = (launcher, ownership) => {
+    if (launcher.processGroupId !== ownership.processGroupId)
+        return "owned launcher process-group identity did not match";
+    if (ownership.expectedParentPid !== undefined &&
+        launcher.parentPid !== ownership.expectedParentPid)
+        return "owned launcher parent identity did not match";
+    if (ownership.expectedCommand !== undefined &&
+        !commandMatches(launcher.command, ownership.expectedCommand))
+        return "owned launcher command identity did not match";
+    return null;
+};
+const revalidateOwnedProcessGroup = async (processGroupId, ownership, host) => {
+    let members;
+    try {
+        members = liveProcesses(await host.listProcesses()).filter(({ processGroupId: observedGroupId }) => observedGroupId === processGroupId);
+    }
+    catch {
+        return {
+            cleaned: false,
+            reason: "process ownership could not be revalidated",
+        };
+    }
+    const failures = await processOwnershipFailures(members, ownership.runId, host);
+    if (failures.length > 0)
+        return cleanupValidationFailure(failures);
+    if (processGroupId === ownership.processGroupId) {
+        const launcher = members.find(({ pid }) => pid === ownership.leaderPid);
+        if (launcher !== undefined) {
+            const identityFailure = launcherIdentityFailure(launcher, ownership);
+            if (identityFailure !== null)
+                return { cleaned: false, reason: identityFailure };
+        }
+    }
+    if (processGroupId !== ownership.processGroupId &&
+        members.length > 0 &&
+        !members.some(({ pid }) => pid === processGroupId))
+        return {
+            cleaned: false,
+            reason: "descendant process-group leader identity could not be revalidated",
+        };
+    return { empty: members.length === 0 };
+};
+const cleanupValidationFailure = (failures) => ({
+    cleaned: false,
+    reason: failures.some(({ reason }) => reason === "run-token-mismatch")
+        ? "process tree contains an unowned or PID-reused process"
+        : "process ownership could not be revalidated",
+    failures,
+});
+const processOwnershipFailures = async (members, runId, host) => {
     const failures = [];
-    for (const member of liveMembers) {
+    for (const member of members) {
         try {
-            const environment = await host.environment(member.pid);
-            if (environment.REA_PROCESS_RUN_ID !== ownership.runId)
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !== runId)
                 failures.push({ pid: member.pid, reason: "run-token-mismatch" });
         }
         catch {
             failures.push({ pid: member.pid, reason: "environment-unreadable" });
         }
     }
-    if (failures.length > 0)
-        return {
-            cleaned: false,
-            reason: failures.some(({ reason }) => reason === "run-token-mismatch")
-                ? "process group contains an unowned or PID-reused process"
-                : "process ownership could not be revalidated",
-            failures,
-        };
-    try {
-        host.signalGroup(ownership.processGroupId, "SIGKILL");
-    }
-    catch (cause) {
-        const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
-        if (code !== "ESRCH")
-            return { cleaned: false, reason: "owned process group signal failed" };
-    }
-    return { cleaned: true, signaled: true };
+    return failures;
 };
 /** Observe one group without signaling it, failing closed on identity doubt. */
 export const observeOwnedProcessGroup = async (ownership, host = systemHost) => {
     let members;
     try {
-        members = await host.listMembers(ownership.processGroupId);
+        members = (await host.listProcesses()).filter(({ processGroupId }) => processGroupId === ownership.processGroupId);
     }
     catch {
         return {
@@ -169,7 +235,7 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
             reason: "process group could not be inspected",
         };
     }
-    const liveMembers = liveProcessGroupMembers(members);
+    const liveMembers = liveProcesses(members);
     if (liveMembers.length === 0)
         return { state: "empty" };
     for (const member of liveMembers) {
@@ -190,10 +256,91 @@ export const observeOwnedProcessGroup = async (ownership, host = systemHost) =>
     }
     return { state: "alive" };
 };
-const liveProcessGroupMembers = (members) => members.filter(({ state }) => !state.startsWith("Z"));
+/**
+ * Record the live launcher and descendant lineage after run-token validation.
+ *
+ * The observation is intentionally point-in-time. A verified empty descendant
+ * list means no descendants were live during this observation, not that the
+ * run never created a short-lived child.
+ */
+export const observeOwnedProcessLineage = async (ownership, host = systemHost) => {
+    let processes;
+    try {
+        processes = liveProcesses(await host.listProcesses());
+    }
+    catch {
+        return unavailableLineage(ownership, "process table could not be inspected");
+    }
+    const launcher = processes.find(({ pid }) => pid === ownership.leaderPid);
+    if (launcher === undefined)
+        return unavailableLineage(ownership, "owned launcher is not live");
+    if (launcher.processGroupId !== ownership.processGroupId)
+        return unavailableLineage(ownership, "owned launcher process-group identity did not match");
+    if (ownership.expectedParentPid !== undefined &&
+        launcher.parentPid !== ownership.expectedParentPid)
+        return unavailableLineage(ownership, "owned launcher parent identity did not match");
+    if (ownership.expectedCommand !== undefined &&
+        !commandMatches(launcher.command, ownership.expectedCommand))
+        return unavailableLineage(ownership, "owned launcher command identity did not match");
+    const descendants = descendantsOf(launcher.pid, processes);
+    for (const member of [launcher, ...descendants]) {
+        try {
+            if ((await host.environment(member.pid)).REA_PROCESS_RUN_ID !==
+                ownership.runId)
+                return unavailableLineage(ownership, "process lineage contains an unowned or PID-reused process");
+        }
+        catch {
+            return unavailableLineage(ownership, "process ownership could not be revalidated");
+        }
+    }
+    return {
+        status: "verified",
+        observedAt: new Date().toISOString(),
+        lineage: {
+            schemaVersion: 1,
+            runId: ownership.runId,
+            launcherPid: launcher.pid,
+            launcherParentPid: launcher.parentPid,
+            processGroupId: launcher.processGroupId,
+            descendants: descendants
+                .sort((left, right) => left.pid - right.pid)
+                .map(({ pid, parentPid, processGroupId }) => ({
+                pid,
+                parentPid,
+                processGroupId,
+            })),
+        },
+    };
+};
+const descendantsOf = (launcherPid, processes) => {
+    const childrenByParent = new Map();
+    for (const process of processes) {
+        const siblings = childrenByParent.get(process.parentPid) ?? [];
+        siblings.push(process);
+        childrenByParent.set(process.parentPid, siblings);
+    }
+    const descendants = [];
+    const pending = [...(childrenByParent.get(launcherPid) ?? [])];
+    const visited = new Set([launcherPid]);
+    for (const process of pending) {
+        if (visited.has(process.pid))
+            continue;
+        visited.add(process.pid);
+        descendants.push(process);
+        pending.push(...(childrenByParent.get(process.pid) ?? []));
+    }
+    return descendants;
+};
+const unavailableLineage = (ownership, reason) => ({
+    status: "unavailable",
+    observedAt: new Date().toISOString(),
+    runId: ownership.runId,
+    launcherPid: ownership.leaderPid,
+    processGroupId: ownership.processGroupId,
+    reason,
+});
+const liveProcesses = (members) => members.filter(({ state }) => !state.startsWith("Z"));
 const commandMatches = (actual, expected) => {
-    const normalizedActual = actual.trim();
-    const normalizedExpected = expected.trim();
-    return (normalizedActual === normalizedExpected ||
-        normalizedActual.startsWith(`${normalizedExpected} `));
+    return (actual.trim() === expected.trim() ||
+        actual.trim().startsWith(`${expected.trim()} `));
 };

package/dist/process/ProviderRunLineage.js

@@ -0,0 +1,21 @@
+import { observeOwnedProcessLineage } from "./ProcessOwnership.js";
+/** Retain the latest truthful process-lineage observation for one client. */
+export class ProviderRunLineage {
+    #observation = null;
+    /** Clear stale lineage before a new launch attempt. */
+    reset() {
+        this.#observation = null;
+    }
+    /** Observe a token-owned launcher without signaling it. */
+    async observe(launch) {
+        if (launch?.ownership === undefined)
+            return;
+        this.#observation = await observeOwnedProcessLineage(launch.ownership);
+    }
+    /** Return a detached copy suitable for caller-visible status. */
+    snapshot() {
+        return this.#observation === null
+            ? null
+            : structuredClone(this.#observation);
+    }
+}

package/dist/server/createServer.js

@@ -15,7 +15,7 @@ import { createServerIdentity } from "../serverIdentity.js";
 import { registerBrowserTools } from "./registerBrowserTools.js";
 import { registerElectronTools } from "./registerElectronTools.js";
 import { registerApplicationTools } from "./registerApplicationTools.js";
-const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts and approved runtime evidence; use repository tools for source. Route: ASAR/JavaScript -> analyze_javascript_application; archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence unless a missing detail requires it.";
+const TARGET_FREE_INSTRUCTIONS = "REA analyzes shipped artifacts. Route: ASAR/JavaScript -> analyze_javascript_application (configured root required); archive/package -> inventory_artifact; managed PE/CLI -> inspect_managed_artifact; browser/Electron runtime -> list_browser_targets/list_electron_targets; native binary/database -> open_binary, then binary_overview. Check binary_session for policy. Start with summaries and cite Evidence IDs. Never repeat identical analysis or read full Evidence without a specific need.";
 const ACTIVE_TARGET_INSTRUCTIONS = "REA analyzes the active reverse-engineering target. Start native analysis with binary_overview, then narrow with analyze_function, literal search, callers, callees, and xrefs. Prefer summary views, never repeat an identical call, and read full Evidence only when the task requires it.";
 import { LinuxJavaScriptReplayRunner } from "../replay/LinuxJavaScriptReplayRunner.js";
 import { SystemJavaScriptReplayHost } from "../replay/SystemJavaScriptReplayHost.js";
@@ -205,6 +205,9 @@ const registerObservationTools = ({ server, session, options, logger, permission
         logger,
         recordEvidence,
         recordEvidenceWithUnknown,
+        evidenceLookup: session === undefined
+            ? undefined
+            : (evidenceId) => session.evidenceById(evidenceId),
         evidenceFilePolicy: options.evidenceFilePolicy ?? {
             roots: [],
             maxBytes: 1,