aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/apps/cli/transactions.py

@@ -0,0 +1,269 @@
+"""The REPL's transaction points: take one before each turn, rewind to any.
+
+``runtime/transactions.py`` stores points; this reads and writes the state a
+point covers, which lives in the terminal and in CLI module globals:
+
+* the conversation — ``terminal.conversation``;
+* approvals — ``_auto_approve_session``, ``_session_always_allow`` and
+  ``_session_command_prefixes`` in the module the terminal was built in
+  (aria_cli rebinds the approval functions onto its own globals, so that copy
+  is the one in force, not tool_executor's);
+* the task list — ``aria_code.apps.cli.todo_tracker``, the copy the
+  ``update_todos`` tool writes;
+* background tasks — ``runtime.subagent``, the copy the CLI registers;
+* the task worktree — ``apps.cli.task_isolation``.
+
+Files are undone first: a conflict there stops the rewind before anything
+else has changed.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from aria_code.runtime.transactions import (
+    TransactionPoint,
+    TransactionStore,
+    default_transaction_store,
+    new_point,
+)
+
+logger = logging.getLogger(__name__)
+
+_STORE: list[Optional[TransactionStore]] = [None]
+
+
+def store() -> TransactionStore:
+    if _STORE[0] is None:
+        _STORE[0] = default_transaction_store()
+    return _STORE[0]
+
+
+def reset_for_tests(replacement: Any = None) -> None:
+    _STORE[0] = replacement
+
+
+def _namespace(terminal: Any) -> dict:
+    return vars(sys.modules[type(terminal).__module__])
+
+
+def _todos():
+    from aria_code.apps.cli import todo_tracker
+    return todo_tracker
+
+
+def _checkpoints():
+    # The aria_code.* copy, as the write tools record with: a conflict raised
+    # from it is the class callers catch.
+    from aria_code.runtime.checkpoints import CheckpointStore
+    return CheckpointStore()
+
+
+def _approvals(namespace: dict) -> dict:
+    return {
+        "allow_all": bool(namespace.get("_auto_approve_session", False)),
+        "tools": sorted(namespace.get("_session_always_allow") or ()),
+        "prefixes": sorted(list(prefix) for prefix in namespace.get("_session_command_prefixes") or ()),
+    }
+
+
+def _open_task(terminal: Any) -> Optional[dict]:
+    try:
+        from apps.cli import task_isolation
+
+        tasks = task_isolation.manager()
+        task = tasks.active(task_isolation._workspace(terminal.config))
+        if task is None:
+            return None
+        return {"task_id": task.task_id, "repository": task.repository, "path": task.path,
+                "patch": tasks.patch(task)}
+    except Exception as exc:
+        logger.debug("task state not captured: %s", exc)
+        return None
+
+
+def capture(terminal: Any, prompt: str) -> Optional[TransactionPoint]:
+    """Record the state before the turn ``prompt`` starts. Never raises."""
+    try:
+        session_id = str(getattr(terminal, "session_id", "") or "default")
+        turn = sum(1 for message in terminal.conversation if message.get("role") == "user") + 1
+        point = new_point(
+            session_id=session_id, turn=turn, prompt=prompt,
+            messages=list(terminal.conversation),
+            todos=list(_todos().get_active_todos()),
+            approvals=_approvals(_namespace(terminal)),
+            checkpoint_sequence=_checkpoints().max_sequence(),
+            verdict=str(getattr(terminal, "_code_verdict", "") or ""),
+            task=_open_task(terminal),
+        )
+        return store().record(point)
+    except Exception as exc:
+        logger.debug("transaction point not recorded: %s", exc)
+        return None
+
+
+@dataclass
+class RewindOutcome:
+    point: TransactionPoint
+    restored_paths: tuple = ()
+    messages_removed: int = 0
+    approvals_revoked: list = field(default_factory=list)
+    tasks_cancelled: list = field(default_factory=list)
+    task_note: str = ""
+
+    def lines(self) -> list[str]:
+        count = len(self.restored_paths)
+        out = [f"Rewound to before turn {self.point.turn}: “{self.point.prompt}”"]
+        out.append(f"  files         {count} restored" if count else "  files         no changes to undo")
+        out.append(f"  conversation  {self.messages_removed} message{'s' if self.messages_removed != 1 else ''} removed")
+        if self.approvals_revoked:
+            out.append(f"  approvals     revoked {', '.join(self.approvals_revoked)}")
+        if self.tasks_cancelled:
+            out.append(f"  background    cancelled {', '.join(self.tasks_cancelled)}")
+        if self.task_note:
+            out.append(f"  task          {self.task_note}")
+        if self.point.verdict:
+            out.append(f"  checks        {self.point.verdict} at this point")
+        if self.point.truncated:
+            out.append("  note          the oldest messages were too large to keep and are not restored")
+        return out
+
+
+def _worktree_skip(terminal: Any):
+    """Files in task worktrees are restored as a whole, not file by file.
+
+    A worktree still open is reset to the point's patch (which also undoes
+    what shell commands changed, which no file checkpoint records); one that
+    is gone has nowhere to be restored to and is reopened from the patch.
+    The user's own files still go back by checkpoint.
+    """
+    try:
+        from apps.cli import task_isolation
+        root = task_isolation.manager().root.resolve()
+    except Exception:
+        return lambda _path: False
+
+    def skip(path: str) -> bool:
+        try:
+            Path(path).resolve().relative_to(root)
+            return True
+        except (ValueError, OSError):
+            return False
+
+    return skip
+
+
+def _settle_open_task(terminal: Any, point: TransactionPoint) -> str:
+    """The task open now, put back to what it was at ``point``."""
+    try:
+        from apps.cli import task_isolation
+
+        tasks = task_isolation.manager()
+        current = tasks.active(task_isolation._workspace(terminal.config))
+    except Exception as exc:
+        logger.debug("task state not restored: %s", exc)
+        return ""
+    if current is None:
+        return ""
+    saved = point.task or {}
+    if saved.get("path") == current.path:
+        tasks.reset_to_patch(current, str(saved.get("patch") or ""))
+        return "worktree reset to this point" if str(saved.get("patch") or "").strip() else ""
+    if current.created_at > point.created_at:
+        tasks.discard(current)
+        return f"discarded {current.task_id}, started after this point"
+    return ""
+
+
+def _restore_task(terminal: Any, point: TransactionPoint) -> str:
+    saved = point.task
+    if not saved or not str(saved.get("patch") or "").strip():
+        return ""
+    if Path(saved["path"]).is_dir():
+        return ""  # still open: its files were restored with the rest
+    from apps.cli import task_isolation
+
+    tasks = task_isolation.manager()
+    try:
+        task = tasks.ensure(task_isolation._workspace(terminal.config))
+        if task is None:
+            raise RuntimeError("not a git repository")
+        tasks.restore_patch(task, saved["patch"])
+        return f"reopened as {task.task_id} with its unapplied changes"
+    except Exception as exc:
+        keep = Path(tasks.root) / f"rewound-{saved['task_id']}.patch"
+        keep.parent.mkdir(parents=True, exist_ok=True)
+        keep.write_text(saved["patch"], encoding="utf-8")
+        return f"could not be reopened ({exc}); its changes are saved in {keep}"
+
+
+def _cancel_later_tasks(terminal: Any, point: TransactionPoint) -> list[str]:
+    try:
+        from runtime.subagent import _TASKS, tool_task_cancel
+    except Exception:
+        return []
+    session_id = str(getattr(terminal, "session_id", "") or "")
+    cancelled = []
+    for task in list(_TASKS.values()):
+        if task.created_at <= point.created_at or task.status not in ("pending", "running"):
+            continue
+        if task.session_id and session_id and task.session_id != session_id:
+            continue
+        if tool_task_cancel({"task_id": task.task_id}).get("success"):
+            cancelled.append(task.task_id)
+    return cancelled
+
+
+def rewind(terminal: Any, point: TransactionPoint) -> RewindOutcome:
+    """Put the session back to ``point``. Raises if files cannot be restored."""
+    session_id = str(getattr(terminal, "session_id", "") or "default")
+    files = _checkpoints().restore_since(point.checkpoint_sequence, session_id=session_id,
+                                         skip=_worktree_skip(terminal))
+    outcome = RewindOutcome(point=point, restored_paths=files.restored_paths)
+    notes = [_settle_open_task(terminal, point), _restore_task(terminal, point)]
+    outcome.task_note = "; ".join(note for note in notes if note)
+
+    outcome.messages_removed = max(0, len(terminal.conversation) - len(point.messages))
+    terminal.conversation[:] = list(point.messages)
+
+    todos = _todos()
+    todos._ACTIVE_TODOS[:] = list(point.todos)
+
+    namespace = _namespace(terminal)
+    before = _approvals(namespace)
+    saved = point.approvals or {}
+    namespace["_auto_approve_session"] = bool(saved.get("allow_all", False))
+    for key, values in (("_session_always_allow", saved.get("tools") or ()),
+                        ("_session_command_prefixes", [tuple(p) for p in saved.get("prefixes") or ()])):
+        current = namespace.get(key)
+        if isinstance(current, set):
+            current.clear()
+            current.update(values)
+    revoked = [tool for tool in before["tools"] if tool not in (saved.get("tools") or ())]
+    revoked += [" ".join(prefix) for prefix in before["prefixes"] if prefix not in (saved.get("prefixes") or [])]
+    if before["allow_all"] and not saved.get("allow_all"):
+        revoked.insert(0, "allow-all")
+    outcome.approvals_revoked = revoked
+
+    outcome.tasks_cancelled = _cancel_later_tasks(terminal, point)
+    terminal._code_verdict = point.verdict
+    store().drop_from(point)
+    return outcome
+
+
+def describe(points: list[TransactionPoint], *, now: Optional[float] = None) -> list[str]:
+    """``/rewind turns``: newest first, numbered as ``/rewind turn N`` takes them."""
+    now = now or time.time()
+    marks = {"passed": "✓", "failed": "✗", "preexisting": "≈", "unverified": "·", "": " "}
+    lines = []
+    for index, point in enumerate(points, 1):
+        age = now - point.created_at
+        when = f"{int(age)}s" if age < 60 else f"{int(age // 60)}m" if age < 3600 else f"{age / 3600:.1f}h"
+        lines.append(f"  {index:>2}  {point.point_id[:8]}  {marks.get(point.verdict, ' ')}  "
+                     f"{when:>5} ago  before turn {point.turn}: {point.prompt[:60]}")
+    return lines

aria_code/apps/cli/turn_planning.py

@@ -0,0 +1,137 @@
+"""Per-turn planning DECISIONS for send_message (pure, testable).
+
+Extracted from ``aria_cli.send_message`` — the first slice of the file's
+1300+ line stateful method to be pulled out. This module holds only the
+*decision* logic (round budget, whether to trigger AI decomposition), which
+depends solely on the user's message text and has no I/O, no ``self`` state,
+and no side effects. It is safe to unit-test in isolation and safe to extract
+without any behavior change, unlike the surrounding streaming/tool-loop code.
+
+Mirrors send_message's inline logic exactly:
+  • task complexity  → message > 120 chars, or contains a multi-step keyword
+  • round budget      → complex tasks get a larger soft/hard round budget
+  • decomposition     → long (>150 char), complex, non-slash-command messages
+                         trigger an upfront AI decomposition pass
+"""
+
+from __future__ import annotations
+
+TASK_COMPLEXITY_LENGTH_THRESHOLD = 120
+
+TASK_COMPLEXITY_KEYWORDS = (
+    "然后", "接着", "最后", "步骤", "并且", "同时",
+    "and then", "step", "finally", "after that", "next",
+    "完整", "全面", "详细", "系统", "comprehensive", "complete",
+)
+
+DECOMP_THRESHOLD = 150   # chars
+
+SOFT_ROUND_BUDGET_SIMPLE = 16
+SOFT_ROUND_BUDGET_COMPLEX = 30
+HARD_ROUND_EXTENSION_SIMPLE = 10
+HARD_ROUND_EXTENSION_COMPLEX = 20
+
+
+def is_complex_task(message: str) -> bool:
+    """A message is 'complex' if it's long or names a multi-step structure."""
+    return (
+        len(message) > TASK_COMPLEXITY_LENGTH_THRESHOLD
+        or any(kw in message for kw in TASK_COMPLEXITY_KEYWORDS)
+    )
+
+
+def round_budget_for(is_complex: bool) -> tuple[int, int]:
+    """-> (max_rounds, hard_max_rounds). Complex tasks get a larger budget
+    on both the soft limit (where we start checking for real progress) and
+    the hard extension (how far a still-progressing task can run past it)."""
+    max_rounds = SOFT_ROUND_BUDGET_COMPLEX if is_complex else SOFT_ROUND_BUDGET_SIMPLE
+    hard_max_rounds = max_rounds + (
+        HARD_ROUND_EXTENSION_COMPLEX if is_complex else HARD_ROUND_EXTENSION_SIMPLE
+    )
+    return max_rounds, hard_max_rounds
+
+
+def should_decompose(message: str, is_complex: bool) -> bool:
+    """Trigger an upfront AI decomposition pass for long, complex, non-slash
+    messages. Slash commands (``/...``) and bang commands (``!...``) are never
+    decomposed — they're already a single deterministic action."""
+    return (
+        len(message) > DECOMP_THRESHOLD
+        and is_complex
+        and not any(message.startswith(p) for p in ("/", "!"))
+    )
+
+
+# ── post-turn context pressure ───────────────────────────────────────────────
+# send_message had three separate places that decide whether history is too hot
+# to carry into the next turn, and they disagreed. The usage-driven one (real
+# provider prompt_tokens) and the pre-turn one both honour auto_compact_context
+# and auto_compact_threshold; the post-turn char-estimate one honoured neither
+# and hardcoded 90% compact / 70% warn. So `/config set
+# auto_compact_context=false` did not turn auto-compaction off — /status said
+# "auto compact off" while the third path still compacted — and a threshold of
+# 0.95 was capped at the hidden 0.90.
+#
+# Warning is deliberately NOT gated on the toggle. Turning auto-compaction off
+# means "do not rewrite my history", not "stop telling me how full it is" —
+# and it is precisely the user who disabled compaction who needs to be told to
+# run /compact.
+
+CONTEXT_WARN_FRACTION = 0.70
+CHARS_PER_TOKEN_ESTIMATE = 3
+DEFAULT_COMPACT_THRESHOLD = 0.78
+MIN_COMPACT_THRESHOLD = 0.50
+MAX_COMPACT_THRESHOLD = 0.95
+
+
+def estimate_context_tokens(conversation: list) -> int:
+    """Rough token count for a conversation, by characters."""
+    return sum(
+        len(m.get("content", "") or "") for m in (conversation or [])
+    ) // CHARS_PER_TOKEN_ESTIMATE
+
+
+def clamp_compact_threshold(value) -> float:
+    """Config threshold as a fraction, clamped to the range /config accepts."""
+    try:
+        threshold = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_COMPACT_THRESHOLD
+    return max(MIN_COMPACT_THRESHOLD, min(MAX_COMPACT_THRESHOLD, threshold))
+
+
+def post_turn_context_decision(
+    used_tokens: int,
+    max_tokens: int,
+    *,
+    auto_compact_enabled: bool = True,
+    threshold=DEFAULT_COMPACT_THRESHOLD,
+    already_compacted: bool = False,
+) -> dict:
+    """-> {"fill_pct", "should_compact", "should_warn"}.
+
+    ``already_compacted`` is the usage-driven path having fired this turn; it
+    suppresses both outcomes so one turn never compacts twice or warns about a
+    figure it just fixed.
+    """
+    if max_tokens <= 0:
+        return {"fill_pct": 0, "should_compact": False, "should_warn": False}
+
+    fill_pct = min(100, int(used_tokens / max_tokens * 100))
+    limit_pct = clamp_compact_threshold(threshold) * 100
+
+    should_compact = (
+        bool(auto_compact_enabled)
+        and not already_compacted
+        and fill_pct >= limit_pct
+    )
+    should_warn = (
+        not should_compact
+        and not already_compacted
+        and fill_pct >= CONTEXT_WARN_FRACTION * 100
+    )
+    return {
+        "fill_pct": fill_pct,
+        "should_compact": should_compact,
+        "should_warn": should_warn,
+    }

aria_code/apps/cli/update_check.py

@@ -0,0 +1,257 @@
+"""Background version checker for the active Aria Code install channel.
+
+Checks GitHub releases or scoped npm once per 24 hours in a daemon thread so
+startup is never blocked. The result is cached in the Aria home directory and read
+at banner render time.
+
+Public API
+----------
+    start_update_check(current_version: str) -> None
+        Call once, early in startup. Spawns daemon thread; returns immediately.
+
+    get_update_notice() -> str | None
+        Call at banner render time. Returns a Rich-markup string if a newer
+        version is available, otherwise None.  Thread-safe — safe to call
+        before the background thread finishes (returns cached result then).
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Optional
+from aria_code.packages.aria_core.paths import aria_home
+
+_RELEASE_URL   = "https://api.github.com/repos/artheras/aria-code/releases/latest"
+_NPM_URL       = "https://registry.npmjs.org/@artheras%2Faria-code/latest"
+_CACHE_FILE    = aria_home() / "update_check.json"
+_CACHE_TTL_S   = 86_400      # 24 hours
+_FETCH_TIMEOUT = 4           # seconds — fail cleanly on slow networks
+
+# These are the project's historical PyPI releases (June–August 2026),
+# published before the current 0.x line. Do not treat arbitrary future 4.x
+# versions as legacy, or recommend these old artifacts to a current install.
+_LEGACY_VERSIONS = frozenset({
+    (4, 1, 3), (4, 1, 4), (4, 1, 7), (4, 2, 0),
+    (4, 3, 0), (4, 4, 0), (4, 4, 1), (4, 4, 2),
+})
+
+_notice: Optional[str] = None
+_lock   = threading.Lock()
+
+
+# ── Version comparison ────────────────────────────────────────────────────────
+
+def _parse(v: str) -> tuple[int, int, int] | None:
+    """Accept only stable project release tags, never another package's version."""
+    import re
+    match = re.fullmatch(r"v?(\d+)\.(\d+)\.(\d+)", v.strip())
+    return tuple(map(int, match.groups())) if match else None
+
+
+def _newer(latest: str, current: str) -> bool:
+    parsed_latest, parsed_current = _parse(latest), _parse(current)
+    if parsed_latest is None or parsed_current is None:
+        return False
+    if parsed_current in _LEGACY_VERSIONS and parsed_latest[0] == 0:
+        return True
+    if parsed_latest in _LEGACY_VERSIONS and parsed_current[0] == 0:
+        return False
+    return parsed_latest > parsed_current
+
+
+# ── Cache helpers ─────────────────────────────────────────────────────────────
+
+def _read_cache() -> dict:
+    try:
+        return json.loads(_CACHE_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def _write_cache(data: dict) -> None:
+    try:
+        _CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(json.dumps(data))
+    except Exception:
+        pass
+
+
+# ── Notice builder ────────────────────────────────────────────────────────────
+
+def _install_channel() -> str:
+    """Infer which update channel owns the running executable."""
+    override = os.environ.get("ARIA_CODE_INSTALL_CHANNEL", "").lower()
+    if override in ("npm", "native", "pip", "source"):
+        return override
+    executable = str(getattr(sys, "executable", "") or "").lower()
+    if "node_modules" in executable and "aria" in executable:
+        return "npm"
+    if getattr(sys, "frozen", False):
+        return "native"
+    root = Path(__file__).resolve().parents[4]
+    if (root / ".git").exists() and (root / "pyproject.toml").exists():
+        return "source"
+    return "pip"
+
+
+def _update_command(channel: str, latest: str = "") -> str:
+    if channel == "npm":
+        return "npm install -g @artheras/aria-code@latest"
+    if channel == "source":
+        return "git pull && python3 -m pip install -e ."
+    if channel == "pip":
+        # Pinned: PyPI still lists an older 4.x numbering, so an unpinned
+        # --upgrade "updates" 0.73.0 to 4.4.2, which is older code.
+        return f'python3 -m pip install --upgrade "aria-code=={latest}"' if latest else \
+            'python3 -m pip install --upgrade "aria-code<4"'
+    if sys.platform == "win32":
+        return "irm https://raw.githubusercontent.com/artheras/aria-code/main/scripts/install.ps1 | iex"
+    return "curl -fsSL https://raw.githubusercontent.com/artheras/aria-code/main/scripts/install.sh | sh"
+
+
+def _build_notice(latest: str, current: str, lang: str, channel: str = "native") -> str:
+    latest = latest.removeprefix("v")
+    current = current.removeprefix("v")
+    cmd = _update_command(channel, latest) if channel == "source" or (channel == "native" and sys.platform == "win32") else "aria update"
+    if lang == "zh":
+        return (
+            f"[yellow]⬆  新版本可用[/yellow] "
+            f"[dim]v{current}[/dim] [dim]→[/dim] [bold]v{latest}[/bold]"
+            f"  [dim]{cmd}[/dim]"
+        )
+    return (
+        f"[yellow]⬆  Update available[/yellow] "
+        f"[dim]v{current}[/dim] [dim]→[/dim] [bold]v{latest}[/bold]"
+        f"  [dim]{cmd}[/dim]"
+    )
+
+
+# ── Background worker ─────────────────────────────────────────────────────────
+
+def _worker(current: str, lang: str, channel: str = "native") -> None:
+    global _notice
+    # GitHub releases are the version of record for every channel but npm.
+    # PyPI's own "latest" is not: it still points at the old 4.x line.
+    source_url, version_field = (_NPM_URL, "version") if channel == "npm" else (_RELEASE_URL, "tag_name")
+
+    # 1. Serve from cache if still fresh
+    cache = _read_cache()
+    now   = time.time()
+    if cache.get("source") == source_url and cache.get("checked_at", 0) + _CACHE_TTL_S > now:
+        latest = cache.get("latest", "")
+        if latest and _newer(latest, current):
+            with _lock:
+                _notice = _build_notice(latest, current, lang, channel)
+        return
+
+    # 2. Fetch metadata for this installation channel, never a similarly named package.
+    latest = _native_latest(current, channel)
+    if latest is None:
+        try:
+            import urllib.request
+            req = urllib.request.Request(
+                source_url,
+                headers={"Accept": "application/json", "User-Agent": "aria-code-update-check"},
+            )
+            with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
+                data   = json.loads(resp.read())
+                latest = data[version_field]
+        except Exception:
+            return   # background checks never interrupt the user's work
+
+    # 3. Persist to cache
+    if _parse(latest) is None:
+        return
+    _write_cache({"source": source_url, "checked_at": now, "latest": latest})
+
+    # 4. Set notice
+    if _newer(latest, current):
+        with _lock:
+            _notice = _build_notice(latest, current, lang, channel)
+
+
+def _native_latest(current: str, channel: str) -> str | None:
+    """Ask the bundled Rust updater to validate/cache release metadata.
+
+    Return None when the helper is unavailable or incompatible so older
+    packages and Windows keep their established Python check path.
+    """
+    payload = _native_check(current, channel)
+    latest = payload.get("latest") if payload else None
+    return latest.removeprefix("v") if isinstance(latest, str) and _parse(latest) else None
+
+
+def _native_check(current: str, channel: str, *, refresh: bool = False) -> dict | None:
+    """Return checked metadata from the bundled Rust updater, if available."""
+    try:
+        # Lazy import avoids a module cycle: updater imports this module's
+        # release constants and version helpers.
+        from aria_code.apps.cli.updater import _native_update_helper
+
+        helper = _native_update_helper()
+        if helper is None:
+            return None
+        command = [str(helper), "update", "check", "--current", current, "--channel", channel]
+        if refresh:
+            command.append("--refresh")
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=_FETCH_TIMEOUT + 2,
+            check=False,
+        )
+        if result.returncode != 0:
+            return None
+        payload = json.loads(result.stdout)
+        return payload if isinstance(payload, dict) else None
+    except Exception:
+        return None
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+def start_update_check(current_version: str, lang: str = "en", enabled: bool = True) -> None:
+    """Start background version check. Call once, early in startup."""
+    global _notice
+    with _lock:
+        _notice = None
+    if not enabled:
+        return
+    channel = _install_channel()
+    source = _NPM_URL if channel == "npm" else _RELEASE_URL
+    cache = _read_cache()
+    if cache.get("source") == source and _newer(cache.get("latest", ""), current_version):
+        with _lock:
+            _notice = _build_notice(cache["latest"], current_version, lang, channel)
+    t = threading.Thread(
+        target=_worker,
+        args=(current_version, lang, channel),
+        daemon=True,
+        name="aria-update-check",
+    )
+    t.start()
+
+
+def get_update_notice(wait_ms: int = 0) -> Optional[str]:
+    """Return Rich-markup update notice, or None if up to date / not yet known.
+
+    Read the cached notice immediately. An explicit wait is supported for
+    callers outside startup, but startup never waits for a network request.
+    """
+    deadline = time.monotonic() + wait_ms / 1000
+    while time.monotonic() < deadline:
+        with _lock:
+            if _notice is not None:
+                return _notice
+        alive = any(t.name == "aria-update-check" for t in threading.enumerate())
+        if not alive:
+            break
+        time.sleep(0.05)
+    with _lock:
+        return _notice