@swarmclawai/swarmclaw 1.8.13 → 1.9.1

package/README.md

@@ -399,6 +399,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.1 Highlights
+
+Task execution workspace release: the first Paperclip-style work-control slice for task-scoped workspaces, preview handoffs, and liveness evidence.
+
+- **Task-scoped execution workspaces.** Tasks can now provision a deterministic workspace under the SwarmClaw workspace root, preserving source cwd and project context while creating a task-local README for artifacts and handoffs.
+- **Preview and runtime metadata.** Tasks can carry preview links and runtime services, and the task board surfaces those links directly on task cards and sheets.
+- **Liveness snapshots.** Task list/read responses now compute blocked, queued, stale, retrying, ready, and terminal liveness states so operators can see why work is stopped or ready to run.
+- **Browser smoke coverage.** The browser smoke now creates a workspace-backed task and verifies the task board renders the workspace and liveness chips.
+
 ### v1.8.13 Highlights
 
 Task retry and host execute hotfix for issues [#68](https://github.com/swarmclawai/swarmclaw/issues/68) and [#69](https://github.com/swarmclawai/swarmclaw/issues/69).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.8.13",
+  "version": "1.9.1",
   "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/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/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/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/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/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/session-tools/execute.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/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/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/providers/[id]/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/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/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/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/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/session-tools/execute.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/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/providers/[id]/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/task-workspace-route.test.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, test } 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,
+  SWARMCLAW_DAEMON_AUTOSTART: process.env.SWARMCLAW_DAEMON_AUTOSTART,
+}
+
+let tempDir = ''
+let putTask: typeof import('./[id]/route')['PUT']
+let getTasks: typeof import('./route')['GET']
+let storage: typeof import('@/lib/server/storage')
+
+function routeParams(id: string) {
+  return { params: Promise.resolve({ id }) }
+}
+
+function seedTask(id: string, overrides: Partial<BoardTask> = {}) {
+  const now = Date.now()
+  storage.saveTasks({
+    [id]: {
+      id,
+      title: 'Workspace Task',
+      description: '',
+      status: 'backlog',
+      agentId: 'agent-1',
+      createdAt: now,
+      updatedAt: now,
+      ...overrides,
+    } as BoardTask,
+  })
+}
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-task-route-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  process.env.SWARMCLAW_DAEMON_AUTOSTART = '0'
+  storage = await import('@/lib/server/storage')
+  putTask = (await import('./[id]/route')).PUT
+  getTasks = (await import('./route')).GET
+})
+
+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
+  if (originalEnv.SWARMCLAW_DAEMON_AUTOSTART === undefined) delete process.env.SWARMCLAW_DAEMON_AUTOSTART
+  else process.env.SWARMCLAW_DAEMON_AUTOSTART = originalEnv.SWARMCLAW_DAEMON_AUTOSTART
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+test('PUT /api/tasks/:id provisions an execution workspace and preview links', async () => {
+  seedTask('task-route-workspace', {
+    title: 'Route Workspace',
+    projectId: 'project-route',
+    cwd: '/source/repo',
+  })
+
+  const response = await putTask(new Request('http://local/api/tasks/task-route-workspace', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      provisionWorkspace: true,
+      previewLinks: [{ label: 'Preview', url: 'http://127.0.0.1:3456', port: 3456 }],
+      runtimeServices: [{ name: 'Next dev', status: 'planned', command: 'npm run dev', port: 3456 }],
+    }),
+  }), routeParams('task-route-workspace'))
+
+  assert.equal(response.status, 200)
+  const body = await response.json() as BoardTask
+  assert.equal(body.executionWorkspace?.sourceCwd, '/source/repo')
+  assert.equal(body.previewLinks?.[0]?.url, 'http://127.0.0.1:3456')
+  assert.equal(body.runtimeServices?.[0]?.name, 'Next dev')
+  assert.equal(fs.existsSync(body.executionWorkspace?.path || ''), true)
+})
+
+test('GET /api/tasks returns computed blocked liveness without persisting a task patch', async () => {
+  seedTask('task-blocked', {
+    title: 'Blocked Route Task',
+    status: 'backlog',
+    blockedBy: ['dep-route'],
+  })
+  const tasks = storage.loadTasks()
+  tasks['dep-route'] = {
+    id: 'dep-route',
+    title: 'Dependency',
+    description: '',
+    status: 'running',
+    agentId: 'agent-1',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  } as BoardTask
+  storage.saveTasks(tasks)
+
+  const response = await getTasks(new Request('http://local/api/tasks'))
+  assert.equal(response.status, 200)
+  const body = await response.json() as Record<string, BoardTask>
+  assert.equal(body['task-blocked']?.liveness?.state, 'blocked')
+  assert.deepEqual(body['task-blocked']?.liveness?.blockerTaskIds, ['dep-route'])
+})

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

@@ -1,6 +1,7 @@
 'use client'
 
 import { useState, useCallback, useEffect } from 'react'
+import { Activity, ExternalLink, FolderOpen } from 'lucide-react'
 import { useAppStore } from '@/stores/use-app-store'
 import { useNavigate } from '@/lib/app/navigation'
 import { useUpdateTaskMutation } from '@/features/tasks/queries'
@@ -8,7 +9,7 @@ import { ConfirmDialog } from '@/components/shared/confirm-dialog'
 import { AgentAvatar } from '@/components/agents/agent-avatar'
 import { timeAgo } from '@/lib/time-format'
 import { InfoChip } from '@/components/ui/info-chip'
-import type { Agent, BoardTask, Project } from '@/types'
+import type { Agent, BoardTask, Project, TaskLivenessState } from '@/types'
 
 interface TaskCardProps {
   task: BoardTask
@@ -21,6 +22,22 @@ interface TaskCardProps {
   index?: number
 }
 
+function livenessTone(state: TaskLivenessState | undefined): 'neutral' | 'muted' | 'warning' | 'danger' | 'success' | 'info' | 'purple' | 'accent' {
+  if (state === 'stale' || state === 'retrying') return 'warning'
+  if (state === 'dead_lettered' || state === 'failed') return 'danger'
+  if (state === 'blocked') return 'purple'
+  if (state === 'completed') return 'success'
+  if (state === 'running' || state === 'queued') return 'info'
+  return 'muted'
+}
+
+function livenessLabel(task: BoardTask): string | null {
+  const state = task.liveness?.state
+  if (!state) return null
+  if (state === 'dead_lettered') return 'dead letter'
+  return state.replace(/_/g, ' ')
+}
+
 export function TaskCard({
   task,
   agents,
@@ -71,6 +88,8 @@ export function TaskCard({
   const prio = task.priority && priorityConfig[task.priority]
 
   const isBlocked = Array.isArray(task.blockedBy) && task.blockedBy.length > 0
+  const previewLink = task.previewLinks?.[0] || task.executionWorkspace?.previewLinks?.[0] || null
+  const liveness = livenessLabel(task)
   const isOverdue = task.dueAt
     && task.dueAt < now
     && task.status !== 'completed'
@@ -278,6 +297,35 @@ export function TaskCard({
         </div>
       )}
 
+      {(liveness || task.executionWorkspace || previewLink) && (
+        <div className="flex flex-wrap gap-1.5 mb-3">
+          {liveness && (
+            <InfoChip tone={livenessTone(task.liveness?.state)} title={task.liveness?.reason}>
+              <Activity size={10} />
+              {liveness}
+            </InfoChip>
+          )}
+          {task.executionWorkspace && (
+            <InfoChip tone="accent" title={task.executionWorkspace.path}>
+              <FolderOpen size={10} />
+              workspace
+            </InfoChip>
+          )}
+          {previewLink && (
+            <a
+              href={previewLink.url}
+              target="_blank"
+              rel="noreferrer"
+              onClick={(e) => e.stopPropagation()}
+              className="inline-flex items-center gap-1.5 rounded-[7px] bg-emerald-500/10 px-2 py-1 text-[10px] font-600 text-emerald-300 hover:bg-emerald-500/15"
+            >
+              <ExternalLink size={10} />
+              {previewLink.label || 'Preview'}
+            </a>
+          )}
+        </div>
+      )}
+
       <div className="flex items-center gap-2 flex-wrap">
         {agent && (
           <span className="px-2 py-1 rounded-[6px] bg-accent-soft text-accent-bright text-[11px] font-600">

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

@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo, useRef, useState } from 'react'
 import { useRouter } from 'next/navigation'
+import { Activity, ExternalLink, FolderOpen, PlayCircle } from 'lucide-react'
 import ReactMarkdown from 'react-markdown'
 import remarkGfm from 'remark-gfm'
 import { useAppStore } from '@/stores/use-app-store'
@@ -21,10 +22,11 @@ import { DirBrowser } from '@/components/shared/dir-browser'
 import { SheetFooter } from '@/components/shared/sheet-footer'
 import { inputClass } from '@/components/shared/form-styles'
 import { StructuredSessionLauncher } from '@/components/protocols/structured-session-launcher'
-import type { BoardTask, TaskComment, TaskQualityGateConfig } from '@/types'
+import type { BoardTask, TaskComment, TaskLivenessState, TaskQualityGateConfig } from '@/types'
 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'
 
 function fmtTime(ts: number) {
   const d = new Date(ts)
@@ -44,6 +46,22 @@ function normalizeGateNumber(value: unknown, fallback: number, min: number, max:
   return Math.max(min, Math.min(max, Math.trunc(parsed)))
 }
 
+function livenessTone(state?: TaskLivenessState): 'neutral' | 'muted' | 'warning' | 'danger' | 'success' | 'info' | 'purple' | 'accent' {
+  if (state === 'stale' || state === 'retrying') return 'warning'
+  if (state === 'dead_lettered' || state === 'failed') return 'danger'
+  if (state === 'blocked') return 'purple'
+  if (state === 'completed') return 'success'
+  if (state === 'running' || state === 'queued') return 'info'
+  return 'muted'
+}
+
+function livenessLabel(task: BoardTask): string {
+  const state = task.liveness?.state
+  if (!state) return 'unknown'
+  if (state === 'dead_lettered') return 'dead letter'
+  return state.replace(/_/g, ' ')
+}
+
 export function TaskSheet() {
   const router = useRouter()
   const open = useAppStore((s) => s.taskSheetOpen)
@@ -85,6 +103,8 @@ export function TaskSheet() {
   const [qualityGateRequireVerification, setQualityGateRequireVerification] = useState(false)
   const [qualityGateRequireArtifact, setQualityGateRequireArtifact] = useState(false)
   const [qualityGateRequireReport, setQualityGateRequireReport] = useState(false)
+  const [provisionWorkspace, setProvisionWorkspace] = useState(false)
+  const [workspacePreparing, setWorkspacePreparing] = useState(false)
   const [structuredSessionOpen, setStructuredSessionOpen] = useState(false)
   const formInitRef = useRef<string | null>(null)
 
@@ -139,6 +159,7 @@ export function TaskSheet() {
       setQualityGateRequireVerification(gate?.requireVerification ?? defaultGateRequireVerification)
       setQualityGateRequireArtifact(gate?.requireArtifact ?? defaultGateRequireArtifact)
       setQualityGateRequireReport(gate?.requireReport ?? defaultGateRequireReport)
+      setProvisionWorkspace(false)
       formInitRef.current = initKey
       return
     }
@@ -163,6 +184,7 @@ export function TaskSheet() {
     setQualityGateRequireVerification(defaultGateRequireVerification)
     setQualityGateRequireArtifact(defaultGateRequireArtifact)
     setQualityGateRequireReport(defaultGateRequireReport)
+    setProvisionWorkspace(false)
     formInitRef.current = initKey
   }, [
     activeProjectFilter,
@@ -212,6 +234,7 @@ export function TaskSheet() {
       customFields: Object.keys(customFields).length > 0 ? customFields : undefined,
       priority: priority || undefined,
       qualityGate,
+      provisionWorkspace: !editing && provisionWorkspace ? true : undefined,
     } as Partial<BoardTask> & { title: string; description: string; agentId: string }
     try {
       if (editing) {
@@ -263,6 +286,19 @@ export function TaskSheet() {
     }
   }
 
+  const handlePrepareWorkspace = async () => {
+    if (!editing) return
+    setWorkspacePreparing(true)
+    try {
+      await updateTaskMutation.mutateAsync({ id: editing.id, patch: { provisionWorkspace: true } })
+      setDepError(null)
+    } catch (err: unknown) {
+      setDepError(errorMessage(err))
+    } finally {
+      setWorkspacePreparing(false)
+    }
+  }
+
   const handleUnarchive = async () => {
     if (editing) {
       await updateTaskMutation.mutateAsync({ id: editing.id, patch: { status: 'backlog' } })
@@ -307,6 +343,16 @@ export function TaskSheet() {
 
   const taskAgent = editing ? agents[editing.agentId] : null
   const taskProject = editing?.projectId ? projects[editing.projectId] : null
+  const previewLinks = editing
+    ? (editing.previewLinks && editing.previewLinks.length > 0
+      ? editing.previewLinks
+      : editing.executionWorkspace?.previewLinks || [])
+    : []
+  const runtimeServices = editing
+    ? (editing.runtimeServices && editing.runtimeServices.length > 0
+      ? editing.runtimeServices
+      : editing.executionWorkspace?.runtimeServices || [])
+    : []
 
   /* ───── View-only mode ───── */
   if (viewOnly && editing) {
@@ -385,6 +431,67 @@ export function TaskSheet() {
           </div>
         )}
 
+        <div className="mb-8">
+          <SectionLabel>Execution</SectionLabel>
+          <div className="rounded-[14px] border border-white/[0.06] bg-surface p-4 space-y-3">
+            <div className="flex flex-wrap items-center gap-2">
+              {editing.liveness && (
+                <InfoChip tone={livenessTone(editing.liveness.state)} title={editing.liveness.reason}>
+                  <Activity size={12} />
+                  {livenessLabel(editing)}
+                </InfoChip>
+              )}
+              {editing.executionWorkspace ? (
+                <InfoChip tone="accent" title={editing.executionWorkspace.path}>
+                  <FolderOpen size={12} />
+                  Workspace ready
+                </InfoChip>
+              ) : (
+                <InfoChip tone="muted">
+                  <FolderOpen size={12} />
+                  No workspace
+                </InfoChip>
+              )}
+              {runtimeServices.map((service) => (
+                <InfoChip key={service.id} tone={service.status === 'running' ? 'success' : service.status === 'failed' ? 'danger' : 'neutral'}>
+                  <PlayCircle size={12} />
+                  {service.name}: {service.status}
+                </InfoChip>
+              ))}
+            </div>
+            {editing.executionWorkspace?.path && (
+              <code className="block text-[12px] text-text-3 font-mono break-all">{editing.executionWorkspace.path}</code>
+            )}
+            {previewLinks.length > 0 && (
+              <div className="flex flex-wrap gap-2">
+                {previewLinks.map((link) => (
+                  <a
+                    key={link.id}
+                    href={link.url}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center gap-1.5 rounded-[8px] bg-emerald-500/10 px-2.5 py-1.5 text-[12px] font-600 text-emerald-300 hover:bg-emerald-500/15"
+                  >
+                    <ExternalLink size={12} />
+                    {link.label || 'Preview'}
+                  </a>
+                ))}
+              </div>
+            )}
+            {!editing.executionWorkspace && (
+              <button
+                onClick={handlePrepareWorkspace}
+                disabled={workspacePreparing}
+                className="inline-flex items-center gap-2 rounded-[10px] border border-accent-bright/20 bg-accent-bright/10 px-3 py-2 text-[12px] font-600 text-accent-bright hover:bg-accent-bright/14 disabled:opacity-50"
+                style={{ fontFamily: 'inherit' }}
+              >
+                <FolderOpen size={13} />
+                {workspacePreparing ? 'Preparing...' : 'Prepare Workspace'}
+              </button>
+            )}
+          </div>
+        </div>
+
         {/* Tags */}
         {editing.tags && editing.tags.length > 0 && (
           <div className="mb-8">
@@ -809,6 +916,71 @@ export function TaskSheet() {
         />
       </div>
 
+      <div className="mb-8">
+        <SectionLabel>Execution Workspace</SectionLabel>
+        {editing ? (
+          <div className="rounded-[14px] border border-white/[0.06] bg-surface p-4 space-y-3">
+            <div className="flex flex-wrap items-center gap-2">
+              {editing.liveness && (
+                <InfoChip tone={livenessTone(editing.liveness.state)} title={editing.liveness.reason}>
+                  <Activity size={12} />
+                  {livenessLabel(editing)}
+                </InfoChip>
+              )}
+              {editing.executionWorkspace ? (
+                <InfoChip tone="accent" title={editing.executionWorkspace.path}>
+                  <FolderOpen size={12} />
+                  Workspace ready
+                </InfoChip>
+              ) : (
+                <InfoChip tone="muted">
+                  <FolderOpen size={12} />
+                  No workspace
+                </InfoChip>
+              )}
+            </div>
+            {editing.executionWorkspace?.path && (
+              <code className="block text-[12px] text-text-3 font-mono break-all">{editing.executionWorkspace.path}</code>
+            )}
+            {previewLinks.length > 0 && (
+              <div className="flex flex-wrap gap-2">
+                {previewLinks.map((link) => (
+                  <a
+                    key={link.id}
+                    href={link.url}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center gap-1.5 rounded-[8px] bg-emerald-500/10 px-2.5 py-1.5 text-[12px] font-600 text-emerald-300 hover:bg-emerald-500/15"
+                  >
+                    <ExternalLink size={12} />
+                    {link.label || 'Preview'}
+                  </a>
+                ))}
+              </div>
+            )}
+            <button
+              onClick={handlePrepareWorkspace}
+              disabled={workspacePreparing}
+              className="inline-flex items-center gap-2 rounded-[10px] border border-accent-bright/20 bg-accent-bright/10 px-3 py-2 text-[12px] font-600 text-accent-bright hover:bg-accent-bright/14 disabled:opacity-50"
+              style={{ fontFamily: 'inherit' }}
+            >
+              <FolderOpen size={13} />
+              {workspacePreparing ? 'Preparing...' : editing.executionWorkspace ? 'Refresh Workspace' : 'Prepare Workspace'}
+            </button>
+          </div>
+        ) : (
+          <label className="flex items-center gap-2 rounded-[14px] border border-white/[0.06] bg-surface px-4 py-3 text-[13px] text-text-2">
+            <input
+              type="checkbox"
+              checked={provisionWorkspace}
+              onChange={(e) => setProvisionWorkspace(e.target.checked)}
+              className="h-4 w-4 rounded border-white/20 accent-accent"
+            />
+            Prepare a task-scoped workspace when this task is created
+          </label>
+        )}
+      </div>
+
       {/* Tags */}
       <div className="mb-8">
         <SectionLabel>Tags <span className="normal-case tracking-normal font-normal text-text-3">(optional)</span></SectionLabel>

package/src/components/ui/info-chip.tsx

@@ -30,11 +30,12 @@ const chipVariants = cva(
 interface InfoChipProps extends VariantProps<typeof chipVariants> {
   children: React.ReactNode
   className?: string
+  title?: string
 }
 
-export function InfoChip({ size, tone, children, className }: InfoChipProps) {
+export function InfoChip({ size, tone, children, className, title }: InfoChipProps) {
   return (
-    <span className={cn(chipVariants({ size, tone }), className)}>
+    <span title={title} className={cn(chipVariants({ size, tone }), className)}>
       {children}
     </span>
   )

package/src/features/tasks/queries.ts

@@ -8,6 +8,7 @@ import {
   updateTask,
   type GitHubIssueImportRequest,
   type GitHubIssueImportResult,
+  type TaskWriteInput,
 } from '@/lib/tasks'
 import type { BoardTask, BoardTaskStatus, TaskComment } from '@/types'
 
@@ -98,7 +99,7 @@ export function useCreateTaskMutation() {
 export function useUpdateTaskMutation() {
   const queryClient = useQueryClient()
   return useMutation({
-    mutationFn: ({ id, patch }: { id: string; patch: Partial<BoardTask> }) => updateTask(id, patch),
+    mutationFn: ({ id, patch }: { id: string; patch: TaskWriteInput }) => updateTask(id, patch),
     onMutate: async ({ id, patch }) => {
       await queryClient.cancelQueries({ queryKey: taskQueryKeys.lists() })
       const snapshots = patchTaskCaches(queryClient, (current, includeArchived) => {

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,6 +22,11 @@ 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 { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
@@ -60,7 +65,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 +82,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 +111,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 +131,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 +220,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 +371,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({

package/src/lib/tasks.ts

@@ -1,5 +1,5 @@
 import { api } from './app/api-client'
-import type { BoardTask } from '../types'
+import type { BoardTask, TaskComment, TaskPreviewLink, TaskRuntimeService } from '../types'
 
 export const fetchTasks = (includeArchived = false) =>
   api<Record<string, BoardTask>>('GET', `/tasks${includeArchived ? '?includeArchived=true' : ''}`)
@@ -29,16 +29,24 @@ export interface GitHubIssueImportResult {
   skipped: GitHubIssueImportItem[]
 }
 
-export const createTask = (data: {
+export type TaskWriteInput = Partial<BoardTask> & {
+  title?: string
+  description?: string
+  agentId?: string
+  provisionWorkspace?: boolean
+  previewLinks?: Array<Partial<TaskPreviewLink> & { url: string }>
+  runtimeServices?: Array<Partial<TaskRuntimeService>>
+  appendComment?: TaskComment
+}
+
+export const createTask = (data: TaskWriteInput & {
   title: string
   description: string
   agentId: string
-  status?: string
-  qualityGate?: BoardTask['qualityGate']
 }) =>
   api<BoardTask>('POST', '/tasks', data)
 
-export const updateTask = (id: string, data: Partial<BoardTask>) =>
+export const updateTask = (id: string, data: TaskWriteInput) =>
   api<BoardTask>('PUT', `/tasks/${id}`, data)
 
 export const deleteTask = (id: string) =>

package/src/lib/validation/schemas.ts

@@ -200,6 +200,23 @@ export const TaskCreateSchema = z.object({
   retryBackoffSec: z.number().optional(),
   priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
   dueAt: z.number().nullable().optional(),
+  provisionWorkspace: z.boolean().optional(),
+  previewLinks: z.array(z.object({
+    id: z.string().optional(),
+    label: z.string().optional(),
+    url: z.string().min(1),
+    kind: z.enum(['web', 'api', 'docs', 'custom']).optional(),
+    port: z.number().nullable().optional(),
+  })).optional(),
+  runtimeServices: z.array(z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    status: z.enum(['planned', 'running', 'stopped', 'failed', 'unknown']).optional(),
+    command: z.string().nullable().optional(),
+    url: z.string().nullable().optional(),
+    port: z.number().nullable().optional(),
+    startedAt: z.number().nullable().optional(),
+  })).optional(),
   qualityGate: z.object({
     enabled: z.boolean().optional(),
     minResultChars: z.number().optional(),

package/src/types/task.ts

@@ -21,6 +21,64 @@ export interface TaskQualityGateConfig {
   requireReport?: boolean
 }
 
+export type TaskExecutionWorkspaceMode = 'task' | 'project' | 'custom'
+
+export interface TaskPreviewLink {
+  id: string
+  label: string
+  url: string
+  kind: 'web' | 'api' | 'docs' | 'custom'
+  port?: number | null
+  addedAt: number
+}
+
+export interface TaskRuntimeService {
+  id: string
+  name: string
+  status: 'planned' | 'running' | 'stopped' | 'failed' | 'unknown'
+  command?: string | null
+  url?: string | null
+  port?: number | null
+  startedAt?: number | null
+  updatedAt: number
+}
+
+export interface TaskExecutionWorkspace {
+  path: string
+  mode: TaskExecutionWorkspaceMode
+  sourceCwd?: string | null
+  projectId?: string | null
+  preparedAt: number
+  preparedBy?: string | null
+  readmePath?: string | null
+  previewLinks: TaskPreviewLink[]
+  runtimeServices: TaskRuntimeService[]
+}
+
+export type TaskLivenessState =
+  | 'not_started'
+  | 'ready'
+  | 'queued'
+  | 'blocked'
+  | 'running'
+  | 'stale'
+  | 'retrying'
+  | 'dead_lettered'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'archived'
+
+export interface TaskLivenessSnapshot {
+  state: TaskLivenessState
+  reason: string
+  checkedAt: number
+  lastActivityAt?: number | null
+  nextWakeAt?: number | null
+  blockerTaskIds?: string[]
+  staleMs?: number | null
+}
+
 export interface BoardTask {
   id: string
   title: string
@@ -49,6 +107,10 @@ export interface BoardTask {
     type: 'image' | 'video' | 'pdf' | 'file'
     filename: string
   }>
+  executionWorkspace?: TaskExecutionWorkspace | null
+  previewLinks?: TaskPreviewLink[]
+  runtimeServices?: TaskRuntimeService[]
+  liveness?: TaskLivenessSnapshot | null
   comments?: TaskComment[]
   images?: string[]
   createdByAgentId?: string | null