release: canary → main (31 commits) — Python truth-layer + cross-platform install + 13 bug fixes

.github/workflows/ci.yml

@@ -0,0 +1,221 @@
+name: ci
+
+# Three jobs on every PR + every push to canary/main:
+#
+#   clean-install-linux   ubuntu install.sh + airc doctor + smoke test
+#   clean-install-macos   macos install.sh + airc doctor + smoke test
+#   clean-install-windows windows install.ps1 + airc doctor (PS-side)
+#
+# Plus on canary/main only (skipped on PR): integration-suite runs the
+# full test/integration.sh on ubuntu — the most thorough gate, but
+# expensive (real gh-gist scenarios + ~5min runtime).
+#
+# The clean-install jobs are the "guarantee installs work from zero"
+# gate Joel asked for (2026-04-28). They run on a stock runner image
+# with no airc preinstalled, exercise install.{sh,ps1} the way a real
+# first-time user would, and validate the binary lands + doctor reports
+# clean. Without these, every Windows install bug (#94, #96, #98, #99)
+# slipped past every PR review and only surfaced when a user hit them.
+
+on:
+  pull_request:
+    branches: [canary, main]
+  push:
+    branches: [canary, main]
+
+# A previous push's CI gets cancelled if the same branch / PR pushes
+# again. Prevents queue pileup when several PRs land in quick succession.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  clean-install-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Stage install.sh in a temp dir (simulate first-time user)
+        # The shipped install.sh clones from the canonical github URL.
+        # In CI we want it to install FROM THIS COMMIT, not from main —
+        # otherwise we'd be testing the published install.sh against
+        # whatever's already on the canonical branch, not the PR.
+        # Override AIRC_DIR + skip the clone step by pre-populating
+        # the source tree, then run install.sh's PATH/skills wiring.
+        run: |
+          mkdir -p $HOME/.airc-src
+          cp -r . $HOME/.airc-src/
+          # Real install — no AIRC_SKIP_PREREQS. install.sh must
+          # detect the package manager and install everything missing.
+          AIRC_DIR=$HOME/.airc-src bash install.sh
+
+      - name: airc doctor (must report environment-clean)
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          which airc
+          airc doctor
+
+      - name: Smoke — connect --no-room --no-gist + teardown
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          export AIRC_HOME=/tmp/ci-airc/state
+          export AIRC_NO_DISCOVERY=1 AIRC_NO_GENERAL=1 AIRC_NO_IDENTITY_PROMPT=1
+          mkdir -p /tmp/ci-airc/state
+          # Spawn host in background. --no-gist keeps it offline.
+          airc connect --no-room --no-gist > /tmp/ci-airc/host.log 2>&1 &
+          # Wait up to 10s for airc.pid to appear (airc writes it once
+          # the host loop is up). Don't pgrep on argv — airc's actual
+          # process line is `bash /path/to/airc connect ...` and pgrep
+          # patterns are brittle across distros.
+          for i in 1 2 3 4 5 6 7 8 9 10; do
+            [ -f /tmp/ci-airc/state/airc.pid ] && break
+            sleep 1
+          done
+          if [ ! -f /tmp/ci-airc/state/airc.pid ]; then
+            echo "FAIL: airc.pid never appeared — connect didn't reach host loop"
+            cat /tmp/ci-airc/host.log || true
+            exit 1
+          fi
+          # Verify all PIDs in airc.pid are alive.
+          for p in $(cat /tmp/ci-airc/state/airc.pid); do
+            if ! kill -0 "$p" 2>/dev/null; then
+              echo "FAIL: PID $p in airc.pid is not alive"
+              cat /tmp/ci-airc/host.log || true
+              exit 1
+            fi
+          done
+          echo "✓ airc connect stayed up (pids: $(cat /tmp/ci-airc/state/airc.pid))"
+          airc teardown
+          sleep 1
+          # After teardown, airc.pid is removed AND no PID from it should
+          # still be alive. We saved the pids before teardown for the
+          # post-check.
+          if [ -f /tmp/ci-airc/state/airc.pid ]; then
+            echo "FAIL: airc teardown left airc.pid behind"
+            exit 1
+          fi
+          echo "✓ airc teardown clean"
+
+  clean-install-macos:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Stage install.sh + run (no skip-prereqs — real install path)
+        run: |
+          mkdir -p $HOME/.airc-src
+          cp -r . $HOME/.airc-src/
+          AIRC_DIR=$HOME/.airc-src bash install.sh
+
+      - name: airc doctor (must report environment-clean)
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          which airc
+          airc doctor
+
+      - name: Smoke — same as linux (airc.pid based)
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          export AIRC_HOME=/tmp/ci-airc/state
+          export AIRC_NO_DISCOVERY=1 AIRC_NO_GENERAL=1 AIRC_NO_IDENTITY_PROMPT=1
+          mkdir -p /tmp/ci-airc/state
+          airc connect --no-room --no-gist > /tmp/ci-airc/host.log 2>&1 &
+          for i in 1 2 3 4 5 6 7 8 9 10; do
+            [ -f /tmp/ci-airc/state/airc.pid ] && break
+            sleep 1
+          done
+          if [ ! -f /tmp/ci-airc/state/airc.pid ]; then
+            echo "FAIL: airc.pid never appeared — connect didn't reach host loop"
+            cat /tmp/ci-airc/host.log || true
+            exit 1
+          fi
+          for p in $(cat /tmp/ci-airc/state/airc.pid); do
+            if ! kill -0 "$p" 2>/dev/null; then
+              echo "FAIL: PID $p in airc.pid is not alive"
+              cat /tmp/ci-airc/host.log || true
+              exit 1
+            fi
+          done
+          echo "✓ airc connect stayed up (pids: $(cat /tmp/ci-airc/state/airc.pid))"
+          airc teardown
+          sleep 1
+          if [ -f /tmp/ci-airc/state/airc.pid ]; then
+            echo "FAIL: airc teardown left airc.pid behind"
+            exit 1
+          fi
+          echo "✓ airc teardown clean"
+
+  clean-install-windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run install.ps1 (no skip — real install path via winget)
+        shell: pwsh
+        run: |
+          $env:AIRC_DIR = "$env:USERPROFILE\.airc-src"
+          New-Item -ItemType Directory -Force -Path $env:AIRC_DIR | Out-Null
+          Copy-Item -Recurse -Force * $env:AIRC_DIR
+          # install.ps1 must work from default Windows PowerShell 5.1
+          # too; we test 5.1 path in a separate job below.
+          & "$env:AIRC_DIR\install.ps1"
+
+      - name: airc doctor (must report environment-clean)
+        shell: pwsh
+        run: |
+          $env:PATH = "$env:USERPROFILE\AppData\Local\Programs\airc;$env:PATH"
+          (Get-Command airc -ErrorAction SilentlyContinue) | Out-String
+          airc doctor
+          if ($LASTEXITCODE -ne 0) {
+            Write-Error "airc doctor failed with exit $LASTEXITCODE"
+            exit $LASTEXITCODE
+          }
+
+  clean-install-windows-ps5:
+    # Validates the bootstrap path under Windows PowerShell 5.1 — the
+    # default that ships with Windows. install.ps1 must work from 5.1
+    # to bootstrap pwsh itself (#91 — bootstrap-airc.ps1 fails under
+    # PS 5.1 because airc.ps1 has #Requires -Version 7.0). Splitting
+    # this into its own job means a 5.1 regression fails loudly without
+    # also failing the pwsh-based smoke.
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run install.ps1 under Windows PowerShell 5.1 (real install)
+        shell: powershell
+        run: |
+          $env:AIRC_DIR = "$env:USERPROFILE\.airc-src-ps5"
+          New-Item -ItemType Directory -Force -Path $env:AIRC_DIR | Out-Null
+          Copy-Item -Recurse -Force * $env:AIRC_DIR
+          & "$env:AIRC_DIR\install.ps1"
+
+  integration-suite:
+    # Heavy gate: the full test/integration.sh, including scenarios that
+    # hit real gh-gists. Runs on canary/main pushes, NOT on PRs (rate
+    # limits + flaky network). When canary→main bundle PRs come up, this
+    # already-green status on the canary tip is the signal that cross-
+    # branch validation passed.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Stage + install (real install path)
+        run: |
+          mkdir -p $HOME/.airc-src
+          cp -r . $HOME/.airc-src/
+          AIRC_DIR=$HOME/.airc-src bash install.sh
+
+      - name: Run integration suite
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          # Tests that need real gists self-skip without gh auth. The
+          # remaining ~85% of the suite covers the local-only scenarios
+          # that catch the lion's share of regressions.
+          bash test/integration.sh

.gitignore

@@ -1 +1,3 @@
 .airc/
+__pycache__/
+*.pyc

README.md

@@ -14,17 +14,15 @@
 
 ## Install
 
-**macOS / Linux / WSL** (bash):
+**Any platform** (bash — works from macOS / Linux / WSL / Windows Git Bash):
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/CambrianTech/airc/main/install.sh | bash
 ```
 
-**Windows** (PowerShell — works from the default Windows PowerShell 5.1; bootstraps pwsh 7 + every other prereq via winget):
+This is the install command for everyone running Claude Code, Codex, Cursor, opencode, Windsurf, or openclaw — all of which use bash on every platform including Windows. On Windows, install.sh detects Git Bash, installs prereqs via winget, and self-elevates once for OpenSSH server + DefaultShell setup. You stay in your terminal — no PowerShell switch.
 
-```powershell
-iwr https://raw.githubusercontent.com/CambrianTech/airc/main/install.ps1 | iex
-```
+> **Native-PowerShell users (rare):** if you specifically want `airc.ps1` (the PowerShell port, not the bash one), use `iwr https://raw.githubusercontent.com/CambrianTech/airc/main/install.ps1 | iex` instead. Most users don't need this — Claude Code / Codex / etc. on Windows run in Git Bash, where `install.sh` is the right entry.
 
 One command. Puts `airc` on your `PATH` and installs the Claude Code skills automatically. Other agents (Codex, Cursor, opencode, Windsurf, openclaw) get their integration files at [`integrations/`](integrations/).
 
@@ -120,19 +118,15 @@ This isn't a knock on the federation protocols — they solve real enterprise fe
 
 ## Install
 
-**macOS / Linux / WSL**:
+**Every platform** (macOS / Linux / WSL / Windows Git Bash):
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/CambrianTech/airc/main/install.sh | bash
 ```
 
-**Windows** (PowerShell):
-
-```powershell
-iwr https://raw.githubusercontent.com/CambrianTech/airc/main/install.ps1 | iex
-```
+Puts `airc` on your `PATH` and installs Claude Code skills automatically. Auto-installs every prereq (gh, openssl, python3, openssh-client, optional tailscale) via the platform's package manager (brew / apt / dnf / pacman / apk / winget). On Windows it self-elevates once for OpenSSH Server + DefaultShell setup; you stay in your terminal.
 
-Puts `airc` on your `PATH` and installs Claude Code skills automatically. Both installers auto-install every prereq (gh, openssl, python3, openssh-client, optional tailscale) via the platform's package manager (brew / apt / dnf / pacman / apk / winget).
+> **Native-PowerShell users:** rare, but if you specifically want the PowerShell port `airc.ps1` instead of the bash binary, use `iwr https://raw.githubusercontent.com/CambrianTech/airc/main/install.ps1 | iex`. The bash install.sh is the right entry for everyone running Claude Code / Codex / Cursor on Windows (which all default to Git Bash).
 
 ## 30-Second Setup