b3os-scheduler

b3os-scheduler — b3os durable 스케줄러

팀원이 세션과 무관하게(durable) 시각에 맞춰 발화하는 반복/예약 잡을 등록하는 절차 스킬이다. 런타임별 세션 cron(claude CronCreate, openclaw/hermes 자체 예약)은 그 세션이 죽으면 유실된다. 팀 정본 반복작업(야간 사이클·주기 리마인드·정기 점검)은 이 스케줄러에 등록해 team.db에 durable 저장하고, b3os 서버 안의 워커가 발화한다.

언제 쓰나

• "매일 03:04에 X 해라", "평일 09시에 Y 깨워라", "매월 1일 리포트" 같은 반복 잡을 durable하게 걸 때
• "N분 뒤 나한테 알려줘" 같은 1회성 리마인드를 턴에서 sleep 없이 예약할 때 (dex/에이전트 in-turn sleep 금지)
• 세션 죽어도 살아남아야 하는 팀 정본 스케줄을 등록/이관할 때
• launchd per-job 플리스트를 durable 스케줄러 잡으로 이관할 때

세션 한정 임시 점검(몇 분 뒤 한 번 확인)은 런타임 세션 cron으로도 충분하다 — 이 스킬은 유실되면 안 되는 잡에 쓴다.

b3os-task-loop(작업루프)과 구분: workloop = 정해진 코디네이터 루프(매일 칸반 PM·주간 self-learning 등 고정 프로그램)를 깨우는 기본 인프라. scheduler(이 스킬) = 임의의 durable 반복·예약 잡을 자유롭게 등록하는 범용 도구. workloop의 스케줄 자체도 이 스케줄러로 이관 가능(launchd per-job → scheduled_job).

개념 (실제 구현)

• 정본 저장: team.db의 scheduled_job 테이블 (id·kind·schedule_kind·next_run_at(UTC)·schedule_expr·payload_json·enabled·lock_until…). 실행 이력=scheduled_job_run.
• 워커: b3os 서버가 startSchedulerWorker로 틱마다(기본 60초, env B3OS_SCHEDULER_INTERVAL_MS로 조정·최소 5초) next_run_at<=now인 잡을 lease-claim → 발화 → 재계산. 코드=src/server/scheduler/core.ts(runDueSchedulerJobsOnce)·workers/schedulerWorker.ts.
• 발화 = 2종 페이로드: ①inbox — payload_json의 인박스 봉투를 acceptInbound로 삽입(실제 wake/라우팅은 wakeDispatcher, 신규 라우팅 0). ②exec — allowlist된 ops 스크립트를 spawn(에이전트 안 깨우고 결정적 작업 직접 수행, 옛 launchd 대체). inbox는 emit+재계산이 단일 트랜잭션(at-most-once), exec는 async라 실행 후 재계산(at-least-once).
• 잡 종류(kind × schedule_kind): recurring×cron(시·분·요일·월) / recurring×interval(N분 간격) / oneshot×once(1회 리마인드).
• 안전: claim은 원자적 조건부 UPDATE(lease)로 이중발화 차단. dedupe_key=job_id+scheduled_for + acceptInbound 창으로 크래시 재발화 시에도 이중게시 0. 한 잡 throw가 워커 안 죽임(격리) — 잘못된 cron 잡은 failed로 파킹돼 재발화 루프 없음.

cron 문법 (표준 5필드, KST)

분 시 일(月) 월 요일 — 예 4 3 * * * = 매일 03:04.

• 필드: * / a / a,b,c / a-b / */n / a-b/n / N/n(N..최대 step n, Vixie)
• 요일: 0-7 (0·7=일요일)
• 일(dom)·요일(dow) 둘 다 지정 시 = 둘 중 하나 맞으면 발화(Vixie 시맨틱)
• 타임존 = 잡의 timezone(기본 Asia/Seoul). 고정 오프셋 존만 지원 — DST 존(America/New_York 등)은 등록 시 throw(오발화 방지). KST는 DST 없어 정확.