Handoffs are the dispatch trigger; everything durable runs on a lease.
handoffs (:1628)from_agent/actor, to_role, to_agent/actor, priority ∈ {low, medium, high, urgent}, status ∈ {pending, claimed, returned, completed, released, abandoned, failed, archived}, kind ∈ {task, consult, completion_handback}, reply_to_handoff_id, completion_report (schema cortex.handoff_completion_report.v1), branch, summary, files_changed[], verification, next_steps, context, acceptance jsonb (contract), evidence jsonb, retry jsonb (policy + retry_count), escalation jsonb (policy), claimed_by(_actor_id), claimed_at, completed_at, terminal_reason, parent_goal_idtasks (:1772)status ∈ {todo, in_progress, review, done, blocked}, blocked_by, assigned_actor_idepics (:2210)epic_id, title, status, overall_pct (0–100 check), increments jsonbsprintsteam_events (:1796)pg_notify('cortex_events') drives SSE + dispatchagent_sessions (:1185), session_sources, execution_analyses, amad_loop_passes/sessions/ingest endpointclaimed_* columns + optimistic claim guardUPDATE handoffs SET status='claimed' … WHERE status='pending' (.agents/api/main.py:13891); expiry → watchdog auto-requeue; retry cap → CONSULT escalation. No SKIP LOCKED exists anywhere in KOS code (verified 2026-09-02; the SKIP LOCKED queue in older design docs never shipped, tasklist I28)handoffs rows with kind='completion_handback' + reply_to_handoff_id (.agents/api/main.py:13977 return_handoff, handback_recipient ≈:1338)POST /handoffs/{id}/return); addressed to the delegator (project default lead when the sender is not a visible actor); the parent stays returned until the handback is returned with decision=accept (parent → completed) or decision=rework (parent → pending, retry_count+1)apply_completion_evidence_floor (.agents/api/main.py, canonical 605de616; D3)completed with no tests_run, artifacts or work_product_id is stored as partial with metadata.evidence_floor; operator returns are untouched. Known holes under rework (v0.2.006 W1): applicability keyed on caller metadata, [{}] counts as evidence, same-recipient auto-acceptcortex.task_executions (:1105)agent_name, customer/project scopingharness_artifacts (:2268)status ∈ {current, stale, error}; project CASCADE FK| Action | Surface |
|---|---|
| Register agent | cortex-add-agent → POST /agents |
| Create / claim / complete handoff | cortex-handoff --create | --mine | --claim | --complete → POST /handoffs |
| Cross-project handoff | --target-project <p> --cto-override <decision-uuid> (validates both rosters; never cross-registers) |
| Return work (reviewable) | cortex-handoff --return <id> --agent <name> --summary <text> [--outcome completed|partial|blocked] [--decision accept|rework] → POST /handoffs/{id}/return; --complete is the compatibility alias routed through the same protocol |
| Update epic | POST /epics (admin-token-gated) |
| Ingest session | /sessions/ingest |
handoff INSERT → pg_notify('cortex_events') → orchestrator LISTEN wakes
→ orchestrator claims via the Cortex optimistic status guard (`UPDATE handoffs SET status='claimed' … WHERE status='pending'`, `.agents/api/main.py:13891`; no `SKIP LOCKED` exists anywhere in KOS code, verified 2026-09-02) → route by role/agent
→ spawn harness OR route to persistent agent → stream SSE
→ worker RETURNS (`POST /handoffs/{id}/return`, parent → `returned`, completion handback → delegator)
→ delegator returns the handback: accept (parent `completed`) | rework (parent `pending`) → notify → next cycleGovernance (built): lease auto-requeue (AV-3), retry cap → escalate, loop guards + DLQ, autonomous dispatch (AV-5), routed reasoning (AV-4). Governance (designed): rate caps, approval gates, budget STOP at proxy, kill switch.