worker

name	worker
description	Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based Omagy teams.

Worker

This skill is for an Antigravity CLI session started as an Omagy Team worker inside a tmux pane. It is not a user-facing planning or review workflow.

Identity

You MUST be running with OMAGY_TEAM_WORKER set:

<team-name>/worker-<n>

Example:

alpha/worker-2

Parse it into team_name and worker before any task work.

Source Of Truth

Use omagy team api ... --json for all team state reads and writes. Do not directly edit .omagy/state/team/** JSON files.

Use these environment variables when present:

• OMAGY_TEAM_WORKER: canonical <team>/<worker> identity.
• OMAGY_TEAM_STATE_ROOT: canonical state root for this worker.
• OMAGY_TEAM_LEADER_CWD: leader workspace path.

If environment variables are missing, stop and report the missing value. Do not guess a sibling team.

Startup ACK

Before task work, send one deterministic ACK to the leader mailbox:

omagy team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"ACK: <workerName> initialized"}' --json

Then read your mailbox and inbox:

omagy team api mailbox-list --input '{"team_name":"<teamName>","worker":"<workerName>"}' --json

Your inbox is informational; the task lifecycle still goes through the API.

Task Lifecycle

1. List tasks:

omagy team api list-tasks --input '{"team_name":"<teamName>"}' --json

2. Pick the first unblocked task assigned to your worker or matching your role.
3. Claim it before doing work:

omagy team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --json

4. Do the work.
5. Transition with the returned claim token:

omagy team api transition-task-status --input '{"team_name":"<teamName>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>","result":"PASS: <evidence>"}' --json

Use to:"failed" with an error field when the task cannot be completed.

Use release-task-claim only for rollback or requeue, not for successful completion.

Mailbox

Mailbox messages are durable state. A tmux nudge is only a wake-up signal.

After reading a mailbox message, mark it delivered:

omagy team api mailbox-mark-delivered --input '{"team_name":"<teamName>","worker":"<workerName>","message_id":"<messageId>"}' --json

Reply to the leader with short status messages when useful:

omagy team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"DONE: <summary>"}' --json

Heartbeat

Record heartbeat evidence during long work:

omagy team api update-worker-heartbeat --input '{"team_name":"<teamName>","worker":"<workerName>","turn_count":1,"alive":true}' --json

Shutdown

If the leader sends a shutdown request, finish any safe cleanup, acknowledge via the API, then exit the worker session:

omagy team api write-shutdown-ack --input '{"team_name":"<teamName>","worker":"<workerName>","reason":"worker drained"}' --json