localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/agent/hollow_module.py

@@ -0,0 +1,230 @@
+"""Detect a module that was created, imported, and then left empty.
+
+The failure this exists for: a build run that wrote ten real files and one
+`src/lib/fsrs.ts` containing exactly `// placeholder`, imported it from the page
+that needed it, and finished. The scheduling core — the entire point of the app
+— was never written, and the README advertised it as a feature.
+
+The signal is deliberately narrow: a file whose whole body is comments AND that
+something else imports. Either half alone is noisy. An empty file nobody
+references is usually intentional (a package marker, a barrel not wired up yet);
+a file with real content is fine however sparse. The conjunction — "you created
+this module, you import it, and there is nothing in it" — is a defect
+essentially every time, which is what makes it safe to block a turn on.
+
+Kept out of `loop.py` for the same reason `project_check_gate` is: the loop has
+no test seam and this needs one.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+__all__ = ["HollowModuleGate", "hollow_imported_modules", "is_hollow_source"]
+
+# Families whose "no executable content" question is well defined. Interpreted
+# config/markup (JSON, YAML, Markdown, CSS) is excluded: an empty one is data,
+# not a missing implementation.
+_C_FAMILY = {".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".go", ".rs",
+             ".java", ".swift", ".c", ".h", ".cpp", ".hpp", ".cs", ".kt"}
+_HASH_FAMILY = {".py", ".rb", ".sh", ".bash"}
+_CODE_EXTS = _C_FAMILY | _HASH_FAMILY
+
+# Files that are legitimately empty by convention — never a missing module.
+_EXEMPT_NAMES = {"__init__.py", "conftest.py", "setup.py", "py.typed"}
+_EXEMPT_DIR_PARTS = {"tests", "test", "__tests__", "migrations", "fixtures",
+                     "node_modules", ".git", "dist", "build", "vendor"}
+
+_MAX_BYTES = 64_000   # a file this size is not a stub; don't read further
+
+
+def _strip_c_comments(text: str) -> str:
+    """Remove `//` and `/* */`, preserving string literals so a `"//"` inside a
+    string still counts as content."""
+    out: list[str] = []
+    i, n = 0, len(text)
+    quote = ""
+    while i < n:
+        c = text[i]
+        if quote:
+            out.append(c)
+            if c == "\\" and i + 1 < n:
+                out.append(text[i + 1])
+                i += 2
+                continue
+            if c == quote:
+                quote = ""
+            i += 1
+            continue
+        if c in "\"'`":
+            quote = c
+            out.append(c)
+            i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "/":
+            while i < n and text[i] != "\n":
+                i += 1
+            continue
+        if c == "/" and i + 1 < n and text[i + 1] == "*":
+            i += 2
+            while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                i += 1
+            i += 2
+            continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def _strip_hash_comments(text: str) -> str:
+    out = []
+    for line in text.splitlines():
+        quote = ""
+        cut = len(line)
+        for idx, ch in enumerate(line):
+            if quote:
+                if ch == quote and line[idx - 1: idx] != "\\":
+                    quote = ""
+            elif ch in "\"'":
+                quote = ch
+            elif ch == "#":
+                cut = idx
+                break
+        out.append(line[:cut])
+    return "\n".join(out)
+
+
+def is_hollow_source(path: str) -> bool:
+    """True when `path` is a code file with no executable content at all.
+
+    Comments and whitespace are stripped; anything left — including a bare
+    docstring, which is at least an intentional statement — counts as content.
+    A file that cannot be read is NOT reported: this must never invent a defect.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext not in _CODE_EXTS:
+        return False
+    if path.endswith(".d.ts"):
+        return False
+    if os.path.basename(path) in _EXEMPT_NAMES:
+        return False
+    parts = {p.lower() for p in path.replace("\\", "/").split("/")}
+    if parts & _EXEMPT_DIR_PARTS:
+        return False
+    try:
+        if os.path.getsize(path) > _MAX_BYTES:
+            return False
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except Exception:
+        return False
+    stripped = (_strip_hash_comments(text) if ext in _HASH_FAMILY
+                else _strip_c_comments(text))
+    return not stripped.strip()
+
+
+def _import_patterns(stem: str) -> list[re.Pattern[str]]:
+    """Ways another file could name this module. Matching on the STEM keeps this
+    language-agnostic; the surrounding syntax keeps it from matching prose."""
+    s = re.escape(stem)
+    return [
+        # from './lib/fsrs' | from "../fsrs.js" | require('./fsrs')
+        re.compile(rf"""(?:from|require\s*\()\s*['"][^'"]*\b{s}(?:\.[a-z]+)?['"]"""),
+        # import './fsrs'
+        re.compile(rf"""import\s+['"][^'"]*\b{s}(?:\.[a-z]+)?['"]"""),
+        # python: import fsrs | from fsrs import x | from .lib.fsrs import x
+        re.compile(rf"^\s*(?:from\s+[.\w]*\b{s}\b|import\s+(?:[.\w]+\s*,\s*)*{s}\b)",
+                   re.MULTILINE),
+    ]
+
+
+def hollow_imported_modules(repo_root: str, changed_files) -> list[str]:
+    """Repo-relative paths of modules changed this turn that are empty AND
+    imported from somewhere else in the project.
+
+    `changed_files` is whatever the loop tracks for the turn — an iterable of
+    paths, absolute or repo-relative. Anything unreadable is skipped silently.
+    """
+    root = os.path.abspath(repo_root)
+    hollow: list[tuple[str, str]] = []   # (abs_path, stem)
+    for raw in changed_files or []:
+        p = str(raw)
+        absolute = p if os.path.isabs(p) else os.path.join(root, p)
+        if not os.path.isfile(absolute):
+            continue
+        rel = os.path.relpath(absolute, root)
+        if rel.startswith(".."):
+            continue
+        if is_hollow_source(absolute):
+            hollow.append((absolute, os.path.splitext(os.path.basename(absolute))[0]))
+    if not hollow:
+        return []
+
+    # Scan the project once for importers, skipping the hollow files themselves
+    # (a module importing its own name proves nothing).
+    hollow_abs = {a for a, _ in hollow}
+    patterns = {stem: _import_patterns(stem) for _, stem in hollow}
+    imported: set[str] = set()
+    for base, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in _EXEMPT_DIR_PARTS and not d.startswith(".")]
+        for name in files:
+            if os.path.splitext(name)[1].lower() not in _CODE_EXTS:
+                continue
+            fpath = os.path.join(base, name)
+            if fpath in hollow_abs:
+                continue
+            try:
+                if os.path.getsize(fpath) > _MAX_BYTES * 8:
+                    continue
+                with open(fpath, encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+            except Exception:
+                continue
+            for stem, pats in patterns.items():
+                if stem in imported:
+                    continue
+                if any(pat.search(text) for pat in pats):
+                    imported.add(stem)
+        if len(imported) == len(patterns):
+            break
+    return sorted(
+        os.path.relpath(a, root) for a, stem in hollow if stem in imported
+    )
+
+
+class HollowModuleGate:
+    """Turn-level state: are there still imported-but-empty modules?
+
+    Mirrors `ProjectCheckGate`. The nudge is bounded so a model that cannot
+    implement the module doesn't spin, but running out of nudges does NOT make
+    the app whole — `blocks_completion` keeps holding, and the reason rides the
+    final result text so it reaches both the TUI and `--json`.
+    """
+
+    def __init__(self, max_retries: int = 2) -> None:
+        self.max_retries = max_retries
+        self.paths: list[str] = []
+        self.retries = 0
+
+    def mark(self, paths) -> None:
+        self.paths = sorted(set(paths))
+
+    def clear(self) -> None:
+        """A later round found nothing hollow — the modules were implemented."""
+        self.paths = []
+
+    def consume_retry(self) -> bool:
+        if self.retries >= self.max_retries:
+            return False
+        self.retries += 1
+        return True
+
+    def blocks_completion(self) -> bool:
+        return bool(self.paths)
+
+    def result_note(self) -> str:
+        if not self.paths:
+            return ""
+        listed = "\n".join(f"  - {p}" for p in self.paths)
+        return ("\n\nThese modules are imported but contain no code — the feature "
+                f"they implement does not exist:\n{listed}")

localcode/agent/hooks.py

@@ -0,0 +1,414 @@
+"""Lifecycle hooks for LocalCode's agent loop.
+
+The loop is responsible for sequencing; policy lives in small hook
+functions here that can be tested and replaced independently.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import re
+from typing import Any
+from ..evidence import EvidenceRegistry
+__all__ = [
+    "TurnState",
+    "EvidenceLedger",
+    "QualityVerdict",
+    "before_turn",
+    "before_model",
+    "after_tool",
+    "quality_monitor",
+    "completion_gate",
+    "ran_build_or_test",
+    "_changed_code_files",
+    "CompletionEvidence",
+    "deterministic_completion",
+]
+
+
+@dataclass
+class TurnState:
+    user_text: str
+    goal_state: Any
+    task_state: Any = None
+    changed_files: list[str] = field(default_factory=list)
+    bash_history: list[tuple[str, str]] = field(default_factory=list)
+    tools_called: list[str] = field(default_factory=list)
+    evidence: "EvidenceLedger" = field(default_factory=lambda: EvidenceLedger())
+    verification_registry: EvidenceRegistry = field(default_factory=EvidenceRegistry)
+
+
+@dataclass
+class EvidenceLedger:
+    """Structured proof gathered during a turn.
+
+    The model may narrate intent, but completion depends on this ledger:
+    explicit tool facts, runtime probes, and observed errors.
+    """
+    verified_urls: list[str] = field(default_factory=list)
+    changed_paths: list[str] = field(default_factory=list)
+    unresolved: list[str] = field(default_factory=list)
+    runtime_errors: list[str] = field(default_factory=list)
+    empty_probe_count: int = 0
+    zero_data_count: int = 0
+
+    def add_tool_result(self, tool_name: str, args: dict[str, Any], result: str, facts: dict[str, Any]) -> None:
+        text = str(result or "").strip()
+        lower = text.lower()
+        compact = re.sub(r"\s+", "", text)
+        command = str(args.get("command", "") or "")
+        path = facts.get("path")
+        if isinstance(path, str) and path and facts.get("changed"):
+            self._add_unique(self.changed_paths, path)
+        url = facts.get("url")
+        if facts.get("verification_signal") and isinstance(url, str) and url:
+            self._add_unique(self.verified_urls, url)
+        if "traceback " in lower or "exception" in lower or facts.get("error_type") in {"syntax_error", "verification_failed"}:
+            self._add_unique(self.runtime_errors, lower[:200])
+            self._add_unique(self.unresolved, "runtime-error")
+        if (("curl" in command.lower() or "/api/" in command.lower()) and compact in {"[]", "{}", "null", "\"\"", ""}):
+            self.empty_probe_count += 1
+            self._add_unique(self.unresolved, "empty-api-response")
+        if re.search(r"\b(loaded|found|returned|has)\s+0\b", lower) or re.search(r"\b0\s+(items|records|rows|entries|levels|results)\b", lower):
+            self.zero_data_count += 1
+            self._add_unique(self.unresolved, "zero-runtime-data")
+
+    def blockers(self) -> list[str]:
+        return list(dict.fromkeys(self.unresolved))
+
+    @staticmethod
+    def _add_unique(items: list[str], value: str) -> None:
+        if value and value not in items:
+            items.append(value)
+
+
+@dataclass
+class QualityVerdict:
+    ok: bool
+    reason: str = ""
+    correction: str = ""
+
+
+@dataclass(frozen=True)
+class CompletionEvidence:
+    criterion: str
+    evidence: tuple[str, ...] = ()
+    satisfied: bool = False
+
+
+def deterministic_completion(criteria: list[CompletionEvidence]) -> QualityVerdict:
+    if not criteria:
+        return QualityVerdict(False, "no-success-criteria", "Define verifiable outcomes first.")
+    missing = [item.criterion for item in criteria if not item.satisfied or not item.evidence]
+    if missing:
+        return QualityVerdict(False, "missing-completion-evidence", "Gather evidence for: " + "; ".join(missing[:5]))
+    return QualityVerdict(True, "success-criteria-satisfied", "Stop: further polish is out of scope.")
+
+
+def before_turn(state: TurnState) -> None:
+    """Reserved hook for per-turn initialization."""
+    return None
+
+
+def before_model(messages: list[dict[str, Any]], state: TurnState) -> list[dict[str, Any]]:
+    """Transform messages before each model call."""
+    return messages
+
+
+def after_tool(tool_name: str, args: dict, result: str, state: TurnState) -> str:
+    """Post-process a tool result before it is fed back to the model."""
+    return result
+
+
+def quality_monitor(content: str, state: TurnState) -> QualityVerdict:
+    """Detect generic bad completions and return a correction if needed."""
+    lower = (content or "").lower()
+    if not content.strip():
+        return QualityVerdict(ok=True)
+    if (
+        not state.changed_files
+        and state.goal_state.goal_type in {"build_app", "edit_existing", "general_task"}
+        and any(phrase in lower for phrase in ("would you like me to", "should i ", "i can implement"))
+        and not getattr(state.goal_state, "allows_blocking_question", True)
+    ):
+        return QualityVerdict(
+            ok=False,
+            reason="permission-question-without-action",
+            correction=(
+                "SYSTEM: The previous response asked for permission instead of "
+                "making the requested local code change. Continue with tools now. "
+                "Ask only if a real missing decision blocks implementation."
+            ),
+        )
+    if "http://localhost:[" in lower or "127.0.0.1:[" in lower:
+        return QualityVerdict(
+            ok=False,
+            reason="fake-placeholder-url",
+            correction=(
+                "SYSTEM: The previous response contained a placeholder URL. "
+                "Use tools to determine the real port/URL, then report the exact value."
+            ),
+        )
+    unsupported = _unsupported_final_claims(content, state)
+    if unsupported:
+        return QualityVerdict(
+            ok=False,
+            reason="unsupported-final-claims",
+            correction=(
+                "SYSTEM: The previous completion summary claimed features that are "
+                f"not evidenced in changed files: {', '.join(unsupported)}. "
+                "Either implement and verify those features now, or remove the "
+                "unsupported claims from the final summary. Do not overstate what was built."
+            ),
+        )
+    return QualityVerdict(ok=True)
+
+
+def completion_gate(
+    *,
+    repo_root: Path | str,
+    state: TurnState,
+    build_stage: str,
+    has_runtime_verification: bool,
+    partial_handoff: bool,
+    blocking_question: bool,
+) -> str | None:
+    """Return a generic completion-block reason, or None if completion is valid."""
+    if state.goal_state.goal_type == "edit_existing" and not blocking_question:
+        if not state.changed_files:
+            return "no-edit-applied"
+        if _changed_code_files(state.changed_files) and not has_runtime_verification:
+            return "unverified-edit"
+    if state.goal_state.goal_type == "build_app" and state.changed_files and not blocking_question:
+        if build_stage != "verified":
+            return f"stage-{build_stage}"
+        if partial_handoff:
+            return "partial-handoff"
+        if not has_runtime_verification:
+            return "unverified-app-build"
+        unresolved = state.evidence.blockers() or _recent_unresolved_verification_signals(state)
+        if unresolved:
+            return f"unresolved-verification:{', '.join(unresolved[:3])}"
+        missing_features = _requested_feature_gaps(state)
+        if missing_features:
+            return f"missing-requested-features:{', '.join(missing_features[:3])}"
+        score, deductions = _completion_score(
+            state=state,
+            has_runtime_verification=has_runtime_verification,
+            missing_features=missing_features,
+        )
+        if score < 4:
+            return f"low-completion-score:{score}:{', '.join(deductions[:3])}"
+    if (
+        not state.changed_files
+        and partial_handoff
+        and not getattr(state.goal_state, "allows_blocking_question", True)
+    ):
+        return "action-required-followup"
+    return None
+
+
+def _completion_score(
+    *,
+    state: TurnState,
+    has_runtime_verification: bool,
+    missing_features: list[str],
+) -> tuple[int, list[str]]:
+    score = 0
+    deductions: list[str] = []
+    if state.changed_files:
+        score += 2
+    else:
+        deductions.append("no_changed_files")
+    if has_runtime_verification:
+        score += 2
+    else:
+        deductions.append("no_runtime_verification")
+    if not missing_features:
+        score += 1
+    else:
+        deductions.append("missing_requested_features")
+    recent_errors = [
+        result for _, result in state.bash_history[-3:]
+        if str(result).startswith("[exit code ") or "Traceback " in str(result)
+    ]
+    recent_errors.extend(state.evidence.runtime_errors[-2:])
+    if recent_errors:
+        score -= 1
+        deductions.append("recent_unresolved_errors")
+    recent_tools = state.tools_called[-8:]
+    if len(recent_tools) >= 6 and len(set(recent_tools)) <= 2:
+        score -= 1
+        deductions.append("repeated_tool_churn")
+    return score, deductions
+
+
+def _recent_unresolved_verification_signals(state: TurnState) -> list[str]:
+    """Detect recent verification probes that prove a build is not actually ready.
+
+    This stays generic: it does not know about a specific app domain. It only
+    treats explicit runtime/probe evidence such as empty API responses, zero
+    loaded records, or tracebacks as blockers for creation-task completion.
+    """
+    if state.goal_state.goal_type != "build_app":
+        return []
+    unresolved: list[str] = []
+    for command, result in state.bash_history[-10:]:
+        cmd = str(command).lower()
+        text = str(result).strip()
+        lower = text.lower()
+        compact = re.sub(r"\s+", "", text)
+        if "traceback " in lower or "exception" in lower:
+            unresolved.append("runtime-error")
+            continue
+        if ("curl" in cmd or "/api/" in cmd) and compact in {"[]", "{}", "null", "\"\"", ""}:
+            unresolved.append("empty-api-response")
+            continue
+        if re.search(r"\b(loaded|found|returned|has)\s+0\b", lower):
+            unresolved.append("zero-runtime-data")
+            continue
+        if re.search(r"\b0\s+(items|records|rows|entries|levels|results)\b", lower):
+            unresolved.append("zero-runtime-data")
+            continue
+    return list(dict.fromkeys(unresolved))
+
+
+_BUILD_TEST_TOKENS = (
+    "tsc", "vitest", "jest", "pytest", "mypy", "ruff", "eslint", "cargo",
+    "go build", "go test", "make ", "make\t", "gradle", "mvn", "compile",
+    "npm run build", "yarn build", "pnpm build", "npm test", "npm run test",
+    "vite build", "next build", "ng build", "go vet", "rustc", "javac",
+)
+
+
+def ran_build_or_test(bash_history: list[tuple[str, str]]) -> bool:
+    """True if any command this turn was a build / typecheck / test / lint —
+    evidence the model actually compiled its code (vs just writing files).
+    Deliberately narrow: a dev-server launch (`npm run dev`) is NOT a build."""
+    for command, _ in bash_history:
+        c = str(command).lower()
+        if any(tok in c for tok in _BUILD_TEST_TOKENS):
+            return True
+    return False
+
+
+def _changed_code_files(paths: list[str]) -> bool:
+    code_suffixes = {
+        ".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+        ".go", ".rs", ".java", ".kt", ".swift", ".c", ".cc", ".cpp",
+        ".h", ".hpp", ".cs", ".rb", ".php", ".lua", ".dart", ".scala",
+        ".sh", ".bash", ".zsh", ".ps1", ".sql", ".html", ".css",
+        ".vue", ".svelte", ".astro",
+    }
+    for path in paths:
+        suffix = Path(str(path)).suffix.lower()
+        if suffix in code_suffixes:
+            return True
+    return False
+
+
+def _unsupported_final_claims(content: str, state: TurnState) -> list[str]:
+    """Reject concrete feature claims absent from changed-file evidence.
+
+    This is intentionally generic. It does not try to understand every
+    possible app domain; it catches high-signal phrases where claiming a
+    feature without code evidence is worse than staying quiet.
+    """
+    if state.goal_state.goal_type not in {"build_app", "edit_existing"}:
+        return []
+    corpus = _changed_file_corpus(state.changed_files)
+    if not corpus:
+        return []
+
+    checks: tuple[tuple[str, tuple[str, ...], tuple[str, ...]], ...] = (
+        ("localStorage persistence", ("localstorage",), ("localstorage",)),
+        ("browser speech synthesis", ("speechsynthesis", "speech synthesis"), ("speechsynthesis", "speechsynthesisutterance")),
+        ("text-to-speech", ("text-to-speech", "tts"), ("speechsynthesis", "speechsynthesisutterance", "gtts", "pyttsx3")),
+        ("true/false quiz", ("true/false", "true false"), ("true/false", "true false", "boolean", "is_correct === true")),
+        ("fill-in-the-blank quiz", ("fill in the blank", "fill-in-the-blank"), ("fill in the blank", "fill-in-the-blank", "blank")),
+        ("OAuth/authentication", ("oauth", "authentication", "login"), ("oauth", "auth", "login", "session")),
+        ("database", ("database", "sqlite", "postgres", "mysql"), ("sqlite", "postgres", "mysql", "sqlalchemy", "database")),
+    )
+    unsupported: list[str] = []
+    text = content.lower()
+    for label, claim_terms, evidence_terms in checks:
+        if any(term in text for term in claim_terms) and not any(term in corpus for term in evidence_terms):
+            unsupported.append(label)
+
+    count_claims = re.findall(r"\b(\d+)\s*\+\s+(?:words|items|questions|tests|examples)\b", text)
+    if count_claims:
+        numbers = [int(n) for n in re.findall(r"\b\d+\b", corpus)]
+        max_number = max(numbers) if numbers else 0
+        for claim in count_claims:
+            if int(claim) > max_number:
+                unsupported.append(f"{claim}+ item count")
+    return unsupported[:4]
+
+
+def _requested_feature_gaps(state: TurnState) -> list[str]:
+    """High-confidence request/evidence checks for build completion.
+
+    This is deliberately generic. It only gates on common capability words
+    where code evidence is straightforward, avoiding domain-specific rules.
+    The model can still choose any stack/language; it just cannot declare
+    completion after verification if obvious requested capabilities are
+    absent from the files it changed.
+    """
+    if state.goal_state.goal_type != "build_app":
+        return []
+    request = (state.user_text or "").lower()
+    corpus = _changed_file_corpus(state.changed_files)
+    if not request or not corpus:
+        return []
+    checks: tuple[tuple[str, tuple[str, ...], tuple[str, ...]], ...] = (
+        (
+            "audio/listening",
+            ("audio", "sound", "listen", "pronunciation", "tts", "speech", "voice"),
+            ("audio", "speechsynthesis", "speechsynthesisutterance", "tts", "voice", "utterance", "pyttsx3", "gtts", "howler"),
+        ),
+        (
+            "quiz/testing",
+            ("quiz", "exam", "multiple choice", "question", "test me"),
+            ("quiz", "question", "answer", "score", "choice", "exam", "correct"),
+        ),
+        (
+            "persistence/progress",
+            ("save", "saved", "persist", "progress", "remember"),
+            ("localstorage", "sessionstorage", "sqlite", "database", "json.dump", "writefile", "save", "progress"),
+        ),
+        (
+            "authentication",
+            ("login", "sign in", "signup", "sign up", "auth", "oauth"),
+            ("login", "signin", "signup", "auth", "oauth", "session", "jwt", "password"),
+        ),
+        (
+            "search/filtering",
+            ("search", "filter", "sort"),
+            ("search", "filter", "sort", "query"),
+        ),
+    )
+    missing: list[str] = []
+    for label, request_terms, evidence_terms in checks:
+        if any(term in request for term in request_terms) and not any(term in corpus for term in evidence_terms):
+            missing.append(label)
+    return missing
+
+
+def _changed_file_corpus(paths: list[str], *, max_chars: int = 160_000) -> str:
+    chunks: list[str] = []
+    total = 0
+    for raw in paths[:40]:
+        path = Path(str(raw))
+        if not path.exists() or not path.is_file():
+            continue
+        if path.suffix.lower() in {".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip"}:
+            continue
+        try:
+            text = path.read_text(errors="replace")
+        except Exception:
+            continue
+        chunks.append(text[: max(0, max_chars - total)])
+        total += len(chunks[-1])
+        if total >= max_chars:
+            break
+    return "\n".join(chunks).lower()