@swarmclawai/swarmclaw 1.9.38 → 1.9.39

package/src/lib/server/runtime/scheduled-run-preflight.ts

@@ -0,0 +1,83 @@
+import { getProvider } from '@/lib/providers'
+import { resolveCredentialSecret } from '@/lib/server/credentials/credential-service'
+import { resolveProviderCredentialId } from '@/lib/server/provider-endpoint'
+
+export interface ProviderCredentialPreflightInput {
+  provider?: string | null
+  ollamaMode?: string | null
+  credentialId?: string | null
+  fallbackCredentialIds?: readonly string[] | null
+}
+
+export interface ProviderCredentialPreflightDeps {
+  getProvider: (id: string) => { requiresApiKey?: boolean } | null
+  resolveProviderCredentialId: (input: {
+    provider?: string | null
+    ollamaMode?: string | null
+    credentialId?: string | null
+  }) => string | null
+  resolveCredentialSecret: (credentialId: string | null | undefined) => string | null
+}
+
+export type ProviderCredentialPreflightResult =
+  | { ok: true }
+  | { ok: false; error: string }
+
+/**
+ * Fail-fast credential check for scheduled runs. Catches the "schedule fires
+ * deep into execution and dies on a 401" case before the run starts. No
+ * network calls: it only verifies that at least one credential with a
+ * decryptable secret exists for a provider that requires an API key.
+ *
+ * Deliberately permissive: it passes whenever ANY candidate credential
+ * resolves, so it can only block runs that are guaranteed to fail.
+ */
+export function preflightProviderCredential(
+  input: ProviderCredentialPreflightInput,
+  deps?: Partial<ProviderCredentialPreflightDeps>,
+): ProviderCredentialPreflightResult {
+  const provider = typeof input.provider === 'string' ? input.provider.trim() : ''
+  if (!provider) return { ok: true }
+
+  const resolved: ProviderCredentialPreflightDeps = {
+    getProvider,
+    resolveProviderCredentialId,
+    resolveCredentialSecret,
+    ...deps,
+  }
+
+  let providerConfig: { requiresApiKey?: boolean } | null = null
+  try {
+    providerConfig = resolved.getProvider(provider)
+  } catch {
+    return { ok: true }
+  }
+  // Unknown/custom providers and key-optional providers (ollama, CLI, gateway
+  // routes) are exempt; execution resolves those credentials differently.
+  if (providerConfig?.requiresApiKey !== true) return { ok: true }
+
+  const candidateIds = [
+    resolved.resolveProviderCredentialId({
+      provider,
+      ollamaMode: input.ollamaMode ?? null,
+      credentialId: input.credentialId ?? null,
+    }),
+    ...(input.fallbackCredentialIds || []),
+    // Last resort: any credential stored for this provider
+    input.credentialId
+      ? resolved.resolveProviderCredentialId({ provider, ollamaMode: input.ollamaMode ?? null, credentialId: null })
+      : null,
+  ]
+  const seen = new Set<string>()
+  for (const candidateId of candidateIds) {
+    const id = typeof candidateId === 'string' ? candidateId.trim() : ''
+    if (!id || seen.has(id)) continue
+    seen.add(id)
+    if (resolved.resolveCredentialSecret(id)) return { ok: true }
+  }
+
+  return {
+    ok: false,
+    error: `Provider authentication preflight failed: no API credential configured for provider "${provider}". Add a key in Settings > Providers (or assign one to the agent), then re-run the schedule.`,
+  }
+}

package/src/lib/server/schedules/schedule-lifecycle.test.ts

@@ -177,4 +177,48 @@ describe('schedule lifecycle helpers', () => {
     assert.equal(Boolean(schedules['sched-archived']), false)
     assert.equal(Boolean(schedules['sched-live']), true)
   })
+
+  it('applyScheduleRunOutcome records a successful run and clears the previous error', () => {
+    const schedule = makeSchedule({
+      lastDeliveryStatus: 'error',
+      lastDeliveryError: 'previous failure',
+    }) as unknown as import('@/types').Schedule
+
+    const changed = lifecycle.applyScheduleRunOutcome(schedule, { status: 'completed', error: null }, 500)
+
+    assert.equal(changed, true)
+    assert.equal(schedule.lastDeliveryStatus, 'ok')
+    assert.equal(schedule.lastDeliveryError, null)
+    assert.equal(schedule.lastDeliveredAt, 500)
+    assert.equal(schedule.updatedAt, 500)
+  })
+
+  it('applyScheduleRunOutcome records a failed run with a truncated error', () => {
+    const schedule = makeSchedule() as unknown as import('@/types').Schedule
+    const longError = 'x'.repeat(600)
+
+    const changed = lifecycle.applyScheduleRunOutcome(schedule, { status: 'failed', error: longError }, 700)
+
+    assert.equal(changed, true)
+    assert.equal(schedule.lastDeliveryStatus, 'error')
+    assert.equal(schedule.lastDeliveryError?.length, 500)
+    assert.equal(schedule.lastDeliveredAt, 700)
+  })
+
+  it('applyScheduleRunOutcome uses a fallback message when the task has no error', () => {
+    const schedule = makeSchedule() as unknown as import('@/types').Schedule
+
+    lifecycle.applyScheduleRunOutcome(schedule, { status: 'failed', error: null }, 800)
+
+    assert.match(schedule.lastDeliveryError || '', /Scheduled run failed without a recorded error/)
+  })
+
+  it('applyScheduleRunOutcome ignores non-terminal task statuses', () => {
+    const schedule = makeSchedule() as unknown as import('@/types').Schedule
+
+    const changed = lifecycle.applyScheduleRunOutcome(schedule, { status: 'queued', error: null }, 900)
+
+    assert.equal(changed, false)
+    assert.equal(schedule.lastDeliveryStatus, undefined)
+  })
 })

package/src/lib/server/schedules/schedule-lifecycle.ts

@@ -84,6 +84,33 @@ function disableSessionHeartbeatLocally(
   return true
 }
 
+/**
+ * Records the outcome of a scheduled run on the schedule itself so failures
+ * are visible without digging through the linked task. Returns true when the
+ * schedule was updated and needs to be persisted.
+ */
+export function applyScheduleRunOutcome(
+  schedule: Schedule,
+  task: Pick<BoardTask, 'status' | 'error'>,
+  now: number,
+): boolean {
+  if (task.status === 'completed') {
+    schedule.lastDeliveryStatus = 'ok'
+    schedule.lastDeliveryError = null
+    schedule.lastDeliveredAt = now
+    schedule.updatedAt = now
+    return true
+  }
+  if (task.status === 'failed') {
+    schedule.lastDeliveryStatus = 'error'
+    schedule.lastDeliveryError = (task.error || 'Scheduled run failed without a recorded error.').slice(0, 500)
+    schedule.lastDeliveredAt = now
+    schedule.updatedAt = now
+    return true
+  }
+  return false
+}
+
 function markTaskCancelled(task: BoardTask, reason: string, now: number): void {
   task.status = 'cancelled'
   task.retryScheduledAt = null

package/src/lib/server/storage-normalization.ts

@@ -171,6 +171,19 @@ function normalizeStoredScheduleRecord(value: unknown, loadItem: CollectionItemL
   if (archivedAt != null) schedule.archivedAt = archivedAt
   else delete schedule.archivedAt
 
+  const lastDeliveryStatus = typeof schedule.lastDeliveryStatus === 'string'
+    ? schedule.lastDeliveryStatus.trim().toLowerCase()
+    : ''
+  if (lastDeliveryStatus === 'ok' || lastDeliveryStatus === 'error') {
+    schedule.lastDeliveryStatus = lastDeliveryStatus
+  } else {
+    delete schedule.lastDeliveryStatus
+  }
+
+  const lastDeliveredAt = normalizeStoredScheduleTimestamp(schedule.lastDeliveredAt)
+  if (lastDeliveredAt != null) schedule.lastDeliveredAt = lastDeliveredAt
+  else delete schedule.lastDeliveredAt
+
   const archivedFromStatus = typeof schedule.archivedFromStatus === 'string'
     ? schedule.archivedFromStatus.trim().toLowerCase()
     : ''

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

@@ -596,7 +596,8 @@ describe('task-followups', () => {
   })
 
   describe('taskAlreadyDeliveredToConnectorTarget', () => {
-    it('returns true when the task session already delivered to the same connector target', () => {
+    it('returns true when the task session already delivered to the same connector target', async () => {
+      const { appendMessage } = await import('@/lib/server/messages/message-repository')
       const task = {
         id: 'task-delivered',
         title: 'Delivered task',
@@ -607,27 +608,29 @@ describe('task-followups', () => {
         createdAt: Date.now(),
         updatedAt: Date.now(),
       }
+      // Delivery evidence is read through the repo-backed message reader, so
+      // the message must be seeded via the repository, not inline on the session.
+      appendMessage('task-session', {
+        role: 'assistant',
+        text: 'Sent it.',
+        time: Date.now(),
+        toolEvents: [
+          {
+            name: 'connector_message_tool',
+            input: '{}',
+            output: JSON.stringify({
+              status: 'voice_sent',
+              connectorId: 'conn-wa',
+              to: '447700900111@s.whatsapp.net',
+              messageId: 'msg-1',
+            }),
+          },
+        ],
+      } as import('@/types').Message)
       const sessions = {
         'task-session': {
           id: 'task-session',
-          messages: [
-            {
-              role: 'assistant',
-              text: 'Sent it.',
-              toolEvents: [
-                {
-                  name: 'connector_message_tool',
-                  input: '{}',
-                  output: JSON.stringify({
-                    status: 'voice_sent',
-                    connectorId: 'conn-wa',
-                    to: '447700900111@s.whatsapp.net',
-                    messageId: 'msg-1',
-                  }),
-                },
-              ],
-            },
-          ],
+          messages: [],
         },
       }
       const connectors = {
@@ -657,38 +660,39 @@ describe('task-followups', () => {
       assert.equal(delivered, true)
     })
 
-    it('returns false when connector delivery was to a different target', () => {
+    it('returns false when connector delivery was to a different target', async () => {
+      const { appendMessage } = await import('@/lib/server/messages/message-repository')
       const task = {
         id: 'task-other-target',
         title: 'Other target',
         description: '',
         agentId: 'agent-1',
-        sessionId: 'task-session',
+        sessionId: 'task-session-other',
         status: 'completed' as const,
         createdAt: Date.now(),
         updatedAt: Date.now(),
       }
+      appendMessage('task-session-other', {
+        role: 'assistant',
+        text: 'Sent it.',
+        time: Date.now(),
+        toolEvents: [
+          {
+            name: 'connector_message_tool',
+            input: '{}',
+            output: JSON.stringify({
+              status: 'sent',
+              connectorId: 'conn-wa',
+              to: '447700900222@s.whatsapp.net',
+              messageId: 'msg-2',
+            }),
+          },
+        ],
+      } as import('@/types').Message)
       const sessions = {
-        'task-session': {
-          id: 'task-session',
-          messages: [
-            {
-              role: 'assistant',
-              text: 'Sent it.',
-              toolEvents: [
-                {
-                  name: 'connector_message_tool',
-                  input: '{}',
-                  output: JSON.stringify({
-                    status: 'sent',
-                    connectorId: 'conn-wa',
-                    to: '447700900222@s.whatsapp.net',
-                    messageId: 'msg-2',
-                  }),
-                },
-              ],
-            },
-          ],
+        'task-session-other': {
+          id: 'task-session-other',
+          messages: [],
         },
       }
       const connectors = {
@@ -719,6 +723,85 @@ describe('task-followups', () => {
     })
   })
 
+  // ---- buildTaskFollowupDedupeKey ----
+
+  describe('buildTaskFollowupDedupeKey', () => {
+    it('is scoped to the task, run number, and target', () => {
+      const key = mod.buildTaskFollowupDedupeKey(
+        { id: 'task-1', runNumber: 7, attempts: 2 },
+        { connectorId: 'conn-1', channelId: 'ch-1', threadId: 'th-1' },
+      )
+      assert.equal(key, 'task-followup:task-1:run7:conn-1|ch-1|th-1')
+    })
+
+    it('changes across runs so scheduled reruns can deliver again', () => {
+      const target = { connectorId: 'conn-1', channelId: 'ch-1' }
+      const run1 = mod.buildTaskFollowupDedupeKey({ id: 'task-1', runNumber: 1 }, target)
+      const run2 = mod.buildTaskFollowupDedupeKey({ id: 'task-1', runNumber: 2 }, target)
+      assert.notEqual(run1, run2)
+    })
+
+    it('falls back to attempts, then zero, when runNumber is missing', () => {
+      const target = { connectorId: 'conn-1', channelId: 'ch-1' }
+      assert.equal(
+        mod.buildTaskFollowupDedupeKey({ id: 'task-1', attempts: 3 }, target),
+        'task-followup:task-1:run3:conn-1|ch-1|',
+      )
+      assert.equal(
+        mod.buildTaskFollowupDedupeKey({ id: 'task-1' }, target),
+        'task-followup:task-1:run0:conn-1|ch-1|',
+      )
+    })
+  })
+
+  // ---- outbox-backed follow-up delivery ----
+
+  describe('outbox-backed follow-up delivery', () => {
+    it('stores taskId/scheduleId on the outbox entry and keeps them through normalization', async () => {
+      const outbox = await import('@/lib/server/connectors/outbox')
+      const dedupeKey = 'task-followup:task-evidence:run1:conn-1|ch-1|'
+      outbox.enqueueConnectorOutbox({
+        connectorId: 'conn-1',
+        channelId: 'ch-1',
+        text: 'Task completed: evidence',
+        taskId: 'task-evidence',
+        scheduleId: 'sched-evidence',
+        dedupeKey,
+        sendAt: Date.now() + 60_000,
+      })
+
+      const entry = outbox.findPendingConnectorOutboxByDedupe(dedupeKey)
+      assert.ok(entry)
+      assert.equal(entry!.taskId, 'task-evidence')
+      assert.equal(entry!.scheduleId, 'sched-evidence')
+      assert.equal(entry!.connectorId, 'conn-1')
+      assert.equal(entry!.status, 'pending')
+    })
+
+    it('hasSentConnectorOutboxForDedupe reports successful terminal deliveries', async () => {
+      const outbox = await import('@/lib/server/connectors/outbox')
+      const storage = await import('@/lib/server/storage')
+      const dedupeKey = 'task-followup:task-sent:run1:conn-1|ch-1|'
+      const now = Date.now()
+      storage.upsertConnectorOutboxItem('sent-entry-1', {
+        id: 'sent-entry-1',
+        channelId: 'ch-1',
+        text: 'done',
+        status: 'sent',
+        sendAt: now,
+        createdAt: now,
+        updatedAt: now,
+        attemptCount: 1,
+        maxAttempts: 6,
+        dedupeKey,
+        deliveredAt: now,
+      })
+
+      assert.equal(outbox.hasSentConnectorOutboxForDedupe(dedupeKey), true)
+      assert.equal(outbox.hasSentConnectorOutboxForDedupe('task-followup:other:run1:c|c|'), false)
+    })
+  })
+
   // ---- isSendableAttachment ----
 
   describe('isSendableAttachment', () => {

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

@@ -4,6 +4,7 @@ import type { BoardTask, Connector, MessageToolEvent } from '@/types'
 import { normalizeWhatsappTarget } from '@/lib/server/connectors/response-media'
 import { isDirectConnectorSession } from '@/lib/server/connectors/session-kind'
 import { loadConnectors } from '@/lib/server/connectors/connector-repository'
+import { enqueueConnectorOutbox, hasSentConnectorOutboxForDedupe } from '@/lib/server/connectors/outbox'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { loadSessions } from '@/lib/server/sessions/session-repository'
 import { UPLOAD_DIR } from '@/lib/server/upload-path'
@@ -434,6 +435,23 @@ export function taskAlreadyDeliveredToConnectorTarget(params: {
   return false
 }
 
+/**
+ * Run-scoped dedupe key for a task follow-up delivery. Scheduled reruns reuse
+ * the same linked task id, so the run number keeps each run's follow-up
+ * distinct while suppressing duplicate sends within one run.
+ */
+export function buildTaskFollowupDedupeKey(
+  task: Pick<BoardTask, 'id' | 'runNumber' | 'attempts'>,
+  target: { connectorId: string; channelId: string; threadId?: string | null },
+): string {
+  const run = typeof task.runNumber === 'number'
+    ? task.runNumber
+    : typeof task.attempts === 'number'
+      ? task.attempts
+      : 0
+  return `task-followup:${task.id}:run${run}:${target.connectorId}|${target.channelId}|${target.threadId || ''}`
+}
+
 export async function notifyConnectorTaskFollowups(params: {
   task: BoardTask
   statusLabel: string
@@ -446,7 +464,6 @@ export async function notifyConnectorTaskFollowups(params: {
 
   const connectors = loadConnectors()
   const running = (await import('@/lib/server/connectors/manager')).listRunningConnectors()
-  const manager = await import('@/lib/server/connectors/manager')
   const sessions = loadSessions()
   const targets = collectTaskConnectorFollowupTargets({
     task,
@@ -499,12 +516,20 @@ export async function notifyConnectorTaskFollowups(params: {
     const outboundMessage = `${message}${preferredChannelNote}`
 
     const resolvedMediaPath = mediaPath || maybeResolveUploadMediaPathFromUrl(imageUrl)
+    // Deliver through the connector outbox so every schedule/task follow-up
+    // leaves a durable delivery record (pending/sent/failed with lastError)
+    // and gets retried with backoff instead of one fire-and-forget attempt.
+    const dedupeKey = buildTaskFollowupDedupeKey(task, target)
+    if (hasSentConnectorOutboxForDedupe(dedupeKey)) continue
     try {
-      await manager.sendConnectorMessage({
+      enqueueConnectorOutbox({
         connectorId: target.connectorId,
         channelId: target.channelId,
         threadId: target.threadId || undefined,
         text: outboundMessage,
+        taskId: task.id,
+        scheduleId: typeof task.sourceScheduleId === 'string' ? task.sourceScheduleId : null,
+        dedupeKey,
         ...(resolvedMediaPath
           ? {
               mediaPath: resolvedMediaPath,
@@ -515,7 +540,7 @@ export async function notifyConnectorTaskFollowups(params: {
       })
     } catch (err: unknown) {
       const errMsg = errorMessage(err)
-      log.warn(TAG, `Failed task follow-up send on connector ${target.connectorId}: ${errMsg}`)
+      log.warn(TAG, `Failed to queue task follow-up for connector ${target.connectorId}: ${errMsg}`)
     }
   }
 }

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

@@ -1,8 +1,11 @@
 import assert from 'node:assert/strict'
+import path from 'node:path'
 import { describe, it } from 'node:test'
 
 import type { BoardTask, Schedule } from '@/types'
 
+import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+
 import {
   buildBoardTask,
   didTaskValidationChange,
@@ -109,6 +112,28 @@ describe('task lifecycle helpers', () => {
     assert.equal(task.runNumber, 2)
   })
 
+  it('resetTaskForRerun remaps a legacy workspace cwd onto the current root', () => {
+    const task = makeTask({
+      status: 'failed',
+      cwd: '/root/.swarmclaw/workspace/tasks/task-1',
+    })
+
+    resetTaskForRerun(task, { title: 'Rerun', now: 99 })
+
+    assert.equal(task.cwd, path.join(WORKSPACE_DIR, 'tasks', 'task-1'))
+  })
+
+  it('resetTaskForRerun preserves an intentional custom cwd', () => {
+    const task = makeTask({
+      status: 'failed',
+      cwd: '/home/me/code/myrepo',
+    })
+
+    resetTaskForRerun(task, { title: 'Rerun', now: 99 })
+
+    assert.equal(task.cwd, '/home/me/code/myrepo')
+  })
+
   it('prepareScheduledTaskRun creates a schedule-backed task when no reusable task exists', () => {
     const schedule = makeSchedule({
       createdInSessionId: 'session-1',

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

@@ -8,6 +8,7 @@ import {
   type TaskCompletionValidation,
 } from '@/lib/server/tasks/task-validation'
 import { syncTaskExecutionPolicyState } from '@/lib/server/tasks/task-execution-policy'
+import { normalizeLegacyWorkspacePath } from '@/lib/server/workspace-paths'
 import { createMission, startMission } from '@/lib/server/missions/mission-service'
 import { getMission } from '@/lib/server/missions/mission-repository'
 import { loadSessions } from '@/lib/server/storage'
@@ -74,6 +75,11 @@ export function resetTaskForRerun(task: BoardTask, options: ResetTaskForRerunOpt
   task.retryScheduledAt = null
   task.deadLetteredAt = null
   task.validation = null
+  // Remap cwds persisted under a previous workspace root so reruns don't keep
+  // executing in the pre-migration directory. Custom cwds pass through unchanged.
+  if (typeof task.cwd === 'string' && task.cwd.trim()) {
+    task.cwd = normalizeLegacyWorkspacePath(task.cwd, { taskId: task.id })
+  }
   task.executionPolicyState = syncTaskExecutionPolicyState(task.executionPolicy || null, null, options.now)
   if (options.runNumber !== undefined) stats.runNumber = options.runNumber
   return task

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

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
-import { extractTaskResult } from '@/lib/server/tasks/task-result'
+import { classifyEmptyRunOutcome, extractTaskResult } from '@/lib/server/tasks/task-result'
 
 describe('extractTaskResult', () => {
   it('limits artifact extraction to messages from the current run window', () => {
@@ -38,3 +38,27 @@ describe('extractTaskResult', () => {
     assert.deepEqual(result.artifacts.map((a) => a.url), ['/api/uploads/dated.png'])
   })
 })
+
+describe('classifyEmptyRunOutcome', () => {
+  it('flags a run with no text, no tool calls, and no error', () => {
+    const reason = classifyEmptyRunOutcome({ text: '', error: null, toolEvents: [] })
+    assert.match(reason || '', /Run produced no output/)
+    assert.match(reason || '', /provider credential, model name, and endpoint/)
+  })
+
+  it('returns null when the run produced text', () => {
+    assert.equal(classifyEmptyRunOutcome({ text: 'done', error: null, toolEvents: [] }), null)
+  })
+
+  it('returns null when the run made tool calls', () => {
+    assert.equal(classifyEmptyRunOutcome({ text: '', error: null, toolEvents: [{ name: 'bash' }] }), null)
+  })
+
+  it('returns null when the run reported an error', () => {
+    assert.equal(classifyEmptyRunOutcome({ text: '', error: 'boom', toolEvents: [] }), null)
+  })
+
+  it('treats whitespace-only text as empty', () => {
+    assert.match(classifyEmptyRunOutcome({ text: '  \n ', error: '  ', toolEvents: null }) || '', /Run produced no output/)
+  })
+})

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

@@ -53,6 +53,28 @@ interface ExtractTaskResultOptions {
   sinceTime?: number | null
 }
 
+export interface RunOutputSnapshot {
+  text?: string | null
+  error?: string | null
+  toolEvents?: readonly unknown[] | null
+}
+
+export const EMPTY_RUN_OUTCOME_MESSAGE =
+  'Run produced no output: the model returned no text, made no tool calls, and reported no error. '
+  + "This usually means the provider returned an empty response. Verify the agent's provider credential, model name, and endpoint."
+
+/**
+ * Detects the "silent empty run" case (no text, no tool calls, no error) and
+ * returns an actionable failure reason for it. Returns null when the run
+ * produced any signal at all.
+ */
+export function classifyEmptyRunOutcome(run: RunOutputSnapshot): string | null {
+  if (typeof run.error === 'string' && run.error.trim()) return null
+  if (typeof run.text === 'string' && run.text.trim()) return null
+  if (Array.isArray(run.toolEvents) && run.toolEvents.length > 0) return null
+  return EMPTY_RUN_OUTCOME_MESSAGE
+}
+
 // ---------------------------------------------------------------------------
 // Core extraction
 // ---------------------------------------------------------------------------

package/src/lib/server/workspace-paths.test.ts

@@ -0,0 +1,72 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import os from 'node:os'
+
+import { normalizeLegacyWorkspacePath } from './workspace-paths'
+
+const ROOT = '/app/data/workspace'
+
+test('remaps a legacy .swarmclaw workspace task path onto the current root', () => {
+  assert.equal(
+    normalizeLegacyWorkspacePath('/root/.swarmclaw/workspace/tasks/a974c8b0', { workspaceRoot: ROOT }),
+    path.join(ROOT, 'tasks', 'a974c8b0'),
+  )
+})
+
+test('remaps the home-dir default workspace root', () => {
+  const legacy = path.join(os.homedir(), '.swarmclaw', 'workspace', 'projects', 'site')
+  assert.equal(
+    normalizeLegacyWorkspacePath(legacy, { workspaceRoot: ROOT }),
+    path.join(ROOT, 'projects', 'site'),
+  )
+})
+
+test('remaps a non-.swarmclaw legacy root when the tail matches tasks/<taskId>', () => {
+  assert.equal(
+    normalizeLegacyWorkspacePath('/old/home/workspace/tasks/abc123', { workspaceRoot: ROOT, taskId: 'abc123' }),
+    path.join(ROOT, 'tasks', 'abc123'),
+  )
+})
+
+test('remaps subdirectories under a matching tasks/<taskId> tail', () => {
+  assert.equal(
+    normalizeLegacyWorkspacePath('/old/home/workspace/tasks/abc123/output', { workspaceRoot: ROOT, taskId: 'abc123' }),
+    path.join(ROOT, 'tasks', 'abc123', 'output'),
+  )
+})
+
+test('does not remap when the taskId does not match the tail', () => {
+  const input = '/old/home/workspace/tasks/othertask'
+  assert.equal(normalizeLegacyWorkspacePath(input, { workspaceRoot: ROOT, taskId: 'abc123' }), input)
+})
+
+test('does not remap intentional custom cwds', () => {
+  const input = '/home/me/code/myrepo'
+  assert.equal(normalizeLegacyWorkspacePath(input, { workspaceRoot: ROOT, taskId: 'abc123' }), input)
+})
+
+test('does not remap an unrelated path that merely contains a workspace segment', () => {
+  const input = '/home/me/code/workspace/notes'
+  assert.equal(normalizeLegacyWorkspacePath(input, { workspaceRoot: ROOT }), input)
+})
+
+test('leaves paths already under the current root unchanged', () => {
+  const input = path.join(ROOT, 'tasks', 'abc123')
+  assert.equal(normalizeLegacyWorkspacePath(input, { workspaceRoot: ROOT, taskId: 'abc123' }), input)
+  assert.equal(normalizeLegacyWorkspacePath(ROOT, { workspaceRoot: ROOT }), ROOT)
+})
+
+test('leaves relative and empty inputs unchanged', () => {
+  assert.equal(normalizeLegacyWorkspacePath('relative/dir', { workspaceRoot: ROOT }), 'relative/dir')
+  assert.equal(normalizeLegacyWorkspacePath('', { workspaceRoot: ROOT }), '')
+  assert.equal(normalizeLegacyWorkspacePath(null, { workspaceRoot: ROOT }), '')
+  assert.equal(normalizeLegacyWorkspacePath(undefined, { workspaceRoot: ROOT }), '')
+})
+
+test('remaps a bare legacy root with no tail to the current root', () => {
+  assert.equal(
+    normalizeLegacyWorkspacePath('/root/.swarmclaw/workspace', { workspaceRoot: ROOT }),
+    ROOT,
+  )
+})