feat(watchdog): runner-side self-heal for stale or hung bridge

.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g. v0.5, v1.0.0)"
+        required: true
+        type: string
+      update_stable:
+        description: "Update the 'stable' tag to point to this release"
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Validate version format
+        run: |
+          if ! echo "${{ inputs.version }}" | grep -qE '^v[0-9]+(\.[0-9]+){1,2}$'; then
+            echo "::error::Version must match vMAJOR.MINOR or vMAJOR.MINOR.PATCH (e.g. v0.5, v1.0.0)"
+            exit 1
+          fi
+
+      - name: Check tag does not already exist
+        run: |
+          if git rev-parse "${{ inputs.version }}" >/dev/null 2>&1; then
+            echo "::error::Tag ${{ inputs.version }} already exists"
+            exit 1
+          fi
+
+      - name: Check for commits since last tag
+        id: changelog
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          if [ -n "$LAST_TAG" ]; then
+            RANGE="${LAST_TAG}..HEAD"
+            COMMIT_COUNT=$(git rev-list --count "$RANGE")
+            if [ "$COMMIT_COUNT" -eq 0 ]; then
+              echo "::error::No commits since $LAST_TAG — nothing to release"
+              exit 1
+            fi
+            NOTES=$(git log "$RANGE" --pretty=format:"- %s (%h)")
+          else
+            NOTES=$(git log --pretty=format:"- %s (%h)")
+          fi
+
+          # Write notes to file (multi-line safe)
+          echo "$NOTES" > /tmp/release-notes.md
+          echo "last_tag=${LAST_TAG:-none}" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ inputs.version }}" -m "Release ${{ inputs.version }}"
+          git push origin "${{ inputs.version }}"
+
+      - name: Update stable tag
+        if: inputs.update_stable
+        run: |
+          echo "Updating stable tag → ${{ inputs.version }}"
+          git tag -f stable "${{ inputs.version }}"
+          git push origin stable --force
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ inputs.version }}" \
+            --title "Kōan ${{ inputs.version }}" \
+            --notes-file /tmp/release-notes.md \
+            --latest

.github/workflows/tests.yml

@@ -23,6 +23,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
+        python-version: ${{ github.event_name == 'pull_request' && fromJSON('["3.14"]') || fromJSON('["3.11", "3.14"]') }}
         group:
           - name: fast
             marker: "not slow"
@@ -36,23 +37,23 @@ jobs:
             marker: "slow"
             split_group: 3
 
-    name: test (${{ matrix.group.name }})
+    name: test (py${{ matrix.python-version }}, ${{ matrix.group.name }})
 
     steps:
       - uses: actions/checkout@v6
 
-      - name: Set up Python 3.14
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
-          python-version: "3.14"
+          python-version: "${{ matrix.python-version }}"
           allow-prereleases: true
           cache: 'pip'
           cache-dependency-path: koan/requirements.txt
 
       - name: Install dependencies
         run: |
           pip install -r koan/requirements.txt
-          pip install pytest pytest-split
+          pip install pytest pytest-split pytest-cov pytest-xdist
 
       - name: Run tests (${{ matrix.group.name }})
         if: ${{ !inputs.group || matrix.group.name == inputs.group }}
@@ -64,7 +65,86 @@ jobs:
           KOAN_TELEGRAM_CHAT_ID: "123456789"
         run: |
           if [ -n "${{ matrix.group.split_group }}" ]; then
-            pytest tests/ -m "${{ matrix.group.marker }}" --splits 3 --group ${{ matrix.group.split_group }} -v
+            pytest tests/ -m "${{ matrix.group.marker }}" --splits 3 --group ${{ matrix.group.split_group }} -v \
+              -n auto --dist loadfile \
+              --cov=app --cov-report=term-missing
           else
-            pytest tests/ -m "${{ matrix.group.marker }}" -v
+            pytest tests/ -m "${{ matrix.group.marker }}" -v \
+              -n auto --dist loadfile \
+              --cov=app --cov-report=term-missing
           fi
+
+      - name: Upload coverage data
+        if: ${{ !inputs.group || matrix.group.name == inputs.group }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-py${{ matrix.python-version }}-${{ matrix.group.name }}
+          path: koan/.coverage
+          include-hidden-files: true
+
+  check-coverage:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    name: check-coverage
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          allow-prereleases: true
+
+      - name: Install coverage
+        run: pip install coverage
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-py*
+          path: coverage-parts
+
+      - name: Combine coverage and check baselines
+        working-directory: koan
+        env:
+          KOAN_ROOT: ${{ github.workspace }}/koan
+        run: |
+          # Collect all .coverage files and rename for combine
+          i=0
+          for f in ../coverage-parts/coverage-*/.coverage; do
+            cp "$f" ".coverage.$i"
+            i=$((i + 1))
+          done
+
+          coverage combine
+          TOTAL_COV=$(coverage report --format=total 2>/dev/null || coverage report | grep '^TOTAL' | awk '{print $NF}' | tr -d '%')
+          echo "Total coverage: ${TOTAL_COV}%"
+
+          # Read baselines
+          BASELINE_COV=$(cat ../coverage-baseline.txt | tr -d '[:space:]')
+          echo "Baseline coverage: ${BASELINE_COV}%"
+
+          # Allow 0.5% tolerance on coverage
+          python3 -c "
+          import sys
+          actual = float('${TOTAL_COV}')
+          baseline = float('${BASELINE_COV}')
+          tolerance = 0.5
+          if actual < baseline - tolerance:
+              print(f'FAIL: Coverage {actual}% is below baseline {baseline}% (tolerance {tolerance}%)')
+              sys.exit(1)
+          print(f'OK: Coverage {actual}% meets baseline {baseline}% (tolerance {tolerance}%)')
+          "
+
+      - name: Check test count baseline
+        run: |
+          BASELINE_COUNT=$(cat test-count-baseline.txt | tr -d '[:space:]')
+          echo "Test count baseline: ${BASELINE_COUNT}"
+
+          # Sum test counts from all matrix job logs
+          # The test count check is best-effort from the coverage report;
+          # the authoritative count comes from running all tests.
+          # For now, this is informational — the hard enforcement is on coverage.
+          echo "INFO: Test count baseline is ${BASELINE_COUNT}. Monitor via PR review."

.gitignore

@@ -10,6 +10,9 @@ __pycache__/
 .venv/
 venv/
 .coverage
+.coverage.*
+htmlcov/
+koan/htmlcov/
 
 # Runtime
 .koan-status

AI_POLICY.md

@@ -0,0 +1,125 @@
+# AI Policy
+
+> **TL;DR** — AI tools assist our workflow at every stage. Humans remain in control of every decision, every review, and every release.
+
+---
+
+## Overview
+
+This document describes how artificial intelligence tools are used in the maintenance and development of this project. It is intended to be transparent with our contributors, users, and the broader open-source community about the role AI plays — and, equally importantly, the role it does **not** play.
+
+We believe in honest, clear communication about AI-assisted workflows. This policy will be updated as our practices evolve.
+
+---
+
+## Our Guiding Principle
+
+**AI assists. Humans decide.**
+
+The maintainers who have been stewarding this project for years remain fully responsible for every line of code that ships. AI tools extend our capacity to review, research, and improve — they do not replace human judgment, expertise, or accountability.
+
+---
+
+## How AI Is Used in This Project
+
+### 1. Code and Issue Analysis
+
+AI tools help us process and understand incoming issues, pull requests, and code changes at scale. This includes:
+
+- Summarising issue reports and identifying patterns across similar bugs
+- Analysing code diffs for potential problems, regressions, or style inconsistencies
+- Surfacing relevant context from the codebase, documentation, and prior discussions
+- Flagging potential security concerns for human review
+
+This analysis is **always** used as input to human decision-making, never as a substitute for it.
+
+### 2. Draft Pull Requests
+
+AI may generate draft pull requests as a starting point for a fix, a refactor, or an improvement. These drafts:
+
+- Are clearly labelled as AI-generated when created
+- Represent a first pass only — they are never considered complete or correct without human review
+- May be substantially reworked, rejected, or replaced entirely by maintainers
+
+Think of these drafts the way you would think of a junior contributor's first attempt: useful raw material that still needs experienced eyes.
+
+### 3. Human Review of Every Pull Request
+
+**Every pull request — whether AI-drafted or human-authored — is reviewed by a human maintainer before it can be merged.**
+
+During review, maintainers actively use AI as a tool to assist their own thinking:
+
+- Asking AI to explain or justify specific implementation choices
+- Challenging AI-generated code and requesting alternative approaches
+- Using AI to research edge cases, relevant standards, or upstream behaviour
+- Requesting targeted rewrites of individual sections based on review feedback
+
+The maintainer's judgment always takes precedence. AI answers are treated as input to be verified, not conclusions to be accepted.
+
+### 4. Test Coverage and Defect Detection
+
+AI helps us improve the quality and completeness of our test suite by:
+
+- Suggesting test cases for edge conditions and failure modes
+- Identifying gaps in existing test coverage
+- Proposing tests that target known classes of defects or security issues
+- Helping reproduce and characterise reported bugs
+
+All suggested tests are reviewed and validated by maintainers before being committed.
+
+### 5. Security Review
+
+AI tools assist in identifying potential security issues, including:
+
+- Common vulnerability patterns (injection, insecure defaults, deprecated APIs, etc.)
+- Dependencies with known CVEs
+- Code paths that may warrant closer scrutiny
+
+Security findings from AI are **always** verified by a human maintainer. We do not act on AI-flagged security issues without independent assessment.
+
+---
+
+## What AI Does Not Do
+
+To be explicit about the limits of AI involvement in this project:
+
+| ❌ AI does not… | ✅ A human maintainer does… |
+|---|---|
+| Approve or merge pull requests | Review and decide on every PR |
+| Make architectural decisions | Own all design and direction choices |
+| Triage and close issues autonomously | Assess and respond to all issues |
+| Publish releases | Tag, build, and release manually |
+| Represent the project publicly | Communicate on behalf of the project |
+
+---
+
+## Releases
+
+Releases are performed manually by the same long-standing maintainers as always. The release process — including changelog review, version tagging, and publication — involves no AI-driven automation. Every release is initiated, supervised, and published by a human maintainer.
+
+AI may assist in drafting changelogs or release notes, but these are always reviewed and edited before publication.
+
+---
+
+## Attribution and Transparency
+
+Where AI has played a material role in generating code or content within a pull request, we aim to note this in the PR description (e.g. via a `Generated-By` or `AI-Assisted` label or note). We do not consider AI the author of any contribution — the maintainer who reviewed and approved the work takes responsibility for it.
+
+---
+
+## Why We Do This
+
+Open-source software is built on trust. Our users and downstream dependants trust us to ship correct, secure, and well-considered code. AI tools help us do that work better — but they do not change who is responsible for the outcome.
+
+We use AI because it makes our maintainers more effective, not because it replaces them.
+
+---
+
+## Questions and Feedback
+
+If you have questions about our use of AI, or concerns about a specific pull request or change, please open an issue or start a discussion. We are committed to being open about our process.
+
+---
+
+*Last updated: 2026-03-23*
+*This policy is maintained by the project maintainers and subject to revision as AI tooling and community norms evolve.*