@swarmclawai/swarmclaw 0.8.4 → 0.8.7

package/src/lib/server/task-service.ts

@@ -0,0 +1,264 @@
+import { computeTaskFingerprint, findDuplicateTask } from '@/lib/task-dedupe'
+import type { BoardTask, BoardTaskStatus } from '@/types'
+
+import { hasManagedAgentAssignmentInput } from './agent-assignment'
+import {
+  buildBoardTask,
+  markInvalidCompletedTaskFailed,
+  markValidatedTaskCompleted,
+  refreshTaskCompletionValidation,
+} from './task-lifecycle'
+import { normalizeTaskQualityGate } from './task-quality-gate'
+
+const TASK_STATUS_VALUES = new Set([
+  'backlog',
+  'queued',
+  'running',
+  'completed',
+  'failed',
+  'archived',
+])
+
+export function deriveTaskTitle(input: { title?: unknown; description?: unknown }): string {
+  const explicit = typeof input.title === 'string' ? input.title.replace(/\s+/g, ' ').trim() : ''
+  if (explicit && !/^untitled task$/i.test(explicit)) return explicit.slice(0, 120)
+
+  const description = typeof input.description === 'string'
+    ? input.description.replace(/\s+/g, ' ').trim()
+    : ''
+  if (!description) return ''
+
+  const firstSentence = description.split(/[.!?]\s+/)[0] || description
+  const compact = firstSentence
+    .replace(/^please\s+/i, '')
+    .replace(/^(create|make|build|implement|write)\s+/i, '')
+    .trim()
+  if (!compact) return ''
+  return compact.slice(0, 120)
+}
+
+export function normalizeTaskStatusInput(status: unknown, prevStatus?: string): BoardTaskStatus | null {
+  if (typeof status !== 'string') return null
+  const normalized = status.trim().toLowerCase()
+  if (!TASK_STATUS_VALUES.has(normalized)) return null
+  if (normalized === 'running' && prevStatus !== 'running') return 'queued'
+  return normalized as BoardTaskStatus
+}
+
+export function normalizeTaskIdList(value: unknown): string[] {
+  const rawValues = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const entry of rawValues) {
+    const normalized = typeof entry === 'string' ? entry.trim() : ''
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    out.push(normalized)
+  }
+  return out
+}
+
+export function pickFirstTaskId(value: unknown): string | null {
+  const ids = normalizeTaskIdList(value)
+  return ids[0] || null
+}
+
+export function applyTaskContinuationDefaults(
+  parsed: Record<string, unknown>,
+  tasks: Record<string, BoardTask>,
+  explicitInput?: Record<string, unknown>,
+): string | null {
+  const explicit = explicitInput || parsed
+  const continuationTaskId = pickFirstTaskId(parsed.continueFromTaskId)
+    || pickFirstTaskId(parsed.followUpToTaskId)
+    || pickFirstTaskId(parsed.resumeFromTaskId)
+  const blockedBy = [
+    ...normalizeTaskIdList(parsed.blockedBy),
+    ...normalizeTaskIdList(parsed.dependsOn),
+    ...normalizeTaskIdList(parsed.dependsOnTaskIds),
+    ...normalizeTaskIdList(parsed.prerequisiteTaskIds),
+  ]
+  if (continuationTaskId && !blockedBy.includes(continuationTaskId)) {
+    blockedBy.unshift(continuationTaskId)
+  }
+  if (blockedBy.length > 0) parsed.blockedBy = blockedBy
+
+  if (continuationTaskId) {
+    const sourceTask = tasks[continuationTaskId]
+    if (!sourceTask) return `Error: source task "${continuationTaskId}" not found.`
+
+    if (!Object.prototype.hasOwnProperty.call(explicit, 'projectId') && typeof sourceTask.projectId === 'string' && sourceTask.projectId.trim()) {
+      parsed.projectId = sourceTask.projectId.trim()
+    }
+    if (
+      !Object.prototype.hasOwnProperty.call(explicit, 'agentId')
+      && !hasManagedAgentAssignmentInput(explicit)
+      && typeof sourceTask.agentId === 'string'
+      && sourceTask.agentId.trim()
+    ) {
+      parsed.agentId = sourceTask.agentId.trim()
+    }
+    if (!Object.prototype.hasOwnProperty.call(explicit, 'cwd') && typeof sourceTask.cwd === 'string' && sourceTask.cwd.trim()) {
+      parsed.cwd = sourceTask.cwd.trim()
+    }
+    const sourceSessionId = typeof sourceTask.checkpoint?.lastSessionId === 'string' && sourceTask.checkpoint.lastSessionId.trim()
+      ? sourceTask.checkpoint.lastSessionId.trim()
+      : typeof sourceTask.sessionId === 'string' && sourceTask.sessionId.trim()
+        ? sourceTask.sessionId.trim()
+        : ''
+    if (!Object.prototype.hasOwnProperty.call(explicit, 'sessionId') && sourceSessionId) {
+      parsed.sessionId = sourceSessionId
+    }
+
+    const resumeFieldMap: Array<[keyof BoardTask, string]> = [
+      ['cliResumeId', 'cliResumeId'],
+      ['cliProvider', 'cliProvider'],
+      ['claudeResumeId', 'claudeResumeId'],
+      ['codexResumeId', 'codexResumeId'],
+      ['opencodeResumeId', 'opencodeResumeId'],
+      ['geminiResumeId', 'geminiResumeId'],
+    ]
+    for (const [sourceKey, targetKey] of resumeFieldMap) {
+      const value = sourceTask[sourceKey]
+      if (Object.prototype.hasOwnProperty.call(explicit, targetKey)) continue
+      if (typeof value === 'string' && value.trim()) {
+        parsed[targetKey] = value.trim()
+      }
+    }
+  }
+
+  for (const aliasKey of ['continueFromTaskId', 'followUpToTaskId', 'resumeFromTaskId', 'dependsOn', 'dependsOnTaskIds', 'prerequisiteTaskIds']) {
+    delete parsed[aliasKey]
+  }
+  return null
+}
+
+export interface PrepareTaskCreationOptions {
+  id?: string
+  input: Record<string, unknown>
+  tasks: Record<string, BoardTask>
+  now: number
+  settings?: Record<string, unknown> | null
+  fallbackAgentId?: string | null
+  defaultCwd?: string | null
+  deriveTitleFromDescription?: boolean
+  requireMeaningfulTitle?: boolean
+  seed?: Record<string, unknown>
+}
+
+export type PrepareTaskCreationResult =
+  | { ok: false; error: string }
+  | { ok: true; task: BoardTask; duplicate: BoardTask | null }
+
+export function prepareTaskCreation(options: PrepareTaskCreationOptions): PrepareTaskCreationResult {
+  const seed = options.seed ? { ...options.seed } : {}
+  const explicitTitle = typeof options.input.title === 'string' ? options.input.title.trim() : ''
+  const derivedTitle = deriveTaskTitle(options.input)
+  const nextTitle = options.deriveTitleFromDescription
+    ? (derivedTitle || explicitTitle || 'Untitled Task')
+    : (explicitTitle || derivedTitle || 'Untitled Task')
+
+  if (options.requireMeaningfulTitle && (!nextTitle || /^untitled task$/i.test(nextTitle))) {
+    return { ok: false, error: 'Error: manage_tasks create requires a specific title or a meaningful description.' }
+  }
+
+  const normalizedStatus = normalizeTaskStatusInput(options.input.status) || 'backlog'
+  const description = typeof options.input.description === 'string' ? options.input.description : ''
+  const agentId = typeof options.input.agentId === 'string'
+    ? options.input.agentId
+    : (typeof options.fallbackAgentId === 'string' ? options.fallbackAgentId : '')
+  const qualityGate = Object.prototype.hasOwnProperty.call(options.input, 'qualityGate')
+    ? (options.input.qualityGate
+      ? normalizeTaskQualityGate(options.input.qualityGate, options.settings || null)
+      : null)
+    : seed.qualityGate
+  const cwd = Object.prototype.hasOwnProperty.call(options.input, 'cwd')
+    ? (typeof options.input.cwd === 'string' ? options.input.cwd : null)
+    : (typeof options.defaultCwd === 'string' ? options.defaultCwd : seed.cwd ?? null)
+
+  const task = buildBoardTask({
+    id: options.id,
+    title: nextTitle,
+    description,
+    agentId,
+    now: options.now,
+    status: normalizedStatus,
+    seed: {
+      ...seed,
+      cwd,
+      qualityGate,
+    },
+  })
+  task.fingerprint = computeTaskFingerprint(task.title || 'Untitled Task', task.agentId || '')
+
+  const duplicate = task.fingerprint
+    ? findDuplicateTask(options.tasks, { fingerprint: task.fingerprint })
+    : null
+  if (duplicate) {
+    return { ok: true, task, duplicate }
+  }
+
+  if (task.status === 'completed') {
+    const { validation } = refreshTaskCompletionValidation(task, options.settings)
+    if (validation.ok) {
+      markValidatedTaskCompleted(task, { now: options.now })
+    } else {
+      markInvalidCompletedTaskFailed(task, validation, { now: options.now })
+    }
+  }
+
+  return { ok: true, task, duplicate: null }
+}
+
+export interface ApplyTaskPatchOptions {
+  task: BoardTask
+  patch: Record<string, unknown>
+  now: number
+  settings?: Record<string, unknown> | null
+  preserveCompletedAt?: boolean
+  clearProjectIdWhenNull?: boolean
+  invalidCompletionCommentAuthor?: string | null
+}
+
+export function applyTaskPatch(options: ApplyTaskPatchOptions): BoardTask {
+  const nextPatch = { ...options.patch }
+  if (Object.prototype.hasOwnProperty.call(nextPatch, 'status')) {
+    const normalized = normalizeTaskStatusInput(nextPatch.status, options.task.status)
+    if (normalized) nextPatch.status = normalized
+    else delete nextPatch.status
+  }
+  if (Object.prototype.hasOwnProperty.call(nextPatch, 'qualityGate')) {
+    nextPatch.qualityGate = nextPatch.qualityGate
+      ? normalizeTaskQualityGate(nextPatch.qualityGate, options.settings || null)
+      : null
+  }
+
+  Object.assign(options.task, nextPatch, { updatedAt: options.now })
+  if (options.clearProjectIdWhenNull && nextPatch.projectId === null) delete options.task.projectId
+
+  if (options.task.status === 'completed') {
+    const { validation } = refreshTaskCompletionValidation(options.task, options.settings)
+    if (validation.ok) {
+      markValidatedTaskCompleted(options.task, {
+        now: options.now,
+        preserveCompletedAt: options.preserveCompletedAt,
+      })
+    } else {
+      markInvalidCompletedTaskFailed(options.task, validation, {
+        now: options.now,
+        comment: options.invalidCompletionCommentAuthor
+          ? {
+              author: options.invalidCompletionCommentAuthor,
+              text: `Completion validation failed.\n\n${validation.reasons.map((reason) => `- ${reason}`).join('\n')}`,
+            }
+          : undefined,
+      })
+    }
+  }
+
+  return options.task
+}

package/src/lib/server/task-validation.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict'
 import { test } from 'node:test'
-import { validateTaskCompletion } from './task-validation.ts'
+import { validateTaskCompletion } from './task-validation'
 import type { BoardTask } from '@/types'
 
 test('validateTaskCompletion fails screenshot delivery tasks without artifact evidence', () => {

package/src/lib/server/test-utils/run-with-temp-data-dir.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../..')
+
+export function runWithTempDataDir<T = unknown>(
+  script: string,
+  options: {
+    prefix?: string
+  } = {},
+): T {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), options.prefix || 'swarmclaw-test-'))
+  const workspaceDir = path.join(tempDir, 'workspace')
+  fs.mkdirSync(workspaceDir, { recursive: true })
+
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: tempDir,
+        WORKSPACE_DIR: workspaceDir,
+      },
+      encoding: 'utf-8',
+    })
+
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}') as T
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}

package/src/lib/server/tool-capability-policy.test.ts

@@ -3,7 +3,7 @@ import { test } from 'node:test'
 import {
   resolveConcreteToolPolicyBlock,
   resolveSessionToolPolicy,
-} from './tool-capability-policy.ts'
+} from './tool-capability-policy'
 
 test('capability policy permissive mode allows non-blocked tools', () => {
   const decision = resolveSessionToolPolicy(['shell', 'web_search'], { capabilityPolicyMode: 'permissive' })
@@ -76,7 +76,7 @@ test('task and project management can be disabled from app settings', () => {
     true,
   )
   assert.match(
-    resolveConcreteToolPolicyBlock('manage_tasks', decision, { taskManagementEnabled: false }),
+    resolveConcreteToolPolicyBlock('manage_tasks', decision as "allow" | "deny" | "review", { taskManagementEnabled: false }),
     /task management is disabled/i,
   )
 })

package/src/lib/server/tool-capability-policy.ts

@@ -1,4 +1,5 @@
 import type { AppSettings } from '@/types'
+import { dedup } from '@/lib/shared-utils'
 
 export type CapabilityPolicyMode = 'permissive' | 'balanced' | 'strict'
 
@@ -117,7 +118,7 @@ function normalizeList(value: unknown): string[] {
     if (!normalized) continue
     names.push(normalized)
   }
-  return Array.from(new Set(names))
+  return dedup(names)
 }
 
 function getSettingsList(settings: Record<string, unknown>, key: string): string[] {
@@ -227,7 +228,7 @@ export function resolveSessionToolPolicy(
   } = parsePolicyConfig(normalizedSettings)
 
   const requestedPlugins = Array.isArray(sessionTools)
-    ? Array.from(new Set(sessionTools.map((id) => normalizeName(id)).filter(Boolean)))
+    ? dedup(sessionTools.map((id) => normalizeName(id)).filter(Boolean))
     : []
 
   const enabledPlugins: string[] = []

package/src/lib/server/tool-planning.ts

@@ -1,4 +1,5 @@
 import type { PluginToolPlanning } from '@/types'
+import { dedup } from '@/lib/shared-utils'
 import { getPluginManager } from './plugins'
 import { canonicalizePluginId, expandPluginIds } from './tool-aliases'
 
@@ -165,7 +166,7 @@ const CORE_TOOL_PLANNING: Record<string, ToolPlanningEntry[]> = {
 }
 
 function dedupeStrings(values: string[]): string[] {
-  return Array.from(new Set(values.filter((value) => typeof value === 'string' && value.trim()).map((value) => value.trim())))
+  return dedup(values.filter((value) => typeof value === 'string' && value.trim()).map((value) => value.trim()))
 }
 
 function normalizePlanningEntry(toolName: string, planning: PluginToolPlanning | null | undefined): ToolPlanningEntry | null {

package/src/lib/server/tool-retry.ts

@@ -2,6 +2,8 @@
  * Structured retry with exponential backoff for transient tool failures.
  */
 
+import { sleep } from '@/lib/shared-utils'
+
 export interface RetryOptions {
   maxAttempts?: number
   backoffMs?: number
@@ -25,9 +27,6 @@ function isRetryableError(error: string, patterns: RegExp[]): boolean {
   return patterns.some((p) => p.test(error))
 }
 
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
 
 /**
  * Wraps a tool handler function with retry logic for transient failures.

package/src/lib/server/wake-dispatcher.test.ts

@@ -0,0 +1,303 @@
+import assert from 'node:assert/strict'
+import { afterEach, describe, it } from 'node:test'
+
+import {
+  cancelScheduledWake,
+  dispatchWake,
+  drainDeferredWakes,
+  endJobExecution,
+  getActiveJob,
+  getActiveJobsForSession,
+  getWakeDispatcherStatus,
+  hasDeferredWakes,
+  resetWakeDispatcherForTests,
+  startJobExecution,
+} from './wake-dispatcher'
+import { resetHeartbeatWakeStateForTests, snapshotPendingHeartbeatWakesForTests } from './heartbeat-wake'
+
+describe('wake-dispatcher', () => {
+  afterEach(() => {
+    resetWakeDispatcherForTests()
+    resetHeartbeatWakeStateForTests()
+  })
+
+  describe('dispatchWake — immediate mode', () => {
+    it('dispatches to heartbeat-wake pending queue', () => {
+      const result = dispatchWake({
+        mode: 'immediate',
+        sessionId: 'sess-1',
+        reason: 'connector-message',
+        source: 'connector:slack',
+        resumeMessage: 'New message from Slack.',
+      })
+
+      assert.equal(result.mode, 'immediate')
+      assert.equal(result.priority, 80)
+      assert.ok(result.runAt !== null)
+      assert.ok(result.jobId.length > 0)
+
+      // Should appear in heartbeat-wake pending state
+      const pending = snapshotPendingHeartbeatWakesForTests()
+      assert.equal(pending.length, 1)
+      assert.equal(pending[0].sessionId, 'sess-1')
+      assert.equal(pending[0].events[0].reason, 'connector-message')
+    })
+
+    it('respects explicit priority override', () => {
+      const result = dispatchWake({
+        mode: 'immediate',
+        sessionId: 'sess-1',
+        reason: 'approval',
+        priority: 95,
+      })
+
+      assert.equal(result.priority, 95)
+    })
+  })
+
+  describe('dispatchWake — next_heartbeat mode', () => {
+    it('queues in the deferred queue instead of firing immediately', () => {
+      const result = dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'agent-1',
+        sessionId: 'sess-1',
+        reason: 'low-priority-poll',
+      })
+
+      assert.equal(result.mode, 'next_heartbeat')
+      assert.equal(result.priority, 40)
+      assert.equal(result.runAt, null)
+
+      // Should NOT appear in heartbeat-wake pending state
+      const pending = snapshotPendingHeartbeatWakesForTests()
+      assert.equal(pending.length, 0)
+
+      // Should be in the deferred queue
+      assert.equal(hasDeferredWakes('agent-1', 'sess-1'), true)
+    })
+
+    it('deduplicates by reason+source', () => {
+      dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'a1',
+        sessionId: 's1',
+        reason: 'poll',
+        source: 'system',
+      })
+      dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'a1',
+        sessionId: 's1',
+        reason: 'poll',
+        source: 'system',
+      })
+
+      const drained = drainDeferredWakes('a1', 's1')
+      assert.equal(drained.length, 1)
+    })
+
+    it('preserves distinct reasons', () => {
+      dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'a1',
+        sessionId: 's1',
+        reason: 'poll',
+        source: 'system',
+      })
+      dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'a1',
+        sessionId: 's1',
+        reason: 'check-email',
+        source: 'system',
+      })
+
+      const drained = drainDeferredWakes('a1', 's1')
+      assert.equal(drained.length, 2)
+      assert.deepEqual(drained.map((d) => d.reason).sort(), ['check-email', 'poll'])
+    })
+
+    it('drainDeferredWakes clears the queue', () => {
+      dispatchWake({
+        mode: 'next_heartbeat',
+        agentId: 'a1',
+        sessionId: 's1',
+        reason: 'poll',
+      })
+
+      assert.equal(hasDeferredWakes('a1', 's1'), true)
+      const first = drainDeferredWakes('a1', 's1')
+      assert.equal(first.length, 1)
+
+      // Second drain returns empty
+      assert.equal(hasDeferredWakes('a1', 's1'), false)
+      const second = drainDeferredWakes('a1', 's1')
+      assert.equal(second.length, 0)
+    })
+  })
+
+  describe('dispatchWake — scheduled mode', () => {
+    it('fires immediately when target time is in the past', () => {
+      const result = dispatchWake({
+        mode: 'scheduled',
+        sessionId: 'sess-1',
+        reason: 'overdue-schedule',
+        runAt: Date.now() - 1000,
+      })
+
+      assert.equal(result.mode, 'scheduled')
+
+      // Should have dispatched as immediate (appears in heartbeat-wake queue)
+      const pending = snapshotPendingHeartbeatWakesForTests()
+      assert.equal(pending.length, 1)
+    })
+
+    it('creates a scheduled timer for future execution', () => {
+      const result = dispatchWake({
+        mode: 'scheduled',
+        sessionId: 'sess-1',
+        reason: 'future-task',
+        delayMs: 60_000,
+      })
+
+      assert.equal(result.mode, 'scheduled')
+      assert.ok(result.runAt !== null && result.runAt > Date.now())
+
+      const status = getWakeDispatcherStatus()
+      assert.equal(status.scheduledTimerCount, 1)
+
+      // Not yet in heartbeat-wake queue
+      const pending = snapshotPendingHeartbeatWakesForTests()
+      assert.equal(pending.length, 0)
+    })
+
+    it('cancelScheduledWake removes the timer', () => {
+      const result = dispatchWake({
+        mode: 'scheduled',
+        sessionId: 'sess-1',
+        reason: 'cancellable',
+        delayMs: 300_000,
+      })
+
+      assert.equal(getWakeDispatcherStatus().scheduledTimerCount, 1)
+      const cancelled = cancelScheduledWake(result.jobId)
+      assert.equal(cancelled, true)
+      assert.equal(getWakeDispatcherStatus().scheduledTimerCount, 0)
+    })
+  })
+
+  describe('job context management', () => {
+    it('startJobExecution creates an isolated context', () => {
+      const controller = new AbortController()
+      const ctx = startJobExecution({
+        sessionId: 'sess-1',
+        agentId: 'agent-1',
+        mode: 'immediate',
+        signal: controller.signal,
+        source: 'connector:slack',
+        reason: 'New message',
+        heartbeatSnapshot: '# Tasks\n- [ ] Check weather',
+      })
+
+      assert.ok(ctx.jobId.length > 0)
+      assert.equal(ctx.sessionId, 'sess-1')
+      assert.equal(ctx.mode, 'immediate')
+      assert.ok(ctx.startedAt! > 0)
+      assert.equal(ctx.heartbeatSnapshot, '# Tasks\n- [ ] Check weather')
+
+      // Verify it's registered
+      const retrieved = getActiveJob(ctx.jobId)
+      assert.ok(retrieved)
+      assert.equal(retrieved!.jobId, ctx.jobId)
+    })
+
+    it('endJobExecution removes from active tracking', () => {
+      const controller = new AbortController()
+      const ctx = startJobExecution({
+        sessionId: 'sess-1',
+        mode: 'immediate',
+        signal: controller.signal,
+      })
+
+      const ended = endJobExecution(ctx.jobId)
+      assert.ok(ended)
+      assert.ok(ended!.endedAt! > 0)
+
+      // No longer active
+      assert.equal(getActiveJob(ctx.jobId), null)
+    })
+
+    it('getActiveJobsForSession lists jobs for a session', () => {
+      const controller = new AbortController()
+      startJobExecution({
+        sessionId: 'sess-1',
+        mode: 'immediate',
+        signal: controller.signal,
+      })
+      startJobExecution({
+        sessionId: 'sess-1',
+        mode: 'next_heartbeat',
+        signal: controller.signal,
+      })
+      startJobExecution({
+        sessionId: 'sess-2',
+        mode: 'immediate',
+        signal: controller.signal,
+      })
+
+      const jobs = getActiveJobsForSession('sess-1')
+      assert.equal(jobs.length, 2)
+      assert.ok(jobs.every((j) => j.sessionId === 'sess-1'))
+    })
+
+    it('scratchpad provides per-job isolation', () => {
+      const controller = new AbortController()
+      const job1 = startJobExecution({
+        sessionId: 'sess-1',
+        mode: 'immediate',
+        signal: controller.signal,
+      })
+      const job2 = startJobExecution({
+        sessionId: 'sess-1',
+        mode: 'immediate',
+        signal: controller.signal,
+      })
+
+      job1.scratchpad.set('result', 'job1-data')
+      job2.scratchpad.set('result', 'job2-data')
+
+      assert.equal(getActiveJob(job1.jobId)!.scratchpad.get('result'), 'job1-data')
+      assert.equal(getActiveJob(job2.jobId)!.scratchpad.get('result'), 'job2-data')
+    })
+  })
+
+  describe('diagnostics', () => {
+    it('getWakeDispatcherStatus reports queue depths', () => {
+      const controller = new AbortController()
+
+      dispatchWake({ mode: 'next_heartbeat', agentId: 'a1', sessionId: 's1', reason: 'poll' })
+      dispatchWake({ mode: 'next_heartbeat', agentId: 'a1', sessionId: 's1', reason: 'check' })
+      dispatchWake({ mode: 'scheduled', sessionId: 's2', reason: 'future', delayMs: 60_000 })
+      startJobExecution({ sessionId: 's1', mode: 'immediate', signal: controller.signal })
+
+      const status = getWakeDispatcherStatus()
+      assert.equal(status.deferredQueueCount, 2)
+      assert.equal(status.scheduledTimerCount, 1)
+      assert.equal(status.activeJobCount, 1)
+    })
+
+    it('resetWakeDispatcherForTests clears all state', () => {
+      const controller = new AbortController()
+      dispatchWake({ mode: 'next_heartbeat', agentId: 'a1', sessionId: 's1', reason: 'poll' })
+      dispatchWake({ mode: 'scheduled', sessionId: 's2', reason: 'future', delayMs: 60_000 })
+      startJobExecution({ sessionId: 's1', mode: 'immediate', signal: controller.signal })
+
+      resetWakeDispatcherForTests()
+
+      const status = getWakeDispatcherStatus()
+      assert.equal(status.deferredQueueCount, 0)
+      assert.equal(status.scheduledTimerCount, 0)
+      assert.equal(status.activeJobCount, 0)
+    })
+  })
+})