shkit 1.2.0__py3-none-any.whl

iic/notify/teams_notifier.py

@@ -0,0 +1,112 @@
+"""Stage 11 — push incident reports to Teams (optional, informational).
+
+The new product *explains and prioritises*; it does not auto-fix, so the card has
+no Approve/Reject buttons — it carries the intelligence (severity-ranked summary,
+root cause, impact, changes, evidence, suggested fix) and a deep link to the run.
+
+``build_incident_card`` is a pure function (no I/O) so the card layout is unit
+tested; ``TeamsNotifier.send`` is the thin transport wrapper.
+"""
+
+from __future__ import annotations
+
+from iic.models.impact import Severity
+from iic.models.report import IncidentReport
+
+_SEVERITY_RANK = {Severity.CRITICAL: 0, Severity.HIGH: 1, Severity.MEDIUM: 2, Severity.LOW: 3}
+_SEVERITY_EMOJI = {
+    Severity.CRITICAL: "\U0001f534",  # red
+    Severity.HIGH: "\U0001f7e0",      # orange
+    Severity.MEDIUM: "\U0001f7e1",    # yellow
+    Severity.LOW: "\U0001f7e2",       # green
+}
+
+
+def build_incident_card(reports: list[IncidentReport], run_id: str = "",
+                        host: str = "", job_id: str = "", antibodies: dict | None = None) -> dict:
+    """Build a single severity-ranked Adaptive Card for a batch of incidents.
+
+    ``antibodies`` (optional) maps ``pattern_id -> (state, entry)`` from the
+    Antibody Ledger, where ``state`` ∈ {"resolved", "known_unresolved", "new"}.
+    When a report's pattern is present, a ledger block is added ABOVE the machine
+    "Suggested fix" (which always stays — it is the deterministic suggestion; the
+    ledger line is the separate, human-confirmed answer). Callers that don't pass
+    ``antibodies`` get the exact card as before (no ledger block)."""
+    ranked = sorted(reports, key=lambda r: _SEVERITY_RANK.get(r.impact.severity, 9))
+
+    body = [
+        {"type": "TextBlock", "size": "Large", "weight": "Bolder",
+         "text": "\U0001f9e0 Incident Intelligence Report"},
+        {"type": "TextBlock", "isSubtle": True, "wrap": True,
+         "text": f"Run {run_id} · {len(ranked)} incident(s), highest severity first"},
+        {"type": "TextBlock", "separator": True, "text": "---"},
+    ]
+
+    for i, r in enumerate(ranked, 1):
+        emoji = _SEVERITY_EMOJI.get(r.impact.severity, "")
+        body.append({"type": "TextBlock", "weight": "Bolder", "size": "Medium", "separator": True, "wrap": True,
+                     "text": f"{emoji} {i}. [{r.impact.severity.value}] {r.task} — {r.dna.failure_type.value}"})
+        body.append({"type": "TextBlock", "wrap": True,
+                     "text": f"**Root cause** ({int(r.diagnosis.confidence * 100)}%): {r.diagnosis.root_cause}"})
+        body.append({"type": "FactSet", "facts": [
+            {"title": "Business risk", "value": r.impact.business_risk.value},
+            {"title": "Blast radius", "value": f"{r.impact.downstream_jobs} jobs · "
+                                                f"{r.impact.affected_tables} tables · "
+                                                f"{r.impact.dashboard_impact} dashboards"},
+            {"title": "Layer", "value": r.dna.affected_layer},
+            {"title": "Diagnosed by", "value": r.diagnosis.produced_by},
+        ]})
+        if r.changes:
+            body.append({"type": "TextBlock", "wrap": True,
+                         "text": "**Recent changes:** " + "; ".join(r.changes[:3])})
+        ab = (antibodies or {}).get(r.dna.pattern_id)
+        if ab:
+            state, entry = ab
+            n = (entry or {}).get("times_seen", 0) if entry else 0
+            if state == "resolved":
+                resolution = str((entry or {}).get("resolution", "")).strip()
+                body.append({"type": "TextBlock", "wrap": True,
+                             "text": f"♻️ **Known issue** (seen {n}×) — "
+                                     f"Recorded fix that worked for a similar issue: {resolution}"})
+            elif state == "known_unresolved":
+                body.append({"type": "TextBlock", "wrap": True,
+                             "text": f"⚠️ **Recurring issue** (seen {n}×) — "
+                                     "no resolution recorded yet"})
+            else:  # new
+                body.append({"type": "TextBlock", "wrap": True,
+                             "text": "\U0001f195 **New issue** — no resolution recorded yet"})
+        if r.diagnosis.suggested_fix:
+            body.append({"type": "TextBlock", "wrap": True,
+                         "text": f"**Suggested fix:** {r.diagnosis.suggested_fix}"})
+
+    actions = []
+    if host and run_id:
+        actions.append({"type": "Action.OpenUrl", "title": "\U0001f50d View Run",
+                        "url": f"{host.rstrip('/')}/#job/{job_id}/run/{run_id}"})
+
+    content = {
+        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+        "type": "AdaptiveCard", "version": "1.4", "body": body,
+    }
+    if actions:
+        content["actions"] = actions
+    return {"type": "message", "attachments": [
+        {"contentType": "application/vnd.microsoft.card.adaptive", "content": content}]}
+
+
+class TeamsNotifier:
+    def __init__(self, webhook_url: str = ""):
+        self.webhook_url = webhook_url
+
+    def send(self, reports: list[IncidentReport], run_id: str = "",
+             host: str = "", job_id: str = "") -> bool:
+        if not (self.webhook_url and reports):
+            return False
+        import requests
+        card = build_incident_card(reports, run_id=run_id, host=host, job_id=job_id)
+        try:
+            r = requests.post(self.webhook_url, json=card,
+                              headers={"Content-Type": "application/json"}, timeout=15)
+            return r.status_code in (200, 202)
+        except Exception:
+            return False

iic/report/__init__.py

@@ -0,0 +1,7 @@
+"""Stage 10 — incident report generation."""
+
+from __future__ import annotations
+
+from iic.report.report_generator import ReportGenerator
+
+__all__ = ["ReportGenerator"]

iic/report/report_generator.py

@@ -0,0 +1,67 @@
+"""Stage 10 — assemble the final IncidentReport.
+
+Pure assembly: it stitches the products of every prior stage into one
+:class:`IncidentReport`, building a one-line executive summary and a timeline.
+No I/O, no LLM — given the same inputs it always produces the same report.
+"""
+
+from __future__ import annotations
+
+from iic.models.change import ChangeDiffObject
+from iic.models.context import IncidentContextBundle
+from iic.models.diagnosis import DiagnosisResult
+from iic.models.dna import IncidentDNA
+from iic.models.event import NormalizedFailureEvent
+from iic.models.impact import ImpactScore
+from iic.models.report import IncidentReport
+from iic.models.routing import RoutingDecision
+
+
+class ReportGenerator:
+    def build(
+        self,
+        incident_id: str,
+        event: NormalizedFailureEvent,
+        dna: IncidentDNA,
+        impact: ImpactScore,
+        diagnosis: DiagnosisResult,
+        routing: RoutingDecision | None = None,
+        context: IncidentContextBundle | None = None,
+        change_diff: ChangeDiffObject | None = None,
+        evidence: list[str] | None = None,
+    ) -> IncidentReport:
+        summary = self._summary(event, dna, impact)
+        return IncidentReport(
+            incident_id=incident_id,
+            pipeline=event.pipeline,
+            task=event.task,
+            timestamp=event.timestamp,
+            summary=summary,
+            dna=dna,
+            impact=impact,
+            diagnosis=diagnosis,
+            routing=routing,
+            evidence=list(evidence or []),
+            changes=change_diff.summaries() if change_diff else [],
+            timeline=self._timeline(event, dna, diagnosis),
+        )
+
+    @staticmethod
+    def _summary(event: NormalizedFailureEvent, dna: IncidentDNA, impact: ImpactScore) -> str:
+        ftype = dna.failure_type.value.replace("_", " ").lower()
+        return (
+            f"{impact.severity.value} {ftype} in {event.pipeline}.{event.task} "
+            f"({dna.affected_layer} layer) — {impact.downstream_jobs} downstream job(s), "
+            f"{impact.dashboard_impact} dashboard(s) at risk; business risk {impact.business_risk.value}."
+        )
+
+    @staticmethod
+    def _timeline(event: NormalizedFailureEvent, dna: IncidentDNA, diagnosis: DiagnosisResult) -> list[str]:
+        tl = []
+        if event.timestamp:
+            tl.append(f"{event.timestamp} — task '{event.task}' failed")
+        if dna.root_signal:
+            tl.append(f"signal detected — {dna.root_signal}")
+        tl.append(f"classified as {dna.failure_type.value} ({dna.confidence_signature} confidence)")
+        tl.append(f"diagnosed by {diagnosis.produced_by}")
+        return tl

iic/routing/__init__.py

@@ -0,0 +1,7 @@
+"""Stage 8 — model routing."""
+
+from __future__ import annotations
+
+from iic.routing.router import IncidentModelRouter
+
+__all__ = ["IncidentModelRouter"]

iic/routing/router.py

@@ -0,0 +1,42 @@
+"""Stage 8 — decide which model (if any) the diagnosis stage uses.
+
+Deterministic and auditable: impact + cache state + DNA confidence pick the tier,
+never the LLM. The goal is to spend the expensive model only where it earns its
+cost — high-severity or low-confidence incidents — and to skip the LLM entirely
+when the answer is already known (cache) or structurally obvious (a derived
+dependency failure).
+"""
+
+from __future__ import annotations
+
+from iic.models.dna import FailureType, IncidentDNA
+from iic.models.impact import ImpactScore, Severity
+from iic.models.routing import ModelTier, RoutingDecision
+
+
+class IncidentModelRouter:
+    def __init__(self, lightweight_model: str, powerful_model: str):
+        self.lightweight_model = lightweight_model
+        self.powerful_model = powerful_model
+
+    def route(self, dna: IncidentDNA, impact: ImpactScore, cache_hit: bool = False) -> RoutingDecision:
+        if cache_hit:
+            return RoutingDecision(ModelTier.NONE, reason="Known pattern — cached resolution replayed (zero tokens).",
+                                   cache_hit=True)
+
+        # A derived dependency failure needs no LLM: the real cause is the upstream
+        # incident, which gets its own report.
+        if dna.failure_type == FailureType.DEPENDENCY:
+            return RoutingDecision(ModelTier.NONE,
+                                   reason="Derived from an upstream failure — diagnosed deterministically.")
+
+        # High stakes or low confidence → spend the powerful model.
+        if impact.severity in (Severity.HIGH, Severity.CRITICAL) or dna.confidence_signature == "low":
+            return RoutingDecision(ModelTier.POWERFUL, model=self.powerful_model,
+                                   reason=f"severity={impact.severity.value}, "
+                                          f"dna_confidence={dna.confidence_signature}")
+
+        # Confident, low-impact, well-understood pattern → cheap model is enough.
+        return RoutingDecision(ModelTier.LIGHTWEIGHT, model=self.lightweight_model,
+                               reason=f"severity={impact.severity.value}, "
+                                      f"dna_confidence={dna.confidence_signature}")

iic/runtime/__init__.py

@@ -0,0 +1,10 @@
+"""IIC runtime package.
+
+Intentionally EMPTY of eager imports: the self-arming `.pth` does
+``import iic.runtime.bootstrap``, which imports this package first. If this module
+eagerly imported the engine, every interpreter (incl. a serverless kernel boot)
+would pull the whole engine at startup — slow, and a kernel-restart risk. Import
+the engine lazily from :mod:`iic.runtime.incident_engine` where you need it.
+"""
+
+from __future__ import annotations

iic/runtime/_sql.py

@@ -0,0 +1,11 @@
+"""Tiny re-export so IIC runtime has one safe SQL-literal helper.
+
+Reuses the audited escaping from the shared library rather than re-implementing
+string interpolation (the original codebase's #1 injection foot-gun).
+"""
+
+from __future__ import annotations
+
+from healing_kit.utils.sql_safety import sql_literal as lit
+
+__all__ = ["lit"]

iic/runtime/agent_config.py

@@ -0,0 +1,48 @@
+"""Environment-driven config for the v4 Databricks-native agent.
+
+All knobs come from env vars so the same wheel behaves correctly whether it runs
+inside a job, a notebook, or the reconciler. Sensible free defaults: LLM off,
+Postgres optional.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _b(name: str, default: bool) -> bool:
+    return os.environ.get(name, str(default)).strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass
+class AgentConfig:
+    databricks_host: str = ""
+    databricks_token: str = ""           # usually the ambient cluster token
+    teams_webhook_url: str = ""
+    slack_webhook_url: str = ""
+    llm_enabled: bool = False
+    lightweight_model: str = "databricks-meta-llama-3-3-70b-instruct"
+    powerful_model: str = "databricks-claude-opus-4-8"
+    pg_dsn: str = ""                     # empty → no persistence/dedup (wrapper-only)
+    poll_interval_seconds: int = 90      # reconciler
+    lookback_hours: int = 24             # reconciler backfill window
+    max_jobs_scanned: int = 50
+    notify: bool = True
+
+    @classmethod
+    def from_env(cls) -> "AgentConfig":
+        return cls(
+            databricks_host=os.environ.get("DATABRICKS_HOST", "").rstrip("/"),
+            databricks_token=os.environ.get("DATABRICKS_TOKEN", ""),
+            teams_webhook_url=os.environ.get("TEAMS_WEBHOOK_URL", ""),
+            slack_webhook_url=os.environ.get("SLACK_WEBHOOK_URL", ""),
+            llm_enabled=_b("LLM_ENABLED", False),
+            lightweight_model=os.environ.get("LIGHTWEIGHT_MODEL", "databricks-meta-llama-3-3-70b-instruct"),
+            powerful_model=os.environ.get("POWERFUL_MODEL", "databricks-claude-opus-4-8"),
+            pg_dsn=os.environ.get("POSTGRES_DSN", ""),
+            poll_interval_seconds=int(os.environ.get("POLL_INTERVAL_SECONDS", "90")),
+            lookback_hours=int(os.environ.get("LOOKBACK_HOURS", "24")),
+            max_jobs_scanned=int(os.environ.get("MAX_JOBS_SCANNED", "50")),
+            notify=_b("IIC_NOTIFY", True),
+        )

iic/runtime/agent_runtime.py

@@ -0,0 +1,70 @@
+"""Shared analysis path for the v4 agent — used by both the wrapper and the reconciler.
+
+Given one or more already-known failure events, run the unchanged v2
+``IncidentEngine``, dedup by fingerprint, persist, and (the engine itself) notify.
+Keeping this in one place means the two detection sources produce identical
+incidents and can't diverge.
+"""
+
+from __future__ import annotations
+
+from iic.ingestion.static_source import StaticFailureSource
+from iic.models.event import NormalizedFailureEvent
+from iic.runtime.agent_config import AgentConfig
+from iic.runtime.store import fingerprint
+
+
+def analyze_events(events: list[NormalizedFailureEvent], *, run_info: dict, client,
+                   config: AgentConfig, store) -> list:
+    """Analyze fresh (non-duplicate) events; return the IncidentReports produced."""
+    # Dedup against what either source already processed.
+    fresh, fp_by_task = [], {}
+    for ev in events:
+        fp = fingerprint(ev.run_id, ev.task, ev.error_message)
+        if store.already_seen(fp):
+            continue
+        fresh.append(ev)
+        fp_by_task[ev.task] = fp
+    if not fresh:
+        return []
+
+    engine = _build_engine(fresh, run_info, client, config, store)
+    result = engine.run()
+
+    for report in result.reports:
+        fp = fp_by_task.get(report.task) or fingerprint(_run_id(run_info), report.task, "")
+        store.save_incident(
+            incident_id=report.incident_id, run_id=_run_id(run_info),
+            task_key=report.task, fingerprint=fp, pattern_id=report.dna.pattern_id,
+            failure_type=report.dna.failure_type.value, severity=report.impact.severity.value,
+            root_cause=report.diagnosis.root_cause, confidence=report.diagnosis.confidence,
+            produced_by=report.diagnosis.produced_by, report_json=report.to_dict())
+    return result.reports
+
+
+def _build_engine(events, run_info, client, config: AgentConfig, store):
+    from iic.change.change_detector import ChangeDetector
+    from iic.context.context_builder import ContextBuilder
+    from iic.dependency.dependency_analyzer import DependencyAnalyzer
+    from iic.diagnosis.diagnosis_engine import DiagnosisEngine
+    from iic.runtime.incident_engine import EngineConfig, IncidentEngine
+
+    job_id = events[0].job_id if events else ""
+    cfg = EngineConfig(job_id=job_id, host=config.databricks_host,
+                       lightweight_model=config.lightweight_model,
+                       powerful_model=config.powerful_model,
+                       teams_webhook=config.teams_webhook_url, notify=config.notify)
+    diag_client = client if config.llm_enabled else None
+    return IncidentEngine(
+        cfg,
+        source=StaticFailureSource(events, run_info=run_info),
+        context_builder=ContextBuilder(client=client),
+        dependency_analyzer=DependencyAnalyzer(client=client),
+        change_detector=ChangeDetector(client=client),
+        diagnosis_engine=DiagnosisEngine(client=diag_client),
+        pattern_store=store,
+    )
+
+
+def _run_id(run_info: dict) -> str:
+    return str((run_info or {}).get("run_id", ""))

iic/runtime/antibodies.py

@@ -0,0 +1,100 @@
+"""Antibody Ledger (runtime side) — per-tenant memory of failure patterns and the
+human-recorded resolutions that worked.
+
+The runtime is **read-only** on the shared ``antibodies.yaml`` (humans edit it in
+git via the GitHub web editor; the sync workflows copy it to/from the Volume). The
+only thing the runtime *writes* is a tiny per-occurrence marker file into
+``.iic_pending/`` — mirroring the proven ``.iic_seen/`` dedup-marker mechanism, so
+two concurrent processes never contend on a single shared file (one file per
+process per occurrence). The pull workflow folds those markers into the git ledger.
+
+HARD RULES (identical to the rest of the failure path):
+  * fail-open everywhere — any read/write error → behave exactly as today;
+  * never raise into the workload;
+  * lazy heavy imports (yaml) inside the functions that need them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+from iic.runtime.constants import ANTIBODIES_FILENAME, DEFAULT_CONFIG_PATH, PENDING_DIRNAME
+
+# Redaction patterns for the human-readable ``example`` sub-field. The ledger KEY
+# is the already-generic pattern_id; the example is only context for the human
+# writing a resolution, so it must never carry a credential or PII.
+_SECRET_RE = re.compile(r"(?i)(token|secret|password|passwd|pwd|api[_-]?key|key)\s*[=:]\s*\S+")
+_EMAIL_RE = re.compile(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")
+_URL_CRED_RE = re.compile(r"([A-Za-z][A-Za-z0-9+.\-]*://)[^\s:/@]+:[^\s:/@]+@")
+
+
+def sanitize_example(short_error: str) -> str:
+    """First line only, ≤120 chars, with obvious secrets / emails / URL creds redacted."""
+    try:
+        lines = (short_error or "").strip().splitlines()
+        text = lines[0] if lines else ""
+        text = _URL_CRED_RE.sub(r"\1***@", text)
+        text = _SECRET_RE.sub(r"\1=***", text)
+        text = _EMAIL_RE.sub("***", text)
+        return text[:120]
+    except Exception:
+        return ""
+
+
+def _base(base_dir: str) -> str:
+    return base_dir or os.path.dirname(DEFAULT_CONFIG_PATH)
+
+
+def load_ledger(base_dir: str) -> dict:
+    """Read ``{base_dir}/antibodies.yaml`` (the volume_path anchor). Absent/corrupt → {}."""
+    try:
+        path = os.path.join(_base(base_dir), ANTIBODIES_FILENAME)
+        if not os.path.exists(path):
+            return {}
+        import yaml
+        data = yaml.safe_load(open(path)) or {}
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def lookup(ledger: dict, pattern_id: str):
+    """Return ``(state, entry)`` with ``state`` ∈ {"resolved", "known_unresolved", "new"}."""
+    entry = ledger.get(pattern_id) if isinstance(ledger, dict) else None
+    if not isinstance(entry, dict):
+        return "new", None
+    resolution = str(entry.get("resolution", "") or "").strip()
+    return ("resolved" if resolution else "known_unresolved"), entry
+
+
+def record_occurrence(base_dir: str, pattern_id: str, example: str) -> None:
+    """Append ONE tiny per-occurrence marker into ``{base_dir}/.iic_pending/``.
+
+    Never touches the shared ledger; one file per process per occurrence makes this
+    race-free by construction. Whole body is fail-open — any error is a silent no-op.
+    """
+    try:
+        if not pattern_id:
+            return
+        import time
+        import uuid
+        pending = os.path.join(_base(base_dir), PENDING_DIRNAME)
+        os.makedirs(pending, exist_ok=True)
+        safe_pid = re.sub(r"[^A-Za-z0-9_.\-]", "_", str(pattern_id))[:80]
+        now = time.time()
+        fname = f"{safe_pid}__{int(now)}_{uuid.uuid4().hex[:8]}.json"
+        payload = {"pattern_id": str(pattern_id), "example": example or "", "ts": _iso(now)}
+        with open(os.path.join(pending, fname), "w") as f:
+            json.dump(payload, f)
+    except Exception:
+        pass
+
+
+def _iso(epoch: float) -> str:
+    try:
+        import datetime
+        return datetime.datetime.fromtimestamp(epoch, datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    except Exception:
+        return ""

iic/runtime/bootstrap.py

@@ -0,0 +1,157 @@
+"""Self-arming tripwire — imported by ``iic_autoload.pth`` at interpreter startup.
+
+"Airbag, not camera": at every Python startup this arms in-process failure hooks
+in microseconds, then does nothing. The engine runs ONLY at the moment an
+unhandled exception occurs. On a successful run it leaves zero trace.
+
+HARD RULES enforced here:
+  * stdlib-only imports at module load (os, sys, threading, builtins). The engine,
+    requests, yaml, etc. are imported lazily inside the failure handler.
+  * fail-open everywhere — a .pth import error would print noise at the start of
+    every process, so the whole module body is wrapped in try/except.
+  * never alter the user's failure — every hook runs our handler first (itself
+    fully guarded) then ALWAYS calls the previous hook, preserving the original
+    traceback/exit behavior.
+  * idempotent (``_ARMED``) and re-entrant.
+  * kill switch: ``IIC_DISABLE=1`` disarms entirely.
+"""
+
+try:  # the entire module must never raise at import (it runs in every process)
+    import os
+    import sys
+
+    _ARMED = False
+    _IPY_ARMED = False  # True once the IPython/notebook hook owns failure reporting
+
+    def _handle_failure(exc_type, exc, tb):
+        """Lazy, fully-guarded bridge to the in-process responder."""
+        try:
+            from iic.runtime.inprocess import process_local_failure
+            process_local_failure(exc_type, exc, tb)
+        except Exception:
+            pass  # monitoring must never break or slow the workload
+
+    # ── IPython / notebook arming (cells bypass sys.excepthook) ──
+
+    def _arm_ipython():
+        """Arm notebook-cell failure capture if a live IPython shell exists.
+
+        Databricks notebook cells do NOT route exceptions through
+        ``set_custom_exc`` (Databricks wraps cell execution itself), so the
+        reliable hook is the ``post_run_cell`` event, which fires after every cell
+        with ``result.error_in_exec`` set on failure. We register BOTH (custom_exc
+        for plain Jupyter, post_run_cell for Databricks); the per-process
+        fingerprint dedup ensures at most one incident if both fire. Returns True
+        if armed.
+        """
+        try:
+            import IPython
+            shell = IPython.get_ipython()
+            if shell is None:
+                return False
+            if getattr(shell, "_iic_armed", False):
+                return True
+
+            def _custom_exc(shell, etype, evalue, tb, tb_offset=None):
+                _handle_failure(etype, evalue, tb)
+                return shell.showtraceback((etype, evalue, tb), tb_offset=tb_offset)
+
+            def _post_run_cell(result):
+                try:
+                    err = getattr(result, "error_in_exec", None)
+                    if err is not None:
+                        _handle_failure(type(err), err, getattr(err, "__traceback__", None))
+                except Exception:
+                    pass
+
+            try:
+                shell.set_custom_exc((BaseException,), _custom_exc)
+            except Exception:
+                pass
+            try:
+                shell.events.register("post_run_cell", _post_run_cell)  # the Databricks-reliable hook
+            except Exception:
+                pass
+
+            shell._iic_armed = True
+            global _IPY_ARMED
+            _IPY_ARMED = True  # excepthook now defers to the notebook hook (avoid double cards)
+            return True
+        except Exception:
+            return False
+
+    def _install_ipython_watcher():
+        """Arm the notebook hook once the IPython shell exists.
+
+        IMPORTANT: do NOT wrap ``builtins.__import__`` — doing so fires on every
+        import during kernel boot and re-imports IPython re-entrantly, which can
+        deadlock the kernel startup (ERROR_RESTART_PYTHON). Instead, a tiny daemon
+        thread polls for the shell, arms it once, and exits. It never touches the
+        import machinery and never blocks the main (kernel) thread.
+        """
+        if _arm_ipython():
+            return  # shell already live → armed now
+        try:
+            import threading
+            import time
+
+            def _poll():
+                for _ in range(150):  # ~30s max, then give up (script-task path still covered)
+                    try:
+                        if _arm_ipython():
+                            return
+                    except Exception:
+                        pass
+                    time.sleep(0.2)
+
+            threading.Thread(target=_poll, name="iic-ipython-arm", daemon=True).start()
+        except Exception:
+            pass
+
+    # ── main arming ──
+
+    def activate():
+        global _ARMED
+        if _ARMED or os.environ.get("IIC_DISABLE") == "1":
+            return
+        # Never arm Spark executor processes; only the driver. On serverless the
+        # var is absent, which means proceed.
+        db_driver = os.environ.get("DB_IS_DRIVER")
+        if db_driver is not None and db_driver.upper() != "TRUE":
+            return
+        _ARMED = True
+
+        # sys.excepthook (script tasks / top-level) — run handler, then the previous hook.
+        _prev_excepthook = sys.excepthook
+
+        def _excepthook(exc_type, exc, tb):
+            # In a notebook/job a live IPython shell exists and post_run_cell is the
+            # single source of truth — the job wrapper ALSO hits sys.excepthook with
+            # a re-raised exception, which would double-report (and misclassify). So
+            # only report here when IPython is NOT armed (pure script / non-IPython).
+            if not _IPY_ARMED:
+                _handle_failure(exc_type, exc, tb)
+            return _prev_excepthook(exc_type, exc, tb)
+
+        sys.excepthook = _excepthook
+
+        # notebook cells
+        _install_ipython_watcher()
+
+        # worker-thread failures (best-effort; threading.excepthook is 3.8+)
+        try:
+            import threading
+            _prev_thread_hook = threading.excepthook
+
+            def _thread_hook(args):
+                _handle_failure(args.exc_type, args.exc_value, args.exc_traceback)
+                return _prev_thread_hook(args)
+
+            threading.excepthook = _thread_hook
+        except Exception:
+            pass
+
+    activate()
+
+except Exception:
+    pass