@swarmclawai/swarmclaw 1.8.13 → 1.9.2

package/src/lib/server/tasks/task-execution-workspace.test.ts

@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+
+import type { BoardTask } from '@/types'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let workspace: typeof import('@/lib/server/tasks/task-execution-workspace')
+
+function makeTask(overrides: Partial<BoardTask> = {}): BoardTask {
+  return {
+    id: 'task-1',
+    title: 'Ship preview URLs',
+    description: 'Prepare an isolated task workspace.',
+    status: 'backlog',
+    agentId: 'agent-1',
+    createdAt: 1,
+    updatedAt: 1,
+    ...overrides,
+  } as BoardTask
+}
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-task-workspace-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  workspace = await import('@/lib/server/tasks/task-execution-workspace')
+})
+
+after(() => {
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+describe('task execution workspaces', () => {
+  it('provisions a deterministic task workspace with preview metadata', () => {
+    const task = makeTask({
+      id: 'task-alpha',
+      title: 'Launch QA / preview',
+      cwd: '/repo/source',
+      projectId: 'project-1',
+    })
+
+    const patch = workspace.prepareTaskExecutionWorkspace(task, {
+      now: 100,
+      actor: 'test',
+      previewLinks: [{ label: 'Local preview', url: 'http://127.0.0.1:3456', port: 3456 }],
+      runtimeServices: [{ name: 'Next dev', status: 'planned', command: 'npm run dev', port: 3456 }],
+    })
+
+    assert.match(patch.executionWorkspace.path, /project-1/)
+    assert.match(patch.executionWorkspace.path, /task-alpha-launch-qa-preview/)
+    assert.equal(fs.existsSync(patch.executionWorkspace.path), true)
+    assert.equal(fs.existsSync(patch.executionWorkspace.readmePath || ''), true)
+    assert.equal(patch.executionWorkspace.sourceCwd, '/repo/source')
+    assert.equal(patch.executionWorkspace.previewLinks[0]?.label, 'Local preview')
+    assert.equal(patch.previewLinks[0]?.url, 'http://127.0.0.1:3456')
+    assert.equal(patch.runtimeServices[0]?.status, 'planned')
+  })
+
+  it('deduplicates preview URLs and computes blocked, stale, and retrying liveness', () => {
+    const task = makeTask({
+      id: 'task-beta',
+      status: 'running',
+      startedAt: 10,
+      updatedAt: 10,
+      lastActivityAt: 10,
+      previewLinks: [{ id: 'old', label: 'Existing', url: 'http://localhost:3000', kind: 'web', addedAt: 5 }],
+    })
+
+    const patch = workspace.prepareTaskExecutionWorkspace(task, {
+      now: 100,
+      previewLinks: [
+        { label: 'Duplicate', url: 'http://localhost:3000' },
+        { label: 'Docs', url: 'http://localhost:3000/docs', kind: 'docs' },
+      ],
+    })
+
+    assert.equal(patch.previewLinks.length, 2)
+    assert.equal(patch.previewLinks[0]?.label, 'Existing')
+    assert.equal(patch.previewLinks[1]?.kind, 'docs')
+
+    const stale = workspace.computeTaskLiveness(task, {}, { now: 100, staleAfterMs: 50 })
+    assert.equal(stale.state, 'stale')
+    assert.match(stale.reason, /No activity/)
+
+    const blocked = workspace.computeTaskLiveness(makeTask({
+      status: 'queued',
+      blockedBy: ['dep-1'],
+    }), {
+      'dep-1': makeTask({ id: 'dep-1', status: 'running' }),
+    }, { now: 100 })
+    assert.equal(blocked.state, 'blocked')
+    assert.deepEqual(blocked.blockerTaskIds, ['dep-1'])
+
+    const retrying = workspace.computeTaskLiveness(makeTask({
+      status: 'queued',
+      retryScheduledAt: 150,
+    }), {}, { now: 100 })
+    assert.equal(retrying.state, 'retrying')
+    assert.equal(retrying.nextWakeAt, 150)
+  })
+})

package/src/lib/server/tasks/task-execution-workspace.ts

@@ -0,0 +1,321 @@
+import fs from 'fs'
+import path from 'path'
+
+import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import type {
+  BoardTask,
+  TaskExecutionWorkspace,
+  TaskLivenessSnapshot,
+  TaskPreviewLink,
+  TaskRuntimeService,
+} from '@/types'
+
+const DEFAULT_STALE_RUNNING_MS = 30 * 60 * 1000
+const MAX_PREVIEW_LINKS = 12
+const MAX_RUNTIME_SERVICES = 12
+
+type PreviewInput = Partial<Omit<TaskPreviewLink, 'id' | 'addedAt'>> & {
+  id?: unknown
+  label?: unknown
+  url?: unknown
+  kind?: unknown
+  port?: unknown
+}
+
+type RuntimeServiceInput = Partial<Omit<TaskRuntimeService, 'id' | 'updatedAt'>> & {
+  id?: unknown
+  name?: unknown
+  status?: unknown
+  command?: unknown
+  url?: unknown
+  port?: unknown
+  startedAt?: unknown
+}
+
+export interface PrepareTaskExecutionWorkspaceOptions {
+  now?: number
+  actor?: string | null
+  workspaceRoot?: string
+  previewLinks?: PreviewInput[]
+  runtimeServices?: RuntimeServiceInput[]
+  tasks?: Record<string, BoardTask>
+}
+
+export interface TaskExecutionWorkspacePatch {
+  executionWorkspace: TaskExecutionWorkspace
+  previewLinks: TaskPreviewLink[]
+  runtimeServices: TaskRuntimeService[]
+  liveness: TaskLivenessSnapshot
+}
+
+function compactText(value: unknown, maxLen: number): string {
+  if (typeof value !== 'string') return ''
+  const compact = value.replace(/\s+/g, ' ').trim()
+  return compact.slice(0, maxLen)
+}
+
+function stableIdFrom(value: string): string {
+  let hash = 5381
+  for (let i = 0; i < value.length; i += 1) {
+    hash = ((hash << 5) + hash) ^ value.charCodeAt(i)
+  }
+  return Math.abs(hash >>> 0).toString(36)
+}
+
+export function taskWorkspaceSlug(task: Pick<BoardTask, 'id' | 'title'>): string {
+  const raw = `${task.id} ${task.title || 'task'}`
+  let out = ''
+  let lastWasDash = false
+  for (const char of raw.toLowerCase()) {
+    const isAlpha = char >= 'a' && char <= 'z'
+    const isDigit = char >= '0' && char <= '9'
+    if (isAlpha || isDigit) {
+      out += char
+      lastWasDash = false
+      continue
+    }
+    if (!lastWasDash && out) {
+      out += '-'
+      lastWasDash = true
+    }
+  }
+  const trimmed = out.replace(/-+$/g, '')
+  return (trimmed || `task-${task.id}`).slice(0, 96)
+}
+
+function normalizePort(value: unknown): number | null {
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Number.parseInt(value, 10) : Number.NaN
+  if (!Number.isFinite(parsed)) return null
+  const port = Math.trunc(parsed)
+  return port > 0 && port < 65536 ? port : null
+}
+
+function normalizePreviewKind(value: unknown): TaskPreviewLink['kind'] {
+  return value === 'api' || value === 'docs' || value === 'custom' ? value : 'web'
+}
+
+export function normalizeTaskPreviewLinks(
+  existing: TaskPreviewLink[] | undefined,
+  incoming: PreviewInput[] | undefined,
+  now = Date.now(),
+): TaskPreviewLink[] {
+  const out: TaskPreviewLink[] = []
+  const seenUrls = new Set<string>()
+
+  const append = (link: PreviewInput | TaskPreviewLink) => {
+    const url = compactText(link.url, 2048)
+    if (!url || seenUrls.has(url)) return
+    seenUrls.add(url)
+    const label = compactText(link.label, 80) || 'Preview'
+    const port = normalizePort(link.port)
+    out.push({
+      id: compactText(link.id, 80) || `preview-${stableIdFrom(url)}`,
+      label,
+      url,
+      kind: normalizePreviewKind(link.kind),
+      port,
+      addedAt: typeof (link as TaskPreviewLink).addedAt === 'number' && Number.isFinite((link as TaskPreviewLink).addedAt)
+        ? (link as TaskPreviewLink).addedAt
+        : now,
+    })
+  }
+
+  for (const link of existing || []) append(link)
+  for (const link of incoming || []) append(link)
+  return out.slice(0, MAX_PREVIEW_LINKS)
+}
+
+function normalizeRuntimeStatus(value: unknown): TaskRuntimeService['status'] {
+  return value === 'running' || value === 'stopped' || value === 'failed' || value === 'unknown'
+    ? value
+    : 'planned'
+}
+
+export function normalizeTaskRuntimeServices(
+  existing: TaskRuntimeService[] | undefined,
+  incoming: RuntimeServiceInput[] | undefined,
+  now = Date.now(),
+): TaskRuntimeService[] {
+  const out: TaskRuntimeService[] = []
+  const seenKeys = new Set<string>()
+
+  const append = (service: RuntimeServiceInput | TaskRuntimeService) => {
+    const name = compactText(service.name, 100)
+    const url = compactText(service.url, 2048) || null
+    const port = normalizePort(service.port)
+    const command = compactText(service.command, 500) || null
+    const key = `${name || 'service'}:${url || ''}:${port || ''}`
+    if (seenKeys.has(key)) return
+    seenKeys.add(key)
+    out.push({
+      id: compactText(service.id, 80) || `service-${stableIdFrom(key)}`,
+      name: name || 'Runtime service',
+      status: normalizeRuntimeStatus(service.status),
+      command,
+      url,
+      port,
+      startedAt: typeof service.startedAt === 'number' && Number.isFinite(service.startedAt) ? service.startedAt : null,
+      updatedAt: typeof (service as TaskRuntimeService).updatedAt === 'number' && Number.isFinite((service as TaskRuntimeService).updatedAt)
+        ? (service as TaskRuntimeService).updatedAt
+        : now,
+    })
+  }
+
+  for (const service of existing || []) append(service)
+  for (const service of incoming || []) append(service)
+  return out.slice(0, MAX_RUNTIME_SERVICES)
+}
+
+function taskWorkspaceRoot(task: BoardTask, workspaceRoot: string): string {
+  if (task.projectId) return path.join(workspaceRoot, 'projects', task.projectId, 'task-workspaces')
+  return path.join(workspaceRoot, 'task-workspaces')
+}
+
+function writeWorkspaceReadme(task: BoardTask, workspacePath: string, now: number): string {
+  const readmePath = path.join(workspacePath, 'README.md')
+  const lines = [
+    `# ${task.title || 'Task Workspace'}`,
+    '',
+    `Task ID: ${task.id}`,
+    `Status: ${task.status}`,
+    `Prepared: ${new Date(now).toISOString()}`,
+  ]
+  if (task.projectId) lines.push(`Project ID: ${task.projectId}`)
+  if (task.cwd) lines.push(`Source cwd: ${task.cwd}`)
+  lines.push('', 'Use this directory for task-local notes, generated artifacts, and preview handoff files.')
+  fs.writeFileSync(readmePath, `${lines.join('\n')}\n`, 'utf8')
+  return readmePath
+}
+
+export function computeTaskLiveness(
+  task: BoardTask,
+  tasks: Record<string, BoardTask> = {},
+  options: { now?: number; staleAfterMs?: number } = {},
+): TaskLivenessSnapshot {
+  const now = options.now ?? Date.now()
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_RUNNING_MS
+  const lastActivityAt = task.lastActivityAt ?? task.updatedAt ?? task.startedAt ?? task.createdAt ?? null
+  const blockerTaskIds = (task.blockedBy || [])
+    .filter((id) => {
+      const blocker = tasks[id]
+      return !blocker || blocker.status !== 'completed'
+    })
+
+  if (task.status === 'completed' || task.status === 'failed' || task.status === 'cancelled' || task.status === 'archived') {
+    return {
+      state: task.status,
+      reason: `Task is ${task.status}.`,
+      checkedAt: now,
+      lastActivityAt,
+    }
+  }
+
+  if (task.deadLetteredAt) {
+    return {
+      state: 'dead_lettered',
+      reason: 'Retry budget was exhausted.',
+      checkedAt: now,
+      lastActivityAt,
+    }
+  }
+
+  if (blockerTaskIds.length > 0) {
+    return {
+      state: 'blocked',
+      reason: `Waiting on ${blockerTaskIds.length} blocker${blockerTaskIds.length === 1 ? '' : 's'}.`,
+      checkedAt: now,
+      lastActivityAt,
+      blockerTaskIds,
+    }
+  }
+
+  if (task.retryScheduledAt && task.retryScheduledAt > now) {
+    return {
+      state: 'retrying',
+      reason: 'Retry is scheduled.',
+      checkedAt: now,
+      lastActivityAt,
+      nextWakeAt: task.retryScheduledAt,
+    }
+  }
+
+  if (task.status === 'running') {
+    const staleMs = lastActivityAt ? now - lastActivityAt : null
+    if (staleMs !== null && staleMs > staleAfterMs) {
+      return {
+        state: 'stale',
+        reason: `No activity for ${Math.round(staleMs / 60000)} minute${Math.round(staleMs / 60000) === 1 ? '' : 's'}.`,
+        checkedAt: now,
+        lastActivityAt,
+        staleMs,
+      }
+    }
+    return {
+      state: 'running',
+      reason: 'Task is checked out and running.',
+      checkedAt: now,
+      lastActivityAt,
+    }
+  }
+
+  if (task.status === 'queued') {
+    return {
+      state: 'queued',
+      reason: 'Ready in the execution queue.',
+      checkedAt: now,
+      lastActivityAt,
+    }
+  }
+
+  return {
+    state: task.executionWorkspace ? 'ready' : 'not_started',
+    reason: task.executionWorkspace ? 'Workspace is prepared.' : 'No execution workspace has been prepared yet.',
+    checkedAt: now,
+    lastActivityAt,
+  }
+}
+
+export function prepareTaskExecutionWorkspace(
+  task: BoardTask,
+  options: PrepareTaskExecutionWorkspaceOptions = {},
+): TaskExecutionWorkspacePatch {
+  const now = options.now ?? Date.now()
+  const workspaceRoot = options.workspaceRoot || WORKSPACE_DIR
+  const existing = task.executionWorkspace || null
+  const workspacePath = existing?.path || path.join(taskWorkspaceRoot(task, workspaceRoot), taskWorkspaceSlug(task))
+  fs.mkdirSync(workspacePath, { recursive: true })
+  const readmePath = writeWorkspaceReadme(task, workspacePath, now)
+  const previewLinks = normalizeTaskPreviewLinks(
+    task.previewLinks || existing?.previewLinks,
+    options.previewLinks,
+    now,
+  )
+  const runtimeServices = normalizeTaskRuntimeServices(
+    task.runtimeServices || existing?.runtimeServices,
+    options.runtimeServices,
+    now,
+  )
+  const executionWorkspace: TaskExecutionWorkspace = {
+    path: workspacePath,
+    mode: task.projectId ? 'project' : 'task',
+    sourceCwd: task.cwd || existing?.sourceCwd || null,
+    projectId: task.projectId || existing?.projectId || null,
+    preparedAt: existing?.preparedAt || now,
+    preparedBy: options.actor || existing?.preparedBy || null,
+    readmePath,
+    previewLinks,
+    runtimeServices,
+  }
+  const taskForLiveness = {
+    ...task,
+    executionWorkspace,
+    previewLinks,
+    runtimeServices,
+  }
+  return {
+    executionWorkspace,
+    previewLinks,
+    runtimeServices,
+    liveness: computeTaskLiveness(taskForLiveness, options.tasks || {}, { now }),
+  }
+}

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

@@ -22,8 +22,17 @@ import {
   saveTask,
   saveTaskMany,
 } from '@/lib/server/tasks/task-repository'
+import {
+  computeTaskLiveness,
+  prepareTaskExecutionWorkspace,
+  type PrepareTaskExecutionWorkspaceOptions,
+} from '@/lib/server/tasks/task-execution-workspace'
 import { resolveTaskAgentFromDescription } from '@/lib/server/tasks/task-mention'
-import { applyTaskPatch, prepareTaskCreation } from '@/lib/server/tasks/task-service'
+import {
+  applyTaskPatch,
+  prepareTaskCreation,
+  resolveAssignmentWorkflowStateTransition,
+} from '@/lib/server/tasks/task-service'
 import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
 import { queueSwarmFeedTaskCompletionWake } from '@/lib/server/swarmfeed-runtime'
 import { notify } from '@/lib/server/ws-hub'
@@ -60,7 +69,15 @@ export function prepareTasksForListing() {
   validateCompletedTasksQueue()
   recoverStalledRunningTasks()
   const allTasks = loadTasks()
-  return allTasks
+  const listed: Record<string, BoardTask> = {}
+  const now = Date.now()
+  for (const [id, task] of Object.entries(allTasks)) {
+    listed[id] = {
+      ...task,
+      liveness: computeTaskLiveness(task, allTasks, { now }),
+    }
+  }
+  return listed
 }
 
 export function updateTaskFromRoute(id: string, body: Record<string, unknown>): ServiceResult<BoardTask> {
@@ -69,6 +86,21 @@ export function updateTaskFromRoute(id: string, body: Record<string, unknown>):
   if (!tasks[id]) return serviceFail(404, 'Task not found')
 
   const prevStatus = tasks[id].status
+  const now = Date.now()
+  const shouldProvisionWorkspace = body.provisionWorkspace === true
+  const workspaceOptions: Pick<PrepareTaskExecutionWorkspaceOptions, 'previewLinks' | 'runtimeServices'> = {
+    previewLinks: Array.isArray(body.previewLinks)
+      ? body.previewLinks as PrepareTaskExecutionWorkspaceOptions['previewLinks']
+      : undefined,
+    runtimeServices: Array.isArray(body.runtimeServices)
+      ? body.runtimeServices as PrepareTaskExecutionWorkspaceOptions['runtimeServices']
+      : undefined,
+  }
+  const patchBody = { ...body }
+  delete patchBody.provisionWorkspace
+  delete patchBody.previewLinks
+  delete patchBody.runtimeServices
+
   if (Array.isArray(body.blockedBy)) {
     const dagResult = validateDag(tasks, id, body.blockedBy)
     if (!dagResult.valid) {
@@ -83,12 +115,12 @@ export function updateTaskFromRoute(id: string, body: Record<string, unknown>):
     }
     if (!tasks[id].comments) tasks[id].comments = []
     tasks[id].comments.push(appendedComment)
-    tasks[id].updatedAt = Date.now()
+    tasks[id].updatedAt = now
   } else {
     applyTaskPatch({
       task: tasks[id],
-      patch: body,
-      now: Date.now(),
+      patch: patchBody,
+      now,
       settings,
       preserveCompletedAt: true,
       clearProjectIdWhenNull: true,
@@ -103,22 +135,34 @@ export function updateTaskFromRoute(id: string, body: Record<string, unknown>):
     if (oldParentId && oldParentId !== newParentId && tasks[oldParentId]) {
       const oldSubs = Array.isArray(tasks[oldParentId].subtaskIds) ? tasks[oldParentId].subtaskIds : []
       tasks[oldParentId].subtaskIds = oldSubs.filter((s: string) => s !== id)
-      tasks[oldParentId].updatedAt = Date.now()
+      tasks[oldParentId].updatedAt = now
       saveTask(oldParentId, tasks[oldParentId])
     }
     if (newParentId && tasks[newParentId]) {
       const newSubs = Array.isArray(tasks[newParentId].subtaskIds) ? tasks[newParentId].subtaskIds : []
       if (!newSubs.includes(id)) {
         tasks[newParentId].subtaskIds = [...newSubs, id]
-        tasks[newParentId].updatedAt = Date.now()
+        tasks[newParentId].updatedAt = now
         saveTask(newParentId, tasks[newParentId])
       }
     }
     tasks[id].parentTaskId = newParentId
   }
 
+  if (shouldProvisionWorkspace || workspaceOptions.previewLinks || workspaceOptions.runtimeServices) {
+    Object.assign(tasks[id], prepareTaskExecutionWorkspace(tasks[id], {
+      now,
+      actor: 'user',
+      tasks,
+      ...workspaceOptions,
+    }))
+    tasks[id].updatedAt = now
+  } else {
+    tasks[id].liveness = computeTaskLiveness(tasks[id], tasks, { now })
+  }
+
   if (prevStatus !== 'archived' && tasks[id].status === 'archived') {
-    tasks[id].archivedAt = Date.now()
+    tasks[id].archivedAt = now
   }
 
   saveTask(id, tasks[id])
@@ -180,7 +224,8 @@ export function updateTaskFromRoute(id: string, body: Record<string, unknown>):
     const incompleteBlocker = blockers.find((bid: string) => tasks[bid] && tasks[bid].status !== 'completed')
     if (incompleteBlocker) {
       tasks[id].status = prevStatus
-      tasks[id].updatedAt = Date.now()
+      tasks[id].updatedAt = now
+      tasks[id].liveness = computeTaskLiveness(tasks[id], tasks, { now })
       saveTask(id, tasks[id])
       return serviceFail(409, 'Cannot queue: blocked by incomplete tasks')
     }
@@ -330,6 +375,26 @@ export function createTaskFromRoute(body: Record<string, unknown>): ServiceResul
     }
   }
 
+  if (
+    body.provisionWorkspace === true
+    || Array.isArray(body.previewLinks)
+    || Array.isArray(body.runtimeServices)
+  ) {
+    Object.assign(task, prepareTaskExecutionWorkspace(task, {
+      now,
+      actor: 'user',
+      tasks,
+      previewLinks: Array.isArray(body.previewLinks)
+        ? body.previewLinks as PrepareTaskExecutionWorkspaceOptions['previewLinks']
+        : undefined,
+      runtimeServices: Array.isArray(body.runtimeServices)
+        ? body.runtimeServices as PrepareTaskExecutionWorkspaceOptions['runtimeServices']
+        : undefined,
+    }))
+  } else {
+    task.liveness = computeTaskLiveness(task, tasks, { now })
+  }
+
   saveTask(id, task)
   logActivity({ entityType: 'task', entityId: id, action: 'created', actor: 'user', summary: `Task created: "${task.title}"` })
   pushMainLoopEventToMainSessions({
@@ -366,12 +431,25 @@ export function bulkUpdateTasksFromRoute(body: Record<string, unknown>): Service
       }
     }
     if ('agentId' in body) {
+      const previousAgentId = tasks[id].agentId
+      const previousWorkflowStateId = tasks[id].workflowStateId || null
       tasks[id].agentId = body.agentId === null ? '' : String(body.agentId)
+      const workflowTransition = resolveAssignmentWorkflowStateTransition({
+        previousAgentId,
+        nextAgentId: tasks[id].agentId,
+        previousWorkflowStateId,
+        explicitWorkflowState: Object.prototype.hasOwnProperty.call(body, 'workflowStateId'),
+      })
+      if (workflowTransition) tasks[id].workflowStateId = workflowTransition
     }
     if ('projectId' in body) {
       if (body.projectId === null) delete tasks[id].projectId
       else tasks[id].projectId = String(body.projectId)
     }
+    if ('workflowStateId' in body) {
+      if (body.workflowStateId === null) delete tasks[id].workflowStateId
+      else tasks[id].workflowStateId = String(body.workflowStateId)
+    }
     tasks[id].updatedAt = Date.now()
     updated += 1
     results.push(id)

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

@@ -3,8 +3,11 @@ import { describe, it } from 'node:test'
 
 import { computeTaskFingerprint } from '@/lib/task-dedupe'
 import type { BoardTask } from '@/types'
-
-import { applyTaskPatch, prepareTaskCreation } from '@/lib/server/tasks/task-service'
+import {
+  applyTaskPatch,
+  prepareTaskCreation,
+  resolveAssignmentWorkflowStateTransition,
+} from '@/lib/server/tasks/task-service'
 
 function makeTask(overrides: Partial<BoardTask> = {}): BoardTask {
   return {
@@ -106,3 +109,58 @@ describe('task service helpers', () => {
     assert.equal(task.status, 'queued')
   })
 })
+
+describe('task-service assignment workflow transitions', () => {
+  it('moves newly assigned backlog workflow tasks to in_progress without queueing runtime work', () => {
+    const task = makeTask({ agentId: '', workflowStateId: 'backlog' })
+    applyTaskPatch({
+      task,
+      patch: { agentId: 'agent-builder' },
+      now: 100,
+    })
+
+    assert.equal(task.agentId, 'agent-builder')
+    assert.equal(task.status, 'backlog')
+    assert.equal(task.workflowStateId, 'in_progress')
+    assert.equal(task.updatedAt, 100)
+  })
+
+  it('preserves explicit workflow state patches', () => {
+    const task = makeTask({ workflowStateId: 'todo' })
+    applyTaskPatch({
+      task,
+      patch: { agentId: 'agent-builder', workflowStateId: 'needs_review' },
+      now: 100,
+    })
+
+    assert.equal(task.workflowStateId, 'needs_review')
+  })
+
+  it('seeds assigned task creation into the in_progress workflow lane', () => {
+    const prepared = prepareTaskCreation({
+      input: {
+        title: 'Build the client',
+        description: '',
+        agentId: 'builder',
+      },
+      tasks: {},
+      now: 200,
+    })
+
+    assert.equal(prepared.ok, true)
+    if (prepared.ok) {
+      assert.equal(prepared.task.status, 'backlog')
+      assert.equal(prepared.task.workflowStateId, 'in_progress')
+    }
+  })
+
+  it('leaves already-started workflow states alone', () => {
+    const next = resolveAssignmentWorkflowStateTransition({
+      previousAgentId: '',
+      nextAgentId: 'agent-builder',
+      previousWorkflowStateId: 'needs_review',
+    })
+
+    assert.equal(next, null)
+  })
+})