From e42458a21c8b164467aa66e7da8e17a0d631c5bb Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 02:41:00 +0200
Subject: [PATCH 01/12] fix(worker-bus): enforce runOnPool() timeoutMs with
 watchdog + force-terminate

- runOnPool() now arms a timer keyed to task.timeoutMs when the TASK
  message is posted. Previously a wedged worker (no crash, no message)
  left the task's result promise pending forever.
- PROGRESS messages re-arm the watchdog so long-running jobs (ProForge
  stages, LoRA training) that report progress aren't falsely killed.
- On expiry: settle with a recoverable TaskResult error (code TIMEOUT),
  which flows through the existing retry/circuit-breaker/DLQ pipeline
  unchanged (recordFailure(), retry-then-DLQ-then-reject).
- Add WorkerPool.terminateWorker(workerId): force-terminates one worker
  and respawns a replacement (mirrors the crash-detection restart path)
  instead of recycling a wedged worker back to idle via release().
- Tests: timeout rejects a hung task, force-terminates the worker, and
  is not called for release(); watchdog reset via PROGRESS keeps a
  slow-but-alive task from being killed; terminateWorker unit tests.
---
 packages/worker-bus/src/workerBus.ts         |  55 +++++++++-
 packages/worker-bus/src/workerPool.ts        |  12 +++
 packages/worker-bus/tests/workerBus.test.ts  | 101 +++++++++++++++++++
 packages/worker-bus/tests/workerPool.test.ts |  37 +++++++
 4 files changed, 200 insertions(+), 5 deletions(-)

diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index f7e4b964e..9bb7fee8b 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -262,6 +262,9 @@ export class WorkerBus {
     const worker = await pool.acquire(token.signal);
     const startedAt = performance.now();
     const queueTimeMs = Math.round(startedAt - task.createdAt);
+    // QNBS-v3: [P0 timeout enforcement — runOnPool previously awaited RESULT/abort forever;
+    //          a wedged worker (no crash, no message) left the task's promise pending indefinitely.]
+    let timedOut = false;
 
     try {
       const port = worker.port;
@@ -271,12 +274,49 @@ export class WorkerBus {
 
       const result = await new Promise<TaskResult<TResult>>((resolve, _reject) => {
         let settled = false;
+        let timeoutTimer: ReturnType<typeof setTimeout>;
+
+        const settle = () => {
+          settled = true;
+          clearTimeout(timeoutTimer);
+          port.removeEventListener('message', handler);
+        };
+
+        // QNBS-v3: watchdog, not a hard ceiling — re-armed on every PROGRESS message so
+        //          long-running jobs (ProForge stages, LoRA training) that report progress
+        //          aren't falsely killed while genuinely wedged workers still get caught.
+        const armTimeout = () => {
+          clearTimeout(timeoutTimer);
+          timeoutTimer = setTimeout(onTimeout, task.timeoutMs);
+        };
+
+        const onTimeout = () => {
+          if (settled) return;
+          settle();
+          timedOut = true;
+          resolve({
+            taskId: task.taskId,
+            success: false,
+            error: {
+              code: 'TIMEOUT',
+              message: `Task exceeded its ${task.timeoutMs}ms deadline with no response from the worker`,
+              recoverable: true,
+              retryCount: 0,
+            },
+            latencyMs: Math.round(performance.now() - startedAt),
+            queueTimeMs,
+            workerId: worker.workerId,
+            layer: 'web',
+          });
+        };
+
         const handler = (event: MessageEvent) => {
           if (settled) return;
           const msg = validateWorkerMessage(event.data);
           if (!msg) return;
 
           if (msg.kind === 'PROGRESS') {
+            armTimeout();
             this.progress.emit(task.taskId, {
               taskId: task.taskId,
               taskType: task.taskType,
@@ -286,8 +326,7 @@ export class WorkerBus {
               timestamp: Date.now(),
             });
           } else if (msg.kind === 'RESULT') {
-            settled = true;
-            port.removeEventListener('message', handler);
+            settle();
             const latencyMs = Math.round(performance.now() - startedAt);
             resolve({
               taskId: task.taskId,
@@ -309,11 +348,11 @@ export class WorkerBus {
           }
         };
         port.addEventListener('message', handler);
+        armTimeout();
 
         const onAbort = () => {
           if (settled) return;
-          settled = true;
-          port.removeEventListener('message', handler);
+          settle();
           port.postMessage(createCancelMessage(task.taskId, 'Aborted'));
           resolve({
             taskId: task.taskId,
@@ -342,7 +381,13 @@ export class WorkerBus {
       }
       return result;
     } finally {
-      pool.release(worker);
+      // QNBS-v3: a timed-out worker is presumed wedged — force-terminate + respawn instead of
+      //          releasing it back to the idle pool where a future task would reuse it.
+      if (timedOut) {
+        pool.terminateWorker(worker.workerId);
+      } else {
+        pool.release(worker);
+      }
     }
   }
 
diff --git a/packages/worker-bus/src/workerPool.ts b/packages/worker-bus/src/workerPool.ts
index b1d2531ba..88cf0ada8 100644
--- a/packages/worker-bus/src/workerPool.ts
+++ b/packages/worker-bus/src/workerPool.ts
@@ -82,6 +82,18 @@ export class WorkerPool {
     this.entries = [];
   }
 
+  /**
+   * Force-terminate one worker and respawn a replacement (pool stays at capacity).
+   * QNBS-v3: a task that missed its timeoutMs deadline may have wedged the worker in an
+   * unknown state — treat it like a crash instead of recycling it back to idle via release().
+   */
+  terminateWorker(workerId: string): void {
+    const entry = this.entries.find((e) => e.instance.workerId === workerId);
+    if (!entry) return;
+    this.setCrashed(workerId);
+    this.restartWorker(entry);
+  }
+
   getHealth(): {
     totalWorkers: number;
     idleWorkers: number;
diff --git a/packages/worker-bus/tests/workerBus.test.ts b/packages/worker-bus/tests/workerBus.test.ts
index c0c83332d..6c64d04cc 100644
--- a/packages/worker-bus/tests/workerBus.test.ts
+++ b/packages/worker-bus/tests/workerBus.test.ts
@@ -626,4 +626,105 @@ describe('WorkerBus', () => {
     handle.cancel('test-abort');
     await expect(handle.result).rejects.toThrow('cancelled');
   });
+
+  it('times out a hung worker, records a circuit-breaker failure, and force-terminates it', async () => {
+    // Worker never sends PROGRESS or RESULT — simulates a wedged worker (not crashed, just silent).
+    const mockPort = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      postMessage: vi.fn(),
+      start: vi.fn(),
+    };
+
+    const mockWorker = {
+      workerId: 'mock-worker-hung',
+      worker: {} as Worker,
+      channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
+      port: mockPort as unknown as MessagePort,
+      state: 'idle' as const,
+      capabilities: ['inference.text'] as const,
+      labels: {},
+    };
+
+    const pool = (bus as unknown as { pools: Map<string, WorkerPool> }).pools.get('fake')!;
+    vi.spyOn(pool, 'acquire').mockResolvedValue(
+      mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
+    );
+    const terminateWorkerSpy = vi.spyOn(pool, 'terminateWorker').mockImplementation(() => {});
+    const releaseSpy = vi.spyOn(pool, 'release');
+
+    const handle = bus.enqueue(
+      'test.task',
+      { data: 1 },
+      { timeoutMs: 25, retryPolicy: { maxRetries: 0 } },
+    );
+
+    await expect(handle.result).rejects.toThrow(/exceeded its 25ms deadline/i);
+    expect(terminateWorkerSpy).toHaveBeenCalledWith('mock-worker-hung');
+    expect(releaseSpy).not.toHaveBeenCalled();
+    expect(bus.getTelemetry().failedTasks).toBe(1);
+    expect(bus.getTelemetry().deadLetterCount).toBe(1);
+    expect(bus.getTelemetry().circuitBreakerStates['test.task']).toBeDefined();
+  });
+
+  it('resets the timeout watchdog on PROGRESS so a slow-but-alive task is not killed early', async () => {
+    const mockPort = {
+      addEventListener: vi.fn((type: string, handler: EventListener) => {
+        if (type === 'message') {
+          // Two PROGRESS pings inside the timeout window, then RESULT after the original
+          // deadline would have expired — only survives if PROGRESS re-arms the watchdog.
+          setTimeout(() => {
+            handler(
+              new MessageEvent('message', {
+                data: { kind: 'PROGRESS', taskId: 'mock-task-id', stage: 'step1', progress: 0.3 },
+              }),
+            );
+          }, 15);
+          setTimeout(() => {
+            handler(
+              new MessageEvent('message', {
+                data: { kind: 'PROGRESS', taskId: 'mock-task-id', stage: 'step2', progress: 0.6 },
+              }),
+            );
+          }, 30);
+          setTimeout(() => {
+            handler(
+              new MessageEvent('message', {
+                data: {
+                  kind: 'RESULT',
+                  taskId: 'mock-task-id',
+                  success: true,
+                  result: 'slow-but-done',
+                  latencyMs: 45,
+                },
+              }),
+            );
+          }, 45);
+        }
+      }),
+      removeEventListener: vi.fn(),
+      postMessage: vi.fn(),
+      start: vi.fn(),
+    };
+
+    const mockWorker = {
+      workerId: 'mock-worker-slow',
+      worker: {} as Worker,
+      channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
+      port: mockPort as unknown as MessagePort,
+      state: 'idle' as const,
+      capabilities: ['inference.text'] as const,
+      labels: {},
+    };
+
+    const pool = (bus as unknown as { pools: Map<string, WorkerPool> }).pools.get('fake')!;
+    vi.spyOn(pool, 'acquire').mockResolvedValue(
+      mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
+    );
+
+    // timeoutMs (20ms) is shorter than the total run (45ms), but each PROGRESS arrives
+    // well within 20ms of the previous reset, so the watchdog never fires.
+    const handle = bus.enqueue('test.task', { data: 1 }, { timeoutMs: 20 });
+    await expect(handle.result).resolves.toBe('slow-but-done');
+  });
 });
diff --git a/packages/worker-bus/tests/workerPool.test.ts b/packages/worker-bus/tests/workerPool.test.ts
index af7f99850..89488174c 100644
--- a/packages/worker-bus/tests/workerPool.test.ts
+++ b/packages/worker-bus/tests/workerPool.test.ts
@@ -204,4 +204,41 @@ describe('WorkerPool', () => {
     pool.release(worker);
     expect(pool.getHealth().totalWorkers).toBe(0);
   });
+
+  it('terminateWorker force-terminates a specific worker and respawns a replacement', async () => {
+    const pool = new WorkerPool('test-pool', ['inference.text'], {
+      maxWorkers: 1,
+      minWorkers: 1,
+      idleTimeoutMs: 120_000,
+      workerScript: '/mock.worker.js',
+      capabilities: ['inference.text'],
+      labels: {},
+    });
+    const worker = await pool.acquire();
+    const mockWorker = worker.worker as unknown as MockWorker;
+
+    pool.terminateWorker(worker.workerId);
+
+    expect(mockWorker.terminated).toBe(true);
+    // QNBS-v3: like restartWorker() on crash — the pool respawns to stay at capacity,
+    //          but the new worker must be a distinct instance, not the wedged one.
+    expect(pool.getHealth().totalWorkers).toBe(1);
+    expect(pool.getHealth().crashedWorkers).toBe(0);
+    await pool.terminateAll();
+  });
+
+  it('terminateWorker is a no-op for an unknown workerId', async () => {
+    const pool = new WorkerPool('test-pool', ['inference.text'], {
+      maxWorkers: 1,
+      minWorkers: 1,
+      idleTimeoutMs: 120_000,
+      workerScript: '/mock.worker.js',
+      capabilities: ['inference.text'],
+      labels: {},
+    });
+    await pool.acquire();
+    expect(() => pool.terminateWorker('nonexistent-worker-id')).not.toThrow();
+    expect(pool.getHealth().totalWorkers).toBe(1);
+    await pool.terminateAll();
+  });
 });

From 1a9b13ddb125231167d611861d00def93899c252 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 02:52:10 +0200
Subject: [PATCH 02/12] feat(worker-bus): size inference pool maxWorkers to
 device memory tier
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- workerBusManager.inferencePoolOptions() now derives maxWorkers from
  localAiDeviceProfiler.detectMemoryTier() instead of a hardcoded 2:
  high memory tier -> 3, medium -> 2 (unchanged default), low -> 1.
  Still capped at MAX_WORKERS_INFERENCE.
- Export detectMemoryTier from localAiDeviceProfiler.ts (was
  module-private) — it's a synchronous, side-effect-free read, so
  callers that only need pool sizing don't pay for the full async
  generateDeviceProfile() (WebGPU/WebNN/battery probes).
- Falls back to maxWorkers 2 (previous default) if memory-tier
  detection throws, so pool init can never be blocked by this.
- Tests: high/medium/low tier sizing + throw-fallback, exercised via
  the same ensureInferencePool() re-registration path as the existing
  memory-safety-cap test (initWorkerBus() itself only calls the mocked
  registry.register(), not bus.registerPool()).
---
 services/ai/localAiDeviceProfiler.ts |  5 ++-
 services/workerBusManager.ts         | 25 ++++++++++-
 tests/unit/workerBusManager.test.ts  | 66 ++++++++++++++++++++++++++++
 3 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/services/ai/localAiDeviceProfiler.ts b/services/ai/localAiDeviceProfiler.ts
index acd397150..35ef2aa63 100644
--- a/services/ai/localAiDeviceProfiler.ts
+++ b/services/ai/localAiDeviceProfiler.ts
@@ -172,7 +172,10 @@ function detectDirectML(
 // Memory Tier
 // ---------------------------------------------------------------------------
 
-function detectMemoryTier(): DeviceCapabilityProfile['memoryTier'] {
+// QNBS-v3: exported (previously module-private) so callers that only need a fast, synchronous
+//          memory-tier read — e.g. workerBusManager sizing the inference pool at init — don't
+//          have to pay for the full async generateDeviceProfile() (WebGPU/WebNN/battery probes).
+export function detectMemoryTier(): DeviceCapabilityProfile['memoryTier'] {
   const deviceMemory =
     typeof navigator !== 'undefined' && 'deviceMemory' in navigator
       ? (navigator as Navigator & { deviceMemory?: number }).deviceMemory
diff --git a/services/workerBusManager.ts b/services/workerBusManager.ts
index caf9a97a9..ad58ca875 100644
--- a/services/workerBusManager.ts
+++ b/services/workerBusManager.ts
@@ -72,9 +72,12 @@ async function inferencePoolOptions() {
   const { MAX_WORKERS_INFERENCE, MIN_WORKERS, WORKER_IDLE_TIMEOUT_MS } = await import(
     '@domain/worker-bus'
   );
+  // QNBS-v3: [P1 — scale inference worker count to the device's memory tier instead of a fixed
+  //          cap. Each replica loads its own transformers.js pipeline (no cross-replica cache
+  //          sharing), so more replicas only help on devices with RAM headroom to spare.]
+  const maxWorkers = Math.min(await resolveInferenceMaxWorkers(), MAX_WORKERS_INFERENCE);
   return {
-    // QNBS-v3: [Capped below MAX_WORKERS_INFERENCE — each replica loads its own transformers.js pipeline (no cross-replica cache sharing), so 4 concurrent workers could mean 4x the model memory footprint under a burst.]
-    maxWorkers: Math.min(2, MAX_WORKERS_INFERENCE),
+    maxWorkers,
     minWorkers: MIN_WORKERS,
     idleTimeoutMs: WORKER_IDLE_TIMEOUT_MS,
     workerScript: new URL('../workers/v2/inference.worker.ts', import.meta.url).href,
@@ -83,6 +86,24 @@ async function inferencePoolOptions() {
   };
 }
 
+/**
+ * QNBS-v3: memory-tier-driven worker count — high:3, medium:2 (previous hardcoded default),
+ * low:1. Falls back to the previous default (2) if device profiling throws (e.g. non-browser
+ * test environment) so this can never block or fail pool initialization.
+ */
+async function resolveInferenceMaxWorkers(): Promise<number> {
+  try {
+    const { detectMemoryTier } = await import('./ai/localAiDeviceProfiler');
+    const tier = detectMemoryTier();
+    if (tier === 'high') return 3;
+    if (tier === 'low') return 1;
+    return 2;
+  } catch (err) {
+    log.warn('Failed to detect memory tier for inference pool sizing; using default', err);
+    return 2;
+  }
+}
+
 /** Re-register the 'inference' pool if it was removed via terminatePool() — a no-op if already present. */
 async function reRegisterInferencePool(bus: WorkerBus): Promise<void> {
   if (bus.hasPool('inference')) return;
diff --git a/tests/unit/workerBusManager.test.ts b/tests/unit/workerBusManager.test.ts
index 2a17c768f..3f15aed2b 100644
--- a/tests/unit/workerBusManager.test.ts
+++ b/tests/unit/workerBusManager.test.ts
@@ -295,4 +295,70 @@ describe('workerBusManager', () => {
       );
     });
   });
+
+  describe('inference pool sizing by memory tier', () => {
+    // QNBS-v3: [P1 — inference pool maxWorkers is now derived from
+    //          localAiDeviceProfiler.detectMemoryTier() instead of a hardcoded 2. Verified via
+    //          the same re-registration path as the "memory-safety cap" test above, since
+    //          initWorkerBus() only calls registry.register() (mocked, no-op) — bus.registerPool()
+    //          with the real computed options is only exercised by ensureInferencePool().]
+    afterEach(() => {
+      vi.doUnmock('../../services/ai/localAiDeviceProfiler');
+    });
+
+    async function expectMaxWorkersForTier(
+      detectMemoryTier: () => 'high' | 'medium' | 'low',
+      expectedMaxWorkers: number,
+    ): Promise<void> {
+      vi.doMock('../../services/ai/localAiDeviceProfiler', () => ({ detectMemoryTier }));
+      const { initWorkerBus, ensureInferencePool } = await import(
+        '../../services/workerBusManager'
+      );
+      await initWorkerBus();
+      mockRegisterPool.mockClear();
+      mockHasPool.mockReturnValue(false);
+
+      await ensureInferencePool();
+
+      expect(mockRegisterPool).toHaveBeenCalledWith(
+        'inference',
+        expect.arrayContaining(['inference.text', 'inference.embed']),
+        expect.objectContaining({ maxWorkers: expectedMaxWorkers }),
+      );
+    }
+
+    it('sizes maxWorkers to 3 on a high memory tier', async () => {
+      await expectMaxWorkersForTier(() => 'high', 3);
+    });
+
+    it('sizes maxWorkers to 2 on a medium memory tier (unchanged default)', async () => {
+      await expectMaxWorkersForTier(() => 'medium', 2);
+    });
+
+    it('sizes maxWorkers to 1 on a low memory tier', async () => {
+      await expectMaxWorkersForTier(() => 'low', 1);
+    });
+
+    it('falls back to maxWorkers 2 when memory-tier detection throws', async () => {
+      vi.doMock('../../services/ai/localAiDeviceProfiler', () => ({
+        detectMemoryTier: () => {
+          throw new Error('profiler boom');
+        },
+      }));
+      const { initWorkerBus, ensureInferencePool } = await import(
+        '../../services/workerBusManager'
+      );
+      await initWorkerBus();
+      mockRegisterPool.mockClear();
+      mockHasPool.mockReturnValue(false);
+
+      await ensureInferencePool();
+
+      expect(mockRegisterPool).toHaveBeenCalledWith(
+        'inference',
+        expect.arrayContaining(['inference.text', 'inference.embed']),
+        expect.objectContaining({ maxWorkers: 2 }),
+      );
+    });
+  });
 });

From 29627ec5960fef3afbfded045e55adf085221bdd Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 03:10:03 +0200
Subject: [PATCH 03/12] fix(worker-bus): forward-declare handler/onTimeout to
 satisfy DeepSource no-use-before-define

---
 packages/worker-bus/src/workerBus.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index 9bb7fee8b..20f367b02 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -275,6 +275,12 @@ export class WorkerBus {
       const result = await new Promise<TaskResult<TResult>>((resolve, _reject) => {
         let settled = false;
         let timeoutTimer: ReturnType<typeof setTimeout>;
+        // QNBS-v3: `handler`/`onTimeout` are forward-declared via `let` (hoisted, no TDZ read)
+        //          because `settle`/`armTimeout` close over them before their real definitions
+        //          run — the three closures are mutually recursive, so a strict top-to-bottom
+        //          `const` chain isn't possible without one forward reference.
+        let handler: (event: MessageEvent) => void;
+        let onTimeout: () => void;
 
         const settle = () => {
           settled = true;
@@ -290,7 +296,7 @@ export class WorkerBus {
           timeoutTimer = setTimeout(onTimeout, task.timeoutMs);
         };
 
-        const onTimeout = () => {
+        onTimeout = () => {
           if (settled) return;
           settle();
           timedOut = true;
@@ -310,7 +316,7 @@ export class WorkerBus {
           });
         };
 
-        const handler = (event: MessageEvent) => {
+        handler = (event: MessageEvent) => {
           if (settled) return;
           const msg = validateWorkerMessage(event.data);
           if (!msg) return;

From 58a52c105b0d9e311e8edf6891927769ea02ac17 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 03:35:28 +0200
Subject: [PATCH 04/12] fix(workerBus): filter stale worker messages by taskId,
 start MessagePort, address review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- workerBus.ts: filter PROGRESS/RESULT messages by msg.taskId so a released-and-reused
  MessagePort can't let a cancelled task's late message reset the watchdog or resolve a
  new task (CodeRabbit + Copilot, real bug)
- workerPool.ts: call channel.port1.start() in spawnWorker — an addEventListener-based
  MessagePort never dispatches without it (Copilot, real bug); add log.warn parity in
  terminateWorker (CodeRabbit nitpick)
- reword TIMEOUT error message for accuracy (Copilot)
- reformat QNBS-v3 comments in localAiDeviceProfiler.ts/workerBusManager.ts to the
  required single-line format (CodeRabbit nitpick)
- workerBus.test.ts: fix two pre-existing tests broken by the new taskId filter
  (hardcoded mock taskId no longer matched the real generated one), convert the two new
  watchdog tests to fake timers to remove CI wall-clock flakiness risk, add a regression
  test for the taskId/MessagePort-reuse fix, add missing QNBS-v3 markers
- workerPool.test.ts, workerBusManager.test.ts: QNBS-v3 marker / single-line reformat
- docs/DEEPSOURCE-REVIEW-LOOP.md: log JS-0067 as a systemic false-positive for this
  ES-module codebase (informational-only check, not required for merge)

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 docs/DEEPSOURCE-REVIEW-LOOP.md               |  15 ++
 packages/worker-bus/src/workerBus.ts         |   5 +-
 packages/worker-bus/src/workerPool.ts        |   3 +
 packages/worker-bus/tests/workerBus.test.ts  | 244 +++++++++++++------
 packages/worker-bus/tests/workerPool.test.ts |   1 +
 services/ai/localAiDeviceProfiler.ts         |   4 +-
 services/workerBusManager.ts                 |  10 +-
 tests/unit/workerBusManager.test.ts          |   6 +-
 8 files changed, 195 insertions(+), 93 deletions(-)

diff --git a/docs/DEEPSOURCE-REVIEW-LOOP.md b/docs/DEEPSOURCE-REVIEW-LOOP.md
index 573dfcb3e..9a3d12aaf 100644
--- a/docs/DEEPSOURCE-REVIEW-LOOP.md
+++ b/docs/DEEPSOURCE-REVIEW-LOOP.md
@@ -270,6 +270,21 @@ GitHub App resumes auto-reviewing, run **both** loops: CodeAnt for narrative/AI
   new service/hook needs its branches tested or patch coverage dips below the ~72% target and the
   `codecov/patch` check fails. #236's hook+panel needed a dedicated hook test (offline/error/disabled/
   stale-apply/dictionary/clear branches) to clear it — same posture as #232's binderDepth test.
+- **2026-08-01** — On PR #305, `DeepSource: JavaScript` surfaced **JS-0067** ("unexpected function
+  declaration in the global scope") on top-level `function`/`async function` declarations in
+  `services/ai/localAiDeviceProfiler.ts` and `services/workerBusManager.ts` — a pattern used
+  throughout this repo's ES modules (every service file declares top-level functions; this is
+  idiomatic, Biome-approved module code, not `<script>`-tag global-scope pollution). Confirmed via
+  `gh api .../branches/main/protection`: only the `CI Success` aggregator is a **required** status
+  check — `DeepSource: JavaScript` is informational-only and does not block merge. Per §4a.3, do not
+  scatter `# skipcq: JS-0067` across dozens of pre-existing functions repo-wide to chase this; the
+  correct fix is a **dashboard rule-level ignore** for JS-0067 (maintainer action, not toml-expressible
+  — DeepSource rule toggles live under Settings → Issue Types on app.deepsource.com, not
+  `.deepsource.toml`). Real, valuable findings from the same wave (real bugs, not style noise) were
+  fixed instead: a stale-`MessagePort`-reuse bug (late PROGRESS/RESULT from a cancelled task could
+  reset/resolve a new task sharing the same released port — fixed by filtering on `msg.taskId` in
+  `workerBus.ts`), and a missing `port.start()` call in `workerPool.ts::spawnWorker()` (an
+  `addEventListener`-based `MessagePort` never dispatches without it per the WHATWG spec).
 
 ---
 
diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index 20f367b02..6ed27b05b 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -305,7 +305,7 @@ export class WorkerBus {
             success: false,
             error: {
               code: 'TIMEOUT',
-              message: `Task exceeded its ${task.timeoutMs}ms deadline with no response from the worker`,
+              message: `No response from the worker for ${task.timeoutMs}ms (inactivity watchdog, not a fixed deadline)`,
               recoverable: true,
               retryCount: 0,
             },
@@ -320,6 +320,9 @@ export class WorkerBus {
           if (settled) return;
           const msg = validateWorkerMessage(event.data);
           if (!msg) return;
+          // QNBS-v3: a released+reused port can still deliver a stale PROGRESS/RESULT from a
+          //          cancelled prior task — ignore anything not addressed to this task.
+          if (msg.taskId !== task.taskId) return;
 
           if (msg.kind === 'PROGRESS') {
             armTimeout();
diff --git a/packages/worker-bus/src/workerPool.ts b/packages/worker-bus/src/workerPool.ts
index 88cf0ada8..126d51265 100644
--- a/packages/worker-bus/src/workerPool.ts
+++ b/packages/worker-bus/src/workerPool.ts
@@ -90,6 +90,7 @@ export class WorkerPool {
   terminateWorker(workerId: string): void {
     const entry = this.entries.find((e) => e.instance.workerId === workerId);
     if (!entry) return;
+    log.warn(`Worker ${workerId} force-terminated after exceeding its task timeout`);
     this.setCrashed(workerId);
     this.restartWorker(entry);
   }
@@ -125,6 +126,8 @@ export class WorkerPool {
       port: channel.port1,
     };
 
+    // QNBS-v3: addEventListener (unlike onmessage) never dispatches until start() is called.
+    channel.port1.start();
     // QNBS-v3: Transfer port2 to worker for dedicated bidirectional channel
     worker.postMessage({ kind: 'INIT_PORT', port: channel.port2 }, [channel.port2]);
 
diff --git a/packages/worker-bus/tests/workerBus.test.ts b/packages/worker-bus/tests/workerBus.test.ts
index 6c64d04cc..361a907b3 100644
--- a/packages/worker-bus/tests/workerBus.test.ts
+++ b/packages/worker-bus/tests/workerBus.test.ts
@@ -485,6 +485,8 @@ describe('WorkerBus', () => {
   });
 
   it('runs task through real worker port and resolves result', async () => {
+    // QNBS-v3: taskId is captured post-enqueue since the mock's RESULT must now match the real generated taskId (taskId filter above).
+    let capturedTaskId = '';
     // Create a mock port that responds with a RESULT message
     const mockPort = {
       addEventListener: vi.fn((type: string, handler: EventListener) => {
@@ -495,7 +497,7 @@ describe('WorkerBus', () => {
               new MessageEvent('message', {
                 data: {
                   kind: 'RESULT',
-                  taskId: 'mock-task-id',
+                  taskId: capturedTaskId,
                   success: true,
                   result: 'worker-output',
                   latencyMs: 10,
@@ -526,10 +528,13 @@ describe('WorkerBus', () => {
     );
 
     const handle = bus.enqueue('test.task', { data: 1 });
+    capturedTaskId = handle.taskId;
     await expect(handle.result).resolves.toBe('worker-output');
   });
 
   it('runs task through real worker port and handles progress', async () => {
+    // QNBS-v3: taskId is captured post-enqueue since the mock's PROGRESS/RESULT must now match the real generated taskId (taskId filter above).
+    let capturedTaskId = '';
     const progressEvents: Array<{ stage: string; progress: number }> = [];
     const mockPort = {
       addEventListener: vi.fn((type: string, handler: EventListener) => {
@@ -539,7 +544,7 @@ describe('WorkerBus', () => {
               new MessageEvent('message', {
                 data: {
                   kind: 'PROGRESS',
-                  taskId: 'mock-task-id',
+                  taskId: capturedTaskId,
                   stage: 'loading',
                   progress: 0.5,
                 },
@@ -551,7 +556,7 @@ describe('WorkerBus', () => {
               new MessageEvent('message', {
                 data: {
                   kind: 'RESULT',
-                  taskId: 'mock-task-id',
+                  taskId: capturedTaskId,
                   success: true,
                   result: 'done',
                   latencyMs: 10,
@@ -588,6 +593,7 @@ describe('WorkerBus', () => {
         onProgress: (p) => progressEvents.push({ stage: p.stage, progress: p.progress }),
       },
     );
+    capturedTaskId = handle.taskId;
     await handle.result;
     expect(progressEvents.length).toBeGreaterThanOrEqual(1);
     expect(progressEvents[0]?.stage).toBe('loading');
@@ -628,79 +634,144 @@ describe('WorkerBus', () => {
   });
 
   it('times out a hung worker, records a circuit-breaker failure, and force-terminates it', async () => {
-    // Worker never sends PROGRESS or RESULT — simulates a wedged worker (not crashed, just silent).
-    const mockPort = {
-      addEventListener: vi.fn(),
-      removeEventListener: vi.fn(),
-      postMessage: vi.fn(),
-      start: vi.fn(),
-    };
-
-    const mockWorker = {
-      workerId: 'mock-worker-hung',
-      worker: {} as Worker,
-      channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
-      port: mockPort as unknown as MessagePort,
-      state: 'idle' as const,
-      capabilities: ['inference.text'] as const,
-      labels: {},
-    };
-
-    const pool = (bus as unknown as { pools: Map<string, WorkerPool> }).pools.get('fake')!;
-    vi.spyOn(pool, 'acquire').mockResolvedValue(
-      mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
-    );
-    const terminateWorkerSpy = vi.spyOn(pool, 'terminateWorker').mockImplementation(() => {});
-    const releaseSpy = vi.spyOn(pool, 'release');
-
-    const handle = bus.enqueue(
-      'test.task',
-      { data: 1 },
-      { timeoutMs: 25, retryPolicy: { maxRetries: 0 } },
-    );
-
-    await expect(handle.result).rejects.toThrow(/exceeded its 25ms deadline/i);
-    expect(terminateWorkerSpy).toHaveBeenCalledWith('mock-worker-hung');
-    expect(releaseSpy).not.toHaveBeenCalled();
-    expect(bus.getTelemetry().failedTasks).toBe(1);
-    expect(bus.getTelemetry().deadLetterCount).toBe(1);
-    expect(bus.getTelemetry().circuitBreakerStates['test.task']).toBeDefined();
+    // QNBS-v3: fake timers make the 25ms deadline deterministic instead of racing real wall-clock time in CI.
+    vi.useFakeTimers();
+    try {
+      // Worker never sends PROGRESS or RESULT — simulates a wedged worker (not crashed, just silent).
+      const mockPort = {
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        postMessage: vi.fn(),
+        start: vi.fn(),
+      };
+
+      const mockWorker = {
+        workerId: 'mock-worker-hung',
+        worker: {} as Worker,
+        channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
+        port: mockPort as unknown as MessagePort,
+        state: 'idle' as const,
+        capabilities: ['inference.text'] as const,
+        labels: {},
+      };
+
+      const pool = (bus as unknown as { pools: Map<string, WorkerPool> }).pools.get('fake')!;
+      vi.spyOn(pool, 'acquire').mockResolvedValue(
+        mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
+      );
+      const terminateWorkerSpy = vi.spyOn(pool, 'terminateWorker').mockImplementation(() => {});
+      const releaseSpy = vi.spyOn(pool, 'release');
+
+      const handle = bus.enqueue(
+        'test.task',
+        { data: 1 },
+        { timeoutMs: 25, retryPolicy: { maxRetries: 0 } },
+      );
+      const assertion = expect(handle.result).rejects.toThrow(
+        /no response from the worker for 25ms/i,
+      );
+      await vi.advanceTimersByTimeAsync(25);
+      await assertion;
+
+      expect(terminateWorkerSpy).toHaveBeenCalledWith('mock-worker-hung');
+      expect(releaseSpy).not.toHaveBeenCalled();
+      expect(bus.getTelemetry().failedTasks).toBe(1);
+      expect(bus.getTelemetry().deadLetterCount).toBe(1);
+      expect(bus.getTelemetry().circuitBreakerStates['test.task']).toBeDefined();
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it('resets the timeout watchdog on PROGRESS so a slow-but-alive task is not killed early', async () => {
+    // QNBS-v3: fake timers replace real 15/30/45ms delays so the 20ms re-arm margin can't flake under CI scheduling jitter.
+    vi.useFakeTimers();
+    try {
+      // QNBS-v3: taskId is captured post-enqueue since the mock's messages must match the real generated taskId (taskId filter above).
+      let capturedTaskId = '';
+      const mockPort = {
+        addEventListener: vi.fn((type: string, handler: EventListener) => {
+          if (type === 'message') {
+            // Two PROGRESS pings inside the timeout window, then RESULT after the original
+            // deadline would have expired — only survives if PROGRESS re-arms the watchdog.
+            setTimeout(() => {
+              handler(
+                new MessageEvent('message', {
+                  data: {
+                    kind: 'PROGRESS',
+                    taskId: capturedTaskId,
+                    stage: 'step1',
+                    progress: 0.3,
+                  },
+                }),
+              );
+            }, 15);
+            setTimeout(() => {
+              handler(
+                new MessageEvent('message', {
+                  data: {
+                    kind: 'PROGRESS',
+                    taskId: capturedTaskId,
+                    stage: 'step2',
+                    progress: 0.6,
+                  },
+                }),
+              );
+            }, 30);
+            setTimeout(() => {
+              handler(
+                new MessageEvent('message', {
+                  data: {
+                    kind: 'RESULT',
+                    taskId: capturedTaskId,
+                    success: true,
+                    result: 'slow-but-done',
+                    latencyMs: 45,
+                  },
+                }),
+              );
+            }, 45);
+          }
+        }),
+        removeEventListener: vi.fn(),
+        postMessage: vi.fn(),
+        start: vi.fn(),
+      };
+
+      const mockWorker = {
+        workerId: 'mock-worker-slow',
+        worker: {} as Worker,
+        channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
+        port: mockPort as unknown as MessagePort,
+        state: 'idle' as const,
+        capabilities: ['inference.text'] as const,
+        labels: {},
+      };
+
+      const pool = (bus as unknown as { pools: Map<string, WorkerPool> }).pools.get('fake')!;
+      vi.spyOn(pool, 'acquire').mockResolvedValue(
+        mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
+      );
+
+      // timeoutMs (20ms) is shorter than the total run (45ms), but each PROGRESS arrives
+      // well within 20ms of the previous reset, so the watchdog never fires.
+      const handle = bus.enqueue('test.task', { data: 1 }, { timeoutMs: 20 });
+      capturedTaskId = handle.taskId;
+      const assertion = expect(handle.result).resolves.toBe('slow-but-done');
+      await vi.advanceTimersByTimeAsync(45);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('ignores a stale PROGRESS/RESULT for a cancelled task after the MessagePort is reused', async () => {
+    // QNBS-v3: regression test for the taskId filter above — a released (not terminated) port
+    //          handed to a new task must not let the old task's late messages resolve/rearm it.
+    let messageHandler: ((event: MessageEvent) => void) | undefined;
     const mockPort = {
       addEventListener: vi.fn((type: string, handler: EventListener) => {
-        if (type === 'message') {
-          // Two PROGRESS pings inside the timeout window, then RESULT after the original
-          // deadline would have expired — only survives if PROGRESS re-arms the watchdog.
-          setTimeout(() => {
-            handler(
-              new MessageEvent('message', {
-                data: { kind: 'PROGRESS', taskId: 'mock-task-id', stage: 'step1', progress: 0.3 },
-              }),
-            );
-          }, 15);
-          setTimeout(() => {
-            handler(
-              new MessageEvent('message', {
-                data: { kind: 'PROGRESS', taskId: 'mock-task-id', stage: 'step2', progress: 0.6 },
-              }),
-            );
-          }, 30);
-          setTimeout(() => {
-            handler(
-              new MessageEvent('message', {
-                data: {
-                  kind: 'RESULT',
-                  taskId: 'mock-task-id',
-                  success: true,
-                  result: 'slow-but-done',
-                  latencyMs: 45,
-                },
-              }),
-            );
-          }, 45);
-        }
+        if (type === 'message') messageHandler = handler as (event: MessageEvent) => void;
       }),
       removeEventListener: vi.fn(),
       postMessage: vi.fn(),
@@ -708,7 +779,7 @@ describe('WorkerBus', () => {
     };
 
     const mockWorker = {
-      workerId: 'mock-worker-slow',
+      workerId: 'mock-worker-reused',
       worker: {} as Worker,
       channel: { port1: mockPort, port2: mockPort } as unknown as MessageChannel,
       port: mockPort as unknown as MessagePort,
@@ -721,10 +792,31 @@ describe('WorkerBus', () => {
     vi.spyOn(pool, 'acquire').mockResolvedValue(
       mockWorker as unknown as import('../src/workerPool').PooledWorkerInstance,
     );
+    vi.spyOn(pool, 'release').mockImplementation(() => {});
+
+    // Task A is cancelled (released, not terminated) — its port is reused for task B below.
+    const handleA = bus.enqueue('test.task', { data: 'A' }, { timeoutMs: 5_000 });
+    await new Promise((r) => setTimeout(r, 5));
+    const staleTaskId = handleA.taskId;
+    handleA.cancel('superseded');
+    await expect(handleA.result).rejects.toThrow('cancelled');
+
+    const handleB = bus.enqueue('test.task', { data: 'B' }, { timeoutMs: 5_000 });
+    await new Promise((r) => setTimeout(r, 5));
+
+    // Stale RESULT from task A arrives on the reused port while task B is in flight — must be ignored.
+    messageHandler?.(
+      new MessageEvent('message', {
+        data: { kind: 'RESULT', taskId: staleTaskId, success: true, result: 'stale-A-result' },
+      }),
+    );
+
+    messageHandler?.(
+      new MessageEvent('message', {
+        data: { kind: 'RESULT', taskId: handleB.taskId, success: true, result: 'real-B-result' },
+      }),
+    );
 
-    // timeoutMs (20ms) is shorter than the total run (45ms), but each PROGRESS arrives
-    // well within 20ms of the previous reset, so the watchdog never fires.
-    const handle = bus.enqueue('test.task', { data: 1 }, { timeoutMs: 20 });
-    await expect(handle.result).resolves.toBe('slow-but-done');
+    await expect(handleB.result).resolves.toBe('real-B-result');
   });
 });
diff --git a/packages/worker-bus/tests/workerPool.test.ts b/packages/worker-bus/tests/workerPool.test.ts
index 89488174c..1762cc3ae 100644
--- a/packages/worker-bus/tests/workerPool.test.ts
+++ b/packages/worker-bus/tests/workerPool.test.ts
@@ -228,6 +228,7 @@ describe('WorkerPool', () => {
   });
 
   it('terminateWorker is a no-op for an unknown workerId', async () => {
+    // QNBS-v3: guards against a race where the caller holds a stale workerId (already replaced by a prior restart).
     const pool = new WorkerPool('test-pool', ['inference.text'], {
       maxWorkers: 1,
       minWorkers: 1,
diff --git a/services/ai/localAiDeviceProfiler.ts b/services/ai/localAiDeviceProfiler.ts
index 35ef2aa63..0ee9c2060 100644
--- a/services/ai/localAiDeviceProfiler.ts
+++ b/services/ai/localAiDeviceProfiler.ts
@@ -172,9 +172,7 @@ function detectDirectML(
 // Memory Tier
 // ---------------------------------------------------------------------------
 
-// QNBS-v3: exported (previously module-private) so callers that only need a fast, synchronous
-//          memory-tier read — e.g. workerBusManager sizing the inference pool at init — don't
-//          have to pay for the full async generateDeviceProfile() (WebGPU/WebNN/battery probes).
+// QNBS-v3: exported (was private) so callers needing a fast sync memory-tier read (pool sizing) skip the async generateDeviceProfile() probes.
 export function detectMemoryTier(): DeviceCapabilityProfile['memoryTier'] {
   const deviceMemory =
     typeof navigator !== 'undefined' && 'deviceMemory' in navigator
diff --git a/services/workerBusManager.ts b/services/workerBusManager.ts
index ad58ca875..88d5015d1 100644
--- a/services/workerBusManager.ts
+++ b/services/workerBusManager.ts
@@ -72,9 +72,7 @@ async function inferencePoolOptions() {
   const { MAX_WORKERS_INFERENCE, MIN_WORKERS, WORKER_IDLE_TIMEOUT_MS } = await import(
     '@domain/worker-bus'
   );
-  // QNBS-v3: [P1 — scale inference worker count to the device's memory tier instead of a fixed
-  //          cap. Each replica loads its own transformers.js pipeline (no cross-replica cache
-  //          sharing), so more replicas only help on devices with RAM headroom to spare.]
+  // QNBS-v3: scale worker count to memory tier — each replica loads its own pipeline, no shared cache.
   const maxWorkers = Math.min(await resolveInferenceMaxWorkers(), MAX_WORKERS_INFERENCE);
   return {
     maxWorkers,
@@ -86,11 +84,7 @@ async function inferencePoolOptions() {
   };
 }
 
-/**
- * QNBS-v3: memory-tier-driven worker count — high:3, medium:2 (previous hardcoded default),
- * low:1. Falls back to the previous default (2) if device profiling throws (e.g. non-browser
- * test environment) so this can never block or fail pool initialization.
- */
+// QNBS-v3: high:3, medium:2 (prior default), low:1; falls back to 2 if profiling throws so init never blocks.
 async function resolveInferenceMaxWorkers(): Promise<number> {
   try {
     const { detectMemoryTier } = await import('./ai/localAiDeviceProfiler');
diff --git a/tests/unit/workerBusManager.test.ts b/tests/unit/workerBusManager.test.ts
index 3f15aed2b..8e323a460 100644
--- a/tests/unit/workerBusManager.test.ts
+++ b/tests/unit/workerBusManager.test.ts
@@ -297,11 +297,7 @@ describe('workerBusManager', () => {
   });
 
   describe('inference pool sizing by memory tier', () => {
-    // QNBS-v3: [P1 — inference pool maxWorkers is now derived from
-    //          localAiDeviceProfiler.detectMemoryTier() instead of a hardcoded 2. Verified via
-    //          the same re-registration path as the "memory-safety cap" test above, since
-    //          initWorkerBus() only calls registry.register() (mocked, no-op) — bus.registerPool()
-    //          with the real computed options is only exercised by ensureInferencePool().]
+    // QNBS-v3: verified via ensureInferencePool()'s re-registration path — initWorkerBus() only calls the mocked registry.register(), not bus.registerPool().
     afterEach(() => {
       vi.doUnmock('../../services/ai/localAiDeviceProfiler');
     });

From 95cf9ac001b27c14391f81224a04d5016c4cc03b Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 03:49:45 +0200
Subject: [PATCH 05/12] fix(worker-bus): hoist runOnPool closures to eliminate
 forward-reference lint findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- workerBus.ts: convert settle/armTimeout/onTimeout/handler from let-forward-declared
  arrow functions to plain function declarations. Function declarations hoist fully
  (name + body), so the mutual recursion between settle<->handler no longer needs a
  forward let reference — this resolves DeepSource's 'used before defined' (major) and
  'prefer const' findings on handler/onTimeout without changing behavior
- capture this.progress as progressEmitter before the Promise executor so handler (now a
  plain function, no lexical ) still reaches the emitter correctly
- workerPool.ts: expand the port1.start() comment to make explicit that this single
  early call (before any task traffic) covers every later
  port.addEventListener('message', ...) in workerBus.ts::runOnPool for the port's full
  lifetime, addressing Copilot's 'MessagePort never started' finding (the fix already
  existed here, just not visible from the workerBus.ts diff)

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 packages/worker-bus/src/workerBus.ts  | 34 ++++++++++++++-------------
 packages/worker-bus/src/workerPool.ts |  5 ++++
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index 6ed27b05b..bba60977c 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -272,31 +272,33 @@ export class WorkerBus {
         createTaskMessage(task.taskId, task.taskType, task.payload, task.traceId, task.timeoutMs),
       );
 
+      // QNBS-v3: captured so the message handler below can be a plain hoisted `function`
+      //          (not an arrow bound to `this`) without losing access to the emitter.
+      const progressEmitter = this.progress;
+
       const result = await new Promise<TaskResult<TResult>>((resolve, _reject) => {
         let settled = false;
         let timeoutTimer: ReturnType<typeof setTimeout>;
-        // QNBS-v3: `handler`/`onTimeout` are forward-declared via `let` (hoisted, no TDZ read)
-        //          because `settle`/`armTimeout` close over them before their real definitions
-        //          run — the three closures are mutually recursive, so a strict top-to-bottom
-        //          `const` chain isn't possible without one forward reference.
-        let handler: (event: MessageEvent) => void;
-        let onTimeout: () => void;
-
-        const settle = () => {
+
+        // QNBS-v3: `settle`/`armTimeout`/`onTimeout`/`handler` are mutually recursive
+        //          (settle reads `handler`, `handler` calls `settle`/`armTimeout`) — plain
+        //          `function` declarations hoist fully (name + body), so each can reference
+        //          the others regardless of source order, with no TDZ and no `let` needed.
+        function settle() {
           settled = true;
           clearTimeout(timeoutTimer);
           port.removeEventListener('message', handler);
-        };
+        }
 
         // QNBS-v3: watchdog, not a hard ceiling — re-armed on every PROGRESS message so
         //          long-running jobs (ProForge stages, LoRA training) that report progress
         //          aren't falsely killed while genuinely wedged workers still get caught.
-        const armTimeout = () => {
+        function armTimeout() {
           clearTimeout(timeoutTimer);
           timeoutTimer = setTimeout(onTimeout, task.timeoutMs);
-        };
+        }
 
-        onTimeout = () => {
+        function onTimeout() {
           if (settled) return;
           settle();
           timedOut = true;
@@ -314,9 +316,9 @@ export class WorkerBus {
             workerId: worker.workerId,
             layer: 'web',
           });
-        };
+        }
 
-        handler = (event: MessageEvent) => {
+        function handler(event: MessageEvent) {
           if (settled) return;
           const msg = validateWorkerMessage(event.data);
           if (!msg) return;
@@ -326,7 +328,7 @@ export class WorkerBus {
 
           if (msg.kind === 'PROGRESS') {
             armTimeout();
-            this.progress.emit(task.taskId, {
+            progressEmitter.emit(task.taskId, {
               taskId: task.taskId,
               taskType: task.taskType,
               stage: msg.stage,
@@ -355,7 +357,7 @@ export class WorkerBus {
               layer: 'web',
             });
           }
-        };
+        }
         port.addEventListener('message', handler);
         armTimeout();
 
diff --git a/packages/worker-bus/src/workerPool.ts b/packages/worker-bus/src/workerPool.ts
index 126d51265..49bec2955 100644
--- a/packages/worker-bus/src/workerPool.ts
+++ b/packages/worker-bus/src/workerPool.ts
@@ -127,6 +127,11 @@ export class WorkerPool {
     };
 
     // QNBS-v3: addEventListener (unlike onmessage) never dispatches until start() is called.
+    //          Enabling here — once, before any task traffic — covers every later
+    //          `port.addEventListener('message', ...)` in workerBus.ts::runOnPool for the
+    //          lifetime of this port (including across task reuse): per the WHATWG spec,
+    //          start() only flips the port's [[Enabled]] flag, it doesn't need to be
+    //          re-called once a listener is attached or for subsequent tasks on the port.
     channel.port1.start();
     // QNBS-v3: Transfer port2 to worker for dedicated bidirectional channel
     worker.postMessage({ kind: 'INIT_PORT', port: channel.port2 }, [channel.port2]);

From 8561d53a97483589723577e99dc3b77ca7656d87 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 03:53:28 +0200
Subject: [PATCH 06/12] docs: correct stale agent-model attribution in
 commit-message convention

The DeepSource/CodeAnt review-loop runbooks and session-handoff doc referenced a
hardcoded 'Claude Opus 4.8 <noreply@anthropic.com>' co-author trailer; this
repo's Copilot Chat sessions run on Claude Sonnet 5 via GitHub Copilot, not a
direct Anthropic API client, so the example now points at the actual agent.
---
 docs/CODEANT-REVIEW-LOOP.md              | 4 ++--
 docs/DEEPSOURCE-REVIEW-LOOP.md           | 3 ++-
 docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md | 3 ++-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/CODEANT-REVIEW-LOOP.md b/docs/CODEANT-REVIEW-LOOP.md
index ab386c0d8..c6e660e88 100644
--- a/docs/CODEANT-REVIEW-LOOP.md
+++ b/docs/CODEANT-REVIEW-LOOP.md
@@ -167,10 +167,10 @@ git commit -m "refactor(scope): address CodeAnt wave N review feedback"
 git push origin <feature-branch>
 ```
 
-End commit messages with:
+End commit messages with the attribution matching whichever agent/model actually made the change, e.g.:
 
 ```
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
 ```
 
 ## 6. Reply to every thread, then resolve it → 0 unresolved
diff --git a/docs/DEEPSOURCE-REVIEW-LOOP.md b/docs/DEEPSOURCE-REVIEW-LOOP.md
index 9a3d12aaf..b038db700 100644
--- a/docs/DEEPSOURCE-REVIEW-LOOP.md
+++ b/docs/DEEPSOURCE-REVIEW-LOOP.md
@@ -215,7 +215,8 @@ git commit -m "refactor(scope): address DeepSource wave N (<issue codes>)"
 git push origin <feature-branch>
 ```
 
-End commit messages with `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
+End commit messages with the attribution matching whichever agent/model actually made the change, e.g.
+`Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>`.
 **No manual re-trigger** — DeepSource analyses the new head SHA on its own. Wait for the fresh run,
 then go back to §3.
 
diff --git a/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md b/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
index ed45010d9..8da1ead00 100644
--- a/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
+++ b/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
@@ -158,5 +158,6 @@ Flow-Mode fullscreen + docs). Each = one PR off main, CodeAnt deferred.
 ## Environment reminders
 - **ONE Bash call per turn** (low-end hardware ~3.7 GB RAM); no concurrent heavy shells. A full local
   coverage run ≈ 1 hour — prefer single-file runs for diagnosis.
-- Co-Author commits with `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
+- Co-Author commits with the attribution matching whichever agent/model actually made the change, e.g.
+  `Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>`.
 - Never lower coverage thresholds or `it.skip` to go green — fix the root cause.

From 2399e9963882c0301768385de30410dd8bd3319a Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 04:02:06 +0200
Subject: [PATCH 07/12] refactor(worker-bus): extract settleWithResult to
 reduce handler() complexity

DeepSource flagged handler() at cyclomatic complexity 6, then 7 as review
iterations progressed (the RESULT branch's error ternary was the extra path).
Extracting settleWithResult(msg) as its own named function removes that
branch and its ternary from handler(), leaving handler() with a flat
guard-clause + kind dispatch shape only.
---
 packages/worker-bus/src/workerBus.ts | 44 ++++++++++++++++------------
 1 file changed, 25 insertions(+), 19 deletions(-)

diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index bba60977c..b8a4b5697 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -7,6 +7,7 @@ import { CircuitBreaker } from './circuitBreaker';
 import { DeadLetterQueue } from './deadLetterQueue';
 import { createCancelMessage, createTaskMessage, validateWorkerMessage } from './messageBus';
 import { ProgressEmitter } from './progressEmitter';
+import type { WorkerMessage } from './schemas';
 import { PriorityTaskQueue } from './taskQueue';
 import type {
   BusEvent,
@@ -318,6 +319,29 @@ export class WorkerBus {
           });
         }
 
+        // QNBS-v3: split out of handler() to keep its cyclomatic complexity down — this is
+        //          the only branch with an inner conditional (the error ternary).
+        function settleWithResult(msg: Extract<WorkerMessage, { kind: 'RESULT' }>) {
+          settle();
+          resolve({
+            taskId: task.taskId,
+            success: msg.success,
+            result: msg.result as TResult,
+            error: msg.error
+              ? {
+                  code: msg.error.code,
+                  message: msg.error.message,
+                  recoverable: true,
+                  retryCount: 0,
+                }
+              : undefined,
+            latencyMs: Math.round(performance.now() - startedAt),
+            queueTimeMs,
+            workerId: worker.workerId,
+            layer: 'web',
+          });
+        }
+
         function handler(event: MessageEvent) {
           if (settled) return;
           const msg = validateWorkerMessage(event.data);
@@ -337,25 +361,7 @@ export class WorkerBus {
               timestamp: Date.now(),
             });
           } else if (msg.kind === 'RESULT') {
-            settle();
-            const latencyMs = Math.round(performance.now() - startedAt);
-            resolve({
-              taskId: task.taskId,
-              success: msg.success,
-              result: msg.result as TResult,
-              error: msg.error
-                ? {
-                    code: msg.error.code,
-                    message: msg.error.message,
-                    recoverable: true,
-                    retryCount: 0,
-                  }
-                : undefined,
-              latencyMs,
-              queueTimeMs,
-              workerId: worker.workerId,
-              layer: 'web',
-            });
+            settleWithResult(msg);
           }
         }
         port.addEventListener('message', handler);

From 557b3926a12bb799947ea56e8714cc6b199559c6 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 04:06:08 +0200
Subject: [PATCH 08/12] docs: fix pre-rebrand drift and curate correction-loop
 doc set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- .cursorrules: this-repo context section still said 'StoryCraft-Studio' /
  '5-Locale-i18n' (pre-#165 rebrand leftover); corrected to WorldScript-Studio,
  19 locales, current multi-provider AI stack, and pointed the iron-rule
  paragraph at the DeepSource loop too (previously CodeAnt-only).
- KIMI-INSTRUCT.md: corrected stale '11 Locales' to 19, added an explicit
  pointer to the two canonical runbooks (CODEANT-REVIEW-LOOP.md,
  DEEPSOURCE-REVIEW-LOOP.md) so this file's summary can't silently drift from
  them again, and added an attribution line for Kimi-authored commits.
- docs/DEEPSOURCE-REMEDIATION-PLAN.md: logged the JS-0067 finding from PR #305
  (global-scope function declarations) in both the P3 inventory and the
  config-decision log, cross-referencing DEEPSOURCE-REVIEW-LOOP.md §11.
- README.md: Documentation Hub was missing a row for the canonical
  CODEANT-REVIEW-LOOP.md (its DeepSource counterpart was already listed).
---
 .cursorrules                        | 6 +++---
 KIMI-INSTRUCT.md                    | 8 +++++++-
 README.md                           | 1 +
 docs/DEEPSOURCE-REMEDIATION-PLAN.md | 2 ++
 4 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/.cursorrules b/.cursorrules
index 1909e671e..6714e1436 100644
--- a/.cursorrules
+++ b/.cursorrules
@@ -21,9 +21,9 @@ Analysiere **jede Datei, jedes Feature und jedes Repo individuell und ganzheitli
 
 ---
 
-## StoryCraft-Studio (dieses Repo) — Kurzkontext
+## WorldScript-Studio (dieses Repo, ehem. StoryCraft-Studio) — Kurzkontext
 
-Offline-first, **Privacy**, Redux Toolkit + IndexedDB + Zustand (transient UI), Hybrid-KI (Gemini, Vercel AI SDK, Ollama/WebLLM), pnpm-Workspace (`packages/*`), PWA, 5-Locale-i18n. Fokus: **Erzählung**, Schreibflow, KI als Co-Pilot — nicht als Ghostwriter. Vollständiger Stack und Regelkatalog: **`.cursor/index.mdc`**.
+Offline-first, **Privacy**, Redux Toolkit + IndexedDB + Zustand (transient UI), Multi-Provider-KI (Gemini, Vercel AI SDK, OpenAI/Claude/Grok/OpenRouter, Ollama/WebLLM/ONNX/Transformers.js), pnpm-Workspace (`packages/*`), PWA + Tauri 2, 19-Locale-i18n. Fokus: **Erzählung**, Schreibflow, KI als Co-Pilot — nicht als Ghostwriter. Vollständiger Stack und Regelkatalog: **`.cursor/index.mdc`**.
 
 ---
 
@@ -46,7 +46,7 @@ Inhalt des Kommentars: **warum** die Änderung, **was** sie verbessert, optional
 
 Bei jeder offenen PR **alle** Inline-Review-Kommentare (CodeRabbit + jeder andere Bot/Mensch) **proaktiv, ungefragt** abarbeiten. Pro Finding: gegen den **aktuellen** Code validieren (Anker oft veraltet), dann **Root-Cause-Fix** vollständig umsetzen (Code **+ Tests + i18n + Doku**) oder mit Begründung als False-Positive ablehnen. Jeden Thread mit Commit-Referenz beantworten, **resolven**, **0 unresolved** hinterlassen, committen + pushen.
 
-**Iron Rule — Loop bis Ruhe:** Nach jedem Push **Review erneut triggern** (`gh pr comment <N> --body "@coderabbitai review"`) und die komplette Review-Historie prüfen, nicht nur den letzten Status (ein „rate limited"-Status kann eine frühere echte Review verdecken); eine frische Review bringt regelmäßig **neue** Findings (eine „Welle"). Zyklus wiederholen, bis **BEIDES** gilt: frische Review = **0 neue Kommentare** UND **0 offene Threads**. Niemals aufhören, solange noch Kommentare kommen. **Niemals ein neues `biome-ignore`/Suppression** einbauen, um ein Finding stummzuschalten — der Suppression-Ratchet-Gate lässt die CI scheitern; stattdessen sauber refaktorieren. CodeAnt AI erscheint nur als 5 CI-Status-Checks (Quality Gates/SAST/SCA/SCR/Test Coverage) zur Grün-Prüfung, kein Kommentar-Thread — dort nicht erneut triggern in Erwartung eines Kommentars. Vollständige Prozedur: **`docs/CODEANT-REVIEW-LOOP.md`**.
+**Iron Rule — Loop bis Ruhe:** Nach jedem Push **Review erneut triggern** (`gh pr comment <N> --body "@coderabbitai review"`) und die komplette Review-Historie prüfen, nicht nur den letzten Status (ein „rate limited"-Status kann eine frühere echte Review verdecken); eine frische Review bringt regelmäßig **neue** Findings (eine „Welle"). Zyklus wiederholen, bis **BEIDES** gilt: frische Review = **0 neue Kommentare** UND **0 offene Threads**. Niemals aufhören, solange noch Kommentare kommen. **Niemals ein neues `biome-ignore`/Suppression** einbauen, um ein Finding stummzuschalten — der Suppression-Ratchet-Gate lässt die CI scheitern; stattdessen sauber refaktorieren. CodeAnt AI erscheint nur als 5 CI-Status-Checks (Quality Gates/SAST/SCA/SCR/Test Coverage) zur Grün-Prüfung, kein Kommentar-Thread — dort nicht erneut triggern in Erwartung eines Kommentars. Vollständige Prozedur (inkl. des komplementären, token-freien DeepSource-Loops): **`docs/CODEANT-REVIEW-LOOP.md`** + **`docs/DEEPSOURCE-REVIEW-LOOP.md`**.
 
 ---
 
diff --git a/KIMI-INSTRUCT.md b/KIMI-INSTRUCT.md
index 04a2abe4e..917839b39 100644
--- a/KIMI-INSTRUCT.md
+++ b/KIMI-INSTRUCT.md
@@ -40,6 +40,11 @@ Dieses Projekt läuft auf Low-End-Hardware. Beachte strikt:
 
 Dieser Workflow ist die Standardvorgehensweise, wenn der Nutzer um Behebung von CodeAnt-Kommentaren bittet.
 
+> **Kanonische Quelle:** Die vollständige, agenten-unabhängige Prozedur (inkl. GraphQL-Snippets, PR-Split
+> bei >100 Dateien, Merge-Regeln) lebt in **`docs/CODEANT-REVIEW-LOOP.md`**; der komplementäre,
+> token-freie statische-Analyse-Loop in **`docs/DEEPSOURCE-REVIEW-LOOP.md`**. Der Abschnitt unten ist
+> eine Kimi-spezifische Kurzfassung — bei Abweichungen gelten die beiden kanonischen Dateien.
+
 > **In der Praxis (Beobachtung 2026-07-30):** Der Bot, der tatsächlich Inline-Kommentare postet, ist
 > **CodeRabbit** (`@coderabbitai review` zum erneuten Triggern) — nicht CodeAnt AI. CodeAnt AI
 > erscheint als 5 CI-Status-Checks (`CodeAnt - Quality Gates/SAST/SCA/SCR/Test Coverage`), die auf
@@ -102,7 +107,8 @@ pnpm exec vitest run <betroffene-testdateien>
 
 - Lint/Format-Fehler vor dem Commit beheben (`biome check --write ...`).
 - TypeScript-Fehler sofort beheben.
-- i18n-Keys bei neuem UI-Text zu **allen 11 Locales** hinzufügen und Bundles neu bauen.
+- i18n-Keys bei neuem UI-Text zu **allen 19 Locales** hinzufügen (`node scripts/check-i18n-keys.mjs --fix`) und Bundles neu bauen (`pnpm run i18n:bundle`).
+- Commit-Nachrichten mit der Zuordnung des tatsächlich arbeitenden Agenten/Modells abschließen, z. B. `Co-Authored-By: Kimi K2 <noreply@moonshot.ai>` — niemals eine generische oder falsche Modellangabe übernehmen.
 
 ### 3.4 Commit & Push
 
diff --git a/README.md b/README.md
index 8ea328751..acc4c40da 100644
--- a/README.md
+++ b/README.md
@@ -767,6 +767,7 @@ See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for the full dev setup, Biome / Vit
 | [`AUDIT.md`](AUDIT.md) | Security & quality audit trail + scorecard |
 | [`docs/AUDIT-PERFECTION-PLAN-v1.23.md`](docs/AUDIT-PERFECTION-PLAN-v1.23.md) | Living master plan for the v1.23 audit/perfection engagement (phase status + batch log) |
 | [`docs/CI.md`](docs/CI.md) | GitHub Actions jobs, Node/pnpm parity, Act examples |
+| [`docs/CODEANT-REVIEW-LOOP.md`](docs/CODEANT-REVIEW-LOOP.md) | Canonical, agent-agnostic PR review correction loop (CodeRabbit/CodeAnt/any bot) — GraphQL fetch/reply/resolve, PR-size split, merge rules |
 | [`docs/DEEPSOURCE-REVIEW-LOOP.md`](docs/DEEPSOURCE-REVIEW-LOOP.md) | DeepSource static-analysis correction loop (living runbook; complements the CodeAnt loop) |
 | [`docs/DEEPSOURCE-REMEDIATION-PLAN.md`](docs/DEEPSOURCE-REMEDIATION-PLAN.md) | Prioritised DeepSource backlog tracker (P0-security→P5-docs) with triage decisions |
 | [`docs/adr/`](docs/adr/README.md) | Architecture Decision Records — state-management boundaries, local-AI stack layering, WorkerBus v2 hybrid routing |
diff --git a/docs/DEEPSOURCE-REMEDIATION-PLAN.md b/docs/DEEPSOURCE-REMEDIATION-PLAN.md
index 6369d1279..2305faf09 100644
--- a/docs/DEEPSOURCE-REMEDIATION-PLAN.md
+++ b/docs/DEEPSOURCE-REMEDIATION-PLAN.md
@@ -88,6 +88,7 @@ Fix in this order — highest user/security impact first; cosmetic last. Within
 |---|---|---|---|---|---|---|
 | **JS-0323** | Detected usage of `any` (Critical) | 34 / 20 files | **100% test files** (browser-API mocks: MediaRecorder/AudioContext …), all already `biome-ignore noExplicitAny`'d; **0 production** | **rule-ignore, test scope** — redundant with Biome `noExplicitAny` + the suppression ratchet (baseline 52). Do NOT add 34 inline `skipcq`. Long-term: opportunistic typed-mock cleanup (§4c). | maintainer-click (rule-ignore) | — |
 | **JS-0415** | JSX tree too deeply nested (5–6 levels) | 2 | `components/HelpView.tsx` | pre-existing structural; genuine refactor candidate (extract sub-components to cut nesting). Minor severity → schedule as a low-priority hygiene PR; **not** a false positive. | todo (future refactor) | — |
+| **JS-0067** | Unexpected function declaration in the global scope | 2+ (repo-wide pattern) | `services/ai/localAiDeviceProfiler.ts`, `services/workerBusManager.ts` (representative — every top-level `services/*.ts` function hits this) | **rule-ignore, repo-wide** — idiomatic top-level ES-module functions, not `<script>`-tag globals; fixing per-occurrence would touch dozens of pre-existing files for no behavioral gain. | todo (maintainer dashboard click) | #305 |
 
 ### P4 — Hygiene / Style
 | Issue code | Title | Occ. | Files / modules | Decision | Status | PR |
@@ -148,6 +149,7 @@ config level (`.deepsource.toml`) instead of scattering inline `skipcq`. Log eac
 |---|---|---|---|
 | **JS-0323** (`any`) | dashboard rule-ignore, **test-file scope** | 34 occ all in test mocks, already governed by Biome `noExplicitAny` + the suppression ratchet (baseline 52); double-suppressing is noise. 0 production `any`. Long-term cleanup → §4c. | 2026-06-24 |
 | **JS-0440** (`dangerouslySetInnerHTML`) | dashboard "Ignore" (single occurrence) | reviewed-safe — `__html` is DOMPurify-sanitized (repo policy). In-code skipcq can't attach to a JSX attribute (§4b). | 2026-06-24 |
+| **JS-0067** ("unexpected function declaration in the global scope") | recommend dashboard rule-ignore (not yet actioned — maintainer click) | flagged on PR #305 for ordinary top-level `function`/`async function` declarations in `services/ai/localAiDeviceProfiler.ts` + `services/workerBusManager.ts` — idiomatic Biome-approved ES-module code, not `<script>`-tag global pollution; repo-wide pattern, not a per-file fix. Informational-only check (not in required-status list). See `DEEPSOURCE-REVIEW-LOOP.md` §11, 2026-08-01 entry. | 2026-08-01 |
 
 ## 6. Definition of done
 

From f552a3205079e76d127f33281965a9541260016a Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 04:16:18 +0200
Subject: [PATCH 09/12] refactor(workerBus): extract parseRelevantMessage to
 reduce handler complexity; docs: MD040 fence language tags

- packages/worker-bus/src/workerBus.ts: split handler()'s three early-return
  guards (settled/invalid/stale-taskId) into parseRelevantMessage(), leaving
  handler() as a pure kind-dispatch (PROGRESS/RESULT). Addresses DeepSource
  cyclomatic-complexity=6 finding on PR #305 without merging conditions into
  an opaque boolean expression.
- docs/CODEANT-REVIEW-LOOP.md, docs/DEEPSOURCE-REVIEW-LOOP.md,
  docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md: add 'text' language identifier to
  all remaining unlabeled fenced code blocks (ASCII diagrams + raw
  error/log output) to satisfy markdownlint MD040, per CodeRabbit finding on
  docs/CODEANT-REVIEW-LOOP.md:172 plus proactive fix of the same pattern
  elsewhere in the same doc set.

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 docs/CODEANT-REVIEW-LOOP.md              |  4 ++--
 docs/DEEPSOURCE-REVIEW-LOOP.md           |  2 +-
 docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md |  4 ++--
 packages/worker-bus/src/workerBus.ts     | 16 ++++++++++++----
 4 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/docs/CODEANT-REVIEW-LOOP.md b/docs/CODEANT-REVIEW-LOOP.md
index c6e660e88..299c45a6d 100644
--- a/docs/CODEANT-REVIEW-LOOP.md
+++ b/docs/CODEANT-REVIEW-LOOP.md
@@ -38,7 +38,7 @@ Each wave is handled exactly like the first.
 > Until both are true, **keep iterating**. Never declare the PR done while new comments are still
 > arriving or any thread is open.
 
-```
+```text
         ┌─────────────────────────────────────────────┐
         │ 1. Fetch unresolved threads (GraphQL)        │
         │ 2. Validate each against CURRENT code        │
@@ -169,7 +169,7 @@ git push origin <feature-branch>
 
 End commit messages with the attribution matching whichever agent/model actually made the change, e.g.:
 
-```
+```text
 Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
 ```
 
diff --git a/docs/DEEPSOURCE-REVIEW-LOOP.md b/docs/DEEPSOURCE-REVIEW-LOOP.md
index b038db700..6fd0078ff 100644
--- a/docs/DEEPSOURCE-REVIEW-LOOP.md
+++ b/docs/DEEPSOURCE-REVIEW-LOOP.md
@@ -60,7 +60,7 @@ List + resolve via the GraphQL snippet in §3a.
 A push that fixes findings triggers a **fresh** DeepSource run, which can surface **new** findings
 caused by the fix (a "wave"). Handle each wave like the first.
 
-```
+```text
         ┌─────────────────────────────────────────────┐
         │ 1. Fetch DeepSource findings (check-runs +   │
         │    annotations) for the PR head SHA          │
diff --git a/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md b/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
index 8da1ead00..a3359201b 100644
--- a/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
+++ b/docs/SESSION-HANDOFF-MAIN-CI-COVERAGE.md
@@ -25,7 +25,7 @@ The diagnostic narrative below is retained for the record.
 **Symptom:** On `main`, the **`CI / CD` → `🔍 Quality Gate`** job (both Node 22 and Node 24) fails on the
 **coverage threshold**:
 
-```
+```text
 ERROR: Coverage for lines (5.16%) does not meet global threshold (74%)
 ERROR: Coverage for functions (4.91%) ... (67%)
 ERROR: Coverage for statements (5.02%) ... (72%)
@@ -113,7 +113,7 @@ the coverage-threshold path (i.e. not as a hard test failure). Candidates, in pr
 **⚠️ BLOCKER on #180 — real typecheck failure (must fix before commit):**
 `pnpm run typecheck` fails with **3× TS2352** at `features/proForge/machine/proForgeMachine.ts` lines
 **68, 71, 75** (the pre-existing `setPreSnapshot`/`setResult`/`setDecision` actions):
-```
+```text
 Conversion of type 'ProForgeMachineEvent' to type '{ output: ... }' may be a mistake ...
 Property 'output' is missing in type '{ type: "ABORT"; }' ...
 ```
diff --git a/packages/worker-bus/src/workerBus.ts b/packages/worker-bus/src/workerBus.ts
index b8a4b5697..662809b7c 100644
--- a/packages/worker-bus/src/workerBus.ts
+++ b/packages/worker-bus/src/workerBus.ts
@@ -342,13 +342,21 @@ export class WorkerBus {
           });
         }
 
-        function handler(event: MessageEvent) {
-          if (settled) return;
+        // QNBS-v3: split out of handler() — isolates the "is this message ours to act on"
+        //          guard from the "what do we do with it" dispatch, each staying low-complexity.
+        function parseRelevantMessage(event: MessageEvent): WorkerMessage | null {
+          if (settled) return null;
           const msg = validateWorkerMessage(event.data);
-          if (!msg) return;
+          if (!msg) return null;
           // QNBS-v3: a released+reused port can still deliver a stale PROGRESS/RESULT from a
           //          cancelled prior task — ignore anything not addressed to this task.
-          if (msg.taskId !== task.taskId) return;
+          if (msg.taskId !== task.taskId) return null;
+          return msg;
+        }
+
+        function handler(event: MessageEvent) {
+          const msg = parseRelevantMessage(event);
+          if (!msg) return;
 
           if (msg.kind === 'PROGRESS') {
             armTimeout();

From aee8d207d44cc331db5f2097c1a54380d0d0abfd Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 06:35:58 +0200
Subject: [PATCH 10/12] fix(worker-bus): hoist waitForIdle closures to
 eliminate used-before-defined finding

packages/worker-bus/src/workerPool.ts: convert check/cleanup/onAbort in waitForIdle()
from const arrow functions to plain hoisted function declarations, mirroring the same
fix already applied to runOnPool() in workerBus.ts. Resolves DeepSource's Major
'cleanup'/'onAbort' used-before-defined findings blocking the JavaScript analysis gate
on PR #305. this is captured as a local 'pool' const since function declarations don't
have their own lexical this.

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 packages/worker-bus/src/workerPool.ts | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/packages/worker-bus/src/workerPool.ts b/packages/worker-bus/src/workerPool.ts
index 49bec2955..5808aefd8 100644
--- a/packages/worker-bus/src/workerPool.ts
+++ b/packages/worker-bus/src/workerPool.ts
@@ -230,30 +230,37 @@ export class WorkerPool {
   }
 
   private waitForIdle(signal?: AbortSignal): Promise<PooledWorkerInstance> {
+    // QNBS-v3: captured so the hoisted `function` declarations below (which don't have
+    //          their own lexical `this`) can still reach the pool instance.
+    const pool = this;
     return new Promise((resolve, reject) => {
-      const check = () => {
-        const idle = this.entries.find((e) => e.instance.state === 'idle');
+      // QNBS-v3: `check`/`cleanup`/`onAbort` are mutually recursive (check calls cleanup,
+      //          onAbort calls cleanup) — plain `function` declarations hoist fully (name +
+      //          body), so each can reference the others regardless of source order, with no
+      //          TDZ and no `const` "used before defined" antipattern.
+      function check() {
+        const idle = pool.entries.find((e) => e.instance.state === 'idle');
         if (idle) {
           cleanup();
-          this.setBusy(idle.instance.workerId);
+          pool.setBusy(idle.instance.workerId);
           resolve(idle.instance);
           return;
         }
-        if (this.shutdownFlag) {
+        if (pool.shutdownFlag) {
           cleanup();
           reject(new Error('Pool is shutting down'));
           return;
         }
         requestAnimationFrame(check);
-      };
+      }
 
-      const cleanup = () => {
+      function cleanup() {
         signal?.removeEventListener('abort', onAbort);
-      };
-      const onAbort = () => {
+      }
+      function onAbort() {
         cleanup();
         reject(new Error('Aborted'));
-      };
+      }
 
       signal?.addEventListener('abort', onAbort);
       check();

From 6003f56308047fe8c18c8c556c9cc8bfc8892b13 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 06:58:57 +0200
Subject: [PATCH 11/12] fix(worker-bus): avoid this-aliasing antipattern in
 waitForIdle

packages/worker-bus/src/workerPool.ts: keep cleanup/onAbort as plain hoisted
function declarations (neither touches pool state, so no this needed), and
revert check to a lexical-this arrow function instead of aliasing this to a
local const. Resolves DeepSource's Major 'Unexpected aliasing of this to
local variable' finding introduced by the prior fix.

docs: fix README locale-inventory drift (CodeRabbit)

README.md: the i18n table row was missing ru and ko from the 19-locale list,
and the Contributing section said 'Five locale trees' without qualifying that
only the five production locales (de/en/es/fr/it) want native-speaker polish.

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 README.md                             |  4 +--
 packages/worker-bus/src/workerPool.ts | 39 +++++++++++++--------------
 2 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index acc4c40da..8d445d0a4 100644
--- a/README.md
+++ b/README.md
@@ -505,7 +505,7 @@ The Settings → AI panel shows a live GPU status badge with adapter details and
 | **PDF Export**       | jsPDF                                                     | Client-side, configurable PDF document generation                    |
 | **Document Export**  | docx + jszip                                              | Word-compatible `.docx` generation (lazy-loaded)                     |
 | **PWA**              | Service Worker + Web App Manifest v3                     | Offline support, installability, Workbox chunking                    |
-| **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2861 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu Beta); EN fallback; `localStorage` persistence |
+| **i18n**             | Custom React Context (`I18nContext.tsx`)                  | 2861 keys × 19 locales (de/en/es/fr/it + ar/he/fa RTL Beta + ja/zh/pt/el/fi/sv/hu/is/eu/ru/ko Beta); EN fallback; `localStorage` persistence |
 | **Testing**          | Vitest 4.x (6477+ tests / 532 files) + Playwright E2E     | Unit/integration + cross-browser E2E; Stryker mutation (manual workflow)          |
 | **Code Quality**     | Biome (lint + format) + TypeScript 7 (tsgo) strict       | `--error-on-warnings` in CI; zero `any` policy                      |
 | **Visualization**    | Force-directed graph                                      | Interactive character relationship network                           |
@@ -748,7 +748,7 @@ Shared Playwright helpers (`waitForSpaReady`, `ensureBlankProject`, `clickNavIte
 
 - **🐛 Report Bugs** — Open a GitHub Issue with details and reproduction steps
 - **💡 Suggest Features** — Open a Discussion or Issue
-- **🌍 Improve Translations** — Five locale trees (`en` is the reference); native polish for FR/ES/IT especially welcome in PRs
+- **🌍 Improve Translations** — Five core locale trees (`en` is the reference); native polish for FR/ES/IT especially welcome in PRs
 - **🧪 Write Tests** — Coverage thresholds: branches ≥ 60 %, functions ≥ 67 %, lines ≥ 74 %; contributions to large components (collaboration, AI streaming paths, OpenRouter provider) are particularly valuable
 
 See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for the full dev setup, Biome / Vitest / Playwright guide, and architecture notes.
diff --git a/packages/worker-bus/src/workerPool.ts b/packages/worker-bus/src/workerPool.ts
index 5808aefd8..d8e83171a 100644
--- a/packages/worker-bus/src/workerPool.ts
+++ b/packages/worker-bus/src/workerPool.ts
@@ -230,37 +230,36 @@ export class WorkerPool {
   }
 
   private waitForIdle(signal?: AbortSignal): Promise<PooledWorkerInstance> {
-    // QNBS-v3: captured so the hoisted `function` declarations below (which don't have
-    //          their own lexical `this`) can still reach the pool instance.
-    const pool = this;
     return new Promise((resolve, reject) => {
-      // QNBS-v3: `check`/`cleanup`/`onAbort` are mutually recursive (check calls cleanup,
-      //          onAbort calls cleanup) — plain `function` declarations hoist fully (name +
-      //          body), so each can reference the others regardless of source order, with no
-      //          TDZ and no `const` "used before defined" antipattern.
-      function check() {
-        const idle = pool.entries.find((e) => e.instance.state === 'idle');
+      // QNBS-v3: cleanup/onAbort are mutually recursive — plain `function` declarations
+      //          hoist fully, avoiding the `const` "used before defined" antipattern
+      //          without aliasing `this` (neither touches pool state, unlike `check`).
+      function cleanup() {
+        signal?.removeEventListener('abort', onAbort);
+      }
+      function onAbort() {
+        cleanup();
+        reject(new Error('Aborted'));
+      }
+
+      // QNBS-v3: arrow function keeps `this` lexical (no aliasing) since it only
+      //          self-recurses via requestAnimationFrame and references `cleanup`,
+      //          both already declared above.
+      const check = (): void => {
+        const idle = this.entries.find((e) => e.instance.state === 'idle');
         if (idle) {
           cleanup();
-          pool.setBusy(idle.instance.workerId);
+          this.setBusy(idle.instance.workerId);
           resolve(idle.instance);
           return;
         }
-        if (pool.shutdownFlag) {
+        if (this.shutdownFlag) {
           cleanup();
           reject(new Error('Pool is shutting down'));
           return;
         }
         requestAnimationFrame(check);
-      }
-
-      function cleanup() {
-        signal?.removeEventListener('abort', onAbort);
-      }
-      function onAbort() {
-        cleanup();
-        reject(new Error('Aborted'));
-      }
+      };
 
       signal?.addEventListener('abort', onAbort);
       check();

From 9f9b5e6bed7824146d03a619482c3708b3626bc5 Mon Sep 17 00:00:00 2001
From: qnbs <155236708+qnbs@users.noreply.github.com>
Date: Sat, 1 Aug 2026 07:12:05 +0200
Subject: [PATCH 12/12] docs(deepsource): log pre-existing complexity +
 short-var-name findings on PR #305
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

docs/DEEPSOURCE-REMEDIATION-PLAN.md: JS-R1005 (enqueue=11, detectWebnn=10,
detectMemoryTier=9, recommendBackend=9, detectDirectML=6) and JS-C1002 (toError's
e, a workerBus.test.ts t) are all pre-existing debt on code this PR never touched
(confirmed via diff) — DeepSource's PR-scope view widens 'introduced' to every
issue in a touched file, not just changed lines. Tracked here instead of bundling
an unrelated refactor into the WorkerBus timeout-enforcement feature.

Co-Authored-By: GitHub Copilot (Claude Sonnet 5) <noreply@github.com>
---
 docs/DEEPSOURCE-REMEDIATION-PLAN.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/DEEPSOURCE-REMEDIATION-PLAN.md b/docs/DEEPSOURCE-REMEDIATION-PLAN.md
index 2305faf09..bbdb9416d 100644
--- a/docs/DEEPSOURCE-REMEDIATION-PLAN.md
+++ b/docs/DEEPSOURCE-REMEDIATION-PLAN.md
@@ -89,6 +89,8 @@ Fix in this order — highest user/security impact first; cosmetic last. Within
 | **JS-0323** | Detected usage of `any` (Critical) | 34 / 20 files | **100% test files** (browser-API mocks: MediaRecorder/AudioContext …), all already `biome-ignore noExplicitAny`'d; **0 production** | **rule-ignore, test scope** — redundant with Biome `noExplicitAny` + the suppression ratchet (baseline 52). Do NOT add 34 inline `skipcq`. Long-term: opportunistic typed-mock cleanup (§4c). | maintainer-click (rule-ignore) | — |
 | **JS-0415** | JSX tree too deeply nested (5–6 levels) | 2 | `components/HelpView.tsx` | pre-existing structural; genuine refactor candidate (extract sub-components to cut nesting). Minor severity → schedule as a low-priority hygiene PR; **not** a false positive. | todo (future refactor) | — |
 | **JS-0067** | Unexpected function declaration in the global scope | 2+ (repo-wide pattern) | `services/ai/localAiDeviceProfiler.ts`, `services/workerBusManager.ts` (representative — every top-level `services/*.ts` function hits this) | **rule-ignore, repo-wide** — idiomatic top-level ES-module functions, not `<script>`-tag globals; fixing per-occurrence would touch dozens of pre-existing files for no behavioral gain. | todo (maintainer dashboard click) | #305 |
+| **JS-R1005** | Cyclomatic complexity (medium risk) | 5 | `packages/worker-bus/src/workerBus.ts` (`enqueue`=11), `services/ai/localAiDeviceProfiler.ts` (`detectWebnn`=10, `detectMemoryTier`=9, `recommendBackend`=9, `detectDirectML`=6) | **pre-existing, out of scope for #305** — confirmed via diff that none of these 5 functions were touched by the PR (only `runOnPool`/`waitForIdle` in `workerBus.ts` and an `export` keyword add on `detectMemoryTier`); DeepSource's PR view widens "introduced" to every issue in a touched file, not just changed lines. Genuine refactor candidates (extract sub-checks to cut branching) — schedule as a dedicated low-priority hygiene PR, not bundled into feature work. | todo (future refactor) | #305 |
+| **JS-C1002** | Variable name is too small | 2 | `packages/worker-bus/src/workerBus.ts` (`toError`'s `e`), `packages/worker-bus/tests/workerBus.test.ts` (`t` in a telemetry assertion) | **pre-existing, out of scope for #305** — same "introduced" widening as JS-R1005 above; neither line is in this PR's diff. Trivial rename (`e`→`err`, `t`→`telemetry`) whenever either file is next touched for an unrelated reason. | todo (opportunistic) | #305 |
 
 ### P4 — Hygiene / Style
 | Issue code | Title | Occ. | Files / modules | Decision | Status | PR |