Merge remote-tracking branch 'origin/master' into codex/simp-prune-workflow-worker-surface

# Conflicts:
#	docs/config-catalog.md

packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts

@@ -12,17 +12,12 @@ const builtWorker = join(packageRoot, 'lib', 'worker.cjs')
 const run = promisify(execFile)
 
 /**
- * The BUILT-output guard for the worker entry: every other suite runs
- * unbuilt (src/ + tsx), so nothing else proves that `lib/index.js` resolves
- * its sibling `lib/worker.cjs` and that the bundle boots a worker under plain
- * node (no tsx loader). Keyless — a zero-agent script needs no provider —
- * and self-skips until `pnpm run build` has produced the bundles.
+ * Keyless built-artifact guard: plain Node loads `lib/index.js` and its sibling
+ * `lib/worker.cjs` without tsx. Skips until the build produces both bundles.
  */
 describe.skipIf(!existsSync(builtIndex) || !existsSync(builtWorker))('built worker entry (lib/worker.cjs)', () => {
   it('the built engine spawns its built worker under plain node and completes a run', async () => {
-    // ESM resolves bare specifiers from the IMPORTING FILE's location, so the
-    // driver must live inside the package for its node_modules to apply — a
-    // temp-named file at the package root, removed on the way out.
+    // Keep the driver in-package so bare imports resolve its node_modules.
     const driver = join(packageRoot, `.built-worker-driver-${process.pid}.mjs`)
     try {
       await writeFile(driver, `
@@ -36,7 +31,7 @@ await ctx.plugin(WorkerWorkflowEngine, {})
 const run = ctx.workflows.start({
   script: 'return 6 * 7',
   meta: { name: 'built-smoke', description: 'built worker smoke' },
-  // A zero-agent script never touches the provider, so a bare id suffices.
+  // A zero-agent script never touches the provider.
   parent: { id: 'built-smoke-parent', options: {} },
 })
 const result = await run.result
@@ -47,7 +42,6 @@ if (result.stopReason !== 'completed' || result.value !== 42) {
 }
 console.log('built-worker-smoke-ok')
 `, 'utf8')
-      // Plain node — no tsx loader anywhere; the bundle must stand on its own.
       const { stdout } = await run(process.execPath, [driver], { cwd: packageRoot, timeout: 60_000 })
       expect(stdout).toContain('built-worker-smoke-ok')
     } finally {

packages/workflow/workflow-workerthread/tests/session.spec.ts

@@ -437,10 +437,7 @@ describe('runWorkerSession over an in-process MessageChannel', () => {
     void runWorkerSession(host.port, init("return await agent('p')"))
     await vi.waitFor(() => { expect(host.ofType(WorkerToHostType.ChildStart).length).toBe(1) })
     const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
-    // Cancel FIRST, then the (stale) started reply: the worker processes them
-    // in order, so the agent() continuation resumes already-cancelled — the
-    // window the real host cannot produce (it refuses starts once cancelled)
-    // but a teardown race can.
+    // Simulate a teardown race by delivering cancellation before a stale start reply.
     host.send({ type: HostToWorkerType.Cancel, reason: 'raced the start' })
     host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
     const result = await host.result()
@@ -448,7 +445,7 @@ describe('runWorkerSession over an in-process MessageChannel', () => {
     await vi.waitFor(() => {
       expect(host.ofType(WorkerToHostType.ChildDispose).map(m => m.callId)).toContain(callId)
     })
-    // The child never became an agent-start: it was wound down pre-lifecycle.
+    // The unpublished child is disposed without a lifecycle announcement.
     expect(host.ofType(WorkerToHostType.AgentStart)).toEqual([])
     host.close()
   })

packages/workflow/workflow-workerthread/tests/workflow-workerthread.spec.ts

@@ -17,27 +17,13 @@ function fakeParent(): Agent {
   return { id: AgentId('workflow-parent'), options: {} } as unknown as Agent
 }
 
-// Worker-thread startup is CPU-bound (a fresh thread compiles the runtime on
-// every start): on a contended CI runner it regularly blows past vitest's 5s
-// default test timeout, observed repeatedly on the coverage lane.
+// Allow cold worker startup on contended CI runners.
 vi.setConfig({ testTimeout: 30_000 })
 
 /**
- * `vi.waitFor` with a contention-proof default timeout: the 1s default
- * flaked repeatedly on the CI coverage lane, where worker-thread cold start
- * (CPU-bound — a fresh thread compiles the runtime) competes with three
- * sibling vitest workers for CPU. The 10s default is for exactly those
- * races — waiting for a worker to start, run its first script line, or
- * deliver an async child-registration message to the host. It is NOT for a
- * wait that asserts the HOST reacted PROMPTLY to something that already
- * happened (a settled result, an observed worker death): those keep an
- * explicit tight override below, or the generous default would silently
- * accept a multi-second regression in host-side reap latency as passing
- * (proven by injecting a 6s delay into one such reap and watching the
- * un-overridden version of this helper still pass in ~6s).
- * @param assertion - retried until it stops throwing or the timeout elapses.
- * @param timeout - override for a wait that must stay deliberately tight.
- * @returns resolves when the assertion passes.
+ * Wait up to 10 seconds for CPU-bound worker startup or cross-thread delivery on contended CI.
+ * Host reactions after an observed event use explicit tight overrides, so this generous startup
+ * allowance cannot hide multi-second reap regressions.
  */
 function waitFor(assertion: () => void, timeout = 10_000): Promise<void> {
   return vi.waitFor(assertion, { timeout, interval: 50 })