agentic-devtools 0.2.9__tar.gz → 0.2.10__tar.gz

{agentic_devtools-0.2.9 → agentic_devtools-0.2.10}/.github/copilot-instructions.md

@@ -634,7 +634,7 @@ These commands initiate a workflow, loading and rendering the appropriate prompt
 
 | Command | Purpose | Required Parameters |
 |---------|---------|---------------------|
-| `agdt-initiate-pull-request-review-workflow` | Start PR review workflow | `--pull-request-id` or `--issue-key` |
+| `agdt-initiate-pull-request-review-workflow` | Start PR review workflow | `--pull-request-id` or `--issue-key`; optional `--interactive false` for pipeline mode |
 | `agdt-initiate-work-on-jira-issue-workflow` | Start work on Jira issue | `--issue-key` |
 | `agdt-initiate-create-jira-issue-workflow` | Start create issue workflow | `--project-key` |
 | `agdt-initiate-create-jira-epic-workflow` | Start create epic workflow | `--project-key` |
@@ -1466,33 +1466,40 @@ agdt-reply-to-pull-request-thread  # Previews without API calls
 
 ### Pull Request Review Workflow
 
-The `agdt-review-pull-request` command orchestrates the entire PR review process:
+The end-to-end automated PR review is initiated with a **single command**:
 
 ```bash
-# Option 1: Start with Jira issue key
-agdt-set jira.issue_key DFLY-1840
-agdt-review-pull-request
+# Start with a PR ID (interactive mode — VS Code terminal)
+agdt-initiate-pull-request-review-workflow --pull-request-id 12345
 
-# Option 2: Start with PR ID
-agdt-set pull_request_id 23523
-agdt-review-pull-request
-
-# Option 3: Pass parameters directly
-agdt-review-pull-request --pull-request-id 23523 --jira-issue-key DFLY-1840
+# Start with a Jira issue key (looks up the PR automatically)
+agdt-initiate-pull-request-review-workflow --issue-key DFLY-1234
 
-# Option 4: Include already-reviewed files
-agdt-review-pull-request --include-reviewed
+# Non-interactive / pipeline mode
+agdt-initiate-pull-request-review-workflow --pull-request-id 12345 --interactive false
 ```
 
-The command:
+**Automated flow:**
+
+1. Resolves both the PR ID and Jira issue key (cross-lookup when only one is provided).
+2. Fetches the PR source branch from Azure DevOps.
+3. Validates the current worktree/branch context via pre-flight checks.
+4. If the context is wrong, **automatically creates a dedicated worktree**, attempts to open VS Code (when available), then re-runs the command inside the new worktree.
+5. Fetches full PR details (diff, threads, iterations) and Jira issue details.
+6. Generates per-file review prompts in `scripts/temp/pull-request-review/prompts/<pr_id>/`.
+7. **When auto-setup ran (new worktree was created):** starts a `gh copilot` CLI session
+   (interactive or background depending on `--interactive`). When already in the correct
+   worktree context, the rendered initiate prompt is printed to the console for the agent
+   to use manually.
+
+#### `--interactive` Flag
 
-1. **Resolves both PR ID and Jira issue key** from params, state, or derived sources:
-   - If Jira key provided but no PR ID → searches Jira for linked PRs
-   - If PR ID provided but no Jira key → extracts issue key from PR title
-2. **Fetches full PR details** (diff, threads, iterations)
-3. **Fetches Jira issue details** (if available)
-4. **Generates per-file review prompts** in `scripts/temp/pull-request-review/prompts/<pr_id>/`
-5. **Prints instructions** for the review workflow
+| Value | Behavior (when a Copilot session is started) |
+|-------|----------------------------------------------|
+| `true` (default) | Starts `gh copilot suggest` with an attached terminal — the reviewer interacts with it directly in VS Code. |
+| `false` | Starts `gh copilot suggest` as a detached background process, capturing output to `scripts/temp/background-tasks/logs/`. Use for Azure DevOps pipelines or other headless environments. |
+
+If `gh copilot` is not installed, a warning is printed and the prompt file path is shown so the review can be started manually.
 
 #### Generated Review Artifacts
 
@@ -1506,7 +1513,7 @@ The command:
 
 #### File Review Commands
 
-After starting a review, use these commands for each file:
+After a review session is active, use these commands for each file:
 
 ```bash
 # Approve a file (no issues found)
@@ -1528,6 +1535,94 @@ const descriptiveVariableName = value;
 agdt-request-changes-with-suggestion
 ```
 
+#### Pipeline Usage
+
+For use in Azure DevOps pipelines (headless, no interactive terminal):
+
+```yaml
+# azure-pipelines.yml example
+- script: agdt-initiate-pull-request-review-workflow --pull-request-id $(System.PullRequest.PullRequestId) --interactive false
+  displayName: 'Run automated PR review'
+  env:
+    AZURE_DEV_OPS_COPILOT_PAT: $(AzureDevOpsCopilotPat)
+    JIRA_COPILOT_PAT: $(JiraCopilotPat)
+```
+
+When running in pipeline mode (`--interactive false`):
+
+- `gh copilot` output is captured to `scripts/temp/background-tasks/logs/copilot_session_*.log`.
+- The Copilot process runs as a direct child process (via `subprocess.Popen`), not as an
+  agdt background task, so there is no background task ID and `agdt-task-wait` is not
+  applicable. Monitor completion using the `copilot.pid` state key and/or by tailing the
+  Copilot session log file.
+- The `worktree_setup.auto_execute_exit_code` state key records the exit code of the
+  setup/auto-execute command, not the Copilot session itself.
+
+#### Copilot / VS Code Graceful Degradation
+
+When an interactive Copilot session cannot be started, the workflow falls back to a
+non-interactive mode:
+
+- If `gh copilot` is not available on the machine, a warning is printed to stderr.
+- If the VS Code `code` CLI is not available, or there is no attached TTY (for example,
+  in CI pipelines), interactive mode is automatically disabled and `copilot.mode` is set
+  to `"non-interactive"`.
+- In all of these cases, the rendered prompt is written to
+  `scripts/temp/copilot-session-<session_id>-prompt.md`, and the session metadata is still
+  persisted to state (`copilot.*` keys).
+- The reviewer can open the prompt file in VS Code (or any editor) and start a manual
+  Copilot session if desired.
+
+#### Copilot CLI Session Management
+
+State keys written to `agdt-state.json` after a session is started:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `copilot.session_id` | string | UUID4 hex identifying the session |
+| `copilot.mode` | string | `"interactive"` or `"non-interactive"` |
+| `copilot.prompt_file` | string | Absolute path to the temporary prompt file |
+| `copilot.start_time` | string | ISO-8601 UTC timestamp when the session was started |
+| `copilot.pid` | `integer \| ""` | PID of background process (empty for interactive sessions) |
+
+Additional `worktree_setup` keys written during automated environment setup:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `worktree_setup.auto_execute_exit_code` | string | Exit code of the auto-executed setup command |
+
+#### Target Repository Configuration (`.github/agdt-config.json`)
+
+Target repositories can place a `.github/agdt-config.json` file in their root to customize the review workflow. The file is **optional** — if absent, the review proceeds with defaults.
+
+**Schema:**
+
+```json
+{
+  "review": {
+    "focus-areas-file": ".github/review-focus-areas.md"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `review.focus-areas-file` | string | Repo-root-relative path to a markdown file listing review focus areas. |
+
+**`.github/review-focus-areas.md` format:**
+
+Free-form markdown injected into the review prompt to guide the Copilot reviewer. Example:
+
+```markdown
+## Review Focus Areas
+
+- Ensure all public APIs have JSDoc/docstring documentation.
+- Validate that new database migrations are backward-compatible.
+- Check that error messages are user-friendly and don't leak internals.
+```
+
+Both files are optional and safe to omit; the review will still run without repo-specific guidance.
+
 ### Get Jira Issue Details
 
 ```bash

{agentic_devtools-0.2.9 → agentic_devtools-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-devtools
-Version: 0.2.9
+Version: 0.2.10
 Summary: AI assistant helper commands for the Dragonfly platform
 Author: Dragonfly Team
 License-Expression: MIT

{agentic_devtools-0.2.9 → agentic_devtools-0.2.10}/agentic_devtools/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.9'
-__version_tuple__ = version_tuple = (0, 2, 9)
+__version__ = version = '0.2.10'
+__version_tuple__ = version_tuple = (0, 2, 10)
 
 __commit_id__ = commit_id = None

{agentic_devtools-0.2.9 → agentic_devtools-0.2.10}/agentic_devtools/cli/azure_devops/commands.py

@@ -10,6 +10,7 @@ import sys
 from typing import Any, Dict, Optional
 
 from ...state import (
+    delete_value,
     get_pull_request_id,
     get_thread_id,
     get_value,
@@ -38,6 +39,39 @@ from .pull_request_details_commands import (
 )
 
 
+OVERALL_PR_SUMMARY_HEADING = "## Overall PR Review Summary"
+
+
+def _find_summary_thread_id(
+    requests, headers: Dict[str, str], config: AzureDevOpsConfig, repo_id: str, pull_request_id: int
+) -> Optional[int]:
+    """Find the thread ID of the 'Overall PR Review Summary' thread, if it exists.
+
+    Returns the ID of the first matching thread. If multiple summary threads exist
+    (e.g., from duplicate summary runs), the first one found is used.
+    """
+    threads_url = config.build_api_url(repo_id, "pullRequests", pull_request_id, "threads")
+    try:
+        response = requests.get(threads_url, headers=headers, timeout=30)
+        response.raise_for_status()
+    except Exception as e:
+        print(f"Warning: Could not search for summary thread: {e}", file=sys.stderr)
+        return None
+    threads = response.json().get("value", [])
+    for thread in threads:
+        for comment in thread.get("comments", []):
+            if OVERALL_PR_SUMMARY_HEADING in (comment.get("content") or ""):
+                thread_id = thread.get("id")
+                if thread_id is None:
+                    print(
+                        "Warning: Found summary thread without an 'id' field; skipping.",
+                        file=sys.stderr,
+                    )
+                    break
+                return thread_id
+    return None
+
+
 def _extract_issue_key_from_branch(branch_name: str) -> Optional[str]:
     """
     Extract a Jira issue key from a branch name.
@@ -201,7 +235,7 @@ def add_pull_request_comment() -> None:
     if is_approval:
         content = format_approval_content(content)
 
-    # Optional file context
+    # Optional file context (used for both regular and file-level approval comments)
     path = get_value("path")
     line = get_value("line")
     end_line = get_value("end_line")
@@ -216,6 +250,8 @@ def add_pull_request_comment() -> None:
             print(f"[DRY RUN] File: {path}{line_info}{end_line_info}")
         if is_approval:
             print("[DRY RUN] Comment will include approval sentinel banner")
+            if not path:
+                print("[DRY RUN] Will reply to existing summary thread if found, otherwise create new thread")
         if not leave_thread_active:
             print("[DRY RUN] Would also resolve the thread after posting")
         print(f"Content:\n{content}")
@@ -227,6 +263,26 @@ def add_pull_request_comment() -> None:
     print(f"Resolving repository ID for '{config.repository}'...")
     repo_id = get_repository_id(config.organization, config.project, config.repository)
 
+    # For PR-level approval comments (no file path), try to reply to the existing summary thread
+    if is_approval and not path:
+        summary_thread_id = _find_summary_thread_id(
+            requests, headers, config, repo_id, pull_request_id
+        )
+        if summary_thread_id:
+            try:
+                comment_url = config.build_api_url(
+                    repo_id, "pullRequests", pull_request_id, "threads", summary_thread_id, "comments"
+                )
+                comment_body = {"content": content, "commentType": "text"}
+                print(f"Posting approval to existing summary thread {summary_thread_id}...")
+                response = requests.post(comment_url, headers=headers, json=comment_body, timeout=30)
+                response.raise_for_status()
+                result = response.json()
+                print(f"Approval reply added (comment ID: {result.get('id')}, thread: {summary_thread_id})")
+                return
+            except Exception as e:
+                print(f"Warning: Could not reply to summary thread, creating new thread: {e}", file=sys.stderr)
+
     # Build thread context for file-level comments
     thread_context = build_thread_context(path, line, end_line)
 
@@ -552,8 +608,12 @@ def approve_pull_request() -> None:
         agdt-set content "LGTM! All acceptance criteria met."
         agdt-approve-pull-request
     """
-    # Set approval mode and delegate to add_pull_request_comment
+    # Set approval mode and clear any stale file context from previous file-review
+    # operations, so the approval posts as a PR-level comment, not a file-level one.
     set_value("is_pull_request_approval", True)
+    delete_value("path")
+    delete_value("line")
+    delete_value("end_line")
     add_pull_request_comment()
 
 

{agentic_devtools-0.2.9 → agentic_devtools-0.2.10}/agentic_devtools/cli/azure_devops/review_commands.py

@@ -676,6 +676,27 @@ def setup_pull_request_review() -> None:
         print("WORKFLOW INITIALIZED: pull-request-review")
         print("=" * 60)
 
+        # Load repo-specific review focus areas (optional — None if not configured)
+        from ...config import load_review_focus_areas
+
+        # Determine repository root for loading .github/agdt-config.json
+        try:
+            git_root_result = run_safe(
+                ["git", "rev-parse", "--show-toplevel"],
+                capture_output=True,
+                text=True,
+                check=False,
+                shell=False,
+            )
+            if git_root_result.returncode == 0 and git_root_result.stdout:
+                repo_root = git_root_result.stdout.strip()
+            else:
+                repo_root = str(Path.cwd())
+        except Exception:
+            repo_root = str(Path.cwd())
+
+        repo_review_focus_areas = load_review_focus_areas(repo_root)
+
         variables = {
             "pull_request_id": pull_request_id,
             "jira_issue_key": jira_issue_key or "",
@@ -684,6 +705,7 @@ def setup_pull_request_review() -> None:
             "source_branch": source_branch,
             "target_branch": target_branch,
             "file_count": file_count,
+            "repo_review_focus_areas": repo_review_focus_areas or "",
         }
 
         load_and_render_prompt(

agentic_devtools-0.2.10/agentic_devtools/cli/copilot/__init__.py

@@ -0,0 +1,14 @@
+"""
+GitHub Copilot CLI session management package.
+
+Provides utilities for starting and managing gh copilot CLI sessions,
+supporting both interactive and non-interactive modes.
+"""
+
+from .session import CopilotSessionResult, is_gh_copilot_available, start_copilot_session
+
+__all__ = [
+    "is_gh_copilot_available",
+    "start_copilot_session",
+    "CopilotSessionResult",
+]

agentic_devtools-0.2.10/agentic_devtools/cli/copilot/session.py

@@ -0,0 +1,338 @@
+"""
+GitHub Copilot CLI session management.
+
+Provides utilities for starting and managing ``gh copilot`` CLI sessions
+programmatically, supporting both interactive and non-interactive modes,
+with session ID tracking and state persistence.
+
+Research notes
+--------------
+The ``gh copilot suggest`` command is the primary entry point for the
+``gh copilot`` extension.  As of early 2025, autonomous / non-interactive
+operation is not natively exposed through a stable flag.  The module
+therefore implements non-interactive mode by spawning the process with
+stdin/stdout captured to a log file, which is sufficient for pipeline use
+cases where no interactive terminal is available.  When a stable
+``--non-interactive`` or agent-mode flag is added upstream, the
+``_build_copilot_args`` helper can be updated to include it without any
+other changes.
+
+Fallback behaviour
+------------------
+When ``gh copilot`` is not installed or is not callable the session cannot
+be started.  The module logs a warning and prints the prompt to stdout so
+that the user or pipeline can invoke a session manually.
+"""
+
+import shutil
+import subprocess
+import sys
+import uuid
+import warnings
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from agentic_devtools.state import get_state_dir, set_value
+
+from ..subprocess_utils import run_safe
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# State key namespace
+_COPILOT_NS = "copilot"
+
+# Log file directory (relative to state dir)
+_LOG_DIR_NAME = "background-tasks/logs"
+
+# Prompt file naming pattern
+_PROMPT_FILE_PATTERN = "copilot-session-{session_id}-prompt.md"
+
+
+# ---------------------------------------------------------------------------
+# Public dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class CopilotSessionResult:
+    """Result returned by :func:`start_copilot_session`.
+
+    Attributes:
+        session_id: Unique identifier for the session (UUID4 hex).
+        mode: ``"interactive"`` or ``"non-interactive"``.
+        prompt_file: Absolute path to the temporary prompt file.
+        start_time: ISO-8601 UTC timestamp when the session was started.
+        pid: Process ID for non-interactive sessions; ``None`` for
+            interactive sessions (where the process has already exited
+            when this object is returned).
+        process: The :class:`subprocess.Popen` handle for non-interactive
+            sessions; ``None`` for interactive sessions.
+    """
+
+    session_id: str
+    mode: str
+    prompt_file: str
+    start_time: str
+    pid: Optional[int] = field(default=None)
+    process: Optional[subprocess.Popen] = field(default=None, repr=False)  # type: ignore[type-arg]
+
+
+# ---------------------------------------------------------------------------
+# Availability check
+# ---------------------------------------------------------------------------
+
+
+def is_gh_copilot_available() -> bool:
+    """Return ``True`` if ``gh copilot`` can be invoked on this machine.
+
+    Performs two checks:
+    1. The ``gh`` binary is present on ``PATH`` (via :func:`shutil.which`).
+    2. ``gh copilot --help`` exits with return code 0, confirming that the
+       ``copilot`` extension is installed and responsive.
+
+    Returns:
+        ``True`` when both checks pass; ``False`` otherwise.
+    """
+    if not shutil.which("gh"):
+        return False
+    try:
+        result = run_safe(
+            ["gh", "copilot", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            shell=False,
+        )
+        return result.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_session_id() -> str:
+    """Generate a new unique session identifier (UUID4 hex string)."""
+    return uuid.uuid4().hex
+
+
+def _get_prompt_file_path(session_id: str) -> Path:
+    """Return the path where the prompt file should be written.
+
+    The file is placed inside ``scripts/temp/`` relative to the state
+    directory, following the same convention as other temporary files.
+
+    Args:
+        session_id: The session identifier.
+
+    Returns:
+        Absolute :class:`~pathlib.Path` for the prompt file.
+    """
+    state_dir = get_state_dir()
+    return state_dir / _PROMPT_FILE_PATTERN.format(session_id=session_id)
+
+
+def _get_log_file_path(session_id: str, start_time: str) -> Path:
+    """Return the path for the non-interactive session log file.
+
+    Args:
+        session_id: The session identifier.
+        start_time: ISO-8601 timestamp (used in the filename).
+
+    Returns:
+        Absolute :class:`~pathlib.Path` for the log file.
+    """
+    state_dir = get_state_dir()
+    timestamp = start_time.replace(":", "").replace("-", "").replace(".", "_")[:18]
+    filename = f"copilot_session_{timestamp}.log"
+    return state_dir / _LOG_DIR_NAME / filename
+
+
+def _build_copilot_args(prompt_file: str) -> list[str]:
+    """Build the ``gh copilot suggest`` argument list.
+
+    The prompt is passed via the ``--file`` flag (when supported) so that
+    large prompts do not hit shell argument-length limits.  If a stable
+    ``--non-interactive`` or ``--agent-mode`` flag is introduced upstream
+    it should be appended here.
+
+    Args:
+        prompt_file: Absolute path to the file containing the prompt.
+
+    Returns:
+        List of strings suitable for :func:`subprocess.Popen`.
+    """
+    return ["gh", "copilot", "suggest", "--file", prompt_file]
+
+
+def _persist_session_state(result: CopilotSessionResult) -> None:
+    """Write session metadata to ``agdt-state.json``.
+
+    Keys written (all under the ``copilot.`` namespace):
+    - ``copilot.session_id``
+    - ``copilot.mode``
+    - ``copilot.prompt_file``
+    - ``copilot.start_time``
+    - ``copilot.pid`` (empty string when not applicable)
+
+    Args:
+        result: The :class:`CopilotSessionResult` to persist.
+    """
+    set_value(f"{_COPILOT_NS}.session_id", result.session_id)
+    set_value(f"{_COPILOT_NS}.mode", result.mode)
+    set_value(f"{_COPILOT_NS}.prompt_file", result.prompt_file)
+    set_value(f"{_COPILOT_NS}.start_time", result.start_time)
+    set_value(f"{_COPILOT_NS}.pid", result.pid if result.pid is not None else "")
+
+
+def _print_fallback_prompt(prompt: str) -> None:
+    """Print the prompt to stdout as a fallback when ``gh copilot`` is unavailable.
+
+    Args:
+        prompt: The full prompt text to display.
+    """
+    print(
+        "WARNING: gh copilot is not available. Please start a session manually with the following prompt:\n",
+        file=sys.stderr,
+    )
+    print(prompt)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def start_copilot_session(
+    prompt: str,
+    working_directory: str,
+    interactive: bool = True,
+    session_id: Optional[str] = None,
+) -> CopilotSessionResult:
+    """Start a ``gh copilot`` CLI session with the given prompt.
+
+    Behaviour:
+    - Generates (or reuses) a unique session ID.
+    - Writes *prompt* to a temporary file so that large prompts do not
+      exceed CLI argument-length limits.
+    - Starts ``gh copilot suggest --file <prompt_file>``.
+    - In **interactive** mode the child process inherits the current
+      terminal (stdin / stdout / stderr), so the user can interact with
+      it directly.  This call blocks until the interactive session ends.
+    - In **non-interactive** mode the child process runs in the
+      background with stdout and stderr captured to a log file.  The
+      call returns immediately.
+    - Session metadata is written to ``agdt-state.json`` under the
+      ``copilot.*`` namespace.
+    - If ``gh copilot`` is not available, a warning is emitted and the
+      prompt is printed to stdout so the user can start a session
+      manually.
+
+    Args:
+        prompt: The full prompt text to send to the Copilot session.
+        working_directory: The directory in which to run the command.
+            Typically the worktree root.
+        interactive: When ``True`` (default) the process runs with an
+            attached terminal.  When ``False`` the process runs
+            detached in the background.
+        session_id: Optional pre-generated session ID.  A new UUID4 hex
+            string is generated when this is ``None``.
+
+    Returns:
+        A :class:`CopilotSessionResult` with session metadata.
+
+    Raises:
+        OSError: If the prompt file cannot be written to disk.
+    """
+    if session_id is None:
+        session_id = _make_session_id()
+
+    start_time = datetime.now(timezone.utc).isoformat()
+    mode = "interactive" if interactive else "non-interactive"
+
+    # --- Write prompt to temp file -------------------------------------------
+    prompt_file_path = _get_prompt_file_path(session_id)
+    prompt_file_path.parent.mkdir(parents=True, exist_ok=True)
+    prompt_file_path.write_text(prompt, encoding="utf-8")
+    prompt_file = str(prompt_file_path)
+
+    # --- Check availability --------------------------------------------------
+    if not is_gh_copilot_available():
+        warnings.warn(
+            "gh copilot is not available; printing prompt to stdout as fallback.",
+            stacklevel=2,
+        )
+        _print_fallback_prompt(prompt)
+        result = CopilotSessionResult(
+            session_id=session_id,
+            mode=mode,
+            prompt_file=prompt_file,
+            start_time=start_time,
+            pid=None,
+            process=None,
+        )
+        _persist_session_state(result)
+        return result
+
+    # --- Build command -------------------------------------------------------
+    args = _build_copilot_args(prompt_file)
+
+    # --- Launch process -------------------------------------------------------
+    if interactive:
+        # Inherit stdio so the user can interact with the session.
+        # This call blocks until the interactive session ends.
+        # shell=False is required: gh is a proper .exe (not a .cmd batch script),
+        # and the argument list contains a file path derived from user-supplied
+        # prompt content; shell=True on Windows would allow cmd.exe to expand
+        # %VAR% patterns inside those values.
+        process = subprocess.Popen(
+            args,
+            cwd=working_directory,
+            shell=False,
+        )
+        process.wait()
+        result = CopilotSessionResult(
+            session_id=session_id,
+            mode=mode,
+            prompt_file=prompt_file,
+            start_time=start_time,
+            pid=None,  # process has already exited; PID not meaningful
+            process=None,
+        )
+    else:
+        # Non-interactive: run as background process, capture output to log file.
+        log_file_path = _get_log_file_path(session_id, start_time)
+        log_file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open without a context manager so the file handle stays open while the
+        # background process is still running; the OS will release it when the
+        # child process (which inherits the fd) eventually exits.
+        # shell=False: same reasoning as the interactive case above.
+        log_fh = open(log_file_path, "w", encoding="utf-8")  # noqa: WPS515
+        process = subprocess.Popen(
+            args,
+            cwd=working_directory,
+            stdout=log_fh,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True if sys.platform != "win32" else False,
+            shell=False,
+        )
+
+        result = CopilotSessionResult(
+            session_id=session_id,
+            mode=mode,
+            prompt_file=prompt_file,
+            start_time=start_time,
+            pid=process.pid,
+            process=process,
+        )
+
+    _persist_session_state(result)
+    return result