ENG-34: Run scripts under a PTY so terminal-aware tools work

.github/workflows/e2e.yml

@@ -15,7 +15,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: '3.11'
 
       - run: pip install pytest
 
@@ -52,7 +52,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
+          python-version: '3.11'
 
       - run: pip install pytest
 
@@ -61,22 +61,57 @@ jobs:
           CODEPLAIN_API_KEY: ${{ secrets.CODEPLAIN_API_KEY }}
         run: pytest tests/e2e/ -v --tb=short
 
+  # The installer jobs above test the published package; this one tests the wheel built
+  # from the checkout. It runs neither the pytest e2e collection (its POSIX fixture needs
+  # a Docker daemon and its other case is Windows-only) nor anything that needs the API
+  # key: the point is that a real toolchain runs through the terminal backend on macOS.
+  e2e-macos:
+    runs-on: macos-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # hatch-vcs derives the version from the git tags
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build and install this checkout's wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+          pip install dist/*.whl
+
+      - name: Report the Node under test
+        run: node --version   # macos-latest ships Node preinstalled
+
+      # Under `nohup` with stdin from /dev/null: the detached shape a renderer is started
+      # in, where nothing upstream of the script has a terminal to lend it.
+      - name: Run Node through the installed execute_script()
+        run: nohup python tests/e2e/macos_node_smoke.py < /dev/null
+
   notify-on-failure:
     name: Notify Slack on failure
-    needs: [e2e-linux, e2e-windows]
+    needs: [e2e-linux, e2e-windows, e2e-macos]
     if: failure()
     runs-on: ubuntu-latest
     env:
       SLACK_WEBHOOK_URL: ${{ secrets.SLACK_E2E_WEBHOOK_URL }}
+      LINUX_RESULT: ${{ needs.e2e-linux.result }}
+      WINDOWS_RESULT: ${{ needs.e2e-windows.result }}
+      MACOS_RESULT: ${{ needs.e2e-macos.result }}
     steps:
       - name: Determine failed platforms
         id: platforms
         run: |
           failed=""
-          [ "${{ needs.e2e-linux.result }}" = "failure" ] && failed="Linux"
-          if [ "${{ needs.e2e-windows.result }}" = "failure" ]; then
-            [ -n "$failed" ] && failed="$failed and Windows" || failed="Windows"
-          fi
+          for entry in "Linux:$LINUX_RESULT" "Windows:$WINDOWS_RESULT" "macOS:$MACOS_RESULT"; do
+            if [ "${entry#*:}" = "failure" ]; then
+              name="${entry%%:*}"
+              if [ -n "$failed" ]; then failed="$failed and $name"; else failed="$name"; fi
+            fi
+          done
           echo "failed=$failed" >> "$GITHUB_OUTPUT"
 
       - name: Send failure notification to Slack

.github/workflows/lint-and-test.yml

@@ -72,8 +72,15 @@ jobs:
         run: flake8 .
 
   mypy:
-    name: MyPy Type Checking
+    name: MyPy Type Checking (${{ matrix.platform }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # --platform is a static narrowing setting, so every target is checked from
+        # one runner: code is verified under the platform where it runs and proven
+        # guarded under the platforms where it does not.
+        platform: [linux, darwin, win32]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -90,37 +97,67 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
       - name: Type check with mypy
-        run: mypy . --check-untyped-defs
+        run: mypy . --check-untyped-defs --platform ${{ matrix.platform }}
 
-  tests:
-    name: Run Tests
-    runs-on: ubuntu-latest
+  conpty-lifecycle:
+    # windows-latest is Windows Server 2025 (build 26100), the build that made
+    # ClosePseudoConsole() non-blocking, so the teardown-ordering assertions pass there
+    # whether or not the ordering is correct. Windows Server 2022 is build 20348, inside the
+    # affected range, which is the only place those assertions prove anything.
+    name: ConPTY Lifecycle (windows-2022)
+    runs-on: windows-2022
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-      - name: Configure git for tests
-        run: |
-          git config --global user.email "test@example.com"
-          git config --global user.name "Test Runner"
-          git config --global init.defaultBranch main
-      - name: Cache pip
-        uses: actions/cache@v4
+          cache: pip
+          cache-dependency-path: requirements.txt
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+      - name: Install requirements
+        run: pip install -r requirements.txt
+      - name: Run the ConPTY lifecycle tests
+        run: python -m pytest tests/test_conpty.py -v
+
+  tests:
+    name: Run Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install coverage
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+          cache-dependency-path: requirements.txt
+      # Every step below runs a single command. Windows runners default to
+      # PowerShell, where a failing native command does not abort the remaining
+      # commands of a multi-command run block; one command per step makes a
+      # failure fail the job on every OS without shell-specific workarounds.
+      - name: Configure git user email
+        run: git config --global user.email "test@example.com"
+      - name: Configure git user name
+        run: git config --global user.name "Test Runner"
+      - name: Configure git default branch
+        run: git config --global init.defaultBranch main
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+      - name: Install requirements
+        run: pip install -r requirements.txt
+      - name: Install coverage
+        run: pip install coverage
       - name: Run tests with coverage
-        run: |
-          export $(cat .env.dev.example | xargs)
-          coverage run -m pytest tests/ -v
-          coverage xml
-          coverage report
+        run: coverage run -m pytest tests/ -v
+      - name: Generate coverage XML
+        run: coverage xml
+      - name: Show coverage report
+        run: coverage report
       - name: Upload coverage reports
+        if: matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v3

.gitignore

@@ -30,3 +30,4 @@ dist
 
 .coverage
 logging_config.yaml
+/.idea/

CLAUDE.md

@@ -248,7 +248,7 @@ git push origin subtree/standard-template-library
 ```
 
 ### Windows Support
-Windows users must use WSL (Windows Subsystem for Linux). The codebase has some platform-specific script handling (`.ps1` for Windows, `.sh` for Unix).
+Native Windows is supported and tested in CI. The codebase has platform-specific script handling (`.ps1` for Windows, `.sh` for Unix), and scripts run on a ConPTY-backed terminal with a Job Object containing their process tree (`render_machine/_conpty.py`), which needs Windows 10 build 17763 (1809) or newer. WSL works too, and is then an ordinary Linux host.
 
 ### CRITICAL: No User-Specific Paths in Version Control
 **Never commit files containing user-specific absolute paths** (e.g., `/Users/username/...`, `/home/username/...`, `C:\Users\...`) to version-controlled files like:

cli_output/render_summary.py

@@ -1,11 +1,19 @@
 """Render completion summary display."""
 
+import logging
 from typing import Optional
 
+import plain2code_logger
 from plain2code_console import console
 from plain2code_state import RunState
 from usage_summary import format_usage_summary
 
+logger = logging.getLogger(plain2code_logger.LOGGER_NAME)
+
+# Marks the last line of a render's log file. Greppable on purpose: benchmark runs and
+# support artifacts are read by tooling before they are read by a person.
+RENDER_TRAILER_PREFIX = "[render-trailer]"
+
 
 def print_exit_summary(
     run_state: RunState,
@@ -27,6 +35,49 @@ def print_exit_summary(
     msg += format_usage_summary(run_state.rendered_functionalities, run_state.render_time_accumulated) + "\n"
     console.print(msg)
 
-    if not run_state.render_succeeded and error_message:
+    # Reported whenever there is one. A render can finish its functionalities and still
+    # raise on the way out — publishing the build, for instance — and that combination
+    # used to print the success banner and swallow the reason entirely, leaving a caller
+    # with a tick mark and a non-zero exit code.
+    if error_message:
         console.error(error_message)
     console.quiet = True
+
+    log_render_trailer(run_state, spec_filename, error_message)
+
+
+def log_render_trailer(
+    run_state: RunState,
+    spec_filename: str,
+    error_message: Optional[str] = None,
+) -> None:
+    """Writes the render's outcome to the log file, as its last line.
+
+    The summary above reaches the terminal through Rich, which never touches logging, so
+    a captured `codeplain.log` used to stop at whatever happened to be logged last —
+    indistinguishable from a process that died silently. This ends every log with what
+    the render did, and because it is written on every exit path a log *without* a
+    trailer is itself evidence that the file was truncated.
+    """
+    if run_state.render_succeeded:
+        outcome = "completed"
+    elif run_state.render_cancelled:
+        outcome = "cancelled"
+    else:
+        outcome = "failed"
+
+    logger.info(
+        f"{RENDER_TRAILER_PREFIX} outcome={outcome} "
+        f"render_id={run_state.render_id} "
+        f"functionalities={run_state.rendered_functionalities} "
+        f"render_time_s={run_state.render_time_accumulated} "
+        f"generated_code={run_state.render_generated_code_path or '-'} "
+        f"spec={spec_filename}"
+    )
+    if error_message:
+        logger.error(f"{RENDER_TRAILER_PREFIX} error={error_message}")
+
+    # The process may exit immediately after this; an unflushed trailer would defeat the
+    # purpose of writing one.
+    for handler in logger.handlers:
+        handler.flush()

codeplain_REST_api.py

@@ -19,6 +19,7 @@
 ERROR_CODE_EXCEPTIONS = {
     "FunctionalRequirementTooComplex": plain2code_exceptions.FunctionalRequirementTooComplex,
     "ConflictingRequirements": plain2code_exceptions.ConflictingRequirements,
+    "ConformanceTestsFixExhausted": plain2code_exceptions.ConformanceTestsFixExhausted,
     "RenderingCreditBalanceTooLow": plain2code_exceptions.RenderingCreditBalanceTooLow,
     "LLMInternalError": plain2code_exceptions.LLMInternalError,
     "MissingResource": plain2code_exceptions.MissingResource,
@@ -382,6 +383,7 @@ def fix_conformance_tests_issue(
         current_testing_frid_high_level_implementation_plan: Optional[str],
         conflicting_requirements_count: int,
         run_state: RunState,
+        stalled_reason: Optional[str] = None,
     ):
         endpoint_url = f"{self.api_url}/fix_conformance_tests_issue"
         headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
@@ -408,6 +410,11 @@ def fix_conformance_tests_issue(
         if acceptance_tests is not None:
             payload["acceptance_tests"] = acceptance_tests
 
+        # Sent only once the loop has stopped moving. Omitted otherwise, so an
+        # ordinary fix request is byte-identical to what it was.
+        if stalled_reason is not None:
+            payload["stalled_reason"] = stalled_reason
+
         return self.post_request(endpoint_url, headers, payload, run_state)
 
     def render_acceptance_tests(