localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/__init__.py

@@ -0,0 +1,11 @@
+__all__ = ["__version__"]
+
+# Read the version from installed package metadata so it can never drift from
+# pyproject.toml (it was hardcoded and went ~12 releases stale). Falls back to a
+# hardcoded value only when running from a source tree that isn't installed.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("localcode")
+except PackageNotFoundError:  # not installed (e.g. raw source checkout)
+    __version__ = "0.4.0"

localcode/__main__.py

@@ -0,0 +1,5 @@
+from .entrypoint import main
+
+
+if __name__ == "__main__":
+    main()

localcode/_subproc_env.py

@@ -0,0 +1,54 @@
+"""Single source of truth for the env dict passed to subprocesses.
+
+Background: macOS's libsystem prints
+  "MallocStackLogging: can't turn off malloc stack logging
+   because it was not enabled."
+to stderr at libsystem-init of every spawned child whenever certain
+env vars are set in the child's environment. The vars are commonly
+set by Xcode CLI tools, IDE shell integrations, and Conda env-activate
+hooks. The warning fires before any user code runs, so Python can't
+suppress it from inside the child — the only fix is to strip the vars
+from the env dict we hand to subprocess.Popen / subprocess.run.
+
+the console-script entrypoint pops them from os.environ on entry, but every site that builds
+an explicit env dict must also strip them or risk re-introducing the
+var. Real failure 2026-04-26: terminal flooded with ~60 of these
+warnings because spawn sites filtered MallocStackLogging* but missed
+MallocNanoZone, which produces the same warning class.
+
+This module is the SINGLE place that knows the full ban list. Every
+subprocess spawn that needs to construct an env dict should use
+clean_env() rather than rolling its own filter.
+"""
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+
+# Env vars whose presence triggers the libsystem malloc-stack-logging
+# warning at child-process startup on macOS. Sources:
+#   • MallocStackLogging[NoCompact]: enabled by Xcode Instruments and
+#     a few legacy debug profiles; setting it to "0" doesn't disable —
+#     the var must be UNSET.
+#   • MallocNanoZone: typically "0" set by Xcode CLI tools / IDE
+#     terminal integrations to opt-out of the nano malloc zone.
+#     Triggers the same class of warning at libsystem init.
+_MALLOC_NOISE_VARS = {
+    "MallocStackLogging",
+    "MallocStackLoggingNoCompact",
+    "MallocNanoZone",
+}
+
+
+def clean_env(base: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Return a copy of `base` (default: os.environ) with malloc-noise
+    vars stripped. Safe to pass to subprocess.Popen / subprocess.run as
+    `env=`.
+
+    Always returns a NEW dict — never mutates the input. Callers that
+    need to add or override keys (`env["GGML_BACKEND_PATH"] = ""`,
+    etc.) can do so on the returned dict without affecting os.environ.
+    """
+    src = os.environ if base is None else base
+    return {k: v for k, v in src.items() if k not in _MALLOC_NOISE_VARS}

localcode/agent/__init__.py

@@ -0,0 +1,177 @@
+"""localcode.agent — public re-export surface.
+
+This package contains the agent turn engine, split across several
+focused modules (T0.1 refactor). Everything listed below is
+re-exported here so external callers can continue to import from
+`localcode.agent` without caring about the internal split.
+
+  loop.py       — `run_agent_loop`, the main entry point
+  prompts.py    — SYSTEM_PROMPT, REASONING_RULES,
+                  _load_project_instructions
+  constants.py  — policy knobs, safety caps, tables
+  context.py    — message aging / redaction / compaction pipeline
+  recovery.py   — stall detection + auto-nudge
+  helpers.py    — tool-dispatch + display helpers
+
+Background: before T0.1, agent.py was a 1792-line monolith. The split
+broke it into focused modules (each ≤ ~720 LoC), with __init__.py
+reduced to this re-export surface — well under the 400-LoC cap the
+plan sets for god modules (see dev/eval/OPTIMIZATION_PLAN.md § T0).
+
+Unused-import warnings in this file are expected — every imported
+name is intentionally re-exported. The `# noqa: F401` comments
+document this for linters that honour them; Pylance doesn't, so its
+"not accessed" warnings on this module are false positives.
+"""
+from __future__ import annotations
+
+
+# Public contract for `localcode.agent`. Anything not in this list is
+# internal and may be renamed / moved / deleted without warning. Names
+# starting with an underscore are included for back-compat with
+# tests/test_context_pipeline_e2e.py which reaches into the context
+# pipeline by name — once that test is migrated to a public helper,
+# those entries can come out of `__all__` and move to underscore-only
+# "internal import at your own risk."
+__all__ = [
+    # Loop entry
+    "run_agent_loop",
+    # Prompts
+    "SYSTEM_PROMPT",
+    "REASONING_RULES",
+    # Constants (policy knobs external code may want to read)
+    "MAX_ROUNDS",
+    "MAX_OUTPUT_TOKENS",
+    "MAX_THINKING_SECONDS",
+    "MAX_THINKING_CHARS",
+    "RESULT_LIMITS",
+    "MAX_AGGREGATE_PER_TURN",
+    "DESTRUCTIVE_PATTERNS",
+    "COMPACT_KEEP_RECENT_TOOL_RESULTS",
+    "COMPACT_MIN_CONTENT_CHARS",
+    "REDACT_KEEP_RECENT_WRITES",
+    "REDACT_MIN_CONTENT_CHARS",
+    "READ_UNCHANGED_STUB_PREFIX",
+    # Recovery
+    "StallMode",
+    "detect_stall",
+    "nudge_for",
+    "MAX_EMPTY_ROUND_RETRIES",
+    # Context pipeline — underscore-prefixed, test-only back-compat
+    "_prepare_model_messages",
+    "_redact_old_write_args",
+    "_redact_duplicate_reads",
+    "_compact_old_tool_results",
+]
+
+
+# ── Constants ────────────────────────────────────────────────────────
+# Policy knobs / safety caps / table data moved to agent/constants.py
+# during the T0.1 split. Re-exported here so external callers (tests,
+# eval, app.py) that do `from localcode.agent import MAX_THINKING_SECONDS`
+# keep working unchanged.
+
+from .constants import (  # noqa: F401 — re-exports for back-compat
+    MAX_ROUNDS,
+    MAX_OUTPUT_TOKENS,
+    MAX_THINKING_SECONDS,
+    MAX_THINKING_CHARS,
+    RESULT_LIMITS,
+    MAX_AGGREGATE_PER_TURN,
+    DESTRUCTIVE_PATTERNS,
+    COMPACT_KEEP_RECENT_TOOL_RESULTS,
+    COMPACT_MIN_CONTENT_CHARS,
+    REDACT_KEEP_RECENT_WRITES,
+    REDACT_MIN_CONTENT_CHARS,
+    PROJECT_FILES as _PROJECT_FILES,
+    READ_UNCHANGED_STUB_PREFIX,
+)
+
+# ── Context-management pipeline ─────────────────────────────────────
+# Moved to agent/context.py during T0.1-c. Re-exported here so
+# tests/test_context_pipeline_e2e.py + other callers that do
+#   `from localcode.agent import _prepare_model_messages`
+# keep working unchanged.
+
+from .context import (  # noqa: F401
+    _truncate_result,
+    _compact_old_tool_results,
+    _redact_old_write_args,
+    _redact_duplicate_reads,
+    _msg_bytes,
+    _prepare_model_messages,
+    _estimate_tokens,
+    _compact_messages,
+    _summarize_args,
+)
+
+
+# ── Stall detection + auto-nudge recovery ──────────────────────────
+# Moved to agent/recovery.py during T0.1-d. The loop calls
+# `detect_stall(...)` after each round and, if the round stalled,
+# appends `nudge_for(mode)` as a synthetic user message before
+# looping. MAX_EMPTY_ROUND_RETRIES bounds how many consecutive
+# stalls we tolerate per turn.
+
+from .recovery import (  # noqa: F401
+    StallMode,
+    detect_stall,
+    nudge_for,
+    MAX_EMPTY_ROUND_RETRIES,
+)
+
+
+# ── Loop-adjacent helpers ──────────────────────────────────────────
+# Moved to agent/helpers.py during T0.1-e. Re-exported here so any
+# internal caller that still imports via `from localcode.agent import
+# _execute_tool` (or other private helpers) keeps working unchanged.
+# These are not part of the public API — they're named here only to
+# preserve the back-compat surface during the refactor.
+
+from .helpers import (  # noqa: F401
+    _execute_tool,
+    _first_token,
+    _needs_confirmation,
+    _render_markdown,
+    _brief_result,
+    _grounded_file_summary,
+    _tool_stage_label,
+)
+
+# ── Prompt templates + project-instructions loader ────────────────────────
+# Moved to agent/prompts.py during the T0.1-b split. Re-exported here so
+# external callers (dev/eval/prompt_variants.py, tests/promptfoo, app.py,
+# tests/test_context_pipeline_e2e.py) that do
+#   `from localcode.agent import SYSTEM_PROMPT`
+# keep working unchanged. See agent/prompts.py for the commented
+# MINIMAL-CORE variant preserved there for visual diffing.
+
+from .prompts import (  # noqa: F401 — re-exports for back-compat
+    SYSTEM_PROMPT,
+    REASONING_RULES,
+    _load_project_instructions,
+)
+
+
+# ── Tool registry ────────────────────────────────────────────────────────
+#
+# Every tool lives in its own file under src/localcode/tools/. That package
+# assembles the registry; we just pull in the schemas (for the LLM call)
+# and the dispatcher (for _execute_tool). Plan-mode gating still lives
+# here because it's cross-tool policy, not tool-specific logic.
+
+
+
+# ── Result Management ────────────────────────────────────────────────────
+
+# ── Context Management ───────────────────────────────────────────────────
+
+# ── Display Helpers ──────────────────────────────────────────────────────
+
+# ── Main agent loop ─────────────────────────────────────────────────
+# Moved to agent/loop.py during T0.1-f. Re-exported here so every
+# existing caller that does `from localcode.agent import run_agent_loop`
+# keeps working unchanged. This is the public entry point into the
+# agent turn engine.
+
+from .loop import run_agent_loop  # noqa: F401

localcode/agent/app_tasks.py

@@ -0,0 +1,157 @@
+"""App/build/run task helpers for the agent loop."""
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+
+PARTIAL_HANDOFF_RE = re.compile(
+    r"(?:\bnext steps\b|\bimplemented features so far\b|\bi have started building\b|"
+    r"\bready to proceed\b|\bready to continue\b|\barchitecture overview\b|"
+    r"\bwould you like me to\b|\bI'?m ready to proceed\b)",
+    re.IGNORECASE,
+)
+BLOCKING_QUESTION_RE = re.compile(r"^(?:[^?]{0,320}\?)$", re.DOTALL)
+PORT_RE = re.compile(r"(?:--port\s+|-p\s+|localhost:|127\.0\.0\.1:)(\d{2,5})")
+__all__ = [
+    "looks_like_partial_handoff",
+    "is_focused_blocking_question",
+    "extract_port",
+    "has_runtime_verification_signal",
+    "app_source_line_stats",
+    "has_launch_signal",
+    "ground_run_or_launch_text",
+    "format_run_or_launch_summary",
+]
+
+
+def looks_like_partial_handoff(content: str) -> bool:
+    return bool(PARTIAL_HANDOFF_RE.search(content or ""))
+
+
+def is_focused_blocking_question(content: str) -> bool:
+    text = (content or "").strip()
+    if not text:
+        return False
+    if text.count("?") != 1:
+        return False
+    if not BLOCKING_QUESTION_RE.match(text):
+        return False
+    lower = text.lower()
+    if re.match(r"^(?:hi|hello|hey|yo)[!.\s,]*(?:how can i help|what can i do)", lower):
+        return False
+    return not any(
+        bad in lower for bad in (
+            "next steps",
+            "ready to proceed",
+            "implemented features so far",
+            "architecture overview",
+        )
+    )
+
+
+def extract_port(text: str) -> int:
+    for raw in PORT_RE.findall(text or ""):
+        try:
+            port = int(raw)
+        except Exception:
+            continue
+        if 1 <= port <= 65535:
+            return port
+    return 0
+
+
+def has_runtime_verification_signal(bash_history: list[tuple[str, str]]) -> bool:
+    for cmd, result in bash_history:
+        cmd_l = (cmd or "").lower()
+        result_l = (result or "").lower()
+        if result_l.startswith("error:") or result_l.startswith("rejected:"):
+            continue
+        if "curl " in cmd_l or "http://localhost:" in cmd_l or "http://127.0.0.1:" in cmd_l:
+            if any(
+                bad in result_l for bad in (
+                    "address already in use",
+                    "error while attempting to bind",
+                    "failed to start",
+                    "connection refused",
+                    "not found",
+                )
+            ):
+                continue
+            return True
+        if "open http://localhost:" in cmd_l or "open http://127.0.0.1:" in cmd_l:
+            return True
+    return False
+
+
+def app_source_line_stats(repo_root: Path | str, changed_files: list[str]) -> tuple[int, int]:
+    repo = Path(repo_root)
+    source_exts = {".py", ".js", ".jsx", ".ts", ".tsx", ".html", ".css"}
+    source_count = 0
+    total_lines = 0
+    for rel in changed_files:
+        try:
+            path = repo / rel
+            if path.suffix.lower() not in source_exts or not path.is_file():
+                continue
+            source_count += 1
+            total_lines += len(path.read_text(errors="replace").splitlines())
+        except Exception:
+            continue
+    return source_count, total_lines
+
+
+def has_launch_signal(bash_history: list[tuple[str, str]]) -> bool:
+    for cmd, result in bash_history:
+        cmd_l = (cmd or "").lower()
+        result_l = (result or "").lower()
+        if result_l.startswith("error:") or result_l.startswith("rejected:"):
+            continue
+        if any(
+            token in cmd_l for token in (
+                "npm run dev",
+                "vite",
+                "uvicorn",
+                "flask run",
+                "python -m http.server",
+                "streamlit run",
+            )
+        ):
+            if any(
+                bad in result_l for bad in (
+                    "exit code 1",
+                    "address already in use",
+                    "failed to start",
+                    "connection refused",
+                    "error:",
+                )
+            ):
+                continue
+            return True
+    return False
+
+
+def ground_run_or_launch_text(text: str, port: int) -> str:
+    if port <= 0 or not text:
+        return text
+    grounded = text
+    grounded = grounded.replace("http://localhost:[FRONTEND_PORT]", f"http://localhost:{port}")
+    grounded = grounded.replace("http://127.0.0.1:[FRONTEND_PORT]", f"http://127.0.0.1:{port}")
+    grounded = grounded.replace("http://localhost:[PORT]", f"http://localhost:{port}")
+    grounded = grounded.replace("http://127.0.0.1:[PORT]", f"http://127.0.0.1:{port}")
+    grounded = grounded.replace("localhost:[FRONTEND_PORT]", f"localhost:{port}")
+    grounded = grounded.replace("127.0.0.1:[FRONTEND_PORT]", f"127.0.0.1:{port}")
+    grounded = grounded.replace("localhost:[PORT]", f"localhost:{port}")
+    grounded = grounded.replace("127.0.0.1:[PORT]", f"127.0.0.1:{port}")
+    return grounded
+
+
+def format_run_or_launch_summary(port: int, verified: bool) -> str:
+    if port > 0:
+        if verified:
+            return f"The app is now running and verified.\n\nOpen it at http://localhost:{port}."
+        return f"The app is now running.\n\nOpen it at http://localhost:{port}."
+    if verified:
+        return "The app is now running and verified."
+    return "The app is now running."
+

localcode/agent/constants.py

@@ -0,0 +1,275 @@
+"""Agent loop constants, kept separate from the loop logic.
+
+Pulled out of agent/__init__.py during the T0.1 split. Every name here
+was previously a module-level constant in the old agent.py — nothing
+has changed semantically. Keeping them in their own module lets us:
+
+  1. Reason about policy knobs without scrolling past 1,800 lines of
+     loop logic.
+  2. Re-export them from `localcode.agent` so external callers
+     (tests, eval, app.py) don't notice the split.
+  3. Import them from sibling modules (context.py, recovery.py,
+     loop.py) without creating an import cycle through the package
+     `__init__`.
+"""
+from __future__ import annotations
+
+
+__all__ = [
+    "MAX_ROUNDS",
+    "MAX_OUTPUT_TOKENS",
+    "MAX_THINKING_SECONDS",
+    "MAX_THINKING_CHARS",
+    "RESULT_LIMITS",
+    "MAX_AGGREGATE_PER_TURN",
+    "DESTRUCTIVE_PATTERNS",
+    "COMPACT_KEEP_RECENT_TOOL_RESULTS",
+    "COMPACT_MIN_CONTENT_CHARS",
+    "REDACT_KEEP_RECENT_WRITES",
+    "REDACT_MIN_CONTENT_CHARS",
+    "PROJECT_FILES",
+    "READ_UNCHANGED_STUB_PREFIX",
+    "CHURN_FILE_WRITE_LIMIT",
+    "CHURN_COMMAND_FAIL_LIMIT",
+    "CHURN_READONLY_STREAK_LIMIT",
+    "CHURN_PLANNING_STREAK_LIMIT",
+    "CROSS_ROUND_REPEAT_LIMIT",
+]
+
+
+# ── Turn-level caps ─────────────────────────────────────────────────
+
+MAX_ROUNDS = 0
+"""Upper bound on round-trips the agent loop takes per turn. Each
+round = one model call + any tool dispatches that follow.
+
+`0` means NO HARD CAP — matches agent (`maxTurns` opt-in, default
+unlimited) and terminal coding tools (no per-turn limit). Loop termination is
+delegated to the targeted safety nets that catch REAL failure
+patterns rather than counting rounds:
+
+  - 3-in-a-row identical-call breaker  (`recent_tool_sigs`)
+  - same-tool > 10 in a turn           (`tool_name_counts`)
+  - file-edit > 3 same path            (`file_edit_counts`)
+  - investigation-spin (≥10 read-only) (`_readonly_streak`)
+  - looks-fine streak (≥3 rounds)      (`_looks_fine_streak`)
+  - MAX_THINKING_SECONDS / CHARS       (per-round thinking cap)
+  - empty-round nudge (no content/tools)
+  - `cancel_requested` + Ctrl+C        (user-initiated)
+
+Bumped through 20 → 50 → 0 on 2026-04-26 after observing legitimate
+"redesign this section" investigations need 10+ rounds, and that
+every pathological loop in our telemetry trips one of the targeted
+guards inside 15 rounds. MAX_ROUNDS as a hard cap was emergency
+insurance with no observed claims. Set to a positive integer to
+re-enable a hard ceiling (eval / batch / unattended modes may want
+this; interactive sessions don't)."""
+
+MAX_OUTPUT_TOKENS = -1
+"""Per-round generation cap. -1 = unlimited; the model stops at its
+natural EOS. This stays -1 deliberately: capping mid-stream truncates
+valid tool-call JSON into unparseable garbage, which then triggers a
+useless recovery round. A prior 5.8-minute round burn was caused by an
+8192 cap chopping a long-but-valid write_file call. So a small per-round
+token cap is the WRONG lever.
+
+The runaway backstop is NOT ctx-size. An earlier version of this note
+claimed `--ctx-size 32768` bounded prompt+generation so "the model can't
+run forever" — that is FALSE for long-context models. LocalCode launches
+Qwen (262K trained) with `--ctx-size 131072`; a 6K-token prompt then
+leaves ~125K tokens of generation headroom ≈ ~28 minutes of nonstop
+decode. A real 40-minute / no-output hang (thinking on, no answer emitted)
+was traced to exactly this.
+
+The primary control is llama.cpp's per-request `thinking_budget_tokens`: it
+forces the template's end-thinking sequence and lets the SAME generation move
+on to a tool call. Feature.THINKING_CAPS + MAX_THINKING_SECONDS / CHARS are
+compatibility backstops for templates whose thinking tags the server cannot
+identify. Leaving MAX_OUTPUT_TOKENS at -1 keeps valid long tool calls intact
+without leaving the reasoning channel unbounded."""
+
+
+# ── Thinking-phase safety caps ──────────────────────────────────────
+#
+# Bound how much reasoning Python will accept if the server-side token budget
+# cannot recognize the model's thinking delimiters. Either cap trips a
+# `_thinking_abort`. Exact periodic loops retry once with thinking disabled;
+# other runaways surface a clear user message.
+#
+# These are a RUNAWAY guard, not a reasoning budget. The earlier tight
+# values (90 s / 4000 chars ≈ 1000 tokens) aborted legitimate long
+# reasoning and were disabled 2026-04-27 (see features.THINKING_CAPS).
+# They are re-enabled now with far more generous bounds after a real
+# 29-minute / 94.8k-token runaway on Qwen Q8 with thinking on: the
+# cap must never touch normal reasoning, only a pathological loop.
+#
+#   * 600 s (10 min): a genuine slow-reason path on a heavy Q8 model
+#     (~50-75 tok/s) fits comfortably; a 29-minute loop does not.
+#   * 80000 chars (~20k reasoning tokens): well above any legitimate
+#     planning trace; the observed runaway was ~380k chars.
+#
+# With reasoning now streamed live in the TUI, the user also SEES a
+# runaway and can `esc` — the cap is the backstop for unattended /
+# headless runs where no one is watching.
+
+# NOTE: the CHAR cap is the real, speed-independent runaway guard (~20k
+# reasoning tokens); the structural loop detector catches periodic loops in
+# ~1s. The TIME cap is only a final backstop, and it must scale to the SLOWEST
+# model we ship: at ~15 tok/s (dense Qwen 3.8 27B Q8 / Muse Glimmer, not the
+# ~50-75 tok/s MoEs this was first tuned for), 80k chars ≈ 20k tokens ≈ 22 min
+# of legitimate reasoning. A 600s cap tripped that at ~5.7k tokens — aborting
+# NORMAL slow reasoning, the exact thing this cap must never do. 1800s (30 min)
+# keeps the char cap + loop detector as the real guards. Either way a trip now
+# recovers via a no-think retry (see loop.py), so the turn is never thrown away.
+MAX_THINKING_SECONDS = 1800
+MAX_THINKING_CHARS = 80000
+
+
+# ── Tool-result size policy ─────────────────────────────────────────
+
+RESULT_LIMITS: dict[str, int] = {
+    "grep": 20_000,
+    "bash": 30_000,
+    "read_file": 50_000,
+    "web_search": 10_000,
+    "default": 50_000,
+}
+"""Per-tool truncation budgets (chars). Tools whose payload exceeds
+their budget get truncated with a clear "[truncated N chars]" tail
+so the judge / user can tell content was dropped. Tune per tool
+because grep output and bash stdout have different density."""
+
+MAX_AGGREGATE_PER_TURN = 100_000
+"""Sum of tool-result chars across a single turn. If a turn ingests
+more than this across its tool calls, later tool calls get their
+results aggressively truncated or stubbed — prevents a single turn
+from blowing past the context window via 10× big grep results."""
+
+
+# ── Destructive-command detection ───────────────────────────────────
+
+DESTRUCTIVE_PATTERNS: list[str] = [
+    "rm -rf", "rm -r", "rmdir", "git push", "git reset --hard",
+    "sudo ", "pip install", "npm install", "brew install",
+    "docker rm", "kubectl delete", "DROP TABLE", "DELETE FROM",
+    "python ", "python3 ", "node ", "npm run", "npm start",
+]
+"""Prefixes that trigger the approval flow in the bash tool. Matching
+is substring-wise so `bash -c 'rm -rf foo'` still fires. NOT a
+security boundary — a determined user can bypass via e.g. `\\rm`
+or `eval` — but catches the common footgun cases."""
+
+
+# ── Context-management policy ───────────────────────────────────────
+
+COMPACT_KEEP_RECENT_TOOL_RESULTS = 4
+"""Number of most-recent tool_result messages to preserve verbatim
+before aging starts. Older tool_result payloads get replaced with a
+brief summary stub."""
+
+COMPACT_MIN_CONTENT_CHARS = 400
+"""Only tool_result messages longer than this get considered for
+aging. Short results (exit codes, one-line stdout) stay inline
+because they're cheap and often load-bearing."""
+
+REDACT_KEEP_RECENT_WRITES = 1
+"""Number of most-recent write_file/edit_file tool_call args to
+preserve verbatim. Older ones get their `content`/`new_string` args
+redacted with a stub telling the model to read_file the path if it
+needs the content. Prevents the ~10× context bloat that would
+otherwise accumulate from repeated full-file writes."""
+
+REDACT_MIN_CONTENT_CHARS = 400
+"""Threshold for redaction — small writes (short configs, tiny
+shims) stay inline because the savings aren't worth the indirection."""
+
+
+# ── Project-instruction files (load order matters) ──────────────────
+
+PROJECT_FILES: list[str] = ["LOCALCODE.md", "localcode.md", ".localcode.md"]
+"""Filenames the agent looks for at repo root for project-specific
+instructions. First match wins. Kept in this list so the agent
+behaviour is documented in one place and other callers (eval /
+tests / setup UI) can list them without duplicating the literal."""
+
+
+# ── Duplicate-read stub text ────────────────────────────────────────
+
+READ_UNCHANGED_STUB_PREFIX = (
+    "[FILE UNCHANGED — a later read_file call for this same path is in "
+    "history below with the current content. Scroll forward, or re-call "
+    "read_file if needed.]"
+)
+"""Replacement text for older duplicate read_file results, so the
+model sees "the content exists further down" rather than the raw
+bytes twice. `_redact_duplicate_reads` inserts this prefix."""
+
+
+# ── Semantic-churn thresholds ───────────────────────────────────────
+#
+# These catch the "thrashing without converging" pattern that the
+# byte-identical-call breakers miss: the model keeps WRITING a file
+# (different content each time) or keeps RE-RUNNING a failing command,
+# never reading the actual error and making a targeted fix. Distinct
+# from the exact-repeat guards (`recent_tool_sigs`, `success_counts`)
+# which only trip on identical args. Tuned conservatively so normal
+# multi-step flows (a couple of edits to one file, running a build
+# command twice while iterating) do NOT trip — only sustained churn.
+
+CHURN_FILE_WRITE_LIMIT = 3
+"""How many times the SAME path may be written/edited in one turn
+before we nudge "stop rewriting it, read the error and make a
+targeted fix." Counts every write/edit/append to the path regardless
+of whether content differs — semantic churn, not byte-identical
+repeats. 3 chosen because a legit flow is typically write-once then
+one corrective edit (2); a 3rd full rewrite of the same file in a
+turn is the churn signal (the real incident rewrote package.json ~5×)."""
+
+CHURN_COMMAND_FAIL_LIMIT = 3
+"""How many times the SAME command (keyed by its first token, e.g.
+`npm`) may FAIL in one turn before we nudge "read its error output
+and fix the root cause before re-running." 3 (not 2) so running a
+build/install command, fixing, and one more failure while iterating
+is tolerated; the 3rd failure of the same command family means the
+model is re-running without absorbing the error."""
+
+CHURN_READONLY_STREAK_LIMIT = 6
+"""Consecutive rounds of PURE read-only investigation (read_file /
+grep / glob / list_files / web_*) with no mutating or server action
+before we nudge "take a concrete action now." Tighter than the prior
+generic streak of 10: a 10-round read-only run is already 5+ minutes
+of the user staring at a frozen screen. 6 still allows reading the
+handful of files needed to understand a redesign before committing,
+but interrupts a genuine investigation spin sooner."""
+
+CHURN_PLANNING_STREAK_LIMIT = 4
+"""Consecutive rounds of PLANNING-WITHOUT-PROGRESS before we nudge
+"you've planned enough; take a concrete action now."
+
+A round counts toward this streak when ALL of:
+  • it changed NO new file this turn (changed_files count didn't grow),
+  • it ran NO build/test/verify command, and
+  • it produced thinking or narration content (i.e. the model was
+    reasoning/planning, not idle).
+
+This catches the model that re-derives the SAME plan across many rounds
+— lots of thinking, no concrete action — which the read-only-spin
+signal misses because that streak resets on any round with zero tool
+calls (a pure think-then-read-then-think alternation never accumulates
+a pure read-only streak). Set to 4 (one higher than the read-only
+limit's effective reach) so legitimate "read two files, think, read a
+third, then edit" flows do NOT trip: as soon as a round changes a file
+or runs a build, the streak resets to 0."""
+
+CROSS_ROUND_REPEAT_LIMIT = 4
+"""How many times the SAME (tool, canonical-args) call may run ACROSS the
+turn before we nudge "you already have this result — stop repeating it."
+
+The in-round breaker catches identical calls within ONE round; this catches
+the cross-ROUND spin the logs show — read_file on the same path 53x over many
+rounds, or a pkill->curl->read loop where each command succeeds (so the
+command-FAILURE breaker never trips). Crucially this only NUDGES — it never
+withholds the tool result (the 2026-04-29 read-dedup STUB starved legitimate
+debug re-reads and hung a turn 17 min; we do not repeat that). A write/edit to
+a path resets that path's read counts, so a legitimate read-after-edit isn't
+counted. 4 tolerates a couple of genuine re-looks before flagging a true loop."""