@abot-ai/runtime 1.7.0 → 1.8.0

package/dist/src/computer-access/companion/observation-process.js

@@ -34,12 +34,19 @@ export function startDesktopCollector(options) {
     const command = desktopCollectorCommand(options.platform ?? process.platform);
     let child;
     let closed = false;
+    let stopped = false;
+    const confirmStopped = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        options.onStopped?.();
+    };
     let received = Buffer.alloc(0);
     let terminalStatus = false;
     const filter = new ObservationFilter(options.excludedApplications);
     const close = () => {
         closed = true;
-        if (!child?.pid)
+        if (stopped || !child?.pid)
             return;
         // POSIX language launchers can spawn an interpreter; stop the entire owned process group.
         if (process.platform !== "win32") {
@@ -59,6 +66,7 @@ export function startDesktopCollector(options) {
             state: "unavailable",
             reason: "platform_unsupported",
         });
+        confirmStopped();
         return { close };
     }
     if (process.platform === "darwin") {
@@ -77,19 +85,28 @@ export function startDesktopCollector(options) {
                 state: "unavailable",
                 reason: "macos_swift_tools_unavailable",
             });
+            confirmStopped();
             return { close };
         }
     }
     options.onEvent({ type: "status", state: "starting" });
-    child = (options.spawnProcess ?? spawn)(command.file, command.args, {
-        windowsHide: true,
-        detached: process.platform !== "win32",
-        stdio: ["pipe", "pipe", "pipe"],
-        env: {
-            ...process.env,
-            ABOT_OBSERVATION_EXCLUSIONS: JSON.stringify(options.excludedApplications),
-        },
-    });
+    try {
+        child = (options.spawnProcess ?? spawn)(command.file, command.args, {
+            windowsHide: true,
+            detached: process.platform !== "win32",
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                ABOT_OBSERVATION_EXCLUSIONS: JSON.stringify(options.excludedApplications),
+            },
+        });
+    }
+    catch {
+        options.onEvent({ type: "status", state: "failed", reason: "collector_start_failed" });
+        closed = true;
+        confirmStopped();
+        return { close };
+    }
     child.stdin?.on("error", () => { });
     child.stdin?.end(command.input);
     // Compiler/dependency diagnostics can contain local paths. Never forward them into model or general logs.
@@ -130,25 +147,34 @@ export function startDesktopCollector(options) {
         }
     });
     child.once("error", () => {
-        if (closed)
-            return;
-        options.onEvent({
-            type: "status",
-            state: "unavailable",
-            reason: "collector_dependency_unavailable",
-        });
-        close();
-    });
-    child.once("exit", (code) => {
-        if (closed)
-            return;
-        if (!terminalStatus)
+        try {
+            if (closed)
+                return;
             options.onEvent({
                 type: "status",
                 state: "unavailable",
-                reason: code === 0 ? "collector_stopped" : "collector_start_failed",
+                reason: "collector_dependency_unavailable",
             });
-        close();
+            close();
+        }
+        finally {
+            if (!child?.pid)
+                confirmStopped();
+        }
+    });
+    child.once("exit", (code) => {
+        try {
+            if (!closed && !terminalStatus)
+                options.onEvent({
+                    type: "status",
+                    state: "unavailable",
+                    reason: code === 0 ? "collector_stopped" : "collector_start_failed",
+                });
+        }
+        finally {
+            closed = true;
+            confirmStopped();
+        }
     });
     return { close };
 }

package/dist/src/computer-access/companion/observation-redaction.d.ts

@@ -1,9 +1,4 @@
 import type { PassiveObservationSource } from "../../shared/passive-observation.js";
-/**
- * Mask the entire field when a known secret indicator is present, including
- * surrounding useful text. No value boundaries or source-language grammar are
- * inferred. Unlabelled arbitrary secrets and unknown encodings remain outside
- * detection; this is not a guarantee that unchanged text contains no secrets.
- */
-export declare function redactObservationText(input: string): string;
+import { redactSecretText as redactObservationText } from "../security/secret-text.js";
+export { redactObservationText };
 export declare function redactObservationSource(source: PassiveObservationSource, sourceKey: string): PassiveObservationSource;

package/dist/src/computer-access/companion/observation-redaction.js

@@ -1,114 +1,5 @@
-const REDACTED = "[REDACTED]";
-const CREDENTIAL_KEY_SOURCE = String.raw `(?:[A-Za-z][A-Za-z0-9_-]*\.)*(?:[A-Za-z][A-Za-z0-9]*[-_])*(?:password|passwd|pwd|api[_ -]?key|access[_ -]?token|refresh[_ -]?token|client[_ -]?secret|secret[_ -]?access[_ -]?key|recovery[_ -]?code)`;
-const credentialIndicator = new RegExp(String.raw `(?<![\p{L}\p{N}_.-])(?:-{1,2})?(?:${CREDENTIAL_KEY_SOURCE}|(?:proxy-)?authorization)[\s"'\\]*[:=]`, "iu");
-/** Detection only: normalize ASCII encodings once, without interpreting a language. */
-function detectionText(input) {
-    const percentDecoded = input.replace(/%([0-7][0-9a-f])/giu, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
-    return percentDecoded.replace(/\\(?:u00|x|U000000)([0-7][0-9a-fA-F])/gu, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
-}
-function hasPrivateKeyIndicator(text) {
-    return /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/u.test(text);
-}
-function hasUrlCredentials(text) {
-    return /\b[a-z][a-z0-9+.-]*(?::|%3a)(?:\/|%2f){2}[^\s/?#<>]*(?:@|%40)/iu.test(text);
-}
-function hasAuthorizationCredentials(text) {
-    for (const match of text.matchAll(/\b(Bearer|Basic)[ \t]+([A-Za-z0-9._~+/-]+={0,2})/giu)) {
-        if (match[1].toLowerCase() === "bearer")
-            return true;
-        const value = match[2];
-        if (!/^[A-Za-z0-9+/]+={0,2}$/u.test(value))
-            continue;
-        if (value.length < 8)
-            continue;
-        if (Buffer.from(value, "base64").toString("utf8").includes(":"))
-            return true;
-    }
-    return false;
-}
-function isAwsAccessKeyValue(value, atEnd) {
-    if (/^[A-Z0-9]{16}$/u.test(value))
-        return true;
-    if (!atEnd)
-        return false;
-    return /^[A-Z0-9]{4,15}$/u.test(value);
-}
-function isRecognizedProviderToken(prefix, value, atEnd) {
-    if (prefix === "AKIA" || prefix === "ASIA")
-        return isAwsAccessKeyValue(value, atEnd);
-    if (value.length >= 20)
-        return true;
-    const partialMinimum = prefix === "sk-" ? 8 : 1;
-    return atEnd && value.length >= partialMinimum;
-}
-function hasProviderToken(text) {
-    const provider = /\b(sk-(?:proj-|svcacct-)?|gh[pousr]_|github_pat_|xox[baprs]-|AKIA|ASIA)([A-Za-z0-9_-]+)/gu;
-    for (const match of text.matchAll(provider)) {
-        const atEnd = match.index + match[0].length === text.length;
-        if (isRecognizedProviderToken(match[1], match[2], atEnd))
-            return true;
-    }
-    return false;
-}
-function compactJoseSegmentCount(header) {
-    try {
-        const value = JSON.parse(Buffer.from(header, "base64url").toString("utf8"));
-        if (typeof value !== "object" || value === null || Array.isArray(value))
-            return undefined;
-        const fields = value;
-        if (typeof fields.alg !== "string")
-            return undefined;
-        return typeof fields.enc === "string" ? 5 : 3;
-    }
-    catch {
-        return undefined;
-    }
-}
-function hasCompactJoseToken(text) {
-    const jose = /\b([A-Za-z0-9_-]+)(?:\.[A-Za-z0-9_-]*)+/gu;
-    for (const match of text.matchAll(jose)) {
-        const parts = match[0].split(".");
-        const capturedAtEnd = match.index + match[0].length === text.length;
-        for (let index = 0; index < parts.length - 1; index += 1) {
-            const expected = compactJoseSegmentCount(parts[index]);
-            if (expected === undefined)
-                continue;
-            if (expected === 3 && parts[index + 1] === "")
-                continue;
-            if (parts.length - index >= expected)
-                return true;
-            if (capturedAtEnd)
-                return true;
-        }
-    }
-    return false;
-}
-function hasSecretIndicator(text) {
-    if (credentialIndicator.test(text))
-        return true;
-    if (hasPrivateKeyIndicator(text))
-        return true;
-    if (hasUrlCredentials(text))
-        return true;
-    if (hasAuthorizationCredentials(text))
-        return true;
-    if (hasProviderToken(text))
-        return true;
-    return hasCompactJoseToken(text);
-}
-/**
- * Mask the entire field when a known secret indicator is present, including
- * surrounding useful text. No value boundaries or source-language grammar are
- * inferred. Unlabelled arbitrary secrets and unknown encodings remain outside
- * detection; this is not a guarantee that unchanged text contains no secrets.
- */
-export function redactObservationText(input) {
-    if (hasSecretIndicator(input))
-        return REDACTED;
-    if (hasSecretIndicator(detectionText(input)))
-        return REDACTED;
-    return input;
-}
+import { redactSecretText as redactObservationText } from "../security/secret-text.js";
+export { redactObservationText };
 export function redactObservationSource(source, sourceKey) {
     const redacted = {
         app: redactObservationText(source.app).slice(0, 128),

package/dist/src/computer-access/companion/secret-protection-protocol.d.ts

@@ -0,0 +1,6 @@
+/** Host-side observed-text protection before delivery, projection and transport.
+ * Command capture may temporarily retain unchecked bytes in private local files.
+ * Version 1 covers text and metadata; images are withheld when their associated
+ * text is suspect. It does not assert OCR or pixel-content inspection.
+ */
+export declare const HOST_SECRET_PROTECTION_CAPABILITY = "host_secret_protection_v1";

package/dist/src/computer-access/companion/secret-protection-protocol.js

@@ -0,0 +1,6 @@
+/** Host-side observed-text protection before delivery, projection and transport.
+ * Command capture may temporarily retain unchecked bytes in private local files.
+ * Version 1 covers text and metadata; images are withheld when their associated
+ * text is suspect. It does not assert OCR or pixel-content inspection.
+ */
+export const HOST_SECRET_PROTECTION_CAPABILITY = "host_secret_protection_v1";

package/dist/src/computer-access/computer/companion-sessions.js

@@ -6,6 +6,8 @@ import { computerNumber, computerText } from "./action-input.js";
 import { createNativeComputerBackend } from "./native-backend.js";
 import { COMPUTER_FRAME_CHUNK_BYTES, COMPUTER_IMAGE_MAX_BYTES, readNativeComputerRequest, readNativeComputerResult, } from "./native-validation.js";
 import { withDesktopQueue } from "./desktop-action-queue.js";
+import { protectDesktopResult } from "../security/desktop-result.js";
+import { protectObservedError } from "../security/observed-error.js";
 /** Connection-owned, bounded private sessions. No image is written to disk. */
 export class CompanionComputerSessions {
     platform;
@@ -30,9 +32,7 @@ export class CompanionComputerSessions {
             catch (error) {
                 return failureResult({
                     errorCode: "computer_native_operation_failed",
-                    message: error instanceof Error
-                        ? error.message
-                        : "The computer operation failed; observe before retrying.",
+                    message: protectObservedError(error, "The computer operation failed; observe before retrying."),
                 });
             }
         };
@@ -96,14 +96,15 @@ export class CompanionComputerSessions {
             const session = await this.acquire(id);
             this.eraseFrame(session);
             const result = await session.backend.execute(request, signal);
-            const { image, ...metadata } = result;
+            const { image: rawImage, ...rawMetadata } = result;
             try {
-                readNativeComputerResult(metadata);
+                readNativeComputerResult(rawMetadata);
             }
             catch (error) {
-                image?.bytes.fill(0);
+                rawImage?.bytes.fill(0);
                 throw error;
             }
+            const { image, ...metadata } = protectDesktopResult(result);
             if (!image)
                 return successResult({
                     output: "Native desktop observation.",

package/dist/src/computer-access/computer/unix-native-process.js

@@ -9,7 +9,7 @@ export function createUnixNativeProcess(options) {
     let failedReason;
     let buffer = Buffer.alloc(0);
     let queue = Promise.resolve();
-    let lastResult;
+    let lastDesktop;
     function interruptedResult(reason) {
         const dispatch = pending?.request.operation === "act"
             ? (pending.dispatch ?? {
@@ -19,13 +19,9 @@ export function createUnixNativeProcess(options) {
             })
             : undefined;
         const result = unavailableUnixDesktop(options.platform, reason, dispatch);
-        if (!lastResult)
+        if (!lastDesktop)
             return result;
-        return {
-            ...result,
-            desktop: { ...lastResult.desktop, available: false, reason },
-            windows: lastResult.windows,
-        };
+        return { ...result, desktop: { ...result.desktop, ...lastDesktop } };
     }
     function terminate(reason) {
         failedReason = reason;
@@ -38,6 +34,7 @@ export function createUnixNativeProcess(options) {
             retiring.once("exit", () => clearTimeout(hardStop));
         }
         child = undefined;
+        buffer.fill(0);
         buffer = Buffer.alloc(0);
     }
     function receiveLine(line) {
@@ -54,7 +51,18 @@ export function createUnixNativeProcess(options) {
         if (message.type !== "result")
             throw new Error("native_protocol_invalid");
         const result = readUnixNativeResult(message.result, options.platform);
-        lastResult = result;
+        // Retain only mechanical interruption identity, never observation content.
+        lastDesktop = {
+            binding: result.desktop.binding,
+            bounds: {
+                x: result.desktop.bounds.x,
+                y: result.desktop.bounds.y,
+                width: result.desktop.bounds.width,
+                height: result.desktop.bounds.height,
+            },
+            coordinateSpace: result.desktop.coordinateSpace,
+            targetingGuarantee: result.desktop.targetingGuarantee,
+        };
         pending.finish(result);
     }
     function ensureHelper() {
@@ -69,15 +77,19 @@ export function createUnixNativeProcess(options) {
         child.stdout.on("data", (chunk) => {
             if (closed || failedReason)
                 return;
-            buffer = Buffer.concat([buffer, chunk]);
+            const previous = buffer;
+            buffer = Buffer.concat([previous, chunk]);
+            previous.fill(0);
             if (buffer.length > NATIVE_JSON_LIMIT) {
                 terminate("computer_native_result_limit");
                 return;
             }
             let boundary = buffer.indexOf(10);
             while (boundary >= 0) {
-                const line = buffer.subarray(0, boundary).toString("utf8");
-                buffer = buffer.subarray(boundary + 1);
+                const received = buffer;
+                const line = received.subarray(0, boundary).toString("utf8");
+                buffer = Buffer.from(received.subarray(boundary + 1));
+                received.fill(0);
                 try {
                     receiveLine(line);
                 }

package/dist/src/computer-access/handlers.d.ts

@@ -1,4 +1,5 @@
 import { type ToolImplementation } from "../plugin-sdk/index.js";
 import { type SystemProcessRunner, type SystemTarget, type SystemTargetId } from "./contracts.js";
 import type { SystemCommandOutputFactory } from "./command-output.js";
-export declare function createSystemHandlers(run?: SystemProcessRunner, resolveTarget?: (id: SystemTargetId) => Promise<SystemTarget>, commandOutput?: SystemCommandOutputFactory): Record<string, ToolImplementation>;
+import type { SystemResultProtection } from "./system-result-protection.js";
+export declare function createSystemHandlers(run?: SystemProcessRunner, resolveTarget?: (id: SystemTargetId) => Promise<SystemTarget>, commandOutput?: SystemCommandOutputFactory, protection?: SystemResultProtection): Record<string, ToolImplementation>;

package/dist/src/computer-access/handlers.js

@@ -8,16 +8,63 @@ import { SystemOperationError, } from "./contracts.js";
 import { runSystemProcess } from "./process-runner.js";
 import { systemProcessResult } from "./process-result.js";
 import { readSystemTargetId, resolveSystemTarget } from "./targets.js";
-function withSystemOperationErrors(operation) {
+const PROTECTION_FAILURE = "The system result could not be protected for delivery.";
+function protectSystemResult(operation) {
+    try {
+        return operation();
+    }
+    catch {
+        throw new SystemOperationError("system_result_protection_failed", PROTECTION_FAILURE);
+    }
+}
+function failedSystemProtectionReceipt(target, result, evidenceScope) {
+    const safeProcess = {
+        status: result.status,
+        exitCode: result.exitCode,
+        outputTruncated: result.outputTruncated,
+        stdout: "[UNAVAILABLE: result protection failed]",
+        stderr: "[UNAVAILABLE: result protection failed]",
+        ...(result.spawnedProcess ? {
+            spawnedProcess: {
+                pid: result.spawnedProcess.pid,
+                pidNamespace: result.spawnedProcess.pidNamespace,
+                identitySource: result.spawnedProcess.identitySource,
+                executable: "[REDACTED]",
+            },
+        } : {}),
+    };
+    const receipt = systemProcessResult(target, safeProcess, evidenceScope);
+    return failureResult({
+        errorCode: "system_result_protection_failed",
+        message: PROTECTION_FAILURE,
+        output: "The operation was dispatched. Inspect the process receipt before another action; the command was not replayed.\n" + receipt.output,
+        stdout: safeProcess.stdout,
+        stderr: safeProcess.stderr,
+        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        data: receipt.data,
+    });
+}
+function withSystemOperationErrors(operation, protection) {
     return async (params, context) => {
         try {
             return await operation(params, context);
         }
         catch (error) {
+            let message = error instanceof Error ? error.message : undefined;
+            try {
+                if (protection && message !== undefined)
+                    message = protection.protectMessage(message);
+            }
+            catch {
+                return failureResult({
+                    errorCode: "system_result_protection_failed",
+                    message: PROTECTION_FAILURE,
+                });
+            }
             if (error instanceof SystemOperationError)
                 return failureResult({
                     errorCode: error.code,
-                    message: error.message,
+                    message: message,
                     data: {
                         humanActionRequired: error.code === "system_authorization_required",
                     },
@@ -30,9 +77,10 @@ function withSystemOperationErrors(operation) {
         }
     };
 }
-export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run), commandOutput) {
+export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run), commandOutput, protection) {
     const targets = async () => {
-        const observation = await observeSystemTargets(run);
+        const observed = await observeSystemTargets(run);
+        const observation = protection ? protectSystemResult(() => protection.protectTargets(observed)) : observed;
         return successResult({
             output: JSON.stringify(observation),
             data: {
@@ -44,13 +92,21 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
     const command = async (params, context) => {
         const target = await resolveTarget(readSystemTargetId(params.target));
         const output = commandOutput?.(context);
-        const result = await executeSystemCommand({
+        const observed = await executeSystemCommand({
             target,
             params,
             run,
             ...(output ? { runCommand: output.run } : {}),
             ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
         });
+        let result = observed;
+        try {
+            if (protection)
+                result = protection.protectProcess(observed);
+        }
+        catch {
+            return failedSystemProtectionReceipt(target, observed, "command_process_completion");
+        }
         if (output)
             return output.present(target, result);
         return systemProcessResult(target, result, "command_process_completion");
@@ -65,7 +121,8 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
                 minimum: 1,
                 maximum: 100,
             });
-        const catalog = await readSystemApplications(target, run);
+        const observed = await readSystemApplications(target, run);
+        const catalog = protection ? protectSystemResult(() => protection.protectCatalog(observed)) : observed;
         const { output, data } = systemApplicationObservation(target, catalog, query, limit);
         return successResult({
             output,
@@ -83,12 +140,23 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
             run,
             ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
         });
-        return systemProcessResult(target, result.process, "launch_request_dispatch", result.application);
+        let process = result.process;
+        let application = result.application;
+        try {
+            if (protection) {
+                process = protection.protectProcess(result.process);
+                application = protection.protectApplication(result.application);
+            }
+        }
+        catch {
+            return failedSystemProtectionReceipt(target, result.process, "launch_request_dispatch");
+        }
+        return systemProcessResult(target, process, "launch_request_dispatch", application);
     };
     return {
-        system_targets: withSystemOperationErrors(targets),
-        system_command: withSystemOperationErrors(command),
-        system_applications: withSystemOperationErrors(applications),
-        system_launch: withSystemOperationErrors(launch),
+        system_targets: withSystemOperationErrors(targets, protection),
+        system_command: withSystemOperationErrors(command, protection),
+        system_applications: withSystemOperationErrors(applications, protection),
+        system_launch: withSystemOperationErrors(launch, protection),
     };
 }

package/dist/src/computer-access/host-observation.d.ts

@@ -7,7 +7,7 @@ export type SystemHostFacts = Readonly<{
 export declare function readSystemHostFacts(): SystemHostFacts;
 export declare function isWslHostRuntime(facts: SystemHostFacts): boolean;
 export declare function observeSystemHost(facts?: SystemHostFacts): {
-    readonly runtimeOs: SystemTargetId | "unsupported";
+    readonly runtimeOs: "unsupported" | SystemTargetId;
     readonly kernelRelease: string;
     readonly environment: "container";
     readonly inferredHostOs: "unknown";
@@ -15,10 +15,10 @@ export declare function observeSystemHost(facts?: SystemHostFacts): {
     readonly windowsExecutionRequiresProbe: false;
     readonly guiSessionStatus: "not_checked";
 } | {
-    readonly runtimeOs: SystemTargetId | "unsupported";
+    readonly runtimeOs: "unsupported" | SystemTargetId;
     readonly kernelRelease: string;
     readonly environment: "wsl_guest" | "not_identified_as_wsl";
-    readonly inferredHostOs: SystemTargetId | "unsupported";
+    readonly inferredHostOs: "unsupported" | SystemTargetId;
     readonly hostInferenceSource: "wsl_kernel_signature" | "runtime_platform_only";
     readonly windowsExecutionRequiresProbe: boolean;
     readonly guiSessionStatus: "not_checked";

package/dist/src/computer-access/native-observation-connection.d.ts

@@ -0,0 +1,12 @@
+import type { HostObservationSubscription } from "../shared/passive-observation.js";
+import { startDesktopCollector } from "./companion/observation-process.js";
+import { acquireNativeObservationOwnership } from "./native-observation-ownership.js";
+type NativeObservationDependencies = Readonly<{
+    acquireOwnership?: typeof acquireNativeObservationOwnership;
+    startCollector?: typeof startDesktopCollector;
+}>;
+/** Local transport retains the existing collector's filtering and the source's owner/lease contract. */
+export declare function connectNativeObservations(options: HostObservationSubscription, dependencies?: NativeObservationDependencies): Promise<Readonly<{
+    close(): void;
+}>>;
+export {};

package/dist/src/computer-access/native-observation-connection.js

@@ -0,0 +1,78 @@
+import { startDesktopCollector } from "./companion/observation-process.js";
+import { acquireNativeObservationOwnership } from "./native-observation-ownership.js";
+import { createNativeObservationShutdown, waitForNativeObservationShutdown } from "./native-observation-shutdown.js";
+function canPublishNativeObservation(closed, signal) {
+    if (closed)
+        return false;
+    return !signal.aborted;
+}
+/** Local transport retains the existing collector's filtering and the source's owner/lease contract. */
+export async function connectNativeObservations(options, dependencies = {}) {
+    await waitForNativeObservationShutdown(options.rootDir, options.ownerId, options.abortSignal);
+    options.abortSignal.throwIfAborted();
+    const ownership = await (dependencies.acquireOwnership ?? acquireNativeObservationOwnership)(options.rootDir);
+    const shutdown = createNativeObservationShutdown(options.rootDir, options.ownerId);
+    let collector;
+    let closed = false;
+    let starting = true;
+    let stopped = false;
+    function onStopped() {
+        if (stopped)
+            return;
+        stopped = true;
+        closed = true;
+        options.abortSignal.removeEventListener("abort", close);
+        shutdown.begin();
+        void ownership.release().then(() => shutdown.confirmReleased()).catch(() => process.emitWarning("Native collection ownership could not be released.", { code: "NATIVE_OBSERVATION_RELEASE_FAILED" }));
+    }
+    function stopCollector() {
+        if (stopped)
+            return;
+        try {
+            collector?.close();
+        }
+        catch {
+            process.emitWarning("Native collector stop was not confirmed; its ownership is retained.", { code: "NATIVE_OBSERVATION_STOP_UNCONFIRMED" });
+        }
+    }
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        shutdown.begin();
+        options.abortSignal.removeEventListener("abort", close);
+        if (!starting)
+            stopCollector();
+    }
+    function onEvent(event) {
+        if (!canPublishNativeObservation(closed, options.abortSignal))
+            return;
+        try {
+            options.onEvent({ ...event, deviceId: ownership.deviceId, ownerId: options.ownerId, leaseId: options.leaseId });
+        }
+        catch {
+            process.emitWarning("Native observation delivery failed; collection is closing.", { code: "NATIVE_OBSERVATION_DELIVERY_FAILED" });
+            close();
+        }
+    }
+    options.abortSignal.addEventListener("abort", close, { once: true });
+    if (options.abortSignal.aborted) {
+        onStopped();
+        options.abortSignal.throwIfAborted();
+    }
+    try {
+        collector = (dependencies.startCollector ?? startDesktopCollector)({
+            excludedApplications: options.excludedApplications ?? [], onEvent, onStopped,
+        });
+    }
+    catch {
+        onEvent({ type: "status", state: "failed", reason: "collector_start_failed" });
+        close();
+    }
+    finally {
+        starting = false;
+        if (closed)
+            stopCollector();
+    }
+    return { close };
+}

package/dist/src/computer-access/native-observation-ownership.d.ts

@@ -0,0 +1,6 @@
+export type NativeObservationOwnership = Readonly<{
+    deviceId: string;
+    release(): Promise<void>;
+}>;
+/** One installation shares a device identity and exclusive collector across environment processes. */
+export declare function acquireNativeObservationOwnership(rootDir: string): Promise<NativeObservationOwnership>;