@rightkit/qa 0.3.0 → 0.3.2

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.

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/storage.d.ts

@@ -0,0 +1,56 @@
+export declare const RUN_MARKER = ".rightkit-run.json";
+export declare const DEFAULT_RETENTION_BYTES = 20000000000;
+export declare const DEFAULT_YOUNG_MS: number;
+export declare const DEFAULT_KEEP_COUNT = 5;
+export interface RunMarker {
+    schemaVersion: 1;
+    app: string;
+    runId: string;
+    createdAt: number;
+    ownerPid: number;
+    leaseUntil: number;
+    completedAt?: number;
+    /** Owned internal-temp companion; validated against its binding before cleanup. */
+    appRoot?: string;
+}
+export interface ManagedRun {
+    root: string;
+    app: string;
+    runId: string;
+    marker: RunMarker;
+}
+export interface RetentionPolicy {
+    maxBytes?: number;
+    keepCount?: number;
+    youngMs?: number;
+    now?: number;
+    keepRunIds?: string[];
+}
+export interface RetentionReport {
+    removed: string[];
+    retained: Array<{
+        path: string;
+        reason: string;
+    }>;
+    totalBytes: number;
+    capBytes: number;
+    overCapBytes: number;
+    blockedBytes: number;
+    unknownBytes: number;
+}
+export declare function resolveManagedRoot(explicit?: string): string;
+export declare function safeKey(value: string, name: string): string;
+export declare function runRoot(managedRoot: string, app: string, runId: string): string;
+export declare function createManagedRun(options: {
+    managedRoot?: string;
+    app: string;
+    runId?: string;
+    leaseMs?: number;
+    retention?: RetentionPolicy;
+}): 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

@@ -0,0 +1,380 @@
+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;
+export const DEFAULT_YOUNG_MS = 24 * 60 * 60_000;
+export const DEFAULT_KEEP_COUNT = 5;
+const LOCK_WAIT_MS = 5_000;
+export function resolveManagedRoot(explicit) {
+    if (explicit?.trim())
+        return path.resolve(explicit);
+    if (process.env.RIGHTKIT_MANAGED_ROOT?.trim())
+        return path.resolve(process.env.RIGHTKIT_MANAGED_ROOT);
+    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();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(v))
+        throw new Error(`unsafe QA ${name}: ${value}`);
+    return v;
+}
+export function runRoot(managedRoot, app, runId) {
+    const root = path.resolve(managedRoot);
+    const appKey = safeKey(app, 'app');
+    const id = safeKey(runId, 'run id');
+    const result = path.join(root, 'runs', appKey, id);
+    if (!isInside(path.join(root, 'runs', appKey), result))
+        throw new Error('QA run path escapes managed root');
+    return result;
+}
+export function createManagedRun(options) {
+    const managedRoot = resolveManagedRoot(options.managedRoot);
+    const app = safeKey(options.app, 'app');
+    const runId = safeKey(options.runId ?? cryptoRandomId(), 'run id');
+    const appRoot = path.join(managedRoot, 'runs', app);
+    withRetentionLock(appRoot, () => {
+        ensureSafeDirectory(managedRoot);
+        ensureSafeDirectory(path.join(managedRoot, 'runs'));
+        ensureSafeDirectory(appRoot);
+        const retention = { now: Date.now(), ...(options.retention ?? {}) };
+        const report = { removed: [], retained: [], totalBytes: 0, capBytes: DEFAULT_RETENTION_BYTES, overCapBytes: 0, blockedBytes: 0, unknownBytes: 0 };
+        pruneUnlocked(appRoot, app, retention, report);
+        if (report.overCapBytes > 0)
+            throw new Error(`QA retention cap is blocked by ${report.overCapBytes} bytes of protected or unknown data`);
+        const root = runRoot(managedRoot, app, runId);
+        if (fs.existsSync(root))
+            throw new Error(`QA run already exists: ${root}`);
+        fs.mkdirSync(root, { recursive: true });
+        const marker = {
+            schemaVersion: 1,
+            app,
+            runId,
+            createdAt: Date.now(),
+            ownerPid: process.pid,
+            leaseUntil: Date.now() + Math.max(1, options.leaseMs ?? DEFAULT_YOUNG_MS),
+        };
+        writeMarker(root, marker);
+    });
+    const root = runRoot(managedRoot, app, runId);
+    const marker = readMarker(path.join(root, RUN_MARKER));
+    if (!marker)
+        throw new Error(`QA run marker was not created: ${root}`);
+    return { root, app, runId, marker };
+}
+export function finishManagedRun(run) {
+    const root = typeof run === 'string' ? run : run.root;
+    const markerPath = path.join(path.resolve(root), RUN_MARKER);
+    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;
+}
+export function pruneManagedRuns(managedRoot, app, policy = {}) {
+    const root = resolveManagedRoot(managedRoot);
+    const appKey = safeKey(app, 'app');
+    const appRoot = path.join(root, 'runs', appKey);
+    const cap = Number.isFinite(policy.maxBytes) && policy.maxBytes >= 0 ? policy.maxBytes : DEFAULT_RETENTION_BYTES;
+    const report = { removed: [], retained: [], totalBytes: 0, capBytes: cap, overCapBytes: 0, blockedBytes: 0, unknownBytes: 0 };
+    if (!safeDirectory(appRoot))
+        return report;
+    return withRetentionLock(appRoot, () => pruneUnlocked(appRoot, appKey, policy, report));
+}
+function pruneUnlocked(appRoot, app, policy, report) {
+    const now = policy.now ?? Date.now();
+    const cap = Number.isFinite(policy.maxBytes) && policy.maxBytes >= 0 ? policy.maxBytes : DEFAULT_RETENTION_BYTES;
+    report.capBytes = cap;
+    const keepCount = Math.max(0, Math.floor(policy.keepCount ?? DEFAULT_KEEP_COUNT));
+    const youngMs = Math.max(0, policy.youngMs ?? DEFAULT_YOUNG_MS);
+    const candidates = [];
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(appRoot, { withFileTypes: true });
+    }
+    catch {
+        return report;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (entry.isSymbolicLink()) {
+            report.retained.push({ path: path.join(appRoot, entry.name), reason: 'symlink skipped' });
+            continue;
+        }
+        if (!entry.isDirectory())
+            continue;
+        const runPath = path.join(appRoot, entry.name);
+        if (!isInside(appRoot, runPath))
+            continue;
+        const marker = readMarker(path.join(runPath, RUN_MARKER));
+        if (!marker || marker.app !== app || marker.runId !== entry.name) {
+            const bytes = directoryBytes(runPath);
+            if (bytes !== undefined)
+                report.unknownBytes += bytes;
+            report.retained.push({ path: runPath, reason: 'unknown or malformed run metadata' });
+            continue;
+        }
+        const bytes = directoryBytes(runPath);
+        if (bytes === undefined) {
+            report.retained.push({ path: runPath, reason: 'symlink or unreadable content skipped' });
+            continue;
+        }
+        const active = marker.ownerPid > 0 && isProcessLive(marker.ownerPid) || marker.leaseUntil > now;
+        total += bytes;
+        candidates.push({ root: runPath, marker, bytes, active });
+    }
+    candidates.sort((a, b) => b.marker.createdAt - a.marker.createdAt || a.marker.runId.localeCompare(b.marker.runId));
+    const countProtected = new Set(candidates.slice(0, keepCount).map((x) => x.marker.runId));
+    const protectedIds = new Set();
+    const callerProtected = new Set(policy.keepRunIds ?? []);
+    for (const item of candidates) {
+        if (now - item.marker.createdAt < youngMs)
+            protectedIds.add(item.marker.runId);
+        if (item.active)
+            protectedIds.add(item.marker.runId);
+        if (callerProtected.has(item.marker.runId))
+            protectedIds.add(item.marker.runId);
+    }
+    const old = candidates
+        .filter((x) => !protectedIds.has(x.marker.runId) && (total > cap || !countProtected.has(x.marker.runId)))
+        .sort((a, b) => a.marker.createdAt - b.marker.createdAt || a.marker.runId.localeCompare(b.marker.runId));
+    const removed = new Set();
+    for (const item of old) {
+        if (total <= cap && countProtected.has(item.marker.runId))
+            continue;
+        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);
+            total -= item.bytes;
+        }
+        catch (error) {
+            report.retained.push({ path: item.root, reason: describeError(error) });
+        }
+    }
+    for (const item of candidates) {
+        if (!removed.has(item.marker.runId) && (protectedIds.has(item.marker.runId) || (total <= cap && countProtected.has(item.marker.runId))))
+            report.retained.push({ path: item.root, reason: callerProtected.has(item.marker.runId) ? 'caller protected run' : item.active ? 'active run; may belong to a live run' : (now - item.marker.createdAt < youngMs ? 'younger than retention window' : 'newest protected run') });
+    }
+    report.blockedBytes = candidates.filter((item) => !removed.has(item.marker.runId) && (protectedIds.has(item.marker.runId) || (total <= cap && countProtected.has(item.marker.runId)))).reduce((sum, item) => sum + item.bytes, 0);
+    report.totalBytes = total + report.unknownBytes;
+    report.overCapBytes = Math.max(0, report.totalBytes - report.capBytes);
+    return report;
+}
+function withRetentionLock(appRoot, body) {
+    ensureSafeDirectory(path.dirname(appRoot));
+    ensureSafeDirectory(appRoot);
+    const lock = path.join(appRoot, '.retention-lock');
+    const owner = path.join(lock, 'owner.json');
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    while (true) {
+        try {
+            fs.mkdirSync(lock);
+            fs.writeFileSync(owner, JSON.stringify({ pid: process.pid, createdAt: Date.now() }), 'utf8');
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let pid;
+            try {
+                pid = JSON.parse(fs.readFileSync(owner, 'utf8')).pid;
+            }
+            catch { /* uncertain owner: wait */ }
+            if (typeof pid === 'number' && pid > 0 && !isProcessLive(pid)) {
+                try {
+                    fs.rmSync(lock, { recursive: true, force: true });
+                }
+                catch { /* retry */ }
+            }
+            else if (Date.now() >= deadline) {
+                throw new Error(`QA retention lock is held: ${lock}`);
+            }
+            if (Date.now() < deadline)
+                sleepSync(20);
+        }
+    }
+    try {
+        return body();
+    }
+    finally {
+        try {
+            fs.rmSync(lock, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+function writeMarker(root, marker) {
+    const target = path.join(root, RUN_MARKER);
+    const temp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(marker)}\n`, { encoding: 'utf8', flag: 'wx' });
+    fs.renameSync(temp, target);
+}
+function readMarker(file) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const x = raw;
+        if (x.schemaVersion !== 1 || typeof x.app !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(x.app) || typeof x.runId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(x.runId) || typeof x.createdAt !== 'number' || !Number.isFinite(x.createdAt) || x.createdAt <= 0 || typeof x.ownerPid !== 'number' || !Number.isInteger(x.ownerPid) || x.ownerPid < 0 || typeof x.leaseUntil !== 'number' || !Number.isFinite(x.leaseUntil) || x.leaseUntil < 0)
+            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 {
+        return undefined;
+    }
+}
+function directoryBytes(root) {
+    let total = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            const p = path.join(dir, entry.name);
+            if (entry.isSymbolicLink())
+                return false;
+            if (entry.isDirectory()) {
+                if (!walk(p))
+                    return false;
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += fs.statSync(p).size;
+                }
+                catch {
+                    return false;
+                }
+            }
+            else
+                return false;
+        }
+        return true;
+    };
+    return walk(root) ? total : undefined;
+}
+function safeDirectory(dir) {
+    try {
+        return fs.lstatSync(dir).isDirectory() && !fs.lstatSync(dir).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function ensureSafeDirectory(dir) {
+    const absolute = path.resolve(dir);
+    const parts = absolute.split(path.sep);
+    let current = parts[0] || path.sep;
+    for (const part of parts.slice(1)) {
+        if (!part)
+            continue;
+        current = path.join(current, part);
+        try {
+            if (fs.lstatSync(current).isSymbolicLink())
+                throw new Error(`refusing symlink in managed path: ${current}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    fs.mkdirSync(absolute, { recursive: true });
+}
+function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+function isProcessLive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function describeError(error) {
+    const x = error;
+    return x?.code ? `${x.code}: ${x.message}` : String(error?.message ?? 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

@@ -1,12 +1,20 @@
+import { type ManagedRun } from './storage.js';
 export interface QaWorkspace {
     runId: string;
+    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. */
     evidenceDir: string;
+    /** Managed capture output directory. */
+    captureDir: string;
     /** Environment overrides that point the app at this workspace. */
     env: Record<string, string>;
+    marker: ManagedRun['marker'];
 }
 export interface DisposeReport {
     removed: string[];
@@ -16,9 +24,12 @@ export interface DisposeReport {
     }>;
 }
 export interface CreateQaWorkspaceOptions {
-    root: string;
+    /** Managed root override; tests may provide a temporary directory. */
+    root?: string;
     runId?: string;
     appKey: string;
+    leaseMs?: number;
+    retention?: import('./storage.js').RetentionPolicy;
 }
 export declare function createQaWorkspace(options: CreateQaWorkspaceOptions): QaWorkspace;
 export interface DisposeOptions {

package/dist/workspace.js

@@ -17,26 +17,52 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createManagedRun, createManagedAppRoot, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
-    const runId = options.runId ?? crypto.randomUUID();
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
-        throw new Error(`unsafe QA run id: ${runId}`);
-    const root = path.resolve(requireText(options.root, 'root'), 'runs', runId);
-    const dataDir = path.join(root, 'data');
+    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 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(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: 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_EVIDENCE_DIR: appEvidenceDir,
+            RIGHTKIT_QA_CAPTURE_DIR: appCaptureDir,
+            TMPDIR: tmpDir,
+            TMP: tmpDir,
+            TEMP: tmpDir,
             // Tauri/webview honour these for profile isolation; setting all three keeps
             // the run off the user's real profile regardless of which the app reads.
             XDG_DATA_HOME: dataDir,
@@ -44,6 +70,7 @@ export function createQaWorkspace(options) {
             WEBVIEW2_USER_DATA_FOLDER: path.join(dataDir, 'webview2'),
             [`${appKey.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_DATA_DIR`]: dataDir,
         },
+        marker: managed.marker,
     };
 }
 /**
@@ -55,12 +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: [] };
+    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;
         }
@@ -83,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;
 }
@@ -93,47 +133,29 @@ export function disposeQaWorkspace(workspace, options = {}) {
  * workspace's own `runs` directory and to entries older than `olderThanMs`, so a
  * concurrent run is never removed out from under itself.
  */
-export function pruneAbandonedWorkspaces(root, { olderThanMs = 6 * 60 * 60_000, now = Date.now(), keep = [] } = {}) {
-    const runsRoot = path.resolve(root, 'runs');
+export function pruneAbandonedWorkspaces(root, { olderThanMs, now = Date.now(), keep = [] } = {}) {
+    const managedRoot = path.resolve(root);
     const report = { removed: [], retained: [] };
-    let entries;
+    const runsRoot = path.join(managedRoot, 'runs');
+    let apps;
     try {
-        entries = fs.readdirSync(runsRoot, { withFileTypes: true });
+        apps = fs.readdirSync(runsRoot, { withFileTypes: true });
     }
     catch {
         return report;
     }
-    for (const entry of entries) {
-        if (!entry.isDirectory() || entry.isSymbolicLink())
-            continue;
-        if (keep.includes(entry.name))
-            continue;
-        const target = path.join(runsRoot, entry.name);
-        let ageMs;
-        try {
-            ageMs = now - fs.statSync(target).mtimeMs;
-        }
-        catch {
-            continue;
-        }
-        if (ageMs < olderThanMs) {
-            report.retained.push({ path: target, reason: `only ${Math.round(ageMs / 1000)}s old; may belong to a live run` });
-            continue;
-        }
-        try {
-            fs.rmSync(target, { recursive: true, force: true });
-            report.removed.push(target);
-        }
-        catch (error) {
-            report.retained.push({ path: target, reason: describeError(error) });
+    for (const app of apps) {
+        if (app.isDirectory() && !app.isSymbolicLink()) {
+            const policy = olderThanMs === undefined
+                ? { now, keepRunIds: keep }
+                : { now, youngMs: olderThanMs, keepCount: 0, maxBytes: 0, keepRunIds: keep };
+            const sub = pruneManagedRuns(managedRoot, app.name, policy);
+            report.removed.push(...sub.removed);
+            report.retained.push(...sub.retained);
         }
     }
     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.0",
+  "version": "0.3.2",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@rightkit/qa-chrome": "0.1.2"
+    "@rightkit/qa-chrome": "0.1.3"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -43,6 +43,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run"
+    "test": "vitest run && node --test public-storage.test.mjs"
   }
 }