@molecule/api-ai-tools 1.17.1 → 1.17.2

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-11-06T15:20:37.703Z
+Generated: 2026-11-06T17:48:40.314Z
 -->
 
 # @molecule/api-ai-tools
@@ -466,7 +466,7 @@ interface PlaywrightFeedbackResult {
   spec: string
   revision: number
   durationMs: number
-  status: 'passed' | 'failed' | 'unavailable'
+  status: 'passed' | 'failed' | 'unavailable' | 'cancelled'
   failures: PlaywrightFeedbackFailure[]
   /** Native counts for this one diagnostic selection, never whole-suite proof. */
   nativeStats?: PlaywrightReportStats
@@ -486,6 +486,8 @@ interface PlaywrightFeedbackOptions {
     sources: string[],
     revision: number,
     emit: (result: PlaywrightFeedbackResult) => void,
+    /** Stop the owned native process group when cancelled; never wait for the tests to finish. */
+    signal: AbortSignal,
   ) => Promise<PlaywrightFeedbackResult>
   /** Only current native failures are delivered. Passing apps receive no note. */
   onFailures?: (result: PlaywrightFeedbackResult) => void
@@ -503,6 +505,8 @@ A nonblocking source-change subscription.
 interface PlaywrightFeedback {
   changed: (paths: readonly string[]) => void
   takeFailures: () => PlaywrightFeedbackResult[]
+  /** Cancel speculation before foreground work. Release after that work; nested callers are safe. */
+  pause: () => Promise<() => void>
   /** Wait only in tests or shutdown; file writes and deploys must never await this. */
   settled: () => Promise<void>
   close: () => Promise<void>
@@ -2733,6 +2737,7 @@ function runPlaywrightFeedback(
     timeoutMs?: number
     emit?: (result: PlaywrightFeedbackResult) => void
     pollMs?: number
+    signal?: AbortSignal
   },
 ): Promise<PlaywrightFeedbackResult>
 ```
@@ -6006,7 +6011,12 @@ Peer dependencies:
   to batch source reads over either backend and `runPlaywrightFeedback` to run each
   supplied spec through its native command. Its incremental reporter supplies exact
   locator failures and the failure-time page snapshot. Healthy runs emit no note;
-  no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+  no suite schedules no runner. Pass the runner's cancellation signal to
+  `runPlaywrightFeedback` in its options and call `pause()` before foreground tools,
+  then invoke its returned release function afterwards. Speculation yields to
+  independent native CLI tests/builds and uses OS idle CPU/I/O priority. Its
+  private temporary reports are not a user test result or something to poll.
+  New writes cancel stale native work. `settled()`/`close()` are for tests and shutdown,
   never a deployment barrier. Diagnoses are not whole-suite completion proof.
 - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.

package/dist/index.d.ts

@@ -17,7 +17,12 @@
  *   to batch source reads over either backend and `runPlaywrightFeedback` to run each
  *   supplied spec through its native command. Its incremental reporter supplies exact
  *   locator failures and the failure-time page snapshot. Healthy runs emit no note;
- *   no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+ *   no suite schedules no runner. Pass the runner's cancellation signal to
+ *   `runPlaywrightFeedback` in its options and call `pause()` before foreground tools,
+ *   then invoke its returned release function afterwards. Speculation yields to
+ *   independent native CLI tests/builds and uses OS idle CPU/I/O priority. Its
+ *   private temporary reports are not a user test result or something to poll.
+ *   New writes cancel stale native work. `settled()`/`close()` are for tests and shutdown,
  *   never a deployment barrier. Diagnoses are not whole-suite completion proof.
  * - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
  *   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+JG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oCAAoC,CAAA;AAClD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoKG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,0BAA0B,CAAA;AACxC,cAAc,oCAAoC,CAAA;AAClD,cAAc,gCAAgC,CAAA;AAC9C,cAAc,wBAAwB,CAAA;AACtC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -17,7 +17,12 @@
  *   to batch source reads over either backend and `runPlaywrightFeedback` to run each
  *   supplied spec through its native command. Its incremental reporter supplies exact
  *   locator failures and the failure-time page snapshot. Healthy runs emit no note;
- *   no suite schedules no runner. `settled()`/`close()` are for tests and shutdown,
+ *   no suite schedules no runner. Pass the runner's cancellation signal to
+ *   `runPlaywrightFeedback` in its options and call `pause()` before foreground tools,
+ *   then invoke its returned release function afterwards. Speculation yields to
+ *   independent native CLI tests/builds and uses OS idle CPU/I/O priority. Its
+ *   private temporary reports are not a user test result or something to poll.
+ *   New writes cancel stale native work. `settled()`/`close()` are for tests and shutdown,
  *   never a deployment barrier. Diagnoses are not whole-suite completion proof.
  * - **Opaque command plans:** prepare each logical step with `streamingBackgroundCommand`,
  *   call `createCommandPlan`, and attach it to the executed wrapper with `commandWithPlan`.

package/dist/playwright-feedback-process.d.ts

@@ -0,0 +1,14 @@
+interface FeedbackProcessOptions {
+    command: string;
+    cwd: string;
+    root: string;
+    directory: string;
+}
+/**
+ * Compose a private native supervisor without putting the test command on its argv.
+ * @param config - The known command, working directory and owned scratch directory.
+ * @returns A self-contained native Node program.
+ */
+export declare function feedbackProcessSource(config: FeedbackProcessOptions): string;
+export {};
+//# sourceMappingURL=playwright-feedback-process.d.ts.map

package/dist/playwright-feedback-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-feedback-process.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-process.ts"],"names":[],"mappings":"AASA,UAAU,sBAAsB;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB;AAkLD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CAE5E"}

package/dist/playwright-feedback-process.js

@@ -0,0 +1,189 @@
+/** Serialized into either execution backend; only standard Node/OS operations run there. */
+function feedbackProcess(loadModule, config) {
+    const fs = loadModule('node:fs');
+    const cp = loadModule('node:child_process');
+    const os = loadModule('node:os');
+    const path = loadModule('node:path');
+    const stopFile = path.join(config.directory, 'stop');
+    const yielded = path.join(config.directory, 'yielded');
+    try {
+        os.setPriority(0, 19);
+    }
+    catch (_error) {
+        /* best effort on platforms without POSIX priorities */
+    }
+    let child = undefined;
+    let done = false;
+    const owned = new Map();
+    const rememberChildren = () => {
+        if (!child?.pid || process.platform !== 'linux')
+            return;
+        const processes = new Map();
+        for (const pid of fs.readdirSync('/proc')) {
+            if (!/^\d+$/.test(pid))
+                continue;
+            try {
+                const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+                const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+                processes.set(Number(pid), { parent: Number(fields[1]), ticks: fields[19] });
+            }
+            catch (_error) {
+                /* already exited */
+            }
+        }
+        for (const [pid, entry] of processes) {
+            const seen = new Set();
+            let ancestor = pid;
+            while (ancestor > 1 && !seen.has(ancestor)) {
+                const ticks = owned.get(ancestor);
+                if (ancestor === child.pid ||
+                    (ticks !== undefined && ticks === processes.get(ancestor)?.ticks)) {
+                    owned.set(pid, entry.ticks);
+                    break;
+                }
+                seen.add(ancestor);
+                ancestor = processes.get(ancestor)?.parent ?? 0;
+            }
+        }
+    };
+    const stop = (foreground = false) => {
+        if (done)
+            return;
+        done = true;
+        if (foreground)
+            fs.writeFileSync(yielded, 'foreground');
+        rememberChildren();
+        // Chromium creates a separate process group. Remember descendants before
+        // killing the launcher and verify start ticks so a reused PID is never hit.
+        for (const [pid, ticks] of [...owned].reverse()) {
+            try {
+                const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+                if (stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] === ticks)
+                    process.kill(pid, 'SIGKILL');
+            }
+            catch (_error) {
+                /* already exited */
+            }
+        }
+        // This process created the detached group. Never signal by command/name.
+        if (child?.pid) {
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch (_error) {
+                /* already exited */
+            }
+        }
+    };
+    const ancestors = new Set();
+    let parent = process.pid;
+    while (parent > 1 && !ancestors.has(parent)) {
+        ancestors.add(parent);
+        try {
+            const stat = fs.readFileSync(`/proc/${parent}/stat`, 'utf8');
+            parent = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
+        }
+        catch (_error) {
+            break;
+        }
+    }
+    // CLI agents can launch native tests without using our backend. /proc supplies
+    // process identity and cwd, so they need no hook, lock or instruction to yield.
+    // The host adapter cancels before its own tools; this catches independent CLI work.
+    const foreground = () => {
+        if (process.platform !== 'linux')
+            return false;
+        const project = fs.statSync(config.root);
+        for (const pid of fs.readdirSync('/proc')) {
+            if (!/^\d+$/.test(pid) || ancestors.has(Number(pid)))
+                continue;
+            try {
+                const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+                const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+                if (fields[0] === 'Z' ||
+                    Number(fields[2]) === child?.pid ||
+                    owned.get(Number(pid)) === fields[19])
+                    continue;
+                const cwd = fs.readlinkSync(`/proc/${pid}/cwd`);
+                if (cwd !== config.root && !cwd.startsWith(config.root + path.sep))
+                    continue;
+                // Separate mount namespaces can both call their project /workspace.
+                const other = fs.statSync(`/proc/${pid}/root${config.root}`);
+                if (other.dev !== project.dev || other.ino !== project.ino)
+                    continue;
+                const argv = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+                const executable = path.basename(argv[0] || '');
+                // npm replaces argv with its process title before it starts the script.
+                if (/^(?:npm|npx|pnpm|yarn|bun)(?: run)? (?:test(?::[\w-]+)?|build|deploy|check|typecheck)(?: |$)/.test(executable))
+                    return true;
+                const native = argv
+                    .slice(0, 3)
+                    .some((a) => /(?:^|\/)(?:@playwright\/test|playwright(?:-core)?|hurl)(?:\/|$)/.test(a));
+                if (native || /^(?:hurl|playwright|fly|flyctl|vercel|netlify)$/.test(executable))
+                    return true;
+                if (argv.slice(1, 4).some((a) => a === 'deploy' || a === 'build'))
+                    return true;
+                if (/^(?:npm|npx|pnpm|yarn|bun|corepack)(?:\.c?js)?$/.test(executable) ||
+                    argv.some((a) => /\/(?:npm|npx)-cli\.js$/.test(a))) {
+                    if (argv.some((a) => /^(?:test(?::[\w-]+)?|e2e|build|deploy|check|typecheck)$/.test(a)))
+                        return true;
+                }
+            }
+            catch (_error) {
+                /* processes can exit between reads */
+            }
+        }
+        return false;
+    };
+    if (fs.existsSync(stopFile) || foreground()) {
+        fs.writeFileSync(yielded, 'foreground');
+        process.exitCode = 125;
+        return;
+    }
+    // OS idle CPU and I/O scheduling are inherited by the runner and Chromium.
+    // Fall back to nice(19) where chrt/ionice are unavailable.
+    const lowPriority = 'if command -v ionice >/dev/null 2>&1; then ionice -c 3 -p $$ 2>/dev/null; fi; if command -v chrt >/dev/null 2>&1; then chrt --idle --pid 0 $$ 2>/dev/null; fi; exec sh -c "$1"';
+    child = cp.spawn('sh', ['-c', lowPriority, 'feedback', config.command], {
+        cwd: config.cwd,
+        detached: true,
+        stdio: 'inherit',
+    });
+    const watch = fs.watch(config.directory, () => {
+        if (fs.existsSync(stopFile))
+            stop();
+    });
+    const poll = setInterval(() => {
+        rememberChildren();
+        if (foreground())
+            stop(true);
+    }, 100);
+    const terminate = () => stop();
+    process.on('SIGINT', terminate);
+    process.on('SIGTERM', terminate);
+    process.on('exit', terminate);
+    child.on('error', () => {
+        stop();
+        finish(1);
+    });
+    const finish = (code) => {
+        stop();
+        watch.close();
+        clearInterval(poll);
+        process.off('SIGINT', terminate);
+        process.off('SIGTERM', terminate);
+        process.off('exit', terminate);
+        process.exitCode = code;
+    };
+    child.on('close', (code) => finish(done ? 125 : (code ?? 1)));
+    // An abort can arrive between the first check and installing fs.watch.
+    if (fs.existsSync(stopFile))
+        stop();
+}
+/**
+ * Compose a private native supervisor without putting the test command on its argv.
+ * @param config - The known command, working directory and owned scratch directory.
+ * @returns A self-contained native Node program.
+ */
+export function feedbackProcessSource(config) {
+    return `(${feedbackProcess.toString()})(require,${JSON.stringify(config)});\n`;
+}

package/dist/playwright-feedback-reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-feedback-reporter.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-reporter.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAG/E;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAyB/C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,yBAAyB,EAAE,CA4C7B"}
+{"version":3,"file":"playwright-feedback-reporter.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-reporter.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAG/E;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAyB/C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EAAE,GACpB,yBAAyB,EAAE,CAiD7B"}

package/dist/playwright-feedback-reporter.js

@@ -58,6 +58,9 @@ export function nativeFeedbackFailures(text, sourceFiles) {
             const locator = /(?:Locator:\s*|waiting for )(locator\([^\n]+|getBy[^\n]+)/.exec(error)?.[1] ??
                 /strict mode violation: ([^\n]+)/.exec(error)?.[1] ??
                 /(?:^|\n)((?:Error: )?expect\([^\n]+|AssertionError:[^\n]+)/.exec(error)?.[1] ??
+                // Navigation waits can expire before the overall test budget. They have no
+                // locator, but still carry the native operation, test line and page snapshot.
+                /(?:^|\n)TimeoutError: ((?:page|locator)\.[\w.]+): Timeout \d+ms exceeded\./.exec(error)?.[1] ??
                 // A UI loop can exhaust the test budget between actions. Playwright then names
                 // page.waitForTimeout/locator.count rather than a locator. That is still the
                 // supplied test's real failure, with its native location and page snapshot.

package/dist/playwright-feedback-types.d.ts

@@ -38,7 +38,7 @@ export interface PlaywrightFeedbackResult {
     spec: string;
     revision: number;
     durationMs: number;
-    status: 'passed' | 'failed' | 'unavailable';
+    status: 'passed' | 'failed' | 'unavailable' | 'cancelled';
     failures: PlaywrightFeedbackFailure[];
     /** Native counts for this one diagnostic selection, never whole-suite proof. */
     nativeStats?: PlaywrightReportStats;
@@ -47,7 +47,9 @@ export interface PlaywrightFeedbackResult {
 /** Host operations for the same scheduler in a CLI process or a remote sandbox. */
 export interface PlaywrightFeedbackOptions {
     load: () => Promise<FeedbackProject>;
-    run: (spec: FeedbackSpec, sources: string[], revision: number, emit: (result: PlaywrightFeedbackResult) => void) => Promise<PlaywrightFeedbackResult>;
+    run: (spec: FeedbackSpec, sources: string[], revision: number, emit: (result: PlaywrightFeedbackResult) => void, 
+    /** Stop the owned native process group when cancelled; never wait for the tests to finish. */
+    signal: AbortSignal) => Promise<PlaywrightFeedbackResult>;
     /** Only current native failures are delivered. Passing apps receive no note. */
     onFailures?: (result: PlaywrightFeedbackResult) => void;
     /** Operational state is separate from defect feedback. */
@@ -58,6 +60,8 @@ export interface PlaywrightFeedbackOptions {
 export interface PlaywrightFeedback {
     changed: (paths: readonly string[]) => void;
     takeFailures: () => PlaywrightFeedbackResult[];
+    /** Cancel speculation before foreground work. Release after that work; nested callers are safe. */
+    pause: () => Promise<() => void>;
     /** Wait only in tests or shutdown; file writes and deploys must never await this. */
     settled: () => Promise<void>;
     close: () => Promise<void>;

package/dist/playwright-feedback-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-feedback-types.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3C,QAAQ,EAAE,yBAAyB,EAAE,CAAA;IACrC,gFAAgF;IAChF,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC,GAAG,EAAE,CACH,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,KAC7C,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACtC,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,MAAM,wBAAwB,EAAE,CAAA;IAC9C,qFAAqF;IACrF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}
+{"version":3,"file":"playwright-feedback-types.d.ts","sourceRoot":"","sources":["../src/playwright-feedback-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAEnE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wFAAwF;IACxF,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAA;IACzD,QAAQ,EAAE,yBAAyB,EAAE,CAAA;IACrC,gFAAgF;IAChF,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAA;IACpC,GAAG,EAAE,CACH,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI;IAChD,8FAA8F;IAC9F,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,wBAAwB,CAAC,CAAA;IACtC,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACvD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,MAAM,wBAAwB,EAAE,CAAA;IAC9C,mGAAmG;IACnG,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IAChC,qFAAqF;IACrF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}

package/dist/playwright-feedback.d.ts

@@ -38,5 +38,6 @@ export declare function runPlaywrightFeedback(backend: ExecutionBackend, spec: F
     timeoutMs?: number;
     emit?: (result: PlaywrightFeedbackResult) => void;
     pollMs?: number;
+    signal?: AbortSignal;
 }): Promise<PlaywrightFeedbackResult>;
 //# sourceMappingURL=playwright-feedback.d.ts.map

package/dist/playwright-feedback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-feedback.d.ts","sourceRoot":"","sources":["../src/playwright-feedback.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAElB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGlD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAyG/F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GACA,OAAO,CAAC,wBAAwB,CAAC,CAwInC"}
+{"version":3,"file":"playwright-feedback.d.ts","sourceRoot":"","sources":["../src/playwright-feedback.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAEV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAElB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,gCAAgC,CAAA;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGlD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CA2I/F;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,gBAAgB,EACzB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAAC,cAAc,EAAE,CAAC,CAkB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IACP,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GACA,OAAO,CAAC,wBAAwB,CAAC,CA+KnC"}

package/dist/playwright-feedback.js

@@ -8,7 +8,9 @@
  * @module
  */
 import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
 import { posix } from 'node:path';
+import { feedbackProcessSource } from './playwright-feedback-process.js';
 import { feedbackReporterSource, nativeFeedbackFailures } from './playwright-feedback-reporter.js';
 import { selectFeedbackSpecs } from './playwright-feedback-selection.js';
 import { summarizePlaywrightReport } from './playwright-report.js';
@@ -28,15 +30,22 @@ export function isPlaywrightFeedbackSource(path) {
  */
 export function createPlaywrightFeedback(options) {
     let revision = 0, timer, active;
+    let running;
+    let cancellation;
+    let paused = 0;
     let stopped = false;
     const changed = new Set(), waiting = [];
     const delivered = new Map();
     const failing = new Set();
     const start = () => {
-        if (active || stopped || changed.size === 0)
+        if (active || stopped || paused || changed.size === 0)
             return;
         const version = revision, paths = [...changed];
         changed.clear();
+        const abort = new AbortController();
+        cancellation = abort;
+        let yielded = false;
+        const current = () => !stopped && !abort.signal.aborted && version === revision;
         active = (async () => {
             let project;
             try {
@@ -45,16 +54,16 @@ export function createPlaywrightFeedback(options) {
             catch (_error) {
                 return;
             }
-            if (stopped || version !== revision)
+            if (!current())
                 return;
             const sourcePaths = project.root ? paths.map((p) => posix.resolve(project.root, p)) : paths;
             // The native failures already name the files to rerun first after an edit.
             const selected = selectFeedbackSpecs(project, sourcePaths).sort((a, b) => Number(failing.has(b.spec.path)) - Number(failing.has(a.spec.path)));
             for (const { spec, sourceFiles } of selected) {
-                if (stopped || version !== revision)
+                if (!current())
                     break;
                 const emit = (result) => {
-                    if (stopped || version !== revision || result.status !== 'failed')
+                    if (!current() || result.status !== 'failed')
                         return;
                     failing.add(spec.path);
                     const identities = delivered.get(spec.path) ?? new Set();
@@ -74,13 +83,23 @@ export function createPlaywrightFeedback(options) {
                 };
                 let result;
                 try {
-                    result = await options.run(spec, sourceFiles, version, emit);
+                    running = options.run(spec, sourceFiles, version, emit, abort.signal);
+                    result = await running;
                 }
                 catch (_error) {
                     continue;
+                }
+                finally {
+                    running = undefined;
                 } // runner availability is not a markup defect
-                if (stopped || version !== revision)
+                if (!current())
+                    break;
+                if (result.status === 'cancelled') {
+                    yielded = true;
+                    for (const path of paths)
+                        changed.add(path);
                     break;
+                }
                 options.onResult?.(result);
                 if (result.status === 'passed')
                     failing.delete(spec.path);
@@ -90,21 +109,25 @@ export function createPlaywrightFeedback(options) {
             }
         })().finally(() => {
             active = undefined;
-            if (!stopped && changed.size && !timer)
-                schedule();
+            cancellation = undefined;
+            if (abort.signal.aborted && !stopped)
+                for (const path of paths)
+                    changed.add(path);
+            if (!stopped && !paused && changed.size && !timer)
+                schedule(yielded ? 1000 : undefined);
         });
     };
-    const schedule = () => {
+    const schedule = (delay = options.debounceMs ?? 250) => {
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = undefined;
             start();
-        }, options.debounceMs ?? 250);
+        }, delay);
         timer.unref?.();
     };
     const settled = async () => {
-        while (timer || active || (!stopped && changed.size)) {
+        while (timer || active || (!stopped && !paused && changed.size)) {
             if (timer) {
                 clearTimeout(timer);
                 timer = undefined;
@@ -112,7 +135,7 @@ export function createPlaywrightFeedback(options) {
             }
             if (active)
                 await active;
-            else if (!stopped && changed.size)
+            else if (!stopped && !paused && changed.size)
                 start();
         }
     };
@@ -127,14 +150,35 @@ export function createPlaywrightFeedback(options) {
             // A queued diagnosis can be invalidated before its host delivers it. A
             // new revision must be allowed to report the same still-failing locator.
             delivered.clear();
-            schedule();
+            cancellation?.abort();
+            if (!paused)
+                schedule();
         },
         takeFailures() {
             return waiting.splice(0).filter((r) => r.revision === revision);
         },
+        async pause() {
+            paused++;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            cancellation?.abort();
+            // Loading metadata is not native work and must not become a foreground barrier.
+            await running?.catch(() => undefined);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                paused--;
+                if (!paused && !stopped && changed.size)
+                    schedule();
+            };
+        },
         settled,
         async close() {
             stopped = true;
+            cancellation?.abort();
             if (timer)
                 clearTimeout(timer);
             timer = undefined;
@@ -185,7 +229,8 @@ for(const f of ${JSON.stringify([...sourceRoots, ...suiteFiles])})read(f);proces
  */
 export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision, options) {
     const started = Date.now();
-    const dir = posix.join(options.scratchRoot ?? posix.join(backend.projectRoot, '.mol', 'test-feedback'), randomUUID());
+    const dir = posix.join(options.scratchRoot ??
+        posix.join(backend.hostFs ? tmpdir() : '/tmp', 'molecule-playwright-feedback'), randomUUID());
     const reportPath = posix.join(dir, 'report.json');
     const reporterPath = posix.join(dir, 'feedback-reporter.cjs');
     const eventsPath = posix.join(dir, 'failures.jsonl');
@@ -206,7 +251,16 @@ export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision
     ]);
     // The standard OS priority keeps background diagnosis behind the dev server
     // and builds when they share one CPU. Playwright owns its global deadline.
-    const command = `export PLAYWRIGHT_JSON_OUTPUT_FILE=${shellQuote(reportPath)} MOL_TEST_FEEDBACK_EVENTS=${shellQuote(eventsPath)}; nice -n 10 sh -c ${shellQuote(native)}`;
+    const command = `export MOL_TEST_INTERNAL=1 PLAYWRIGHT_JSON_OUTPUT_FILE=${shellQuote(reportPath)} MOL_TEST_FEEDBACK_EVENTS=${shellQuote(eventsPath)}; node ${shellQuote(posix.join(dir, 'run.cjs'))}`;
+    let cancelling;
+    const cancel = () => {
+        cancelling ??= backend.writeFile(posix.join(dir, 'stop'), '').catch(() => undefined);
+    };
+    const cancelled = () => ({
+        ...base,
+        status: 'cancelled',
+        durationMs: Date.now() - started,
+    });
     let poll, reading, done = false;
     const emitted = new Set();
     const nativeFailures = new Map();
@@ -219,6 +273,8 @@ export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision
                 if (emitted.has(identity))
                     continue;
                 emitted.add(identity);
+                if (options.signal?.aborted)
+                    continue;
                 options.emit?.({
                     ...base,
                     failures: [failure],
@@ -242,7 +298,23 @@ export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision
         });
     };
     try {
+        if (options.signal?.aborted)
+            return cancelled();
+        await backend.run(`node -e ${shellQuote(`require('node:fs').mkdirSync(${JSON.stringify(dir)},{recursive:true,mode:0o700})`)}`, { timeout: 5_000 });
         await backend.writeFile(reporterPath, feedbackReporterSource());
+        await backend.writeFile(posix.join(dir, 'run.cjs'), feedbackProcessSource({
+            command: native,
+            cwd: spec.cwd,
+            root: backend.projectRoot,
+            directory: dir,
+        }));
+        options.signal?.addEventListener('abort', cancel, { once: true });
+        if (options.signal?.aborted)
+            cancel();
+        if (cancelling) {
+            await cancelling;
+            return cancelled();
+        }
         if (options.emit)
             tick();
         const result = await backend.run(command, {
@@ -250,6 +322,15 @@ export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision
             timeout: timeout + 10_000,
             budgetMs: timeout + 5_000,
         });
+        if (options.signal?.aborted)
+            return cancelled();
+        try {
+            if ((await backend.readFile(posix.join(dir, 'yielded'))) === 'foreground')
+                return cancelled();
+        }
+        catch (_error1) {
+            /* the native run was not preempted */
+        }
         done = true;
         if (poll)
             clearTimeout(poll);
@@ -306,6 +387,9 @@ export async function runPlaywrightFeedback(backend, spec, sourceFiles, revision
     }
     finally {
         done = true;
+        options.signal?.removeEventListener('abort', cancel);
+        if (cancelling)
+            await cancelling;
         if (poll)
             clearTimeout(poll);
         if (reading)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",