@swarmclawai/swarmclaw 1.9.9 → 1.9.10

package/README.md

@@ -399,6 +399,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.10 Highlights
+
+Task handoff release: operators can package task state, readiness, workspace context, dependencies, outputs, and resume handles into a shareable packet before continuing work.
+
+- **Task handoff packets.** `GET /api/tasks/:id/handoff` returns a structured packet with owner, liveness, workspace, runtime links, dependencies, quality checks, outputs, run summary, and recommended actions.
+- **Workspace snapshots.** `POST /api/tasks/:id/handoff` prepares a workspace when needed and writes `handoff.md` plus `handoff.json` beside the task context files.
+- **Board-level triage.** `GET /api/tasks/handoffs` lists readiness packets with ready, needs-attention, and blocked counts so operators can scan handoff risk across the board.
+- **CLI and UI access.** `swarmclaw tasks handoff`, `swarmclaw tasks handoff-save`, and `swarmclaw tasks handoffs` expose the workflow for scripts, while the task sheet can copy, open, or save packets.
+
 ### v1.9.9 Highlights
 
 Schedule revision timeline release: schedule edits, lifecycle changes, and run evidence now stay inspectable from UI, API, and CLI surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.9",
+  "version": "1.9.10",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/quality/release-readiness.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/quality/release-readiness.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

package/src/app/api/tasks/[id]/handoff/route.ts

@@ -0,0 +1,73 @@
+import { NextResponse } from 'next/server'
+import fs from 'fs'
+import path from 'path'
+import { buildTaskHandoffPacket, formatTaskHandoffMarkdown } from '@/lib/server/tasks/task-handoff'
+import { prepareTaskExecutionWorkspace } from '@/lib/server/tasks/task-execution-workspace'
+import { loadTasks, saveTask } from '@/lib/server/tasks/task-repository'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const tasks = loadTasks()
+  const task = tasks[id]
+  if (!task) return NextResponse.json({ error: 'Task not found' }, { status: 404 })
+
+  const packet = buildTaskHandoffPacket(task, tasks)
+  const { searchParams } = new URL(req.url)
+  if (searchParams.get('format') === 'markdown') {
+    return new Response(formatTaskHandoffMarkdown(packet), {
+      headers: {
+        'content-type': 'text/markdown; charset=utf-8',
+      },
+    })
+  }
+
+  return NextResponse.json(packet)
+}
+
+export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const tasks = loadTasks()
+  const task = tasks[id]
+  if (!task) return NextResponse.json({ error: 'Task not found' }, { status: 404 })
+
+  let body: Record<string, unknown> = {}
+  try {
+    body = await req.json() as Record<string, unknown>
+  } catch {
+    body = {}
+  }
+
+  if (!task.executionWorkspace || body.prepareWorkspace !== false) {
+    Object.assign(task, prepareTaskExecutionWorkspace(task, {
+      now: Date.now(),
+      actor: 'user',
+      tasks,
+    }))
+    task.updatedAt = Date.now()
+    tasks[id] = task
+    saveTask(id, task)
+  }
+
+  const workspacePath = task.executionWorkspace?.path
+  if (!workspacePath) {
+    return NextResponse.json({ error: 'Task workspace is not available' }, { status: 409 })
+  }
+
+  fs.mkdirSync(workspacePath, { recursive: true })
+  const packet = buildTaskHandoffPacket(task, tasks)
+  const markdown = formatTaskHandoffMarkdown(packet)
+  const markdownPath = path.join(workspacePath, 'handoff.md')
+  const jsonPath = path.join(workspacePath, 'handoff.json')
+  fs.writeFileSync(markdownPath, markdown, 'utf8')
+  fs.writeFileSync(jsonPath, `${JSON.stringify(packet, null, 2)}\n`, 'utf8')
+
+  return NextResponse.json({
+    packet,
+    files: {
+      markdownPath,
+      jsonPath,
+    },
+  })
+}

package/src/app/api/tasks/handoffs/route.ts

@@ -0,0 +1,50 @@
+import { NextResponse } from 'next/server'
+import { buildTaskHandoffPacket } from '@/lib/server/tasks/task-handoff'
+import { loadTasks } from '@/lib/server/tasks/task-repository'
+import type { TaskHandoffReadinessStatus } from '@/types'
+
+export const dynamic = 'force-dynamic'
+
+const READINESS_STATUSES: TaskHandoffReadinessStatus[] = ['ready', 'needs_attention', 'blocked']
+
+function normalizeLimit(value: string | null): number {
+  const parsed = value ? Number.parseInt(value, 10) : 50
+  if (!Number.isFinite(parsed)) return 50
+  return Math.max(1, Math.min(200, Math.trunc(parsed)))
+}
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url)
+  const status = searchParams.get('status') as TaskHandoffReadinessStatus | null
+  const includeArchived = searchParams.get('includeArchived') === 'true'
+  const limit = normalizeLimit(searchParams.get('limit'))
+  const now = Date.now()
+  const tasks = loadTasks()
+  const packets = Object.values(tasks)
+    .filter((task) => includeArchived || task.status !== 'archived')
+    .map((task) => buildTaskHandoffPacket(task, tasks, { now, runBrief: null }))
+    .sort((left, right) => {
+      const statusRank: Record<TaskHandoffReadinessStatus, number> = {
+        blocked: 0,
+        needs_attention: 1,
+        ready: 2,
+      }
+      return statusRank[left.readiness.status] - statusRank[right.readiness.status] || right.updatedAt - left.updatedAt
+    })
+
+  const filtered = status && READINESS_STATUSES.includes(status)
+    ? packets.filter((packet) => packet.readiness.status === status)
+    : packets
+  const counts: Record<TaskHandoffReadinessStatus, number> = {
+    ready: 0,
+    needs_attention: 0,
+    blocked: 0,
+  }
+  for (const packet of packets) counts[packet.readiness.status] += 1
+
+  return NextResponse.json({
+    generatedAt: now,
+    counts,
+    items: filtered.slice(0, limit),
+  })
+}

package/src/app/api/tasks/task-workspace-route.test.ts

@@ -15,6 +15,9 @@ const originalEnv = {
 
 let tempDir = ''
 let putTask: typeof import('./[id]/route')['PUT']
+let getTaskHandoff: typeof import('./[id]/handoff/route')['GET']
+let postTaskHandoff: typeof import('./[id]/handoff/route')['POST']
+let getTaskHandoffs: typeof import('./handoffs/route')['GET']
 let getTasks: typeof import('./route')['GET']
 let storage: typeof import('@/lib/server/storage')
 
@@ -46,6 +49,10 @@ before(async () => {
   process.env.SWARMCLAW_DAEMON_AUTOSTART = '0'
   storage = await import('@/lib/server/storage')
   putTask = (await import('./[id]/route')).PUT
+  const handoffRoute = await import('./[id]/handoff/route')
+  getTaskHandoff = handoffRoute.GET
+  postTaskHandoff = handoffRoute.POST
+  getTaskHandoffs = (await import('./handoffs/route')).GET
   getTasks = (await import('./route')).GET
 })
 
@@ -114,3 +121,94 @@ test('GET /api/tasks returns computed blocked liveness without persisting a task
   assert.equal(body['task-blocked']?.liveness?.state, 'blocked')
   assert.deepEqual(body['task-blocked']?.liveness?.blockerTaskIds, ['dep-route'])
 })
+
+test('GET /api/tasks/:id/handoff returns readiness and markdown packets', async () => {
+  seedTask('task-handoff', {
+    title: 'Handoff Route Task',
+    description: 'Prepare a packet.',
+    blockedBy: ['dep-handoff'],
+    qualityGate: {
+      enabled: true,
+      minResultChars: 50,
+      minEvidenceItems: 1,
+    },
+  })
+  const tasks = storage.loadTasks()
+  tasks['dep-handoff'] = {
+    id: 'dep-handoff',
+    title: 'Dependency',
+    description: '',
+    status: 'running',
+    agentId: 'agent-1',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  } as BoardTask
+  storage.saveTasks(tasks)
+
+  const jsonResponse = await getTaskHandoff(
+    new Request('http://local/api/tasks/task-handoff/handoff'),
+    routeParams('task-handoff'),
+  )
+  assert.equal(jsonResponse.status, 200)
+  const packet = await jsonResponse.json()
+  assert.equal(packet.taskId, 'task-handoff')
+  assert.equal(packet.readiness.status, 'blocked')
+  assert.equal(packet.dependencies.blockedBy[0]?.id, 'dep-handoff')
+
+  const markdownResponse = await getTaskHandoff(
+    new Request('http://local/api/tasks/task-handoff/handoff?format=markdown'),
+    routeParams('task-handoff'),
+  )
+  assert.equal(markdownResponse.status, 200)
+  assert.match(markdownResponse.headers.get('content-type') || '', /text\/markdown/)
+  const markdown = await markdownResponse.text()
+  assert.match(markdown, /# Task Handoff: Handoff Route Task/)
+  assert.match(markdown, /Readiness: blocked/)
+})
+
+test('POST /api/tasks/:id/handoff saves markdown and JSON snapshots into the workspace', async () => {
+  seedTask('task-handoff-save', {
+    title: 'Saved Handoff Task',
+    cwd: '/source/repo',
+    result: 'Ready for the next operator.',
+  })
+
+  const response = await postTaskHandoff(
+    new Request('http://local/api/tasks/task-handoff-save/handoff', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ prepareWorkspace: true }),
+    }),
+    routeParams('task-handoff-save'),
+  )
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.packet.taskId, 'task-handoff-save')
+  assert.equal(fs.existsSync(body.files.markdownPath), true)
+  assert.equal(fs.existsSync(body.files.jsonPath), true)
+  assert.match(fs.readFileSync(body.files.markdownPath, 'utf8'), /# Task Handoff: Saved Handoff Task/)
+})
+
+test('GET /api/tasks/handoffs lists board-level readiness packets with counts', async () => {
+  seedTask('task-ready', {
+    title: 'Ready Task',
+    executionWorkspace: {
+      path: '/tmp/ready',
+      mode: 'task',
+      preparedAt: Date.now(),
+      previewLinks: [],
+      runtimeServices: [],
+    },
+  })
+  seedTask('task-needs-attention', {
+    title: 'Needs Workspace',
+  })
+
+  const response = await getTaskHandoffs(new Request('http://local/api/tasks/handoffs?status=needs_attention&limit=10'))
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.counts.ready >= 1, true)
+  assert.equal(body.counts.needs_attention >= 1, true)
+  assert.equal(body.items.every((packet: { readiness: { status: string } }) => packet.readiness.status === 'needs_attention'), true)
+})

package/src/cli/index.js

@@ -735,6 +735,9 @@ const COMMAND_GROUPS = [
     commands: [
       cmd('list', 'GET', '/tasks', 'List tasks'),
       cmd('get', 'GET', '/tasks/:id', 'Get task'),
+      cmd('handoff', 'GET', '/tasks/:id/handoff', 'Get task handoff packet'),
+      cmd('handoff-save', 'POST', '/tasks/:id/handoff', 'Save task handoff packet into the task workspace', { expectsJsonBody: true }),
+      cmd('handoffs', 'GET', '/tasks/handoffs', 'List task handoff readiness packets'),
       cmd('create', 'POST', '/tasks', 'Create task', { expectsJsonBody: true }),
       cmd('bulk', 'POST', '/tasks/bulk', 'Bulk update tasks (status/agent/project)', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/tasks/:id', 'Update task', { expectsJsonBody: true }),

package/src/cli/index.test.js

@@ -163,6 +163,38 @@ test('runCli sends authenticated request and emits compact JSON when --json is s
   assert.equal(stderr.toString(), '')
 })
 
+test('tasks handoff command can request markdown packets', async () => {
+  const stdout = makeWritable()
+  const stderr = makeWritable()
+  const calls = []
+
+  const fetchImpl = async (url, init) => {
+    calls.push({ url: String(url), init })
+    return new Response('# Task Handoff\n', {
+      status: 200,
+      headers: { 'content-type': 'text/markdown; charset=utf-8' },
+    })
+  }
+
+  const exitCode = await runCli(
+    ['tasks', 'handoff', 'task-1', '--query', 'format=markdown'],
+    {
+      fetchImpl,
+      stdout,
+      stderr,
+      env: {},
+      cwd: process.cwd(),
+    }
+  )
+
+  assert.equal(exitCode, 0)
+  assert.equal(calls.length, 1)
+  assert.match(calls[0].url, /\/api\/tasks\/task-1\/handoff\?format=markdown$/)
+  assert.equal(calls[0].init.method, 'GET')
+  assert.equal(stdout.toString(), '# Task Handoff\n')
+  assert.equal(stderr.toString(), '')
+})
+
 test('openclaw deploy bundle command merges action with provided JSON body', async () => {
   const stdout = makeWritable()
   const stderr = makeWritable()

package/src/cli/spec.js

@@ -529,6 +529,9 @@ const COMMAND_GROUPS = {
     commands: {
       list: { description: 'List tasks', method: 'GET', path: '/tasks' },
       get: { description: 'Get task by id', method: 'GET', path: '/tasks/:id', params: ['id'] },
+      handoff: { description: 'Get task handoff packet', method: 'GET', path: '/tasks/:id/handoff', params: ['id'] },
+      'handoff-save': { description: 'Save task handoff packet into the task workspace', method: 'POST', path: '/tasks/:id/handoff', params: ['id'] },
+      handoffs: { description: 'List task handoff readiness packets', method: 'GET', path: '/tasks/handoffs' },
       create: { description: 'Create task', method: 'POST', path: '/tasks' },
       bulk: { description: 'Bulk update tasks (status/agent/project)', method: 'POST', path: '/tasks/bulk' },
       update: { description: 'Update task', method: 'PUT', path: '/tasks/:id', params: ['id'] },

package/src/components/tasks/task-sheet.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useRouter } from 'next/navigation'
-import { Activity, ExternalLink, FolderOpen, PlayCircle } from 'lucide-react'
+import { Activity, ClipboardCopy, ExternalLink, FileText, FolderOpen, PlayCircle, Save } from 'lucide-react'
 import ReactMarkdown from 'react-markdown'
 import remarkGfm from 'remark-gfm'
 import { useAppStore } from '@/stores/use-app-store'
@@ -27,6 +27,7 @@ import { dedup, errorMessage } from '@/lib/shared-utils'
 import { SectionLabel } from '@/components/shared/section-label'
 import { AgentAvatar } from '@/components/agents/agent-avatar'
 import { InfoChip } from '@/components/ui/info-chip'
+import { fetchTaskHandoffMarkdown, saveTaskHandoffSnapshot } from '@/lib/tasks'
 
 function fmtTime(ts: number) {
   const d = new Date(ts)
@@ -105,6 +106,11 @@ export function TaskSheet() {
   const [qualityGateRequireReport, setQualityGateRequireReport] = useState(false)
   const [provisionWorkspace, setProvisionWorkspace] = useState(false)
   const [workspacePreparing, setWorkspacePreparing] = useState(false)
+  const [handoffCopying, setHandoffCopying] = useState(false)
+  const [handoffSaving, setHandoffSaving] = useState(false)
+  const [handoffCopied, setHandoffCopied] = useState(false)
+  const [handoffError, setHandoffError] = useState<string | null>(null)
+  const [handoffSavedPath, setHandoffSavedPath] = useState<string | null>(null)
   const [structuredSessionOpen, setStructuredSessionOpen] = useState(false)
   const formInitRef = useRef<string | null>(null)
 
@@ -160,6 +166,9 @@ export function TaskSheet() {
       setQualityGateRequireArtifact(gate?.requireArtifact ?? defaultGateRequireArtifact)
       setQualityGateRequireReport(gate?.requireReport ?? defaultGateRequireReport)
       setProvisionWorkspace(false)
+      setHandoffCopied(false)
+      setHandoffError(null)
+      setHandoffSavedPath(null)
       formInitRef.current = initKey
       return
     }
@@ -185,6 +194,9 @@ export function TaskSheet() {
     setQualityGateRequireArtifact(defaultGateRequireArtifact)
     setQualityGateRequireReport(defaultGateRequireReport)
     setProvisionWorkspace(false)
+    setHandoffCopied(false)
+    setHandoffError(null)
+    setHandoffSavedPath(null)
     formInitRef.current = initKey
   }, [
     activeProjectFilter,
@@ -209,6 +221,9 @@ export function TaskSheet() {
   const onClose = () => {
     formInitRef.current = null
     setDepError(null)
+    setHandoffCopied(false)
+    setHandoffError(null)
+    setHandoffSavedPath(null)
     setOpen(false)
     setEditingId(null)
   }
@@ -299,6 +314,39 @@ export function TaskSheet() {
     }
   }
 
+  const handleCopyHandoff = async () => {
+    if (!editing) return
+    setHandoffCopying(true)
+    try {
+      const markdown = await fetchTaskHandoffMarkdown(editing.id)
+      if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+        throw new Error('Clipboard is unavailable in this browser')
+      }
+      await navigator.clipboard.writeText(markdown)
+      setHandoffCopied(true)
+      setHandoffError(null)
+      globalThis.setTimeout(() => setHandoffCopied(false), 1800)
+    } catch (err: unknown) {
+      setHandoffError(errorMessage(err))
+    } finally {
+      setHandoffCopying(false)
+    }
+  }
+
+  const handleSaveHandoff = async () => {
+    if (!editing) return
+    setHandoffSaving(true)
+    try {
+      const result = await saveTaskHandoffSnapshot(editing.id, { prepareWorkspace: true })
+      setHandoffSavedPath(result.files.markdownPath)
+      setHandoffError(null)
+    } catch (err: unknown) {
+      setHandoffError(errorMessage(err))
+    } finally {
+      setHandoffSaving(false)
+    }
+  }
+
   const handleUnarchive = async () => {
     if (editing) {
       await updateTaskMutation.mutateAsync({ id: editing.id, patch: { status: 'backlog' } })
@@ -353,6 +401,48 @@ export function TaskSheet() {
       ? editing.runtimeServices
       : editing.executionWorkspace?.runtimeServices || [])
     : []
+  const handoffUrl = editing
+    ? `/api/tasks/${encodeURIComponent(editing.id)}/handoff?format=markdown`
+    : ''
+  const handoffControls = editing ? (
+    <div className="space-y-2">
+      <div className="flex flex-wrap gap-2">
+        <button
+          onClick={handleCopyHandoff}
+          disabled={handoffCopying}
+          className="inline-flex items-center gap-2 rounded-[10px] border border-white/[0.08] bg-white/[0.04] px-3 py-2 text-[12px] font-600 text-text-2 hover:bg-white/[0.08] disabled:opacity-50"
+          style={{ fontFamily: 'inherit' }}
+        >
+          <ClipboardCopy size={13} />
+          {handoffCopied ? 'Copied' : handoffCopying ? 'Copying...' : 'Copy Handoff'}
+        </button>
+        <a
+          href={handoffUrl}
+          target="_blank"
+          rel="noreferrer"
+          className="inline-flex items-center gap-2 rounded-[10px] border border-white/[0.08] bg-white/[0.04] px-3 py-2 text-[12px] font-600 text-text-2 hover:bg-white/[0.08]"
+        >
+          <FileText size={13} />
+          Open Packet
+        </a>
+        <button
+          onClick={handleSaveHandoff}
+          disabled={handoffSaving}
+          className="inline-flex items-center gap-2 rounded-[10px] border border-white/[0.08] bg-white/[0.04] px-3 py-2 text-[12px] font-600 text-text-2 hover:bg-white/[0.08] disabled:opacity-50"
+          style={{ fontFamily: 'inherit' }}
+        >
+          <Save size={13} />
+          {handoffSaving ? 'Saving...' : 'Save Packet'}
+        </button>
+      </div>
+      {handoffSavedPath && (
+        <code className="block text-[11px] text-text-3 font-mono break-all">{handoffSavedPath}</code>
+      )}
+      {handoffError && (
+        <p className="text-[12px] font-600 text-red-400">{handoffError}</p>
+      )}
+    </div>
+  ) : null
 
   /* ───── View-only mode ───── */
   if (viewOnly && editing) {
@@ -503,6 +593,7 @@ export function TaskSheet() {
                 ))}
               </div>
             )}
+            {handoffControls}
             {!editing.executionWorkspace && (
               <button
                 onClick={handlePrepareWorkspace}
@@ -1008,6 +1099,7 @@ export function TaskSheet() {
                 ))}
               </div>
             )}
+            {handoffControls}
             <button
               onClick={handlePrepareWorkspace}
               disabled={workspacePreparing}

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

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import { buildTaskHandoffPacket, formatTaskHandoffMarkdown } from '@/lib/server/tasks/task-handoff'
+import type { BoardTask } from '@/types'
+
+function task(overrides: Partial<BoardTask> = {}): BoardTask {
+  return {
+    id: 'task-main',
+    title: 'Prepare release handoff',
+    description: 'Summarize the release state for the next operator.',
+    status: 'backlog',
+    agentId: 'agent-1',
+    createdAt: 100,
+    updatedAt: 200,
+    ...overrides,
+  } as BoardTask
+}
+
+describe('task handoff packets', () => {
+  it('marks unresolved blockers as blocked and recommends a concrete action', () => {
+    const tasks: Record<string, BoardTask> = {
+      'task-main': task({
+        blockedBy: ['dep-1'],
+        executionWorkspace: {
+          path: '/tmp/workspace',
+          mode: 'task',
+          preparedAt: 150,
+          previewLinks: [],
+          runtimeServices: [],
+        },
+      }),
+      'dep-1': task({
+        id: 'dep-1',
+        title: 'Finish prerequisite',
+        status: 'running',
+        agentId: 'agent-2',
+      }),
+    }
+
+    const packet = buildTaskHandoffPacket(tasks['task-main'], tasks, { now: 300, runBrief: null })
+
+    assert.equal(packet.readiness.status, 'blocked')
+    assert.deepEqual(packet.dependencies.blockedBy.map((ref) => ref.id), ['dep-1'])
+    assert.equal(packet.readiness.checks.find((item) => item.id === 'dependencies')?.status, 'blocked')
+    assert.ok(packet.readiness.recommendedActions.some((action) => action.includes('unresolved blockers')))
+  })
+
+  it('summarizes workspace, evidence, and quality gate state in markdown', () => {
+    const mainTask = task({
+      status: 'completed',
+      result: 'Release completed with tests and browser smoke.',
+      completionReportPath: '/tmp/workspace/report.md',
+      outputFiles: ['/tmp/workspace/report.md'],
+      artifacts: [{ filename: 'smoke.txt', type: 'file', url: '/uploads/smoke.txt' }],
+      verificationSummary: 'npm run test passed',
+      qualityGate: {
+        enabled: true,
+        minResultChars: 10,
+        minEvidenceItems: 2,
+        requireVerification: true,
+        requireArtifact: true,
+        requireReport: true,
+      },
+      executionWorkspace: {
+        path: '/tmp/workspace',
+        mode: 'task',
+        contextPath: '/tmp/workspace/context.json',
+        envPath: '/tmp/workspace/.env.swarmclaw',
+        preparedAt: 150,
+        previewLinks: [{ id: 'preview', label: 'Preview', kind: 'web', url: 'http://127.0.0.1:3456', addedAt: 160 }],
+        runtimeServices: [{ id: 'dev', name: 'Dev server', status: 'running', updatedAt: 160 }],
+      },
+    })
+
+    const packet = buildTaskHandoffPacket(mainTask, { 'task-main': mainTask }, { now: 300, runBrief: null })
+    const markdown = formatTaskHandoffMarkdown(packet)
+
+    assert.equal(packet.readiness.status, 'ready')
+    assert.match(markdown, /# Task Handoff: Prepare release handoff/)
+    assert.match(markdown, /Readiness: ready/)
+    assert.match(markdown, /Workspace: \/tmp\/workspace/)
+    assert.match(markdown, /Preview: Preview http:\/\/127\.0\.0\.1:3456/)
+    assert.match(markdown, /Task report: \/tmp\/workspace\/report\.md/)
+  })
+})

package/src/lib/server/tasks/task-handoff.ts

@@ -0,0 +1,365 @@
+import { buildRunBrief } from '@/lib/server/runs/run-brief'
+import { getUnifiedRunById, listUnifiedRunEvents, listUnifiedRuns } from '@/lib/server/runs/unified-run-queries'
+import { computeTaskLiveness } from '@/lib/server/tasks/task-execution-workspace'
+import type {
+  BoardTask,
+  RunBrief,
+  TaskHandoffCheck,
+  TaskHandoffPacket,
+  TaskHandoffReadinessStatus,
+  TaskHandoffTaskRef,
+} from '@/types'
+
+const MAX_MARKDOWN_TEXT = 900
+
+function compactText(value: unknown, maxChars = MAX_MARKDOWN_TEXT): string | null {
+  if (typeof value !== 'string') return null
+  const text = value.split(/\s+/).filter(Boolean).join(' ').trim()
+  if (!text) return null
+  return text.length > maxChars ? `${text.slice(0, maxChars - 3)}...` : text
+}
+
+function toIso(value: number | null | undefined): string {
+  return value && Number.isFinite(value) ? new Date(value).toISOString() : 'n/a'
+}
+
+function taskRef(id: string, tasks: Record<string, BoardTask>, now: number): TaskHandoffTaskRef {
+  const task = tasks[id]
+  if (!task) {
+    return {
+      id,
+      title: id,
+      status: 'backlog',
+      agentId: null,
+      completedAt: null,
+      liveness: {
+        state: 'blocked',
+        reason: 'Referenced task is missing.',
+        checkedAt: now,
+      },
+    }
+  }
+  return {
+    id: task.id,
+    title: task.title || task.id,
+    status: task.status,
+    agentId: task.agentId || null,
+    completedAt: task.completedAt ?? null,
+    liveness: computeTaskLiveness(task, tasks, { now }),
+  }
+}
+
+function resolveLatestRunBrief(task: BoardTask): RunBrief | null {
+  const candidateIds = [
+    task.checkpoint?.lastRunId,
+    task.protocolRunId,
+  ].filter((id): id is string => typeof id === 'string' && id.trim().length > 0)
+
+  for (const runId of candidateIds) {
+    const run = getUnifiedRunById(runId)
+    if (run) return buildRunBrief(run, listUnifiedRunEvents(runId, 300))
+  }
+
+  if (!task.sessionId) return null
+  const latestOwnedRun = listUnifiedRuns({ sessionId: task.sessionId, limit: 50 })
+    .find((run) => run.ownerType === 'task' && run.ownerId === task.id)
+  if (!latestOwnedRun) return null
+  return buildRunBrief(latestOwnedRun, listUnifiedRunEvents(latestOwnedRun.id, 300))
+}
+
+function check(id: string, label: string, status: TaskHandoffCheck['status'], detail?: string | null, taskIds?: string[]): TaskHandoffCheck {
+  return { id, label, status, detail: detail || null, ...(taskIds?.length ? { taskIds } : {}) }
+}
+
+function qualityChecks(task: BoardTask, runBrief: RunBrief | null): TaskHandoffCheck[] {
+  const gate = task.qualityGate || null
+  if (!gate?.enabled) return [check('quality-gate', 'Quality gate', 'ok', 'No task-specific gate is enabled.')]
+
+  const checks: TaskHandoffCheck[] = []
+  const resultLength = (task.result || '').trim().length
+  const minResultChars = Math.max(0, Math.trunc(gate.minResultChars ?? 0))
+  if (minResultChars > 0) {
+    checks.push(check(
+      'quality-result',
+      'Result length',
+      resultLength >= minResultChars ? 'ok' : 'warning',
+      resultLength >= minResultChars
+        ? `Result has ${resultLength} characters.`
+        : `Result has ${resultLength} of ${minResultChars} required characters.`,
+    ))
+  }
+
+  const evidenceCount =
+    (Array.isArray(task.outputFiles) ? task.outputFiles.length : 0)
+    + (Array.isArray(task.artifacts) ? task.artifacts.length : 0)
+    + (runBrief?.evidence.length || 0)
+  const minEvidenceItems = Math.max(0, Math.trunc(gate.minEvidenceItems ?? 0))
+  if (minEvidenceItems > 0) {
+    checks.push(check(
+      'quality-evidence',
+      'Evidence',
+      evidenceCount >= minEvidenceItems ? 'ok' : 'warning',
+      evidenceCount >= minEvidenceItems
+        ? `${evidenceCount} evidence signal${evidenceCount === 1 ? '' : 's'} available.`
+        : `${evidenceCount} of ${minEvidenceItems} required evidence signals are available.`,
+    ))
+  }
+
+  if (gate.requireVerification) {
+    const hasVerification = Boolean(compactText(task.verificationSummary, 240) || runBrief?.warnings.length === 0 && runBrief?.status === 'completed')
+    checks.push(check(
+      'quality-verification',
+      'Verification',
+      hasVerification ? 'ok' : 'warning',
+      hasVerification ? 'Verification signal is present.' : 'Add verification notes before handoff.',
+    ))
+  }
+
+  if (gate.requireArtifact) {
+    const artifactCount = Array.isArray(task.artifacts) ? task.artifacts.length : 0
+    checks.push(check(
+      'quality-artifact',
+      'Artifact',
+      artifactCount > 0 ? 'ok' : 'warning',
+      artifactCount > 0 ? `${artifactCount} artifact${artifactCount === 1 ? '' : 's'} attached.` : 'Attach at least one artifact.',
+    ))
+  }
+
+  if (gate.requireReport) {
+    checks.push(check(
+      'quality-report',
+      'Task report',
+      task.completionReportPath ? 'ok' : 'warning',
+      task.completionReportPath ? 'Task report path is present.' : 'Generate or attach a task report.',
+    ))
+  }
+
+  return checks.length > 0 ? checks : [check('quality-gate', 'Quality gate', 'ok', 'Enabled gate has no active requirements.')]
+}
+
+function readinessStatus(checks: TaskHandoffCheck[]): TaskHandoffReadinessStatus {
+  if (checks.some((item) => item.status === 'blocked')) return 'blocked'
+  if (checks.some((item) => item.status === 'warning')) return 'needs_attention'
+  return 'ready'
+}
+
+function recommendedActions(checks: TaskHandoffCheck[]): string[] {
+  const actions: string[] = []
+  for (const item of checks) {
+    if (item.status === 'ok') continue
+    if (item.id === 'dependencies') actions.push('Complete or remove unresolved blockers before queueing the task.')
+    else if (item.id === 'workspace') actions.push('Prepare or refresh the task workspace before handing it to another operator.')
+    else if (item.id === 'liveness') actions.push('Inspect the current run state and clear stale or failed execution before resuming.')
+    else if (item.id.startsWith('quality-')) actions.push(item.detail || 'Resolve the task quality gate before handoff.')
+    else if (item.detail) actions.push(item.detail)
+  }
+  return Array.from(new Set(actions)).slice(0, 8)
+}
+
+export function buildTaskHandoffPacket(
+  task: BoardTask,
+  tasks: Record<string, BoardTask>,
+  options: { now?: number; runBrief?: RunBrief | null } = {},
+): TaskHandoffPacket {
+  const now = options.now ?? Date.now()
+  const liveness = computeTaskLiveness(task, tasks, { now })
+  const blockedBy = (task.blockedBy || []).map((id) => taskRef(id, tasks, now))
+  const blocks = (task.blocks || []).map((id) => taskRef(id, tasks, now))
+  const unresolvedBlockerIds = blockedBy
+    .filter((ref) => ref.status !== 'completed')
+    .map((ref) => ref.id)
+  const runBrief = options.runBrief === undefined ? resolveLatestRunBrief(task) : options.runBrief
+  const gateChecks = qualityChecks(task, runBrief)
+  const executionWorkspace = task.executionWorkspace || null
+  const previewLinks = task.previewLinks && task.previewLinks.length > 0
+    ? task.previewLinks
+    : executionWorkspace?.previewLinks || []
+  const runtimeServices = task.runtimeServices && task.runtimeServices.length > 0
+    ? task.runtimeServices
+    : executionWorkspace?.runtimeServices || []
+
+  const checks: TaskHandoffCheck[] = [
+    check(
+      'owner',
+      'Owner',
+      task.agentId ? 'ok' : 'warning',
+      task.agentId ? `Assigned to ${task.agentId}.` : 'Assign an agent before execution.',
+    ),
+    check(
+      'dependencies',
+      'Dependencies',
+      unresolvedBlockerIds.length > 0 ? 'blocked' : 'ok',
+      unresolvedBlockerIds.length > 0
+        ? `Waiting on ${unresolvedBlockerIds.length} blocker${unresolvedBlockerIds.length === 1 ? '' : 's'}.`
+        : 'No unresolved blockers.',
+      unresolvedBlockerIds,
+    ),
+    check(
+      'workspace',
+      'Execution workspace',
+      executionWorkspace ? 'ok' : 'warning',
+      executionWorkspace ? 'Workspace is prepared.' : 'No task workspace is prepared.',
+    ),
+    check(
+      'liveness',
+      'Liveness',
+      liveness.state === 'failed' || liveness.state === 'dead_lettered' || liveness.state === 'cancelled'
+        ? 'blocked'
+        : liveness.state === 'stale' || liveness.state === 'retrying'
+          ? 'warning'
+          : 'ok',
+      liveness.reason,
+    ),
+    ...gateChecks,
+  ]
+
+  const status = readinessStatus(checks)
+  return {
+    schemaVersion: 1,
+    taskId: task.id,
+    title: task.title || task.id,
+    description: task.description || null,
+    objective: task.objective || null,
+    status: task.status,
+    priority: task.priority,
+    generatedAt: now,
+    updatedAt: task.updatedAt,
+    owner: {
+      agentId: task.agentId || null,
+      projectId: task.projectId || null,
+      sessionId: task.sessionId || null,
+      createdByAgentId: task.createdByAgentId || null,
+      delegatedByAgentId: task.delegatedByAgentId || null,
+    },
+    liveness,
+    execution: {
+      workspacePath: executionWorkspace?.path || null,
+      sourceCwd: executionWorkspace?.sourceCwd || task.cwd || null,
+      mode: executionWorkspace?.mode || null,
+      contextPath: executionWorkspace?.contextPath || null,
+      envPath: executionWorkspace?.envPath || null,
+      previewLinks,
+      runtimeServices,
+    },
+    dependencies: {
+      blockedBy,
+      blocks,
+    },
+    qualityGate: {
+      enabled: Boolean(task.qualityGate?.enabled),
+      config: task.qualityGate || null,
+      checks: gateChecks,
+    },
+    outputs: {
+      result: task.result || null,
+      error: task.error || null,
+      outputFiles: Array.isArray(task.outputFiles) ? task.outputFiles : [],
+      artifacts: Array.isArray(task.artifacts) ? task.artifacts : [],
+      completionReportPath: task.completionReportPath || null,
+      verificationSummary: task.verificationSummary || null,
+    },
+    resume: {
+      cliProvider: task.cliProvider || null,
+      cliResumeId: task.cliResumeId || null,
+      claudeResumeId: task.claudeResumeId || null,
+      codexResumeId: task.codexResumeId || null,
+      opencodeResumeId: task.opencodeResumeId || null,
+      geminiResumeId: task.geminiResumeId || null,
+    },
+    run: runBrief
+      ? {
+          runId: runBrief.runId,
+          sessionId: runBrief.sessionId,
+          title: runBrief.title,
+          status: runBrief.status,
+          result: runBrief.result,
+          error: runBrief.error,
+          warnings: runBrief.warnings,
+          evidenceCount: runBrief.evidence.length,
+        }
+      : null,
+    readiness: {
+      status,
+      checks,
+      recommendedActions: status === 'ready'
+        ? ['Handoff packet is ready to share.']
+        : recommendedActions(checks),
+    },
+  }
+}
+
+function lineForRef(ref: TaskHandoffTaskRef): string {
+  const suffix = ref.liveness?.reason ? `, ${ref.liveness.reason}` : ''
+  return `- ${ref.title} (${ref.id}): ${ref.status}${suffix}`
+}
+
+function appendSection(lines: string[], title: string, body: string[] = []) {
+  lines.push('', `## ${title}`)
+  if (body.length === 0) lines.push('None.')
+  else lines.push(...body)
+}
+
+export function formatTaskHandoffMarkdown(packet: TaskHandoffPacket): string {
+  const lines = [
+    `# Task Handoff: ${packet.title}`,
+    '',
+    `Generated: ${toIso(packet.generatedAt)}`,
+    `Task ID: ${packet.taskId}`,
+    `Status: ${packet.status}`,
+    `Readiness: ${packet.readiness.status}`,
+    `Owner: ${packet.owner.agentId || 'unassigned'}`,
+    `Updated: ${toIso(packet.updatedAt)}`,
+  ]
+
+  const objective = compactText(packet.objective || packet.description, 1400)
+  if (objective) appendSection(lines, 'Objective', [objective])
+
+  appendSection(lines, 'Liveness', [
+    `- State: ${packet.liveness.state}`,
+    `- Reason: ${packet.liveness.reason}`,
+    packet.liveness.nextWakeAt ? `- Next wake: ${toIso(packet.liveness.nextWakeAt)}` : '',
+  ].filter(Boolean))
+
+  appendSection(lines, 'Workspace', [
+    packet.execution.workspacePath ? `- Workspace: ${packet.execution.workspacePath}` : '- Workspace: not prepared',
+    packet.execution.sourceCwd ? `- Source: ${packet.execution.sourceCwd}` : '',
+    packet.execution.contextPath ? `- Context: ${packet.execution.contextPath}` : '',
+    packet.execution.envPath ? `- Env: ${packet.execution.envPath}` : '',
+  ].filter(Boolean))
+
+  appendSection(lines, 'Runtime', [
+    ...packet.execution.previewLinks.map((link) => `- Preview: ${link.label || 'Preview'} ${link.url}`),
+    ...packet.execution.runtimeServices.map((service) => `- Service: ${service.name} (${service.status})${service.url ? ` ${service.url}` : ''}`),
+  ])
+
+  appendSection(lines, 'Dependencies', [
+    ...packet.dependencies.blockedBy.map(lineForRef),
+    ...packet.dependencies.blocks.map((ref) => `- Blocks ${ref.title} (${ref.id}): ${ref.status}`),
+  ])
+
+  appendSection(lines, 'Quality Checks', packet.readiness.checks.map((item) => {
+    const detail = item.detail ? `, ${item.detail}` : ''
+    return `- ${item.label}: ${item.status}${detail}`
+  }))
+
+  appendSection(lines, 'Evidence', [
+    packet.outputs.result ? `- Result: ${compactText(packet.outputs.result, 500)}` : '',
+    packet.outputs.error ? `- Error: ${compactText(packet.outputs.error, 500)}` : '',
+    ...packet.outputs.outputFiles.map((file) => `- Output file: ${file}`),
+    ...packet.outputs.artifacts.map((artifact) => `- Artifact: ${artifact.filename} ${artifact.url}`),
+    packet.outputs.completionReportPath ? `- Task report: ${packet.outputs.completionReportPath}` : '',
+    packet.run ? `- Latest run: ${packet.run.title} (${packet.run.status}, ${packet.run.evidenceCount} evidence items)` : '',
+  ].filter(Boolean))
+
+  appendSection(lines, 'Resume Handles', [
+    packet.resume.cliResumeId ? `- ${packet.resume.cliProvider || 'CLI'}: ${packet.resume.cliResumeId}` : '',
+    packet.resume.claudeResumeId ? `- Claude: ${packet.resume.claudeResumeId}` : '',
+    packet.resume.codexResumeId ? `- Codex: ${packet.resume.codexResumeId}` : '',
+    packet.resume.opencodeResumeId ? `- OpenCode: ${packet.resume.opencodeResumeId}` : '',
+    packet.resume.geminiResumeId ? `- Gemini: ${packet.resume.geminiResumeId}` : '',
+  ].filter(Boolean))
+
+  appendSection(lines, 'Recommended Actions', packet.readiness.recommendedActions.map((action) => `- ${action}`))
+
+  return `${lines.join('\n')}\n`
+}

package/src/lib/tasks.ts

@@ -1,5 +1,5 @@
 import { api } from './app/api-client'
-import type { BoardTask, TaskComment, TaskPreviewLink, TaskRuntimeService } from '../types'
+import type { BoardTask, TaskComment, TaskHandoffPacket, TaskPreviewLink, TaskRuntimeService } from '../types'
 
 export const fetchTasks = (includeArchived = false) =>
   api<Record<string, BoardTask>>('GET', `/tasks${includeArchived ? '?includeArchived=true' : ''}`)
@@ -29,6 +29,14 @@ export interface GitHubIssueImportResult {
   skipped: GitHubIssueImportItem[]
 }
 
+export interface TaskHandoffSnapshotResult {
+  packet: TaskHandoffPacket
+  files: {
+    markdownPath: string
+    jsonPath: string
+  }
+}
+
 export type TaskWriteInput = Partial<BoardTask> & {
   title?: string
   description?: string
@@ -49,6 +57,17 @@ export const createTask = (data: TaskWriteInput & {
 export const updateTask = (id: string, data: TaskWriteInput) =>
   api<BoardTask>('PUT', `/tasks/${id}`, data)
 
+export const fetchTaskHandoff = (id: string) =>
+  api<TaskHandoffPacket>('GET', `/tasks/${encodeURIComponent(id)}/handoff`)
+
+export const fetchTaskHandoffMarkdown = (id: string) =>
+  api<string>('GET', `/tasks/${encodeURIComponent(id)}/handoff?format=markdown`)
+
+export const saveTaskHandoffSnapshot = (id: string, options: { prepareWorkspace?: boolean } = {}) =>
+  api<TaskHandoffSnapshotResult>('POST', `/tasks/${encodeURIComponent(id)}/handoff`, {
+    prepareWorkspace: options.prepareWorkspace ?? true,
+  }, { timeoutMs: 30_000 })
+
 export const deleteTask = (id: string) =>
   api<BoardTask>('DELETE', `/tasks/${id}`)
 

package/src/types/task.ts

@@ -240,3 +240,94 @@ export interface BoardTask {
   /** Customizable workflow state (separate from `status` lifecycle). */
   workflowStateId?: string | null
 }
+
+export type TaskHandoffCheckStatus = 'ok' | 'warning' | 'blocked'
+export type TaskHandoffReadinessStatus = 'ready' | 'needs_attention' | 'blocked'
+
+export interface TaskHandoffTaskRef {
+  id: string
+  title: string
+  status: BoardTaskStatus
+  agentId?: string | null
+  completedAt?: number | null
+  liveness?: TaskLivenessSnapshot | null
+}
+
+export interface TaskHandoffCheck {
+  id: string
+  label: string
+  status: TaskHandoffCheckStatus
+  detail?: string | null
+  taskIds?: string[]
+}
+
+export interface TaskHandoffRunSummary {
+  runId: string
+  sessionId: string
+  title: string
+  status: string
+  result: string | null
+  error: string | null
+  warnings: string[]
+  evidenceCount: number
+}
+
+export interface TaskHandoffPacket {
+  schemaVersion: 1
+  taskId: string
+  title: string
+  description?: string | null
+  objective?: string | null
+  status: BoardTaskStatus
+  priority?: BoardTask['priority']
+  generatedAt: number
+  updatedAt: number
+  owner: {
+    agentId: string | null
+    projectId?: string | null
+    sessionId?: string | null
+    createdByAgentId?: string | null
+    delegatedByAgentId?: string | null
+  }
+  liveness: TaskLivenessSnapshot
+  execution: {
+    workspacePath?: string | null
+    sourceCwd?: string | null
+    mode?: TaskExecutionWorkspaceMode | null
+    contextPath?: string | null
+    envPath?: string | null
+    previewLinks: TaskPreviewLink[]
+    runtimeServices: TaskRuntimeService[]
+  }
+  dependencies: {
+    blockedBy: TaskHandoffTaskRef[]
+    blocks: TaskHandoffTaskRef[]
+  }
+  qualityGate: {
+    enabled: boolean
+    config: TaskQualityGateConfig | null
+    checks: TaskHandoffCheck[]
+  }
+  outputs: {
+    result?: string | null
+    error?: string | null
+    outputFiles: string[]
+    artifacts: NonNullable<BoardTask['artifacts']>
+    completionReportPath?: string | null
+    verificationSummary?: string | null
+  }
+  resume: {
+    cliProvider?: string | null
+    cliResumeId?: string | null
+    claudeResumeId?: string | null
+    codexResumeId?: string | null
+    opencodeResumeId?: string | null
+    geminiResumeId?: string | null
+  }
+  run: TaskHandoffRunSummary | null
+  readiness: {
+    status: TaskHandoffReadinessStatus
+    checks: TaskHandoffCheck[]
+    recommendedActions: string[]
+  }
+}