devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/execution/gated_write.py

@@ -0,0 +1,203 @@
+"""Policy-gated file writes shared by CLI and MCP."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import subprocess
+from pathlib import Path
+
+from devcouncil.execution.hook_policy import HookPolicy
+from devcouncil.execution.lease_validation import require_valid_lease
+from devcouncil.integrations.mcp.util import (
+    GIT_APPLY_TIMEOUT_SECONDS,
+    diff_target_paths,
+    is_git_repo,
+    within_root,
+)
+from devcouncil.storage.native import FileChangeRepository, TaskLeaseRepository
+from devcouncil.storage.repositories import TaskRepository
+
+
+def _explicitly_planned(path: str, task) -> bool:  # noqa: ANN001
+    normalized = path.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    return any(
+        normalized == planned.path.replace("\\", "/")
+        or fnmatch.fnmatch(normalized, planned.path.replace("\\", "/"))
+        for planned in task.planned_files
+    )
+
+
+def write_file_payload(
+    project_root: Path,
+    *,
+    task_id: str,
+    lease_token: str,
+    rel_path: str,
+    content: str,
+) -> dict:
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    with db.get_session() as session:
+        lease_error = require_valid_lease(session, task_id, lease_token)
+        if lease_error:
+            return lease_error
+        lease_record = TaskLeaseRepository(session).active_for_task(task_id)
+        assert lease_record is not None
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            return {"ok": False, "error": f"Task {task_id} not found.", "code": "not_found", "task_id": task_id}
+
+        target = within_root(project_root, rel_path)
+        if target is None:
+            reason = "path escapes the project root"
+            FileChangeRepository(session).record(
+                rel_path, "write", False, task_id=task_id, lease_id=lease_record.id, reason=reason,
+            )
+            return {
+                "ok": False, "task_id": task_id, "applied_files": [],
+                "rejected_files": [{"path": rel_path, "reason": reason}],
+            }
+
+        if not _explicitly_planned(rel_path, task):
+            reason = f"Task {task_id} does not explicitly authorize changes to {rel_path}."
+            FileChangeRepository(session).record(
+                rel_path, "write", False, task_id=task_id, lease_id=lease_record.id, reason=reason,
+            )
+            return {
+                "ok": False, "task_id": task_id, "applied_files": [],
+                "rejected_files": [{"path": rel_path, "reason": reason}],
+            }
+
+        decision = HookPolicy(project_root=project_root).evaluate_file_write(rel_path, task, content=content)
+        if not decision.allowed:
+            FileChangeRepository(session).record(
+                rel_path, "write", False, task_id=task_id, lease_id=lease_record.id, reason=decision.reason,
+            )
+            return {
+                "ok": False, "task_id": task_id, "applied_files": [],
+                "rejected_files": [{"path": rel_path, "reason": decision.reason}],
+            }
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            tmp = target.with_name(target.name + ".devcouncil-tmp")
+            tmp.write_text(content, encoding="utf-8")
+            os.replace(tmp, target)
+        except OSError as exc:
+            return {"ok": False, "error": f"Write failed: {exc}", "code": "write_failed", "task_id": task_id}
+        FileChangeRepository(session).record(
+            rel_path, "write", True, task_id=task_id, lease_id=lease_record.id, reason=decision.reason,
+        )
+        return {
+            "ok": True, "task_id": task_id, "applied_files": [rel_path], "rejected_files": [],
+        }
+
+
+def apply_patch_payload(
+    project_root: Path,
+    *,
+    task_id: str,
+    lease_token: str,
+    unified_diff: str,
+) -> dict:
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    if not is_git_repo(project_root):
+        return {
+            "ok": False,
+            "error": "apply_patch requires a git repository. Use write_file instead.",
+            "code": "not_a_git_repo",
+            "task_id": task_id,
+        }
+    targets = diff_target_paths(unified_diff)
+    if not targets:
+        return {"ok": False, "error": "No target files found in the diff.", "code": "empty_patch", "task_id": task_id}
+
+    with db.get_session() as session:
+        lease_error = require_valid_lease(session, task_id, lease_token)
+        if lease_error:
+            return lease_error
+        lease_record = TaskLeaseRepository(session).active_for_task(task_id)
+        assert lease_record is not None
+        task = TaskRepository(session).get_by_id(task_id)
+        if not task:
+            return {"ok": False, "error": f"Task {task_id} not found.", "code": "not_found", "task_id": task_id}
+
+        policy = HookPolicy(project_root=project_root)
+        rejected: list[dict[str, str]] = []
+        for path in targets:
+            if within_root(project_root, path) is None:
+                rejected.append({"path": path, "reason": "path escapes the project root"})
+                continue
+            if not _explicitly_planned(path, task):
+                rejected.append({
+                    "path": path,
+                    "reason": f"Task {task_id} does not explicitly authorize changes to {path}.",
+                })
+                continue
+            decision = policy.evaluate_file_write(path, task)
+            if not decision.allowed:
+                rejected.append({"path": path, "reason": decision.reason})
+        if rejected:
+            for item in rejected:
+                FileChangeRepository(session).record(
+                    item["path"], "apply_patch", False, task_id=task_id, lease_id=lease_record.id, reason=item["reason"],
+                )
+            return {
+                "ok": False, "task_id": task_id, "applied_files": [], "rejected_files": rejected,
+            }
+
+        patch_path = project_root / ".devcouncil" / f"mcp-apply-{lease_record.id}.patch"
+        patch_path.parent.mkdir(parents=True, exist_ok=True)
+        patch_path.write_text(unified_diff, encoding="utf-8")
+        try:
+            check = subprocess.run(
+                ["git", "apply", "--check", "--ignore-whitespace", str(patch_path)],
+                cwd=project_root, capture_output=True, text=True,
+                timeout=GIT_APPLY_TIMEOUT_SECONDS,
+            )
+            if check.returncode != 0:
+                return {
+                    "ok": False,
+                    "error": f"Patch does not apply cleanly: {check.stderr.strip()}",
+                    "code": "patch_rejected",
+                    "task_id": task_id,
+                }
+            applied = subprocess.run(
+                ["git", "apply", "--ignore-whitespace", str(patch_path)],
+                cwd=project_root, capture_output=True, text=True,
+                timeout=GIT_APPLY_TIMEOUT_SECONDS,
+            )
+            if applied.returncode != 0:
+                return {
+                    "ok": False,
+                    "error": f"Patch apply failed: {applied.stderr.strip()}",
+                    "code": "patch_failed",
+                    "task_id": task_id,
+                }
+        finally:
+            try:
+                patch_path.unlink()
+            except OSError:
+                pass
+        for path in targets:
+            FileChangeRepository(session).record(
+                path, "apply_patch", True, task_id=task_id, lease_id=lease_record.id, reason="policy allowed",
+            )
+        return {
+            "ok": True, "task_id": task_id, "applied_files": targets, "rejected_files": [],
+        }

package/src/devcouncil/execution/handoff.py

@@ -12,6 +12,7 @@ from devcouncil.execution.checkpoints import CheckpointService
 from devcouncil.storage.db import get_db
 from devcouncil.storage.native import AgentHandoffRepository, SemanticDiffRepository, TaskLeaseRepository
 from devcouncil.storage.repositories import EvidenceRepository, GapRepository, RequirementRepository, TaskRepository
+from devcouncil.utils.json_persist import write_model_json
 from devcouncil.verification.verifier import Verifier
 
 
@@ -78,7 +79,7 @@ class HandoffService:
             instruction=instruction,
             created_at=datetime.now(timezone.utc).isoformat(),
         )
-        manifest_path.write_text(manifest.model_dump_json(indent=2), encoding="utf-8")
+        write_model_json(manifest_path, manifest)
 
         status = "manifest_only"
         with db.get_session() as session:

package/src/devcouncil/execution/hook_policy.py

@@ -1,4 +1,5 @@
 import fnmatch
+import logging
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -13,6 +14,8 @@ from devcouncil.execution.policy_engine import (
 )
 from devcouncil.utils.redaction import SECRET_PATTERNS
 
+logger = logging.getLogger(__name__)
+
 # Splits a shell command into the segments a shell would execute independently, on
 # the chaining/pipe/sequence operators. We deliberately do NOT try to parse quoting
 # perfectly — any operator we miss only makes us evaluate a *larger* segment as a
@@ -56,12 +59,23 @@ class HookPolicy:
         try:
             from devcouncil.app.config import load_config
 
-            execution = load_config(self.project_root).execution
-            configured = getattr(execution, "global_allowed_commands", None)
+            config = load_config(self.project_root)
+            # Same derivation as the run command's PermissionPolicy: the project's
+            # configured test/lint/typecheck commands are repo-wide allowed.
+            allowed = [
+                str(item)
+                for item in (config.commands.test + config.commands.lint + config.commands.typecheck)
+            ]
+            # Forward-compat: honor an explicit execution.global_allowed_commands
+            # if the config schema ever grows one.
+            configured = getattr(config.execution, "global_allowed_commands", None)
             if isinstance(configured, (list, tuple)):
-                return [str(item) for item in configured]
-        except Exception:
-            pass
+                allowed.extend(str(item) for item in configured)
+            return allowed
+        except Exception as e:
+            # Fail-closed is safe, but a silently dropped allowlist makes every
+            # configured command deny with no visible cause.
+            logger.warning("Failed to load global allowed commands from config, gate uses empty allowlist: %s", e)
         return []
 
     secret_path_patterns = SECRET_PATH_PATTERNS

package/src/devcouncil/execution/lease_ops.py

@@ -0,0 +1,177 @@
+"""Task lease operations shared by CLI and MCP."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.execution.lease_validation import diagnose_lease, lease_error_payload, LeaseCode
+from devcouncil.integrations.mcp.util import allowed_next_tools, lease_ttl_seconds
+from devcouncil.storage.native import TaskLeaseRepository
+from devcouncil.storage.repositories import GapRepository, RequirementRepository, TaskRepository
+from devcouncil.utils.json_persist import read_json
+
+logger = logging.getLogger(__name__)
+
+
+def _refresh_stale_map_if_needed(project_root: Path) -> bool:
+    """Regenerate ``repo_map.json`` when stale, before prompt/baseline."""
+    from devcouncil.indexing.map_refresh import refresh_stale_map_if_needed
+
+    return refresh_stale_map_if_needed(project_root, on_checkout=True, on_verify=False)
+
+
+def checkout_task_payload(
+    project_root: Path,
+    *,
+    task_id: str,
+    client_id: str,
+    agent: str | None = None,
+    force: bool = False,
+) -> dict:
+    """Acquire a task lease and return scope for gated write tools."""
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    with db.get_session() as session:
+        task_repo = TaskRepository(session)
+        task = task_repo.get_by_id(task_id)
+        if not task:
+            return {"ok": False, "error": f"Task {task_id} not found.", "code": "not_found", "task_id": task_id}
+        lease_repo = TaskLeaseRepository(session)
+        try:
+            lease = lease_repo.acquire(
+                task_id,
+                owner=f"mcp:{client_id}",
+                agent=agent,
+                client_id=client_id,
+                ttl_seconds=lease_ttl_seconds(project_root),
+                force=force,
+            )
+        except ValueError as exc:
+            return {"ok": False, "error": str(exc), "code": "lease_conflict", "task_id": task_id}
+        # Refresh stale map BEFORE prompt + liveness baseline so both see fresh
+        # fingerprints. Write-once baseline semantics are unchanged (snapshot still
+        # skips when a complete baseline already exists).
+        _refresh_stale_map_if_needed(project_root)
+        prompt = PromptBuilder(project_root).build_task_prompt(task, RequirementRepository(session).get_all())
+        semantic = None
+        semantic_path = project_root / ".devcouncil" / "semantic" / task_id / "before.json"
+        if semantic_path.exists():
+            semantic = read_json(semantic_path)
+        # Snapshot liveness at checkout so verify can ratchet against stranded
+        # pre-existing code. Write-once (skip if complete baseline exists).
+        # Best-effort; never blocks checkout.
+        try:
+            from devcouncil.verification.checks.liveness_ratchet import (
+                snapshot_liveness_baseline,
+            )
+
+            snapshot_liveness_baseline(project_root, task_id, reset=False)
+        except Exception:
+            pass
+        return {
+            "ok": True,
+            "lease_token": lease.lease_token,
+            "task_id": task.id,
+            "status": task.status,
+            "expires_at": lease.expires_at,
+            "prompt": prompt,
+            "planned_files": [f.model_dump() for f in task.planned_files],
+            "allowed_commands": task.allowed_commands,
+            "expected_tests": task.expected_tests,
+            "semantic_context": semantic,
+            "allowed_next_tools": allowed_next_tools(
+                "running",
+                bool(GapRepository(session).get_blocking_for_task(task_id)),
+            ),
+        }
+
+
+def release_task_payload(project_root: Path, *, task_id: str, lease_token: str) -> dict:
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    with db.get_session() as session:
+        released = TaskLeaseRepository(session).release(task_id, lease_token)
+        if not released:
+            code, message = diagnose_lease(session, task_id, lease_token)
+            if code is LeaseCode.VALID:
+                return {"ok": False, "error": "Lease already released.", "code": "invalid_lease", "task_id": task_id}
+            return lease_error_payload(code, message, task_id)
+        try:
+            from devcouncil.verification.checks.liveness_ratchet import (
+                delete_liveness_baseline,
+            )
+
+            delete_liveness_baseline(project_root, task_id)
+        except Exception:
+            pass
+        return {"ok": True, "task_id": task_id, "released": True}
+
+
+def renew_lease_payload(
+    project_root: Path,
+    *,
+    task_id: str,
+    lease_token: str,
+    ttl_seconds: int | None = None,
+) -> dict:
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    ttl = ttl_seconds if ttl_seconds is not None else lease_ttl_seconds(project_root)
+    with db.get_session() as session:
+        renewed_lease = TaskLeaseRepository(session).renew(task_id, lease_token, ttl)
+        if renewed_lease is None:
+            code, message = diagnose_lease(session, task_id, lease_token)
+            if code is LeaseCode.VALID:
+                return {"ok": False, "error": "Lease renew failed.", "code": "invalid_lease", "task_id": task_id}
+            return lease_error_payload(code, message, task_id)
+        return {
+            "ok": True,
+            "task_id": task_id,
+            "expires_at": renewed_lease.expires_at,
+            "ttl_seconds": ttl,
+        }
+
+
+def list_leases_payload(project_root: Path, *, active_only: bool = True) -> dict:
+    from devcouncil.cli.commands.init import initialize_project
+    from devcouncil.storage.db import get_db
+
+    initialize_project(project_root, quiet=True)
+    db = get_db(project_root)
+    if not db:
+        return {"ok": False, "error": "DevCouncil state is unavailable in this directory.", "code": "not_initialized"}
+
+    with db.get_session() as session:
+        pairs = TaskLeaseRepository(session).list_leases(active_only=active_only)
+    leases = [
+        {
+            "task_id": lease.task_id,
+            "owner": lease.owner,
+            "agent": lease.agent,
+            "status": lease.status,
+            "expires_at": lease.expires_at,
+            "expired": expired,
+        }
+        for lease, expired in pairs
+    ]
+    return {"ok": True, "leases": leases, "count": len(leases)}

package/src/devcouncil/execution/lease_validation.py

@@ -0,0 +1,71 @@
+"""Lease diagnosis for MCP/CLI gates — distinguish expired vs invalid vs conflict."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from sqlmodel import Session, col, select
+
+from devcouncil.storage.models import TaskLeaseModel
+from devcouncil.storage.native import TaskLeaseRepository
+
+
+class LeaseCode(str, Enum):
+    VALID = "valid"
+    LEASE_EXPIRED = "lease_expired"
+    INVALID_LEASE = "invalid_lease"
+    LEASE_HELD_BY_OTHER = "lease_held_by_other"
+
+
+def diagnose_lease(session: Session, task_id: str, lease_token: str) -> tuple[LeaseCode, str]:
+    """Classify a lease token for actionable agent recovery."""
+    repo = TaskLeaseRepository(session)
+    active = repo.active_for_task(task_id)
+    if active is not None:
+        if active.lease_token == lease_token:
+            return LeaseCode.VALID, ""
+        holder = active.owner or active.client_id or "another agent"
+        return (
+            LeaseCode.LEASE_HELD_BY_OTHER,
+            f"Task {task_id} is held by {holder}. Pick another task or wait for release.",
+        )
+
+    stmt = (
+        select(TaskLeaseModel)
+        .where(TaskLeaseModel.task_id == task_id)
+        .where(TaskLeaseModel.lease_token == lease_token)
+        .order_by(col(TaskLeaseModel.created_at).desc())
+    )
+    prior = session.exec(stmt).first()
+    if prior is not None and prior.status in {"stale", "released"}:
+        return (
+            LeaseCode.LEASE_EXPIRED,
+            "Lease TTL expired. Check out the task again with devcouncil_checkout_task.",
+        )
+    return LeaseCode.INVALID_LEASE, "Invalid lease token."
+
+
+def lease_error_payload(code: LeaseCode, message: str, task_id: str) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "error": message,
+        "code": code.value,
+        "task_id": task_id,
+    }
+    if code is LeaseCode.LEASE_EXPIRED:
+        payload["suggested_action"] = "checkout_again"
+        payload["suggested_tool"] = "devcouncil_checkout_task"
+        payload["hint"] = "Renew only works before TTL expiry; call checkout again after expiry."
+    elif code is LeaseCode.LEASE_HELD_BY_OTHER:
+        payload["suggested_action"] = "pick_other_task"
+        payload["suggested_tool"] = "devcouncil_next_task"
+    return payload
+
+
+def require_valid_lease(session: Session, task_id: str, lease_token: str) -> dict[str, Any] | None:
+    """Return an error payload when the lease is not valid, else None."""
+    code, message = diagnose_lease(session, task_id, lease_token)
+    if code is LeaseCode.VALID:
+        return None
+    return lease_error_payload(code, message, task_id)

package/src/devcouncil/execution/patch.py

@@ -6,6 +6,8 @@ from devcouncil.app.errors import ExecutionError
 
 logger = logging.getLogger(__name__)
 
+_GIT_APPLY_TIMEOUT_SECONDS = 120
+
 
 class PatchEngine:
     """Handles applying unified diff patches to the codebase."""
@@ -67,6 +69,7 @@ class PatchEngine:
                     text=True,
                     encoding="utf-8",
                     errors="replace",
+                    timeout=_GIT_APPLY_TIMEOUT_SECONDS,
                 )
                 if proc.returncode == 0:
                     logger.info("Patch applied (git apply %s)", " ".join(extra_args) or "strict")

package/src/devcouncil/execution/permissions.py

@@ -34,6 +34,7 @@ class PermissionManager:
                 lines = ignore_file.read_text().splitlines()
                 return [line.strip() for line in lines if line.strip() and not line.startswith("#")]
             except Exception:
+                logger.debug("Failed to read .devcouncilignore", exc_info=True)
                 pass
         return []