devcouncil 0.1.1 → 0.2.0

package/src/devcouncil/executors/coding_cli.py

@@ -1,14 +1,33 @@
+import json
+import os
+import queue
 import shutil
 import subprocess
-import os
+import sys
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 
 from rich.console import Console
 
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.task import Task
+from devcouncil.app.config import load_config
 from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.executors.agent_registry import (
+    VALID_INPUT_MODES,
+    CliAgentSpec,
+    get_cli_agent_spec,
+    load_agent_profiles,
+    normalize_agent_name,
+    resolve_cursor_agent_executable,
+)
+from devcouncil.repo.gitignore import ensure_gitignore
+from devcouncil.telemetry.traces import TraceLogger
+from devcouncil.utils.redaction import redact_text
 
 console = Console()
 
@@ -16,34 +35,199 @@ console = Console()
 class CodingCliExecutor(Executor):
     """Execute a DevCouncil task by handing it off to an external coding CLI."""
 
-    _ALIASES = {
-        "codex-cli": "codex",
-        "gemini-cli": "gemini",
-        "claude-cli": "claude",
-        "claude-code": "claude",
-    }
-
-    def __init__(self, project_root: Path, client: str, timeout_seconds: int = 1800):
-        self.client = self._normalize_client(client)
+    def __init__(
+        self,
+        project_root: Path,
+        client: str,
+        timeout_seconds: int = 1800,
+        profile: str | None = None,
+        stream_output: bool | None = None,
+    ):
         self.project_root = project_root
+        self.client = self._normalize_client(client)
         self.timeout_seconds = timeout_seconds
+        self.spec = self._resolve_spec()
+        self.profile_name = profile or self.spec.default_profile or "default"
+        self.profile = load_agent_profiles(project_root).get(self.profile_name)
+        self.last_run_id: str | None = None
+        self.last_transcript_path: Path | None = None
+        self.stream_output = self._resolve_stream_output(stream_output)
 
     def _normalize_client(self, client: str) -> str:
-        normalized = (client or "").strip().lower().replace("_", "-")
-        return self._ALIASES.get(normalized, normalized)
-
-    def _command(self) -> list[str]:
-        if self.client == "codex":
-            return ["codex", "exec", "-"]
-        if self.client == "gemini":
-            return ["gemini"]
-        if self.client == "claude":
-            return ["claude", "-p"]
+        return normalize_agent_name(client)
+
+    def _resolve_spec(self) -> CliAgentSpec:
+        spec = get_cli_agent_spec(self.project_root, self.client)
+        if spec:
+            return spec
         raise ValueError(f"Unsupported coding CLI client: {self.client}")
 
+    def _resolve_stream_output(self, stream_output: bool | None) -> bool:
+        if stream_output is not None:
+            return stream_output
+        try:
+            return bool(load_config(self.project_root).execution.stream_cli_output)
+        except Exception:
+            return False
+
+    def _command(self, task_id: str | None = None) -> list[str]:
+        if self.client == "warp":
+            base = self._warp_command()
+        elif self.client == "cursor":
+            base = self._cursor_command(task_id)
+        else:
+            base = self.spec.base_command()
+        return self._apply_profile_args(base)
+
+    # Per-CLI flag used to override the model, when the CLI accepts one. Clients
+    # absent from this map simply ignore a profile ``model`` override.
+    _MODEL_FLAGS: dict[str, str] = {
+        "claude": "--model",
+        "codex": "--model",
+        "gemini": "--model",
+        "cursor": "--model",
+        "qwen": "--model",
+        "opencode": "--model",
+        "aider": "--model",
+    }
+
+    def _apply_profile_args(self, command: list[str]) -> list[str]:
+        """Apply per-profile CLI overrides to the resolved command.
+
+        Empty/None overrides reproduce today's invocation exactly (no regression):
+        ``model`` rewrites/adds the model flag for CLIs that accept one,
+        ``permission_mode`` is translated into the right per-CLI flag (and an
+        overly-permissive baked-in flag is replaced for stricter modes), and
+        ``extra_args`` are appended verbatim. Surfaced in the run manifest so
+        ``dev runs show`` reveals exactly how the CLI was invoked."""
+        if not self.profile:
+            return command
+        result = list(command)
+        result = self._apply_permission_mode(result)
+        result = self._apply_model_override(result)
+        # NOTE: extra_args are NOT appended here. For argument/prompt-file CLIs the prompt
+        # (and sometimes its flag, e.g. warp --prompt / aider --message) is appended last
+        # by _invocation; appending extra_args at the tail here would slot them between the
+        # prompt flag and its value. _invocation places them correctly instead.
+        return result
+
+    def _apply_model_override(self, command: list[str]) -> list[str]:
+        model = (self.profile.model or "").strip() if self.profile else ""
+        if not model:
+            return command
+        flag = self._MODEL_FLAGS.get(self.client)
+        if not flag:
+            return command
+        result = list(command)
+        for index, part in enumerate(result):
+            if part == flag and index + 1 < len(result):
+                result[index + 1] = model
+                return result
+        return [*result, flag, model]
+
+    def _apply_permission_mode(self, command: list[str]) -> list[str]:
+        mode = (self.profile.permission_mode or "").strip() if self.profile else ""
+        if not mode:
+            return command
+        if self.client == "claude":
+            return self._apply_claude_permission_mode(command, mode)
+        return command
+
+    @staticmethod
+    def _apply_claude_permission_mode(command: list[str], mode: str) -> list[str]:
+        """Translate an abstract permission mode into Claude Code's
+        ``--permission-mode`` value. ``auto`` keeps blanket auto-apply
+        (``acceptEdits``); ``gated``/``ask`` drop blanket auto-apply so edits are
+        gated (``default``); ``plan`` is read-only planning. An explicit native
+        value (e.g. ``acceptEdits``, ``bypassPermissions``) is passed through."""
+        translation = {
+            "auto": "acceptEdits",
+            "gated": "default",
+            "ask": "default",
+            "plan": "plan",
+        }
+        value = translation.get(mode.lower(), mode)
+        result = list(command)
+        for index, part in enumerate(result):
+            if part == "--permission-mode" and index + 1 < len(result):
+                result[index + 1] = value
+                return result
+        return [*result, "--permission-mode", value]
+
+    def _cursor_command(self, task_id: str | None = None) -> list[str]:
+        executable = resolve_cursor_agent_executable()
+        if not executable:
+            raise ValueError("cursor-agent (or agent) is not installed or not on PATH.")
+        command = [
+            executable,
+            "--print",
+            "--trust",
+            "--workspace",
+            str(self.project_root),
+        ]
+        chat_id = self._cursor_resume_chat_id(task_id)
+        if chat_id:
+            command.extend(["--resume", chat_id])
+        command.append("Read and execute the DevCouncil task prompt at {prompt_file}.")
+        return command
+
+    def _warp_command(self) -> list[str]:
+        config = self._load_warp_config()
+        command = config.get("command", "oz")
+        mode = config.get("run_mode", "local")
+        subcommand = "run-cloud" if mode == "cloud" else "run"
+        mcp_path = self._ensure_warp_mcp_config(config)
+        args = [command, "agent", subcommand, "--name", "devcouncil-task", "--mcp", str(mcp_path)]
+        if subcommand == "run":
+            args.extend(["--cwd", str(self.project_root)])
+        if profile := config.get("profile"):
+            args.extend(["--profile", str(profile)])
+        if model := config.get("model"):
+            args.extend(["--model", str(model)])
+        if environment := config.get("environment"):
+            args.extend(["--environment", str(environment)])
+        for share in config.get("share", []):
+            args.extend(["--share", str(share)])
+        args.append("--prompt")
+        return args
+
+    def _load_warp_config(self) -> dict:
+        try:
+            warp = load_config(self.project_root).integrations.warp
+            data = warp.model_dump()
+        except Exception:
+            data = {}
+        if command := os.environ.get("DEVCOUNCIL_WARP_COMMAND"):
+            data["command"] = command
+        if mode := os.environ.get("DEVCOUNCIL_WARP_RUN_MODE"):
+            data["run_mode"] = mode
+        if profile := os.environ.get("DEVCOUNCIL_WARP_PROFILE"):
+            data["profile"] = profile
+        if model := os.environ.get("DEVCOUNCIL_WARP_MODEL"):
+            data["model"] = model
+        if environment := os.environ.get("DEVCOUNCIL_WARP_ENVIRONMENT"):
+            data["environment"] = environment
+        return data
+
     def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
+        if self.profile is None:
+            return ExecutionResult(
+                success=False,
+                message=f"Unknown agent profile '{self.profile_name}' for {self.client}.",
+            )
+        if self.spec.input_mode not in VALID_INPUT_MODES:
+            return ExecutionResult(
+                success=False,
+                message=(
+                    f"Invalid input_mode '{self.spec.input_mode}' for {self.client}. "
+                    "Use one of: argument, prompt-file, stdin."
+                ),
+            )
+
+        ensure_gitignore(self.project_root)
+
         try:
-            command = self._command()
+            command = self._command(task.id)
         except ValueError as exc:
             return ExecutionResult(success=False, message=str(exc))
 
@@ -55,47 +239,463 @@ class CodingCliExecutor(Executor):
             )
 
         prompt = PromptBuilder(self.project_root).build_task_prompt(task, requirements)
+        from devcouncil.planning.correction_manifest import load_latest_correction_manifest
+
+        correction = load_latest_correction_manifest(self.project_root, task.id)
+        if correction is not None:
+            prompt = (
+                f"# DevCouncil Correction Manifest\n\n"
+                f"{correction.model_dump_json(indent=2)}\n\n"
+                f"{prompt}"
+            )
+        prompt = self._apply_profile_prompt(prompt)
         instruction_file = self.project_root / ".devcouncil" / f"{task.id}-{self.client}-task.md"
         instruction_file.parent.mkdir(parents=True, exist_ok=True)
         instruction_file.write_text(prompt, encoding="utf-8")
 
-        env = {**dict(os.environ), "DEVCOUNCIL_PROJECT_ROOT": str(self.project_root)}
+        custom_env = self.spec.env
+        env = {**dict(os.environ), **custom_env, "DEVCOUNCIL_PROJECT_ROOT": str(self.project_root)}
+        env["DEVCOUNCIL_AGENT_PROFILE"] = self.profile_name
         log_prefix = f"{task.id}-{self.client}"
+        run_id = str(uuid.uuid4())
+        self.last_run_id = run_id
 
         console.print(f"Starting [bold]{self.client.upper()}[/bold] for task [bold]{task.id}[/bold]...")
         console.print(f"Task prompt: [dim]{instruction_file}[/dim]")
-        console.print(f"Command: [dim]{' '.join(command)}[/dim]")
 
+        started = time.monotonic()
         try:
-            result = subprocess.run(
-                command,
-                input=prompt,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                cwd=self.project_root,
-                env=env,
-                timeout=self.timeout_seconds,
+            invocation, input_text = self._invocation(command, prompt, instruction_file)
+            display_invocation = self._display_invocation(invocation, prompt)
+            # Print the resolved command (placeholders like {prompt_file} already
+            # substituted, prompt redacted) rather than the raw template.
+            console.print(f"Command: [dim]{' '.join(display_invocation)}[/dim]")
+            manifest_path = self._write_run_manifest(
+                run_id,
+                task,
+                display_invocation,
+                instruction_file,
+                stream=self.stream_output,
             )
+            TraceLogger(self.project_root).log_event(
+                "agent_run_started",
+                {
+                    "agent": self.client,
+                    "profile": self.profile_name,
+                    "command": display_invocation,
+                    "prompt_file": str(instruction_file),
+                    "manifest": str(manifest_path),
+                },
+                run_id=run_id,
+                task_id=task.id,
+                summary=f"Started {self.client} for {task.id}",
+            )
+            transcript_path = (
+                self.project_root / ".devcouncil" / "runs" / run_id / "transcript.txt"
+                if self.stream_output
+                else None
+            )
+            started = time.monotonic()
+            result = self._run_subprocess(invocation, input_text, env, transcript_path=transcript_path)
+            duration = round(time.monotonic() - started, 3)
+            finished_at = datetime.now(timezone.utc).isoformat()
             self._write_log(log_prefix, result)
+            if transcript_path and transcript_path.exists():
+                self._append_manifest_transcript(run_id, transcript_path)
+                self.last_transcript_path = transcript_path
+                console.print(f"Stream transcript: [dim]{transcript_path}[/dim]")
             if result.returncode != 0:
+                self._update_run_manifest(
+                    run_id,
+                    status="failed",
+                    returncode=result.returncode,
+                    stdout_preview=self._preview_lines(result.stdout),
+                    stderr_preview=self._preview_lines(result.stderr),
+                    finished_at=finished_at,
+                    duration_seconds=duration,
+                )
                 stderr_preview = (result.stderr or result.stdout or "").strip().splitlines()[:5]
-                detail = stderr_preview[0] if stderr_preview else "No diagnostics were produced."
+                detail = redact_text(stderr_preview[0]) if stderr_preview else "No diagnostics were produced."
+                TraceLogger(self.project_root).log_event(
+                    "agent_run_failed",
+                    {"agent": self.client, "profile": self.profile_name, "returncode": result.returncode, "detail": detail},
+                    run_id=run_id,
+                    task_id=task.id,
+                    summary=f"{self.client} exited with code {result.returncode}",
+                )
                 return ExecutionResult(
                     success=False,
                     message=f"{self.client} exited with code {result.returncode}: {detail}",
                 )
+            self._update_run_manifest(
+                run_id,
+                status="finished",
+                returncode=result.returncode,
+                stdout_preview=self._preview_lines(result.stdout),
+                stderr_preview=self._preview_lines(result.stderr),
+                finished_at=finished_at,
+                duration_seconds=duration,
+            )
+            TraceLogger(self.project_root).log_event(
+                "agent_run_finished",
+                {"agent": self.client, "profile": self.profile_name, "returncode": result.returncode},
+                run_id=run_id,
+                task_id=task.id,
+                summary=f"{self.client} finished for {task.id}",
+            )
             return ExecutionResult(success=True, message=f"{self.client} execution finished.")
-        except subprocess.TimeoutExpired as exc:
-            _ = exc
+        except subprocess.TimeoutExpired:
+            self._update_run_manifest(
+                run_id,
+                status="timeout",
+                finished_at=datetime.now(timezone.utc).isoformat(),
+                duration_seconds=round(time.monotonic() - started, 3),
+            )
+            TraceLogger(self.project_root).log_event(
+                "agent_run_failed",
+                {"agent": self.client, "profile": self.profile_name, "timeout_seconds": self._effective_timeout()},
+                run_id=run_id,
+                task_id=task.id,
+                summary=f"{self.client} timed out for {task.id}",
+            )
             return ExecutionResult(
                 success=False,
-                message=f"{self.client} execution timed out after {self.timeout_seconds}s.",
+                message=f"{self.client} execution timed out after {self._effective_timeout()}s.",
             )
         except Exception as exc:
+            self._update_run_manifest(
+                run_id,
+                status="failed",
+                returncode=None,
+                stderr_preview=self._preview_lines(str(exc)),
+                finished_at=datetime.now(timezone.utc).isoformat(),
+                duration_seconds=round(time.monotonic() - started, 3),
+            )
             return ExecutionResult(success=False, message=str(exc))
 
+    def _resolve_invocation(self, invocation: list[str], env: dict[str, str]) -> list[str]:
+        """Route Windows batch shims through the command interpreter.
+
+        Coding CLIs installed via npm are exposed on Windows as ``.cmd``/``.bat``
+        shims (e.g. ``codex.CMD``). ``CreateProcess`` (shell=False) cannot execute
+        a batch file directly nor apply PATHEXT to a bare ``codex``, so the run
+        fails with ``WinError 2``/``193``. When the program resolves to such a
+        shim, invoke it via ``cmd /c <shim>``; ``.exe`` programs and non-Windows
+        platforms are left untouched so the invocation passed to the agent is
+        otherwise verbatim.
+        """
+        if not invocation or os.name != "nt":
+            return invocation
+        # Resolve against the PATH the child will actually run with (which includes any
+        # per-agent env overrides), not the parent process PATH — otherwise shim
+        # detection and execution can disagree on which executable runs.
+        resolved = shutil.which(invocation[0], path=env.get("PATH"))
+        if resolved and resolved.lower().endswith((".cmd", ".bat")):
+            comspec = os.environ.get("COMSPEC", "cmd.exe")
+            return [comspec, "/c", resolved, *invocation[1:]]
+        return invocation
+
+    @staticmethod
+    def _emit_stream_line(line: str) -> None:
+        """Print a streamed agent line without letting a non-encodable character
+        crash the run. Coding agents emit Unicode (e.g. ``✓``) that the
+        Windows console / a redirected cp1252 stdout cannot encode; an unguarded
+        ``console.print`` would raise UnicodeEncodeError and be misreported as the
+        agent failing to start, even though it ran (and may have applied edits).
+        """
+        try:
+            console.print(line, end="")
+        except UnicodeEncodeError:
+            encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+            safe = line.encode(encoding, errors="replace").decode(encoding, errors="replace")
+            console.print(safe, end="")
+
+    def _run_subprocess(
+        self,
+        invocation: list[str],
+        input_text: str | None,
+        env: dict[str, str],
+        transcript_path: Path | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        timeout = self._effective_timeout()
+        invocation = self._resolve_invocation(invocation, env)
+        if not self.stream_output:
+            return subprocess.run(
+                invocation,
+                input=input_text,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=self.project_root,
+                env=env,
+                timeout=timeout,
+            )
+
+        process = subprocess.Popen(
+            invocation,
+            stdin=subprocess.PIPE if input_text is not None else None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            cwd=self.project_root,
+            env=env,
+        )
+        stdin = process.stdin
+        if input_text is not None and stdin is not None:
+            # Feed stdin from a thread so a child that fills its stdout pipe
+            # before consuming stdin cannot deadlock against us.
+            def _feed_stdin() -> None:
+                try:
+                    stdin.write(input_text)
+                    stdin.close()
+                except (BrokenPipeError, OSError):
+                    pass
+
+            threading.Thread(target=_feed_stdin, daemon=True).start()
+
+        stdout = process.stdout
+        assert stdout is not None
+        lines: queue.Queue[str | None] = queue.Queue()
+
+        def _drain_stdout() -> None:
+            try:
+                for raw_line in iter(stdout.readline, ""):
+                    lines.put(raw_line)
+            finally:
+                lines.put(None)
+
+        reader = threading.Thread(target=_drain_stdout, daemon=True)
+        reader.start()
+
+        captured: list[str] = []
+        transcript_handle = None
+        if transcript_path is not None:
+            transcript_path.parent.mkdir(parents=True, exist_ok=True)
+            transcript_handle = transcript_path.open("w", encoding="utf-8")
+        deadline = time.monotonic() + timeout
+        try:
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    process.kill()
+                    # Reap the killed child so it doesn't linger as a zombie, and close
+                    # stdin so the feeder thread unblocks. Bounded wait — kill() already
+                    # signalled it.
+                    try:
+                        if process.stdin is not None:
+                            process.stdin.close()
+                    except OSError:
+                        pass
+                    try:
+                        process.wait(timeout=5)
+                    except subprocess.TimeoutExpired:
+                        pass
+                    raise subprocess.TimeoutExpired(invocation, timeout)
+                try:
+                    line = lines.get(timeout=min(remaining, 1.0))
+                except queue.Empty:
+                    continue
+                if line is None:
+                    break
+                self._emit_stream_line(line)
+                captured.append(line)
+                if transcript_handle is not None:
+                    transcript_handle.write(redact_text(line))
+                    transcript_handle.flush()
+            process.wait()
+        finally:
+            if transcript_handle is not None:
+                transcript_handle.close()
+            reader.join(timeout=5)
+
+        return subprocess.CompletedProcess(
+            invocation,
+            process.returncode if process.returncode is not None else 0,
+            stdout="".join(captured),
+            stderr="",
+        )
+
+    def _cursor_resume_mode(self) -> str:
+        try:
+            mode = (load_config(self.project_root).execution.cursor_resume_mode or "off").strip().lower()
+        except Exception:
+            mode = "off"
+        if mode not in {"off", "project", "task"}:
+            return "off"
+        return mode
+
+    def _cursor_session_path(self, task_id: str | None = None) -> Path:
+        if self._cursor_resume_mode() == "task" and task_id:
+            return self.project_root / ".devcouncil" / "sessions" / f"{task_id}-cursor.json"
+        return self.project_root / ".devcouncil" / "integrations" / "cursor-session.json"
+
+    def _cursor_resume_chat_id(self, task_id: str | None) -> str | None:
+        mode = self._cursor_resume_mode()
+        if mode == "off":
+            return None
+        path = self._cursor_session_path(task_id if mode == "task" else None)
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8")) or {}
+            except json.JSONDecodeError:
+                data = {}
+            existing_chat_id = str(data.get("chat_id") or "").strip()
+            if existing_chat_id:
+                return existing_chat_id
+        ensured_chat_id = self._ensure_cursor_chat_id()
+        if not ensured_chat_id:
+            return None
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({"chat_id": ensured_chat_id}, indent=2) + "\n", encoding="utf-8")
+        return ensured_chat_id
+
+    def _ensure_cursor_chat_id(self) -> str | None:
+        executable = resolve_cursor_agent_executable()
+        if not executable:
+            return None
+        try:
+            result = subprocess.run(
+                [executable, "create-chat"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                cwd=self.project_root,
+                timeout=60,
+            )
+        except subprocess.TimeoutExpired:
+            return None
+        if result.returncode != 0:
+            return None
+        chat_id = (result.stdout or result.stderr or "").strip().splitlines()[-1].strip()
+        return chat_id or None
+
+    def _effective_timeout(self) -> int:
+        if self.profile and self.profile.timeout_seconds:
+            return int(self.profile.timeout_seconds)
+        return int(self.spec.timeout_seconds or self.timeout_seconds)
+
+    def _invocation(self, command: list[str], prompt: str, instruction_file: Path) -> tuple[list[str], str | None]:
+        mode = self.spec.input_mode
+        resolved = [
+            part.replace("{prompt_file}", str(instruction_file)).replace("{project_root}", str(self.project_root))
+            for part in command
+        ]
+        extra = list(self.profile.extra_args) if (self.profile and self.profile.extra_args) else []
+
+        def _place(base: list[str]) -> list[str]:
+            """Insert profile extra_args after the base flags but before a trailing prompt
+            flag (the last token of a baked-in prompt-flag CLI like warp ``--prompt`` /
+            aider ``--message``), so that flag still binds to the prompt appended after it."""
+            if extra and base and base[-1].startswith("-"):
+                return [*base[:-1], *extra, base[-1]]
+            return [*base, *extra]
+
+        if mode == "stdin":
+            return _place(resolved), prompt
+        if mode == "argument":
+            if any("{prompt}" in part for part in resolved):
+                return [part.replace("{prompt}", prompt) for part in resolved] + extra, None
+            prompt_arg = self.spec.prompt_arg
+            if prompt_arg:
+                return [*resolved, *extra, prompt_arg, prompt], None
+            return [*_place(resolved), prompt], None
+        if mode == "prompt-file":
+            if "{prompt_file}" in " ".join(command):
+                return resolved + extra, None
+            prompt_arg = self.spec.prompt_arg
+            if prompt_arg:
+                return [*resolved, *extra, prompt_arg, str(instruction_file)], None
+            return [*_place(resolved), str(instruction_file)], None
+        return _place(resolved), prompt
+
+    def _display_invocation(self, invocation: list[str], prompt: str) -> list[str]:
+        return [part.replace(prompt, "<task prompt>") for part in invocation]
+
+    def _apply_profile_prompt(self, prompt: str) -> str:
+        if not self.profile:
+            return prompt
+        additions = []
+        if self.profile.prompt_preamble:
+            additions.append(self.profile.prompt_preamble)
+        if self.profile.require_explicit_confirmation:
+            additions.append("Ask for confirmation before any high-risk, out-of-scope, or destructive action.")
+        if not additions:
+            return prompt
+        return "\n\n".join(["# DevCouncil Agent Profile", *additions, prompt])
+
+    def _profile_override_summary(self) -> dict[str, object]:
+        """Resolved per-profile CLI overrides recorded in the manifest so a
+        supervisor can see exactly how the profile constrained the invocation."""
+        if not self.profile:
+            return {"extra_args": [], "permission_mode": None, "model": None}
+        return {
+            "extra_args": list(self.profile.extra_args or []),
+            "permission_mode": self.profile.permission_mode,
+            "model": self.profile.model,
+        }
+
+    def _update_run_manifest(self, run_id: str, **updates: object) -> None:
+        manifest_path = self.project_root / ".devcouncil" / "runs" / run_id / "agent-run.json"
+        if not manifest_path.exists():
+            return
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8")) or {}
+        except json.JSONDecodeError:
+            return
+        manifest.update(updates)
+        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    def _preview_lines(self, value: str | None, *, limit: int = 20) -> list[str]:
+        lines = redact_text(value or "").splitlines()
+        return lines[:limit]
+
+    def _append_manifest_transcript(self, run_id: str, transcript_path: Path) -> None:
+        self._update_run_manifest(run_id, transcript=str(transcript_path))
+
+    def _write_run_manifest(
+        self,
+        run_id: str,
+        task: Task,
+        invocation: list[str],
+        instruction_file: Path,
+        *,
+        stream: bool = False,
+    ) -> Path:
+        run_dir = self.project_root / ".devcouncil" / "runs" / run_id
+        run_dir.mkdir(parents=True, exist_ok=True)
+        manifest_path = run_dir / "agent-run.json"
+        manifest = {
+            "run_id": run_id,
+            "task_id": task.id,
+            "agent": self.client,
+            "display_name": self.spec.label,
+            "profile": self.profile_name,
+            "profile_overrides": self._profile_override_summary(),
+            "kind": self.spec.kind,
+            "command": invocation,
+            "prompt_file": str(instruction_file),
+            "planned_files": [planned.model_dump() for planned in task.planned_files],
+            "allowed_commands": task.allowed_commands,
+            "expected_tests": task.expected_tests,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "stream": stream,
+            "artifact_version": 1,
+            "started_at": datetime.now(timezone.utc).isoformat(),
+            "status": "running",
+            "transcript": None,
+            "returncode": None,
+            "stdout_preview": [],
+            "stderr_preview": [],
+            "finished_at": None,
+            "duration_seconds": None,
+        }
+        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+        return manifest_path
+
     def _write_log(self, task_client: str, result: subprocess.CompletedProcess[str]) -> None:
         log_dir = self.project_root / ".devcouncil" / "logs"
         log_dir.mkdir(parents=True, exist_ok=True)
@@ -104,9 +704,33 @@ class CodingCliExecutor(Executor):
             "\n".join([
                 f"command_returncode={result.returncode}",
                 "=== stdout ===",
-                result.stdout or "",
+                redact_text(result.stdout or ""),
                 "=== stderr ===",
-                result.stderr or "",
+                redact_text(result.stderr or ""),
             ]),
             encoding="utf-8",
         )
+
+    def _ensure_warp_mcp_config(self, config: dict | None = None) -> Path:
+        configured_path = (config or {}).get("mcp_config_path") or ".devcouncil/integrations/warp-mcp.json"
+        path = Path(configured_path).expanduser()
+        if not path.is_absolute():
+            path = self.project_root / path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        desired = {
+            "devcouncil": {
+                "command": "devcouncil",
+                "args": ["mcp-server"],
+                "env": {"DEVCOUNCIL_PROJECT_ROOT": str(self.project_root)},
+            }
+        }
+        should_write = not path.exists()
+        if path.exists():
+            try:
+                existing = json.loads(path.read_text(encoding="utf-8")) or {}
+            except json.JSONDecodeError:
+                existing = {}
+            should_write = "mcpServers" in existing and "devcouncil" not in existing
+        if should_write:
+            path.write_text(json.dumps(desired, indent=2) + "\n", encoding="utf-8")
+        return path