@swarmclawai/swarmclaw 1.2.4 → 1.2.5

package/src/lib/server/runtime/queue/core.ts

@@ -13,16 +13,17 @@ import { loadSessions, saveSessions } from '@/lib/server/sessions/session-reposi
 import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { loadTasks, saveTasks } from '@/lib/server/tasks/task-repository'
 import { notify } from '@/lib/server/ws-hub'
+import { getMessages, getLastMessage, appendMessage } from '@/lib/server/messages/message-repository'
 import { perf } from '@/lib/server/runtime/perf'
 import { WORKSPACE_DIR } from '@/lib/server/data-dir'
 import { createAgentTaskSession } from '@/lib/server/agents/task-session'
 import { formatValidationFailure } from '@/lib/server/tasks/task-validation'
 import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-loop'
-import { executeSessionChatTurn, type ExecuteChatTurnResult } from '@/lib/server/chat-execution/chat-execution'
+import type { ExecuteChatTurnResult } from '@/lib/server/chat-execution/chat-execution-types'
 import { checkAgentBudgetLimits } from '@/lib/server/cost'
+import { enqueueExecution } from '@/lib/server/execution-engine'
 import { extractTaskResult, formatResultBody } from '@/lib/server/tasks/task-result'
 import {
-  assessAutonomyRun,
   classifyRuntimeFailure,
   observeAutonomyRunOutcome,
   recordSupervisorIncident,
@@ -40,7 +41,7 @@ import {
 } from '@/lib/server/tasks/task-followups'
 import { getCheckpointSaver } from '@/lib/server/langgraph-checkpoint'
 import { cascadeUnblock } from '@/lib/server/dag-validation'
-import { captureGuardianCheckpoint, prepareGuardianRecovery } from '@/lib/server/agents/guardian'
+import { prepareGuardianRecovery } from '@/lib/server/agents/guardian'
 import { notifyOrchestrators } from '@/lib/server/runtime/orchestrator-events'
 import type { Agent, BoardTask, Message, Session } from '@/types'
 import { buildAgentDisabledMessage, isAgentDisabled } from '@/lib/server/agents/agent-availability'
@@ -549,9 +550,9 @@ function collectTaskResultDeliveryData(
 ): TaskResultDeliveryData {
   const runSessionId = typeof task.sessionId === 'string' ? task.sessionId : ''
   const runSession = runSessionId ? sessions[runSessionId] : null
-  const fallbackText = runSession ? latestAssistantText(runSession) : ''
+  const fallbackText = runSessionId ? latestAssistantText(runSessionId) : ''
   const taskResult = extractTaskResult(
-    runSession,
+    runSessionId ? getMessages(runSessionId) : [],
     task.result || fallbackText || null,
     { sinceTime: typeof task.startedAt === 'number' ? task.startedAt : null },
   )
@@ -606,10 +607,11 @@ function buildTaskTerminalMessage(
   return parts.join('\n\n')
 }
 
-function latestAssistantText(session: SessionLike | null | undefined): string {
-  if (!Array.isArray(session?.messages)) return ''
-  for (let i = session.messages.length - 1; i >= 0; i--) {
-    const msg = session.messages[i]
+function latestAssistantText(sessionId: string | null | undefined): string {
+  if (!sessionId) return ''
+  const messages = getMessages(sessionId)
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]
     if (msg?.role !== 'assistant') continue
     const text = typeof msg?.text === 'string' ? msg.text.trim() : ''
     if (!text) continue
@@ -619,23 +621,6 @@ function latestAssistantText(session: SessionLike | null | undefined): string {
   return ''
 }
 
-// Task result extraction now uses Zod-validated structured data
-// from ./task-result.ts (extractTaskResult, formatResultBody)
-
-/** Check if a task result looks incomplete (agent stopped mid-objective). */
-function looksIncomplete(text: string): boolean {
-  if (!text) return false
-  const trimmed = text.trim()
-  // Ends with ellipsis or continuation signal
-  if (trimmed.endsWith('...') || trimmed.endsWith('…')) return true
-  // Ends with a step/phase header (agent was listing next steps)
-  if (/(?:^|\n)#{1,3}\s+(?:Step|Phase|Next)\s+\d/i.test(trimmed.slice(-200))) return true
-  // Contains forward-looking language at the end
-  const lastChunk = trimmed.slice(-300).toLowerCase()
-  if (/\b(?:next i(?:'ll| will)|now i(?:'ll| will)|let me (?:now|next)|moving on to|proceeding to)\b/.test(lastChunk)) return true
-  return false
-}
-
 function queueTaskAutonomyObservation(input: {
   runId: string
   sessionId: string
@@ -663,128 +648,6 @@ function queueTaskAutonomyObservation(input: {
   })
 }
 
-async function executeTaskRun(
-  task: BoardTask,
-  agent: Agent,
-  sessionId: string,
-): Promise<ExecuteChatTurnResult> {
-  if (agent.autoRecovery) {
-    const cwd = task.projectId
-      ? path.join(WORKSPACE_DIR, 'projects', task.projectId)
-      : WORKSPACE_DIR
-    captureGuardianCheckpoint(cwd, `task:${task.id}`)
-  }
-  const settings = loadSettings()
-  const basePrompt = task.description || task.title
-  const prompt = [
-    basePrompt,
-    '',
-    'Completion requirements:',
-    '- Execute the task before replying; do not reply with only a plan.',
-    '- Include concrete evidence in your final summary: changed file paths, commands run, and verification results.',
-    '- If blocked, state the blocker explicitly and what input or permission is missing.',
-  ].join('\n')
-  // All agents go through the unified chat execution path.
-  // Agents with delegation enabled get delegation tools automatically via session-tools.
-  let latestRun: ExecuteChatTurnResult = await executeSessionChatTurn({
-    sessionId,
-    message: prompt,
-    internal: false,
-    source: 'task',
-    runId: task.id,
-  })
-  let text = typeof latestRun.text === 'string' ? latestRun.text.trim() : ''
-  let previousSummary: string | null = null
-  let totalInputTokens = latestRun.inputTokens || 0
-  let totalOutputTokens = latestRun.outputTokens || 0
-  let totalEstimatedCost = Number(latestRun.estimatedCost || 0)
-  if (latestRun.error) {
-    return {
-      ...latestRun,
-      text,
-    }
-  }
-
-  const maxSupervisorFollowups = 2
-  for (let followupIndex = 0; followupIndex < maxSupervisorFollowups; followupIndex += 1) {
-    const sessions = loadSessions()
-    const session = sessions[sessionId] as unknown as Session | undefined
-    const assessment = assessAutonomyRun({
-      runId: `${task.id}:attempt-${(task.attempts || 0) + 1}:step-${followupIndex + 1}`,
-      sessionId,
-      taskId: task.id,
-      agentId: agent.id,
-      source: 'task',
-      status: latestRun.error ? 'failed' : 'completed',
-      resultText: text,
-      error: latestRun.error,
-      toolEvents: latestRun.toolEvents,
-      mainLoopState: {
-        followupChainCount: followupIndex + 1,
-        summary: previousSummary,
-        missionCostUsd: totalEstimatedCost,
-      },
-      session: session || null,
-      settings,
-    })
-    if (assessment.shouldBlock) break
-    if (assessment.autoActions?.length) {
-      const { executeSupervisorAutoActions } = await import('@/lib/server/autonomy/supervisor-reflection')
-      const result = await executeSupervisorAutoActions({
-        actions: assessment.autoActions,
-        sessionId,
-        agentId: agent?.id,
-      })
-      if (result.blocked) break
-    }
-    const followupMessage = assessment.interventionPrompt
-      || (text && looksIncomplete(text)
-        ? 'Continue and complete the remaining steps. Provide a final summary when done.'
-        : null)
-    if (!followupMessage) break
-
-    // Budget check before follow-up
-    const typedAgentForBudget = agent as Agent
-    if (typedAgentForBudget.monthlyBudget || typedAgentForBudget.dailyBudget || typedAgentForBudget.hourlyBudget) {
-      try {
-        const followupBudget = checkAgentBudgetLimits(typedAgentForBudget)
-        if (!followupBudget.ok) {
-          log.warn(TAG, `[queue] Budget exceeded for "${typedAgentForBudget.name}" during follow-up, stopping.`)
-          break
-        }
-      } catch {}
-    }
-
-    previousSummary = text || previousSummary
-    const followUp = await executeSessionChatTurn({
-      sessionId,
-      message: followupMessage,
-      internal: false,
-      source: 'task',
-    })
-    totalInputTokens += followUp.inputTokens || 0
-    totalOutputTokens += followUp.outputTokens || 0
-    totalEstimatedCost += Number(followUp.estimatedCost || 0)
-    text = typeof followUp.text === 'string' ? followUp.text.trim() : ''
-    latestRun = {
-      ...followUp,
-      text,
-      inputTokens: totalInputTokens,
-      outputTokens: totalOutputTokens,
-      estimatedCost: totalEstimatedCost,
-    }
-    if (latestRun.error) break
-  }
-
-  return {
-    ...latestRun,
-    text,
-    inputTokens: totalInputTokens,
-    outputTokens: totalOutputTokens,
-    estimatedCost: totalEstimatedCost,
-  }
-}
-
 function hasFinishedExecutionSession(session: SessionLike | Session | null | undefined): boolean {
   if (!session) return false
   return session.active === false && !session.currentRunId
@@ -810,7 +673,7 @@ export function reconcileFinishedRunningTasks(): { reconciled: number; deadLette
     const session = sessions[sessionId]
     if (!hasFinishedExecutionSession(session)) continue
 
-    const fallbackText = latestAssistantText(session)
+    const fallbackText = latestAssistantText(sessionId)
     if (!fallbackText && !task.result) {
       task.status = 'failed'
       task.result = 'Agent session finished without producing output.'
@@ -821,7 +684,7 @@ export function reconcileFinishedRunningTasks(): { reconciled: number; deadLette
 
     applyTaskPolicyDefaults(task)
     const taskResult = extractTaskResult(
-      session,
+      getMessages(sessionId),
       task.result || fallbackText || null,
       { sinceTime: typeof task.startedAt === 'number' ? task.startedAt : null },
     )
@@ -930,8 +793,7 @@ function pushUserFacingTaskResult(task: BoardTask, sessions: Record<string, Sess
   const taskLink = `[${task.title}](#task:${task.id})`
   const body = buildTaskTerminalMessage(`Task ${delivery.statusLabel}: **${taskLink}**`, task, delivery)
   const now = Date.now()
-  if (!Array.isArray(targetSession.messages)) targetSession.messages = []
-  const lastMsg = targetSession.messages.at(-1)
+  const lastMsg = getLastMessage(targetSessionId)
   if (lastMsg?.role === 'assistant' && lastMsg?.text === body && typeof lastMsg?.time === 'number' && now - lastMsg.time < 30_000) {
     return
   }
@@ -943,9 +805,7 @@ function pushUserFacingTaskResult(task: BoardTask, sessions: Record<string, Sess
     kind: 'system',
   }
   if (delivery.firstImage) message.imageUrl = delivery.firstImage.url
-  targetSession.messages.push(message)
-  targetSession.lastActiveAt = now
-  saveSessions(sessions as Record<string, Session>)
+  appendMessage(targetSessionId, message)
   notify(`messages:${targetSessionId}`)
 }
 
@@ -1455,32 +1315,33 @@ export async function processNext() {
       })
 
       // Save initial assistant message so user sees context when opening the session
-      const sessions = loadSessions()
-      if (sessions[sessionId]) {
-        const isDelegation = (task as unknown as Record<string, unknown>).sourceType === 'delegation'
-        let initialText: string
-        if (isDelegation) {
-          const delegatorId = (task as unknown as Record<string, unknown>).delegatedByAgentId as string | undefined
-          const delegator = delegatorId ? agents[delegatorId] : null
-          const prefix = `[delegation-source:${delegatorId || ''}:${delegator?.name || 'Agent'}:${delegator?.avatarSeed || ''}]`
-          initialText = `${prefix}\nDelegated by **${delegator?.name || 'another agent'}** | [${task.title}](#task:${task.id})\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`${buildTaskContinuationNote(Boolean(reusedExistingSession), resumeContext)}\n\nI'll begin working on this now.`
-        } else {
-          initialText = `Starting task: **${task.title}**\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`${buildTaskContinuationNote(Boolean(reusedExistingSession), resumeContext)}\n\nI'll begin working on this now.`
-        }
-        // Inject upstream task results context
-        if (Array.isArray(task.upstreamResults) && task.upstreamResults.length > 0) {
-          const upstreamBlock = task.upstreamResults
-            .map((ur) => `### ${ur.taskTitle}\n${ur.resultPreview || '(no result)'}`)
-            .join('\n\n')
-          initialText += `\n\n## Context from upstream tasks\n\n${upstreamBlock}`
+      {
+        const sessionExists = Boolean(loadSessions()[sessionId])
+        if (sessionExists) {
+          const isDelegation = (task as unknown as Record<string, unknown>).sourceType === 'delegation'
+          let initialText: string
+          if (isDelegation) {
+            const delegatorId = (task as unknown as Record<string, unknown>).delegatedByAgentId as string | undefined
+            const delegator = delegatorId ? agents[delegatorId] : null
+            const prefix = `[delegation-source:${delegatorId || ''}:${delegator?.name || 'Agent'}:${delegator?.avatarSeed || ''}]`
+            initialText = `${prefix}\nDelegated by **${delegator?.name || 'another agent'}** | [${task.title}](#task:${task.id})\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`${buildTaskContinuationNote(Boolean(reusedExistingSession), resumeContext)}\n\nI'll begin working on this now.`
+          } else {
+            initialText = `Starting task: **${task.title}**\n\n${task.description || ''}\n\nWorking directory: \`${taskCwd}\`${buildTaskContinuationNote(Boolean(reusedExistingSession), resumeContext)}\n\nI'll begin working on this now.`
+          }
+          // Inject upstream task results context
+          if (Array.isArray(task.upstreamResults) && task.upstreamResults.length > 0) {
+            const upstreamBlock = task.upstreamResults
+              .map((ur) => `### ${ur.taskTitle}\n${ur.resultPreview || '(no result)'}`)
+              .join('\n\n')
+            initialText += `\n\n## Context from upstream tasks\n\n${upstreamBlock}`
+          }
+          appendMessage(sessionId, {
+            role: 'assistant',
+            text: initialText,
+            time: Date.now(),
+            ...(isDelegation ? { kind: 'system' as const } : {}),
+          })
         }
-        sessions[sessionId].messages.push({
-          role: 'assistant',
-          text: initialText,
-          time: Date.now(),
-          ...(isDelegation ? { kind: 'system' as const } : {}),
-        })
-        saveSessions(sessions)
       }
 
       log.info(TAG, `[queue] Running task "${task.title}" (${taskId}) with ${agent.name}`)
@@ -1488,7 +1349,14 @@ export async function processNext() {
       try {
         const taskRunId = `${taskId}:attempt-${(task.attempts || 0) + 1}`
         const endTaskRunPerf = perf.start('queue', 'executeTaskRun', { taskId, agentName: agent.name })
-        const taskRun = await executeTaskRun(task, agent, sessionId)
+        const taskRunHandle = enqueueExecution({
+          kind: 'task_attempt',
+          task,
+          agent,
+          sessionId,
+          executionId: taskRunId,
+        })
+        const taskRun = await taskRunHandle.promise
         endTaskRunPerf()
         // Update lastActivityAt after execution completes (idle timeout tracking)
         {
@@ -1524,9 +1392,8 @@ export async function processNext() {
         if (t2[taskId]) {
           applyTaskPolicyDefaults(t2[taskId])
           // Structured extraction: Zod-validated result with typed artifacts
-          const runSessions = loadSessions()
           const taskResult = extractTaskResult(
-            runSessions[sessionId],
+            getMessages(sessionId),
             result || null,
             { sinceTime: typeof t2[taskId].startedAt === 'number' ? t2[taskId].startedAt : null },
           )
@@ -1723,13 +1590,17 @@ export async function processNext() {
               t2[taskId].repairRunId = repairRunId
               t2[taskId].lastRepairAttemptAt = Date.now()
               saveTasks(t2)
-              await executeSessionChatTurn({
-                sessionId: t2[taskId].sessionId!,
-                message: `[AUTO-REPAIR] ${failureClassification.repairPrompt}\n\nOriginal error: ${errMsg.slice(0, 300)}`,
-                internal: true,
-                source: 'task-repair',
-                runId: repairRunId,
-              })
+              await enqueueExecution({
+                kind: 'session_turn',
+                input: {
+                  sessionId: t2[taskId].sessionId!,
+                  message: `[AUTO-REPAIR] ${failureClassification.repairPrompt}\n\nOriginal error: ${errMsg.slice(0, 300)}`,
+                  internal: true,
+                  source: 'task-repair',
+                  mode: 'followup',
+                  dedupeKey: repairRunId,
+                },
+              }).promise
               log.info(TAG, `[queue] Repair turn completed for task "${task.title}" (${taskId})`)
             } catch (repairErr: unknown) {
               log.warn(TAG, `[queue] Repair turn failed for task "${task.title}":`, repairErr instanceof Error ? repairErr.message : String(repairErr))

package/src/lib/server/runtime/run-ledger.ts

@@ -73,6 +73,10 @@ export function listPersistedRuns(params?: {
 export function appendPersistedRunEvent(input: {
   runId: string
   sessionId: string
+  kind?: RunEventRecord['kind']
+  ownerType?: RunEventRecord['ownerType']
+  ownerId?: RunEventRecord['ownerId']
+  parentExecutionId?: RunEventRecord['parentExecutionId']
   phase: 'status' | 'event'
   status?: SessionRunStatus
   event: SSEEvent
@@ -86,6 +90,10 @@ export function appendPersistedRunEvent(input: {
     id: genId(12),
     runId: input.runId,
     sessionId: input.sessionId,
+    kind: input.kind,
+    ownerType: input.ownerType,
+    ownerId: input.ownerId,
+    parentExecutionId: input.parentExecutionId,
     timestamp,
     phase: input.phase,
     status: input.status,

package/src/lib/server/runtime/session-run-manager/drain.ts

@@ -1,4 +1,4 @@
-import { executeSessionChatTurn } from '@/lib/server/chat-execution/chat-execution'
+import { executeExecutionChatTurn } from '@/lib/server/execution-engine/chat-turn'
 import { log } from '@/lib/server/logger'
 import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
 import { notify } from '@/lib/server/ws-hub'
@@ -98,7 +98,7 @@ export async function drainExecution(
     }
 
     try {
-      const result = await executeSessionChatTurn({
+      const result = await executeExecutionChatTurn({
         sessionId: next.run.sessionId,
         message: next.message,
         imagePath: next.imagePath,

package/src/lib/server/runtime/session-run-manager/enqueue.ts

@@ -6,6 +6,7 @@ import { log } from '@/lib/server/logger'
 import { isInternalHeartbeatRun } from '@/lib/server/runtime/heartbeat-source'
 import { getEnabledToolIds } from '@/lib/capability-selection'
 import { isAllEstopEngaged, isAutonomyEstopEngaged } from '@/lib/server/runtime/estop'
+import { isRestartRecoverableSource } from '@/lib/server/runtime/run-ledger'
 import { getActiveSessionProcess } from '@/lib/server/runtime/runtime-state'
 
 import { cancelPendingForSession } from './cancellation'
@@ -215,6 +216,11 @@ export function enqueueSessionRun(
     id: runId,
     sessionId: input.sessionId,
     missionId: input.missionId ?? getSession(input.sessionId)?.missionId ?? null,
+    kind: 'session_turn',
+    ownerType: 'session',
+    ownerId: input.sessionId,
+    parentExecutionId: null,
+    recoveryPolicy: isRestartRecoverableSource(source) ? 'restart_recoverable' : 'ephemeral',
     source,
     internal,
     mode,

package/src/lib/server/runtime/session-run-manager/state.ts

@@ -118,6 +118,10 @@ export function persistEventForRun(entry: SessionRunQueueEntry, event: SSEEvent,
   appendPersistedRunEvent({
     runId: entry.run.id,
     sessionId: entry.run.sessionId,
+    kind: entry.run.kind,
+    ownerType: entry.run.ownerType,
+    ownerId: entry.run.ownerId,
+    parentExecutionId: entry.run.parentExecutionId,
     phase: opts?.phase || 'event',
     status: opts?.status,
     summary: opts?.summary,

package/src/lib/server/schedules/schedule-route-service.ts

@@ -0,0 +1,230 @@
+import { buildAgentDisabledMessage, isAgentDisabled } from '@/lib/server/agents/agent-availability'
+import { loadAgents } from '@/lib/server/agents/agent-repository'
+import { logActivity } from '@/lib/server/activity/activity-log'
+import { enqueueTask } from '@/lib/server/runtime/queue'
+import { loadSessions } from '@/lib/server/sessions/session-repository'
+import { prepareScheduleUpdate, prepareScheduleCreate } from '@/lib/server/schedules/schedule-service'
+import {
+  archiveScheduleCluster,
+  purgeArchivedScheduleCluster,
+  restoreArchivedScheduleCluster,
+} from '@/lib/server/schedules/schedule-lifecycle'
+import { loadSchedule, loadSchedules, upsertSchedule, upsertSchedules } from '@/lib/server/schedules/schedule-repository'
+import { serviceFail, serviceOk } from '@/lib/server/service-result'
+import { errorMessage } from '@/lib/shared-utils'
+import { getScheduleSignatureKey } from '@/lib/schedules/schedule-dedupe'
+import { prepareScheduledTaskRun } from '@/lib/server/tasks/task-lifecycle'
+import { loadTasks, saveTask } from '@/lib/server/tasks/task-repository'
+import { pushMainLoopEventToMainSessions } from '@/lib/server/agents/main-agent-loop'
+import { WORKSPACE_DIR } from '@/lib/server/data-dir'
+import { notify } from '@/lib/server/ws-hub'
+import type { Schedule } from '@/types'
+import type { ScheduleLike } from '@/lib/schedules/schedule-dedupe'
+import type { ServiceResult } from '@/lib/server/service-result'
+
+type InFlightTask = {
+  status?: string
+  sourceScheduleKey?: string | null
+}
+
+export function listSchedulesForApi(includeArchived: boolean) {
+  const schedules = loadSchedules()
+  if (includeArchived) return schedules
+  const filtered: typeof schedules = {}
+  for (const [id, schedule] of Object.entries(schedules)) {
+    if (schedule.status === 'archived') continue
+    filtered[id] = schedule
+  }
+  return filtered
+}
+
+export function createScheduleFromRoute(body: Record<string, unknown>): ServiceResult<ScheduleLike> {
+  const now = Date.now()
+  const schedules = loadSchedules()
+  const agents = loadAgents()
+  const candidateAgentId = typeof body.agentId === 'string' ? body.agentId.trim() : ''
+  const agent = agents[candidateAgentId]
+  if (!agent) {
+    return serviceFail(400, `Agent not found: ${String(body.agentId)}`)
+  }
+  if (isAgentDisabled(agent)) {
+    return serviceFail(409, buildAgentDisabledMessage(agent, 'take scheduled work'))
+  }
+  const prepared = prepareScheduleCreate({
+    input: body,
+    schedules,
+    now,
+    cwd: WORKSPACE_DIR,
+  })
+  if (!prepared.ok) {
+    return serviceFail(400, prepared.error)
+  }
+  if (prepared.kind === 'duplicate') {
+    if (prepared.entries.length === 1) upsertSchedule(prepared.scheduleId, prepared.schedule)
+    else if (prepared.entries.length > 1) upsertSchedules(prepared.entries)
+    if (prepared.entries.length > 0) notify('schedules')
+    return serviceOk(prepared.schedule)
+  }
+  upsertSchedule(prepared.scheduleId, prepared.schedule)
+  logActivity({
+    entityType: 'schedule',
+    entityId: prepared.scheduleId,
+    action: 'created',
+    actor: 'user',
+    summary: `Schedule created: "${prepared.schedule.name}"`,
+  })
+  notify('schedules')
+  return serviceOk(prepared.schedule)
+}
+
+export function updateScheduleFromRoute(id: string, body: Record<string, unknown>): ServiceResult<ScheduleLike & { [key: string]: unknown }> {
+  const schedules = loadSchedules()
+  const current = schedules[id]
+  if (!current) return serviceFail(404, 'Schedule not found')
+
+  if (body.restore === true) {
+    const restored = restoreArchivedScheduleCluster(id, {
+      actor: { actor: 'user' },
+    })
+    if (!restored.ok || !restored.schedule) {
+      return serviceFail(409, 'Schedule is not archived.')
+    }
+    return serviceOk({
+      ...restored.schedule,
+      restoredIds: restored.restoredIds,
+    })
+  }
+
+  if (body.status === 'archived') {
+    const archived = archiveScheduleCluster(id, {
+      actor: { actor: 'user' },
+    })
+    if (!archived.ok || !archived.schedule) {
+      return serviceFail(500, 'Failed to archive schedule.')
+    }
+    return serviceOk({
+      ...archived.schedule,
+      archivedIds: archived.archivedIds,
+      cancelledTaskIds: archived.cancelledTaskIds,
+      abortedRunSessionIds: archived.abortedRunSessionIds,
+    })
+  }
+
+  const sessions = loadSessions()
+  const agents = loadAgents()
+  const sessionCwd = typeof current.createdInSessionId === 'string'
+    ? sessions[current.createdInSessionId]?.cwd
+    : null
+  const prepared = prepareScheduleUpdate({
+    id,
+    current,
+    patch: body,
+    schedules,
+    now: Date.now(),
+    cwd: sessionCwd || WORKSPACE_DIR,
+    agentExists: (agentId) => Boolean(agents[agentId]),
+    propagateEquivalentStatuses: true,
+    propagationSource: current as unknown as Record<string, unknown>,
+  })
+  if (!prepared.ok) {
+    return serviceFail(400, errorMessage(prepared.error))
+  }
+  upsertSchedules(prepared.entries)
+  logActivity({
+    entityType: 'schedule',
+    entityId: id,
+    action: 'updated',
+    actor: 'user',
+    summary: `Schedule updated: "${prepared.schedule.name}"`,
+    detail: prepared.affectedScheduleIds.length > 1 ? { affectedScheduleIds: prepared.affectedScheduleIds } : undefined,
+  })
+  notify('schedules')
+  return serviceOk(
+    prepared.affectedScheduleIds.length > 1
+      ? { ...prepared.schedule, affectedScheduleIds: prepared.affectedScheduleIds }
+      : prepared.schedule,
+  )
+}
+
+export function deleteScheduleFromRoute(id: string, purge: boolean): ServiceResult<Record<string, unknown>> {
+  const current = loadSchedule(id)
+  if (!current) return serviceFail(404, 'Schedule not found')
+  if (purge) {
+    const purged = purgeArchivedScheduleCluster(id, {
+      actor: { actor: 'user' },
+    })
+    if (!purged.ok) {
+      return serviceFail(409, 'Only archived schedules can be purged.')
+    }
+    return serviceOk({ ok: true, purgedIds: purged.purgedIds })
+  }
+  const archived = archiveScheduleCluster(id, {
+    actor: { actor: 'user' },
+  })
+  if (!archived.ok || !archived.schedule) {
+    return serviceFail(500, 'Failed to archive schedule.')
+  }
+  return serviceOk({
+    ok: true,
+    archivedIds: archived.archivedIds,
+    cancelledTaskIds: archived.cancelledTaskIds,
+    removedQueuedTaskIds: archived.removedQueuedTaskIds,
+    abortedRunSessionIds: archived.abortedRunSessionIds,
+    schedule: archived.schedule,
+  })
+}
+
+export function runScheduleNow(id: string): ServiceResult<Record<string, unknown>> {
+  const schedule = loadSchedule(id) as Schedule | null
+  if (!schedule) return serviceFail(404, 'Schedule not found')
+  if (schedule.status === 'archived') {
+    return serviceFail(409, 'Archived schedules must be restored before they can run.')
+  }
+
+  const agents = loadAgents()
+  const agent = agents[schedule.agentId]
+  if (!agent) return serviceFail(400, 'Agent not found')
+  if (isAgentDisabled(agent)) {
+    return serviceFail(409, buildAgentDisabledMessage(agent, 'run schedules'))
+  }
+
+  const tasks = loadTasks()
+  const scheduleSignature = getScheduleSignatureKey(schedule)
+  if (scheduleSignature) {
+    const inFlight = Object.values(tasks as Record<string, InFlightTask>).some((task) =>
+      task
+      && (task.status === 'queued' || task.status === 'running')
+      && task.sourceScheduleKey === scheduleSignature
+    )
+    if (inFlight) {
+      return serviceOk({ ok: true, queued: false, reason: 'in_flight' })
+    }
+  }
+
+  const now = Date.now()
+  schedule.runNumber = (schedule.runNumber || 0) + 1
+  const { taskId } = prepareScheduledTaskRun({
+    schedule,
+    tasks,
+    now,
+    scheduleSignature,
+  })
+  saveTask(taskId, tasks[taskId])
+  enqueueTask(taskId)
+  pushMainLoopEventToMainSessions({
+    type: 'schedule_fired',
+    text: `Schedule fired manually: "${schedule.name}" (${schedule.id}) run #${schedule.runNumber} — task ${taskId}`,
+  })
+  schedule.lastRunAt = now
+  upsertSchedule(schedule.id, schedule)
+  logActivity({
+    entityType: 'schedule',
+    entityId: schedule.id,
+    action: 'started',
+    actor: 'user',
+    summary: `Schedule run started: "${schedule.name}"`,
+    detail: { taskId, runNumber: schedule.runNumber },
+  })
+
+  return serviceOk({ ok: true, queued: true, taskId, runNumber: schedule.runNumber })
+}

package/src/lib/server/service-result.ts

@@ -0,0 +1,16 @@
+/**
+ * Standardized result type for route-facing services.
+ *
+ * Routes inspect `ok` to decide the HTTP status code and response body.
+ */
+export type ServiceResult<T> =
+  | { ok: true; payload: T }
+  | { ok: false; status: number; payload: { error: string } }
+
+export function serviceOk<T>(payload: T): ServiceResult<T> {
+  return { ok: true, payload }
+}
+
+export function serviceFail(status: number, error: string): ServiceResult<never> {
+  return { ok: false, status, payload: { error } }
+}