@rightkit/qa 0.3.1 → 0.4.0

package/README.md

@@ -6,6 +6,14 @@ Shared QA primitives for Right Suite desktop apps. The package owns run locking,
 
 This package is intentionally private until the Windows and macOS phase gate passes. App repositories must never consume it through a Git, path, `file:`, `link:`, or `workspace:` dependency; adoption happens only after a registry version is published.
 
+## Run storage
+
+Run roots, harness evidence, captures & summaries remain under `<managed>/runs/<app>/<run-id>`. App homes, profiles, service/port files, live logs & app-provided output paths use an owned internal system-temp companion recorded as `appRoot` in `.rightkit-run.json`. On macOS, companions always use `/private/tmp/rightkit-qa/<app-prefix>-<random>` with short names so launchd can open app files & control socket paths fit `sockaddr_un`.
+
+Finish copies app logs to managed `evidence/`, app-written evidence to `evidence/app/` & app captures to `captures/` before releasing ownership. Disposal removes temp companions; failed copies or cleanup preserve ownership metadata for recovery. Retention & orphan pruning validate companion bindings & protect live runs.
+
+Workspace env sets `RIGHTKIT_RUN_ROOT`, `HOME` & `USERPROFILE` to `home`; `RIGHTKIT_SUITE_ROOT` to `home/suite`; data/profile keys to `home/data`; `XDG_CACHE_HOME` to `home/cache`; `TMPDIR`, `TMP` & `TEMP` to `home/tmp`. `RIGHTKIT_QA_EVIDENCE_DIR` & `RIGHTKIT_QA_CAPTURE_DIR` use `home/evidence` & `home/captures`. The JS package supplies workspace env; native UI bundle staging & unique per-launch suite/service identity belong to Rust `control::launch`.
+
 ## Chrome for Testing (`@rightkit/qa/chrome`)
 
 Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on macOS each regular Chrome instance clones its app bundle under `<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`, and a killed instance leaks that clone.
@@ -14,3 +22,52 @@ Web/CDP harnesses launch Chrome for Testing, never regular Google Chrome: on mac
 - `launchChromeForTesting(options)` starts it in its own process group with a temp profile and returns `{ wsEndpoint, port, pid, profileDir, close() }`. Launch one browser per suite and open targets per test.
 - `close()` / `closeChromeGracefully()` sends CDP `Browser.close`, waits up to 5 s, sends SIGTERM to the process group (`taskkill /T` on Windows), waits again, sends SIGKILL only last, then removes the profile. It reports the step that ended the tree.
 - `codeSignCloneEntries()` lists the macOS clone entries so tests can assert that none appear.
+
+## Raw CDP page driver (Node 26)
+
+`QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard` & `TimeoutError` are exported from `@rightkit/qa`. Transport uses Node's built-in `WebSocket` directly; no Puppeteer, Playwright, or CDP wrapper dependency.
+
+```ts
+import { launchChromeForTesting, QaBrowserSession } from '@rightkit/qa';
+
+const chrome = await launchChromeForTesting();
+const browser = await QaBrowserSession.connect(chrome.wsEndpoint);
+try {
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 1 });
+  await page.evaluateOnNewDocument(() => { window.localStorage.setItem('qa', '1'); });
+  await page.goto('http://127.0.0.1:3000', { waitUntil: 'networkidle0', timeout: 10_000 });
+  const button = await page.waitForSelector('button', { visible: true });
+  await button?.click();
+  await button?.dispose();
+  await page.screenshot({ path: 'viewport.png', type: 'png', captureBeyondViewport: false });
+} finally {
+  try { await browser.close(); } finally { await chrome.close(); }
+}
+```
+
+Session owns targets it creates; launcher owns browser process & profile. `connect(endpoint, { timeout, debug })` defaults to 30,000 ms per connection/command, with logging off. Positive finite deadlines apply to navigation & waits; failures use typed `TimeoutError`. `page.on(cdpMethod, listener)` subscribes to page-session events & returns an unsubscribe function. Debug callbacks receive method names only. Throwing event subscribers are isolated from transport state.
+
+Evaluation uses main frame's default execution context, awaits promises & returns values by JSON. Functions run in Chrome, so pass external values as arguments rather than closing over Node variables. JavaScript exceptions become `Error` with Chrome's message. `evaluateOnNewDocument` accepts function + arguments or source text & runs before document scripts, including subsequent reloads.
+
+`goto`/`reload` support `load`, `domcontentloaded` & `networkidle0` (zero outstanding requests for 500 ms). `waitForSelector` supports present/visible/hidden states; hidden waits return `null`. `waitForFunction` supports animation-frame or positive millisecond polling & resolves when predicate is truthy. Both name selector/predicate in timeout errors. `$`/`$$` return remote element handles, released by `dispose()`, navigation, or page closure.
+
+Click/hover scroll elements into view & use box centres. Mouse, keyboard & text input use CDP `Input` commands; `select` dispatches DOM `input`/`change` after selecting values. Keyboard supports required navigation/editing keys, letters/digits & modifier chords such as `Control+A`, `Meta+A`, or `Shift+ArrowLeft`. Screenshots return `Buffer`, optionally write `path`, & capture viewport PNG at configured DPR; `fullPage` & `captureBeyondViewport` support `false` only.
+
+| Puppeteer | QaPage equivalent |
+|---|---|
+| `puppeteer.connect({ browserWSEndpoint })` | `QaBrowserSession.connect(wsEndpoint)` |
+| `browser.newPage()` / `browser.close()` | Same calls; session closes owned targets |
+| `page.goto()` / `reload()` / `close()` | Same calls & navigation options |
+| `page.setViewport()` | Same call; CDP device metrics |
+| `page.evaluateOnNewDocument()` | Same call; function or source |
+| `page.evaluate()` / `$eval()` / `$$eval()` | Same calls; JSON results & awaited promises |
+| `page.waitForSelector()` | Same options; `QaElement` or `null` |
+| `page.waitForFunction()` | Same predicate/options/arguments; returns `void` |
+| `page.$()` / `page.$$()` | `QaElement` / `QaElement[]` |
+| `element.click/type/hover/focus/boundingBox/evaluate/dispose()` | Same calls on `QaElement` |
+| `page.click/type/hover/focus/select()` | Same calls; click accepts selector or handle |
+| `page.keyboard.press()` | Same call; named key or modifier chord |
+| `page.screenshot()` | Viewport PNG `Buffer`; optional `path` |
+
+`pnpm --dir packages/qa test` runs mock-WebSocket unit tests & real Chrome for Testing integration against local static fixture. Install Chrome through `@rightkit/qa-chrome` or set `RIGHTKIT_CHROME_FOR_TESTING`; integration requires Chrome & does not silently skip.

package/dist/cdp.d.ts

@@ -0,0 +1,32 @@
+/** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export interface QaConnectOptions {
+    /** Default 30 seconds; applies to connection & each CDP command. */
+    timeout?: number;
+    /** Off by default. Receives method names only, never evaluated source or input text. */
+    debug?: (message: string) => void;
+}
+export type CdpParams = Record<string, any>;
+type Listener = (params: CdpParams) => void;
+/** @internal All operations use finite deadlines. */
+export declare function validateTimeout(timeout: number): number;
+export declare class CdpClient {
+    private socket;
+    readonly timeout: number;
+    private debug?;
+    private nextId;
+    private pending;
+    private listeners;
+    private closed?;
+    private constructor();
+    static connect(endpoint: string, options?: QaConnectOptions): Promise<CdpClient>;
+    send(method: string, params?: CdpParams, session?: string, timeout?: number): Promise<CdpParams>;
+    on(method: string, listener: Listener, session?: string): () => void;
+    private emit;
+    rejectSession(session: string, error: Error): void;
+    private fail;
+    close(): void;
+}
+export {};

package/dist/cdp.js

@@ -0,0 +1,141 @@
+/** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
+export class TimeoutError extends Error {
+    constructor(message) { super(message); this.name = 'TimeoutError'; }
+}
+/** @internal All operations use finite deadlines. */
+export function validateTimeout(timeout) {
+    if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2_147_483_647)
+        throw new Error('Timeout must be a positive finite number below 2147483648ms');
+    return timeout;
+}
+export class CdpClient {
+    socket;
+    timeout;
+    debug;
+    nextId = 0;
+    pending = new Map();
+    listeners = new Map();
+    closed;
+    constructor(socket, timeout, debug) {
+        this.socket = socket;
+        this.timeout = timeout;
+        this.debug = debug;
+        socket.addEventListener('message', (event) => {
+            let message;
+            try {
+                message = JSON.parse(String(event.data));
+            }
+            catch (error) {
+                this.fail(new Error(`Invalid CDP message: ${String(error)}`));
+                this.socket.close();
+                return;
+            }
+            if (message.id !== undefined) {
+                const pending = this.pending.get(message.id);
+                if (!pending)
+                    return;
+                this.pending.delete(message.id);
+                clearTimeout(pending.timer);
+                if (message.error)
+                    pending.reject(new Error(`CDP: ${message.error.message}`));
+                else
+                    pending.resolve(message.result ?? {});
+            }
+            else if (message.method) {
+                this.emit(message.method, message.params ?? {}, message.sessionId);
+            }
+        });
+        socket.addEventListener('close', () => this.fail(new Error('CDP socket closed')));
+        socket.addEventListener('error', () => this.fail(new Error('CDP socket error')));
+    }
+    static async connect(endpoint, options = {}) {
+        const timeout = validateTimeout(options.timeout ?? 30_000);
+        const socket = new WebSocket(endpoint);
+        const client = new CdpClient(socket, timeout, options.debug);
+        await new Promise((resolve, reject) => {
+            const done = (error) => {
+                clearTimeout(timer);
+                socket.removeEventListener('open', open);
+                socket.removeEventListener('error', errorHandler);
+                socket.removeEventListener('close', close);
+                if (error) {
+                    client.close();
+                    reject(error);
+                }
+                else
+                    resolve();
+            };
+            const open = () => done();
+            const errorHandler = () => done(new Error('CDP connection failed'));
+            const close = () => done(new Error('CDP socket closed while connecting'));
+            const timer = setTimeout(() => done(new TimeoutError(`CDP connect timed out after ${timeout}ms`)), timeout);
+            socket.addEventListener('open', open);
+            socket.addEventListener('error', errorHandler);
+            socket.addEventListener('close', close);
+        });
+        return client;
+    }
+    send(method, params = {}, session, timeout = this.timeout) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        validateTimeout(timeout);
+        this.debug?.(`CDP ${method}`);
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new TimeoutError(`${method} timed out after ${timeout}ms`));
+            }, timeout);
+            this.pending.set(id, { resolve, reject, timer, session });
+            try {
+                this.socket.send(JSON.stringify({ id, method, params, ...(session ? { sessionId: session } : {}) }));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    on(method, listener, session) {
+        const key = `${session ?? ''}:${method}`;
+        let listeners = this.listeners.get(key);
+        if (!listeners)
+            this.listeners.set(key, listeners = new Set());
+        listeners.add(listener);
+        return () => { listeners.delete(listener); if (!listeners.size)
+            this.listeners.delete(key); };
+    }
+    emit(method, params, session) {
+        for (const listener of [...(this.listeners.get(`${session ?? ''}:${method}`) ?? [])]) {
+            // A user subscription cannot corrupt transport state or suppress internal listeners.
+            try {
+                listener(params);
+            }
+            catch {
+                this.debug?.(`CDP listener failed: ${method}`);
+            }
+        }
+    }
+    rejectSession(session, error) {
+        for (const [id, pending] of this.pending)
+            if (pending.session === session) {
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                pending.reject(error);
+            }
+    }
+    fail(error) {
+        if (this.closed)
+            return;
+        this.closed = error;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.emit('Disconnected', { error });
+        this.listeners.clear();
+    }
+    close() { this.fail(new Error('CDP socket closed')); this.socket.close(); }
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
 export * from './storage.js';
+export * from './page.js';

package/dist/index.js

@@ -9,3 +9,4 @@ export * from './panes.js';
 export * from './process.js';
 export * from './workspace.js';
 export * from './storage.js';
+export * from './page.js';

package/dist/keyboard.d.ts

@@ -0,0 +1,9 @@
+import type { CdpParams } from './cdp.js';
+export declare const modifierBits: Record<string, number>;
+export declare function keyDefinition(key: string, modifiers: number): CdpParams;
+export declare class QaKeyboard {
+    private send;
+    constructor(send: (method: string, params: CdpParams) => Promise<CdpParams>);
+    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    press(chord: string): Promise<void>;
+}

package/dist/keyboard.js

@@ -0,0 +1,79 @@
+const special = {
+    Escape: ['Escape', 27], Enter: ['Enter', 13, '\r'], Tab: ['Tab', 9],
+    ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40],
+    Backspace: ['Backspace', 8], Delete: ['Delete', 46], Home: ['Home', 36], End: ['End', 35],
+    PageUp: ['PageUp', 33], PageDown: ['PageDown', 34], Space: ['Space', 32, ' '],
+    Shift: ['ShiftLeft', 16], Control: ['ControlLeft', 17], Alt: ['AltLeft', 18], Meta: ['MetaLeft', 91],
+};
+export const modifierBits = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+export function keyDefinition(key, modifiers) {
+    const named = special[key];
+    let code, windowsVirtualKeyCode, text;
+    if (named)
+        [code, windowsVirtualKeyCode, text] = named;
+    else if (/^[a-z]$/i.test(key)) {
+        code = `Key${key.toUpperCase()}`;
+        windowsVirtualKeyCode = key.toUpperCase().charCodeAt(0);
+        key = modifiers & 8 ? key.toUpperCase() : modifiers & 7 ? key.toLowerCase() : key;
+        text = key;
+    }
+    else if (/^[0-9]$/.test(key)) {
+        code = `Digit${key}`;
+        windowsVirtualKeyCode = key.charCodeAt(0);
+        key = modifiers & 8 ? ')!@#$%^&*('[Number(key)] : key;
+        text = key;
+    }
+    else if (key === ' ') {
+        code = 'Space';
+        windowsVirtualKeyCode = 32;
+        text = ' ';
+    }
+    else
+        throw new Error(`Unsupported key: ${key}`);
+    if (key === 'Space')
+        key = ' ';
+    if (modifiers & (1 | 2 | 4))
+        text = undefined;
+    const unmodifiedText = code.startsWith('Key') ? code.slice(3).toLowerCase() : code.startsWith('Digit') ? code.slice(5) : text;
+    return { key, code, windowsVirtualKeyCode, modifiers, ...(text ? { text, unmodifiedText } : {}) };
+}
+export class QaKeyboard {
+    send;
+    constructor(send) {
+        this.send = send;
+    }
+    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    async press(chord) {
+        const parts = chord.split('+');
+        if (parts.some((part, i) => i < parts.length - 1 && !modifierBits[part]))
+            throw new Error(`Invalid key chord: ${chord}`);
+        keyDefinition(parts.at(-1), 0); // Validate before holding any modifier.
+        let modifiers = 0;
+        const held = [];
+        let failure;
+        try {
+            for (const part of parts) {
+                modifiers |= modifierBits[part] ?? 0;
+                const definition = keyDefinition(part, modifiers);
+                await this.send('Input.dispatchKeyEvent', { type: definition.text ? 'keyDown' : 'rawKeyDown', ...definition });
+                held.push(part);
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        finally {
+            for (const part of held.reverse()) {
+                modifiers &= ~(modifierBits[part] ?? 0);
+                try {
+                    await this.send('Input.dispatchKeyEvent', { type: 'keyUp', ...keyDefinition(part, modifiers), text: undefined, unmodifiedText: undefined });
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+        }
+        if (failure)
+            throw failure;
+    }
+}

package/dist/page.d.ts

@@ -0,0 +1,143 @@
+import { CdpClient, type CdpParams, type QaConnectOptions } from './cdp.js';
+import { QaKeyboard } from './keyboard.js';
+export { TimeoutError, type QaConnectOptions } from './cdp.js';
+export { QaKeyboard } from './keyboard.js';
+export interface NavigationOptions {
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0';
+    timeout?: number;
+}
+export interface ViewportOptions {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+    mobile?: boolean;
+}
+export interface WaitOptions {
+    timeout?: number;
+    polling?: 'raf' | number;
+}
+export interface SelectorWaitOptions {
+    visible?: boolean;
+    hidden?: boolean;
+    timeout?: number;
+}
+export interface ClickOptions {
+    button?: 'left' | 'right' | 'middle';
+    clickCount?: number;
+    delay?: number;
+}
+export interface TypeOptions {
+    delay?: number;
+}
+export interface ScreenshotOptions {
+    path?: string;
+    type?: 'png';
+    captureBeyondViewport?: false;
+    fullPage?: false;
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type PageFunction<Args extends unknown[], Result> = (...args: Args) => Result;
+/** Owns only targets it creates; launcher owns browser process & profile cleanup. */
+export declare class QaBrowserSession {
+    private client;
+    private pages;
+    private closed;
+    private closing?;
+    private opening;
+    private constructor();
+    static connect(wsEndpoint: string, options?: QaConnectOptions): Promise<QaBrowserSession>;
+    newPage(): Promise<QaPage>;
+    private createPage;
+    close(): Promise<void>;
+}
+export declare class QaPage {
+    private client;
+    readonly targetId: string;
+    private sessionId;
+    private onClosed;
+    readonly keyboard: QaKeyboard;
+    private frameId?;
+    private contexts;
+    private contextId?;
+    private handles;
+    private unsubs;
+    private subscriptions;
+    private closed?;
+    private closing?;
+    private closedListeners;
+    private requests;
+    private frameParents;
+    private lastNetworkActivity;
+    private generation;
+    private navigating;
+    private get objectGroup();
+    /** @internal Use QaBrowserSession.newPage(). */
+    constructor(client: CdpClient, targetId: string, sessionId: string, onClosed: () => void);
+    private chooseContext;
+    /** Subscribe to this page's raw CDP events; returned function unsubscribes. */
+    on(method: string, listener: (params: CdpParams) => void): () => void;
+    /** @internal */
+    initialize(): Promise<void>;
+    /** @internal */
+    send(method: string, params?: CdpParams, timeout?: number): Promise<CdpParams>;
+    private invalidateHandles;
+    /** @internal */
+    markClosed(error?: Error): void;
+    close(): Promise<void>;
+    private bounded;
+    private mainContext;
+    private navigate;
+    goto(url: string, options?: NavigationOptions): Promise<void>;
+    reload(options?: NavigationOptions): Promise<void>;
+    setViewport(options: ViewportOptions): Promise<void>;
+    evaluateOnNewDocument<Args extends unknown[]>(fn: PageFunction<Args, unknown> | string, ...args: Args): Promise<void>;
+    private run;
+    evaluate<Args extends unknown[], Result>(fn: PageFunction<Args, Result> | string, ...args: Args): Promise<Awaited<Result>>;
+    /** @internal */
+    callElement<Args extends unknown[], Result>(handle: QaElement, fn: (element: HTMLElement, ...args: Args) => Result, args: Args): Promise<Awaited<Result>>;
+    private handle;
+    $(selector: string): Promise<QaElement | null>;
+    private lookup;
+    $$(selector: string): Promise<QaElement[]>;
+    $eval<Args extends unknown[], Result>(selector: string, fn: (element: HTMLElement, ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    $$eval<Args extends unknown[], Result>(selector: string, fn: (elements: HTMLElement[], ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    private runSourceFunction;
+    waitForFunction<Args extends unknown[]>(fn: PageFunction<Args, unknown> | string, options?: WaitOptions, ...args: Args): Promise<void>;
+    waitForSelector(selector: string, options?: SelectorWaitOptions): Promise<QaElement | null>;
+    private requireElement;
+    private withElement;
+    private point;
+    click(target: string | QaElement, options?: ClickOptions): Promise<void>;
+    type(selector: string, text: string, options?: TypeOptions): Promise<void>;
+    /** @internal */
+    typeElement(handle: QaElement, text: string, options?: TypeOptions): Promise<void>;
+    hover(target: string | QaElement): Promise<void>;
+    focus(target: string | QaElement): Promise<void>;
+    select(selector: string, ...values: string[]): Promise<string[]>;
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+}
+/** Remote DOM reference; dispose explicitly or let navigation release its object group. */
+export declare class QaElement {
+    private page;
+    readonly objectId: string;
+    private onDisposed;
+    private disposed;
+    /** @internal */
+    constructor(page: QaPage, objectId: string, onDisposed: () => void);
+    /** @internal */
+    assertUsable(page: QaPage): void;
+    /** @internal */
+    invalidate(): void;
+    dispose(): Promise<void>;
+    evaluate<Args extends unknown[], Result>(fn: (element: HTMLElement, ...args: Args) => Result, ...args: Args): Promise<Awaited<Result>>;
+    click(options?: ClickOptions): Promise<void>;
+    type(text: string, options?: TypeOptions): Promise<void>;
+    hover(): Promise<void>;
+    focus(): Promise<void>;
+    boundingBox(): Promise<BoundingBox | null>;
+}

package/dist/page.js

@@ -0,0 +1,573 @@
+import { writeFile } from 'node:fs/promises';
+import { CdpClient, TimeoutError, validateTimeout } from './cdp.js';
+import { QaKeyboard } from './keyboard.js';
+export { TimeoutError } from './cdp.js';
+export { QaKeyboard } from './keyboard.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function functionSource(fn) {
+    const source = fn.toString();
+    if (source.includes('[native code]'))
+        throw new Error('Cannot evaluate native function');
+    // Parse only (never execute) to distinguish methods from async arrow functions.
+    try {
+        new Function(`return (${source}\n)`);
+    }
+    catch {
+        const declaration = source.startsWith('async ') ? source.replace(/^async\s+/, 'async function ') : `function ${source}`;
+        new Function(`return (${declaration}\n)`);
+        return declaration;
+    }
+    return source;
+}
+function argument(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value === 'number' && (!Number.isFinite(value) || Object.is(value, -0)))
+        return { unserializableValue: Object.is(value, -0) ? '-0' : String(value) };
+    if (typeof value === 'bigint')
+        return { unserializableValue: `${value}n` };
+    return { value };
+}
+function resultValue(result) {
+    if (result.exceptionDetails) {
+        throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.exception?.value ?? result.exceptionDetails.text ?? 'JavaScript evaluation failed');
+    }
+    return result.result?.value;
+}
+/** Owns only targets it creates; launcher owns browser process & profile cleanup. */
+export class QaBrowserSession {
+    client;
+    pages = new Set();
+    closed = false;
+    closing;
+    opening = new Set();
+    constructor(client) {
+        this.client = client;
+    }
+    static async connect(wsEndpoint, options = {}) {
+        return new QaBrowserSession(await CdpClient.connect(wsEndpoint, options));
+    }
+    newPage() {
+        if (this.closed)
+            return Promise.reject(new Error('Browser session closed'));
+        const pending = this.createPage();
+        this.opening.add(pending);
+        void pending.then(() => this.opening.delete(pending), () => this.opening.delete(pending));
+        return pending;
+    }
+    async createPage() {
+        const { targetId } = await this.client.send('Target.createTarget', { url: 'about:blank' });
+        try {
+            const { sessionId } = await this.client.send('Target.attachToTarget', { targetId, flatten: true });
+            const page = new QaPage(this.client, targetId, sessionId, () => this.pages.delete(page));
+            this.pages.add(page);
+            await page.initialize();
+            if (this.closed)
+                throw new Error('Browser session closed');
+            return page;
+        }
+        catch (error) {
+            await this.client.send('Target.closeTarget', { targetId }).catch(() => { });
+            for (const page of this.pages)
+                if (page.targetId === targetId)
+                    page.markClosed();
+            throw error;
+        }
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closed = true;
+        this.closing = (async () => {
+            try {
+                await Promise.allSettled([...this.opening]);
+                const results = await Promise.allSettled([...this.pages].map((page) => page.close()));
+                const failed = results.find((result) => result.status === 'rejected');
+                if (failed?.status === 'rejected')
+                    throw failed.reason;
+            }
+            finally {
+                this.client.close();
+            }
+        })();
+        return this.closing;
+    }
+}
+export class QaPage {
+    client;
+    targetId;
+    sessionId;
+    onClosed;
+    keyboard;
+    frameId;
+    contexts = new Map();
+    contextId;
+    handles = new Set();
+    unsubs = [];
+    subscriptions = new Set();
+    closed;
+    closing;
+    closedListeners = new Set();
+    requests = new Map();
+    frameParents = new Map();
+    lastNetworkActivity = 0;
+    generation = 0;
+    navigating = false;
+    get objectGroup() { return `qa-elements-${this.generation}`; }
+    /** @internal Use QaBrowserSession.newPage(). */
+    constructor(client, targetId, sessionId, onClosed) {
+        this.client = client;
+        this.targetId = targetId;
+        this.sessionId = sessionId;
+        this.onClosed = onClosed;
+        this.keyboard = new QaKeyboard((method, params) => this.send(method, params));
+        this.unsubs.push(this.on('Runtime.executionContextCreated', ({ context }) => { this.contexts.set(context.id, context); this.chooseContext(); }), this.on('Runtime.executionContextDestroyed', ({ executionContextId }) => {
+            this.contexts.delete(executionContextId);
+            if (executionContextId === this.contextId) {
+                this.invalidateHandles();
+                this.chooseContext();
+            }
+        }), this.on('Runtime.executionContextsCleared', () => { this.contexts.clear(); this.contextId = undefined; this.invalidateHandles(); }), this.on('Page.frameNavigated', ({ frame }) => {
+            if (frame.parentId)
+                this.frameParents.set(frame.id, frame.parentId);
+            else {
+                this.frameId = frame.id;
+                this.frameParents.clear();
+                this.invalidateHandles();
+                this.chooseContext();
+            }
+            // Chrome can abandon old-document favicon/fetch requests without a terminal event.
+            // New document requests have already started by frameNavigated; preserve that loader.
+            for (const [id, request] of this.requests) {
+                if ((!frame.parentId || request.frameId === frame.id) && request.loaderId !== frame.loaderId)
+                    this.requests.delete(id);
+            }
+        }), this.on('Page.frameAttached', ({ frameId, parentFrameId }) => this.frameParents.set(frameId, parentFrameId)), this.on('Page.frameDetached', ({ frameId, reason }) => {
+            if (reason === 'swap')
+                return;
+            const removed = new Set([frameId]);
+            for (const id of removed)
+                for (const [child, parent] of this.frameParents)
+                    if (parent === id)
+                        removed.add(child);
+            for (const id of removed)
+                this.frameParents.delete(id);
+            for (const [id, request] of this.requests)
+                if (request.frameId && removed.has(request.frameId))
+                    this.requests.delete(id);
+        }), this.on('Network.requestWillBeSent', ({ requestId, frameId, loaderId }) => { this.requests.set(requestId, { frameId, loaderId }); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFinished', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFailed', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), client.on('Disconnected', ({ error }) => this.markClosed(error)), client.on('Target.detachedFromTarget', ({ sessionId }) => { if (sessionId === this.sessionId)
+            this.markClosed(); }), this.on('Inspector.detached', () => this.markClosed()));
+    }
+    chooseContext() {
+        this.contextId = [...this.contexts.values()].reverse().find((context) => context.auxData?.isDefault && context.auxData.frameId === this.frameId)?.id;
+    }
+    /** Subscribe to this page's raw CDP events; returned function unsubscribes. */
+    on(method, listener) {
+        if (this.closed)
+            throw this.closed;
+        const off = this.client.on(method, listener, this.sessionId);
+        const unsubscribe = () => { off(); this.subscriptions.delete(unsubscribe); };
+        this.subscriptions.add(unsubscribe);
+        return unsubscribe;
+    }
+    /** @internal */
+    async initialize() {
+        await this.send('Page.enable');
+        const { frameTree } = await this.send('Page.getFrameTree');
+        this.frameId = frameTree.frame.id;
+        this.chooseContext();
+        await this.send('Runtime.enable');
+        await this.send('Network.enable');
+        await this.send('Page.setLifecycleEventsEnabled', { enabled: true });
+    }
+    /** @internal */
+    send(method, params = {}, timeout) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        return this.client.send(method, params, this.sessionId, timeout);
+    }
+    invalidateHandles() {
+        const objectGroup = this.objectGroup;
+        this.generation++;
+        for (const handle of this.handles)
+            handle.invalidate();
+        this.handles.clear();
+        // Navigation destroys the context; explicitly release any surviving remote references.
+        if (!this.closed)
+            void this.send('Runtime.releaseObjectGroup', { objectGroup }).catch(() => { });
+    }
+    /** @internal */
+    markClosed(error = new Error('Page closed')) {
+        if (this.closed)
+            return;
+        this.closed = error;
+        this.invalidateHandles();
+        this.client.rejectSession(this.sessionId, error);
+        for (const unsubscribe of this.unsubs.splice(0))
+            unsubscribe();
+        for (const unsubscribe of this.subscriptions)
+            unsubscribe();
+        for (const listener of this.closedListeners)
+            listener(error);
+        this.closedListeners.clear();
+        this.onClosed();
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        if (this.closed)
+            return Promise.resolve();
+        this.closing = (async () => {
+            try {
+                await this.client.send('Target.closeTarget', { targetId: this.targetId });
+            }
+            finally {
+                this.markClosed();
+            }
+        })();
+        return this.closing;
+    }
+    bounded(label, timeout, work) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        validateTimeout(timeout);
+        const deadline = Date.now() + timeout;
+        let stopped = false;
+        return new Promise((resolve, reject) => {
+            const finish = (error, value) => {
+                if (stopped)
+                    return;
+                stopped = true;
+                clearTimeout(timer);
+                this.closedListeners.delete(onClose);
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const onClose = (error) => finish(error);
+            this.closedListeners.add(onClose);
+            const timer = setTimeout(() => finish(new TimeoutError(`${label} timed out after ${timeout}ms`)), timeout);
+            work(() => Math.max(1, deadline - Date.now()), () => stopped).then((value) => finish(undefined, value), (error) => finish(error));
+        });
+    }
+    async mainContext(timeout = this.client.timeout) {
+        return this.bounded('Main execution context', timeout, async (_remaining, stopped) => {
+            while (this.contextId === undefined) {
+                if (stopped())
+                    throw new Error('Context wait cancelled');
+                await sleep(10);
+            }
+            return this.contextId;
+        });
+    }
+    async navigate(method, params, options) {
+        if (this.navigating)
+            throw new Error('Navigation already in progress');
+        const waitUntil = options.waitUntil ?? 'load';
+        if (!['load', 'domcontentloaded', 'networkidle0'].includes(waitUntil))
+            throw new Error(`Unsupported waitUntil: ${waitUntil}`);
+        const timeout = validateTimeout(options.timeout ?? this.client.timeout);
+        this.navigating = true;
+        const events = [];
+        let sameDocument = false;
+        let loaderId;
+        const off = this.on('Page.lifecycleEvent', (event) => events.push(event));
+        const offSame = this.on('Page.navigatedWithinDocument', ({ frameId }) => { if (frameId === this.frameId)
+            sameDocument = true; });
+        try {
+            await this.bounded(`Navigation (${waitUntil})`, timeout, async (remaining, stopped) => {
+                const response = await this.send(method, params, remaining());
+                if (response.errorText)
+                    throw new Error(`Navigation failed: ${response.errorText}`);
+                loaderId = response.loaderId;
+                if (method === 'Page.navigate' && !loaderId)
+                    sameDocument = true;
+                let idleSince;
+                while (!stopped()) {
+                    const name = waitUntil === 'domcontentloaded' ? 'DOMContentLoaded' : 'load';
+                    // Reload's loader is learned from init, never a previous document's load event.
+                    if (!loaderId && !sameDocument)
+                        loaderId = events.find((event) => event.frameId === this.frameId && event.name === 'init')?.loaderId;
+                    const ready = sameDocument || events.some((event) => event.frameId === this.frameId && event.loaderId === loaderId && event.name === name);
+                    if (ready && waitUntil !== 'networkidle0')
+                        return;
+                    const committed = sameDocument || !!loaderId;
+                    if (waitUntil === 'networkidle0' && committed && !this.requests.size) {
+                        idleSince = Math.max(idleSince ?? Date.now(), this.lastNetworkActivity);
+                        if (Date.now() - idleSince >= 500)
+                            return;
+                    }
+                    else
+                        idleSince = undefined;
+                    await sleep(Math.min(20, remaining()));
+                }
+            });
+        }
+        finally {
+            off();
+            offSame();
+            this.navigating = false;
+        }
+    }
+    goto(url, options = {}) { return this.navigate('Page.navigate', { url }, options); }
+    reload(options = {}) { return this.navigate('Page.reload', {}, options); }
+    async setViewport(options) {
+        await this.send('Emulation.setDeviceMetricsOverride', { ...options, deviceScaleFactor: options.deviceScaleFactor ?? 1, mobile: options.mobile ?? false });
+    }
+    async evaluateOnNewDocument(fn, ...args) {
+        const source = typeof fn === 'string' ? fn : `(${functionSource(fn)})(...${JSON.stringify(args)})`;
+        await this.send('Page.addScriptToEvaluateOnNewDocument', { source });
+    }
+    async run(fn, args, returnByValue, timeout = this.client.timeout) {
+        const deadline = Date.now() + timeout;
+        const contextId = await this.mainContext(timeout);
+        timeout = Math.max(1, deadline - Date.now());
+        const common = { returnByValue, awaitPromise: true, objectGroup: this.objectGroup, timeout };
+        const result = typeof fn === 'string'
+            ? await this.send('Runtime.evaluate', { expression: fn, contextId, ...common }, timeout)
+            : await this.send('Runtime.callFunctionOn', { functionDeclaration: functionSource(fn), executionContextId: contextId, arguments: args.map(argument), ...common }, timeout);
+        resultValue(result);
+        return result;
+    }
+    async evaluate(fn, ...args) {
+        return resultValue(await this.run(fn, args, true));
+    }
+    /** @internal */
+    async callElement(handle, fn, args) {
+        handle.assertUsable(this);
+        const result = await this.send('Runtime.callFunctionOn', {
+            objectId: handle.objectId, functionDeclaration: `function(...args) { return (${functionSource(fn)})(this, ...args); }`,
+            arguments: args.map(argument), returnByValue: true, awaitPromise: true,
+        });
+        return resultValue(result);
+    }
+    handle(objectId) {
+        const handle = new QaElement(this, objectId, () => this.handles.delete(handle));
+        this.handles.add(handle);
+        return handle;
+    }
+    async $(selector) {
+        return this.lookup(selector);
+    }
+    async lookup(selector, timeout = this.client.timeout) {
+        const generation = this.generation;
+        const { result } = await this.run((selector) => document.querySelector(selector), [selector], false, timeout);
+        if (generation !== this.generation)
+            throw new Error('Element lookup interrupted by navigation');
+        return result.objectId ? this.handle(result.objectId) : null;
+    }
+    async $$(selector) {
+        const generation = this.generation;
+        const { result } = await this.run((selector) => Array.from(document.querySelectorAll(selector)), [selector], false);
+        if (!result.objectId)
+            return [];
+        try {
+            const { result: properties } = await this.send('Runtime.getProperties', { objectId: result.objectId, ownProperties: true });
+            if (generation !== this.generation)
+                throw new Error('Element lookup interrupted by navigation');
+            return properties.filter((property) => /^\d+$/.test(property.name) && property.value?.objectId).map((property) => this.handle(property.value.objectId));
+        }
+        finally {
+            await this.send('Runtime.releaseObject', { objectId: result.objectId }).catch(() => { });
+        }
+    }
+    async $eval(selector, fn, ...args) {
+        const handle = await this.requireElement(selector);
+        try {
+            return await handle.evaluate(fn, ...args);
+        }
+        finally {
+            await handle.dispose();
+        }
+    }
+    async $$eval(selector, fn, ...args) {
+        const source = `function(selector, ...args) { return (${functionSource(fn)})(Array.from(document.querySelectorAll(selector)), ...args); }`;
+        return resultValue(await this.runSourceFunction(source, [selector, ...args]));
+    }
+    async runSourceFunction(source, args, timeout = this.client.timeout) {
+        const deadline = Date.now() + timeout;
+        const executionContextId = await this.mainContext(timeout);
+        timeout = Math.max(1, deadline - Date.now());
+        const result = await this.send('Runtime.callFunctionOn', { functionDeclaration: source, executionContextId, arguments: args.map(argument), returnByValue: true, awaitPromise: true, timeout }, timeout);
+        resultValue(result);
+        return result;
+    }
+    async waitForFunction(fn, options = {}, ...args) {
+        const polling = options.polling ?? 'raf';
+        if (typeof polling === 'number' && (!(polling > 0) || !Number.isFinite(polling)))
+            throw new Error('Polling interval must be positive');
+        const source = typeof fn === 'string' ? `function() { return (${fn}); }` : functionSource(fn);
+        await this.bounded(`Predicate ${source}`, options.timeout ?? this.client.timeout, async (remaining, stopped) => {
+            while (!stopped()) {
+                try {
+                    if (resultValue(await this.runSourceFunction(source, args, remaining())))
+                        return;
+                    if (polling === 'raf') {
+                        // A browser animation frame, bounded fallback for background targets.
+                        await this.runSourceFunction('function() { return new Promise(resolve => { const timer = setTimeout(resolve, 100); requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); }); }', [], remaining());
+                    }
+                    else
+                        await sleep(Math.min(polling, remaining()));
+                }
+                catch (error) {
+                    if (error instanceof TimeoutError) {
+                        await sleep(remaining());
+                        continue;
+                    }
+                    if (!/context.*(destroyed|not found)|Cannot find context/i.test(String(error)))
+                        throw error;
+                    await sleep(Math.min(10, remaining()));
+                }
+            }
+        });
+    }
+    async waitForSelector(selector, options = {}) {
+        if (options.visible && options.hidden)
+            throw new Error('visible & hidden cannot both be true');
+        try {
+            return await this.bounded(`Selector ${selector}`, options.timeout ?? this.client.timeout, async (remaining) => {
+                await this.waitForFunction((selector, visible, hidden) => {
+                    const element = document.querySelector(selector);
+                    if (!element)
+                        return hidden;
+                    const style = getComputedStyle(element), box = element.getBoundingClientRect();
+                    const shown = style.visibility !== 'hidden' && style.visibility !== 'collapse' && box.width > 0 && box.height > 0;
+                    return hidden ? !shown : visible ? shown : true;
+                }, { timeout: remaining() }, selector, !!options.visible, !!options.hidden);
+                return options.hidden ? null : this.lookup(selector, remaining());
+            });
+        }
+        catch (error) {
+            if (error instanceof TimeoutError)
+                throw new TimeoutError(`Selector ${selector} timed out after ${options.timeout ?? this.client.timeout}ms`);
+            throw error;
+        }
+    }
+    async requireElement(selector) {
+        const handle = await this.$(selector);
+        if (!handle)
+            throw new Error(`No element matches selector: ${selector}`);
+        return handle;
+    }
+    async withElement(target, work) {
+        const handle = typeof target === 'string' ? await this.requireElement(target) : target;
+        handle.assertUsable(this);
+        try {
+            return await work(handle);
+        }
+        finally {
+            if (typeof target === 'string')
+                await handle.dispose();
+        }
+    }
+    async point(handle) {
+        await handle.evaluate((element) => { if (!element.isConnected)
+            throw new Error('Element detached'); element.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' }); });
+        const box = await handle.boundingBox();
+        if (!box || !box.width || !box.height)
+            throw new Error('Element has no clickable box');
+        return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    }
+    async click(target, options = {}) {
+        await this.withElement(target, async (handle) => {
+            const point = await this.point(handle), button = options.button ?? 'left', count = options.clickCount ?? 1;
+            await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
+            for (let clickCount = 1; clickCount <= count; clickCount++) {
+                await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button, buttons: button === 'left' ? 1 : button === 'right' ? 2 : 4, clickCount });
+                if (options.delay)
+                    await sleep(options.delay);
+                await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', ...point, button, buttons: 0, clickCount });
+            }
+        });
+    }
+    async type(selector, text, options = {}) {
+        await this.withElement(selector, (handle) => this.typeElement(handle, text, options));
+    }
+    /** @internal */
+    async typeElement(handle, text, options = {}) {
+        await handle.focus();
+        if (!options.delay) {
+            await this.send('Input.insertText', { text });
+            return;
+        }
+        for (const char of text) {
+            await this.send('Input.insertText', { text: char });
+            await sleep(options.delay);
+        }
+    }
+    async hover(target) {
+        await this.withElement(target, async (handle) => { await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...await this.point(handle) }); });
+    }
+    async focus(target) { await this.withElement(target, (handle) => handle.focus()); }
+    async select(selector, ...values) {
+        return this.$eval(selector, (element, values) => {
+            if (!(element instanceof HTMLSelectElement))
+                throw new Error('Element is not a select');
+            element.selectedIndex = -1;
+            const selected = [];
+            for (const option of Array.from(element.options)) {
+                if (!element.multiple && selected.length)
+                    break;
+                option.selected = values.includes(option.value);
+                if (option.selected)
+                    selected.push(option.value);
+            }
+            element.dispatchEvent(new Event('input', { bubbles: true }));
+            element.dispatchEvent(new Event('change', { bubbles: true }));
+            return selected;
+        }, values);
+    }
+    async screenshot(options = {}) {
+        if (options.type && options.type !== 'png' || options.fullPage || options.captureBeyondViewport)
+            throw new Error('Only viewport PNG screenshots are supported');
+        const { data } = await this.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false, fromSurface: true });
+        const buffer = Buffer.from(data, 'base64');
+        if (options.path)
+            await writeFile(options.path, buffer);
+        return buffer;
+    }
+}
+/** Remote DOM reference; dispose explicitly or let navigation release its object group. */
+export class QaElement {
+    page;
+    objectId;
+    onDisposed;
+    disposed = false;
+    /** @internal */
+    constructor(page, objectId, onDisposed) {
+        this.page = page;
+        this.objectId = objectId;
+        this.onDisposed = onDisposed;
+    }
+    /** @internal */
+    assertUsable(page) {
+        if (this.disposed)
+            throw new Error('Element handle disposed or released by navigation');
+        if (page !== this.page)
+            throw new Error('Element belongs to another page');
+    }
+    /** @internal */
+    invalidate() { this.disposed = true; this.onDisposed(); }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.invalidate();
+        await this.page.send('Runtime.releaseObject', { objectId: this.objectId });
+    }
+    evaluate(fn, ...args) {
+        return this.page.callElement(this, fn, args);
+    }
+    click(options = {}) { return this.page.click(this, options); }
+    type(text, options = {}) { return this.page.typeElement(this, text, options); }
+    hover() { return this.page.hover(this); }
+    async focus() { await this.evaluate((element) => element.focus()); }
+    boundingBox() {
+        return this.evaluate((element) => {
+            if (!element.isConnected || !element.getClientRects().length || getComputedStyle(element).visibility === 'hidden')
+                return null;
+            const { x, y, width, height } = element.getBoundingClientRect();
+            return { x, y, width, height };
+        });
+    }
+}

package/dist/storage.d.ts

@@ -10,6 +10,8 @@ export interface RunMarker {
     ownerPid: number;
     leaseUntil: number;
     completedAt?: number;
+    /** Owned internal-temp companion; validated against its binding before cleanup. */
+    appRoot?: string;
 }
 export interface ManagedRun {
     root: string;
@@ -48,3 +50,7 @@ export declare function createManagedRun(options: {
 }): ManagedRun;
 export declare function finishManagedRun(run: ManagedRun | string): RunMarker | undefined;
 export declare function pruneManagedRuns(managedRoot: string, app: string, policy?: RetentionPolicy): RetentionReport;
+/** Short internal paths keep launchd files accessible & service sockets within sockaddr_un. */
+export declare function appTempDir(): string;
+export declare function createManagedAppRoot(run: ManagedRun): string;
+export declare function removeManagedAppRoot(root: string, marker: RunMarker): void;

package/dist/storage.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 export const RUN_MARKER = '.rightkit-run.json';
 export const DEFAULT_RETENTION_BYTES = 20_000_000_000;
@@ -10,9 +11,12 @@ export function resolveManagedRoot(explicit) {
         return path.resolve(explicit);
     if (process.env.RIGHTKIT_MANAGED_ROOT?.trim())
         return path.resolve(process.env.RIGHTKIT_MANAGED_ROOT);
-    if (process.platform === 'win32')
-        return path.resolve('D:\\.rightkit-managed');
-    return '/Volumes/D/.rightkit-managed';
+    const [workstation, volume] = process.platform === 'win32' ? ['D:\\.rightkit-managed', 'D:\\'] : ['/Volumes/D/.rightkit-managed', '/Volumes/D'];
+    if (fs.existsSync(volume))
+        return path.resolve(workstation);
+    // Hosted CI and other machines: runner temp, then the system temp dir.
+    const runnerTemp = process.env.RUNNER_TEMP?.trim();
+    return path.join(runnerTemp && fs.existsSync(runnerTemp) ? runnerTemp : os.tmpdir(), 'rightkit-managed');
 }
 export function safeKey(value, name) {
     const v = String(value ?? '').trim();
@@ -69,6 +73,14 @@ export function finishManagedRun(run) {
     const marker = readMarker(markerPath);
     if (!marker)
         return undefined;
+    const home = ownedAppRoot(root, marker);
+    if (home) {
+        copyAppTree(path.join(home, 'evidence'), path.join(root, 'evidence', 'app'));
+        copyAppTree(path.join(home, 'captures'), path.join(root, 'captures'));
+        for (const name of fs.readdirSync(home))
+            if (name.endsWith('.log'))
+                copyAppTree(path.join(home, name), path.join(root, 'evidence', name));
+    }
     const finished = { ...marker, ownerPid: 0, leaseUntil: 0, completedAt: Date.now() };
     writeMarker(root, finished);
     return finished;
@@ -149,6 +161,7 @@ function pruneUnlocked(appRoot, app, policy, report) {
         if (!safeDirectory(item.root))
             continue;
         try {
+            removeManagedAppRoot(item.root, item.marker);
             fs.rmSync(item.root, { recursive: true, force: false });
             report.removed.push(item.root);
             removed.add(item.marker.runId);
@@ -226,6 +239,8 @@ function readMarker(file) {
             return undefined;
         if (x.completedAt !== undefined && (typeof x.completedAt !== 'number' || !Number.isFinite(x.completedAt) || x.completedAt < 0))
             return undefined;
+        if (x.appRoot !== undefined && typeof x.appRoot !== 'string')
+            return undefined;
         return x;
     }
     catch {
@@ -313,3 +328,53 @@ function describeError(error) {
 }
 function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
 function cryptoRandomId() { return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`; }
+/** Short internal paths keep launchd files accessible & service sockets within sockaddr_un. */
+export function appTempDir() {
+    return process.platform === 'darwin' ? '/private/tmp' : fs.realpathSync(os.tmpdir());
+}
+export function createManagedAppRoot(run) {
+    const parent = path.join(appTempDir(), 'rightkit-qa');
+    ensureSafeDirectory(parent);
+    const home = fs.mkdtempSync(path.join(parent, `${run.app.slice(0, 16)}-`));
+    fs.writeFileSync(path.join(home, '.rightkit-app.json'), JSON.stringify({ runRoot: fs.realpathSync(run.root), app: run.app, runId: run.runId }), { flag: 'wx' });
+    run.marker.appRoot = home;
+    writeMarker(run.root, run.marker);
+    return home;
+}
+function ownedAppRoot(root, marker) {
+    const home = marker.appRoot;
+    if (!home || !fs.existsSync(home))
+        return undefined;
+    const parent = path.dirname(home);
+    const temp = path.dirname(parent);
+    const allowedTemp = temp === appTempDir() || process.platform === 'darwin' && (temp === '/private/tmp' || isInside('/private/var/folders', temp) && path.basename(temp) === 'T');
+    if (path.basename(parent) !== 'rightkit-qa' || !allowedTemp || fs.realpathSync(home) !== home || !safeDirectory(home))
+        throw new Error('invalid QA app temp root');
+    const binding = JSON.parse(fs.readFileSync(path.join(home, '.rightkit-app.json'), 'utf8'));
+    if (binding.runRoot !== fs.realpathSync(root) || binding.app !== marker.app || binding.runId !== marker.runId)
+        throw new Error('QA app temp ownership mismatch');
+    return home;
+}
+export function removeManagedAppRoot(root, marker) {
+    const home = ownedAppRoot(root, marker);
+    if (home)
+        fs.rmSync(home, { recursive: true, force: false });
+}
+function copyAppTree(source, target) {
+    const meta = fs.lstatSync(source);
+    if (meta.isSymbolicLink())
+        throw new Error('symlink in QA app evidence');
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+        throw new Error('symlink in managed QA evidence');
+    if (meta.isDirectory()) {
+        ensureSafeDirectory(target);
+        for (const name of fs.readdirSync(source))
+            copyAppTree(path.join(source, name), path.join(target, name));
+    }
+    else if (meta.isFile()) {
+        ensureSafeDirectory(path.dirname(target));
+        fs.copyFileSync(source, target);
+    }
+    else
+        throw new Error('unsupported QA app evidence file');
+}

package/dist/workspace.d.ts

@@ -4,6 +4,8 @@ export interface QaWorkspace {
     appKey: string;
     managedRoot: string;
     root: string;
+    /** Owned app home on internal system temp storage. */
+    home: string;
     /** Isolated user-data directory; pass to the app so it takes its own lock. */
     dataDir: string;
     /** Somewhere for screenshots, logs, and other recorded evidence. */

package/dist/workspace.js

@@ -17,35 +17,49 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createManagedRun, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
+import { createManagedRun, createManagedAppRoot, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
     const managed = createManagedRun({ managedRoot: options.root ? requireText(options.root, 'root') : resolveManagedRoot(), app: appKey, runId: options.runId ?? crypto.randomUUID(), leaseMs: options.leaseMs, retention: options.retention });
     const runId = managed.runId;
     const root = managed.root;
-    const dataDir = path.join(root, 'data');
+    const home = createManagedAppRoot(managed);
+    const dataDir = path.join(home, 'data');
     const evidenceDir = path.join(root, 'evidence');
     const captureDir = path.join(root, 'captures');
-    const tmpDir = path.join(root, 'tmp');
+    const tmpDir = path.join(home, 'tmp');
+    const cacheDir = path.join(home, 'cache');
+    const appEvidenceDir = path.join(home, 'evidence');
+    const appCaptureDir = path.join(home, 'captures');
+    fs.mkdirSync(appEvidenceDir, { recursive: true });
+    fs.mkdirSync(appCaptureDir, { recursive: true });
     fs.mkdirSync(dataDir, { recursive: true });
     fs.mkdirSync(evidenceDir, { recursive: true });
     fs.mkdirSync(captureDir, { recursive: true });
     fs.mkdirSync(tmpDir, { recursive: true });
+    fs.mkdirSync(cacheDir, { recursive: true });
     return {
         runId,
         appKey,
         managedRoot: path.resolve(options.root ? requireText(options.root, 'root') : resolveManagedRoot()),
         root,
+        home,
         dataDir,
         evidenceDir,
         captureDir,
         env: {
             RIGHTKIT_QA_NATIVE: '1',
             RIGHTKIT_QA_RUN_ID: runId,
-            RIGHTKIT_RUN_ROOT: root,
+            RIGHTKIT_RUN_ROOT: home,
+            RIGHTKIT_SUITE_ROOT: path.join(home, 'suite'),
+            HOME: home,
+            USERPROFILE: home,
+            APPDATA: dataDir,
+            LOCALAPPDATA: dataDir,
+            XDG_CACHE_HOME: cacheDir,
             RIGHTKIT_QA_DATA_DIR: dataDir,
-            RIGHTKIT_QA_EVIDENCE_DIR: evidenceDir,
-            RIGHTKIT_QA_CAPTURE_DIR: captureDir,
+            RIGHTKIT_QA_EVIDENCE_DIR: appEvidenceDir,
+            RIGHTKIT_QA_CAPTURE_DIR: appCaptureDir,
             TMPDIR: tmpDir,
             TMP: tmpDir,
             TEMP: tmpDir,
@@ -68,13 +82,19 @@ export function disposeQaWorkspace(workspace, options = {}) {
     const attempts = Math.max(1, options.attempts ?? 5);
     const retryDelayMs = options.retryDelayMs ?? 200;
     const sleep = options.sleep ?? sleepSync;
-    const targets = options.keepEvidence ? [workspace.dataDir] : [workspace.root];
+    const targets = options.keepEvidence ? [workspace.home] : [workspace.home, workspace.root];
     const report = { removed: [], retained: [] };
-    finishManagedRun(workspace.root);
+    try {
+        finishManagedRun(workspace.root);
+    }
+    catch (error) {
+        report.retained.push({ path: workspace.root, reason: describeError(error) });
+        return report;
+    }
     for (const target of targets) {
-        // Only ever remove inside the workspace root we created.
+        // Only remove the managed run or its registered temp companion.
         const resolved = path.resolve(target);
-        if (resolved !== path.resolve(workspace.root) && !isInside(workspace.root, resolved)) {
+        if (resolved !== path.resolve(workspace.root) && resolved !== path.resolve(workspace.home)) {
             report.retained.push({ path: resolved, reason: 'outside the QA workspace root' });
             continue;
         }
@@ -97,8 +117,14 @@ export function disposeQaWorkspace(workspace, options = {}) {
         }
         if (lastError === undefined && !fs.existsSync(resolved))
             report.removed.push(resolved);
-        else
+        else {
             report.retained.push({ path: resolved, reason: describeError(lastError) });
+            if (resolved === path.resolve(workspace.home)) {
+                if (!options.keepEvidence)
+                    report.retained.push({ path: workspace.root, reason: 'app temp cleanup pending' });
+                break;
+            }
+        }
     }
     return report;
 }
@@ -130,10 +156,6 @@ export function pruneAbandonedWorkspaces(root, { olderThanMs, now = Date.now(),
     }
     return report;
 }
-function isInside(root, candidate) {
-    const relative = path.relative(path.resolve(root), path.resolve(candidate));
-    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
-}
 function describeError(error) {
     if (error === undefined)
         return 'still present after removal reported success';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",