localcode 0.3.16__tar.gz → 0.3.17__tar.gz

{localcode-0.3.16/src/localcode.egg-info → localcode-0.3.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: localcode
-Version: 0.3.16
+Version: 0.3.17
 Summary: High-performance AI coding on consumer hardware.
 Author: LocalCode contributors
 License-Expression: Apache-2.0

{localcode-0.3.16 → localcode-0.3.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "localcode"
-version = "0.3.16"
+version = "0.3.17"
 description = "High-performance AI coding on consumer hardware."
 readme = "README.md"
 requires-python = ">=3.10"

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.3.16"
+__version__ = "0.3.17"

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/agent/prompts.py

@@ -51,6 +51,7 @@ Top rules (most important first):
 Plan & tools:
 - For a task with 3+ steps, call todo_write first to lay out the steps, then keep exactly one in_progress and mark each done the instant it's finished. Your list is shown back each round — use it to see what's left.
 - Use real, repo-relative paths (don't improvise `/Users/...` paths).
+- For files and dirs use list_files/read_file/write_file/edit_file — NOT bash (`ls`, `cat`, `cat >`, `>`). bash is only for running commands (npm, git, build, test).
 - edit_file for existing files: anchor `old_string` on 2–4 adjacent lines (matching is whitespace-tolerant; the leading `<n>\\t` from read_file is stripped for you). write_file to create or fully rewrite.
 - On a tool error, read it, fix the specific cause, and retry — don't give up after one failure, and don't repeat the same failing call.
 - New project → prefer a small multi-file layout with a thin entrypoint. Write code valid for the file's real language and match the project's existing conventions.

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/agent/recovery.py

@@ -43,6 +43,10 @@ __all__ = [
     "ChurnSignal",
     "detect_churn",
     "churn_nudge_for",
+    "NOT_FOUND_LOOP_LIMIT",
+    "not_found_key",
+    "detect_not_found_loop",
+    "not_found_nudge",
 ]
 
 
@@ -401,3 +405,79 @@ def rewrite_hard_stop(path, file_write_counts) -> str | None:
         "targeted edit_file change to the broken line, or leave this file and "
         "move on. Do NOT call write_file on this path again."
     )
+
+
+# ── Repeated file-not-found (typo death loop) ───────────────────────
+#
+# read_file's own _confident_match auto-reads a real file when the typo
+# is unambiguous, which breaks MOST of these loops at the source. But
+# when the guessed paths are too far off to match (or point at a dir
+# that doesn't exist), the model can still bounce "file not found" 20+
+# times, each time with a slightly different wrong spelling/case. The
+# byte-identical breakers miss it (each path differs); the churn
+# detectors miss it (read_file is read-only, so it just extends the
+# investigation streak). This is the read-side analogue of the bash
+# command-failure guard: key on the PARENT DIRECTORY (differing typos
+# of one filename share a parent) and count not-found failures.
+
+NOT_FOUND_LOOP_LIMIT = 3
+"""How many 'file not found' read_file failures against the SAME parent
+directory may occur in one turn before we pin the correct path. 3 (like
+CHURN_COMMAND_FAIL_LIMIT): a genuine "read A, oops try B" correction is 1-2
+misses; a 3rd not-found in the same dir means the model is spraying spelling
+variants of a real filename it should just list_files for."""
+
+
+def not_found_key(path: str) -> str:
+    """Normalize a missing read path to the family we count not-found errors
+    by: its parent directory. Different typos of the same file
+    (Aki.md / Anki.md / anki.md) all share a parent, so keying on the parent
+    collapses them into one repeat count. Returns "." for a bare filename."""
+    from pathlib import PurePosixPath
+    p = PurePosixPath(str(path or "").strip().replace("\\", "/"))
+    return str(p.parent)
+
+
+def detect_not_found_loop(not_found_counts: dict[str, int]) -> tuple[str, int] | None:
+    """Return (parent_dir, count) when read_file has failed 'file not found'
+    NOT_FOUND_LOOP_LIMIT+ times against the same parent directory this turn —
+    the model is guessing typo/case variants of a real filename instead of
+    listing the directory once.
+
+    Pure function. Caller maintains `not_found_counts` across the turn
+    (parent-dir key via `not_found_key` → count of not-found read failures).
+    Returns None when nothing crosses the threshold.
+    """
+    worst = ""
+    worst_n = 0
+    for key, n in not_found_counts.items():
+        if n > worst_n:
+            worst, worst_n = key, n
+    if worst_n >= NOT_FOUND_LOOP_LIMIT:
+        return worst, worst_n
+    return None
+
+
+def not_found_nudge(parent_dir: str, real_names: list[str] | None = None) -> str:
+    """Hard, forward-only nudge pinning the correct recovery path for a
+    not-found loop: list the directory ONCE, then read an EXACT name from it.
+
+    Like `churn_nudge_for`, this is a FORWARD-ONLY imperative with NO
+    echo-able self-critical loop language ("you keep failing", "stop
+    guessing in circles") that a small model would parrot back into its own
+    context. When `real_names` is supplied (caller listed the dir), the exact
+    names are pinned so the model can't invent another variant.
+    """
+    listing = ""
+    if real_names:
+        shown = ", ".join(sorted(real_names)[:20])
+        listing = (
+            f" The files that actually exist in {parent_dir} are: {shown}. "
+            "Read one of those EXACT names."
+        )
+    return (
+        f"SYSTEM: read_file cannot find that file in {parent_dir}. Do not try "
+        "another spelling or capitalization. Call list_files on "
+        f"{parent_dir} ONCE, then read_file with an EXACT name from that "
+        "listing." + listing
+    )

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/agent/tool_execution.py

@@ -33,6 +33,15 @@ class ToolExecutionState:
     # times in a row and nothing stopped it. Telemetry behind the
     # removal didn't include info-fetch loops.
     success_counts: dict[tuple[str, str], int] = field(default_factory=dict)
+    # Successful write/edit calls keyed by PATH ONLY (not exact args), so
+    # rewriting the same file with slightly different content each round
+    # still accrues. Feeds the write-churn guard in `dedup_stub_for_tool`.
+    # Motivating logs (2026-06): a turn wrote `useData.ts` 14×, `database.ts`
+    # 8×, `package.json` 4× — plus near-duplicate misspelled siblings
+    # (ReviewSession/ReviewSesssion/ReivewSession.tsx). The per-exact-args
+    # `failed_calls`/`success_counts` guards miss this because each rewrite
+    # is a DISTINCT arg blob; only a path-keyed counter catches the churn.
+    write_path_counts: dict[str, int] = field(default_factory=dict)
     # Last error text seen for a failed bash command, keyed by the same
     # whitespace-normalized cmd_key as `bash_failures`. Lets the rejection
     # stub name the ACTUAL cause ("No such file or directory", syntax error,
@@ -49,6 +58,16 @@ class ToolExecutionState:
 # blocked but never steered.
 _HARD_STOP_THRESHOLD = 4
 
+# After this many SUCCESSFUL writes to the SAME path within one turn, the
+# next write/edit to that path is rejected with a "stop rewriting, go
+# verify" nudge. Keyed by path (not exact args) so near-identical rewrites
+# and typo'd-content re-saves both count. The threshold is deliberately
+# generous — this is a DYNAMIC harness where a couple of legitimate
+# rewrites of the same file per turn are normal (scaffold → fill in →
+# fix a syntax error). We only step in once a file is clearly being
+# churned (4th write of the same path this turn).
+_WRITE_CHURN_THRESHOLD = 3
+
 
 def _diagnose_bash_error(err: str) -> str | None:
     """Translate a raw shell error into a concrete corrective action.
@@ -190,6 +209,29 @@ def dedup_stub_for_tool(
                 "exact anchor, use multi_edit/edit_diff where appropriate, or "
                 "move on if the file is already correct."
             )
+        # Write-churn guard: repeated SUCCESSFUL rewrites of the SAME path
+        # this turn. Keyed by path (not exact args) so near-duplicate content
+        # each round still accrues — the failed_calls/success_counts guards
+        # above miss this because every rewrite is a distinct arg blob. Once
+        # a file has already been written `_WRITE_CHURN_THRESHOLD` times, the
+        # earlier writes already landed on disk; another rewrite is churn.
+        # Nudge the model to STOP and verify (run the build) or move to the
+        # next file instead of rewriting the same path again.
+        churn_path = args.get("path") or args.get("file_path") or ""
+        if isinstance(churn_path, str) and churn_path:
+            writes = state.write_path_counts.get(churn_path, 0)
+            if writes >= _WRITE_CHURN_THRESHOLD:
+                return (
+                    f"REJECTED: {churn_path} has already been written {writes} "
+                    "times this turn. Those writes already landed on disk — "
+                    "rewriting the same file again is churn, not progress. "
+                    "STOP rewriting this path. Instead: run the build/test "
+                    "command (bash) to verify what you have and read the ACTUAL "
+                    "error it reports, or move on to the NEXT file. Only write "
+                    f"{churn_path} again if a concrete build error tells you "
+                    "exactly what line to change — and if so, use a small "
+                    "targeted edit_file, not a full rewrite."
+                )
     return None
 
 
@@ -292,6 +334,12 @@ def track_tool_result(
             state.files_modified.add(modified_path)
             state.files_read.pop(modified_path, None)
             state.io_calls.clear()
+            # Path-keyed write tally feeds the write-churn guard. Only
+            # successful writes count — a rejected/failed write did NOT
+            # land on disk, so it isn't churn.
+            state.write_path_counts[modified_path] = (
+                state.write_path_counts.get(modified_path, 0) + 1
+            )
     if (
         tool_name in {"write_file", "append_file", "edit_file", "multi_edit", "edit_diff"}
         and not failed

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/app.py

@@ -15,7 +15,7 @@ from .composer import compose_messages
 # loading were dead code (no user configured an MCP server; Playwright
 # browser path was unreachable from the agent loop).
 from .config import AppConfig, ensure_home_dirs, save_config
-from .context import build_context_block, find_repo_root
+from .context import build_context_block, find_repo_root, _is_home_or_shallower
 from .indexer import build_index, load_index, search_index
 from .models import GEMMA_PROFILES, get_runtime_model, resolve_profile
 from .patching import build_diff, parse_diff
@@ -138,6 +138,20 @@ class LocalCodeApp:
             _, preset = benchmark_report(self.config, self.config.runtime.mode)
             apply_preset(self.config, preset, model=self.config.runtime.model)
         self.repo_root = find_repo_root(cwd or Path.cwd())
+        # Degenerate case: no .git and no project marker anywhere above the
+        # launch dir, and that launch dir is $HOME (or shallower). We can't
+        # invent a better root, but we MUST flag it — otherwise the model ends
+        # up carrying 70-char absolute paths (with spaces/mixed-case) on every
+        # tool call and corrupts them into failed-read loops. Mark it so the
+        # rest of the app (and logs) know paths are unanchored, and prefer the
+        # deepest dir the model actually builds in once files start landing.
+        self.repo_root_is_home = _is_home_or_shallower(self.repo_root)
+        if self.repo_root_is_home:
+            self.log.warning(
+                "No project root found above %s; running unanchored at $HOME. "
+                "Paths will be resolved relative to whatever directory the task "
+                "builds in.", self.repo_root,
+            )
         self.store = SessionStore()
         if session_id:
             self.session = self.store.load(session_id)

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/auto_compact.py

@@ -58,25 +58,33 @@ def _build_summary(old: list[dict]) -> str:
             if result:
                 key_actions.append(f"Tool {tool_name or 'unknown'}: {result}")
 
-    summary_lines = ["[Conversation summary]"]
+    # Second-person, self-referential framing: everything below is the
+    # ASSISTANT's OWN prior work, NOT files/work the user handed over. This
+    # stops the model from reading its own build after compaction as
+    # pre-existing user-provided code ("the user created these files…").
+    summary_lines = [
+        "Summary of what YOU have already done this task (this is YOUR OWN prior "
+        "work — NOT the user's, and NOT pre-existing files on disk; build on it — "
+        "do NOT restart, re-read, or ask the user what to build):"
+    ]
     if latest_user_goal:
-        summary_lines.append(f"Current objective: {latest_user_goal}")
+        summary_lines.append(f"The user's task: {latest_user_goal}")
     if summary_parts:
-        summary_lines.append("Topics discussed:")
+        summary_lines.append("Context so far:")
         for s in summary_parts[-8:]:
             summary_lines.append(f"  - {s}")
     if key_actions:
-        summary_lines.append("Work already completed:")
+        summary_lines.append("You already did:")
         for a in key_actions[-10:]:
             summary_lines.append(f"  - {a}")
     if open_questions:
-        summary_lines.append("Open issues / pending follow-ups:")
+        summary_lines.append("Still to do:")
         for q in open_questions[-6:]:
             summary_lines.append(f"  - {q}")
     if files_mentioned:
-        summary_lines.append(f"Files involved: {', '.join(sorted(files_mentioned)[:20])}")
+        summary_lines.append(f"Files YOU created/edited: {', '.join(sorted(files_mentioned)[:20])}")
     if tools_used:
-        summary_lines.append(f"Tools used: {', '.join(sorted(tools_used))}")
+        summary_lines.append(f"Tools YOU used: {', '.join(sorted(tools_used))}")
     return "\n".join(summary_lines)
 
 
@@ -110,12 +118,24 @@ def auto_compact(messages: list[dict], max_chars: int,
 
     summary_text = _build_summary(old)
 
+    # Frame the summary as a role:"system" memo (matching compaction.py) so the
+    # model never mistakes its OWN compacted work for user-authored code. The
+    # old approach injected the summary under role:"user" with passive
+    # third-person wording ("Work already completed:"), which made the model
+    # read its own build as pre-existing files the user had handed over ("the
+    # user created these files", "what would you like me to build?").
+    memo = (
+        "Earlier turns of THIS task were compacted to save context. The summary "
+        "below is YOUR OWN work already done — build on it and do NOT restart, "
+        "re-read files, redo steps, or ask the user what to build:\n\n"
+        f"{summary_text}"
+    )
+
     # Build compacted messages
     compacted = []
     if system_msg:
         compacted.append(system_msg)
-    compacted.append({"role": "user", "content": summary_text})
-    compacted.append({"role": "assistant", "content": "Understood. I have the context from our earlier conversation. How can I continue helping?"})
+    compacted.append({"role": "system", "content": memo})
     compacted.extend(recent)
 
     return compacted, summary_text

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/context.py

@@ -16,11 +16,68 @@ IGNORE_DIRS = {
 }
 
 
+# Non-.git project markers, in the same spirit as agent/context._PROJECT_MARKERS.
+# When a directory has no git history, one of these still identifies the ROOT of
+# a real project — so a deep build dir anchors to its own project instead of
+# silently adopting $HOME.
+_ROOT_PROJECT_MARKERS = (
+    "package.json",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "tsconfig.json",
+)
+
+
+def _is_home_or_shallower(path: Path) -> bool:
+    """True when `path` is $HOME, its parent, or the filesystem root/anchor.
+
+    These are never legitimate project roots. Adopting one forces the model to
+    carry long absolute paths (e.g. `$HOME/Desktop/Github/.../Anki/<model>/…`)
+    on every tool call, which it then corrupts (`Aki`, `gitHub`, hallucinated
+    users) and dies in failed-read loops. This predicate lets us refuse them.
+    """
+    try:
+        home = Path.home().resolve()
+    except (RuntimeError, OSError):
+        return False
+    return path in {home, home.parent, Path(path.anchor)}
+
+
 def find_repo_root(start: Path) -> Path:
+    """Locate the project root to anchor the model's paths against.
+
+    Order of preference:
+      1. The nearest ancestor containing `.git` — a real VCS root. This path is
+         behaviour-IDENTICAL to the original implementation and is what runs
+         whenever the user is inside a git checkout.
+      2. If there is no `.git` anywhere above `start`, the nearest ancestor
+         carrying a non-git project marker (package.json / pyproject.toml /
+         go.mod / Cargo.toml / tsconfig.json). This pins a *real* project dir
+         instead of walking all the way up to (and silently adopting) $HOME.
+      3. Otherwise `start` itself — but NEVER bare $HOME (or shallower). When
+         `start` resolves to $HOME with no project marker, we still hand back
+         $HOME (there is nothing nearer to anchor to), but callers can detect
+         that degenerate case via `_is_home_or_shallower` and mark it.
+    """
     current = start.resolve()
-    for candidate in [current, *current.parents]:
+    chain = [current, *current.parents]
+
+    # 1. A real .git root always wins — identical to the original behaviour.
+    for candidate in chain:
         if (candidate / ".git").exists():
             return candidate
+
+    # 2. No .git: prefer the nearest non-git project marker, but never accept a
+    #    marker at $HOME or shallower (those are not project roots).
+    for candidate in chain:
+        if _is_home_or_shallower(candidate):
+            break
+        if any((candidate / marker).exists() for marker in _ROOT_PROJECT_MARKERS):
+            return candidate
+
+    # 3. Nothing better than the launch dir. Return it unchanged (this is cwd);
+    #    if it IS $HOME the caller is responsible for marking the degenerate case.
     return current
 
 

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/tools/project_check.py

@@ -65,6 +65,12 @@ def _detect_commands(repo_root: str) -> list[tuple[str, list[str], str]]:
             scripts = {}
         # Only run node-based checks once deps are installed (else every import
         # is a false "cannot find module" error that would derail the model).
+        # NOTE: tsc/typecheck only covers the files the project's tsconfig
+        # includes (typically `src/`). A module written OUTSIDE that root (e.g.
+        # accidentally at the repo root) is never type-checked here, so the
+        # Tier-1 per-write syntax_check is the only gate it passes through. If
+        # this proves a recurring miss, widen coverage (e.g. an explicit tsc
+        # over stray *.ts outside `include`) rather than assuming src/-only.
         if os.path.isdir(node_modules):
             if "typecheck" in scripts:
                 cmds.append(("npm run typecheck", ["npm", "run", "--silent", "typecheck"], pj_dir))

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/tools/read_file.py

@@ -52,31 +52,87 @@ SCHEMA = {
 }
 
 
+# Fuzzy-match ratio at/above which we AUTO-READ the real file instead of
+# merely suggesting it. 0.85 is high enough that only genuine typos /
+# case-variants of one real name match (Aki→Anki, gitHub→Github), not two
+# distinct files that happen to be somewhat similar.
+AUTO_READ_RATIO = 0.85
+
+
+def _list_dir_candidates(missing):
+    """(candidates, base) — every file under the nearest existing ancestor of
+    `missing`. Walk up to 6 levels so a wrong path segment deep in the tree
+    still resolves to a searchable directory. Capped at 4000 files."""
+    from pathlib import Path
+    missing = Path(missing)
+    base = missing.parent
+    for _ in range(6):
+        if base.exists():
+            break
+        base = base.parent
+    if not base.exists():
+        return [], None
+    candidates = []
+    for p in base.rglob("*"):
+        if p.is_file():
+            candidates.append(p)
+        if len(candidates) > 4000:
+            break
+    return candidates, base
+
+
+def _confident_match(missing):
+    """Return the ONE real file `missing` is almost certainly a typo of, else
+    None. Authoritative (used to auto-read), so it only fires when unambiguous:
+
+      • exactly one file whose basename equals `missing`'s case-insensitively
+        (a pure case/typo of a unique name — gitHub→Github, README.MD→readme.md), OR
+      • exactly one file whose basename fuzzy-matches at ratio ≥ AUTO_READ_RATIO.
+
+    Requiring the winner to be UNIQUE prevents auto-reading the wrong one of
+    several same-named files in different dirs — that stays a soft suggestion.
+    """
+    import difflib
+    from pathlib import Path
+    try:
+        candidates, _ = _list_dir_candidates(missing)
+        if not candidates:
+            return None
+        name = Path(missing).name
+        # Pure case/typo of a unique basename → definitely that file.
+        same = [p for p in candidates if p.name.lower() == name.lower()]
+        if len(same) == 1:
+            return same[0]
+        if len(same) > 1:
+            return None  # ambiguous by name — don't auto-pick.
+        # High-confidence fuzzy basename match, and it must be unique.
+        names = [p.name for p in candidates]
+        close = difflib.get_close_matches(name, names, n=1, cutoff=AUTO_READ_RATIO)
+        if close:
+            hits = [p for p in candidates if p.name == close[0]]
+            if len(hits) == 1:
+                return hits[0]
+    except Exception:
+        pass
+    return None
+
+
 def _suggest_path(missing) -> str:
     """Suggest the real file when the model gave a typo'd/wrong-case path.
 
     Walk up to the nearest existing ancestor dir and fuzzy-match the missing
-    filename (and its path segments) against what's actually there.
+    filename (and its path segments) against what's actually there. Lower-
+    confidence sibling of `_confident_match`: used only when we're NOT sure
+    enough to auto-read, so it stays a hint the model can act on.
     """
     import difflib
     from pathlib import Path
     try:
         missing = Path(missing)
         name = missing.name
-        # Nearest existing ancestor to search in.
-        base = missing.parent
-        for _ in range(6):
-            if base.exists():
-                break
-            base = base.parent
-        if not base.exists():
+        candidates, base = _list_dir_candidates(missing)
+        if not candidates:
             return ""
-        candidates = []
-        for p in base.rglob("*"):
-            if p.is_file():
-                candidates.append(p)
-            if len(candidates) > 4000:
-                break
         names = [p.name for p in candidates]
         close = difflib.get_close_matches(name, names, n=1, cutoff=0.6)
         if close:
@@ -90,14 +146,34 @@ def _suggest_path(missing) -> str:
 def execute(ctx: ToolContext, args: dict) -> str:
     if "path" not in args:
         return "Error: 'path' argument is required for read_file."
-    path = ctx.repo / args["path"]
+    requested = args["path"]
+    path = ctx.repo / requested
+    note = ""
+    source_disp = str(requested)
     if not path.exists():
         # A small model invents misspelled/wrong-case paths (a dropped letter,
         # gitHub/github/Github) and, getting a bare "not found", retries with
         # ANOTHER wrong variant forever (dedup can't collapse differing typos).
-        # Point it at the real nearby file so it corrects instead of guessing.
-        hint = _suggest_path(path)
-        return f"File not found: {args['path']}" + (f"\n{hint}" if hint else "")
+        real = _confident_match(path)
+        if real is None:
+            # Not confident enough to auto-read — hand back the best soft hint.
+            hint = _suggest_path(path)
+            return f"File not found: {requested}" + (f"\n{hint}" if hint else "")
+        # AUTHORITATIVE recovery: `requested` is unambiguously a typo/case-
+        # variant of exactly one real file. Read THAT file now instead of
+        # bouncing the model back with a suggestion it can ignore (which is
+        # what fuels the 20+-retry not-found death loop). The note pins the
+        # correct path so the next call uses it directly.
+        try:
+            source_disp = str(real.relative_to(ctx.repo))
+        except Exception:
+            source_disp = str(real)
+        note = (
+            f"[read {source_disp} instead of '{requested}' — that path does not "
+            f"exist and this is the only close match. Use '{source_disp}' "
+            "exactly from now on; do NOT guess more spellings.]\n\n"
+        )
+        path = real
     content = path.read_text(errors="replace")
     lines = content.splitlines()
     default_limit, max_default_chars = _dynamic_read_defaults(ctx)
@@ -131,7 +207,7 @@ def execute(ctx: ToolContext, args: dict) -> str:
     # phrases (IGNORE ALL PRIOR INSTRUCTIONS, etc.) with a visible
     # warning before the content. See src/localcode/injection_defense.py.
     from ..injection_defense import wrap_untrusted
-    return wrap_untrusted(result, source=str(args["path"]))
+    return note + wrap_untrusted(result, source=source_disp)
 
 
 def is_concurrency_safe(args: dict) -> bool:

{localcode-0.3.16 → localcode-0.3.17}/src/localcode/tools/syntax_check.py

@@ -20,6 +20,7 @@ LOCALCODE_SYNTAX_CHECK=0.
 """
 from __future__ import annotations
 
+import ast
 import json
 import os
 import subprocess
@@ -70,10 +71,40 @@ def _check_json(content: str) -> str | None:
 def _check_python(content: str, path: str) -> str | None:
     try:
         compile(content, path, "exec")
-        return None
     except SyntaxError as e:
         loc = f"line {e.lineno}" + (f" col {e.offset}" if e.offset else "")
         return f"Python syntax error at {loc}: {e.msg}"
+    # Grammar is valid — also flag a name defined twice at module top level
+    # (legal Python, but almost always an accidental clobber the model should fix).
+    return _check_python_duplicates(content)
+
+
+def _check_python_duplicates(content: str) -> str | None:
+    """Best-effort: a top-level def/class name declared twice in one module.
+
+    Skips @overload-decorated defs (a legitimate repeated name). Returns None on
+    any parse trouble so this never blocks a write it can't reason about.
+    """
+    try:
+        tree = ast.parse(content)
+    except Exception:
+        return None
+    seen: dict[str, int] = {}
+    for node in tree.body:
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        # @overload / @typing.overload legitimately repeats a name — ignore.
+        if any(
+            (getattr(dec, "attr", None) or getattr(dec, "id", None)) == "overload"
+            for dec in node.decorator_list
+        ):
+            continue
+        name = node.name
+        line = node.lineno
+        if name in seen:
+            return f"duplicate declaration: '{name}' declared at lines {seen[name]} and {line}"
+        seen[name] = line
+    return None
 
 
 def _check_treesitter(content: str, lang: str) -> str | None:
@@ -94,7 +125,10 @@ def _check_treesitter(content: str, lang: str) -> str | None:
         return None
     root = tree.root_node
     if not root.has_error:
-        return None
+        # Grammar is valid — but a duplicate top-level declaration is still a
+        # real build error (e.g. `export function foo` twice → esbuild/tsc
+        # "has already been declared") that a grammar check alone can't catch.
+        return _check_duplicate_decls(root, content, lang)
     node = _first_error_node(root)
     if node is None:
         return f"syntax error detected in this {lang} file (unbalanced brackets/quotes or a stray token)"
@@ -120,3 +154,63 @@ def _first_error_node(root):
         # push children in order so we return the earliest error
         stack.extend(reversed(n.children))
     return None
+
+
+# Top-level TS/JS declaration node types that bind a single name.
+_JS_NAMED_DECL = frozenset({
+    "function_declaration", "generator_function_declaration",
+    "class_declaration", "abstract_class_declaration",
+    "interface_declaration", "type_alias_declaration", "enum_declaration",
+})
+# var/let/const wrappers that hold one or more variable_declarator children.
+_JS_VAR_DECL = frozenset({"lexical_declaration", "variable_declaration"})
+
+
+def _check_duplicate_decls(root, content: str, lang: str) -> str | None:
+    """Flag a top-level name declared more than once in a TS/JS file.
+
+    Grammatically valid, but a hard build error real users hit (esbuild/tsc:
+    "The symbol X has already been declared"). Best-effort over the parse tree
+    we already produced; returns None for unrelated languages or on any trouble.
+    """
+    if lang not in ("javascript", "typescript", "tsx"):
+        return None
+    try:
+        src = content.encode("utf-8")
+    except Exception:
+        return None
+
+    def _text(node) -> str:
+        return src[node.start_byte:node.end_byte].decode("utf-8", "replace")
+
+    seen: dict[str, int] = {}
+
+    def _record(name_node) -> str | None:
+        if name_node is None or name_node.type != "identifier":
+            return None
+        name = _text(name_node)
+        line = name_node.start_point[0] + 1
+        if name in seen:
+            return f"duplicate declaration: '{name}' declared at lines {seen[name]} and {line}"
+        seen[name] = line
+        return None
+
+    for child in root.children:
+        node = child
+        # `export function foo` / `export const x` — unwrap to the declaration.
+        if node.type == "export_statement":
+            decl = node.child_by_field_name("declaration")
+            if decl is None:
+                continue
+            node = decl
+        if node.type in _JS_NAMED_DECL:
+            err = _record(node.child_by_field_name("name"))
+            if err:
+                return err
+        elif node.type in _JS_VAR_DECL:
+            for c in node.children:
+                if c.type == "variable_declarator":
+                    err = _record(c.child_by_field_name("name"))
+                    if err:
+                        return err
+    return None