rea-agents 1.2.0 → 1.3.0

package/dist/domain/investigationWorkspace.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { evidenceBundleSchema, parseEvidenceBundle, } from "./evidenceBundle.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const artifactFormatSchema = evidenceBundleSchema.shape.artifacts.element.shape.format;
+/** Bounded controls for one automatic, provider-neutral artifact comparison. */
+const investigationRunOptionsSchema = z.object({
+    max_entries: z.number().int().min(1).max(50_000).default(10_000),
+    max_total_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(1_073_741_824),
+    max_entry_bytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(268_435_456),
+    max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
+    max_depth: z.number().int().min(0).max(100).default(20),
+    max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
+    page_size: z.number().int().min(1).max(500).default(500),
+    change_limit: z.number().int().min(1).max(500).default(500),
+});
+const DEFAULT_INVESTIGATION_RUN_OPTIONS = {
+    max_entries: 10_000,
+    max_total_bytes: 1_073_741_824,
+    max_entry_bytes: 268_435_456,
+    max_compression_ratio: 1_000,
+    max_depth: 20,
+    max_path_bytes: 4_096,
+    page_size: 500,
+    change_limit: 500,
+};
+/** Explicit write approval and two local versions for an automatic run. */
+export const crossVersionInvestigationInputSchema = z.object({
+    approved: z.literal(true),
+    workspace_path: z.string().min(1).max(4_096),
+    workspace_name: z.string().trim().min(1).max(200).default("default"),
+    expected_workspace_revision: z.number().int().min(1).optional(),
+    left_path: z.string().min(1).max(4_096),
+    right_path: z.string().min(1).max(4_096),
+    options: investigationRunOptionsSchema.default(DEFAULT_INVESTIGATION_RUN_OPTIONS),
+});
+const targetSchema = z.object({
+    root_sha256: digestSchema,
+    graph_sha256: digestSchema,
+    manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    format: artifactFormatSchema,
+});
+const stageSchema = z.enum([
+    "inventory_left",
+    "inventory_right",
+    "compare_artifacts",
+    "find_changed_behavior",
+]);
+export const investigationRunSchema = z.object({
+    schema_version: z.literal(1),
+    run_id: z.string().regex(/^run_[a-f0-9]{64}$/u),
+    request_sha256: digestSchema,
+    left: targetSchema,
+    right: targetSchema,
+    options: investigationRunOptionsSchema,
+    status: z.enum(["running", "complete"]),
+    completed_stages: z.array(stageSchema).max(4),
+    left_inventory_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    right_inventory_evidence_ids: z.array(evidenceIdSchema).min(1).max(100),
+    comparison_evidence_id: evidenceIdSchema.nullable(),
+    result_evidence_id: evidenceIdSchema.nullable(),
+    limitations: z.array(z.string().max(4_096)).max(100),
+});
+export const investigationRunSummarySchema = z.object({
+    schema_version: z.literal(1),
+    workspace_id: z.string().regex(/^ws_[a-f0-9]{64}$/u),
+    run_id: z.string().regex(/^run_[a-f0-9]{64}$/u),
+    left_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    right_manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u),
+    inventory_evidence_count: z.number().int().min(2).max(200),
+    comparison_evidence_id: evidenceIdSchema,
+    limitations: z.array(z.string().max(4_096)).max(100),
+});
+const investigationWorkspaceSchema = z.object({
+    workspace_version: z.literal(1),
+    workspace_id: z.string().regex(/^ws_[a-f0-9]{64}$/u),
+    name: z.string().trim().min(1).max(200),
+    revision: z.number().int().min(1),
+    previous_revision_digest: z
+        .string()
+        .regex(/^wrev_[a-f0-9]{64}$/u)
+        .nullable(),
+    revision_digest: z.string().regex(/^wrev_[a-f0-9]{64}$/u),
+    bundle: evidenceBundleSchema,
+    runs: z.array(investigationRunSchema).max(1_000),
+});
+/** Derive a stable run identity from content commitments and bounded controls. */
+export const createInvestigationRunIdentity = (input) => {
+    const requestSha256 = digestCanonical({
+        schema: "rea.cross-version-investigation-request/v1",
+        left: input.left,
+        right: input.right,
+        options: input.options,
+    });
+    return { runId: `run_${requestSha256}`, requestSha256 };
+};
+/** Build the first canonical workspace revision. */
+export const createInvestigationWorkspace = (name, bundle, runs) => buildWorkspace({
+    workspaceId: `ws_${digestCanonical({ schema: "rea.workspace/v1", name })}`,
+    name,
+    revision: 1,
+    previousRevisionDigest: null,
+    bundle,
+    runs,
+});
+/** Create the next immutable workspace revision. */
+export const reviseInvestigationWorkspace = (current, bundle, runs) => buildWorkspace({
+    workspaceId: current.workspace_id,
+    name: current.name,
+    revision: current.revision + 1,
+    previousRevisionDigest: current.revision_digest,
+    bundle,
+    runs,
+});
+/** Parse a workspace and verify identities, revision digest, and references. */
+export const parseInvestigationWorkspace = (input) => {
+    const parsed = investigationWorkspaceSchema.parse(input);
+    const bundle = parseEvidenceBundle(parsed.bundle);
+    const canonical = buildWorkspace({
+        workspaceId: parsed.workspace_id,
+        name: parsed.name,
+        revision: parsed.revision,
+        previousRevisionDigest: parsed.previous_revision_digest,
+        bundle,
+        runs: parsed.runs,
+    });
+    if (parsed.workspace_id !== workspaceIdFor(parsed.name))
+        throw new TypeError("Investigation workspace ID does not match its name");
+    if (parsed.revision_digest !== canonical.revision_digest)
+        throw new TypeError("Investigation workspace revision digest is invalid");
+    if (JSON.stringify(parsed) !== JSON.stringify(canonical))
+        throw new TypeError("Investigation workspace is not canonical");
+    validateRunReferences(canonical);
+    return canonical;
+};
+/** Encode a validated workspace as byte-stable canonical JSON. */
+export const serializeInvestigationWorkspace = (workspace) => canonicalJson(parseInvestigationWorkspace(workspace));
+const buildWorkspace = (input) => {
+    const runs = [...input.runs]
+        .map((run) => investigationRunSchema.parse(run))
+        .sort((left, right) => left.run_id.localeCompare(right.run_id));
+    assertUnique(runs.map(({ run_id: id }) => id), "investigation run ID");
+    const semantic = {
+        workspace_version: 1,
+        workspace_id: input.workspaceId,
+        name: input.name,
+        revision: input.revision,
+        previous_revision_digest: input.previousRevisionDigest,
+        bundle: parseEvidenceBundle(input.bundle),
+        runs,
+    };
+    return investigationWorkspaceSchema.parse({
+        ...semantic,
+        revision_digest: `wrev_${digestCanonical(semantic)}`,
+    });
+};
+const validateRunReferences = (workspace) => {
+    const evidenceIds = new Set(workspace.bundle.records.map(({ evidence_id: id }) => id));
+    for (const run of workspace.runs) {
+        const expectedIdentity = createInvestigationRunIdentity(run);
+        if (run.run_id !== expectedIdentity.runId ||
+            run.request_sha256 !== expectedIdentity.requestSha256)
+            throw new TypeError("Investigation run identity is invalid");
+        validateRunStages(run);
+        const references = [
+            ...run.left_inventory_evidence_ids,
+            ...run.right_inventory_evidence_ids,
+            ...(run.comparison_evidence_id === null
+                ? []
+                : [run.comparison_evidence_id]),
+            ...(run.result_evidence_id === null ? [] : [run.result_evidence_id]),
+        ];
+        if (references.some((evidenceId) => !evidenceIds.has(evidenceId)))
+            throw new TypeError("Investigation run references missing Evidence");
+    }
+};
+const validateRunStages = (run) => {
+    const expected = [
+        "inventory_left",
+        "inventory_right",
+        ...(run.comparison_evidence_id === null ? [] : ["compare_artifacts"]),
+        ...(run.result_evidence_id === null ? [] : ["find_changed_behavior"]),
+    ];
+    if (JSON.stringify(run.completed_stages) !== JSON.stringify(expected))
+        throw new TypeError("Investigation run stages are inconsistent");
+    if (run.status === "complete" && run.result_evidence_id === null)
+        throw new TypeError("Completed investigation run has no result Evidence");
+    if (run.status === "running" && run.result_evidence_id !== null)
+        throw new TypeError("Running investigation run has final result Evidence");
+};
+const workspaceIdFor = (name) => `ws_${digestCanonical({ schema: "rea.workspace/v1", name })}`;
+const digestCanonical = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Investigation workspace could not canonicalize data");
+    return encoded;
+};
+const assertUnique = (values, description) => {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`Duplicate ${description}`);
+};

package/dist/domain/jsonValue.js

@@ -1,3 +1,5 @@
 import { z } from "zod";
 /** JSON-safe value shared by domain, application, and adapter boundaries. */
 export const jsonValueSchema = z.json();
+/** JSON object boundary for caller-visible parameter maps. */
+export const jsonObjectSchema = z.record(z.string(), jsonValueSchema);

package/dist/domain/nativeInspection.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
 const hexAddress = z.string().regex(/^0x[a-fA-F0-9]+$/u);
 const coverage = (item) => z.object({
     items: z.array(item),
@@ -106,7 +107,7 @@ export const inspectSignatureSchema = z.object({
     hash_algorithms: z.array(z.string()),
     authorities: z.array(z.string()),
     designated_requirement: z.string().nullable(),
-    entitlements: z.unknown().nullable(),
+    entitlements: jsonValueSchema.nullable(),
     timestamp: z.string().nullable(),
     hardened_runtime: z.boolean().nullable(),
     provenance: z.array(nativeCommandInvocationSchema),
@@ -114,7 +115,7 @@ export const inspectSignatureSchema = z.object({
 });
 export const inspectPlistSchema = z.object({
     format: z.enum(["xml", "binary", "json", "unknown"]),
-    value: z.unknown(),
+    value: jsonValueSchema,
     bundle: z.object({
         identifier: z.string().nullable(),
         executable: z.string().nullable(),

package/dist/domain/processCapture.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { jsonValueSchema } from "./jsonValue.js";
 import { LEGACY_PROCESS_CAPTURE_MESSAGE, normalizationSchema, } from "./processScenario.js";
 export * from "./processScenario.js";
 const fileStateSchema = z.object({
@@ -31,10 +32,10 @@ export const processCaptureSchema = z.object({
         pty_backend: z.literal("node-pty"),
         started_at: z.iso.datetime(),
         completed_at: z.iso.datetime(),
-        scenario: z.record(z.string(), z.unknown()),
-        comparison_contract: z.record(z.string(), z.unknown()),
-        shim_plan: z.array(z.unknown()),
-        replay_plan: z.record(z.string(), z.unknown()),
+        scenario: z.record(z.string(), jsonValueSchema),
+        comparison_contract: z.record(z.string(), jsonValueSchema),
+        shim_plan: z.array(jsonValueSchema),
+        replay_plan: z.record(z.string(), jsonValueSchema),
         full_scenario_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
         comparison_contract_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
         executable_sha256: z.string().regex(/^[a-f0-9]{64}$/u),

package/dist/domain/processComparison.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { validateProcessCapture } from "./processCapture.js";
+import { jsonValueSchema } from "./jsonValue.js";
 /** Comparison classification that never equates incomplete evidence. */
 export const comparisonStatusSchema = z.enum([
     "unchanged",
@@ -37,8 +38,8 @@ export const processCaptureComparisonSchema = z
             index: z.number().int().nonnegative(),
             left_at_ms: z.number().int().nonnegative().nullable(),
             right_at_ms: z.number().int().nonnegative().nullable(),
-            left: z.unknown().nullable(),
-            right: z.unknown().nullable(),
+            left: jsonValueSchema.nullable(),
+            right: jsonValueSchema.nullable(),
         }),
     ]),
     limitations: z.array(z.string()),
@@ -127,8 +128,8 @@ const firstCollectionDivergence = (dimension, left, right) => {
             index,
             left_at_ms: eventTime(leftValue),
             right_at_ms: eventTime(rightValue),
-            left: leftValue,
-            right: rightValue,
+            left: jsonValueSchema.parse(leftValue),
+            right: jsonValueSchema.parse(rightValue),
         };
     }
     return null;

package/dist/hopper/BridgeLauncher.js

@@ -34,6 +34,7 @@ export class HopperApplicationLauncher {
             `REA_SOCKET = ${JSON.stringify(session.socketPath)}`,
             `REA_TOKEN = ${JSON.stringify(session.token)}`,
             `REA_RUN_ID = ${JSON.stringify(session.runId)}`,
+            `REA_TARGET_PATH = ${JSON.stringify(this.options.targetPath)}`,
             `exec(compile(open(${JSON.stringify(this.options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(this.options.bridgeScriptPath)}, 'exec'))`,
             "",
         ].join("\n");
@@ -59,25 +60,12 @@ export class HopperApplicationLauncher {
             const prepared = await prepareHopperApplication(this.options.launcherPath, options.signal);
             if (!prepared)
                 return err(new HopperCancelledError());
-            const child = spawn(this.options.launcherPath, args, {
-                stdio: ["ignore", "ignore", "pipe"],
-                detached: process.platform !== "win32",
-                env: { ...process.env, REA_PROCESS_RUN_ID: session.runId },
-            });
-            const started = await new Promise((resolve) => {
-                const onSpawn = () => {
-                    child.off("error", onError);
-                    resolve(ok(undefined));
-                };
-                const onError = (cause) => {
-                    child.off("spawn", onSpawn);
-                    resolve(err(new HopperStartError({ cause })));
-                };
-                child.once("spawn", onSpawn);
-                child.once("error", onError);
-            });
+            const linuxDemo = linuxDemoLaunch(this.options, session, args);
+            const ownershipCommand = linuxDemo?.ownershipCommand ?? this.options.launcherPath;
+            const started = await spawnLauncher(linuxDemo?.command ?? this.options.launcherPath, linuxDemo?.args ?? args, session.runId);
             if (!started.ok)
                 return started;
+            const child = started.value;
             const pid = child.pid;
             if (pid === undefined)
                 return err(new HopperStartError({ cause: new Error("missing launcher PID") }));
@@ -87,20 +75,20 @@ export class HopperApplicationLauncher {
                 pid,
                 process_group_id: pid,
                 parent_pid: process.pid,
-                launcher: this.options.launcherPath,
+                launcher: linuxDemo?.command ?? this.options.launcherPath,
                 created_at: new Date().toISOString(),
             };
             try {
                 await writeFileAtomic(join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 });
             }
             catch (cause) {
-                await cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath));
+                await cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, ownershipCommand));
                 return err(new HopperStartError({ cause }));
             }
             return ok({
                 process: child,
                 ownsProcessLifetime: true,
-                cleanup: () => cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, this.options.launcherPath)),
+                cleanup: () => cleanupOwnedProcessGroup(ownedProcessGroup(session, pid, ownershipCommand)),
             });
         }
         catch (cause) {
@@ -108,6 +96,45 @@ export class HopperApplicationLauncher {
         }
     }
 }
+const linuxDemoLaunch = (options, session, hopperArgs) => {
+    if (process.platform !== "linux" ||
+        basename(options.launcherPath) !== "Hopper" ||
+        options.demoHelperPath === undefined)
+        return undefined;
+    return {
+        command: "/usr/bin/python3",
+        ownershipCommand: "/usr/bin/python3",
+        args: [
+            options.demoHelperPath,
+            "--hopper",
+            options.launcherPath,
+            "--socket",
+            session.socketPath,
+            "--",
+            options.launcherPath,
+            ...hopperArgs,
+        ],
+    };
+};
+const spawnLauncher = async (command, args, runId) => {
+    const child = spawn(command, args, {
+        stdio: ["ignore", "ignore", "pipe"],
+        detached: process.platform !== "win32",
+        env: { ...process.env, REA_PROCESS_RUN_ID: runId },
+    });
+    return new Promise((resolve) => {
+        const onSpawn = () => {
+            child.off("error", onError);
+            resolve(ok(child));
+        };
+        const onError = (cause) => {
+            child.off("spawn", onSpawn);
+            resolve(err(new HopperStartError({ cause })));
+        };
+        child.once("spawn", onSpawn);
+        child.once("error", onError);
+    });
+};
 const ownedProcessGroup = (session, pid, launcherPath) => ({
     runId: session.runId,
     leaderPid: pid,

package/dist/hopper/HopperClient.js

@@ -3,11 +3,12 @@ import { access, mkdtemp, rm } from "node:fs/promises";
 import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperStartError, HopperTimeoutError, } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperProtocolError, HopperStartError, hopperStartupFailure, HopperTimeoutError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { parseResponseLine, responseResult } from "./protocol.js";
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
+const SHUTDOWN_TIMEOUT_MS = 30_000;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
 /**
  * Owns one authenticated NDJSON-over-Unix-socket bridge session.
@@ -28,6 +29,7 @@ export class HopperClient {
     #nextId = 1;
     #buffer = "";
     #closing = false;
+    #launcherExitCode;
     #startPromise;
     #closePromise;
     constructor(options) {
@@ -57,6 +59,7 @@ export class HopperClient {
         }
         const socketPath = join(this.#directory, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
+        this.#launcherExitCode = undefined;
         const runId = randomUUID();
         const launched = await this.#options.launcher.launch({
             directory: this.#directory,
@@ -105,7 +108,9 @@ export class HopperClient {
         try {
             const socket = this.#socket;
             if (socket !== undefined && !socket.destroyed) {
-                await this.#request("shutdown", {}, { timeoutMs: 500 }).catch(() => err(new HopperProcessError(null)));
+                const shutdown = await this.#request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS }).catch(() => err(new HopperProcessError(null)));
+                if (!shutdown.ok || !isShutdownAcknowledgement(shutdown.value))
+                    this.#logger.warn({ status: shutdown.ok ? "invalid-acknowledgement" : "failed" }, "Hopper document shutdown was not confirmed");
             }
             this.#failAll(new HopperProcessError(null));
             socket?.destroy();
@@ -139,6 +144,9 @@ export class HopperClient {
                 return err(new HopperCancelledError());
             if (this.#closing)
                 return err(new HopperProcessError(null));
+            if (this.#launcherExitCode !== undefined &&
+                hopperStartupFailure(this.#launcherExitCode) !== undefined)
+                return err(new HopperProcessError(this.#launcherExitCode));
             try {
                 await access(socketPath);
             }
@@ -222,6 +230,7 @@ export class HopperClient {
             });
         });
         launch.process.on("exit", (code) => {
+            this.#launcherExitCode = code;
             this.#options.onDiagnostic?.({ type: "launcher-exit", code });
             if (launch.ownsProcessLifetime && !this.#closing) {
                 this.#failAll(new HopperProcessError(code));
@@ -310,6 +319,12 @@ const connectOnce = async (socketPath) => new Promise((resolve) => {
         resolve(err(new HopperStartError({ cause })));
     });
 });
+const isShutdownAcknowledgement = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    value.shutdown === true &&
+    value.analysis_stopped === true &&
+    value.document_closed === true;
 const parseServerInfo = (value, expectedRunId) => {
     if (typeof value === "object" &&
         value !== null &&

package/dist/hopper/HopperProvider.js

@@ -78,6 +78,7 @@ export class HopperProvider {
                     ? this.config.hopperLoaderArgs
                     : target.loaderArgs,
                 bridgeScriptPath: fileURLToPath(new URL("../../bridge/hopper_bridge.py", import.meta.url)),
+                demoHelperPath: fileURLToPath(new URL("../../scripts/hopper-demo-x11.py", import.meta.url)),
             }),
             logger: this.logger.child({ layer: "bridge" }),
         });

package/dist/main.js

@@ -6,15 +6,34 @@ import { parseConfig } from "./config.js";
 import { createBinarySession } from "./application/runtime.js";
 import { createServer } from "./server/createServer.js";
 import { createLogger } from "./logger.js";
+import { projectAnalysisError } from "./domain/errors.js";
+const MCP_CONNECTION_LOST = "REA lost its MCP client connection. Restart REA from your MCP client.";
+const MCP_CONNECTION_START_FAILED = "REA could not start its MCP connection. Restart REA from your MCP client; run `rea doctor` if it fails again.";
+const MCP_SHUTDOWN_FAILED = "REA could not close cleanly. End the REA process before starting it again.";
+const SERVER_START_FAILED = "REA could not start. Run `rea doctor`, then restart REA from your MCP client.";
+const runtimeDependencies = () => ({
+    env: process.env,
+    serve: serveStdio,
+    writeStderr: (text) => process.stderr.write(text),
+    setExitCode: (code) => {
+        process.exitCode = code;
+    },
+    registerShutdown: (handler) => {
+        process.once("SIGINT", handler);
+        process.once("SIGTERM", handler);
+        process.stdin.once("end", handler);
+        process.stdin.once("close", handler);
+    },
+});
 /**
  * Start the long-lived MCP adapter and install idempotent shutdown handlers.
  * The adapter owns its BinarySession for the process lifetime; EOF and process
  * signals close bridge resources without assuming ownership of the Hopper app.
  */
-export const run = async () => {
-    const config = parseConfig(process.env);
+export const run = async (dependencies = runtimeDependencies()) => {
+    const config = parseConfig(dependencies.env);
     if (!config.ok) {
-        process.stderr.write(`${config.error._tag}: ${config.error.message}\n`);
+        dependencies.writeStderr(`${projectAnalysisError(config.error).message}\n`);
         return 1;
     }
     const logger = createLogger("mcp", config.value.logLevel);
@@ -27,27 +46,29 @@ export const run = async () => {
         if (!opened.ok) {
             await session.close();
             serverLogger.error({ errorTag: opened.error._tag }, "Initial target failed to open");
-            process.stderr.write(`${opened.error._tag}: ${opened.error.message}\n`);
+            dependencies.writeStderr(`${projectAnalysisError(opened.error).message}\n`);
             return 1;
         }
     }
     let handle;
     try {
-        handle = serveStdio(() => createServer(session, session, {
+        handle = dependencies.serve(() => createServer(session, session, {
             logger,
             processPolicy: config.value.processExecutionPolicy,
             evidenceFilePolicy: config.value.evidenceFilePolicy,
+            investigationInputRoots: config.value.investigationInputRoots,
+            analysisSnapshotFilePolicy: config.value.analysisSnapshotFilePolicy,
         }), {
             onerror: () => {
-                serverLogger.error("MCP stdio transport error");
-                process.stderr.write("MCP stdio transport error\n");
+                serverLogger.error(MCP_CONNECTION_LOST);
+                dependencies.writeStderr(`${MCP_CONNECTION_LOST}\n`);
             },
         });
     }
     catch {
         await session.close();
-        serverLogger.error("Failed to start MCP stdio transport");
-        process.stderr.write("Failed to start MCP stdio transport\n");
+        serverLogger.error(MCP_CONNECTION_START_FAILED);
+        dependencies.writeStderr(`${MCP_CONNECTION_START_FAILED}\n`);
         return 1;
     }
     let shutdownPromise;
@@ -60,26 +81,28 @@ export const run = async () => {
     };
     const requestShutdown = () => {
         shutdown().catch(() => {
-            process.exitCode = 1;
-            serverLogger.error("Failed to shut down cleanly");
-            process.stderr.write("Failed to shut down cleanly\n");
+            dependencies.setExitCode(1);
+            serverLogger.error(MCP_SHUTDOWN_FAILED);
+            dependencies.writeStderr(`${MCP_SHUTDOWN_FAILED}\n`);
         });
     };
-    process.once("SIGINT", requestShutdown);
-    process.once("SIGTERM", requestShutdown);
-    process.stdin.once("end", requestShutdown);
-    process.stdin.once("close", requestShutdown);
+    dependencies.registerShutdown(requestShutdown);
     return 0;
 };
+/** Run the executable boundary without exposing an unexpected startup cause. */
+export const runEntrypoint = async (start = () => run(), writeStderr = (text) => process.stderr.write(text), setExitCode = (code) => {
+    process.exitCode = code;
+}) => {
+    try {
+        setExitCode(await start());
+    }
+    catch {
+        writeStderr(`${SERVER_START_FAILED}\n`);
+        setExitCode(1);
+    }
+};
 const entryPath = process.argv[1];
 if (entryPath !== undefined &&
     pathToFileURL(realpathSync(entryPath)).href === import.meta.url) {
-    run()
-        .then((exitCode) => {
-        process.exitCode = exitCode;
-    })
-        .catch(() => {
-        process.stderr.write("Unexpected server startup failure\n");
-        process.exitCode = 1;
-    });
+    void runEntrypoint();
 }

package/dist/server/createServer.js

@@ -6,6 +6,7 @@ import { registerSessionTools } from "./registerSessionTools.js";
 import { registerNativeTools } from "./registerNativeTools.js";
 import { registerArtifactTools } from "./registerArtifactTools.js";
 import { silentLogger } from "../logger.js";
+import { registerGuidedPrompts } from "./registerPrompts.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
@@ -50,6 +51,7 @@ export const createServer = (analysis, session, options = {}) => {
         activeTarget,
         recordEvidence,
     });
+    registerGuidedPrompts(server, analysis, session);
     if (session !== undefined)
         registerSessionTools(server, session, toolLogger, options);
     return server;