Skip to content

Phone notifications

The mobile inbox uses curated event labels for the event types below. Task and workflow alerts use the listed fixed sentence; the project name is prefixed when available. Server Beat builds its body from the incident scope and summary. Backup labels are reserved in the client; no enqueue site currently sends these event types, so they have no built-in body or severity.

Event type Label Push sentence Severity When sent
task_started Task started Work on this task has started. info A task status changes to in progress.
task_blocked Task blocked Blocked. Open the task in HeyAira to see what is needed. error A task status changes to blocked.
task_completed Task completed Completed. The handoff lists the next step. attention A task status changes to done; or GitHub reports the task's own published pull request merged while the task was blocked or its publication unconfirmed.
task_offer_unclaimed Task waiting Sent to the Mac, but not picked up yet. Open the task in HeyAira to see why. attention An offered execution remains unclaimed for five minutes, except a workspace_config retry offer (infra_attempts > 0).
task_stalled Task stalled Work has stalled. Open the task in HeyAira to see the reason and next step. warning A current workflow reaches a stall rule's threshold; once per workflow, rule and triggering timestamp. Sleep suppresses the generic active-phase rules, not workspace_config or blocked_unattended. Also a move handed to a session on a task without a workflow that stays untouched for 30 minutes; once per task, recipient and anchor (see Unattended moves).
task_publication_missing Not published Accepted, but no pull request yet. Open the task in HeyAira to see why. error Accepted work has no reported pull request after ten minutes, or its Mac reports that publishing failed; the task becomes blocked (this push replaces "Task blocked").
task_checks_failed Checks failed Checks failed on the pull request. Open the task in HeyAira to see which. error CI fails for the current candidate.
task_ci_passed CI passed The task status changed. attention All runs for an interactive task PR head pass; body also names the outcome, stage and next actor; or the server's CI follow-up on a confirmed Bridge publication ends with every run passed: once per candidate commit, the body names the pull request and the next actor (the recipient who merges).
task_ci_failed CI failed The task status changed. error All runs finish and at least one fails; the executor has the move.
task_ci_unfinished CI unfinished The task status changed. attention Interactive CI polling reaches its limit; the responsible actor has the move.
task_checks_unfinished Checks unfinished CI did not finish within an hour; the task stays done. Open the task in HeyAira to see which checks. attention The server's CI follow-up after a confirmed pull request ends (one hour) with CI still not settled; the history gets a ci_unfinished entry with the reason. Once per candidate commit; the task stays done.
workflow_parked Task parked Execution parked. Open the task in HeyAira to see the reason. error An execution is parked because its failure is ineligible for retry, it failed after the provider started, the retry window or transient attempt budget expired, or authorization was revoked. Eligible workspace_config failures have no attempt-count limit.
backup_failed Backup failed Caller supplied; no built-in push sentence. not enqueued Reserved label; no current enqueue site.
backup_recovered Backup recovered Caller supplied; no built-in push sentence. not enqueued Reserved label; no current enqueue site.
server_beat_incident_opened Incident opened The incident scope and summary from Server Beat. error A monitored service goes down.
server_beat_incident_recovered Incident recovered The incident scope and summary from Server Beat. attention A monitored service recovers.
server_beat_incident_escalated Incident escalated The incident scope and summary from Server Beat. warning A continuing incident reaches escalation.

task_blocked, task_publication_missing, task_checks_failed and task_stalled are not left to the phone alone. When no phone received one of them within 15 minutes (HEYAIRA_SERVER_BEAT_TASK_ESCALATION_SECONDS), because the push failed or ran out of attempts, the device token is missing, the project has no active phone or the push worker is not running, the Server Beat runner e-mails the same title and sentence through its SES file. This happens once per event; a failed send is retried for up to 24 hours, and at most 20 task alert e-mails go out per hour (HEYAIRA_SERVER_BEAT_TASK_EMAIL_HOURLY_CAP; the rest wait). An alert whose problem is over by the time it would be sent (the task is no longer blocked, the pull request arrived, or the checks passed on a later run, the workflow no longer has the same stall rule and timestamp, or an unattended move was made) is dropped instead of e-mailed. Only the project in HEYAIRA_SERVER_BEAT_NOTIFICATION_PROJECT_ID is escalated. A push the owner's own preferences exclude (severity, event types) is not escalated, and quiet hours delay the e-mail until they end.

Labels and fixed task sentences are defined in src/heyaira/bridge.py; enqueue severities and triggers are defined at the task/workflow and Server Beat enqueue sites. python scripts/check_docs_contract.py checks that every curated event appears exactly once and that labels and fixed sentences match the runtime mappings. The checker reads literal runtime mappings from source, so it runs with the documentation-only dependencies used by CI.

Unattended moves

Stall rules judge only tasks with a current workflow. A task without one has an explicit "the move belongs to X since T" clock instead, when its move was handed over: the move is unattended when all of these hold:

  • next_actor_override names an active assignment of a session (not a person, a catalog agent or the account owner) and that assignment is the task's derived next actor;
  • the task is open (todo, in_progress or blocked), its stage is not idea, done or dropped, it has no current workflow and no decision hold;
  • for 15 minutes (900 seconds inclusive) neither the task was written nor did that session create, report on or release a claim on it. The anchor is the latest of those timestamps.

A scheduled check is the second clock: an open task with the same exclusions (stage, workflow, decision hold) whose due_at has passed with no task write since is unattended at once, with or without a derived next actor.

Bridge reads count such tasks under counter=unattended and expose organization.unattended_since (null otherwise), so a local watcher can wake the session whose move it is. assignment_id/subject_id filters match only the next actor, so a task without one is counted but not listed under them. unattended_since is when the move became unattended: the anchor plus 900 seconds for a handover, due_at for a missed due time, and the earliest of the two when both apply. A rule starts applying only at that time, so the value never decreases within one continuous episode and tasks that become unattended later always show a later value; the watcher's --after <next_after> re-arm relies on this. A handover counts only while its override is the derived next actor. continuity_context lists at most twenty of them as work.unattended, earliest first, with next_actor naming the handover recipient (null for a missed due time alone) and due_at.

After 30 minutes from an internal anchor (the handover anchor or due_at) the recovery loop sends one task_stalled warning naming the recipient. Its key names the rule with the earlier anchor: unattended:<task>:<assignment>:<anchor epoch>, or unattended:<task>:due:<due_at epoch>. There is one warning per continuous episode, kept as explicit state (task_unattended_episodes, one row per task) by the same recovery scan: it opens the episode when it first sees the task unattended, records the warning's key when it sends it, and closes the episode when it sees the task attended (no rule applies, or a task write followed the episode's start). While the episode is open, a change of the winning rule neither sends another warning nor resolves the first; the warning is resolved once its episode is closed. Any gap the scan observes starts a new episode with its own warning. The owner's phone gets it only where project notification copies are enabled; the e-mail fallback stays limited to the escalation project.

Handing a move over: call task_stage_set with the current stage, next_actor_override_assignment_id set to the recipient session's assignment and a waiting_reason. The recipient's task write or claim activity is its move; it clears or replaces the override when it hands the move back. A scheduled wait sets the override only when the move becomes due. Changing the stage clears the override.

Scheduling a check: set due_at with task_update or task_stage_set (ISO 8601 with an offset). A time written only in a handoff is invisible to the server. The first task write after due_at resolves it; a stage change keeps due_at, null clears it.

Workflow stall limits

The app-process recovery loop checks current active, blocked, retry_wait and awaiting_verification workflows in batches. task_stalled reports a stage whose triggering anchor is older than its limit; the generic boundaries are strict (limit + 1 second stalls, the limit does not). workspace_config instead starts at 600 seconds inclusive. The five-minute task_offer_unclaimed notification is suppressed for offers whose workflow has infra_attempts > 0 and last_failure_class=workspace_config; first offers and other classes keep their existing behavior. Expired leases and deadlines are not stall rules: existing recovery blocks or parks the workflow and sends its existing blocked/parked notification.

Rule Phase Anchor (since, UTC) Default limit Environment override
workspace_config retry_wait, queued, awaiting_verification, claimed, preparing Workflow first_failure_at, while last_failure_class=workspace_config 600 seconds inclusive None
offer_unclaimed queued Active execution created_at 600 seconds HEYAIRA_STALL_OFFER_UNCLAIMED_SECONDS
start_stuck claimed, preparing Active execution picked_up event 300 seconds, without session_started HEYAIRA_STALL_START_STUCK_SECONDS
bridge_away queued, claimed, preparing, running, verifying Assigned node last_seen_at 900 seconds, with offline presence HEYAIRA_STALL_BRIDGE_AWAY_SECONDS
blocked_unattended blocked Latest blocked transition event created_at 600 seconds, with no task write after the block HEYAIRA_STALL_BLOCKED_UNATTENDED_SECONDS

workspace_config takes precedence over every generic active-phase rule, including bridge_away and offer_unclaimed. Its fixed reason identifies unsupported Git configuration in the Bridge task clone and appends only a sanitized, bounded diagnostic. Its hint tells the operator to recreate a clean project clone in the Bridge agents directory without attaching editor worktrees; the workflow resumes automatically. The episode keeps its first_failure_at anchor through re-offers, claims and verifier retries in awaiting_verification, including sleep and decision holds. It clears when running resets the failure fields, the class changes, or the workflow stops or becomes non-current. The existing escalation closes a resolved alert without sending a resolution notification; re-offering alone does not resolve it.

Among generic active-phase rules, bridge_away takes precedence. Sleep suppresses these rules; scheduled wakes retain asleep presence through the existing wake grace; missing a wake changes presence to offline. blocked_unattended covers the next move after a block, which belongs to a person or session, so the Mac's presence does not matter: any task write later than the block (a handoff note, a resend, a retirement) is the move and clears it, while CI or recovery writes to the workflow row do not move the anchor; a decision hold on the task or a done task never raises it. Other terminal phases and ready, waiting_capacity and changes_requested do not stall. awaiting_verification and retry_wait stall only for an eligible workspace_config episode. Configurable limits are nonnegative integer seconds, loaded when heyaira.stalls is imported; invalid overrides use the defaults. since remains the original anchor on every read, and its integer UTC epoch identifies the notification and its resolution. Ordinary execution-specific Bridge skip reasons appear in the pickup hint; the workspace rule appends only sanitized failure diagnostics to its reason. Credential-like text is suppressed. No stall is stored; stall evaluation itself changes no recovery, lease, phase or dispatch rule.