@modelprofile.com/browser-runtime 3.2.0 → 4.1.0

package/dist_ts/internal.testing.d.ts

@@ -1,5 +1,6 @@
 import type * as plugins from './plugins.js';
 import type { IBrowserConfinementProbeContext, IBrowserRuntimeFramedClientOptions, IBrowserRuntimeOptions, IBrowserRuntimeEnvironment, ILiveBrowserSessionLike } from './interfaces.js';
+import type { IBrowserRuntimeOwnershipTestingOptions } from './classes.runtimeownership.js';
 export declare const browserRuntimeTesting: unique symbol;
 export interface IBrowserRuntimeTestingOptions extends IBrowserRuntimeOptions {
     [browserRuntimeTesting]: true;
@@ -11,6 +12,7 @@ export interface IBrowserRuntimeTestingOptions extends IBrowserRuntimeOptions {
     beforeFrameFailureTermination?(): Promise<void>;
     afterFrameFailureFence?(): Promise<void>;
     beforeFramedPeerLeasePublication?(): Promise<void>;
+    ownership?: IBrowserRuntimeOwnershipTestingOptions;
 }
 export interface IBrowserRuntimeFramedClientTestingOptions extends IBrowserRuntimeFramedClientOptions {
     [browserRuntimeTesting]: true;

package/dist_ts/internal.testing.js

@@ -1,2 +1,2 @@
 export const browserRuntimeTesting = Symbol('browserRuntimeTesting');
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJuYWwudGVzdGluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVybmFsLnRlc3RpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBU0EsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsTUFBTSxDQUFDLHVCQUF1QixDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJuYWwudGVzdGluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2ludGVybmFsLnRlc3RpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBVUEsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsTUFBTSxDQUFDLHVCQUF1QixDQUFDLENBQUMifQ==

package/dist_ts/plugins.d.ts

@@ -13,8 +13,9 @@ import * as url from 'node:url';
 export { Buffer, crypto, dns, fs, fsPromises, http, net, os, path, stream, tls, url };
 import * as flexharness from '@modelprofile.com/flexharness';
 import * as smartagent from '@push.rocks/smartagent';
+import * as smartipc from '@push.rocks/smartipc';
 import * as smartmcp from '@push.rocks/smartmcp';
 import * as smartpuppeteer from '@push.rocks/smartpuppeteer';
-export { flexharness, smartagent, smartmcp, smartpuppeteer };
+export { flexharness, smartagent, smartipc, smartmcp, smartpuppeteer };
 import ipaddr from 'ipaddr.js';
 export { ipaddr };

package/dist_ts/plugins.js

@@ -15,10 +15,11 @@ export { Buffer, crypto, dns, fs, fsPromises, http, net, os, path, stream, tls,
 // foss.global scopes
 import * as flexharness from '@modelprofile.com/flexharness';
 import * as smartagent from '@push.rocks/smartagent';
+import * as smartipc from '@push.rocks/smartipc';
 import * as smartmcp from '@push.rocks/smartmcp';
 import * as smartpuppeteer from '@push.rocks/smartpuppeteer';
-export { flexharness, smartagent, smartmcp, smartpuppeteer };
+export { flexharness, smartagent, smartipc, smartmcp, smartpuppeteer };
 // third-party scope
 import ipaddr from 'ipaddr.js';
 export { ipaddr };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLE1BQU0sTUFBTSxhQUFhLENBQUM7QUFDdEMsT0FBTyxLQUFLLEdBQUcsTUFBTSxVQUFVLENBQUM7QUFDaEMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUIsT0FBTyxLQUFLLFVBQVUsTUFBTSxrQkFBa0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssSUFBSSxNQUFNLFdBQVcsQ0FBQztBQUNsQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUM5QixPQUFPLEtBQUssSUFBSSxNQUFNLFdBQVcsQ0FBQztBQUNsQyxPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUVoQyxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxHQUFHLEVBQUUsRUFBRSxFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsR0FBRyxFQUFFLEVBQUUsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsQ0FBQztBQUV0RixxQkFBcUI7QUFDckIsT0FBTyxLQUFLLFdBQVcsTUFBTSwrQkFBK0IsQ0FBQztBQUM3RCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxRQUFRLE1BQU0sc0JBQXNCLENBQUM7QUFDakQsT0FBTyxLQUFLLGNBQWMsTUFBTSw0QkFBNEIsQ0FBQztBQUU3RCxPQUFPLEVBQUUsV0FBVyxFQUFFLFVBQVUsRUFBRSxRQUFRLEVBQUUsY0FBYyxFQUFFLENBQUM7QUFFN0Qsb0JBQW9CO0FBQ3BCLE9BQU8sTUFBTSxNQUFNLFdBQVcsQ0FBQztBQUUvQixPQUFPLEVBQUUsTUFBTSxFQUFFLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFDckMsT0FBTyxLQUFLLE1BQU0sTUFBTSxhQUFhLENBQUM7QUFDdEMsT0FBTyxLQUFLLEdBQUcsTUFBTSxVQUFVLENBQUM7QUFDaEMsT0FBTyxLQUFLLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDOUIsT0FBTyxLQUFLLFVBQVUsTUFBTSxrQkFBa0IsQ0FBQztBQUMvQyxPQUFPLEtBQUssSUFBSSxNQUFNLFdBQVcsQ0FBQztBQUNsQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUM5QixPQUFPLEtBQUssSUFBSSxNQUFNLFdBQVcsQ0FBQztBQUNsQyxPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUVoQyxPQUFPLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxHQUFHLEVBQUUsRUFBRSxFQUFFLFVBQVUsRUFBRSxJQUFJLEVBQUUsR0FBRyxFQUFFLEVBQUUsRUFBRSxJQUFJLEVBQUUsTUFBTSxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsQ0FBQztBQUV0RixxQkFBcUI7QUFDckIsT0FBTyxLQUFLLFdBQVcsTUFBTSwrQkFBK0IsQ0FBQztBQUM3RCxPQUFPLEtBQUssVUFBVSxNQUFNLHdCQUF3QixDQUFDO0FBQ3JELE9BQU8sS0FBSyxRQUFRLE1BQU0sc0JBQXNCLENBQUM7QUFDakQsT0FBTyxLQUFLLFFBQVEsTUFBTSxzQkFBc0IsQ0FBQztBQUNqRCxPQUFPLEtBQUssY0FBYyxNQUFNLDRCQUE0QixDQUFDO0FBRTdELE9BQU8sRUFBRSxXQUFXLEVBQUUsVUFBVSxFQUFFLFFBQVEsRUFBRSxRQUFRLEVBQUUsY0FBYyxFQUFFLENBQUM7QUFFdkUsb0JBQW9CO0FBQ3BCLE9BQU8sTUFBTSxNQUFNLFdBQVcsQ0FBQztBQUUvQixPQUFPLEVBQUUsTUFBTSxFQUFFLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/browser-runtime",
-  "version": "3.2.0",
+  "version": "4.1.0",
   "private": false,
   "description": "Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.",
   "main": "dist_ts/index.js",
@@ -23,11 +23,12 @@
     "url": "https://community.foss.global/"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24 <27"
   },
   "dependencies": {
     "@modelprofile.com/flexharness": "^4.0.0",
     "@push.rocks/smartagent": "^4.8.0",
+    "@push.rocks/smartipc": "^2.5.0",
     "@push.rocks/smartmcp": "^0.3.0",
     "@push.rocks/smartpuppeteer": "^2.6.0",
     "ipaddr.js": "^2.5.0"

package/readme.hints.md

@@ -4,6 +4,13 @@ Durable implementation findings for `@modelprofile.com/browser-runtime`.
 
 ## Ownership and lifecycle
 
+- Host-runtime liveness is owned by SmartIPC `NamedMutex` using a namespace bound to the UID and secured runtime-directory device, inode, and path hash. Its permanent private `runtime.mutex` anchor directory and file stay on the runtime directory's trusted local filesystem. Clean native contention is `LOCKED`; backend, anchor, lock, or release uncertainty is `FENCED`.
+- Persistent, fsynced `runtime.lock` metadata is a downgrade fence, not the live mutex, and is never removed by normal shutdown. Every start owns one metadata-named generation containing private profile and artifact roots.
+- Metadata-generation recovery performs no lock-descriptor scan. It removes only the exact named generation after checking every same-UID process for an absolute `--user-data-dir` equal to or below that profile root; this check is process-generic, not Chromium-specific.
+- Process ownership comes from all four `/proc/<pid>/status` `Uid:` values, not `/proc/<pid>` directory ownership. Only an exact same-UID or definite other-UID classification is actionable; mixed, unreadable, malformed, symlinked, wrongly owned/mode, hard-linked, ambiguous, or uncontained ownership state remains fenced.
+- Legacy zero-byte locks alone use exact-inode descriptor inspection. Adoption additionally requires birth, change, and modification timestamps strictly before bounded `/proc/stat` `btime`, plus no same-UID process using the exact or descendant legacy profile root. Same-boot, malformed, or ambiguous state remains fenced against the 3.2 close-before-unlink race.
+- A clean 3.2 stopped layout has no lock and may retain private empty top-level profile and artifact roots. The native-mutex winner validates, process-checks, and removes only those roots. Before metadata fsync succeeds, failure cleanup may unlink only the exact lock inode that acquisition just created; preexisting locks are never removed.
+- Shutdown attempts artifact and ownership cleanup after peer, revocation, or resource failures, retains retryable local slot state, and blocks restart until that state clears. Automatic ownership-loss cleanup gets one bounded retry; stale active metadata remains a fail-closed recovery fence.
 - Controller durable truth is a logical resource with immutable `projectId`, stable random `browserResourceId`, and a revisioned attachment binding. Runtime state is process-local and must be re-registered after every restart.
 - A resource slot owns only incarnation and arbitration state: its transition mutex, arbitration, incarnation, and process-local authority generations, lease, bounded operation FIFO, bounded frame window, Chromium session, authenticated egress proxy, private profile, and idle termination timer.
 - `terminateResource()` and idle termination remove only the incarnation. They preserve registration, attachment, capabilities, and artifacts. `retireResource()` permanently fences, revokes, terminates, purges exact-resource artifacts, then unregisters only after all cleanup succeeds. Durable retirement remains Controller truth; Runtime tombstones are bounded and process-local.

package/readme.md

@@ -12,11 +12,12 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm add @modelprofile.com/browser-runtime
 ```
 
-The runtime requires Node.js 24 or newer and a non-root Linux host. Production browser sessions require a sandbox-capable Chromium installation.
+The runtime requires Node.js 24 through 26 on a non-root Linux x64 host. Production browser sessions require a sandbox-capable Chromium installation.
+The `NamedMutex` backend uses the statically linked Rust helper packaged with `@push.rocks/smartipc`; startup fails closed with `FENCED` when the helper is unavailable.
 
 ## Resource Model
 
-The Controller owns durable resource and attachment truth. `BrowserRuntime` owns process-local registrations, fences, capabilities, leases, browser incarnations, artifacts, and its runtime lock. Registration never launches Chromium.
+The Controller owns durable resource and attachment truth. `BrowserRuntime` owns process-local registrations, fences, capabilities, leases, browser incarnations, artifacts, and its host-runtime ownership lease. Registration never launches Chromium.
 
 ```typescript
 import {
@@ -73,7 +74,25 @@ try {
 
 Projects and qualified sessions may each own many resources. Human/agent arbitration, mutexes, leases, operation queues, profiles, proxies, frame subscriptions, and idle timers are per resource.
 
-`registerResource()` is idempotent only for the same project/resource key and identical attachment. `listResources()` reports process-local registration and incarnation metadata. `terminateResource()` terminates only the current incarnation and preserves registration, attachment, and artifacts. `retireResource()` permanently fences the process-local registration, revokes and quiesces authority, terminates its incarnation, purges exact-resource artifacts, and unregisters only after cleanup succeeds. The Controller separately owns durable retirement truth and must not rehydrate retired resources. Runtime tombstones and registrations are ephemeral, bounded process state. `stop()` revokes all process-local capabilities, terminates every incarnation, removes the Runtime-owned artifact root and registrations, and releases the lock without deleting Controller durable truth. `cleanupTimeoutMs` defaults to 30,000 milliseconds and accepts values from 100 through 120,000. If that caller-visible deadline expires, `stop()` rejects with `TIMEOUT` while Runtime retains ownership of the cleanup still in flight; a later `stop()` rejoins it, and `start()` waits for it to finish before restarting.
+`registerResource()` is idempotent only for the same project/resource key and identical attachment. `listResources()` reports process-local registration and incarnation metadata. `terminateResource()` terminates only the current incarnation and preserves registration, attachment, and artifacts. `retireResource()` permanently fences the process-local registration, revokes and quiesces authority, terminates its incarnation, purges exact-resource artifacts, and unregisters only after cleanup succeeds. The Controller separately owns durable retirement truth and must not rehydrate retired resources. Runtime tombstones and registrations are ephemeral, bounded process state. `stop()` attempts peer, capability, resource, artifact-store, and ownership cleanup even when an earlier stage fails, then reports all failures together. It removes only the current generation, durably marks its owner metadata relinquished, and releases the native ownership lease when ownership cleanup succeeds. It intentionally leaves `runtime.lock` and the mutex anchor in place. Failed local slot cleanup remains retryable and blocks a new generation; automatic ownership-loss shutdown performs one additional bounded cleanup attempt. `cleanupTimeoutMs` defaults to 30,000 milliseconds and accepts values from 100 through 120,000. If that caller-visible deadline expires, `stop()` rejects with `TIMEOUT` while Runtime retains cleanup still in flight; a later `stop()` rejoins it, and `start()` waits for all prior local cleanup before restarting.
+
+## Host Runtime Ownership
+
+The runtime directory must be an owner-only `0700` directory on a trusted local filesystem; NFS and other network filesystems are unsupported. Its permanent `runtime.mutex` anchor directory is an owner-only `0700` directory on the same filesystem device. Runtime uses `@push.rocks/smartipc` `NamedMutex` with a namespace bound to the UID plus the validated runtime-directory device, inode, and path hash. SmartIPC keeps one permanent `0600`, single-link anchor file in `runtime.mutex` and holds a native advisory lock for the complete metadata and generation operation. Clean `tryAcquire()` contention returns `LOCKED`. Unsupported native backends, unsafe or changed anchors, native lock failures, and uncertain release return `FENCED`. Process exit, `SIGKILL`, and reboot release the advisory lock in the kernel.
+
+`runtime.lock` is a permanent `0600`, single-link regular file retained through an open descriptor while ownership is live. It is metadata and a downgrade fence, not the live mutex, and is never removed by `stop()`. Version 3.2 and older create-exclusive runtimes therefore remain fenced during and between new-runtime generations. Bounded JSON metadata is overwritten and fsynced through that descriptor. It records the schema, directory identity, UID, boot ID, PID, `/proc/self/stat` start ticks, generation ID, nonce, and active/relinquished state. Malformed metadata or unsafe directory, anchor, lock, link, ownership, mode, containment, or inspection state fails closed with `FENCED`.
+
+Each successful `start()` creates private `generations/<generationId>/profiles` and `generations/<generationId>/artifacts` directories. A replacement holding the native mutex may inspect and remove only the generation named by valid metadata. For metadata generations, Runtime does not scan `runtime.lock` descriptors. It inspects every same-UID process and returns `LOCKED` when any process, Chromium or otherwise, has an absolute `--user-data-dir` equal to or below that generation's profile root. Process ownership is classified from all four IDs in `/proc/<pid>/status` `Uid:`: exact same-UID processes are inspected, definite other-UID processes are ignored, and mixed or unreadable identity remains indeterminate. Unknown generations and indeterminate inspection remain fenced.
+
+A version 3.2 zero-byte lock uses a separate one-time migration gate. Runtime adopts it only when an exact-inode legacy descriptor scan finds no holder, the lock's birth, change, and modification timestamps are all strictly before the bounded `/proc/stat` `btime`, and no same-UID process has `--user-data-dir` equal to or below the legacy `profiles` root. A same-boot unheld lock is `FENCED`; this prevents takeover during the old owner's close-before-unlink window. Malformed boot data or ambiguous timestamps are also `FENCED`.
+
+When version 3.2 stopped cleanly and removed `runtime.lock`, it may leave empty top-level `profiles` and `artifacts` directories. After winning creation of a new lock under the native mutex, Runtime validates those directories as exact private empty roots, performs the same exact-or-descendant profile-process inspection, removes only the validated roots, and publishes the new metadata without applying the stale-lock boot gate. If startup fails before metadata is durably published, Runtime unlinks only that exact process-created lock inode while still holding the native mutex; a preexisting lock is never removed.
+
+## Breaking Changes
+
+The version 3.2 runtime-directory migration is one-way. A cleanly stopped 3.2 runtime that removed its zero-byte lock can be upgraded directly when any remaining top-level `profiles` and `artifacts` directories are private and empty. A stale 3.2 lock is recoverable only after reboot, once it conclusively predates the current boot and no legacy holder or profile process remains. The first successful new-runtime start writes permanent metadata and creates `runtime.mutex`; version 3.2 must not reuse that directory.
+
+To downgrade, first stop the new runtime and verify that no process still uses any generation profile path. Then remove the entire runtime directory, including `runtime.lock`, `runtime.mutex`, and `generations`, and let version 3.2 create a fresh directory. Never delete only the lock or anchor, and never perform this procedure while either runtime generation is active.
 
 ## Attachment Fencing
 
@@ -138,7 +157,7 @@ pnpm test
 pnpm run test:real-chrome
 ```
 
-The real Chromium check launches two resources in one project and qualified session, verifies distinct private profiles, sandboxed renderer process trees, mandatory confinement, screenshots, confirmed shutdown, and profile deletion.
+The real Chromium check launches two resources in one project and qualified session, verifies distinct generation-scoped private profiles, sandboxed renderer process trees, mandatory confinement, screenshots, confirmed shutdown, and generation deletion.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/browser-runtime',
-  version: '3.2.0',
+  version: '4.1.0',
   description: 'Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.'
 }

package/ts/classes.artifactstore.ts

@@ -32,7 +32,7 @@ interface IProjectArtifacts {
 }
 
 export class BrowserArtifactStore {
-  private readonly rootDirectory: string;
+  private rootDirectory: string;
   private readonly maxFileBytes: number;
   private readonly maxArtifactsPerResource: number;
   private readonly maxResourceBytes: number;
@@ -127,6 +127,17 @@ export class BrowserArtifactStore {
     return this.startPromise;
   }
 
+  /** @internal */
+  public setRootDirectoryForRuntime(rootDirectoryArg: string): void {
+    if (
+      !plugins.path.isAbsolute(rootDirectoryArg)
+      || this.started
+      || this.startPromise
+      || this.stopPromise
+    ) throw new BrowserRuntimeError('FENCED', 'artifact store cannot change generations');
+    this.rootDirectory = rootDirectoryArg;
+  }
+
   public stop(): Promise<void> {
     if (this.stopPromise) return this.stopPromise;
     if (!this.started && !this.startPromise) return Promise.resolve();
@@ -384,15 +395,7 @@ export class BrowserArtifactStore {
       }
       throw error;
     }
-    const stat = await plugins.fsPromises.lstat(this.rootDirectory);
-    const uid = process.getuid?.();
-    if (
-      !stat.isDirectory()
-      || stat.isSymbolicLink()
-      || (uid !== undefined && stat.uid !== uid)
-      || (stat.mode & 0o777) !== 0o700
-    ) throw new BrowserRuntimeError('FENCED', 'artifact root is not private');
-    await plugins.fsPromises.chmod(this.rootDirectory, 0o700);
+    await this.secureNewDirectory(this.rootDirectory);
     this.started = true;
     const sweepIntervalMs = Math.min(60_000, Math.max(1000, Math.floor(this.artifactTtlMs / 2)));
     this.sweepTimer = setInterval(() => {
@@ -411,10 +414,12 @@ export class BrowserArtifactStore {
 
   private async createProject(projectId: string): Promise<IProjectArtifacts> {
     const directoryName = this.digestDirectory(`project\0${projectId}`);
-    await plugins.fsPromises.mkdir(plugins.path.join(this.rootDirectory, directoryName), {
+    const projectDirectory = plugins.path.join(this.rootDirectory, directoryName);
+    await plugins.fsPromises.mkdir(projectDirectory, {
       recursive: false,
       mode: 0o700,
     });
+    await this.secureNewDirectory(projectDirectory);
     const project: IProjectArtifacts = {
       directoryName,
       totalBytes: 0,
@@ -431,10 +436,13 @@ export class BrowserArtifactStore {
     browserResourceId: string,
   ): Promise<IResourceArtifacts> {
     const directoryName = this.digestDirectory(`resource\0${projectId}\0${browserResourceId}`);
-    await plugins.fsPromises.mkdir(
-      plugins.path.join(this.rootDirectory, project.directoryName, directoryName),
-      { recursive: false, mode: 0o700 },
+    const resourceDirectory = plugins.path.join(
+      this.rootDirectory,
+      project.directoryName,
+      directoryName,
     );
+    await plugins.fsPromises.mkdir(resourceDirectory, { recursive: false, mode: 0o700 });
+    await this.secureNewDirectory(resourceDirectory);
     const resource: IResourceArtifacts = {
       browserResourceId,
       directoryName,
@@ -445,6 +453,35 @@ export class BrowserArtifactStore {
     return resource;
   }
 
+  private async secureNewDirectory(pathArg: string): Promise<void> {
+    await plugins.fsPromises.chmod(pathArg, 0o700);
+    const handle = await plugins.fsPromises.open(
+      pathArg,
+      plugins.fs.constants.O_RDONLY
+        | plugins.fs.constants.O_DIRECTORY
+        | plugins.fs.constants.O_NOFOLLOW,
+    );
+    try {
+      await handle.chmod(0o700);
+      await plugins.fsPromises.chmod(pathArg, 0o700);
+      const [pathStat, handleStat] = await Promise.all([
+        plugins.fsPromises.lstat(pathArg, { bigint: true }),
+        handle.stat({ bigint: true }),
+      ]);
+      const uid = process.getuid?.();
+      if (
+        !pathStat.isDirectory()
+        || pathStat.isSymbolicLink()
+        || (uid !== undefined && pathStat.uid !== BigInt(uid))
+        || (pathStat.mode & 0o777n) !== 0o700n
+        || pathStat.dev !== handleStat.dev
+        || pathStat.ino !== handleStat.ino
+      ) throw new BrowserRuntimeError('FENCED', 'artifact directory is not private');
+    } finally {
+      await handle.close();
+    }
+  }
+
   private async purgeExpiredInternal(resourceKey?: IBrowserResourceKey): Promise<number> {
     const projectEntries = resourceKey
       ? [[resourceKey.projectId, this.projects.get(resourceKey.projectId)] as const]

package/ts/classes.runtime.ts

@@ -2,6 +2,7 @@ import * as plugins from './plugins.js';
 import { validateAgentAction } from './actions.js';
 import { BrowserArtifactStore } from './classes.artifactstore.js';
 import { BrowserEgressProxy } from './classes.egressproxy.js';
+import { BrowserRuntimeOwnership } from './classes.runtimeownership.js';
 import { runProductionConfinementProbe } from './confinement.js';
 import { BrowserRuntimeError } from './errors.js';
 import {
@@ -89,6 +90,7 @@ interface INormalizedRuntimeOptions {
   maxOutstandingFrames: number;
   frameAcknowledgementTimeoutMs: number;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
+  ownership?: IBrowserRuntimeTestingOptions['ownership'];
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
   beforeIdleTermination?: IBrowserRuntimeTestingOptions['beforeIdleTermination'];
   beforeFrameFailureTermination?: IBrowserRuntimeTestingOptions['beforeFrameFailureTermination'];
@@ -233,9 +235,8 @@ const identifierMaximum = 256;
 
 export class BrowserRuntime {
   private readonly options: INormalizedRuntimeOptions;
-  private readonly profileRoot: string;
-  private readonly artifactRoot: string;
-  private readonly lockPath: string;
+  private readonly ownership: BrowserRuntimeOwnership;
+  private profileRoot?: string;
   private readonly artifactStore: BrowserArtifactStore;
   private readonly runtimeAuthorityId = randomId(18);
   private readonly slots = new Map<string, IResourceSlot>();
@@ -247,11 +248,10 @@ export class BrowserRuntime {
   private readonly capabilityMutex = new TransitionMutex();
   private readonly cleanupOperations = new Set<Promise<void>>();
   private readonly framedPeers = new Set<BrowserRuntimeFramedServerPeer>();
-  private lockHandle?: plugins.fsPromises.FileHandle;
-  private lockHandleClosed = false;
   private startPromise?: Promise<void>;
   private stopPromise?: Promise<void>;
   private stopCleanupPromise?: Promise<void>;
+  private localCleanupPending = false;
   private lifecycleState: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
   private lifecycleEpoch = 0;
   private lifecycleController = new AbortController();
@@ -473,17 +473,21 @@ export class BrowserRuntime {
         10_000,
       ),
       egress: options.egress ?? {},
+      ownership: testingOptions?.ownership,
       beforeLeasePublication: testingOptions?.beforeLeasePublication,
       beforeIdleTermination: testingOptions?.beforeIdleTermination,
       beforeFrameFailureTermination: testingOptions?.beforeFrameFailureTermination,
       afterFrameFailureFence: testingOptions?.afterFrameFailureFence,
       beforeFramedPeerLeasePublication: testingOptions?.beforeFramedPeerLeasePublication,
     };
-    this.profileRoot = plugins.path.join(options.runtimeDirectory, 'profiles');
-    this.artifactRoot = plugins.path.join(options.runtimeDirectory, 'artifacts');
-    this.lockPath = plugins.path.join(options.runtimeDirectory, 'runtime.lock');
+    this.ownership = new BrowserRuntimeOwnership({
+      runtimeDirectory: options.runtimeDirectory,
+      uid: environment.uid ?? -1,
+      testing: testingOptions?.ownership,
+      onOwnershipLost: () => this.handleOwnershipLost(),
+    });
     this.artifactStore = new BrowserArtifactStore({
-      rootDirectory: this.artifactRoot,
+      rootDirectory: plugins.path.join(options.runtimeDirectory, 'artifacts'),
       ...(options.artifacts ?? {}),
     });
   }
@@ -492,6 +496,13 @@ export class BrowserRuntime {
     if (this.lifecycleState === 'running') return Promise.resolve();
     if (this.startPromise) return this.startPromise;
     if (this.stopCleanupPromise) return this.stopCleanupPromise.then(() => this.start());
+    if (
+      this.lifecycleState === 'stopping'
+      || this.localCleanupPending
+      || this.ownership.cleanupPending
+    ) {
+      return this.stop().then(() => this.start());
+    }
     this.lifecycleState = 'starting';
     const epoch = ++this.lifecycleEpoch;
     this.lifecycleController = new AbortController();
@@ -515,7 +526,8 @@ export class BrowserRuntime {
     if (this.stopPromise) return this.stopPromise;
     if (
       this.lifecycleState === 'stopped'
-      && !this.lockHandle
+      && !this.localCleanupPending
+      && !this.ownership.cleanupPending
       && !this.startPromise
       && !this.stopCleanupPromise
     ) {
@@ -528,8 +540,13 @@ export class BrowserRuntime {
       const startup = this.startPromise;
       const cleanup = (async () => {
         await startup?.catch(() => undefined);
-        await this.stopInternal();
-        this.lifecycleState = 'stopped';
+        try {
+          await this.stopInternal();
+        } finally {
+          if (!this.localCleanupPending && !this.ownership.cleanupPending) {
+            this.lifecycleState = 'stopped';
+          }
+        }
       })();
       this.stopCleanupPromise = cleanup;
       void cleanup.then(
@@ -1321,7 +1338,7 @@ export class BrowserRuntime {
   ): Promise<Uint8Array> {
     this.requireHuman(lease);
     this.requireValidLease(lease);
-    return this.artifactStore.read(
+    return this.requireArtifactStore().read(
       lease.capability.projectId,
       lease.capability.browserResourceId,
       artifactId,
@@ -1332,7 +1349,7 @@ export class BrowserRuntime {
   public async deleteLeaseArtifact(lease: ILeaseRecord, artifactId: string): Promise<void> {
     this.requireHuman(lease);
     this.requireValidLease(lease);
-    await this.artifactStore.delete(
+    await this.requireArtifactStore().delete(
       lease.capability.projectId,
       lease.capability.browserResourceId,
       artifactId,
@@ -1360,30 +1377,31 @@ export class BrowserRuntime {
     if (this.options.environment.uid === undefined || this.options.environment.uid === 0) {
       throw new BrowserRuntimeError('FENCED', 'browser runtime requires a non-root uid');
     }
-    await plugins.fsPromises.mkdir(this.options.runtimeDirectory, { recursive: true, mode: 0o700 });
-    await plugins.fsPromises.chmod(this.options.runtimeDirectory, 0o700);
-    if (!this.lockHandle) {
+    const generation = await this.ownership.acquire();
+    this.profileRoot = generation.profileRoot;
+    try {
+      this.artifactStore.setRootDirectoryForRuntime(generation.artifactRoot);
+      await plugins.fsPromises.mkdir(this.profileRoot, { recursive: false, mode: 0o700 });
+      await this.secureNewPrivateDirectory(this.profileRoot);
+      await this.artifactStore.start();
+    } catch (error) {
       try {
-        this.lockHandle = await plugins.fsPromises.open(this.lockPath, 'wx', 0o600);
-        this.lockHandleClosed = false;
-        await this.lockHandle.chmod(0o600);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-          throw new BrowserRuntimeError('LOCKED');
-        }
-        throw error;
+        await this.ownership.release('startup-failure');
+        this.profileRoot = undefined;
+      } catch {
+        throw new BrowserRuntimeError('FENCED', 'runtime startup cleanup is incomplete');
       }
+      throw error;
     }
-    await plugins.fsPromises.mkdir(this.profileRoot, { recursive: true, mode: 0o700 });
-    await plugins.fsPromises.chmod(this.profileRoot, 0o700);
-    const profileEntries = await plugins.fsPromises.readdir(this.profileRoot);
-    if (profileEntries.length > 0) {
-      throw new BrowserRuntimeError('FENCED', 'profile root is not empty');
-    }
-    await this.artifactStore.start();
   }
 
   private async stopInternal(): Promise<void> {
+    this.localCleanupPending = true;
+    const errors: unknown[] = [];
+    const localErrors: unknown[] = [];
+    if (this.ownership.owned) {
+      await this.ownership.assertCurrentOwnership().catch((error) => errors.push(error));
+    }
     const peerResults = await Promise.allSettled(
       [...this.framedPeers].map((peer) => peer.close()),
     );
@@ -1402,34 +1420,98 @@ export class BrowserRuntime {
     while (this.cleanupOperations.size > 0) {
       await Promise.allSettled([...this.cleanupOperations]);
     }
-    const errors = [...peerResults, ...revokeResults, ...retirementResults]
+    localErrors.push(...[...peerResults, ...revokeResults, ...retirementResults]
       .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
-      .map((result) => result.reason);
+      .map((result) => result.reason));
+    await this.artifactStore.stop().catch((error) => localErrors.push(error));
+    errors.push(...localErrors);
+    await this.ownership.release('stop').catch((error) => errors.push(error));
+    if (localErrors.length === 0) {
+      this.localCleanupPending = false;
+      this.clearStoppedRuntimeState();
+    }
     if (errors.length > 0) {
       throw new AggregateError(errors, 'Browser runtime cleanup is incomplete');
     }
-    await this.artifactStore.stop();
-    if (this.lockHandle) {
-      if (!this.lockHandleClosed) {
-        await this.lockHandle.close();
-        this.lockHandleClosed = true;
-      }
-      await plugins.fsPromises.rm(this.lockPath, { force: true });
-      this.lockHandle = undefined;
-      this.lockHandleClosed = false;
-    }
+  }
+
+  private clearStoppedRuntimeState(): void {
+    this.profileRoot = undefined;
     this.slots.clear();
+    this.capabilitiesByDigest.clear();
+    this.capabilitiesById.clear();
+    this.failedRevocations.clear();
+    this.framedPeers.clear();
     this.retiredResourceIds.fill(0);
     this.retiredResourceKeys.fill(0);
     this.startPromise = undefined;
   }
 
+  private async secureNewPrivateDirectory(pathArg: string): Promise<void> {
+    const uid = this.options.environment.uid;
+    if (uid === undefined) throw new BrowserRuntimeError('FENCED');
+    await plugins.fsPromises.chmod(pathArg, 0o700);
+    const handle = await plugins.fsPromises.open(
+      pathArg,
+      plugins.fs.constants.O_RDONLY
+        | plugins.fs.constants.O_DIRECTORY
+        | plugins.fs.constants.O_NOFOLLOW,
+    );
+    try {
+      await handle.chmod(0o700);
+      await plugins.fsPromises.chmod(pathArg, 0o700);
+      const [pathStat, handleStat] = await Promise.all([
+        plugins.fsPromises.lstat(pathArg, { bigint: true }),
+        handle.stat({ bigint: true }),
+      ]);
+      if (
+        !pathStat.isDirectory()
+        || pathStat.isSymbolicLink()
+        || pathStat.uid !== BigInt(uid)
+        || (pathStat.mode & 0o777n) !== 0o700n
+        || pathStat.dev !== handleStat.dev
+        || pathStat.ino !== handleStat.ino
+      ) throw new BrowserRuntimeError('FENCED', 'runtime directory is not private');
+    } finally {
+      await handle.close();
+    }
+  }
+
   private requireRunning(): void {
-    if (this.lifecycleState !== 'running' || this.lifecycleController.signal.aborted) {
+    if (
+      this.lifecycleState !== 'running'
+      || this.lifecycleController.signal.aborted
+      || !this.ownership.owned
+    ) {
       throw new BrowserRuntimeError('NOT_RUNNING');
     }
   }
 
+  private requireArtifactStore(): BrowserArtifactStore {
+    this.requireRunning();
+    return this.artifactStore;
+  }
+
+  private handleOwnershipLost(): void {
+    if (this.lifecycleState === 'stopped' || this.lifecycleState === 'stopping') return;
+    this.lifecycleEpoch += 1;
+    this.lifecycleController.abort(new BrowserRuntimeError('FENCED'));
+    this.lifecycleState = 'stopping';
+    void this.stopAfterOwnershipLoss();
+  }
+
+  private async stopAfterOwnershipLoss(): Promise<void> {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        await this.stop();
+        return;
+      } catch {
+        if (!this.localCleanupPending && !this.ownership.cleanupPending) return;
+        await Promise.resolve();
+      }
+    }
+  }
+
   private async acquireAgentLease(
     slot: IResourceSlot,
     capability: TCapabilityRecord,
@@ -1570,7 +1652,9 @@ export class BrowserRuntime {
     if (slot.session) return;
     this.assertSlotAvailable(slot);
     this.reserveLaunch(slot);
-    const profileDirectory = plugins.path.join(this.profileRoot, randomId(24));
+    const profileRoot = this.profileRoot;
+    if (!profileRoot) throw new BrowserRuntimeError('FENCED');
+    const profileDirectory = plugins.path.join(profileRoot, randomId(24));
     let profileCreated = false;
     let proxy: BrowserEgressProxy | undefined;
     let session: ILiveBrowserSessionLike | undefined;
@@ -1578,7 +1662,7 @@ export class BrowserRuntime {
     try {
       await plugins.fsPromises.mkdir(profileDirectory, { mode: 0o700 });
       profileCreated = true;
-      await plugins.fsPromises.chmod(profileDirectory, 0o700);
+      await this.secureNewPrivateDirectory(profileDirectory);
       proxy = new BrowserEgressProxy({
         projectId: slot.projectId,
         browserResourceId: slot.browserResourceId,
@@ -2199,7 +2283,7 @@ export class BrowserRuntime {
         signal.throwIfAborted();
         this.requireValidLease(lease);
         if (lease.slot.session !== session) throw new BrowserRuntimeError('ABORTED');
-        const artifact = await this.artifactStore.store(
+        const artifact = await this.requireArtifactStore().store(
           lease.capability.projectId,
           lease.capability.browserResourceId,
           snapshot.mimeType,