@modelprofile.com/browser-runtime 3.1.1 → 4.0.0

package/dist_ts/interfaces.d.ts

@@ -202,6 +202,7 @@ export interface IBrowserRuntimeState {
     lastError?: {
         code: string;
         fatal: boolean;
+        message?: string;
         tabId?: string;
     };
 }
@@ -289,6 +290,7 @@ export type TBrowserRuntimeEvent = {
     error: {
         code: string;
         fatal: boolean;
+        message?: string;
         tabId?: string;
     };
 } | {

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.1.1",
+  "version": "4.0.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,13 +23,14 @@
     "url": "https://community.foss.global/"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=24 <26"
   },
   "dependencies": {
     "@modelprofile.com/flexharness": "^4.0.0",
     "@push.rocks/smartagent": "^4.8.0",
+    "@push.rocks/smartipc": "^2.4.2",
     "@push.rocks/smartmcp": "^0.3.0",
-    "@push.rocks/smartpuppeteer": "^2.5.0",
+    "@push.rocks/smartpuppeteer": "^2.6.0",
     "ipaddr.js": "^2.5.0"
   },
   "devDependencies": {

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.
@@ -42,5 +49,6 @@ Durable implementation findings for `@modelprofile.com/browser-runtime`.
 - Framed request counts and queued write bytes are bounded. Runtime shutdown has a bounded caller-visible cleanup deadline while retaining in-flight cleanup ownership for retry.
 - Frame delivery owns a bounded map of exact identities and configures SmartPuppeteer's separate private CDP-to-ack map to the same limit. Equal limits prevent private eviction while the application map has spare capacity, but private-first retirement at full capacity can make an exact acknowledgement fulfill `{ accepted: false }`. Both fulfilled booleans settle the application entry without proving successful upstream retirement; rejection or timeout fails closed. Application acknowledgement timeout and failed delivery deliberately fail the lease regardless of a fulfilled boolean. There is no cumulative frame protocol.
 - During refresh, application entries plus refresh-owned acknowledgement promises share the same hard frame-window bound. ACK ownership is fixed at admission, refresh failures defer until the operation reservation is gone, and the exact failure fence completes before terminal audit, caller settlement, or FIFO advancement. Lifecycle teardown explicitly abandons an exact refresh record so stale state cannot retain `BUSY` admission.
+- Runtime state and error events preserve diagnostic messages only after truncating them to 2,048 characters. The first fatal session error invalidates exact capability admission synchronously, delivers once to the captured exact subscriber, and schedules revocation in `finally` so a throwing listener cannot retain authority.
 - Flex resolves only a capability token, and the provider's run must exactly match its trusted framed client. SmartAgent exposes exactly navigate, snapshot, screenshot, click, fill, and press.
 - MCP independent authentication returns the complete expected binding. The binding is retained in server-owned auth context and tool schemas expose no resource, session, revision, or authority selector.

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 or 25 on a non-root Linux x64 host. Production browser sessions require a sandbox-capable Chromium installation.
+The `NamedMutex` backend requires the `fs-ext-extra-prebuilt@2.2.9` install script to be approved by pnpm; startup fails closed with `FENCED` when the native backend 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
 
@@ -105,6 +124,8 @@ Operations from one valid lease enter a strict bounded FIFO. `maxQueuedOperation
 
 Human frame delivery keeps a bounded exact-identity application window. `maxOutstandingFrames` defaults to 4 and accepts values from 1 through 32. Runtime passes the same bound to SmartPuppeteer's private CDP-to-ack window; the windows remain separately owned, but equal limits prevent private eviction while the application window still has spare capacity. At full capacity SmartPuppeteer retires its oldest private entry before publishing the next frame, so a later exact acknowledgement can fulfill with `{ accepted: false }`. A fulfilled `true` or `false` settles the Runtime entry locally without fencing; `false` does not prove that upstream retirement succeeded. Rejected or timed-out acknowledgement operations fail closed, as do application acknowledgement timeout and failed-delivery retirement regardless of a fulfilled boolean. Frame acknowledgement stays outside the operation FIFO.
 
+Human state and error events retain an optional diagnostic `message` bounded to 2,048 characters. A fatal session error synchronously invalidates the exact capability before its captured subscriber is notified once, then revokes and cleans up the lease even when that subscriber throws.
+
 `humanLease.refreshFrameStream(options?: IBrowserRuntimeOperationOptions): Promise<void>` requires the lease's exact active frame subscription and enters the same audited FIFO as other browser mutations. Runtime retires the old application window, asks SmartPuppeteer for a new screencast generation, and succeeds only after the exact first new-generation frame was delivered through that subscription and validated against the current tab, viewport, lease, session, and incarnation. Existing and refresh-owned acknowledgement work share `maxOutstandingFrames`; synchronous listener acknowledgements cannot create an unbounded promise set. A missing or pre-execution-replaced subscription fails with `BUSY`. Refresh protocol, delivery, retirement, or acknowledgement failure returns `FRAME_STREAM_FAILED` or `FRAME_TOO_LARGE` only after the exact incarnation is fenced; stale authority returns `ABORTED` without touching its replacement. Pass `options.signal` for caller cancellation; active cancellation preserves a successfully restored stream.
 
 ## Trusted Pipe And Flex
@@ -136,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.1.1',
+  version: '4.0.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/actions.ts

@@ -184,9 +184,17 @@ const validateRuntimeState = (value: unknown): IBrowserRuntimeState => {
     );
   }
   if (state.lastError !== undefined) {
-    const lastError = validateExactKeys(state.lastError, ['code', 'fatal', 'tabId'], 'lastError');
+    const lastError = validateExactKeys(
+      state.lastError,
+      ['code', 'fatal', 'message', 'tabId'],
+      'lastError',
+    );
     validateBoundedString(lastError.code, 'lastError.code', 1, 128);
     if (typeof lastError.fatal !== 'boolean') throw new BrowserRuntimeError('PROTOCOL_ERROR');
+    if (
+      lastError.message !== undefined
+      && (typeof lastError.message !== 'string' || lastError.message.length > 2048)
+    ) throw new BrowserRuntimeError('PROTOCOL_ERROR');
     if (lastError.tabId !== undefined) validateBoundedString(lastError.tabId, 'lastError.tabId', 1, 128);
   }
   return value as IBrowserRuntimeState;

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]