@swarmclawai/swarmclaw 1.9.14 → 1.9.15

package/README.md

@@ -399,6 +399,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.15 Highlights
+
+Run handoff release: SwarmClaw now turns completed, failed, queued, or running execution records into copyable handoff packets with outcome, evidence, artifacts, timeline, usage, resume commands, and recommended next actions.
+
+- **Run handoff API.** `GET /api/runs/:id/handoff` returns structured handoff JSON, and `?format=markdown` returns copyable markdown.
+- **Run Review copy action.** The run detail sheet exposes a copy handoff button so operators can move outcome evidence into another session without replaying the full event log.
+- **CLI access.** `swarmclaw runs handoff <runId> --query format=markdown` exposes the same packet for scripts and release automation.
+- **Readiness guidance.** Packets mark failed, cancelled, running, warning, or under-evidenced runs as blocked or needing attention before another operator relies on the result.
+
 ### v1.9.14 Highlights
 
 Session context-pack release: SwarmClaw now turns a live chat into a concise handoff packet with session metadata, recent visible turns, linked tasks, attachments, resume handles, and next actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.14",
+  "version": "1.9.15",
   "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",
@@ -88,7 +88,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/chats/session-context-pack.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/quality/architecture-health.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-execution-policy.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-pack-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/chats/session-context-pack.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/runs/run-handoff.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/quality/architecture-health.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-execution-policy.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-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/runs/run-handoff-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/runs/[id]/handoff/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server'
+import { listEvidenceArtifacts } from '@/lib/server/artifacts/artifact-resolver'
+import { buildRunBrief } from '@/lib/server/runs/run-brief'
+import { buildRunHandoffPacket, formatRunHandoffMarkdown } from '@/lib/server/runs/run-handoff'
+import { getUnifiedRunById, listUnifiedRunEvents } from '@/lib/server/runs/unified-run-queries'
+
+export const dynamic = 'force-dynamic'
+
+export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const run = getUnifiedRunById(id)
+  if (!run) return NextResponse.json({ error: 'Run not found' }, { status: 404 })
+
+  const events = listUnifiedRunEvents(id, 300)
+  const brief = buildRunBrief(run, events)
+  const packet = buildRunHandoffPacket(run, brief, listEvidenceArtifacts({ runId: id }))
+  const url = new URL(req.url)
+
+  if (url.searchParams.get('format') === 'markdown') {
+    return new NextResponse(formatRunHandoffMarkdown(packet), {
+      headers: { 'content-type': 'text/markdown; charset=utf-8' },
+    })
+  }
+
+  return NextResponse.json(packet)
+}

package/src/app/api/runs/run-handoff-route.test.ts

@@ -0,0 +1,120 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { runWithTempDataDir } from '@/lib/server/test-utils/run-with-temp-data-dir'
+
+test('GET /api/runs/[id]/handoff returns structured and markdown handoff context', () => {
+  const output = runWithTempDataDir<{
+    status: number
+    markdownStatus: number
+    missingStatus: number
+    schemaVersion: number
+    readiness: string
+    artifactCount: number
+    markdownContentType: string
+    markdownIncludesTitle: boolean
+    markdownIncludesCommand: boolean
+  }>(`
+    const storageMod = await import('./src/lib/server/storage')
+    const ledgerMod = await import('./src/lib/server/runtime/run-ledger')
+    const routeMod = await import('./src/app/api/runs/[id]/handoff/route')
+    const storage = storageMod.default || storageMod
+    const ledger = ledgerMod.default || ledgerMod
+    const route = routeMod.default || routeMod
+
+    const now = Date.now()
+    storage.saveSessions({
+      sess_run_handoff: {
+        id: 'sess_run_handoff',
+        name: 'Run handoff session',
+        cwd: process.env.WORKSPACE_DIR,
+        user: 'tester',
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        messages: [],
+        createdAt: now,
+        lastActiveAt: now,
+      },
+    })
+
+    ledger.persistRun({
+      id: 'run_handoff_1',
+      sessionId: 'sess_run_handoff',
+      source: 'task',
+      internal: false,
+      mode: 'direct',
+      status: 'completed',
+      messagePreview: 'Ship the next fix',
+      queuedAt: now - 5000,
+      startedAt: now - 4000,
+      endedAt: now - 1000,
+      resultPreview: 'Fix shipped and verified.',
+      totalInputTokens: 11,
+      totalOutputTokens: 22,
+      retrievalSummary: { citationCount: 1, sourceIds: ['source_1'] },
+    })
+    ledger.appendPersistedRunEvent({
+      runId: 'run_handoff_1',
+      sessionId: 'sess_run_handoff',
+      phase: 'status',
+      status: 'completed',
+      timestamp: now - 1000,
+      event: { t: 'md', text: 'Fix shipped and verified.' },
+      citations: [{
+        sourceId: 'source_1',
+        sourceTitle: 'Release evidence',
+        sourceKind: 'manual',
+        sourceUrl: 'https://example.test/release',
+        sourceLabel: null,
+        chunkId: 'chunk_1',
+        chunkIndex: 0,
+        chunkCount: 1,
+        charStart: 0,
+        charEnd: 20,
+        sectionLabel: null,
+        snippet: 'Release checks passed.',
+        whyMatched: null,
+        score: 0.9,
+      }],
+    })
+
+    const response = await route.GET(
+      new Request('http://local/api/runs/run_handoff_1/handoff'),
+      { params: Promise.resolve({ id: 'run_handoff_1' }) },
+    )
+    const payload = await response.json()
+
+    const markdownResponse = await route.GET(
+      new Request('http://local/api/runs/run_handoff_1/handoff?format=markdown'),
+      { params: Promise.resolve({ id: 'run_handoff_1' }) },
+    )
+    const markdown = await markdownResponse.text()
+
+    const missingResponse = await route.GET(
+      new Request('http://local/api/runs/missing/handoff'),
+      { params: Promise.resolve({ id: 'missing' }) },
+    )
+
+    console.log(JSON.stringify({
+      status: response.status,
+      markdownStatus: markdownResponse.status,
+      missingStatus: missingResponse.status,
+      schemaVersion: payload.schemaVersion,
+      readiness: payload.readiness.status,
+      artifactCount: payload.artifacts.length,
+      markdownContentType: markdownResponse.headers.get('content-type') || '',
+      markdownIncludesTitle: markdown.includes('# Run Handoff: Ship the next fix'),
+      markdownIncludesCommand: markdown.includes('swarmclaw runs handoff run_handoff_1'),
+    }))
+  `, { prefix: 'swarmclaw-run-handoff-route-' })
+
+  assert.equal(output.status, 200)
+  assert.equal(output.markdownStatus, 200)
+  assert.equal(output.missingStatus, 404)
+  assert.equal(output.schemaVersion, 1)
+  assert.equal(output.readiness, 'ready')
+  assert.equal(output.artifactCount >= 1, true)
+  assert.match(output.markdownContentType, /text\/markdown/)
+  assert.equal(output.markdownIncludesTitle, true)
+  assert.equal(output.markdownIncludesCommand, true)
+})

package/src/cli/index.js

@@ -572,6 +572,7 @@ const COMMAND_GROUPS = [
       cmd('get', 'GET', '/runs/:id', 'Get run by id'),
       cmd('events', 'GET', '/runs/:id/events', 'Get run event history by run id'),
       cmd('brief', 'GET', '/runs/:id/brief', 'Get deterministic run brief by run id'),
+      cmd('handoff', 'GET', '/runs/:id/handoff', 'Get run handoff packet by run id'),
     ],
   },
   {

package/src/cli/spec.js

@@ -552,6 +552,7 @@ const COMMAND_GROUPS = {
       get: { description: 'Get run by id', method: 'GET', path: '/runs/:id', params: ['id'] },
       events: { description: 'Get run event history by run id', method: 'GET', path: '/runs/:id/events', params: ['id'] },
       brief: { description: 'Get deterministic run brief by run id', method: 'GET', path: '/runs/:id/brief', params: ['id'] },
+      handoff: { description: 'Get run handoff packet by run id', method: 'GET', path: '/runs/:id/handoff', params: ['id'] },
     },
   },
   webhooks: {

package/src/components/runs/run-list.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { useEffect, useMemo, useState, useCallback } from 'react'
+import { ClipboardList } from 'lucide-react'
 import { api } from '@/lib/app/api-client'
 import { useNow } from '@/hooks/use-now'
 import { useWs } from '@/hooks/use-ws'
@@ -10,6 +11,7 @@ import type { EvidenceArtifact, RunBrief, RunEventRecord, SessionRunRecord, Sess
 import { PageLoader } from '@/components/ui/page-loader'
 import { formatElapsed } from '@/lib/format-display'
 import { GroundingPanel } from '@/components/knowledge/grounding-panel'
+import { copyTextToClipboard } from '@/lib/clipboard'
 
 const STATUS_COLORS: Record<SessionRunStatus, { bg: string; text: string }> = {
   queued: { bg: 'bg-yellow-500/10', text: 'text-yellow-400' },
@@ -47,6 +49,9 @@ export function RunList() {
   const [eventsLoading, setEventsLoading] = useState(false)
   const [briefLoading, setBriefLoading] = useState(false)
   const [artifactsLoading, setArtifactsLoading] = useState(false)
+  const [handoffCopying, setHandoffCopying] = useState(false)
+  const [handoffCopied, setHandoffCopied] = useState(false)
+  const [handoffError, setHandoffError] = useState<string | null>(null)
 
   const fetchRuns = useCallback(async () => {
     try {
@@ -57,7 +62,6 @@ export function RunList() {
   }, [])
 
   useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect
     fetchRuns()
   }, [fetchRuns])
 
@@ -102,8 +106,30 @@ export function RunList() {
     setEventsLoading(true)
     setBriefLoading(true)
     setArtifactsLoading(true)
+    setHandoffCopied(false)
+    setHandoffError(null)
   }, [])
 
+  const copyRunHandoff = useCallback(async () => {
+    if (!selected || handoffCopying) return
+    setHandoffCopying(true)
+    setHandoffError(null)
+    try {
+      const markdown = await api<string>('GET', `/runs/${selected.id}/handoff?format=markdown`)
+      const copied = await copyTextToClipboard(markdown)
+      if (!copied) {
+        setHandoffError('Clipboard unavailable.')
+        return
+      }
+      setHandoffCopied(true)
+      setTimeout(() => setHandoffCopied(false), 2000)
+    } catch {
+      setHandoffError('Could not copy handoff.')
+    } finally {
+      setHandoffCopying(false)
+    }
+  }, [handoffCopying, selected])
+
   const sources = useMemo(() => {
     return Array.from(new Set(runs.map((run) => run.source).filter(Boolean))).sort((a, b) => a.localeCompare(b))
   }, [runs])
@@ -248,12 +274,24 @@ export function RunList() {
         {selected && (
           <div style={{ animation: 'fade-in 0.3s ease' }}>
             <div className="mb-6">
-              <div className="flex items-center gap-3 mb-3">
-                <span className={`text-[11px] font-700 uppercase tracking-wider px-2.5 py-1 rounded-[6px] ${STATUS_COLORS[selected.status].bg} ${STATUS_COLORS[selected.status].text}`}>
-                  {selected.status}
-                </span>
-                <span className="text-[12px] font-mono text-text-3/60">{selected.source}</span>
+              <div className="mb-3 flex flex-wrap items-center gap-3">
+                <div className="flex min-w-0 items-center gap-3">
+                  <span className={`text-[11px] font-700 uppercase tracking-wider px-2.5 py-1 rounded-[6px] ${STATUS_COLORS[selected.status].bg} ${STATUS_COLORS[selected.status].text}`}>
+                    {selected.status}
+                  </span>
+                  <span className="text-[12px] font-mono text-text-3/60">{selected.source}</span>
+                </div>
+                <button
+                  type="button"
+                  onClick={copyRunHandoff}
+                  disabled={handoffCopying}
+                  className="ml-auto inline-flex items-center gap-1.5 rounded-[8px] border border-white/[0.07] bg-white/[0.04] px-2.5 py-1.5 text-[11px] font-700 text-text-2 transition-colors hover:bg-white/[0.07] disabled:cursor-not-allowed disabled:opacity-60"
+                >
+                  <ClipboardList size={13} />
+                  {handoffCopied ? 'Copied' : handoffCopying ? 'Copying...' : 'Copy Handoff'}
+                </button>
               </div>
+              {handoffError && <p className="mb-3 text-[11px] font-600 text-red-400">{handoffError}</p>}
               <h2 className="font-display text-[20px] font-700 tracking-[-0.02em] mb-2 leading-snug">
                 Run Details
               </h2>

package/src/lib/server/agents/main-agent-loop.test.ts

@@ -307,7 +307,7 @@ describe('main-agent-loop', () => {
           agentId: 'agent-a',
           taskIds: [],
           currentStep: 'Verify the release checklist',
-          plannerSummary: 'Use the mission controller instead of legacy tags.',
+          plannerSummary: 'Use the mission runtime instead of legacy tags.',
           verifierSummary: null,
           blockerSummary: null,
           waitState: null,

package/src/lib/server/runs/run-handoff.test.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+
+import {
+  buildRunHandoffPacket,
+  formatRunHandoffMarkdown,
+} from './run-handoff'
+import type { EvidenceArtifact, RunBrief, SessionRunRecord } from '@/types'
+
+function run(overrides: Partial<SessionRunRecord> = {}): SessionRunRecord {
+  return {
+    id: overrides.id || 'run_1',
+    sessionId: overrides.sessionId || 'sess_1',
+    source: overrides.source || 'task',
+    internal: overrides.internal ?? false,
+    mode: overrides.mode || 'direct',
+    status: overrides.status || 'completed',
+    messagePreview: overrides.messagePreview || 'Verify the release',
+    queuedAt: overrides.queuedAt ?? 1000,
+    startedAt: overrides.startedAt ?? 1500,
+    endedAt: overrides.endedAt ?? 4500,
+    resultPreview: overrides.resultPreview || 'Release verified with browser smoke evidence.',
+    ownerType: overrides.ownerType ?? 'task',
+    ownerId: overrides.ownerId ?? 'task_1',
+    ...overrides,
+  }
+}
+
+function brief(overrides: Partial<RunBrief> = {}): RunBrief {
+  return {
+    runId: overrides.runId || 'run_1',
+    sessionId: overrides.sessionId || 'sess_1',
+    title: overrides.title || 'Verify the release',
+    objective: overrides.objective || 'Verify the release',
+    status: overrides.status || 'completed',
+    source: overrides.source || 'task',
+    owner: overrides.owner ?? { type: 'task', id: 'task_1' },
+    timeline: overrides.timeline || [
+      { label: 'Queued', status: 'queued', at: 1000 },
+      { label: 'Started', status: 'running', at: 1500 },
+      { label: 'Ended', status: 'completed', at: 4500 },
+    ],
+    result: overrides.result ?? 'Release verified with browser smoke evidence.',
+    error: overrides.error ?? null,
+    warnings: overrides.warnings || [],
+    usage: overrides.usage || {
+      inputTokens: 10,
+      outputTokens: 20,
+      estimatedCost: 0.01,
+      citationCount: 1,
+      sourceIds: ['source_1'],
+    },
+    evidence: overrides.evidence || [{
+      id: 'evidence_1',
+      kind: 'event',
+      title: 'Smoke test',
+      summary: 'Browser smoke passed.',
+      createdAt: 4300,
+    }],
+    generatedAt: overrides.generatedAt ?? 5000,
+  }
+}
+
+function artifact(overrides: Partial<EvidenceArtifact> = {}): EvidenceArtifact {
+  return {
+    id: overrides.id || 'artifact_1',
+    kind: overrides.kind || 'run_result',
+    title: overrides.title || 'Run result',
+    preview: overrides.preview || 'Release verified.',
+    createdAt: overrides.createdAt ?? 4500,
+    source: overrides.source || { type: 'run', id: 'run_1', label: 'Verify the release' },
+    ...overrides,
+  }
+}
+
+describe('run handoff packets', () => {
+  it('summarizes a completed run with evidence, artifacts, and resume commands', () => {
+    const packet = buildRunHandoffPacket(run(), brief(), [artifact()], 6000)
+
+    assert.equal(packet.schemaVersion, 1)
+    assert.equal(packet.runId, 'run_1')
+    assert.equal(packet.readiness.status, 'ready')
+    assert.equal(packet.timing.durationMs, 3000)
+    assert.equal(packet.evidence.length, 1)
+    assert.equal(packet.artifacts.length, 1)
+    assert.ok(packet.resume.commands.some((command) => command.includes('swarmclaw runs handoff run_1')))
+    assert.deepEqual(packet.readiness.recommendedActions, ['Handoff packet is ready to share.'])
+  })
+
+  it('marks failed and under-evidenced runs as needing attention', () => {
+    const packet = buildRunHandoffPacket(
+      run({ status: 'failed', error: 'Provider timed out.', resultPreview: undefined }),
+      brief({ status: 'failed', result: null, error: 'Provider timed out.', warnings: ['Run failed and needs review before using the result.'], evidence: [] }),
+      [],
+      6000,
+    )
+
+    assert.equal(packet.readiness.status, 'blocked')
+    assert.ok(packet.readiness.recommendedActions.some((action) => action.includes('Review the run error')))
+    assert.ok(packet.outcome.warnings.length > 0)
+  })
+
+  it('formats concise markdown for handoff into another operator context', () => {
+    const markdown = formatRunHandoffMarkdown(buildRunHandoffPacket(run(), brief(), [artifact({ url: '/api/files/serve?path=result.md' })], 6000))
+
+    assert.match(markdown, /^# Run Handoff: Verify the release/)
+    assert.match(markdown, /Run ID: run_1/)
+    assert.match(markdown, /## Outcome/)
+    assert.match(markdown, /Browser smoke passed/)
+    assert.match(markdown, /swarmclaw chats context-pack sess_1/)
+  })
+})

package/src/lib/server/runs/run-handoff.ts

@@ -0,0 +1,171 @@
+import type { EvidenceArtifact, RunBrief, RunHandoffPacket, RunHandoffReadinessStatus, SessionRunRecord } from '@/types'
+
+const MAX_TEXT = 900
+const MAX_EVIDENCE = 12
+const MAX_ARTIFACTS = 16
+
+function compactText(value: string | null | undefined, maxChars = MAX_TEXT): string | 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 durationMs(run: SessionRunRecord, now: number): number | null {
+  if (!run.startedAt) return null
+  const end = run.endedAt || now
+  if (!Number.isFinite(end) || end < run.startedAt) return null
+  return Math.max(0, Math.trunc(end - run.startedAt))
+}
+
+function readinessStatus(run: SessionRunRecord, brief: RunBrief, artifacts: EvidenceArtifact[]): RunHandoffReadinessStatus {
+  if (run.status === 'failed') return 'blocked'
+  if (run.status === 'cancelled') return 'needs_attention'
+  if (run.status === 'queued' || run.status === 'running') return 'needs_attention'
+  if (brief.warnings.length > 0) return 'needs_attention'
+  if (!compactText(brief.result || run.resultPreview)) return 'needs_attention'
+  if (brief.evidence.length === 0 && artifacts.length === 0) return 'needs_attention'
+  return 'ready'
+}
+
+function recommendedActions(run: SessionRunRecord, brief: RunBrief, artifacts: EvidenceArtifact[]): string[] {
+  const actions: string[] = []
+  if (run.status === 'failed') actions.push('Review the run error, fix the cause, then rerun from the source session or owner.')
+  if (run.status === 'cancelled') actions.push('Review why the run was cancelled before continuing the handoff.')
+  if (run.status === 'queued' || run.status === 'running') actions.push('Wait for the run to finish or cancel it before using the result as final.')
+  if (!compactText(brief.result || run.resultPreview) && run.status === 'completed') actions.push('Record a result summary before sharing this run.')
+  if (brief.evidence.length === 0 && artifacts.length === 0 && run.status === 'completed') {
+    actions.push('Attach evidence, artifacts, or a task report if another operator will continue from this run.')
+  }
+  for (const warning of brief.warnings) {
+    actions.push(warning)
+  }
+  return actions.length > 0 ? Array.from(new Set(actions)).slice(0, 8) : ['Handoff packet is ready to share.']
+}
+
+function resumeCommands(run: SessionRunRecord): string[] {
+  return [
+    `swarmclaw runs handoff ${run.id} --query format=markdown`,
+    `swarmclaw runs brief ${run.id}`,
+    `swarmclaw chats context-pack ${run.sessionId} --query format=markdown`,
+  ]
+}
+
+export function buildRunHandoffPacket(
+  run: SessionRunRecord,
+  brief: RunBrief,
+  artifacts: EvidenceArtifact[] = [],
+  now = Date.now(),
+): RunHandoffPacket {
+  const limitedArtifacts = artifacts.slice(0, MAX_ARTIFACTS)
+  return {
+    schemaVersion: 1,
+    runId: run.id,
+    sessionId: run.sessionId,
+    title: compactText(brief.title || run.messagePreview, 160) || run.id,
+    objective: compactText(brief.objective || run.messagePreview, 1400) || run.source,
+    source: run.source,
+    mode: run.mode,
+    status: run.status,
+    owner: brief.owner || (run.ownerType && run.ownerId ? { type: run.ownerType, id: run.ownerId } : null),
+    generatedAt: now,
+    timing: {
+      queuedAt: run.queuedAt,
+      startedAt: run.startedAt || null,
+      endedAt: run.endedAt || null,
+      durationMs: durationMs(run, now),
+    },
+    outcome: {
+      result: compactText(brief.result || run.resultPreview, 1400),
+      error: compactText(brief.error || run.error, 1400),
+      warnings: brief.warnings.slice(0, 12),
+    },
+    usage: brief.usage,
+    timeline: brief.timeline.slice(0, 20),
+    evidence: brief.evidence.slice(0, MAX_EVIDENCE),
+    artifacts: limitedArtifacts,
+    resume: {
+      sessionId: run.sessionId,
+      commands: resumeCommands(run),
+      links: [
+        { label: 'Run events', href: `/api/runs/${encodeURIComponent(run.id)}/events` },
+        { label: 'Run brief', href: `/api/runs/${encodeURIComponent(run.id)}/brief` },
+        { label: 'Session context pack', href: `/api/chats/${encodeURIComponent(run.sessionId)}/context-pack?format=markdown` },
+      ],
+    },
+    readiness: {
+      status: readinessStatus(run, brief, limitedArtifacts),
+      recommendedActions: recommendedActions(run, brief, limitedArtifacts),
+    },
+  }
+}
+
+function appendSection(lines: string[], title: string, body: string[] = []) {
+  lines.push('', `## ${title}`)
+  if (body.length === 0) lines.push('None.')
+  else lines.push(...body)
+}
+
+function artifactLine(artifact: EvidenceArtifact): string {
+  const target = artifact.url || artifact.href || ''
+  const preview = compactText(artifact.preview || artifact.description, 280)
+  return `- ${artifact.title} (${artifact.kind})${target ? ` ${target}` : ''}${preview ? `: ${preview}` : ''}`
+}
+
+export function formatRunHandoffMarkdown(packet: RunHandoffPacket): string {
+  const owner = packet.owner ? `${packet.owner.type}:${packet.owner.id}` : 'unassigned'
+  const duration = packet.timing.durationMs == null ? 'n/a' : `${Math.round(packet.timing.durationMs / 1000)}s`
+  const lines = [
+    `# Run Handoff: ${packet.title}`,
+    '',
+    `Generated: ${toIso(packet.generatedAt)}`,
+    `Run ID: ${packet.runId}`,
+    `Session ID: ${packet.sessionId}`,
+    `Status: ${packet.status}`,
+    `Readiness: ${packet.readiness.status}`,
+    `Source: ${packet.source}`,
+    `Owner: ${owner}`,
+    `Duration: ${duration}`,
+  ]
+
+  appendSection(lines, 'Objective', [packet.objective])
+
+  appendSection(lines, 'Outcome', [
+    packet.outcome.result ? `- Result: ${packet.outcome.result}` : '',
+    packet.outcome.error ? `- Error: ${packet.outcome.error}` : '',
+    ...packet.outcome.warnings.map((warning) => `- Warning: ${warning}`),
+  ].filter(Boolean))
+
+  appendSection(lines, 'Timeline', packet.timeline.map((item) => {
+    const status = item.status ? ` (${item.status})` : ''
+    const detail = item.detail ? `: ${compactText(item.detail, 260)}` : ''
+    return `- ${item.label}${status} at ${toIso(item.at)}${detail}`
+  }))
+
+  appendSection(lines, 'Evidence', packet.evidence.map((item) => {
+    const url = item.url ? ` ${item.url}` : ''
+    return `- ${item.title} (${item.kind})${url}: ${item.summary}`
+  }))
+
+  appendSection(lines, 'Artifacts', packet.artifacts.map(artifactLine))
+
+  appendSection(lines, 'Usage', [
+    `- Input tokens: ${packet.usage.inputTokens ?? 0}`,
+    `- Output tokens: ${packet.usage.outputTokens ?? 0}`,
+    packet.usage.estimatedCost != null ? `- Estimated cost: $${packet.usage.estimatedCost.toFixed(4)}` : '',
+    `- Citations: ${packet.usage.citationCount}`,
+    packet.usage.sourceIds.length > 0 ? `- Sources: ${packet.usage.sourceIds.join(', ')}` : '',
+  ].filter(Boolean))
+
+  appendSection(lines, 'Resume', [
+    ...packet.resume.commands.map((command) => `- \`${command}\``),
+    ...packet.resume.links.map((link) => `- ${link.label}: ${link.href}`),
+  ])
+
+  appendSection(lines, 'Recommended Actions', packet.readiness.recommendedActions.map((action) => `- ${action}`))
+
+  return `${lines.join('\n')}\n`
+}

package/src/types/index.ts

@@ -17,6 +17,7 @@ export * from './goal'
 export * from './mission'
 export * from './operations'
 export * from './run-brief'
+export * from './run-handoff'
 export * from './artifact'
 export * from './swarmdock'
 export * from './dream'

package/src/types/run-handoff.ts

@@ -0,0 +1,48 @@
+import type { EvidenceArtifact } from './artifact'
+import type { ExecutionOwnerType, SessionRunStatus } from './run'
+import type { RunBriefEvidenceItem, RunBriefTimelineItem } from './run-brief'
+
+export type RunHandoffReadinessStatus = 'ready' | 'needs_attention' | 'blocked'
+
+export interface RunHandoffPacket {
+  schemaVersion: 1
+  runId: string
+  sessionId: string
+  title: string
+  objective: string
+  source: string
+  mode: string
+  status: SessionRunStatus
+  owner: { type: ExecutionOwnerType; id: string } | null
+  generatedAt: number
+  timing: {
+    queuedAt: number
+    startedAt: number | null
+    endedAt: number | null
+    durationMs: number | null
+  }
+  outcome: {
+    result: string | null
+    error: string | null
+    warnings: string[]
+  }
+  usage: {
+    inputTokens: number | null
+    outputTokens: number | null
+    estimatedCost: number | null
+    citationCount: number
+    sourceIds: string[]
+  }
+  timeline: RunBriefTimelineItem[]
+  evidence: RunBriefEvidenceItem[]
+  artifacts: EvidenceArtifact[]
+  resume: {
+    sessionId: string
+    commands: string[]
+    links: Array<{ label: string; href: string }>
+  }
+  readiness: {
+    status: RunHandoffReadinessStatus
+    recommendedActions: string[]
+  }
+}