Impact Alerts

A function you depend on changed on another branch. You want to know now, not at merge time.

Impact alerts are Aura's way of surfacing cross-branch changes that reach into the code you are currently editing. When a teammate on main, or an agent on a feature branch, modifies or deletes a function that your working copy calls, Aura raises an alert — in your terminal, in the MCP status payload, and on the dashboard. You see the impact within seconds of it being pushed to the Mothership, not days later when you rebase. Impact alerts are how Live Sync keeps you aware of changes that are too far away to show up as a sync conflict but still relevant to what you are doing right now.

Overview

Normal version control gives you two moments of truth: the moment you pull (where you find out what happened) and the moment you merge (where you find out what broke). Everything in between is silence. In a world where a teammate and two AI agents are working in parallel, silence is where bugs breed.

Impact alerts turn the silence into a continuous feed. The feed is narrowly scoped on purpose — it only tells you about functions you actually touch. The dependency graph that underlies semantic diff is the same graph that powers impact alerts. If function A on your branch calls function B, and someone modifies B on another branch, you get an alert. If B is in a different part of the tree you never touch, you get nothing. The signal-to-noise ratio is high by construction.

A sample alert, as shown in aura_status:

cross-branch impacts: 2 unresolved

  [impact-8f3a]  modified   billing::compute_tax
                 caller on this branch: billing::generate_invoice
                 modified by: alice        branch: main     12m ago
                 old hash: 4a21...   new hash: 9b11...

  [impact-0c71]  deleted    utils::retry_with_backoff
                 caller on this branch: http::fetch_user
                 deleted by: claude-agent  branch: feat/fetch  3m ago

Each alert carries: the affected function, how you depend on it, who changed it, on which branch, and what kind of change (modified, deleted, renamed, signature-changed). You act on it by fixing your caller, adjusting your plan, or acknowledging the alert.

How It Works

Impact alerts are a byproduct of two systems working together: the logic graph and Live Sync's push channel.

    ┌── alice on main ─────────┐         ┌── Mothership ──┐         ┌── you on feat/x ─────┐
    │ edit billing::compute_tax│  push   │                │  fan-out │ scan my callers of    │
    │ (new AST hash)           ├────────>│ route fn push  ├─────────>│   compute_tax         │
    └──────────────────────────┘         └────────────────┘          │ any? -> raise alert   │
                                                                      └───────────────────────┘

When a function body arrives via Live Sync from another branch, Aura does three things:

Check your logic graph. Does any function on your current branch call the modified function? If no, the event is filed in history but no alert is raised.
Compare signatures. If the function's argument list or return type changed, the alert severity is upgraded — this is more than a body tweak; callers almost certainly need updating.
Attach a proof request. If the caller and callee are on different branches with known divergence, Aura can enqueue a background aura_prove run to check whether your caller is still satisfied by the new body. The result attaches to the alert.

Deletion alerts are a special case. If the incoming event says "function removed" and you have callers, the alert is marked critical — your branch will not build against the other branch until you fix the callers or the callee returns.

Fetching impacts from MCP

Agents see impacts automatically at session start (it is part of the aura_status payload), and they should re-check periodically during long sessions. Explicitly:

# Via MCP:
aura_live_impacts

# Via CLI:
aura live impacts

Output (aura live impacts --json):

{
  "unresolved": [
    {
      "id": "impact-8f3a",
      "kind": "modified",
      "target_fn": "billing::compute_tax",
      "caller_fn": "billing::generate_invoice",
      "remote_branch": "main",
      "remote_author": "alice",
      "old_hash": "4a21...",
      "new_hash": "9b11...",
      "ts_ms": 1740000000000
    }
  ]
}

Resolving an alert

When you have addressed an alert — either by updating your caller, adjusting your plan, or deciding it does not apply — mark it resolved:

# Via MCP:
aura_live_resolve impact-8f3a --note "Updated generate_invoice to pass region."

# Via CLI:
aura live resolve impact-8f3a --note "..."

Resolution is durable. It records who resolved it, when, and why. Re-opening an alert is allowed; Aura will raise a fresh alert with a link to the prior resolution so you can see the history.

There is also a dismissal path for alerts that are not actionable:

aura live resolve impact-8f3a --dismiss --reason "Unrelated — caller no longer uses this path."

Dismissed alerts do not re-appear unless the function changes again.

Alert kinds

| Kind | Meaning | Typical action | |---|---|---| | modified | Function body changed | Re-read the body, check your assumptions, possibly re-prove | | signature_changed | Arguments or return type changed | Update every caller on your branch | | deleted | Function removed | Restore, inline, or replace callers | | renamed | Function moved/renamed (same aura_id) | No code fix needed — update imports if the rename crosses modules | | moved_file | Function moved across files | Update imports |

Acting on impacts as an AI agent

Agents running inside Aura should treat unresolved impacts as blocking for any commit that touches the caller:

  agent turn:
    1. call aura_status
    2. if cross-branch impacts > 0:
         call aura_live_impacts
         for each impact:
            read caller + new callee body
            fix or decide not-applicable
            call aura_live_resolve with note
    3. proceed with original task

This is already wired in the MCP pipeline — the aura_status payload surfaces team.pending_impacts and the Claude Code system prompt instructs agents to handle them before other work.

Config

Impact alerts are on whenever Live Sync is on. You can tune the scope:

[live.impacts]
# Only raise for functions I directly call. If false, also alerts for 2nd-order deps.
direct_callers_only = true

# Ignore impacts older than this. Useful after a long absence when the feed is noisy.
max_age_days = 14

# Suppress alerts from these branches (e.g. long-running experiment branches).
ignore_branches = ["experiment/*", "wip/*"]

Troubleshooting

If you expect an alert and do not see one, check that the remote branch has actually pushed the change to the Mothership (aura live sync status --peer alice). A local commit that has not been pushed cannot raise an impact.

If you see spurious alerts for functions you never touch, the caller graph may be stale. Rebuild it:

aura graph rebuild

Gotcha: Impact alerts are cross-branch. If you and Alice are on the same branch, her push is applied to your working copy directly (possibly producing a sync conflict), not raised as an impact.

Severity and escalation

Alerts have three severity levels and the UI treats them differently:

info — body change only, caller likely unaffected. Shown in status; does not interrupt.
warn — body change with semantic impact (branches taken, error paths), or signature change. Surfaces in aura_status and is expected to be addressed.
critical — function deleted, or signature change that provably breaks your caller. Blocks commits that touch the caller until resolved or explicitly dismissed.

An AI agent flow treats critical as a hard gate:

  on every commit attempt:
    impacts = aura_live_impacts()
    for each impact in impacts where severity == critical:
      if impact.caller in changeset:
        REFUSE commit, request resolution

The CLI pre-commit hook enforces the same rule.

Detection latency

An end-to-end walk of how fast an alert surfaces:

    t+0.0s   teammate saves, scan detects change
    t+5.0s   next sync tick on their side pushes to Mothership
    t+5.1s   Mothership routes event to your peer
    t+5.2s   your peer cross-references caller graph
    t+5.2s   alert raised (visible in aura_status, CLI, dashboard)

Under five and a half seconds from their save to your alert on a healthy Mothership link. Longer if the teammate's sync window is extended for metered networks.

What an alert is not

Impact alerts are not a test signal. They do not tell you "your code is broken" — they tell you "a thing you depend on moved." Whether that movement breaks you is still your call. Aura can optionally run aura_prove against the caller to give a yes/no answer, but that is a separate subsystem layered on top of the alert.

Impact alerts are also not a Git rebase replacement. Rebasing still integrates commits cleanly in Git history; the alert just tells you, before the rebase, that the rebase is going to touch relevant ground.

Historical replay

Sometimes you want to see all impacts over a time window — for retros, or to understand a bug that landed yesterday:

aura live impacts --since 1d --include-resolved

This prints every impact that fired, whether resolved or dismissed, with timestamps and resolution notes. It is a useful post-mortem trail when a bug correlates with "the day Alice and Bob were both in billing::".