실행, 승인, 체크포인트

워크플로우를 작성하고 저장하면, 이후 모든 실행은 런(run) 이 됩니다. 런은 고유한 상태, 단계별 결과, 디스크 체크포인트를 가진 추적 가능한 인스턴스입니다. 이 페이지에서는 런 생명주기와 상태, 인간 승인 또는 자유 형식 입력을 위해 런을 일시 정지하는 방법, 실패한 런을 재시도하는 방법, 체크포인트가 상태를 유지하는 방식, 그리고 Cloud Run과 같은 임시(ephemeral) 호스트에서 발생하는 오래된 실행(stale run) 문제를 다룹니다.

이 페이지는 대시보드에서 런을 모니터링하고, 승인 게이트를 처리하고, 실패를 재시도하는 등 워크플로우를 일상적으로 운영할 때 참고하세요. 아직 워크플로우를 실행해 본 적이 없다면 첫 번째 워크플로우부터 시작하세요. 정의 CRUD 및 런 엔드포인트 전체 내용은 Workflows & Architect API를 참조하세요.

런 생명주기 & 상태

런은 워크플로우를 시작할 때 생성됩니다(대시보드의 Execute 버튼, POST /api/workflows/run/{name}, 크론 트리거, 또는 엔티티 이벤트 트리거). 오퍼레이터는 단계 DAG를 실행하고, 게이트웨이는 로컬 체크포인트 데이터를 Kumiho 런 레코드 위에 오버레이하여 상태를 보고합니다. 이를 통해 지속성 플러시 사이에도 진행 상태가 최신으로 유지됩니다.

상태	의미
pending	생성되었지만 아직 실행기가 처리하지 않은 상태.
running	실행기가 활성 상태.
paused	human_approval 또는 human_input 게이트에서 대기 중.
completed	모든 단계가 성공적으로 완료됨.
failed	단계가 실패함; 재시도할 수 있도록 체크포인트가 보존됨.
cancelled	사용자 또는 시스템에 의해 중지됨.
stale	체크포인트도 없고 활성 잠금도 없는 비종단(non-terminal) 상태 — 오래된 실행을 참조하세요.

참고

stale은 실행기가 기록하는 상태가 아닙니다. 게이트웨이가 활성 상태여야 할(pending/running/paused) 런에 체크포인트 파일도 없고 활성 잠금도 없을 때 이를 파생시킵니다. 일반적으로 호스트가 아직 기록된 런이 있는 상태에서 로컬 디스크를 초기화했을 때 발생합니다.

런 검사

런 id로 단일 런을 조회합니다. 모든 워크플로우 경로에는 페어링 bearer 토큰이 필요합니다(페어링 & 인증 참조).

GET /api/workflows/runs/{run_id}
Authorization: Bearer <token>

응답은 단계별 상세 정보가 포함된 { "run": { ... } } 형식입니다. 활성 런은 실행기의 인메모리 상태에서 읽고, 완료된 런은 Kumiho 런 레코드에서 조회합니다. 알 수 없는 run_id는 404를 반환합니다.

최근 런 목록을 조회하려면:

GET /api/workflows/runs?limit=20&workflow=hello-world
Authorization: Bearer <token>

쿼리 파라미터	기본값	의미
limit	20	반환할 런 수.
workflow	—	워크플로우 이름으로 필터링.

취소 및 삭제

런을 중지하면 실행기에 신호가 전달되고, 실행기는 다음 단계 경계에서 멈추며 가능한 경우 소유한 셸/파이썬 서브프로세스를 종료합니다. 런을 삭제하면 Kumiho 런 레코드와 로컬 체크포인트 및 아티팩트 파일이 최선의 방법으로 제거됩니다. 워크플로우 정의는 삭제되거나 폐기되지 않습니다(정의는 별도의 /api/workflows/{kref} 경로를 사용합니다).

메서드	경로	효과
POST	/api/workflows/runs/{run_id}/cancel	다음 경계에서 활성 런을 중지.
DELETE	/api/workflows/runs/{run_id}	런 레코드와 로컬 파일을 삭제.

전체 런 엔드포인트(목록, 트리거, 승인, 재시도, 취소, 삭제, 대시보드 통계, 에이전트 활동)는 Workflows & Architect API에서 확인할 수 있습니다.

체크포인트

checkpoint: true(워크플로우 수준 기본값)를 설정하면, 실행기는 각 단계가 완료된 후 및 인간 승인을 위해 일시 정지될 때 런 상태를 디스크에 저장합니다. 재시도와 승인 후 재개를 가능하게 하는 것이 바로 이 기능입니다.

name: deploy-pipeline
version: "1.0"
checkpoint: true          # workflow-level default is true
steps:
  - id: build
    type: shell
    shell:
      command: "npm run build"

아티팩트	경로	목적
체크포인트 파일	~/.revka/workflow_checkpoints/{run_id}.json	완료된 단계와 해당 출력의 스냅샷.
잠금 파일	~/.revka/workflow_locks/{run_id[:12]}.lock	런이 실행 중인 동안 보유하는 권고 잠금.

게이트웨이는 두 파일을 모두 읽어 런의 활성 상태를 결정합니다. 활성 잠금은 실행기가 살아있음을 의미하고, 체크포인트는 단계별 진행 상황을 제공합니다.

주의

오퍼레이터 재시작 시 중단된 런이 자동으로 재개되지 않습니다. 오퍼레이터가 런 도중 재시작되면, 고아 상태가 된 진행 중 런은 failed로 표시됩니다. Retry를 사용하여 다시 시작하면 체크포인트부터 재개됩니다. Revka는 자동으로 재개하지 않고 명시적인 사람의 조작을 요구합니다.

재시도

단계별 재시도는 런 진행 중에 발생하는 일시적 오류를 처리합니다. retry(첫 번째 시도 후 추가 시도 횟수)와 선택적 retry_delay(시도 간 대기 시간, 초)를 설정합니다:

- id: flaky_step
  type: agent
  agent:
    role: researcher
    prompt: "Fetch and summarize the latest report."
  retry: 2                # retry up to 2 times after the first attempt
  retry_delay: 10         # wait 10 seconds between retries

필드	타입	기본값	의미
retry	int	0	첫 번째 실패 후 추가 시도 횟수.
retry_delay	int (초)	0	재시도 사이의 대기 시간.

참고

재시도는 단계 실패 시에만 작동합니다. 완료 오류 및 검증 오류는 재시도되지 않습니다. 이러한 오류는 단계가 불안정한 것이 아니라 워크플로우 정의나 출력 계약에 문제가 있음을 의미합니다.

전체 런 재시도

런이 failed 상태에 도달하면, 보존된 체크포인트를 통해 첫 번째 실패한 단계부터 재시도할 수 있습니다. 성공한 단계의 출력은 재사용되므로, 실패한 단계와 그 하위 단계만 다시 실행됩니다.

Dashboard

Workflow Runs 페이지에서 실패한 런을 선택하고 Retry를 클릭합니다. 재시도는 체크포인트부터 실행을 다시 시작합니다.

API

POST /api/workflows/runs/{run_id}/retry
Authorization: Bearer <token>
Content-Type: application/json

{ "cwd": "/path/to/project" }

필드	필수	의미
cwd	아니오	재시도 시 셸 및 에이전트 단계의 작업 디렉터리.

게이트웨이는 오퍼레이터에 요청을 전달하고, 대시보드 클라이언트에 workflow_retry SSE 이벤트를 브로드캐스트합니다.

인간 승인

human_approval 단계는 런을 일시 정지하고 예/아니오 결정을 기다립니다. 런이 일시 정지되기 전에 체크포인트가 기록되므로, 몇 시간 후에 도착한 승인도 깔끔하게 재개됩니다.

- id: approve
  type: human_approval
  human_approval:
    message: "Deploy to production?"
    timeout: 3600          # seconds — here, 1 hour

필드	타입	의미
message	string	승인자에게 표시되는 프롬프트.
timeout	int (초)	게이트가 타임아웃되기까지 대기 시간.

일시 정지된 동안 런은 paused 상태를 유지합니다. API를 통해 결정을 제출합니다:

POST /api/workflows/runs/{run_id}/approve
Authorization: Bearer <token>
Content-Type: application/json

{ "approved": true, "feedback": "LGTM — ship it." }

필드	필수	의미
approved	예	true면 승인하고 계속, false면 거부.
feedback	아니오	런에 전달되는 자유 형식 메모.

결정이 내려지면 게이트웨이는 대시보드 클라이언트에 human_approval_resolved SSE 이벤트(run_id와 approved 포함)를 브로드캐스트합니다.

인간 입력

human_input 단계는 예/아니오 대신 자유 형식 텍스트를 기다리며 일시 정지합니다. 제출된 텍스트는 하위 단계에서 ${step_id.output}으로 사용할 수 있습니다.

- id: ask_user
  type: human_input
  human_input:
    message: "What changes do you want?"
    channel: dashboard
    timeout: 3600

필드	타입	의미
message	string	오퍼레이터에게 표시되는 프롬프트.
channel	string	질문할 채널(예: dashboard).
timeout	int (초)	응답 대기 시간.

이후 단계에서는 예를 들어 prompt: "Apply these changes: ${ask_user.output}"와 같이 답변을 직접 사용할 수 있습니다. 전체 네임스페이스 목록은 변수, 표현식 & 트리거를 참조하세요.

승인 레지스트리 (워크플로우 인간 승인)

승인 게이트는 대시보드에만 국한되지 않습니다. 채팅 채널에서도 처리할 수 있습니다. 게이트웨이는 워크플로우 human_approval 단계를 Discord, Slack, Telegram 답글과 연결하는 프로세스 전역 승인 레지스트리를 유지합니다.

런이 승인 단계에 도달하면, 이 레지스트리에 대기 중인 승인을 등록합니다. 채널 어댑터가 승인 프롬프트를 게시한 후에는 채널의 스레드 및 메시지 ID를 첨부하여 레지스트리가 정확하게 매칭할 수 있도록 합니다. 사용자가 답글을 달면 레지스트리는 메시지를 매칭하고 원자적으로 승인을 클레임(try_claim)합니다. 이 과정에서 항목이 제거되어 이중 결정을 방지합니다. 예를 들어 Discord 답글과 대시보드 클릭이 동시에 도착하는 경쟁 상황을 방지하는 것이 바로 이 메커니즘입니다.

매칭	규칙
승인	메시지가 승인 키워드 중 하나로 시작(대소문자 구분 없음).
거부	메시지가 거부 키워드로 시작; 키워드 이후 텍스트가 feedback이 됨.

주의

병렬 승인에는 스레드 스코핑이 필요합니다. 채널 어댑터가 스레드/메시지 ID를 첨부할 수 없으면 매칭이 채널 단위로만 이루어집니다. 이 경우 여러 승인이 열려 있을 때 답글이 해당 채널의 첫 번째 대기 중인 승인을 결정하여 모호해집니다. 레지스트리는 또한 인메모리 전용입니다. 데몬이 재시작되면 대기 중인 승인이 모두 지워지므로, 진행 중인 게이트는 다시 제출해야 합니다.

기본 실시간 인터페이스와 SSE 이벤트가 대시보드에 전달되는 방식은 실시간: WebSocket, SSE & Live Canvas를 참조하세요. 워크플로우 하위에 위치한 별도의 게이트인 도구 호출 수준 승인은 정책, 명령어 & 샌드박싱과 자율성 수준 & 승인에서 다룹니다.

대시보드 — 시각적 DAG & 런 뷰어

대시보드는 워크플로우 정의와 워크플로우 런을 분리하여 표시합니다. 런 화면(/runs)은 런 범위의 제어만 제공합니다. 활성 런 중지, 실패한 런 재시도, 런 레코드 삭제, 그리고 라이브 그래프 뷰를 제공합니다.

런 뷰어는 워크플로우를 인터랙티브 DAG로 렌더링하고, 각 런을 실행된 정확한 YAML 리비전에 고정합니다(workflow_revision_kref를 확인하여). 이는 정의를 나중에 수정해도 이미 완료된 런의 그래프가 변경되지 않음을 의미합니다. 보이는 것이 실제로 실행된 것입니다.

• 완료된 조건부 노드는 그래프와 단계 인스펙터 모두에서 매칭된 브랜치, goto 대상, 브랜치 값, 출력된 결과를 표시합니다.
• 실패한 노드는 실행기 오류, 구조화된 output_data, stderr 미리보기, 또는 캡처된 입력 등 가능한 최선의 실패 상세 정보를 표시합니다.
• 단계 인스펙터(노드 클릭)는 상태, 에이전트 id와 역할, 출력 미리보기, 주입된 스킬, 그리고 그룹 채팅 트랜스크립트를 표시합니다.
• **“Run to here”**는 target_step_id를 사용하여 대상 단계의 전이적 선조 집합과 단계 자체만 실행한 후 중지합니다. 특정 브랜치를 반복 작업할 때 유용합니다.

참고

라이브 실행 업데이트는 Node.js 세션 매니저 사이드카가 에이전트 SDK 이벤트를 게이트웨이 WebSocket으로 전달하는 것에 의존합니다. 사이드카 없이도 런은 실행되지만 대시보드 DAG는 라이브 이벤트를 수신하지 못합니다. Python MCP 사이드카 설치를 참조하세요.

대시보드는 GET /api/workflows/dashboard를 통해 집계된 통계(정의 수, 활성 런, 최근 런)를 제공하고, GET /api/workflows/agent-activity/{agent_id}를 통해 에이전트별 드릴다운을 제공합니다. 이는 ~/.revka/operator_mcp/runlogs/{agent_id}.jsonl의 JSONL 런 로그를 기반으로 합니다. 전체 대시보드 안내는 워크플로우, 에디터 & 런을 참조하세요.

오래된 실행 & Cloud Run 문제

체크포인트와 잠금 파일은 오퍼레이터를 실행하는 호스트의 로컬 파일시스템에 저장됩니다. 영구 호스트에서는 이 파일들이 요청 사이에도 유지되므로 문제가 없습니다. 하지만 배포 또는 스케일-투-제로 사이클 사이에 디스크를 초기화하는 임시 호스트(Cloud Run 및 유사한 서버리스 PaaS)에서는 Kumiho 런 레코드가 여전히 running 또는 paused 상태를 표시하는 동안 해당 파일들이 사라집니다.

게이트웨이가 이러한 런을 로드할 때 체크포인트도 없고 활성 잠금도 없으면, 해당 런이 활성 상태라고 정직하게 보고할 수 없으므로 stale로 표시합니다. 오래된 실행은 사실상 고아 상태입니다. 해당 런을 보유하는 실행기도 없고, 재개할 디스크 상태도 없습니다.

주의

Cloud Run과 유사한 배포 시마다 재배포되는 플랫폼에서는 배포 후 이전에 running 상태이던 런이 stale로 나타날 수 있습니다. 초기화된 체크포인트는 재개할 수 없으므로, Retry로 복구하려 하지 말고 새로운 런을 시작하세요. 이 문제를 완전히 피하려면 ~/.revka/workflow_checkpoints/ 및 ~/.revka/workflow_locks/에 대해 영구 로컬 스토리지가 있는 호스트에서 오퍼레이터를 실행하세요.

상태를 영구적으로 유지하는 배포 가이드는 Docker, Compose & one-click PaaS와 런타임 모드, 어댑터 & 리소스 제한을 참조하세요.

다음으로

Workflows & Architect API 전체 런 엔드포인트: 트리거, 승인, 재시도, 취소, 삭제, 통계.

단계 유형 참조 human_approval, human_input 및 모든 단계 유형의 상세 내용.

변수, 표현식 & 트리거 human_input 출력 사용 및 단계 결과 참조 방법.

워크플로우, 에디터 & 런 대시보드 DAG 에디터와 런 뷰어 심층 안내.

실시간: WebSocket, SSE & Live Canvas 라이브 런 업데이트를 구동하는 SSE 이벤트 스트림.

Docker, Compose & one-click PaaS 임시 호스트에서 체크포인트 상태를 영구적으로 유지하는 방법.