@lota-sdk/core 0.1.20 → 0.1.22

package/src/services/plan-event-delivery.service.ts

@@ -0,0 +1,170 @@
+import { PlanEventSchema } from '@lota-sdk/shared'
+import type { PlanEventRecord } from '@lota-sdk/shared'
+
+import { ensureRecordId, recordIdToString } from '../db/record-id'
+import { databaseService } from '../db/service'
+import { TABLES } from '../db/tables'
+import { getRedisConnection } from '../redis'
+import { resolvePlanNodeExecutionVisibility } from '../runtime/execution-plan-visibility'
+import { getRuntimeAdapters } from '../runtime/runtime-extensions'
+import type { LotaRuntimePlanEventEnvelope } from '../runtime/runtime-extensions'
+import { planRunService } from './plan-run.service'
+import { userService } from './user.service'
+import { WorkstreamSchema } from './workstream.types'
+
+const PLAN_EVENT_DELIVERED_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+function buildDeliveredKey(eventId: string): string {
+  return `plan-event:delivered:${eventId}`
+}
+
+class PlanEventDeliveryService {
+  async dispatchEvents(events: PlanEventRecord[]): Promise<void> {
+    const runIds = new Set(events.map((event) => recordIdToString(event.runId, TABLES.PLAN_RUN)))
+    for (const runId of runIds) {
+      await this.dispatchUndeliveredEvents(runId)
+    }
+  }
+
+  async dispatchEvent(rawEvent: PlanEventRecord): Promise<void> {
+    const event = PlanEventSchema.parse(rawEvent)
+    const eventId = recordIdToString(event.id, TABLES.PLAN_EVENT)
+    const deliveredKey = buildDeliveredKey(eventId)
+    if (await getRedisConnection().exists(deliveredKey)) {
+      return
+    }
+
+    await this.deliverEvent(event)
+    await getRedisConnection().set(deliveredKey, '1', 'PX', PLAN_EVENT_DELIVERED_TTL_MS)
+  }
+
+  private async deliverEvent(rawEvent: PlanEventRecord): Promise<void> {
+    const event = PlanEventSchema.parse(rawEvent)
+    const run = await planRunService.getRunById(event.runId)
+    const [spec, nodeSpecs, nodeRuns, workstream] = await Promise.all([
+      planRunService.getPlanSpecById(run.planSpecId),
+      planRunService.listNodeSpecs(run.planSpecId),
+      planRunService.listNodeRuns(run.id),
+      databaseService.findOne(
+        TABLES.WORKSTREAM,
+        { id: ensureRecordId(run.workstreamId, TABLES.WORKSTREAM) },
+        WorkstreamSchema,
+      ),
+    ])
+    const nodeSpecsById = new Map(nodeSpecs.map((nodeSpec) => [nodeSpec.nodeId, nodeSpec]))
+    const nodeRunsById = new Map(nodeRuns.map((nodeRun) => [nodeRun.nodeId, nodeRun]))
+    const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
+    const workstreamId = recordIdToString(run.workstreamId, TABLES.WORKSTREAM)
+    const runIdString = recordIdToString(run.id, TABLES.PLAN_RUN)
+    const planSpecId = recordIdToString(spec.id, TABLES.PLAN_SPEC)
+    const userId = workstream?.userId
+      ? recordIdToString(ensureRecordId(workstream.userId, TABLES.USER), TABLES.USER)
+      : undefined
+    const userName =
+      userId === undefined
+        ? undefined
+        : await userService
+            .getUser(userId)
+            .then((user) => user.name)
+            .catch(() => undefined)
+
+    const envelope: LotaRuntimePlanEventEnvelope = {
+      event,
+      spec,
+      run,
+      ...(event.nodeId ? { nodeSpec: nodeSpecsById.get(event.nodeId) } : {}),
+      ...(event.nodeId ? { nodeRun: nodeRunsById.get(event.nodeId) } : {}),
+      organizationId,
+      workstreamId,
+      runId: runIdString,
+      planSpecId,
+      ...(userId ? { userId } : {}),
+      ...(userName ? { userName } : {}),
+    }
+
+    await this.dispatchAdapterEvent(envelope)
+    await this.enqueueWakeIfNeeded(envelope, nodeSpecsById)
+  }
+
+  async dispatchUndeliveredEvents(runId: string, options?: { limit?: number }): Promise<void> {
+    const run = await planRunService.getRunById(runId)
+    const events = await planRunService.listEvents(run.id, options?.limit ?? 200)
+
+    for (const rawEvent of events) {
+      const event = PlanEventSchema.parse(rawEvent)
+      const eventId = recordIdToString(event.id, TABLES.PLAN_EVENT)
+      const deliveredKey = buildDeliveredKey(eventId)
+      if (await getRedisConnection().exists(deliveredKey)) {
+        continue
+      }
+
+      await this.dispatchEvent(event)
+    }
+  }
+
+  private async dispatchAdapterEvent(envelope: LotaRuntimePlanEventEnvelope): Promise<void> {
+    const adapter = getRuntimeAdapters().events?.planEventAdapter
+    if (!adapter) {
+      return
+    }
+
+    await adapter.onPlanEvent(envelope)
+  }
+
+  private async enqueueWakeIfNeeded(
+    envelope: LotaRuntimePlanEventEnvelope,
+    nodeSpecsById: Map<string, NonNullable<LotaRuntimePlanEventEnvelope['nodeSpec']>>,
+  ): Promise<void> {
+    const wakeTarget = this.resolveWakeTarget(envelope, nodeSpecsById)
+    if (!wakeTarget) {
+      return
+    }
+
+    const { enqueuePlanAgentHeartbeatWake } = await import('../queues/plan-agent-heartbeat.queue')
+    await enqueuePlanAgentHeartbeatWake({
+      organizationId: envelope.organizationId,
+      workstreamId: envelope.workstreamId,
+      runId: envelope.runId,
+      nodeId: wakeTarget.nodeId,
+      agentId: wakeTarget.agentId,
+      reason: wakeTarget.reason,
+    })
+  }
+
+  private resolveWakeTarget(
+    envelope: LotaRuntimePlanEventEnvelope,
+    nodeSpecsById: Map<string, NonNullable<LotaRuntimePlanEventEnvelope['nodeSpec']>>,
+  ): { nodeId: string; agentId: string; reason: string } | null {
+    const currentNodeId = envelope.run.currentNodeId ?? envelope.event.nodeId
+    if (!currentNodeId) {
+      return null
+    }
+
+    const effectiveNodeSpec =
+      (envelope.event.nodeId === currentNodeId ? envelope.nodeSpec : undefined) ?? nodeSpecsById.get(currentNodeId)
+    if (!effectiveNodeSpec || effectiveNodeSpec.owner.executorType !== 'agent') {
+      return null
+    }
+
+    const isVisible = resolvePlanNodeExecutionVisibility(envelope.spec, effectiveNodeSpec) === 'visible'
+    if (!isVisible) {
+      return null
+    }
+
+    const supportedEventTypes = new Set([
+      'node-ready',
+      'node-unblocked',
+      'approval-resolved',
+      'run-resumed',
+      'deadline-warning',
+      'escalation-triggered',
+    ])
+    if (!supportedEventTypes.has(envelope.event.eventType)) {
+      return null
+    }
+
+    return { nodeId: currentNodeId, agentId: effectiveNodeSpec.owner.ref, reason: envelope.event.eventType }
+  }
+}
+
+export const planEventDeliveryService = new PlanEventDeliveryService()

package/src/services/plan-executor.service.ts

@@ -35,7 +35,8 @@ import { planApprovalService } from './plan-approval.service'
 import { planArtifactService } from './plan-artifact.service'
 import { planCheckpointService } from './plan-checkpoint.service'
 import { planCoordinationService } from './plan-coordination.service'
-import { readPathValue } from './plan-helpers'
+import { planEventDeliveryService } from './plan-event-delivery.service'
+import { isExecutableConditionExpression, readPathValue } from './plan-helpers'
 import { planRunService } from './plan-run.service'
 import { planSchedulerService } from './plan-scheduler.service'
 import type { PlanValidationIssueInput } from './plan-validator.service'
@@ -117,6 +118,9 @@ function evaluateCondition(expression: string | undefined, context: Record<strin
 
   const match = normalized.match(/^([a-zA-Z0-9_.]+)\s*(==|!=|>=|<=|>|<)\s*(.+)$/)
   if (!match) {
+    if (!isExecutableConditionExpression(normalized)) {
+      return true
+    }
     return Boolean(readPathValue(context, normalized))
   }
 
@@ -164,6 +168,7 @@ type PlanNodeRunUpdate = Omit<
   | 'resolvedInput'
   | 'latestStructuredOutput'
   | 'latestNotes'
+  | 'handoffContext'
   | 'latestAttemptId'
   | 'scheduledAt'
   | 'readyAt'
@@ -175,6 +180,7 @@ type PlanNodeRunUpdate = Omit<
   resolvedInput?: Record<string, unknown> | null
   latestStructuredOutput?: Record<string, unknown> | null
   latestNotes?: string | null
+  handoffContext?: Record<string, unknown> | null
   latestAttemptId?: RecordIdInput | null
   scheduledAt?: string | Date | null
   readyAt?: string | Date | null
@@ -265,6 +271,13 @@ function toNodeRunData(nodeRun: PlanNodeRunRecord, patch: PlanNodeRunUpdate) {
         : nodeRun.latestNotes
           ? { latestNotes: nodeRun.latestNotes }
           : {}),
+    ...(patch.handoffContext === null
+      ? {}
+      : patch.handoffContext !== undefined
+        ? { handoffContext: patch.handoffContext }
+        : nodeRun.handoffContext
+          ? { handoffContext: nodeRun.handoffContext }
+          : {}),
     ...(patch.latestAttemptId === null
       ? {}
       : patch.latestAttemptId !== undefined
@@ -404,9 +417,12 @@ class PlanExecutorService {
           attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
           webPolicy: nodeSpec.contextPolicy.webPolicy,
         },
+        executionVisibility: nodeSpec.executionVisibility,
+        ...(nodeSpec.escalation ? { escalation: nodeSpec.escalation } : {}),
       },
       result: params.result,
     })
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const attempt = await this.createAttempt({
@@ -462,6 +478,7 @@ class PlanExecutorService {
               latestAttemptId: finalizedAttempt.id,
               latestStructuredOutput: params.result.structuredOutput ?? null,
               latestNotes: params.result.notes ?? null,
+              handoffContext: params.result.handoffContext ?? null,
             }),
           )
           .output('after'),
@@ -507,6 +524,21 @@ class PlanExecutorService {
             message: `Validation failed for node "${nodeSpec.label}", scheduling retry.`,
             detail: { issues: validation.blocking.map((issue) => issue.code) },
             emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
+          })
+          await this.emitEvent({
+            tx,
+            run,
+            spec,
+            nodeId: nextNodeRun.nodeId,
+            attemptId: finalizedAttempt.id,
+            eventType: 'node-unblocked',
+            fromStatus: nodeRun.status,
+            toStatus: nextNodeRun.status,
+            message: `Node "${nodeSpec.label}" is ready for another attempt.`,
+            detail: { retryCount: nextNodeRun.retryCount },
+            emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
           })
 
           const synced = await this.syncRunGraph({
@@ -519,6 +551,7 @@ class PlanExecutorService {
             ),
             artifacts: nextArtifacts,
             emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
           })
 
           const checkpoint = await this.saveCheckpoint({
@@ -528,6 +561,7 @@ class PlanExecutorService {
             artifacts: synced.artifacts,
             sequence: (latestCheckpoint?.sequence ?? 0) + 1,
             reason: 'node-result-retry',
+            capturedEvents: emittedEvents,
           })
 
           await this.attachCheckpoint(tx, synced.run, checkpoint)
@@ -587,6 +621,7 @@ class PlanExecutorService {
             message: `Node "${nodeSpec.label}" requires human review before continuing.`,
             detail: { issues: validation.blocking.map((issue) => issue.code) },
             emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
           })
 
           const checkpoint = await this.saveCheckpoint({
@@ -598,6 +633,7 @@ class PlanExecutorService {
             artifacts: nextArtifacts,
             sequence: (latestCheckpoint?.sequence ?? 0) + 1,
             reason: 'node-result-human-review',
+            capturedEvents: emittedEvents,
           })
 
           await this.attachCheckpoint(tx, failedRun, checkpoint)
@@ -639,6 +675,7 @@ class PlanExecutorService {
             message: `Node "${nodeSpec.label}" failed validation and requires replanning.`,
             detail: { failureClass: validation.failureClass, issues: validation.blocking.map((issue) => issue.code) },
             emittedBy: params.emittedBy,
+            capturedEvents: emittedEvents,
           })
 
           const checkpoint = await this.saveCheckpoint({
@@ -650,6 +687,7 @@ class PlanExecutorService {
             artifacts: nextArtifacts,
             sequence: (latestCheckpoint?.sequence ?? 0) + 1,
             reason: 'node-result-replan',
+            capturedEvents: emittedEvents,
           })
 
           await this.attachCheckpoint(tx, blockedRun, checkpoint)
@@ -692,6 +730,7 @@ class PlanExecutorService {
           message: `Node "${nodeSpec.label}" failed validation and the run has been aborted.`,
           detail: { failureClass: validation.failureClass, issues: validation.blocking.map((issue) => issue.code) },
           emittedBy: params.emittedBy,
+          capturedEvents: emittedEvents,
         })
 
         const checkpoint = await this.saveCheckpoint({
@@ -703,6 +742,7 @@ class PlanExecutorService {
           artifacts: nextArtifacts,
           sequence: (latestCheckpoint?.sequence ?? 0) + 1,
           reason: 'node-result-failed',
+          capturedEvents: emittedEvents,
         })
 
         await this.attachCheckpoint(tx, failedRun, checkpoint)
@@ -718,6 +758,7 @@ class PlanExecutorService {
               latestAttemptId: finalizedAttempt.id,
               latestStructuredOutput: params.result.structuredOutput ?? null,
               latestNotes: params.result.notes ?? null,
+              handoffContext: params.result.handoffContext ?? null,
               blockedReason: null,
               failureClass: null,
               completedAt: new Date(),
@@ -741,6 +782,7 @@ class PlanExecutorService {
             : `Node "${nodeSpec.label}" completed successfully.`,
         detail: { warningCount: validation.warnings.length },
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const synced = await this.syncRunGraph({
@@ -753,6 +795,7 @@ class PlanExecutorService {
         ),
         artifacts: nextArtifacts,
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const checkpoint = await this.saveCheckpoint({
@@ -762,6 +805,7 @@ class PlanExecutorService {
         artifacts: synced.artifacts,
         sequence: (latestCheckpoint?.sequence ?? 0) + 1,
         reason: 'node-result-complete',
+        capturedEvents: emittedEvents,
       })
 
       await this.attachCheckpoint(tx, synced.run, checkpoint)
@@ -802,7 +846,7 @@ class PlanExecutorService {
         .then(async (recommendations) => {
           if (recommendations.length === 0) return
           const specRecord = await planRunService.getPlanSpecById(updatedRun.planSpecId)
-          await databaseService.create(
+          const event = await databaseService.create(
             TABLES.PLAN_EVENT,
             {
               planSpecId: ensureRecordId(specRecord.id, TABLES.PLAN_SPEC),
@@ -814,6 +858,7 @@ class PlanExecutorService {
             },
             PlanEventSchema,
           )
+          await planEventDeliveryService.dispatchEvent(event)
         })
         .catch((error) => {
           aiLogger.warn`Failed to analyze feedback outcomes for run ${runIdStr}: ${error instanceof Error ? error.message : String(error)}`
@@ -823,6 +868,8 @@ class PlanExecutorService {
       })
     }
 
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
     const snapshot = await planRunService.toSerializablePlan(updatedRun, {
       includeEvents: true,
       includeArtifacts: true,
@@ -891,6 +938,8 @@ class PlanExecutorService {
           attachmentPolicy: nodeSpec.contextPolicy.attachmentPolicy,
           webPolicy: nodeSpec.contextPolicy.webPolicy,
         },
+        executionVisibility: nodeSpec.executionVisibility,
+        ...(nodeSpec.escalation ? { escalation: nodeSpec.escalation } : {}),
       },
       result: {
         structuredOutput: params.response,
@@ -898,6 +947,7 @@ class PlanExecutorService {
         notes: typeof params.response.comments === 'string' ? params.response.comments : undefined,
       },
     })
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const approvalStatus = deriveApprovalStatus(params.response)
@@ -964,6 +1014,7 @@ class PlanExecutorService {
                     latestAttemptId: attempt.id,
                     latestStructuredOutput: params.response,
                     latestNotes: typeof params.response.comments === 'string' ? params.response.comments : null,
+                    handoffContext: null,
                     blockedReason: validation.blocking[0]?.message ?? null,
                     failureClass: validation.failureClass,
                   }),
@@ -980,6 +1031,7 @@ class PlanExecutorService {
                     latestAttemptId: attempt.id,
                     latestStructuredOutput: params.response,
                     latestNotes: typeof params.response.comments === 'string' ? params.response.comments : null,
+                    handoffContext: null,
                     blockedReason: null,
                     failureClass: null,
                     completedAt: new Date(),
@@ -1014,6 +1066,7 @@ class PlanExecutorService {
           message: `Human response for node "${nodeSpec.label}" blocked execution.`,
           detail: { issues: validation.blocking.map((issue) => issue.code) },
           emittedBy: params.respondedBy,
+          capturedEvents: emittedEvents,
         })
 
         const checkpoint = await this.saveCheckpoint({
@@ -1023,6 +1076,7 @@ class PlanExecutorService {
           artifacts: existingArtifacts,
           sequence: (latestCheckpoint?.sequence ?? 0) + 1,
           reason: 'human-response-blocked',
+          capturedEvents: emittedEvents,
         })
         await this.attachCheckpoint(tx, blockedRun, checkpoint)
         return
@@ -1036,6 +1090,7 @@ class PlanExecutorService {
         nodeRuns,
         artifacts: existingArtifacts,
         emittedBy: params.respondedBy,
+        capturedEvents: emittedEvents,
       })
 
       await this.emitEvent({
@@ -1051,6 +1106,7 @@ class PlanExecutorService {
         message: `Human response for node "${nodeSpec.label}" accepted.`,
         detail: { approvalStatus: approvalStatus },
         emittedBy: params.respondedBy,
+        capturedEvents: emittedEvents,
       })
 
       const checkpoint = await this.saveCheckpoint({
@@ -1060,10 +1116,13 @@ class PlanExecutorService {
         artifacts: synced.artifacts,
         sequence: (latestCheckpoint?.sequence ?? 0) + 1,
         reason: 'human-response-complete',
+        capturedEvents: emittedEvents,
       })
       await this.attachCheckpoint(tx, synced.run, checkpoint)
     })
 
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
     return planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
       includeEvents: true,
       includeArtifacts: true,
@@ -1090,6 +1149,7 @@ class PlanExecutorService {
     const nodeRuns = await planRunService.listNodeRuns(run.id)
     const artifacts = await planRunService.listArtifacts(run.id)
     const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       let currentNodeRuns = [...nodeRuns]
@@ -1130,6 +1190,7 @@ class PlanExecutorService {
         message: `Run "${spec.title}" resumed from the latest checkpoint.`,
         detail: latestCheckpoint ? { checkpointId: recordIdToString(latestCheckpoint.id, TABLES.PLAN_CHECKPOINT) } : {},
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const synced =
@@ -1143,6 +1204,7 @@ class PlanExecutorService {
               nodeRuns: currentNodeRuns,
               artifacts,
               emittedBy: params.emittedBy,
+              capturedEvents: emittedEvents,
             })
 
       const checkpoint = await this.saveCheckpoint({
@@ -1152,10 +1214,13 @@ class PlanExecutorService {
         artifacts: synced.artifacts,
         sequence: (latestCheckpoint?.sequence ?? 0) + 1,
         reason: 'run-resumed',
+        capturedEvents: emittedEvents,
       })
       await this.attachCheckpoint(tx, synced.run, checkpoint)
     })
 
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
     const snapshot = await planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
       includeEvents: true,
       includeArtifacts: true,
@@ -1216,6 +1281,7 @@ class PlanExecutorService {
     const nodeRun = await planRunService.getNodeRunByNodeId(run.id, params.nodeId)
     const artifacts = await planRunService.listArtifacts(run.id)
     const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const blockedNodeRun =
@@ -1253,6 +1319,7 @@ class PlanExecutorService {
         message: `Node "${nodeSpec.label}" failed during owner dispatch.`,
         detail: { failureClass: params.failureClass, phase: 'dispatch', error: params.message },
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const checkpoint = await this.saveCheckpoint({
@@ -1264,10 +1331,13 @@ class PlanExecutorService {
         artifacts,
         sequence: (latestCheckpoint?.sequence ?? 0) + 1,
         reason: 'owner-dispatch-failed',
+        capturedEvents: emittedEvents,
       })
       await this.attachCheckpoint(tx, blockedRun, checkpoint)
     })
 
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
+
     return planRunService.toSerializablePlan(await planRunService.getRunById(run.id), {
       includeEvents: true,
       includeArtifacts: true,
@@ -1293,6 +1363,7 @@ class PlanExecutorService {
     const nodeRuns = await planRunService.listNodeRuns(run.id)
     const artifacts = await planRunService.listArtifacts(run.id)
     const latestCheckpoint = await planRunService.getLatestCheckpoint(run.id)
+    const emittedEvents: PlanEventRecord[] = []
 
     await databaseService.withTransaction(async (tx) => {
       const readyNodeRun = PlanNodeRunSchema.parse(
@@ -1317,6 +1388,7 @@ class PlanExecutorService {
         toStatus: readyNodeRun.status,
         message: `Node "${nodeSpec?.label ?? params.nodeId}" promoted to ready after delay.`,
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const synced = await this.syncRunGraph({
@@ -1327,6 +1399,7 @@ class PlanExecutorService {
         nodeRuns: updatedNodeRuns,
         artifacts,
         emittedBy: params.emittedBy,
+        capturedEvents: emittedEvents,
       })
 
       const checkpoint = await this.saveCheckpoint({
@@ -1336,9 +1409,12 @@ class PlanExecutorService {
         artifacts: synced.artifacts,
         sequence: (latestCheckpoint?.sequence ?? 0) + 1,
         reason: 'delayed-node-promoted',
+        capturedEvents: emittedEvents,
       })
       await this.attachCheckpoint(tx, synced.run, checkpoint)
     })
+
+    await planEventDeliveryService.dispatchEvents(emittedEvents)
   }
 
   async syncRunGraph(params: {
@@ -1357,6 +1433,7 @@ class PlanExecutorService {
       payload?: unknown
     }>
     emittedBy: string
+    capturedEvents?: PlanEventRecord[]
   }): Promise<{
     run: PlanRunRecord
     nodeRuns: PlanNodeRunRecord[]
@@ -1392,6 +1469,7 @@ class PlanExecutorService {
           toStatus: currentRun.status,
           message: `Run blocked: unresolved cross-plan dependencies (${unresolved.map((d) => d.sourcePlanTitle).join(', ')}).`,
           emittedBy: params.emittedBy,
+          capturedEvents: params.capturedEvents,
         })
         return { run: currentRun, nodeRuns: currentNodeRuns, artifacts: currentArtifacts }
       }
@@ -1465,6 +1543,7 @@ class PlanExecutorService {
             toStatus: skippedNodeRun.status,
             message: `Node "${nodeSpec.label}" was skipped because no inbound branch was activated.`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
           changed = true
           continue
@@ -1501,6 +1580,7 @@ class PlanExecutorService {
             toStatus: scheduledNodeRun.status,
             message: `Node "${nodeSpec.label}" is scheduled (${nodeSchedule.type}).`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
           changed = true
         } else if (nodeSpec.delayAfterPredecessorMs) {
@@ -1531,6 +1611,7 @@ class PlanExecutorService {
             toStatus: scheduledNodeRun.status,
             message: `Node "${nodeSpec.label}" is delayed by ${nodeSpec.delayAfterPredecessorMs}ms after predecessor.`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
           changed = true
         } else {
@@ -1551,6 +1632,7 @@ class PlanExecutorService {
             toStatus: readyNodeRun.status,
             message: `Node "${nodeSpec.label}" is ready to execute.`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
           changed = true
         }
@@ -1588,6 +1670,7 @@ class PlanExecutorService {
           toStatus: completedNodeRun.status,
           message: `Structural node "${nodeSpec.label}" auto-completed.`,
           emittedBy: params.emittedBy,
+          capturedEvents: params.capturedEvents,
         })
         changed = true
       }
@@ -1657,6 +1740,7 @@ class PlanExecutorService {
           toStatus: currentRun.status,
           message: `Node "${nextHumanNodeSpec.label}" is awaiting human input.`,
           emittedBy: params.emittedBy,
+          capturedEvents: params.capturedEvents,
         })
       } else {
         const nextActionNodeSpec = sortedNodeSpecs.find((nodeSpec) => {
@@ -1696,6 +1780,20 @@ class PlanExecutorService {
             toStatus: runningNodeRun.status,
             message: `Node "${nextActionNodeSpec.label}" is now running.`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
+          })
+          await this.emitEvent({
+            tx: params.tx,
+            run: currentRun,
+            spec: params.spec,
+            nodeId: runningNodeRun.nodeId,
+            eventType: 'ownership-transition',
+            fromStatus: params.run.currentNodeId ?? undefined,
+            toStatus: runningNodeRun.nodeId,
+            message: `Execution ownership transitioned to "${nextActionNodeSpec.label}".`,
+            detail: { owner: nextActionNodeSpec.owner },
+            emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
         } else if (currentNodeRuns.every((nodeRun) => isSuccessfulTerminalStatus(nodeRun.status))) {
           currentRun = await this.replaceRun(params.tx, currentRun, {
@@ -1715,6 +1813,7 @@ class PlanExecutorService {
             toStatus: currentRun.status,
             message: `Run "${params.spec.title}" completed.`,
             emittedBy: params.emittedBy,
+            capturedEvents: params.capturedEvents,
           })
         } else if (hasScheduledOrMonitoring) {
           // Nodes are waiting on schedules/monitors — run stays active
@@ -1863,6 +1962,7 @@ class PlanExecutorService {
     fromStatus?: string
     toStatus?: string
     detail?: Record<string, unknown>
+    capturedEvents?: PlanEventRecord[]
   }): Promise<PlanEventRecord> {
     const eventId = new RecordId(TABLES.PLAN_EVENT, Bun.randomUUIDv7())
     const created = await params.tx
@@ -1882,7 +1982,9 @@ class PlanExecutorService {
       })
       .output('after')
 
-    return PlanEventSchema.parse(created)
+    const event = PlanEventSchema.parse(created)
+    params.capturedEvents?.push(event)
+    return event
   }
 
   private async replaceRun(tx: DatabaseTransaction, run: PlanRunRecord, patch: PlanRunUpdate): Promise<PlanRunRecord> {
@@ -1899,6 +2001,7 @@ class PlanExecutorService {
     sequence: number
     reason: string
     includeWorkspace?: boolean
+    capturedEvents?: PlanEventRecord[]
   }) {
     const checkpoint = await planCheckpointService.createCheckpoint({
       tx: params.tx,
@@ -1930,6 +2033,7 @@ class PlanExecutorService {
       message: `Saved checkpoint ${checkpoint.sequence}.`,
       detail: { checkpointId: recordIdToString(checkpoint.id, TABLES.PLAN_CHECKPOINT), reason: params.reason },
       emittedBy: 'system',
+      capturedEvents: params.capturedEvents,
     })
 
     return checkpoint

package/src/services/plan-helpers.ts

@@ -13,3 +13,16 @@ export function readPathValue(source: unknown, path: string): unknown {
   }
   return current
 }
+
+export function isExecutableConditionExpression(expression: string | undefined): boolean {
+  if (!expression?.trim()) return false
+
+  const normalized = expression.trim()
+  if (normalized === 'always') return true
+
+  if (/^[a-zA-Z0-9_.]+$/.test(normalized)) {
+    return true
+  }
+
+  return /^[a-zA-Z0-9_.]+\s*(==|!=|>=|<=|>|<)\s*.+$/.test(normalized)
+}