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_overridenames 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.