Hermes cron profile/workdir contract

목적

Hermes scheduled job을 “어느 agent identity(profile)가, 어느 filesystem/project context(workdir)에서, 어떤 delivery/archive contract로 실행하는지” 명시해 무인 실행의 재현성·idempotency·장애 진단성을 높인다.

언제 쓰나

• project repo의 AGENTS.md, package manager, relative path, CI artifact를 읽거나 수정하는 cron
• specialist profile의 memory/skills/env를 써야 하는 recurring job
• nightly learning, news/reporting, watchdog처럼 자동 delivery되는 job
• gateway/cron 장애 때 default profile과 named profile의 failure domain을 분리 진단해야 할 때

핵심 규칙

1. Profile을 암묵값으로 두지 말 것

   • default 작업도 필요하면 --profile default로 의도를 기록한다.
   • specialist 작업은 --profile <name> 또는 profile alias를 명시한다.
   • profile별 .env, config.yaml, auth.json, skills, cron list는 독립이다.

2. Repo context가 필요하면 absolute workdir을 둔다

   • --workdir /absolute/path/to/repo
   • workdir이 설정되면 project instruction files와 file/terminal tools의 기준이 해당 디렉터리가 된다.
   • 같은 workdir job은 scheduler tick에서 순차 실행되므로 repo 충돌 방지에 유리하다.

3. Repo context가 필요 없으면 workdir-less로 둔다

   • 외부 리서치, daily note 생성, 단순 상태 요약처럼 repo-local instruction이 필요 없는 job은 workdir을 생략한다.
   • workdir 없는 job은 parallel pool 실행 가능성이 있어 불필요한 지연을 줄인다.

4. Fresh session 전제

   • cron job은 매번 isolated fresh agent session으로 실행된다.
   • 이전 run의 기억에 의존하지 말고, 필요한 상태는 파일/DB/manifest/Obsidian note에서 읽게 한다.

5. Cron recursion 금지 전제

   • cron 실행 중 cron 관리 도구는 비활성화된다.
   • recurring job이 스스로 새 recurring job을 만드는 구조를 설계하지 않는다.

생성 전 체크리스트

• [ ] 이 job은 어떤 profile identity로 실행되어야 하는가?
• [ ] profile-local env/auth/config가 준비되어 있는가?
• [ ] project instruction/repo-relative path가 필요한가? 필요하면 workdir은 absolute path인가?
• [ ] 같은 repo를 쓰는 다른 cron과 충돌 가능성이 있는가?
• [ ] delivery target은 명시되어 있는가? 자동 final response delivery만 쓰는가, 별도 platform delivery인가?
• [ ] archive path와 filename convention이 prompt에 들어갔는가?
• [ ] no-news/no-change 시 [SILENT] 같은 silent contract가 필요한가?
• [ ] old duplicate job을 제거/비활성화할 계획이 있는가?

CLI 템플릿

Project-aware cron

hermes cron create "0 7 * * *" \
  "<fresh-session prompt with archive/delivery/source/failure contract>" \
  --profile <profile> \
  --workdir /absolute/path/to/project \
  --name "<project-purpose>"

hermes cron list
hermes cron run "<project-purpose>"

Report-only cron

hermes cron create "0 6 * * *" \
  "<fresh-session prompt; final response only; write durable report>" \
  --profile default \
  --name "<report-purpose>"

hermes cron list
hermes cron run "<report-purpose>"

Prompt contract snippet

You are running as a scheduled cron job.
DELIVERY: final response is automatically delivered; do not use send_message.
TIMEZONE: use Asia/Seoul date for filenames and report date.
ARCHIVE: write durable output to <absolute-path>/Daily/YYYY-MM-DD.md.
STATE: do not rely on memory from previous runs; read <manifest-or-index> if needed.
SOURCE: prefer official docs; mark unofficial/unverified content.
SECURITY: do not store secrets, tokens, or private credentials.
SILENT: if genuinely nothing changed, respond exactly [SILENT].
VERIFY: verify the written file and summarize paths changed.

검증 루틴

# 1. 전체 cron 확인
hermes cron list

# 2. profile별 상태 확인
hermes profile list
hermes -p <profile> status --all

# 3. 수동 1회 실행
hermes cron run "<job-name-or-id>"

# 4. archive와 delivery 분리 확인
# - archive file exists and contains today's date/frontmatter
# - outbound platform received the final response, if explicit delivery is configured
# - logs have no provider/auth error

장애 분류

• Profile 문제: default는 정상이나 named profile에서 API key/OAuth/skill/tool 설정이 없음.
• Workdir 문제: repo instruction 미로딩, relative path 실패, package manager 실행 위치 오류.
• Concurrency 문제: 같은 repo를 여러 workdir-less cron이 동시에 빌드/수정함.
• Fresh-session 문제: 이전 실행 맥락을 prompt가 가정해 누락/중복 보고 발생.
• Delivery 문제: agent run은 성공했지만 Telegram/Mattermost/channel delivery 실패.

관련 링크

• [[2026-06-10]]
• [[hermes-gateway-cron-systemd-guardrails]]
• Hermes Cron docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
• Hermes Profiles docs: https://hermes-agent.nousresearch.com/docs/user-guide/profiles
• Hermes Messaging Gateway docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/