@swarmclawai/swarmclaw 1.9.8 → 1.9.10

package/README.md

@@ -399,6 +399,24 @@ 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.
+
+- **Schedule history ledger.** Schedules now carry a bounded revision history for create, update, archive, restore, skipped, failed, and run-started events.
+- **History console.** The Schedule Console adds a searchable History tab with revision badges, actor labels, and before/after change summaries.
+- **API and CLI access.** `GET /api/schedules/:id/history` and `swarmclaw schedules history <id>` expose the same timeline for scripts and operator audits.
+- **Runtime evidence.** Manual runs and scheduler-fired runs append history entries, while storage normalization caps old entries and keeps legacy schedules compatible.
+
 ### v1.9.8 Highlights
 
 Bundled release-readiness release: a single operator report that combines eval gates, operations blockers, approvals, and runtime readiness.
@@ -703,6 +721,62 @@ Older releases: https://swarmclaw.ai/docs/release-notes
 - npm package: https://www.npmjs.com/package/@swarmclawai/swarmclaw
 - Historical release notes: https://swarmclaw.ai/docs/release-notes
 
+
+## FAQ
+
+### General
+
+**What is SwarmClaw?**
+SwarmClaw is an open-source, self-hosted AI agent runtime and multi-agent framework. It lets you run autonomous AI agents, agent swarms, and orchestrators with durable memory, MCP tools, skills, delegation, schedules, and support for 23+ LLM providers — serving as a practical alternative to Claude Code and LangChain for self-hosted workflows.
+
+**How does SwarmClaw differ from LangChain or CrewAI?**
+SwarmClaw is a self-hosted runtime rather than a code library. It provides a persistent dashboard, durable agent memory, real-time org chart visualization, and built-in multi-agent orchestration with delegation — all running on your own infrastructure. LangChain and CrewAI are code frameworks you embed in your applications; SwarmClaw is the platform your agents run on.
+
+**Is SwarmClaw production-ready?**
+Yes. SwarmClaw is used in production by teams running autonomous agent swarms. It includes security features like approval-gated actions, TLS support, and access key management.
+
+### Setup & Configuration
+
+**How do I install SwarmClaw?**
+Install via npm: `npm install -g @swarmclawai/swarmclaw`, then run `swarmclaw init` to create your configuration. Docker deployment is also available via the provided Docker Compose setup.
+
+**Which LLM providers are supported?**
+SwarmClaw supports 23+ providers including OpenAI, Anthropic (Claude), Google Gemini, OpenRouter, Ollama (local), DeepSeek, Groq, Together AI, and more. Configure your API keys in the `.env` file or via the dashboard.
+
+**Can I use local models?**
+Yes. SwarmClaw integrates with Ollama and other local LLM backends for fully offline agent operation.
+
+### Agent Development
+
+**What is an agent swarm?**
+An agent swarm is a group of AI agents working together under an orchestrator. Each agent has its own role, tools, and memory. The orchestrator delegates tasks, agents execute in parallel, and results are aggregated — mimicking a real organizational structure.
+
+**What are MCP tools?**
+MCP (Model Context Protocol) tools let agents interact with external systems — databases, APIs, file systems, browsers, and more. SwarmClaw provides a marketplace of pre-built MCP tools at SwarmDock.
+
+**How does agent memory work?**
+SwarmClaw provides durable agent memory that persists across sessions. Each agent maintains its own conversation history, learned skills, and context — enabling long-running autonomous workflows.
+
+### Deployment
+
+**How do I deploy SwarmClaw?**
+Options include: local npm installation, Docker Compose for containerized deployment, or cloud VPS with reverse proxy and TLS. See the [deployment docs](https://swarmclaw.ai/docs/deployment) for detailed guides.
+
+**Can I run SwarmClaw in the cloud?**
+Yes. SwarmClaw runs on any Linux server with Node.js 18+. Popular options include AWS EC2, DigitalOcean, Hetzner, and self-hosted on home servers.
+
+### Troubleshooting
+
+**Agent is not responding. What should I check?**
+Verify your LLM API key is valid, check the agent's configuration in the dashboard, and review the agent chat logs for error messages. Common issues include rate limiting and invalid model names.
+
+**How do I update SwarmClaw?**
+Run `npm update -g @swarmclawai/swarmclaw` or pull the latest Docker image. Check the [release notes](https://swarmclaw.ai/docs/release-notes) for breaking changes.
+
+**Where can I get help?**
+- Documentation: https://swarmclaw.ai/docs
+- Discord community: https://discord.gg/sbEavS8cPV
+- GitHub Issues: https://github.com/swarmclawai/swarmclaw/issues
 ## Security Notes
 
 - First run creates an access key; keep it private.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.8",
+  "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/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/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/schedules/[id]/history/route.ts

@@ -0,0 +1,15 @@
+import { NextResponse } from 'next/server'
+import { notFound } from '@/lib/server/collection-helpers'
+import { loadSchedule } from '@/lib/server/schedules/schedule-repository'
+import { normalizeScheduleHistory } from '@/lib/server/schedules/schedule-history'
+
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const schedule = loadSchedule(id)
+  if (!schedule) return notFound()
+  return NextResponse.json({
+    scheduleId: schedule.id,
+    revision: schedule.revision || 0,
+    history: normalizeScheduleHistory(schedule.history),
+  })
+}

package/src/app/api/schedules/[id]/route.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import test, { afterEach } from 'node:test'
 
 import { DELETE as deleteScheduleRoute, PUT as updateSchedule } from './route'
+import { GET as getScheduleHistory } from './history/route'
 import { loadAgents, loadSchedules, saveAgents, saveSchedules } from '@/lib/server/storage'
 
 const originalAgents = loadAgents()
@@ -84,7 +85,7 @@ test('PUT /api/schedules/[id] pauses equivalent reminder schedules together', as
   assert.equal(schedules.two.status, 'paused')
 })
 
-test('DELETE /api/schedules/[id] deletes equivalent reminder schedules together', async () => {
+test('DELETE /api/schedules/[id] archives equivalent reminder schedules together', async () => {
   seedAgent('schedule-route-agent-delete')
   const now = Date.now()
   saveSchedules({
@@ -123,6 +124,54 @@ test('DELETE /api/schedules/[id] deletes equivalent reminder schedules together'
 
   assert.equal(response.status, 200)
   const payload = await response.json() as Record<string, unknown>
-  assert.deepEqual(new Set(payload.deletedIds as string[]), new Set(['one', 'two']))
-  assert.deepEqual(loadSchedules(), {})
+  assert.deepEqual(new Set(payload.archivedIds as string[]), new Set(['one', 'two']))
+  const schedules = loadSchedules()
+  assert.equal(schedules.one.status, 'archived')
+  assert.equal(schedules.two.status, 'archived')
+  assert.equal(schedules.one.history?.[0]?.action, 'archived')
+})
+
+test('GET /api/schedules/[id]/history returns revision history', async () => {
+  const now = Date.now()
+  saveSchedules({
+    one: {
+      id: 'one',
+      name: 'History Schedule',
+      agentId: 'schedule-route-agent-history',
+      taskPrompt: 'Report changes',
+      scheduleType: 'interval',
+      intervalMs: 86_400_000,
+      status: 'active',
+      revision: 2,
+      history: [{
+        id: 'history-2',
+        at: now,
+        actor: 'user',
+        action: 'updated',
+        revision: 2,
+        summary: 'Schedule updated: "History Schedule"',
+        changes: [{
+          field: 'status',
+          label: 'Status',
+          before: 'paused',
+          after: 'active',
+        }],
+      }],
+      createdAt: now,
+      updatedAt: now,
+    },
+  })
+
+  const response = await getScheduleHistory(
+    new Request('http://local/api/schedules/one/history', { method: 'GET' }),
+    routeParams('one'),
+  )
+
+  assert.equal(response.status, 200)
+  const payload = await response.json() as Record<string, unknown>
+  assert.equal(payload.scheduleId, 'one')
+  assert.equal(payload.revision, 2)
+  const history = payload.history as Array<Record<string, unknown>>
+  assert.equal(history.length, 1)
+  assert.equal(history[0].action, 'updated')
 })

package/src/app/api/schedules/schedule-history-route.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import test, { afterEach } from 'node:test'
+
+import { GET as getScheduleHistory } from './[id]/history/route'
+import { loadSchedules, saveSchedules } from '@/lib/server/storage'
+
+const originalSchedules = loadSchedules()
+
+function routeParams(id: string) {
+  return { params: Promise.resolve({ id }) }
+}
+
+afterEach(() => {
+  saveSchedules(originalSchedules)
+})
+
+test('GET /api/schedules/[id]/history returns normalized revision history', async () => {
+  const now = Date.now()
+  saveSchedules({
+    one: {
+      id: 'one',
+      name: 'History Schedule',
+      agentId: 'schedule-route-agent-history',
+      taskPrompt: 'Report changes',
+      scheduleType: 'interval',
+      intervalMs: 86_400_000,
+      status: 'active',
+      revision: 2,
+      history: [{
+        id: 'history-2',
+        at: now,
+        actor: 'user',
+        action: 'updated',
+        revision: 2,
+        summary: 'Schedule updated: "History Schedule"',
+        changes: [{
+          field: 'status',
+          label: 'Status',
+          before: 'paused',
+          after: 'active',
+        }],
+      }],
+      createdAt: now,
+      updatedAt: now,
+    },
+  })
+
+  const response = await getScheduleHistory(
+    new Request('http://local/api/schedules/one/history', { method: 'GET' }),
+    routeParams('one'),
+  )
+
+  assert.equal(response.status, 200)
+  const payload = await response.json() as Record<string, unknown>
+  assert.equal(payload.scheduleId, 'one')
+  assert.equal(payload.revision, 2)
+  const history = payload.history as Array<Record<string, unknown>>
+  assert.equal(history.length, 1)
+  assert.equal(history[0].action, 'updated')
+})

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

@@ -579,6 +579,7 @@ const COMMAND_GROUPS = [
     commands: [
       cmd('list', 'GET', '/schedules', 'List schedules'),
       cmd('get', 'GET', '/schedules/:id', 'Get schedule by id'),
+      cmd('history', 'GET', '/schedules/:id/history', 'Get schedule revision history'),
       cmd('create', 'POST', '/schedules', 'Create schedule', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/schedules/:id', 'Update schedule', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/schedules/:id', 'Delete schedule'),
@@ -734,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/index.ts

@@ -608,6 +608,14 @@ export function buildProgram(): Command {
       await runWithHandler(this as Command, (ctx) => resolveByIdFromCollection(ctx, '/schedules', id))
     })
 
+  schedules
+    .command('history')
+    .description('Get schedule revision history')
+    .argument('<id>', 'Schedule id')
+    .action(async function (id: string) {
+      await runWithHandler(this as Command, (ctx) => apiRequest(ctx, 'GET', `/schedules/${encodeURIComponent(id)}/history`))
+    })
+
   schedules
     .command('create')
     .description('Create schedule')

package/src/cli/spec.js

@@ -420,6 +420,7 @@ const COMMAND_GROUPS = {
       list: { description: 'List schedules', method: 'GET', path: '/schedules' },
       create: { description: 'Create schedule', method: 'POST', path: '/schedules' },
       get: { description: 'Get schedule by id (from list)', virtualGet: true, collectionPath: '/schedules', params: ['id'] },
+      history: { description: 'Get schedule revision history', method: 'GET', path: '/schedules/:id/history', params: ['id'] },
       update: { description: 'Update schedule', method: 'PUT', path: '/schedules/:id', params: ['id'] },
       delete: { description: 'Delete schedule', method: 'DELETE', path: '/schedules/:id', params: ['id'] },
       run: { description: 'Trigger schedule immediately', method: 'POST', path: '/schedules/:id/run', params: ['id'] },
@@ -528,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'] },