@swarmclawai/swarmclaw 1.2.4 → 1.2.5

package/src/lib/server/agents/delegation-advisory.test.ts

@@ -0,0 +1,206 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { after, before, describe, it } from 'node:test'
+import type { Agent } from '@/types'
+import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
+
+const originalEnv = {
+  DATA_DIR: process.env.DATA_DIR,
+  WORKSPACE_DIR: process.env.WORKSPACE_DIR,
+  SWARMCLAW_BUILD_MODE: process.env.SWARMCLAW_BUILD_MODE,
+}
+
+let tempDir = ''
+let advisory: typeof import('@/lib/server/agents/delegation-advisory')
+let storage: typeof import('@/lib/server/storage')
+
+before(async () => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-delegation-advisory-'))
+  process.env.DATA_DIR = path.join(tempDir, 'data')
+  process.env.WORKSPACE_DIR = path.join(tempDir, 'workspace')
+  process.env.SWARMCLAW_BUILD_MODE = '1'
+  fs.mkdirSync(process.env.DATA_DIR, { recursive: true })
+  fs.mkdirSync(process.env.WORKSPACE_DIR, { recursive: true })
+
+  advisory = await import('@/lib/server/agents/delegation-advisory')
+  storage = await import('@/lib/server/storage')
+})
+
+after(() => {
+  if (originalEnv.DATA_DIR === undefined) delete process.env.DATA_DIR
+  else process.env.DATA_DIR = originalEnv.DATA_DIR
+  if (originalEnv.WORKSPACE_DIR === undefined) delete process.env.WORKSPACE_DIR
+  else process.env.WORKSPACE_DIR = originalEnv.WORKSPACE_DIR
+  if (originalEnv.SWARMCLAW_BUILD_MODE === undefined) delete process.env.SWARMCLAW_BUILD_MODE
+  else process.env.SWARMCLAW_BUILD_MODE = originalEnv.SWARMCLAW_BUILD_MODE
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+function makeAgent(params: Partial<Agent> & Pick<Agent, 'id' | 'name'>): Agent {
+  const now = Date.now()
+  return {
+    id: params.id,
+    name: params.name,
+    role: params.role || 'worker',
+    description: params.description || '',
+    systemPrompt: params.systemPrompt || '',
+    provider: params.provider || 'openai',
+    model: params.model || 'gpt-test',
+    capabilities: params.capabilities || [],
+    delegationEnabled: params.delegationEnabled ?? false,
+    delegationTargetMode: params.delegationTargetMode || 'all',
+    delegationTargetAgentIds: params.delegationTargetAgentIds || [],
+    createdAt: params.createdAt || now,
+    updatedAt: params.updatedAt || now,
+  } as Agent
+}
+
+function makeClassification(overrides: Partial<MessageClassification>): MessageClassification {
+  return {
+    taskIntent: 'general',
+    isDeliverableTask: false,
+    isBroadGoal: false,
+    walletIntent: 'none',
+    hasHumanSignals: false,
+    hasSignificantEvent: false,
+    isResearchSynthesis: false,
+    workType: 'general',
+    wantsScreenshots: false,
+    wantsOutboundDelivery: false,
+    wantsVoiceDelivery: false,
+    explicitToolRequests: [],
+    confidence: 0.9,
+    ...overrides,
+  }
+}
+
+function saveAgents(agents: Agent[]): Record<string, Agent> {
+  const record = Object.fromEntries(agents.map((agent) => [agent.id, agent]))
+  storage.saveAgents(record)
+  storage.saveTasks({})
+  storage.saveSessions({})
+  return record
+}
+
+describe('delegation-advisory', () => {
+  it('prefers a builder over a coordinator for coding work', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'ceo',
+        name: 'CEO',
+        role: 'coordinator',
+        capabilities: ['coordination', 'delegation', 'operations'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder',
+        name: 'Builder',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+      makeAgent({
+        id: 'writer',
+        name: 'Writer',
+        role: 'worker',
+        capabilities: ['writing', 'editing'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isDeliverableTask: true,
+        workType: 'coding',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents.ceo,
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.shouldDelegate, true)
+    assert.equal(result.style, 'managerial')
+    assert.equal(result.recommended?.agentId, 'builder')
+    assert.match(advisory.formatDelegationRationale(result.recommended), /coding/i)
+  })
+
+  it('prefers a researcher for research work', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'ceo',
+        name: 'CEO',
+        role: 'coordinator',
+        capabilities: ['coordination', 'delegation', 'operations'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder',
+        name: 'Builder',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+      makeAgent({
+        id: 'researcher',
+        name: 'Researcher',
+        role: 'worker',
+        capabilities: ['research', 'analysis', 'summarization'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isResearchSynthesis: true,
+        workType: 'research',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents.ceo,
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.shouldDelegate, true)
+    assert.equal(result.recommended?.agentId, 'researcher')
+  })
+
+  it('does not advise delegation when self is already as capable as peers', () => {
+    const agents = saveAgents([
+      makeAgent({
+        id: 'builder-a',
+        name: 'Builder A',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+        delegationEnabled: true,
+      }),
+      makeAgent({
+        id: 'builder-b',
+        name: 'Builder B',
+        role: 'worker',
+        capabilities: ['coding', 'implementation', 'debugging'],
+      }),
+    ])
+
+    const profile = advisory.buildDelegationTaskProfile({
+      classification: makeClassification({
+        isDeliverableTask: true,
+        workType: 'coding',
+      }),
+    })
+    const result = advisory.resolveDelegationAdvisory({
+      currentAgent: agents['builder-a'],
+      agents,
+      profile,
+      delegationTargetMode: 'all',
+      delegationTargetAgentIds: [],
+    })
+
+    assert.equal(result.recommended?.agentId, 'builder-b')
+    assert.equal(result.shouldDelegate, false)
+  })
+})

package/src/lib/server/agents/delegation-advisory.ts

@@ -0,0 +1,251 @@
+import type { Agent } from '@/types'
+import type { MessageClassification } from '@/lib/server/chat-execution/message-classifier'
+import { capabilityMatchScore } from '@/lib/server/agents/capability-match'
+import { getAgentDirectory, type AgentDirectoryEntry } from '@/lib/server/agents/agent-registry'
+
+export type DelegationWorkType =
+  | 'coding'
+  | 'research'
+  | 'writing'
+  | 'review'
+  | 'operations'
+  | 'general'
+
+export interface DelegationTaskProfile {
+  workType: DelegationWorkType
+  requiredCapabilities: string[]
+  substantial: boolean
+}
+
+export interface DelegationCandidateFit {
+  agentId: string
+  agentName: string
+  score: number
+  availability: 'idle' | 'working' | 'unknown'
+  matchedCapabilities: string[]
+  reasons: string[]
+}
+
+export interface DelegationAdvisory {
+  profile: DelegationTaskProfile
+  current: DelegationCandidateFit | null
+  recommended: DelegationCandidateFit | null
+  shouldDelegate: boolean
+  style: 'managerial' | 'advisory'
+}
+
+const WORK_TYPE_CAPABILITIES: Record<DelegationWorkType, string[]> = {
+  coding: ['coding', 'implementation', 'debugging'],
+  research: ['research', 'analysis', 'summarization'],
+  writing: ['writing', 'messaging', 'structuring', 'editing'],
+  review: ['review', 'testing', 'risk assessment'],
+  operations: ['coordination', 'delegation', 'operations'],
+  general: [],
+}
+
+function normalizeCapabilityList(value: string[] | undefined | null): string[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const entry of value) {
+    const trimmed = typeof entry === 'string' ? entry.trim() : ''
+    const key = trimmed.toLowerCase()
+    if (!trimmed || seen.has(key)) continue
+    seen.add(key)
+    out.push(trimmed)
+  }
+  return out
+}
+
+function normalizeWorkType(value: unknown): DelegationWorkType {
+  if (
+    value === 'coding'
+    || value === 'research'
+    || value === 'writing'
+    || value === 'review'
+    || value === 'operations'
+  ) {
+    return value
+  }
+  return 'general'
+}
+
+function matchedCapabilities(agentCapabilities: string[] | undefined, requiredCapabilities: string[]): string[] {
+  if (!requiredCapabilities.length || !Array.isArray(agentCapabilities) || !agentCapabilities.length) return []
+  const agentSet = new Set(agentCapabilities.map((entry) => entry.toLowerCase()))
+  return requiredCapabilities.filter((entry) => agentSet.has(entry.toLowerCase()))
+}
+
+function roleAdjustment(agent: Agent, profile: DelegationTaskProfile): number {
+  const role = agent.role === 'coordinator' ? 'coordinator' : 'worker'
+  if (profile.workType === 'operations') {
+    return role === 'coordinator' ? 0.28 : -0.04
+  }
+  if (profile.workType === 'general') {
+    return role === 'coordinator' ? -0.03 : 0
+  }
+  return role === 'coordinator' ? -0.18 : 0.16
+}
+
+function selfExecutionPenalty(agent: Agent, profile: DelegationTaskProfile, isSelf: boolean): number {
+  if (!isSelf) return 0
+  if (agent.role !== 'coordinator') return 0
+  if (!profile.substantial) return 0
+  if (profile.workType === 'operations') return 0
+  return -0.42
+}
+
+function availabilityAdjustment(
+  availability: DelegationCandidateFit['availability'],
+  isSelf: boolean,
+  directoryEntry?: AgentDirectoryEntry,
+): number {
+  if (availability === 'idle') return 0.08
+  if (availability === 'working') {
+    // The current live chat session should not count as a self-load penalty.
+    if (isSelf && !directoryEntry?.statusDetail) return 0.08
+    return -0.08
+  }
+  return 0
+}
+
+function buildAvailabilityMap(): Map<string, AgentDirectoryEntry> {
+  return new Map(getAgentDirectory().map((entry) => [entry.id, entry]))
+}
+
+function buildCandidateFit(
+  agent: Agent,
+  profile: DelegationTaskProfile,
+  directory: Map<string, AgentDirectoryEntry>,
+  isSelf = false,
+): DelegationCandidateFit {
+  const directoryEntry = directory.get(agent.id)
+  const availability = directoryEntry?.status || 'unknown'
+  const matched = matchedCapabilities(agent.capabilities, profile.requiredCapabilities)
+  const capabilityScore = profile.requiredCapabilities.length > 0
+    ? capabilityMatchScore(agent.capabilities, profile.requiredCapabilities) * 1.45
+    : 0
+  const score = capabilityScore
+    + roleAdjustment(agent, profile)
+    + availabilityAdjustment(availability, isSelf, directoryEntry)
+    + selfExecutionPenalty(agent, profile, isSelf)
+
+  const reasons: string[] = []
+  if (matched.length > 0) reasons.push(`capability match: ${matched.join(', ')}`)
+  if (profile.workType === 'operations' && agent.role === 'coordinator') reasons.push('coordinator role fits operations work')
+  if (profile.workType !== 'operations' && profile.workType !== 'general' && agent.role !== 'coordinator') reasons.push('worker role fits execution-heavy work')
+  if (availability === 'idle') reasons.push('currently idle')
+  if (availability === 'working' && directoryEntry?.statusDetail) reasons.push(directoryEntry.statusDetail)
+  if (isSelf && selfExecutionPenalty(agent, profile, true) < 0) reasons.push('coordinator should prefer orchestration over direct execution')
+
+  return {
+    agentId: agent.id,
+    agentName: agent.name,
+    score,
+    availability,
+    matchedCapabilities: matched,
+    reasons,
+  }
+}
+
+function isAllowedDelegateTarget(
+  agentId: string,
+  opts?: { delegationTargetMode?: 'all' | 'selected'; delegationTargetAgentIds?: string[] },
+): boolean {
+  if (opts?.delegationTargetMode !== 'selected') return true
+  const allowed = new Set(normalizeCapabilityList(opts.delegationTargetAgentIds))
+  return allowed.size === 0 || allowed.has(agentId)
+}
+
+export function resolveDelegationWorkType(
+  classification: MessageClassification | null | undefined,
+): DelegationWorkType {
+  return normalizeWorkType(classification?.workType)
+}
+
+export function buildDelegationTaskProfile(params: {
+  classification?: MessageClassification | null
+  workType?: DelegationWorkType | null
+  requiredCapabilities?: string[] | null
+}): DelegationTaskProfile {
+  const workType = params.workType
+    ? normalizeWorkType(params.workType)
+    : resolveDelegationWorkType(params.classification)
+  const explicitRequirements = normalizeCapabilityList(params.requiredCapabilities)
+  const requiredCapabilities = explicitRequirements.length > 0
+    ? explicitRequirements
+    : WORK_TYPE_CAPABILITIES[workType]
+  const substantial = explicitRequirements.length > 0
+    || Boolean(params.classification?.isBroadGoal)
+    || Boolean(params.classification?.isDeliverableTask)
+    || Boolean(params.classification?.isResearchSynthesis)
+    || workType !== 'general'
+  return {
+    workType,
+    requiredCapabilities,
+    substantial,
+  }
+}
+
+export function resolveBestDelegateTarget(params: {
+  currentAgentId?: string | null
+  agents: Record<string, Agent>
+  profile: DelegationTaskProfile
+  delegationTargetMode?: 'all' | 'selected'
+  delegationTargetAgentIds?: string[]
+}): DelegationCandidateFit | null {
+  const directory = buildAvailabilityMap()
+  const candidates = Object.values(params.agents)
+    .filter((agent) => agent.id !== params.currentAgentId)
+    .filter((agent) => !agent.disabled && !agent.trashedAt)
+    .filter((agent) => isAllowedDelegateTarget(agent.id, params))
+    .map((agent) => buildCandidateFit(agent, params.profile, directory))
+    .sort((left, right) => {
+      if (right.score !== left.score) return right.score - left.score
+      return left.agentName.localeCompare(right.agentName)
+    })
+  return candidates[0] || null
+}
+
+export function resolveDelegationAdvisory(params: {
+  currentAgent: Agent | null | undefined
+  agents: Record<string, Agent>
+  profile: DelegationTaskProfile
+  delegationTargetMode?: 'all' | 'selected'
+  delegationTargetAgentIds?: string[]
+}): DelegationAdvisory {
+  const directory = buildAvailabilityMap()
+  const current = params.currentAgent && !params.currentAgent.disabled && !params.currentAgent.trashedAt
+    ? buildCandidateFit(params.currentAgent, params.profile, directory, true)
+    : null
+  const recommended = resolveBestDelegateTarget({
+    currentAgentId: params.currentAgent?.id || null,
+    agents: params.agents,
+    profile: params.profile,
+    delegationTargetMode: params.delegationTargetMode,
+    delegationTargetAgentIds: params.delegationTargetAgentIds,
+  })
+  const currentScore = current?.score ?? 0
+  const recommendedScore = recommended?.score ?? Number.NEGATIVE_INFINITY
+  const shouldDelegate = Boolean(
+    params.profile.substantial
+    && recommended
+    && recommendedScore >= currentScore + 0.3
+    && recommendedScore >= 0.25,
+  )
+  const style = params.currentAgent?.role === 'coordinator' && params.profile.workType !== 'operations'
+    ? 'managerial'
+    : 'advisory'
+  return {
+    profile: params.profile,
+    current,
+    recommended,
+    shouldDelegate,
+    style,
+  }
+}
+
+export function formatDelegationRationale(candidate: DelegationCandidateFit | null | undefined): string {
+  if (!candidate || candidate.reasons.length === 0) return 'better fit for this work'
+  return candidate.reasons.slice(0, 2).join('; ')
+}

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

@@ -1,4 +1,5 @@
 import { hmrSingleton } from '@/lib/shared-utils'
+import { getMessages } from '@/lib/server/messages/message-repository'
 import type { GoalContract, Message, MessageToolEvent, Session } from '@/types'
 import { mergeGoalContracts, parseGoalContractFromText, parseMainLoopPlan, parseMainLoopReview } from '@/lib/server/agents/autonomy-contract'
 import {
@@ -12,6 +13,10 @@ import { enqueueSystemEvent } from '@/lib/server/runtime/system-events'
 import { buildMissionHeartbeatPrompt as buildMissionHeartbeatPromptFromMission, getMissionForSession } from '@/lib/server/missions/mission-service'
 import { loadSettings } from '@/lib/server/settings/settings-repository'
 import { getSession, loadSessions } from '@/lib/server/sessions/session-repository'
+import { deleteSessionWorkingState, loadSessionWorkingState, syncWorkingStateFromMainLoopState } from '@/lib/server/working-state/service'
+import { syncMainLoopToRunContext } from '@/lib/server/run-context'
+import { buildExecutionBrief, buildExecutionBriefContextBlock } from '@/lib/server/execution-brief'
+import { cleanText, cleanMultiline } from '@/lib/server/text-normalization'
 
 const LEGACY_META_LINE_RE = /\[(?:MAIN_LOOP_META|MAIN_LOOP_PLAN|MAIN_LOOP_REVIEW|AGENT_HEARTBEAT_META)\]\s*(\{[^\n]*\})?/i
 const HEARTBEAT_META_RE = /\[AGENT_HEARTBEAT_META\]\s*(\{[^\n]*\})/i
@@ -19,7 +24,7 @@ const MAX_PENDING_EVENTS = 16
 const MAX_TIMELINE_ITEMS = 40
 const MAX_WORKING_MEMORY_NOTES = 12
 const DEFAULT_FOLLOWUP_DELAY_MS = 1500
-const DEFAULT_MAX_FOLLOWUP_CHAIN = 4
+const DEFAULT_MAX_FOLLOWUP_CHAIN = 3
 const MAX_LIFETIME_ITERATIONS = 200
 
 export interface MainLoopState {
@@ -111,24 +116,6 @@ function asSession(session: unknown): MainSessionLike | null {
   return session as MainSessionLike
 }
 
-function cleanText(value: unknown, maxChars = 320): string | null {
-  if (typeof value !== 'string') return null
-  const normalized = value.replace(/\s+/g, ' ').trim()
-  return normalized ? normalized.slice(0, maxChars) : null
-}
-
-function cleanMultiline(value: unknown, maxChars = 1400): string | null {
-  if (typeof value !== 'string') return null
-  const normalized = value
-    .split('\n')
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .join('\n')
-    .slice(0, maxChars)
-    .trim()
-  return normalized || null
-}
-
 function normalizeConfidence(value: unknown): number | null {
   const raw = typeof value === 'number'
     ? value
@@ -403,7 +390,7 @@ function hydrateStateFromSession(sessionId: string): MainLoopState | null {
   const session = sessions[sessionId]
   if (!session || !isMainSession(session)) return null
 
-  const messages = Array.isArray(session.messages) ? session.messages : []
+  const messages = getMessages(sessionId)
   const hydrated = defaultState()
   hydrated.autonomyMode = session.heartbeatEnabled === true ? 'autonomous' : 'assist'
   hydrated.updatedAt = typeof session.lastActiveAt === 'number' ? session.lastActiveAt : now()
@@ -440,21 +427,48 @@ function hydrateStateFromSession(sessionId: string): MainLoopState | null {
     }
   }
 
-  return normalizeState(hydrated)
+  return mergeWorkingStateIntoMainLoopState(sessionId, normalizeState(hydrated))
 }
 
 function persistState(sessionId: string, state: MainLoopState): void {
-  upsertPersistedMainLoopState(sessionId, state as unknown as Record<string, unknown>)
+  const normalized = clampState(state)
+  upsertPersistedMainLoopState(sessionId, normalized as unknown as Record<string, unknown>)
+  const session = getSession(sessionId)
+  if (!session) return
+  const mission = getMissionForSession(session)
+  void syncWorkingStateFromMainLoopState({
+    sessionId,
+    mission,
+    goal: normalized.goal,
+    summary: normalized.summary,
+    status: normalized.status === 'ok'
+      ? 'completed'
+      : normalized.status === 'blocked'
+        ? 'blocked'
+        : normalized.status === 'progress'
+          ? 'progress'
+          : 'idle',
+    nextAction: normalized.nextAction,
+    planSteps: normalized.planSteps,
+    blockers: normalized.skillBlocker ? [{
+      summary: normalized.skillBlocker.summary,
+      kind: normalized.skillBlocker.status === 'approval_requested' ? 'approval' : 'other',
+    }] : undefined,
+  })
 }
 
 function getOrCreateState(sessionId: string): MainLoopState | null {
   const existing = stateMap.get(sessionId)
-  if (existing) return existing
+  if (existing) {
+    const merged = mergeWorkingStateIntoMainLoopState(sessionId, existing)
+    stateMap.set(sessionId, merged)
+    return merged
+  }
 
   // Try disk (survives full restart)
   const persisted = loadPersistedMainLoopState(sessionId) as Partial<MainLoopState> | null
   if (persisted) {
-    const restored = normalizeState(persisted)
+    const restored = mergeWorkingStateIntoMainLoopState(sessionId, normalizeState(persisted))
     stateMap.set(sessionId, restored)
     return restored
   }
@@ -467,6 +481,43 @@ function getOrCreateState(sessionId: string): MainLoopState | null {
   return hydrated
 }
 
+function mergeWorkingStateIntoMainLoopState(sessionId: string, current: MainLoopState): MainLoopState {
+  const workingState = loadSessionWorkingState(sessionId)
+  if (!workingState) return clampState(current)
+  const next = normalizeState(current)
+  if (workingState.objective) next.goal = cleanMultiline(workingState.objective, 900)
+  if (workingState.summary) next.summary = cleanText(workingState.summary, 1000)
+  if (workingState.nextAction) next.nextAction = cleanText(workingState.nextAction, 240)
+  if (workingState.status === 'completed') next.status = 'ok'
+  else if (workingState.status === 'blocked' || workingState.status === 'waiting') next.status = 'blocked'
+  else if (workingState.status === 'progress') next.status = 'progress'
+
+  const planSteps = (workingState.planSteps || [])
+    .map((step) => cleanText(step.text, 240))
+    .filter((step): step is string => Boolean(step))
+  if (planSteps.length > 0) {
+    next.planSteps = uniqueStrings(planSteps, 8)
+    next.completedPlanSteps = uniqueStrings(
+      (workingState.planSteps || [])
+        .filter((step) => step.status === 'resolved')
+        .map((step) => cleanText(step.text, 240))
+        .filter((step): step is string => Boolean(step)),
+      16,
+    )
+    const activeStep = (workingState.planSteps || []).find((step) => step.status === 'active')
+    if (activeStep?.text) next.currentPlanStep = cleanText(activeStep.text, 240)
+  }
+
+  const noteCandidates = [
+    ...(workingState.confirmedFacts || []).filter((item) => item.status === 'active').map((item) => `Fact: ${item.statement}`),
+    ...(workingState.blockers || []).filter((item) => item.status === 'active').map((item) => `Blocker: ${item.summary}`),
+  ]
+  if (noteCandidates.length > 0) {
+    next.workingMemoryNotes = uniqueStrings([...(next.workingMemoryNotes || []), ...noteCandidates], MAX_WORKING_MEMORY_NOTES)
+  }
+  return clampState(next)
+}
+
 function summarizePendingEvents(events: MainLoopState['pendingEvents']): string {
   if (!events.length) return ''
   return events
@@ -754,39 +805,38 @@ export function buildMainLoopHeartbeatPrompt(session: unknown, fallbackPrompt: s
   const state = getOrCreateState(String(candidate.id))
   if (!state) return fallbackPrompt
   const latestExternalGoal = extractLatestGoal(Array.isArray(candidate.messages) ? candidate.messages as Message[] : [])
-  const effectiveGoal = state.goal || latestExternalGoal.goal
   const effectiveGoalContract = latestExternalGoal.goalContract
     ? mergeGoalContracts(state.goalContract, latestExternalGoal.goalContract)
     : state.goalContract
 
-  const completedSet = new Set(state.completedPlanSteps.map((s) => s.toLowerCase()))
-  const planLines = state.planSteps.length > 0
-    ? state.planSteps.slice(0, 8).map((step, index) => {
-      const isDone = completedSet.has(step.toLowerCase())
-      return `${index + 1}. ${isDone ? '[DONE] ' : ''}${step}`
-    }).join('\n')
-    : ''
+  const heartbeatSession = (persistedSession || candidate as Session)
+  const executionBrief = buildExecutionBrief({
+    session: heartbeatSession,
+    mission: getMissionForSession(heartbeatSession),
+  })
+  const executionBriefBlock = buildExecutionBriefContextBlock(executionBrief)
   const boundedFallbackPrompt = cleanMultiline(fallbackPrompt, 500)
-  const boundedSummary = cleanMultiline(state.summary, 500)
+  const workingState = loadSessionWorkingState(String(candidate.id))
+  const activeWorkingBlockers = (workingState?.blockers || [])
+    .filter((item) => item.status === 'active')
+    .map((item) => item.nextAction ? `${item.summary} | next: ${item.nextAction}` : item.summary)
+    .slice(0, 4)
+    .join('\n')
 
   return [
     'MAIN_AGENT_HEARTBEAT_TICK',
     `Time: ${new Date().toISOString()}`,
-    effectiveGoal ? `Current goal:\n${effectiveGoal}` : '',
+    executionBriefBlock,
     formatGoalContract(effectiveGoalContract),
-    `Current status: ${state.status}`,
-    state.nextAction ? `Planned next action: ${state.nextAction}` : '',
-    state.currentPlanStep ? `Current plan step: ${state.currentPlanStep}` : '',
-    planLines ? `Plan:\n${planLines}` : '',
     state.pendingEvents.length > 0 ? `Pending external events:\n${summarizePendingEvents(state.pendingEvents)}` : '',
+    activeWorkingBlockers ? `Active blockers:\n${activeWorkingBlockers}` : '',
     state.skillBlocker ? `Active skill blocker:\n${summarizeSkillBlocker(state.skillBlocker)}` : '',
     summarizeSelectedSkillRuntime(candidate),
-    boundedSummary ? `Latest summary:\n${boundedSummary}` : '',
     boundedFallbackPrompt ? `Base heartbeat instructions:\n${boundedFallbackPrompt}` : '',
     '',
     'You are checking the durable main mission thread for this agent.',
     'Keep this status check brief — 5-10 tool calls maximum. Read key state, summarize progress, and report. Do not attempt fixes or deep investigation during heartbeats.',
-    'Use only the current goal, plan, next action, and pending external events shown above.',
+    'Use the execution brief and pending external events shown above as the authoritative state for this tick.',
     'Do not infer or repeat old tasks from prior heartbeats.',
     'Prefer taking the single highest-value next step over restating the plan. Do not repeat completed work.',
     'If you revise the plan, emit exactly one line like:',
@@ -827,6 +877,7 @@ export function getMainLoopStateForSession(sessionId: string): MainLoopState | n
 
 export function clearMainLoopStateForSession(sessionId: string): boolean {
   deletePersistedMainLoopState(sessionId)
+  deleteSessionWorkingState(sessionId)
   return stateMap.delete(sessionId)
 }
 
@@ -840,6 +891,7 @@ export function pruneMainLoopState(liveSessionIds: Set<string>): number {
     if (!liveSessionIds.has(sessionId)) {
       stateMap.delete(sessionId)
       deletePersistedMainLoopState(sessionId)
+      deleteSessionWorkingState(sessionId)
       removed++
     }
   }
@@ -1096,5 +1148,11 @@ export function handleMainLoopRunResult(input: HandleMainLoopRunResultInput): Ma
   const finalClamped = clampState(state)
   stateMap.set(input.sessionId, finalClamped)
   persistState(input.sessionId, finalClamped)
+
+  // Project orchestrator state into session RunContext (non-critical)
+  try {
+    syncMainLoopToRunContext(input.sessionId, finalClamped)
+  } catch { /* non-critical — main loop continues even if sync fails */ }
+
   return followup
 }