@lota-sdk/core 0.1.20 → 0.1.22

package/infrastructure/schema/02_execution_plan.surql

@@ -17,6 +17,7 @@ DEFINE FIELD IF NOT EXISTS edges.*.target ON TABLE planSpec TYPE string;
 DEFINE FIELD IF NOT EXISTS edges.*.when ON TABLE planSpec TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS edges.*.map ON TABLE planSpec TYPE object FLEXIBLE DEFAULT {};
 DEFINE FIELD IF NOT EXISTS entryNodeIds ON TABLE planSpec TYPE array<string>;
+DEFINE FIELD IF NOT EXISTS defaultExecutionVisibility ON TABLE planSpec TYPE string DEFAULT 'auto';
 DEFINE FIELD IF NOT EXISTS executionMode ON TABLE planSpec TYPE string DEFAULT 'linear';
 DEFINE FIELD IF NOT EXISTS contextEnrichments ON TABLE planSpec TYPE option<array<object>> FLEXIBLE;
 DEFINE FIELD OVERWRITE contextEnrichments.* ON TABLE planSpec TYPE object FLEXIBLE;
@@ -65,8 +66,10 @@ DEFINE FIELD IF NOT EXISTS failurePolicy.*.note ON TABLE planNodeSpec TYPE strin
 DEFINE FIELD IF NOT EXISTS timeoutMs ON TABLE planNodeSpec TYPE option<int>;
 DEFINE FIELD IF NOT EXISTS toolPolicy ON TABLE planNodeSpec TYPE object FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS contextPolicy ON TABLE planNodeSpec TYPE object FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS executionVisibility ON TABLE planNodeSpec TYPE string DEFAULT 'auto';
 DEFINE FIELD IF NOT EXISTS schedule ON TABLE planNodeSpec TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS deadline ON TABLE planNodeSpec TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS escalation ON TABLE planNodeSpec TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS monitoringConfig ON TABLE planNodeSpec TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS delayAfterPredecessorMs ON TABLE planNodeSpec TYPE option<int>;
 DEFINE FIELD IF NOT EXISTS deliberationConfig ON TABLE planNodeSpec TYPE option<object> FLEXIBLE;
@@ -113,6 +116,7 @@ DEFINE FIELD IF NOT EXISTS retryCount ON TABLE planNodeRun TYPE int DEFAULT 0;
 DEFINE FIELD IF NOT EXISTS resolvedInput ON TABLE planNodeRun TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS latestStructuredOutput ON TABLE planNodeRun TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS latestNotes ON TABLE planNodeRun TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS handoffContext ON TABLE planNodeRun TYPE option<object> FLEXIBLE;
 DEFINE FIELD IF NOT EXISTS latestAttemptId ON TABLE planNodeRun TYPE option<record<planNodeAttempt>>;
 DEFINE FIELD IF NOT EXISTS blockedReason ON TABLE planNodeRun TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS failureClass ON TABLE planNodeRun TYPE option<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lota-sdk/core",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -19,7 +19,7 @@
     "lint": "bunx oxlint --fix -c ../oxlint.config.ts src",
     "format": "bunx oxfmt src",
     "typecheck": "bunx tsgo --noEmit",
-    "test:unit": "bun test ../tests/unit/core",
+    "test:unit": "bun test --max-concurrency=1 ../tests/unit/core",
     "test:coverage": "bun test --coverage ../tests/unit/core"
   },
   "publishConfig": {
@@ -32,11 +32,11 @@
     "@chat-adapter/slack": "^4.23.0",
     "@chat-adapter/state-ioredis": "^4.23.0",
     "@logtape/logtape": "^2.0.5",
-    "@lota-sdk/shared": "0.1.20",
-    "@mendable/firecrawl-js": "^4.17.0",
+    "@lota-sdk/shared": "0.1.22",
+    "@mendable/firecrawl-js": "^4.18.0",
     "@surrealdb/node": "^3.0.3",
-    "ai": "^6.0.137",
-    "bullmq": "^5.71.0",
+    "ai": "^6.0.141",
+    "bullmq": "^5.71.1",
     "chat": "^4.23.0",
     "cron-parser": "^5.5.0",
     "hono": "^4.12.9",

package/src/ai-gateway/ai-gateway.ts

@@ -349,7 +349,7 @@ function createAiGatewayFetch(extraParams?: AiGatewayExtraParams): typeof fetch
         ? injectAiGatewayExtraParamsRequestBody(bodyWithPromptCacheRetention, extraParams)
         : bodyWithPromptCacheRetention
 
-    const headers = new Headers(init?.headers as HeadersInit | undefined)
+    const headers = new Headers(init?.headers)
     if (extraParams !== undefined || (isAiGatewayOpenAIModelRequest(body) && hasAiGatewayPromptCacheRetention(body))) {
       // Bifrost only forwards provider-specific extra params when passthrough is enabled.
       headers.set(AI_GATEWAY_EXTRA_PARAMS_HEADER, 'true')
@@ -370,9 +370,7 @@ function createAiGatewayProvider(extraParams?: AiGatewayExtraParams) {
   return createOpenAI({
     baseURL,
     apiKey,
-    headers: {
-      [AI_GATEWAY_VIRTUAL_KEY_HEADER]: apiKey,
-    },
+    headers: { [AI_GATEWAY_VIRTUAL_KEY_HEADER]: apiKey },
     fetch: createAiGatewayFetch(extraParams),
   })
 }

package/src/create-runtime.ts

@@ -46,6 +46,8 @@ import type { organizationMemberService } from './services/organization-member.s
 import { organizationMemberService as organizationMemberServiceSingleton } from './services/organization-member.service'
 import type { organizationService } from './services/organization.service'
 import { organizationService as organizationServiceSingleton } from './services/organization.service'
+import type { planAgentQueryService } from './services/plan-agent-query.service'
+import { planAgentQueryService as planAgentQueryServiceSingleton } from './services/plan-agent-query.service'
 import { playbookRegistryService } from './services/playbook-registry.service'
 import type { recentActivityTitleService } from './services/recent-activity-title.service'
 import { recentActivityTitleService as recentActivityTitleServiceSingleton } from './services/recent-activity-title.service'
@@ -67,6 +69,7 @@ import type {
   createWorkstreamNativeToolApprovalStream,
   createWorkstreamTurnStream,
   runWorkstreamTurnInBackground,
+  triggerPlanNodeTurn,
 } from './services/workstream-turn'
 import {
   createWorkstreamApprovalContinuationStream as createWorkstreamApprovalContinuationStreamSingleton,
@@ -74,6 +77,7 @@ import {
   createWorkstreamTurnStream as createWorkstreamTurnStreamSingleton,
   isApprovalContinuationRequest as isApprovalContinuationRequestSingleton,
   runWorkstreamTurnInBackground as runWorkstreamTurnInBackgroundSingleton,
+  triggerPlanNodeTurn as triggerPlanNodeTurnSingleton,
 } from './services/workstream-turn'
 import type { workstreamService } from './services/workstream.service'
 import { workstreamService as workstreamServiceSingleton } from './services/workstream.service'
@@ -126,6 +130,7 @@ export interface LotaRuntime {
     recentActivityTitleService: typeof recentActivityTitleService
     socialChatHistoryService: typeof socialChatHistoryServiceSingleton
     executionPlanService: typeof executionPlanService
+    planAgentQueryService: typeof planAgentQueryService
     workstreamMessageService: typeof workstreamMessageService
     workstreamService: typeof workstreamService
     workstreamTitleService: typeof workstreamTitleService
@@ -134,6 +139,7 @@ export interface LotaRuntime {
     createWorkstreamTurnStream: typeof createWorkstreamTurnStream
     isApprovalContinuationRequest: typeof isApprovalContinuationRequest
     runWorkstreamTurnInBackground: typeof runWorkstreamTurnInBackground
+    triggerPlanNodeTurn: typeof triggerPlanNodeTurn
     syncPlaybookTemplates: typeof playbookRegistryService.syncPlaybookTemplates
   }
   lota: {
@@ -397,6 +403,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
         recentActivityTitleService: recentActivityTitleServiceSingleton,
         socialChatHistoryService: socialChatHistoryServiceSingleton,
         executionPlanService: executionPlanServiceSingleton,
+        planAgentQueryService: planAgentQueryServiceSingleton,
         workstreamMessageService: workstreamMessageServiceSingleton,
         workstreamService: workstreamServiceSingleton,
         workstreamTitleService: workstreamTitleServiceSingleton,
@@ -405,6 +412,7 @@ export async function createLotaRuntime(config: LotaRuntimeConfig): Promise<Lota
         createWorkstreamTurnStream: createWorkstreamTurnStreamSingleton,
         isApprovalContinuationRequest: isApprovalContinuationRequestSingleton,
         runWorkstreamTurnInBackground: runWorkstreamTurnInBackgroundSingleton,
+        triggerPlanNodeTurn: triggerPlanNodeTurnSingleton,
         syncPlaybookTemplates: playbookRegistryService.syncPlaybookTemplates.bind(playbookRegistryService),
       },
       lota,

package/src/queues/document-processor.queue.ts

@@ -1,4 +1,5 @@
 import { Queue, Worker } from 'bullmq'
+import type { QueueOptions } from 'bullmq'
 import type IORedis from 'ioredis'
 
 import type { chatLogger } from '../config/logger'
@@ -70,22 +71,24 @@ export function createDocumentProcessorQueueRuntime<TJob extends DocumentProcess
   enqueue: (job: TJob) => Promise<unknown>
   startWorker: (options?: { registerSignals?: boolean }) => WorkerHandle
 } {
+  type QueueShape = Queue<TJob, unknown, string, TJob, unknown, string>
+
   const queueName = params.queueName ?? DEFAULT_DOCUMENT_PROCESSOR_QUEUE
   const workerName = params.workerName ?? DEFAULT_WORKER_NAME
   const concurrency = params.concurrency ?? 10
   const lockDuration = params.lockDuration ?? 300_000
-  const jobName = 'process-document' as Parameters<Queue<TJob, unknown, string>['add']>[0]
-  const toQueueData = (job: TJob): Parameters<Queue<TJob, unknown, string>['add']>[1] =>
-    job as Parameters<Queue<TJob, unknown, string>['add']>[1]
-  let queue: Queue<TJob, unknown, string> | null = null
+  const jobName = 'process-document' as Parameters<QueueShape['add']>[0]
+  const toQueueData = (job: TJob): Parameters<QueueShape['add']>[1] => job
+  let queue: QueueShape | null = null
+  const getConnection = (): IORedis => params.getConnectionForBullMQ()
 
-  const getQueue = (): Queue<TJob, unknown, string> => {
+  const getQueue = (): QueueShape => {
     if (queue) {
       return queue
     }
 
-    queue = new Queue<TJob, unknown, string>(queueName, {
-      connection: params.getConnectionForBullMQ(),
+    queue = new Queue<TJob, unknown, string, TJob, unknown, string>(queueName, {
+      connection: getConnection() as QueueOptions['connection'],
       defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 1000 } },
     })
 
@@ -108,7 +111,7 @@ export function createDocumentProcessorQueueRuntime<TJob extends DocumentProcess
     startWorker: (options = {}) => {
       const { registerSignals = import.meta.main } = options
       const worker = new Worker(queueName, params.getWorkerPath(), {
-        connection: params.getConnectionForBullMQ(),
+        connection: getConnection() as QueueOptions['connection'],
         concurrency,
         lockDuration,
       })

package/src/queues/index.ts

@@ -4,6 +4,7 @@ export * from './context-compaction.queue'
 export * from './delayed-node-promotion.queue'
 export * from './document-processor.queue'
 export * from './memory-consolidation.queue'
+export * from './plan-agent-heartbeat.queue'
 export * from './plan-scheduler.queue'
 export * from './post-chat-memory.queue'
 export * from './recent-activity-title-refinement.queue'

package/src/queues/plan-agent-heartbeat.queue.ts

@@ -0,0 +1,100 @@
+import type { Job } from 'bullmq'
+
+import { serverLogger } from '../config/logger'
+import { databaseService } from '../db/service'
+import { planAgentHeartbeatService } from '../services/plan-agent-heartbeat.service'
+import type { WorkerHandle } from '../workers/worker-utils'
+import { DEFAULT_JOB_RETENTION, LONG_JOB_LOCK_DURATION_MS } from '../workers/worker-utils'
+import { createQueueFactory } from './queue-factory'
+
+export interface PlanAgentHeartbeatWakeJob {
+  type: 'wake-node'
+  organizationId: string
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  reason: string
+}
+
+export interface PlanAgentHeartbeatSweepJob {
+  type: 'sweep'
+  organizationId?: string
+}
+
+export type PlanAgentHeartbeatJob = PlanAgentHeartbeatWakeJob | PlanAgentHeartbeatSweepJob
+
+export const PLAN_AGENT_HEARTBEAT_QUEUE = 'plan-agent-heartbeat'
+
+async function processPlanAgentHeartbeatJob(job: Job<PlanAgentHeartbeatJob>): Promise<void> {
+  await databaseService.connect()
+
+  if (job.data.type === 'wake-node') {
+    await planAgentHeartbeatService.wakeNode(job.data)
+    return
+  }
+
+  await planAgentHeartbeatService.sweep({ organizationId: job.data.organizationId })
+}
+
+const planAgentHeartbeatQueue = createQueueFactory<PlanAgentHeartbeatJob>({
+  name: PLAN_AGENT_HEARTBEAT_QUEUE,
+  displayName: 'Plan agent heartbeat',
+  jobName: 'plan-agent-heartbeat-job',
+  concurrency: 2,
+  lockDuration: LONG_JOB_LOCK_DURATION_MS,
+  stalledInterval: 120_000,
+  maxStalledCount: 5,
+  defaultJobOptions: { ...DEFAULT_JOB_RETENTION, attempts: 3, backoff: { type: 'exponential', delay: 5_000 } },
+  processor: processPlanAgentHeartbeatJob,
+})
+
+function buildWakeJobId(params: {
+  organizationId: string
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  reason: string
+}): string {
+  const encode = (value: string) => Buffer.from(value).toString('base64url')
+  return `plan-agent-wake__${encode(params.runId)}__${encode(params.nodeId)}__${encode(params.agentId)}`
+}
+
+export async function enqueuePlanAgentHeartbeatWake(params: {
+  organizationId: string
+  workstreamId: string
+  runId: string
+  nodeId: string
+  agentId: string
+  reason: string
+}): Promise<void> {
+  await planAgentHeartbeatQueue.enqueue({ type: 'wake-node', ...params }, { jobId: buildWakeJobId(params) })
+}
+
+const PLAN_AGENT_HEARTBEAT_SCHEDULER_ID = 'plan-agent-heartbeat-sweep'
+
+export async function schedulePlanAgentHeartbeatSweep(params?: { everyMs?: number }): Promise<void> {
+  const everyMs = params?.everyMs ?? 30_000
+  await planAgentHeartbeatQueue
+    .getQueue()
+    .upsertJobScheduler(
+      PLAN_AGENT_HEARTBEAT_SCHEDULER_ID,
+      { every: everyMs },
+      { name: 'plan-agent-heartbeat-job', data: { type: 'sweep' }, opts: { ...DEFAULT_JOB_RETENTION } },
+    )
+}
+
+export function startPlanAgentHeartbeatWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
+  const handle = planAgentHeartbeatQueue.startWorker(options)
+
+  schedulePlanAgentHeartbeatSweep().catch((error: unknown) => {
+    serverLogger.error`Plan agent heartbeat scheduler setup failed: ${error}`
+  })
+
+  return handle
+}
+
+if (import.meta.main) {
+  startPlanAgentHeartbeatWorker()
+}

package/src/queues/queue-factory.ts

@@ -1,5 +1,5 @@
 import { Queue, Worker } from 'bullmq'
-import type { Job, JobsOptions, WorkerOptions } from 'bullmq'
+import type { Job, JobsOptions, QueueOptions, WorkerOptions } from 'bullmq'
 import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
@@ -39,18 +39,20 @@ interface QueueFactoryConfigFile extends QueueFactoryConfigBase {
 export type QueueFactoryConfig<TJob> = QueueFactoryConfigInline<TJob> | QueueFactoryConfigFile
 
 export interface QueueFactory<TJob> {
-  getQueue: () => Queue<TJob, unknown, string>
+  getQueue: () => Queue<TJob, unknown, string, TJob, unknown, string>
   enqueue: (job: TJob, options?: JobsOptions) => Promise<void>
   startWorker: (options?: { registerSignals?: boolean }) => WorkerHandle
 }
 
 export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): QueueFactory<TJob> {
-  let _queue: Queue<TJob, unknown, string> | null = null
+  type QueueShape = Queue<TJob, unknown, string, TJob, unknown, string>
+
+  let _queue: QueueShape | null = null
   let _queueConnection: IORedis | null = null
 
-  const getConnection = () => config.connectionProvider?.() ?? getRedisConnectionForBullMQ()
+  const getConnection = (): IORedis => config.connectionProvider?.() ?? getRedisConnectionForBullMQ()
 
-  const getQueue = (): Queue<TJob, unknown, string> => {
+  const getQueue = (): QueueShape => {
     const connection = getConnection()
     const shouldRecreateQueue =
       _queue === null ||
@@ -66,8 +68,8 @@ export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): Queu
         })
       }
 
-      _queue = new Queue<TJob, unknown, string>(config.name, {
-        connection,
+      _queue = new Queue<TJob, unknown, string, TJob, unknown, string>(config.name, {
+        connection: connection as QueueOptions['connection'],
         defaultJobOptions: { ...DEFAULT_JOB_RETENTION, ...config.defaultJobOptions },
       })
       _queueConnection = connection
@@ -78,9 +80,8 @@ export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): Queu
     return _queue
   }
 
-  type QueueAdd = Queue<TJob, unknown, string>['add']
-  const jobName = config.jobName as Parameters<QueueAdd>[0]
-  const toData = (job: TJob) => job as Parameters<QueueAdd>[1]
+  const jobName = config.jobName
+  const toData = (job: TJob) => job
 
   const enqueue = async (job: TJob, options?: JobsOptions): Promise<void> => {
     const queuedJob = await getQueue().add(jobName, toData(job), options)
@@ -99,7 +100,7 @@ export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): Queu
     const { registerSignals = import.meta.main } = options
 
     const workerOptions: WorkerOptions = {
-      connection: getConnection(),
+      connection: getConnection() as QueueOptions['connection'],
       concurrency: config.concurrency,
       ...(config.lockDuration !== undefined ? { lockDuration: config.lockDuration } : {}),
       ...(config.stalledInterval !== undefined ? { stalledInterval: config.stalledInterval } : {}),

package/src/redis/redis-lease-lock.ts

@@ -43,7 +43,7 @@ end
 function log(logger: RedisLeaseLockLogger | undefined, level: keyof RedisLeaseLockLogger, message: string): void {
   const sink = logger?.[level]
   if (typeof sink === 'function') {
-    sink(message)
+    sink.call(logger, message)
   }
 }
 

package/src/runtime/agent-runtime-policy.ts

@@ -1,4 +1,10 @@
-import type { ExecutionMode, PlanArtifactSubmission, PlanNodeSpec } from '@lota-sdk/shared'
+import type {
+  ExecutionMode,
+  OwnershipDispatchContext,
+  PlanArtifactSubmission,
+  PlanNodeSpec,
+  PlanNodeSpecRecord,
+} from '@lota-sdk/shared'
 
 import { getLeadAgentId } from '../config/agent-defaults'
 import { resolveOnboardingOwnerAgentId } from '../config/workstream-defaults'
@@ -40,6 +46,27 @@ export const OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES = Object.freeze([
   'teamThink',
 ])
 
+export function buildCompletionCheckStructuredOutputHints(node: PlanNodeSpec | PlanNodeSpecRecord): string[] {
+  const hints: string[] = []
+
+  for (const check of node.completionChecks) {
+    if (check.type === 'llm-judge') {
+      const resultField = typeof check.config.resultField === 'string' ? check.config.resultField : 'passed'
+      hints.push(`Set structuredOutput.${resultField} = true only when this check is satisfied: ${check.description}`)
+      continue
+    }
+
+    if (check.type === 'human-approval') {
+      const approvedField = typeof check.config.approvedField === 'string' ? check.config.approvedField : 'approved'
+      hints.push(
+        `Set structuredOutput.${approvedField} = true only when this human approval check is satisfied: ${check.description}`,
+      )
+    }
+  }
+
+  return hints
+}
+
 function buildOwnershipDispatchArtifactPayload(artifacts: PlanArtifactSubmission[]) {
   return artifacts.map((artifact) => ({
     name: artifact.name,
@@ -206,6 +233,7 @@ export function buildOwnershipDispatchContextSection(params: {
   node: PlanNodeSpec
   resolvedInput: Record<string, unknown>
   inputArtifacts: PlanArtifactSubmission[]
+  upstreamHandoffs?: OwnershipDispatchContext['upstreamHandoffs']
 }): string {
   const payload = {
     node: {
@@ -223,14 +251,15 @@ export function buildOwnershipDispatchContextSection(params: {
     },
     resolvedInput: params.resolvedInput,
     inputArtifacts: buildOwnershipDispatchArtifactPayload(params.inputArtifacts),
+    upstreamHandoffs: params.upstreamHandoffs ?? [],
   }
 
   return [
     '<ownership-dispatch-execution>',
     'You are executing a single isolated execution-plan node.',
     'Do not ask the user questions. Do not reference any hidden or prior workstream chat history.',
-    'Use only the provided node context, resolved input, and input artifacts.',
-    'Return only the final structured node result that satisfies the required output contract.',
+    'Use only the provided node context, resolved input, input artifacts, and upstream handoff context.',
+    'Return only the final structured node result that satisfies the required output contract, including durable handoffContext for downstream nodes.',
     JSON.stringify(payload, null, 2),
     '</ownership-dispatch-execution>',
   ].join('\n')
@@ -241,15 +270,20 @@ export function buildOwnershipDispatchResponseGuard(params: {
   executionMode?: ExecutionMode
 }): string {
   const mode = params.executionMode ?? 'linear'
+  const completionCheckHints = buildCompletionCheckStructuredOutputHints(params.node)
 
   if (mode === 'linear') {
     return [
       '<ownership-dispatch-result-contract>',
       'Return a single JSON object with this exact shape:',
-      '{"structuredOutput"?: object, "artifacts": Array<{ "name": string, "kind": "json"|"markdown"|"file"|"external-ref"|"record", "pointer": string, "schemaRef"?: string, "description"?: string, "payload"?: object|array }>, "notes"?: string}',
+      '{"structuredOutput"?: object, "artifacts": Array<{ "name": string, "kind": "json"|"markdown"|"file"|"external-ref"|"record", "pointer": string, "schemaRef"?: string, "description"?: string, "payload"?: object|array }>, "notes"?: string, "handoffContext"?: { "summary": string, "keyDecisions"?: string[], "openQuestions"?: string[], "risks"?: string[], "recommendations"?: string[], "references"?: string[] }}',
       'Do not wrap the JSON in markdown or code fences.',
       `Node label: ${params.node.label}`,
       `Required deliverables: ${params.node.deliverables.length > 0 ? params.node.deliverables.map((item) => item.name).join(', ') : 'none'}`,
+      ...(completionCheckHints.length > 0
+        ? ['Structured output fields required by completion checks:', ...completionCheckHints]
+        : []),
+      'If downstream nodes depend on this work, include handoffContext.',
       '</ownership-dispatch-result-contract>',
     ].join('\n')
   }
@@ -263,6 +297,9 @@ export function buildOwnershipDispatchResponseGuard(params: {
         .map((d) => d.name)
         .join(', ') || 'none'
     }`,
+    ...(completionCheckHints.length > 0
+      ? ['Write these structuredOutput fields when the checks are satisfied:', ...completionCheckHints]
+      : []),
     'If writeIntent returns validation_failed, correct and re-call.',
     'After all writes, return a brief summary.',
     '</ownership-dispatch-result-contract>',

package/src/runtime/execution-plan-visibility.ts

@@ -0,0 +1,23 @@
+import type { PlanExecutionVisibility, PlanNodeSpecRecord, PlanSpecRecord } from '@lota-sdk/shared'
+
+import { agentRoster } from '../config/agent-defaults'
+
+export function resolvePlanNodeExecutionVisibility(
+  plan: Pick<PlanSpecRecord, 'defaultExecutionVisibility'>,
+  node: Pick<PlanNodeSpecRecord, 'executionVisibility' | 'owner'>,
+): PlanExecutionVisibility {
+  const configuredVisibility =
+    node.executionVisibility === 'auto' ? plan.defaultExecutionVisibility : node.executionVisibility
+  if (configuredVisibility === 'visible' || configuredVisibility === 'silent') {
+    return configuredVisibility
+  }
+
+  return node.owner.executorType === 'agent' && agentRoster.includes(node.owner.ref) ? 'visible' : 'silent'
+}
+
+export function shouldPlanNodeUseVisibleTurn(
+  plan: Pick<PlanSpecRecord, 'defaultExecutionVisibility'>,
+  node: Pick<PlanNodeSpecRecord, 'executionVisibility' | 'owner'>,
+): boolean {
+  return resolvePlanNodeExecutionVisibility(plan, node) === 'visible'
+}

package/src/runtime/execution-plan.ts

@@ -7,6 +7,7 @@ const EXECUTION_PLAN_AGENT_PROTOCOL_PROMPT = `<execution-plan-protocol>
 - The runtime executor owns lifecycle truth. Do not claim that a node is complete until submitExecutionNodeResult succeeds.
 - Use execution-plan tools to create, replace, inspect, and resume runs.
 - Visible workstream agents do not manually submit node results; dispatched execution nodes are completed by the runtime executor.
+- When the runtime starts a plan-triggered visible execution turn, use the dedicated result-submission tool for that turn and include durable handoffContext for downstream nodes.
 - Treat the active execution runs in <execution-plan-state> as authoritative. Do not mutate run or node status in prose.
 - Work only on nodes that are active or explicitly ready for your executor. If a node is awaiting human input or approval, stop and let the runtime resume it.
 - If the graph, contracts, or success criteria materially change, replace the plan instead of silently drifting.

package/src/runtime/runtime-extensions.ts

@@ -1,3 +1,10 @@
+import type {
+  PlanEventRecord,
+  PlanNodeRunRecord,
+  PlanNodeSpecRecord,
+  PlanRunRecord,
+  PlanSpecRecord,
+} from '@lota-sdk/shared'
 import type { ToolSet } from 'ai'
 
 import type { RecordIdRef } from '../db/record-id'
@@ -76,6 +83,24 @@ export interface LotaRuntimeTeamThinkToolsParams {
   toolProviders?: ToolSet
 }
 
+export interface LotaRuntimePlanEventEnvelope {
+  event: PlanEventRecord
+  spec: PlanSpecRecord
+  run: PlanRunRecord
+  nodeSpec?: PlanNodeSpecRecord
+  nodeRun?: PlanNodeRunRecord
+  organizationId: string
+  workstreamId: string
+  runId: string
+  planSpecId: string
+  userId?: string
+  userName?: string
+}
+
+export interface LotaRuntimePlanEventAdapter {
+  onPlanEvent(event: LotaRuntimePlanEventEnvelope): Promise<void>
+}
+
 export interface BuildContextParams {
   workstream: unknown
   workstreamRef: RecordIdRef
@@ -160,6 +185,7 @@ export interface LotaRuntimeTurnHooks {
 
 export interface LotaRuntimeAdapters {
   services?: { workspaceProvider?: LotaRuntimeWorkspaceProvider }
+  events?: { planEventAdapter?: LotaRuntimePlanEventAdapter }
   workstream?: {
     buildIndexedRepositoriesContext?: (workspaceId: string) => Promise<LotaRuntimeIndexedRepositoriesContext>
     buildTeamThinkAgentTools?: (params: LotaRuntimeTeamThinkToolsParams) => Promise<{ tools: ToolSet }>

package/src/runtime/runtime-worker-registry.ts

@@ -2,6 +2,7 @@ import { startAutonomousJobWorker } from '../queues/autonomous-job.queue'
 import { startContextCompactionWorker } from '../queues/context-compaction.queue'
 import { startDelayedNodePromotionWorker } from '../queues/delayed-node-promotion.queue'
 import { scheduleRecurringConsolidation, startMemoryConsolidationWorker } from '../queues/memory-consolidation.queue'
+import { schedulePlanAgentHeartbeatSweep, startPlanAgentHeartbeatWorker } from '../queues/plan-agent-heartbeat.queue'
 import { startPlanSchedulerWorker } from '../queues/plan-scheduler.queue'
 import { startPostChatMemoryWorker } from '../queues/post-chat-memory.queue'
 import { startRecentActivityTitleRefinementWorker } from '../queues/recent-activity-title-refinement.queue'
@@ -14,6 +15,7 @@ export interface LotaRuntimeWorkerStartRegistry {
   contextCompaction: typeof startContextCompactionWorker
   delayedNodePromotion: typeof startDelayedNodePromotionWorker
   memoryConsolidation: typeof startMemoryConsolidationWorker
+  planAgentHeartbeat: typeof startPlanAgentHeartbeatWorker
   planScheduler: typeof startPlanSchedulerWorker
   postChatMemory: typeof startPostChatMemoryWorker
   regularChatMemoryDigest: typeof startRegularChatMemoryDigestWorker
@@ -24,6 +26,7 @@ export interface LotaRuntimeWorkerStartRegistry {
 
 export interface LotaRuntimeWorkerScheduleRegistry {
   recurringConsolidation: typeof scheduleRecurringConsolidation
+  planAgentHeartbeatSweep: typeof schedulePlanAgentHeartbeatSweep
 }
 
 export interface LotaRuntimeWorkers {
@@ -43,6 +46,7 @@ export function buildRuntimeWorkerRegistry(extraWorkers?: LotaRuntimeWorkerExten
       contextCompaction: startContextCompactionWorker,
       delayedNodePromotion: startDelayedNodePromotionWorker,
       memoryConsolidation: startMemoryConsolidationWorker,
+      planAgentHeartbeat: startPlanAgentHeartbeatWorker,
       planScheduler: startPlanSchedulerWorker,
       postChatMemory: startPostChatMemoryWorker,
       regularChatMemoryDigest: startRegularChatMemoryDigestWorker,
@@ -51,6 +55,10 @@ export function buildRuntimeWorkerRegistry(extraWorkers?: LotaRuntimeWorkerExten
       recentActivityTitleRefinement: startRecentActivityTitleRefinementWorker,
       ...extraWorkers?.start,
     },
-    schedule: { recurringConsolidation: scheduleRecurringConsolidation, ...extraWorkers?.schedule },
+    schedule: {
+      recurringConsolidation: scheduleRecurringConsolidation,
+      planAgentHeartbeatSweep: schedulePlanAgentHeartbeatSweep,
+      ...extraWorkers?.schedule,
+    },
   }
 }

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

@@ -17,6 +17,7 @@ import { databaseService } from '../db/service'
 import { TABLES } from '../db/tables'
 import {
   OWNERSHIP_DISPATCH_BLOCKED_TOOL_NAMES,
+  buildCompletionCheckStructuredOutputHints,
   buildOwnershipDispatchContextSection,
   buildOwnershipDispatchResponseGuard,
 } from '../runtime/agent-runtime-policy'
@@ -50,6 +51,7 @@ export function buildWriteIntentDispatchPrompt(nodeSpec: PlanNodeSpec): string {
   const deliverables = nodeSpec.deliverables
     .map((d) => `- ${d.name} (${d.kind}${d.required ? ', required' : ''})`)
     .join('\n')
+  const completionCheckHints = buildCompletionCheckStructuredOutputHints(nodeSpec)
   return [
     `Execute the execution-plan node "${nodeSpec.label}".`,
     `Objective: ${nodeSpec.objective}`,
@@ -59,6 +61,9 @@ export function buildWriteIntentDispatchPrompt(nodeSpec: PlanNodeSpec): string {
     deliverables,
     '',
     'For each, call writeIntent with targetPath matching the deliverable name.',
+    ...(completionCheckHints.length > 0
+      ? ['Also write these structuredOutput fields when the checks are satisfied:', ...completionCheckHints, '']
+      : []),
     'If writeIntent returns validation_failed, correct the payload and try again.',
     'When all deliverables are written, end with a brief completion summary.',
   ].join('\n')
@@ -151,6 +156,7 @@ class AgentExecutorService {
           node: params.nodeSpec,
           resolvedInput: params.resolvedInput,
           inputArtifacts: params.inputArtifacts,
+          upstreamHandoffs: params.context.upstreamHandoffs,
         }),
       ],
       responseGuardSection: buildOwnershipDispatchResponseGuard({ node: params.nodeSpec, executionMode: mode }),