feat(cli): wire runtime, security, ux, protocol and plugin surfaces (#39)

* feat(cli): wire runtime, security, ux, protocol and plugin surfaces

Implement the capability lots from the feature audit across seven areas,
then wire them together so declared surfaces reach a real executor.

Runtime and protocols: server-owned tool results are never re-executed
locally, incomplete streams and unsuccessful terminal events never report
success, sessions are origin-bound with persistent multi-turn JSON-RPC and
event-independent deadlines. MCP gains async stdio plus Streamable HTTP with
OAuth keyring reuse; the app server shares one live-session registry with
independent WebSocket and SSE subscribers and returns 501 for unsupported
compatibility endpoints.

Execution security: one authorization gate covers direct, Batch, child and
plugin paths with exact single-use approvals, workspace confinement,
traversal and symlink checks, final environment filtering, bounded capture
and controlled process-group cancellation. Interactive sessions now honor
--sandbox, --ask-for-approval, --full-auto, --dangerously-bypass and
--add-dir instead of ignoring them, and the TUI and agent executors build an
explicit authorized context. Policy evaluation and process-group termination
run in-process; the Linux sandbox wrapper is the binary itself when no
sibling helper is installed, and an unregistered host still fails closed.

UX and sessions: a shared local store backs persisted new, resume and fork,
durable rename, favorite and protection, JSON and YAML export and import,
and conversation-scoped undo and redo, with unified dispatch across CLI and
TUI. Plugins gain an explicit ABI, activation and packaging contract with a
Node runtime. Platform work aligns the opentelemetry family, corrects release
asset names, and makes installers validate URLs, architecture, checksums and
bounds with staging and rollback.

Config overrides for sandbox mode and writable roots are now applied,
shutdown no longer deletes other sessions' files, and --debug writes a
content-free local journal instead of a full trace dump.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* ci: provision node for plugin tests and fix bsd version parsing

The distribution matrix added macOS runners, where BSD sed does not accept
the GNU `\s` class, so the workspace version was captured as the whole
`version = "0.1.8"` line and never matched VERSION_CLI. Use a POSIX
character class instead.

Node plugin tests launch a real `node` worker; the test and coverage jobs
had no Node, so eight tests failed on a missing runtime rather than on
behavior. Provision Node 22 in both jobs and in the dev container, and state
the prerequisite in the development guide, instead of skipping the tests.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* fix(install): install on case-insensitive volumes and drop gnu-only stat

On macOS and Windows the filesystem folds case, so the alias path "cortex"
resolves to the destination "Cortex" itself. The installer read that as a
foreign command already occupying the name and refused to install at all.
Skip alias names that are the destination file, and keep refusing a real
unrelated binary, now covered by a regression test that runs on a
case-insensitive volume plus one that always runs.

The release metadata fixture also used GNU `stat -c%s`, which BSD stat
rejects; `wc -c` is portable.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* fix(plugins): resolve node before clearing the worker environment

Keep the resolved executable for cleanup and cover custom PATH execution
with a real Node child. Verify installer aliases on case-folding filesystems.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

* fix(tests): resolve node consistently in cli plugin fixtures

Use the runtime resolver when detecting supported Node installations so
custom-PATH builds are not incorrectly expected to fail.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

---------

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: echobt

.devcontainer/devcontainer.json

@@ -1,6 +1,9 @@
 {
   "name": "Cortex Rust workspace",
   "build": {"dockerfile": "Dockerfile", "context": ".."},
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {"version": "22"}
+  },
   "remoteUser": "cortex",
   "updateRemoteUserUID": true,
   "postCreateCommand": "bash scripts/dev-setup.sh",

.github/workflows/ci.yml

@@ -54,12 +54,23 @@ jobs:
           retention-days: 14
 
   version-check:
-    name: CLI Version Check
-    runs-on: ubuntu-latest
+    name: CLI Version and Distribution (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, macos-15-intel, windows-latest]
     steps:
       - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -r scripts/readiness/requirements.txt
       - name: Verify CLI version consistency
+        shell: bash
         run: ./scripts/check-cli-version.sh
+      - name: Verify installer fixtures and package contracts
+        run: python -B -m unittest discover -s scripts/readiness -p test_distribution.py -v
       - name: Verify Windows installer arch detection
         shell: pwsh
         run: ./scripts/test-install-ps1.ps1
@@ -103,6 +114,9 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y libasound2-dev libssl-dev pkg-config git ripgrep
       - uses: dtolnay/rust-toolchain@1.98.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
       - uses: Swatinem/rust-cache@v2
         with:
           prefix-key: rust-test
@@ -147,6 +161,9 @@ jobs:
       - uses: dtolnay/rust-toolchain@1.98.0
         with:
           components: llvm-tools-preview
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
       - uses: Swatinem/rust-cache@v2
         with:
           prefix-key: rust-coverage

.github/workflows/homebrew.yml

@@ -31,7 +31,7 @@ jobs:
         with:
           formula-name: cortex
           homebrew-tap: CortexLM/homebrew-tap
-          download-url: https://github.com/${{ github.repository }}/releases/download/${{ steps.tag.outputs.tag }}/cortex-macos-arm64.tar.gz
+          download-url: https://github.com/${{ github.repository }}/releases/download/${{ steps.tag.outputs.tag }}/cortex-cli-macos-arm64.tar.gz
           commit-message: |
             {{formulaName}} {{version}}
 

.github/workflows/publish-r2.yml

@@ -129,6 +129,8 @@ jobs:
           EXPECTED_ARTIFACTS=(
             "cortex-cli-linux-x64"
             "cortex-cli-linux-arm64"
+            "cortex-cli-linux-x64-static"
+            "cortex-cli-linux-arm64-static"
             "cortex-cli-macos-x64"
             "cortex-cli-macos-arm64"
             "cortex-cli-windows-x64"
@@ -152,11 +154,11 @@ jobs:
         run: |
           mkdir -p dist
 
-          for mapping in linux-x86_64:cortex-cli-linux-x64 linux-aarch64:cortex-cli-linux-arm64 darwin-x86_64:cortex-cli-macos-x64 darwin-aarch64:cortex-cli-macos-arm64; do
+          for mapping in linux-x86_64:cortex-cli-linux-x64 linux-aarch64:cortex-cli-linux-arm64 linux-x86_64-musl:cortex-cli-linux-x64-static linux-aarch64-musl:cortex-cli-linux-arm64-static darwin-x86_64:cortex-cli-macos-x64 darwin-aarch64:cortex-cli-macos-arm64; do
             IFS=':' read -r platform artifact <<< "$mapping"
 
-            ARCHIVE=$(find "artifacts/$artifact" -name "*.tar.gz" | head -1)
-            if [ -z "$ARCHIVE" ]; then
+            ARCHIVE="artifacts/$artifact/$artifact.tar.gz"
+            if [ ! -f "$ARCHIVE" ]; then
               echo "ERROR: No .tar.gz found in artifacts/$artifact"
               ls -la "artifacts/$artifact/"
               exit 1
@@ -171,8 +173,8 @@ jobs:
           for mapping in windows-x86_64:cortex-cli-windows-x64; do
             IFS=':' read -r platform artifact <<< "$mapping"
 
-            ARCHIVE=$(find "artifacts/$artifact" -name "*.zip" | head -1)
-            if [ -z "$ARCHIVE" ]; then
+            ARCHIVE="artifacts/$artifact/$artifact.zip"
+            if [ ! -f "$ARCHIVE" ]; then
               echo "ERROR: No .zip found in artifacts/$artifact"
               ls -la "artifacts/$artifact/"
               exit 1
@@ -205,7 +207,8 @@ jobs:
             local sha
             sha=$(awk '{print $1}' "dist/$platform/${file}.sha256")
             local size
-            size=$(stat -c%s "dist/$platform/$file")
+            # wc -c is portable; GNU stat -c is unavailable on BSD/macOS.
+            size=$(wc -c < "dist/$platform/$file" | tr -d '[:space:]')
             jq -n --arg url "$url" --arg sha256 "$sha" --argjson size "$size" \
               '{url: $url, sha256: $sha256, size: $size}'
           }
@@ -218,6 +221,8 @@ jobs:
             --arg release_notes "$RELEASE_NOTES" \
             --argjson linux_x86_64 "$(asset_obj linux-x86_64 cortex.tar.gz)" \
             --argjson linux_aarch64 "$(asset_obj linux-aarch64 cortex.tar.gz)" \
+            --argjson linux_x86_64_musl "$(asset_obj linux-x86_64-musl cortex.tar.gz)" \
+            --argjson linux_aarch64_musl "$(asset_obj linux-aarch64-musl cortex.tar.gz)" \
             --argjson darwin_x86_64 "$(asset_obj darwin-x86_64 cortex.tar.gz)" \
             --argjson darwin_aarch64 "$(asset_obj darwin-aarch64 cortex.tar.gz)" \
             --argjson windows_x86_64 "$(asset_obj windows-x86_64 cortex.zip)" \
@@ -230,6 +235,8 @@ jobs:
               assets: {
                 "linux-x86_64": $linux_x86_64,
                 "linux-aarch64": $linux_aarch64,
+                "linux-x86_64-musl": $linux_x86_64_musl,
+                "linux-aarch64-musl": $linux_aarch64_musl,
                 "darwin-x86_64": $darwin_x86_64,
                 "darwin-aarch64": $darwin_aarch64,
                 "windows-x86_64": $windows_x86_64
@@ -271,7 +278,7 @@ jobs:
             rclone copyto "$src" "$REMOTE/$dest" --progress
           }
 
-          for platform in linux-x86_64 linux-aarch64 darwin-x86_64 darwin-aarch64; do
+          for platform in linux-x86_64 linux-aarch64 linux-x86_64-musl linux-aarch64-musl darwin-x86_64 darwin-aarch64; do
             echo "Uploading $platform..."
             r2_copy "dist/$platform/cortex.tar.gz" "v1/assets/$platform/$VERSION/cortex.tar.gz"
             r2_copy "dist/$platform/cortex.tar.gz.sha256" "v1/assets/$platform/$VERSION/cortex.tar.gz.sha256"

.github/workflows/release.yml

@@ -237,7 +237,7 @@ jobs:
       # =========================================================================
       - name: Build release binary (dynamic)
         if: matrix.static == false
-        run: cargo +nightly build --release --target ${{ matrix.target }} -p cortex-cli
+        run: cargo +nightly build --locked --release --target ${{ matrix.target }} -p cortex-cli
         env:
           RUSTFLAGS: ""
           CARGO_PROFILE_RELEASE_LTO: thin
@@ -246,7 +246,7 @@ jobs:
         if: matrix.target == 'x86_64-unknown-linux-musl'
         run: |
           # Build without audio feature (rodio/alsa) for musl - uses terminal bell fallback
-          cargo +nightly build --release --target ${{ matrix.target }} -p cortex-cli --no-default-features --features cortex-tui
+          cargo +nightly build --locked --release --target ${{ matrix.target }} -p cortex-cli --no-default-features --features cortex-tui
         env:
           RUSTFLAGS: "-Zthreads=32 -C target-feature=+crt-static"
           CARGO_PROFILE_RELEASE_LTO: thin
@@ -259,7 +259,7 @@ jobs:
         run: |
           # Build without audio feature (rodio/alsa) for musl - uses terminal bell fallback
           # Using native musl-gcc since we're on an ARM64 runner building for ARM64 target
-          cargo +nightly build --release --target ${{ matrix.target }} -p cortex-cli --no-default-features --features cortex-tui
+          cargo +nightly build --locked --release --target ${{ matrix.target }} -p cortex-cli --no-default-features --features cortex-tui
         env:
           RUSTFLAGS: "-Zthreads=32 -C target-feature=+crt-static"
           CARGO_PROFILE_RELEASE_LTO: thin
@@ -273,22 +273,17 @@ jobs:
       - name: Verify static binary
         if: matrix.static == true
         run: |
-          echo "=== Verifying static binary ==="
+          set -euo pipefail
           BINARY="target/${{ matrix.target }}/release/${{ env.BINARY_NAME }}"
           file "$BINARY"
-          echo ""
-          echo "=== Checking dynamic dependencies ==="
-          # For a truly static binary, ldd should report "not a dynamic executable"
-          # or show no dynamic dependencies
-          if ldd "$BINARY" 2>&1 | grep -q "not a dynamic executable\|statically linked"; then
-            echo "✅ Binary is statically linked"
-          else
-            echo "⚠️ Binary has some dynamic dependencies (expected for musl with linux-keyutils):"
-            ldd "$BINARY" 2>&1 || true
+          # readelf is deterministic for static PIE too; ldd text is not.
+          readelf -l "$BINARY" > program-headers.txt
+          readelf -d "$BINARY" > dynamic-headers.txt
+          if grep -q INTERP program-headers.txt || grep -q NEEDED dynamic-headers.txt; then
+            echo "::error::musl artifact is dynamically linked"
+            exit 1
           fi
-          echo ""
-          echo "=== Binary size ==="
-          ls -lh "$BINARY"
+          "$BINARY" --version
 
       - name: Prepare artifact (Unix)
         if: runner.os != 'Windows'
@@ -313,7 +308,7 @@ jobs:
           path: |
             ${{ matrix.artifact }}.tar.gz
             ${{ matrix.artifact }}.zip
-          if-no-files-found: ignore
+          if-no-files-found: error
 
   # ==========================================================================
   # Create GitHub Release (lightweight - 4 vCPU)
@@ -341,14 +336,22 @@ jobs:
 
       - name: Flatten and generate checksums
         run: |
-          cd artifacts
-          find . -type f \( -name "*.tar.gz" -o -name "*.zip" -o -name "*.dmg" -o -name "*.msi" -o -name "*.AppImage" \) -exec mv {} . \;
-          rm -rf cortex-*/ || true
-          sha256sum * > checksums-sha256.txt 2>/dev/null || true
-          echo "=== Release artifacts ==="
-          ls -la
-          echo "=== Checksums ==="
-          cat checksums-sha256.txt
+          set -euo pipefail
+          mkdir release-assets
+          for artifact in artifacts/*; do
+            [ -d "$artifact" ] || { echo "Unexpected artifact layout"; exit 1; }
+            name=$(basename "$artifact")
+            case "$name" in
+              cortex-cli-windows-x64) ext=zip ;;
+              cortex-cli-macos-x64|cortex-cli-macos-arm64|cortex-cli-linux-x64|cortex-cli-linux-arm64|cortex-cli-linux-x64-static|cortex-cli-linux-arm64-static) ext=tar.gz ;;
+              *) echo "Unexpected artifact: $name"; exit 1 ;;
+            esac
+            cp "$artifact/$name.$ext" release-assets/
+          done
+          [ "$(find release-assets -type f | wc -l)" -eq 7 ]
+          cd release-assets
+          sha256sum -- *.tar.gz *.zip > checksums-sha256.txt
+          sha256sum --check checksums-sha256.txt
 
       - name: Determine release name
         id: release_name
@@ -370,7 +373,7 @@ jobs:
           prerelease: ${{ contains(needs.prepare.outputs.version, '-') }}
           generate_release_notes: true
           files: |
-            artifacts/*
+            release-assets/*
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/winget.yml

@@ -40,24 +40,13 @@ jobs:
           $baseUrl = "https://github.com/${{ github.repository }}/releases/download/$tag"
           
           # Download and hash x64
-          $x64Url = "$baseUrl/cortex-windows-x64.zip"
+          $x64Url = "$baseUrl/cortex-cli-windows-x64.zip"
           Invoke-WebRequest -Uri $x64Url -OutFile "cortex-x64.zip" -ErrorAction Stop
           $x64Hash = (Get-FileHash -Path "cortex-x64.zip" -Algorithm SHA256).Hash
           
-          # Download and hash arm64
-          $arm64Url = "$baseUrl/cortex-windows-arm64.zip"
-          try {
-            Invoke-WebRequest -Uri $arm64Url -OutFile "cortex-arm64.zip" -ErrorAction Stop
-            $arm64Hash = (Get-FileHash -Path "cortex-arm64.zip" -Algorithm SHA256).Hash
-          } catch {
-            $arm64Hash = ""
-            $arm64Url = ""
-          }
-          
+          # ARM64 is intentionally absent from the release matrix.
           echo "x64_url=$x64Url" >> $env:GITHUB_OUTPUT
           echo "x64_hash=$x64Hash" >> $env:GITHUB_OUTPUT
-          echo "arm64_url=$arm64Url" >> $env:GITHUB_OUTPUT
-          echo "arm64_hash=$arm64Hash" >> $env:GITHUB_OUTPUT
 
       - name: Create winget manifest directory
         shell: pwsh
@@ -99,15 +88,6 @@ jobs:
               InstallerSha256: ${{ steps.release.outputs.x64_hash }}
           "@
           
-          if ("${{ steps.release.outputs.arm64_hash }}" -ne "") {
-            $installers += @"
-
-            - Architecture: arm64
-              InstallerUrl: ${{ steps.release.outputs.arm64_url }}
-              InstallerSha256: ${{ steps.release.outputs.arm64_hash }}
-          "@
-          }
-          
           $installers += @"
 
           ManifestType: installer
@@ -125,11 +105,11 @@ jobs:
           PackageLocale: en-US
           Publisher: CortexLM
           PublisherUrl: https://github.com/CortexLM
-          PublisherSupportUrl: https://github.com/CortexLM/cortex-cli/issues
+          PublisherSupportUrl: https://github.com/CortexLM/cli/issues
           PackageName: Cortex CLI
-          PackageUrl: https://github.com/CortexLM/cortex-cli
+          PackageUrl: https://github.com/CortexLM/cli
           License: Apache-2.0
-          LicenseUrl: https://github.com/CortexLM/cortex-cli/blob/master/LICENSE
+          LicenseUrl: https://github.com/CortexLM/cli/blob/main/LICENSE
           ShortDescription: Cortex CLI - A modern AI coding agent
           Description: Cortex is a powerful command-line AI coding assistant that helps developers write, debug, and maintain code more efficiently.
           Tags:
@@ -143,20 +123,26 @@ jobs:
           "@
           $content | Out-File -FilePath "${{ env.MANIFEST_DIR }}/${{ env.PACKAGE_ID }}.locale.en-US.yaml" -Encoding utf8
 
-      - name: Install wingetcreate
+      - name: Require provisioned package tooling
         shell: pwsh
         run: |
-          iwr https://aka.ms/wingetcreate/latest -OutFile wingetcreate.exe
+          # Do not execute an unpinned executable downloaded at publish time.
+          # The Windows runner image must provision the reviewed tooling.
+          $tool = Get-Command wingetcreate.exe -CommandType Application -ErrorAction Stop
+          $signature = Get-AuthenticodeSignature -FilePath $tool.Source
+          if ($signature.Status -ne 'Valid' -or $signature.SignerCertificate.Subject -notmatch 'O=Microsoft Corporation') {
+            throw 'wingetcreate must have a valid Microsoft signature'
+          }
 
       - name: Validate manifests
         shell: pwsh
         run: |
-          .\wingetcreate.exe validate ${{ env.MANIFEST_DIR }}
+          wingetcreate.exe validate ${{ env.MANIFEST_DIR }}
 
       - name: Submit to winget-pkgs
         shell: pwsh
         run: |
-          .\wingetcreate.exe submit ${{ env.MANIFEST_DIR }} --token ${{ secrets.WINGET_PAT }}
+          wingetcreate.exe submit ${{ env.MANIFEST_DIR }} --token $env:WINGET_PAT
         env:
           WINGET_PAT: ${{ secrets.WINGET_PAT }}