chore: update react to apply patch for CVE-2025-55182 (#21084)

Reference:

https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components
(cherry picked from commit 770fdb377c)

.claude/docs/TROUBLESHOOTING.md

@@ -91,6 +91,9 @@
 
 ## Systematic Debugging Approach
 
+YOU MUST ALWAYS find the root cause of any issue you are debugging
+YOU MUST NEVER fix a symptom or add a workaround instead of finding a root cause, even if it is faster.
+
 ### Multi-Issue Problem Solving
 
 When facing multiple failing tests or complex integration issues:
@@ -98,16 +101,21 @@ When facing multiple failing tests or complex integration issues:
 1. **Identify Root Causes**:
    - Run failing tests individually to isolate issues
    - Use LSP tools to trace through call chains
-   - Check both compilation and runtime errors
+   - Read Error Messages Carefully: Check both compilation and runtime errors
+   - Reproduce Consistently: Ensure you can reliably reproduce the issue before investigating
+   - Check Recent Changes: What changed that could have caused this? Git diff, recent commits, etc.
+   - When You Don't Know: Say "I don't understand X" rather than pretending to know
 
 2. **Fix in Logical Order**:
    - Address compilation issues first (imports, syntax)
    - Fix authorization and RBAC issues next
    - Resolve business logic and validation issues
    - Handle edge cases and race conditions last
+   - IF your first fix doesn't work, STOP and re-analyze rather than adding more fixes
 
 3. **Verification Strategy**:
-   - Test each fix individually before moving to next issue
+   - Always Test each fix individually before moving to next issue
+   - Verify Before Continuing: Did your test work? If not, form new hypothesis - don't add more fixes
    - Use `make lint` and `make gen` after database changes
    - Verify RFC compliance with actual specifications
    - Run comprehensive test suites before considering complete

.claude/docs/WORKFLOWS.md

@@ -40,11 +40,15 @@
 - Use proper error types
 - Pattern: `xerrors.Errorf("failed to X: %w", err)`
 
-### Naming Conventions
+## Naming Conventions
 
-- Use clear, descriptive names
-- Abbreviate only when obvious
+- Names MUST tell what code does, not how it's implemented or its history
 - Follow Go and TypeScript naming conventions
+- When changing code, never document the old behavior or the behavior change
+- NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
+- NEVER use temporal/historical context in names (e.g., "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")
+- NEVER use pattern names unless they add clarity (e.g., prefer "Tool" over "ToolFactory")
+- Abbreviate only when obvious
 
 ### Comments
 

.devcontainer/scripts/post_create.sh

@@ -1,13 +1,21 @@
 #!/bin/sh
 
 install_devcontainer_cli() {
-	npm install -g @devcontainers/cli@0.80.0 --integrity=sha512-w2EaxgjyeVGyzfA/KUEZBhyXqu/5PyWNXcnrXsZOBrt3aN2zyGiHrXoG54TF6K0b5DSCF01Rt5fnIyrCeFzFKw==
+	set -e
+	echo "🔧 Installing DevContainer CLI..."
+	cd "$(dirname "$0")/../tools/devcontainer-cli"
+	npm ci --omit=dev
+	ln -sf "$(pwd)/node_modules/.bin/devcontainer" "$(npm config get prefix)/bin/devcontainer"
 }
 
 install_ssh_config() {
 	echo "🔑 Installing SSH configuration..."
-	rsync -a /mnt/home/coder/.ssh/ ~/.ssh/
-	chmod 0700 ~/.ssh
+	if [ -d /mnt/home/coder/.ssh ]; then
+		rsync -a /mnt/home/coder/.ssh/ ~/.ssh/
+		chmod 0700 ~/.ssh
+	else
+		echo "⚠️ SSH directory not found."
+	fi
 }
 
 install_git_config() {

.devcontainer/tools/devcontainer-cli/package-lock.json

@@ -0,0 +1,26 @@
+{
+  "name": "devcontainer-cli",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "devcontainer-cli",
+      "version": "1.0.0",
+      "dependencies": {
+        "@devcontainers/cli": "^0.80.0"
+      }
+    },
+    "node_modules/@devcontainers/cli": {
+      "version": "0.80.0",
+      "resolved": "https://registry.npmjs.org/@devcontainers/cli/-/cli-0.80.0.tgz",
+      "integrity": "sha512-w2EaxgjyeVGyzfA/KUEZBhyXqu/5PyWNXcnrXsZOBrt3aN2zyGiHrXoG54TF6K0b5DSCF01Rt5fnIyrCeFzFKw==",
+      "bin": {
+        "devcontainer": "devcontainer.js"
+      },
+      "engines": {
+        "node": "^16.13.0 || >=18.0.0"
+      }
+    }
+  }
+}

.devcontainer/tools/devcontainer-cli/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "devcontainer-cli",
+  "private": true,
+  "version": "1.0.0",
+  "dependencies": {
+    "@devcontainers/cli": "^0.80.0"
+  }
+}

.github/.linkspector.yml

@@ -26,5 +26,8 @@ ignorePatterns:
   - pattern: "claude.ai"
   - pattern: "splunk.com"
   - pattern: "stackoverflow.com/questions"
+  - pattern: "developer.hashicorp.com/terraform/language"
+  - pattern: "platform.openai.com"
+  - pattern: "api.openai.com"
 aliveStatusCodes:
   - 200

.github/actions/setup-go/action.yaml

@@ -4,7 +4,7 @@ description: |
 inputs:
   version:
     description: "The Go version to use."
-    default: "1.24.6"
+    default: "1.24.10"
   use-preinstalled-go:
     description: "Whether to use preinstalled Go."
     default: "false"

.github/actions/setup-node/action.yaml

@@ -16,7 +16,7 @@ runs:
     - name: Setup Node
       uses: actions/setup-node@0a44ba7841725637a19e28fa30b79a866c81b0a6 # v4.0.4
       with:
-        node-version: 20.19.4
+        node-version: 22.19.0
         # See https://github.com/actions/setup-node#caching-global-packages-data
         cache: "pnpm"
         cache-dependency-path: ${{ inputs.directory }}/pnpm-lock.yaml

.github/actions/setup-sqlc/action.yaml

@@ -5,6 +5,13 @@ runs:
   using: "composite"
   steps:
     - name: Setup sqlc
-      uses: sqlc-dev/setup-sqlc@c0209b9199cd1cce6a14fc27cabcec491b651761 # v4.0.0
-      with:
-        sqlc-version: "1.27.0"
+      # uses: sqlc-dev/setup-sqlc@c0209b9199cd1cce6a14fc27cabcec491b651761 # v4.0.0
+      # with:
+      #   sqlc-version: "1.30.0"
+
+      # Switched to coder/sqlc fork to fix ambiguous column bug, see:
+      # - https://github.com/coder/sqlc/pull/1
+      # - https://github.com/sqlc-dev/sqlc/pull/4159
+      shell: bash
+      run: |
+        CGO_ENABLED=1 go install github.com/coder/sqlc/cmd/sqlc@aab4e865a51df0c43e1839f81a9d349b41d14f05

.github/actions/setup-tf/action.yaml

@@ -7,5 +7,5 @@ runs:
     - name: Install Terraform
       uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3.1.2
       with:
-        terraform_version: 1.13.0
+        terraform_version: 1.13.4
         terraform_wrapper: false

.github/dependabot.yaml

@@ -33,6 +33,7 @@ updates:
       - dependency-name: "*"
         update-types:
           - version-update:semver-patch
+      - dependency-name: "github.com/mark3labs/mcp-go"
 
   # Update our Dockerfile.
   - package-ecosystem: "docker"
@@ -79,6 +80,9 @@ updates:
       mui:
         patterns:
           - "@mui*"
+      radix:
+        patterns:
+          - "@radix-ui/*"
       react:
         patterns:
           - "react"
@@ -103,6 +107,7 @@ updates:
       - dependency-name: "*"
         update-types:
           - version-update:semver-major
+      - dependency-name: "@playwright/test"
     open-pull-requests-limit: 15
 
   - package-ecosystem: "terraform"

.github/fly-wsproxies/sao-paulo-coder.toml

@@ -1,34 +0,0 @@
-app = "sao-paulo-coder"
-primary_region = "gru"
-
-[experimental]
-  entrypoint = ["/bin/sh", "-c", "CODER_DERP_SERVER_RELAY_URL=\"http://[${FLY_PRIVATE_IP}]:3000\" /opt/coder wsproxy server"]
-  auto_rollback = true
-
-[build]
-  image = "ghcr.io/coder/coder-preview:main"
-
-[env]
-  CODER_ACCESS_URL = "https://sao-paulo.fly.dev.coder.com"
-  CODER_HTTP_ADDRESS = "0.0.0.0:3000"
-  CODER_PRIMARY_ACCESS_URL = "https://dev.coder.com"
-  CODER_WILDCARD_ACCESS_URL = "*--apps.sao-paulo.fly.dev.coder.com"
-  CODER_VERBOSE = "true"
-
-[http_service]
-  internal_port = 3000
-  force_https = true
-  auto_stop_machines = true
-  auto_start_machines = true
-  min_machines_running = 0
-
-# Ref: https://fly.io/docs/reference/configuration/#http_service-concurrency
-[http_service.concurrency]
-  type = "requests"
-  soft_limit = 50
-  hard_limit = 100
-
-[[vm]]
-  cpu_kind = "shared"
-  cpus = 2
-  memory_mb = 512

.github/pull_request_template.md

@@ -1 +1,5 @@
+<!--
+
 If you have used AI to produce some or all of this PR, please ensure you have read our [AI Contribution guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING) before submitting.
+
+-->

.github/workflows/ci.yaml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - release/*
 
   pull_request:
   workflow_dispatch:
@@ -34,12 +35,12 @@ jobs:
       tailnet-integration: ${{ steps.filter.outputs.tailnet-integration }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -123,7 +124,7 @@ jobs:
   #   runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
   #   steps:
   #     - name: Checkout
-  #       uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+  #       uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
   #       with:
   #         fetch-depth: 1
   #         # See: https://github.com/stefanzweifel/git-auto-commit-action?tab=readme-ov-file#commits-made-by-this-action-do-not-trigger-new-workflow-runs
@@ -156,12 +157,12 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -180,7 +181,7 @@ jobs:
           echo "LINT_CACHE_DIR=$dir" >> "$GITHUB_ENV"
 
       - name: golangci-lint cache
-        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
             ${{ env.LINT_CACHE_DIR }}
@@ -190,7 +191,7 @@ jobs:
 
       # Check for any typos
       - name: Check for typos
-        uses: crate-ci/typos@52bd719c2c91f9d676e2aa359fc8e0db8925e6d8 # v1.35.3
+        uses: crate-ci/typos@626c4bedb751ce0b7f03262ca97ddda9a076ae1c # v1.39.2
         with:
           config: .github/workflows/typos.toml
 
@@ -203,7 +204,7 @@ jobs:
 
       # Needed for helm chart linting
       - name: Install helm
-        uses: azure/setup-helm@b9e51907a09c216f16ebe8536097933489208112 # v4.3.0
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
         with:
           version: v3.9.2
 
@@ -229,17 +230,17 @@ jobs:
         shell: bash
 
   gen:
-    timeout-minutes: 8
+    timeout-minutes: 20
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     if: ${{ !cancelled() }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -270,6 +271,7 @@ jobs:
           popd
 
       - name: make gen
+        timeout-minutes: 8
         run: |
           # Remove golden files to detect discrepancy in generated files.
           make clean/golden-files
@@ -287,15 +289,15 @@ jobs:
     needs: changes
     if: needs.changes.outputs.offlinedocs-only == 'false' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
-    timeout-minutes: 7
+    timeout-minutes: 20
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -314,6 +316,7 @@ jobs:
         run: go install mvdan.cc/sh/v3/cmd/shfmt@v3.7.0
 
       - name: make fmt
+        timeout-minutes: 7
         run: |
           PATH="${PATH}:$(go env GOPATH)/bin" \
             make --output-sync -j -B fmt
@@ -340,7 +343,7 @@ jobs:
           - windows-2022
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
@@ -366,7 +369,7 @@ jobs:
         uses: coder/setup-ramdisk-action@e1100847ab2d7bcd9d14bcda8f2d1b0f07b36f1b # v0.1.0
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -375,13 +378,6 @@ jobs:
         id: go-paths
         uses: ./.github/actions/setup-go-paths
 
-      - name: Download Go Build Cache
-        id: download-go-build-cache
-        uses: ./.github/actions/test-cache/download
-        with:
-          key-prefix: test-go-build-${{ runner.os }}-${{ runner.arch }}
-          cache-path: ${{ steps.go-paths.outputs.cached-dirs }}
-
       - name: Setup Go
         uses: ./.github/actions/setup-go
         with:
@@ -389,8 +385,7 @@ jobs:
           # download the toolchain configured in go.mod, so we don't
           # need to reinstall it. It's faster on Windows runners.
           use-preinstalled-go: ${{ runner.os == 'Windows' }}
-          # Cache is already downloaded above
-          use-cache: false
+          use-cache: true
 
       - name: Setup Terraform
         uses: ./.github/actions/setup-tf
@@ -499,17 +494,11 @@ jobs:
           make test
 
       - name: Upload failed test db dumps
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: failed-test-db-dump-${{matrix.os}}
           path: "**/*.test.sql"
 
-      - name: Upload Go Build Cache
-        uses: ./.github/actions/test-cache/upload
-        with:
-          cache-key: ${{ steps.download-go-build-cache.outputs.cache-key }}
-          cache-path: ${{ steps.go-paths.outputs.cached-dirs }}
-
       - name: Upload Test Cache
         uses: ./.github/actions/test-cache/upload
         with:
@@ -531,9 +520,6 @@ jobs:
         with:
           api-key: ${{ secrets.DATADOG_API_KEY }}
 
-  # NOTE: this could instead be defined as a matrix strategy, but we want to
-  # only block merging if tests on postgres 13 fail. Using a matrix strategy
-  # here makes the check in the above `required` job rather complicated.
   test-go-pg-17:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     needs:
@@ -546,12 +532,12 @@ jobs:
     timeout-minutes: 25
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -595,12 +581,12 @@ jobs:
     timeout-minutes: 25
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -655,12 +641,12 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -682,12 +668,12 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -715,12 +701,12 @@ jobs:
     name: ${{ matrix.variant.name }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -764,15 +750,23 @@ jobs:
 
       - name: Upload Playwright Failed Tests
         if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: failed-test-videos${{ matrix.variant.premium && '-premium' || '' }}
           path: ./site/test-results/**/*.webm
           retention-days: 7
 
+      - name: Upload debug log
+        if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: coderd-debug-logs${{ matrix.variant.premium && '-premium' || ''  }}
+          path: ./site/e2e/test-results/debug.log
+          retention-days: 7
+
       - name: Upload pprof dumps
         if: always() && github.actor != 'dependabot[bot]' && runner.os == 'Linux' && !github.event.pull_request.head.repo.fork
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: debug-pprof-dumps${{ matrix.variant.premium && '-premium' || ''  }}
           path: ./site/test-results/**/debug-pprof-*.txt
@@ -787,12 +781,12 @@ jobs:
     if: needs.changes.outputs.site == 'true' || needs.changes.outputs.ci == 'true'
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           # 👇 Ensures Chromatic can read your full git history
           fetch-depth: 0
@@ -808,7 +802,7 @@ jobs:
       # the check to pass. This is desired in PRs, but not in mainline.
       - name: Publish to Chromatic (non-mainline)
         if: github.ref != 'refs/heads/main' && github.repository_owner == 'coder'
-        uses: chromaui/action@58d9ffb36c90c97a02d061544ecc849cc4a242a9 # v13.1.3
+        uses: chromaui/action@ac86f2ff0a458ffbce7b40698abd44c0fa34d4b6 # v13.3.3
         env:
           NODE_OPTIONS: "--max_old_space_size=4096"
           STORYBOOK: true
@@ -840,7 +834,7 @@ jobs:
       # infinitely "in progress" in mainline unless we re-review each build.
       - name: Publish to Chromatic (mainline)
         if: github.ref == 'refs/heads/main' && github.repository_owner == 'coder'
-        uses: chromaui/action@58d9ffb36c90c97a02d061544ecc849cc4a242a9 # v13.1.3
+        uses: chromaui/action@ac86f2ff0a458ffbce7b40698abd44c0fa34d4b6 # v13.3.3
         env:
           NODE_OPTIONS: "--max_old_space_size=4096"
           STORYBOOK: true
@@ -868,12 +862,12 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           # 0 is required here for version.sh to work.
           fetch-depth: 0
@@ -922,10 +916,12 @@ jobs:
   required:
     runs-on: ubuntu-latest
     needs:
+      - changes
       - fmt
       - lint
       - gen
       - test-go-pg
+      - test-go-pg-17
       - test-go-race-pg
       - test-js
       - test-e2e
@@ -937,17 +933,19 @@ jobs:
     if: always()
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Ensure required checks
         run: | # zizmor: ignore[template-injection] We're just reading needs.x.result here, no risk of injection
           echo "Checking required checks"
+          echo "- changes: ${{ needs.changes.result }}"
           echo "- fmt: ${{ needs.fmt.result }}"
           echo "- lint: ${{ needs.lint.result }}"
           echo "- gen: ${{ needs.gen.result }}"
           echo "- test-go-pg: ${{ needs.test-go-pg.result }}"
+          echo "- test-go-pg-17: ${{ needs.test-go-pg-17.result }}"
           echo "- test-go-race-pg: ${{ needs.test-go-race-pg.result }}"
           echo "- test-js: ${{ needs.test-js.result }}"
           echo "- test-e2e: ${{ needs.test-e2e.result }}"
@@ -968,12 +966,12 @@ jobs:
     needs: changes
     # We always build the dylibs on Go changes to verify we're not merging unbuildable code,
     # but they need only be signed and uploaded on coder/coder main.
-    if: needs.changes.outputs.go == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
+    if: needs.changes.outputs.go == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-macos-latest' || 'macos-latest' }}
     steps:
       # Harden Runner doesn't work on macOS
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -996,7 +994,7 @@ jobs:
         uses: ./.github/actions/setup-go
 
       - name: Install rcodesign
-        if: ${{ github.repository_owner == 'coder' && github.ref == 'refs/heads/main' }}
+        if: ${{ github.repository_owner == 'coder' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) }}
         run: |
           set -euo pipefail
           wget -O /tmp/rcodesign.tar.gz https://github.com/indygreg/apple-platform-rs/releases/download/apple-codesign%2F0.22.0/apple-codesign-0.22.0-macos-universal.tar.gz
@@ -1007,7 +1005,7 @@ jobs:
           rm /tmp/rcodesign.tar.gz
 
       - name: Setup Apple Developer certificate and API key
-        if: ${{ github.repository_owner == 'coder' && github.ref == 'refs/heads/main' }}
+        if: ${{ github.repository_owner == 'coder' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) }}
         run: |
           set -euo pipefail
           touch /tmp/{apple_cert.p12,apple_cert_password.txt,apple_apikey.p8}
@@ -1028,13 +1026,13 @@ jobs:
           make gen/mark-fresh
           make build/coder-dylib
         env:
-          CODER_SIGN_DARWIN: ${{ github.ref == 'refs/heads/main' && '1' || '0' }}
+          CODER_SIGN_DARWIN: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) && '1' || '0' }}
           AC_CERTIFICATE_FILE: /tmp/apple_cert.p12
           AC_CERTIFICATE_PASSWORD_FILE: /tmp/apple_cert_password.txt
 
       - name: Upload build artifacts
-        if: ${{ github.repository_owner == 'coder' && github.ref == 'refs/heads/main' }}
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: ${{ github.repository_owner == 'coder' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) }}
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: dylibs
           path: |
@@ -1043,7 +1041,7 @@ jobs:
           retention-days: 7
 
       - name: Delete Apple Developer certificate and API key
-        if: ${{ github.repository_owner == 'coder' && github.ref == 'refs/heads/main' }}
+        if: ${{ github.repository_owner == 'coder' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) }}
         run: rm -f /tmp/{apple_cert.p12,apple_cert_password.txt,apple_apikey.p8}
 
   check-build:
@@ -1055,12 +1053,12 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -1093,7 +1091,7 @@ jobs:
     needs:
       - changes
       - build-dylib
-    if: github.ref == 'refs/heads/main' && needs.changes.outputs.docs-only == 'false' && !github.event.pull_request.head.repo.fork
+    if: (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')) && needs.changes.outputs.docs-only == 'false' && !github.event.pull_request.head.repo.fork
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-22.04' }}
     permissions:
       # Necessary to push docker images to ghcr.io.
@@ -1110,18 +1108,18 @@ jobs:
       IMAGE: ghcr.io/coder/coder-preview:${{ steps.build-docker.outputs.tag }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
 
       - name: GHCR Login
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -1156,7 +1154,7 @@ jobs:
 
       # Necessary for signing Windows binaries.
       - name: Setup Java
-        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
         with:
           distribution: "zulu"
           java-version: "11.0"
@@ -1189,17 +1187,17 @@ jobs:
       # Setup GCloud for signing Windows binaries.
       - name: Authenticate to Google Cloud
         id: gcloud_auth
-        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
         with:
           workload_identity_provider: ${{ vars.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
           service_account: ${{ vars.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
           token_format: "access_token"
 
       - name: Setup GCloud SDK
-        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # v2.2.0
+        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db # v3.0.1
 
       - name: Download dylibs
-        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: dylibs
           path: ./build
@@ -1246,40 +1244,45 @@ jobs:
         id: build-docker
         env:
           CODER_IMAGE_BASE: ghcr.io/coder/coder-preview
-          CODER_IMAGE_TAG_PREFIX: main
           DOCKER_CLI_EXPERIMENTAL: "enabled"
         run: |
           set -euxo pipefail
 
           # build Docker images for each architecture
           version="$(./scripts/version.sh)"
-          tag="main-${version//+/-}"
+          tag="${version//+/-}"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
 
           # build images for each architecture
           # note: omitting the -j argument to avoid race conditions when pushing
           make build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
 
-          # only push if we are on main branch
-          if [ "${GITHUB_REF}" == "refs/heads/main" ]; then
+          # only push if we are on main branch or release branch
+          if [[ "${GITHUB_REF}" == "refs/heads/main" || "${GITHUB_REF}" == refs/heads/release/* ]]; then
             # build and push multi-arch manifest, this depends on the other images
             # being pushed so will automatically push them
             # note: omitting the -j argument to avoid race conditions when pushing
             make push/build/coder_"$version"_linux_{amd64,arm64,armv7}.tag
 
             # Define specific tags
-            tags=("$tag" "main" "latest")
+            tags=("$tag")
+            if [ "${GITHUB_REF}" == "refs/heads/main" ]; then
+              tags+=("main" "latest")
+            elif [[ "${GITHUB_REF}" == refs/heads/release/* ]]; then
+              tags+=("release-${GITHUB_REF#refs/heads/release/}")
+            fi
 
             # Create and push a multi-arch manifest for each tag
             # we are adding `latest` tag and keeping `main` for backward
             # compatibality
             for t in "${tags[@]}"; do
-                # shellcheck disable=SC2046
-                ./scripts/build_docker_multiarch.sh \
-                    --push \
-                    --target "ghcr.io/coder/coder-preview:$t" \
-                    --version "$version" \
-                    $(cat build/coder_"$version"_linux_{amd64,arm64,armv7}.tag)
+              echo "Pushing multi-arch manifest for tag: $t"
+              # shellcheck disable=SC2046
+              ./scripts/build_docker_multiarch.sh \
+                  --push \
+                  --target "ghcr.io/coder/coder-preview:$t" \
+                  --version "$version" \
+                  $(cat build/coder_"$version"_linux_{amd64,arm64,armv7}.tag)
             done
           fi
 
@@ -1323,7 +1326,7 @@ jobs:
         id: attest_main
         if: github.ref == 'refs/heads/main'
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: "ghcr.io/coder/coder-preview:main"
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -1360,7 +1363,7 @@ jobs:
         id: attest_latest
         if: github.ref == 'refs/heads/main'
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: "ghcr.io/coder/coder-preview:latest"
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -1397,7 +1400,7 @@ jobs:
         id: attest_version
         if: github.ref == 'refs/heads/main'
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: "ghcr.io/coder/coder-preview:${{ steps.build-docker.outputs.tag }}"
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -1461,7 +1464,7 @@ jobs:
 
       - name: Upload build artifacts
         if: github.ref == 'refs/heads/main'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: coder
           path: |
@@ -1470,112 +1473,28 @@ jobs:
             ./build/*.deb
           retention-days: 7
 
+  # Deploy is handled in deploy.yaml so we can apply concurrency limits.
   deploy:
-    name: "deploy"
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
     needs:
       - changes
       - build
     if: |
-      github.ref == 'refs/heads/main' && !github.event.pull_request.head.repo.fork
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/'))
       && needs.changes.outputs.docs-only == 'false'
+      && !github.event.pull_request.head.repo.fork
+    uses: ./.github/workflows/deploy.yaml
+    with:
+      image: ${{ needs.build.outputs.IMAGE }}
     permissions:
       contents: read
       id-token: write
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
-        with:
-          workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
-          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
-
-      - name: Set up Google Cloud SDK
-        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # v2.2.0
-
-      - name: Set up Flux CLI
-        uses: fluxcd/flux2/action@6bf37f6a560fd84982d67f853162e4b3c2235edb # v2.6.4
-        with:
-          # Keep this and the github action up to date with the version of flux installed in dogfood cluster
-          version: "2.5.1"
-
-      - name: Get Cluster Credentials
-        uses: google-github-actions/get-gke-credentials@8e574c49425fa7efed1e74650a449bfa6a23308a # v2.3.4
-        with:
-          cluster_name: dogfood-v2
-          location: us-central1-a
-          project_id: coder-dogfood-v2
-
-      - name: Reconcile Flux
-        run: |
-          set -euxo pipefail
-          flux --namespace flux-system reconcile source git flux-system
-          flux --namespace flux-system reconcile source git coder-main
-          flux --namespace flux-system reconcile kustomization flux-system
-          flux --namespace flux-system reconcile kustomization coder
-          flux --namespace flux-system reconcile source chart coder-coder
-          flux --namespace flux-system reconcile source chart coder-coder-provisioner
-          flux --namespace coder reconcile helmrelease coder
-          flux --namespace coder reconcile helmrelease coder-provisioner
-
-      # Just updating Flux is usually not enough. The Helm release may get
-      # redeployed, but unless something causes the Deployment to update the
-      # pods won't be recreated. It's important that the pods get recreated,
-      # since we use `imagePullPolicy: Always` to ensure we're running the
-      # latest image.
-      - name: Rollout Deployment
-        run: |
-          set -euxo pipefail
-          kubectl --namespace coder rollout restart deployment/coder
-          kubectl --namespace coder rollout status deployment/coder
-          kubectl --namespace coder rollout restart deployment/coder-provisioner
-          kubectl --namespace coder rollout status deployment/coder-provisioner
-          kubectl --namespace coder rollout restart deployment/coder-provisioner-tagged
-          kubectl --namespace coder rollout status deployment/coder-provisioner-tagged
-
-  deploy-wsproxies:
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main' && !github.event.pull_request.head.repo.fork
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
-        with:
-          egress-policy: audit
-
-      - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-
-      - name: Setup flyctl
-        uses: superfly/flyctl-actions/setup-flyctl@fc53c09e1bc3be6f54706524e3b82c4f462f77be # v1.5
-
-      - name: Deploy workspace proxies
-        run: |
-          flyctl deploy --image "$IMAGE" --app paris-coder --config ./.github/fly-wsproxies/paris-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_PARIS" --yes
-          flyctl deploy --image "$IMAGE" --app sydney-coder --config ./.github/fly-wsproxies/sydney-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_SYDNEY" --yes
-          flyctl deploy --image "$IMAGE" --app sao-paulo-coder --config ./.github/fly-wsproxies/sao-paulo-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_SAO_PAULO" --yes
-          flyctl deploy --image "$IMAGE" --app jnb-coder --config ./.github/fly-wsproxies/jnb-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_JNB" --yes
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
-          IMAGE: ${{ needs.build.outputs.IMAGE }}
-          TOKEN_PARIS: ${{ secrets.FLY_PARIS_CODER_PROXY_SESSION_TOKEN }}
-          TOKEN_SYDNEY: ${{ secrets.FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN }}
-          TOKEN_SAO_PAULO: ${{ secrets.FLY_SAO_PAULO_CODER_PROXY_SESSION_TOKEN }}
-          TOKEN_JNB: ${{ secrets.FLY_JNB_CODER_PROXY_SESSION_TOKEN }}
+      packages: write # to retag image as dogfood
+    secrets:
+      FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      FLY_PARIS_CODER_PROXY_SESSION_TOKEN: ${{ secrets.FLY_PARIS_CODER_PROXY_SESSION_TOKEN }}
+      FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN: ${{ secrets.FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN }}
+      FLY_SAO_PAULO_CODER_PROXY_SESSION_TOKEN: ${{ secrets.FLY_SAO_PAULO_CODER_PROXY_SESSION_TOKEN }}
+      FLY_JNB_CODER_PROXY_SESSION_TOKEN: ${{ secrets.FLY_JNB_CODER_PROXY_SESSION_TOKEN }}
 
   # sqlc-vet runs a postgres docker container, runs Coder migrations, and then
   # runs sqlc-vet to ensure all queries are valid. This catches any mistakes
@@ -1586,12 +1505,12 @@ jobs:
     if: needs.changes.outputs.db == 'true' || needs.changes.outputs.ci == 'true' || github.ref == 'refs/heads/main'
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -1614,6 +1533,7 @@ jobs:
     steps:
       - name: Send Slack notification
         run: |
+          ESCAPED_PROMPT=$(printf "%s" "<@U09LQ75AHKR> $BLINK_CI_FAILURE_PROMPT" | jq -Rsa .)
           curl -X POST -H 'Content-type: application/json' \
           --data '{
             "blocks": [
@@ -1625,23 +1545,6 @@ jobs:
                   "emoji": true
                 }
               },
-              {
-                "type": "section",
-                "fields": [
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Workflow:*\n'"${GITHUB_WORKFLOW}"'"
-                  },
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Committer:*\n'"${GITHUB_ACTOR}"'"
-                  },
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Commit:*\n'"${GITHUB_SHA}"'"
-                  }
-                ]
-              },
               {
                 "type": "section",
                 "text": {
@@ -1653,7 +1556,7 @@ jobs:
                 "type": "section",
                 "text": {
                   "type": "mrkdwn",
-                  "text": "<@U08TJ4YNCA3> investigate this CI failure. Check logs, search for existing issues, use git blame to find who last modified failing tests, create issue in coder/internal (not public repo), use title format \"flake: TestName\" for flaky tests, and assign to the person from git blame."
+                  "text": '"$ESCAPED_PROMPT"'
                 }
               }
             ]
@@ -1661,3 +1564,4 @@ jobs:
         env:
           SLACK_WEBHOOK: ${{ secrets.CI_FAILURE_SLACK_WEBHOOK }}
           RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          BLINK_CI_FAILURE_PROMPT: ${{ vars.BLINK_CI_FAILURE_PROMPT }}

.github/workflows/contrib.yaml

@@ -53,7 +53,7 @@ jobs:
     if: ${{ github.event_name == 'pull_request_target' && !github.event.pull_request.draft }}
     steps:
       - name: release-labels
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           # This script ensures PR title and labels are in sync:
           #

.github/workflows/deploy.yaml

@@ -0,0 +1,172 @@
+name: deploy
+
+on:
+  # Via workflow_call, called from ci.yaml
+  workflow_call:
+    inputs:
+      image:
+        description: "Image and tag to potentially deploy. Current branch will be validated against should-deploy check."
+        required: true
+        type: string
+    secrets:
+      FLY_API_TOKEN:
+        required: true
+      FLY_PARIS_CODER_PROXY_SESSION_TOKEN:
+        required: true
+      FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN:
+        required: true
+      FLY_SAO_PAULO_CODER_PROXY_SESSION_TOKEN:
+        required: true
+      FLY_JNB_CODER_PROXY_SESSION_TOKEN:
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }} # no per-branch concurrency
+  cancel-in-progress: false
+
+jobs:
+  # Determines if the given branch should be deployed to dogfood.
+  should-deploy:
+    name: should-deploy
+    runs-on: ubuntu-latest
+    outputs:
+      verdict: ${{ steps.check.outputs.verdict }} # DEPLOY or NOOP
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check if deploy is enabled
+        id: check
+        run: |
+          set -euo pipefail
+          verdict="$(./scripts/should_deploy.sh)"
+          echo "verdict=$verdict" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    name: "deploy"
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    needs: should-deploy
+    if: needs.should-deploy.outputs.verdict == 'DEPLOY'
+    permissions:
+      contents: read
+      id-token: write
+      packages: write # to retag image as dogfood
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: GHCR Login
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
+        with:
+          workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
+          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
+
+      - name: Set up Google Cloud SDK
+        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db # v3.0.1
+
+      - name: Set up Flux CLI
+        uses: fluxcd/flux2/action@b6e76ca2534f76dcb8dd94fb057cdfa923c3b641 # v2.7.3
+        with:
+          # Keep this and the github action up to date with the version of flux installed in dogfood cluster
+          version: "2.7.0"
+
+      - name: Get Cluster Credentials
+        uses: google-github-actions/get-gke-credentials@3da1e46a907576cefaa90c484278bb5b259dd395 # v3.0.0
+        with:
+          cluster_name: dogfood-v2
+          location: us-central1-a
+          project_id: coder-dogfood-v2
+
+      # Retag image as dogfood while maintaining the multi-arch manifest
+      - name: Tag image as dogfood
+        run: docker buildx imagetools create --tag "ghcr.io/coder/coder-preview:dogfood" "$IMAGE"
+        env:
+          IMAGE: ${{ inputs.image }}
+
+      - name: Reconcile Flux
+        run: |
+          set -euxo pipefail
+          flux --namespace flux-system reconcile source git flux-system
+          flux --namespace flux-system reconcile source git coder-main
+          flux --namespace flux-system reconcile kustomization flux-system
+          flux --namespace flux-system reconcile kustomization coder
+          flux --namespace flux-system reconcile source chart coder-coder
+          flux --namespace flux-system reconcile source chart coder-coder-provisioner
+          flux --namespace coder reconcile helmrelease coder
+          flux --namespace coder reconcile helmrelease coder-provisioner
+          flux --namespace coder reconcile helmrelease coder-provisioner-tagged
+          flux --namespace coder reconcile helmrelease coder-provisioner-tagged-prebuilds
+
+      # Just updating Flux is usually not enough. The Helm release may get
+      # redeployed, but unless something causes the Deployment to update the
+      # pods won't be recreated. It's important that the pods get recreated,
+      # since we use `imagePullPolicy: Always` to ensure we're running the
+      # latest image.
+      - name: Rollout Deployment
+        run: |
+          set -euxo pipefail
+          kubectl --namespace coder rollout restart deployment/coder
+          kubectl --namespace coder rollout status deployment/coder
+          kubectl --namespace coder rollout restart deployment/coder-provisioner
+          kubectl --namespace coder rollout status deployment/coder-provisioner
+          kubectl --namespace coder rollout restart deployment/coder-provisioner-tagged
+          kubectl --namespace coder rollout status deployment/coder-provisioner-tagged
+          kubectl --namespace coder rollout restart deployment/coder-provisioner-tagged-prebuilds
+          kubectl --namespace coder rollout status deployment/coder-provisioner-tagged-prebuilds
+
+  deploy-wsproxies:
+    runs-on: ubuntu-latest
+    needs: deploy
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup flyctl
+        uses: superfly/flyctl-actions/setup-flyctl@fc53c09e1bc3be6f54706524e3b82c4f462f77be # v1.5
+
+      - name: Deploy workspace proxies
+        run: |
+          flyctl deploy --image "$IMAGE" --app paris-coder --config ./.github/fly-wsproxies/paris-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_PARIS" --yes
+          flyctl deploy --image "$IMAGE" --app sydney-coder --config ./.github/fly-wsproxies/sydney-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_SYDNEY" --yes
+          flyctl deploy --image "$IMAGE" --app jnb-coder --config ./.github/fly-wsproxies/jnb-coder.toml --env "CODER_PROXY_SESSION_TOKEN=$TOKEN_JNB" --yes
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+          IMAGE: ${{ inputs.image }}
+          TOKEN_PARIS: ${{ secrets.FLY_PARIS_CODER_PROXY_SESSION_TOKEN }}
+          TOKEN_SYDNEY: ${{ secrets.FLY_SYDNEY_CODER_PROXY_SESSION_TOKEN }}
+          TOKEN_JNB: ${{ secrets.FLY_JNB_CODER_PROXY_SESSION_TOKEN }}

.github/workflows/doc-check.yaml

@@ -0,0 +1,205 @@
+# This workflow checks if a PR requires documentation updates.
+# It creates a Coder Task that uses AI to analyze the PR changes,
+# search existing docs, and comment with recommendations.
+#
+# Triggered by: Adding the "doc-check" label to a PR, or manual dispatch.
+
+name: AI Documentation Check
+
+on:
+  pull_request:
+    types:
+      - labeled
+  workflow_dispatch:
+    inputs:
+      pr_url:
+        description: "Pull Request URL to check"
+        required: true
+        type: string
+      template_preset:
+        description: "Template preset to use"
+        required: false
+        default: ""
+        type: string
+
+jobs:
+  doc-check:
+    name: Analyze PR for Documentation Updates Needed
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.label.name == 'doc-check' || github.event_name == 'workflow_dispatch') &&
+      (github.event.pull_request.draft == false || github.event_name == 'workflow_dispatch')
+    timeout-minutes: 30
+    env:
+      CODER_URL: ${{ secrets.DOC_CHECK_CODER_URL }}
+      CODER_SESSION_TOKEN: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}
+    permissions:
+      contents: read
+      pull-requests: write
+      actions: write
+
+    steps:
+      - name: Determine PR Context
+        id: determine-context
+        env:
+          GITHUB_ACTOR: ${{ github.actor }}
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+          GITHUB_EVENT_PR_HTML_URL: ${{ github.event.pull_request.html_url }}
+          GITHUB_EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+          GITHUB_EVENT_SENDER_ID: ${{ github.event.sender.id }}
+          GITHUB_EVENT_SENDER_LOGIN: ${{ github.event.sender.login }}
+          INPUTS_PR_URL: ${{ inputs.pr_url }}
+          INPUTS_TEMPLATE_PRESET: ${{ inputs.template_preset || '' }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "Using template preset: ${INPUTS_TEMPLATE_PRESET}"
+          echo "template_preset=${INPUTS_TEMPLATE_PRESET}" >> "${GITHUB_OUTPUT}"
+
+          # For workflow_dispatch, use the provided PR URL
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            if ! GITHUB_USER_ID=$(gh api "users/${GITHUB_ACTOR}" --jq '.id'); then
+              echo "::error::Failed to get GitHub user ID for actor ${GITHUB_ACTOR}"
+              exit 1
+            fi
+            echo "Using workflow_dispatch actor: ${GITHUB_ACTOR} (ID: ${GITHUB_USER_ID})"
+            echo "github_user_id=${GITHUB_USER_ID}" >> "${GITHUB_OUTPUT}"
+            echo "github_username=${GITHUB_ACTOR}" >> "${GITHUB_OUTPUT}"
+
+            echo "Using PR URL: ${INPUTS_PR_URL}"
+            # Convert /pull/ to /issues/ for create-task-action compatibility
+            ISSUE_URL="${INPUTS_PR_URL/\/pull\//\/issues\/}"
+            echo "pr_url=${ISSUE_URL}" >> "${GITHUB_OUTPUT}"
+
+            # Extract PR number from URL for later use
+            PR_NUMBER=$(echo "${INPUTS_PR_URL}" | grep -oP '(?<=pull/)\d+')
+            echo "pr_number=${PR_NUMBER}" >> "${GITHUB_OUTPUT}"
+
+          elif [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            GITHUB_USER_ID=${GITHUB_EVENT_SENDER_ID}
+            echo "Using label adder: ${GITHUB_EVENT_SENDER_LOGIN} (ID: ${GITHUB_USER_ID})"
+            echo "github_user_id=${GITHUB_USER_ID}" >> "${GITHUB_OUTPUT}"
+            echo "github_username=${GITHUB_EVENT_SENDER_LOGIN}" >> "${GITHUB_OUTPUT}"
+
+            echo "Using PR URL: ${GITHUB_EVENT_PR_HTML_URL}"
+            # Convert /pull/ to /issues/ for create-task-action compatibility
+            ISSUE_URL="${GITHUB_EVENT_PR_HTML_URL/\/pull\//\/issues\/}"
+            echo "pr_url=${ISSUE_URL}" >> "${GITHUB_OUTPUT}"
+            echo "pr_number=${GITHUB_EVENT_PR_NUMBER}" >> "${GITHUB_OUTPUT}"
+
+          else
+            echo "::error::Unsupported event type: ${GITHUB_EVENT_NAME}"
+            exit 1
+          fi
+
+      - name: Extract changed files and build prompt
+        id: extract-context
+        env:
+          PR_URL: ${{ steps.determine-context.outputs.pr_url }}
+          PR_NUMBER: ${{ steps.determine-context.outputs.pr_number }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "Analyzing PR #${PR_NUMBER}"
+
+          # Build task prompt - using unquoted heredoc so variables expand
+          TASK_PROMPT=$(cat <<EOF
+          Review PR #${PR_NUMBER} and determine if documentation needs updating or creating.
+
+          PR URL: ${PR_URL}
+
+          WORKFLOW:
+            1. Setup (repo is pre-cloned at ~/coder)
+               cd ~/coder
+               git fetch origin pull/${PR_NUMBER}/head:pr-${PR_NUMBER}
+               git checkout pr-${PR_NUMBER}
+
+            2. Get PR info
+               Use GitHub MCP tools to get PR title, body, and diff
+               Or use: git diff main...pr-${PR_NUMBER}
+
+            3. Understand Changes
+               Read the diff and identify what changed
+               Ask: Is this user-facing? Does it change behavior? Is it a new feature?
+
+            4. Search for Related Docs
+               cat ~/coder/docs/manifest.json | jq '.routes[] | {title, path}' | head -50
+               grep -ri "relevant_term" ~/coder/docs/ --include="*.md"
+
+            5. Decide
+               NEEDS DOCS if: New feature, API change, CLI change, behavior change, user-visible
+               NO DOCS if: Internal refactor, test-only, already documented, non-user-facing, dependency updates
+               FIRST check: Did this PR already update docs? If yes and complete, say "No Changes Needed"
+
+            6. Comment on the PR using this format
+
+          COMMENT FORMAT:
+          ## 📚 Documentation Check
+
+          ### ✅ Updates Needed
+          - **[docs/path/file.md](github_link)** - Brief what needs changing
+
+          ### 📝 New Docs Needed
+          - **docs/suggested/location.md** - What should be documented
+
+          ### ✨ No Changes Needed
+          [Reason: Documents already updated in PR | Internal changes only | Test-only | No user-facing impact]
+
+          ---
+          *This comment was generated by an AI Agent through [Coder Tasks](https://coder.com/docs/ai-coder/tasks)*
+
+          DOCS STRUCTURE:
+            Read ~/coder/docs/manifest.json for the complete documentation structure.
+            Common areas include: reference/, admin/, user-guides/, ai-coder/, install/, tutorials/
+            But check manifest.json - it has everything.
+
+          EOF
+          )
+
+          # Output the prompt
+          {
+            echo "task_prompt<<EOFOUTPUT"
+            echo "${TASK_PROMPT}"
+            echo "EOFOUTPUT"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Checkout create-task-action
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 1
+          path: ./.github/actions/create-task-action
+          persist-credentials: false
+          ref: main
+          repository: coder/create-task-action
+
+      - name: Create Coder Task for Documentation Check
+        id: create_task
+        uses: ./.github/actions/create-task-action
+        with:
+          coder-url: ${{ secrets.DOC_CHECK_CODER_URL }}
+          coder-token: ${{ secrets.DOC_CHECK_CODER_SESSION_TOKEN }}
+          coder-organization: "default"
+          coder-template-name: coder
+          coder-template-preset: ${{ steps.determine-context.outputs.template_preset }}
+          coder-task-name-prefix: doc-check
+          coder-task-prompt: ${{ steps.extract-context.outputs.task_prompt }}
+          github-user-id: ${{ steps.determine-context.outputs.github_user_id }}
+          github-token: ${{ github.token }}
+          github-issue-url: ${{ steps.determine-context.outputs.pr_url }}
+          comment-on-issue: true
+
+      - name: Write outputs
+        env:
+          TASK_CREATED: ${{ steps.create_task.outputs.task-created }}
+          TASK_NAME: ${{ steps.create_task.outputs.task-name }}
+          TASK_URL: ${{ steps.create_task.outputs.task-url }}
+          PR_URL: ${{ steps.determine-context.outputs.pr_url }}
+        run: |
+          {
+            echo "## Documentation Check Task"
+            echo ""
+            echo "**PR:** ${PR_URL}"
+            echo "**Task created:** ${TASK_CREATED}"
+            echo "**Task name:** ${TASK_NAME}"
+            echo "**Task URL:** ${TASK_URL}"
+            echo ""
+            echo "The Coder task is analyzing the PR changes and will comment with documentation recommendations."
+          } >> "${GITHUB_STEP_SUMMARY}"

.github/workflows/docker-base.yaml

@@ -38,17 +38,17 @@ jobs:
     if: github.repository_owner == 'coder'
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: Docker login
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -62,7 +62,7 @@ jobs:
 
       # This uses OIDC authentication, so no auth variables are required.
       - name: Build base Docker image via depot.dev
-        uses: depot/build-push-action@2583627a84956d07561420dcc1d0eb1f2af3fac0 # v1.15.0
+        uses: depot/build-push-action@9785b135c3c76c33db102e45be96a25ab55cd507 # v1.16.2
         with:
           project: wl5hnrrkns
           context: base-build-context

.github/workflows/docs-ci.yaml

@@ -23,14 +23,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: Setup Node
         uses: ./.github/actions/setup-node
 
-      - uses: tj-actions/changed-files@f963b3f3562b00b6d2dd25efc390eb04e51ef6c6 # v45.0.7
+      - uses: tj-actions/changed-files@70069877f29101175ed2b055d210fe8b1d54d7d7 # v45.0.7
         id: changed-files
         with:
           files: |

.github/workflows/dogfood.yaml

@@ -26,21 +26,21 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-4' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: Setup Nix
-        uses: nixbuild/nix-quick-install-action@63ca48f939ee3b8d835f4126562537df0fee5b91 # v32
+        uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
         with:
           # Pinning to 2.28 here, as Nix gets a "error: [json.exception.type_error.302] type must be array, but is string"
           # on version 2.29 and above.
-          nix_version: "2.28.4"
+          nix_version: "2.28.5"
 
       - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
         with:
@@ -82,13 +82,13 @@ jobs:
 
       - name: Login to DockerHub
         if: github.ref == 'refs/heads/main'
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_PASSWORD }}
 
       - name: Build and push Non-Nix image
-        uses: depot/build-push-action@2583627a84956d07561420dcc1d0eb1f2af3fac0 # v1.15.0
+        uses: depot/build-push-action@9785b135c3c76c33db102e45be96a25ab55cd507 # v1.16.2
         with:
           project: b4q6ltmpzh
           token: ${{ secrets.DEPOT_TOKEN }}
@@ -125,12 +125,12 @@ jobs:
       id-token: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
@@ -138,7 +138,7 @@ jobs:
         uses: ./.github/actions/setup-tf
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
         with:
           workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
           service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

.github/workflows/nightly-gauntlet.yaml

@@ -27,7 +27,7 @@ jobs:
           - windows-2022
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
@@ -53,7 +53,7 @@ jobs:
         uses: coder/setup-ramdisk-action@e1100847ab2d7bcd9d14bcda8f2d1b0f07b36f1b # v0.1.0
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false
@@ -143,7 +143,7 @@ jobs:
 
           DB=ci gotestsum \
             --format standard-quiet --packages "./..." \
-            -- -timeout=20m -v -p $NUM_PARALLEL_PACKAGES -parallel=$NUM_PARALLEL_TESTS $TESTCOUNT
+            -- -timeout=20m -v -p "$NUM_PARALLEL_PACKAGES" -parallel="$NUM_PARALLEL_TESTS" "$TESTCOUNT"
 
       - name: Upload Embedded Postgres Cache
         uses: ./.github/actions/embedded-pg-cache/upload
@@ -170,6 +170,7 @@ jobs:
     steps:
       - name: Send Slack notification
         run: |
+          ESCAPED_PROMPT=$(printf "%s" "<@U09LQ75AHKR> $BLINK_CI_FAILURE_PROMPT" | jq -Rsa .)
           curl -X POST -H 'Content-type: application/json' \
           --data '{
             "blocks": [
@@ -181,23 +182,6 @@ jobs:
                   "emoji": true
                 }
               },
-              {
-                "type": "section",
-                "fields": [
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Workflow:*\n'"${GITHUB_WORKFLOW}"'"
-                  },
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Committer:*\n'"${GITHUB_ACTOR}"'"
-                  },
-                  {
-                    "type": "mrkdwn",
-                    "text": "*Commit:*\n'"${GITHUB_SHA}"'"
-                  }
-                ]
-              },
               {
                 "type": "section",
                 "text": {
@@ -209,7 +193,7 @@ jobs:
                 "type": "section",
                 "text": {
                   "type": "mrkdwn",
-                  "text": "<@U08TJ4YNCA3> investigate this CI failure. Check logs, search for existing issues, use git blame to find who last modified failing tests, create issue in coder/internal (not public repo), use title format \"flake: TestName\" for flaky tests, and assign to the person from git blame."
+                  "text": '"$ESCAPED_PROMPT"'
                 }
               }
             ]
@@ -217,3 +201,4 @@ jobs:
         env:
           SLACK_WEBHOOK: ${{ secrets.CI_FAILURE_SLACK_WEBHOOK }}
           RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          BLINK_CI_FAILURE_PROMPT: ${{ vars.BLINK_CI_FAILURE_PROMPT }}

.github/workflows/pr-auto-assign.yaml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 

.github/workflows/pr-cleanup.yaml

@@ -19,7 +19,7 @@ jobs:
       packages: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 

.github/workflows/pr-deploy.yaml

@@ -39,12 +39,12 @@ jobs:
       PR_OPEN: ${{ steps.check_pr.outputs.pr_open }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
@@ -76,12 +76,12 @@ jobs:
     runs-on: "ubuntu-latest"
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -184,12 +184,12 @@ jobs:
       pull-requests: write # needed for commenting on PRs
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Find Comment
-        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
         id: fc
         with:
           issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -199,7 +199,7 @@ jobs:
 
       - name: Comment on PR
         id: comment_id
-        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
         with:
           comment-id: ${{ steps.fc.outputs.comment-id }}
           issue-number: ${{ needs.get_info.outputs.PR_NUMBER }}
@@ -228,12 +228,12 @@ jobs:
       CODER_IMAGE_TAG: ${{ needs.get_info.outputs.CODER_IMAGE_TAG }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -248,7 +248,7 @@ jobs:
         uses: ./.github/actions/setup-sqlc
 
       - name: GHCR Login
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -288,7 +288,7 @@ jobs:
       PR_HOSTNAME: "pr${{ needs.get_info.outputs.PR_NUMBER }}.${{ secrets.PR_DEPLOYMENTS_DOMAIN }}"
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
@@ -337,7 +337,7 @@ jobs:
           kubectl create namespace "pr${PR_NUMBER}"
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
@@ -370,6 +370,7 @@ jobs:
           helm repo add bitnami https://charts.bitnami.com/bitnami
           helm install coder-db bitnami/postgresql \
             --namespace "pr${PR_NUMBER}" \
+            --set image.repository=bitnamilegacy/postgresql \
             --set auth.username=coder \
             --set auth.password=coder \
             --set auth.database=coder \
@@ -490,7 +491,7 @@ jobs:
           PASSWORD: ${{ steps.setup_deployment.outputs.password }}
 
       - name: Find Comment
-        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
         id: fc
         with:
           issue-number: ${{ env.PR_NUMBER }}
@@ -499,7 +500,7 @@ jobs:
           direction: last
 
       - name: Comment on PR
-        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
         env:
           STATUS: ${{ needs.get_info.outputs.NEW == 'true' && 'Created' || 'Updated' }}
         with:

.github/workflows/release-validation.yaml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 

.github/workflows/release.yaml

@@ -37,7 +37,7 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Allow only maintainers/admins
-        uses: actions/github-script@v7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -65,7 +65,7 @@ jobs:
     steps:
       # Harden Runner doesn't work on macOS.
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -131,7 +131,7 @@ jobs:
           AC_CERTIFICATE_PASSWORD_FILE: /tmp/apple_cert_password.txt
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: dylibs
           path: |
@@ -164,12 +164,12 @@ jobs:
       version: ${{ steps.version.outputs.version }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -239,7 +239,7 @@ jobs:
           cat "$CODER_RELEASE_NOTES_FILE"
 
       - name: Docker Login
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3.5.0
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -253,7 +253,7 @@ jobs:
 
       # Necessary for signing Windows binaries.
       - name: Setup Java
-        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
         with:
           distribution: "zulu"
           java-version: "11.0"
@@ -317,17 +317,17 @@ jobs:
       # Setup GCloud for signing Windows binaries.
       - name: Authenticate to Google Cloud
         id: gcloud_auth
-        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
         with:
           workload_identity_provider: ${{ vars.GCP_CODE_SIGNING_WORKLOAD_ID_PROVIDER }}
           service_account: ${{ vars.GCP_CODE_SIGNING_SERVICE_ACCOUNT }}
           token_format: "access_token"
 
       - name: Setup GCloud SDK
-        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # v2.2.0
+        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db # v3.0.1
 
       - name: Download dylibs
-        uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: dylibs
           path: ./build
@@ -397,7 +397,7 @@ jobs:
       # This uses OIDC authentication, so no auth variables are required.
       - name: Build base Docker image via depot.dev
         if: steps.image-base-tag.outputs.tag != ''
-        uses: depot/build-push-action@2583627a84956d07561420dcc1d0eb1f2af3fac0 # v1.15.0
+        uses: depot/build-push-action@9785b135c3c76c33db102e45be96a25ab55cd507 # v1.16.2
         with:
           project: wl5hnrrkns
           context: base-build-context
@@ -454,7 +454,7 @@ jobs:
         id: attest_base
         if: ${{ !inputs.dry_run && steps.image-base-tag.outputs.tag != '' }}
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: ${{ steps.image-base-tag.outputs.tag }}
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -570,7 +570,7 @@ jobs:
         id: attest_main
         if: ${{ !inputs.dry_run }}
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: ${{ steps.build_docker.outputs.multiarch_image }}
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -614,7 +614,7 @@ jobs:
         id: attest_latest
         if: ${{ !inputs.dry_run && steps.build_docker.outputs.created_latest_tag == 'true' }}
         continue-on-error: true
-        uses: actions/attest@ce27ba3b4a9a139d9a20a4a07d69fabb52f1e5bc # v2.4.0
+        uses: actions/attest@daf44fb950173508f38bd2406030372c1d1162b1 # v3.0.0
         with:
           subject-name: ${{ steps.latest_tag.outputs.tag }}
           predicate-type: "https://slsa.dev/provenance/v1"
@@ -734,13 +734,13 @@ jobs:
           CREATED_LATEST_TAG: ${{ steps.build_docker.outputs.created_latest_tag }}
 
       - name: Authenticate to Google Cloud
-        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5 # v2.1.12
+        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093 # v3.0.0
         with:
           workload_identity_provider: ${{ vars.GCP_WORKLOAD_ID_PROVIDER }}
           service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
 
       - name: Setup GCloud SDK
-        uses: google-github-actions/setup-gcloud@cb1e50a9932213ecece00a606661ae9ca44f3397 # 2.2.0
+        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db # 3.0.1
 
       - name: Publish Helm Chart
         if: ${{ !inputs.dry_run }}
@@ -761,7 +761,7 @@ jobs:
 
       - name: Upload artifacts to actions (if dry-run)
         if: ${{ inputs.dry_run }}
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: release-artifacts
           path: |
@@ -777,7 +777,7 @@ jobs:
 
       - name: Upload latest sbom artifact to actions (if dry-run)
         if: inputs.dry_run && steps.build_docker.outputs.created_latest_tag == 'true'
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: latest-sbom-artifact
           path: ./coder_latest_sbom.spdx.json
@@ -785,7 +785,7 @@ jobs:
 
       - name: Send repository-dispatch event
         if: ${{ !inputs.dry_run }}
-        uses: peter-evans/repository-dispatch@ff45666b9427631e3450c54a1bcbee4d9ff4d7c0 # v3.0.0
+        uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v4.0.1
         with:
           token: ${{ secrets.CDRCI_GITHUB_TOKEN }}
           repository: coder/packages
@@ -802,7 +802,7 @@ jobs:
       # TODO: skip this if it's not a new release (i.e. a backport). This is
       #       fine right now because it just makes a PR that we can close.
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
@@ -878,7 +878,7 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
@@ -888,7 +888,7 @@ jobs:
           GH_TOKEN: ${{ secrets.CDRCI_GITHUB_TOKEN }}
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -971,12 +971,12 @@ jobs:
     if: ${{ !inputs.dry_run }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 1
           persist-credentials: false

.github/workflows/scorecard.yml

@@ -20,17 +20,17 @@ jobs:
 
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: "Checkout code"
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
         with:
           results_file: results.sarif
           results_format: sarif
@@ -39,7 +39,7 @@ jobs:
 
       # Upload the results as artifacts.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: SARIF file
           path: results.sarif
@@ -47,6 +47,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
+        uses: github/codeql-action/upload-sarif@014f16e7ab1402f30e7c3329d33797e7948572db # v3.29.5
         with:
           sarif_file: results.sarif

.github/workflows/security.yaml

@@ -27,12 +27,12 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
@@ -40,7 +40,7 @@ jobs:
         uses: ./.github/actions/setup-go
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
+        uses: github/codeql-action/init@014f16e7ab1402f30e7c3329d33797e7948572db # v3.29.5
         with:
           languages: go, javascript
 
@@ -50,7 +50,7 @@ jobs:
           rm Makefile
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
+        uses: github/codeql-action/analyze@014f16e7ab1402f30e7c3329d33797e7948572db # v3.29.5
 
       - name: Send Slack notification on failure
         if: ${{ failure() }}
@@ -69,12 +69,12 @@ jobs:
     runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -146,7 +146,7 @@ jobs:
           echo "image=$(cat "$image_job")" >> "$GITHUB_OUTPUT"
 
       - name: Run Trivy vulnerability scanner
-        uses: aquasecurity/trivy-action@dc5a429b52fcf669ce959baa2c2dd26090d2a6c4
+        uses: aquasecurity/trivy-action@b6643a29fecd7f34b3597bc6acb0a98b03d33ff8
         with:
           image-ref: ${{ steps.build.outputs.image }}
           format: sarif
@@ -154,13 +154,13 @@ jobs:
           severity: "CRITICAL,HIGH"
 
       - name: Upload Trivy scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@76621b61decf072c1cee8dd1ce2d2a82d33c17ed # v3.29.5
+        uses: github/codeql-action/upload-sarif@014f16e7ab1402f30e7c3329d33797e7948572db # v3.29.5
         with:
           sarif_file: trivy-results.sarif
           category: "Trivy"
 
       - name: Upload Trivy scan results as an artifact
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: trivy
           path: trivy-results.sarif

.github/workflows/stale.yaml

@@ -18,12 +18,12 @@ jobs:
       pull-requests: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: stale
-        uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.0
+        uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
         with:
           stale-issue-label: "stale"
           stale-pr-label: "stale"
@@ -44,7 +44,7 @@ jobs:
           # Start with the oldest issues, always.
           ascending: true
       - name: "Close old issues labeled likely-no"
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
@@ -96,12 +96,12 @@ jobs:
       contents: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout repository
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
       - name: Run delete-old-branches-action
@@ -120,12 +120,12 @@ jobs:
       actions: write
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Delete PR Cleanup workflow runs
-        uses: Mattraks/delete-workflow-runs@39f0bbed25d76b34de5594dceab824811479e5de # v2.0.6
+        uses: Mattraks/delete-workflow-runs@5bf9a1dac5c4d041c029f0a8370ddf0c5cb5aeb7 # v2.1.0
         with:
           token: ${{ github.token }}
           repository: ${{ github.repository }}
@@ -134,7 +134,7 @@ jobs:
           delete_workflow_pattern: pr-cleanup.yaml
 
       - name: Delete PR Deploy workflow skipped runs
-        uses: Mattraks/delete-workflow-runs@39f0bbed25d76b34de5594dceab824811479e5de # v2.0.6
+        uses: Mattraks/delete-workflow-runs@5bf9a1dac5c4d041c029f0a8370ddf0c5cb5aeb7 # v2.1.0
         with:
           token: ${{ github.token }}
           repository: ${{ github.repository }}

.github/workflows/traiage.yaml

@@ -0,0 +1,190 @@
+name: AI Triage Automation
+
+on:
+  issues:
+    types:
+      - labeled
+  workflow_dispatch:
+    inputs:
+      issue_url:
+        description: "GitHub Issue URL to process"
+        required: true
+        type: string
+      template_name:
+        description: "Coder template to use for workspace"
+        required: true
+        default: "coder"
+        type: string
+      template_preset:
+        description: "Template preset to use"
+        required: false
+        default: ""
+        type: string
+      prefix:
+        description: "Prefix for workspace name"
+        required: false
+        default: "traiage"
+        type: string
+
+jobs:
+  traiage:
+    name: Triage GitHub Issue with Claude Code
+    runs-on: ubuntu-latest
+    if: github.event.label.name == 'traiage' || github.event_name == 'workflow_dispatch'
+    timeout-minutes: 30
+    env:
+      CODER_URL: ${{ secrets.TRAIAGE_CODER_URL }}
+      CODER_SESSION_TOKEN: ${{ secrets.TRAIAGE_CODER_SESSION_TOKEN }}
+    permissions:
+      contents: read
+      issues: write
+      actions: write
+
+    steps:
+      # This is only required for testing locally using nektos/act, so leaving commented out.
+      # An alternative is to use a larger or custom image.
+      # - name: Install Github CLI
+      #   id: install-gh
+      #   run: |
+      #     (type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
+      #     && sudo mkdir -p -m 755 /etc/apt/keyrings \
+      #     && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+      #     && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
+      #     && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+      #     && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
+      #     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
+      #     && sudo apt update \
+      #     && sudo apt install gh -y
+
+      - name: Determine Inputs
+        id: determine-inputs
+        if: always()
+        env:
+          GITHUB_ACTOR: ${{ github.actor }}
+          GITHUB_EVENT_ISSUE_HTML_URL: ${{ github.event.issue.html_url }}
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+          GITHUB_EVENT_USER_ID: ${{ github.event.sender.id }}
+          GITHUB_EVENT_USER_LOGIN: ${{ github.event.sender.login }}
+          INPUTS_ISSUE_URL: ${{ inputs.issue_url }}
+          INPUTS_TEMPLATE_NAME: ${{ inputs.template_name || 'coder' }}
+          INPUTS_TEMPLATE_PRESET: ${{ inputs.template_preset || ''}}
+          INPUTS_PREFIX: ${{ inputs.prefix || 'traiage' }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          echo "Using template name: ${INPUTS_TEMPLATE_NAME}"
+          echo "template_name=${INPUTS_TEMPLATE_NAME}" >> "${GITHUB_OUTPUT}"
+
+          echo "Using template preset: ${INPUTS_TEMPLATE_PRESET}"
+          echo "template_preset=${INPUTS_TEMPLATE_PRESET}" >> "${GITHUB_OUTPUT}"
+
+          echo "Using prefix: ${INPUTS_PREFIX}"
+          echo "prefix=${INPUTS_PREFIX}" >> "${GITHUB_OUTPUT}"
+
+          # For workflow_dispatch, use the actor who triggered it
+          # For issues events, use the issue author.
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            if ! GITHUB_USER_ID=$(gh api "users/${GITHUB_ACTOR}" --jq '.id'); then
+              echo "::error::Failed to get GitHub user ID for actor ${GITHUB_ACTOR}"
+              exit 1
+            fi
+            echo "Using workflow_dispatch actor: ${GITHUB_ACTOR} (ID: ${GITHUB_USER_ID})"
+            echo "github_user_id=${GITHUB_USER_ID}" >> "${GITHUB_OUTPUT}"
+            echo "github_username=${GITHUB_ACTOR}" >> "${GITHUB_OUTPUT}"
+
+            echo "Using issue URL: ${INPUTS_ISSUE_URL}"
+            echo "issue_url=${INPUTS_ISSUE_URL}" >> "${GITHUB_OUTPUT}"
+
+            exit 0
+          elif [[ "${GITHUB_EVENT_NAME}" == "issues" ]]; then
+            GITHUB_USER_ID=${GITHUB_EVENT_USER_ID}
+            echo "Using issue author: ${GITHUB_EVENT_USER_LOGIN} (ID: ${GITHUB_USER_ID})"
+            echo "github_user_id=${GITHUB_USER_ID}" >> "${GITHUB_OUTPUT}"
+            echo "github_username=${GITHUB_EVENT_USER_LOGIN}" >> "${GITHUB_OUTPUT}"
+
+            echo "Using issue URL: ${GITHUB_EVENT_ISSUE_HTML_URL}"
+            echo "issue_url=${GITHUB_EVENT_ISSUE_HTML_URL}" >> "${GITHUB_OUTPUT}"
+
+            exit 0
+          else
+            echo "::error::Unsupported event type: ${GITHUB_EVENT_NAME}"
+            exit 1
+          fi
+
+      - name: Verify push access
+        env:
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_USERNAME: ${{ steps.determine-inputs.outputs.github_username }}
+          GITHUB_USER_ID: ${{ steps.determine-inputs.outputs.github_user_id }}
+        run: |
+          # Query the actor’s permission on this repo
+          can_push="$(gh api "/repos/${GITHUB_REPOSITORY}/collaborators/${GITHUB_USERNAME}/permission" --jq '.user.permissions.push')"
+          if [[ "${can_push}" != "true" ]]; then
+            echo "::error title=Access Denied::${GITHUB_USERNAME} does not have push access to ${GITHUB_REPOSITORY}"
+            exit 1
+          fi
+
+      - name: Extract context key and description from issue
+        id: extract-context
+        env:
+          ISSUE_URL: ${{ steps.determine-inputs.outputs.issue_url }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          issue_number="$(gh issue view "${ISSUE_URL}" --json number --jq '.number')"
+          context_key="gh-${issue_number}"
+
+          TASK_PROMPT=$(cat <<EOF
+          Fix ${ISSUE_URL}
+
+            1. Use the gh CLI to read the issue description and comments.
+            2. Think carefully and try to understand the root cause. If the issue is unclear or not well defined, ask me to clarify and provide more information.
+            3. Write a proposed implementation plan to PLAN.md for me to review before starting implementation. Your plan should use TDD and only make the minimal changes necessary to fix the root cause.
+            4. When I approve your plan, start working on it. If you encounter issues with the plan, ask me for clarification and update the plan as required.
+            5. When you have finished implementation according to the plan, commit and push your changes, and create a PR using the gh CLI for me to review.
+
+          EOF
+          )
+
+          echo "context_key=${context_key}" >> "${GITHUB_OUTPUT}"
+          {
+            echo "TASK_PROMPT<<EOF"
+            echo "${TASK_PROMPT}"
+            echo "EOF"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Checkout repository
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          fetch-depth: 1
+          path: ./.github/actions/create-task-action
+          persist-credentials: false
+          ref: main
+          repository: coder/create-task-action
+
+      - name: Create Coder Task
+        id: create_task
+        uses: ./.github/actions/create-task-action
+        with:
+          coder-url: ${{ secrets.TRAIAGE_CODER_URL }}
+          coder-token: ${{ secrets.TRAIAGE_CODER_SESSION_TOKEN }}
+          coder-organization: "default"
+          coder-template-name: coder
+          coder-template-preset: ${{ steps.determine-inputs.outputs.template_preset }}
+          coder-task-name-prefix: gh-coder
+          coder-task-prompt: ${{ steps.extract-context.outputs.task_prompt }}
+          github-user-id: ${{ steps.determine-inputs.outputs.github_user_id }}
+          github-token: ${{ github.token }}
+          github-issue-url: ${{ steps.determine-inputs.outputs.issue_url }}
+          comment-on-issue: ${{ startsWith(steps.determine-inputs.outputs.issue_url, format('{0}/{1}', github.server_url, github.repository)) }}
+
+      - name: Write outputs
+        env:
+          TASK_CREATED: ${{ steps.create_task.outputs.task-created }}
+          TASK_NAME: ${{ steps.create_task.outputs.task-name }}
+          TASK_URL: ${{ steps.create_task.outputs.task-url }}
+        run: |
+          {
+            echo "**Task created:** ${TASK_CREATED}"
+            echo "**Task name:**    ${TASK_NAME}"
+            echo "**Task URL**:     ${TASK_URL}"
+          } >> "${GITHUB_STEP_SUMMARY}"

.github/workflows/typos.toml

@@ -1,5 +1,6 @@
 [default]
 extend-ignore-identifiers-re = ["gho_.*"]
+extend-ignore-re = ["(#|//)\\s*spellchecker:ignore-next-line\\n.*"]
 
 [default.extend-identifiers]
 alog = "alog"
@@ -8,6 +9,7 @@ IST = "IST"
 MacOS = "macOS"
 AKS = "AKS"
 O_WRONLY = "O_WRONLY"
+AIBridge = "AI Bridge"
 
 [default.extend-words]
 AKS = "AKS"

.github/workflows/weekly-docs.yaml

@@ -21,17 +21,17 @@ jobs:
       pull-requests: write # required to post PR review comments by the action
     steps:
       - name: Harden Runner
-        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
         with:
           egress-policy: audit
 
       - name: Checkout
-        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
       - name: Check Markdown links
-        uses: umbrelladocs/action-linkspector@874d01cae9fd488e3077b08952093235bd626977 # v1.3.7
+        uses: umbrelladocs/action-linkspector@652f85bc57bb1e7d4327260decc10aa68f7694c3 # v1.4.0
         id: markdown-link-check
         # checks all markdown files from /docs including all subfolders
         with:

.github/zizmor.yml

@@ -0,0 +1,4 @@
+rules:
+  cache-poisoning:
+    ignore:
+      - "ci.yaml:184"

.gitignore

@@ -12,6 +12,9 @@ node_modules/
 vendor/
 yarn-error.log
 
+# Test output files
+test-output/
+
 # VSCode settings.
 **/.vscode/*
 # Allow VSCode recommendations and default settings in project root.
@@ -86,3 +89,8 @@ result
 __debug_bin*
 
 **/.claude/settings.local.json
+
+/.env
+
+# Ignore plans written by AI agents.
+PLAN.md

.golangci.yaml

@@ -169,6 +169,16 @@ linters-settings:
       - name: var-declaration
       - name: var-naming
       - name: waitgroup-by-value
+  usetesting:
+    # Only os-setenv is enabled because we migrated to usetesting from another linter that
+    # only covered os-setenv.
+    os-setenv: true
+    os-create-temp: false
+    os-mkdir-temp: false
+    os-temp-dir: false
+    os-chdir: false
+    context-background: false
+    context-todo: false
 
   # irrelevant as of Go v1.22: https://go.dev/blog/loopvar-preview
   govet:
@@ -252,7 +262,6 @@ linters:
     # - wastedassign
 
     - staticcheck
-    - tenv
     # In Go, it's possible for a package to test it's internal functionality
     # without testing any exported functions. This is enabled to promote
     # decomposing a package before testing it's internals. A function caller
@@ -265,4 +274,5 @@ linters:
     - typecheck
     - unconvert
     - unused
+    - usetesting
     - dupl

.vscode/settings.json

@@ -54,11 +54,13 @@
 		}
 	},
 
+	"tailwindCSS.classFunctions": ["cva", "cn"],
 	"[css][html][markdown][yaml]": {
 		"editor.defaultFormatter": "esbenp.prettier-vscode"
 	},
 	"typos.config": ".github/workflows/typos.toml",
 	"[markdown]": {
 		"editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
-	}
+	},
+	"biome.lsp.bin": "site/node_modules/.bin/biome"
 }

CLAUDE.md

@@ -1,11 +1,41 @@
 # Coder Development Guidelines
 
+You are an experienced, pragmatic software engineer. You don't over-engineer a solution when a simple one is possible.
+Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permission first. BREAKING THE LETTER OR SPIRIT OF THE RULES IS FAILURE.
+
+## Foundational rules
+
+- Doing it right is better than doing it fast. You are not in a rush. NEVER skip steps or take shortcuts.
+- Tedious, systematic work is often the correct solution. Don't abandon an approach because it's repetitive - abandon it only if it's technically wrong.
+- Honesty is a core value.
+
+## Our relationship
+
+- Act as a critical peer reviewer. Your job is to disagree with me when I'm wrong, not to please me. Prioritize accuracy and reasoning over agreement.
+- YOU MUST speak up immediately when you don't know something or we're in over our heads
+- YOU MUST call out bad ideas, unreasonable expectations, and mistakes - I depend on this
+- NEVER be agreeable just to be nice - I NEED your HONEST technical judgment
+- NEVER write the phrase "You're absolutely right!"  You are not a sycophant. We're working together because I value your opinion. Do not agree with me unless you can justify it with evidence or reasoning.
+- YOU MUST ALWAYS STOP and ask for clarification rather than making assumptions.
+- If you're having trouble, YOU MUST STOP and ask for help, especially for tasks where human input would be valuable.
+- When you disagree with my approach, YOU MUST push back. Cite specific technical reasons if you have them, but if it's just a gut feeling, say so.
+- If you're uncomfortable pushing back out loud, just say "Houston, we have a problem". I'll know what you mean
+- We discuss architectutral decisions (framework changes, major refactoring, system design) together before implementation. Routine fixes and clear implementations don't need discussion.
+
+## Proactiveness
+
+When asked to do something, just do it - including obvious follow-up actions needed to complete the task properly.
+Only pause to ask for confirmation when:
+
+- Multiple valid approaches exist and the choice matters
+- The action would delete or significantly restructure existing code
+- You genuinely don't understand what's being asked
+- Your partner asked a question (answer the question, don't jump to implementation)
+
 @.claude/docs/WORKFLOWS.md
-@.cursorrules
-@README.md
 @package.json
 
-## 🚀 Essential Commands
+## Essential Commands
 
 | Task              | Command                  | Notes                            |
 |-------------------|--------------------------|----------------------------------|
@@ -21,22 +51,13 @@
 | **Format**        | `make fmt`               | Auto-format code                 |
 | **Clean**         | `make clean`             | Clean build artifacts            |
 
-### Frontend Commands (site directory)
-
-- `pnpm build` - Build frontend
-- `pnpm dev` - Run development server
-- `pnpm check` - Run code checks
-- `pnpm format` - Format frontend code
-- `pnpm lint` - Lint frontend code
-- `pnpm test` - Run frontend tests
-
 ### Documentation Commands
 
 - `pnpm run format-docs` - Format markdown tables in docs
 - `pnpm run lint-docs` - Lint and fix markdown files
 - `pnpm run storybook` - Run Storybook (from site directory)
 
-## 🔧 Critical Patterns
+## Critical Patterns
 
 ### Database Changes (ALWAYS FOLLOW)
 
@@ -78,7 +99,7 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestrict
 app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 ```
 
-## 📋 Quick Reference
+## Quick Reference
 
 ### Full workflows available in imported WORKFLOWS.md
 
@@ -88,14 +109,14 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 - [ ] Check if feature touches database - you'll need migrations
 - [ ] Check if feature touches audit logs - update `enterprise/audit/table.go`
 
-## 🏗️ Architecture
+## Architecture
 
 - **coderd**: Main API service
 - **provisionerd**: Infrastructure provisioning
 - **Agents**: Workspace services (SSH, port forwarding)
 - **Database**: PostgreSQL with `dbauthz` authorization
 
-## 🧪 Testing
+## Testing
 
 ### Race Condition Prevention
 
@@ -112,21 +133,21 @@ app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)
 NEVER use `time.Sleep` to mitigate timing issues. If an issue
 seems like it should use `time.Sleep`, read through https://github.com/coder/quartz and specifically the [README](https://github.com/coder/quartz/blob/main/README.md) to better understand how to handle timing issues.
 
-## 🎯 Code Style
+## Code Style
 
 ### Detailed guidelines in imported WORKFLOWS.md
 
 - Follow [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md)
 - Commit format: `type(scope): message`
 
-## 📚 Detailed Development Guides
+## Detailed Development Guides
 
 @.claude/docs/OAUTH2.md
 @.claude/docs/TESTING.md
 @.claude/docs/TROUBLESHOOTING.md
 @.claude/docs/DATABASE.md
 
-## 🚨 Common Pitfalls
+## Common Pitfalls
 
 1. **Audit table errors** → Update `enterprise/audit/table.go`
 2. **OAuth2 errors** → Return RFC-compliant format

CODEOWNERS

@@ -18,18 +18,6 @@ coderd/rbac/ @Emyrk
 scripts/apitypings/ @Emyrk
 scripts/gensite/ @aslilac
 
-site/ @aslilac @Parkreiner
-site/src/hooks/ @Parkreiner
-# These rules intentionally do not specify any owners. More specific rules
-# override less specific rules, so these files are "ignored" by the site/ rule.
-site/e2e/google/protobuf/timestampGenerated.ts
-site/e2e/provisionerGenerated.ts
-site/src/api/countriesGenerated.ts
-site/src/api/rbacresourcesGenerated.ts
-site/src/api/typesGenerated.ts
-site/src/testHelpers/entities.ts
-site/CLAUDE.md
-
 # The blood and guts of the autostop algorithm, which is quite complex and
 # requires elite ball knowledge of most of the scheduling code to make changes
 # without inadvertently affecting other parts of the codebase.
@@ -39,3 +27,5 @@ coderd/schedule/autostop.go @deansheather @DanielleMaywood
 # well as guidance from revenue.
 coderd/usage/ @deansheather @spikecurtis
 enterprise/coderd/usage/ @deansheather @spikecurtis
+
+.github/ 	@jdomeracki-coder

Makefile

@@ -561,7 +561,7 @@ endif
 
 # Note: we don't run zizmor in the lint target because it takes a while. CI
 #       runs it explicitly.
-lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/actions/actionlint
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/actions/actionlint lint/check-scopes
 .PHONY: lint
 
 lint/site-icons:
@@ -614,6 +614,11 @@ lint/actions/zizmor:
 		.
 .PHONY: lint/actions/zizmor
 
+# Verify api_key_scope enum contains all RBAC <resource>:<action> values.
+lint/check-scopes: coderd/database/dump.sql
+	go run ./scripts/check-scopes
+.PHONY: lint/check-scopes
+
 # All files generated by the database should be added here, and this can be used
 # as a target for jobs that need to run after the database is generated.
 DB_GEN_FILES := \
@@ -630,16 +635,24 @@ TAILNETTEST_MOCKS := \
 	tailnet/tailnettest/workspaceupdatesprovidermock.go \
 	tailnet/tailnettest/subscriptionmock.go
 
+AIBRIDGED_MOCKS := \
+	enterprise/aibridged/aibridgedmock/clientmock.go \
+	enterprise/aibridged/aibridgedmock/poolmock.go
+
 GEN_FILES := \
 	tailnet/proto/tailnet.pb.go \
 	agent/proto/agent.pb.go \
+	agent/agentsocket/proto/agentsocket.pb.go \
 	provisionersdk/proto/provisioner.pb.go \
 	provisionerd/proto/provisionerd.pb.go \
 	vpn/vpn.pb.go \
+	enterprise/aibridged/proto/aibridged.pb.go \
 	$(DB_GEN_FILES) \
 	$(SITE_GEN_FILES) \
 	coderd/rbac/object_gen.go \
 	codersdk/rbacresources_gen.go \
+	coderd/rbac/scopes_constants_gen.go \
+	codersdk/apikey_scopes_gen.go \
 	docs/admin/integrations/prometheus.md \
 	docs/reference/cli/index.md \
 	docs/admin/security/audit-logs.md \
@@ -653,7 +666,8 @@ GEN_FILES := \
 	agent/agentcontainers/acmock/acmock.go \
 	agent/agentcontainers/dcspec/dcspec_gen.go \
 	coderd/httpmw/loggermw/loggermock/loggermock.go \
-	codersdk/workspacesdk/agentconnmock/agentconnmock.go
+	codersdk/workspacesdk/agentconnmock/agentconnmock.go \
+	$(AIBRIDGED_MOCKS)
 
 # all gen targets should be added here and to gen/mark-fresh
 gen: gen/db gen/golden-files $(GEN_FILES)
@@ -663,6 +677,7 @@ gen/db: $(DB_GEN_FILES)
 .PHONY: gen/db
 
 gen/golden-files: \
+	agent/unit/testdata/.gen-golden \
 	cli/testdata/.gen-golden \
 	coderd/.gen-golden \
 	coderd/notifications/.gen-golden \
@@ -682,12 +697,15 @@ gen/mark-fresh:
 		agent/proto/agent.pb.go \
 		provisionersdk/proto/provisioner.pb.go \
 		provisionerd/proto/provisionerd.pb.go \
+		agent/agentsocket/proto/agentsocket.pb.go \
 		vpn/vpn.pb.go \
+		enterprise/aibridged/proto/aibridged.pb.go \
 		coderd/database/dump.sql \
 		$(DB_GEN_FILES) \
 		site/src/api/typesGenerated.ts \
 		coderd/rbac/object_gen.go \
 		codersdk/rbacresources_gen.go \
+		coderd/rbac/scopes_constants_gen.go \
 		site/src/api/rbacresourcesGenerated.ts \
 		site/src/api/countriesGenerated.ts \
 		docs/admin/integrations/prometheus.md \
@@ -704,6 +722,7 @@ gen/mark-fresh:
 		agent/agentcontainers/dcspec/dcspec_gen.go \
 		coderd/httpmw/loggermw/loggermock/loggermock.go \
 		codersdk/workspacesdk/agentconnmock/agentconnmock.go \
+		$(AIBRIDGED_MOCKS) \
 		"
 
 	for file in $$files; do
@@ -751,6 +770,10 @@ codersdk/workspacesdk/agentconnmock/agentconnmock.go: codersdk/workspacesdk/agen
 	go generate ./codersdk/workspacesdk/agentconnmock/
 	touch "$@"
 
+$(AIBRIDGED_MOCKS): enterprise/aibridged/client.go enterprise/aibridged/pool.go
+	go generate ./enterprise/aibridged/aibridgedmock/
+	touch "$@"
+
 agent/agentcontainers/dcspec/dcspec_gen.go: \
 	node_modules/.installed \
 	agent/agentcontainers/dcspec/devContainer.base.schema.json \
@@ -779,6 +802,14 @@ agent/proto/agent.pb.go: agent/proto/agent.proto
 		--go-drpc_opt=paths=source_relative \
 		./agent/proto/agent.proto
 
+agent/agentsocket/proto/agentsocket.pb.go: agent/agentsocket/proto/agentsocket.proto
+	protoc \
+		--go_out=. \
+		--go_opt=paths=source_relative \
+		--go-drpc_out=. \
+		--go-drpc_opt=paths=source_relative \
+		./agent/agentsocket/proto/agentsocket.proto
+
 provisionersdk/proto/provisioner.pb.go: provisionersdk/proto/provisioner.proto
 	protoc \
 		--go_out=. \
@@ -801,6 +832,14 @@ vpn/vpn.pb.go: vpn/vpn.proto
 		--go_opt=paths=source_relative \
 		./vpn/vpn.proto
 
+enterprise/aibridged/proto/aibridged.pb.go: enterprise/aibridged/proto/aibridged.proto
+	protoc \
+		--go_out=. \
+		--go_opt=paths=source_relative \
+		--go-drpc_out=. \
+		--go-drpc_opt=paths=source_relative \
+		./enterprise/aibridged/proto/aibridged.proto
+
 site/src/api/typesGenerated.ts: site/node_modules/.installed $(wildcard scripts/apitypings/*) $(shell find ./codersdk $(FIND_EXCLUSIONS) -type f -name '*.go')
 	# -C sets the directory for the go run command
 	go run -C ./scripts/apitypings main.go > $@
@@ -827,6 +866,15 @@ coderd/rbac/object_gen.go: scripts/typegen/rbacobject.gotmpl scripts/typegen/mai
 	rmdir -v "$$tempdir"
 	touch "$@"
 
+coderd/rbac/scopes_constants_gen.go: scripts/typegen/scopenames.gotmpl scripts/typegen/main.go coderd/rbac/policy/policy.go
+	# Generate typed low-level ScopeName constants from RBACPermissions
+	# Write to a temp file first to avoid truncating the package during build
+	# since the generator imports the rbac package.
+	tempfile=$(shell mktemp /tmp/scopes_constants_gen.XXXXXX)
+	go run ./scripts/typegen/main.go rbac scopenames > "$$tempfile"
+	mv -v "$$tempfile" coderd/rbac/scopes_constants_gen.go
+	touch "$@"
+
 codersdk/rbacresources_gen.go: scripts/typegen/codersdk.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
 	# Do no overwrite codersdk/rbacresources_gen.go directly, as it would make the file empty, breaking
  	# the `codersdk` package and any parallel build targets.
@@ -834,6 +882,12 @@ codersdk/rbacresources_gen.go: scripts/typegen/codersdk.gotmpl scripts/typegen/m
 	mv /tmp/rbacresources_gen.go codersdk/rbacresources_gen.go
 	touch "$@"
 
+codersdk/apikey_scopes_gen.go: scripts/apikeyscopesgen/main.go coderd/rbac/scopes_catalog.go coderd/rbac/scopes.go
+	# Generate SDK constants for external API key scopes.
+	go run ./scripts/apikeyscopesgen > /tmp/apikey_scopes_gen.go
+	mv /tmp/apikey_scopes_gen.go codersdk/apikey_scopes_gen.go
+	touch "$@"
+
 site/src/api/rbacresourcesGenerated.ts: site/node_modules/.installed scripts/typegen/codersdk.gotmpl scripts/typegen/main.go coderd/rbac/object.go coderd/rbac/policy/policy.go
 	go run scripts/typegen/main.go rbac typescript > "$@"
 	(cd site/ && pnpm exec biome format --write src/api/rbacresourcesGenerated.ts)
@@ -909,6 +963,10 @@ clean/golden-files:
 		-type f -name '*.golden' -delete
 .PHONY: clean/golden-files
 
+agent/unit/testdata/.gen-golden: $(wildcard agent/unit/testdata/*.golden) $(GO_SRC_FILES) $(wildcard agent/unit/*_test.go)
+	TZ=UTC go test ./agent/unit -run="TestGraph" -update
+	touch "$@"
+
 cli/testdata/.gen-golden: $(wildcard cli/testdata/*.golden) $(wildcard cli/*.tpl) $(GO_SRC_FILES) $(wildcard cli/*_test.go)
 	TZ=UTC go test ./cli -run="Test(CommandHelp|ServerYAML|ErrorExamples|.*Golden)" -update
 	touch "$@"
@@ -1134,3 +1192,8 @@ endif
 
 dogfood/coder/nix.hash: flake.nix flake.lock
 	sha256sum flake.nix flake.lock >./dogfood/coder/nix.hash
+
+# Count the number of test databases created per test package.
+count-test-databases:
+	PGPASSWORD=postgres psql -h localhost -U postgres -d coder_testing -P pager=off -c 'SELECT test_package, count(*) as count from test_databases GROUP BY test_package ORDER BY count DESC'
+.PHONY: count-test-databases

agent/agent.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"hash/fnv"
 	"io"
+	"maps"
 	"net"
 	"net/http"
 	"net/netip"
@@ -40,6 +41,7 @@ import (
 	"github.com/coder/coder/v2/agent/agentcontainers"
 	"github.com/coder/coder/v2/agent/agentexec"
 	"github.com/coder/coder/v2/agent/agentscripts"
+	"github.com/coder/coder/v2/agent/agentsocket"
 	"github.com/coder/coder/v2/agent/agentssh"
 	"github.com/coder/coder/v2/agent/proto"
 	"github.com/coder/coder/v2/agent/proto/resourcesmonitor"
@@ -70,17 +72,21 @@ const (
 )
 
 type Options struct {
-	Filesystem                   afero.Fs
-	LogDir                       string
-	TempDir                      string
-	ScriptDataDir                string
-	ExchangeToken                func(ctx context.Context) (string, error)
-	Client                       Client
-	ReconnectingPTYTimeout       time.Duration
-	EnvironmentVariables         map[string]string
-	Logger                       slog.Logger
-	IgnorePorts                  map[int]string
-	PortCacheDuration            time.Duration
+	Filesystem             afero.Fs
+	LogDir                 string
+	TempDir                string
+	ScriptDataDir          string
+	Client                 Client
+	ReconnectingPTYTimeout time.Duration
+	EnvironmentVariables   map[string]string
+	Logger                 slog.Logger
+	// IgnorePorts tells the api handler which ports to ignore when
+	// listing all listening ports. This is helpful to hide ports that
+	// are used by the agent, that the user does not care about.
+	IgnorePorts map[int]string
+	// ListeningPortsGetter is used to get the list of listening ports. Only
+	// tests should set this. If unset, a default that queries the OS will be used.
+	ListeningPortsGetter         ListeningPortsGetter
 	SSHMaxTimeout                time.Duration
 	TailnetListenPort            uint16
 	Subsystems                   []codersdk.AgentSubsystem
@@ -92,6 +98,8 @@ type Options struct {
 	Devcontainers                bool
 	DevcontainerAPIOptions       []agentcontainers.Option // Enable Devcontainers for these to be effective.
 	Clock                        quartz.Clock
+	SocketServerEnabled          bool
+	SocketPath                   string // Path for the agent socket server socket
 }
 
 type Client interface {
@@ -99,6 +107,7 @@ type Client interface {
 		proto.DRPCAgentClient26, tailnetproto.DRPCTailnetClient26, error,
 	)
 	tailnet.DERPMapRewriter
+	agentsdk.RefreshableSessionTokenProvider
 }
 
 type Agent interface {
@@ -131,20 +140,13 @@ func New(options Options) Agent {
 		}
 		options.ScriptDataDir = options.TempDir
 	}
-	if options.ExchangeToken == nil {
-		options.ExchangeToken = func(_ context.Context) (string, error) {
-			return "", nil
-		}
-	}
 	if options.ReportMetadataInterval == 0 {
 		options.ReportMetadataInterval = time.Second
 	}
 	if options.ServiceBannerRefreshInterval == 0 {
 		options.ServiceBannerRefreshInterval = 2 * time.Minute
 	}
-	if options.PortCacheDuration == 0 {
-		options.PortCacheDuration = 1 * time.Second
-	}
+
 	if options.Clock == nil {
 		options.Clock = quartz.NewReal()
 	}
@@ -158,31 +160,38 @@ func New(options Options) Agent {
 		options.Execer = agentexec.DefaultExecer
 	}
 
+	if options.ListeningPortsGetter == nil {
+		options.ListeningPortsGetter = &osListeningPortsGetter{
+			cacheDuration: 1 * time.Second,
+		}
+	}
+
 	hardCtx, hardCancel := context.WithCancel(context.Background())
 	gracefulCtx, gracefulCancel := context.WithCancel(hardCtx)
 	a := &agent{
-		clock:                              options.Clock,
-		tailnetListenPort:                  options.TailnetListenPort,
-		reconnectingPTYTimeout:             options.ReconnectingPTYTimeout,
-		logger:                             options.Logger,
-		gracefulCtx:                        gracefulCtx,
-		gracefulCancel:                     gracefulCancel,
-		hardCtx:                            hardCtx,
-		hardCancel:                         hardCancel,
-		coordDisconnected:                  make(chan struct{}),
-		environmentVariables:               options.EnvironmentVariables,
-		client:                             options.Client,
-		exchangeToken:                      options.ExchangeToken,
-		filesystem:                         options.Filesystem,
-		logDir:                             options.LogDir,
-		tempDir:                            options.TempDir,
-		scriptDataDir:                      options.ScriptDataDir,
-		lifecycleUpdate:                    make(chan struct{}, 1),
-		lifecycleReported:                  make(chan codersdk.WorkspaceAgentLifecycle, 1),
-		lifecycleStates:                    []agentsdk.PostLifecycleRequest{{State: codersdk.WorkspaceAgentLifecycleCreated}},
-		reportConnectionsUpdate:            make(chan struct{}, 1),
-		ignorePorts:                        options.IgnorePorts,
-		portCacheDuration:                  options.PortCacheDuration,
+		clock:                   options.Clock,
+		tailnetListenPort:       options.TailnetListenPort,
+		reconnectingPTYTimeout:  options.ReconnectingPTYTimeout,
+		logger:                  options.Logger,
+		gracefulCtx:             gracefulCtx,
+		gracefulCancel:          gracefulCancel,
+		hardCtx:                 hardCtx,
+		hardCancel:              hardCancel,
+		coordDisconnected:       make(chan struct{}),
+		environmentVariables:    options.EnvironmentVariables,
+		client:                  options.Client,
+		filesystem:              options.Filesystem,
+		logDir:                  options.LogDir,
+		tempDir:                 options.TempDir,
+		scriptDataDir:           options.ScriptDataDir,
+		lifecycleUpdate:         make(chan struct{}, 1),
+		lifecycleReported:       make(chan codersdk.WorkspaceAgentLifecycle, 1),
+		lifecycleStates:         []agentsdk.PostLifecycleRequest{{State: codersdk.WorkspaceAgentLifecycleCreated}},
+		reportConnectionsUpdate: make(chan struct{}, 1),
+		listeningPortsHandler: listeningPortsHandler{
+			getter:      options.ListeningPortsGetter,
+			ignorePorts: maps.Clone(options.IgnorePorts),
+		},
 		reportMetadataInterval:             options.ReportMetadataInterval,
 		announcementBannersRefreshInterval: options.ServiceBannerRefreshInterval,
 		sshMaxTimeout:                      options.SSHMaxTimeout,
@@ -196,6 +205,8 @@ func New(options Options) Agent {
 
 		devcontainers:       options.Devcontainers,
 		containerAPIOptions: options.DevcontainerAPIOptions,
+		socketPath:          options.SocketPath,
+		socketServerEnabled: options.SocketServerEnabled,
 	}
 	// Initially, we have a closed channel, reflecting the fact that we are not initially connected.
 	// Each time we connect we replace the channel (while holding the closeMutex) with a new one
@@ -203,27 +214,21 @@ func New(options Options) Agent {
 	// coordinator during shut down.
 	close(a.coordDisconnected)
 	a.announcementBanners.Store(new([]codersdk.BannerConfig))
-	a.sessionToken.Store(new(string))
 	a.init()
 	return a
 }
 
 type agent struct {
-	clock             quartz.Clock
-	logger            slog.Logger
-	client            Client
-	exchangeToken     func(ctx context.Context) (string, error)
-	tailnetListenPort uint16
-	filesystem        afero.Fs
-	logDir            string
-	tempDir           string
-	scriptDataDir     string
-	// ignorePorts tells the api handler which ports to ignore when
-	// listing all listening ports. This is helpful to hide ports that
-	// are used by the agent, that the user does not care about.
-	ignorePorts       map[int]string
-	portCacheDuration time.Duration
-	subsystems        []codersdk.AgentSubsystem
+	clock                 quartz.Clock
+	logger                slog.Logger
+	client                Client
+	tailnetListenPort     uint16
+	filesystem            afero.Fs
+	logDir                string
+	tempDir               string
+	scriptDataDir         string
+	listeningPortsHandler listeningPortsHandler
+	subsystems            []codersdk.AgentSubsystem
 
 	reconnectingPTYTimeout time.Duration
 	reconnectingPTYServer  *reconnectingpty.Server
@@ -254,7 +259,6 @@ type agent struct {
 	scriptRunner                       *agentscripts.Runner
 	announcementBanners                atomic.Pointer[[]codersdk.BannerConfig] // announcementBanners is atomic because it is periodically updated.
 	announcementBannersRefreshInterval time.Duration
-	sessionToken                       atomic.Pointer[string]
 	sshServer                          *agentssh.Server
 	sshMaxTimeout                      time.Duration
 	blockFileTransfer                  bool
@@ -280,6 +284,10 @@ type agent struct {
 	devcontainers       bool
 	containerAPIOptions []agentcontainers.Option
 	containerAPI        *agentcontainers.API
+
+	socketServerEnabled bool
+	socketPath          string
+	socketServer        *agentsocket.Server
 }
 
 func (a *agent) TailnetConn() *tailnet.Conn {
@@ -359,9 +367,32 @@ func (a *agent) init() {
 			s.ExperimentalContainers = a.devcontainers
 		},
 	)
+
+	a.initSocketServer()
+
 	go a.runLoop()
 }
 
+// initSocketServer initializes server that allows direct communication with a workspace agent using IPC.
+func (a *agent) initSocketServer() {
+	if !a.socketServerEnabled {
+		a.logger.Info(a.hardCtx, "socket server is disabled")
+		return
+	}
+
+	server, err := agentsocket.NewServer(
+		a.logger.Named("socket"),
+		agentsocket.WithPath(a.socketPath),
+	)
+	if err != nil {
+		a.logger.Warn(a.hardCtx, "failed to create socket server", slog.Error(err), slog.F("path", a.socketPath))
+		return
+	}
+
+	a.socketServer = server
+	a.logger.Debug(a.hardCtx, "socket server started", slog.F("path", a.socketPath))
+}
+
 // runLoop attempts to start the agent in a retry loop.
 // Coder may be offline temporarily, a connection issue
 // may be happening, but regardless after the intermittent
@@ -790,11 +821,15 @@ func (a *agent) reportConnectionsLoop(ctx context.Context, aAPI proto.DRPCAgentC
 			logger.Debug(ctx, "reporting connection")
 			_, err := aAPI.ReportConnection(ctx, payload)
 			if err != nil {
-				return xerrors.Errorf("failed to report connection: %w", err)
+				// Do not fail the loop if we fail to report a connection, just
+				// log a warning.
+				// Related to https://github.com/coder/coder/issues/20194
+				logger.Warn(ctx, "failed to report connection to server", slog.Error(err))
+				// keep going, we still need to remove it from the slice
+			} else {
+				logger.Debug(ctx, "successfully reported connection")
 			}
 
-			logger.Debug(ctx, "successfully reported connection")
-
 			// Remove the payload we sent.
 			a.reportConnectionsMu.Lock()
 			a.reportConnections[0] = nil // Release the pointer from the underlying array.
@@ -825,6 +860,13 @@ func (a *agent) reportConnection(id uuid.UUID, connectionType proto.Connection_T
 		ip = host
 	}
 
+	// If the IP is "localhost" (which it can be in some cases), set it to
+	// 127.0.0.1 instead.
+	// Related to https://github.com/coder/coder/issues/20194
+	if ip == "localhost" {
+		ip = "127.0.0.1"
+	}
+
 	a.reportConnectionsMu.Lock()
 	defer a.reportConnectionsMu.Unlock()
 
@@ -916,11 +958,10 @@ func (a *agent) run() (retErr error) {
 	// This allows the agent to refresh its token if necessary.
 	// For instance identity this is required, since the instance
 	// may not have re-provisioned, but a new agent ID was created.
-	sessionToken, err := a.exchangeToken(a.hardCtx)
+	err := a.client.RefreshToken(a.hardCtx)
 	if err != nil {
-		return xerrors.Errorf("exchange token: %w", err)
+		return xerrors.Errorf("refresh token: %w", err)
 	}
-	a.sessionToken.Store(&sessionToken)
 
 	// ConnectRPC returns the dRPC connection we use for the Agent and Tailnet v2+ APIs
 	aAPI, tAPI, err := a.client.ConnectRPC26(a.hardCtx)
@@ -1086,7 +1127,7 @@ func (a *agent) handleManifest(manifestOK *checkpoint) func(ctx context.Context,
 		if err != nil {
 			return xerrors.Errorf("fetch metadata: %w", err)
 		}
-		a.logger.Info(ctx, "fetched manifest", slog.F("manifest", mp))
+		a.logger.Info(ctx, "fetched manifest")
 		manifest, err := agentsdk.ManifestFromProto(mp)
 		if err != nil {
 			a.logger.Critical(ctx, "failed to convert manifest", slog.F("manifest", mp), slog.Error(err))
@@ -1359,7 +1400,7 @@ func (a *agent) updateCommandEnv(current []string) (updated []string, err error)
 		"CODER_WORKSPACE_OWNER_NAME": manifest.OwnerName,
 
 		// Specific Coder subcommands require the agent token exposed!
-		"CODER_AGENT_TOKEN": *a.sessionToken.Load(),
+		"CODER_AGENT_TOKEN": a.client.GetSessionToken(),
 
 		// Git on Windows resolves with UNIX-style paths.
 		// If using backslashes, it's unable to find the executable.
@@ -1919,6 +1960,7 @@ func (a *agent) Close() error {
 			lifecycleState = codersdk.WorkspaceAgentLifecycleShutdownError
 		}
 	}
+
 	a.setLifecycle(lifecycleState)
 
 	err = a.scriptRunner.Close()
@@ -1926,6 +1968,12 @@ func (a *agent) Close() error {
 		a.logger.Error(a.hardCtx, "script runner close", slog.Error(err))
 	}
 
+	if a.socketServer != nil {
+		if err := a.socketServer.Close(); err != nil {
+			a.logger.Error(a.hardCtx, "socket server close", slog.Error(err))
+		}
+	}
+
 	if err := a.containerAPI.Close(); err != nil {
 		a.logger.Error(a.hardCtx, "container API close", slog.Error(err))
 	}

agent/agent_test.go

@@ -22,7 +22,6 @@ import (
 	"slices"
 	"strconv"
 	"strings"
-	"sync/atomic"
 	"testing"
 	"time"
 
@@ -1808,11 +1807,12 @@ func TestAgent_ReconnectingPTY(t *testing.T) {
 
 			//nolint:dogsled
 			conn, agentClient, _, _, _ := setupAgent(t, agentsdk.Manifest{}, 0)
+			idConnectionReport := uuid.New()
 			id := uuid.New()
 
 			// Test that the connection is reported. This must be tested in the
 			// first connection because we care about verifying all of these.
-			netConn0, err := conn.ReconnectingPTY(ctx, id, 80, 80, "bash --norc")
+			netConn0, err := conn.ReconnectingPTY(ctx, idConnectionReport, 80, 80, "bash --norc")
 			require.NoError(t, err)
 			_ = netConn0.Close()
 			assertConnectionReport(t, agentClient, proto.Connection_RECONNECTING_PTY, 0, "")
@@ -2028,7 +2028,8 @@ func runSubAgentMain() int {
 	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
 	defer cancel()
 	req = req.WithContext(ctx)
-	resp, err := http.DefaultClient.Do(req)
+	client := &http.Client{}
+	resp, err := client.Do(req)
 	if err != nil {
 		_, _ = fmt.Fprintf(os.Stderr, "agent connection failed: %v\n", err)
 		return 11
@@ -2926,11 +2927,11 @@ func TestAgent_Speedtest(t *testing.T) {
 
 func TestAgent_Reconnect(t *testing.T) {
 	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
 	logger := testutil.Logger(t)
 	// After the agent is disconnected from a coordinator, it's supposed
 	// to reconnect!
-	coordinator := tailnet.NewCoordinator(logger)
-	defer coordinator.Close()
+	fCoordinator := tailnettest.NewFakeCoordinator()
 
 	agentID := uuid.New()
 	statsCh := make(chan *proto.Stats, 50)
@@ -2942,27 +2943,24 @@ func TestAgent_Reconnect(t *testing.T) {
 			DERPMap: derpMap,
 		},
 		statsCh,
-		coordinator,
+		fCoordinator,
 	)
 	defer client.Close()
-	initialized := atomic.Int32{}
+
 	closer := agent.New(agent.Options{
-		ExchangeToken: func(ctx context.Context) (string, error) {
-			initialized.Add(1)
-			return "", nil
-		},
 		Client: client,
 		Logger: logger.Named("agent"),
 	})
 	defer closer.Close()
 
-	require.Eventually(t, func() bool {
-		return coordinator.Node(agentID) != nil
-	}, testutil.WaitShort, testutil.IntervalFast)
-	client.LastWorkspaceAgent()
-	require.Eventually(t, func() bool {
-		return initialized.Load() == 2
-	}, testutil.WaitShort, testutil.IntervalFast)
+	call1 := testutil.RequireReceive(ctx, t, fCoordinator.CoordinateCalls)
+	require.Equal(t, client.GetNumRefreshTokenCalls(), 1)
+	close(call1.Resps) // hang up
+	// expect reconnect
+	testutil.RequireReceive(ctx, t, fCoordinator.CoordinateCalls)
+	// Check that the agent refreshes the token when it reconnects.
+	require.Equal(t, client.GetNumRefreshTokenCalls(), 2)
+	closer.Close()
 }
 
 func TestAgent_WriteVSCodeConfigs(t *testing.T) {
@@ -2984,9 +2982,6 @@ func TestAgent_WriteVSCodeConfigs(t *testing.T) {
 	defer client.Close()
 	filesystem := afero.NewMemMapFs()
 	closer := agent.New(agent.Options{
-		ExchangeToken: func(ctx context.Context) (string, error) {
-			return "", nil
-		},
 		Client:     client,
 		Logger:     logger.Named("agent"),
 		Filesystem: filesystem,
@@ -3015,9 +3010,6 @@ func TestAgent_DebugServer(t *testing.T) {
 	conn, _, _, _, agnt := setupAgent(t, agentsdk.Manifest{
 		DERPMap: derpMap,
 	}, 0, func(c *agenttest.Client, o *agent.Options) {
-		o.ExchangeToken = func(context.Context) (string, error) {
-			return "token", nil
-		}
 		o.LogDir = logDir
 	})
 
@@ -3470,11 +3462,7 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 	registry := prometheus.NewRegistry()
 
 	//nolint:dogsled
-	conn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{
-		// Make sure we always get a DERP connection for
-		// currently_reachable_peers.
-		DisableDirectConnections: true,
-	}, 0, func(_ *agenttest.Client, o *agent.Options) {
+	conn, _, _, _, _ := setupAgent(t, agentsdk.Manifest{}, 0, func(_ *agenttest.Client, o *agent.Options) {
 		o.PrometheusRegistry = registry
 	})
 
@@ -3489,16 +3477,31 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 	err = session.Shell()
 	require.NoError(t, err)
 
-	expected := []*proto.Stats_Metric{
+	expected := []struct {
+		Name    string
+		Type    proto.Stats_Metric_Type
+		CheckFn func(float64) error
+		Labels  []*proto.Stats_Metric_Label
+	}{
 		{
-			Name:  "agent_reconnecting_pty_connections_total",
-			Type:  proto.Stats_Metric_COUNTER,
-			Value: 0,
+			Name: "agent_reconnecting_pty_connections_total",
+			Type: proto.Stats_Metric_COUNTER,
+			CheckFn: func(v float64) error {
+				if v == 0 {
+					return nil
+				}
+				return xerrors.Errorf("expected 0, got %f", v)
+			},
 		},
 		{
-			Name:  "agent_sessions_total",
-			Type:  proto.Stats_Metric_COUNTER,
-			Value: 1,
+			Name: "agent_sessions_total",
+			Type: proto.Stats_Metric_COUNTER,
+			CheckFn: func(v float64) error {
+				if v == 1 {
+					return nil
+				}
+				return xerrors.Errorf("expected 1, got %f", v)
+			},
 			Labels: []*proto.Stats_Metric_Label{
 				{
 					Name:  "magic_type",
@@ -3511,24 +3514,44 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 			},
 		},
 		{
-			Name:  "agent_ssh_server_failed_connections_total",
-			Type:  proto.Stats_Metric_COUNTER,
-			Value: 0,
+			Name: "agent_ssh_server_failed_connections_total",
+			Type: proto.Stats_Metric_COUNTER,
+			CheckFn: func(v float64) error {
+				if v == 0 {
+					return nil
+				}
+				return xerrors.Errorf("expected 0, got %f", v)
+			},
 		},
 		{
-			Name:  "agent_ssh_server_sftp_connections_total",
-			Type:  proto.Stats_Metric_COUNTER,
-			Value: 0,
+			Name: "agent_ssh_server_sftp_connections_total",
+			Type: proto.Stats_Metric_COUNTER,
+			CheckFn: func(v float64) error {
+				if v == 0 {
+					return nil
+				}
+				return xerrors.Errorf("expected 0, got %f", v)
+			},
 		},
 		{
-			Name:  "agent_ssh_server_sftp_server_errors_total",
-			Type:  proto.Stats_Metric_COUNTER,
-			Value: 0,
+			Name: "agent_ssh_server_sftp_server_errors_total",
+			Type: proto.Stats_Metric_COUNTER,
+			CheckFn: func(v float64) error {
+				if v == 0 {
+					return nil
+				}
+				return xerrors.Errorf("expected 0, got %f", v)
+			},
 		},
 		{
-			Name:  "coderd_agentstats_currently_reachable_peers",
-			Type:  proto.Stats_Metric_GAUGE,
-			Value: 1,
+			Name: "coderd_agentstats_currently_reachable_peers",
+			Type: proto.Stats_Metric_GAUGE,
+			CheckFn: func(float64) error {
+				// We can't reliably ping a peer here, and networking is out of
+				// scope of this test, so we just test that the metric exists
+				// with the correct labels.
+				return nil
+			},
 			Labels: []*proto.Stats_Metric_Label{
 				{
 					Name:  "connection_type",
@@ -3537,9 +3560,11 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 			},
 		},
 		{
-			Name:  "coderd_agentstats_currently_reachable_peers",
-			Type:  proto.Stats_Metric_GAUGE,
-			Value: 0,
+			Name: "coderd_agentstats_currently_reachable_peers",
+			Type: proto.Stats_Metric_GAUGE,
+			CheckFn: func(float64) error {
+				return nil
+			},
 			Labels: []*proto.Stats_Metric_Label{
 				{
 					Name:  "connection_type",
@@ -3548,9 +3573,20 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 			},
 		},
 		{
-			Name:  "coderd_agentstats_startup_script_seconds",
-			Type:  proto.Stats_Metric_GAUGE,
-			Value: 1,
+			Name: "coderd_agentstats_startup_script_seconds",
+			Type: proto.Stats_Metric_GAUGE,
+			CheckFn: func(f float64) error {
+				if f >= 0 {
+					return nil
+				}
+				return xerrors.Errorf("expected >= 0, got %f", f)
+			},
+			Labels: []*proto.Stats_Metric_Label{
+				{
+					Name:  "success",
+					Value: "true",
+				},
+			},
 		},
 	}
 
@@ -3572,11 +3608,10 @@ func TestAgent_Metrics_SSH(t *testing.T) {
 		for _, m := range mf.GetMetric() {
 			assert.Equal(t, expected[i].Name, mf.GetName())
 			assert.Equal(t, expected[i].Type.String(), mf.GetType().String())
-			// Value is max expected
 			if expected[i].Type == proto.Stats_Metric_GAUGE {
-				assert.GreaterOrEqualf(t, expected[i].Value, m.GetGauge().GetValue(), "expected %s to be greater than or equal to %f, got %f", expected[i].Name, expected[i].Value, m.GetGauge().GetValue())
+				assert.NoError(t, expected[i].CheckFn(m.GetGauge().GetValue()), "check fn for %s failed", expected[i].Name)
 			} else if expected[i].Type == proto.Stats_Metric_COUNTER {
-				assert.GreaterOrEqualf(t, expected[i].Value, m.GetCounter().GetValue(), "expected %s to be greater than or equal to %f, got %f", expected[i].Name, expected[i].Value, m.GetCounter().GetValue())
+				assert.NoError(t, expected[i].CheckFn(m.GetCounter().GetValue()), "check fn for %s failed", expected[i].Name)
 			}
 			for j, lbl := range expected[i].Labels {
 				assert.Equal(t, m.GetLabel()[j], &promgo.LabelPair{

agent/agentcontainers/api.go

@@ -682,8 +682,6 @@ func (api *API) updaterLoop() {
 			} else {
 				prevErr = nil
 			}
-		default:
-			api.logger.Debug(api.ctx, "updater loop ticker skipped, update in progress")
 		}
 
 		return nil // Always nil to keep the ticker going.

agent/agentsocket/client.go

@@ -0,0 +1,146 @@
+package agentsocket
+
+import (
+	"context"
+
+	"golang.org/x/xerrors"
+	"storj.io/drpc"
+	"storj.io/drpc/drpcconn"
+
+	"github.com/coder/coder/v2/agent/agentsocket/proto"
+	"github.com/coder/coder/v2/agent/unit"
+)
+
+// Option represents a configuration option for NewClient.
+type Option func(*options)
+
+type options struct {
+	path string
+}
+
+// WithPath sets the socket path. If not provided or empty, the client will
+// auto-discover the default socket path.
+func WithPath(path string) Option {
+	return func(opts *options) {
+		if path == "" {
+			return
+		}
+		opts.path = path
+	}
+}
+
+// Client provides a client for communicating with the workspace agentsocket API.
+type Client struct {
+	client proto.DRPCAgentSocketClient
+	conn   drpc.Conn
+}
+
+// NewClient creates a new socket client and opens a connection to the socket.
+// If path is not provided via WithPath or is empty, it will auto-discover the
+// default socket path.
+func NewClient(ctx context.Context, opts ...Option) (*Client, error) {
+	options := &options{}
+	for _, opt := range opts {
+		opt(options)
+	}
+
+	conn, err := dialSocket(ctx, options.path)
+	if err != nil {
+		return nil, xerrors.Errorf("connect to socket: %w", err)
+	}
+
+	drpcConn := drpcconn.New(conn)
+	client := proto.NewDRPCAgentSocketClient(drpcConn)
+
+	return &Client{
+		client: client,
+		conn:   drpcConn,
+	}, nil
+}
+
+// Close closes the socket connection.
+func (c *Client) Close() error {
+	return c.conn.Close()
+}
+
+// Ping sends a ping request to the agent.
+func (c *Client) Ping(ctx context.Context) error {
+	_, err := c.client.Ping(ctx, &proto.PingRequest{})
+	return err
+}
+
+// SyncStart starts a unit in the dependency graph.
+func (c *Client) SyncStart(ctx context.Context, unitName unit.ID) error {
+	_, err := c.client.SyncStart(ctx, &proto.SyncStartRequest{
+		Unit: string(unitName),
+	})
+	return err
+}
+
+// SyncWant declares a dependency between units.
+func (c *Client) SyncWant(ctx context.Context, unitName, dependsOn unit.ID) error {
+	_, err := c.client.SyncWant(ctx, &proto.SyncWantRequest{
+		Unit:      string(unitName),
+		DependsOn: string(dependsOn),
+	})
+	return err
+}
+
+// SyncComplete marks a unit as complete in the dependency graph.
+func (c *Client) SyncComplete(ctx context.Context, unitName unit.ID) error {
+	_, err := c.client.SyncComplete(ctx, &proto.SyncCompleteRequest{
+		Unit: string(unitName),
+	})
+	return err
+}
+
+// SyncReady requests whether a unit is ready to be started. That is, all dependencies are satisfied.
+func (c *Client) SyncReady(ctx context.Context, unitName unit.ID) (bool, error) {
+	resp, err := c.client.SyncReady(ctx, &proto.SyncReadyRequest{
+		Unit: string(unitName),
+	})
+	return resp.Ready, err
+}
+
+// SyncStatus gets the status of a unit and its dependencies.
+func (c *Client) SyncStatus(ctx context.Context, unitName unit.ID) (SyncStatusResponse, error) {
+	resp, err := c.client.SyncStatus(ctx, &proto.SyncStatusRequest{
+		Unit: string(unitName),
+	})
+	if err != nil {
+		return SyncStatusResponse{}, err
+	}
+
+	var dependencies []DependencyInfo
+	for _, dep := range resp.Dependencies {
+		dependencies = append(dependencies, DependencyInfo{
+			DependsOn:      unit.ID(dep.DependsOn),
+			RequiredStatus: unit.Status(dep.RequiredStatus),
+			CurrentStatus:  unit.Status(dep.CurrentStatus),
+			IsSatisfied:    dep.IsSatisfied,
+		})
+	}
+
+	return SyncStatusResponse{
+		UnitName:     unitName,
+		Status:       unit.Status(resp.Status),
+		IsReady:      resp.IsReady,
+		Dependencies: dependencies,
+	}, nil
+}
+
+// SyncStatusResponse contains the status information for a unit.
+type SyncStatusResponse struct {
+	UnitName     unit.ID          `table:"unit,default_sort" json:"unit_name"`
+	Status       unit.Status      `table:"status" json:"status"`
+	IsReady      bool             `table:"ready" json:"is_ready"`
+	Dependencies []DependencyInfo `table:"dependencies" json:"dependencies"`
+}
+
+// DependencyInfo contains information about a unit dependency.
+type DependencyInfo struct {
+	DependsOn      unit.ID     `table:"depends on,default_sort" json:"depends_on"`
+	RequiredStatus unit.Status `table:"required status" json:"required_status"`
+	CurrentStatus  unit.Status `table:"current status" json:"current_status"`
+	IsSatisfied    bool        `table:"satisfied" json:"is_satisfied"`
+}

agent/agentsocket/proto/agentsocket.pb.go

@@ -0,0 +1,968 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.30.0
+// 	protoc        v4.23.4
+// source: agent/agentsocket/proto/agentsocket.proto
+
+package proto
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+type PingRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+}
+
+func (x *PingRequest) Reset() {
+	*x = PingRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[0]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *PingRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PingRequest) ProtoMessage() {}
+
+func (x *PingRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[0]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PingRequest.ProtoReflect.Descriptor instead.
+func (*PingRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{0}
+}
+
+type PingResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+}
+
+func (x *PingResponse) Reset() {
+	*x = PingResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[1]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *PingResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*PingResponse) ProtoMessage() {}
+
+func (x *PingResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[1]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use PingResponse.ProtoReflect.Descriptor instead.
+func (*PingResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{1}
+}
+
+type SyncStartRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+}
+
+func (x *SyncStartRequest) Reset() {
+	*x = SyncStartRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[2]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncStartRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncStartRequest) ProtoMessage() {}
+
+func (x *SyncStartRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[2]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncStartRequest.ProtoReflect.Descriptor instead.
+func (*SyncStartRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{2}
+}
+
+func (x *SyncStartRequest) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+type SyncStartResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+}
+
+func (x *SyncStartResponse) Reset() {
+	*x = SyncStartResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[3]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncStartResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncStartResponse) ProtoMessage() {}
+
+func (x *SyncStartResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[3]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncStartResponse.ProtoReflect.Descriptor instead.
+func (*SyncStartResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{3}
+}
+
+type SyncWantRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit      string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+	DependsOn string `protobuf:"bytes,2,opt,name=depends_on,json=dependsOn,proto3" json:"depends_on,omitempty"`
+}
+
+func (x *SyncWantRequest) Reset() {
+	*x = SyncWantRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[4]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncWantRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncWantRequest) ProtoMessage() {}
+
+func (x *SyncWantRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[4]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncWantRequest.ProtoReflect.Descriptor instead.
+func (*SyncWantRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *SyncWantRequest) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+func (x *SyncWantRequest) GetDependsOn() string {
+	if x != nil {
+		return x.DependsOn
+	}
+	return ""
+}
+
+type SyncWantResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+}
+
+func (x *SyncWantResponse) Reset() {
+	*x = SyncWantResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[5]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncWantResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncWantResponse) ProtoMessage() {}
+
+func (x *SyncWantResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[5]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncWantResponse.ProtoReflect.Descriptor instead.
+func (*SyncWantResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{5}
+}
+
+type SyncCompleteRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+}
+
+func (x *SyncCompleteRequest) Reset() {
+	*x = SyncCompleteRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[6]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncCompleteRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncCompleteRequest) ProtoMessage() {}
+
+func (x *SyncCompleteRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[6]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncCompleteRequest.ProtoReflect.Descriptor instead.
+func (*SyncCompleteRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{6}
+}
+
+func (x *SyncCompleteRequest) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+type SyncCompleteResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+}
+
+func (x *SyncCompleteResponse) Reset() {
+	*x = SyncCompleteResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[7]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncCompleteResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncCompleteResponse) ProtoMessage() {}
+
+func (x *SyncCompleteResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[7]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncCompleteResponse.ProtoReflect.Descriptor instead.
+func (*SyncCompleteResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{7}
+}
+
+type SyncReadyRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+}
+
+func (x *SyncReadyRequest) Reset() {
+	*x = SyncReadyRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[8]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncReadyRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncReadyRequest) ProtoMessage() {}
+
+func (x *SyncReadyRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[8]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncReadyRequest.ProtoReflect.Descriptor instead.
+func (*SyncReadyRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{8}
+}
+
+func (x *SyncReadyRequest) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+type SyncReadyResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Ready bool `protobuf:"varint,1,opt,name=ready,proto3" json:"ready,omitempty"`
+}
+
+func (x *SyncReadyResponse) Reset() {
+	*x = SyncReadyResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[9]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncReadyResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncReadyResponse) ProtoMessage() {}
+
+func (x *SyncReadyResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[9]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncReadyResponse.ProtoReflect.Descriptor instead.
+func (*SyncReadyResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{9}
+}
+
+func (x *SyncReadyResponse) GetReady() bool {
+	if x != nil {
+		return x.Ready
+	}
+	return false
+}
+
+type SyncStatusRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+}
+
+func (x *SyncStatusRequest) Reset() {
+	*x = SyncStatusRequest{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[10]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncStatusRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncStatusRequest) ProtoMessage() {}
+
+func (x *SyncStatusRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[10]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncStatusRequest.ProtoReflect.Descriptor instead.
+func (*SyncStatusRequest) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{10}
+}
+
+func (x *SyncStatusRequest) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+type DependencyInfo struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Unit           string `protobuf:"bytes,1,opt,name=unit,proto3" json:"unit,omitempty"`
+	DependsOn      string `protobuf:"bytes,2,opt,name=depends_on,json=dependsOn,proto3" json:"depends_on,omitempty"`
+	RequiredStatus string `protobuf:"bytes,3,opt,name=required_status,json=requiredStatus,proto3" json:"required_status,omitempty"`
+	CurrentStatus  string `protobuf:"bytes,4,opt,name=current_status,json=currentStatus,proto3" json:"current_status,omitempty"`
+	IsSatisfied    bool   `protobuf:"varint,5,opt,name=is_satisfied,json=isSatisfied,proto3" json:"is_satisfied,omitempty"`
+}
+
+func (x *DependencyInfo) Reset() {
+	*x = DependencyInfo{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[11]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *DependencyInfo) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*DependencyInfo) ProtoMessage() {}
+
+func (x *DependencyInfo) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[11]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use DependencyInfo.ProtoReflect.Descriptor instead.
+func (*DependencyInfo) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{11}
+}
+
+func (x *DependencyInfo) GetUnit() string {
+	if x != nil {
+		return x.Unit
+	}
+	return ""
+}
+
+func (x *DependencyInfo) GetDependsOn() string {
+	if x != nil {
+		return x.DependsOn
+	}
+	return ""
+}
+
+func (x *DependencyInfo) GetRequiredStatus() string {
+	if x != nil {
+		return x.RequiredStatus
+	}
+	return ""
+}
+
+func (x *DependencyInfo) GetCurrentStatus() string {
+	if x != nil {
+		return x.CurrentStatus
+	}
+	return ""
+}
+
+func (x *DependencyInfo) GetIsSatisfied() bool {
+	if x != nil {
+		return x.IsSatisfied
+	}
+	return false
+}
+
+type SyncStatusResponse struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	Status       string            `protobuf:"bytes,1,opt,name=status,proto3" json:"status,omitempty"`
+	IsReady      bool              `protobuf:"varint,2,opt,name=is_ready,json=isReady,proto3" json:"is_ready,omitempty"`
+	Dependencies []*DependencyInfo `protobuf:"bytes,3,rep,name=dependencies,proto3" json:"dependencies,omitempty"`
+}
+
+func (x *SyncStatusResponse) Reset() {
+	*x = SyncStatusResponse{}
+	if protoimpl.UnsafeEnabled {
+		mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[12]
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		ms.StoreMessageInfo(mi)
+	}
+}
+
+func (x *SyncStatusResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SyncStatusResponse) ProtoMessage() {}
+
+func (x *SyncStatusResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_agent_agentsocket_proto_agentsocket_proto_msgTypes[12]
+	if protoimpl.UnsafeEnabled && x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SyncStatusResponse.ProtoReflect.Descriptor instead.
+func (*SyncStatusResponse) Descriptor() ([]byte, []int) {
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *SyncStatusResponse) GetStatus() string {
+	if x != nil {
+		return x.Status
+	}
+	return ""
+}
+
+func (x *SyncStatusResponse) GetIsReady() bool {
+	if x != nil {
+		return x.IsReady
+	}
+	return false
+}
+
+func (x *SyncStatusResponse) GetDependencies() []*DependencyInfo {
+	if x != nil {
+		return x.Dependencies
+	}
+	return nil
+}
+
+var File_agent_agentsocket_proto_agentsocket_proto protoreflect.FileDescriptor
+
+var file_agent_agentsocket_proto_agentsocket_proto_rawDesc = []byte{
+	0x0a, 0x29, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x2f, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63,
+	0x6b, 0x65, 0x74, 0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x2f, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73,
+	0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x12, 0x14, 0x63, 0x6f, 0x64,
+	0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76,
+	0x31, 0x22, 0x0d, 0x0a, 0x0b, 0x50, 0x69, 0x6e, 0x67, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74,
+	0x22, 0x0e, 0x0a, 0x0c, 0x50, 0x69, 0x6e, 0x67, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65,
+	0x22, 0x26, 0x0a, 0x10, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x72, 0x74, 0x52, 0x65, 0x71,
+	0x75, 0x65, 0x73, 0x74, 0x12, 0x12, 0x0a, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x18, 0x01, 0x20, 0x01,
+	0x28, 0x09, 0x52, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x22, 0x13, 0x0a, 0x11, 0x53, 0x79, 0x6e, 0x63,
+	0x53, 0x74, 0x61, 0x72, 0x74, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x22, 0x44, 0x0a,
+	0x0f, 0x53, 0x79, 0x6e, 0x63, 0x57, 0x61, 0x6e, 0x74, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74,
+	0x12, 0x12, 0x0a, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04,
+	0x75, 0x6e, 0x69, 0x74, 0x12, 0x1d, 0x0a, 0x0a, 0x64, 0x65, 0x70, 0x65, 0x6e, 0x64, 0x73, 0x5f,
+	0x6f, 0x6e, 0x18, 0x02, 0x20, 0x01, 0x28, 0x09, 0x52, 0x09, 0x64, 0x65, 0x70, 0x65, 0x6e, 0x64,
+	0x73, 0x4f, 0x6e, 0x22, 0x12, 0x0a, 0x10, 0x53, 0x79, 0x6e, 0x63, 0x57, 0x61, 0x6e, 0x74, 0x52,
+	0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x22, 0x29, 0x0a, 0x13, 0x53, 0x79, 0x6e, 0x63, 0x43,
+	0x6f, 0x6d, 0x70, 0x6c, 0x65, 0x74, 0x65, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x12, 0x12,
+	0x0a, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x75, 0x6e,
+	0x69, 0x74, 0x22, 0x16, 0x0a, 0x14, 0x53, 0x79, 0x6e, 0x63, 0x43, 0x6f, 0x6d, 0x70, 0x6c, 0x65,
+	0x74, 0x65, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x22, 0x26, 0x0a, 0x10, 0x53, 0x79,
+	0x6e, 0x63, 0x52, 0x65, 0x61, 0x64, 0x79, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x12, 0x12,
+	0x0a, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x75, 0x6e,
+	0x69, 0x74, 0x22, 0x29, 0x0a, 0x11, 0x53, 0x79, 0x6e, 0x63, 0x52, 0x65, 0x61, 0x64, 0x79, 0x52,
+	0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x12, 0x14, 0x0a, 0x05, 0x72, 0x65, 0x61, 0x64, 0x79,
+	0x18, 0x01, 0x20, 0x01, 0x28, 0x08, 0x52, 0x05, 0x72, 0x65, 0x61, 0x64, 0x79, 0x22, 0x27, 0x0a,
+	0x11, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x52, 0x65, 0x71, 0x75, 0x65,
+	0x73, 0x74, 0x12, 0x12, 0x0a, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09,
+	0x52, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x22, 0xb6, 0x01, 0x0a, 0x0e, 0x44, 0x65, 0x70, 0x65, 0x6e,
+	0x64, 0x65, 0x6e, 0x63, 0x79, 0x49, 0x6e, 0x66, 0x6f, 0x12, 0x12, 0x0a, 0x04, 0x75, 0x6e, 0x69,
+	0x74, 0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x04, 0x75, 0x6e, 0x69, 0x74, 0x12, 0x1d, 0x0a,
+	0x0a, 0x64, 0x65, 0x70, 0x65, 0x6e, 0x64, 0x73, 0x5f, 0x6f, 0x6e, 0x18, 0x02, 0x20, 0x01, 0x28,
+	0x09, 0x52, 0x09, 0x64, 0x65, 0x70, 0x65, 0x6e, 0x64, 0x73, 0x4f, 0x6e, 0x12, 0x27, 0x0a, 0x0f,
+	0x72, 0x65, 0x71, 0x75, 0x69, 0x72, 0x65, 0x64, 0x5f, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73, 0x18,
+	0x03, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0e, 0x72, 0x65, 0x71, 0x75, 0x69, 0x72, 0x65, 0x64, 0x53,
+	0x74, 0x61, 0x74, 0x75, 0x73, 0x12, 0x25, 0x0a, 0x0e, 0x63, 0x75, 0x72, 0x72, 0x65, 0x6e, 0x74,
+	0x5f, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73, 0x18, 0x04, 0x20, 0x01, 0x28, 0x09, 0x52, 0x0d, 0x63,
+	0x75, 0x72, 0x72, 0x65, 0x6e, 0x74, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x12, 0x21, 0x0a, 0x0c,
+	0x69, 0x73, 0x5f, 0x73, 0x61, 0x74, 0x69, 0x73, 0x66, 0x69, 0x65, 0x64, 0x18, 0x05, 0x20, 0x01,
+	0x28, 0x08, 0x52, 0x0b, 0x69, 0x73, 0x53, 0x61, 0x74, 0x69, 0x73, 0x66, 0x69, 0x65, 0x64, 0x22,
+	0x91, 0x01, 0x0a, 0x12, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x52, 0x65,
+	0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x12, 0x16, 0x0a, 0x06, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73,
+	0x18, 0x01, 0x20, 0x01, 0x28, 0x09, 0x52, 0x06, 0x73, 0x74, 0x61, 0x74, 0x75, 0x73, 0x12, 0x19,
+	0x0a, 0x08, 0x69, 0x73, 0x5f, 0x72, 0x65, 0x61, 0x64, 0x79, 0x18, 0x02, 0x20, 0x01, 0x28, 0x08,
+	0x52, 0x07, 0x69, 0x73, 0x52, 0x65, 0x61, 0x64, 0x79, 0x12, 0x48, 0x0a, 0x0c, 0x64, 0x65, 0x70,
+	0x65, 0x6e, 0x64, 0x65, 0x6e, 0x63, 0x69, 0x65, 0x73, 0x18, 0x03, 0x20, 0x03, 0x28, 0x0b, 0x32,
+	0x24, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63,
+	0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x44, 0x65, 0x70, 0x65, 0x6e, 0x64, 0x65, 0x6e, 0x63,
+	0x79, 0x49, 0x6e, 0x66, 0x6f, 0x52, 0x0c, 0x64, 0x65, 0x70, 0x65, 0x6e, 0x64, 0x65, 0x6e, 0x63,
+	0x69, 0x65, 0x73, 0x32, 0xbb, 0x04, 0x0a, 0x0b, 0x41, 0x67, 0x65, 0x6e, 0x74, 0x53, 0x6f, 0x63,
+	0x6b, 0x65, 0x74, 0x12, 0x4d, 0x0a, 0x04, 0x50, 0x69, 0x6e, 0x67, 0x12, 0x21, 0x2e, 0x63, 0x6f,
+	0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e,
+	0x76, 0x31, 0x2e, 0x50, 0x69, 0x6e, 0x67, 0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x22,
+	0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b,
+	0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x50, 0x69, 0x6e, 0x67, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e,
+	0x73, 0x65, 0x12, 0x5c, 0x0a, 0x09, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x72, 0x74, 0x12,
+	0x26, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63,
+	0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x72, 0x74,
+	0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x27, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e,
+	0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53,
+	0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x72, 0x74, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65,
+	0x12, 0x59, 0x0a, 0x08, 0x53, 0x79, 0x6e, 0x63, 0x57, 0x61, 0x6e, 0x74, 0x12, 0x25, 0x2e, 0x63,
+	0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74,
+	0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x57, 0x61, 0x6e, 0x74, 0x52, 0x65, 0x71, 0x75,
+	0x65, 0x73, 0x74, 0x1a, 0x26, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e,
+	0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x57,
+	0x61, 0x6e, 0x74, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65, 0x12, 0x65, 0x0a, 0x0c, 0x53,
+	0x79, 0x6e, 0x63, 0x43, 0x6f, 0x6d, 0x70, 0x6c, 0x65, 0x74, 0x65, 0x12, 0x29, 0x2e, 0x63, 0x6f,
+	0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e,
+	0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x43, 0x6f, 0x6d, 0x70, 0x6c, 0x65, 0x74, 0x65, 0x52,
+	0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x2a, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61,
+	0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79,
+	0x6e, 0x63, 0x43, 0x6f, 0x6d, 0x70, 0x6c, 0x65, 0x74, 0x65, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e,
+	0x73, 0x65, 0x12, 0x5c, 0x0a, 0x09, 0x53, 0x79, 0x6e, 0x63, 0x52, 0x65, 0x61, 0x64, 0x79, 0x12,
+	0x26, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63,
+	0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x52, 0x65, 0x61, 0x64, 0x79,
+	0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x27, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e,
+	0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53,
+	0x79, 0x6e, 0x63, 0x52, 0x65, 0x61, 0x64, 0x79, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73, 0x65,
+	0x12, 0x5f, 0x0a, 0x0a, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x12, 0x27,
+	0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b,
+	0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53, 0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73,
+	0x52, 0x65, 0x71, 0x75, 0x65, 0x73, 0x74, 0x1a, 0x28, 0x2e, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2e,
+	0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74, 0x2e, 0x76, 0x31, 0x2e, 0x53,
+	0x79, 0x6e, 0x63, 0x53, 0x74, 0x61, 0x74, 0x75, 0x73, 0x52, 0x65, 0x73, 0x70, 0x6f, 0x6e, 0x73,
+	0x65, 0x42, 0x33, 0x5a, 0x31, 0x67, 0x69, 0x74, 0x68, 0x75, 0x62, 0x2e, 0x63, 0x6f, 0x6d, 0x2f,
+	0x63, 0x6f, 0x64, 0x65, 0x72, 0x2f, 0x63, 0x6f, 0x64, 0x65, 0x72, 0x2f, 0x76, 0x32, 0x2f, 0x61,
+	0x67, 0x65, 0x6e, 0x74, 0x2f, 0x61, 0x67, 0x65, 0x6e, 0x74, 0x73, 0x6f, 0x63, 0x6b, 0x65, 0x74,
+	0x2f, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x62, 0x06, 0x70, 0x72, 0x6f, 0x74, 0x6f, 0x33,
+}
+
+var (
+	file_agent_agentsocket_proto_agentsocket_proto_rawDescOnce sync.Once
+	file_agent_agentsocket_proto_agentsocket_proto_rawDescData = file_agent_agentsocket_proto_agentsocket_proto_rawDesc
+)
+
+func file_agent_agentsocket_proto_agentsocket_proto_rawDescGZIP() []byte {
+	file_agent_agentsocket_proto_agentsocket_proto_rawDescOnce.Do(func() {
+		file_agent_agentsocket_proto_agentsocket_proto_rawDescData = protoimpl.X.CompressGZIP(file_agent_agentsocket_proto_agentsocket_proto_rawDescData)
+	})
+	return file_agent_agentsocket_proto_agentsocket_proto_rawDescData
+}
+
+var file_agent_agentsocket_proto_agentsocket_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
+var file_agent_agentsocket_proto_agentsocket_proto_goTypes = []interface{}{
+	(*PingRequest)(nil),          // 0: coder.agentsocket.v1.PingRequest
+	(*PingResponse)(nil),         // 1: coder.agentsocket.v1.PingResponse
+	(*SyncStartRequest)(nil),     // 2: coder.agentsocket.v1.SyncStartRequest
+	(*SyncStartResponse)(nil),    // 3: coder.agentsocket.v1.SyncStartResponse
+	(*SyncWantRequest)(nil),      // 4: coder.agentsocket.v1.SyncWantRequest
+	(*SyncWantResponse)(nil),     // 5: coder.agentsocket.v1.SyncWantResponse
+	(*SyncCompleteRequest)(nil),  // 6: coder.agentsocket.v1.SyncCompleteRequest
+	(*SyncCompleteResponse)(nil), // 7: coder.agentsocket.v1.SyncCompleteResponse
+	(*SyncReadyRequest)(nil),     // 8: coder.agentsocket.v1.SyncReadyRequest
+	(*SyncReadyResponse)(nil),    // 9: coder.agentsocket.v1.SyncReadyResponse
+	(*SyncStatusRequest)(nil),    // 10: coder.agentsocket.v1.SyncStatusRequest
+	(*DependencyInfo)(nil),       // 11: coder.agentsocket.v1.DependencyInfo
+	(*SyncStatusResponse)(nil),   // 12: coder.agentsocket.v1.SyncStatusResponse
+}
+var file_agent_agentsocket_proto_agentsocket_proto_depIdxs = []int32{
+	11, // 0: coder.agentsocket.v1.SyncStatusResponse.dependencies:type_name -> coder.agentsocket.v1.DependencyInfo
+	0,  // 1: coder.agentsocket.v1.AgentSocket.Ping:input_type -> coder.agentsocket.v1.PingRequest
+	2,  // 2: coder.agentsocket.v1.AgentSocket.SyncStart:input_type -> coder.agentsocket.v1.SyncStartRequest
+	4,  // 3: coder.agentsocket.v1.AgentSocket.SyncWant:input_type -> coder.agentsocket.v1.SyncWantRequest
+	6,  // 4: coder.agentsocket.v1.AgentSocket.SyncComplete:input_type -> coder.agentsocket.v1.SyncCompleteRequest
+	8,  // 5: coder.agentsocket.v1.AgentSocket.SyncReady:input_type -> coder.agentsocket.v1.SyncReadyRequest
+	10, // 6: coder.agentsocket.v1.AgentSocket.SyncStatus:input_type -> coder.agentsocket.v1.SyncStatusRequest
+	1,  // 7: coder.agentsocket.v1.AgentSocket.Ping:output_type -> coder.agentsocket.v1.PingResponse
+	3,  // 8: coder.agentsocket.v1.AgentSocket.SyncStart:output_type -> coder.agentsocket.v1.SyncStartResponse
+	5,  // 9: coder.agentsocket.v1.AgentSocket.SyncWant:output_type -> coder.agentsocket.v1.SyncWantResponse
+	7,  // 10: coder.agentsocket.v1.AgentSocket.SyncComplete:output_type -> coder.agentsocket.v1.SyncCompleteResponse
+	9,  // 11: coder.agentsocket.v1.AgentSocket.SyncReady:output_type -> coder.agentsocket.v1.SyncReadyResponse
+	12, // 12: coder.agentsocket.v1.AgentSocket.SyncStatus:output_type -> coder.agentsocket.v1.SyncStatusResponse
+	7,  // [7:13] is the sub-list for method output_type
+	1,  // [1:7] is the sub-list for method input_type
+	1,  // [1:1] is the sub-list for extension type_name
+	1,  // [1:1] is the sub-list for extension extendee
+	0,  // [0:1] is the sub-list for field type_name
+}
+
+func init() { file_agent_agentsocket_proto_agentsocket_proto_init() }
+func file_agent_agentsocket_proto_agentsocket_proto_init() {
+	if File_agent_agentsocket_proto_agentsocket_proto != nil {
+		return
+	}
+	if !protoimpl.UnsafeEnabled {
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[0].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*PingRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[1].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*PingResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[2].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncStartRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[3].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncStartResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[4].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncWantRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[5].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncWantResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[6].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncCompleteRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[7].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncCompleteResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[8].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncReadyRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[9].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncReadyResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[10].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncStatusRequest); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[11].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*DependencyInfo); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+		file_agent_agentsocket_proto_agentsocket_proto_msgTypes[12].Exporter = func(v interface{}, i int) interface{} {
+			switch v := v.(*SyncStatusResponse); i {
+			case 0:
+				return &v.state
+			case 1:
+				return &v.sizeCache
+			case 2:
+				return &v.unknownFields
+			default:
+				return nil
+			}
+		}
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: file_agent_agentsocket_proto_agentsocket_proto_rawDesc,
+			NumEnums:      0,
+			NumMessages:   13,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_agent_agentsocket_proto_agentsocket_proto_goTypes,
+		DependencyIndexes: file_agent_agentsocket_proto_agentsocket_proto_depIdxs,
+		MessageInfos:      file_agent_agentsocket_proto_agentsocket_proto_msgTypes,
+	}.Build()
+	File_agent_agentsocket_proto_agentsocket_proto = out.File
+	file_agent_agentsocket_proto_agentsocket_proto_rawDesc = nil
+	file_agent_agentsocket_proto_agentsocket_proto_goTypes = nil
+	file_agent_agentsocket_proto_agentsocket_proto_depIdxs = nil
+}

agent/agentsocket/proto/agentsocket.proto

@@ -0,0 +1,69 @@
+syntax = "proto3";
+option go_package = "github.com/coder/coder/v2/agent/agentsocket/proto";
+
+package coder.agentsocket.v1;
+
+message PingRequest {}
+
+message PingResponse {}
+
+message SyncStartRequest {
+  string unit = 1;
+}
+
+message SyncStartResponse {}
+
+message SyncWantRequest {
+  string unit = 1;
+  string depends_on = 2;
+}
+
+message SyncWantResponse {}
+
+message SyncCompleteRequest {
+  string unit = 1;
+}
+
+message SyncCompleteResponse {}
+
+message SyncReadyRequest {
+  string unit = 1;
+}
+
+message SyncReadyResponse {
+  bool ready = 1;
+}
+
+message SyncStatusRequest {
+  string unit = 1;
+}
+
+message DependencyInfo {
+  string unit = 1;
+  string depends_on = 2;
+  string required_status = 3;
+  string current_status = 4;
+  bool is_satisfied = 5;
+}
+
+message SyncStatusResponse {
+  string status = 1;
+  bool is_ready = 2;
+  repeated DependencyInfo dependencies = 3;
+}
+
+// AgentSocket provides direct access to the agent over local IPC.
+service AgentSocket {
+  // Ping the agent to check if it is alive.
+  rpc Ping(PingRequest) returns (PingResponse);
+  // Report the start of a unit.
+  rpc SyncStart(SyncStartRequest) returns (SyncStartResponse);
+  // Declare a dependency between units.
+  rpc SyncWant(SyncWantRequest) returns (SyncWantResponse);
+  // Report the completion of a unit.
+  rpc SyncComplete(SyncCompleteRequest) returns (SyncCompleteResponse);
+  // Request whether a unit is ready to be started. That is, all dependencies are satisfied.
+  rpc SyncReady(SyncReadyRequest) returns (SyncReadyResponse);
+  // Get the status of a unit and list its dependencies.
+  rpc SyncStatus(SyncStatusRequest) returns (SyncStatusResponse);
+}

agent/agentsocket/proto/agentsocket_drpc.pb.go

@@ -0,0 +1,311 @@
+// Code generated by protoc-gen-go-drpc. DO NOT EDIT.
+// protoc-gen-go-drpc version: v0.0.34
+// source: agent/agentsocket/proto/agentsocket.proto
+
+package proto
+
+import (
+	context "context"
+	errors "errors"
+	protojson "google.golang.org/protobuf/encoding/protojson"
+	proto "google.golang.org/protobuf/proto"
+	drpc "storj.io/drpc"
+	drpcerr "storj.io/drpc/drpcerr"
+)
+
+type drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto struct{}
+
+func (drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto) Marshal(msg drpc.Message) ([]byte, error) {
+	return proto.Marshal(msg.(proto.Message))
+}
+
+func (drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto) MarshalAppend(buf []byte, msg drpc.Message) ([]byte, error) {
+	return proto.MarshalOptions{}.MarshalAppend(buf, msg.(proto.Message))
+}
+
+func (drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto) Unmarshal(buf []byte, msg drpc.Message) error {
+	return proto.Unmarshal(buf, msg.(proto.Message))
+}
+
+func (drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto) JSONMarshal(msg drpc.Message) ([]byte, error) {
+	return protojson.Marshal(msg.(proto.Message))
+}
+
+func (drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto) JSONUnmarshal(buf []byte, msg drpc.Message) error {
+	return protojson.Unmarshal(buf, msg.(proto.Message))
+}
+
+type DRPCAgentSocketClient interface {
+	DRPCConn() drpc.Conn
+
+	Ping(ctx context.Context, in *PingRequest) (*PingResponse, error)
+	SyncStart(ctx context.Context, in *SyncStartRequest) (*SyncStartResponse, error)
+	SyncWant(ctx context.Context, in *SyncWantRequest) (*SyncWantResponse, error)
+	SyncComplete(ctx context.Context, in *SyncCompleteRequest) (*SyncCompleteResponse, error)
+	SyncReady(ctx context.Context, in *SyncReadyRequest) (*SyncReadyResponse, error)
+	SyncStatus(ctx context.Context, in *SyncStatusRequest) (*SyncStatusResponse, error)
+}
+
+type drpcAgentSocketClient struct {
+	cc drpc.Conn
+}
+
+func NewDRPCAgentSocketClient(cc drpc.Conn) DRPCAgentSocketClient {
+	return &drpcAgentSocketClient{cc}
+}
+
+func (c *drpcAgentSocketClient) DRPCConn() drpc.Conn { return c.cc }
+
+func (c *drpcAgentSocketClient) Ping(ctx context.Context, in *PingRequest) (*PingResponse, error) {
+	out := new(PingResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/Ping", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *drpcAgentSocketClient) SyncStart(ctx context.Context, in *SyncStartRequest) (*SyncStartResponse, error) {
+	out := new(SyncStartResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/SyncStart", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *drpcAgentSocketClient) SyncWant(ctx context.Context, in *SyncWantRequest) (*SyncWantResponse, error) {
+	out := new(SyncWantResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/SyncWant", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *drpcAgentSocketClient) SyncComplete(ctx context.Context, in *SyncCompleteRequest) (*SyncCompleteResponse, error) {
+	out := new(SyncCompleteResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/SyncComplete", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *drpcAgentSocketClient) SyncReady(ctx context.Context, in *SyncReadyRequest) (*SyncReadyResponse, error) {
+	out := new(SyncReadyResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/SyncReady", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *drpcAgentSocketClient) SyncStatus(ctx context.Context, in *SyncStatusRequest) (*SyncStatusResponse, error) {
+	out := new(SyncStatusResponse)
+	err := c.cc.Invoke(ctx, "/coder.agentsocket.v1.AgentSocket/SyncStatus", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}, in, out)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+type DRPCAgentSocketServer interface {
+	Ping(context.Context, *PingRequest) (*PingResponse, error)
+	SyncStart(context.Context, *SyncStartRequest) (*SyncStartResponse, error)
+	SyncWant(context.Context, *SyncWantRequest) (*SyncWantResponse, error)
+	SyncComplete(context.Context, *SyncCompleteRequest) (*SyncCompleteResponse, error)
+	SyncReady(context.Context, *SyncReadyRequest) (*SyncReadyResponse, error)
+	SyncStatus(context.Context, *SyncStatusRequest) (*SyncStatusResponse, error)
+}
+
+type DRPCAgentSocketUnimplementedServer struct{}
+
+func (s *DRPCAgentSocketUnimplementedServer) Ping(context.Context, *PingRequest) (*PingResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+func (s *DRPCAgentSocketUnimplementedServer) SyncStart(context.Context, *SyncStartRequest) (*SyncStartResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+func (s *DRPCAgentSocketUnimplementedServer) SyncWant(context.Context, *SyncWantRequest) (*SyncWantResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+func (s *DRPCAgentSocketUnimplementedServer) SyncComplete(context.Context, *SyncCompleteRequest) (*SyncCompleteResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+func (s *DRPCAgentSocketUnimplementedServer) SyncReady(context.Context, *SyncReadyRequest) (*SyncReadyResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+func (s *DRPCAgentSocketUnimplementedServer) SyncStatus(context.Context, *SyncStatusRequest) (*SyncStatusResponse, error) {
+	return nil, drpcerr.WithCode(errors.New("Unimplemented"), drpcerr.Unimplemented)
+}
+
+type DRPCAgentSocketDescription struct{}
+
+func (DRPCAgentSocketDescription) NumMethods() int { return 6 }
+
+func (DRPCAgentSocketDescription) Method(n int) (string, drpc.Encoding, drpc.Receiver, interface{}, bool) {
+	switch n {
+	case 0:
+		return "/coder.agentsocket.v1.AgentSocket/Ping", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					Ping(
+						ctx,
+						in1.(*PingRequest),
+					)
+			}, DRPCAgentSocketServer.Ping, true
+	case 1:
+		return "/coder.agentsocket.v1.AgentSocket/SyncStart", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					SyncStart(
+						ctx,
+						in1.(*SyncStartRequest),
+					)
+			}, DRPCAgentSocketServer.SyncStart, true
+	case 2:
+		return "/coder.agentsocket.v1.AgentSocket/SyncWant", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					SyncWant(
+						ctx,
+						in1.(*SyncWantRequest),
+					)
+			}, DRPCAgentSocketServer.SyncWant, true
+	case 3:
+		return "/coder.agentsocket.v1.AgentSocket/SyncComplete", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					SyncComplete(
+						ctx,
+						in1.(*SyncCompleteRequest),
+					)
+			}, DRPCAgentSocketServer.SyncComplete, true
+	case 4:
+		return "/coder.agentsocket.v1.AgentSocket/SyncReady", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					SyncReady(
+						ctx,
+						in1.(*SyncReadyRequest),
+					)
+			}, DRPCAgentSocketServer.SyncReady, true
+	case 5:
+		return "/coder.agentsocket.v1.AgentSocket/SyncStatus", drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{},
+			func(srv interface{}, ctx context.Context, in1, in2 interface{}) (drpc.Message, error) {
+				return srv.(DRPCAgentSocketServer).
+					SyncStatus(
+						ctx,
+						in1.(*SyncStatusRequest),
+					)
+			}, DRPCAgentSocketServer.SyncStatus, true
+	default:
+		return "", nil, nil, nil, false
+	}
+}
+
+func DRPCRegisterAgentSocket(mux drpc.Mux, impl DRPCAgentSocketServer) error {
+	return mux.Register(impl, DRPCAgentSocketDescription{})
+}
+
+type DRPCAgentSocket_PingStream interface {
+	drpc.Stream
+	SendAndClose(*PingResponse) error
+}
+
+type drpcAgentSocket_PingStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_PingStream) SendAndClose(m *PingResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}
+
+type DRPCAgentSocket_SyncStartStream interface {
+	drpc.Stream
+	SendAndClose(*SyncStartResponse) error
+}
+
+type drpcAgentSocket_SyncStartStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_SyncStartStream) SendAndClose(m *SyncStartResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}
+
+type DRPCAgentSocket_SyncWantStream interface {
+	drpc.Stream
+	SendAndClose(*SyncWantResponse) error
+}
+
+type drpcAgentSocket_SyncWantStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_SyncWantStream) SendAndClose(m *SyncWantResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}
+
+type DRPCAgentSocket_SyncCompleteStream interface {
+	drpc.Stream
+	SendAndClose(*SyncCompleteResponse) error
+}
+
+type drpcAgentSocket_SyncCompleteStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_SyncCompleteStream) SendAndClose(m *SyncCompleteResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}
+
+type DRPCAgentSocket_SyncReadyStream interface {
+	drpc.Stream
+	SendAndClose(*SyncReadyResponse) error
+}
+
+type drpcAgentSocket_SyncReadyStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_SyncReadyStream) SendAndClose(m *SyncReadyResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}
+
+type DRPCAgentSocket_SyncStatusStream interface {
+	drpc.Stream
+	SendAndClose(*SyncStatusResponse) error
+}
+
+type drpcAgentSocket_SyncStatusStream struct {
+	drpc.Stream
+}
+
+func (x *drpcAgentSocket_SyncStatusStream) SendAndClose(m *SyncStatusResponse) error {
+	if err := x.MsgSend(m, drpcEncoding_File_agent_agentsocket_proto_agentsocket_proto{}); err != nil {
+		return err
+	}
+	return x.CloseSend()
+}

agent/agentsocket/proto/version.go

@@ -0,0 +1,17 @@
+package proto
+
+import "github.com/coder/coder/v2/apiversion"
+
+// Version history:
+//
+// API v1.0:
+//   - Initial release
+//   - Ping
+//   - Sync operations: SyncStart, SyncWant, SyncComplete, SyncWait, SyncStatus
+
+const (
+	CurrentMajor = 1
+	CurrentMinor = 0
+)
+
+var CurrentVersion = apiversion.New(CurrentMajor, CurrentMinor)

agent/agentsocket/server.go

@@ -0,0 +1,138 @@
+package agentsocket
+
+import (
+	"context"
+	"errors"
+	"net"
+	"sync"
+
+	"golang.org/x/xerrors"
+	"storj.io/drpc/drpcmux"
+	"storj.io/drpc/drpcserver"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentsocket/proto"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/codersdk/drpcsdk"
+)
+
+// Server provides access to the DRPCAgentSocketService via a Unix domain socket.
+// Do not invoke Server{} directly. Use NewServer() instead.
+type Server struct {
+	logger     slog.Logger
+	path       string
+	drpcServer *drpcserver.Server
+	service    *DRPCAgentSocketService
+
+	mu       sync.Mutex
+	listener net.Listener
+	ctx      context.Context
+	cancel   context.CancelFunc
+	wg       sync.WaitGroup
+}
+
+// NewServer creates a new agent socket server.
+func NewServer(logger slog.Logger, opts ...Option) (*Server, error) {
+	options := &options{}
+	for _, opt := range opts {
+		opt(options)
+	}
+
+	logger = logger.Named("agentsocket-server")
+	server := &Server{
+		logger: logger,
+		path:   options.path,
+		service: &DRPCAgentSocketService{
+			logger:      logger,
+			unitManager: unit.NewManager(),
+		},
+	}
+
+	mux := drpcmux.New()
+	err := proto.DRPCRegisterAgentSocket(mux, server.service)
+	if err != nil {
+		return nil, xerrors.Errorf("failed to register drpc service: %w", err)
+	}
+
+	server.drpcServer = drpcserver.NewWithOptions(mux, drpcserver.Options{
+		Manager: drpcsdk.DefaultDRPCOptions(nil),
+		Log: func(err error) {
+			if errors.Is(err, context.Canceled) ||
+				errors.Is(err, context.DeadlineExceeded) {
+				return
+			}
+			logger.Debug(context.Background(), "drpc server error", slog.Error(err))
+		},
+	})
+
+	listener, err := createSocket(server.path)
+	if err != nil {
+		return nil, xerrors.Errorf("create socket: %w", err)
+	}
+
+	server.listener = listener
+
+	// This context is canceled by server.Close().
+	// canceling it will close all connections.
+	server.ctx, server.cancel = context.WithCancel(context.Background())
+
+	server.logger.Info(server.ctx, "agent socket server started", slog.F("path", server.path))
+
+	server.wg.Add(1)
+	go func() {
+		defer server.wg.Done()
+		server.acceptConnections()
+	}()
+
+	return server, nil
+}
+
+// Close stops the server and cleans up resources.
+func (s *Server) Close() error {
+	s.mu.Lock()
+
+	if s.listener == nil {
+		s.mu.Unlock()
+		return nil
+	}
+
+	s.logger.Info(s.ctx, "stopping agent socket server")
+
+	s.cancel()
+
+	if err := s.listener.Close(); err != nil {
+		s.logger.Warn(s.ctx, "error closing socket listener", slog.Error(err))
+	}
+
+	s.listener = nil
+
+	s.mu.Unlock()
+
+	// Wait for all connections to finish
+	s.wg.Wait()
+
+	if err := cleanupSocket(s.path); err != nil {
+		s.logger.Warn(s.ctx, "error cleaning up socket file", slog.Error(err))
+	}
+
+	s.logger.Info(s.ctx, "agent socket server stopped")
+
+	return nil
+}
+
+func (s *Server) acceptConnections() {
+	// In an edge case, Close() might race with acceptConnections() and set s.listener to nil.
+	// Therefore, we grab a copy of the listener under a lock. We might still get a nil listener,
+	// but then we know close has already run and we can return early.
+	s.mu.Lock()
+	listener := s.listener
+	s.mu.Unlock()
+	if listener == nil {
+		return
+	}
+
+	err := s.drpcServer.Serve(s.ctx, listener)
+	if err != nil {
+		s.logger.Warn(s.ctx, "error serving drpc server", slog.Error(err))
+	}
+}

agent/agentsocket/server_test.go

@@ -0,0 +1,138 @@
+package agentsocket_test
+
+import (
+	"context"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/google/uuid"
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/require"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent"
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/agenttest"
+	agentproto "github.com/coder/coder/v2/agent/proto"
+	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/tailnet"
+	"github.com/coder/coder/v2/tailnet/tailnettest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestServer(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS == "windows" {
+		t.Skip("agentsocket is not supported on Windows")
+	}
+
+	t.Run("StartStop", func(t *testing.T) {
+		t.Parallel()
+
+		socketPath := filepath.Join(t.TempDir(), "test.sock")
+		logger := slog.Make().Leveled(slog.LevelDebug)
+		server, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
+		require.NoError(t, err)
+		require.NoError(t, server.Close())
+	})
+
+	t.Run("AlreadyStarted", func(t *testing.T) {
+		t.Parallel()
+
+		socketPath := filepath.Join(t.TempDir(), "test.sock")
+		logger := slog.Make().Leveled(slog.LevelDebug)
+		server1, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
+		require.NoError(t, err)
+		defer server1.Close()
+		_, err = agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
+		require.ErrorContains(t, err, "create socket")
+	})
+
+	t.Run("AutoSocketPath", func(t *testing.T) {
+		t.Parallel()
+
+		socketPath := filepath.Join(t.TempDir(), "test.sock")
+		logger := slog.Make().Leveled(slog.LevelDebug)
+		server, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
+		require.NoError(t, err)
+		require.NoError(t, server.Close())
+	})
+}
+
+func TestServerWindowsNotSupported(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS != "windows" {
+		t.Skip("this test only runs on Windows")
+	}
+
+	t.Run("NewServer", func(t *testing.T) {
+		t.Parallel()
+
+		socketPath := filepath.Join(t.TempDir(), "test.sock")
+		logger := slog.Make().Leveled(slog.LevelDebug)
+		_, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
+		require.ErrorContains(t, err, "agentsocket is not supported on Windows")
+	})
+
+	t.Run("NewClient", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := agentsocket.NewClient(context.Background(), agentsocket.WithPath("test.sock"))
+		require.ErrorContains(t, err, "agentsocket is not supported on Windows")
+	})
+}
+
+func TestAgentInitializesOnWindowsWithoutSocketServer(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS != "windows" {
+		t.Skip("this test only runs on Windows")
+	}
+
+	ctx := testutil.Context(t, testutil.WaitShort)
+	logger := testutil.Logger(t).Named("agent")
+
+	derpMap, _ := tailnettest.RunDERPAndSTUN(t)
+
+	coordinator := tailnet.NewCoordinator(logger)
+	t.Cleanup(func() {
+		_ = coordinator.Close()
+	})
+
+	statsCh := make(chan *agentproto.Stats, 50)
+	agentID := uuid.New()
+	manifest := agentsdk.Manifest{
+		AgentID:       agentID,
+		AgentName:     "test-agent",
+		WorkspaceName: "test-workspace",
+		OwnerName:     "test-user",
+		WorkspaceID:   uuid.New(),
+		DERPMap:       derpMap,
+	}
+
+	client := agenttest.NewClient(t, logger.Named("agenttest"), agentID, manifest, statsCh, coordinator)
+	t.Cleanup(client.Close)
+
+	options := agent.Options{
+		Client:                 client,
+		Filesystem:             afero.NewMemMapFs(),
+		Logger:                 logger.Named("agent"),
+		ReconnectingPTYTimeout: testutil.WaitShort,
+		EnvironmentVariables:   map[string]string{},
+		SocketPath:             "",
+	}
+
+	agnt := agent.New(options)
+	t.Cleanup(func() {
+		_ = agnt.Close()
+	})
+
+	startup := testutil.TryReceive(ctx, t, client.GetStartup())
+	require.NotNil(t, startup, "agent should send startup message")
+
+	err := agnt.Close()
+	require.NoError(t, err, "agent should close cleanly")
+}

agent/agentsocket/service.go

@@ -0,0 +1,152 @@
+package agentsocket
+
+import (
+	"context"
+	"errors"
+
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentsocket/proto"
+	"github.com/coder/coder/v2/agent/unit"
+)
+
+var _ proto.DRPCAgentSocketServer = (*DRPCAgentSocketService)(nil)
+
+var ErrUnitManagerNotAvailable = xerrors.New("unit manager not available")
+
+// DRPCAgentSocketService implements the DRPC agent socket service.
+type DRPCAgentSocketService struct {
+	unitManager *unit.Manager
+	logger      slog.Logger
+}
+
+// Ping responds to a ping request to check if the service is alive.
+func (*DRPCAgentSocketService) Ping(_ context.Context, _ *proto.PingRequest) (*proto.PingResponse, error) {
+	return &proto.PingResponse{}, nil
+}
+
+// SyncStart starts a unit in the dependency graph.
+func (s *DRPCAgentSocketService) SyncStart(_ context.Context, req *proto.SyncStartRequest) (*proto.SyncStartResponse, error) {
+	if s.unitManager == nil {
+		return nil, xerrors.Errorf("SyncStart: %w", ErrUnitManagerNotAvailable)
+	}
+
+	unitID := unit.ID(req.Unit)
+
+	if err := s.unitManager.Register(unitID); err != nil {
+		if !errors.Is(err, unit.ErrUnitAlreadyRegistered) {
+			return nil, xerrors.Errorf("SyncStart: %w", err)
+		}
+	}
+
+	isReady, err := s.unitManager.IsReady(unitID)
+	if err != nil {
+		return nil, xerrors.Errorf("cannot check readiness: %w", err)
+	}
+	if !isReady {
+		return nil, xerrors.Errorf("cannot start unit %q: unit not ready", req.Unit)
+	}
+
+	err = s.unitManager.UpdateStatus(unitID, unit.StatusStarted)
+	if err != nil {
+		return nil, xerrors.Errorf("cannot start unit %q: %w", req.Unit, err)
+	}
+
+	return &proto.SyncStartResponse{}, nil
+}
+
+// SyncWant declares a dependency between units.
+func (s *DRPCAgentSocketService) SyncWant(_ context.Context, req *proto.SyncWantRequest) (*proto.SyncWantResponse, error) {
+	if s.unitManager == nil {
+		return nil, xerrors.Errorf("cannot add dependency: %w", ErrUnitManagerNotAvailable)
+	}
+
+	unitID := unit.ID(req.Unit)
+	dependsOnID := unit.ID(req.DependsOn)
+
+	if err := s.unitManager.Register(unitID); err != nil && !errors.Is(err, unit.ErrUnitAlreadyRegistered) {
+		return nil, xerrors.Errorf("cannot add dependency: %w", err)
+	}
+
+	if err := s.unitManager.AddDependency(unitID, dependsOnID, unit.StatusComplete); err != nil {
+		return nil, xerrors.Errorf("cannot add dependency: %w", err)
+	}
+
+	return &proto.SyncWantResponse{}, nil
+}
+
+// SyncComplete marks a unit as complete in the dependency graph.
+func (s *DRPCAgentSocketService) SyncComplete(_ context.Context, req *proto.SyncCompleteRequest) (*proto.SyncCompleteResponse, error) {
+	if s.unitManager == nil {
+		return nil, xerrors.Errorf("cannot complete unit: %w", ErrUnitManagerNotAvailable)
+	}
+
+	unitID := unit.ID(req.Unit)
+
+	if err := s.unitManager.UpdateStatus(unitID, unit.StatusComplete); err != nil {
+		return nil, xerrors.Errorf("cannot complete unit %q: %w", req.Unit, err)
+	}
+
+	return &proto.SyncCompleteResponse{}, nil
+}
+
+// SyncReady checks whether a unit is ready to be started. That is, all dependencies are satisfied.
+func (s *DRPCAgentSocketService) SyncReady(_ context.Context, req *proto.SyncReadyRequest) (*proto.SyncReadyResponse, error) {
+	if s.unitManager == nil {
+		return nil, xerrors.Errorf("cannot check readiness: %w", ErrUnitManagerNotAvailable)
+	}
+
+	unitID := unit.ID(req.Unit)
+	isReady, err := s.unitManager.IsReady(unitID)
+	if err != nil {
+		return nil, xerrors.Errorf("cannot check readiness: %w", err)
+	}
+
+	return &proto.SyncReadyResponse{
+		Ready: isReady,
+	}, nil
+}
+
+// SyncStatus gets the status of a unit and lists its dependencies.
+func (s *DRPCAgentSocketService) SyncStatus(_ context.Context, req *proto.SyncStatusRequest) (*proto.SyncStatusResponse, error) {
+	if s.unitManager == nil {
+		return nil, xerrors.Errorf("cannot get status for unit %q: %w", req.Unit, ErrUnitManagerNotAvailable)
+	}
+
+	unitID := unit.ID(req.Unit)
+
+	isReady, err := s.unitManager.IsReady(unitID)
+	if err != nil {
+		return nil, xerrors.Errorf("cannot check readiness: %w", err)
+	}
+
+	dependencies, err := s.unitManager.GetAllDependencies(unitID)
+	switch {
+	case errors.Is(err, unit.ErrUnitNotFound):
+		dependencies = []unit.Dependency{}
+	case err != nil:
+		return nil, xerrors.Errorf("cannot get dependencies: %w", err)
+	}
+
+	var depInfos []*proto.DependencyInfo
+	for _, dep := range dependencies {
+		depInfos = append(depInfos, &proto.DependencyInfo{
+			Unit:           string(dep.Unit),
+			DependsOn:      string(dep.DependsOn),
+			RequiredStatus: string(dep.RequiredStatus),
+			CurrentStatus:  string(dep.CurrentStatus),
+			IsSatisfied:    dep.IsSatisfied,
+		})
+	}
+
+	u, err := s.unitManager.Unit(unitID)
+	if err != nil {
+		return nil, xerrors.Errorf("cannot get status for unit %q: %w", req.Unit, err)
+	}
+	return &proto.SyncStatusResponse{
+		Status:       string(u.Status()),
+		IsReady:      isReady,
+		Dependencies: depInfos,
+	}, nil
+}

agent/agentsocket/service_test.go

@@ -0,0 +1,389 @@
+package agentsocket_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// tempDirUnixSocket returns a temporary directory that can safely hold unix
+// sockets (probably).
+//
+// During tests on darwin we hit the max path length limit for unix sockets
+// pretty easily in the default location, so this function uses /tmp instead to
+// get shorter paths. To keep paths short, we use a hash of the test name
+// instead of the full test name.
+func tempDirUnixSocket(t *testing.T) string {
+	t.Helper()
+	if runtime.GOOS == "darwin" {
+		// Use a short hash of the test name to keep the path under 104 chars
+		hash := sha256.Sum256([]byte(t.Name()))
+		hashStr := hex.EncodeToString(hash[:])[:8] // Use first 8 chars of hash
+		dir, err := os.MkdirTemp("/tmp", fmt.Sprintf("c-%s-", hashStr))
+		require.NoError(t, err, "create temp dir for unix socket test")
+		t.Cleanup(func() {
+			err := os.RemoveAll(dir)
+			assert.NoError(t, err, "remove temp dir", dir)
+		})
+		return dir
+	}
+	return t.TempDir()
+}
+
+// newSocketClient creates a DRPC client connected to the Unix socket at the given path.
+func newSocketClient(ctx context.Context, t *testing.T, socketPath string) *agentsocket.Client {
+	t.Helper()
+
+	client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(socketPath))
+	t.Cleanup(func() {
+		_ = client.Close()
+	})
+	require.NoError(t, err)
+
+	return client
+}
+
+func TestDRPCAgentSocketService(t *testing.T) {
+	t.Parallel()
+
+	if runtime.GOOS == "windows" {
+		t.Skip("agentsocket is not supported on Windows")
+	}
+
+	t.Run("Ping", func(t *testing.T) {
+		t.Parallel()
+
+		socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+		ctx := testutil.Context(t, testutil.WaitShort)
+		server, err := agentsocket.NewServer(
+			slog.Make().Leveled(slog.LevelDebug),
+			agentsocket.WithPath(socketPath),
+		)
+		require.NoError(t, err)
+		defer server.Close()
+
+		client := newSocketClient(ctx, t, socketPath)
+
+		err = client.Ping(ctx)
+		require.NoError(t, err)
+	})
+
+	t.Run("SyncStart", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("NewUnit", func(t *testing.T) {
+			t.Parallel()
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+		})
+
+		t.Run("UnitAlreadyStarted", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// First Start
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+
+			// Second Start
+			err = client.SyncStart(ctx, "test-unit")
+			require.ErrorContains(t, err, unit.ErrSameStatusAlreadySet.Error())
+
+			status, err = client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+		})
+
+		t.Run("UnitAlreadyCompleted", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// First start
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+
+			// Complete the unit
+			err = client.SyncComplete(ctx, "test-unit")
+			require.NoError(t, err)
+
+			status, err = client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusComplete, status.Status)
+
+			// Second start
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+
+			status, err = client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+		})
+
+		t.Run("UnitNotReady", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
+			require.NoError(t, err)
+
+			err = client.SyncStart(ctx, "test-unit")
+			require.ErrorContains(t, err, "unit not ready")
+
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusPending, status.Status)
+			require.False(t, status.IsReady)
+		})
+	})
+
+	t.Run("SyncWant", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("NewUnits", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// If dependency units are not registered, they are registered automatically
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
+			require.NoError(t, err)
+
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Len(t, status.Dependencies, 1)
+			require.Equal(t, unit.ID("dependency-unit"), status.Dependencies[0].DependsOn)
+			require.Equal(t, unit.StatusComplete, status.Dependencies[0].RequiredStatus)
+		})
+
+		t.Run("DependencyAlreadyRegistered", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// Start the dependency unit
+			err = client.SyncStart(ctx, "dependency-unit")
+			require.NoError(t, err)
+
+			status, err := client.SyncStatus(ctx, "dependency-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+
+			// Add the dependency after the dependency unit has already started
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
+
+			// Dependencies can be added even if the dependency unit has already started
+			require.NoError(t, err)
+
+			// The dependency is now reflected in the test unit's status
+			status, err = client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.ID("dependency-unit"), status.Dependencies[0].DependsOn)
+			require.Equal(t, unit.StatusComplete, status.Dependencies[0].RequiredStatus)
+		})
+
+		t.Run("DependencyAddedAfterDependentStarted", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// Start the dependent unit
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+
+			status, err := client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.StatusStarted, status.Status)
+
+			// Add the dependency after the dependency unit has already started
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
+
+			// Dependencies can be added even if the dependent unit has already started.
+			// The dependency applies the next time a unit is started. The current status is not updated.
+			// This is to allow flexible dependency management. It does mean that users of this API should
+			// take care to add dependencies before they start their dependent units.
+			require.NoError(t, err)
+
+			// The dependency is now reflected in the test unit's status
+			status, err = client.SyncStatus(ctx, "test-unit")
+			require.NoError(t, err)
+			require.Equal(t, unit.ID("dependency-unit"), status.Dependencies[0].DependsOn)
+			require.Equal(t, unit.StatusComplete, status.Dependencies[0].RequiredStatus)
+		})
+	})
+
+	t.Run("SyncReady", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("UnregisteredUnit", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			ready, err := client.SyncReady(ctx, "unregistered-unit")
+			require.NoError(t, err)
+			require.True(t, ready)
+		})
+
+		t.Run("UnitNotReady", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// Register a unit with an unsatisfied dependency
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
+			require.NoError(t, err)
+
+			// Check readiness - should be false because dependency is not satisfied
+			ready, err := client.SyncReady(ctx, "test-unit")
+			require.NoError(t, err)
+			require.False(t, ready)
+		})
+
+		t.Run("UnitReady", func(t *testing.T) {
+			t.Parallel()
+
+			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+			ctx := testutil.Context(t, testutil.WaitShort)
+			server, err := agentsocket.NewServer(
+				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
+			)
+			require.NoError(t, err)
+			defer server.Close()
+
+			client := newSocketClient(ctx, t, socketPath)
+
+			// Register a unit with no dependencies - should be ready immediately
+			err = client.SyncStart(ctx, "test-unit")
+			require.NoError(t, err)
+
+			// Check readiness - should be true
+			ready, err := client.SyncReady(ctx, "test-unit")
+			require.NoError(t, err)
+			require.True(t, ready)
+
+			// Also test a unit with satisfied dependencies
+			err = client.SyncWant(ctx, "dependent-unit", "test-unit")
+			require.NoError(t, err)
+
+			// Complete the dependency
+			err = client.SyncComplete(ctx, "test-unit")
+			require.NoError(t, err)
+
+			// Now dependent-unit should be ready
+			ready, err = client.SyncReady(ctx, "dependent-unit")
+			require.NoError(t, err)
+			require.True(t, ready)
+		})
+	})
+}

agent/agentsocket/socket_unix.go

@@ -0,0 +1,73 @@
+//go:build !windows
+
+package agentsocket
+
+import (
+	"context"
+	"net"
+	"os"
+	"path/filepath"
+	"time"
+
+	"golang.org/x/xerrors"
+)
+
+const defaultSocketPath = "/tmp/coder-agent.sock"
+
+func createSocket(path string) (net.Listener, error) {
+	if path == "" {
+		path = defaultSocketPath
+	}
+
+	if !isSocketAvailable(path) {
+		return nil, xerrors.Errorf("socket path %s is not available", path)
+	}
+
+	if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+		return nil, xerrors.Errorf("remove existing socket: %w", err)
+	}
+
+	parentDir := filepath.Dir(path)
+	if err := os.MkdirAll(parentDir, 0o700); err != nil {
+		return nil, xerrors.Errorf("create socket directory: %w", err)
+	}
+
+	listener, err := net.Listen("unix", path)
+	if err != nil {
+		return nil, xerrors.Errorf("listen on unix socket: %w", err)
+	}
+
+	if err := os.Chmod(path, 0o600); err != nil {
+		_ = listener.Close()
+		return nil, xerrors.Errorf("set socket permissions: %w", err)
+	}
+	return listener, nil
+}
+
+func cleanupSocket(path string) error {
+	return os.Remove(path)
+}
+
+func isSocketAvailable(path string) bool {
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		return true
+	}
+
+	// Try to connect to see if it's actually listening.
+	dialer := net.Dialer{Timeout: 10 * time.Second}
+	conn, err := dialer.Dial("unix", path)
+	if err != nil {
+		return true
+	}
+	_ = conn.Close()
+	return false
+}
+
+func dialSocket(ctx context.Context, path string) (net.Conn, error) {
+	if path == "" {
+		path = defaultSocketPath
+	}
+
+	dialer := net.Dialer{}
+	return dialer.DialContext(ctx, "unix", path)
+}

agent/agentsocket/socket_windows.go

@@ -0,0 +1,22 @@
+//go:build windows
+
+package agentsocket
+
+import (
+	"context"
+	"net"
+
+	"golang.org/x/xerrors"
+)
+
+func createSocket(_ string) (net.Listener, error) {
+	return nil, xerrors.New("agentsocket is not supported on Windows")
+}
+
+func cleanupSocket(_ string) error {
+	return nil
+}
+
+func dialSocket(_ context.Context, _ string) (net.Conn, error) {
+	return nil, xerrors.New("agentsocket is not supported on Windows")
+}

agent/agenttest/agent.go

@@ -1,7 +1,6 @@
 package agenttest
 
 import (
-	"context"
 	"net/url"
 	"testing"
 
@@ -31,18 +30,11 @@ func New(t testing.TB, coderURL *url.URL, agentToken string, opts ...func(*agent
 	}
 
 	if o.Client == nil {
-		agentClient := agentsdk.New(coderURL)
-		agentClient.SetSessionToken(agentToken)
+		agentClient := agentsdk.New(coderURL, agentsdk.WithFixedToken(agentToken))
 		agentClient.SDK.SetLogger(log)
 		o.Client = agentClient
 	}
 
-	if o.ExchangeToken == nil {
-		o.ExchangeToken = func(_ context.Context) (string, error) {
-			return agentToken, nil
-		}
-	}
-
 	if o.LogDir == "" {
 		o.LogDir = t.TempDir()
 	}

agent/agenttest/client.go

@@ -3,6 +3,7 @@ package agenttest
 import (
 	"context"
 	"io"
+	"net/http"
 	"slices"
 	"sync"
 	"sync/atomic"
@@ -28,6 +29,7 @@ import (
 	"github.com/coder/coder/v2/tailnet"
 	"github.com/coder/coder/v2/tailnet/proto"
 	"github.com/coder/coder/v2/testutil"
+	"github.com/coder/websocket"
 )
 
 const statsInterval = 500 * time.Millisecond
@@ -86,10 +88,34 @@ type Client struct {
 	fakeAgentAPI       *FakeAgentAPI
 	LastWorkspaceAgent func()
 
-	mu             sync.Mutex // Protects following.
-	logs           []agentsdk.Log
-	derpMapUpdates chan *tailcfg.DERPMap
-	derpMapOnce    sync.Once
+	mu                sync.Mutex // Protects following.
+	logs              []agentsdk.Log
+	derpMapUpdates    chan *tailcfg.DERPMap
+	derpMapOnce       sync.Once
+	refreshTokenCalls int
+}
+
+func (*Client) AsRequestOption() codersdk.RequestOption {
+	return func(_ *http.Request) {}
+}
+
+func (*Client) SetDialOption(*websocket.DialOptions) {}
+
+func (*Client) GetSessionToken() string {
+	return "agenttest-token"
+}
+
+func (c *Client) RefreshToken(context.Context) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.refreshTokenCalls++
+	return nil
+}
+
+func (c *Client) GetNumRefreshTokenCalls() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.refreshTokenCalls
 }
 
 func (*Client) RewriteDERPMap(*tailcfg.DERPMap) {}

agent/api.go

@@ -2,41 +2,31 @@ package agent
 
 import (
 	"net/http"
-	"sync"
-	"time"
 
 	"github.com/go-chi/chi/v5"
 	"github.com/google/uuid"
 
 	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/coderd/httpmw/loggermw"
+	"github.com/coder/coder/v2/coderd/tracing"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+	"github.com/coder/coder/v2/httpmw"
 )
 
 func (a *agent) apiHandler() http.Handler {
 	r := chi.NewRouter()
+	r.Use(
+		httpmw.Recover(a.logger),
+		tracing.StatusWriterMiddleware,
+		loggermw.Logger(a.logger),
+	)
 	r.Get("/", func(rw http.ResponseWriter, r *http.Request) {
 		httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.Response{
 			Message: "Hello from the agent!",
 		})
 	})
 
-	// Make a copy to ensure the map is not modified after the handler is
-	// created.
-	cpy := make(map[int]string)
-	for k, b := range a.ignorePorts {
-		cpy[k] = b
-	}
-
-	cacheDuration := 1 * time.Second
-	if a.portCacheDuration > 0 {
-		cacheDuration = a.portCacheDuration
-	}
-
-	lp := &listeningPortsHandler{
-		ignorePorts:   cpy,
-		cacheDuration: cacheDuration,
-	}
-
 	if a.devcontainers {
 		r.Mount("/api/v0/containers", a.containerAPI.Routes())
 	} else if manifest := a.manifest.Load(); manifest != nil && manifest.ParentID != uuid.Nil {
@@ -57,9 +47,12 @@ func (a *agent) apiHandler() http.Handler {
 
 	promHandler := PrometheusMetricsHandler(a.prometheusRegistry, a.logger)
 
-	r.Get("/api/v0/listening-ports", lp.handler)
+	r.Get("/api/v0/listening-ports", a.listeningPortsHandler.handler)
 	r.Get("/api/v0/netcheck", a.HandleNetcheck)
 	r.Post("/api/v0/list-directory", a.HandleLS)
+	r.Get("/api/v0/read-file", a.HandleReadFile)
+	r.Post("/api/v0/write-file", a.HandleWriteFile)
+	r.Post("/api/v0/edit-files", a.HandleEditFiles)
 	r.Get("/debug/logs", a.HandleHTTPDebugLogs)
 	r.Get("/debug/magicsock", a.HandleHTTPDebugMagicsock)
 	r.Get("/debug/magicsock/debug-logging/{state}", a.HandleHTTPMagicsockDebugLoggingState)
@@ -69,22 +62,21 @@ func (a *agent) apiHandler() http.Handler {
 	return r
 }
 
-type listeningPortsHandler struct {
-	ignorePorts   map[int]string
-	cacheDuration time.Duration
+type ListeningPortsGetter interface {
+	GetListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error)
+}
 
-	//nolint: unused  // used on some but not all platforms
-	mut sync.Mutex
-	//nolint: unused  // used on some but not all platforms
-	ports []codersdk.WorkspaceAgentListeningPort
-	//nolint: unused  // used on some but not all platforms
-	mtime time.Time
+type listeningPortsHandler struct {
+	// In production code, this is set to an osListeningPortsGetter, but it can be overridden for
+	// testing.
+	getter      ListeningPortsGetter
+	ignorePorts map[int]string
 }
 
 // handler returns a list of listening ports. This is tested by coderd's
 // TestWorkspaceAgentListeningPorts test.
 func (lp *listeningPortsHandler) handler(rw http.ResponseWriter, r *http.Request) {
-	ports, err := lp.getListeningPorts()
+	ports, err := lp.getter.GetListeningPorts()
 	if err != nil {
 		httpapi.Write(r.Context(), rw, http.StatusInternalServerError, codersdk.Response{
 			Message: "Could not scan for listening ports.",
@@ -93,7 +85,20 @@ func (lp *listeningPortsHandler) handler(rw http.ResponseWriter, r *http.Request
 		return
 	}
 
+	filteredPorts := make([]codersdk.WorkspaceAgentListeningPort, 0, len(ports))
+	for _, port := range ports {
+		if port.Port < workspacesdk.AgentMinimumListeningPort {
+			continue
+		}
+
+		// Ignore ports that we've been told to ignore.
+		if _, ok := lp.ignorePorts[int(port.Port)]; ok {
+			continue
+		}
+		filteredPorts = append(filteredPorts, port)
+	}
+
 	httpapi.Write(r.Context(), rw, http.StatusOK, codersdk.WorkspaceAgentListeningPortsResponse{
-		Ports: ports,
+		Ports: filteredPorts,
 	})
 }

agent/apphealth.go

@@ -63,6 +63,7 @@ func NewAppHealthReporterWithClock(
 		// run a ticker for each app health check.
 		var mu sync.RWMutex
 		failures := make(map[uuid.UUID]int, 0)
+		client := &http.Client{}
 		for _, nextApp := range apps {
 			if !shouldStartTicker(nextApp) {
 				continue
@@ -91,7 +92,7 @@ func NewAppHealthReporterWithClock(
 						if err != nil {
 							return err
 						}
-						res, err := http.DefaultClient.Do(req)
+						res, err := client.Do(req)
 						if err != nil {
 							return err
 						}

agent/files.go

@@ -0,0 +1,275 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"syscall"
+
+	"github.com/icholy/replace"
+	"github.com/spf13/afero"
+	"golang.org/x/text/transform"
+	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+type HTTPResponseCode = int
+
+func (a *agent) HandleReadFile(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	query := r.URL.Query()
+	parser := httpapi.NewQueryParamParser().RequiredNotEmpty("path")
+	path := parser.String(query, "", "path")
+	offset := parser.PositiveInt64(query, 0, "offset")
+	limit := parser.PositiveInt64(query, 0, "limit")
+	parser.ErrorExcessParams(query)
+	if len(parser.Errors) > 0 {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message:     "Query parameters have invalid values.",
+			Validations: parser.Errors,
+		})
+		return
+	}
+
+	status, err := a.streamFile(ctx, rw, path, offset, limit)
+	if err != nil {
+		httpapi.Write(ctx, rw, status, codersdk.Response{
+			Message: err.Error(),
+		})
+		return
+	}
+}
+
+func (a *agent) streamFile(ctx context.Context, rw http.ResponseWriter, path string, offset, limit int64) (HTTPResponseCode, error) {
+	if !filepath.IsAbs(path) {
+		return http.StatusBadRequest, xerrors.Errorf("file path must be absolute: %q", path)
+	}
+
+	f, err := a.filesystem.Open(path)
+	if err != nil {
+		status := http.StatusInternalServerError
+		switch {
+		case errors.Is(err, os.ErrNotExist):
+			status = http.StatusNotFound
+		case errors.Is(err, os.ErrPermission):
+			status = http.StatusForbidden
+		}
+		return status, err
+	}
+	defer f.Close()
+
+	stat, err := f.Stat()
+	if err != nil {
+		return http.StatusInternalServerError, err
+	}
+
+	if stat.IsDir() {
+		return http.StatusBadRequest, xerrors.Errorf("open %s: not a file", path)
+	}
+
+	size := stat.Size()
+	if limit == 0 {
+		limit = size
+	}
+	bytesRemaining := max(size-offset, 0)
+	bytesToRead := min(bytesRemaining, limit)
+
+	// Relying on just the file name for the mime type for now.
+	mimeType := mime.TypeByExtension(filepath.Ext(path))
+	if mimeType == "" {
+		mimeType = "application/octet-stream"
+	}
+	rw.Header().Set("Content-Type", mimeType)
+	rw.Header().Set("Content-Length", strconv.FormatInt(bytesToRead, 10))
+	rw.WriteHeader(http.StatusOK)
+
+	reader := io.NewSectionReader(f, offset, bytesToRead)
+	_, err = io.Copy(rw, reader)
+	if err != nil && !errors.Is(err, io.EOF) && ctx.Err() == nil {
+		a.logger.Error(ctx, "workspace agent read file", slog.Error(err))
+	}
+
+	return 0, nil
+}
+
+func (a *agent) HandleWriteFile(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	query := r.URL.Query()
+	parser := httpapi.NewQueryParamParser().RequiredNotEmpty("path")
+	path := parser.String(query, "", "path")
+	parser.ErrorExcessParams(query)
+	if len(parser.Errors) > 0 {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message:     "Query parameters have invalid values.",
+			Validations: parser.Errors,
+		})
+		return
+	}
+
+	status, err := a.writeFile(ctx, r, path)
+	if err != nil {
+		httpapi.Write(ctx, rw, status, codersdk.Response{
+			Message: err.Error(),
+		})
+		return
+	}
+
+	httpapi.Write(ctx, rw, http.StatusOK, codersdk.Response{
+		Message: fmt.Sprintf("Successfully wrote to %q", path),
+	})
+}
+
+func (a *agent) writeFile(ctx context.Context, r *http.Request, path string) (HTTPResponseCode, error) {
+	if !filepath.IsAbs(path) {
+		return http.StatusBadRequest, xerrors.Errorf("file path must be absolute: %q", path)
+	}
+
+	dir := filepath.Dir(path)
+	err := a.filesystem.MkdirAll(dir, 0o755)
+	if err != nil {
+		status := http.StatusInternalServerError
+		switch {
+		case errors.Is(err, os.ErrPermission):
+			status = http.StatusForbidden
+		case errors.Is(err, syscall.ENOTDIR):
+			status = http.StatusBadRequest
+		}
+		return status, err
+	}
+
+	f, err := a.filesystem.Create(path)
+	if err != nil {
+		status := http.StatusInternalServerError
+		switch {
+		case errors.Is(err, os.ErrPermission):
+			status = http.StatusForbidden
+		case errors.Is(err, syscall.EISDIR):
+			status = http.StatusBadRequest
+		}
+		return status, err
+	}
+	defer f.Close()
+
+	_, err = io.Copy(f, r.Body)
+	if err != nil && !errors.Is(err, io.EOF) && ctx.Err() == nil {
+		a.logger.Error(ctx, "workspace agent write file", slog.Error(err))
+	}
+
+	return 0, nil
+}
+
+func (a *agent) HandleEditFiles(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	var req workspacesdk.FileEditRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	if len(req.Files) == 0 {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: "must specify at least one file",
+		})
+		return
+	}
+
+	var combinedErr error
+	status := http.StatusOK
+	for _, edit := range req.Files {
+		s, err := a.editFile(r.Context(), edit.Path, edit.Edits)
+		// Keep the highest response status, so 500 will be preferred over 400, etc.
+		if s > status {
+			status = s
+		}
+		if err != nil {
+			combinedErr = errors.Join(combinedErr, err)
+		}
+	}
+
+	if combinedErr != nil {
+		httpapi.Write(ctx, rw, status, codersdk.Response{
+			Message: combinedErr.Error(),
+		})
+		return
+	}
+
+	httpapi.Write(ctx, rw, http.StatusOK, codersdk.Response{
+		Message: "Successfully edited file(s)",
+	})
+}
+
+func (a *agent) editFile(ctx context.Context, path string, edits []workspacesdk.FileEdit) (int, error) {
+	if path == "" {
+		return http.StatusBadRequest, xerrors.New("\"path\" is required")
+	}
+
+	if !filepath.IsAbs(path) {
+		return http.StatusBadRequest, xerrors.Errorf("file path must be absolute: %q", path)
+	}
+
+	if len(edits) == 0 {
+		return http.StatusBadRequest, xerrors.New("must specify at least one edit")
+	}
+
+	f, err := a.filesystem.Open(path)
+	if err != nil {
+		status := http.StatusInternalServerError
+		switch {
+		case errors.Is(err, os.ErrNotExist):
+			status = http.StatusNotFound
+		case errors.Is(err, os.ErrPermission):
+			status = http.StatusForbidden
+		}
+		return status, err
+	}
+	defer f.Close()
+
+	stat, err := f.Stat()
+	if err != nil {
+		return http.StatusInternalServerError, err
+	}
+
+	if stat.IsDir() {
+		return http.StatusBadRequest, xerrors.Errorf("open %s: not a file", path)
+	}
+
+	transforms := make([]transform.Transformer, len(edits))
+	for i, edit := range edits {
+		transforms[i] = replace.String(edit.Search, edit.Replace)
+	}
+
+	// Create an adjacent file to ensure it will be on the same device and can be
+	// moved atomically.
+	tmpfile, err := afero.TempFile(a.filesystem, filepath.Dir(path), filepath.Base(path))
+	if err != nil {
+		return http.StatusInternalServerError, err
+	}
+	defer tmpfile.Close()
+
+	_, err = io.Copy(tmpfile, replace.Chain(f, transforms...))
+	if err != nil {
+		if rerr := a.filesystem.Remove(tmpfile.Name()); rerr != nil {
+			a.logger.Warn(ctx, "unable to clean up temp file", slog.Error(rerr))
+		}
+		return http.StatusInternalServerError, xerrors.Errorf("edit %s: %w", path, err)
+	}
+
+	err = a.filesystem.Rename(tmpfile.Name(), path)
+	if err != nil {
+		return http.StatusInternalServerError, err
+	}
+
+	return 0, nil
+}

agent/files_test.go

@@ -0,0 +1,722 @@
+package agent_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"syscall"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent"
+	"github.com/coder/coder/v2/agent/agenttest"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/codersdk/agentsdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+	"github.com/coder/coder/v2/testutil"
+)
+
+type testFs struct {
+	afero.Fs
+	// intercept can return an error for testing when a call fails.
+	intercept func(call, file string) error
+}
+
+func newTestFs(base afero.Fs, intercept func(call, file string) error) *testFs {
+	return &testFs{
+		Fs:        base,
+		intercept: intercept,
+	}
+}
+
+func (fs *testFs) Open(name string) (afero.File, error) {
+	if err := fs.intercept("open", name); err != nil {
+		return nil, err
+	}
+	return fs.Fs.Open(name)
+}
+
+func (fs *testFs) Create(name string) (afero.File, error) {
+	if err := fs.intercept("create", name); err != nil {
+		return nil, err
+	}
+	// Unlike os, afero lets you create files where directories already exist and
+	// lets you nest them underneath files, somehow.
+	stat, err := fs.Fs.Stat(name)
+	if err == nil && stat.IsDir() {
+		return nil, &os.PathError{
+			Op:   "open",
+			Path: name,
+			Err:  syscall.EISDIR,
+		}
+	}
+	stat, err = fs.Fs.Stat(filepath.Dir(name))
+	if err == nil && !stat.IsDir() {
+		return nil, &os.PathError{
+			Op:   "open",
+			Path: name,
+			Err:  syscall.ENOTDIR,
+		}
+	}
+	return fs.Fs.Create(name)
+}
+
+func (fs *testFs) MkdirAll(name string, mode os.FileMode) error {
+	if err := fs.intercept("mkdirall", name); err != nil {
+		return err
+	}
+	// Unlike os, afero lets you create directories where files already exist and
+	// lets you nest them underneath files somehow.
+	stat, err := fs.Fs.Stat(filepath.Dir(name))
+	if err == nil && !stat.IsDir() {
+		return &os.PathError{
+			Op:   "mkdir",
+			Path: name,
+			Err:  syscall.ENOTDIR,
+		}
+	}
+	stat, err = fs.Fs.Stat(name)
+	if err == nil && !stat.IsDir() {
+		return &os.PathError{
+			Op:   "mkdir",
+			Path: name,
+			Err:  syscall.ENOTDIR,
+		}
+	}
+	return fs.Fs.MkdirAll(name, mode)
+}
+
+func (fs *testFs) Rename(oldName, newName string) error {
+	if err := fs.intercept("rename", newName); err != nil {
+		return err
+	}
+	return fs.Fs.Rename(oldName, newName)
+}
+
+func TestReadFile(t *testing.T) {
+	t.Parallel()
+
+	tmpdir := os.TempDir()
+	noPermsFilePath := filepath.Join(tmpdir, "no-perms")
+	//nolint:dogsled
+	conn, _, _, fs, _ := setupAgent(t, agentsdk.Manifest{}, 0, func(_ *agenttest.Client, opts *agent.Options) {
+		opts.Filesystem = newTestFs(opts.Filesystem, func(call, file string) error {
+			if file == noPermsFilePath {
+				return os.ErrPermission
+			}
+			return nil
+		})
+	})
+
+	dirPath := filepath.Join(tmpdir, "a-directory")
+	err := fs.MkdirAll(dirPath, 0o755)
+	require.NoError(t, err)
+
+	filePath := filepath.Join(tmpdir, "file")
+	err = afero.WriteFile(fs, filePath, []byte("content"), 0o644)
+	require.NoError(t, err)
+
+	imagePath := filepath.Join(tmpdir, "file.png")
+	err = afero.WriteFile(fs, imagePath, []byte("not really an image"), 0o644)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name     string
+		path     string
+		limit    int64
+		offset   int64
+		bytes    []byte
+		mimeType string
+		errCode  int
+		error    string
+	}{
+		{
+			name:    "NoPath",
+			path:    "",
+			errCode: http.StatusBadRequest,
+			error:   "\"path\" is required",
+		},
+		{
+			name:    "RelativePathDotSlash",
+			path:    "./relative",
+			errCode: http.StatusBadRequest,
+			error:   "file path must be absolute",
+		},
+		{
+			name:    "RelativePath",
+			path:    "also-relative",
+			errCode: http.StatusBadRequest,
+			error:   "file path must be absolute",
+		},
+		{
+			name:    "NegativeLimit",
+			path:    filePath,
+			limit:   -10,
+			errCode: http.StatusBadRequest,
+			error:   "value is negative",
+		},
+		{
+			name:    "NegativeOffset",
+			path:    filePath,
+			offset:  -10,
+			errCode: http.StatusBadRequest,
+			error:   "value is negative",
+		},
+		{
+			name:    "NonExistent",
+			path:    filepath.Join(tmpdir, "does-not-exist"),
+			errCode: http.StatusNotFound,
+			error:   "file does not exist",
+		},
+		{
+			name:    "IsDir",
+			path:    dirPath,
+			errCode: http.StatusBadRequest,
+			error:   "not a file",
+		},
+		{
+			name:    "NoPermissions",
+			path:    noPermsFilePath,
+			errCode: http.StatusForbidden,
+			error:   "permission denied",
+		},
+		{
+			name:     "Defaults",
+			path:     filePath,
+			bytes:    []byte("content"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Limit1",
+			path:     filePath,
+			limit:    1,
+			bytes:    []byte("c"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Offset1",
+			path:     filePath,
+			offset:   1,
+			bytes:    []byte("ontent"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Limit1Offset2",
+			path:     filePath,
+			limit:    1,
+			offset:   2,
+			bytes:    []byte("n"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Limit7Offset0",
+			path:     filePath,
+			limit:    7,
+			offset:   0,
+			bytes:    []byte("content"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Limit100",
+			path:     filePath,
+			limit:    100,
+			bytes:    []byte("content"),
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Offset7",
+			path:     filePath,
+			offset:   7,
+			bytes:    []byte{},
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "Offset100",
+			path:     filePath,
+			offset:   100,
+			bytes:    []byte{},
+			mimeType: "application/octet-stream",
+		},
+		{
+			name:     "MimeTypePng",
+			path:     imagePath,
+			bytes:    []byte("not really an image"),
+			mimeType: "image/png",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+			defer cancel()
+
+			reader, mimeType, err := conn.ReadFile(ctx, tt.path, tt.offset, tt.limit)
+			if tt.errCode != 0 {
+				require.Error(t, err)
+				cerr := coderdtest.SDKError(t, err)
+				require.Contains(t, cerr.Error(), tt.error)
+				require.Equal(t, tt.errCode, cerr.StatusCode())
+			} else {
+				require.NoError(t, err)
+				defer reader.Close()
+				bytes, err := io.ReadAll(reader)
+				require.NoError(t, err)
+				require.Equal(t, tt.bytes, bytes)
+				require.Equal(t, tt.mimeType, mimeType)
+			}
+		})
+	}
+}
+
+func TestWriteFile(t *testing.T) {
+	t.Parallel()
+
+	tmpdir := os.TempDir()
+	noPermsFilePath := filepath.Join(tmpdir, "no-perms-file")
+	noPermsDirPath := filepath.Join(tmpdir, "no-perms-dir")
+	//nolint:dogsled
+	conn, _, _, fs, _ := setupAgent(t, agentsdk.Manifest{}, 0, func(_ *agenttest.Client, opts *agent.Options) {
+		opts.Filesystem = newTestFs(opts.Filesystem, func(call, file string) error {
+			if file == noPermsFilePath || file == noPermsDirPath {
+				return os.ErrPermission
+			}
+			return nil
+		})
+	})
+
+	dirPath := filepath.Join(tmpdir, "directory")
+	err := fs.MkdirAll(dirPath, 0o755)
+	require.NoError(t, err)
+
+	filePath := filepath.Join(tmpdir, "file")
+	err = afero.WriteFile(fs, filePath, []byte("content"), 0o644)
+	require.NoError(t, err)
+
+	notDirErr := "not a directory"
+	if runtime.GOOS == "windows" {
+		notDirErr = "cannot find the path"
+	}
+
+	tests := []struct {
+		name    string
+		path    string
+		bytes   []byte
+		errCode int
+		error   string
+	}{
+		{
+			name:    "NoPath",
+			path:    "",
+			errCode: http.StatusBadRequest,
+			error:   "\"path\" is required",
+		},
+		{
+			name:    "RelativePathDotSlash",
+			path:    "./relative",
+			errCode: http.StatusBadRequest,
+			error:   "file path must be absolute",
+		},
+		{
+			name:    "RelativePath",
+			path:    "also-relative",
+			errCode: http.StatusBadRequest,
+			error:   "file path must be absolute",
+		},
+		{
+			name:  "NonExistent",
+			path:  filepath.Join(tmpdir, "/nested/does-not-exist"),
+			bytes: []byte("now it does exist"),
+		},
+		{
+			name:    "IsDir",
+			path:    dirPath,
+			errCode: http.StatusBadRequest,
+			error:   "is a directory",
+		},
+		{
+			name:    "IsNotDir",
+			path:    filepath.Join(filePath, "file2"),
+			errCode: http.StatusBadRequest,
+			error:   notDirErr,
+		},
+		{
+			name:    "NoPermissionsFile",
+			path:    noPermsFilePath,
+			errCode: http.StatusForbidden,
+			error:   "permission denied",
+		},
+		{
+			name:    "NoPermissionsDir",
+			path:    filepath.Join(noPermsDirPath, "within-no-perm-dir"),
+			errCode: http.StatusForbidden,
+			error:   "permission denied",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+			defer cancel()
+
+			reader := bytes.NewReader(tt.bytes)
+			err := conn.WriteFile(ctx, tt.path, reader)
+			if tt.errCode != 0 {
+				require.Error(t, err)
+				cerr := coderdtest.SDKError(t, err)
+				require.Contains(t, cerr.Error(), tt.error)
+				require.Equal(t, tt.errCode, cerr.StatusCode())
+			} else {
+				require.NoError(t, err)
+				b, err := afero.ReadFile(fs, tt.path)
+				require.NoError(t, err)
+				require.Equal(t, tt.bytes, b)
+			}
+		})
+	}
+}
+
+func TestEditFiles(t *testing.T) {
+	t.Parallel()
+
+	tmpdir := os.TempDir()
+	noPermsFilePath := filepath.Join(tmpdir, "no-perms-file")
+	failRenameFilePath := filepath.Join(tmpdir, "fail-rename")
+	//nolint:dogsled
+	conn, _, _, fs, _ := setupAgent(t, agentsdk.Manifest{}, 0, func(_ *agenttest.Client, opts *agent.Options) {
+		opts.Filesystem = newTestFs(opts.Filesystem, func(call, file string) error {
+			if file == noPermsFilePath {
+				return &os.PathError{
+					Op:   call,
+					Path: file,
+					Err:  os.ErrPermission,
+				}
+			} else if file == failRenameFilePath && call == "rename" {
+				return xerrors.New("rename failed")
+			}
+			return nil
+		})
+	})
+
+	dirPath := filepath.Join(tmpdir, "directory")
+	err := fs.MkdirAll(dirPath, 0o755)
+	require.NoError(t, err)
+
+	tests := []struct {
+		name     string
+		contents map[string]string
+		edits    []workspacesdk.FileEdits
+		expected map[string]string
+		errCode  int
+		errors   []string
+	}{
+		{
+			name:    "NoFiles",
+			errCode: http.StatusBadRequest,
+			errors:  []string{"must specify at least one file"},
+		},
+		{
+			name:    "NoPath",
+			errCode: http.StatusBadRequest,
+			edits: []workspacesdk.FileEdits{
+				{
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errors: []string{"\"path\" is required"},
+		},
+		{
+			name: "RelativePathDotSlash",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: "./relative",
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusBadRequest,
+			errors:  []string{"file path must be absolute"},
+		},
+		{
+			name: "RelativePath",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: "also-relative",
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusBadRequest,
+			errors:  []string{"file path must be absolute"},
+		},
+		{
+			name: "NoEdits",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "no-edits"),
+				},
+			},
+			errCode: http.StatusBadRequest,
+			errors:  []string{"must specify at least one edit"},
+		},
+		{
+			name: "NonExistent",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "does-not-exist"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusNotFound,
+			errors:  []string{"file does not exist"},
+		},
+		{
+			name: "IsDir",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: dirPath,
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusBadRequest,
+			errors:  []string{"not a file"},
+		},
+		{
+			name: "NoPermissions",
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: noPermsFilePath,
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusForbidden,
+			errors:  []string{"permission denied"},
+		},
+		{
+			name:     "FailRename",
+			contents: map[string]string{failRenameFilePath: "foo bar"},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: failRenameFilePath,
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			errCode: http.StatusInternalServerError,
+			errors:  []string{"rename failed"},
+		},
+		{
+			name:     "Edit1",
+			contents: map[string]string{filepath.Join(tmpdir, "edit1"): "foo bar"},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "edit1"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+					},
+				},
+			},
+			expected: map[string]string{filepath.Join(tmpdir, "edit1"): "bar bar"},
+		},
+		{
+			name:     "EditEdit", // Edits affect previous edits.
+			contents: map[string]string{filepath.Join(tmpdir, "edit-edit"): "foo bar"},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "edit-edit"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "foo",
+							Replace: "bar",
+						},
+						{
+							Search:  "bar",
+							Replace: "qux",
+						},
+					},
+				},
+			},
+			expected: map[string]string{filepath.Join(tmpdir, "edit-edit"): "qux qux"},
+		},
+		{
+			name:     "Multiline",
+			contents: map[string]string{filepath.Join(tmpdir, "multiline"): "foo\nbar\nbaz\nqux"},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "multiline"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "bar\nbaz",
+							Replace: "frob",
+						},
+					},
+				},
+			},
+			expected: map[string]string{filepath.Join(tmpdir, "multiline"): "foo\nfrob\nqux"},
+		},
+		{
+			name: "Multifile",
+			contents: map[string]string{
+				filepath.Join(tmpdir, "file1"): "file 1",
+				filepath.Join(tmpdir, "file2"): "file 2",
+				filepath.Join(tmpdir, "file3"): "file 3",
+			},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: filepath.Join(tmpdir, "file1"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited1",
+						},
+					},
+				},
+				{
+					Path: filepath.Join(tmpdir, "file2"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited2",
+						},
+					},
+				},
+				{
+					Path: filepath.Join(tmpdir, "file3"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited3",
+						},
+					},
+				},
+			},
+			expected: map[string]string{
+				filepath.Join(tmpdir, "file1"): "edited1 1",
+				filepath.Join(tmpdir, "file2"): "edited2 2",
+				filepath.Join(tmpdir, "file3"): "edited3 3",
+			},
+		},
+		{
+			name: "MultiError",
+			contents: map[string]string{
+				filepath.Join(tmpdir, "file8"): "file 8",
+			},
+			edits: []workspacesdk.FileEdits{
+				{
+					Path: noPermsFilePath,
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited7",
+						},
+					},
+				},
+				{
+					Path: filepath.Join(tmpdir, "file8"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited8",
+						},
+					},
+				},
+				{
+					Path: filepath.Join(tmpdir, "file9"),
+					Edits: []workspacesdk.FileEdit{
+						{
+							Search:  "file",
+							Replace: "edited9",
+						},
+					},
+				},
+			},
+			expected: map[string]string{
+				filepath.Join(tmpdir, "file8"): "edited8 8",
+			},
+			// Higher status codes will override lower ones, so in this case the 404
+			// takes priority over the 403.
+			errCode: http.StatusNotFound,
+			errors: []string{
+				fmt.Sprintf("%s: permission denied", noPermsFilePath),
+				"file9: file does not exist",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+			defer cancel()
+
+			for path, content := range tt.contents {
+				err := afero.WriteFile(fs, path, []byte(content), 0o644)
+				require.NoError(t, err)
+			}
+
+			err := conn.EditFiles(ctx, workspacesdk.FileEditRequest{Files: tt.edits})
+			if tt.errCode != 0 {
+				require.Error(t, err)
+				cerr := coderdtest.SDKError(t, err)
+				for _, error := range tt.errors {
+					require.Contains(t, cerr.Error(), error)
+				}
+				require.Equal(t, tt.errCode, cerr.StatusCode())
+			} else {
+				require.NoError(t, err)
+			}
+			for path, expect := range tt.expected {
+				b, err := afero.ReadFile(fs, path)
+				require.NoError(t, err)
+				require.Equal(t, expect, string(b))
+			}
+		})
+	}
+}

agent/immortalstreams/backedpipe/backed_pipe.go

@@ -0,0 +1,350 @@
+package backedpipe
+
+import (
+	"context"
+	"io"
+	"sync"
+
+	"golang.org/x/sync/errgroup"
+	"golang.org/x/sync/singleflight"
+	"golang.org/x/xerrors"
+)
+
+var (
+	ErrPipeClosed             = xerrors.New("pipe is closed")
+	ErrPipeAlreadyConnected   = xerrors.New("pipe is already connected")
+	ErrReconnectionInProgress = xerrors.New("reconnection already in progress")
+	ErrReconnectFailed        = xerrors.New("reconnect failed")
+	ErrInvalidSequenceNumber  = xerrors.New("remote sequence number exceeds local sequence")
+	ErrReconnectWriterFailed  = xerrors.New("reconnect writer failed")
+)
+
+// connectionState represents the current state of the BackedPipe connection.
+type connectionState int
+
+const (
+	// connected indicates the pipe is connected and operational.
+	connected connectionState = iota
+	// disconnected indicates the pipe is not connected but not closed.
+	disconnected
+	// reconnecting indicates a reconnection attempt is in progress.
+	reconnecting
+	// closed indicates the pipe is permanently closed.
+	closed
+)
+
+// ErrorEvent represents an error from a reader or writer with connection generation info.
+type ErrorEvent struct {
+	Err        error
+	Component  string // "reader" or "writer"
+	Generation uint64 // connection generation when error occurred
+}
+
+const (
+	// Default buffer capacity used by the writer - 64MB
+	DefaultBufferSize = 64 * 1024 * 1024
+)
+
+// Reconnector is an interface for establishing connections when the BackedPipe needs to reconnect.
+// Implementations should:
+// 1. Establish a new connection to the remote side
+// 2. Exchange sequence numbers with the remote side
+// 3. Return the new connection and the remote's reader sequence number
+//
+// The readerSeqNum parameter is the local reader's current sequence number
+// (total bytes successfully read from the remote). This must be sent to the
+// remote so it can replay its data to us starting from this number.
+//
+// The returned remoteReaderSeqNum should be the remote side's reader sequence
+// number (how many bytes of our outbound data it has successfully read). This
+// informs our writer where to resume (i.e., which bytes to replay to the remote).
+type Reconnector interface {
+	Reconnect(ctx context.Context, readerSeqNum uint64) (conn io.ReadWriteCloser, remoteReaderSeqNum uint64, err error)
+}
+
+// BackedPipe provides a reliable bidirectional byte stream over unreliable network connections.
+// It orchestrates a BackedReader and BackedWriter to provide transparent reconnection
+// and data replay capabilities.
+type BackedPipe struct {
+	ctx         context.Context
+	cancel      context.CancelFunc
+	mu          sync.RWMutex
+	reader      *BackedReader
+	writer      *BackedWriter
+	reconnector Reconnector
+	conn        io.ReadWriteCloser
+
+	// State machine
+	state   connectionState
+	connGen uint64 // Increments on each successful reconnection
+
+	// Unified error handling with generation filtering
+	errChan chan ErrorEvent
+
+	// singleflight group to dedupe concurrent ForceReconnect calls
+	sf singleflight.Group
+
+	// Track first error per generation to avoid duplicate reconnections
+	lastErrorGen uint64
+}
+
+// NewBackedPipe creates a new BackedPipe with default options and the specified reconnector.
+// The pipe starts disconnected and must be connected using Connect().
+func NewBackedPipe(ctx context.Context, reconnector Reconnector) *BackedPipe {
+	pipeCtx, cancel := context.WithCancel(ctx)
+
+	errChan := make(chan ErrorEvent, 1)
+
+	bp := &BackedPipe{
+		ctx:         pipeCtx,
+		cancel:      cancel,
+		reconnector: reconnector,
+		state:       disconnected,
+		connGen:     0, // Start with generation 0
+		errChan:     errChan,
+	}
+
+	// Create reader and writer with typed error channel for generation-aware error reporting
+	bp.reader = NewBackedReader(errChan)
+	bp.writer = NewBackedWriter(DefaultBufferSize, errChan)
+
+	// Start error handler goroutine
+	go bp.handleErrors()
+
+	return bp
+}
+
+// Connect establishes the initial connection using the reconnect function.
+func (bp *BackedPipe) Connect() error {
+	bp.mu.Lock()
+	defer bp.mu.Unlock()
+
+	if bp.state == closed {
+		return ErrPipeClosed
+	}
+
+	if bp.state == connected {
+		return ErrPipeAlreadyConnected
+	}
+
+	// Use internal context for the actual reconnect operation to ensure
+	// Close() reliably cancels any in-flight attempt.
+	return bp.reconnectLocked()
+}
+
+// Read implements io.Reader by delegating to the BackedReader.
+func (bp *BackedPipe) Read(p []byte) (int, error) {
+	return bp.reader.Read(p)
+}
+
+// Write implements io.Writer by delegating to the BackedWriter.
+func (bp *BackedPipe) Write(p []byte) (int, error) {
+	bp.mu.RLock()
+	writer := bp.writer
+	state := bp.state
+	bp.mu.RUnlock()
+
+	if state == closed {
+		return 0, io.EOF
+	}
+
+	return writer.Write(p)
+}
+
+// Close closes the pipe and all underlying connections.
+func (bp *BackedPipe) Close() error {
+	bp.mu.Lock()
+	defer bp.mu.Unlock()
+
+	if bp.state == closed {
+		return nil
+	}
+
+	bp.state = closed
+	bp.cancel() // Cancel main context
+
+	// Close all components in parallel to avoid deadlocks
+	//
+	// IMPORTANT: The connection must be closed first to unblock any
+	// readers or writers that might be holding the mutex on Read/Write
+	var g errgroup.Group
+
+	if bp.conn != nil {
+		conn := bp.conn
+		g.Go(func() error {
+			return conn.Close()
+		})
+		bp.conn = nil
+	}
+
+	if bp.reader != nil {
+		reader := bp.reader
+		g.Go(func() error {
+			return reader.Close()
+		})
+	}
+
+	if bp.writer != nil {
+		writer := bp.writer
+		g.Go(func() error {
+			return writer.Close()
+		})
+	}
+
+	// Wait for all close operations to complete and return any error
+	return g.Wait()
+}
+
+// Connected returns whether the pipe is currently connected.
+func (bp *BackedPipe) Connected() bool {
+	bp.mu.RLock()
+	defer bp.mu.RUnlock()
+	return bp.state == connected && bp.reader.Connected() && bp.writer.Connected()
+}
+
+// reconnectLocked handles the reconnection logic. Must be called with write lock held.
+func (bp *BackedPipe) reconnectLocked() error {
+	if bp.state == reconnecting {
+		return ErrReconnectionInProgress
+	}
+
+	bp.state = reconnecting
+	defer func() {
+		// Only reset to disconnected if we're still in reconnecting state
+		// (successful reconnection will set state to connected)
+		if bp.state == reconnecting {
+			bp.state = disconnected
+		}
+	}()
+
+	// Close existing connection if any
+	if bp.conn != nil {
+		_ = bp.conn.Close()
+		bp.conn = nil
+	}
+
+	// Increment the generation and update both reader and writer.
+	// We do it now to track even the connections that fail during
+	// Reconnect.
+	bp.connGen++
+	bp.reader.SetGeneration(bp.connGen)
+	bp.writer.SetGeneration(bp.connGen)
+
+	// Reconnect reader and writer
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go bp.reader.Reconnect(seqNum, newR)
+
+	// Get the precise reader sequence number from the reader while it holds its lock
+	readerSeqNum, ok := <-seqNum
+	if !ok {
+		// Reader was closed during reconnection
+		return ErrReconnectFailed
+	}
+
+	// Perform reconnect using the exact sequence number we just received
+	conn, remoteReaderSeqNum, err := bp.reconnector.Reconnect(bp.ctx, readerSeqNum)
+	if err != nil {
+		// Unblock reader reconnect
+		newR <- nil
+		return ErrReconnectFailed
+	}
+
+	// Provide the new connection to the reader (reader still holds its lock)
+	newR <- conn
+
+	// Replay our outbound data from the remote's reader sequence number
+	writerReconnectErr := bp.writer.Reconnect(remoteReaderSeqNum, conn)
+	if writerReconnectErr != nil {
+		return ErrReconnectWriterFailed
+	}
+
+	// Success - update state
+	bp.conn = conn
+	bp.state = connected
+
+	return nil
+}
+
+// handleErrors listens for connection errors from reader/writer and triggers reconnection.
+// It filters errors from old connections and ensures only the first error per generation
+// triggers reconnection.
+func (bp *BackedPipe) handleErrors() {
+	for {
+		select {
+		case <-bp.ctx.Done():
+			return
+		case errorEvt := <-bp.errChan:
+			bp.handleConnectionError(errorEvt)
+		}
+	}
+}
+
+// handleConnectionError handles errors from either reader or writer components.
+// It filters errors from old connections and ensures only one reconnection per generation.
+func (bp *BackedPipe) handleConnectionError(errorEvt ErrorEvent) {
+	bp.mu.Lock()
+	defer bp.mu.Unlock()
+
+	// Skip if already closed
+	if bp.state == closed {
+		return
+	}
+
+	// Filter errors from old connections (lower generation)
+	if errorEvt.Generation < bp.connGen {
+		return
+	}
+
+	// Skip if not connected (already disconnected or reconnecting)
+	if bp.state != connected {
+		return
+	}
+
+	// Skip if we've already seen an error for this generation
+	if bp.lastErrorGen >= errorEvt.Generation {
+		return
+	}
+
+	// This is the first error for this generation
+	bp.lastErrorGen = errorEvt.Generation
+
+	// Mark as disconnected
+	bp.state = disconnected
+
+	// Try to reconnect using internal context
+	reconnectErr := bp.reconnectLocked()
+
+	if reconnectErr != nil {
+		// Reconnection failed - log or handle as needed
+		// For now, we'll just continue and wait for manual reconnection
+		_ = errorEvt.Err       // Use the original error from the component
+		_ = errorEvt.Component // Component info available for potential logging by higher layers
+	}
+}
+
+// ForceReconnect forces a reconnection attempt immediately.
+// This can be used to force a reconnection if a new connection is established.
+// It prevents duplicate reconnections when called concurrently.
+func (bp *BackedPipe) ForceReconnect() error {
+	// Deduplicate concurrent ForceReconnect calls so only one reconnection
+	// attempt runs at a time from this API. Use the pipe's internal context
+	// to ensure Close() cancels any in-flight attempt.
+	_, err, _ := bp.sf.Do("force-reconnect", func() (interface{}, error) {
+		bp.mu.Lock()
+		defer bp.mu.Unlock()
+
+		if bp.state == closed {
+			return nil, io.EOF
+		}
+
+		// Don't force reconnect if already reconnecting
+		if bp.state == reconnecting {
+			return nil, ErrReconnectionInProgress
+		}
+
+		return nil, bp.reconnectLocked()
+	})
+	return err
+}

agent/immortalstreams/backedpipe/backed_pipe_test.go

@@ -0,0 +1,989 @@
+package backedpipe_test
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent/immortalstreams/backedpipe"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// mockConnection implements io.ReadWriteCloser for testing
+type mockConnection struct {
+	mu          sync.Mutex
+	readBuffer  bytes.Buffer
+	writeBuffer bytes.Buffer
+	closed      bool
+	readError   error
+	writeError  error
+	closeError  error
+	readFunc    func([]byte) (int, error)
+	writeFunc   func([]byte) (int, error)
+	seqNum      uint64
+}
+
+func newMockConnection() *mockConnection {
+	return &mockConnection{}
+}
+
+func (mc *mockConnection) Read(p []byte) (int, error) {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+
+	if mc.readFunc != nil {
+		return mc.readFunc(p)
+	}
+
+	if mc.readError != nil {
+		return 0, mc.readError
+	}
+
+	return mc.readBuffer.Read(p)
+}
+
+func (mc *mockConnection) Write(p []byte) (int, error) {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+
+	if mc.writeFunc != nil {
+		return mc.writeFunc(p)
+	}
+
+	if mc.writeError != nil {
+		return 0, mc.writeError
+	}
+
+	return mc.writeBuffer.Write(p)
+}
+
+func (mc *mockConnection) Close() error {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	mc.closed = true
+	return mc.closeError
+}
+
+func (mc *mockConnection) WriteString(s string) {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	_, _ = mc.readBuffer.WriteString(s)
+}
+
+func (mc *mockConnection) ReadString() string {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	return mc.writeBuffer.String()
+}
+
+func (mc *mockConnection) SetReadError(err error) {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	mc.readError = err
+}
+
+func (mc *mockConnection) SetWriteError(err error) {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	mc.writeError = err
+}
+
+func (mc *mockConnection) Reset() {
+	mc.mu.Lock()
+	defer mc.mu.Unlock()
+	mc.readBuffer.Reset()
+	mc.writeBuffer.Reset()
+	mc.readError = nil
+	mc.writeError = nil
+	mc.closed = false
+}
+
+// mockReconnector implements the Reconnector interface for testing
+type mockReconnector struct {
+	mu              sync.Mutex
+	connections     []*mockConnection
+	connectionIndex int
+	callCount       int
+	signalChan      chan struct{}
+}
+
+// Reconnect implements the Reconnector interface
+func (m *mockReconnector) Reconnect(ctx context.Context, readerSeqNum uint64) (io.ReadWriteCloser, uint64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	m.callCount++
+
+	if m.connectionIndex >= len(m.connections) {
+		return nil, 0, xerrors.New("no more connections available")
+	}
+
+	conn := m.connections[m.connectionIndex]
+	m.connectionIndex++
+
+	// Signal when reconnection happens
+	if m.connectionIndex > 1 {
+		select {
+		case m.signalChan <- struct{}{}:
+		default:
+		}
+	}
+
+	// Determine remoteReaderSeqNum (how many bytes of our outbound data the remote has read)
+	var remoteReaderSeqNum uint64
+	switch {
+	case m.callCount == 1:
+		remoteReaderSeqNum = 0
+	case conn.seqNum != 0:
+		remoteReaderSeqNum = conn.seqNum
+	default:
+		// Default to 0 if unspecified
+		remoteReaderSeqNum = 0
+	}
+
+	return conn, remoteReaderSeqNum, nil
+}
+
+// GetCallCount returns the current call count in a thread-safe manner
+func (m *mockReconnector) GetCallCount() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.callCount
+}
+
+// mockReconnectFunc creates a unified reconnector with all behaviors enabled
+func mockReconnectFunc(connections ...*mockConnection) (*mockReconnector, chan struct{}) {
+	signalChan := make(chan struct{}, 1)
+
+	reconnector := &mockReconnector{
+		connections: connections,
+		signalChan:  signalChan,
+	}
+
+	return reconnector, signalChan
+}
+
+// blockingReconnector is a reconnector that blocks on a channel for deterministic testing
+type blockingReconnector struct {
+	conn1       *mockConnection
+	conn2       *mockConnection
+	callCount   int
+	blockChan   <-chan struct{}
+	blockedChan chan struct{}
+	mu          sync.Mutex
+	signalOnce  sync.Once // Ensure we only signal once for the first actual reconnect
+}
+
+func (b *blockingReconnector) Reconnect(ctx context.Context, readerSeqNum uint64) (io.ReadWriteCloser, uint64, error) {
+	b.mu.Lock()
+	b.callCount++
+	currentCall := b.callCount
+	b.mu.Unlock()
+
+	if currentCall == 1 {
+		// Initial connect
+		return b.conn1, 0, nil
+	}
+
+	// Signal that we're about to block, but only once for the first reconnect attempt
+	// This ensures we properly test singleflight deduplication
+	b.signalOnce.Do(func() {
+		select {
+		case b.blockedChan <- struct{}{}:
+		default:
+			// If channel is full, don't block
+		}
+	})
+
+	// For subsequent calls, block until channel is closed
+	select {
+	case <-b.blockChan:
+		// Channel closed, proceed with reconnection
+	case <-ctx.Done():
+		return nil, 0, ctx.Err()
+	}
+
+	return b.conn2, 0, nil
+}
+
+// GetCallCount returns the current call count in a thread-safe manner
+func (b *blockingReconnector) GetCallCount() int {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.callCount
+}
+
+func mockBlockingReconnectFunc(conn1, conn2 *mockConnection, blockChan <-chan struct{}) (*blockingReconnector, chan struct{}) {
+	blockedChan := make(chan struct{}, 1)
+	reconnector := &blockingReconnector{
+		conn1:       conn1,
+		conn2:       conn2,
+		blockChan:   blockChan,
+		blockedChan: blockedChan,
+	}
+
+	return reconnector, blockedChan
+}
+
+// eofTestReconnector is a custom reconnector for the EOF test case
+type eofTestReconnector struct {
+	mu        sync.Mutex
+	conn1     io.ReadWriteCloser
+	conn2     io.ReadWriteCloser
+	callCount int
+}
+
+func (e *eofTestReconnector) Reconnect(ctx context.Context, readerSeqNum uint64) (io.ReadWriteCloser, uint64, error) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+
+	e.callCount++
+
+	if e.callCount == 1 {
+		return e.conn1, 0, nil
+	}
+	if e.callCount == 2 {
+		// Second call is the reconnection after EOF
+		// Return 5 to indicate remote has read all 5 bytes of "hello"
+		return e.conn2, 5, nil
+	}
+
+	return nil, 0, xerrors.New("no more connections")
+}
+
+// GetCallCount returns the current call count in a thread-safe manner
+func (e *eofTestReconnector) GetCallCount() int {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return e.callCount
+}
+
+func TestBackedPipe_NewBackedPipe(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	reconnectFn, _ := mockReconnectFunc(newMockConnection())
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+	require.NotNil(t, bp)
+	require.False(t, bp.Connected())
+}
+
+func TestBackedPipe_Connect(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnector, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 1, reconnector.GetCallCount())
+}
+
+func TestBackedPipe_ConnectAlreadyConnected(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+
+	err := bp.Connect()
+	require.NoError(t, err)
+
+	// Second connect should fail
+	err = bp.Connect()
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrPipeAlreadyConnected)
+}
+
+func TestBackedPipe_ConnectAfterClose(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+
+	err := bp.Close()
+	require.NoError(t, err)
+
+	err = bp.Connect()
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrPipeClosed)
+}
+
+func TestBackedPipe_BasicReadWrite(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+
+	err := bp.Connect()
+	require.NoError(t, err)
+
+	// Write data
+	n, err := bp.Write([]byte("hello"))
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+
+	// Simulate data coming back
+	conn.WriteString("world")
+
+	// Read data
+	buf := make([]byte, 10)
+	n, err = bp.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+	require.Equal(t, "world", string(buf[:n]))
+}
+
+func TestBackedPipe_WriteBeforeConnect(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+
+	// Write before connecting should block
+	writeComplete := make(chan error, 1)
+	go func() {
+		_, err := bp.Write([]byte("hello"))
+		writeComplete <- err
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when disconnected")
+	case <-time.After(100 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Connect should unblock the write
+	err := bp.Connect()
+	require.NoError(t, err)
+
+	// Write should now complete
+	err = testutil.RequireReceive(ctx, t, writeComplete)
+	require.NoError(t, err)
+
+	// Check that data was replayed to connection
+	require.Equal(t, "hello", conn.ReadString())
+}
+
+func TestBackedPipe_ReadBlocksWhenDisconnected(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	testCtx := testutil.Context(t, testutil.WaitShort)
+	reconnectFn, _ := mockReconnectFunc(newMockConnection())
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+
+	// Start a read that should block
+	readDone := make(chan struct{})
+	readStarted := make(chan struct{}, 1)
+	var readErr error
+
+	go func() {
+		defer close(readDone)
+		readStarted <- struct{}{} // Signal that we're about to start the read
+		buf := make([]byte, 10)
+		_, readErr = bp.Read(buf)
+	}()
+
+	// Wait for the goroutine to start
+	testutil.TryReceive(testCtx, t, readStarted)
+
+	// Ensure the read is actually blocked by verifying it hasn't completed
+	require.Eventually(t, func() bool {
+		select {
+		case <-readDone:
+			t.Fatal("Read should be blocked when disconnected")
+			return false
+		default:
+			// Good, still blocked
+			return true
+		}
+	}, testutil.WaitShort, testutil.IntervalMedium)
+
+	// Close should unblock the read
+	bp.Close()
+
+	testutil.TryReceive(testCtx, t, readDone)
+	require.Equal(t, io.EOF, readErr)
+}
+
+func TestBackedPipe_Reconnection(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	testCtx := testutil.Context(t, testutil.WaitShort)
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	conn2.seqNum = 17 // Remote has received 17 bytes, so replay from sequence 17
+	reconnectFn, signalChan := mockReconnectFunc(conn1, conn2)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	defer bp.Close()
+
+	// Initial connect
+	err := bp.Connect()
+	require.NoError(t, err)
+
+	// Write some data before failure
+	bp.Write([]byte("before disconnect***"))
+
+	// Simulate connection failure
+	conn1.SetReadError(xerrors.New("connection lost"))
+	conn1.SetWriteError(xerrors.New("connection lost"))
+
+	// Trigger a write to cause the pipe to notice the failure
+	_, _ = bp.Write([]byte("trigger failure "))
+
+	testutil.RequireReceive(testCtx, t, signalChan)
+
+	// Wait for reconnection to complete
+	require.Eventually(t, func() bool {
+		return bp.Connected()
+	}, testutil.WaitShort, testutil.IntervalFast, "pipe should reconnect")
+
+	replayedData := conn2.ReadString()
+	require.Equal(t, "***trigger failure ", replayedData, "Should replay exactly the data written after sequence 17")
+
+	// Verify that new writes work with the reconnected pipe
+	_, err = bp.Write([]byte("new data after reconnect"))
+	require.NoError(t, err)
+
+	// Read all data from the connection (replayed + new data)
+	allData := conn2.ReadString()
+	require.Equal(t, "***trigger failure new data after reconnect", allData, "Should have replayed data plus new data")
+}
+
+func TestBackedPipe_Close(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+
+	err := bp.Connect()
+	require.NoError(t, err)
+
+	err = bp.Close()
+	require.NoError(t, err)
+	require.True(t, conn.closed)
+
+	// Operations after close should fail
+	_, err = bp.Read(make([]byte, 10))
+	require.Equal(t, io.EOF, err)
+
+	_, err = bp.Write([]byte("test"))
+	require.Equal(t, io.EOF, err)
+}
+
+func TestBackedPipe_CloseIdempotent(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+
+	err := bp.Close()
+	require.NoError(t, err)
+
+	// Second close should be no-op
+	err = bp.Close()
+	require.NoError(t, err)
+}
+
+func TestBackedPipe_ReconnectFunctionFailure(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+
+	failingReconnector := &mockReconnector{
+		connections: nil, // No connections available
+	}
+
+	bp := backedpipe.NewBackedPipe(ctx, failingReconnector)
+	defer bp.Close()
+
+	err := bp.Connect()
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrReconnectFailed)
+	require.False(t, bp.Connected())
+}
+
+func TestBackedPipe_ForceReconnect(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	// Set conn2 sequence number to 9 to indicate remote has read all 9 bytes of "test data"
+	conn2.seqNum = 9
+	reconnector, _ := mockReconnectFunc(conn1, conn2)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Initial connect
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 1, reconnector.GetCallCount())
+
+	// Write some data to the first connection
+	_, err = bp.Write([]byte("test data"))
+	require.NoError(t, err)
+	require.Equal(t, "test data", conn1.ReadString())
+
+	// Force a reconnection
+	err = bp.ForceReconnect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 2, reconnector.GetCallCount())
+
+	// Since the mock returns the proper sequence number, no data should be replayed
+	// The new connection should be empty
+	require.Equal(t, "", conn2.ReadString())
+
+	// Verify that data can still be written and read after forced reconnection
+	_, err = bp.Write([]byte("new data"))
+	require.NoError(t, err)
+	require.Equal(t, "new data", conn2.ReadString())
+
+	// Verify that reads work with the new connection
+	conn2.WriteString("response data")
+	buf := make([]byte, 20)
+	n, err := bp.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 13, n)
+	require.Equal(t, "response data", string(buf[:n]))
+}
+
+func TestBackedPipe_ForceReconnectWhenClosed(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+
+	// Close the pipe first
+	err := bp.Close()
+	require.NoError(t, err)
+
+	// Try to force reconnect when closed
+	err = bp.ForceReconnect()
+	require.Error(t, err)
+	require.Equal(t, io.EOF, err)
+}
+
+func TestBackedPipe_StateTransitionsAndGenerationTracking(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	conn3 := newMockConnection()
+	reconnector, signalChan := mockReconnectFunc(conn1, conn2, conn3)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Initial state should be disconnected
+	require.False(t, bp.Connected())
+
+	// Connect should transition to connected
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 1, reconnector.GetCallCount())
+
+	// Write some data
+	_, err = bp.Write([]byte("test data gen 1"))
+	require.NoError(t, err)
+
+	// Simulate connection failure by setting errors on connection
+	conn1.SetReadError(xerrors.New("connection lost"))
+	conn1.SetWriteError(xerrors.New("connection lost"))
+
+	// Trigger a write to cause the pipe to notice the failure
+	_, _ = bp.Write([]byte("trigger failure"))
+
+	// Wait for reconnection signal
+	testutil.RequireReceive(testutil.Context(t, testutil.WaitShort), t, signalChan)
+
+	// Wait for reconnection to complete
+	require.Eventually(t, func() bool {
+		return bp.Connected()
+	}, testutil.WaitShort, testutil.IntervalFast, "should reconnect")
+	require.Equal(t, 2, reconnector.GetCallCount())
+
+	// Force another reconnection
+	err = bp.ForceReconnect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 3, reconnector.GetCallCount())
+
+	// Close should transition to closed state
+	err = bp.Close()
+	require.NoError(t, err)
+	require.False(t, bp.Connected())
+
+	// Operations on closed pipe should fail
+	err = bp.Connect()
+	require.Equal(t, backedpipe.ErrPipeClosed, err)
+
+	err = bp.ForceReconnect()
+	require.Equal(t, io.EOF, err)
+}
+
+func TestBackedPipe_GenerationFiltering(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	reconnector, _ := mockReconnectFunc(conn1, conn2)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Connect
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+
+	// Simulate multiple rapid errors from the same connection generation
+	// Only the first one should trigger reconnection
+	conn1.SetReadError(xerrors.New("error 1"))
+	conn1.SetWriteError(xerrors.New("error 2"))
+
+	// Trigger multiple errors quickly
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		_, _ = bp.Write([]byte("trigger error 1"))
+	}()
+	go func() {
+		defer wg.Done()
+		_, _ = bp.Write([]byte("trigger error 2"))
+	}()
+
+	// Wait for both writes to complete
+	wg.Wait()
+
+	// Wait for reconnection to complete
+	require.Eventually(t, func() bool {
+		return bp.Connected()
+	}, testutil.WaitShort, testutil.IntervalFast, "should reconnect once")
+
+	// Should have only reconnected once despite multiple errors
+	require.Equal(t, 2, reconnector.GetCallCount()) // Initial connect + 1 reconnect
+}
+
+func TestBackedPipe_DuplicateReconnectionPrevention(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	testCtx := testutil.Context(t, testutil.WaitShort)
+
+	// Create a blocking reconnector for deterministic testing
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	blockChan := make(chan struct{})
+	reconnector, blockedChan := mockBlockingReconnectFunc(conn1, conn2, blockChan)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Initial connect
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.Equal(t, 1, reconnector.GetCallCount(), "should have exactly 1 call after initial connect")
+
+	// We'll use channels to coordinate the test execution:
+	// 1. Start all goroutines but have them wait
+	// 2. Release the first one and wait for it to block
+	// 3. Release the others while the first is still blocked
+
+	const numConcurrent = 3
+	startSignals := make([]chan struct{}, numConcurrent)
+	startedSignals := make([]chan struct{}, numConcurrent)
+	for i := range startSignals {
+		startSignals[i] = make(chan struct{})
+		startedSignals[i] = make(chan struct{})
+	}
+
+	errors := make([]error, numConcurrent)
+	var wg sync.WaitGroup
+
+	// Start all goroutines
+	for i := 0; i < numConcurrent; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			// Wait for the signal to start
+			<-startSignals[idx]
+			// Signal that we're about to call ForceReconnect
+			close(startedSignals[idx])
+			errors[idx] = bp.ForceReconnect()
+		}(i)
+	}
+
+	// Start the first ForceReconnect and wait for it to block
+	close(startSignals[0])
+	<-startedSignals[0]
+
+	// Wait for the first reconnect to actually start and block
+	testutil.RequireReceive(testCtx, t, blockedChan)
+
+	// Now start all the other ForceReconnect calls
+	// They should all join the same singleflight operation
+	for i := 1; i < numConcurrent; i++ {
+		close(startSignals[i])
+	}
+
+	// Wait for all additional goroutines to have started their calls
+	for i := 1; i < numConcurrent; i++ {
+		<-startedSignals[i]
+	}
+
+	// At this point, one reconnect has started and is blocked,
+	// and all other goroutines have called ForceReconnect and should be
+	// waiting on the same singleflight operation.
+	// Due to singleflight, only one reconnect should have been attempted.
+	require.Equal(t, 2, reconnector.GetCallCount(), "should have exactly 2 calls: initial connect + 1 reconnect due to singleflight")
+
+	// Release the blocking reconnect function
+	close(blockChan)
+
+	// Wait for all ForceReconnect calls to complete
+	wg.Wait()
+
+	// All calls should succeed (they share the same result from singleflight)
+	for i, err := range errors {
+		require.NoError(t, err, "ForceReconnect %d should succeed", i, err)
+	}
+
+	// Final verification: call count should still be exactly 2
+	require.Equal(t, 2, reconnector.GetCallCount(), "final call count should be exactly 2: initial connect + 1 singleflight reconnect")
+}
+
+func TestBackedPipe_SingleReconnectionOnMultipleErrors(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	testCtx := testutil.Context(t, testutil.WaitShort)
+
+	// Create connections for initial connect and reconnection
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	reconnector, signalChan := mockReconnectFunc(conn1, conn2)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Initial connect
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 1, reconnector.GetCallCount())
+
+	// Write some initial data to establish the connection
+	_, err = bp.Write([]byte("initial data"))
+	require.NoError(t, err)
+
+	// Set up both read and write errors on the connection
+	conn1.SetReadError(xerrors.New("read connection lost"))
+	conn1.SetWriteError(xerrors.New("write connection lost"))
+
+	// Trigger write error (this will trigger reconnection)
+	go func() {
+		_, _ = bp.Write([]byte("trigger write error"))
+	}()
+
+	// Wait for reconnection to start
+	testutil.RequireReceive(testCtx, t, signalChan)
+
+	// Wait for reconnection to complete
+	require.Eventually(t, func() bool {
+		return bp.Connected()
+	}, testutil.WaitShort, testutil.IntervalFast, "should reconnect after write error")
+
+	// Verify that only one reconnection occurred
+	require.Equal(t, 2, reconnector.GetCallCount(), "should have exactly 2 calls: initial connect + 1 reconnection")
+	require.True(t, bp.Connected(), "should be connected after reconnection")
+}
+
+func TestBackedPipe_ForceReconnectWhenDisconnected(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnector, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Don't connect initially, just force reconnect
+	err := bp.ForceReconnect()
+	require.NoError(t, err)
+	require.True(t, bp.Connected())
+	require.Equal(t, 1, reconnector.GetCallCount())
+
+	// Verify we can write and read
+	_, err = bp.Write([]byte("test"))
+	require.NoError(t, err)
+	require.Equal(t, "test", conn.ReadString())
+
+	conn.WriteString("response")
+	buf := make([]byte, 10)
+	n, err := bp.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 8, n)
+	require.Equal(t, "response", string(buf[:n]))
+}
+
+func TestBackedPipe_EOFTriggersReconnection(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.Background()
+
+	// Create connections where we can control when EOF occurs
+	conn1 := newMockConnection()
+	conn2 := newMockConnection()
+	conn2.WriteString("newdata") // Pre-populate conn2 with data
+
+	// Make conn1 return EOF after reading "world"
+	hasReadData := false
+	conn1.readFunc = func(p []byte) (int, error) {
+		// Don't lock here - the Read method already holds the lock
+
+		// First time: return "world"
+		if !hasReadData && conn1.readBuffer.Len() > 0 {
+			n, _ := conn1.readBuffer.Read(p)
+			hasReadData = true
+			return n, nil
+		}
+		// After that: return EOF
+		return 0, io.EOF
+	}
+	conn1.WriteString("world")
+
+	reconnector := &eofTestReconnector{
+		conn1: conn1,
+		conn2: conn2,
+	}
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnector)
+	defer bp.Close()
+
+	// Initial connect
+	err := bp.Connect()
+	require.NoError(t, err)
+	require.Equal(t, 1, reconnector.GetCallCount())
+
+	// Write some data
+	_, err = bp.Write([]byte("hello"))
+	require.NoError(t, err)
+
+	buf := make([]byte, 10)
+
+	// First read should succeed
+	n, err := bp.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+	require.Equal(t, "world", string(buf[:n]))
+
+	// Next read will encounter EOF and should trigger reconnection
+	// After reconnection, it should read from conn2
+	n, err = bp.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 7, n)
+	require.Equal(t, "newdata", string(buf[:n]))
+
+	// Verify reconnection happened
+	require.Equal(t, 2, reconnector.GetCallCount())
+
+	// Verify the pipe is still connected and functional
+	require.True(t, bp.Connected())
+
+	// Further writes should go to the new connection
+	_, err = bp.Write([]byte("aftereof"))
+	require.NoError(t, err)
+	require.Equal(t, "aftereof", conn2.ReadString())
+}
+
+func BenchmarkBackedPipe_Write(b *testing.B) {
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	bp.Connect()
+	b.Cleanup(func() {
+		_ = bp.Close()
+	})
+
+	data := make([]byte, 1024) // 1KB writes
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		bp.Write(data)
+	}
+}
+
+func BenchmarkBackedPipe_Read(b *testing.B) {
+	ctx := context.Background()
+	conn := newMockConnection()
+	reconnectFn, _ := mockReconnectFunc(conn)
+
+	bp := backedpipe.NewBackedPipe(ctx, reconnectFn)
+	bp.Connect()
+	b.Cleanup(func() {
+		_ = bp.Close()
+	})
+
+	buf := make([]byte, 1024)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		// Fill connection with fresh data for each iteration
+		conn.WriteString(string(buf))
+		bp.Read(buf)
+	}
+}

agent/immortalstreams/backedpipe/backed_reader.go

@@ -0,0 +1,166 @@
+package backedpipe
+
+import (
+	"io"
+	"sync"
+)
+
+// BackedReader wraps an unreliable io.Reader and makes it resilient to disconnections.
+// It tracks sequence numbers for all bytes read and can handle reconnection,
+// blocking reads when disconnected instead of erroring.
+type BackedReader struct {
+	mu          sync.Mutex
+	cond        *sync.Cond
+	reader      io.Reader
+	sequenceNum uint64
+	closed      bool
+
+	// Error channel for generation-aware error reporting
+	errorEventChan chan<- ErrorEvent
+
+	// Current connection generation for error reporting
+	currentGen uint64
+}
+
+// NewBackedReader creates a new BackedReader with generation-aware error reporting.
+// The reader is initially disconnected and must be connected using Reconnect before
+// reads will succeed. The errorEventChan will receive ErrorEvent structs containing
+// error details, component info, and connection generation.
+func NewBackedReader(errorEventChan chan<- ErrorEvent) *BackedReader {
+	if errorEventChan == nil {
+		panic("error event channel cannot be nil")
+	}
+	br := &BackedReader{
+		errorEventChan: errorEventChan,
+	}
+	br.cond = sync.NewCond(&br.mu)
+	return br
+}
+
+// Read implements io.Reader. It blocks when disconnected until either:
+// 1. A reconnection is established
+// 2. The reader is closed
+//
+// When connected, it reads from the underlying reader and updates sequence numbers.
+// Connection failures are automatically detected and reported to the higher layer via callback.
+func (br *BackedReader) Read(p []byte) (int, error) {
+	br.mu.Lock()
+	defer br.mu.Unlock()
+
+	for {
+		// Step 1: Wait until we have a reader or are closed
+		for br.reader == nil && !br.closed {
+			br.cond.Wait()
+		}
+
+		if br.closed {
+			return 0, io.EOF
+		}
+
+		// Step 2: Perform the read while holding the mutex
+		// This ensures proper synchronization with Reconnect and Close operations
+		n, err := br.reader.Read(p)
+		br.sequenceNum += uint64(n) // #nosec G115 -- n is always >= 0 per io.Reader contract
+
+		if err == nil {
+			return n, nil
+		}
+
+		// Mark reader as disconnected so future reads will wait for reconnection
+		br.reader = nil
+
+		// Notify parent of error with generation information
+		select {
+		case br.errorEventChan <- ErrorEvent{
+			Err:        err,
+			Component:  "reader",
+			Generation: br.currentGen,
+		}:
+		default:
+			// Channel is full, drop the error.
+			// This is not a problem, because we set the reader to nil
+			// and block until reconnected so no new errors will be sent
+			// until pipe processes the error and reconnects.
+		}
+
+		// If we got some data before the error, return it now
+		if n > 0 {
+			return n, nil
+		}
+	}
+}
+
+// Reconnect coordinates reconnection using channels for better synchronization.
+// The seqNum channel is used to send the current sequence number to the caller.
+// The newR channel is used to receive the new reader from the caller.
+// This allows for better coordination during the reconnection process.
+func (br *BackedReader) Reconnect(seqNum chan<- uint64, newR <-chan io.Reader) {
+	// Grab the lock
+	br.mu.Lock()
+	defer br.mu.Unlock()
+
+	if br.closed {
+		// Close the channel to indicate closed state
+		close(seqNum)
+		return
+	}
+
+	// Get the sequence number to send to the other side via seqNum channel
+	seqNum <- br.sequenceNum
+	close(seqNum)
+
+	// Wait for the reconnect to complete, via newR channel, and give us a new io.Reader
+	newReader := <-newR
+
+	// If reconnection fails while we are starting it, the caller sends nil on newR
+	if newReader == nil {
+		// Reconnection failed, keep current state
+		return
+	}
+
+	// Reconnection successful
+	br.reader = newReader
+
+	// Notify any waiting reads via the cond
+	br.cond.Broadcast()
+}
+
+// Close the reader and wake up any blocked reads.
+// After closing, all Read calls will return io.EOF.
+func (br *BackedReader) Close() error {
+	br.mu.Lock()
+	defer br.mu.Unlock()
+
+	if br.closed {
+		return nil
+	}
+
+	br.closed = true
+	br.reader = nil
+
+	// Wake up any blocked reads
+	br.cond.Broadcast()
+
+	return nil
+}
+
+// SequenceNum returns the current sequence number (total bytes read).
+func (br *BackedReader) SequenceNum() uint64 {
+	br.mu.Lock()
+	defer br.mu.Unlock()
+	return br.sequenceNum
+}
+
+// Connected returns whether the reader is currently connected.
+func (br *BackedReader) Connected() bool {
+	br.mu.Lock()
+	defer br.mu.Unlock()
+	return br.reader != nil
+}
+
+// SetGeneration sets the current connection generation for error reporting.
+func (br *BackedReader) SetGeneration(generation uint64) {
+	br.mu.Lock()
+	defer br.mu.Unlock()
+	br.currentGen = generation
+}

agent/immortalstreams/backedpipe/backed_reader_test.go

@@ -0,0 +1,603 @@
+package backedpipe_test
+
+import (
+	"context"
+	"io"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent/immortalstreams/backedpipe"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// mockReader implements io.Reader with controllable behavior for testing
+type mockReader struct {
+	mu       sync.Mutex
+	data     []byte
+	pos      int
+	err      error
+	readFunc func([]byte) (int, error)
+}
+
+func newMockReader(data string) *mockReader {
+	return &mockReader{data: []byte(data)}
+}
+
+func (mr *mockReader) Read(p []byte) (int, error) {
+	mr.mu.Lock()
+	defer mr.mu.Unlock()
+
+	if mr.readFunc != nil {
+		return mr.readFunc(p)
+	}
+
+	if mr.err != nil {
+		return 0, mr.err
+	}
+
+	if mr.pos >= len(mr.data) {
+		return 0, io.EOF
+	}
+
+	n := copy(p, mr.data[mr.pos:])
+	mr.pos += n
+	return n, nil
+}
+
+func (mr *mockReader) setError(err error) {
+	mr.mu.Lock()
+	defer mr.mu.Unlock()
+	mr.err = err
+}
+
+func TestBackedReader_NewBackedReader(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	require.NotNil(t, br)
+	require.Equal(t, uint64(0), br.SequenceNum())
+	require.False(t, br.Connected())
+}
+
+func TestBackedReader_BasicReadOperation(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader := newMockReader("hello world")
+
+	// Connect the reader
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number from reader
+	seq := testutil.RequireReceive(ctx, t, seqNum)
+	require.Equal(t, uint64(0), seq)
+
+	// Send new reader
+	testutil.RequireSend(ctx, t, newR, io.Reader(reader))
+
+	// Read data
+	buf := make([]byte, 5)
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+	require.Equal(t, "hello", string(buf))
+	require.Equal(t, uint64(5), br.SequenceNum())
+
+	// Read more data
+	n, err = br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+	require.Equal(t, " worl", string(buf))
+	require.Equal(t, uint64(10), br.SequenceNum())
+}
+
+func TestBackedReader_ReadBlocksWhenDisconnected(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+
+	// Start a read operation that should block
+	readDone := make(chan struct{})
+	var readErr error
+	var readBuf []byte
+	var readN int
+
+	go func() {
+		defer close(readDone)
+		buf := make([]byte, 10)
+		readN, readErr = br.Read(buf)
+		readBuf = buf[:readN]
+	}()
+
+	// Ensure the read is actually blocked by verifying it hasn't completed
+	// and that the reader is not connected
+	select {
+	case <-readDone:
+		t.Fatal("Read should be blocked when disconnected")
+	default:
+		// Read is still blocked, which is what we want
+	}
+	require.False(t, br.Connected(), "Reader should not be connected")
+
+	// Connect and the read should unblock
+	reader := newMockReader("test")
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send new reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, io.Reader(reader))
+
+	// Wait for read to complete
+	testutil.TryReceive(ctx, t, readDone)
+	require.NoError(t, readErr)
+	require.Equal(t, "test", string(readBuf))
+}
+
+func TestBackedReader_ReconnectionAfterFailure(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader1 := newMockReader("first")
+
+	// Initial connection
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send new reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, io.Reader(reader1))
+
+	// Read some data
+	buf := make([]byte, 5)
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, "first", string(buf[:n]))
+	require.Equal(t, uint64(5), br.SequenceNum())
+
+	// Simulate connection failure
+	reader1.setError(xerrors.New("connection lost"))
+
+	// Start a read that will block due to connection failure
+	readDone := make(chan error, 1)
+	go func() {
+		_, err := br.Read(buf)
+		readDone <- err
+	}()
+
+	// Wait for the error to be reported via error channel
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Error(t, receivedErrorEvent.Err)
+	require.Equal(t, "reader", receivedErrorEvent.Component)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "connection lost")
+
+	// Verify read is still blocked
+	select {
+	case err := <-readDone:
+		t.Fatalf("Read should still be blocked, but completed with: %v", err)
+	default:
+		// Good, still blocked
+	}
+
+	// Verify disconnection
+	require.False(t, br.Connected())
+
+	// Reconnect with new reader
+	reader2 := newMockReader("second")
+	seqNum2 := make(chan uint64, 1)
+	newR2 := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum2, newR2)
+
+	// Get sequence number and send new reader
+	seq := testutil.RequireReceive(ctx, t, seqNum2)
+	require.Equal(t, uint64(5), seq) // Should return current sequence number
+	testutil.RequireSend(ctx, t, newR2, io.Reader(reader2))
+
+	// Wait for read to unblock and succeed with new data
+	readErr := testutil.RequireReceive(ctx, t, readDone)
+	require.NoError(t, readErr) // Should succeed with new reader
+	require.True(t, br.Connected())
+}
+
+func TestBackedReader_Close(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader := newMockReader("test")
+
+	// Connect
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send new reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, io.Reader(reader))
+
+	// First, read all available data
+	buf := make([]byte, 10)
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 4, n) // "test" is 4 bytes
+
+	// Close the reader before EOF triggers reconnection
+	err = br.Close()
+	require.NoError(t, err)
+
+	// After close, reads should return EOF
+	n, err = br.Read(buf)
+	require.Equal(t, 0, n)
+	require.Equal(t, io.EOF, err)
+
+	// Subsequent reads should return EOF
+	_, err = br.Read(buf)
+	require.Equal(t, io.EOF, err)
+}
+
+func TestBackedReader_CloseIdempotent(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+
+	err := br.Close()
+	require.NoError(t, err)
+
+	// Second close should be no-op
+	err = br.Close()
+	require.NoError(t, err)
+}
+
+func TestBackedReader_ReconnectAfterClose(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+
+	err := br.Close()
+	require.NoError(t, err)
+
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Should get 0 sequence number for closed reader
+	seq := testutil.TryReceive(ctx, t, seqNum)
+	require.Equal(t, uint64(0), seq)
+}
+
+// Helper function to reconnect a reader using channels
+func reconnectReader(ctx context.Context, t testing.TB, br *backedpipe.BackedReader, reader io.Reader) {
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send new reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, reader)
+}
+
+func TestBackedReader_SequenceNumberTracking(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader := newMockReader("0123456789")
+
+	reconnectReader(ctx, t, br, reader)
+
+	// Read in chunks and verify sequence number
+	buf := make([]byte, 3)
+
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 3, n)
+	require.Equal(t, uint64(3), br.SequenceNum())
+
+	n, err = br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 3, n)
+	require.Equal(t, uint64(6), br.SequenceNum())
+
+	n, err = br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 3, n)
+	require.Equal(t, uint64(9), br.SequenceNum())
+}
+
+func TestBackedReader_EOFHandling(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader := newMockReader("test")
+
+	reconnectReader(ctx, t, br, reader)
+
+	// Read all data
+	buf := make([]byte, 10)
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, 4, n)
+	require.Equal(t, "test", string(buf[:n]))
+
+	// Next read should encounter EOF, which triggers disconnection
+	// The read should block waiting for reconnection
+	readDone := make(chan struct{})
+	var readErr error
+	var readN int
+
+	go func() {
+		defer close(readDone)
+		readN, readErr = br.Read(buf)
+	}()
+
+	// Wait for EOF to be reported via error channel
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Equal(t, io.EOF, receivedErrorEvent.Err)
+	require.Equal(t, "reader", receivedErrorEvent.Component)
+
+	// Reader should be disconnected after EOF
+	require.False(t, br.Connected())
+
+	// Read should still be blocked
+	select {
+	case <-readDone:
+		t.Fatal("Read should be blocked waiting for reconnection after EOF")
+	default:
+		// Good, still blocked
+	}
+
+	// Reconnect with new data
+	reader2 := newMockReader("more")
+	reconnectReader(ctx, t, br, reader2)
+
+	// Wait for the blocked read to complete with new data
+	testutil.TryReceive(ctx, t, readDone)
+	require.NoError(t, readErr)
+	require.Equal(t, 4, readN)
+	require.Equal(t, "more", string(buf[:readN]))
+}
+
+func BenchmarkBackedReader_Read(b *testing.B) {
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	buf := make([]byte, 1024)
+
+	// Create a reader that never returns EOF by cycling through data
+	reader := &mockReader{
+		readFunc: func(p []byte) (int, error) {
+			// Fill buffer with 'x' characters - never EOF
+			for i := range p {
+				p[i] = 'x'
+			}
+			return len(p), nil
+		},
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+	defer cancel()
+	reconnectReader(ctx, b, br, reader)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		br.Read(buf)
+	}
+}
+
+func TestBackedReader_PartialReads(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+
+	// Create a reader that returns partial reads
+	reader := &mockReader{
+		readFunc: func(p []byte) (int, error) {
+			// Always return just 1 byte at a time
+			if len(p) == 0 {
+				return 0, nil
+			}
+			p[0] = 'A'
+			return 1, nil
+		},
+	}
+
+	reconnectReader(ctx, t, br, reader)
+
+	// Read multiple times
+	buf := make([]byte, 10)
+	for i := 0; i < 5; i++ {
+		n, err := br.Read(buf)
+		require.NoError(t, err)
+		require.Equal(t, 1, n)
+		require.Equal(t, byte('A'), buf[0])
+	}
+
+	require.Equal(t, uint64(5), br.SequenceNum())
+}
+
+func TestBackedReader_CloseWhileBlockedOnUnderlyingReader(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+
+	// Create a reader that blocks on Read calls but can be unblocked
+	readStarted := make(chan struct{}, 1)
+	readUnblocked := make(chan struct{})
+	blockingReader := &mockReader{
+		readFunc: func(p []byte) (int, error) {
+			select {
+			case readStarted <- struct{}{}:
+			default:
+			}
+			<-readUnblocked // Block until signaled
+			// After unblocking, return an error to simulate connection failure
+			return 0, xerrors.New("connection interrupted")
+		},
+	}
+
+	// Connect the blocking reader
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send blocking reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, io.Reader(blockingReader))
+
+	// Start a read that will block on the underlying reader
+	readDone := make(chan struct{})
+	var readErr error
+	var readN int
+
+	go func() {
+		defer close(readDone)
+		buf := make([]byte, 10)
+		readN, readErr = br.Read(buf)
+	}()
+
+	// Wait for the read to start and block on the underlying reader
+	testutil.RequireReceive(ctx, t, readStarted)
+
+	// Verify read is blocked by checking that it hasn't completed
+	// and ensuring we have adequate time for it to reach the blocking state
+	require.Eventually(t, func() bool {
+		select {
+		case <-readDone:
+			t.Fatal("Read should be blocked on underlying reader")
+			return false
+		default:
+			// Good, still blocked
+			return true
+		}
+	}, testutil.WaitShort, testutil.IntervalMedium)
+
+	// Start Close() in a goroutine since it will block until the underlying read completes
+	closeDone := make(chan error, 1)
+	go func() {
+		closeDone <- br.Close()
+	}()
+
+	// Verify Close() is also blocked waiting for the underlying read
+	select {
+	case <-closeDone:
+		t.Fatal("Close should be blocked until underlying read completes")
+	case <-time.After(10 * time.Millisecond):
+		// Good, Close is blocked
+	}
+
+	// Unblock the underlying reader, which will cause both the read and close to complete
+	close(readUnblocked)
+
+	// Wait for both the read and close to complete
+	testutil.TryReceive(ctx, t, readDone)
+	closeErr := testutil.RequireReceive(ctx, t, closeDone)
+	require.NoError(t, closeErr)
+
+	// The read should return EOF because Close() was called while it was blocked,
+	// even though the underlying reader returned an error
+	require.Equal(t, 0, readN)
+	require.Equal(t, io.EOF, readErr)
+
+	// Subsequent reads should return EOF since the reader is now closed
+	buf := make([]byte, 10)
+	n, err := br.Read(buf)
+	require.Equal(t, 0, n)
+	require.Equal(t, io.EOF, err)
+}
+
+func TestBackedReader_CloseWhileBlockedWaitingForReconnect(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	br := backedpipe.NewBackedReader(errChan)
+	reader1 := newMockReader("initial")
+
+	// Initial connection
+	seqNum := make(chan uint64, 1)
+	newR := make(chan io.Reader, 1)
+
+	go br.Reconnect(seqNum, newR)
+
+	// Get sequence number and send initial reader
+	testutil.RequireReceive(ctx, t, seqNum)
+	testutil.RequireSend(ctx, t, newR, io.Reader(reader1))
+
+	// Read initial data
+	buf := make([]byte, 10)
+	n, err := br.Read(buf)
+	require.NoError(t, err)
+	require.Equal(t, "initial", string(buf[:n]))
+
+	// Simulate connection failure
+	reader1.setError(xerrors.New("connection lost"))
+
+	// Start a read that will block waiting for reconnection
+	readDone := make(chan struct{})
+	var readErr error
+	var readN int
+
+	go func() {
+		defer close(readDone)
+		readN, readErr = br.Read(buf)
+	}()
+
+	// Wait for the error to be reported (indicating disconnection)
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Error(t, receivedErrorEvent.Err)
+	require.Equal(t, "reader", receivedErrorEvent.Component)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "connection lost")
+
+	// Verify read is blocked waiting for reconnection
+	select {
+	case <-readDone:
+		t.Fatal("Read should be blocked waiting for reconnection")
+	default:
+		// Good, still blocked
+	}
+
+	// Verify reader is disconnected
+	require.False(t, br.Connected())
+
+	// Close the BackedReader while read is blocked waiting for reconnection
+	err = br.Close()
+	require.NoError(t, err)
+
+	// The read should unblock and return EOF
+	testutil.TryReceive(ctx, t, readDone)
+	require.Equal(t, 0, readN)
+	require.Equal(t, io.EOF, readErr)
+}

agent/immortalstreams/backedpipe/backed_writer.go

@@ -0,0 +1,243 @@
+package backedpipe
+
+import (
+	"io"
+	"os"
+	"sync"
+
+	"golang.org/x/xerrors"
+)
+
+var (
+	ErrWriterClosed          = xerrors.New("cannot reconnect closed writer")
+	ErrNilWriter             = xerrors.New("new writer cannot be nil")
+	ErrFutureSequence        = xerrors.New("cannot replay from future sequence")
+	ErrReplayDataUnavailable = xerrors.New("failed to read replay data")
+	ErrReplayFailed          = xerrors.New("replay failed")
+	ErrPartialReplay         = xerrors.New("partial replay")
+)
+
+// BackedWriter wraps an unreliable io.Writer and makes it resilient to disconnections.
+// It maintains a ring buffer of recent writes for replay during reconnection.
+type BackedWriter struct {
+	mu          sync.Mutex
+	cond        *sync.Cond
+	writer      io.Writer
+	buffer      *ringBuffer
+	sequenceNum uint64 // total bytes written
+	closed      bool
+
+	// Error channel for generation-aware error reporting
+	errorEventChan chan<- ErrorEvent
+
+	// Current connection generation for error reporting
+	currentGen uint64
+}
+
+// NewBackedWriter creates a new BackedWriter with generation-aware error reporting.
+// The writer is initially disconnected and will block writes until connected.
+// The errorEventChan will receive ErrorEvent structs containing error details,
+// component info, and connection generation. Capacity must be > 0.
+func NewBackedWriter(capacity int, errorEventChan chan<- ErrorEvent) *BackedWriter {
+	if capacity <= 0 {
+		panic("backed writer capacity must be > 0")
+	}
+	if errorEventChan == nil {
+		panic("error event channel cannot be nil")
+	}
+	bw := &BackedWriter{
+		buffer:         newRingBuffer(capacity),
+		errorEventChan: errorEventChan,
+	}
+	bw.cond = sync.NewCond(&bw.mu)
+	return bw
+}
+
+// blockUntilConnectedOrClosed blocks until either a writer is available or the BackedWriter is closed.
+// Returns os.ErrClosed if closed while waiting, nil if connected. You must hold the mutex to call this.
+func (bw *BackedWriter) blockUntilConnectedOrClosed() error {
+	for bw.writer == nil && !bw.closed {
+		bw.cond.Wait()
+	}
+	if bw.closed {
+		return os.ErrClosed
+	}
+	return nil
+}
+
+// Write implements io.Writer.
+// When connected, it writes to both the ring buffer (to preserve data in case we need to replay it)
+// and the underlying writer.
+// If the underlying write fails, the writer is marked as disconnected and the write blocks
+// until reconnection occurs.
+func (bw *BackedWriter) Write(p []byte) (int, error) {
+	if len(p) == 0 {
+		return 0, nil
+	}
+
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+
+	// Block until connected
+	if err := bw.blockUntilConnectedOrClosed(); err != nil {
+		return 0, err
+	}
+
+	// Write to buffer
+	bw.buffer.Write(p)
+	bw.sequenceNum += uint64(len(p))
+
+	// Try to write to underlying writer
+	n, err := bw.writer.Write(p)
+	if err == nil && n != len(p) {
+		err = io.ErrShortWrite
+	}
+
+	if err != nil {
+		// Connection failed or partial write, mark as disconnected
+		bw.writer = nil
+
+		// Notify parent of error with generation information
+		select {
+		case bw.errorEventChan <- ErrorEvent{
+			Err:        err,
+			Component:  "writer",
+			Generation: bw.currentGen,
+		}:
+		default:
+			// Channel is full, drop the error.
+			// This is not a problem, because we set the writer to nil
+			// and block until reconnected so no new errors will be sent
+			// until pipe processes the error and reconnects.
+		}
+
+		// Block until reconnected - reconnection will replay this data
+		if err := bw.blockUntilConnectedOrClosed(); err != nil {
+			return 0, err
+		}
+
+		// Don't retry - reconnection replay handled it
+		return len(p), nil
+	}
+
+	// Write succeeded
+	return len(p), nil
+}
+
+// Reconnect replaces the current writer with a new one and replays data from the specified
+// sequence number. If the requested sequence number is no longer in the buffer,
+// returns an error indicating data loss.
+//
+// IMPORTANT: You must close the current writer, if any, before calling this method.
+// Otherwise, if a Write operation is currently blocked in the underlying writer's
+// Write method, this method will deadlock waiting for the mutex that Write holds.
+func (bw *BackedWriter) Reconnect(replayFromSeq uint64, newWriter io.Writer) error {
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+
+	if bw.closed {
+		return ErrWriterClosed
+	}
+
+	if newWriter == nil {
+		return ErrNilWriter
+	}
+
+	// Check if we can replay from the requested sequence number
+	if replayFromSeq > bw.sequenceNum {
+		return ErrFutureSequence
+	}
+
+	// Calculate how many bytes we need to replay
+	replayBytes := bw.sequenceNum - replayFromSeq
+
+	var replayData []byte
+	if replayBytes > 0 {
+		// Get the last replayBytes from buffer
+		// If the buffer doesn't have enough data (some was evicted),
+		// ReadLast will return an error
+		var err error
+		// Safe conversion: The check above (replayFromSeq > bw.sequenceNum) ensures
+		// replayBytes = bw.sequenceNum - replayFromSeq is always <= bw.sequenceNum.
+		// Since sequence numbers are much smaller than maxInt, the uint64->int conversion is safe.
+		//nolint:gosec // Safe conversion: replayBytes <= sequenceNum, which is much less than maxInt
+		replayData, err = bw.buffer.ReadLast(int(replayBytes))
+		if err != nil {
+			return ErrReplayDataUnavailable
+		}
+	}
+
+	// Clear the current writer first in case replay fails
+	bw.writer = nil
+
+	// Replay data if needed. We keep the mutex held during replay to ensure
+	// no concurrent operations can interfere with the reconnection process.
+	if len(replayData) > 0 {
+		n, err := newWriter.Write(replayData)
+		if err != nil {
+			// Reconnect failed, writer remains nil
+			return ErrReplayFailed
+		}
+
+		if n != len(replayData) {
+			// Reconnect failed, writer remains nil
+			return ErrPartialReplay
+		}
+	}
+
+	// Set new writer only after successful replay. This ensures no concurrent
+	// writes can interfere with the replay operation.
+	bw.writer = newWriter
+
+	// Wake up any operations waiting for connection
+	bw.cond.Broadcast()
+
+	return nil
+}
+
+// Close closes the writer and prevents further writes.
+// After closing, all Write calls will return os.ErrClosed.
+// This code keeps the Close() signature consistent with io.Closer,
+// but it never actually returns an error.
+//
+// IMPORTANT: You must close the current underlying writer, if any, before calling
+// this method. Otherwise, if a Write operation is currently blocked in the
+// underlying writer's Write method, this method will deadlock waiting for the
+// mutex that Write holds.
+func (bw *BackedWriter) Close() error {
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+
+	if bw.closed {
+		return nil
+	}
+
+	bw.closed = true
+	bw.writer = nil
+
+	// Wake up any blocked operations
+	bw.cond.Broadcast()
+
+	return nil
+}
+
+// SequenceNum returns the current sequence number (total bytes written).
+func (bw *BackedWriter) SequenceNum() uint64 {
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+	return bw.sequenceNum
+}
+
+// Connected returns whether the writer is currently connected.
+func (bw *BackedWriter) Connected() bool {
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+	return bw.writer != nil
+}
+
+// SetGeneration sets the current connection generation for error reporting.
+func (bw *BackedWriter) SetGeneration(generation uint64) {
+	bw.mu.Lock()
+	defer bw.mu.Unlock()
+	bw.currentGen = generation
+}

agent/immortalstreams/backedpipe/backed_writer_test.go

@@ -0,0 +1,992 @@
+package backedpipe_test
+
+import (
+	"bytes"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent/immortalstreams/backedpipe"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// mockWriter implements io.Writer with controllable behavior for testing
+type mockWriter struct {
+	mu         sync.Mutex
+	buffer     bytes.Buffer
+	err        error
+	writeFunc  func([]byte) (int, error)
+	writeCalls int
+}
+
+func newMockWriter() *mockWriter {
+	return &mockWriter{}
+}
+
+// newBackedWriterForTest creates a BackedWriter with a small buffer for testing eviction behavior
+func newBackedWriterForTest(bufferSize int) *backedpipe.BackedWriter {
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	return backedpipe.NewBackedWriter(bufferSize, errChan)
+}
+
+func (mw *mockWriter) Write(p []byte) (int, error) {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+
+	mw.writeCalls++
+
+	if mw.writeFunc != nil {
+		return mw.writeFunc(p)
+	}
+
+	if mw.err != nil {
+		return 0, mw.err
+	}
+
+	return mw.buffer.Write(p)
+}
+
+func (mw *mockWriter) Len() int {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	return mw.buffer.Len()
+}
+
+func (mw *mockWriter) Reset() {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	mw.buffer.Reset()
+	mw.writeCalls = 0
+	mw.err = nil
+	mw.writeFunc = nil
+}
+
+func (mw *mockWriter) setError(err error) {
+	mw.mu.Lock()
+	defer mw.mu.Unlock()
+	mw.err = err
+}
+
+func TestBackedWriter_NewBackedWriter(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+	require.NotNil(t, bw)
+	require.Equal(t, uint64(0), bw.SequenceNum())
+	require.False(t, bw.Connected())
+}
+
+func TestBackedWriter_WriteBlocksWhenDisconnected(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Write should block when disconnected
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		n, writeErr = bw.Write([]byte("hello"))
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when disconnected")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Connect and verify write completes
+	writer := newMockWriter()
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+
+	// Write should now complete
+	testutil.TryReceive(ctx, t, writeComplete)
+
+	require.NoError(t, writeErr)
+	require.Equal(t, 5, n)
+	require.Equal(t, uint64(5), bw.SequenceNum())
+	require.Equal(t, []byte("hello"), writer.buffer.Bytes())
+}
+
+func TestBackedWriter_WriteToUnderlyingWhenConnected(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+	writer := newMockWriter()
+
+	// Connect
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+	require.True(t, bw.Connected())
+
+	// Write should go to both buffer and underlying writer
+	n, err := bw.Write([]byte("hello"))
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+
+	// Data should be buffered
+	require.Equal(t, uint64(5), bw.SequenceNum())
+
+	// Check underlying writer
+	require.Equal(t, []byte("hello"), writer.buffer.Bytes())
+}
+
+func TestBackedWriter_BlockOnWriteFailure(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+	writer := newMockWriter()
+
+	// Connect
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+
+	// Cause write to fail
+	writer.setError(xerrors.New("write failed"))
+
+	// Write should block when underlying writer fails, not succeed immediately
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		n, writeErr = bw.Write([]byte("hello"))
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when underlying writer fails")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Wait for error event which implies writer was marked disconnected
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "write failed")
+	require.Equal(t, "writer", receivedErrorEvent.Component)
+	require.False(t, bw.Connected())
+
+	// Reconnect with working writer and verify write completes
+	writer2 := newMockWriter()
+	err = bw.Reconnect(0, writer2) // Replay from beginning
+	require.NoError(t, err)
+
+	// Write should now complete
+	testutil.TryReceive(ctx, t, writeComplete)
+
+	require.NoError(t, writeErr)
+	require.Equal(t, 5, n)
+	require.Equal(t, uint64(5), bw.SequenceNum())
+	require.Equal(t, []byte("hello"), writer2.buffer.Bytes())
+}
+
+func TestBackedWriter_ReplayOnReconnect(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Connect initially to write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	// Write some data while connected
+	_, err = bw.Write([]byte("hello"))
+	require.NoError(t, err)
+	_, err = bw.Write([]byte(" world"))
+	require.NoError(t, err)
+
+	require.Equal(t, uint64(11), bw.SequenceNum())
+
+	// Disconnect by causing a write failure
+	writer1.setError(xerrors.New("connection lost"))
+
+	// Write should block when underlying writer fails
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		n, writeErr = bw.Write([]byte("test"))
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when underlying writer fails")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Wait for error event which implies writer was marked disconnected
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "connection lost")
+	require.Equal(t, "writer", receivedErrorEvent.Component)
+	require.False(t, bw.Connected())
+
+	// Reconnect with new writer and request replay from beginning
+	writer2 := newMockWriter()
+	err = bw.Reconnect(0, writer2)
+	require.NoError(t, err)
+
+	// Write should now complete
+	select {
+	case <-writeComplete:
+		// Expected - write completed
+	case <-time.After(100 * time.Millisecond):
+		t.Fatal("Write should have completed after reconnection")
+	}
+
+	require.NoError(t, writeErr)
+	require.Equal(t, 4, n)
+
+	// Should have replayed all data including the failed write that was buffered
+	require.Equal(t, []byte("hello worldtest"), writer2.buffer.Bytes())
+
+	// Write new data should go to both
+	_, err = bw.Write([]byte("!"))
+	require.NoError(t, err)
+	require.Equal(t, []byte("hello worldtest!"), writer2.buffer.Bytes())
+}
+
+func TestBackedWriter_PartialReplay(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Connect initially to write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	// Write some data
+	_, err = bw.Write([]byte("hello"))
+	require.NoError(t, err)
+	_, err = bw.Write([]byte(" world"))
+	require.NoError(t, err)
+	_, err = bw.Write([]byte("!"))
+	require.NoError(t, err)
+
+	// Reconnect with new writer and request replay from middle
+	writer2 := newMockWriter()
+	err = bw.Reconnect(5, writer2) // From " world!"
+	require.NoError(t, err)
+
+	// Should have replayed only the requested portion
+	require.Equal(t, []byte(" world!"), writer2.buffer.Bytes())
+}
+
+func TestBackedWriter_ReplayFromFutureSequence(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Connect initially to write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	_, err = bw.Write([]byte("hello"))
+	require.NoError(t, err)
+
+	writer2 := newMockWriter()
+	err = bw.Reconnect(10, writer2) // Future sequence
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrFutureSequence)
+}
+
+func TestBackedWriter_ReplayDataLoss(t *testing.T) {
+	t.Parallel()
+
+	bw := newBackedWriterForTest(10) // Small buffer for testing
+
+	// Connect initially to write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	// Fill buffer beyond capacity to cause eviction
+	_, err = bw.Write([]byte("0123456789")) // Fills buffer exactly
+	require.NoError(t, err)
+	_, err = bw.Write([]byte("abcdef")) // Should evict "012345"
+	require.NoError(t, err)
+
+	writer2 := newMockWriter()
+	err = bw.Reconnect(0, writer2) // Try to replay from evicted data
+	// With the new error handling, this should fail because we can't read all the data
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrReplayDataUnavailable)
+}
+
+func TestBackedWriter_BufferEviction(t *testing.T) {
+	t.Parallel()
+
+	bw := newBackedWriterForTest(5) // Very small buffer for testing
+
+	// Connect initially
+	writer := newMockWriter()
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+
+	// Write data that will cause eviction
+	n, err := bw.Write([]byte("abcde"))
+	require.NoError(t, err)
+	require.Equal(t, 5, n)
+
+	// Write more to cause eviction
+	n, err = bw.Write([]byte("fg"))
+	require.NoError(t, err)
+	require.Equal(t, 2, n)
+
+	// Verify that the buffer contains only the latest data after eviction
+	// Total sequence number should be 7 (5 + 2)
+	require.Equal(t, uint64(7), bw.SequenceNum())
+
+	// Try to reconnect from the beginning - this should fail because
+	// the early data was evicted from the buffer
+	writer2 := newMockWriter()
+	err = bw.Reconnect(0, writer2)
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrReplayDataUnavailable)
+
+	// However, reconnecting from a sequence that's still in the buffer should work
+	// The buffer should contain the last 5 bytes: "cdefg"
+	writer3 := newMockWriter()
+	err = bw.Reconnect(2, writer3) // From sequence 2, should replay "cdefg"
+	require.NoError(t, err)
+	require.Equal(t, []byte("cdefg"), writer3.buffer.Bytes())
+	require.True(t, bw.Connected())
+}
+
+func TestBackedWriter_Close(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+	writer := newMockWriter()
+
+	bw.Reconnect(0, writer)
+
+	err := bw.Close()
+	require.NoError(t, err)
+
+	// Writes after close should fail
+	_, err = bw.Write([]byte("test"))
+	require.Equal(t, os.ErrClosed, err)
+
+	// Reconnect after close should fail
+	err = bw.Reconnect(0, newMockWriter())
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrWriterClosed)
+}
+
+func TestBackedWriter_CloseIdempotent(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	err := bw.Close()
+	require.NoError(t, err)
+
+	// Second close should be no-op
+	err = bw.Close()
+	require.NoError(t, err)
+}
+
+func TestBackedWriter_ReconnectDuringReplay(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Connect initially to write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	_, err = bw.Write([]byte("hello world"))
+	require.NoError(t, err)
+
+	// Create a writer that fails during replay
+	writer2 := &mockWriter{
+		err: backedpipe.ErrReplayFailed,
+	}
+
+	err = bw.Reconnect(0, writer2)
+	require.Error(t, err)
+	require.ErrorIs(t, err, backedpipe.ErrReplayFailed)
+	require.False(t, bw.Connected())
+}
+
+func TestBackedWriter_BlockOnPartialWrite(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Create writer that does partial writes
+	writer := &mockWriter{
+		writeFunc: func(p []byte) (int, error) {
+			if len(p) > 3 {
+				return 3, nil // Only write first 3 bytes
+			}
+			return len(p), nil
+		},
+	}
+
+	bw.Reconnect(0, writer)
+
+	// Write should block due to partial write
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		n, writeErr = bw.Write([]byte("hello"))
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when underlying writer does partial write")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Wait for error event which implies writer was marked disconnected
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "short write")
+	require.Equal(t, "writer", receivedErrorEvent.Component)
+	require.False(t, bw.Connected())
+
+	// Reconnect with working writer and verify write completes
+	writer2 := newMockWriter()
+	err := bw.Reconnect(0, writer2) // Replay from beginning
+	require.NoError(t, err)
+
+	// Write should now complete
+	testutil.TryReceive(ctx, t, writeComplete)
+
+	require.NoError(t, writeErr)
+	require.Equal(t, 5, n)
+	require.Equal(t, uint64(5), bw.SequenceNum())
+	require.Equal(t, []byte("hello"), writer2.buffer.Bytes())
+}
+
+func TestBackedWriter_WriteUnblocksOnReconnect(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Start a single write that should block
+	writeResult := make(chan error, 1)
+	go func() {
+		_, err := bw.Write([]byte("test"))
+		writeResult <- err
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeResult:
+		t.Fatal("Write should have blocked when disconnected")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Connect and verify write completes
+	writer := newMockWriter()
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+
+	// Write should now complete
+	err = testutil.RequireReceive(ctx, t, writeResult)
+	require.NoError(t, err)
+
+	// Write should have been written to the underlying writer
+	require.Equal(t, "test", writer.buffer.String())
+}
+
+func TestBackedWriter_CloseUnblocksWaitingWrites(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Start a write that should block
+	writeComplete := make(chan error, 1)
+	go func() {
+		_, err := bw.Write([]byte("test"))
+		writeComplete <- err
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked when disconnected")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Close the writer
+	err := bw.Close()
+	require.NoError(t, err)
+
+	// Write should now complete with error
+	err = testutil.RequireReceive(ctx, t, writeComplete)
+	require.Equal(t, os.ErrClosed, err)
+}
+
+func TestBackedWriter_WriteBlocksAfterDisconnection(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+	writer := newMockWriter()
+
+	// Connect initially
+	err := bw.Reconnect(0, writer)
+	require.NoError(t, err)
+
+	// Write should succeed when connected
+	_, err = bw.Write([]byte("hello"))
+	require.NoError(t, err)
+
+	// Cause disconnection - the write should now block instead of returning an error
+	writer.setError(xerrors.New("connection lost"))
+
+	// This write should block
+	writeComplete := make(chan error, 1)
+	go func() {
+		_, err := bw.Write([]byte("world"))
+		writeComplete <- err
+	}()
+
+	// Verify write is blocked
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should have blocked after disconnection")
+	case <-time.After(50 * time.Millisecond):
+		// Expected - write is blocked
+	}
+
+	// Wait for error event which implies writer was marked disconnected
+	receivedErrorEvent := testutil.RequireReceive(ctx, t, errChan)
+	require.Contains(t, receivedErrorEvent.Err.Error(), "connection lost")
+	require.Equal(t, "writer", receivedErrorEvent.Component)
+	require.False(t, bw.Connected())
+
+	// Reconnect and verify write completes
+	writer2 := newMockWriter()
+	err = bw.Reconnect(5, writer2) // Replay from after "hello"
+	require.NoError(t, err)
+
+	err = testutil.RequireReceive(ctx, t, writeComplete)
+	require.NoError(t, err)
+
+	// Check that only "world" was written during replay (not duplicated)
+	require.Equal(t, []byte("world"), writer2.buffer.Bytes()) // Only "world" since we replayed from sequence 5
+}
+
+func TestBackedWriter_ConcurrentWriteAndClose(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Don't connect initially - this will cause writes to block in blockUntilConnectedOrClosed()
+
+	writeStarted := make(chan struct{}, 1)
+
+	// Start a write operation that will block waiting for connection
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		// Signal that we're about to start the write
+		writeStarted <- struct{}{}
+		// This write will block in blockUntilConnectedOrClosed() since no writer is connected
+		n, writeErr = bw.Write([]byte("hello"))
+	}()
+
+	// Wait for write goroutine to start
+	ctx := testutil.Context(t, testutil.WaitShort)
+	testutil.RequireReceive(ctx, t, writeStarted)
+
+	// Ensure the write is actually blocked by repeatedly checking that:
+	// 1. The write hasn't completed yet
+	// 2. The writer is still not connected
+	// We use require.Eventually to give it a fair chance to reach the blocking state
+	require.Eventually(t, func() bool {
+		select {
+		case <-writeComplete:
+			t.Fatal("Write should be blocked when no writer is connected")
+			return false
+		default:
+			// Write is still blocked, which is what we want
+			return !bw.Connected()
+		}
+	}, testutil.WaitShort, testutil.IntervalMedium)
+
+	// Close the writer while the write is blocked waiting for connection
+	closeErr := bw.Close()
+	require.NoError(t, closeErr)
+
+	// Wait for write to complete
+	select {
+	case <-writeComplete:
+		// Good, write completed
+	case <-ctx.Done():
+		t.Fatal("Write did not complete in time")
+	}
+
+	// The write should have failed with os.ErrClosed because Close() was called
+	// while it was waiting for connection
+	require.ErrorIs(t, writeErr, os.ErrClosed)
+	require.Equal(t, 0, n)
+
+	// Subsequent writes should also fail
+	n, err := bw.Write([]byte("world"))
+	require.Equal(t, 0, n)
+	require.ErrorIs(t, err, os.ErrClosed)
+}
+
+func TestBackedWriter_ConcurrentWriteAndReconnect(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Initial connection
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	// Write some initial data
+	_, err = bw.Write([]byte("initial"))
+	require.NoError(t, err)
+
+	// Start reconnection which will block new writes
+	replayStarted := make(chan struct{}, 1) // Buffered to prevent race condition
+	replayCanComplete := make(chan struct{})
+	writer2 := &mockWriter{
+		writeFunc: func(p []byte) (int, error) {
+			// Signal that replay has started
+			select {
+			case replayStarted <- struct{}{}:
+			default:
+				// Signal already sent, which is fine
+			}
+			// Wait for test to allow replay to complete
+			<-replayCanComplete
+			return len(p), nil
+		},
+	}
+
+	// Start the reconnection in a goroutine so we can control timing
+	reconnectComplete := make(chan error, 1)
+	go func() {
+		reconnectComplete <- bw.Reconnect(0, writer2)
+	}()
+
+	ctx := testutil.Context(t, testutil.WaitShort)
+	// Wait for replay to start
+	testutil.RequireReceive(ctx, t, replayStarted)
+
+	// Now start a write operation that will be blocked by the ongoing reconnect
+	writeStarted := make(chan struct{}, 1)
+	writeComplete := make(chan struct{})
+	var writeErr error
+	var n int
+
+	go func() {
+		defer close(writeComplete)
+		// Signal that we're about to start the write
+		writeStarted <- struct{}{}
+		// This write should be blocked during reconnect
+		n, writeErr = bw.Write([]byte("blocked"))
+	}()
+
+	// Wait for write to start
+	testutil.RequireReceive(ctx, t, writeStarted)
+
+	// Use a small timeout to ensure the write goroutine has a chance to get blocked
+	// on the mutex before we check if it's still blocked
+	writeCheckTimer := time.NewTimer(testutil.IntervalFast)
+	defer writeCheckTimer.Stop()
+
+	select {
+	case <-writeComplete:
+		t.Fatal("Write should be blocked during reconnect")
+	case <-writeCheckTimer.C:
+		// Write is still blocked after a reasonable wait
+	}
+
+	// Allow replay to complete, which will allow reconnect to finish
+	close(replayCanComplete)
+
+	// Wait for reconnection to complete
+	select {
+	case reconnectErr := <-reconnectComplete:
+		require.NoError(t, reconnectErr)
+	case <-ctx.Done():
+		t.Fatal("Reconnect did not complete in time")
+	}
+
+	// Wait for write to complete
+	<-writeComplete
+
+	// Write should succeed after reconnection completes
+	require.NoError(t, writeErr)
+	require.Equal(t, 7, n) // "blocked" is 7 bytes
+
+	// Verify the writer is connected
+	require.True(t, bw.Connected())
+}
+
+func TestBackedWriter_ConcurrentReconnectAndClose(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Initial connection and write some data
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+	_, err = bw.Write([]byte("test data"))
+	require.NoError(t, err)
+
+	// Start reconnection with slow replay
+	reconnectStarted := make(chan struct{}, 1)
+	replayCanComplete := make(chan struct{})
+	reconnectComplete := make(chan struct{})
+	var reconnectErr error
+
+	go func() {
+		defer close(reconnectComplete)
+		writer2 := &mockWriter{
+			writeFunc: func(p []byte) (int, error) {
+				// Signal that replay has started
+				select {
+				case reconnectStarted <- struct{}{}:
+				default:
+				}
+				// Wait for test to allow replay to complete
+				<-replayCanComplete
+				return len(p), nil
+			},
+		}
+		reconnectErr = bw.Reconnect(0, writer2)
+	}()
+
+	// Wait for reconnection to start
+	ctx := testutil.Context(t, testutil.WaitShort)
+	testutil.RequireReceive(ctx, t, reconnectStarted)
+
+	// Start Close() in a separate goroutine since it will block until Reconnect() completes
+	closeStarted := make(chan struct{}, 1)
+	closeComplete := make(chan error, 1)
+	go func() {
+		closeStarted <- struct{}{} // Signal that Close() is starting
+		closeComplete <- bw.Close()
+	}()
+
+	// Wait for Close() to start, then give it a moment to attempt to acquire the mutex
+	testutil.RequireReceive(ctx, t, closeStarted)
+	closeCheckTimer := time.NewTimer(testutil.IntervalFast)
+	defer closeCheckTimer.Stop()
+
+	select {
+	case <-closeComplete:
+		t.Fatal("Close should be blocked during reconnect")
+	case <-closeCheckTimer.C:
+		// Good, Close is still blocked after a reasonable wait
+	}
+
+	// Allow replay to complete so reconnection can finish
+	close(replayCanComplete)
+
+	// Wait for reconnect to complete
+	select {
+	case <-reconnectComplete:
+		// Good, reconnect completed
+	case <-ctx.Done():
+		t.Fatal("Reconnect did not complete in time")
+	}
+
+	// Wait for close to complete
+	select {
+	case closeErr := <-closeComplete:
+		require.NoError(t, closeErr)
+	case <-ctx.Done():
+		t.Fatal("Close did not complete in time")
+	}
+
+	// With mutex held during replay, Close() waits for Reconnect() to finish.
+	// So Reconnect() should succeed, then Close() runs and closes the writer.
+	require.NoError(t, reconnectErr)
+
+	// Verify writer is closed (Close() ran after Reconnect() completed)
+	require.False(t, bw.Connected())
+}
+
+func TestBackedWriter_MultipleWritesDuringReconnect(t *testing.T) {
+	t.Parallel()
+
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Initial connection
+	writer1 := newMockWriter()
+	err := bw.Reconnect(0, writer1)
+	require.NoError(t, err)
+
+	// Write some initial data
+	_, err = bw.Write([]byte("initial"))
+	require.NoError(t, err)
+
+	// Start multiple write operations
+	numWriters := 5
+	var wg sync.WaitGroup
+	writeResults := make([]error, numWriters)
+	writesStarted := make(chan struct{}, numWriters)
+
+	for i := 0; i < numWriters; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			// Signal that this write is starting
+			writesStarted <- struct{}{}
+			data := []byte{byte('A' + id)}
+			_, writeResults[id] = bw.Write(data)
+		}(i)
+	}
+
+	// Wait for all writes to start
+	ctx := testutil.Context(t, testutil.WaitLong)
+	for i := 0; i < numWriters; i++ {
+		testutil.RequireReceive(ctx, t, writesStarted)
+	}
+
+	// Use a timer to ensure all write goroutines have had a chance to start executing
+	// and potentially get blocked on the mutex before we start the reconnection
+	writesReadyTimer := time.NewTimer(testutil.IntervalFast)
+	defer writesReadyTimer.Stop()
+	<-writesReadyTimer.C
+
+	// Start reconnection with controlled replay
+	replayStarted := make(chan struct{}, 1)
+	replayCanComplete := make(chan struct{})
+	writer2 := &mockWriter{
+		writeFunc: func(p []byte) (int, error) {
+			// Signal that replay has started
+			select {
+			case replayStarted <- struct{}{}:
+			default:
+			}
+			// Wait for test to allow replay to complete
+			<-replayCanComplete
+			return len(p), nil
+		},
+	}
+
+	// Start reconnection in a goroutine so we can control timing
+	reconnectComplete := make(chan error, 1)
+	go func() {
+		reconnectComplete <- bw.Reconnect(0, writer2)
+	}()
+
+	// Wait for replay to start
+	testutil.RequireReceive(ctx, t, replayStarted)
+
+	// Allow replay to complete
+	close(replayCanComplete)
+
+	// Wait for reconnection to complete
+	select {
+	case reconnectErr := <-reconnectComplete:
+		require.NoError(t, reconnectErr)
+	case <-ctx.Done():
+		t.Fatal("Reconnect did not complete in time")
+	}
+
+	// Wait for all writes to complete
+	wg.Wait()
+
+	// All writes should succeed
+	for i, err := range writeResults {
+		require.NoError(t, err, "Write %d should succeed", i)
+	}
+
+	// Verify the writer is connected
+	require.True(t, bw.Connected())
+}
+
+func BenchmarkBackedWriter_Write(b *testing.B) {
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan) // 64KB buffer
+	writer := newMockWriter()
+	bw.Reconnect(0, writer)
+
+	data := bytes.Repeat([]byte("x"), 1024) // 1KB writes
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		bw.Write(data)
+	}
+}
+
+func BenchmarkBackedWriter_Reconnect(b *testing.B) {
+	errChan := make(chan backedpipe.ErrorEvent, 1)
+	bw := backedpipe.NewBackedWriter(backedpipe.DefaultBufferSize, errChan)
+
+	// Connect initially to fill buffer with data
+	initialWriter := newMockWriter()
+	err := bw.Reconnect(0, initialWriter)
+	if err != nil {
+		b.Fatal(err)
+	}
+
+	// Fill buffer with data
+	data := bytes.Repeat([]byte("x"), 1024)
+	for i := 0; i < 32; i++ {
+		bw.Write(data)
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		writer := newMockWriter()
+		bw.Reconnect(0, writer)
+	}
+}

agent/immortalstreams/backedpipe/ring_buffer.go

@@ -0,0 +1,129 @@
+package backedpipe
+
+import "golang.org/x/xerrors"
+
+// ringBuffer implements an efficient circular buffer with a fixed-size allocation.
+// This implementation is not thread-safe and relies on external synchronization.
+type ringBuffer struct {
+	buffer []byte
+	start  int // index of first valid byte
+	end    int // index of last valid byte (-1 when empty)
+}
+
+// newRingBuffer creates a new ring buffer with the specified capacity.
+// Capacity must be > 0.
+func newRingBuffer(capacity int) *ringBuffer {
+	if capacity <= 0 {
+		panic("ring buffer capacity must be > 0")
+	}
+	return &ringBuffer{
+		buffer: make([]byte, capacity),
+		end:    -1, // -1 indicates empty buffer
+	}
+}
+
+// Size returns the current number of bytes in the buffer.
+func (rb *ringBuffer) Size() int {
+	if rb.end == -1 {
+		return 0 // Buffer is empty
+	}
+	if rb.start <= rb.end {
+		return rb.end - rb.start + 1
+	}
+	// Buffer wraps around
+	return len(rb.buffer) - rb.start + rb.end + 1
+}
+
+// Write writes data to the ring buffer. If the buffer would overflow,
+// it evicts the oldest data to make room for new data.
+func (rb *ringBuffer) Write(data []byte) {
+	if len(data) == 0 {
+		return
+	}
+
+	capacity := len(rb.buffer)
+
+	// If data is larger than capacity, only keep the last capacity bytes
+	if len(data) > capacity {
+		data = data[len(data)-capacity:]
+		// Clear buffer and write new data
+		rb.start = 0
+		rb.end = -1 // Will be set properly below
+	}
+
+	// Calculate how much we need to evict to fit new data
+	spaceNeeded := len(data)
+	availableSpace := capacity - rb.Size()
+
+	if spaceNeeded > availableSpace {
+		bytesToEvict := spaceNeeded - availableSpace
+		rb.evict(bytesToEvict)
+	}
+
+	// Buffer has data, write after current end
+	writePos := (rb.end + 1) % capacity
+	if writePos+len(data) <= capacity {
+		// No wrap needed - single copy
+		copy(rb.buffer[writePos:], data)
+		rb.end = (rb.end + len(data)) % capacity
+	} else {
+		// Need to wrap around - two copies
+		firstChunk := capacity - writePos
+		copy(rb.buffer[writePos:], data[:firstChunk])
+		copy(rb.buffer[0:], data[firstChunk:])
+		rb.end = len(data) - firstChunk - 1
+	}
+}
+
+// evict removes the specified number of bytes from the beginning of the buffer.
+func (rb *ringBuffer) evict(count int) {
+	if count >= rb.Size() {
+		// Evict everything
+		rb.start = 0
+		rb.end = -1
+		return
+	}
+
+	rb.start = (rb.start + count) % len(rb.buffer)
+	// Buffer remains non-empty after partial eviction
+}
+
+// ReadLast returns the last n bytes from the buffer.
+// If n is greater than the available data, returns an error.
+// If n is negative, returns an error.
+func (rb *ringBuffer) ReadLast(n int) ([]byte, error) {
+	if n < 0 {
+		return nil, xerrors.New("cannot read negative number of bytes")
+	}
+
+	if n == 0 {
+		return nil, nil
+	}
+
+	size := rb.Size()
+
+	// If requested more than available, return error
+	if n > size {
+		return nil, xerrors.Errorf("requested %d bytes but only %d available", n, size)
+	}
+
+	result := make([]byte, n)
+	capacity := len(rb.buffer)
+
+	// Calculate where to start reading from (n bytes before the end)
+	startOffset := size - n
+	actualStart := (rb.start + startOffset) % capacity
+
+	// Copy the last n bytes
+	if actualStart+n <= capacity {
+		// No wrap needed
+		copy(result, rb.buffer[actualStart:actualStart+n])
+	} else {
+		// Need to wrap around
+		firstChunk := capacity - actualStart
+		copy(result[0:firstChunk], rb.buffer[actualStart:capacity])
+		copy(result[firstChunk:], rb.buffer[0:n-firstChunk])
+	}
+
+	return result, nil
+}

agent/immortalstreams/backedpipe/ring_buffer_internal_test.go

@@ -0,0 +1,261 @@
+package backedpipe
+
+import (
+	"bytes"
+	"os"
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/goleak"
+
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestMain(m *testing.M) {
+	if runtime.GOOS == "windows" {
+		// Don't run goleak on windows tests, they're super flaky right now.
+		// See: https://github.com/coder/coder/issues/8954
+		os.Exit(m.Run())
+	}
+	goleak.VerifyTestMain(m, testutil.GoleakOptions...)
+}
+
+func TestRingBuffer_NewRingBuffer(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(100)
+	// Test that we can write and read from the buffer
+	rb.Write([]byte("test"))
+
+	data, err := rb.ReadLast(4)
+	require.NoError(t, err)
+	require.Equal(t, []byte("test"), data)
+}
+
+func TestRingBuffer_WriteAndRead(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(10)
+
+	// Write some data
+	rb.Write([]byte("hello"))
+
+	// Read last 4 bytes
+	data, err := rb.ReadLast(4)
+	require.NoError(t, err)
+	require.Equal(t, "ello", string(data))
+
+	// Write more data
+	rb.Write([]byte("world"))
+
+	// Read last 5 bytes
+	data, err = rb.ReadLast(5)
+	require.NoError(t, err)
+	require.Equal(t, "world", string(data))
+
+	// Read last 3 bytes
+	data, err = rb.ReadLast(3)
+	require.NoError(t, err)
+	require.Equal(t, "rld", string(data))
+
+	// Read more than available (should be 10 bytes total)
+	_, err = rb.ReadLast(15)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "requested 15 bytes but only")
+}
+
+func TestRingBuffer_OverflowEviction(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(5)
+
+	// Fill buffer
+	rb.Write([]byte("abcde"))
+
+	// Overflow should evict oldest data
+	rb.Write([]byte("fg"))
+
+	// Should now contain "cdefg"
+	data, err := rb.ReadLast(5)
+	require.NoError(t, err)
+	require.Equal(t, []byte("cdefg"), data)
+}
+
+func TestRingBuffer_LargeWrite(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(5)
+
+	// Write data larger than capacity
+	rb.Write([]byte("abcdefghij"))
+
+	// Should contain last 5 bytes
+	data, err := rb.ReadLast(5)
+	require.NoError(t, err)
+	require.Equal(t, []byte("fghij"), data)
+}
+
+func TestRingBuffer_WrapAround(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(5)
+
+	// Fill buffer
+	rb.Write([]byte("abcde"))
+
+	// Write more to cause wrap-around
+	rb.Write([]byte("fgh"))
+
+	// Should contain "defgh"
+	data, err := rb.ReadLast(5)
+	require.NoError(t, err)
+	require.Equal(t, []byte("defgh"), data)
+
+	// Test reading last 3 bytes after wrap
+	data, err = rb.ReadLast(3)
+	require.NoError(t, err)
+	require.Equal(t, []byte("fgh"), data)
+}
+
+func TestRingBuffer_ReadLastEdgeCases(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(3)
+
+	// Write some data (5 bytes to a 3-byte buffer, so only last 3 bytes remain)
+	rb.Write([]byte("hello"))
+
+	// Test reading negative count
+	data, err := rb.ReadLast(-1)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "cannot read negative number of bytes")
+	require.Nil(t, data)
+
+	// Test reading zero bytes
+	data, err = rb.ReadLast(0)
+	require.NoError(t, err)
+	require.Nil(t, data)
+
+	// Test reading more than available (buffer has 3 bytes, try to read 10)
+	_, err = rb.ReadLast(10)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "requested 10 bytes but only 3 available")
+
+	// Test reading exact amount available
+	data, err = rb.ReadLast(3)
+	require.NoError(t, err)
+	require.Equal(t, []byte("llo"), data)
+}
+
+func TestRingBuffer_EmptyWrite(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(10)
+
+	// Write empty data
+	rb.Write([]byte{})
+
+	// Buffer should still be empty
+	_, err := rb.ReadLast(5)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "requested 5 bytes but only 0 available")
+}
+
+func TestRingBuffer_MultipleWrites(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(10)
+
+	// Write data in chunks
+	rb.Write([]byte("ab"))
+	rb.Write([]byte("cd"))
+	rb.Write([]byte("ef"))
+
+	data, err := rb.ReadLast(6)
+	require.NoError(t, err)
+	require.Equal(t, []byte("abcdef"), data)
+
+	// Test partial reads
+	data, err = rb.ReadLast(4)
+	require.NoError(t, err)
+	require.Equal(t, []byte("cdef"), data)
+
+	data, err = rb.ReadLast(2)
+	require.NoError(t, err)
+	require.Equal(t, []byte("ef"), data)
+}
+
+func TestRingBuffer_EdgeCaseEviction(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(3)
+
+	// Write data that will cause eviction
+	rb.Write([]byte("abc"))
+
+	// Write more to cause eviction
+	rb.Write([]byte("d"))
+
+	// Should now contain "bcd"
+	data, err := rb.ReadLast(3)
+	require.NoError(t, err)
+	require.Equal(t, []byte("bcd"), data)
+}
+
+func TestRingBuffer_ComplexWrapAroundScenario(t *testing.T) {
+	t.Parallel()
+
+	rb := newRingBuffer(8)
+
+	// Fill buffer
+	rb.Write([]byte("12345678"))
+
+	// Evict some and add more to create complex wrap scenario
+	rb.Write([]byte("abcd"))
+	data, err := rb.ReadLast(8)
+	require.NoError(t, err)
+	require.Equal(t, []byte("5678abcd"), data)
+
+	// Add more
+	rb.Write([]byte("xyz"))
+	data, err = rb.ReadLast(8)
+	require.NoError(t, err)
+	require.Equal(t, []byte("8abcdxyz"), data)
+
+	// Test reading various amounts from the end
+	data, err = rb.ReadLast(7)
+	require.NoError(t, err)
+	require.Equal(t, []byte("abcdxyz"), data)
+
+	data, err = rb.ReadLast(4)
+	require.NoError(t, err)
+	require.Equal(t, []byte("dxyz"), data)
+}
+
+// Benchmark tests for performance validation
+func BenchmarkRingBuffer_Write(b *testing.B) {
+	rb := newRingBuffer(64 * 1024 * 1024)   // 64MB for benchmarks
+	data := bytes.Repeat([]byte("x"), 1024) // 1KB writes
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		rb.Write(data)
+	}
+}
+
+func BenchmarkRingBuffer_ReadLast(b *testing.B) {
+	rb := newRingBuffer(64 * 1024 * 1024) // 64MB for benchmarks
+	// Fill buffer with test data
+	for i := 0; i < 64; i++ {
+		rb.Write(bytes.Repeat([]byte("x"), 1024))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, err := rb.ReadLast((i % 100) + 1)
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+}

agent/ls.go

@@ -11,23 +11,39 @@ import (
 	"strings"
 
 	"github.com/shirou/gopsutil/v4/disk"
+	"github.com/spf13/afero"
 	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/v2/coderd/httpapi"
 	"github.com/coder/coder/v2/codersdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 )
 
 var WindowsDriveRegex = regexp.MustCompile(`^[a-zA-Z]:\\$`)
 
-func (*agent) HandleLS(rw http.ResponseWriter, r *http.Request) {
+func (a *agent) HandleLS(rw http.ResponseWriter, r *http.Request) {
 	ctx := r.Context()
 
-	var query LSRequest
-	if !httpapi.Read(ctx, rw, r, &query) {
+	// An absolute path may be optionally provided, otherwise a path split into an
+	// array must be provided in the body (which can be relative).
+	query := r.URL.Query()
+	parser := httpapi.NewQueryParamParser()
+	path := parser.String(query, "", "path")
+	parser.ErrorExcessParams(query)
+	if len(parser.Errors) > 0 {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message:     "Query parameters have invalid values.",
+			Validations: parser.Errors,
+		})
 		return
 	}
 
-	resp, err := listFiles(query)
+	var req workspacesdk.LSRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	resp, err := listFiles(a.filesystem, path, req)
 	if err != nil {
 		status := http.StatusInternalServerError
 		switch {
@@ -46,58 +62,66 @@ func (*agent) HandleLS(rw http.ResponseWriter, r *http.Request) {
 	httpapi.Write(ctx, rw, http.StatusOK, resp)
 }
 
-func listFiles(query LSRequest) (LSResponse, error) {
-	var fullPath []string
-	switch query.Relativity {
-	case LSRelativityHome:
-		home, err := os.UserHomeDir()
-		if err != nil {
-			return LSResponse{}, xerrors.Errorf("failed to get user home directory: %w", err)
+func listFiles(fs afero.Fs, path string, query workspacesdk.LSRequest) (workspacesdk.LSResponse, error) {
+	absolutePathString := path
+	if absolutePathString != "" {
+		if !filepath.IsAbs(path) {
+			return workspacesdk.LSResponse{}, xerrors.Errorf("path must be absolute: %q", path)
 		}
-		fullPath = []string{home}
-	case LSRelativityRoot:
-		if runtime.GOOS == "windows" {
-			if len(query.Path) == 0 {
-				return listDrives()
+	} else {
+		var fullPath []string
+		switch query.Relativity {
+		case workspacesdk.LSRelativityHome:
+			home, err := os.UserHomeDir()
+			if err != nil {
+				return workspacesdk.LSResponse{}, xerrors.Errorf("failed to get user home directory: %w", err)
 			}
-			if !WindowsDriveRegex.MatchString(query.Path[0]) {
-				return LSResponse{}, xerrors.Errorf("invalid drive letter %q", query.Path[0])
+			fullPath = []string{home}
+		case workspacesdk.LSRelativityRoot:
+			if runtime.GOOS == "windows" {
+				if len(query.Path) == 0 {
+					return listDrives()
+				}
+				if !WindowsDriveRegex.MatchString(query.Path[0]) {
+					return workspacesdk.LSResponse{}, xerrors.Errorf("invalid drive letter %q", query.Path[0])
+				}
+			} else {
+				fullPath = []string{"/"}
 			}
-		} else {
-			fullPath = []string{"/"}
+		default:
+			return workspacesdk.LSResponse{}, xerrors.Errorf("unsupported relativity type %q", query.Relativity)
 		}
-	default:
-		return LSResponse{}, xerrors.Errorf("unsupported relativity type %q", query.Relativity)
-	}
 
-	fullPath = append(fullPath, query.Path...)
-	fullPathRelative := filepath.Join(fullPath...)
-	absolutePathString, err := filepath.Abs(fullPathRelative)
-	if err != nil {
-		return LSResponse{}, xerrors.Errorf("failed to get absolute path of %q: %w", fullPathRelative, err)
+		fullPath = append(fullPath, query.Path...)
+		fullPathRelative := filepath.Join(fullPath...)
+		var err error
+		absolutePathString, err = filepath.Abs(fullPathRelative)
+		if err != nil {
+			return workspacesdk.LSResponse{}, xerrors.Errorf("failed to get absolute path of %q: %w", fullPathRelative, err)
+		}
 	}
 
 	// codeql[go/path-injection] - The intent is to allow the user to navigate to any directory in their workspace.
-	f, err := os.Open(absolutePathString)
+	f, err := fs.Open(absolutePathString)
 	if err != nil {
-		return LSResponse{}, xerrors.Errorf("failed to open directory %q: %w", absolutePathString, err)
+		return workspacesdk.LSResponse{}, xerrors.Errorf("failed to open directory %q: %w", absolutePathString, err)
 	}
 	defer f.Close()
 
 	stat, err := f.Stat()
 	if err != nil {
-		return LSResponse{}, xerrors.Errorf("failed to stat directory %q: %w", absolutePathString, err)
+		return workspacesdk.LSResponse{}, xerrors.Errorf("failed to stat directory %q: %w", absolutePathString, err)
 	}
 
 	if !stat.IsDir() {
-		return LSResponse{}, xerrors.Errorf("path %q is not a directory", absolutePathString)
+		return workspacesdk.LSResponse{}, xerrors.Errorf("path %q is not a directory", absolutePathString)
 	}
 
 	// `contents` may be partially populated even if the operation fails midway.
-	contents, _ := f.ReadDir(-1)
-	respContents := make([]LSFile, 0, len(contents))
+	contents, _ := f.Readdir(-1)
+	respContents := make([]workspacesdk.LSFile, 0, len(contents))
 	for _, file := range contents {
-		respContents = append(respContents, LSFile{
+		respContents = append(respContents, workspacesdk.LSFile{
 			Name:               file.Name(),
 			AbsolutePathString: filepath.Join(absolutePathString, file.Name()),
 			IsDir:              file.IsDir(),
@@ -105,7 +129,7 @@ func listFiles(query LSRequest) (LSResponse, error) {
 	}
 
 	// Sort alphabetically: directories then files
-	slices.SortFunc(respContents, func(a, b LSFile) int {
+	slices.SortFunc(respContents, func(a, b workspacesdk.LSFile) int {
 		if a.IsDir && !b.IsDir {
 			return -1
 		}
@@ -117,35 +141,35 @@ func listFiles(query LSRequest) (LSResponse, error) {
 
 	absolutePath := pathToArray(absolutePathString)
 
-	return LSResponse{
+	return workspacesdk.LSResponse{
 		AbsolutePath:       absolutePath,
 		AbsolutePathString: absolutePathString,
 		Contents:           respContents,
 	}, nil
 }
 
-func listDrives() (LSResponse, error) {
+func listDrives() (workspacesdk.LSResponse, error) {
 	// disk.Partitions() will return partitions even if there was a failure to
 	// get one. Any errored partitions will not be returned.
 	partitionStats, err := disk.Partitions(true)
 	if err != nil && len(partitionStats) == 0 {
 		// Only return the error if there were no partitions returned.
-		return LSResponse{}, xerrors.Errorf("failed to get partitions: %w", err)
+		return workspacesdk.LSResponse{}, xerrors.Errorf("failed to get partitions: %w", err)
 	}
 
-	contents := make([]LSFile, 0, len(partitionStats))
+	contents := make([]workspacesdk.LSFile, 0, len(partitionStats))
 	for _, a := range partitionStats {
 		// Drive letters on Windows have a trailing separator as part of their name.
 		// i.e. `os.Open("C:")` does not work, but `os.Open("C:\\")` does.
 		name := a.Mountpoint + string(os.PathSeparator)
-		contents = append(contents, LSFile{
+		contents = append(contents, workspacesdk.LSFile{
 			Name:               name,
 			AbsolutePathString: name,
 			IsDir:              true,
 		})
 	}
 
-	return LSResponse{
+	return workspacesdk.LSResponse{
 		AbsolutePath:       []string{},
 		AbsolutePathString: "",
 		Contents:           contents,
@@ -163,36 +187,3 @@ func pathToArray(path string) []string {
 	}
 	return out
 }
-
-type LSRequest struct {
-	// e.g. [], ["repos", "coder"],
-	Path []string `json:"path"`
-	// Whether the supplied path is relative to the user's home directory,
-	// or the root directory.
-	Relativity LSRelativity `json:"relativity"`
-}
-
-type LSResponse struct {
-	AbsolutePath []string `json:"absolute_path"`
-	// Returned so clients can display the full path to the user, and
-	// copy it to configure file sync
-	// e.g. Windows: "C:\\Users\\coder"
-	//      Linux: "/home/coder"
-	AbsolutePathString string   `json:"absolute_path_string"`
-	Contents           []LSFile `json:"contents"`
-}
-
-type LSFile struct {
-	Name string `json:"name"`
-	// e.g. "C:\\Users\\coder\\hello.txt"
-	//      "/home/coder/hello.txt"
-	AbsolutePathString string `json:"absolute_path_string"`
-	IsDir              bool   `json:"is_dir"`
-}
-
-type LSRelativity string
-
-const (
-	LSRelativityRoot LSRelativity = "root"
-	LSRelativityHome LSRelativity = "home"
-)

agent/ls_internal_test.go

@@ -6,67 +6,103 @@ import (
 	"runtime"
 	"testing"
 
+	"github.com/spf13/afero"
 	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
 )
 
+type testFs struct {
+	afero.Fs
+}
+
+func newTestFs(base afero.Fs) *testFs {
+	return &testFs{
+		Fs: base,
+	}
+}
+
+func (*testFs) Open(name string) (afero.File, error) {
+	return nil, os.ErrPermission
+}
+
+func TestListFilesWithQueryParam(t *testing.T) {
+	t.Parallel()
+
+	fs := afero.NewMemMapFs()
+	query := workspacesdk.LSRequest{}
+	_, err := listFiles(fs, "not-relative", query)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "must be absolute")
+
+	tmpDir := t.TempDir()
+	err = fs.MkdirAll(tmpDir, 0o755)
+	require.NoError(t, err)
+
+	res, err := listFiles(fs, tmpDir, query)
+	require.NoError(t, err)
+	require.Len(t, res.Contents, 0)
+}
+
 func TestListFilesNonExistentDirectory(t *testing.T) {
 	t.Parallel()
 
-	query := LSRequest{
+	fs := afero.NewMemMapFs()
+	query := workspacesdk.LSRequest{
 		Path:       []string{"idontexist"},
-		Relativity: LSRelativityHome,
+		Relativity: workspacesdk.LSRelativityHome,
 	}
-	_, err := listFiles(query)
+	_, err := listFiles(fs, "", query)
 	require.ErrorIs(t, err, os.ErrNotExist)
 }
 
 func TestListFilesPermissionDenied(t *testing.T) {
 	t.Parallel()
 
-	if runtime.GOOS == "windows" {
-		t.Skip("creating an unreadable-by-user directory is non-trivial on Windows")
-	}
-
+	fs := newTestFs(afero.NewMemMapFs())
 	home, err := os.UserHomeDir()
 	require.NoError(t, err)
 
 	tmpDir := t.TempDir()
 
 	reposDir := filepath.Join(tmpDir, "repos")
-	err = os.Mkdir(reposDir, 0o000)
+	err = fs.MkdirAll(reposDir, 0o000)
 	require.NoError(t, err)
 
 	rel, err := filepath.Rel(home, reposDir)
 	require.NoError(t, err)
 
-	query := LSRequest{
+	query := workspacesdk.LSRequest{
 		Path:       pathToArray(rel),
-		Relativity: LSRelativityHome,
+		Relativity: workspacesdk.LSRelativityHome,
 	}
-	_, err = listFiles(query)
+	_, err = listFiles(fs, "", query)
 	require.ErrorIs(t, err, os.ErrPermission)
 }
 
 func TestListFilesNotADirectory(t *testing.T) {
 	t.Parallel()
 
+	fs := afero.NewMemMapFs()
 	home, err := os.UserHomeDir()
 	require.NoError(t, err)
 
 	tmpDir := t.TempDir()
+	err = fs.MkdirAll(tmpDir, 0o755)
+	require.NoError(t, err)
 
 	filePath := filepath.Join(tmpDir, "file.txt")
-	err = os.WriteFile(filePath, []byte("content"), 0o600)
+	err = afero.WriteFile(fs, filePath, []byte("content"), 0o600)
 	require.NoError(t, err)
 
 	rel, err := filepath.Rel(home, filePath)
 	require.NoError(t, err)
 
-	query := LSRequest{
+	query := workspacesdk.LSRequest{
 		Path:       pathToArray(rel),
-		Relativity: LSRelativityHome,
+		Relativity: workspacesdk.LSRelativityHome,
 	}
-	_, err = listFiles(query)
+	_, err = listFiles(fs, "", query)
 	require.ErrorContains(t, err, "is not a directory")
 }
 
@@ -76,7 +112,7 @@ func TestListFilesSuccess(t *testing.T) {
 	tc := []struct {
 		name       string
 		baseFunc   func(t *testing.T) string
-		relativity LSRelativity
+		relativity workspacesdk.LSRelativity
 	}{
 		{
 			name: "home",
@@ -85,7 +121,7 @@ func TestListFilesSuccess(t *testing.T) {
 				require.NoError(t, err)
 				return home
 			},
-			relativity: LSRelativityHome,
+			relativity: workspacesdk.LSRelativityHome,
 		},
 		{
 			name: "root",
@@ -95,7 +131,7 @@ func TestListFilesSuccess(t *testing.T) {
 				}
 				return "/"
 			},
-			relativity: LSRelativityRoot,
+			relativity: workspacesdk.LSRelativityRoot,
 		},
 	}
 
@@ -104,19 +140,20 @@ func TestListFilesSuccess(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 
+			fs := afero.NewMemMapFs()
 			base := tc.baseFunc(t)
 			tmpDir := t.TempDir()
 
 			reposDir := filepath.Join(tmpDir, "repos")
-			err := os.Mkdir(reposDir, 0o755)
+			err := fs.MkdirAll(reposDir, 0o755)
 			require.NoError(t, err)
 
 			downloadsDir := filepath.Join(tmpDir, "Downloads")
-			err = os.Mkdir(downloadsDir, 0o755)
+			err = fs.MkdirAll(downloadsDir, 0o755)
 			require.NoError(t, err)
 
 			textFile := filepath.Join(tmpDir, "file.txt")
-			err = os.WriteFile(textFile, []byte("content"), 0o600)
+			err = afero.WriteFile(fs, textFile, []byte("content"), 0o600)
 			require.NoError(t, err)
 
 			var queryComponents []string
@@ -129,16 +166,16 @@ func TestListFilesSuccess(t *testing.T) {
 				queryComponents = pathToArray(rel)
 			}
 
-			query := LSRequest{
+			query := workspacesdk.LSRequest{
 				Path:       queryComponents,
 				Relativity: tc.relativity,
 			}
-			resp, err := listFiles(query)
+			resp, err := listFiles(fs, "", query)
 			require.NoError(t, err)
 
 			require.Equal(t, tmpDir, resp.AbsolutePathString)
 			// Output is sorted
-			require.Equal(t, []LSFile{
+			require.Equal(t, []workspacesdk.LSFile{
 				{
 					Name:               "Downloads",
 					AbsolutePathString: downloadsDir,
@@ -166,43 +203,44 @@ func TestListFilesListDrives(t *testing.T) {
 		t.Skip("skipping test on non-Windows OS")
 	}
 
-	query := LSRequest{
+	fs := afero.NewOsFs()
+	query := workspacesdk.LSRequest{
 		Path:       []string{},
-		Relativity: LSRelativityRoot,
+		Relativity: workspacesdk.LSRelativityRoot,
 	}
-	resp, err := listFiles(query)
+	resp, err := listFiles(fs, "", query)
 	require.NoError(t, err)
-	require.Contains(t, resp.Contents, LSFile{
+	require.Contains(t, resp.Contents, workspacesdk.LSFile{
 		Name:               "C:\\",
 		AbsolutePathString: "C:\\",
 		IsDir:              true,
 	})
 
-	query = LSRequest{
+	query = workspacesdk.LSRequest{
 		Path:       []string{"C:\\"},
-		Relativity: LSRelativityRoot,
+		Relativity: workspacesdk.LSRelativityRoot,
 	}
-	resp, err = listFiles(query)
+	resp, err = listFiles(fs, "", query)
 	require.NoError(t, err)
 
-	query = LSRequest{
+	query = workspacesdk.LSRequest{
 		Path:       resp.AbsolutePath,
-		Relativity: LSRelativityRoot,
+		Relativity: workspacesdk.LSRelativityRoot,
 	}
-	resp, err = listFiles(query)
+	resp, err = listFiles(fs, "", query)
 	require.NoError(t, err)
 	// System directory should always exist
-	require.Contains(t, resp.Contents, LSFile{
+	require.Contains(t, resp.Contents, workspacesdk.LSFile{
 		Name:               "Windows",
 		AbsolutePathString: "C:\\Windows",
 		IsDir:              true,
 	})
 
-	query = LSRequest{
+	query = workspacesdk.LSRequest{
 		// Network drives are not supported.
 		Path:       []string{"\\sshfs\\work"},
-		Relativity: LSRelativityRoot,
+		Relativity: workspacesdk.LSRelativityRoot,
 	}
-	resp, err = listFiles(query)
+	resp, err = listFiles(fs, "", query)
 	require.ErrorContains(t, err, "drive")
 }

agent/ports_supported.go

@@ -3,16 +3,23 @@
 package agent
 
 import (
+	"sync"
 	"time"
 
 	"github.com/cakturk/go-netstat/netstat"
 	"golang.org/x/xerrors"
 
 	"github.com/coder/coder/v2/codersdk"
-	"github.com/coder/coder/v2/codersdk/workspacesdk"
 )
 
-func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
+type osListeningPortsGetter struct {
+	cacheDuration time.Duration
+	mut           sync.Mutex
+	ports         []codersdk.WorkspaceAgentListeningPort
+	mtime         time.Time
+}
+
+func (lp *osListeningPortsGetter) GetListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
 	lp.mut.Lock()
 	defer lp.mut.Unlock()
 
@@ -33,12 +40,7 @@ func (lp *listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentL
 	seen := make(map[uint16]struct{}, len(tabs))
 	ports := []codersdk.WorkspaceAgentListeningPort{}
 	for _, tab := range tabs {
-		if tab.LocalAddr == nil || tab.LocalAddr.Port < workspacesdk.AgentMinimumListeningPort {
-			continue
-		}
-
-		// Ignore ports that we've been told to ignore.
-		if _, ok := lp.ignorePorts[int(tab.LocalAddr.Port)]; ok {
+		if tab.LocalAddr == nil {
 			continue
 		}
 

agent/ports_supported_internal_test.go

@@ -0,0 +1,45 @@
+//go:build linux || (windows && amd64)
+
+package agent
+
+import (
+	"net"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestOSListeningPortsGetter(t *testing.T) {
+	t.Parallel()
+
+	uut := &osListeningPortsGetter{
+		cacheDuration: 1 * time.Hour,
+	}
+
+	l, err := net.Listen("tcp", "localhost:0")
+	require.NoError(t, err)
+	defer l.Close()
+
+	ports, err := uut.GetListeningPorts()
+	require.NoError(t, err)
+	found := false
+	for _, port := range ports {
+		// #nosec G115 - Safe conversion as TCP port numbers are within uint16 range (0-65535)
+		if port.Port == uint16(l.Addr().(*net.TCPAddr).Port) {
+			found = true
+			break
+		}
+	}
+	require.True(t, found)
+
+	// check that we cache the ports
+	err = l.Close()
+	require.NoError(t, err)
+	portsNew, err := uut.GetListeningPorts()
+	require.NoError(t, err)
+	require.Equal(t, ports, portsNew)
+
+	// note that it's unsafe to try to assert that a port does not exist in the response
+	// because the OS may reallocate the port very quickly.
+}

agent/ports_unsupported.go

@@ -2,9 +2,17 @@
 
 package agent
 
-import "github.com/coder/coder/v2/codersdk"
+import (
+	"time"
 
-func (*listeningPortsHandler) getListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
+	"github.com/coder/coder/v2/codersdk"
+)
+
+type osListeningPortsGetter struct {
+	cacheDuration time.Duration
+}
+
+func (*osListeningPortsGetter) GetListeningPorts() ([]codersdk.WorkspaceAgentListeningPort, error) {
 	// Can't scan for ports on non-linux or non-windows_amd64 systems at the
 	// moment. The UI will not show any "no ports found" message to the user, so
 	// the user won't suspect a thing.

agent/reconnectingpty/screen.go

@@ -25,6 +25,7 @@ import (
 
 // screenReconnectingPTY provides a reconnectable PTY via `screen`.
 type screenReconnectingPTY struct {
+	logger  slog.Logger
 	execer  agentexec.Execer
 	command *pty.Cmd
 
@@ -62,6 +63,7 @@ type screenReconnectingPTY struct {
 // own which causes it to spawn with the specified size.
 func newScreen(ctx context.Context, logger slog.Logger, execer agentexec.Execer, cmd *pty.Cmd, options *Options) *screenReconnectingPTY {
 	rpty := &screenReconnectingPTY{
+		logger:  logger,
 		execer:  execer,
 		command: cmd,
 		metrics: options.Metrics,
@@ -173,6 +175,7 @@ func (rpty *screenReconnectingPTY) Attach(ctx context.Context, _ string, conn ne
 
 	ptty, process, err := rpty.doAttach(ctx, conn, height, width, logger)
 	if err != nil {
+		logger.Debug(ctx, "unable to attach to screen reconnecting pty", slog.Error(err))
 		if errors.Is(err, context.Canceled) {
 			// Likely the process was too short-lived and canceled the version command.
 			// TODO: Is it worth distinguishing between that and a cancel from the
@@ -182,6 +185,7 @@ func (rpty *screenReconnectingPTY) Attach(ctx context.Context, _ string, conn ne
 		}
 		return err
 	}
+	logger.Debug(ctx, "attached to screen reconnecting pty")
 
 	defer func() {
 		// Log only for debugging since the process might have already exited on its
@@ -403,6 +407,7 @@ func (rpty *screenReconnectingPTY) Wait() {
 }
 
 func (rpty *screenReconnectingPTY) Close(err error) {
+	rpty.logger.Debug(context.Background(), "closing screen reconnecting pty", slog.Error(err))
 	// The closing state change will be handled by the lifecycle.
 	rpty.state.setState(StateClosing, err)
 }

agent/unit/graph.go

@@ -0,0 +1,174 @@
+package unit
+
+import (
+	"fmt"
+	"sync"
+
+	"golang.org/x/xerrors"
+	"gonum.org/v1/gonum/graph/encoding/dot"
+	"gonum.org/v1/gonum/graph/simple"
+	"gonum.org/v1/gonum/graph/topo"
+)
+
+// Graph provides a bidirectional interface over gonum's directed graph implementation.
+// While the underlying gonum graph is directed, we overlay bidirectional semantics
+// by distinguishing between forward and reverse edges. Wanting and being wanted by
+// other units are related but different concepts that have different graph traversal
+// implications when Units update their status.
+//
+// The graph stores edge types to represent different relationships between units,
+// allowing for domain-specific semantics beyond simple connectivity.
+type Graph[EdgeType, VertexType comparable] struct {
+	mu sync.RWMutex
+	// The underlying gonum graph. It stores vertices and edges without knowing about the types of the vertices and edges.
+	gonumGraph *simple.DirectedGraph
+	// Maps vertices to their IDs so that a gonum vertex ID can be used to lookup the vertex type.
+	vertexToID map[VertexType]int64
+	// Maps vertex IDs to their types so that a vertex type can be used to lookup the gonum vertex ID.
+	idToVertex map[int64]VertexType
+	// The next ID to assign to a vertex.
+	nextID int64
+	// Store edge types by "fromID->toID" key. This is used to lookup the edge type for a given edge.
+	edgeTypes map[string]EdgeType
+}
+
+// Edge is a convenience type for representing an edge in the graph.
+// It encapsulates the from and to vertices and the edge type itself.
+type Edge[EdgeType, VertexType comparable] struct {
+	From VertexType
+	To   VertexType
+	Edge EdgeType
+}
+
+// AddEdge adds an edge to the graph. It initializes the graph and metadata on first use,
+// checks for cycles, and adds the edge to the gonum graph.
+func (g *Graph[EdgeType, VertexType]) AddEdge(from, to VertexType, edge EdgeType) error {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	if g.gonumGraph == nil {
+		g.gonumGraph = simple.NewDirectedGraph()
+		g.vertexToID = make(map[VertexType]int64)
+		g.idToVertex = make(map[int64]VertexType)
+		g.edgeTypes = make(map[string]EdgeType)
+		g.nextID = 1
+	}
+
+	fromID := g.getOrCreateVertexID(from)
+	toID := g.getOrCreateVertexID(to)
+
+	if g.canReach(to, from) {
+		return xerrors.Errorf("adding edge (%v -> %v): %w", from, to, ErrCycleDetected)
+	}
+
+	g.gonumGraph.SetEdge(simple.Edge{F: simple.Node(fromID), T: simple.Node(toID)})
+
+	edgeKey := fmt.Sprintf("%d->%d", fromID, toID)
+	g.edgeTypes[edgeKey] = edge
+
+	return nil
+}
+
+// GetForwardAdjacentVertices returns all the edges that originate from the given vertex.
+func (g *Graph[EdgeType, VertexType]) GetForwardAdjacentVertices(from VertexType) []Edge[EdgeType, VertexType] {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+
+	fromID, exists := g.vertexToID[from]
+	if !exists {
+		return []Edge[EdgeType, VertexType]{}
+	}
+
+	edges := []Edge[EdgeType, VertexType]{}
+	toNodes := g.gonumGraph.From(fromID)
+	for toNodes.Next() {
+		toID := toNodes.Node().ID()
+		to := g.idToVertex[toID]
+
+		// Get the edge type
+		edgeKey := fmt.Sprintf("%d->%d", fromID, toID)
+		edgeType := g.edgeTypes[edgeKey]
+
+		edges = append(edges, Edge[EdgeType, VertexType]{From: from, To: to, Edge: edgeType})
+	}
+
+	return edges
+}
+
+// GetReverseAdjacentVertices returns all the edges that terminate at the given vertex.
+func (g *Graph[EdgeType, VertexType]) GetReverseAdjacentVertices(to VertexType) []Edge[EdgeType, VertexType] {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+
+	toID, exists := g.vertexToID[to]
+	if !exists {
+		return []Edge[EdgeType, VertexType]{}
+	}
+
+	edges := []Edge[EdgeType, VertexType]{}
+	fromNodes := g.gonumGraph.To(toID)
+	for fromNodes.Next() {
+		fromID := fromNodes.Node().ID()
+		from := g.idToVertex[fromID]
+
+		// Get the edge type
+		edgeKey := fmt.Sprintf("%d->%d", fromID, toID)
+		edgeType := g.edgeTypes[edgeKey]
+
+		edges = append(edges, Edge[EdgeType, VertexType]{From: from, To: to, Edge: edgeType})
+	}
+
+	return edges
+}
+
+// getOrCreateVertexID returns the ID for a vertex, creating it if it doesn't exist.
+func (g *Graph[EdgeType, VertexType]) getOrCreateVertexID(vertex VertexType) int64 {
+	if id, exists := g.vertexToID[vertex]; exists {
+		return id
+	}
+
+	id := g.nextID
+	g.nextID++
+	g.vertexToID[vertex] = id
+	g.idToVertex[id] = vertex
+
+	// Add the node to the gonum graph
+	g.gonumGraph.AddNode(simple.Node(id))
+
+	return id
+}
+
+// canReach checks if there is a path from the start vertex to the end vertex.
+func (g *Graph[EdgeType, VertexType]) canReach(start, end VertexType) bool {
+	if start == end {
+		return true
+	}
+
+	startID, startExists := g.vertexToID[start]
+	endID, endExists := g.vertexToID[end]
+
+	if !startExists || !endExists {
+		return false
+	}
+
+	// Use gonum's built-in path existence check
+	return topo.PathExistsIn(g.gonumGraph, simple.Node(startID), simple.Node(endID))
+}
+
+// ToDOT exports the graph to DOT format for visualization
+func (g *Graph[EdgeType, VertexType]) ToDOT(name string) (string, error) {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+
+	if g.gonumGraph == nil {
+		return "", xerrors.New("graph is not initialized")
+	}
+
+	// Marshal the graph to DOT format
+	dotBytes, err := dot.Marshal(g.gonumGraph, name, "", "  ")
+	if err != nil {
+		return "", xerrors.Errorf("failed to marshal graph to DOT: %w", err)
+	}
+
+	return string(dotBytes), nil
+}

agent/unit/graph_test.go

@@ -0,0 +1,452 @@
+// Package unit_test provides tests for the unit package.
+//
+// DOT Graph Testing:
+// The graph tests use golden files for DOT representation verification.
+// To update the golden files:
+// make gen/golden-files
+//
+// The golden files contain the expected DOT representation and can be easily
+// inspected, version controlled, and updated when the graph structure changes.
+package unit_test
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/cryptorand"
+)
+
+type testGraphEdge string
+
+const (
+	testEdgeStarted   testGraphEdge = "started"
+	testEdgeCompleted testGraphEdge = "completed"
+)
+
+type testGraphVertex struct {
+	Name string
+}
+
+type (
+	testGraph = unit.Graph[testGraphEdge, *testGraphVertex]
+	testEdge  = unit.Edge[testGraphEdge, *testGraphVertex]
+)
+
+// randInt generates a random integer in the range [0, limit).
+func randInt(limit int) int {
+	if limit <= 0 {
+		return 0
+	}
+	n, err := cryptorand.Int63n(int64(limit))
+	if err != nil {
+		return 0
+	}
+	return int(n)
+}
+
+// UpdateGoldenFiles indicates golden files should be updated.
+// To update the golden files:
+// make gen/golden-files
+var UpdateGoldenFiles = flag.Bool("update", false, "update .golden files")
+
+// assertDOTGraph requires that the graph's DOT representation matches the golden file
+func assertDOTGraph(t *testing.T, graph *testGraph, goldenName string) {
+	t.Helper()
+
+	dot, err := graph.ToDOT(goldenName)
+	require.NoError(t, err)
+
+	goldenFile := filepath.Join("testdata", goldenName+".golden")
+	if *UpdateGoldenFiles {
+		t.Logf("update golden file for: %q: %s", goldenName, goldenFile)
+		err := os.MkdirAll(filepath.Dir(goldenFile), 0o755)
+		require.NoError(t, err, "want no error creating golden file directory")
+		err = os.WriteFile(goldenFile, []byte(dot), 0o600)
+		require.NoError(t, err, "update golden file")
+	}
+
+	expected, err := os.ReadFile(goldenFile)
+	require.NoError(t, err, "read golden file, run \"make gen/golden-files\" and commit the changes")
+
+	// Normalize line endings for cross-platform compatibility
+	expected = normalizeLineEndings(expected)
+	normalizedDot := normalizeLineEndings([]byte(dot))
+
+	assert.Empty(t, cmp.Diff(string(expected), string(normalizedDot)), "golden file mismatch (-want +got): %s, run \"make gen/golden-files\", verify and commit the changes", goldenFile)
+}
+
+// normalizeLineEndings ensures that all line endings are normalized to \n.
+// Required for Windows compatibility.
+func normalizeLineEndings(content []byte) []byte {
+	content = bytes.ReplaceAll(content, []byte("\r\n"), []byte("\n"))
+	content = bytes.ReplaceAll(content, []byte("\r"), []byte("\n"))
+	return content
+}
+
+func TestGraph(t *testing.T) {
+	t.Parallel()
+
+	testFuncs := map[string]func(t *testing.T) *unit.Graph[testGraphEdge, *testGraphVertex]{
+		"ForwardAndReverseEdges": func(t *testing.T) *unit.Graph[testGraphEdge, *testGraphVertex] {
+			graph := &unit.Graph[testGraphEdge, *testGraphVertex]{}
+			unit1 := &testGraphVertex{Name: "unit1"}
+			unit2 := &testGraphVertex{Name: "unit2"}
+			unit3 := &testGraphVertex{Name: "unit3"}
+			err := graph.AddEdge(unit1, unit2, testEdgeCompleted)
+			require.NoError(t, err)
+			err = graph.AddEdge(unit1, unit3, testEdgeStarted)
+			require.NoError(t, err)
+
+			// Check for forward edge
+			vertices := graph.GetForwardAdjacentVertices(unit1)
+			require.Len(t, vertices, 2)
+			// Unit 1 depends on the completion of Unit2
+			require.Contains(t, vertices, testEdge{
+				From: unit1,
+				To:   unit2,
+				Edge: testEdgeCompleted,
+			})
+			// Unit 1 depends on the start of Unit3
+			require.Contains(t, vertices, testEdge{
+				From: unit1,
+				To:   unit3,
+				Edge: testEdgeStarted,
+			})
+
+			// Check for reverse edges
+			unit2ReverseEdges := graph.GetReverseAdjacentVertices(unit2)
+			require.Len(t, unit2ReverseEdges, 1)
+			// Unit 2 must be completed before Unit 1 can start
+			require.Contains(t, unit2ReverseEdges, testEdge{
+				From: unit1,
+				To:   unit2,
+				Edge: testEdgeCompleted,
+			})
+
+			unit3ReverseEdges := graph.GetReverseAdjacentVertices(unit3)
+			require.Len(t, unit3ReverseEdges, 1)
+			// Unit 3 must be started before Unit 1 can complete
+			require.Contains(t, unit3ReverseEdges, testEdge{
+				From: unit1,
+				To:   unit3,
+				Edge: testEdgeStarted,
+			})
+
+			return graph
+		},
+		"SelfReference": func(t *testing.T) *testGraph {
+			graph := &testGraph{}
+			unit1 := &testGraphVertex{Name: "unit1"}
+			err := graph.AddEdge(unit1, unit1, testEdgeCompleted)
+			require.ErrorIs(t, err, unit.ErrCycleDetected)
+
+			return graph
+		},
+		"Cycle": func(t *testing.T) *testGraph {
+			graph := &testGraph{}
+			unit1 := &testGraphVertex{Name: "unit1"}
+			unit2 := &testGraphVertex{Name: "unit2"}
+			err := graph.AddEdge(unit1, unit2, testEdgeCompleted)
+			require.NoError(t, err)
+			err = graph.AddEdge(unit2, unit1, testEdgeStarted)
+			require.ErrorIs(t, err, unit.ErrCycleDetected)
+
+			return graph
+		},
+		"MultipleDependenciesSameStatus": func(t *testing.T) *testGraph {
+			graph := &testGraph{}
+			unit1 := &testGraphVertex{Name: "unit1"}
+			unit2 := &testGraphVertex{Name: "unit2"}
+			unit3 := &testGraphVertex{Name: "unit3"}
+			unit4 := &testGraphVertex{Name: "unit4"}
+
+			// Unit1 depends on completion of both unit2 and unit3 (same status type)
+			err := graph.AddEdge(unit1, unit2, testEdgeCompleted)
+			require.NoError(t, err)
+			err = graph.AddEdge(unit1, unit3, testEdgeCompleted)
+			require.NoError(t, err)
+
+			// Unit1 also depends on starting of unit4 (different status type)
+			err = graph.AddEdge(unit1, unit4, testEdgeStarted)
+			require.NoError(t, err)
+
+			// Check that unit1 has 3 forward dependencies
+			forwardEdges := graph.GetForwardAdjacentVertices(unit1)
+			require.Len(t, forwardEdges, 3)
+
+			// Verify all expected dependencies exist
+			expectedDependencies := []testEdge{
+				{From: unit1, To: unit2, Edge: testEdgeCompleted},
+				{From: unit1, To: unit3, Edge: testEdgeCompleted},
+				{From: unit1, To: unit4, Edge: testEdgeStarted},
+			}
+
+			for _, expected := range expectedDependencies {
+				require.Contains(t, forwardEdges, expected)
+			}
+
+			// Check reverse dependencies
+			unit2ReverseEdges := graph.GetReverseAdjacentVertices(unit2)
+			require.Len(t, unit2ReverseEdges, 1)
+			require.Contains(t, unit2ReverseEdges, testEdge{
+				From: unit1, To: unit2, Edge: testEdgeCompleted,
+			})
+
+			unit3ReverseEdges := graph.GetReverseAdjacentVertices(unit3)
+			require.Len(t, unit3ReverseEdges, 1)
+			require.Contains(t, unit3ReverseEdges, testEdge{
+				From: unit1, To: unit3, Edge: testEdgeCompleted,
+			})
+
+			unit4ReverseEdges := graph.GetReverseAdjacentVertices(unit4)
+			require.Len(t, unit4ReverseEdges, 1)
+			require.Contains(t, unit4ReverseEdges, testEdge{
+				From: unit1, To: unit4, Edge: testEdgeStarted,
+			})
+
+			return graph
+		},
+	}
+
+	for testName, testFunc := range testFuncs {
+		var graph *testGraph
+		t.Run(testName, func(t *testing.T) {
+			t.Parallel()
+			graph = testFunc(t)
+			assertDOTGraph(t, graph, testName)
+		})
+	}
+}
+
+func TestGraphThreadSafety(t *testing.T) {
+	t.Parallel()
+
+	t.Run("ConcurrentReadWrite", func(t *testing.T) {
+		t.Parallel()
+
+		graph := &testGraph{}
+		var wg sync.WaitGroup
+		const numWriters = 50
+		const numReaders = 100
+		const operationsPerWriter = 1000
+		const operationsPerReader = 2000
+
+		barrier := make(chan struct{})
+		// Launch writers
+		for i := 0; i < numWriters; i++ {
+			wg.Add(1)
+			go func(writerID int) {
+				defer wg.Done()
+				<-barrier
+				for j := 0; j < operationsPerWriter; j++ {
+					from := &testGraphVertex{Name: fmt.Sprintf("writer-%d-%d", writerID, j)}
+					to := &testGraphVertex{Name: fmt.Sprintf("writer-%d-%d", writerID, j+1)}
+					graph.AddEdge(from, to, testEdgeCompleted)
+				}
+			}(i)
+		}
+
+		// Launch readers
+		readerResults := make([]struct {
+			panicked  bool
+			readCount int
+		}, numReaders)
+
+		for i := 0; i < numReaders; i++ {
+			wg.Add(1)
+			go func(readerID int) {
+				defer wg.Done()
+				<-barrier
+				defer func() {
+					if r := recover(); r != nil {
+						readerResults[readerID].panicked = true
+					}
+				}()
+
+				readCount := 0
+				for j := 0; j < operationsPerReader; j++ {
+					// Create a test vertex and read
+					testUnit := &testGraphVertex{Name: fmt.Sprintf("test-reader-%d-%d", readerID, j)}
+					forwardEdges := graph.GetForwardAdjacentVertices(testUnit)
+					reverseEdges := graph.GetReverseAdjacentVertices(testUnit)
+
+					// Just verify no panics (results may be nil for non-existent vertices)
+					_ = forwardEdges
+					_ = reverseEdges
+					readCount++
+				}
+				readerResults[readerID].readCount = readCount
+			}(i)
+		}
+
+		close(barrier)
+		wg.Wait()
+
+		// Verify no panics occurred in readers
+		for i, result := range readerResults {
+			require.False(t, result.panicked, "reader %d panicked", i)
+			require.Equal(t, operationsPerReader, result.readCount, "reader %d should have performed expected reads", i)
+		}
+	})
+
+	t.Run("ConcurrentCycleDetection", func(t *testing.T) {
+		t.Parallel()
+
+		graph := &testGraph{}
+
+		// Pre-create chain: A→B→C→D
+		unitA := &testGraphVertex{Name: "A"}
+		unitB := &testGraphVertex{Name: "B"}
+		unitC := &testGraphVertex{Name: "C"}
+		unitD := &testGraphVertex{Name: "D"}
+
+		err := graph.AddEdge(unitA, unitB, testEdgeCompleted)
+		require.NoError(t, err)
+		err = graph.AddEdge(unitB, unitC, testEdgeCompleted)
+		require.NoError(t, err)
+		err = graph.AddEdge(unitC, unitD, testEdgeCompleted)
+		require.NoError(t, err)
+
+		barrier := make(chan struct{})
+		var wg sync.WaitGroup
+		const numGoroutines = 50
+		cycleErrors := make([]error, numGoroutines)
+
+		// Launch goroutines trying to add D→A (creates cycle)
+		for i := 0; i < numGoroutines; i++ {
+			wg.Add(1)
+			go func(goroutineID int) {
+				defer wg.Done()
+				<-barrier
+				err := graph.AddEdge(unitD, unitA, testEdgeCompleted)
+				cycleErrors[goroutineID] = err
+			}(i)
+		}
+
+		close(barrier)
+		wg.Wait()
+
+		// Verify all attempts correctly returned cycle error
+		for i, err := range cycleErrors {
+			require.Error(t, err, "goroutine %d should have detected cycle", i)
+			require.ErrorIs(t, err, unit.ErrCycleDetected)
+		}
+
+		// Verify graph remains valid (original chain intact)
+		dot, err := graph.ToDOT("test")
+		require.NoError(t, err)
+		require.NotEmpty(t, dot)
+	})
+
+	t.Run("ConcurrentToDOT", func(t *testing.T) {
+		t.Parallel()
+
+		graph := &testGraph{}
+
+		// Pre-populate graph
+		for i := 0; i < 20; i++ {
+			from := &testGraphVertex{Name: fmt.Sprintf("dot-unit-%d", i)}
+			to := &testGraphVertex{Name: fmt.Sprintf("dot-unit-%d", i+1)}
+			err := graph.AddEdge(from, to, testEdgeCompleted)
+			require.NoError(t, err)
+		}
+
+		barrier := make(chan struct{})
+		var wg sync.WaitGroup
+		const numReaders = 100
+		const numWriters = 20
+		dotResults := make([]string, numReaders)
+
+		// Launch readers calling ToDOT
+		dotErrors := make([]error, numReaders)
+		for i := 0; i < numReaders; i++ {
+			wg.Add(1)
+			go func(readerID int) {
+				defer wg.Done()
+				<-barrier
+				dot, err := graph.ToDOT(fmt.Sprintf("test-%d", readerID))
+				dotErrors[readerID] = err
+				if err == nil {
+					dotResults[readerID] = dot
+				}
+			}(i)
+		}
+
+		// Launch writers adding edges
+		for i := 0; i < numWriters; i++ {
+			wg.Add(1)
+			go func(writerID int) {
+				defer wg.Done()
+				<-barrier
+				from := &testGraphVertex{Name: fmt.Sprintf("writer-dot-%d", writerID)}
+				to := &testGraphVertex{Name: fmt.Sprintf("writer-dot-target-%d", writerID)}
+				graph.AddEdge(from, to, testEdgeCompleted)
+			}(i)
+		}
+
+		close(barrier)
+		wg.Wait()
+
+		// Verify no errors occurred during DOT generation
+		for i, err := range dotErrors {
+			require.NoError(t, err, "DOT generation error at index %d", i)
+		}
+
+		// Verify all DOT results are valid
+		for i, dot := range dotResults {
+			require.NotEmpty(t, dot, "DOT result %d should not be empty", i)
+		}
+	})
+}
+
+func BenchmarkGraph_ConcurrentMixedOperations(b *testing.B) {
+	graph := &testGraph{}
+	var wg sync.WaitGroup
+	const numGoroutines = 200
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		// Launch goroutines performing random operations
+		for j := 0; j < numGoroutines; j++ {
+			wg.Add(1)
+			go func(goroutineID int) {
+				defer wg.Done()
+				operationCount := 0
+
+				for operationCount < 50 {
+					operation := float32(randInt(100)) / 100.0
+
+					if operation < 0.6 { // 60% reads
+						// Read operation
+						testUnit := &testGraphVertex{Name: fmt.Sprintf("bench-read-%d-%d", goroutineID, operationCount)}
+						forwardEdges := graph.GetForwardAdjacentVertices(testUnit)
+						reverseEdges := graph.GetReverseAdjacentVertices(testUnit)
+
+						// Just verify no panics (results may be nil for non-existent vertices)
+						_ = forwardEdges
+						_ = reverseEdges
+					} else { // 40% writes
+						// Write operation
+						from := &testGraphVertex{Name: fmt.Sprintf("bench-write-%d-%d", goroutineID, operationCount)}
+						to := &testGraphVertex{Name: fmt.Sprintf("bench-write-target-%d-%d", goroutineID, operationCount)}
+						graph.AddEdge(from, to, testEdgeCompleted)
+					}
+
+					operationCount++
+				}
+			}(j)
+		}
+
+		wg.Wait()
+	}
+}

agent/unit/manager.go

@@ -0,0 +1,290 @@
+package unit
+
+import (
+	"errors"
+	"fmt"
+	"sync"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/util/slice"
+)
+
+var (
+	ErrUnitIDRequired           = xerrors.New("unit name is required")
+	ErrUnitNotFound             = xerrors.New("unit not found")
+	ErrUnitAlreadyRegistered    = xerrors.New("unit already registered")
+	ErrCannotUpdateOtherUnit    = xerrors.New("cannot update other unit's status")
+	ErrDependenciesNotSatisfied = xerrors.New("unit dependencies not satisfied")
+	ErrSameStatusAlreadySet     = xerrors.New("same status already set")
+	ErrCycleDetected            = xerrors.New("cycle detected")
+	ErrFailedToAddDependency    = xerrors.New("failed to add dependency")
+)
+
+// Status represents the status of a unit.
+type Status string
+
+var _ fmt.Stringer = Status("")
+
+func (s Status) String() string {
+	if s == StatusNotRegistered {
+		return "not registered"
+	}
+	return string(s)
+}
+
+// Status constants for dependency tracking.
+const (
+	StatusNotRegistered Status = ""
+	StatusPending       Status = "pending"
+	StatusStarted       Status = "started"
+	StatusComplete      Status = "completed"
+)
+
+// ID provides a type narrowed representation of the unique identifier of a unit.
+type ID string
+
+// Unit represents a point-in-time snapshot of a vertex in the dependency graph.
+// Units may depend on other units, or be depended on by other units. The unit struct
+// is not aware of updates made to the dependency graph after it is initialized and should
+// not be cached.
+type Unit struct {
+	id     ID
+	status Status
+	// ready is true if all dependencies are satisfied.
+	// It does not have an accessor method on Unit, because a unit cannot know whether it is ready.
+	// Only the Manager can calculate whether a unit is ready based on knowledge of the dependency graph.
+	// To discourage use of an outdated readiness value, only the Manager should set and return this field.
+	ready bool
+}
+
+func (u Unit) ID() ID {
+	return u.id
+}
+
+func (u Unit) Status() Status {
+	return u.status
+}
+
+// Dependency represents a dependency relationship between units.
+type Dependency struct {
+	Unit           ID
+	DependsOn      ID
+	RequiredStatus Status
+	CurrentStatus  Status
+	IsSatisfied    bool
+}
+
+// Manager provides reactive dependency tracking over a Graph.
+// It manages Unit registration, dependency relationships, and status updates
+// with automatic recalculation of readiness when dependencies are satisfied.
+type Manager struct {
+	mu sync.RWMutex
+
+	// The underlying graph that stores dependency relationships
+	graph *Graph[Status, ID]
+
+	// Store vertex instances for each unit to ensure consistent references
+	units map[ID]Unit
+}
+
+// NewManager creates a new Manager instance.
+func NewManager() *Manager {
+	return &Manager{
+		graph: &Graph[Status, ID]{},
+		units: make(map[ID]Unit),
+	}
+}
+
+// Register adds a unit to the manager if it is not already registered.
+// If a Unit is already registered (per the ID field), it is not updated.
+func (m *Manager) Register(id ID) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if id == "" {
+		return xerrors.Errorf("registering unit %q: %w", id, ErrUnitIDRequired)
+	}
+
+	if m.registered(id) {
+		return xerrors.Errorf("registering unit %q: %w", id, ErrUnitAlreadyRegistered)
+	}
+
+	m.units[id] = Unit{
+		id:     id,
+		status: StatusPending,
+		ready:  true,
+	}
+
+	return nil
+}
+
+// registered checks if a unit is registered in the manager.
+func (m *Manager) registered(id ID) bool {
+	return m.units[id].status != StatusNotRegistered
+}
+
+// Unit fetches a unit from the manager. If the unit does not exist,
+// it returns the Unit zero-value as a placeholder unit, because
+// units may depend on other units that have not yet been created.
+func (m *Manager) Unit(id ID) (Unit, error) {
+	if id == "" {
+		return Unit{}, xerrors.Errorf("unit ID cannot be empty: %w", ErrUnitIDRequired)
+	}
+
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	return m.units[id], nil
+}
+
+func (m *Manager) IsReady(id ID) (bool, error) {
+	if id == "" {
+		return false, xerrors.Errorf("unit ID cannot be empty: %w", ErrUnitIDRequired)
+	}
+
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	if !m.registered(id) {
+		return true, nil
+	}
+
+	return m.units[id].ready, nil
+}
+
+// AddDependency adds a dependency relationship between units.
+// The unit depends on the dependsOn unit reaching the requiredStatus.
+func (m *Manager) AddDependency(unit ID, dependsOn ID, requiredStatus Status) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	switch {
+	case unit == "":
+		return xerrors.Errorf("dependent name cannot be empty: %w", ErrUnitIDRequired)
+	case dependsOn == "":
+		return xerrors.Errorf("dependency name cannot be empty: %w", ErrUnitIDRequired)
+	case !m.registered(unit):
+		return xerrors.Errorf("dependent unit %q must be registered first: %w", unit, ErrUnitNotFound)
+	}
+
+	// Add the dependency edge to the graph
+	// The edge goes from unit to dependsOn, representing the dependency
+	err := m.graph.AddEdge(unit, dependsOn, requiredStatus)
+	if err != nil {
+		return xerrors.Errorf("adding edge for unit %q: %w", unit, errors.Join(ErrFailedToAddDependency, err))
+	}
+
+	// Recalculate readiness for the unit since it now has a new dependency
+	m.recalculateReadinessUnsafe(unit)
+
+	return nil
+}
+
+// UpdateStatus updates a unit's status and recalculates readiness for affected dependents.
+func (m *Manager) UpdateStatus(unit ID, newStatus Status) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	switch {
+	case unit == "":
+		return xerrors.Errorf("updating status for unit %q: %w", unit, ErrUnitIDRequired)
+	case !m.registered(unit):
+		return xerrors.Errorf("unit %q must be registered first: %w", unit, ErrUnitNotFound)
+	}
+
+	u := m.units[unit]
+	if u.status == newStatus {
+		return xerrors.Errorf("checking status for unit %q: %w", unit, ErrSameStatusAlreadySet)
+	}
+
+	u.status = newStatus
+	m.units[unit] = u
+
+	// Get all units that depend on this one (reverse adjacent vertices)
+	dependents := m.graph.GetReverseAdjacentVertices(unit)
+
+	// Recalculate readiness for all dependents
+	for _, dependent := range dependents {
+		m.recalculateReadinessUnsafe(dependent.From)
+	}
+
+	return nil
+}
+
+// recalculateReadinessUnsafe recalculates the readiness state for a unit.
+// This method assumes the caller holds the write lock.
+func (m *Manager) recalculateReadinessUnsafe(unit ID) {
+	u := m.units[unit]
+	dependencies := m.graph.GetForwardAdjacentVertices(unit)
+
+	allSatisfied := true
+	for _, dependency := range dependencies {
+		requiredStatus := dependency.Edge
+		dependsOnUnit := m.units[dependency.To]
+		if dependsOnUnit.status != requiredStatus {
+			allSatisfied = false
+			break
+		}
+	}
+
+	u.ready = allSatisfied
+	m.units[unit] = u
+}
+
+// GetGraph returns the underlying graph for visualization and debugging.
+// This should be used carefully as it exposes the internal graph structure.
+func (m *Manager) GetGraph() *Graph[Status, ID] {
+	return m.graph
+}
+
+// GetAllDependencies returns all dependencies for a unit, both satisfied and unsatisfied.
+func (m *Manager) GetAllDependencies(unit ID) ([]Dependency, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	if unit == "" {
+		return nil, xerrors.Errorf("unit ID cannot be empty: %w", ErrUnitIDRequired)
+	}
+
+	if !m.registered(unit) {
+		return nil, xerrors.Errorf("checking registration for unit %q: %w", unit, ErrUnitNotFound)
+	}
+
+	dependencies := m.graph.GetForwardAdjacentVertices(unit)
+
+	var allDependencies []Dependency
+
+	for _, dependency := range dependencies {
+		dependsOnUnit := m.units[dependency.To]
+		requiredStatus := dependency.Edge
+		allDependencies = append(allDependencies, Dependency{
+			Unit:           unit,
+			DependsOn:      dependency.To,
+			RequiredStatus: requiredStatus,
+			CurrentStatus:  dependsOnUnit.status,
+			IsSatisfied:    dependsOnUnit.status == requiredStatus,
+		})
+	}
+
+	return allDependencies, nil
+}
+
+// GetUnmetDependencies returns a list of unsatisfied dependencies for a unit.
+func (m *Manager) GetUnmetDependencies(unit ID) ([]Dependency, error) {
+	allDependencies, err := m.GetAllDependencies(unit)
+	if err != nil {
+		return nil, err
+	}
+
+	var unmetDependencies []Dependency = slice.Filter(allDependencies, func(dependency Dependency) bool {
+		return !dependency.IsSatisfied
+	})
+
+	return unmetDependencies, nil
+}
+
+// ExportDOT exports the dependency graph to DOT format for visualization.
+func (m *Manager) ExportDOT(name string) (string, error) {
+	return m.graph.ToDOT(name)
+}

agent/unit/manager_test.go

@@ -0,0 +1,743 @@
+package unit_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/agent/unit"
+)
+
+const (
+	unitA unit.ID = "serviceA"
+	unitB unit.ID = "serviceB"
+	unitC unit.ID = "serviceC"
+	unitD unit.ID = "serviceD"
+)
+
+func TestManager_UnitValidation(t *testing.T) {
+	t.Parallel()
+
+	t.Run("Empty Unit Name", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		err := manager.Register("")
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		err = manager.AddDependency("", unitA, unit.StatusStarted)
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		err = manager.AddDependency(unitA, "", unit.StatusStarted)
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		dependencies, err := manager.GetAllDependencies("")
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		require.Len(t, dependencies, 0)
+		unmetDependencies, err := manager.GetUnmetDependencies("")
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		require.Len(t, unmetDependencies, 0)
+		err = manager.UpdateStatus("", unit.StatusStarted)
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		isReady, err := manager.IsReady("")
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		require.False(t, isReady)
+		u, err := manager.Unit("")
+		require.ErrorIs(t, err, unit.ErrUnitIDRequired)
+		assert.Equal(t, unit.Unit{}, u)
+	})
+}
+
+func TestManager_Register(t *testing.T) {
+	t.Parallel()
+
+	t.Run("RegisterNewUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: a unit is registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+
+		// Then: the unit should be ready (no dependencies)
+		u, err := manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unitA, u.ID())
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("RegisterDuplicateUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: a unit is registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+
+		// Newly registered units have StatusPending. We update the unit status to StatusStarted,
+		// so we can later assert that it is not overwritten back to StatusPending by the second
+		// register call
+		manager.UpdateStatus(unitA, unit.StatusStarted)
+
+		// When: the unit is registered again
+		err = manager.Register(unitA)
+
+		// Then: a descriptive error should be returned
+		require.ErrorIs(t, err, unit.ErrUnitAlreadyRegistered)
+
+		// Then: the unit status should not be overwritten
+		u, err := manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusStarted, u.Status())
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("RegisterMultipleUnits", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: multiple units are registered
+		unitIDs := []unit.ID{unitA, unitB, unitC}
+		for _, unit := range unitIDs {
+			err := manager.Register(unit)
+			require.NoError(t, err)
+		}
+
+		// Then: all units should be ready initially
+		for _, unitID := range unitIDs {
+			u, err := manager.Unit(unitID)
+			require.NoError(t, err)
+			assert.Equal(t, unit.StatusPending, u.Status())
+			isReady, err := manager.IsReady(unitID)
+			require.NoError(t, err)
+			assert.True(t, isReady)
+		}
+	})
+}
+
+func TestManager_AddDependency(t *testing.T) {
+	t.Parallel()
+
+	t.Run("AddDependencyBetweenRegisteredUnits", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: units A and B are registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given: Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should not be ready (depends on B)
+		u, err := manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Then: Unit B should still be ready (no dependencies)
+		u, err = manager.Unit(unitB)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should be ready, because its dependency is now in the desired state.
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+
+		// When: Unit B is stopped
+		err = manager.UpdateStatus(unitB, unit.StatusPending)
+		require.NoError(t, err)
+
+		// Then: Unit A should no longer be ready, because its dependency is not in the desired state.
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+	})
+
+	t.Run("AddDependencyByAnUnregisteredDependentUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given Unit B is registered
+		err := manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given Unit A depends on Unit B being started
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+
+		// Then: a descriptive error communicates that the dependency cannot be added
+		// because the dependent unit must be registered first.
+		require.ErrorIs(t, err, unit.ErrUnitNotFound)
+	})
+
+	t.Run("AddDependencyOnAnUnregisteredUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given unit A is registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+
+		// Given Unit B is not yet registered
+		// And Unit A depends on Unit B being started
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: The dependency should be visible in Unit A's status
+		dependencies, err := manager.GetAllDependencies(unitA)
+		require.NoError(t, err)
+		require.Len(t, dependencies, 1)
+		assert.Equal(t, unitB, dependencies[0].DependsOn)
+		assert.Equal(t, unit.StatusStarted, dependencies[0].RequiredStatus)
+		assert.False(t, dependencies[0].IsSatisfied)
+
+		u, err := manager.Unit(unitB)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusNotRegistered, u.Status())
+
+		// Then: Unit A should not be ready, because it depends on Unit B
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// When: Unit B is registered
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Then: Unit A should still not be ready.
+		// Unit B is not registered, but it has not been started as required by the dependency.
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should be ready, because its dependency is now in the desired state.
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("AddDependencyCreatesACyclicDependency", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register units
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+		err = manager.Register(unitC)
+		require.NoError(t, err)
+		err = manager.Register(unitD)
+		require.NoError(t, err)
+
+		// A depends on B
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		// B depends on C
+		err = manager.AddDependency(unitB, unitC, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// C depends on D
+		err = manager.AddDependency(unitC, unitD, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Try to make D depend on A (creates indirect cycle)
+		err = manager.AddDependency(unitD, unitA, unit.StatusStarted)
+		require.ErrorIs(t, err, unit.ErrCycleDetected)
+	})
+
+	t.Run("UpdatingADependency", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given units A and B are registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// When: The dependency is updated to unit.StatusComplete
+		err = manager.AddDependency(unitA, unitB, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// Then: Unit A should only have one dependency, and it should be unit.StatusComplete
+		dependencies, err := manager.GetAllDependencies(unitA)
+		require.NoError(t, err)
+		require.Len(t, dependencies, 1)
+		assert.Equal(t, unit.StatusComplete, dependencies[0].RequiredStatus)
+	})
+}
+
+func TestManager_UpdateStatus(t *testing.T) {
+	t.Parallel()
+
+	t.Run("UpdateStatusTriggersReadinessRecalculation", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given units A and B are registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should not be ready (depends on B)
+		u, err := manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should be ready, because its dependency is now in the desired state.
+		u, err = manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("UpdateStatusWithUnregisteredUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given Unit A is not registered
+		// When: Unit A is updated to unit.StatusStarted
+		err := manager.UpdateStatus(unitA, unit.StatusStarted)
+
+		// Then: a descriptive error communicates that the unit must be registered first.
+		require.ErrorIs(t, err, unit.ErrUnitNotFound)
+	})
+
+	t.Run("LinearChainDependencies", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given units A, B, and C are registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+		err = manager.Register(unitC)
+		require.NoError(t, err)
+
+		// Create chain: A depends on B being "started", B depends on C being "completed"
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitB, unitC, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// Then: only Unit C should be ready (no dependencies)
+		u, err := manager.Unit(unitC)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err := manager.IsReady(unitC)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+
+		u, err = manager.Unit(unitB)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		u, err = manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// When: Unit C is completed
+		err = manager.UpdateStatus(unitC, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// Then: Unit B should be ready, because its dependency is now in the desired state.
+		u, err = manager.Unit(unitB)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+
+		u, err = manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		u, err = manager.Unit(unitB)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should be ready, because its dependency is now in the desired state.
+		u, err = manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusPending, u.Status())
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+}
+
+func TestManager_GetUnmetDependencies(t *testing.T) {
+	t.Parallel()
+
+	t.Run("GetUnmetDependenciesForUnitWithNoDependencies", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: Unit A is registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+
+		// Given: Unit A has no dependencies
+		// Then: Unit A should have no unmet dependencies
+		unmet, err := manager.GetUnmetDependencies(unitA)
+		require.NoError(t, err)
+		assert.Empty(t, unmet)
+	})
+
+	t.Run("GetUnmetDependenciesForUnitWithUnsatisfiedDependencies", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given: Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		unmet, err := manager.GetUnmetDependencies(unitA)
+		require.NoError(t, err)
+		require.Len(t, unmet, 1)
+
+		assert.Equal(t, unitA, unmet[0].Unit)
+		assert.Equal(t, unitB, unmet[0].DependsOn)
+		assert.Equal(t, unit.StatusStarted, unmet[0].RequiredStatus)
+		assert.False(t, unmet[0].IsSatisfied)
+	})
+
+	t.Run("GetUnmetDependenciesForUnitWithSatisfiedDependencies", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: Unit A and Unit B are registered
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Given: Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should have no unmet dependencies
+		unmet, err := manager.GetUnmetDependencies(unitA)
+		require.NoError(t, err)
+		assert.Empty(t, unmet)
+	})
+
+	t.Run("GetUnmetDependenciesForUnregisteredUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// When: Unit A is requested
+		unmet, err := manager.GetUnmetDependencies(unitA)
+
+		// Then: a descriptive error communicates that the unit must be registered first.
+		require.ErrorIs(t, err, unit.ErrUnitNotFound)
+		assert.Nil(t, unmet)
+	})
+}
+
+func TestManager_MultipleDependencies(t *testing.T) {
+	t.Parallel()
+
+	t.Run("UnitWithMultipleDependencies", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register all units
+		units := []unit.ID{unitA, unitB, unitC, unitD}
+		for _, unit := range units {
+			err := manager.Register(unit)
+			require.NoError(t, err)
+		}
+
+		// A depends on B being unit.StatusStarted AND C being "started"
+		err := manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitA, unitC, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// A should not be ready (depends on both B and C)
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Update B to unit.StatusStarted - A should still not be ready (needs C too)
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Update C to "started" - A should now be ready
+		err = manager.UpdateStatus(unitC, unit.StatusStarted)
+		require.NoError(t, err)
+
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("ComplexDependencyChain", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register all units
+		units := []unit.ID{unitA, unitB, unitC, unitD}
+		for _, unit := range units {
+			err := manager.Register(unit)
+			require.NoError(t, err)
+		}
+
+		// Create complex dependency graph:
+		// A depends on B being unit.StatusStarted AND C being "started"
+		err := manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitA, unitC, unit.StatusStarted)
+		require.NoError(t, err)
+		// B depends on D being "completed"
+		err = manager.AddDependency(unitB, unitD, unit.StatusComplete)
+		require.NoError(t, err)
+		// C depends on D being "completed"
+		err = manager.AddDependency(unitC, unitD, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// Initially only D is ready
+		isReady, err := manager.IsReady(unitD)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+		isReady, err = manager.IsReady(unitC)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Update D to "completed" - B and C should become ready
+		err = manager.UpdateStatus(unitD, unit.StatusComplete)
+		require.NoError(t, err)
+
+		isReady, err = manager.IsReady(unitB)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+		isReady, err = manager.IsReady(unitC)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Update B to unit.StatusStarted - A should still not be ready (needs C)
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// Update C to "started" - A should now be ready
+		err = manager.UpdateStatus(unitC, unit.StatusStarted)
+		require.NoError(t, err)
+
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+
+	t.Run("DifferentStatusTypes", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register units
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+		err = manager.Register(unitC)
+		require.NoError(t, err)
+
+		// Given: Unit A depends on Unit B being unit.StatusStarted
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		// Given: Unit A depends on Unit C being "completed"
+		err = manager.AddDependency(unitA, unitC, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// When: Unit B is started
+		err = manager.UpdateStatus(unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		// Then: Unit A should not be ready, because only one of its dependencies is in the desired state.
+		// It still requires Unit C to be completed.
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.False(t, isReady)
+
+		// When: Unit C is completed
+		err = manager.UpdateStatus(unitC, unit.StatusComplete)
+		require.NoError(t, err)
+
+		// Then: Unit A should be ready, because both of its dependencies are in the desired state.
+		isReady, err = manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+}
+
+func TestManager_IsReady(t *testing.T) {
+	t.Parallel()
+
+	t.Run("IsReadyWithUnregisteredUnit", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Given: a unit is not registered
+		u, err := manager.Unit(unitA)
+		require.NoError(t, err)
+		assert.Equal(t, unit.StatusNotRegistered, u.Status())
+		// Then: the unit is not ready
+		isReady, err := manager.IsReady(unitA)
+		require.NoError(t, err)
+		assert.True(t, isReady)
+	})
+}
+
+func TestManager_ToDOT(t *testing.T) {
+	t.Parallel()
+
+	t.Run("ExportSimpleGraph", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register units
+		err := manager.Register(unitA)
+		require.NoError(t, err)
+		err = manager.Register(unitB)
+		require.NoError(t, err)
+
+		// Add dependency
+		err = manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+
+		dot, err := manager.ExportDOT("test")
+		require.NoError(t, err)
+		assert.NotEmpty(t, dot)
+		assert.Contains(t, dot, "digraph")
+	})
+
+	t.Run("ExportComplexGraph", func(t *testing.T) {
+		t.Parallel()
+
+		manager := unit.NewManager()
+
+		// Register all units
+		units := []unit.ID{unitA, unitB, unitC, unitD}
+		for _, unit := range units {
+			err := manager.Register(unit)
+			require.NoError(t, err)
+		}
+
+		// Create complex dependency graph
+		// A depends on B and C, B depends on D, C depends on D
+		err := manager.AddDependency(unitA, unitB, unit.StatusStarted)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitA, unitC, unit.StatusStarted)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitB, unitD, unit.StatusComplete)
+		require.NoError(t, err)
+		err = manager.AddDependency(unitC, unitD, unit.StatusComplete)
+		require.NoError(t, err)
+
+		dot, err := manager.ExportDOT("complex")
+		require.NoError(t, err)
+		assert.NotEmpty(t, dot)
+		assert.Contains(t, dot, "digraph")
+	})
+}

agent/unit/testdata/Cycle.golden

@@ -0,0 +1,8 @@
+strict digraph Cycle {
+  // Node definitions.
+  1;
+  2;
+
+  // Edge definitions.
+  1 -> 2;
+}

agent/unit/testdata/ForwardAndReverseEdges.golden

@@ -0,0 +1,10 @@
+strict digraph ForwardAndReverseEdges {
+  // Node definitions.
+  1;
+  2;
+  3;
+
+  // Edge definitions.
+  1 -> 2;
+  1 -> 3;
+}

agent/unit/testdata/MultipleDependenciesSameStatus.golden

@@ -0,0 +1,12 @@
+strict digraph MultipleDependenciesSameStatus {
+  // Node definitions.
+  1;
+  2;
+  3;
+  4;
+
+  // Edge definitions.
+  1 -> 2;
+  1 -> 3;
+  1 -> 4;
+}

agent/unit/testdata/SelfReference.golden

@@ -0,0 +1,4 @@
+strict digraph SelfReference {
+  // Node definitions.
+  1;
+}

biome.jsonc

@@ -6,10 +6,7 @@
 		"defaultBranch": "main"
 	},
 	"files": {
-		"includes": [
-			"**",
-			"!**/pnpm-lock.yaml"
-		],
+		"includes": ["**", "!**/pnpm-lock.yaml"],
 		"ignoreUnknown": true
 	},
 	"linter": {
@@ -48,13 +45,14 @@
 					"options": {
 						"paths": {
 							"@mui/material": "Use @mui/material/<name> instead. See: https://material-ui.com/guides/minimizing-bundle-size/.",
-							"@mui/icons-material": "Use @mui/icons-material/<name> instead. See: https://material-ui.com/guides/minimizing-bundle-size/.",
 							"@mui/material/Avatar": "Use components/Avatar/Avatar instead.",
 							"@mui/material/Alert": "Use components/Alert/Alert instead.",
 							"@mui/material/Popover": "Use components/Popover/Popover instead.",
 							"@mui/material/Typography": "Use native HTML elements instead. Eg: <span>, <p>, <h1>, etc.",
 							"@mui/material/Box": "Use a <div> instead.",
+							"@mui/material/Button": "Use a components/Button/Button instead.",
 							"@mui/material/styles": "Import from @emotion/react instead.",
+							"@mui/material/Table*": "Import from components/Table/Table instead.",
 							"lodash": "Use lodash/<name> instead."
 						}
 					}
@@ -69,11 +67,7 @@
 				"noConsole": {
 					"level": "error",
 					"options": {
-						"allow": [
-							"error",
-							"info",
-							"warn"
-						]
+						"allow": ["error", "info", "warn"]
 					}
 				}
 			},
@@ -82,5 +76,5 @@
 			}
 		}
 	},
-	"$schema": "https://biomejs.dev/schemas/2.2.0/schema.json"
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json"
 }

cli/agent.go

@@ -11,11 +11,11 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
 
-	"cloud.google.com/go/compute/metadata"
 	"golang.org/x/xerrors"
 	"gopkg.in/natefinch/lumberjack.v2"
 
@@ -38,9 +38,8 @@ import (
 	"github.com/coder/coder/v2/codersdk/agentsdk"
 )
 
-func (r *RootCmd) workspaceAgent() *serpent.Command {
+func workspaceAgent() *serpent.Command {
 	var (
-		auth                           string
 		logDir                         string
 		scriptDataDir                  string
 		pprofAddress                   string
@@ -58,7 +57,10 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 		devcontainers                  bool
 		devcontainerProjectDiscovery   bool
 		devcontainerDiscoveryAutostart bool
+		socketServerEnabled            bool
+		socketPath                     string
 	)
+	agentAuth := &AgentAuth{}
 	cmd := &serpent.Command{
 		Use:   "agent",
 		Short: `Starts the Coder workspace agent.`,
@@ -176,12 +178,14 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 
 			version := buildinfo.Version()
 			logger.Info(ctx, "agent is starting now",
-				slog.F("url", r.agentURL),
-				slog.F("auth", auth),
+				slog.F("url", agentAuth.agentURL),
+				slog.F("auth", agentAuth.agentAuth),
 				slog.F("version", version),
 			)
-
-			client := agentsdk.New(r.agentURL)
+			client, err := agentAuth.CreateClient()
+			if err != nil {
+				return xerrors.Errorf("create agent client: %w", err)
+			}
 			client.SDK.SetLogger(logger)
 			// Set a reasonable timeout so requests can't hang forever!
 			// The timeout needs to be reasonably long, because requests
@@ -190,7 +194,7 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 			client.SDK.HTTPClient.Timeout = 30 * time.Second
 			// Attach header transport so we process --agent-header and
 			// --agent-header-command flags
-			headerTransport, err := headerTransport(ctx, r.agentURL, agentHeader, agentHeaderCommand)
+			headerTransport, err := headerTransport(ctx, &agentAuth.agentURL, agentHeader, agentHeaderCommand)
 			if err != nil {
 				return xerrors.Errorf("configure header transport: %w", err)
 			}
@@ -200,80 +204,15 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 			// Enable pprof handler
 			// This prevents the pprof import from being accidentally deleted.
 			_ = pprof.Handler
-			pprofSrvClose := ServeHandler(ctx, logger, nil, pprofAddress, "pprof")
-			defer pprofSrvClose()
-			if port, err := extractPort(pprofAddress); err == nil {
-				ignorePorts[port] = "pprof"
-			}
+			if pprofAddress != "" {
+				pprofSrvClose := ServeHandler(ctx, logger, nil, pprofAddress, "pprof")
+				defer pprofSrvClose()
 
-			if port, err := extractPort(prometheusAddress); err == nil {
-				ignorePorts[port] = "prometheus"
-			}
-
-			if port, err := extractPort(debugAddress); err == nil {
-				ignorePorts[port] = "debug"
-			}
-
-			// exchangeToken returns a session token.
-			// This is abstracted to allow for the same looping condition
-			// regardless of instance identity auth type.
-			var exchangeToken func(context.Context) (agentsdk.AuthenticateResponse, error)
-			switch auth {
-			case "token":
-				token, _ := inv.ParsedFlags().GetString(varAgentToken)
-				if token == "" {
-					tokenFile, _ := inv.ParsedFlags().GetString(varAgentTokenFile)
-					if tokenFile != "" {
-						tokenBytes, err := os.ReadFile(tokenFile)
-						if err != nil {
-							return xerrors.Errorf("read token file %q: %w", tokenFile, err)
-						}
-						token = strings.TrimSpace(string(tokenBytes))
-					}
-				}
-				if token == "" {
-					return xerrors.Errorf("CODER_AGENT_TOKEN or CODER_AGENT_TOKEN_FILE must be set for token auth")
-				}
-				client.SetSessionToken(token)
-			case "google-instance-identity":
-				// This is *only* done for testing to mock client authentication.
-				// This will never be set in a production scenario.
-				var gcpClient *metadata.Client
-				gcpClientRaw := ctx.Value("gcp-client")
-				if gcpClientRaw != nil {
-					gcpClient, _ = gcpClientRaw.(*metadata.Client)
-				}
-				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
-					return client.AuthGoogleInstanceIdentity(ctx, "", gcpClient)
-				}
-			case "aws-instance-identity":
-				// This is *only* done for testing to mock client authentication.
-				// This will never be set in a production scenario.
-				var awsClient *http.Client
-				awsClientRaw := ctx.Value("aws-client")
-				if awsClientRaw != nil {
-					awsClient, _ = awsClientRaw.(*http.Client)
-					if awsClient != nil {
-						client.SDK.HTTPClient = awsClient
-					}
-				}
-				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
-					return client.AuthAWSInstanceIdentity(ctx)
-				}
-			case "azure-instance-identity":
-				// This is *only* done for testing to mock client authentication.
-				// This will never be set in a production scenario.
-				var azureClient *http.Client
-				azureClientRaw := ctx.Value("azure-client")
-				if azureClientRaw != nil {
-					azureClient, _ = azureClientRaw.(*http.Client)
-					if azureClient != nil {
-						client.SDK.HTTPClient = azureClient
-					}
-				}
-				exchangeToken = func(ctx context.Context) (agentsdk.AuthenticateResponse, error) {
-					return client.AuthAzureInstanceIdentity(ctx)
+				if port, err := extractPort(pprofAddress); err == nil {
+					ignorePorts[port] = "pprof"
 				}
+			} else {
+				logger.Debug(ctx, "pprof address is empty, disabling pprof server")
 			}
 
 			executablePath, err := os.Executable()
@@ -337,24 +276,35 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 			for {
 				prometheusRegistry := prometheus.NewRegistry()
 
+				promHandler := agent.PrometheusMetricsHandler(prometheusRegistry, logger)
+				var serverClose []func()
+				if prometheusAddress != "" {
+					prometheusSrvClose := ServeHandler(ctx, logger, promHandler, prometheusAddress, "prometheus")
+					serverClose = append(serverClose, prometheusSrvClose)
+
+					if port, err := extractPort(prometheusAddress); err == nil {
+						ignorePorts[port] = "prometheus"
+					}
+				} else {
+					logger.Debug(ctx, "prometheus address is empty, disabling prometheus server")
+				}
+
+				if debugAddress != "" {
+					// ServerHandle depends on `agnt.HTTPDebug()`, but `agnt`
+					// depends on `ignorePorts`. Keep this if statement in sync
+					// with below.
+					if port, err := extractPort(debugAddress); err == nil {
+						ignorePorts[port] = "debug"
+					}
+				}
+
 				agnt := agent.New(agent.Options{
 					Client:        client,
 					Logger:        logger,
 					LogDir:        logDir,
 					ScriptDataDir: scriptDataDir,
 					// #nosec G115 - Safe conversion as tailnet listen port is within uint16 range (0-65535)
-					TailnetListenPort: uint16(tailnetListenPort),
-					ExchangeToken: func(ctx context.Context) (string, error) {
-						if exchangeToken == nil {
-							return client.SDK.SessionToken(), nil
-						}
-						resp, err := exchangeToken(ctx)
-						if err != nil {
-							return "", err
-						}
-						client.SetSessionToken(resp.SessionToken)
-						return resp.SessionToken, nil
-					},
+					TailnetListenPort:    uint16(tailnetListenPort),
 					EnvironmentVariables: environmentVariables,
 					IgnorePorts:          ignorePorts,
 					SSHMaxTimeout:        sshMaxTimeout,
@@ -365,16 +315,23 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 					Execer:             execer,
 					Devcontainers:      devcontainers,
 					DevcontainerAPIOptions: []agentcontainers.Option{
-						agentcontainers.WithSubAgentURL(r.agentURL.String()),
+						agentcontainers.WithSubAgentURL(agentAuth.agentURL.String()),
 						agentcontainers.WithProjectDiscovery(devcontainerProjectDiscovery),
 						agentcontainers.WithDiscoveryAutostart(devcontainerDiscoveryAutostart),
 					},
+					SocketPath:          socketPath,
+					SocketServerEnabled: socketServerEnabled,
 				})
 
-				promHandler := agent.PrometheusMetricsHandler(prometheusRegistry, logger)
-				prometheusSrvClose := ServeHandler(ctx, logger, promHandler, prometheusAddress, "prometheus")
-
-				debugSrvClose := ServeHandler(ctx, logger, agnt.HTTPDebug(), debugAddress, "debug")
+				if debugAddress != "" {
+					// ServerHandle depends on `agnt.HTTPDebug()`, but `agnt`
+					// depends on `ignorePorts`. Keep this if statement in sync
+					// with above.
+					debugSrvClose := ServeHandler(ctx, logger, agnt.HTTPDebug(), debugAddress, "debug")
+					serverClose = append(serverClose, debugSrvClose)
+				} else {
+					logger.Debug(ctx, "debug address is empty, disabling debug server")
+				}
 
 				select {
 				case <-ctx.Done():
@@ -386,8 +343,11 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 				}
 
 				lastErr = agnt.Close()
-				debugSrvClose()
-				prometheusSrvClose()
+
+				slices.Reverse(serverClose)
+				for _, closeFunc := range serverClose {
+					closeFunc()
+				}
 
 				if mustExit {
 					break
@@ -400,13 +360,6 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 	}
 
 	cmd.Options = serpent.OptionSet{
-		{
-			Flag:        "auth",
-			Default:     "token",
-			Description: "Specify the authentication type to use for the agent.",
-			Env:         "CODER_AGENT_AUTH",
-			Value:       serpent.StringOf(&auth),
-		},
 		{
 			Flag:        "log-dir",
 			Default:     os.TempDir(),
@@ -528,8 +481,21 @@ func (r *RootCmd) workspaceAgent() *serpent.Command {
 			Description: "Allow the agent to autostart devcontainer projects it discovers based on their configuration.",
 			Value:       serpent.BoolOf(&devcontainerDiscoveryAutostart),
 		},
+		{
+			Flag:        "socket-server-enabled",
+			Default:     "false",
+			Env:         "CODER_AGENT_SOCKET_SERVER_ENABLED",
+			Description: "Enable the agent socket server.",
+			Value:       serpent.BoolOf(&socketServerEnabled),
+		},
+		{
+			Flag:        "socket-path",
+			Env:         "CODER_AGENT_SOCKET_PATH",
+			Description: "Specify the path for the agent socket.",
+			Value:       serpent.StringOf(&socketPath),
+		},
 	}
-
+	agentAuth.AttachOptions(cmd, false)
 	return cmd
 }
 

cli/agent_test.go

@@ -1,7 +1,6 @@
 package cli_test
 
 import (
-	"context"
 	"fmt"
 	"net/http"
 	"os"
@@ -11,7 +10,6 @@ import (
 	"sync/atomic"
 	"testing"
 
-	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -21,10 +19,7 @@ import (
 	"github.com/coder/coder/v2/coderd/coderdtest"
 	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/database/dbfake"
-	"github.com/coder/coder/v2/coderd/database/dbtestutil"
 	"github.com/coder/coder/v2/codersdk"
-	"github.com/coder/coder/v2/codersdk/workspacesdk"
-	"github.com/coder/coder/v2/provisionersdk/proto"
 	"github.com/coder/coder/v2/testutil"
 )
 
@@ -64,158 +59,6 @@ func TestWorkspaceAgent(t *testing.T) {
 		}, testutil.WaitLong, testutil.IntervalMedium)
 	})
 
-	t.Run("Azure", func(t *testing.T) {
-		t.Parallel()
-		instanceID := "instanceidentifier"
-		certificates, metadataClient := coderdtest.NewAzureInstanceIdentity(t, instanceID)
-		db, ps := dbtestutil.NewDB(t,
-			dbtestutil.WithDumpOnFailure(),
-		)
-		client := coderdtest.New(t, &coderdtest.Options{
-			Database:          db,
-			Pubsub:            ps,
-			AzureCertificates: certificates,
-		})
-		user := coderdtest.CreateFirstUser(t, client)
-		r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
-			OrganizationID: user.OrganizationID,
-			OwnerID:        user.UserID,
-		}).WithAgent(func(agents []*proto.Agent) []*proto.Agent {
-			agents[0].Auth = &proto.Agent_InstanceId{InstanceId: instanceID}
-			return agents
-		}).Do()
-
-		inv, _ := clitest.New(t, "agent", "--auth", "azure-instance-identity", "--agent-url", client.URL.String())
-		inv = inv.WithContext(
-			//nolint:revive,staticcheck
-			context.WithValue(inv.Context(), "azure-client", metadataClient),
-		)
-
-		ctx := inv.Context()
-		clitest.Start(t, inv)
-		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
-			MatchResources(matchAgentWithVersion).Wait()
-		workspace, err := client.Workspace(ctx, r.Workspace.ID)
-		require.NoError(t, err)
-		resources := workspace.LatestBuild.Resources
-		if assert.NotEmpty(t, workspace.LatestBuild.Resources) && assert.NotEmpty(t, resources[0].Agents) {
-			assert.NotEmpty(t, resources[0].Agents[0].Version)
-		}
-		dialer, err := workspacesdk.New(client).
-			DialAgent(ctx, resources[0].Agents[0].ID, nil)
-		require.NoError(t, err)
-		defer dialer.Close()
-		require.True(t, dialer.AwaitReachable(ctx))
-	})
-
-	t.Run("AWS", func(t *testing.T) {
-		t.Parallel()
-		instanceID := "instanceidentifier"
-		certificates, metadataClient := coderdtest.NewAWSInstanceIdentity(t, instanceID)
-		db, ps := dbtestutil.NewDB(t,
-			dbtestutil.WithDumpOnFailure(),
-		)
-		client := coderdtest.New(t, &coderdtest.Options{
-			Database:        db,
-			Pubsub:          ps,
-			AWSCertificates: certificates,
-		})
-		user := coderdtest.CreateFirstUser(t, client)
-		r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
-			OrganizationID: user.OrganizationID,
-			OwnerID:        user.UserID,
-		}).WithAgent(func(agents []*proto.Agent) []*proto.Agent {
-			agents[0].Auth = &proto.Agent_InstanceId{InstanceId: instanceID}
-			return agents
-		}).Do()
-
-		inv, _ := clitest.New(t, "agent", "--auth", "aws-instance-identity", "--agent-url", client.URL.String())
-		inv = inv.WithContext(
-			//nolint:revive,staticcheck
-			context.WithValue(inv.Context(), "aws-client", metadataClient),
-		)
-
-		clitest.Start(t, inv)
-		ctx := inv.Context()
-		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
-			MatchResources(matchAgentWithVersion).
-			Wait()
-		workspace, err := client.Workspace(ctx, r.Workspace.ID)
-		require.NoError(t, err)
-		resources := workspace.LatestBuild.Resources
-		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
-			assert.NotEmpty(t, resources[0].Agents[0].Version)
-		}
-		dialer, err := workspacesdk.New(client).
-			DialAgent(ctx, resources[0].Agents[0].ID, nil)
-		require.NoError(t, err)
-		defer dialer.Close()
-		require.True(t, dialer.AwaitReachable(ctx))
-	})
-
-	t.Run("GoogleCloud", func(t *testing.T) {
-		t.Parallel()
-		instanceID := "instanceidentifier"
-		validator, metadataClient := coderdtest.NewGoogleInstanceIdentity(t, instanceID, false)
-		db, ps := dbtestutil.NewDB(t,
-			dbtestutil.WithDumpOnFailure(),
-		)
-		client := coderdtest.New(t, &coderdtest.Options{
-			Database:             db,
-			Pubsub:               ps,
-			GoogleTokenValidator: validator,
-		})
-		owner := coderdtest.CreateFirstUser(t, client)
-		member, memberUser := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID)
-		r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
-			OrganizationID: owner.OrganizationID,
-			OwnerID:        memberUser.ID,
-		}).WithAgent(func(agents []*proto.Agent) []*proto.Agent {
-			agents[0].Auth = &proto.Agent_InstanceId{InstanceId: instanceID}
-			return agents
-		}).Do()
-
-		inv, cfg := clitest.New(t, "agent", "--auth", "google-instance-identity", "--agent-url", client.URL.String())
-		clitest.SetupConfig(t, member, cfg)
-
-		clitest.Start(t,
-			inv.WithContext(
-				//nolint:revive,staticcheck
-				context.WithValue(inv.Context(), "gcp-client", metadataClient),
-			),
-		)
-
-		ctx := inv.Context()
-		coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
-			MatchResources(matchAgentWithVersion).
-			Wait()
-		workspace, err := client.Workspace(ctx, r.Workspace.ID)
-		require.NoError(t, err)
-		resources := workspace.LatestBuild.Resources
-		if assert.NotEmpty(t, resources) && assert.NotEmpty(t, resources[0].Agents) {
-			assert.NotEmpty(t, resources[0].Agents[0].Version)
-		}
-		dialer, err := workspacesdk.New(client).DialAgent(ctx, resources[0].Agents[0].ID, nil)
-		require.NoError(t, err)
-		defer dialer.Close()
-		require.True(t, dialer.AwaitReachable(ctx))
-		sshClient, err := dialer.SSHClient(ctx)
-		require.NoError(t, err)
-		defer sshClient.Close()
-		session, err := sshClient.NewSession()
-		require.NoError(t, err)
-		defer session.Close()
-		key := "CODER_AGENT_TOKEN"
-		command := "sh -c 'echo $" + key + "'"
-		if runtime.GOOS == "windows" {
-			command = "cmd.exe /c echo %" + key + "%"
-		}
-		token, err := session.CombinedOutput(command)
-		require.NoError(t, err)
-		_, err = uuid.Parse(strings.TrimSpace(string(token)))
-		require.NoError(t, err)
-	})
-
 	t.Run("PostStartup", func(t *testing.T) {
 		t.Parallel()
 
@@ -335,6 +178,51 @@ func TestWorkspaceAgent(t *testing.T) {
 		require.Greater(t, atomic.LoadInt64(&called), int64(0), "expected coderd to be reached with custom headers")
 		require.Greater(t, atomic.LoadInt64(&derpCalled), int64(0), "expected /derp to be called with custom headers")
 	})
+
+	t.Run("DisabledServers", func(t *testing.T) {
+		t.Parallel()
+
+		client, db := coderdtest.NewWithDatabase(t, nil)
+		user := coderdtest.CreateFirstUser(t, client)
+		r := dbfake.WorkspaceBuild(t, db, database.WorkspaceTable{
+			OrganizationID: user.OrganizationID,
+			OwnerID:        user.UserID,
+		}).WithAgent().Do()
+
+		logDir := t.TempDir()
+		inv, _ := clitest.New(t,
+			"agent",
+			"--auth", "token",
+			"--agent-token", r.AgentToken,
+			"--agent-url", client.URL.String(),
+			"--log-dir", logDir,
+			"--pprof-address", "",
+			"--prometheus-address", "",
+			"--debug-address", "",
+		)
+
+		clitest.Start(t, inv)
+
+		// Verify the agent is connected and working.
+		resources := coderdtest.NewWorkspaceAgentWaiter(t, client, r.Workspace.ID).
+			MatchResources(matchAgentWithVersion).Wait()
+		require.Len(t, resources, 1)
+		require.Len(t, resources[0].Agents, 1)
+		require.NotEmpty(t, resources[0].Agents[0].Version)
+
+		// Verify the servers are not listening by checking the log for disabled
+		// messages.
+		require.Eventually(t, func() bool {
+			logContent, err := os.ReadFile(filepath.Join(logDir, "coder-agent.log"))
+			if err != nil {
+				return false
+			}
+			logStr := string(logContent)
+			return strings.Contains(logStr, "pprof address is empty, disabling pprof server") &&
+				strings.Contains(logStr, "prometheus address is empty, disabling prometheus server") &&
+				strings.Contains(logStr, "debug address is empty, disabling debug server")
+		}, testutil.WaitLong, testutil.IntervalMedium)
+	})
 }
 
 func matchAgentWithVersion(rs []codersdk.WorkspaceResource) bool {

cli/allowlistflag.go

@@ -0,0 +1,78 @@
+package cli
+
+import (
+	"encoding/csv"
+	"strings"
+
+	"github.com/spf13/pflag"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/codersdk"
+)
+
+var (
+	_ pflag.SliceValue = &AllowListFlag{}
+	_ pflag.Value      = &AllowListFlag{}
+)
+
+// AllowListFlag implements pflag.SliceValue for codersdk.APIAllowListTarget entries.
+type AllowListFlag []codersdk.APIAllowListTarget
+
+func AllowListFlagOf(al *[]codersdk.APIAllowListTarget) *AllowListFlag {
+	return (*AllowListFlag)(al)
+}
+
+func (a AllowListFlag) String() string {
+	return strings.Join(a.GetSlice(), ",")
+}
+
+func (a AllowListFlag) Value() []codersdk.APIAllowListTarget {
+	return []codersdk.APIAllowListTarget(a)
+}
+
+func (AllowListFlag) Type() string { return "allow-list" }
+
+func (a *AllowListFlag) Set(set string) error {
+	values, err := csv.NewReader(strings.NewReader(set)).Read()
+	if err != nil {
+		return xerrors.Errorf("parse allow list entries as csv: %w", err)
+	}
+	for _, v := range values {
+		if err := a.Append(v); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (a *AllowListFlag) Append(value string) error {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return xerrors.New("allow list entry cannot be empty")
+	}
+	var target codersdk.APIAllowListTarget
+	if err := target.UnmarshalText([]byte(value)); err != nil {
+		return err
+	}
+
+	*a = append(*a, target)
+	return nil
+}
+
+func (a *AllowListFlag) Replace(items []string) error {
+	*a = []codersdk.APIAllowListTarget{}
+	for _, item := range items {
+		if err := a.Append(item); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (a *AllowListFlag) GetSlice() []string {
+	out := make([]string, len(*a))
+	for i, entry := range *a {
+		out[i] = entry.String()
+	}
+	return out
+}

cli/autoupdate.go

@@ -12,18 +12,21 @@ import (
 )
 
 func (r *RootCmd) autoupdate() *serpent.Command {
-	client := new(codersdk.Client)
 	cmd := &serpent.Command{
 		Annotations: workspaceCommand,
 		Use:         "autoupdate <workspace> <always|never>",
 		Short:       "Toggle auto-update policy for a workspace",
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(2),
-			r.InitClient(client),
 		),
 		Handler: func(inv *serpent.Invocation) error {
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
 			policy := strings.ToLower(inv.Args[1])
-			err := validateAutoUpdatePolicy(policy)
+			err = validateAutoUpdatePolicy(policy)
 			if err != nil {
 				return xerrors.Errorf("validate policy: %w", err)
 			}

cli/clitest/clitest.go

@@ -28,7 +28,9 @@ import (
 )
 
 // New creates a CLI instance with a configuration pointed to a
-// temporary testing directory.
+// temporary testing directory. The invocation is set up to use a
+// global config directory for the given testing.TB, and keyring
+// usage disabled.
 func New(t testing.TB, args ...string) (*serpent.Invocation, config.Root) {
 	var root cli.RootCmd
 
@@ -59,6 +61,15 @@ func NewWithCommand(
 	t testing.TB, cmd *serpent.Command, args ...string,
 ) (*serpent.Invocation, config.Root) {
 	configDir := config.Root(t.TempDir())
+	// Keyring usage is disabled here when --global-config is set because many existing
+	// tests expect the session token to be stored on disk and is not properly instrumented
+	// for parallel testing against the actual operating system keyring.
+	invArgs := append([]string{"--global-config", string(configDir)}, args...)
+	return setupInvocation(t, cmd, invArgs...), configDir
+}
+
+func setupInvocation(t testing.TB, cmd *serpent.Command, args ...string,
+) *serpent.Invocation {
 	// I really would like to fail test on error logs, but realistically, turning on by default
 	// in all our CLI tests is going to create a lot of flaky noise.
 	logger := slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).
@@ -66,16 +77,21 @@ func NewWithCommand(
 		Named("cli")
 	i := &serpent.Invocation{
 		Command: cmd,
-		Args:    append([]string{"--global-config", string(configDir)}, args...),
+		Args:    args,
 		Stdin:   io.LimitReader(nil, 0),
 		Stdout:  (&logWriter{prefix: "stdout", log: logger}),
 		Stderr:  (&logWriter{prefix: "stderr", log: logger}),
 		Logger:  logger,
 	}
 	t.Logf("invoking command: %s %s", cmd.Name(), strings.Join(i.Args, " "))
+	return i
+}
 
-	// These can be overridden by the test.
-	return i, configDir
+func NewWithDefaultKeyringCommand(t testing.TB, cmd *serpent.Command, args ...string,
+) (*serpent.Invocation, config.Root) {
+	configDir := config.Root(t.TempDir())
+	invArgs := append([]string{"--global-config", string(configDir)}, args...)
+	return setupInvocation(t, cmd, invArgs...), configDir
 }
 
 // SetupConfig applies the URL and SessionToken of the client to the config.

cli/cliui/agent.go

@@ -53,6 +53,9 @@ func Agent(ctx context.Context, writer io.Writer, agentID uuid.UUID, opts AgentO
 		t := time.NewTimer(0)
 		defer t.Stop()
 
+		startTime := time.Now()
+		baseInterval := opts.FetchInterval
+
 		for {
 			select {
 			case <-ctx.Done():
@@ -68,7 +71,11 @@ func Agent(ctx context.Context, writer io.Writer, agentID uuid.UUID, opts AgentO
 					return
 				}
 				fetchedAgent <- fetchAgent{agent: agent}
-				t.Reset(opts.FetchInterval)
+
+				// Adjust the interval based on how long we've been waiting.
+				elapsed := time.Since(startTime)
+				currentInterval := GetProgressiveInterval(baseInterval, elapsed)
+				t.Reset(currentInterval)
 			}
 		}
 	}()
@@ -293,6 +300,24 @@ func safeDuration(sw *stageWriter, a, b *time.Time) time.Duration {
 	return a.Sub(*b)
 }
 
+// GetProgressiveInterval returns an interval that increases over time.
+// The interval starts at baseInterval and increases to
+// a maximum of baseInterval * 16 over time.
+func GetProgressiveInterval(baseInterval time.Duration, elapsed time.Duration) time.Duration {
+	switch {
+	case elapsed < 60*time.Second:
+		return baseInterval // 500ms for first 60 seconds
+	case elapsed < 2*time.Minute:
+		return baseInterval * 2 // 1s for next 1 minute
+	case elapsed < 5*time.Minute:
+		return baseInterval * 4 // 2s for next 3 minutes
+	case elapsed < 10*time.Minute:
+		return baseInterval * 8 // 4s for next 5 minutes
+	default:
+		return baseInterval * 16 // 8s after 10 minutes
+	}
+}
+
 type closeFunc func() error
 
 func (c closeFunc) Close() error {

cli/cliui/agent_test.go

@@ -866,3 +866,31 @@ func TestConnDiagnostics(t *testing.T) {
 		})
 	}
 }
+
+func TestGetProgressiveInterval(t *testing.T) {
+	t.Parallel()
+
+	baseInterval := 500 * time.Millisecond
+
+	testCases := []struct {
+		name     string
+		elapsed  time.Duration
+		expected time.Duration
+	}{
+		{"first_minute", 30 * time.Second, baseInterval},
+		{"second_minute", 90 * time.Second, baseInterval * 2},
+		{"third_to_fifth_minute", 3 * time.Minute, baseInterval * 4},
+		{"sixth_to_tenth_minute", 7 * time.Minute, baseInterval * 8},
+		{"after_ten_minutes", 15 * time.Minute, baseInterval * 16},
+		{"boundary_first_minute", 59 * time.Second, baseInterval},
+		{"boundary_second_minute", 61 * time.Second, baseInterval * 2},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			result := cliui.GetProgressiveInterval(baseInterval, tc.elapsed)
+			require.Equal(t, tc.expected, result)
+		})
+	}
+}

cli/cliui/table.go

@@ -296,22 +296,23 @@ func renderTable(out any, sort string, headers table.Row, filterColumns []string
 // returned. If the table tag is malformed, an error is returned.
 //
 // The returned name is transformed from "snake_case" to "normal text".
-func parseTableStructTag(field reflect.StructField) (name string, defaultSort, noSortOpt, recursive, skipParentName bool, err error) {
+func parseTableStructTag(field reflect.StructField) (name string, defaultSort, noSortOpt, recursive, skipParentName, emptyNil bool, err error) {
 	tags, err := structtag.Parse(string(field.Tag))
 	if err != nil {
-		return "", false, false, false, false, xerrors.Errorf("parse struct field tag %q: %w", string(field.Tag), err)
+		return "", false, false, false, false, false, xerrors.Errorf("parse struct field tag %q: %w", string(field.Tag), err)
 	}
 
 	tag, err := tags.Get("table")
 	if err != nil || tag.Name == "-" {
 		// tags.Get only returns an error if the tag is not found.
-		return "", false, false, false, false, nil
+		return "", false, false, false, false, false, nil
 	}
 
 	defaultSortOpt := false
 	noSortOpt = false
 	recursiveOpt := false
 	skipParentNameOpt := false
+	emptyNilOpt := false
 	for _, opt := range tag.Options {
 		switch opt {
 		case "default_sort":
@@ -326,12 +327,14 @@ func parseTableStructTag(field reflect.StructField) (name string, defaultSort, n
 			// make sure the child name is unique across all nested structs in the parent.
 			recursiveOpt = true
 			skipParentNameOpt = true
+		case "empty_nil":
+			emptyNilOpt = true
 		default:
-			return "", false, false, false, false, xerrors.Errorf("unknown option %q in struct field tag", opt)
+			return "", false, false, false, false, false, xerrors.Errorf("unknown option %q in struct field tag", opt)
 		}
 	}
 
-	return strings.ReplaceAll(tag.Name, "_", " "), defaultSortOpt, noSortOpt, recursiveOpt, skipParentNameOpt, nil
+	return strings.ReplaceAll(tag.Name, "_", " "), defaultSortOpt, noSortOpt, recursiveOpt, skipParentNameOpt, emptyNilOpt, nil
 }
 
 func isStructOrStructPointer(t reflect.Type) bool {
@@ -358,7 +361,7 @@ func typeToTableHeaders(t reflect.Type, requireDefault bool) ([]string, string,
 	noSortOpt := false
 	for i := 0; i < t.NumField(); i++ {
 		field := t.Field(i)
-		name, defaultSort, noSort, recursive, skip, err := parseTableStructTag(field)
+		name, defaultSort, noSort, recursive, skip, _, err := parseTableStructTag(field)
 		if err != nil {
 			return nil, "", xerrors.Errorf("parse struct tags for field %q in type %q: %w", field.Name, t.String(), err)
 		}
@@ -435,7 +438,7 @@ func valueToTableMap(val reflect.Value) (map[string]any, error) {
 	for i := 0; i < val.NumField(); i++ {
 		field := val.Type().Field(i)
 		fieldVal := val.Field(i)
-		name, _, _, recursive, skip, err := parseTableStructTag(field)
+		name, _, _, recursive, skip, emptyNil, err := parseTableStructTag(field)
 		if err != nil {
 			return nil, xerrors.Errorf("parse struct tags for field %q in type %T: %w", field.Name, val, err)
 		}
@@ -443,8 +446,14 @@ func valueToTableMap(val reflect.Value) (map[string]any, error) {
 			continue
 		}
 
-		// Recurse if it's a struct.
 		fieldType := field.Type
+
+		// If empty_nil is set and this is a nil pointer, use a zero value.
+		if emptyNil && fieldVal.Kind() == reflect.Pointer && fieldVal.IsNil() {
+			fieldVal = reflect.New(fieldType.Elem())
+		}
+
+		// Recurse if it's a struct.
 		if recursive {
 			if !isStructOrStructPointer(fieldType) {
 				return nil, xerrors.Errorf("field %q in type %q is marked as recursive but does not contain a struct or a pointer to a struct", field.Name, fieldType.String())
@@ -467,7 +476,7 @@ func valueToTableMap(val reflect.Value) (map[string]any, error) {
 		}
 
 		// Otherwise, we just use the field value.
-		row[name] = val.Field(i).Interface()
+		row[name] = fieldVal.Interface()
 	}
 
 	return row, nil

cli/cliui/table_test.go

@@ -400,6 +400,78 @@ foo   <nil>      10  [a, b, c]  foo1               11  foo2        12         fo
 			})
 		})
 	})
+
+	t.Run("EmptyNil", func(t *testing.T) {
+		t.Parallel()
+
+		type emptyNilTest struct {
+			Name           string  `table:"name,default_sort"`
+			EmptyOnNil     *string `table:"empty_on_nil,empty_nil"`
+			NormalBehavior *string `table:"normal_behavior"`
+		}
+
+		value := "value"
+		in := []emptyNilTest{
+			{
+				Name:           "has_value",
+				EmptyOnNil:     &value,
+				NormalBehavior: &value,
+			},
+			{
+				Name:           "has_nil",
+				EmptyOnNil:     nil,
+				NormalBehavior: nil,
+			},
+		}
+
+		expected := `
+NAME       EMPTY ON NIL  NORMAL BEHAVIOR
+has_nil                  <nil>
+has_value  value         value
+		`
+
+		out, err := cliui.DisplayTable(in, "", nil)
+		log.Println("rendered table:\n" + out)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+	})
+
+	t.Run("EmptyNilWithRecursiveInline", func(t *testing.T) {
+		t.Parallel()
+
+		type nestedData struct {
+			Name string `table:"name"`
+		}
+
+		type inlineTest struct {
+			Nested *nestedData `table:"ignored,recursive_inline,empty_nil"`
+			Count  int         `table:"count,default_sort"`
+		}
+
+		in := []inlineTest{
+			{
+				Nested: &nestedData{
+					Name: "alice",
+				},
+				Count: 1,
+			},
+			{
+				Nested: nil,
+				Count:  2,
+			},
+		}
+
+		expected := `
+NAME   COUNT
+alice  1
+       2
+		`
+
+		out, err := cliui.DisplayTable(in, "", nil)
+		log.Println("rendered table:\n" + out)
+		require.NoError(t, err)
+		compareTables(t, expected, out)
+	})
 }
 
 // compareTables normalizes the incoming table lines

cli/configssh.go

@@ -236,7 +236,6 @@ func (r *RootCmd) configSSH() *serpent.Command {
 		dryRun          bool
 		coderCliPath    string
 	)
-	client := new(codersdk.Client)
 	cmd := &serpent.Command{
 		Annotations: workspaceCommand,
 		Use:         "config-ssh",
@@ -253,9 +252,13 @@ func (r *RootCmd) configSSH() *serpent.Command {
 		),
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(0),
-			r.InitClient(client),
 		),
 		Handler: func(inv *serpent.Invocation) error {
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
 			ctx := inv.Context()
 
 			if sshConfigOpts.waitEnum != "auto" && sshConfigOpts.skipProxyCommand {
@@ -280,7 +283,6 @@ func (r *RootCmd) configSSH() *serpent.Command {
 				out = inv.Stderr
 			}
 
-			var err error
 			coderBinary := coderCliPath
 			if coderBinary == "" {
 				coderBinary, err = currentBinPath(out)

cli/configssh_internal_test.go

@@ -135,11 +135,13 @@ func Test_sshConfigSplitOnCoderSection(t *testing.T) {
 	}
 }
 
-// This test tries to mimic the behavior of OpenSSH
-// when executing e.g. a ProxyCommand.
-// nolint:tparallel
+// This test tries to mimic the behavior of OpenSSH when executing e.g. a ProxyCommand.
+// nolint:paralleltest
 func Test_sshConfigProxyCommandEscape(t *testing.T) {
-	t.Parallel()
+	// Don't run this test, or any of its subtests in parallel. The test works by writing a file and then immediately
+	// executing it.  Other tests might also exec a subprocess, and if they do in parallel, there is a small race
+	// condition where our file is open when they fork, and remains open while we attempt to execute it, causing
+	// a "text file busy" error.
 
 	tests := []struct {
 		name    string

cli/create.go

@@ -50,7 +50,6 @@ func (r *RootCmd) Create(opts CreateOptions) *serpent.Command {
 		// shares the same name across multiple organizations.
 		orgContext = NewOrganizationContext()
 	)
-	client := new(codersdk.Client)
 	cmd := &serpent.Command{
 		Annotations: workspaceCommand,
 		Use:         "create [workspace]",
@@ -61,9 +60,12 @@ func (r *RootCmd) Create(opts CreateOptions) *serpent.Command {
 				Command:     "coder create <username>/<workspace_name>",
 			},
 		),
-		Middleware: serpent.Chain(r.InitClient(client)),
 		Handler: func(inv *serpent.Invocation) error {
-			var err error
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
 			workspaceOwner := codersdk.Me
 			if len(inv.Args) >= 1 {
 				workspaceOwner, workspaceName, err = splitNamedWorkspace(inv.Args[0])
@@ -575,53 +577,57 @@ func prepWorkspaceBuild(inv *serpent.Invocation, client *codersdk.Client, args p
 		return nil, xerrors.Errorf("template version git auth: %w", err)
 	}
 
-	// Run a dry-run with the given parameters to check correctness
-	dryRun, err := client.CreateTemplateVersionDryRun(inv.Context(), templateVersion.ID, codersdk.CreateTemplateVersionDryRunRequest{
-		WorkspaceName:       args.NewWorkspaceName,
-		RichParameterValues: buildParameters,
-	})
-	if err != nil {
-		return nil, xerrors.Errorf("begin workspace dry-run: %w", err)
-	}
+	// Only perform dry-run for workspace creation and updates
+	// Skip for start and restart to avoid unnecessary delays
+	if args.Action == WorkspaceCreate || args.Action == WorkspaceUpdate {
+		// Run a dry-run with the given parameters to check correctness
+		dryRun, err := client.CreateTemplateVersionDryRun(inv.Context(), templateVersion.ID, codersdk.CreateTemplateVersionDryRunRequest{
+			WorkspaceName:       args.NewWorkspaceName,
+			RichParameterValues: buildParameters,
+		})
+		if err != nil {
+			return nil, xerrors.Errorf("begin workspace dry-run: %w", err)
+		}
 
-	matchedProvisioners, err := client.TemplateVersionDryRunMatchedProvisioners(inv.Context(), templateVersion.ID, dryRun.ID)
-	if err != nil {
-		return nil, xerrors.Errorf("get matched provisioners: %w", err)
-	}
-	cliutil.WarnMatchedProvisioners(inv.Stdout, &matchedProvisioners, dryRun)
-	_, _ = fmt.Fprintln(inv.Stdout, "Planning workspace...")
-	err = cliui.ProvisionerJob(inv.Context(), inv.Stdout, cliui.ProvisionerJobOptions{
-		Fetch: func() (codersdk.ProvisionerJob, error) {
-			return client.TemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
-		},
-		Cancel: func() error {
-			return client.CancelTemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
-		},
-		Logs: func() (<-chan codersdk.ProvisionerJobLog, io.Closer, error) {
-			return client.TemplateVersionDryRunLogsAfter(inv.Context(), templateVersion.ID, dryRun.ID, 0)
-		},
-		// Don't show log output for the dry-run unless there's an error.
-		Silent: true,
-	})
-	if err != nil {
-		// TODO (Dean): reprompt for parameter values if we deem it to
-		// be a validation error
-		return nil, xerrors.Errorf("dry-run workspace: %w", err)
-	}
+		matchedProvisioners, err := client.TemplateVersionDryRunMatchedProvisioners(inv.Context(), templateVersion.ID, dryRun.ID)
+		if err != nil {
+			return nil, xerrors.Errorf("get matched provisioners: %w", err)
+		}
+		cliutil.WarnMatchedProvisioners(inv.Stdout, &matchedProvisioners, dryRun)
+		_, _ = fmt.Fprintln(inv.Stdout, "Planning workspace...")
+		err = cliui.ProvisionerJob(inv.Context(), inv.Stdout, cliui.ProvisionerJobOptions{
+			Fetch: func() (codersdk.ProvisionerJob, error) {
+				return client.TemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
+			},
+			Cancel: func() error {
+				return client.CancelTemplateVersionDryRun(inv.Context(), templateVersion.ID, dryRun.ID)
+			},
+			Logs: func() (<-chan codersdk.ProvisionerJobLog, io.Closer, error) {
+				return client.TemplateVersionDryRunLogsAfter(inv.Context(), templateVersion.ID, dryRun.ID, 0)
+			},
+			// Don't show log output for the dry-run unless there's an error.
+			Silent: true,
+		})
+		if err != nil {
+			// TODO (Dean): reprompt for parameter values if we deem it to
+			// be a validation error
+			return nil, xerrors.Errorf("dry-run workspace: %w", err)
+		}
 
-	resources, err := client.TemplateVersionDryRunResources(inv.Context(), templateVersion.ID, dryRun.ID)
-	if err != nil {
-		return nil, xerrors.Errorf("get workspace dry-run resources: %w", err)
-	}
+		resources, err := client.TemplateVersionDryRunResources(inv.Context(), templateVersion.ID, dryRun.ID)
+		if err != nil {
+			return nil, xerrors.Errorf("get workspace dry-run resources: %w", err)
+		}
 
-	err = cliui.WorkspaceResources(inv.Stdout, resources, cliui.WorkspaceResourcesOptions{
-		WorkspaceName: args.NewWorkspaceName,
-		// Since agents haven't connected yet, hiding this makes more sense.
-		HideAgentState: true,
-		Title:          "Workspace Preview",
-	})
-	if err != nil {
-		return nil, xerrors.Errorf("get resources: %w", err)
+		err = cliui.WorkspaceResources(inv.Stdout, resources, cliui.WorkspaceResourcesOptions{
+			WorkspaceName: args.NewWorkspaceName,
+			// Since agents haven't connected yet, hiding this makes more sense.
+			HideAgentState: true,
+			Title:          "Workspace Preview",
+		})
+		if err != nil {
+			return nil, xerrors.Errorf("get resources: %w", err)
+		}
 	}
 
 	return buildParameters, nil

cli/delete.go

@@ -16,7 +16,6 @@ func (r *RootCmd) deleteWorkspace() *serpent.Command {
 		orphan bool
 		prov   buildFlags
 	)
-	client := new(codersdk.Client)
 	cmd := &serpent.Command{
 		Annotations: workspaceCommand,
 		Use:         "delete <workspace>",
@@ -29,9 +28,13 @@ func (r *RootCmd) deleteWorkspace() *serpent.Command {
 		),
 		Middleware: serpent.Chain(
 			serpent.RequireNArgs(1),
-			r.InitClient(client),
 		),
 		Handler: func(inv *serpent.Invocation) error {
+			client, err := r.InitClient(inv)
+			if err != nil {
+				return err
+			}
+
 			workspace, err := namedWorkspace(inv.Context(), client, inv.Args[0])
 			if err != nil {
 				return err

cli/delete_test.go

@@ -185,9 +185,6 @@ func TestDelete(t *testing.T) {
 
 	t.Run("WarnNoProvisioners", func(t *testing.T) {
 		t.Parallel()
-		if !dbtestutil.WillUsePostgres() {
-			t.Skip("this test requires postgres")
-		}
 
 		store, ps, db := dbtestutil.NewDBWithSQLDB(t)
 		client, closeDaemon := coderdtest.NewWithProvisionerCloser(t, &coderdtest.Options{
@@ -228,9 +225,6 @@ func TestDelete(t *testing.T) {
 
 	t.Run("Prebuilt workspace delete permissions", func(t *testing.T) {
 		t.Parallel()
-		if !dbtestutil.WillUsePostgres() {
-			t.Skip("this test requires postgres")
-		}
 
 		// Setup
 		db, pb := dbtestutil.NewDB(t, dbtestutil.WithDumpOnFailure())

cli/exp.go

@@ -1,23 +0,0 @@
-package cli
-
-import "github.com/coder/serpent"
-
-func (r *RootCmd) expCmd() *serpent.Command {
-	cmd := &serpent.Command{
-		Use:   "exp",
-		Short: "Internal commands for testing and experimentation. These are prone to breaking changes with no notice.",
-		Handler: func(i *serpent.Invocation) error {
-			return i.Command.HelpHandler(i)
-		},
-		Hidden: true,
-		Children: []*serpent.Command{
-			r.scaletestCmd(),
-			r.errorExample(),
-			r.mcpCommand(),
-			r.promptExample(),
-			r.rptyCommand(),
-			r.tasksCommand(),
-		},
-	}
-	return cmd
-}

cli/exp_boundary.go

@@ -0,0 +1,12 @@
+package cli
+
+import (
+	boundarycli "github.com/coder/boundary/cli"
+	"github.com/coder/serpent"
+)
+
+func (*RootCmd) boundary() *serpent.Command {
+	cmd := boundarycli.BaseCommand() // Package coder/boundary/cli exports a "base command" designed to be integrated as a subcommand.
+	cmd.Use += " [args...]"          // The base command looks like `boundary -- command`. Serpent adds the flags piece, but we need to add the args.
+	return cmd
+}

cli/exp_boundary_test.go

@@ -0,0 +1,33 @@
+package cli_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	boundarycli "github.com/coder/boundary/cli"
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// Actually testing the functionality of coder/boundary takes place in the
+// coder/boundary repo, since it's a dependency of coder.
+// Here we want to test basically that integrating it as a subcommand doesn't break anything.
+func TestBoundarySubcommand(t *testing.T) {
+	t.Parallel()
+	ctx := testutil.Context(t, testutil.WaitShort)
+
+	inv, _ := clitest.New(t, "exp", "boundary", "--help")
+	pty := ptytest.New(t).Attach(inv)
+
+	go func() {
+		err := inv.WithContext(ctx).Run()
+		assert.NoError(t, err)
+	}()
+
+	// Expect the --help output to include the short description.
+	// We're simply confirming that `coder boundary --help` ran without a runtime error as
+	// a good chunk of serpents self validation logic happens at runtime.
+	pty.ExpectMatch(boundarycli.BaseCommand().Short)
+}

cli/exp_mcp.go

@@ -56,7 +56,7 @@ func (r *RootCmd) mcpConfigure() *serpent.Command {
 		},
 		Children: []*serpent.Command{
 			r.mcpConfigureClaudeDesktop(),
-			r.mcpConfigureClaudeCode(),
+			mcpConfigureClaudeCode(),
 			r.mcpConfigureCursor(),
 		},
 	}
@@ -117,7 +117,7 @@ func (*RootCmd) mcpConfigureClaudeDesktop() *serpent.Command {
 	return cmd
 }
 
-func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
+func mcpConfigureClaudeCode() *serpent.Command {
 	var (
 		claudeAPIKey     string
 		claudeConfigPath string
@@ -131,6 +131,7 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 
 		deprecatedCoderMCPClaudeAPIKey string
 	)
+	agentAuth := &AgentAuth{}
 	cmd := &serpent.Command{
 		Use:   "claude-code <project-directory>",
 		Short: "Configure the Claude Code server. You will need to run this command for each project you want to use. Specify the project directory as the first argument.",
@@ -148,7 +149,7 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 				binPath = testBinaryName
 			}
 			configureClaudeEnv := map[string]string{}
-			agentClient, err := r.createAgentClient()
+			agentClient, err := agentAuth.CreateClient()
 			if err != nil {
 				cliui.Warnf(inv.Stderr, "failed to create agent client: %s", err)
 			} else {
@@ -292,6 +293,7 @@ func (r *RootCmd) mcpConfigureClaudeCode() *serpent.Command {
 			},
 		},
 	}
+	agentAuth.AttachOptions(cmd, false)
 	return cmd
 }
 
@@ -397,15 +399,20 @@ type mcpServer struct {
 
 func (r *RootCmd) mcpServer() *serpent.Command {
 	var (
-		client        = new(codersdk.Client)
 		instructions  string
 		allowedTools  []string
 		appStatusSlug string
 		aiAgentAPIURL url.URL
 	)
-	return &serpent.Command{
+	agentAuth := &AgentAuth{}
+	cmd := &serpent.Command{
 		Use: "server",
 		Handler: func(inv *serpent.Invocation) error {
+			client, err := r.TryInitClient(inv)
+			if err != nil {
+				return err
+			}
+
 			var lastReport taskReport
 			// Create a queue that skips duplicates and preserves summaries.
 			queue := cliutil.NewQueue[taskReport](512).WithPredicate(func(report taskReport) (taskReport, bool) {
@@ -494,7 +501,7 @@ func (r *RootCmd) mcpServer() *serpent.Command {
 			}
 
 			// Try to create an agent client for status reporting.  Not validated.
-			agentClient, err := r.createAgentClient()
+			agentClient, err := agentAuth.CreateClient()
 			if err == nil {
 				cliui.Infof(inv.Stderr, "Agent URL      : %s", agentClient.SDK.URL.String())
 				srv.agentClient = agentClient
@@ -545,9 +552,6 @@ func (r *RootCmd) mcpServer() *serpent.Command {
 			return srv.startServer(ctx, inv, instructions, allowedTools)
 		},
 		Short: "Start the Coder MCP server.",
-		Middleware: serpent.Chain(
-			r.TryInitClient(client),
-		),
 		Options: []serpent.Option{
 			{
 				Name:        "instructions",
@@ -579,6 +583,8 @@ func (r *RootCmd) mcpServer() *serpent.Command {
 			},
 		},
 	}
+	agentAuth.AttachOptions(cmd, false)
+	return cmd
 }
 
 func (s *mcpServer) startReporter(ctx context.Context, inv *serpent.Invocation) {