codna 0.1.36__tar.gz → 0.1.38__tar.gz

{codna-0.1.36 → codna-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codna
-Version: 0.1.36
+Version: 0.1.38
 Summary: Local-first repo intelligence and agent fixing for Codna.
 Author: Thyn
 Maintainer: Thyn

{codna-0.1.36 → codna-0.1.38}/codna/__init__.py

@@ -5,4 +5,4 @@ This package is the `codna` CLI. Users never touch "algenta" directly — the en
 is an internal dependency reached over HTTP.
 """
 
-__version__ = "0.1.36"
+__version__ = "0.1.38"

{codna-0.1.36 → codna-0.1.38}/codna/agent-core/run-server.bundle.mjs

@@ -256588,13 +256588,16 @@ function enabledToolPolicy() {
   return { enabled: true, autoApprove: true };
 }
 function defaultApprovalProfileForArgs(args) {
+  if (args.task_kind === "review") {
+    return "repository_review";
+  }
   if (exactRestoreDisablesPatchTools(args)) {
     return "local_validation";
   }
   return args.tool_profile === "no_exploration_local_validation" ? "local_validation" : DEFAULT_APPROVAL_PROFILE;
 }
 function resolveTaskKind(payload, taskSpec) {
-  return ensureEnumValue(payload.task_kind ?? taskSpec.task_kind, ["fix", "triage"], "task_kind", "fix");
+  return ensureEnumValue(payload.task_kind ?? taskSpec.task_kind, ["fix", "triage", "review"], "task_kind", "fix");
 }
 function requestedToolPolicies(value) {
   const input = asRecord(value);
@@ -256666,10 +256669,13 @@ function resolveSessionPolicy(payload, args) {
     policies.editor = disabledToolPolicy();
     policies.apply_patch = disabledToolPolicy();
   }
-  if (args.task_kind === "triage") {
+  if (args.task_kind === "triage" || args.task_kind === "review") {
     policies.editor = disabledToolPolicy();
     policies.apply_patch = disabledToolPolicy();
   }
+  if (args.task_kind === "review") {
+    policies.run_commands = disabledToolPolicy();
+  }
   if (profile === "repository_review") {
     policies.editor = disabledToolPolicy();
     policies.apply_patch = disabledToolPolicy();

{codna-0.1.36 → codna-0.1.38}/codna/agent-core/vendor/cline/algenta/policy.test.ts

@@ -105,6 +105,15 @@ test("server session policy disables write tools for triage tasks", () => {
 	expect(policy.toolPolicies.run_commands?.enabled).toBeUndefined();
 });
 
+test("server session policy defaults review tasks to repository_review and disables shell/writes", () => {
+	const policy = resolveSessionPolicy({}, { ...ARGS, task_kind: "review" } as never);
+	expect(policy.profile).toBe("repository_review");
+	expect(policy.allowedWriteScope).toEqual([]);
+	expect(policy.toolPolicies.editor?.enabled).toBe(false);
+	expect(policy.toolPolicies.apply_patch?.enabled).toBe(false);
+	expect(policy.toolPolicies.run_commands?.enabled).toBe(false);
+});
+
 test("session_id is path-validated; the artifact run id is server-generated (decoupled)", () => {
 	const ok = normalizeSessionPayload({ ...base, session_id: "sess-123" }, "owner");
 	expect(ok.sessionId).toBe("sess-123");
@@ -256,6 +265,15 @@ test("normalizeSessionPayload preserves explicit task_kind and rejects unknown v
 		"owner",
 	);
 	expect(triage.taskKind).toBe("triage");
+	const review = normalizeSessionPayload(
+		{
+			...base,
+			task_kind: "review",
+		},
+		"owner",
+	);
+	expect(review.taskKind).toBe("review");
+	expect(review.approvalProfile).toBe("repository_review");
 	expect(() =>
 		normalizeSessionPayload(
 			{

{codna-0.1.36 → codna-0.1.38}/codna/agent-core/vendor/cline/algenta/server/policy.ts

@@ -40,6 +40,9 @@ function enabledToolPolicy(): ToolPolicy {
 }
 
 function defaultApprovalProfileForArgs(args: RunAgentArgs): ApprovalProfile {
+	if (args.task_kind === "review") {
+		return "repository_review";
+	}
 	if (exactRestoreDisablesPatchTools(args)) {
 		return "local_validation";
 	}
@@ -54,7 +57,7 @@ function resolveTaskKind(
 ): AgentTaskKind {
 	return ensureEnumValue(
 		payload.task_kind ?? taskSpec.task_kind,
-		["fix", "triage"] as const,
+		["fix", "triage", "review"] as const,
 		"task_kind",
 		"fix",
 	);
@@ -161,10 +164,13 @@ export function resolveSessionPolicy(
 		policies.editor = disabledToolPolicy();
 		policies.apply_patch = disabledToolPolicy();
 	}
-	if (args.task_kind === "triage") {
+	if (args.task_kind === "triage" || args.task_kind === "review") {
 		policies.editor = disabledToolPolicy();
 		policies.apply_patch = disabledToolPolicy();
 	}
+	if (args.task_kind === "review") {
+		policies.run_commands = disabledToolPolicy();
+	}
 	if (profile === "repository_review") {
 		policies.editor = disabledToolPolicy();
 		policies.apply_patch = disabledToolPolicy();

{codna-0.1.36 → codna-0.1.38}/codna/fix_inputs.py

@@ -5,7 +5,9 @@ extraction and PR-body rendering. Split out of ``cli.py`` to keep it under the m
 from __future__ import annotations
 
 import os
+import shutil
 import subprocess
+import tempfile
 
 
 class FixInputError(Exception):
@@ -65,7 +67,79 @@ def _discover_failing_tests_for_fix(repo_dir: str, test_cmd: str | None):
         return discover_failing_tests(worktree.path, test_cmd)
 
 
-def resolve_issue(args):
+def _is_remote_repo_spec(repo: str) -> bool:
+    clean = (repo or "").strip()
+    return clean.startswith(("http://", "https://", "git@")) or clean.endswith(".git")
+
+
+def _run_git_for_remote_tests(args: list[str], *, cwd: str | None, env: dict[str, str] | None) -> None:
+    try:
+        proc = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise FixInputError(f"could not prepare remote checkout for --tests: {exc}") from exc
+    if proc.returncode != 0:
+        stderr = (proc.stderr or proc.stdout or "").strip()[-1000:]
+        raise FixInputError(f"could not prepare remote checkout for --tests: {stderr}")
+
+
+def _checkout_remote_ref(checkout: str, ref: str, *, repository_url: str, token: str | None) -> None:
+    from .packaged_git import _git_auth_env, _validated_ref
+
+    clean_ref = _validated_ref(ref)
+    env = _git_auth_env(repository_url, token)
+    fetch = subprocess.run(
+        ["git", "fetch", "--depth=1", "origin", clean_ref],
+        cwd=checkout,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=120,
+        check=False,
+    )
+    target = "FETCH_HEAD" if fetch.returncode == 0 else clean_ref
+    _run_git_for_remote_tests(["checkout", "--detach", target], cwd=checkout, env=env)
+    _run_git_for_remote_tests(["reset", "--hard", "HEAD"], cwd=checkout, env=env)
+    _run_git_for_remote_tests(["clean", "-fdx"], cwd=checkout, env=env)
+
+
+def _discover_remote_failing_tests_for_fix(args, github_token: str | None):
+    from .packaged_git import PackagedGitError, _git_auth_env, _reject_embedded_credentials
+
+    repo_url = getattr(args, "repo", "") or ""
+    try:
+        _reject_embedded_credentials(repo_url)
+        env = _git_auth_env(repo_url, github_token)
+    except PackagedGitError as exc:
+        raise FixInputError(str(exc)) from exc
+
+    root = tempfile.mkdtemp(prefix="codna-remote-test-discovery-")
+    checkout = os.path.join(root, "repo")
+    try:
+        clone_args = ["clone", "--no-tags"]
+        ref = getattr(args, "ref", None)
+        base_branch = getattr(args, "base_branch", None)
+        if not ref:
+            clone_args.append("--depth=1")
+            if base_branch:
+                clone_args.extend(["--single-branch", "--branch", base_branch])
+        clone_args.extend([repo_url, checkout])
+        _run_git_for_remote_tests(clone_args, cwd=None, env=env)
+        if ref:
+            _checkout_remote_ref(checkout, ref, repository_url=repo_url, token=github_token)
+        return _discover_failing_tests_for_fix(checkout, getattr(args, "test_cmd", None))
+    finally:
+        shutil.rmtree(root, ignore_errors=True)
+
+
+def resolve_issue(args, github_token: str | None = None):
     """Resolve ``(issue_text, failing_test_ids)`` from the fix args. Raises FixInputError on bad input.
 
     Precedence: ``--from-junit`` and ``--failing-test`` are explicit inputs; ``--tests`` auto-discovers
@@ -80,9 +154,13 @@ def resolve_issue(args):
         return (args.issue or issue), merged
 
     if getattr(args, "tests", False):
-        repo_dir = os.path.abspath(os.path.expanduser(getattr(args, "repo", ".") or "."))
         try:
-            issue, failing = _discover_failing_tests_for_fix(repo_dir, getattr(args, "test_cmd", None))
+            repo = getattr(args, "repo", ".") or "."
+            if _is_remote_repo_spec(repo):
+                issue, failing = _discover_remote_failing_tests_for_fix(args, github_token)
+            else:
+                repo_dir = os.path.abspath(os.path.expanduser(repo))
+                issue, failing = _discover_failing_tests_for_fix(repo_dir, getattr(args, "test_cmd", None))
         except Exception as exc:  # noqa: BLE001 - surface any discovery failure as a clean CLI error
             raise FixInputError(str(exc)) from exc
         merged = list(dict.fromkeys([*explicit_failing, *failing]))

{codna-0.1.36 → codna-0.1.38}/codna/fix_run.py

@@ -272,13 +272,6 @@ def run_fix(c, args) -> dict:
     from . import cli as _cli
     from .cli_errors import format_cli_error
 
-    try:
-        issue, failing = resolve_issue(args)
-    except FixInputError as exc:
-        _cli._die(str(exc))
-    if not issue and not failing:
-        _cli._die("`codna fix` needs --issue (or --from-junit / --tests) describing what's broken.")
-
     gh_token = (args.github_token or os.environ.get("CODNA_GITHUB_TOKEN") or os.environ.get("GITHUB_TOKEN"))
     open_pr = bool(getattr(args, "open_pr", False))
     apply = bool(getattr(args, "apply", False))
@@ -288,6 +281,13 @@ def run_fix(c, args) -> dict:
         if not gh_token:
             _cli._die("--open-pr needs a write token: pass --github-token or set GITHUB_TOKEN.")
 
+    try:
+        issue, failing = resolve_issue(args, github_token=gh_token)
+    except FixInputError as exc:
+        _cli._die(str(exc))
+    if not issue and not failing:
+        _cli._die("`codna fix` needs --issue (or --from-junit / --tests) describing what's broken.")
+
     verify = (bool(getattr(args, "tests", False)) or bool(getattr(args, "test_cmd", None))) and apply and not open_pr
     max_iterations = max(1, int(getattr(args, "max_iterations", 1) or 1)) if verify else 1
 

{codna-0.1.36 → codna-0.1.38}/codna/memory.py

@@ -623,17 +623,33 @@ def _semantic_rerank(query: str, cands: list, mem) -> list:
 
 def repo_id_for(repo_path: str) -> str:
     """Stable repo identity for partitioning: ``github.com/owner/repo`` if there's an origin remote,
-    else the absolute path (so memory works on any local checkout, not only GitHub repos)."""
+    else the absolute path (so memory works on any local checkout, not only GitHub repos).
+
+    Git deliberately walks up parent directories. That is correct for commands run at a repo root, but
+    unsafe for arbitrary local paths: a temporary non-git repo under this source checkout must not inherit
+    Codna's own GitHub remote and collide with other paths in a shared collection.
+    """
+    local = os.path.abspath(os.path.expanduser(repo_path))
     try:
-        out = subprocess.run(["git", "-C", repo_path, "remote", "get-url", "origin"],
-                             capture_output=True, text=True, timeout=5)
-        if out.returncode == 0:
+        root = subprocess.run(
+            ["git", "-C", local, "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        git_root = os.path.abspath(os.path.expanduser(root.stdout.strip())) if root.returncode == 0 else ""
+        if git_root and os.path.realpath(git_root) == os.path.realpath(local):
+            out = subprocess.run(["git", "-C", local, "remote", "get-url", "origin"],
+                                 capture_output=True, text=True, timeout=5)
+        else:
+            out = None
+        if out is not None and out.returncode == 0:
             m = re.search(r"github\.com[:/]([^/]+/[^/.]+)", out.stdout)
             if m:
                 return f"github.com/{m.group(1)}"
     except (OSError, subprocess.SubprocessError):
         pass
-    return os.path.abspath(os.path.expanduser(repo_path))
+    return local
 
 
 def _git(repo_path: str, *args: str) -> str | None:

{codna-0.1.36 → codna-0.1.38}/codna/packaged_agent_runner.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import shutil
 import subprocess
 from dataclasses import dataclass
@@ -119,8 +120,9 @@ class SidecarPackagedAgentRunner:
 
 
 def _sidecar_payload(request: PackagedAgentRunRequest, workspace: Path) -> dict[str, Any]:
-    timeout_ms = _dynamic_timeout_ms(request.snapshot)
-    max_turns = _env_int("ALGENTA_AGENT_MAX_TURNS", default=4, minimum=1, maximum=50)
+    task_kind = _validated_task_kind(request.task_kind)
+    timeout_ms = _timeout_ms_for_request(request)
+    max_turns = _max_turns_for_request(request)
     requested_provider, requested_model = _provider_model_from_request(request.model)
     provider = (
         os.environ.get("ALGENTA_AGENT_PROVIDER")
@@ -136,19 +138,20 @@ def _sidecar_payload(request: PackagedAgentRunRequest, workspace: Path) -> dict[
         "working_dir": str(workspace),
         "channel": "cli",
         "repository_scope": request.repository_id,
-        "task_kind": "fix",
-        "tool_profile": os.environ.get(
-            "ALGENTA_REPOSITORY_AGENT_TOOL_PROFILE",
-            "no_exploration_local_validation",
-        ),
+        "task_kind": task_kind,
+        "tool_profile": _tool_profile_for_task(task_kind),
         "limits": {"maxIterations": max_turns, "timeoutMs": timeout_ms},
         "task_spec": {
             "issue_text": _issue_text_with_guidance(request),
+            "task_kind": task_kind,
             "engine": {"enabled": False},
         },
         "injected_context": _injected_context(request),
-        "allowed_write_paths": _allowed_write_paths(request),
+        "allowed_write_paths": [] if task_kind == "review" else _allowed_write_paths(request),
     }
+    if task_kind == "review":
+        payload["approval_profile"] = "repository_review"
+        payload["allowed_write_scope"] = []
     if provider:
         payload["provider"] = provider
     if model:
@@ -156,6 +159,40 @@ def _sidecar_payload(request: PackagedAgentRunRequest, workspace: Path) -> dict[
     return payload
 
 
+def _validated_task_kind(value: str) -> str:
+    task_kind = (value or "fix").strip()
+    if task_kind not in {"fix", "triage", "review"}:
+        raise PackagedRepositoryAdvancedError(
+            "agent_task_kind_invalid",
+            "Unsupported local agent task kind.",
+            {"task_kind": value, "allowed": ["fix", "triage", "review"]},
+        )
+    return task_kind
+
+
+def _tool_profile_for_task(task_kind: str) -> str | None:
+    if task_kind == "review":
+        return None
+    return os.environ.get(
+        "ALGENTA_REPOSITORY_AGENT_TOOL_PROFILE",
+        "no_exploration_local_validation",
+    )
+
+
+def _timeout_ms_for_request(request: PackagedAgentRunRequest) -> int:
+    value = request.signals.get("review_timeout_s") if request.task_kind == "review" else None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return _env_int_value(str(int(value * 1000)), minimum=30_000, maximum=3_600_000)
+    return _dynamic_timeout_ms(request.snapshot)
+
+
+def _max_turns_for_request(request: PackagedAgentRunRequest) -> int:
+    value = request.signals.get("review_max_iterations") if request.task_kind == "review" else None
+    if isinstance(value, int) and not isinstance(value, bool):
+        return max(1, min(50, value))
+    return _env_int("ALGENTA_AGENT_MAX_TURNS", default=4, minimum=1, maximum=50)
+
+
 def _provider_model_from_request(model: str) -> tuple[str | None, str | None]:
     requested = (model or "").strip()
     if not requested or requested == _VERIFIED_AGENTIC_MODEL:
@@ -187,6 +224,14 @@ def _project_guidance(request: PackagedAgentRunRequest) -> str | None:
 def _issue_text_with_guidance(request: PackagedAgentRunRequest) -> str:
     """The Cline agent's task, with project guidance appended so the agent honors it while editing."""
     allowed = _allowed_write_paths(request)
+    test_guidance = ""
+    if _is_test_driven_fix(request.signals) and not _explicit_test_edit_request(request.signals):
+        test_guidance = (
+            "\n\n[CODNA FAILING-TEST FIX CONTRACT]\n"
+            "The failing tests are verification signals, not the target fix. "
+            "Do not modify test/spec files unless the user explicitly states that the test expectation is wrong. "
+            "Fix the production/source code that makes the tests fail."
+        )
     path_guidance = ""
     if allowed:
         path_guidance = (
@@ -198,10 +243,10 @@ def _issue_text_with_guidance(request: PackagedAgentRunRequest) -> str:
         )
     guidance = _project_guidance(request)
     if not guidance:
-        return request.issue_text + path_guidance
+        return request.issue_text + test_guidance + path_guidance
     return (f"{request.issue_text}\n\n"
             "[PROJECT GUIDANCE — honor these project rules while making changes]\n"
-            f"{guidance}{path_guidance}")
+            f"{guidance}{test_guidance}{path_guidance}")
 
 
 def _injected_context(request: PackagedAgentRunRequest) -> dict[str, Any]:
@@ -241,6 +286,9 @@ def _allowed_write_paths(request: PackagedAgentRunRequest) -> list[str]:
     for item in request.evidence_bundle.get("evidence_items", []):
         if isinstance(item, dict):
             _append_path(output, item.get("file_path"))
+    if _is_test_driven_fix(request.signals) and not _explicit_test_edit_request(request.signals):
+        non_test_paths = [path for path in output if not _is_test_path(path)]
+        return non_test_paths
     return output
 
 
@@ -255,6 +303,36 @@ def _append_path(output: list[str], value: Any) -> None:
         output.append(normalized)
 
 
+def _is_test_driven_fix(signals: Mapping[str, Any]) -> bool:
+    if _string_list(signals.get("failing_tests")):
+        return True
+    issue = signals.get("issue_text")
+    return isinstance(issue, str) and bool(
+        re.search(r"\b(failing test|tests? are failing|unittest|pytest|junit|assertionerror)\b", issue, re.I)
+    )
+
+
+def _explicit_test_edit_request(signals: Mapping[str, Any]) -> bool:
+    issue = signals.get("issue_text")
+    if not isinstance(issue, str):
+        return False
+    return bool(
+        re.search(r"\b(update|change|rewrite|correct)\s+(the\s+)?(test|tests|assertion|expectation)s?\b", issue, re.I)
+        or re.search(r"\b(test|tests|assertion|expectation)s?\s+(is|are)\s+(wrong|incorrect|outdated)\b", issue, re.I)
+    )
+
+
+def _is_test_path(path: str) -> bool:
+    normalized = path.replace("\\", "/").lower()
+    parts = normalized.split("/")
+    name = parts[-1] if parts else normalized
+    return (
+        any(part in {"test", "tests", "__tests__", "spec", "specs"} for part in parts[:-1])
+        or name.startswith("test_")
+        or name.endswith(("_test.py", "_spec.py", ".test.js", ".test.ts", ".spec.js", ".spec.ts"))
+    )
+
+
 def _dynamic_timeout_ms(snapshot: Mapping[str, Any]) -> int:
     raw_tokens = _int_value(snapshot.get("raw_repo_token_estimate"))
     files = _int_value(snapshot.get("snapshot_file_count") or snapshot.get("file_count"))
@@ -282,7 +360,7 @@ def _prepare_workspace(
     workspace.parent.mkdir(parents=True, exist_ok=True)
     if _is_clean_git_repo(repo_root) and _git_worktree_add(repo_root, workspace):
         return _Workspace(path=workspace, kind="git_worktree")
-    shutil.copytree(repo_root, workspace, ignore=_copy_ignore)
+    shutil.copytree(repo_root, workspace, ignore=_copy_ignore_for(runtime_root))
     _init_baseline_git_repo(workspace)
     return _Workspace(path=workspace, kind="copy")
 
@@ -420,8 +498,27 @@ def _git_worktree_add(repo_root: Path, workspace: Path) -> bool:
     return False
 
 
-def _copy_ignore(_directory: str, names: list[str]) -> set[str]:
-    return {name for name in names if name in _WORKSPACE_SKIP_DIRS}
+def _copy_ignore_for(runtime_root: Path):
+    runtime_root = runtime_root.expanduser().resolve()
+
+    def _copy_ignore(directory: str, names: list[str]) -> set[str]:
+        directory_path = Path(directory).resolve()
+        ignored = {name for name in names if name in _WORKSPACE_SKIP_DIRS}
+        for name in names:
+            child = (directory_path / name).resolve()
+            if child == runtime_root or _is_relative_to(child, runtime_root):
+                ignored.add(name)
+        return ignored
+
+    return _copy_ignore
+
+
+def _is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
 
 
 def _parse_final_frame(body: str, *, sidecar_url: str) -> dict[str, Any]:

{codna-0.1.36 → codna-0.1.38}/codna/packaged_repository_advanced.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import json
 import os
+import re
 import subprocess
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -32,6 +33,7 @@ class PackagedAgentRunRequest:
     signals: dict[str, Any]
     evidence_bundle: dict[str, Any]
     snapshot: dict[str, Any]
+    task_kind: str = "fix"
 
 
 @dataclass(frozen=True)
@@ -102,13 +104,21 @@ class PackagedRepositoryAdvanced:
                     "session_id": result.session_id,
                 },
             )
+        changed_files = _changed_files_from_patch(patch_diff)
+        _validate_patch_scope_for_test_driven_fix(
+            signals=run_request.signals,
+            changed_files=changed_files,
+            repository_id=repository_id,
+            snapshot_id=str(snapshot["snapshot_id"]),
+            agent_run_id=result.agent_run_id,
+            session_id=result.session_id,
+        )
         created_at = _utc_now()
         patch_id = "patch_" + _sha256_text(
             f"{repository_id}|{snapshot['snapshot_id']}|{patch_diff}"
         )[:24]
         patch_path = self._patch_dir / f"{patch_id}.diff"
         _atomic_write_text(patch_path, patch_diff + "\n")
-        changed_files = _changed_files_from_patch(patch_diff)
         plan_id = "plan_" + _sha256_text(
             f"{repository_id}|{snapshot['snapshot_id']}|{patch_id}|{issue_text}"
         )[:24]
@@ -533,6 +543,71 @@ def _changed_files_from_patch(patch_diff: str) -> list[str]:
     return files
 
 
+def _validate_patch_scope_for_test_driven_fix(
+    *,
+    signals: Mapping[str, Any],
+    changed_files: list[str],
+    repository_id: str,
+    snapshot_id: str,
+    agent_run_id: str | None,
+    session_id: str | None,
+) -> None:
+    if not _is_test_driven_fix(signals) or not changed_files:
+        return
+    if _explicit_test_edit_request(signals):
+        return
+    if any(not _is_test_path(path) for path in changed_files):
+        return
+    raise PackagedRepositoryAdvancedError(
+        "local_repository_agent_test_only_patch",
+        "Codna refused a test-only patch for a failing-test fix. Fix source code, not the test, "
+        "or pass an explicit --issue stating that the test expectation itself is wrong.",
+        {
+            "repository_id": repository_id,
+            "snapshot_id": snapshot_id,
+            "changed_files": changed_files,
+            "agent_run_id": agent_run_id,
+            "session_id": session_id,
+        },
+    )
+
+
+def _is_test_driven_fix(signals: Mapping[str, Any]) -> bool:
+    if _string_list(signals.get("failing_tests")):
+        return True
+    issue = signals.get("issue_text")
+    return isinstance(issue, str) and bool(
+        re.search(r"\b(failing test|tests? are failing|unittest|pytest|junit|assertionerror)\b", issue, re.I)
+    )
+
+
+def _explicit_test_edit_request(signals: Mapping[str, Any]) -> bool:
+    issue = signals.get("issue_text")
+    if not isinstance(issue, str):
+        return False
+    return bool(
+        re.search(r"\b(update|change|rewrite|correct)\s+(the\s+)?(test|tests|assertion|expectation)s?\b", issue, re.I)
+        or re.search(r"\b(test|tests|assertion|expectation)s?\s+(is|are)\s+(wrong|incorrect|outdated)\b", issue, re.I)
+    )
+
+
+def _is_test_path(path: str) -> bool:
+    normalized = path.replace("\\", "/").lower()
+    parts = normalized.split("/")
+    name = parts[-1] if parts else normalized
+    return (
+        any(part in {"test", "tests", "__tests__", "spec", "specs"} for part in parts[:-1])
+        or name.startswith("test_")
+        or name.endswith(("_test.py", "_spec.py", ".test.js", ".test.ts", ".spec.js", ".spec.ts"))
+    )
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, str) and item.strip()]
+
+
 def _changed_line_count(patch_diff: str) -> int:
     count = 0
     for line in patch_diff.splitlines():