fuli-context 0.7.6 → 0.7.7

package/graph-provider/fuli_graph/store_project_agent_tasks.py

@@ -1,25 +1,15 @@
 import json
 from collections import defaultdict
 from datetime import date
-
 from fastapi import HTTPException
-
 from .personal_project_access import authorize_personal_project
 from .project_agent_access import authorize_project_agent
-from .project_agent_executor_models import (
-    ProjectAgentExecutorActualReport,
-    ProjectAgentExecutorOutcomeEvidenceCreate,
-)
-from .project_agent_models import (
-    ProjectAgentModelStrategy,
-    ProjectAgentProfile,
-)
+from .project_agent_models import ProjectAgentModelStrategy, ProjectAgentProfile
 from .project_agent_task_models import (
     ProjectAgentActivityDay,
     ProjectAgentActivityResult,
     ProjectAgentActivityTask,
     ProjectAgentRoutingDecisionRecord,
-    ProjectAgentTaskActivityCreate,
     ProjectAgentTaskRecord,
     ProjectAgentTaskRouteResult,
     ProjectAgentTaskSubmit,
@@ -27,35 +17,32 @@ from .project_agent_task_models import (
 from .provider_values import native_datetime, now_utc, stable_uuid
 from .store_project_agents import SYSTEM_COORDINATOR_AGENT_ID
 from .store_project_agent_task_reads import StoreProjectAgentTaskReads
+from .store_project_agent_task_persistence import StoreProjectAgentTaskPersistence
 from .store_project_agent_task_recruitment import StoreProjectAgentTaskRecruitment
 from .store_project_agent_task_staffing import StoreProjectAgentTaskStaffing
-from .store_project_agent_coordination_policy import (
-    StoreProjectAgentCoordinationPolicy,
-)
-
-
-TERMINAL_TASK_STATUSES = {'completed', 'failed', 'cancelled'}
-
-
+from .store_project_agent_coordination_policy import StoreProjectAgentCoordinationPolicy
+from .store_project_agent_task_activity import StoreProjectAgentTaskActivity, TERMINAL_TASK_STATUSES
+from .store_transactions import TransactionQueryDriver, query_store_transaction
 class StoreProjectAgentTasks(
+    StoreProjectAgentTaskActivity,
     StoreProjectAgentCoordinationPolicy,
     StoreProjectAgentTaskRecruitment,
     StoreProjectAgentTaskReads,
-    # Keep the pre-existing base order ahead of the extracted implementation.
+    StoreProjectAgentTaskPersistence,
     StoreProjectAgentTaskStaffing,
 ):
     """Durable task, routing, recruitment, and verified activity control plane.
 
-    This is deliberately not a worker or scheduler. Registered clients submit
-    tasks and append truthful state events to the same persistent Agent/task
-    history. No task is shown as running until a client records that event.
+    Clients append real state events; this control plane does not run workers.
     """
-
     async def submit_project_agent_task(
         self,
         actor: dict,
         request: ProjectAgentTaskSubmit,
     ) -> ProjectAgentTaskRouteResult:
+        if not isinstance(self.runtime.driver, TransactionQueryDriver):
+            async with query_store_transaction(self) as scoped:
+                return await scoped.submit_project_agent_task(actor, request)
         self._require_personal()
         space = await self.authorize(actor, request.personal_space_id, 'maintainer')
         await authorize_personal_project(
@@ -79,11 +66,32 @@ class StoreProjectAgentTasks(
                     status_code=409,
                     detail='task idempotency key was used with different input',
                 )
+            await self._repair_task_persistence(request, raw)
+            existing = await self._find_task_row(
+                request.personal_space_id,
+                task_id,
+            )
             task = self._task_from_row(existing)
-            recruitment = await self._task_recruitment(
+            recruitments = await self._task_recruitments(
                 request.personal_space_id,
                 task.task_id,
             )
+            if await self._recover_recruitment_lifecycle(
+                actor,
+                request,
+                task,
+                recruitments,
+            ):
+                existing = await self._find_task_row(
+                    request.personal_space_id,
+                    task_id,
+                )
+                task = self._task_from_row(existing)
+                recruitments = await self._task_recruitments(
+                    request.personal_space_id,
+                    task.task_id,
+                )
+            recruitment = recruitments[0] if recruitments else None
             assigned_agent = await self._route_assigned_agent(
                 actor,
                 request,
@@ -93,13 +101,9 @@ class StoreProjectAgentTasks(
                 task,
                 recruitment,
                 assigned_agent=assigned_agent,
+                recruitments=recruitments,
             )
 
-        coordinator = await self.ensure_system_project_coordinator(
-            actor,
-            request.personal_space_id,
-        )
-        coordinator_agent_id = request.coordinator_agent_id or coordinator.agent_id
         if request.coordinator_agent_id:
             await authorize_project_agent(
                 self,
@@ -162,12 +166,53 @@ class StoreProjectAgentTasks(
                     'qualified durable Agent candidates'
                 )
 
+        parallel_recruitment_slots = (
+            await self._automatic_parallel_recruitment_slots(
+                actor,
+                request,
+                lead=lead,
+                participants=participants,
+                routing_reason=reason,
+            )
+        )
+        projected_participants = await self._parallel_plan_participant_projection(
+            actor,
+            request,
+            lead=lead,
+            participants=participants,
+            routing_reason=reason,
+            recruitment_slots=parallel_recruitment_slots,
+        )
+        self._verify_parallel_plan(request.parallel_plan, projected_participants)
+
+        will_open_recruitment = (
+            request.staffing_intent != 'unassigned'
+            and reason != 'manual_agent_selection'
+            and (
+                bool(parallel_recruitment_slots) or not lead
+                or request.staffing_intent in {'new_durable', 'temporary'}
+            )
+        )
+        if will_open_recruitment:
+            _, recruitment_profile = self._normalized_recruitment_profile(request)
+            self._require_agent_client_allowed(
+                recruitment_profile,
+                request.source_application,
+            )
+
+        coordinator = await self.ensure_system_project_coordinator(
+            actor,
+            request.personal_space_id,
+        )
+        coordinator_agent_id = request.coordinator_agent_id or coordinator.agent_id
+
         model_strategy, model_source = self._effective_model_strategy(
             request,
             lead,
             coordinator.profile.default_model_strategy,
         )
         recruitment = None
+        recruitments = []
         routing_outcome = 'assigned_existing' if lead else 'unassigned'
         task_status = 'queued' if lead else 'blocked'
         if request.staffing_intent == 'unassigned':
@@ -177,6 +222,72 @@ class StoreProjectAgentTasks(
         elif reason == 'manual_agent_selection':
             routing_outcome = 'unassigned'
             task_status = 'blocked'
+        elif parallel_recruitment_slots:
+            recruited_count = 0
+            recruited_lead = False
+            for slot in parallel_recruitment_slots:
+                slot_recruitment, recruited = await self._open_recruitment(
+                    actor,
+                    space,
+                    request,
+                    task_id,
+                    coordinator_agent_id,
+                    reason,
+                    participant_role=slot['participant_role'],
+                    recruitment_slot=slot['recruitment_slot'],
+                )
+                if slot_recruitment:
+                    recruitments.append(slot_recruitment)
+                    if slot['participant_role'] == 'lead':
+                        recruitment = slot_recruitment
+                if not recruited:
+                    continue
+
+                recruited_count += 1
+                participant = {
+                    'agent_id': recruited['agent_id'],
+                    'role': slot['participant_role'],
+                    'assignment_summary': recruited.get('responsibility'),
+                }
+                if not any(
+                    item['agent_id'] == recruited['agent_id']
+                    for item in participants
+                ):
+                    if slot['participant_role'] == 'lead':
+                        participants.insert(0, participant)
+                    else:
+                        participants.append(participant)
+                if slot['participant_role'] == 'lead':
+                    lead = recruited
+                    recruited_lead = True
+
+            if recruitment is None and recruitments:
+                recruitment = recruitments[0]
+            if recruited_count == len(parallel_recruitment_slots):
+                routing_outcome = 'recruited'
+                task_status = 'queued'
+                match_basis = [
+                    *match_basis,
+                    'parallel automatic recruitment: filled '
+                    f'{recruited_count} missing participant slot(s)',
+                    'HR recruitment recorded before Agent creation',
+                ]
+                if recruited_lead:
+                    model_strategy, model_source = self._effective_model_strategy(
+                        request,
+                        lead,
+                        coordinator.profile.default_model_strategy,
+                    )
+            elif any(
+                item.status == 'awaiting_confirmation'
+                for item in recruitments
+            ):
+                routing_outcome = 'recruitment_required'
+                task_status = 'awaiting_recruitment'
+            else:
+                routing_outcome = 'blocked'
+                task_status = 'blocked'
+                reason = 'hr_unavailable'
         elif not lead or request.staffing_intent in {'new_durable', 'temporary'}:
             recruitment, recruited = await self._open_recruitment(
                 actor,
@@ -186,6 +297,8 @@ class StoreProjectAgentTasks(
                 coordinator_agent_id,
                 reason,
             )
+            if recruitment:
+                recruitments.append(recruitment)
             if recruited:
                 lead = recruited
                 if not any(
@@ -290,6 +403,7 @@ class StoreProjectAgentTasks(
             participants=participants,
             decision=decision,
             recruitment=recruitment,
+            recruitments=recruitments,
             executor_decision=executor_decision,
             created_at=now,
         )
@@ -307,6 +421,7 @@ class StoreProjectAgentTasks(
             task,
             recruitment,
             assigned_agent=assigned_agent,
+            recruitments=recruitments,
         )
 
     async def get_project_agent_task(
@@ -314,19 +429,33 @@ class StoreProjectAgentTasks(
         actor: dict,
         personal_space_id: str,
         task_id: str,
+        *,
+        personal_project_id: str | None = None,
     ) -> ProjectAgentTaskRecord:
         self._require_personal()
         space = await self.authorize(actor, personal_space_id, 'reader')
-        row = await self._find_task_row(personal_space_id, task_id)
+        if personal_project_id:
+            await authorize_personal_project(
+                self,
+                actor,
+                space,
+                personal_project_id,
+            )
+        row = await self._find_task_row(
+            personal_space_id,
+            task_id,
+            personal_project_id,
+        )
         if not row:
             raise HTTPException(status_code=404, detail='project Agent task not found')
         task = dict(row['task'])
-        await authorize_personal_project(
-            self,
-            actor,
-            space,
-            task['personal_project_id'],
-        )
+        if not personal_project_id:
+            await authorize_personal_project(
+                self,
+                actor,
+                space,
+                task['personal_project_id'],
+            )
         return self._task_from_row(row)
 
     async def list_project_agent_tasks(
@@ -369,349 +498,6 @@ class StoreProjectAgentTasks(
         )
         return [self._task_from_row(row) for row in records]
 
-    async def record_project_agent_task_activity(
-        self,
-        actor: dict,
-        request: ProjectAgentTaskActivityCreate,
-    ) -> ProjectAgentTaskRecord:
-        self._require_personal()
-        space = await self.authorize(actor, request.personal_space_id, 'maintainer')
-        await authorize_personal_project(
-            self,
-            actor,
-            space,
-            request.personal_project_id,
-        )
-        row = await self._find_task_row(request.personal_space_id, request.task_id)
-        if not row:
-            raise HTTPException(status_code=404, detail='project Agent task not found')
-        raw_task = dict(row['task'])
-        if raw_task['personal_project_id'] != request.personal_project_id:
-            raise HTTPException(status_code=404, detail='project Agent task not found')
-        event_id = stable_uuid(
-            self.settings.provider_id,
-            request.personal_space_id,
-            'project-agent-task-event',
-            request.task_id,
-            request.idempotency_key,
-        )
-        payload_hash = self._payload_hash(request)
-        existing_event = next(
-            (
-                dict(value)
-                for value in (row.get('event_rows') or [])
-                if value
-                and (value.get('event_id') or value.get('id')) == event_id
-            ),
-            None,
-        )
-        if existing_event:
-            if existing_event.get('payload_hash') != payload_hash:
-                raise HTTPException(
-                    status_code=409,
-                    detail=(
-                        'task event idempotency key was used with different input'
-                    ),
-                )
-            return self._task_from_row(row)
-        self._validate_task_transition(
-            raw_task.get('status'),
-            request.status,
-            has_actual_executor=bool(request.actual_executor_id),
-        )
-        expected_revision = getattr(request, 'expected_revision', None)
-        if expected_revision is None:
-            expected_revision = raw_task.get('revision', 0)
-        if request.agent_id:
-            participant = next(
-                (
-                    item for item in self._participant_maps(row)
-                    if item['agent_id'] == request.agent_id
-                ),
-                None,
-            )
-            if not participant:
-                raise HTTPException(
-                    status_code=409,
-                    detail='Agent is not assigned to this task',
-                )
-            if participant.get('profile_json'):
-                self._require_agent_client_allowed(
-                    {
-                        'agent_id': request.agent_id,
-                        'profile': ProjectAgentProfile.model_validate_json(
-                            participant['profile_json']
-                        ),
-                    },
-                    request.source_application,
-                )
-        now = now_utc()
-        terminal_at = now if request.status in TERMINAL_TASK_STATUSES else None
-        actual_executor_id = getattr(request, 'actual_executor_id', None)
-        matched_executor_rule_id = getattr(request, 'matched_executor_rule_id', None)
-        executor_selection_reason = getattr(request, 'executor_selection_reason', None)
-        executor_fallback_reason = getattr(request, 'executor_fallback_reason', None)
-        executor_blocked_reason = getattr(request, 'executor_blocked_reason', None)
-        worker_id = getattr(request, 'worker_id', None)
-        worker_label = getattr(request, 'worker_label', None)
-        worker_occupation_emoji = getattr(
-            request,
-            'worker_occupation_emoji',
-            None,
-        )
-        worker_status = getattr(request, 'worker_status', None)
-        actual_recorder = None
-        actual_report = None
-        if actual_executor_id:
-            actual_recorder = getattr(
-                self,
-                'record_project_agent_executor_actual',
-                None,
-            )
-            if not callable(actual_recorder):
-                raise HTTPException(
-                    status_code=503,
-                    detail='executor evidence control plane is unavailable',
-                )
-            strategy = (
-                ProjectAgentModelStrategy.model_validate_json(
-                    raw_task['effective_model_strategy_json']
-                )
-                if raw_task.get('effective_model_strategy_json')
-                else ProjectAgentModelStrategy()
-            )
-            actual_report = ProjectAgentExecutorActualReport(
-                personal_space_id=request.personal_space_id,
-                personal_project_id=request.personal_project_id,
-                task_id=request.task_id,
-                run_id=event_id,
-                agent_id=request.agent_id,
-                executor_id=actual_executor_id,
-                provider=request.actual_model_provider,
-                model=request.actual_model,
-                model_strategy=strategy,
-                model_strategy_source=(
-                    raw_task.get('model_strategy_source') or 'coordinator'
-                ),
-                matched_rule_id=matched_executor_rule_id,
-                fallback_reason=executor_fallback_reason,
-                idempotency_key=f'actual:{event_id}',
-                occurred_at=now,
-                source_application=request.source_application,
-                source_session_id=request.source_session_id,
-            )
-        records, _, _ = await self.runtime.driver.execute_query(
-            '''
-            MATCH (space:FuliSpace {
-              id: $personal_space_id, kind: 'personal'
-            })-[:HAS_PROJECT_AGENT_TASK]->
-                  (task:FuliProjectAgentTask {
-                    personal_space_id: $personal_space_id,
-                    task_id: $task_id
-                  })
-            WHERE task.revision = $expected_revision
-               OR EXISTS {
-                 MATCH (task)-[:HAS_TASK_EVENT]->
-                       (:FuliProjectAgentTaskEvent {id: $event_id})
-               }
-            OPTIONAL MATCH (space)-[:HAS_PROJECT_AGENT_IDENTITY]->
-                  (agent:FuliProjectAgent {agent_id: $agent_id})
-            WHERE $agent_id IS NULL OR EXISTS {
-              MATCH (task)-[:HAS_PARTICIPANT]->(agent)
-            }
-            MERGE (event:FuliProjectAgentTaskEvent {id: $event_id})
-            ON CREATE SET event.event_id = $event_id,
-                          event.task_id = $task_id,
-                          event.agent_id = $agent_id,
-                          event.status = $status,
-                          event.actor_kind = $actor_kind,
-                          event.summary = $summary,
-                          event.payload_hash = $payload_hash,
-                          event.source_application = $source_application,
-                          event.source_session_id = $source_session_id,
-                          event.actual_model_provider = $actual_model_provider,
-                          event.actual_model = $actual_model,
-                          event.actual_executor_id = $actual_executor_id,
-                          event.matched_executor_rule_id =
-                            $matched_executor_rule_id,
-                          event.executor_selection_reason =
-                            $executor_selection_reason,
-                          event.executor_fallback_reason =
-                            $executor_fallback_reason,
-                          event.executor_blocked_reason =
-                            $executor_blocked_reason,
-                          event.worker_id = $worker_id,
-                          event.worker_label = $worker_label,
-                          event.worker_occupation_emoji = $worker_occupation_emoji,
-                          event.worker_status = $worker_status,
-                          event.activity_date = CASE
-                            WHEN $terminal_at IS NULL THEN null
-                            ELSE date($terminal_at) END,
-                          event.created_at = $updated_at
-            WITH task, event, agent,
-                 event.payload_hash = $payload_hash AS same_payload,
-                 task.revision = $expected_revision AS applied_transition
-            FOREACH (_ IN CASE
-              WHEN same_payload AND applied_transition
-              THEN [1] ELSE [] END |
-              MERGE (task)-[:HAS_TASK_EVENT]->(event)
-            )
-            FOREACH (_ IN CASE
-              WHEN same_payload AND applied_transition AND agent IS NOT NULL
-              THEN [1] ELSE [] END |
-              MERGE (event)-[:EVENT_AGENT]->(agent)
-            )
-            FOREACH (_ IN CASE
-              WHEN same_payload AND applied_transition
-              THEN [1] ELSE [] END |
-              SET task.status = $status,
-                  task.result_summary = CASE
-                    WHEN $status = 'completed' THEN $summary
-                    ELSE task.result_summary END,
-                  task.failure_reason = CASE
-                    WHEN $status = 'failed' THEN $summary
-                    ELSE task.failure_reason END,
-                  task.actual_executor_id = coalesce(
-                    $actual_executor_id, task.actual_executor_id),
-                  task.actual_model_provider = coalesce(
-                    $actual_model_provider, task.actual_model_provider),
-                  task.actual_model = coalesce($actual_model, task.actual_model),
-                  task.matched_executor_rule_id = coalesce(
-                    $matched_executor_rule_id,
-                    task.matched_executor_rule_id),
-                  task.executor_selection_reason = coalesce(
-                    $executor_selection_reason,
-                    task.executor_selection_reason),
-                  task.executor_fallback_reason = coalesce(
-                    $executor_fallback_reason,
-                    task.executor_fallback_reason),
-                  task.executor_blocked_reason = coalesce(
-                    $executor_blocked_reason,
-                    task.executor_blocked_reason),
-                  task.completed_at = $terminal_at,
-                  task.updated_at = $updated_at,
-                  task.revision = task.revision + 1
-            )
-            FOREACH (_ IN CASE
-              WHEN same_payload AND applied_transition AND agent IS NOT NULL
-              THEN [1] ELSE [] END |
-              SET task.lead_agent_id = CASE
-                WHEN task.lead_agent_id IS NULL AND $status = 'running'
-                THEN agent.agent_id ELSE task.lead_agent_id END
-            )
-            WITH task, event, same_payload, applied_transition
-            OPTIONAL MATCH (task)-[participant:HAS_PARTICIPANT]->
-                           (participant_agent:FuliProjectAgent)
-            FOREACH (_ IN CASE
-              WHEN same_payload
-                AND applied_transition
-                AND participant IS NOT NULL
-                AND NOT (coalesce(participant.status, '') IN
-                    ['completed', 'failed', 'cancelled'])
-                AND (
-                  $terminal_at IS NOT NULL
-                  OR $agent_id IS NULL
-                  OR participant_agent.agent_id = $agent_id
-                )
-              THEN [1] ELSE [] END |
-              SET participant.status = $status,
-                  participant.updated_at = $updated_at,
-                  participant.ended_at = $terminal_at
-            )
-            RETURN DISTINCT task, event, same_payload, applied_transition
-            ''',
-            personal_space_id=request.personal_space_id,
-            task_id=request.task_id,
-            expected_revision=expected_revision,
-            event_id=event_id,
-            agent_id=request.agent_id,
-            status=request.status,
-            actor_kind=request.actor_kind,
-            summary=request.summary,
-            payload_hash=payload_hash,
-            source_application=request.source_application,
-            source_session_id=request.source_session_id,
-            actual_model_provider=request.actual_model_provider,
-            actual_model=request.actual_model,
-            actual_executor_id=actual_executor_id,
-            matched_executor_rule_id=matched_executor_rule_id,
-            executor_selection_reason=executor_selection_reason,
-            executor_fallback_reason=executor_fallback_reason,
-            executor_blocked_reason=executor_blocked_reason,
-            worker_id=worker_id,
-            worker_label=worker_label,
-            worker_occupation_emoji=worker_occupation_emoji,
-            worker_status=worker_status,
-            terminal_at=terminal_at,
-            updated_at=now,
-        )
-        if not records:
-            raise HTTPException(
-                status_code=409,
-                detail='task revision is stale or participant is invalid',
-            )
-        if not records[0]['same_payload']:
-            raise HTTPException(
-                status_code=409,
-                detail='task event idempotency key was used with different input',
-            )
-        if not records[0].get('applied_transition'):
-            return await self.get_project_agent_task(
-                actor,
-                request.personal_space_id,
-                request.task_id,
-            )
-        if actual_report:
-            await actual_recorder(actor, actual_report)
-        evidence_status = (
-            request.status
-            if request.status in TERMINAL_TASK_STATUSES
-            else worker_status
-        )
-        if (
-            evidence_status in TERMINAL_TASK_STATUSES
-            and actual_executor_id
-            and request.agent_id
-        ):
-            evidence_recorder = getattr(
-                self,
-                'record_project_agent_executor_outcome_evidence',
-                None,
-            )
-            if callable(evidence_recorder):
-                strategy = (
-                    ProjectAgentModelStrategy.model_validate_json(
-                        raw_task['effective_model_strategy_json']
-                    )
-                    if raw_task.get('effective_model_strategy_json')
-                    else ProjectAgentModelStrategy()
-                )
-                await evidence_recorder(
-                    actor,
-                    ProjectAgentExecutorOutcomeEvidenceCreate(
-                        personal_space_id=request.personal_space_id,
-                        personal_project_id=request.personal_project_id,
-                        work_kind=raw_task['work_kind'],
-                        agent_id=request.agent_id,
-                        executor_id=actual_executor_id,
-                        task_id=request.task_id,
-                        run_id=event_id,
-                        model_strategy=strategy,
-                        evidence_kind='terminal_outcome',
-                        source='system_terminal',
-                        terminal_outcome=evidence_status,
-                        reference_ids=[event_id],
-                        idempotency_key=f'terminal:{event_id}',
-                        occurred_at=now,
-                    ),
-                )
-        await self._archive_finished_temporary_agent(request, raw_task, now)
-        return await self.get_project_agent_task(
-            actor,
-            request.personal_space_id,
-            request.task_id,
-        )
-
     async def get_project_agent_activity(
         self,
         actor: dict,
@@ -719,9 +505,18 @@ class StoreProjectAgentTasks(
         agent_id: str,
         from_date: date,
         to_date: date,
+        *,
+        personal_project_id: str | None = None,
     ) -> ProjectAgentActivityResult:
         self._require_personal()
-        await self.authorize(actor, personal_space_id, 'reader')
+        space = await self.authorize(actor, personal_space_id, 'reader')
+        if personal_project_id:
+            await authorize_personal_project(
+                self,
+                actor,
+                space,
+                personal_project_id,
+            )
         if from_date > to_date:
             raise HTTPException(status_code=422, detail='from date must not exceed to date')
         records, _, _ = await self.runtime.driver.execute_query(
@@ -733,12 +528,18 @@ class StoreProjectAgentTasks(
                   (task:FuliProjectAgentTask)-[:HAS_TASK_EVENT]->
                   (event:FuliProjectAgentTaskEvent)-[:EVENT_AGENT]->(agent)
             WHERE event.status IN ['completed', 'failed', 'cancelled']
+              AND ($personal_project_id IS NULL
+                   OR task.personal_project_id = $personal_project_id)
               AND event.activity_date >= date($from_date)
               AND event.activity_date <= date($to_date)
-            RETURN event, task.title AS title
+            WITH task, event, agent
+            OPTIONAL MATCH (task)-[:HAS_TASK_EVENT]->(evidence_event:FuliProjectAgentTaskEvent)-[:EVENT_AGENT]->(agent)
+            WHERE evidence_event.created_at <= event.created_at
+            RETURN event, task.title AS title, collect(evidence_event) AS evidence_events
             ORDER BY event.created_at DESC, event.event_id
             ''',
             personal_space_id=personal_space_id,
+            personal_project_id=personal_project_id,
             agent_id=agent_id,
             from_date=from_date.isoformat(),
             to_date=to_date.isoformat(),
@@ -746,7 +547,9 @@ class StoreProjectAgentTasks(
         )
         grouped = defaultdict(list)
         for row in records:
-            event = dict(row['event'])
+            event = self._event_with_latest_execution_evidence(
+                row['event'], row.get('evidence_events') or []
+            )
             occurred_at = native_datetime(event['created_at'])
             grouped[occurred_at.date()].append(ProjectAgentActivityTask(
                 task_id=event['task_id'],
@@ -784,7 +587,6 @@ class StoreProjectAgentTasks(
 
     async def _route_assigned_agent(self, actor, request, task):
         """Project the selected durable identity into the route response."""
-
         agent_id = getattr(task, 'lead_agent_id', None)
         getter = getattr(self, 'get_project_agent', None)
         if not agent_id or not callable(getter):
@@ -898,7 +700,7 @@ class StoreProjectAgentTasks(
             task_id=task_id,
             agent_id=selected['agent_id'],
             work_kind=request.work_kind,
-            required_capabilities=request.required_capabilities,
+            required_capabilities=request.executor_capability_hints,
             model_strategy=model_strategy,
             task_override=(
                 getattr(request, 'executor_policy_override', None)
@@ -919,9 +721,6 @@ class StoreProjectAgentTasks(
             return {}
         raw = decision.model_dump(mode='json') if hasattr(decision, 'model_dump') else dict(decision)
         aliases = {
-            # The routing decision audit field is JSON data.  Keep the
-            # provider-neutral snapshot instead of leaking a Pydantic model
-            # into the parent record (which fails validation in real routing).
             'executor_decision': raw,
             'selected_executor_id': raw.get('selected_executor_id') or raw.get('executor_id'),
             'matched_executor_rule_id': raw.get('matched_rule_id') or raw.get('rule_id'),
@@ -935,26 +734,15 @@ class StoreProjectAgentTasks(
             if key in ProjectAgentRoutingDecisionRecord.model_fields
         }
 
-    @staticmethod
-    def _activity_executor_fields(event):
-        return {
-            key: value
-            for key, value in {
-                'actual_executor_id': event.get('actual_executor_id'),
-                'matched_executor_rule_id': event.get('matched_executor_rule_id'),
-                'worker_id': event.get('worker_id'),
-                'worker_label': event.get('worker_label'),
-                'worker_occupation_emoji': event.get(
-                    'worker_occupation_emoji'
-                ),
-                'worker_status': event.get('worker_status'),
-            }.items()
-            if key in ProjectAgentActivityTask.model_fields
-        }
+    async def _persist_task(self, request, **values):
+        # The task must not become visible before all of its planned edges exist.
+        async with self.runtime.driver.transaction() as transaction:
+            await self._persist_task_transaction(request, transaction, **values)
 
-    async def _persist_task(
+    async def _persist_task_transaction(
         self,
         request,
+        transaction,
         *,
         task_id,
         payload_hash,
@@ -974,7 +762,24 @@ class StoreProjectAgentTasks(
         recruitment,
         executor_decision,
         created_at,
+        recruitments=None,
     ):
+        linked_recruitments = list(recruitments or [])
+        if recruitment and not any(
+            item.recruitment_id == recruitment.recruitment_id
+            for item in linked_recruitments
+        ):
+            linked_recruitments.insert(0, recruitment)
+        recruitment_links = [
+            {
+                'recruitment_id': item.recruitment_id,
+                'is_primary': bool(
+                    recruitment
+                    and item.recruitment_id == recruitment.recruitment_id
+                ),
+            }
+            for item in linked_recruitments
+        ]
         decision_raw = decision.model_dump(mode='json')
         executor_raw = (
             executor_decision.model_dump(mode='json')
@@ -988,15 +793,15 @@ class StoreProjectAgentTasks(
             task_id,
             'created',
         )
-        await self.runtime.driver.execute_query(
+        result = await transaction.run(
             '''
             MATCH (space:FuliSpace {id: $personal_space_id, kind: 'personal'})
             MATCH (space)-[:CONTAINS_PROJECT]->
                   (project:FuliPersonalProject {project_id: $personal_project_id})
             MATCH (space)-[:HAS_PROJECT_AGENT_IDENTITY]->
                   (coordinator:FuliProjectAgent {agent_id: $coordinator_agent_id})
-            CREATE (task:FuliProjectAgentTask {
-              id: $task_id,
+            MERGE (task:FuliProjectAgentTask {id: $task_id})
+            ON CREATE SET task += {
               task_id: $task_id,
               personal_space_id: $personal_space_id,
               personal_project_id: $personal_project_id,
@@ -1005,6 +810,7 @@ class StoreProjectAgentTasks(
               objective: $objective,
               work_kind: $work_kind,
               required_capabilities: $required_capabilities,
+              executor_capability_hints: $executor_capability_hints,
               duration: $duration,
               staffing_intent: $staffing_intent,
               status: $status,
@@ -1028,32 +834,39 @@ class StoreProjectAgentTasks(
               executor_decision_json: $executor_decision_json,
               executor_policy_json: $executor_policy_json,
               selected_executor_id: $selected_executor_id,
+              participant_plan_json: $participant_plan_json,
+              recruitment_plan_json: $recruitment_plan_json,
               created_at: $created_at,
               updated_at: $created_at
+            }
+            WITH space, project, coordinator, task
+            WHERE task.payload_hash = $payload_hash
+            MERGE (decision_node:FuliProjectAgentRoutingDecision {
+              id: $decision_id
             })
-            CREATE (decision_node:FuliProjectAgentRoutingDecision {
-              id: $decision_id,
-              decision_id: $decision_id,
-              task_id: $task_id,
-              decision_json: $decision_json,
-              created_at: $created_at
-            })
-            CREATE (event:FuliProjectAgentTaskEvent {
-              id: $initial_event_id,
-              event_id: $initial_event_id,
-              task_id: $task_id,
-              status: $status,
-              actor_kind: 'system',
-              summary: $routing_explanation,
-              source_application: $source_application,
-              source_session_id: $source_session_id,
-              created_at: $created_at
-            })
+            ON CREATE SET decision_node.decision_id = $decision_id,
+                          decision_node.task_id = $task_id,
+                          decision_node.decision_json = $decision_json,
+                          decision_node.created_at = $created_at
+            MERGE (event:FuliProjectAgentTaskEvent {id: $initial_event_id})
+            ON CREATE SET event.event_id = $initial_event_id,
+                          event.task_id = $task_id,
+                          event.status = $status,
+                          event.actor_kind = 'system',
+                          event.summary = $routing_explanation,
+                          event.source_application = $source_application,
+                          event.source_session_id = $source_session_id,
+                          event.created_at = $created_at
             MERGE (space)-[:HAS_PROJECT_AGENT_TASK]->(task)
             MERGE (project)-[:HAS_PROJECT_AGENT_TASK]->(task)
             MERGE (task)-[:COORDINATED_BY]->(coordinator)
             MERGE (task)-[:ROUTED_BY]->(decision_node)
             MERGE (task)-[:HAS_TASK_EVENT]->(event)
+            RETURN true AS payload_matches,
+                   task.participant_plan_json AS participant_plan_json,
+                   task.recruitment_plan_json AS recruitment_plan_json,
+                   task.status AS persisted_status,
+                   task.created_at AS persisted_created_at
             ''',
             task_id=task_id,
             personal_space_id=request.personal_space_id,
@@ -1063,6 +876,7 @@ class StoreProjectAgentTasks(
             objective=request.objective,
             work_kind=request.work_kind,
             required_capabilities=request.required_capabilities,
+            executor_capability_hints=request.executor_capability_hints,
             duration=request.duration,
             staffing_intent=request.staffing_intent,
             status=status,
@@ -1101,51 +915,30 @@ class StoreProjectAgentTasks(
                 (executor_raw or {}).get('selected_executor_id')
                 or (executor_raw or {}).get('executor_id')
             ),
+            participant_plan_json=json.dumps(participants, sort_keys=True),
+            recruitment_plan_json=json.dumps(recruitment_links, sort_keys=True),
             created_at=created_at,
             decision_id=decision.decision_id,
             decision_json=json.dumps(decision_raw, sort_keys=True),
             initial_event_id=initial_event_id,
         )
-        for participant in participants:
-            await self.runtime.driver.execute_query(
-                '''
-                MATCH (space:FuliSpace {
-                  id: $personal_space_id, kind: 'personal'
-                })-[:HAS_PROJECT_AGENT_TASK]->
-                      (task:FuliProjectAgentTask {task_id: $task_id})
-                MATCH (space)-[:HAS_PROJECT_AGENT_IDENTITY]->
-                      (agent:FuliProjectAgent {agent_id: $agent_id})
-                MERGE (task)-[participant:HAS_PARTICIPANT]->(agent)
-                SET participant.role = $role,
-                    participant.status = $status,
-                    participant.assignment_summary = $assignment_summary,
-                    participant.joined_at = $created_at,
-                    participant.updated_at = $created_at
-                ''',
-                personal_space_id=request.personal_space_id,
-                task_id=task_id,
-                agent_id=participant['agent_id'],
-                role=participant['role'],
-                status=status,
-                assignment_summary=participant.get('assignment_summary'),
-                created_at=created_at,
-            )
-        if recruitment:
-            await self.runtime.driver.execute_query(
-                '''
-                MATCH (space:FuliSpace {
-                  id: $personal_space_id, kind: 'personal'
-                })-[:HAS_PROJECT_AGENT_TASK]->
-                      (task:FuliProjectAgentTask {task_id: $task_id})
-                MATCH (space)-[:HAS_PROJECT_AGENT_RECRUITMENT]->
-                      (recruitment:FuliProjectAgentRecruitment {
-                        recruitment_id: $recruitment_id
-                      })
-                SET task.recruitment_id = $recruitment_id,
-                    task.hr_agent_id = recruitment.hr_agent_id
-                MERGE (task)-[:TRIGGERED_RECRUITMENT]->(recruitment)
-                ''',
-                personal_space_id=request.personal_space_id,
-                task_id=task_id,
-                recruitment_id=recruitment.recruitment_id,
+        records = [record async for record in result]
+        if not records or not dict(records[0]).get('payload_matches'):
+            raise HTTPException(
+                status_code=409,
+                detail='task idempotency key was used with different input',
             )
+        persisted = dict(records[0])
+        await self._persist_task_links(
+            request,
+            transaction=transaction,
+            task_id=task_id,
+            participants=self._task_link_plan(
+                persisted.get('participant_plan_json')
+            ),
+            recruitment_links=self._task_link_plan(
+                persisted.get('recruitment_plan_json')
+            ),
+            status=persisted.get('persisted_status') or status,
+            created_at=persisted.get('persisted_created_at') or created_at,
+        )