rea-agents 6.4.0 → 6.7.0

package/dist/process/ProviderProcess.js

@@ -1,8 +1,11 @@
 import { spawn } from "node:child_process";
 import { WindowsOwnedProcess } from "../windows/WindowsOwnedProcess.js";
-import { prepareProcessOwnershipInspection } from "./ProcessOwnershipObservation.js";
+import { prepareProcessOwnershipInspection, systemProcessOwnershipHost, } from "./ProcessOwnershipObservation.js";
 const DEFAULT_TERMINATION_GRACE_MS = 250;
 const DEFAULT_KILL_GRACE_MS = 1_000;
+const OUTPUT_CLOSE_GRACE_MS = 1_000;
+const MAX_LATE_OUTPUT_BYTES = 64 * 1024;
+const outputCheckpoints = new WeakMap();
 /**
  * Spawn a provider in an owned Windows job or dedicated POSIX process group.
  *
@@ -14,6 +17,15 @@ export const spawnOwnedProviderProcess = async (options) => {
     await prepareProcessOwnershipInspection(options.signal);
     options.signal?.throwIfAborted();
     const platform = options.platform ?? process.platform;
+    const sweepTokenOwnedProcesses = options.sweepTokenOwnedProcesses === true && platform !== "win32";
+    let captureBaseline;
+    if (sweepTokenOwnedProcesses) {
+        const capture = systemProcessOwnershipHost.captureBaseline;
+        if (capture === undefined)
+            throw new Error("Process ownership baseline is unavailable on this host");
+        captureBaseline = await capture(options.signal);
+        options.signal?.throwIfAborted();
+    }
     const hostEnvironment = options.hostEnvironment ?? process.env;
     const environment = {
         ...hostEnvironment,
@@ -21,7 +33,12 @@ export const spawnOwnedProviderProcess = async (options) => {
         REA_PROCESS_RUN_ID: options.runId,
     };
     if (platform === "win32" && process.platform === "win32") {
-        const child = new WindowsOwnedProcess(options.command, options.arguments, options.cwd, environment, options.windowsVerbatimArguments ?? false, options.stdin === "pipe");
+        const child = new WindowsOwnedProcess(options.command, options.arguments, options.cwd, environment, options.windowsVerbatimArguments ?? false, {
+            protocolStdin: options.stdin === "pipe",
+            ...(options.memoryLimitBytes === undefined
+                ? {}
+                : { memoryLimitBytes: options.memoryLimitBytes }),
+        });
         return {
             process: child,
             ownership: {
@@ -33,6 +50,8 @@ export const spawnOwnedProviderProcess = async (options) => {
             cleanup: () => child.cleanup(),
         };
     }
+    if (options.memoryLimitBytes !== undefined)
+        throw new Error("Owned process memory limits require the Windows Job Object launcher; no limit can be enforced on this host.");
     const child = spawn(options.command, [...options.arguments], {
         shell: false,
         windowsHide: true,
@@ -51,6 +70,12 @@ export const spawnOwnedProviderProcess = async (options) => {
         leaderPid: pid,
         processGroupId: pid,
         expectedParentPid: process.pid,
+        ...(sweepTokenOwnedProcesses
+            ? {
+                sweepTokenOwnedProcesses: true,
+                captureBaseline: captureBaseline,
+            }
+            : {}),
         ...(options.expectedCommand === null
             ? {}
             : { expectedCommand: options.expectedCommand ?? options.command }),
@@ -72,6 +97,7 @@ export class ProviderProcessSupervisor {
     #exit = deferred();
     #outputClose = deferred();
     #outputClosed = false;
+    #outputIncomplete = false;
     #stdoutObservedBytes = 0;
     #stderrObservedBytes = 0;
     #diagnosticTruncated = false;
@@ -96,14 +122,21 @@ export class ProviderProcessSupervisor {
         this.#outputClose.resolve(undefined);
     };
     #onError = (cause) => {
-        this.#options.onDiagnostic?.({ type: "error", message: cause.message });
+        this.#options.onDiagnostic?.({
+            type: "error",
+            message: cause.message,
+            cause,
+        });
     };
     #exitObservation;
     #stopPromise;
     #disposed = false;
+    #maxDiagnosticBytes;
+    #outputEpoch = 0;
     constructor(launch, options = {}) {
         this.launch = launch;
         this.#options = options;
+        this.#maxDiagnosticBytes = options.maxDiagnosticBytes;
         if (options.captureStdout !== false)
             this.#attach(launch.process.stdout, "stdout");
         this.#attach(launch.process.stderr, "stderr");
@@ -113,18 +146,93 @@ export class ProviderProcessSupervisor {
         if (launch.process.exitCode !== null || launch.process.signalCode !== null)
             this.#recordExit(launch.process.exitCode, launch.process.signalCode);
     }
+    /**
+     * Recorded process exit without concatenating retained stream diagnostics.
+     * Undefined until exit or close is observed.
+     */
+    observedExit() {
+        const exit = this.#exitObservation;
+        if (exit === undefined)
+            return undefined;
+        return { code: exit.code, signal: exit.signal };
+    }
+    /** Whether the process owner acknowledged output closure, separately from exit. */
+    observedOutputClose() {
+        return this.#outputClosed;
+    }
     /** Latest retained output and exit observation, with explicit configured truncation. */
     snapshot() {
+        const outputIncomplete = this.#outputIncomplete || this.launch.process.outputIncomplete === true;
         return {
-            ...(this.#diagnosticTruncated ? { diagnosticTruncated: true } : {}),
+            ...(this.#diagnosticTruncated || outputIncomplete
+                ? { diagnosticTruncated: true }
+                : {}),
             stdout: this.#stdout.snapshot(this.#stdoutObservedBytes),
             stderr: this.#stderr.snapshot(this.#stderrObservedBytes),
             exitCode: this.#exitObservation?.code,
             signal: this.#exitObservation?.signal,
+            ...(this.launch.process.memoryLimitReached === true
+                ? { memoryLimitReached: true }
+                : {}),
+            ...(outputIncomplete ? { outputIncomplete: true } : {}),
+        };
+    }
+    /** Mark the current raw-byte position without copying or retaining output. */
+    checkpointOutput() {
+        const checkpoint = Object.freeze({});
+        outputCheckpoints.set(checkpoint, {
+            owner: this,
+            epoch: this.#outputEpoch,
+            stdout: this.#stdoutObservedBytes,
+            stderr: this.#stderrObservedBytes,
+        });
+        return checkpoint;
+    }
+    /** Snapshot only bytes produced after a valid checkpoint on this supervisor. */
+    snapshotOutputSince(checkpoint) {
+        const position = typeof checkpoint === "object" && checkpoint !== null
+            ? outputCheckpoints.get(checkpoint)
+            : undefined;
+        if (position === undefined ||
+            position.owner !== this ||
+            position.epoch !== this.#outputEpoch)
+            return {
+                snapshot: {
+                    stdout: { text: "", bytes: 0, observedBytes: 0 },
+                    stderr: { text: "", bytes: 0, observedBytes: 0 },
+                    exitCode: this.#exitObservation?.code,
+                    signal: this.#exitObservation?.signal,
+                    outputIncomplete: true,
+                    diagnosticTruncated: true,
+                },
+                complete: false,
+            };
+        const stdout = this.#stdout.snapshotRange(position.stdout, this.#stdoutObservedBytes);
+        const stderr = this.#stderr.snapshotRange(position.stderr, this.#stderrObservedBytes);
+        const incomplete = stdout.complete === false ||
+            stderr.complete === false ||
+            this.#outputIncomplete ||
+            this.launch.process.outputIncomplete === true;
+        return {
+            snapshot: {
+                ...(incomplete || this.#diagnosticTruncated
+                    ? { diagnosticTruncated: true }
+                    : {}),
+                stdout: stdout.stream,
+                stderr: stderr.stream,
+                exitCode: this.#exitObservation?.code,
+                signal: this.#exitObservation?.signal,
+                ...(this.launch.process.memoryLimitReached === true
+                    ? { memoryLimitReached: true }
+                    : {}),
+                ...(incomplete ? { outputIncomplete: true } : {}),
+            },
+            complete: !incomplete && !this.#diagnosticTruncated,
         };
     }
     /** Begin a new observation on a retained process without retaining earlier output. */
     resetOutput() {
+        this.#outputEpoch += 1;
         this.#stdout.reset();
         this.#stderr.reset();
         this.#stdoutObservedBytes = 0;
@@ -135,9 +243,33 @@ export class ProviderProcessSupervisor {
     async waitForExit(timeoutMs) {
         return waitForProcessEvent(this.#exitObservation !== undefined, this.#exit.promise, timeoutMs);
     }
-    /** Wait until the producer has closed its output streams; exit alone does not prove complete output. */
-    async waitForOutputClose(timeoutMs) {
-        return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs);
+    /** Wait until output streams close; omit the timeout to await physical completion.
+     * WindowsOwnedProcess closes only after its whole Job Object settles.
+     */
+    async waitForOutputClose(timeoutMs, signal) {
+        return waitForProcessEvent(this.#outputClosed, this.#outputClose.promise, timeoutMs, signal);
+    }
+    /** Bound additional retained bytes while still draining all later output. */
+    limitAdditionalOutputBytes(maxBytes) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+            throw new RangeError("Additional output limit must be a non-negative safe integer.");
+        const retained = this.#stdout.bytes + this.#stderr.bytes;
+        const requestedLimit = Math.min(Number.MAX_SAFE_INTEGER, retained + maxBytes);
+        this.#maxDiagnosticBytes =
+            this.#maxDiagnosticBytes === undefined
+                ? requestedLimit
+                : Math.min(this.#maxDiagnosticBytes, requestedLimit);
+    }
+    /** Unreference inherited output pipes without closing streams shared with descendants. */
+    unrefOutputStreams() {
+        for (const stream of [
+            this.launch.process.stdout,
+            this.launch.process.stderr,
+        ]) {
+            const unref = stream
+                ?.unref;
+            unref?.call(stream);
+        }
     }
     /** Share each stop attempt; incomplete cleanup retains ownership and permits retry. */
     stop(options = {}) {
@@ -152,6 +284,9 @@ export class ProviderProcessSupervisor {
     dispose() {
         if (this.#disposed)
             return;
+        // Releasing capture before close cannot establish a complete output history.
+        if (!this.#outputClosed)
+            this.#outputIncomplete = true;
         this.#disposed = true;
         this.launch.process.stdout?.off("data", this.#onStdout);
         this.launch.process.stdout?.off("error", this.#onStdoutError);
@@ -161,11 +296,42 @@ export class ProviderProcessSupervisor {
         this.launch.process.off("close", this.#onClose);
         this.launch.process.off("error", this.#onError);
     }
+    /** Release event-loop references so incomplete cleanup does not prevent host exit. */
+    unref() {
+        const process = this.launch.process;
+        process.unref?.();
+        process.stdin?.unref?.();
+        process.stdout?.unref?.();
+        process.stderr?.unref?.();
+    }
+    /** Restore event-loop references when retrying supervised process cleanup. */
+    ref() {
+        const process = this.launch.process;
+        process.ref?.();
+        process.stdin?.ref?.();
+        process.stdout?.ref?.();
+        process.stderr?.ref?.();
+    }
     async #stop(options) {
+        if (this.launch.ownsProcessLifetime) {
+            this.ref();
+            // Bound retention throughout termination and failed cleanup, including retries.
+            this.limitAdditionalOutputBytes(MAX_LATE_OUTPUT_BYTES);
+        }
         let completed = false;
         try {
             const result = await this.#stopWithin(options);
             completed = result.status !== "incomplete";
+            if (completed && result.status !== "not-owned" && !this.#outputClosed) {
+                // Exit proves process lifetime only. Bound final retention while draining
+                // inherited pipes; a lost output tail does not revoke verified cleanup.
+                if (!(await this.waitForOutputClose(OUTPUT_CLOSE_GRACE_MS))) {
+                    this.#outputIncomplete = true;
+                    this.unref();
+                }
+            }
+            if (!completed)
+                this.unref();
             return result;
         }
         finally {
@@ -180,13 +346,21 @@ export class ProviderProcessSupervisor {
             if (this.launch.cleanup !== undefined) {
                 const cleanup = await this.#ownedCleanup(options.cleanupResult);
                 if (!cleanup.cleaned)
-                    return { status: "incomplete", reason: cleanup.reason };
+                    return {
+                        status: "incomplete",
+                        reason: cleanup.reason,
+                        cleanupResult: cleanup,
+                    };
                 const graceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
                 if (await this.waitForExit(graceMs))
                     return { status: "verified-cleanup" };
                 const retried = await this.launch.cleanup();
                 if (!retried.cleaned)
-                    return { status: "incomplete", reason: retried.reason };
+                    return {
+                        status: "incomplete",
+                        reason: retried.reason,
+                        cleanupResult: retried,
+                    };
                 if (await this.waitForExit(graceMs))
                     return { status: "verified-cleanup" };
                 return {
@@ -243,9 +417,11 @@ export class ProviderProcessSupervisor {
         }
     }
     #recordStreamError(stream, cause) {
+        this.#outputIncomplete = true;
         this.#options.onDiagnostic?.({
             type: "error",
             message: `${stream} stream failed: ${cause.message}`,
+            cause,
         });
     }
     #capture(stream, capture, chunk) {
@@ -254,11 +430,9 @@ export class ProviderProcessSupervisor {
             this.#stdoutObservedBytes += bytes.byteLength;
         else
             this.#stderrObservedBytes += bytes.byteLength;
-        const remaining = this.#options.maxDiagnosticBytes === undefined
+        const remaining = this.#maxDiagnosticBytes === undefined
             ? bytes.byteLength
-            : Math.max(0, this.#options.maxDiagnosticBytes -
-                this.#stdout.bytes -
-                this.#stderr.bytes);
+            : Math.max(0, this.#maxDiagnosticBytes - this.#stdout.bytes - this.#stderr.bytes);
         const retained = Math.min(bytes.byteLength, remaining);
         if (retained < bytes.byteLength)
             this.#diagnosticTruncated = true;
@@ -302,11 +476,43 @@ class ProcessOutputCapture {
         this.#chunks.push(Buffer.from(chunk));
     }
     snapshot(observedBytes) {
-        const text = Buffer.concat(this.#chunks, this.#bytes).toString("utf8");
+        return this.#snapshotBuffer(Buffer.concat(this.#chunks, this.#bytes), observedBytes);
+    }
+    snapshotRange(start, end) {
+        const availableEnd = Math.min(end, this.#bytes);
+        const availableStart = Math.min(start, availableEnd);
+        const chunks = [];
+        let offset = 0;
+        for (const chunk of this.#chunks) {
+            const chunkEnd = offset + chunk.byteLength;
+            const from = Math.max(availableStart, offset);
+            const to = Math.min(availableEnd, chunkEnd);
+            if (to > from)
+                chunks.push(chunk.subarray(from - offset, to - offset));
+            offset = chunkEnd;
+            if (offset >= availableEnd)
+                break;
+        }
+        const buffer = Buffer.concat(chunks, availableEnd - availableStart);
+        return {
+            stream: this.#snapshotBuffer(buffer, Math.max(0, end - start)),
+            complete: start <= this.#bytes && end <= this.#bytes,
+        };
+    }
+    #snapshotBuffer(buffer, observedBytes) {
+        const text = buffer.toString("utf8");
+        let invalidUtf8 = false;
+        try {
+            new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+        }
+        catch {
+            invalidUtf8 = true;
+        }
         return {
             text,
-            bytes: this.#bytes,
+            bytes: buffer.byteLength,
             observedBytes,
+            ...(invalidUtf8 ? { invalidUtf8: true } : {}),
         };
     }
 }
@@ -334,20 +540,30 @@ const waitForSpawn = (child) => new Promise((resolve, reject) => {
     child.once("spawn", onSpawn);
     child.once("error", onError);
 });
-const waitForProcessEvent = async (observed, event, timeoutMs) => {
+const waitForProcessEvent = async (observed, event, timeoutMs, signal) => {
     if (observed)
         return true;
+    if (signal?.aborted === true)
+        return false;
     let timer;
+    let onAbort;
     try {
         return await Promise.race([
             event.then(() => true),
             new Promise((resolve) => {
-                timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+                if (timeoutMs !== undefined)
+                    timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs));
+                if (signal !== undefined) {
+                    onAbort = () => resolve(false);
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }
             }),
         ]);
     }
     finally {
         if (timer !== undefined)
             clearTimeout(timer);
+        if (onAbort !== undefined)
+            signal?.removeEventListener("abort", onAbort);
     }
 };

package/dist/process/RegexMatcher.js

@@ -0,0 +1,96 @@
+import { Worker } from "node:worker_threads";
+import { z } from "zod";
+import { AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+const MATCHING_DEADLINE_MS = 5_000;
+const WORKER_HEAP_MIB = 128;
+/** Shared capability text for the supervised ECMAScript matching boundary. */
+export const REGEX_MATCHING_LIMITATION = `Regex mode uses ECMAScript Unicode semantics in a cancellable worker with a ${String(MATCHING_DEADLINE_MS / 1000)}-second matching deadline; matching failure leaves the service available.`;
+const replySchema = z.discriminatedUnion("status", [
+    z.strictObject({
+        status: z.literal("matched"),
+        indices: z.array(z.number().int().nonnegative()),
+    }),
+    z.strictObject({ status: z.literal("invalid_pattern"), reason: z.string() }),
+]);
+// Code is constant; caller patterns and target strings cross only workerData.
+const WORKER_SOURCE = String.raw `
+(async () => {
+const { parentPort, workerData } = await import("node:worker_threads");
+let expression;
+try {
+  expression = new RegExp(workerData.pattern, workerData.caseSensitive ? "u" : "iu");
+} catch (cause) {
+  parentPort.postMessage({ status: "invalid_pattern", reason: cause instanceof Error ? cause.message : String(cause) });
+}
+if (expression !== undefined) {
+  const indices = [];
+  for (const [index, value] of workerData.values.entries())
+    if (expression.test(value)) indices.push(index);
+  parentPort.postMessage({ status: "matched", indices });
+}
+})();
+`;
+/** Match an inventory off the service thread, and prove worker exit before returning. */
+export const matchRegexValues = async (input) => {
+    if (input.signal?.aborted)
+        return err(new AnalysisCancelledError(input.operation));
+    let worker;
+    try {
+        worker = new Worker(WORKER_SOURCE, {
+            eval: true,
+            workerData: {
+                pattern: input.pattern,
+                caseSensitive: input.caseSensitive,
+                values: input.values,
+            },
+            resourceLimits: { maxOldGenerationSizeMb: WORKER_HEAP_MIB },
+        });
+    }
+    catch (cause) {
+        return err(new AnalysisOutputError(input.operation, "Cannot start regex worker", {
+            cause,
+        }));
+    }
+    try {
+        return await new Promise((resolve) => {
+            let settled = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                input.signal?.removeEventListener("abort", onAbort);
+                resolve(result);
+            };
+            const onAbort = () => finish(err(new AnalysisCancelledError(input.operation)));
+            const timer = setTimeout(() => finish(err(new AnalysisResourceConstraintError(input.operation, "cpu", "Regex matching exceeded its supervised deadline; the service remains available.", { matching_deadline_ms: MATCHING_DEADLINE_MS }, {
+                remediationAction: "Simplify the ECMAScript Unicode regex or use literal mode, then retry in the same session.",
+            }))), MATCHING_DEADLINE_MS);
+            input.signal?.addEventListener("abort", onAbort, { once: true });
+            if (input.signal?.aborted)
+                onAbort();
+            worker.once("message", (message) => {
+                const reply = replySchema.safeParse(message);
+                if (!reply.success)
+                    return finish(err(new AnalysisOutputError(input.operation, "Regex worker reply is malformed")));
+                if (reply.data.status === "invalid_pattern")
+                    return finish(err(input.invalidPattern?.(reply.data.reason) ??
+                        new AnalysisInputError(input.operation, {
+                            userMessage: `Invalid regex pattern: ${reply.data.reason}`,
+                        })));
+                if (reply.data.indices.some((index, position, indices) => index >= input.values.length ||
+                    (position > 0 && index <= (indices[position - 1] ?? -1))))
+                    return finish(err(new AnalysisOutputError(input.operation, "Regex worker returned invalid inventory indices")));
+                finish(ok(reply.data.indices));
+            });
+            worker.once("error", (cause) => finish(err(cause.code === "ERR_WORKER_OUT_OF_MEMORY"
+                ? new AnalysisResourceConstraintError(input.operation, "memory", "Regex worker exhausted its heap budget", { worker_heap_mib: WORKER_HEAP_MIB }, { cause })
+                : new AnalysisOutputError(input.operation, `Regex worker failed: ${cause.message}`, { cause }))));
+            worker.once("exit", (code) => finish(err(new AnalysisOutputError(input.operation, `Regex worker exited without a result (${String(code)})`))));
+        });
+    }
+    finally {
+        await worker.terminate();
+    }
+};

package/dist/process/SharedStartupAttempt.js

@@ -0,0 +1,59 @@
+import { ABORTED, waitForAbortable } from "./AbortablePromise.js";
+/** An owner closing a provider is distinct from a caller cancelling its wait. */
+export const STARTUP_OWNER_CLOSED = Symbol("provider startup owner closed");
+/** Own one startup operation while its callers wait independently. */
+export class SharedStartupAttempt {
+    #controller = new AbortController();
+    promise;
+    #signal;
+    #waiters = 0;
+    #settlement = { status: "pending" };
+    constructor(start, 
+    /** An owning operation's cancellation is independent of individual waiters. */
+    ownerSignal) {
+        this.#signal =
+            ownerSignal === undefined
+                ? this.#controller.signal
+                : AbortSignal.any([ownerSignal, this.#controller.signal]);
+        this.promise = start(this.#signal);
+        void this.promise.then((value) => {
+            this.#settlement = { status: "completed", value };
+        }, () => {
+            this.#settlement = { status: "rejected" };
+        });
+    }
+    /** Signal consumed by the startup producer, never by an individual waiter. */
+    get signal() {
+        return this.#signal;
+    }
+    /** Completion includes the producer's final cleanup, not just its abort. */
+    get settled() {
+        return this.#settlement.status !== "pending";
+    }
+    /** Parsed completion facts are owned here, rather than copied into adapters. */
+    get settlement() {
+        return this.#settlement;
+    }
+    /** Stop startup when its owning provider closes, regardless of active waits. */
+    close() {
+        if (!this.settled)
+            this.#controller.abort(STARTUP_OWNER_CLOSED);
+    }
+    /** A peer's departure leaves the producer running; final departure joins cleanup. */
+    async wait(signal) {
+        this.#waiters += 1;
+        try {
+            const waited = await waitForAbortable(this.promise, signal);
+            if (waited !== ABORTED)
+                return { status: "completed", value: waited };
+            if (this.#waiters > 1)
+                return { status: "cancelled" };
+            if (!this.settled)
+                this.#controller.abort(signal?.reason);
+            return { status: "stopped", value: await this.promise };
+        }
+        finally {
+            this.#waiters -= 1;
+        }
+    }
+}

package/dist/process/WindowsAuthority.js

@@ -1,51 +1,60 @@
-import { systemWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";
+import { systemWindowsNativeAuthority, } from "../windows/WindowsNativeLoader.js";
 /** Stable explanation used whenever the native Windows authority is absent. */
 export const WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON = "Windows native controls are unavailable in this runtime; use the Windows x64 REA package with its matching bundled native artifact.";
-/**
- * Describe native Windows controls without inferring them from taskkill,
- * chmod, symlink creation, or a numeric POSIX open flag.
- */
-export const windowsNativeCapabilities = (platform) => {
-    if (platform !== "win32") {
-        const notApplicable = {
+/** Interpret the loader's tagged failure without guessing from OS error text. */
+export const inspectWindowsNativeReadiness = (platform, observation) => {
+    if (platform !== "win32")
+        return {
             available: false,
+            failureStage: "host",
             reason: "Windows native authority is not applicable on this host",
             proof: "not-applicable",
+            code: "unsupported_host",
+            remediation: "Use a Windows x64 host for Windows native controls.",
         };
-        return {
-            job_object_process_ownership: notApplicable,
-            private_runtime_dacl: notApplicable,
-            reparse_safe_path_admission: notApplicable,
-        };
-    }
-    if (process.platform === "win32") {
-        const loaded = systemWindowsNativeAuthority();
-        const capability = loaded.available
-            ? { available: true, reason: null, proof: "native-authority" }
-            : {
-                available: false,
-                reason: loaded.reason,
-                proof: "not-proven",
-            };
-        return {
-            job_object_process_ownership: capability,
-            private_runtime_dacl: capability,
-            reparse_safe_path_admission: capability,
-        };
-    }
-    const notProven = {
+    const loaded = observation ?? systemWindowsNativeAuthority();
+    if (loaded.available)
+        return { available: true };
+    const failureStage = loaded.failureStage;
+    return {
         available: false,
-        reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
+        failureStage,
+        reason: loaded.reason,
+        ...(loaded.retryable === true ? { retryable: true } : {}),
         proof: "not-proven",
+        code: failureStage === "host"
+            ? "unsupported_host"
+            : failureStage === "artifact"
+                ? "runtime_missing"
+                : "runtime_unavailable",
+        remediation: failureStage === "host"
+            ? "Use a Windows x64 host and a supported Node.js runtime with Node-API 8 or newer."
+            : failureStage === "artifact"
+                ? "Use the matching Windows x64 REA package, or restore native/windows/build/manifest.json and native/windows/build/rea-windows-x64.node from the same-version rea-agents tarball or build them with native/windows/README.md. The loader checks version, ABI, architecture, and digest before granting authority; no download or install is performed automatically."
+                : failureStage === "inspection"
+                    ? "Install the matching Windows x64 REA package; its native inspection must prove every required security control."
+                    : "Inspect the preserved native self-test error. Check that the process's temporary directory is writable local NTFS and that its filesystem, DACL, Job Object, and cleanup operations are permitted. Resolve the reported constraint, then rerun rea doctor; reinstalling Ghidra or Java cannot fix this self-test.",
     };
+};
+/**
+ * Describe native Windows controls without inferring them from taskkill,
+ * chmod, symlink creation, or a numeric POSIX open flag.
+ */
+export const windowsNativeCapabilities = (platform, readiness = inspectWindowsNativeReadiness(platform)) => {
+    const capability = readiness.available
+        ? { available: true, reason: null, proof: "native-authority" }
+        : {
+            available: false,
+            reason: readiness.reason,
+            proof: readiness.proof,
+            code: readiness.code,
+            failureStage: readiness.failureStage,
+            remediation: readiness.remediation,
+            ...(readiness.retryable === true ? { retryable: true } : {}),
+        };
     return {
-        job_object_process_ownership: notProven,
-        private_runtime_dacl: notProven,
-        reparse_safe_path_admission: notProven,
+        job_object_process_ownership: capability,
+        private_runtime_dacl: capability,
+        reparse_safe_path_admission: capability,
     };
 };
-/** Whether every native control needed for Windows isolation is proven. */
-export const hasWindowsNativeAuthority = (platform) => Object.values(windowsNativeCapabilities(platform)).every(({ available }) => available);
-/** Preserve the actual loader or operating-system constraint in provider errors. */
-export const windowsNativeAuthorityUnavailableReason = (platform) => windowsNativeCapabilities(platform).job_object_process_ownership.reason ??
-    WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON;