@allansantos-dev/smart-tool 0.9.39 → 0.9.41

package/hook_decision.py

@@ -12,9 +12,11 @@ chamada não dá para montar. Nenhuma decisão aqui é sobre periculosidade, só
 """
 import os
 
+import affected_tests
 import code_graph
 import code_impact
 import config
+import dependency_notice
 import doc_check
 import duplicates
 import edit_preview
@@ -182,7 +184,16 @@ def _impact_line(root, rel, name):
     counts = found["counts"]
     tests = ", ".join(f"{t['function']} ({t['path']})" for t in found["tests"])
     calls = f"; tests calling it: {tests}" if tests else ""
-    return f" {counts['callers']} caller(s){calls}; project_manage affected_tests lists every test to run after the edit."
+    return (f" {counts['callers']} caller(s){calls}{_run_command(root, found['tests'])}; project_manage affected_tests "
+            "lists every test to run after the edit.")
+
+
+def _run_command(root, tests):
+    """`; run them: <command>` for the test files of `tests`, one command per runner and folder, or "" when no runner
+    is known for them."""
+    commands = affected_tests._commands(root, sorted({t["path"] for t in tests})) if tests else []
+    runnable = [f"cd {c['cwd']} && {c['command']}" if c["cwd"] != "." else c["command"] for c in commands if c["command"]]
+    return f"; run them: {' ; '.join(runnable)}" if runnable else ""
 
 
 def _doc_lines(findings):
@@ -215,19 +226,37 @@ def _duplicate_lines(findings):
             + " If the copy is intentional (moving the function, a deliberate fork), go ahead.")
 
 
-def _edit_review(payload, doc_mode, duplicate_mode):
+def _edit_review(payload, doc_mode, duplicate_mode, dependency_mode):
     """Checks of an edit before it runs. Docstrings follow doc_mode, in code files of registered projects only (tests,
     docs and files outside a project are left out, as in the docs coverage): missing ones deny the edit in require mode and become a reminder in remind mode; a
     documented function whose signature changed always gets a reminder. Copies of indexed functions follow
-    duplicate_mode and only add context, never deny."""
+    duplicate_mode and only add context, never deny. An edit of a package.json, requirements*.txt or go.mod follows dependency_mode: advisories
+    of the added or changed dependencies are added as context, never a denial."""
     with code_graph.pending_scope():
-        return _edit_review_scoped(payload, doc_mode, duplicate_mode)
+        return _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode)
 
 
-def _edit_review_scoped(payload, doc_mode, duplicate_mode):
+def _dependency_part(before, after, ecosystem):
+    """The dependency notice of one manifest edit, or the "dependency check skipped" line when it cannot run.
+
+    Parameters: before (str or None) text before the edit; after (str) text after it; ecosystem (str) from
+    `dependency_notice.ecosystem_of`.
+    Returns: str, empty when there is nothing to say.
+    """
+    try:
+        return dependency_notice.notice(before, after, ecosystem)
+    except dependency_notice.DependencyCheckError as exc:
+        return f"{dependency_notice.PREFIX}dependency check skipped: {exc}"
+
+
+def _edit_review_scoped(payload, doc_mode, duplicate_mode, dependency_mode):
     """`_edit_review` inside one `code_graph.pending_scope`, so the pending-changes scan runs once per review."""
-    doc_findings, duplicate_findings, failures = [], [], []
+    doc_findings, duplicate_findings, failures, dependency_parts = [], [], [], []
     for path, before, after in edit_preview.preview(payload.get("tool_name"), payload.get("tool_input"), payload.get("cwd")):
+        ecosystem = dependency_notice.ecosystem_of(path)
+        if dependency_mode != "off" and ecosystem:
+            dependency_parts += [part for part in (_dependency_part(before, after, ecosystem),) if part]
+            continue
         if not doc_check.supported(path):
             continue
         root = _project_of(path)
@@ -242,7 +271,7 @@ def _edit_review_scoped(payload, doc_mode, duplicate_mode):
             except (ValueError, RuntimeError) as exc:
                 failures.append(f"Smart Tool duplicates check skipped: {exc}")
     parts = ([_doc_lines(doc_findings)] if doc_findings else []) + \
-        ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures
+        ([_duplicate_lines(duplicate_findings)] if duplicate_findings else []) + failures + dependency_parts
     if not parts:
         return {}
     message = " ".join(parts)
@@ -253,16 +282,17 @@ def _edit_review_scoped(payload, doc_mode, duplicate_mode):
 
 def decide(payload, client, web_route, jobs):
     """Hook output for one PreToolUse payload: edits follow doc_mode (require | remind | off) and duplicate_mode
-    (warn | off), the other tools follow hook_mode (redirect | advise | off). In redirect mode the Smart Tool call that
+    (warn | off) and dependency_mode (warn | off), the other tools follow hook_mode (redirect | advise | off). In redirect mode the Smart Tool call that
     replaces a redirected one starts in `jobs` under the call's tool_use_id (see `_redirect`); only a search whose
     query cannot be built, or a client that sends no tool_use_id, is denied with the exact call to make, and never in a
     subagent whose tool list has no Smart Tool MCP tool: it has nothing to switch to."""
     cfg = config.load_config()
     if isinstance(payload, dict) and payload.get("tool_name") in EDIT_TOOLS:
-        doc_mode, duplicate_mode = config.doc_mode(cfg), config.duplicate_mode(cfg)
-        if doc_mode == "off" and duplicate_mode == "off":
+        doc_mode, duplicate_mode, dependency_mode = (config.doc_mode(cfg), config.duplicate_mode(cfg),
+                                                     config.dependency_mode(cfg))
+        if doc_mode == "off" and duplicate_mode == "off" and dependency_mode == "off":
             return {}
-        return _edit_review(payload, doc_mode, duplicate_mode)
+        return _edit_review(payload, doc_mode, duplicate_mode, dependency_mode)
     if isinstance(payload, dict) and str(payload.get("tool_name")).startswith(f"mcp__{SMART_TOOL_SERVER}__"):
         if payload["tool_name"] == SMART_SEARCH_TOOL:
             router.CLIENT.set(client)

package/index_profile.py

@@ -11,7 +11,7 @@ PROFILE_VERSION = 2
 KINDS = ("code", "test", "doc")
 RETRY_AFTER_S = 3600
 MAX_DIRS = 90
-PROSE = {"md", "txt", "docx", "rst", "adoc"}
+PROSE = {"md", "txt", "docx", "pdf", "rst", "adoc"}
 # Data and markup inside a documentation, design or data-dump folder are reports and mockups, not code (GitHub Linguist
 # treats docs/ as documentation; a design/ HTML or a probe's JSON result pushed hook_decision.py out of the code block).
 DOC_DATA = {"html", "htm", "json", "csv", "xml", "yaml", "yml", "svg"}

package/index_scope.py

@@ -40,10 +40,13 @@ _PROJECT_TYPE_EXCLUDES = (
     (("Podfile",), ("Pods",)),
 )
 
+# Files a tool writes while it works and replaces or deletes right after (atomic-write temp, backup, editor swap).
+TRANSIENT_FILES = {"*.tmp", "*.bak", "*.swp", "*~"}
+
 # Mesmo critério do `_ALWAYS_EXCLUDE`, para arquivo: o significado não varia por
 # projeto. Lockfile é grafo de dependência resolvido por ferramenta — nunca é fonte de
 # resposta numa busca semântica, e é grande o bastante pra dominar o índice.
-_ALWAYS_EXCLUDE_FILES = {
+_ALWAYS_EXCLUDE_FILES = TRANSIENT_FILES | {
     "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "npm-shrinkwrap.json",
     "poetry.lock", "pdm.lock", "uv.lock", "Pipfile.lock", "Cargo.lock",
     "composer.lock", "go.sum", "Gemfile.lock", "packages.lock.json",
@@ -110,6 +113,11 @@ def normalize_include(include):
     return bases, dropped
 
 
+def is_transient(name):
+    """Whether a file name is a temporary, backup or editor-swap file (`*.tmp`, `*.bak`, `*.swp`, `*~`)."""
+    return any(fnmatch.fnmatch(name.casefold(), pattern) for pattern in TRANSIENT_FILES)
+
+
 def always_excluded(name):
     """Directory name in _ALWAYS_EXCLUDE, entries may be globs (e.g. *.egg-info)."""
     folded = name.casefold()

package/indexer.py

@@ -31,8 +31,10 @@ CHUNK_MAX_CHARS = 8000
 CHUNK_OVERLAP_LINES = 12
 CHUNKER_VERSION = 3
 SCHEMA_VERSION = 2
-REINDEX_BATCH_MAX_CHARS = 32_000
-REINDEX_BATCH_MAX_ITEMS = 32
+# An embeddings request holds up to 128 items and 120,000 characters (about 30,000 tokens): far under the 2048 items and
+# 300,000 tokens per request that OpenAI and Azure accept (docs/research/2026-10-27-excesso-de-chamadas-embed-rerank.md).
+REINDEX_BATCH_MAX_CHARS = 120_000
+REINDEX_BATCH_MAX_ITEMS = 128
 # Embedding requests in flight per flush. Measured 2026-10-03 (docs/spikes/embed_parallel_spike.py, 30 batches,
 # 3 interleaved rounds): 1 worker 33-50 s, 2 workers 19-27 s, 4 workers 11-20 s (~2.8x), no 429 from the gateway.
 EMBED_WORKERS = 4
@@ -129,7 +131,7 @@ def read_indexable(root, rel_path):
         size = os.path.getsize(full)
         if name.endswith(".svg") and size > MAX_SVG_INDEXABLE_BYTES:
             return None, SKIP_GRAPHIC
-        limit = document_text.MAX_ARCHIVE_BYTES if name.endswith('.docx') else MAX_INDEXABLE_BYTES
+        limit = document_text.size_limit(name) if document_text.is_extracted(name) else MAX_INDEXABLE_BYTES
         if size > limit:
             return None, SKIP_TOO_LARGE
         with open(full, "rb") as f:
@@ -138,9 +140,9 @@ def read_indexable(root, rel_path):
         return None, SKIP_UNREADABLE
     if len(data) > limit:
         return None, SKIP_TOO_LARGE
-    if name.endswith('.docx'):
+    if document_text.is_extracted(name):
         try:
-            data = document_text.extract_docx(data)
+            data = document_text.extract(name, data)
         except document_text.DocumentError as exc:
             return None, str(exc)
     prefix = data[:_SNIFF_BYTES]
@@ -507,7 +509,7 @@ def _stat_candidate(root, rel):
             return None, SKIP_UNREADABLE
     except OSError:
         return None, SKIP_UNREADABLE
-    if stat.st_size > (document_text.MAX_ARCHIVE_BYTES if name.endswith('.docx') else MAX_INDEXABLE_BYTES):
+    if stat.st_size > (document_text.size_limit(name) if document_text.is_extracted(name) else MAX_INDEXABLE_BYTES):
         return None, SKIP_TOO_LARGE
     if name.endswith(".svg") and stat.st_size > MAX_SVG_INDEXABLE_BYTES:
         return None, SKIP_GRAPHIC
@@ -523,7 +525,7 @@ def _stable_read(root, rel):
         if data is None:
             return None, encoding, before
         after, _ = _stat_candidate(root, rel)
-        if after == before and (str(rel).lower().endswith('.docx') or len(data) == before[1]):
+        if after == before and (document_text.is_extracted(rel) or len(data) == before[1]):
             return data, encoding, before
     return None, "file changed while reading", None
 
@@ -621,7 +623,7 @@ def _reindex(root, included_paths, embed_batch, chunk_lines=CHUNK_LINES, on_prog
                 continue
             observed[rel] = stat
             force_file = any(rel.casefold() == p or rel.casefold().startswith(p + "/") for p in forced)
-            extractor_changed = rel.lower().endswith('.docx') and meta.get('document_extractor_version') != document_text.VERSION
+            extractor_changed = document_text.is_extracted(rel) and meta.get('document_extractor_version') != document_text.VERSION
             if (full_check or building or force_file or extractor_changed or old_state.get(rel) != stat):
                 candidates.append(rel)
             else:

package/model_breaker.py

@@ -0,0 +1,70 @@
+"""Protection of the model gateway, per model id: a circuit that opens after consecutive 429/503 answers and a cap on
+the requests in flight.
+
+Pattern: a circuit breaker (closed, open for a pause, then one trial call decides). Retrying a gateway that answers
+busy only adds load (AWS Bedrock throughput guide: honor Retry-After, back off with jitter); once it keeps answering
+busy the caller stops asking for a while and serves what it can without the model.
+"""
+import contextlib
+import threading
+import time
+import urllib.error
+
+FAILURES_TO_OPEN = 3
+PAUSE_S = 30
+MAX_IN_FLIGHT = 6
+_BUSY_CODES = (429, 503)
+_lock = threading.Lock()
+_failures = {}
+_open_until = {}
+_slots = {}
+
+
+class CircuitOpen(RuntimeError):
+    """The model is paused after repeated busy answers; no request was sent."""
+
+
+def guard(model):
+    """Raises CircuitOpen while `model` is paused. Nothing happens for a call without a model id."""
+    if not model:
+        return
+    with _lock:
+        left = _open_until.get(model, 0) - time.monotonic()
+    if left > 0:
+        raise CircuitOpen(f"Model {model} is paused for {int(left) + 1} s after {FAILURES_TO_OPEN} consecutive "
+                          "HTTP 429/503 answers from the gateway; no request was sent.")
+
+
+def note(model, failure=None):
+    """Records the outcome of a request: a success closes the circuit, a 429/503 counts toward opening it, any other
+    failure changes nothing. After the pause the first failure opens it again."""
+    if not model:
+        return
+    busy = isinstance(failure, urllib.error.HTTPError) and failure.code in _BUSY_CODES
+    with _lock:
+        if failure is None:
+            _failures[model] = 0
+        elif busy:
+            _failures[model] = _failures.get(model, 0) + 1
+            if _failures[model] >= FAILURES_TO_OPEN:
+                _open_until[model] = time.monotonic() + PAUSE_S
+
+
+@contextlib.contextmanager
+def slot(model):
+    """Holds one of the `MAX_IN_FLIGHT` places of `model` for the duration of a request."""
+    if not model:
+        yield
+        return
+    with _lock:
+        semaphore = _slots.setdefault(model, threading.BoundedSemaphore(MAX_IN_FLIGHT))
+    with semaphore:
+        yield
+
+
+def reset():
+    """Forgets every circuit and cap (tests)."""
+    with _lock:
+        _failures.clear()
+        _open_until.clear()
+        _slots.clear()

package/model_client.py

@@ -9,6 +9,7 @@ import usage_meter
 
 import config
 import gateway
+import model_breaker
 import model_health
 
 OFFLINE = contextvars.ContextVar("model_offline", default=None)
@@ -26,18 +27,24 @@ def get_token():
 
 
 def fetch(path, token, method="GET", body=None, timeout=15):
+    """One gateway request; returns the parsed JSON. A call that names a model first passes that model's circuit and
+    request cap (model_breaker, CircuitOpen when paused), and every attempt is metered. HTTP errors propagate."""
     if OFFLINE.get():
         raise RuntimeError(OFFLINE.get())
-    started=time.monotonic();result=None;headers=None;failure=None
-    try:
-        result,headers=_fetch(path,token,method,body,timeout)
-        return result
-    except Exception as exc:
-        failure=exc
-        raise
-    finally:
-        usage_meter.record(path,body,result,headers,failure,time.monotonic()-started)
-        model_health.record(path,body,failure)
+    model=body.get("model") if isinstance(body,dict) else None
+    model_breaker.guard(model)
+    with model_breaker.slot(model):
+        started=time.monotonic();result=None;headers=None;failure=None
+        try:
+            result,headers=_fetch(path,token,method,body,timeout)
+            return result
+        except Exception as exc:
+            failure=exc
+            raise
+        finally:
+            model_breaker.note(model,failure)
+            usage_meter.record(path,body,result,headers,failure,time.monotonic()-started)
+            model_health.record(path,body,failure)
 
 
 def _fetch(path, _token, method="GET", body=None, timeout=15):

package/model_health.py

@@ -3,17 +3,19 @@ rerank). Never stores request content: the model, the role, the tool that was ru
 text and the time.
 
 Three consumers read it: the tool answer (a warning line when a call of that very tool failed), the setup screen
-(rate table and recent failures) and the tray (one toast per model per day when the rate passes the limit).
+(rate table, failures by type and calls per purpose) and the tray (one toast per model per day when the rate passes the limit).
 """
 import contextlib
 import contextvars
 import io
 import os
+import re
 import sqlite3
 import time
 
 import config
 import project_store
+import usage_meter
 
 WINDOW_S = 24 * 3600
 ALERT_MIN_CALLS = 5
@@ -23,10 +25,17 @@ MUTE_S = 7 * 24 * 3600
 KEEP_S = 7 * 24 * 3600
 KEEP_FAILURES = 500
 ERROR_CHARS = 300
+SAMPLE_CHARS = 160
+GROUP_ROWS = 20
+PURPOSES = ("index_embedding", "query_embedding", "rerank", "embedding_probe", "scope")
 _PATHS = ("/v1/chat/completions", "/v1/embeddings", "/v1/rerank")
 _TOOL = contextvars.ContextVar("model_health_tool", default=None)
 _COLLECTED = contextvars.ContextVar("model_health_collected", default=None)
 _SCHEMA = set()
+_STATUS = re.compile(r"HTTP(?: Error)? (\d{3})")
+_TIMEOUT = re.compile(r"timed out|timeout|WinError 10060|Errno 110\b", re.I)
+_CONNECTION = re.compile(r"URLError|ConnectionError|ConnectionRefused|ConnectionReset|refused|reset|getaddrinfo|"
+                         r"WinError 1006[01]|WinError 10054|Name or service|unreachable", re.I)
 
 
 @contextlib.contextmanager
@@ -56,6 +65,22 @@ def _tables(db):
     _SCHEMA.add(project_store.DB_PATH)
 
 
+def classify(error):
+    """Failure type of a stored error text: '429', '503', '5xx' (any other 5xx), 'auth' (401/403), 'timeout',
+    'connection' or 'other'. An HTTP status in the text wins over words in the response body."""
+    status = _STATUS.search(error or "")
+    if status:
+        code = int(status.group(1))
+        if code in (429, 503):
+            return str(code)
+        if code in (401, 403):
+            return "auth"
+        return "5xx" if code >= 500 else "other"
+    if _TIMEOUT.search(error or ""):
+        return "timeout"
+    return "connection" if _CONNECTION.search(error or "") else "other"
+
+
 def role_of(model, cfg=None):
     """Name of the config field that selects `model` ('other' when none does)."""
     cfg = cfg if cfg is not None else config.load_config()
@@ -111,8 +136,24 @@ def warning_text(failures, setup_url):
             f"{first['error']}. Pick another model: {setup_url}/setup#models")
 
 
+def _groups(rows):
+    """Failure rows (latest first) as one entry per (type, role): count, first and last time, the latest message cut to
+    SAMPLE_CHARS and the latest GROUP_ROWS raw rows. Largest group first."""
+    groups = {}
+    for row in rows:
+        group = groups.setdefault((classify(row["error"]), row["role"]), {
+            "type": classify(row["error"]), "role": row["role"], "count": 0, "first_at": row["at"], "last_at": row["at"],
+            "sample": row["error"][:SAMPLE_CHARS], "rows": []})
+        group["count"] += 1
+        group["first_at"] = row["at"]
+        if len(group["rows"]) < GROUP_ROWS:
+            group["rows"].append(row)
+    return sorted(groups.values(), key=lambda group: (-group["count"], -group["last_at"]))
+
+
 def summary(now=None):
-    """Per model and role over the last 24 h, plus the 20 latest failures."""
+    """Per model and role over the last 24 h, every kept failure of the window grouped by type and role, and the calls
+    per purpose of the usage meter (its days are UTC, so that part covers the window's days, not its exact hours)."""
     now = now or time.time()
     with project_store._LOCK, _db() as db:
         _tables(db)
@@ -121,7 +162,7 @@ def summary(now=None):
             "SELECT model,role,SUM(calls) AS calls,SUM(errors) AS errors FROM model_calls WHERE hour>=? "
             "GROUP BY model,role ORDER BY SUM(errors) DESC,SUM(calls) DESC", (int((now - WINDOW_S) // 3600),))]
         failures = [dict(row) for row in db.execute(
-            "SELECT at,model,role,tool,path,error FROM model_failures WHERE at>=? ORDER BY at DESC LIMIT 20", (now - WINDOW_S,))]
+            "SELECT at,model,role,tool,path,error FROM model_failures WHERE at>=? ORDER BY at DESC", (now - WINDOW_S,))]
         for row in models:
             last = db.execute("SELECT error FROM model_failures WHERE model=? AND role=? ORDER BY at DESC LIMIT 1",
                               (row["model"], row["role"])).fetchone()
@@ -129,7 +170,8 @@ def summary(now=None):
     for row in models:
         row["rate"] = round(row["errors"] / row["calls"], 3) if row["calls"] else 0.0
         row["failing"] = row["calls"] >= ALERT_MIN_CALLS and row["rate"] >= ALERT_RATE
-    return {"window_hours": WINDOW_S // 3600, "models": models, "failures": failures}
+    return {"window_hours": WINDOW_S // 3600, "models": models, "groups": _groups(failures),
+            "calls_by_purpose": usage_meter.calls_by_purpose(now - WINDOW_S, PURPOSES)}
 
 
 def alerts_due(now=None):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allansantos-dev/smart-tool",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "description": "Local MCP server that gives coding agents (Claude Code, Codex) cheaper, sharper tools than their built-in search. Windows.",
   "license": "Apache-2.0",
   "author": "Allan Santos",

package/project_monitor.py

@@ -20,6 +20,8 @@ IDLE_TICK_S = 5
 # A folder that changes all the time (a tool's state folder) is indexed at most this often by the monitor; the changes
 # keep accumulating and one job covers them, and a search meanwhile reads the stale files straight from disk.
 MIN_JOB_GAP_S = 60
+# While the changes do not stop, each job lengthens the wait for the next one; a wait that passes unused resets it.
+JOB_GAP_STEPS_S = (MIN_JOB_GAP_S, 120, 240, 480, 900)
 FULL_CHECK_S = 86400
 MAX_EVENT_PATHS = 1000
 
@@ -27,7 +29,8 @@ MAX_EVENT_PATHS = 1000
 def relevant_path(path):
     parts = path.replace("\\", "/").strip("/").split("/")
     return bool(parts and all(part not in ("", ".", "..") and not part.startswith(".")
-                              and not index_scope.always_excluded(part) for part in parts))
+                              and not index_scope.always_excluded(part) for part in parts)
+                and not index_scope.is_transient(parts[-1]))
 
 
 def snapshot(root, scope):
@@ -58,6 +61,7 @@ class ProjectMonitor:
         self._git_checked = {}
         self._pending = {}
         self._next_job = {}
+        self._gap_level = {}
         self._filters = {}
         self._views = {}
         self._lock = threading.RLock()
@@ -155,6 +159,17 @@ class ProjectMonitor:
             project_store.update(key, watch_backend="windows_events", watch_error="")
             watcher.start()
 
+    def _job_gap(self, key, now):
+        """Wait before the next job of a project, called when a job is enqueued at `now`: one step longer than the last
+        one when the previous wait was used up at once (at most twice its length went by), the first step otherwise."""
+        level, at = self._gap_level.get(key, (0, None))
+        if at is None or now - at >= 2 * JOB_GAP_STEPS_S[level]:
+            level = 0
+        else:
+            level = min(level + 1, len(JOB_GAP_STEPS_S) - 1)
+        self._gap_level[key] = (level, now)
+        return JOB_GAP_STEPS_S[level]
+
     def tick(self):
         now = time.monotonic()
         projects = project_store.all_projects()
@@ -223,7 +238,7 @@ class ProjectMonitor:
             except Exception as exc:
                 project_store.update(key, status="error", last_error=str(exc)[:300], next_retry_at=time.time() + 60)
                 continue
-            self._next_job[key] = now + MIN_JOB_GAP_S
+            self._next_job[key] = now + self._job_gap(key, now)
             with self._lock:
                 # Um evento recebido durante o submit continua pendente para a próxima geração.
                 if self._pending.get(key) is pending and pending.get("revision", 0) == revision:

package/scout.py

@@ -12,6 +12,7 @@ Market pattern copied (docs/research/2026-10-24-scout-modelo-leve-no-smart-tool.
 excerpts, never an agent prompt, so no agent context is reopened per call.
 """
 import os
+import re
 
 import document_text
 import index_scope
@@ -35,6 +36,8 @@ PLAN_MAX_FOLDERS = 6
 OUTLINE_MAX_DIRS = 300
 OUTLINE_MAX_ROOT_FILES = 200
 _FIELDS = {"project_root", "question", "terms", "max_files"}
+DECISION_NOTES_MAX = 3
+_INTENT = re.compile(r"\b(why|por\s*qu[êe]|rationale|reason|motivo|raz[ãa]o|decid\w*|decis[ãa]o)\b", re.IGNORECASE)
 
 PLAN_SYSTEM = (
     "You plan a keyword scan of a code project that has no search index yet. Given a question and the project's "
@@ -91,9 +94,15 @@ def arguments(raw):
     return {"project_root": root, "question": question.strip(), "terms": (terms or "").strip(), "max_files": max_files}
 
 
+def is_intent_question(question):
+    """The question asks why something is as it is (why, reason, rationale, decided; por que, motivo, decisão): the
+    answer may sit in the notes the project keeps about its own intent, not in the code."""
+    return bool(_INTENT.search(question or ""))
+
+
 def disk_lines(root, path, start, end):
     """`[(line_number, text)]` of lines `start..end` of the file as it is on disk now, or None when the file cannot be
-    read by the index rules (secret, dotfile, too large, binary, gone) or holds no line text (docx)."""
+    read by the index rules (secret, dotfile, too large, binary, gone) or holds no line text (docx, pdf)."""
     if document_text.location_kind(path) != "source_line":
         return None
     data, encoding = indexer.read_indexable(root, path)
@@ -250,12 +259,13 @@ def valid_answer(raw, items):
     return raw["found"], answer, citations
 
 
-def render(question, source, items, citations=None, answer=None, found=None, model_note="", warnings=(), others=()):
+def render(question, source, items, citations=None, answer=None, found=None, model_note="", warnings=(), others=(),
+           notes=()):
     """The text returned to the agent. Lexical mode (`citations` None): every evidence window, within
     LITERAL_BUDGET_CHARS, after the model's answer when there is one (a model that cited nothing never leaves the
     answer without lines). Model mode: the model's answer, then only the cited ranges (sliced from the windows read
     from disk), and the uncited excerpts as `path:lines` pointers. `others` are candidates not shown, listed as
-    pointers."""
+    pointers. `notes` are the dossier hits for a question about intent: ids with one excerpt each, after the evidence."""
     out = [f"question: {question}", f"source: {source}", f"model: {model_note or 'none (literal lines only)'}"]
     if answer is not None:
         out.append(("answer: " if found else "answer (not found in the excerpts): ") + answer)
@@ -280,6 +290,9 @@ def render(question, source, items, citations=None, answer=None, found=None, mod
                 and citations is not None] + list(others)
     if pointers:
         out.append("other candidates (not shown): " + ", ".join(pointers))
+    if notes:
+        out.append("decision notes (project notes, not code):")
+        out += [f"- [{note['id']}] {note['source']}: {note['title']}: {note['snippet']}" for note in notes]
     for warning in warnings:
         out.append(f"warning: {warning}")
     return "\n".join(out) + "\n"

package/setup_audit.py

@@ -865,13 +865,55 @@ def _save_locked(report):
     atomic_io.write_secret_text(last_path, json.dumps(report, indent=1, ensure_ascii=False))
     changes = report.get("changes") or {}
     data = index()
-    data[index_key(report["project"])] = {"summary": report["summary"], "new": len(changes.get("new", [])),
-                                          "resolved": len(changes.get("resolved", [])),
-                                          "checked_at": report["checked_at"], "trigger": report["trigger"],
-                                          "snapshot_key": report["snapshot_key"]}
+    key = index_key(report["project"])
+    entry = {"project": report["project"], "summary": report["summary"], "new": len(changes.get("new", [])),
+             "resolved": len(changes.get("resolved", [])), "checked_at": report["checked_at"],
+             "trigger": report["trigger"], "snapshot_key": report["snapshot_key"],
+             "pending": _pending_notice(data.get(key), report)}
+    data[key] = entry
     _write_index(data)
 
 
+def _pending_notice(previous, report):
+    """The new errors and warnings of a scheduled run not yet told to the user, added to those a former run left
+    unannounced (by finding id). A manual run adds none: the user is looking at its result."""
+    pending = list((previous or {}).get("pending") or [])
+    if report["trigger"] == "schedule":
+        known = {item["id"] for item in pending}
+        pending += [{"id": f["id"], "severity": f["severity"], "check": f["check"], "subject": f["subject"]}
+                    for f in report["findings"]
+                    if f.get("new") and f["severity"] in ("error", "warn") and f["id"] not in known]
+    return pending
+
+
+def notices_due():
+    """[{project, errors, warnings, items}] for the projects whose scheduled audits found new errors or warnings since
+    the last call; marks them announced, so each finding is told once (the tray toast)."""
+    with _INDEX_LOCK:
+        data = index()
+        due = []
+        for entry in data.values():
+            pending = entry.get("pending") or []
+            if pending:
+                due.append({"project": entry["project"], "errors": sum(i["severity"] == "error" for i in pending),
+                            "warnings": sum(i["severity"] == "warn" for i in pending), "items": pending})
+                entry["pending"] = []
+        if due:
+            _write_index(data)
+    return due
+
+
+def toast_text(row):
+    """(title, lines) of the toast for one `notices_due` row."""
+    total = row["errors"] + row["warnings"]
+    title = f"Setup audit: {total} new problem{'s' if total != 1 else ''} in the agent configuration"
+    lines = [os.path.basename(row["project"].rstrip("\\/")) or row["project"]]
+    lines += [f"{item['severity']}: {item['check']} - {item['subject']}"[:120] for item in row["items"][:3]]
+    if len(row["items"]) > 3:
+        lines.append(f"and {len(row['items']) - 3} more")
+    return title, lines
+
+
 class Scheduler:
     """Periodic mode: audits every registered project whose folder exists, FIRST_RUN_DELAY_S after start and then
     every SCHEDULE_S, one project at a time, reusing MCP probes younger than PROBE_MAX_AGE_S. projects() returns the