test(core): characterize promise-core error and hang paths

Adds browser-free characterization tests that pin down the error and
settle-guarantees of the promise composition core, so it can be fixed or
refactored safely. No lib/ code is changed — current behavior (including
known-bad behavior) is frozen.

- recorder_test.js: errHandler/catch routing, catchWithoutStop terminal
  vs normal errors, ignoreErr, nested-session id semantics, unbalanced
  session restore, and task timeout (success + failure).
- session_composition_test.js (new): session()/within()/retryTo()/hopeThat()
  composition with a fake helper registered through the real container, a
  settles()/drain() harness that turns deadlocks into fast named failures,
  and hermetic per-test isolation of the recorder singleton.
- mocha/asyncWrapper_test.js: test() lifecycle (queued-step failure, sync
  throw, test.throws pass) and a rejecting injected() before-hook.

Characterized divergences (session-id leak on error, within skipping
_withinEnd, retryTo retrying past rejection, recorder.retries leaking across
runs, stopped-recorder hang) are documented for the follow-up fix plan.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DavertMik

test/unit/mocha/asyncWrapper_test.js

@@ -1,6 +1,6 @@
 import { expect } from 'chai'
 import sinon from 'sinon'
-import { test as testWrapper, setup, teardown, suiteSetup, suiteTeardown } from '../../../lib/mocha/asyncWrapper.js'
+import { test as testWrapper, injected, setup, teardown, suiteSetup, suiteTeardown } from '../../../lib/mocha/asyncWrapper.js'
 import recorder from '../../../lib/recorder.js'
 import event from '../../../lib/event.js'
 import Container from '../../../lib/container.js'
@@ -14,6 +14,27 @@ let afterSuite
 let failed
 let started
 
+// Runs a wrapped test/hook fn and resolves with how many times its done
+// callback fired and the argument it received. A done that never fires becomes
+// a fast, named rejection instead of a mocha timeout.
+function runHook(hookFn, ms = 2000) {
+  return new Promise((resolve, reject) => {
+    let count = 0
+    let arg
+    const timer = setTimeout(() => reject(new Error('done callback was never called')), ms)
+    timer.unref?.()
+    hookFn(err => {
+      count++
+      arg = err
+      const settle = setTimeout(() => {
+        clearTimeout(timer)
+        resolve({ count, arg })
+      }, 50)
+      settle.unref?.()
+    })
+  })
+}
+
 describe('AsyncWrapper', () => {
   beforeEach(async () => {
     test = { timeout: () => {} }
@@ -140,4 +161,73 @@ describe('AsyncWrapper', () => {
         .catch(() => null)
     })
   })
+
+  describe('test() lifecycle (characterization)', () => {
+    beforeEach(() => recorder.start())
+
+    it('calls done once with the error and fires test.failed when a queued step throws', async () => {
+      const onFailed = sinon.spy()
+      event.dispatcher.on(event.test.failed, onFailed)
+      test.fn = () => {
+        recorder.add(() => {
+          throw new Error('stepfail')
+        })
+      }
+      const { count, arg } = await runHook(testWrapper(test).fn)
+      expect(count).to.equal(1)
+      expect(arg).to.be.instanceof(Error)
+      expect(arg.message).to.equal('stepfail')
+      expect(onFailed.calledOnce, 'test.failed fired once').to.be.true
+    })
+
+    it('calls done once with the error when the body throws synchronously', async () => {
+      const onFailed = sinon.spy()
+      event.dispatcher.on(event.test.failed, onFailed)
+      test.fn = () => {
+        throw new Error('syncthrow')
+      }
+      const { count, arg } = await runHook(testWrapper(test).fn)
+      expect(count).to.equal(1)
+      expect(arg).to.be.instanceof(Error)
+      expect(arg.message).to.equal('syncthrow')
+      expect(onFailed.called, 'test.failed fired').to.be.true
+    })
+
+    it('passes (done with no error) and fires test.passed when test.throws matches', async () => {
+      const onPassed = sinon.spy()
+      event.dispatcher.on(event.test.passed, onPassed)
+      test.throws = /boom/
+      test.fn = () => {
+        throw new Error('boom happened')
+      }
+      const { count, arg } = await runHook(testWrapper(test).fn)
+      expect(count).to.equal(1)
+      expect(arg, 'done called with no error').to.be.undefined
+      expect(onPassed.called, 'test.passed fired').to.be.true
+    })
+  })
+
+  describe('injected() hooks (characterization)', () => {
+    beforeEach(() => recorder.start())
+
+    it('a rejecting before-hook calls done with the error and fails the suite tests', async () => {
+      const onFailed = sinon.spy()
+      event.dispatcher.on(event.test.failed, onFailed)
+      const suiteTests = [{ title: 'sample test' }]
+      const suite = {
+        opts: {},
+        ctx: { test: { title: '"before each" hook' }, currentTest: suiteTests[0] },
+        eachTest: cb => suiteTests.forEach(cb),
+      }
+      const fn = async () => {
+        throw new Error('hookfail')
+      }
+      const hook = injected(fn, suite, 'before')
+      const { arg } = await runHook(hook.bind({ test: {} }))
+      expect(arg, 'done received the error').to.be.instanceof(Error)
+      expect(arg.message).to.equal('hookfail')
+      expect(onFailed.called, 'test.failed emitted for suite tests').to.be.true
+      expect(suiteTests[0].err, 'the suite test got the hook error attached').to.be.instanceof(Error)
+    })
+  })
 })

test/unit/recorder_test.js

@@ -1,5 +1,6 @@
 import { expect } from 'chai'
 import recorder from '../../lib/recorder.js'
+import { TimeoutError } from '../../lib/timeout.js'
 
 describe('Recorder', () => {
   beforeEach(() => recorder.start())
@@ -168,4 +169,107 @@ describe('Recorder', () => {
       return recorder.promise()
     })
   })
+
+  describe('#error paths (characterization)', () => {
+    it('routes a task error to errFn and stops when catch() has no args', async () => {
+      let caught
+      recorder.errHandler(err => (caught = err))
+      recorder.add(() => {
+        throw new Error('boom')
+      })
+      recorder.catch()
+      await recorder.promise()
+      expect(caught).to.be.instanceof(Error)
+      expect(caught.message).to.equal('boom')
+      expect(recorder.isRunning()).to.equal(false)
+    })
+
+    it('catchWithoutStop runs fn for a normal error and the chain continues', async () => {
+      let handled
+      let after = false
+      recorder.add(() => {
+        throw new Error('soft')
+      })
+      recorder.catchWithoutStop(err => (handled = err.message))
+      recorder.add(() => (after = true))
+      await recorder.promise()
+      expect(handled).to.equal('soft')
+      expect(after).to.equal(true)
+    })
+
+    it('catchWithoutStop re-throws a terminal error past fn', async () => {
+      let fnCalled = false
+      const err = new Error('terminal')
+      err.isTerminal = true
+      recorder.add(() => {
+        throw err
+      })
+      recorder.catchWithoutStop(() => (fnCalled = true))
+      let rejected
+      await recorder.promise().catch(e => (rejected = e))
+      expect(fnCalled).to.equal(false)
+      expect(rejected).to.equal(err)
+    })
+
+    it('throw() after ignoreErr() does not reject the chain', async () => {
+      const err = new Error('ignored')
+      recorder.ignoreErr(err)
+      recorder.throw(err)
+      recorder.add(() => 'ok')
+      let rejected = false
+      await recorder.promise().catch(() => (rejected = true))
+      expect(rejected).to.equal(false)
+    })
+
+    it('two levels of nested sessions restore the session id to parent then null', () => {
+      const ids = []
+      recorder.add(() => {
+        recorder.session.start('outer')
+        ids.push(recorder.getCurrentSessionId())
+        recorder.session.start('inner')
+        ids.push(recorder.getCurrentSessionId())
+        recorder.session.restore('inner')
+        ids.push(recorder.getCurrentSessionId())
+        recorder.session.restore('outer')
+        ids.push(recorder.getCurrentSessionId())
+      })
+      return recorder.promise().then(() => {
+        expect(ids).to.deep.equal(['outer', 'inner', 'outer', null])
+      })
+    })
+
+    it('characterizes an unbalanced session start (no matching restore)', async () => {
+      recorder.add(() => {
+        recorder.session.start('orphan')
+      })
+      recorder.add(() => 'x')
+      await recorder.promise()
+      expect(recorder.getCurrentSessionId()).to.equal('orphan')
+      recorder.reset()
+      expect(recorder.getCurrentSessionId()).to.equal(null)
+    })
+
+    it('rejects with TimeoutError when a task exceeds its timeout', async () => {
+      recorder.retries = []
+      recorder.add('slow', () => new Promise(r => setTimeout(r, 200)), false, false, 50)
+      let err
+      await recorder.promise().catch(e => (err = e))
+      expect(err).to.be.instanceof(TimeoutError)
+    })
+
+    it('does not reject later when a fast task finishes within its timeout', async () => {
+      recorder.retries = []
+      const unhandled = []
+      const onUnhandled = e => unhandled.push(e)
+      process.on('unhandledRejection', onUnhandled)
+      try {
+        recorder.add('fast', () => new Promise(r => setTimeout(r, 10)), false, false, 50)
+        await recorder.promise()
+        await new Promise(r => setTimeout(r, 120))
+        expect(unhandled).to.have.length(0)
+      } finally {
+        process.removeListener('unhandledRejection', onUnhandled)
+      }
+    })
+  })
 })