feat(site)!: add consent prompt for auto-creation with prefilled parameters (#22256 )

Cherry-pick of 60e3ab7632 from main. Workspace created via mode=auto links now require explicit user confirmation before provisioning. A warning dialog shows all prefilled param.* values from the URL and blocks creation until the user clicks `Confirm and Create`. Clicking `Cancel` falls back to the standard form view. ### Breaking behavior change Links using `mode=auto` (e.g., "Open in Coder" buttons) will no longer silently create workspaces. Users will now see a consent dialog and must explicitly confirm before the workspace is provisioned. Original PR: #22011 Co-authored-by: Kacper Sawicki <kacper@coder.com> Co-authored-by: Jake Howell <jacob@coder.com>
fix: avoid re-using AuthInstanceID for sub agents (#22196 ) (#22212 )
2026-02-23 17:37:57 -05:00 · 2026-02-23 17:37:41 -05:00 · 2026-02-23 17:37:15 -05:00 · 2026-02-23 15:32:41 +01:00 · 2026-02-20 12:49:36 +01:00 · 2026-02-05 16:35:41 -06:00
188 changed files with 5634 additions and 2510 deletions
@@ -27,7 +27,7 @@ ignorePatterns:
  - pattern: "splunk.com"
  - pattern: "stackoverflow.com/questions"
  - pattern: "developer.hashicorp.com/terraform/language"
-  - pattern: "platform.openai.com/docs/api-reference"
+  - pattern: "platform.openai.com"
  - pattern: "api.openai.com"
 aliveStatusCodes:
  - 200
@@ -7,5 +7,5 @@ runs:
    - name: Install Terraform
      uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3.1.2
      with:
-        terraform_version: 1.13.4
+        terraform_version: 1.14.5
        terraform_wrapper: false
@@ -35,7 +35,7 @@ jobs:
      tailnet-integration: ${{ steps.filter.outputs.tailnet-integration }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -157,7 +157,7 @@ jobs:
    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -235,7 +235,7 @@ jobs:
    if: ${{ !cancelled() }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -292,7 +292,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -343,7 +343,7 @@ jobs:
          - windows-2022
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -532,7 +532,7 @@ jobs:
    timeout-minutes: 25
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -581,7 +581,7 @@ jobs:
    timeout-minutes: 25
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -641,7 +641,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -668,7 +668,7 @@ jobs:
    timeout-minutes: 20
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -701,7 +701,7 @@ jobs:
    name: ${{ matrix.variant.name }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -781,7 +781,7 @@ jobs:
    if: needs.changes.outputs.site == 'true' || needs.changes.outputs.ci == 'true'
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -862,7 +862,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -933,7 +933,7 @@ jobs:
    if: always()
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -1053,7 +1053,7 @@ jobs:
    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -1108,7 +1108,7 @@ jobs:
      IMAGE: ghcr.io/coder/coder-preview:${{ steps.build-docker.outputs.tag }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -1505,7 +1505,7 @@ 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@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -36,7 +36,7 @@ jobs:
      verdict: ${{ steps.check.outputs.verdict }} # DEPLOY or NOOP
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -65,7 +65,7 @@ jobs:
      packages: write # to retag image as dogfood
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -146,7 +146,7 @@ jobs:
    needs: deploy
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -38,7 +38,7 @@ jobs:
    if: github.repository_owner == 'coder'
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -26,7 +26,7 @@ jobs:
    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-4' || 'ubuntu-latest' }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -125,7 +125,7 @@ jobs:
      id-token: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -27,7 +27,7 @@ jobs:
          - windows-2022
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

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

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

@@ -39,7 +39,7 @@ jobs:
      PR_OPEN: ${{ steps.check_pr.outputs.pr_open }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -76,7 +76,7 @@ jobs:
    runs-on: "ubuntu-latest"
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -184,7 +184,7 @@ jobs:
      pull-requests: write # needed for commenting on PRs
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -228,7 +228,7 @@ jobs:
      CODER_IMAGE_TAG: ${{ needs.get_info.outputs.CODER_IMAGE_TAG }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -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@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -14,7 +14,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -164,7 +164,7 @@ jobs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -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@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -878,7 +878,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -971,7 +971,7 @@ jobs:
    if: ${{ !inputs.dry_run }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -20,7 +20,7 @@ jobs:

    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -27,7 +27,7 @@ jobs:
    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -69,7 +69,7 @@ jobs:
    runs-on: ${{ github.repository_owner == 'coder' && 'depot-ubuntu-22.04-8' || 'ubuntu-latest' }}
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -146,7 +146,7 @@ jobs:
          echo "image=$(cat "$image_job")" >> "$GITHUB_OUTPUT"

      - name: Run Trivy vulnerability scanner
-        uses: aquasecurity/trivy-action@b6643a29fecd7f34b3597bc6acb0a98b03d33ff8
+        uses: aquasecurity/trivy-action@c1824fd6edce30d7ab345a9989de00bbd46ef284 # v0.34.0
        with:
          image-ref: ${{ steps.build.outputs.image }}
          format: sarif
@@ -18,7 +18,7 @@ jobs:
      pull-requests: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -96,7 +96,7 @@ jobs:
      contents: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -120,7 +120,7 @@ jobs:
      actions: write
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -21,7 +21,7 @@ jobs:
      pull-requests: write # required to post PR review comments by the action
    steps:
      - name: Harden Runner
-        uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
+        uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2
        with:
          egress-policy: audit

@@ -69,6 +69,9 @@ MOST_GO_SRC_FILES := $(shell \
 # All the shell files in the repo, excluding ignored files.
 SHELL_SRC_FILES := $(shell find . $(FIND_EXCLUSIONS) -type f -name '*.sh')

+MIGRATION_FILES := $(shell find ./coderd/database/migrations/ -maxdepth 1 $(FIND_EXCLUSIONS) -type f -name '*.sql')
+FIXTURE_FILES := $(shell find ./coderd/database/migrations/testdata/fixtures/ $(FIND_EXCLUSIONS) -type f -name '*.sql')
+
 # Ensure we don't use the user's git configs which might cause side-effects
 GIT_FLAGS = GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null

@@ -561,7 +564,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/check-scopes
+lint: lint/shellcheck lint/go lint/ts lint/examples lint/helm lint/site-icons lint/markdown lint/actions/actionlint lint/check-scopes lint/migrations
 .PHONY: lint

 lint/site-icons:
@@ -619,6 +622,12 @@ lint/check-scopes: coderd/database/dump.sql
 	go run ./scripts/check-scopes
 .PHONY: lint/check-scopes

+# Verify migrations do not hardcode the public schema.
+lint/migrations:
+	./scripts/check_pg_schema.sh "Migrations" $(MIGRATION_FILES)
+	./scripts/check_pg_schema.sh "Fixtures" $(FIXTURE_FILES)
+.PHONY: lint/migrations
+
 # 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 := \
@@ -41,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"
@@ -97,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 {
@@ -202,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
@@ -279,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 {
@@ -358,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
@@ -1095,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))
@@ -1928,6 +1960,7 @@ func (a *agent) Close() error {
 			lifecycleState = codersdk.WorkspaceAgentLifecycleShutdownError
 		}
 	}
+
 	a.setLifecycle(lifecycleState)

 	err = a.scriptRunner.Close()
@@ -1935,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))
 	}
@@ -0,0 +1,149 @@
+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),
+	})
+	if err != nil {
+		return false, xerrors.Errorf("sync ready: %w", err)
+	}
+	return resp.Ready, nil
+}
+
+// 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"`
+}
@@ -7,8 +7,6 @@ import (
 	"sync"

 	"golang.org/x/xerrors"
-
-	"github.com/hashicorp/yamux"
 	"storj.io/drpc/drpcmux"
 	"storj.io/drpc/drpcserver"

@@ -33,11 +31,17 @@ type Server struct {
 	wg       sync.WaitGroup
 }

-func NewServer(path string, logger slog.Logger) (*Server, error) {
+// 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:   path,
+		path:   options.path,
 		service: &DRPCAgentSocketService{
 			logger:      logger,
 			unitManager: unit.NewManager(),
@@ -61,14 +65,6 @@ func NewServer(path string, logger slog.Logger) (*Server, error) {
 		},
 	})

-	if server.path == "" {
-		var err error
-		server.path, err = getDefaultSocketPath()
-		if err != nil {
-			return nil, xerrors.Errorf("get default socket path: %w", err)
-		}
-	}
-
 	listener, err := createSocket(server.path)
 	if err != nil {
 		return nil, xerrors.Errorf("create socket: %w", err)
@@ -91,6 +87,7 @@ func NewServer(path string, logger slog.Logger) (*Server, error) {
 	return server, nil
 }

+// Close stops the server and cleans up resources.
 func (s *Server) Close() error {
 	s.mu.Lock()

@@ -134,52 +131,8 @@ func (s *Server) acceptConnections() {
 		return
 	}

-	for {
-		select {
-		case <-s.ctx.Done():
-			return
-		default:
-		}
-
-		conn, err := listener.Accept()
-		if err != nil {
-			s.logger.Warn(s.ctx, "error accepting connection", slog.Error(err))
-			continue
-		}
-
-		s.mu.Lock()
-		if s.listener == nil {
-			s.mu.Unlock()
-			_ = conn.Close()
-			return
-		}
-		s.wg.Add(1)
-		s.mu.Unlock()
-
-		go func() {
-			defer s.wg.Done()
-			s.handleConnection(conn)
-		}()
-	}
-}
-
-func (s *Server) handleConnection(conn net.Conn) {
-	defer conn.Close()
-
-	s.logger.Debug(s.ctx, "new connection accepted", slog.F("remote_addr", conn.RemoteAddr()))
-
-	config := yamux.DefaultConfig()
-	config.LogOutput = nil
-	config.Logger = slog.Stdlib(s.ctx, s.logger.Named("agentsocket-yamux"), slog.LevelInfo)
-	session, err := yamux.Server(conn, config)
-	if err != nil {
-		s.logger.Warn(s.ctx, "failed to create yamux session", slog.Error(err))
-		return
-	}
-	defer session.Close()
-
-	err = s.drpcServer.Serve(s.ctx, session)
-	if err != nil {
-		s.logger.Debug(s.ctx, "drpc server finished", slog.Error(err))
+	err := s.drpcServer.Serve(s.ctx, listener)
+	if err != nil {
+		s.logger.Warn(s.ctx, "error serving drpc server", slog.Error(err))
 	}
 }
@@ -1,14 +1,24 @@
 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) {
@@ -23,7 +33,7 @@ func TestServer(t *testing.T) {

 		socketPath := filepath.Join(t.TempDir(), "test.sock")
 		logger := slog.Make().Leveled(slog.LevelDebug)
-		server, err := agentsocket.NewServer(socketPath, logger)
+		server, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
 		require.NoError(t, err)
 		require.NoError(t, server.Close())
 	})
@@ -33,10 +43,10 @@ func TestServer(t *testing.T) {

 		socketPath := filepath.Join(t.TempDir(), "test.sock")
 		logger := slog.Make().Leveled(slog.LevelDebug)
-		server1, err := agentsocket.NewServer(socketPath, logger)
+		server1, err := agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
 		require.NoError(t, err)
 		defer server1.Close()
-		_, err = agentsocket.NewServer(socketPath, logger)
+		_, err = agentsocket.NewServer(logger, agentsocket.WithPath(socketPath))
 		require.ErrorContains(t, err, "create socket")
 	})

@@ -45,8 +55,84 @@ func TestServer(t *testing.T) {

 		socketPath := filepath.Join(t.TempDir(), "test.sock")
 		logger := slog.Make().Leveled(slog.LevelDebug)
-		server, err := agentsocket.NewServer(socketPath, logger)
+		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")
+}
@@ -15,15 +15,18 @@ 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)
@@ -53,6 +56,7 @@ func (s *DRPCAgentSocketService) SyncStart(_ context.Context, req *proto.SyncSta
 	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)
@@ -72,6 +76,7 @@ func (s *DRPCAgentSocketService) SyncWant(_ context.Context, req *proto.SyncWant
 	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)
@@ -86,6 +91,7 @@ func (s *DRPCAgentSocketService) SyncComplete(_ context.Context, req *proto.Sync
 	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)
@@ -102,6 +108,7 @@ func (s *DRPCAgentSocketService) SyncReady(_ context.Context, req *proto.SyncRea
 	}, 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)
@@ -115,8 +122,11 @@ func (s *DRPCAgentSocketService) SyncStatus(_ context.Context, req *proto.SyncSt
 	}

 	dependencies, err := s.unitManager.GetAllDependencies(unitID)
-	if err != nil {
-		return nil, xerrors.Errorf("failed to get dependencies: %w", err)
+	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
@@ -5,21 +5,18 @@ import (
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
-	"net"
 	"os"
 	"path/filepath"
 	"runtime"
 	"testing"

-	"github.com/hashicorp/yamux"
 	"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/agentsocket/proto"
 	"github.com/coder/coder/v2/agent/unit"
-	"github.com/coder/coder/v2/codersdk/drpcsdk"
+	"github.com/coder/coder/v2/testutil"
 )

 // tempDirUnixSocket returns a temporary directory that can safely hold unix
@@ -47,23 +44,15 @@ func tempDirUnixSocket(t *testing.T) string {
 }

 // newSocketClient creates a DRPC client connected to the Unix socket at the given path.
-func newSocketClient(t *testing.T, socketPath string) proto.DRPCAgentSocketClient {
+func newSocketClient(ctx context.Context, t *testing.T, socketPath string) *agentsocket.Client {
 	t.Helper()

-	conn, err := net.Dial("unix", socketPath)
-	require.NoError(t, err)
-
-	config := yamux.DefaultConfig()
-	config.Logger = nil
-	session, err := yamux.Client(conn, config)
-	require.NoError(t, err)
-
-	client := proto.NewDRPCAgentSocketClient(drpcsdk.MultiplexedConn(session))
-
+	client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(socketPath))
 	t.Cleanup(func() {
-		_ = session.Close()
-		_ = conn.Close()
+		_ = client.Close()
 	})
+	require.NoError(t, err)
+
 	return client
 }

@@ -78,17 +67,17 @@ func TestDRPCAgentSocketService(t *testing.T) {
 		t.Parallel()

 		socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
-
+		ctx := testutil.Context(t, testutil.WaitShort)
 		server, err := agentsocket.NewServer(
-			socketPath,
 			slog.Make().Leveled(slog.LevelDebug),
+			agentsocket.WithPath(socketPath),
 		)
 		require.NoError(t, err)
 		defer server.Close()

-		client := newSocketClient(t, socketPath)
+		client := newSocketClient(ctx, t, socketPath)

-		_, err = client.Ping(context.Background(), &proto.PingRequest{})
+		err = client.Ping(ctx)
 		require.NoError(t, err)
 	})

@@ -98,147 +87,116 @@ func TestDRPCAgentSocketService(t *testing.T) {
 		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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// First Start
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)
-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			require.Equal(t, unit.StatusStarted, status.Status)

 			// Second Start
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.ErrorContains(t, err, unit.ErrSameStatusAlreadySet.Error())

-			status, err = client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err = client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// First start
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			require.Equal(t, unit.StatusStarted, status.Status)

 			// Complete the unit
-			_, err = client.SyncComplete(context.Background(), &proto.SyncCompleteRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncComplete(ctx, "test-unit")
 			require.NoError(t, err)

-			status, err = client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err = client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "completed", status.Status)
+			require.Equal(t, unit.StatusComplete, status.Status)

 			// Second start
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)

-			status, err = client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err = client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

-			_, err = client.SyncWant(context.Background(), &proto.SyncWantRequest{
-				Unit:      "test-unit",
-				DependsOn: "dependency-unit",
-			})
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
 			require.NoError(t, err)

-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.ErrorContains(t, err, "unit not ready")

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, string(unit.StatusPending), status.Status)
+			require.Equal(t, unit.StatusPending, status.Status)
 			require.False(t, status.IsReady)
 		})
 	})
@@ -250,107 +208,86 @@ func TestDRPCAgentSocketService(t *testing.T) {
 			t.Parallel()

 			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
-
+			ctx := testutil.Context(t, testutil.WaitShort)
 			server, err := agentsocket.NewServer(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// If dependency units are not registered, they are registered automatically
-			_, err = client.SyncWant(context.Background(), &proto.SyncWantRequest{
-				Unit:      "test-unit",
-				DependsOn: "dependency-unit",
-			})
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
 			require.NoError(t, err)

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
 			require.Len(t, status.Dependencies, 1)
-			require.Equal(t, "dependency-unit", status.Dependencies[0].DependsOn)
-			require.Equal(t, "completed", status.Dependencies[0].RequiredStatus)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// Start the dependency unit
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "dependency-unit",
-			})
+			err = client.SyncStart(ctx, "dependency-unit")
 			require.NoError(t, err)

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "dependency-unit",
-			})
+			status, err := client.SyncStatus(ctx, "dependency-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			require.Equal(t, unit.StatusStarted, status.Status)

 			// Add the dependency after the dependency unit has already started
-			_, err = client.SyncWant(context.Background(), &proto.SyncWantRequest{
-				Unit:      "test-unit",
-				DependsOn: "dependency-unit",
-			})
+			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(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err = client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "dependency-unit", status.Dependencies[0].DependsOn)
-			require.Equal(t, "completed", status.Dependencies[0].RequiredStatus)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// Start the dependent unit
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)

-			status, err := client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err := client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "started", status.Status)
+			require.Equal(t, unit.StatusStarted, status.Status)

 			// Add the dependency after the dependency unit has already started
-			_, err = client.SyncWant(context.Background(), &proto.SyncWantRequest{
-				Unit:      "test-unit",
-				DependsOn: "dependency-unit",
-			})
+			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.
@@ -359,12 +296,10 @@ func TestDRPCAgentSocketService(t *testing.T) {
 			require.NoError(t, err)

 			// The dependency is now reflected in the test unit's status
-			status, err = client.SyncStatus(context.Background(), &proto.SyncStatusRequest{
-				Unit: "test-unit",
-			})
+			status, err = client.SyncStatus(ctx, "test-unit")
 			require.NoError(t, err)
-			require.Equal(t, "dependency-unit", status.Dependencies[0].DependsOn)
-			require.Equal(t, "completed", status.Dependencies[0].RequiredStatus)
+			require.Equal(t, unit.ID("dependency-unit"), status.Dependencies[0].DependsOn)
+			require.Equal(t, unit.StatusComplete, status.Dependencies[0].RequiredStatus)
 		})
 	})

@@ -375,96 +310,80 @@ func TestDRPCAgentSocketService(t *testing.T) {
 			t.Parallel()

 			socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
-
+			ctx := testutil.Context(t, testutil.WaitShort)
 			server, err := agentsocket.NewServer(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

-			response, err := client.SyncReady(context.Background(), &proto.SyncReadyRequest{
-				Unit: "unregistered-unit",
-			})
+			ready, err := client.SyncReady(ctx, "unregistered-unit")
 			require.NoError(t, err)
-			require.False(t, response.Ready)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// Register a unit with an unsatisfied dependency
-			_, err = client.SyncWant(context.Background(), &proto.SyncWantRequest{
-				Unit:      "test-unit",
-				DependsOn: "dependency-unit",
-			})
+			err = client.SyncWant(ctx, "test-unit", "dependency-unit")
 			require.NoError(t, err)

 			// Check readiness - should be false because dependency is not satisfied
-			response, err := client.SyncReady(context.Background(), &proto.SyncReadyRequest{
-				Unit: "test-unit",
-			})
+			ready, err := client.SyncReady(ctx, "test-unit")
 			require.NoError(t, err)
-			require.False(t, response.Ready)
+			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(
-				socketPath,
 				slog.Make().Leveled(slog.LevelDebug),
+				agentsocket.WithPath(socketPath),
 			)
 			require.NoError(t, err)
 			defer server.Close()

-			client := newSocketClient(t, socketPath)
+			client := newSocketClient(ctx, t, socketPath)

 			// Register a unit with no dependencies - should be ready immediately
-			_, err = client.SyncStart(context.Background(), &proto.SyncStartRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncStart(ctx, "test-unit")
 			require.NoError(t, err)

 			// Check readiness - should be true
-			_, err = client.SyncReady(context.Background(), &proto.SyncReadyRequest{
-				Unit: "test-unit",
-			})
+			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(context.Background(), &proto.SyncWantRequest{
-				Unit:      "dependent-unit",
-				DependsOn: "test-unit",
-			})
+			err = client.SyncWant(ctx, "dependent-unit", "test-unit")
 			require.NoError(t, err)

 			// Complete the dependency
-			_, err = client.SyncComplete(context.Background(), &proto.SyncCompleteRequest{
-				Unit: "test-unit",
-			})
+			err = client.SyncComplete(ctx, "test-unit")
 			require.NoError(t, err)

 			// Now dependent-unit should be ready
-			_, err = client.SyncReady(context.Background(), &proto.SyncReadyRequest{
-				Unit: "dependent-unit",
-			})
+			ready, err = client.SyncReady(ctx, "dependent-unit")
 			require.NoError(t, err)
+			require.True(t, ready)
 		})
 	})
 }
@@ -3,8 +3,7 @@
 package agentsocket

 import (
-	"crypto/rand"
-	"encoding/hex"
+	"context"
 	"net"
 	"os"
 	"path/filepath"
@@ -13,8 +12,13 @@ import (
 	"golang.org/x/xerrors"
 )

-// createSocket creates a Unix domain socket listener
+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)
 	}
@@ -23,7 +27,6 @@ func createSocket(path string) (net.Listener, error) {
 		return nil, xerrors.Errorf("remove existing socket: %w", err)
 	}

-	// Create parent directory if it doesn't exist
 	parentDir := filepath.Dir(path)
 	if err := os.MkdirAll(parentDir, 0o700); err != nil {
 		return nil, xerrors.Errorf("create socket directory: %w", err)
@@ -41,43 +44,30 @@ func createSocket(path string) (net.Listener, error) {
 	return listener, nil
 }

-// getDefaultSocketPath returns the default socket path for Unix-like systems
-func getDefaultSocketPath() (string, error) {
-	randomBytes := make([]byte, 4)
-	if _, err := rand.Read(randomBytes); err != nil {
-		return "", xerrors.Errorf("generate random socket name: %w", err)
-	}
-	randomSuffix := hex.EncodeToString(randomBytes)
-
-	// Try XDG_RUNTIME_DIR first
-	if runtimeDir := os.Getenv("XDG_RUNTIME_DIR"); runtimeDir != "" {
-		return filepath.Join(runtimeDir, "coder-agent-"+randomSuffix+".sock"), nil
-	}
-
-	return filepath.Join("/tmp", "coder-agent-"+randomSuffix+".sock"), nil
-}
-
-// CleanupSocket removes the socket file
 func cleanupSocket(path string) error {
 	return os.Remove(path)
 }

-// isSocketAvailable checks if a socket path is available for use
 func isSocketAvailable(path string) bool {
-	// Check if file exists
 	if _, err := os.Stat(path); os.IsNotExist(err) {
 		return true
 	}

-	// Try to connect to see if it's actually listening
+	// 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 {
-		// If we can't connect, the socket is not in use
-		// Socket is available for use
 		return true
 	}
 	_ = conn.Close()
-	// Socket is in use
 	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)
+}
@@ -3,25 +3,20 @@
 package agentsocket

 import (
+	"context"
 	"net"

 	"golang.org/x/xerrors"
 )

-// createSocket returns an error indicating that agentsocket is not supported on Windows.
-// This feature is unix-only in its current experimental state.
 func createSocket(_ string) (net.Listener, error) {
 	return nil, xerrors.New("agentsocket is not supported on Windows")
 }

-// getDefaultSocketPath returns an error indicating that agentsocket is not supported on Windows.
-// This feature is unix-only in its current experimental state.
-func getDefaultSocketPath() (string, error) {
-	return "", xerrors.New("agentsocket is not supported on Windows")
-}
-
-// cleanupSocket is a no-op on Windows since agentsocket is not supported.
 func cleanupSocket(_ string) error {
-	// No-op since agentsocket is not supported on Windows
 	return nil
 }
+
+func dialSocket(_ context.Context, _ string) (net.Conn, error) {
+	return nil, xerrors.New("agentsocket is not supported on Windows")
+}
@@ -4,6 +4,8 @@ import (
 	"os"

 	"github.com/hashicorp/go-reap"
+
+	"cdr.dev/slog"
 )

 type Option func(o *options)
@@ -34,8 +36,15 @@ func WithCatchSignals(sigs ...os.Signal) Option {
 	}
 }

+func WithLogger(logger slog.Logger) Option {
+	return func(o *options) {
+		o.Logger = logger
+	}
+}
+
 type options struct {
 	ExecArgs     []string
 	PIDs         reap.PidCh
 	CatchSignals []os.Signal
+	Logger       slog.Logger
 }
@@ -7,6 +7,6 @@ func IsInitProcess() bool {
 	return false
 }

-func ForkReap(_ ...Option) error {
-	return nil
+func ForkReap(_ ...Option) (int, error) {
+	return 0, nil
 }
@@ -32,12 +32,13 @@ func TestReap(t *testing.T) {
 	}

 	pids := make(reap.PidCh, 1)
-	err := reaper.ForkReap(
+	exitCode, err := reaper.ForkReap(
 		reaper.WithPIDCallback(pids),
 		// Provide some argument that immediately exits.
 		reaper.WithExecArgs("/bin/sh", "-c", "exit 0"),
 	)
 	require.NoError(t, err)
+	require.Equal(t, 0, exitCode)

 	cmd := exec.Command("tail", "-f", "/dev/null")
 	err = cmd.Start()
@@ -65,6 +66,36 @@ func TestReap(t *testing.T) {
 	}
 }

+//nolint:paralleltest
+func TestForkReapExitCodes(t *testing.T) {
+	if testutil.InCI() {
+		t.Skip("Detected CI, skipping reaper tests")
+	}
+
+	tests := []struct {
+		name         string
+		command      string
+		expectedCode int
+	}{
+		{"exit 0", "exit 0", 0},
+		{"exit 1", "exit 1", 1},
+		{"exit 42", "exit 42", 42},
+		{"exit 255", "exit 255", 255},
+		{"SIGKILL", "kill -9 $$", 128 + 9},
+		{"SIGTERM", "kill -15 $$", 128 + 15},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			exitCode, err := reaper.ForkReap(
+				reaper.WithExecArgs("/bin/sh", "-c", tt.command),
+			)
+			require.NoError(t, err)
+			require.Equal(t, tt.expectedCode, exitCode, "exit code mismatch for %q", tt.command)
+		})
+	}
+}
+
 //nolint:paralleltest // Signal handling.
 func TestReapInterrupt(t *testing.T) {
 	// Don't run the reaper test in CI. It does weird
@@ -84,13 +115,17 @@ func TestReapInterrupt(t *testing.T) {
 	defer signal.Stop(usrSig)

 	go func() {
-		errC <- reaper.ForkReap(
+		exitCode, err := reaper.ForkReap(
 			reaper.WithPIDCallback(pids),
 			reaper.WithCatchSignals(os.Interrupt),
 			// Signal propagation does not extend to children of children, so
 			// we create a little bash script to ensure sleep is interrupted.
 			reaper.WithExecArgs("/bin/sh", "-c", fmt.Sprintf("pid=0; trap 'kill -USR2 %d; kill -TERM $pid' INT; sleep 10 &\npid=$!; kill -USR1 %d; wait", os.Getpid(), os.Getpid())),
 		)
+		// The child exits with 128 + SIGTERM (15) = 143, but the trap catches
+		// SIGINT and sends SIGTERM to the sleep process, so exit code varies.
+		_ = exitCode
+		errC <- err
 	}()

 	require.Equal(t, <-usrSig, syscall.SIGUSR1)
@@ -3,12 +3,15 @@
 package reaper

 import (
+	"context"
 	"os"
 	"os/signal"
 	"syscall"

 	"github.com/hashicorp/go-reap"
 	"golang.org/x/xerrors"
+
+	"cdr.dev/slog"
 )

 // IsInitProcess returns true if the current process's PID is 1.
@@ -16,7 +19,7 @@ func IsInitProcess() bool {
 	return os.Getpid() == 1
 }

-func catchSignals(pid int, sigs []os.Signal) {
+func catchSignals(logger slog.Logger, pid int, sigs []os.Signal) {
 	if len(sigs) == 0 {
 		return
 	}
@@ -25,10 +28,19 @@ func catchSignals(pid int, sigs []os.Signal) {
 	signal.Notify(sc, sigs...)
 	defer signal.Stop(sc)

+	logger.Info(context.Background(), "reaper catching signals",
+		slog.F("signals", sigs),
+		slog.F("child_pid", pid),
+	)
+
 	for {
 		s := <-sc
 		sig, ok := s.(syscall.Signal)
 		if ok {
+			logger.Info(context.Background(), "reaper caught signal, killing child process",
+				slog.F("signal", sig.String()),
+				slog.F("child_pid", pid),
+			)
 			_ = syscall.Kill(pid, sig)
 		}
 	}
@@ -40,7 +52,10 @@ func catchSignals(pid int, sigs []os.Signal) {
 // the reaper and an exec.Command waiting for its process to complete.
 // The provided 'pids' channel may be nil if the caller does not care about the
 // reaped children PIDs.
-func ForkReap(opt ...Option) error {
+//
+// Returns the child's exit code (using 128+signal for signal termination)
+// and any error from Wait4.
+func ForkReap(opt ...Option) (int, error) {
 	opts := &options{
 		ExecArgs: os.Args,
 	}
@@ -53,7 +68,7 @@ func ForkReap(opt ...Option) error {

 	pwd, err := os.Getwd()
 	if err != nil {
-		return xerrors.Errorf("get wd: %w", err)
+		return 1, xerrors.Errorf("get wd: %w", err)
 	}

 	pattrs := &syscall.ProcAttr{
@@ -72,15 +87,28 @@ func ForkReap(opt ...Option) error {
 	//#nosec G204
 	pid, err := syscall.ForkExec(opts.ExecArgs[0], opts.ExecArgs, pattrs)
 	if err != nil {
-		return xerrors.Errorf("fork exec: %w", err)
+		return 1, xerrors.Errorf("fork exec: %w", err)
 	}

-	go catchSignals(pid, opts.CatchSignals)
+	go catchSignals(opts.Logger, pid, opts.CatchSignals)

 	var wstatus syscall.WaitStatus
 	_, err = syscall.Wait4(pid, &wstatus, 0, nil)
 	for xerrors.Is(err, syscall.EINTR) {
 		_, err = syscall.Wait4(pid, &wstatus, 0, nil)
 	}
-	return err
+
+	// Convert wait status to exit code using standard Unix conventions:
+	// - Normal exit: use the exit code
+	// - Signal termination: use 128 + signal number
+	var exitCode int
+	switch {
+	case wstatus.Exited():
+		exitCode = wstatus.ExitStatus()
+	case wstatus.Signaled():
+		exitCode = 128 + int(wstatus.Signal())
+	default:
+		exitCode = 1
+	}
+	return exitCode, err
 }
@@ -2,6 +2,7 @@ package unit

 import (
 	"errors"
+	"fmt"
 	"sync"

 	"golang.org/x/xerrors"
@@ -23,6 +24,15 @@ var (
 // 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 = ""
@@ -137,7 +147,7 @@ func (m *Manager) IsReady(id ID) (bool, error) {
 	defer m.mu.RUnlock()

 	if !m.registered(id) {
-		return false, nil
+		return true, nil
 	}

 	return m.units[id].ready, nil
@@ -684,7 +684,7 @@ func TestManager_IsReady(t *testing.T) {
 		// Then: the unit is not ready
 		isReady, err := manager.IsReady(unitA)
 		require.NoError(t, err)
-		assert.False(t, isReady)
+		assert.True(t, isReady)
 	})
 }

@@ -9,6 +9,7 @@ import (
 	"net/http/pprof"
 	"net/url"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"runtime"
 	"slices"
@@ -57,6 +58,8 @@ func workspaceAgent() *serpent.Command {
 		devcontainers                  bool
 		devcontainerProjectDiscovery   bool
 		devcontainerDiscoveryAutostart bool
+		socketServerEnabled            bool
+		socketPath                     string
 	)
 	agentAuth := &AgentAuth{}
 	cmd := &serpent.Command{
@@ -128,40 +131,29 @@ func workspaceAgent() *serpent.Command {

 				sinks = append(sinks, sloghuman.Sink(logWriter))
 				logger := inv.Logger.AppendSinks(sinks...).Leveled(slog.LevelDebug)
+				logger = logger.Named("reaper")

 				logger.Info(ctx, "spawning reaper process")
 				// Do not start a reaper on the child process. It's important
 				// to do this else we fork bomb ourselves.
 				//nolint:gocritic
 				args := append(os.Args, "--no-reap")
-				err := reaper.ForkReap(
+				exitCode, err := reaper.ForkReap(
 					reaper.WithExecArgs(args...),
 					reaper.WithCatchSignals(StopSignals...),
+					reaper.WithLogger(logger),
 				)
 				if err != nil {
 					logger.Error(ctx, "agent process reaper unable to fork", slog.Error(err))
 					return xerrors.Errorf("fork reap: %w", err)
 				}

-				logger.Info(ctx, "reaper process exiting")
-				return nil
+				logger.Info(ctx, "child process exited, propagating exit code",
+					slog.F("exit_code", exitCode),
+				)
+				return ExitError(exitCode, nil)
 			}

-			// Handle interrupt signals to allow for graceful shutdown,
-			// note that calling stopNotify disables the signal handler
-			// and the next interrupt will terminate the program (you
-			// probably want cancel instead).
-			//
-			// Note that we don't want to handle these signals in the
-			// process that runs as PID 1, that's why we do this after
-			// the reaper forked.
-			ctx, stopNotify := inv.SignalNotifyContext(ctx, StopSignals...)
-			defer stopNotify()
-
-			// DumpHandler does signal handling, so we call it after the
-			// reaper.
-			go DumpHandler(ctx, "agent")
-
 			logWriter := &clilog.LumberjackWriteCloseFixer{Writer: &lumberjack.Logger{
 				Filename: filepath.Join(logDir, "coder-agent.log"),
 				MaxSize:  5, // MB
@@ -174,6 +166,21 @@ func workspaceAgent() *serpent.Command {
 			sinks = append(sinks, sloghuman.Sink(logWriter))
 			logger := inv.Logger.AppendSinks(sinks...).Leveled(slog.LevelDebug)

+			// Handle interrupt signals to allow for graceful shutdown,
+			// note that calling stopNotify disables the signal handler
+			// and the next interrupt will terminate the program (you
+			// probably want cancel instead).
+			//
+			// Note that we also handle these signals in the
+			// process that runs as PID 1, mainly to forward it to the agent child
+			// so that it can shutdown gracefully.
+			ctx, stopNotify := logSignalNotifyContext(ctx, logger, StopSignals...)
+			defer stopNotify()
+
+			// DumpHandler does signal handling, so we call it after the
+			// reaper.
+			go DumpHandler(ctx, "agent")
+
 			version := buildinfo.Version()
 			logger.Info(ctx, "agent is starting now",
 				slog.F("url", agentAuth.agentURL),
@@ -317,6 +324,8 @@ func workspaceAgent() *serpent.Command {
 						agentcontainers.WithProjectDiscovery(devcontainerProjectDiscovery),
 						agentcontainers.WithDiscoveryAutostart(devcontainerDiscoveryAutostart),
 					},
+					SocketPath:          socketPath,
+					SocketServerEnabled: socketServerEnabled,
 				})

 				if debugAddress != "" {
@@ -477,6 +486,19 @@ func 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
@@ -540,3 +562,26 @@ func urlPort(u string) (int, error) {
 	}
 	return -1, xerrors.Errorf("invalid port: %s", u)
 }
+
+// logSignalNotifyContext is like signal.NotifyContext but logs the received
+// signal before canceling the context.
+func logSignalNotifyContext(parent context.Context, logger slog.Logger, signals ...os.Signal) (context.Context, context.CancelFunc) {
+	ctx, cancel := context.WithCancelCause(parent)
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, signals...)
+
+	go func() {
+		select {
+		case sig := <-c:
+			logger.Info(ctx, "agent received signal", slog.F("signal", sig.String()))
+			cancel(xerrors.Errorf("signal: %s", sig.String()))
+		case <-ctx.Done():
+			logger.Info(ctx, "ctx canceled, stopping signal handler")
+		}
+	}()
+
+	return ctx, func() {
+		cancel(context.Canceled)
+		signal.Stop(c)
+	}
+}
@@ -61,10 +61,10 @@ func NewWithCommand(
 	t testing.TB, cmd *serpent.Command, args ...string,
 ) (*serpent.Invocation, config.Root) {
 	configDir := config.Root(t.TempDir())
-	// Keyring usage is disabled here 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), "--use-keyring=false"}, args...)
+	// 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
 }

@@ -54,6 +54,7 @@ func setupKeyringTestEnv(t *testing.T, clientURL string, args ...string) keyring

 	serviceName := keyringTestServiceName(t)
 	root.WithKeyringServiceName(serviceName)
+	root.UseKeyringWithGlobalConfig()

 	inv, cfg := clitest.NewWithDefaultKeyringCommand(t, cmd, args...)

@@ -169,6 +170,7 @@ func TestUseKeyring(t *testing.T) {
 		logoutCmd, err := logoutRoot.Command(logoutRoot.AGPL())
 		require.NoError(t, err)
 		logoutRoot.WithKeyringServiceName(env.serviceName)
+		logoutRoot.UseKeyringWithGlobalConfig()

 		logoutInv, _ := clitest.NewWithDefaultKeyringCommand(t, logoutCmd,
 			"logout",
@@ -150,6 +150,7 @@ func (r *RootCmd) AGPLExperimental() []*serpent.Command {
 		r.mcpCommand(),
 		r.promptExample(),
 		r.rptyCommand(),
+		r.syncCommand(),
 		r.boundary(),
 	}
 }
@@ -483,9 +484,9 @@ func (r *RootCmd) Command(subcommands []*serpent.Command) (*serpent.Command, err
 			Flag: varUseKeyring,
 			Env:  envUseKeyring,
 			Description: "Store and retrieve session tokens using the operating system " +
-				"keyring. Enabled by default. If the keyring is not supported on the " +
-				"current platform, file-based storage is used automatically. Set to " +
-				"false to force file-based storage.",
+				"keyring. This flag is ignored and file-based storage is used when " +
+				"--global-config is set or keyring usage is not supported on the current " +
+				"platform. Set to false to force file-based storage on supported platforms.",
 			Default: "true",
 			Value:   serpent.BoolOf(&r.useKeyring),
 			Group:   globalGroup,
@@ -536,11 +537,12 @@ type RootCmd struct {
 	disableDirect bool
 	debugHTTP     bool

-	disableNetworkTelemetry bool
-	noVersionCheck          bool
-	noFeatureWarning        bool
-	useKeyring              bool
-	keyringServiceName      string
+	disableNetworkTelemetry    bool
+	noVersionCheck             bool
+	noFeatureWarning           bool
+	useKeyring                 bool
+	keyringServiceName         string
+	useKeyringWithGlobalConfig bool
 }

 // InitClient creates and configures a new client with authentication, telemetry,
@@ -721,8 +723,14 @@ func (r *RootCmd) createUnauthenticatedClient(ctx context.Context, serverURL *ur
 // flag.
 func (r *RootCmd) ensureTokenBackend() sessionstore.Backend {
 	if r.tokenBackend == nil {
+		// Checking for the --global-config directory being set is a bit wonky but necessary
+		// to allow extensions that invoke the CLI with this flag (e.g. VS code) to continue
+		// working without modification. In the future we should modify these extensions to
+		// either access the credential in the keyring (like Coder Desktop) or some other
+		// approach that doesn't rely on the session token being stored on disk.
+		assumeExtensionInUse := r.globalConfig != config.DefaultDir() && !r.useKeyringWithGlobalConfig
 		keyringSupported := runtime.GOOS == "windows" || runtime.GOOS == "darwin"
-		if r.useKeyring && keyringSupported {
+		if r.useKeyring && !assumeExtensionInUse && keyringSupported {
 			serviceName := sessionstore.DefaultServiceName
 			if r.keyringServiceName != "" {
 				serviceName = r.keyringServiceName
@@ -742,6 +750,13 @@ func (r *RootCmd) WithKeyringServiceName(serviceName string) {
 	r.keyringServiceName = serviceName
 }

+// UseKeyringWithGlobalConfig enables the use of the keyring storage backend
+// when the --global-config directory is set. This is only intended as an override
+// for tests, which require specifying the global config directory for test isolation.
+func (r *RootCmd) UseKeyringWithGlobalConfig() {
+	r.useKeyringWithGlobalConfig = true
+}
+
 type AgentAuth struct {
 	// Agent Client config
 	agentToken     string
@@ -72,6 +72,31 @@ func TestCommandHelp(t *testing.T) {
 			Name: "coder provisioner jobs list --output json",
 			Cmd:  []string{"provisioner", "jobs", "list", "--output", "json"},
 		},
+		// TODO (SasSwart): Remove these once the sync commands are promoted out of experimental.
+		clitest.CommandHelpCase{
+			Name: "coder exp sync --help",
+			Cmd:  []string{"exp", "sync", "--help"},
+		},
+		clitest.CommandHelpCase{
+			Name: "coder exp sync ping --help",
+			Cmd:  []string{"exp", "sync", "ping", "--help"},
+		},
+		clitest.CommandHelpCase{
+			Name: "coder exp sync start --help",
+			Cmd:  []string{"exp", "sync", "start", "--help"},
+		},
+		clitest.CommandHelpCase{
+			Name: "coder exp sync want --help",
+			Cmd:  []string{"exp", "sync", "want", "--help"},
+		},
+		clitest.CommandHelpCase{
+			Name: "coder exp sync complete --help",
+			Cmd:  []string{"exp", "sync", "complete", "--help"},
+		},
+		clitest.CommandHelpCase{
+			Name: "coder exp sync status --help",
+			Cmd:  []string{"exp", "sync", "status", "--help"},
+		},
 	))
 }

@@ -87,6 +87,7 @@ func buildNumberOption(n *int64) serpent.Option {

 func (r *RootCmd) statePush() *serpent.Command {
 	var buildNumber int64
+	var noBuild bool
 	cmd := &serpent.Command{
 		Use:   "push <workspace> <file>",
 		Short: "Push a Terraform state file to a workspace.",
@@ -126,6 +127,16 @@ func (r *RootCmd) statePush() *serpent.Command {
 				return err
 			}

+			if noBuild {
+				// Update state directly without triggering a build.
+				err = client.UpdateWorkspaceBuildState(inv.Context(), build.ID, state)
+				if err != nil {
+					return err
+				}
+				_, _ = fmt.Fprintln(inv.Stdout, "State updated successfully.")
+				return nil
+			}
+
 			build, err = client.CreateWorkspaceBuild(inv.Context(), workspace.ID, codersdk.CreateWorkspaceBuildRequest{
 				TemplateVersionID: build.TemplateVersionID,
 				Transition:        build.Transition,
@@ -139,6 +150,12 @@ func (r *RootCmd) statePush() *serpent.Command {
 	}
 	cmd.Options = serpent.OptionSet{
 		buildNumberOption(&buildNumber),
+		{
+			Flag:          "no-build",
+			FlagShorthand: "n",
+			Description:   "Update the state without triggering a workspace build. Useful for state-only migrations.",
+			Value:         serpent.BoolOf(&noBuild),
+		},
 	}
 	return cmd
 }
@@ -2,6 +2,7 @@ package cli_test

 import (
 	"bytes"
+	"context"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -10,6 +11,7 @@ import (
 	"testing"

 	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/database/dbauthz"
 	"github.com/coder/coder/v2/coderd/database/dbfake"

 	"github.com/stretchr/testify/require"
@@ -158,4 +160,49 @@ func TestStatePush(t *testing.T) {
 		err := inv.Run()
 		require.NoError(t, err)
 	})
+
+	t.Run("NoBuild", func(t *testing.T) {
+		t.Parallel()
+		client, store := coderdtest.NewWithDatabase(t, nil)
+		owner := coderdtest.CreateFirstUser(t, client)
+		templateAdmin, taUser := coderdtest.CreateAnotherUser(t, client, owner.OrganizationID, rbac.RoleTemplateAdmin())
+		initialState := []byte("initial state")
+		r := dbfake.WorkspaceBuild(t, store, database.WorkspaceTable{
+			OrganizationID: owner.OrganizationID,
+			OwnerID:        taUser.ID,
+		}).
+			Seed(database.WorkspaceBuild{ProvisionerState: initialState}).
+			Do()
+		wantState := []byte("updated state")
+		stateFile, err := os.CreateTemp(t.TempDir(), "")
+		require.NoError(t, err)
+		_, err = stateFile.Write(wantState)
+		require.NoError(t, err)
+		err = stateFile.Close()
+		require.NoError(t, err)
+
+		inv, root := clitest.New(t, "state", "push", "--no-build", r.Workspace.Name, stateFile.Name())
+		clitest.SetupConfig(t, templateAdmin, root)
+		var stdout bytes.Buffer
+		inv.Stdout = &stdout
+		err = inv.Run()
+		require.NoError(t, err)
+		require.Contains(t, stdout.String(), "State updated successfully")
+
+		// Verify the state was updated by pulling it.
+		inv, root = clitest.New(t, "state", "pull", r.Workspace.Name)
+		var gotState bytes.Buffer
+		inv.Stdout = &gotState
+		clitest.SetupConfig(t, templateAdmin, root)
+		err = inv.Run()
+		require.NoError(t, err)
+		require.Equal(t, wantState, bytes.TrimSpace(gotState.Bytes()))
+
+		// Verify no new build was created.
+		builds, err := store.GetWorkspaceBuildsByWorkspaceID(dbauthz.AsSystemRestricted(context.Background()), database.GetWorkspaceBuildsByWorkspaceIDParams{
+			WorkspaceID: r.Workspace.ID,
+		})
+		require.NoError(t, err)
+		require.Len(t, builds, 1, "expected only the initial build, no new build should be created")
+	})
 }
@@ -0,0 +1,35 @@
+package cli
+
+import (
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) syncCommand() *serpent.Command {
+	var socketPath string
+
+	cmd := &serpent.Command{
+		Use:   "sync",
+		Short: "Manage unit dependencies for coordinated startup",
+		Long:  "Commands for orchestrating unit startup order in workspaces. Units are most commonly coder scripts. Use these commands to declare dependencies between units, coordinate their startup sequence, and ensure units start only after their dependencies are ready. This helps prevent race conditions and startup failures.",
+		Handler: func(i *serpent.Invocation) error {
+			return i.Command.HelpHandler(i)
+		},
+		Children: []*serpent.Command{
+			r.syncPing(&socketPath),
+			r.syncStart(&socketPath),
+			r.syncWant(&socketPath),
+			r.syncComplete(&socketPath),
+			r.syncStatus(&socketPath),
+		},
+		Options: serpent.OptionSet{
+			{
+				Flag:        "socket-path",
+				Env:         "CODER_AGENT_SOCKET_PATH",
+				Description: "Specify the path for the agent socket.",
+				Value:       serpent.StringOf(&socketPath),
+			},
+		},
+	}
+
+	return cmd
+}
@@ -0,0 +1,47 @@
+package cli
+
+import (
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/serpent"
+)
+
+func (*RootCmd) syncComplete(socketPath *string) *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "complete <unit>",
+		Short: "Mark a unit as complete",
+		Long:  "Mark a unit as complete. Indicating to other units that it has completed its work. This allows units that depend on it to proceed with their startup.",
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+
+			if len(i.Args) != 1 {
+				return xerrors.New("exactly one unit name is required")
+			}
+			unit := unit.ID(i.Args[0])
+
+			opts := []agentsocket.Option{}
+			if *socketPath != "" {
+				opts = append(opts, agentsocket.WithPath(*socketPath))
+			}
+
+			client, err := agentsocket.NewClient(ctx, opts...)
+			if err != nil {
+				return xerrors.Errorf("connect to agent socket: %w", err)
+			}
+			defer client.Close()
+
+			if err := client.SyncComplete(ctx, unit); err != nil {
+				return xerrors.Errorf("complete unit failed: %w", err)
+			}
+
+			cliui.Info(i.Stdout, "Success")
+
+			return nil
+		},
+	}
+
+	return cmd
+}
@@ -0,0 +1,42 @@
+package cli
+
+import (
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/serpent"
+)
+
+func (*RootCmd) syncPing(socketPath *string) *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "ping",
+		Short: "Test agent socket connectivity and health",
+		Long:  "Test connectivity to the local Coder agent socket to verify the agent is running and responsive. Useful for troubleshooting startup issues or verifying the agent is accessible before running other sync commands.",
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+
+			opts := []agentsocket.Option{}
+			if *socketPath != "" {
+				opts = append(opts, agentsocket.WithPath(*socketPath))
+			}
+
+			client, err := agentsocket.NewClient(ctx, opts...)
+			if err != nil {
+				return xerrors.Errorf("connect to agent socket: %w", err)
+			}
+			defer client.Close()
+
+			err = client.Ping(ctx)
+			if err != nil {
+				return xerrors.Errorf("ping failed: %w", err)
+			}
+
+			cliui.Info(i.Stdout, "Success")
+
+			return nil
+		},
+	}
+
+	return cmd
+}
@@ -0,0 +1,101 @@
+package cli
+
+import (
+	"context"
+	"time"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/serpent"
+
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/cli/cliui"
+)
+
+const (
+	syncPollInterval = 1 * time.Second
+)
+
+func (*RootCmd) syncStart(socketPath *string) *serpent.Command {
+	var timeout time.Duration
+
+	cmd := &serpent.Command{
+		Use:   "start <unit>",
+		Short: "Wait until all unit dependencies are satisfied",
+		Long:  "Wait until all dependencies are satisfied, consider the unit to have started, then allow it to proceed. This command polls until dependencies are ready, then marks the unit as started.",
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+
+			if len(i.Args) != 1 {
+				return xerrors.New("exactly one unit name is required")
+			}
+			unitName := unit.ID(i.Args[0])
+
+			if timeout > 0 {
+				var cancel context.CancelFunc
+				ctx, cancel = context.WithTimeout(ctx, timeout)
+				defer cancel()
+			}
+
+			opts := []agentsocket.Option{}
+			if *socketPath != "" {
+				opts = append(opts, agentsocket.WithPath(*socketPath))
+			}
+
+			client, err := agentsocket.NewClient(ctx, opts...)
+			if err != nil {
+				return xerrors.Errorf("connect to agent socket: %w", err)
+			}
+			defer client.Close()
+
+			ready, err := client.SyncReady(ctx, unitName)
+			if err != nil {
+				return xerrors.Errorf("error checking dependencies: %w", err)
+			}
+
+			if !ready {
+				cliui.Infof(i.Stdout, "Waiting for dependencies of unit '%s' to be satisfied...", unitName)
+
+				ticker := time.NewTicker(syncPollInterval)
+				defer ticker.Stop()
+
+			pollLoop:
+				for {
+					select {
+					case <-ctx.Done():
+						if ctx.Err() == context.DeadlineExceeded {
+							return xerrors.Errorf("timeout waiting for dependencies of unit '%s'", unitName)
+						}
+						return ctx.Err()
+					case <-ticker.C:
+						ready, err := client.SyncReady(ctx, unitName)
+						if err != nil {
+							return xerrors.Errorf("error checking dependencies: %w", err)
+						}
+						if ready {
+							break pollLoop
+						}
+					}
+				}
+			}
+
+			if err := client.SyncStart(ctx, unitName); err != nil {
+				return xerrors.Errorf("start unit failed: %w", err)
+			}
+
+			cliui.Info(i.Stdout, "Success")
+
+			return nil
+		},
+	}
+
+	cmd.Options = append(cmd.Options, serpent.Option{
+		Flag:        "timeout",
+		Description: "Maximum time to wait for dependencies (e.g., 30s, 5m). 5m by default.",
+		Value:       serpent.DurationOf(&timeout),
+		Default:     "5m",
+	})
+
+	return cmd
+}
@@ -0,0 +1,88 @@
+package cli
+
+import (
+	"fmt"
+
+	"golang.org/x/xerrors"
+
+	"github.com/coder/serpent"
+
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/cli/cliui"
+)
+
+func (*RootCmd) syncStatus(socketPath *string) *serpent.Command {
+	formatter := cliui.NewOutputFormatter(
+		cliui.ChangeFormatterData(
+			cliui.TableFormat(
+				[]agentsocket.DependencyInfo{},
+				[]string{
+					"depends on",
+					"required status",
+					"current status",
+					"satisfied",
+				},
+			),
+			func(data any) (any, error) {
+				resp, ok := data.(agentsocket.SyncStatusResponse)
+				if !ok {
+					return nil, xerrors.Errorf("expected agentsocket.SyncStatusResponse, got %T", data)
+				}
+				return resp.Dependencies, nil
+			}),
+		cliui.JSONFormat(),
+	)
+
+	cmd := &serpent.Command{
+		Use:   "status <unit>",
+		Short: "Show unit status and dependency state",
+		Long:  "Show the current status of a unit, whether it is ready to start, and lists its dependencies. Shows which dependencies are satisfied and which are still pending. Supports multiple output formats.",
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+
+			if len(i.Args) != 1 {
+				return xerrors.New("exactly one unit name is required")
+			}
+			unit := unit.ID(i.Args[0])
+
+			opts := []agentsocket.Option{}
+			if *socketPath != "" {
+				opts = append(opts, agentsocket.WithPath(*socketPath))
+			}
+
+			client, err := agentsocket.NewClient(ctx, opts...)
+			if err != nil {
+				return xerrors.Errorf("connect to agent socket: %w", err)
+			}
+			defer client.Close()
+
+			statusResp, err := client.SyncStatus(ctx, unit)
+			if err != nil {
+				return xerrors.Errorf("get status failed: %w", err)
+			}
+
+			var out string
+			header := fmt.Sprintf("Unit: %s\nStatus: %s\nReady: %t\n\nDependencies:\n", unit, statusResp.Status, statusResp.IsReady)
+			if formatter.FormatID() == "table" && len(statusResp.Dependencies) == 0 {
+				out = header + "No dependencies found"
+			} else {
+				out, err = formatter.Format(ctx, statusResp)
+				if err != nil {
+					return xerrors.Errorf("format status: %w", err)
+				}
+
+				if formatter.FormatID() == "table" {
+					out = header + out
+				}
+			}
+
+			_, _ = fmt.Fprintln(i.Stdout, out)
+
+			return nil
+		},
+	}
+
+	formatter.AttachOptions(&cmd.Options)
+	return cmd
+}
@@ -0,0 +1,330 @@
+//go:build !windows
+
+package cli_test
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"cdr.dev/slog"
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+// setupSocketServer creates an agentsocket server at a temporary path for testing.
+// Returns the socket path and a cleanup function. The path should be passed to
+// sync commands via the --socket-path flag.
+func setupSocketServer(t *testing.T) (path string, cleanup func()) {
+	t.Helper()
+
+	// Use a temporary socket path for each test
+	socketPath := filepath.Join(tempDirUnixSocket(t), "test.sock")
+
+	// Create parent directory if needed
+	parentDir := filepath.Dir(socketPath)
+	err := os.MkdirAll(parentDir, 0o700)
+	require.NoError(t, err, "create socket directory")
+
+	server, err := agentsocket.NewServer(
+		slog.Make().Leveled(slog.LevelDebug),
+		agentsocket.WithPath(socketPath),
+	)
+	require.NoError(t, err, "create socket server")
+
+	// Return cleanup function
+	return socketPath, func() {
+		err := server.Close()
+		require.NoError(t, err, "close socket server")
+		_ = os.Remove(socketPath)
+	}
+}
+
+func TestSyncCommands_Golden(t *testing.T) {
+	t.Parallel()
+
+	t.Run("ping", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "ping", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/ping_success", outBuf.Bytes(), nil)
+	})
+
+	t.Run("start_no_dependencies", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "start", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/start_no_dependencies", outBuf.Bytes(), nil)
+	})
+
+	t.Run("start_with_dependencies", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Set up dependency: test-unit depends on dep-unit
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+
+		// Declare dependency
+		err = client.SyncWant(ctx, "test-unit", "dep-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		// Start a goroutine to complete the dependency after a short delay
+		// This simulates the dependency being satisfied while start is waiting
+		// The delay ensures the "Waiting..." message appears in the output
+		done := make(chan error, 1)
+		go func() {
+			// Wait a moment to let the start command begin waiting and print the message
+			time.Sleep(100 * time.Millisecond)
+
+			compCtx := context.Background()
+			compClient, err := agentsocket.NewClient(compCtx, agentsocket.WithPath(path))
+			if err != nil {
+				done <- err
+				return
+			}
+			defer compClient.Close()
+
+			// Start and complete the dependency unit
+			err = compClient.SyncStart(compCtx, "dep-unit")
+			if err != nil {
+				done <- err
+				return
+			}
+			err = compClient.SyncComplete(compCtx, "dep-unit")
+			done <- err
+		}()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "start", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		// Run the start command - it should wait for the dependency
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		// Ensure the completion goroutine finished
+		select {
+		case err := <-done:
+			require.NoError(t, err, "complete dependency")
+		case <-time.After(time.Second):
+			// Goroutine should have finished by now
+		}
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/start_with_dependencies", outBuf.Bytes(), nil)
+	})
+
+	t.Run("want", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "want", "test-unit", "dep-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err := inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/want_success", outBuf.Bytes(), nil)
+	})
+
+	t.Run("complete", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// First start the unit
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncStart(ctx, "test-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "complete", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/complete_success", outBuf.Bytes(), nil)
+	})
+
+	t.Run("status_pending", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Set up a unit with unsatisfied dependency
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncWant(ctx, "test-unit", "dep-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "status", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/status_pending", outBuf.Bytes(), nil)
+	})
+
+	t.Run("status_started", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Start a unit
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncStart(ctx, "test-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "status", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/status_started", outBuf.Bytes(), nil)
+	})
+
+	t.Run("status_completed", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Start and complete a unit
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncStart(ctx, "test-unit")
+		require.NoError(t, err)
+		err = client.SyncComplete(ctx, "test-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "status", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/status_completed", outBuf.Bytes(), nil)
+	})
+
+	t.Run("status_with_dependencies", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Set up a unit with dependencies, some satisfied, some not
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncWant(ctx, "test-unit", "dep-1")
+		require.NoError(t, err)
+		err = client.SyncWant(ctx, "test-unit", "dep-2")
+		require.NoError(t, err)
+		// Complete dep-1, leave dep-2 incomplete
+		err = client.SyncStart(ctx, "dep-1")
+		require.NoError(t, err)
+		err = client.SyncComplete(ctx, "dep-1")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "status", "test-unit", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/status_with_dependencies", outBuf.Bytes(), nil)
+	})
+
+	t.Run("status_json_format", func(t *testing.T) {
+		t.Parallel()
+		path, cleanup := setupSocketServer(t)
+		defer cleanup()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// Set up a unit with dependencies
+		client, err := agentsocket.NewClient(ctx, agentsocket.WithPath(path))
+		require.NoError(t, err)
+		err = client.SyncWant(ctx, "test-unit", "dep-unit")
+		require.NoError(t, err)
+		err = client.SyncStart(ctx, "dep-unit")
+		require.NoError(t, err)
+		err = client.SyncComplete(ctx, "dep-unit")
+		require.NoError(t, err)
+		client.Close()
+
+		var outBuf bytes.Buffer
+		inv, _ := clitest.New(t, "exp", "sync", "status", "test-unit", "--output", "json", "--socket-path", path)
+		inv.Stdout = &outBuf
+		inv.Stderr = &outBuf
+
+		err = inv.WithContext(ctx).Run()
+		require.NoError(t, err)
+
+		clitest.TestGoldenFile(t, "TestSyncCommands_Golden/status_json_format", outBuf.Bytes(), nil)
+	})
+}
@@ -0,0 +1,49 @@
+package cli
+
+import (
+	"golang.org/x/xerrors"
+
+	"github.com/coder/serpent"
+
+	"github.com/coder/coder/v2/agent/agentsocket"
+	"github.com/coder/coder/v2/agent/unit"
+	"github.com/coder/coder/v2/cli/cliui"
+)
+
+func (*RootCmd) syncWant(socketPath *string) *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "want <unit> <depends-on>",
+		Short: "Declare that a unit depends on another unit completing before it can start",
+		Long:  "Declare that a unit depends on another unit completing before it can start. The unit specified first will not start until the second has signaled that it has completed.",
+		Handler: func(i *serpent.Invocation) error {
+			ctx := i.Context()
+
+			if len(i.Args) != 2 {
+				return xerrors.New("exactly two arguments are required: unit and depends-on")
+			}
+			dependentUnit := unit.ID(i.Args[0])
+			dependsOn := unit.ID(i.Args[1])
+
+			opts := []agentsocket.Option{}
+			if *socketPath != "" {
+				opts = append(opts, agentsocket.WithPath(*socketPath))
+			}
+
+			client, err := agentsocket.NewClient(ctx, opts...)
+			if err != nil {
+				return xerrors.Errorf("connect to agent socket: %w", err)
+			}
+			defer client.Close()
+
+			if err := client.SyncWant(ctx, dependentUnit, dependsOn); err != nil {
+				return xerrors.Errorf("declare dependency failed: %w", err)
+			}
+
+			cliui.Info(i.Stdout, "Success")
+
+			return nil
+		},
+	}
+
+	return cmd
+}
@@ -0,0 +1 @@
+Success
@@ -0,0 +1 @@
+Success
@@ -0,0 +1 @@
+Success
@@ -0,0 +1,2 @@
+Waiting for dependencies of unit 'test-unit' to be satisfied...
+Success
@@ -0,0 +1,6 @@
+Unit: test-unit
+Status: completed
+Ready: true
+
+Dependencies:
+No dependencies found
@@ -0,0 +1,13 @@
+{
+  "unit_name": "test-unit",
+  "status": "pending",
+  "is_ready": true,
+  "dependencies": [
+    {
+      "depends_on": "dep-unit",
+      "required_status": "completed",
+      "current_status": "completed",
+      "is_satisfied": true
+    }
+  ]
+}
@@ -0,0 +1,7 @@
+Unit: test-unit
+Status: pending
+Ready: false
+
+Dependencies:
+DEPENDS ON  REQUIRED STATUS  CURRENT STATUS  SATISFIED  
+dep-unit    completed        not registered  false      
@@ -0,0 +1,6 @@
+Unit: test-unit
+Status: started
+Ready: true
+
+Dependencies:
+No dependencies found
@@ -0,0 +1,8 @@
+Unit: test-unit
+Status: pending
+Ready: false
+
+Dependencies:
+DEPENDS ON  REQUIRED STATUS  CURRENT STATUS  SATISFIED  
+dep-1       completed        completed       true       
+dep-2       completed        not registered  false      
@@ -0,0 +1 @@
+Success
@@ -111,9 +111,10 @@ variables or flags.

      --use-keyring bool, $CODER_USE_KEYRING (default: true)
          Store and retrieve session tokens using the operating system keyring.
-          Enabled by default. If the keyring is not supported on the current
-          platform, file-based storage is used automatically. Set to false to
-          force file-based storage.
+          This flag is ignored and file-based storage is used when
+          --global-config is set or keyring usage is not supported on the
+          current platform. Set to false to force file-based storage on
+          supported platforms.

  -v, --verbose bool, $CODER_VERBOSE
          Enable verbose output.
@@ -67,6 +67,12 @@ OPTIONS:
      --script-data-dir string, $CODER_AGENT_SCRIPT_DATA_DIR (default: /tmp)
          Specify the location for storing script data.

+      --socket-path string, $CODER_AGENT_SOCKET_PATH
+          Specify the path for the agent socket.
+
+      --socket-server-enabled bool, $CODER_AGENT_SOCKET_SERVER_ENABLED (default: false)
+          Enable the agent socket server.
+
      --ssh-max-timeout duration, $CODER_AGENT_SSH_MAX_TIMEOUT (default: 72h)
          Specify the max timeout for a SSH connection, it is advisable to set
          it to a minimum of 60s, but no more than 72h.
@@ -0,0 +1,27 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync [flags]
+
+  Manage unit dependencies for coordinated startup
+
+  Commands for orchestrating unit startup order in workspaces. Units are most
+  commonly coder scripts. Use these commands to declare dependencies between
+  units, coordinate their startup sequence, and ensure units start only after
+  their dependencies are ready. This helps prevent race conditions and startup
+  failures.
+
+SUBCOMMANDS:
+    complete    Mark a unit as complete
+    ping        Test agent socket connectivity and health
+    start       Wait until all unit dependencies are satisfied
+    status      Show unit status and dependency state
+    want        Declare that a unit depends on another unit completing before it
+                can start
+
+OPTIONS:
+      --socket-path string, $CODER_AGENT_SOCKET_PATH
+          Specify the path for the agent socket.
+
+———
+Run `coder --help` for a list of global options.
@@ -0,0 +1,12 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync complete <unit>
+
+  Mark a unit as complete
+
+  Mark a unit as complete. Indicating to other units that it has completed its
+  work. This allows units that depend on it to proceed with their startup.
+
+———
+Run `coder --help` for a list of global options.
@@ -0,0 +1,13 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync ping
+
+  Test agent socket connectivity and health
+
+  Test connectivity to the local Coder agent socket to verify the agent is
+  running and responsive. Useful for troubleshooting startup issues or verifying
+  the agent is accessible before running other sync commands.
+
+———
+Run `coder --help` for a list of global options.
@@ -0,0 +1,17 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync start [flags] <unit>
+
+  Wait until all unit dependencies are satisfied
+
+  Wait until all dependencies are satisfied, consider the unit to have started,
+  then allow it to proceed. This command polls until dependencies are ready,
+  then marks the unit as started.
+
+OPTIONS:
+      --timeout duration (default: 5m)
+          Maximum time to wait for dependencies (e.g., 30s, 5m). 5m by default.
+
+———
+Run `coder --help` for a list of global options.
@@ -0,0 +1,20 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync status [flags] <unit>
+
+  Show unit status and dependency state
+
+  Show the current status of a unit, whether it is ready to start, and lists its
+  dependencies. Shows which dependencies are satisfied and which are still
+  pending. Supports multiple output formats.
+
+OPTIONS:
+  -c, --column [depends on|required status|current status|satisfied] (default: depends on,required status,current status,satisfied)
+          Columns to display in table output.
+
+  -o, --output table|json (default: table)
+          Output format.
+
+———
+Run `coder --help` for a list of global options.
@@ -0,0 +1,13 @@
+coder v0.0.0-devel
+
+USAGE:
+  coder exp sync want <unit> <depends-on>
+
+  Declare that a unit depends on another unit completing before it can start
+
+  Declare that a unit depends on another unit completing before it can start.
+  The unit specified first will not start until the second has signaled that it
+  has completed.
+
+———
+Run `coder --help` for a list of global options.
@@ -9,5 +9,9 @@ OPTIONS:
  -b, --build int
          Specify a workspace build to target by name. Defaults to latest.

+  -n, --no-build bool
+          Update the state without triggering a workspace build. Useful for
+          state-only migrations.
+
 ———
 Run `coder --help` for a list of global options.
@@ -69,7 +69,7 @@ type Options struct {
 	WorkspaceID    uuid.UUID
 	OrganizationID uuid.UUID

-	Ctx                               context.Context
+	AuthenticatedCtx                  context.Context
 	Log                               slog.Logger
 	Clock                             quartz.Clock
 	Database                          database.Store
@@ -220,7 +220,7 @@ func New(opts Options, workspace database.Workspace) *API {

 	// Start background cache refresh loop to handle workspace changes
 	// like prebuild claims where owner_id and other fields may be modified in the DB.
-	go api.startCacheRefreshLoop(opts.Ctx)
+	go api.startCacheRefreshLoop(opts.AuthenticatedCtx)

 	return api
 }
@@ -671,15 +671,15 @@ func TestBatchUpdateMetadata(t *testing.T) {

 		// Create full API with cached workspace fields (initial state)
 		api := agentapi.New(agentapi.Options{
-			Ctx:            ctxWithActor,
-			AgentID:        agentID,
-			WorkspaceID:    workspaceID,
-			OwnerID:        ownerID,
-			OrganizationID: orgID,
-			Database:       dbauthz.New(dbM, auth, testutil.Logger(t), accessControlStore),
-			Log:            testutil.Logger(t),
-			Clock:          mClock,
-			Pubsub:         pub,
+			AuthenticatedCtx: ctxWithActor,
+			AgentID:          agentID,
+			WorkspaceID:      workspaceID,
+			OwnerID:          ownerID,
+			OrganizationID:   orgID,
+			Database:         dbauthz.New(dbM, auth, testutil.Logger(t), accessControlStore),
+			Log:              testutil.Logger(t),
+			Clock:            mClock,
+			Pubsub:           pub,
 		}, initialWorkspace) // Cache is initialized with 9am schedule and "my-workspace" name

 		// Wait for ticker to be set up and release it so it can fire
@@ -92,7 +92,7 @@ func (a *SubAgentAPI) CreateSubAgent(ctx context.Context, req *agentproto.Create
 		Name:                     agentName,
 		ResourceID:               parentAgent.ResourceID,
 		AuthToken:                uuid.New(),
-		AuthInstanceID:           parentAgent.AuthInstanceID,
+		AuthInstanceID:           sql.NullString{},
 		Architecture:             req.Architecture,
 		EnvironmentVariables:     pqtype.NullRawMessage{},
 		OperatingSystem:          req.OperatingSystem,
@@ -175,6 +175,52 @@ func TestSubAgentAPI(t *testing.T) {
 		}
 	})

+	// Context: https://github.com/coder/coder/pull/22196
+	t.Run("CreateSubAgentDoesNotInheritAuthInstanceID", func(t *testing.T) {
+		t.Parallel()
+
+		var (
+			log   = testutil.Logger(t)
+			clock = quartz.NewMock(t)
+
+			db, org     = newDatabaseWithOrg(t)
+			user, agent = newUserWithWorkspaceAgent(t, db, org)
+		)
+
+		// Given: The parent agent has an AuthInstanceID set
+		ctx := testutil.Context(t, testutil.WaitShort)
+		parentAgent, err := db.GetWorkspaceAgentByID(dbauthz.AsSystemRestricted(ctx), agent.ID)
+		require.NoError(t, err)
+		require.True(t, parentAgent.AuthInstanceID.Valid, "parent agent should have an AuthInstanceID")
+		require.NotEmpty(t, parentAgent.AuthInstanceID.String)
+
+		api := newAgentAPI(t, log, db, clock, user, org, agent)
+
+		// When: We create a sub agent
+		createResp, err := api.CreateSubAgent(ctx, &proto.CreateSubAgentRequest{
+			Name:            "sub-agent",
+			Directory:       "/workspaces/test",
+			Architecture:    "amd64",
+			OperatingSystem: "linux",
+		})
+		require.NoError(t, err)
+
+		subAgentID, err := uuid.FromBytes(createResp.Agent.Id)
+		require.NoError(t, err)
+
+		// Then: The sub-agent must NOT re-use the parent's AuthInstanceID.
+		subAgent, err := db.GetWorkspaceAgentByID(dbauthz.AsSystemRestricted(ctx), subAgentID)
+		require.NoError(t, err)
+		assert.False(t, subAgent.AuthInstanceID.Valid, "sub-agent should not have an AuthInstanceID")
+		assert.Empty(t, subAgent.AuthInstanceID.String, "sub-agent AuthInstanceID string should be empty")
+
+		// Double-check: looking up by the parent's instance ID must
+		// still return the parent, not the sub-agent.
+		lookedUp, err := db.GetWorkspaceAgentByInstanceID(dbauthz.AsSystemRestricted(ctx), parentAgent.AuthInstanceID.String)
+		require.NoError(t, err)
+		assert.Equal(t, parentAgent.ID, lookedUp.ID, "instance ID lookup should still return the parent agent")
+	})
+
 	type expectedAppError struct {
 		index int32
 		field string
@@ -8387,6 +8387,84 @@ const docTemplate = `{
                }
            }
        },
+        "/users/{user}/preferences": {
+            "get": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Get user preference settings",
+                "operationId": "get-user-preference-settings",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User ID, name, or me",
+                        "name": "user",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UserPreferenceSettings"
+                        }
+                    }
+                }
+            },
+            "put": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Users"
+                ],
+                "summary": "Update user preference settings",
+                "operationId": "update-user-preference-settings",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "User ID, name, or me",
+                        "name": "user",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "New preference settings",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UpdateUserPreferenceSettingsRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UserPreferenceSettings"
+                        }
+                    }
+                }
+            }
+        },
        "/users/{user}/profile": {
            "put": {
                "security": [
@@ -10104,6 +10182,45 @@ const docTemplate = `{
                        }
                    }
                }
+            },
+            "put": {
+                "security": [
+                    {
+                        "CoderSessionToken": []
+                    }
+                ],
+                "consumes": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Builds"
+                ],
+                "summary": "Update workspace build state",
+                "operationId": "update-workspace-build-state",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "format": "uuid",
+                        "description": "Workspace build ID",
+                        "name": "workspacebuild",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Request body",
+                        "name": "request",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/codersdk.UpdateWorkspaceBuildStateRequest"
+                        }
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No Content"
+                    }
+                }
            }
        },
        "/workspacebuilds/{workspacebuild}/timings": {
@@ -14680,10 +14797,6 @@ const docTemplate = `{
                "limit": {
                    "type": "integer"
                },
-                "soft_limit": {
-                    "description": "SoftLimit is the soft limit of the feature, and is only used for showing\nincluded limits in the dashboard. No license validation or warnings are\ngenerated from this value.",
-                    "type": "integer"
-                },
                "usage_period": {
                    "description": "UsagePeriod denotes that the usage is a counter that accumulates over\nthis period (and most likely resets with the issuance of the next\nlicense).\n\nThese dates are determined from the license that this entitlement comes\nfrom, see enterprise/coderd/license/license.go.\n\nOnly certain features set these fields:\n- FeatureManagedAgentLimit",
                    "allOf": [
@@ -19254,6 +19367,14 @@ const docTemplate = `{
                }
            }
        },
+        "codersdk.UpdateUserPreferenceSettingsRequest": {
+            "type": "object",
+            "properties": {
+                "task_notification_alert_dismissed": {
+                    "type": "boolean"
+                }
+            }
+        },
        "codersdk.UpdateUserProfileRequest": {
            "type": "object",
            "required": [
@@ -19316,6 +19437,17 @@ const docTemplate = `{
                }
            }
        },
+        "codersdk.UpdateWorkspaceBuildStateRequest": {
+            "type": "object",
+            "properties": {
+                "state": {
+                    "type": "array",
+                    "items": {
+                        "type": "integer"
+                    }
+                }
+            }
+        },
        "codersdk.UpdateWorkspaceDormancy": {
            "type": "object",
            "properties": {
@@ -19639,6 +19771,14 @@ const docTemplate = `{
                }
            }
        },
+        "codersdk.UserPreferenceSettings": {
+            "type": "object",
+            "properties": {
+                "task_notification_alert_dismissed": {
+                    "type": "boolean"
+                }
+            }
+        },
        "codersdk.UserQuietHoursScheduleConfig": {
            "type": "object",
            "properties": {
@@ -7418,6 +7418,74 @@
 				}
 			}
 		},
+		"/users/{user}/preferences": {
+			"get": {
+				"security": [
+					{
+						"CoderSessionToken": []
+					}
+				],
+				"produces": ["application/json"],
+				"tags": ["Users"],
+				"summary": "Get user preference settings",
+				"operationId": "get-user-preference-settings",
+				"parameters": [
+					{
+						"type": "string",
+						"description": "User ID, name, or me",
+						"name": "user",
+						"in": "path",
+						"required": true
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"schema": {
+							"$ref": "#/definitions/codersdk.UserPreferenceSettings"
+						}
+					}
+				}
+			},
+			"put": {
+				"security": [
+					{
+						"CoderSessionToken": []
+					}
+				],
+				"consumes": ["application/json"],
+				"produces": ["application/json"],
+				"tags": ["Users"],
+				"summary": "Update user preference settings",
+				"operationId": "update-user-preference-settings",
+				"parameters": [
+					{
+						"type": "string",
+						"description": "User ID, name, or me",
+						"name": "user",
+						"in": "path",
+						"required": true
+					},
+					{
+						"description": "New preference settings",
+						"name": "request",
+						"in": "body",
+						"required": true,
+						"schema": {
+							"$ref": "#/definitions/codersdk.UpdateUserPreferenceSettingsRequest"
+						}
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"schema": {
+							"$ref": "#/definitions/codersdk.UserPreferenceSettings"
+						}
+					}
+				}
+			}
+		},
 		"/users/{user}/profile": {
 			"put": {
 				"security": [
@@ -8946,6 +9014,41 @@
 						}
 					}
 				}
+			},
+			"put": {
+				"security": [
+					{
+						"CoderSessionToken": []
+					}
+				],
+				"consumes": ["application/json"],
+				"tags": ["Builds"],
+				"summary": "Update workspace build state",
+				"operationId": "update-workspace-build-state",
+				"parameters": [
+					{
+						"type": "string",
+						"format": "uuid",
+						"description": "Workspace build ID",
+						"name": "workspacebuild",
+						"in": "path",
+						"required": true
+					},
+					{
+						"description": "Request body",
+						"name": "request",
+						"in": "body",
+						"required": true,
+						"schema": {
+							"$ref": "#/definitions/codersdk.UpdateWorkspaceBuildStateRequest"
+						}
+					}
+				],
+				"responses": {
+					"204": {
+						"description": "No Content"
+					}
+				}
 			}
 		},
 		"/workspacebuilds/{workspacebuild}/timings": {
@@ -13267,10 +13370,6 @@
 				"limit": {
 					"type": "integer"
 				},
-				"soft_limit": {
-					"description": "SoftLimit is the soft limit of the feature, and is only used for showing\nincluded limits in the dashboard. No license validation or warnings are\ngenerated from this value.",
-					"type": "integer"
-				},
 				"usage_period": {
 					"description": "UsagePeriod denotes that the usage is a counter that accumulates over\nthis period (and most likely resets with the issuance of the next\nlicense).\n\nThese dates are determined from the license that this entitlement comes\nfrom, see enterprise/coderd/license/license.go.\n\nOnly certain features set these fields:\n- FeatureManagedAgentLimit",
 					"allOf": [
@@ -17660,6 +17759,14 @@
 				}
 			}
 		},
+		"codersdk.UpdateUserPreferenceSettingsRequest": {
+			"type": "object",
+			"properties": {
+				"task_notification_alert_dismissed": {
+					"type": "boolean"
+				}
+			}
+		},
 		"codersdk.UpdateUserProfileRequest": {
 			"type": "object",
 			"required": ["username"],
@@ -17718,6 +17825,17 @@
 				}
 			}
 		},
+		"codersdk.UpdateWorkspaceBuildStateRequest": {
+			"type": "object",
+			"properties": {
+				"state": {
+					"type": "array",
+					"items": {
+						"type": "integer"
+					}
+				}
+			}
+		},
 		"codersdk.UpdateWorkspaceDormancy": {
 			"type": "object",
 			"properties": {
@@ -18020,6 +18138,14 @@
 				}
 			}
 		},
+		"codersdk.UserPreferenceSettings": {
+			"type": "object",
+			"properties": {
+				"task_notification_alert_dismissed": {
+					"type": "boolean"
+				}
+			}
+		},
 		"codersdk.UserQuietHoursScheduleConfig": {
 			"type": "object",
 			"properties": {
@@ -1336,6 +1336,8 @@ func New(options *Options) *API {
 						})
 						r.Get("/appearance", api.userAppearanceSettings)
 						r.Put("/appearance", api.putUserAppearanceSettings)
+						r.Get("/preferences", api.userPreferenceSettings)
+						r.Put("/preferences", api.putUserPreferenceSettings)
 						r.Route("/password", func(r chi.Router) {
 							r.Use(httpmw.RateLimit(options.LoginRateLimit, time.Minute))
 							r.Put("/", api.putUserPassword)
@@ -1499,6 +1501,7 @@ func New(options *Options) *API {
 			r.Get("/parameters", api.workspaceBuildParameters)
 			r.Get("/resources", api.workspaceBuildResourcesDeprecated)
 			r.Get("/state", api.workspaceBuildState)
+			r.Put("/state", api.workspaceBuildUpdateState)
 			r.Get("/timings", api.workspaceBuildTimings)
 		})
 		r.Route("/authcheck", func(r chi.Router) {
@@ -83,6 +83,7 @@ import (
 	"github.com/coder/coder/v2/coderd/schedule"
 	"github.com/coder/coder/v2/coderd/telemetry"
 	"github.com/coder/coder/v2/coderd/updatecheck"
+	"github.com/coder/coder/v2/coderd/usage"
 	"github.com/coder/coder/v2/coderd/util/ptr"
 	"github.com/coder/coder/v2/coderd/webpush"
 	"github.com/coder/coder/v2/coderd/workspaceapps"
@@ -186,6 +187,7 @@ type Options struct {
 	TelemetryReporter                  telemetry.Reporter

 	ProvisionerdServerMetrics *provisionerdserver.Metrics
+	UsageInserter             usage.Inserter
 }

 // New constructs a codersdk client connected to an in-memory API instance.
@@ -266,6 +268,11 @@ func NewOptions(t testing.TB, options *Options) (func(http.Handler), context.Can
 		}
 	}

+	var usageInserter *atomic.Pointer[usage.Inserter]
+	if options.UsageInserter != nil {
+		usageInserter = &atomic.Pointer[usage.Inserter]{}
+		usageInserter.Store(&options.UsageInserter)
+	}
 	if options.Database == nil {
 		options.Database, options.Pubsub = dbtestutil.NewDB(t)
 	}
@@ -559,6 +566,7 @@ func NewOptions(t testing.TB, options *Options) (func(http.Handler), context.Can
 			Database:                       options.Database,
 			Pubsub:                         options.Pubsub,
 			ExternalAuthConfigs:            options.ExternalAuthConfigs,
+			UsageInserter:                  usageInserter,

 			Auditor:                            options.Auditor,
 			ConnectionLogger:                   options.ConnectionLogger,
@@ -0,0 +1,44 @@
+package coderdtest
+
+import (
+	"context"
+	"sync"
+
+	"github.com/coder/coder/v2/coderd/database"
+	"github.com/coder/coder/v2/coderd/usage"
+	"github.com/coder/coder/v2/coderd/usage/usagetypes"
+)
+
+var _ usage.Inserter = (*UsageInserter)(nil)
+
+type UsageInserter struct {
+	sync.Mutex
+	events []usagetypes.DiscreteEvent
+}
+
+func NewUsageInserter() *UsageInserter {
+	return &UsageInserter{
+		events: []usagetypes.DiscreteEvent{},
+	}
+}
+
+func (u *UsageInserter) InsertDiscreteUsageEvent(_ context.Context, _ database.Store, event usagetypes.DiscreteEvent) error {
+	u.Lock()
+	defer u.Unlock()
+	u.events = append(u.events, event)
+	return nil
+}
+
+func (u *UsageInserter) GetEvents() []usagetypes.DiscreteEvent {
+	u.Lock()
+	defer u.Unlock()
+	eventsCopy := make([]usagetypes.DiscreteEvent, len(u.events))
+	copy(eventsCopy, u.events)
+	return eventsCopy
+}
+
+func (u *UsageInserter) Reset() {
+	u.Lock()
+	defer u.Unlock()
+	u.events = []usagetypes.DiscreteEvent{}
+}
@@ -3431,6 +3431,17 @@ func (q *querier) GetUserStatusCounts(ctx context.Context, arg database.GetUserS
 	return q.db.GetUserStatusCounts(ctx, arg)
 }

+func (q *querier) GetUserTaskNotificationAlertDismissed(ctx context.Context, userID uuid.UUID) (bool, error) {
+	user, err := q.db.GetUserByID(ctx, userID)
+	if err != nil {
+		return false, err
+	}
+	if err := q.authorizeContext(ctx, policy.ActionReadPersonal, user); err != nil {
+		return false, err
+	}
+	return q.db.GetUserTaskNotificationAlertDismissed(ctx, userID)
+}
+
 func (q *querier) GetUserTerminalFont(ctx context.Context, userID uuid.UUID) (string, error) {
 	u, err := q.db.GetUserByID(ctx, userID)
 	if err != nil {
@@ -5464,6 +5475,17 @@ func (q *querier) UpdateUserStatus(ctx context.Context, arg database.UpdateUserS
 	return updateWithReturn(q.log, q.auth, fetch, q.db.UpdateUserStatus)(ctx, arg)
 }

+func (q *querier) UpdateUserTaskNotificationAlertDismissed(ctx context.Context, arg database.UpdateUserTaskNotificationAlertDismissedParams) (bool, error) {
+	user, err := q.db.GetUserByID(ctx, arg.UserID)
+	if err != nil {
+		return false, err
+	}
+	if err := q.authorizeContext(ctx, policy.ActionUpdatePersonal, user); err != nil {
+		return false, err
+	}
+	return q.db.UpdateUserTaskNotificationAlertDismissed(ctx, arg)
+}
+
 func (q *querier) UpdateUserTerminalFont(ctx context.Context, arg database.UpdateUserTerminalFontParams) (database.UserConfig, error) {
 	u, err := q.db.GetUserByID(ctx, arg.UserID)
 	if err != nil {
@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net"
 	"reflect"
+	"strconv"
 	"testing"
 	"time"

@@ -1477,6 +1478,21 @@ func (s *MethodTestSuite) TestUser() {
 		dbm.EXPECT().UpdateUserTerminalFont(gomock.Any(), arg).Return(uc, nil).AnyTimes()
 		check.Args(arg).Asserts(u, policy.ActionUpdatePersonal).Returns(uc)
 	}))
+	s.Run("GetUserTaskNotificationAlertDismissed", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
+		u := testutil.Fake(s.T(), faker, database.User{})
+		dbm.EXPECT().GetUserByID(gomock.Any(), u.ID).Return(u, nil).AnyTimes()
+		dbm.EXPECT().GetUserTaskNotificationAlertDismissed(gomock.Any(), u.ID).Return(false, nil).AnyTimes()
+		check.Args(u.ID).Asserts(u, policy.ActionReadPersonal).Returns(false)
+	}))
+	s.Run("UpdateUserTaskNotificationAlertDismissed", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
+		user := testutil.Fake(s.T(), faker, database.User{})
+		userConfig := database.UserConfig{UserID: user.ID, Key: "task_notification_alert_dismissed", Value: "false"}
+		userConfigValue, _ := strconv.ParseBool(userConfig.Value)
+		arg := database.UpdateUserTaskNotificationAlertDismissedParams{UserID: user.ID, TaskNotificationAlertDismissed: userConfigValue}
+		dbm.EXPECT().GetUserByID(gomock.Any(), user.ID).Return(user, nil).AnyTimes()
+		dbm.EXPECT().UpdateUserTaskNotificationAlertDismissed(gomock.Any(), arg).Return(false, nil).AnyTimes()
+		check.Args(arg).Asserts(user, policy.ActionUpdatePersonal).Returns(userConfigValue)
+	}))
 	s.Run("UpdateUserStatus", s.Mocked(func(dbm *dbmock.MockStore, faker *gofakeit.Faker, check *expects) {
 		u := testutil.Fake(s.T(), faker, database.User{})
 		arg := database.UpdateUserStatusParams{ID: u.ID, Status: u.Status, UpdatedAt: u.UpdatedAt}
@@ -1845,6 +1845,13 @@ func (m queryMetricsStore) GetUserStatusCounts(ctx context.Context, arg database
 	return r0, r1
 }

+func (m queryMetricsStore) GetUserTaskNotificationAlertDismissed(ctx context.Context, userID uuid.UUID) (bool, error) {
+	start := time.Now()
+	r0, r1 := m.s.GetUserTaskNotificationAlertDismissed(ctx, userID)
+	m.queryLatencies.WithLabelValues("GetUserTaskNotificationAlertDismissed").Observe(time.Since(start).Seconds())
+	return r0, r1
+}
+
 func (m queryMetricsStore) GetUserTerminalFont(ctx context.Context, userID uuid.UUID) (string, error) {
 	start := time.Now()
 	r0, r1 := m.s.GetUserTerminalFont(ctx, userID)
@@ -3350,6 +3357,13 @@ func (m queryMetricsStore) UpdateUserStatus(ctx context.Context, arg database.Up
 	return user, err
 }

+func (m queryMetricsStore) UpdateUserTaskNotificationAlertDismissed(ctx context.Context, arg database.UpdateUserTaskNotificationAlertDismissedParams) (bool, error) {
+	start := time.Now()
+	r0, r1 := m.s.UpdateUserTaskNotificationAlertDismissed(ctx, arg)
+	m.queryLatencies.WithLabelValues("UpdateUserTaskNotificationAlertDismissed").Observe(time.Since(start).Seconds())
+	return r0, r1
+}
+
 func (m queryMetricsStore) UpdateUserTerminalFont(ctx context.Context, arg database.UpdateUserTerminalFontParams) (database.UserConfig, error) {
 	start := time.Now()
 	r0, r1 := m.s.UpdateUserTerminalFont(ctx, arg)
@@ -3942,6 +3942,21 @@ func (mr *MockStoreMockRecorder) GetUserStatusCounts(ctx, arg any) *gomock.Call
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetUserStatusCounts", reflect.TypeOf((*MockStore)(nil).GetUserStatusCounts), ctx, arg)
 }

+// GetUserTaskNotificationAlertDismissed mocks base method.
+func (m *MockStore) GetUserTaskNotificationAlertDismissed(ctx context.Context, userID uuid.UUID) (bool, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "GetUserTaskNotificationAlertDismissed", ctx, userID)
+	ret0, _ := ret[0].(bool)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// GetUserTaskNotificationAlertDismissed indicates an expected call of GetUserTaskNotificationAlertDismissed.
+func (mr *MockStoreMockRecorder) GetUserTaskNotificationAlertDismissed(ctx, userID any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetUserTaskNotificationAlertDismissed", reflect.TypeOf((*MockStore)(nil).GetUserTaskNotificationAlertDismissed), ctx, userID)
+}
+
 // GetUserTerminalFont mocks base method.
 func (m *MockStore) GetUserTerminalFont(ctx context.Context, userID uuid.UUID) (string, error) {
 	m.ctrl.T.Helper()
@@ -7174,6 +7189,21 @@ func (mr *MockStoreMockRecorder) UpdateUserStatus(ctx, arg any) *gomock.Call {
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateUserStatus", reflect.TypeOf((*MockStore)(nil).UpdateUserStatus), ctx, arg)
 }

+// UpdateUserTaskNotificationAlertDismissed mocks base method.
+func (m *MockStore) UpdateUserTaskNotificationAlertDismissed(ctx context.Context, arg database.UpdateUserTaskNotificationAlertDismissedParams) (bool, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "UpdateUserTaskNotificationAlertDismissed", ctx, arg)
+	ret0, _ := ret[0].(bool)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// UpdateUserTaskNotificationAlertDismissed indicates an expected call of UpdateUserTaskNotificationAlertDismissed.
+func (mr *MockStoreMockRecorder) UpdateUserTaskNotificationAlertDismissed(ctx, arg any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateUserTaskNotificationAlertDismissed", reflect.TypeOf((*MockStore)(nil).UpdateUserTaskNotificationAlertDismissed), ctx, arg)
+}
+
 // UpdateUserTerminalFont mocks base method.
 func (m *MockStore) UpdateUserTerminalFont(ctx context.Context, arg database.UpdateUserTerminalFontParams) (database.UserConfig, error) {
 	m.ctrl.T.Helper()
@@ -1 +1 @@
-DROP INDEX IF EXISTS public.workspace_agents_auth_instance_id_deleted_idx;
+DROP INDEX IF EXISTS workspace_agents_auth_instance_id_deleted_idx;
@@ -1 +1 @@
-CREATE INDEX IF NOT EXISTS workspace_agents_auth_instance_id_deleted_idx ON public.workspace_agents (auth_instance_id, deleted);
+CREATE INDEX IF NOT EXISTS workspace_agents_auth_instance_id_deleted_idx ON workspace_agents (auth_instance_id, deleted);
@@ -1,34 +1,34 @@
 -- This is a deleted user that shares the same username and linked_id as the existing user below.
 -- Any future migrations need to handle this case.
-INSERT INTO public.users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
+INSERT INTO users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
 	VALUES ('a0061a8e-7db7-4585-838c-3116a003dd21', 'githubuser@coder.com', 'githubuser', '\x', '2022-11-02 13:05:21.445455+02', '2022-11-02 13:05:21.445455+02', 'active', '{}', true) ON CONFLICT DO NOTHING;
-INSERT INTO public.organization_members VALUES ('a0061a8e-7db7-4585-838c-3116a003dd21', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
-INSERT INTO public.user_links(user_id, login_type, linked_id, oauth_access_token)
+INSERT INTO organization_members VALUES ('a0061a8e-7db7-4585-838c-3116a003dd21', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
+INSERT INTO user_links(user_id, login_type, linked_id, oauth_access_token)
 	VALUES('a0061a8e-7db7-4585-838c-3116a003dd21', 'github', '100', '');


-INSERT INTO public.users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
+INSERT INTO users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
 	VALUES ('fc1511ef-4fcf-4a3b-98a1-8df64160e35a', 'githubuser@coder.com', 'githubuser', '\x', '2022-11-02 13:05:21.445455+02', '2022-11-02 13:05:21.445455+02', 'active', '{}', false) ON CONFLICT DO NOTHING;
-INSERT INTO public.organization_members VALUES ('fc1511ef-4fcf-4a3b-98a1-8df64160e35a', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
-INSERT INTO public.user_links(user_id, login_type, linked_id, oauth_access_token)
+INSERT INTO organization_members VALUES ('fc1511ef-4fcf-4a3b-98a1-8df64160e35a', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
+INSERT INTO user_links(user_id, login_type, linked_id, oauth_access_token)
 	VALUES('fc1511ef-4fcf-4a3b-98a1-8df64160e35a', 'github', '100', '');

 -- Additionally, there is no unique constraint on user_id. So also add another user_link for the same user.
 -- This has happened on a production database.
-INSERT INTO public.user_links(user_id, login_type, linked_id, oauth_access_token)
+INSERT INTO user_links(user_id, login_type, linked_id, oauth_access_token)
 VALUES('fc1511ef-4fcf-4a3b-98a1-8df64160e35a', 'oidc', 'foo', '');


 -- Lastly, make 2 other users who have the same user link.
-INSERT INTO public.users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
+INSERT INTO users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
 VALUES ('580ed397-727d-4aaf-950a-51f89f556c24', 'dup_link_a@coder.com', 'dupe_a', '\x', '2022-11-02 13:05:21.445455+02', '2022-11-02 13:05:21.445455+02', 'active', '{}', false) ON CONFLICT DO NOTHING;
-INSERT INTO public.organization_members VALUES ('580ed397-727d-4aaf-950a-51f89f556c24', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
-INSERT INTO public.user_links(user_id, login_type, linked_id, oauth_access_token)
+INSERT INTO organization_members VALUES ('580ed397-727d-4aaf-950a-51f89f556c24', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
+INSERT INTO user_links(user_id, login_type, linked_id, oauth_access_token)
 VALUES('580ed397-727d-4aaf-950a-51f89f556c24', 'github', '500', '');


-INSERT INTO public.users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
+INSERT INTO users(id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, deleted)
 VALUES ('c813366b-2fde-45ae-920c-101c3ad6a1e1', 'dup_link_b@coder.com', 'dupe_b', '\x', '2022-11-02 13:05:21.445455+02', '2022-11-02 13:05:21.445455+02', 'active', '{}', false) ON CONFLICT DO NOTHING;
-INSERT INTO public.organization_members VALUES ('c813366b-2fde-45ae-920c-101c3ad6a1e1', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
-INSERT INTO public.user_links(user_id, login_type, linked_id, oauth_access_token)
+INSERT INTO organization_members VALUES ('c813366b-2fde-45ae-920c-101c3ad6a1e1', 'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', '2022-11-02 13:05:21.447595+02', '2022-11-02 13:05:21.447595+02', '{}') ON CONFLICT DO NOTHING;
+INSERT INTO user_links(user_id, login_type, linked_id, oauth_access_token)
 VALUES('c813366b-2fde-45ae-920c-101c3ad6a1e1', 'github', '500', '');
@@ -1,4 +1,4 @@
-INSERT INTO public.workspace_app_stats (
+INSERT INTO workspace_app_stats (
 	id,
 	user_id,
 	workspace_id,
@@ -1,5 +1,5 @@
 INSERT INTO
-    public.workspace_modules (
+    workspace_modules (
        id,
        job_id,
        transition,
@@ -1,15 +1,15 @@
-INSERT INTO public.organizations (id, name, description, created_at, updated_at, is_default, display_name, icon) VALUES ('20362772-802a-4a72-8e4f-3648b4bfd168', 'strange_hopper58', 'wizardly_stonebraker60', '2025-02-07 07:46:19.507551 +00:00', '2025-02-07 07:46:19.507552 +00:00', false, 'competent_rhodes59', '');
+INSERT INTO organizations (id, name, description, created_at, updated_at, is_default, display_name, icon) VALUES ('20362772-802a-4a72-8e4f-3648b4bfd168', 'strange_hopper58', 'wizardly_stonebraker60', '2025-02-07 07:46:19.507551 +00:00', '2025-02-07 07:46:19.507552 +00:00', false, 'competent_rhodes59', '');

-INSERT INTO public.users (id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, login_type, avatar_url, deleted, last_seen_at, quiet_hours_schedule, theme_preference, name, github_com_user_id, hashed_one_time_passcode, one_time_passcode_expires_at) VALUES ('6c353aac-20de-467b-bdfb-3c30a37adcd2', 'vigorous_murdock61', 'affectionate_hawking62', 'lqTu9C5363AwD7NVNH6noaGjp91XIuZJ', '2025-02-07 07:46:19.510861 +00:00', '2025-02-07 07:46:19.512949 +00:00', 'active', '{}', 'password', '', false, '0001-01-01 00:00:00.000000', '', '', 'vigilant_hugle63', null, null, null);
+INSERT INTO users (id, email, username, hashed_password, created_at, updated_at, status, rbac_roles, login_type, avatar_url, deleted, last_seen_at, quiet_hours_schedule, theme_preference, name, github_com_user_id, hashed_one_time_passcode, one_time_passcode_expires_at) VALUES ('6c353aac-20de-467b-bdfb-3c30a37adcd2', 'vigorous_murdock61', 'affectionate_hawking62', 'lqTu9C5363AwD7NVNH6noaGjp91XIuZJ', '2025-02-07 07:46:19.510861 +00:00', '2025-02-07 07:46:19.512949 +00:00', 'active', '{}', 'password', '', false, '0001-01-01 00:00:00.000000', '', '', 'vigilant_hugle63', null, null, null);

-INSERT INTO public.templates (id, created_at, updated_at, organization_id, deleted, name, provisioner, active_version_id, description, default_ttl, created_by, icon, user_acl, group_acl, display_name, allow_user_cancel_workspace_jobs, allow_user_autostart, allow_user_autostop, failure_ttl, time_til_dormant, time_til_dormant_autodelete, autostop_requirement_days_of_week, autostop_requirement_weeks, autostart_block_days_of_week, require_active_version, deprecated, activity_bump, max_port_sharing_level) VALUES ('6b298946-7a4f-47ac-9158-b03b08740a41', '2025-02-07 07:46:19.513317 +00:00', '2025-02-07 07:46:19.513317 +00:00', '20362772-802a-4a72-8e4f-3648b4bfd168', false, 'modest_leakey64', 'echo', 'e6cfa2a4-e4cf-4182-9e19-08b975682a28', 'upbeat_wright65', 604800000000000, '6c353aac-20de-467b-bdfb-3c30a37adcd2', 'nervous_keller66', '{}', '{"20362772-802a-4a72-8e4f-3648b4bfd168": ["read", "use"]}', 'determined_aryabhata67', false, true, true, 0, 0, 0, 0, 0, 0, false, '', 3600000000000, 'owner');
-INSERT INTO public.template_versions (id, template_id, organization_id, created_at, updated_at, name, readme, job_id, created_by, external_auth_providers, message, archived, source_example_id) VALUES ('af58bd62-428c-4c33-849b-d43a3be07d93', '6b298946-7a4f-47ac-9158-b03b08740a41', '20362772-802a-4a72-8e4f-3648b4bfd168', '2025-02-07 07:46:19.514782 +00:00', '2025-02-07 07:46:19.514782 +00:00', 'distracted_shockley68', 'sleepy_turing69', 'f2e2ea1c-5aa3-4a1d-8778-2e5071efae59', '6c353aac-20de-467b-bdfb-3c30a37adcd2', '[]', '', false, null);
+INSERT INTO templates (id, created_at, updated_at, organization_id, deleted, name, provisioner, active_version_id, description, default_ttl, created_by, icon, user_acl, group_acl, display_name, allow_user_cancel_workspace_jobs, allow_user_autostart, allow_user_autostop, failure_ttl, time_til_dormant, time_til_dormant_autodelete, autostop_requirement_days_of_week, autostop_requirement_weeks, autostart_block_days_of_week, require_active_version, deprecated, activity_bump, max_port_sharing_level) VALUES ('6b298946-7a4f-47ac-9158-b03b08740a41', '2025-02-07 07:46:19.513317 +00:00', '2025-02-07 07:46:19.513317 +00:00', '20362772-802a-4a72-8e4f-3648b4bfd168', false, 'modest_leakey64', 'echo', 'e6cfa2a4-e4cf-4182-9e19-08b975682a28', 'upbeat_wright65', 604800000000000, '6c353aac-20de-467b-bdfb-3c30a37adcd2', 'nervous_keller66', '{}', '{"20362772-802a-4a72-8e4f-3648b4bfd168": ["read", "use"]}', 'determined_aryabhata67', false, true, true, 0, 0, 0, 0, 0, 0, false, '', 3600000000000, 'owner');
+INSERT INTO template_versions (id, template_id, organization_id, created_at, updated_at, name, readme, job_id, created_by, external_auth_providers, message, archived, source_example_id) VALUES ('af58bd62-428c-4c33-849b-d43a3be07d93', '6b298946-7a4f-47ac-9158-b03b08740a41', '20362772-802a-4a72-8e4f-3648b4bfd168', '2025-02-07 07:46:19.514782 +00:00', '2025-02-07 07:46:19.514782 +00:00', 'distracted_shockley68', 'sleepy_turing69', 'f2e2ea1c-5aa3-4a1d-8778-2e5071efae59', '6c353aac-20de-467b-bdfb-3c30a37adcd2', '[]', '', false, null);

-INSERT INTO public.template_version_presets (id, template_version_id, name, created_at) VALUES ('28b42cc0-c4fe-4907-a0fe-e4d20f1e9bfe', 'af58bd62-428c-4c33-849b-d43a3be07d93', 'test', '0001-01-01 00:00:00.000000 +00:00');
+INSERT INTO template_version_presets (id, template_version_id, name, created_at) VALUES ('28b42cc0-c4fe-4907-a0fe-e4d20f1e9bfe', 'af58bd62-428c-4c33-849b-d43a3be07d93', 'test', '0001-01-01 00:00:00.000000 +00:00');

 -- Add presets with the same template version ID and name
 -- to ensure they're correctly handled by the 00031*_preset_prebuilds migration.
-INSERT INTO public.template_version_presets (
+INSERT INTO template_version_presets (
 	id, template_version_id, name, created_at
 )
 VALUES (
@@ -19,7 +19,7 @@ VALUES (
 	'0001-01-01 00:00:00.000000 +00:00'
 );

-INSERT INTO public.template_version_presets (
+INSERT INTO template_version_presets (
 	id, template_version_id, name, created_at
 )
 VALUES (
@@ -29,4 +29,4 @@ VALUES (
 	'0001-01-01 00:00:00.000000 +00:00'
 );

-INSERT INTO public.template_version_preset_parameters (id, template_version_preset_id, name, value) VALUES ('ea90ccd2-5024-459e-87e4-879afd24de0f', '28b42cc0-c4fe-4907-a0fe-e4d20f1e9bfe', 'test', 'test');
+INSERT INTO template_version_preset_parameters (id, template_version_preset_id, name, value) VALUES ('ea90ccd2-5024-459e-87e4-879afd24de0f', '28b42cc0-c4fe-4907-a0fe-e4d20f1e9bfe', 'test', 'test');
@@ -1,4 +1,4 @@
-INSERT INTO public.tasks VALUES (
+INSERT INTO tasks VALUES (
    'f5a1c3e4-8b2d-4f6a-9d7e-2a8b5c9e1f3d', -- id
    'bb640d07-ca8a-4869-b6bc-ae61ebb2fda1', -- organization_id
    '30095c71-380b-457a-8995-97b8ee6e5307', -- owner_id
@@ -11,7 +11,7 @@ INSERT INTO public.tasks VALUES (
    NULL                                    -- deleted_at
 ) ON CONFLICT DO NOTHING;

-INSERT INTO public.task_workspace_apps VALUES (
+INSERT INTO task_workspace_apps VALUES (
    'f5a1c3e4-8b2d-4f6a-9d7e-2a8b5c9e1f3d', -- task_id
    'a8c0b8c5-c9a8-4f33-93a4-8142e6858244', -- workspace_build_id
    '8fa17bbd-c48c-44c7-91ae-d4acbc755fad', -- workspace_agent_id
@@ -1,4 +1,4 @@
-INSERT INTO public.task_workspace_apps VALUES (
+INSERT INTO task_workspace_apps VALUES (
    'f5a1c3e4-8b2d-4f6a-9d7e-2a8b5c9e1f3d', -- task_id
    NULL,                                   -- workspace_agent_id
    NULL,                                   -- workspace_app_id
@@ -447,6 +447,7 @@ type sqlcQuerier interface {
 	// We do not start counting from 0 at the start_time. We check the last status change before the start_time for each user. As such,
 	// the result shows the total number of users in each status on any particular day.
 	GetUserStatusCounts(ctx context.Context, arg GetUserStatusCountsParams) ([]GetUserStatusCountsRow, error)
+	GetUserTaskNotificationAlertDismissed(ctx context.Context, userID uuid.UUID) (bool, error)
 	GetUserTerminalFont(ctx context.Context, userID uuid.UUID) (string, error)
 	GetUserThemePreference(ctx context.Context, userID uuid.UUID) (string, error)
 	GetUserWorkspaceBuildParameters(ctx context.Context, arg GetUserWorkspaceBuildParametersParams) ([]GetUserWorkspaceBuildParametersRow, error)
@@ -714,6 +715,7 @@ type sqlcQuerier interface {
 	UpdateUserRoles(ctx context.Context, arg UpdateUserRolesParams) (User, error)
 	UpdateUserSecret(ctx context.Context, arg UpdateUserSecretParams) (UserSecret, error)
 	UpdateUserStatus(ctx context.Context, arg UpdateUserStatusParams) (User, error)
+	UpdateUserTaskNotificationAlertDismissed(ctx context.Context, arg UpdateUserTaskNotificationAlertDismissedParams) (bool, error)
 	UpdateUserTerminalFont(ctx context.Context, arg UpdateUserTerminalFontParams) (UserConfig, error)
 	UpdateUserThemePreference(ctx context.Context, arg UpdateUserThemePreferenceParams) (UserConfig, error)
 	UpdateVolumeResourceMonitor(ctx context.Context, arg UpdateVolumeResourceMonitorParams) error
@@ -6107,6 +6107,56 @@ func TestGetWorkspaceAgentsByParentID(t *testing.T) {
 	})
 }

+func TestGetWorkspaceAgentByInstanceID(t *testing.T) {
+	t.Parallel()
+
+	// Context: https://github.com/coder/coder/pull/22196
+	t.Run("DoesNotReturnSubAgents", func(t *testing.T) {
+		t.Parallel()
+
+		// Given: A parent workspace agent with an AuthInstanceID and a
+		// sub-agent that shares the same AuthInstanceID.
+		db, _ := dbtestutil.NewDB(t)
+		org := dbgen.Organization(t, db, database.Organization{})
+		job := dbgen.ProvisionerJob(t, db, nil, database.ProvisionerJob{
+			Type:           database.ProvisionerJobTypeTemplateVersionImport,
+			OrganizationID: org.ID,
+		})
+		resource := dbgen.WorkspaceResource(t, db, database.WorkspaceResource{
+			JobID: job.ID,
+		})
+
+		authInstanceID := fmt.Sprintf("instance-%s-%d", t.Name(), time.Now().UnixNano())
+		parentAgent := dbgen.WorkspaceAgent(t, db, database.WorkspaceAgent{
+			ResourceID: resource.ID,
+			AuthInstanceID: sql.NullString{
+				String: authInstanceID,
+				Valid:  true,
+			},
+		})
+		// Create a sub-agent with the same AuthInstanceID (simulating
+		// the old behavior before the fix).
+		_ = dbgen.WorkspaceAgent(t, db, database.WorkspaceAgent{
+			ParentID:   uuid.NullUUID{UUID: parentAgent.ID, Valid: true},
+			ResourceID: resource.ID,
+			AuthInstanceID: sql.NullString{
+				String: authInstanceID,
+				Valid:  true,
+			},
+		})
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+
+		// When: We look up the agent by instance ID.
+		agent, err := db.GetWorkspaceAgentByInstanceID(ctx, authInstanceID)
+		require.NoError(t, err)
+
+		// Then: The result must be the parent agent, not the sub-agent.
+		assert.Equal(t, parentAgent.ID, agent.ID, "instance ID lookup should return the parent agent, not a sub-agent")
+		assert.False(t, agent.ParentID.Valid, "returned agent should not have a parent (should be the parent itself)")
+	})
+}
+
 func requireUsersMatch(t testing.TB, expected []database.User, found []database.GetUsersRow, msg string) {
 	t.Helper()
 	require.ElementsMatch(t, expected, database.ConvertUserRows(found), msg)
@@ -16324,6 +16324,23 @@ func (q *sqlQuerier) GetUserCount(ctx context.Context, includeSystem bool) (int6
 	return count, err
 }

+const getUserTaskNotificationAlertDismissed = `-- name: GetUserTaskNotificationAlertDismissed :one
+SELECT
+	value::boolean as task_notification_alert_dismissed
+FROM
+	user_configs
+WHERE
+	user_id = $1
+	AND key = 'preference_task_notification_alert_dismissed'
+`
+
+func (q *sqlQuerier) GetUserTaskNotificationAlertDismissed(ctx context.Context, userID uuid.UUID) (bool, error) {
+	row := q.db.QueryRowContext(ctx, getUserTaskNotificationAlertDismissed, userID)
+	var task_notification_alert_dismissed bool
+	err := row.Scan(&task_notification_alert_dismissed)
+	return task_notification_alert_dismissed, err
+}
+
 const getUserTerminalFont = `-- name: GetUserTerminalFont :one
 SELECT
 	value as terminal_font
@@ -17076,6 +17093,33 @@ func (q *sqlQuerier) UpdateUserStatus(ctx context.Context, arg UpdateUserStatusP
 	return i, err
 }

+const updateUserTaskNotificationAlertDismissed = `-- name: UpdateUserTaskNotificationAlertDismissed :one
+INSERT INTO
+	user_configs (user_id, key, value)
+VALUES
+	($1, 'preference_task_notification_alert_dismissed', ($2::boolean)::text)
+ON CONFLICT
+	ON CONSTRAINT user_configs_pkey
+DO UPDATE
+SET
+	value = $2
+WHERE user_configs.user_id = $1
+	AND user_configs.key = 'preference_task_notification_alert_dismissed'
+RETURNING value::boolean AS task_notification_alert_dismissed
+`
+
+type UpdateUserTaskNotificationAlertDismissedParams struct {
+	UserID                         uuid.UUID `db:"user_id" json:"user_id"`
+	TaskNotificationAlertDismissed bool      `db:"task_notification_alert_dismissed" json:"task_notification_alert_dismissed"`
+}
+
+func (q *sqlQuerier) UpdateUserTaskNotificationAlertDismissed(ctx context.Context, arg UpdateUserTaskNotificationAlertDismissedParams) (bool, error) {
+	row := q.db.QueryRowContext(ctx, updateUserTaskNotificationAlertDismissed, arg.UserID, arg.TaskNotificationAlertDismissed)
+	var task_notification_alert_dismissed bool
+	err := row.Scan(&task_notification_alert_dismissed)
+	return task_notification_alert_dismissed, err
+}
+
 const updateUserTerminalFont = `-- name: UpdateUserTerminalFont :one
 INSERT INTO
 	user_configs (user_id, key, value)
@@ -18008,6 +18052,8 @@ WHERE
 	auth_instance_id = $1 :: TEXT
 	-- Filter out deleted sub agents.
 	AND deleted = FALSE
+	-- Filter out sub agents, they do not authenticate with auth_instance_id.
+	AND parent_id IS NULL
 ORDER BY
 	created_at DESC
 `
@@ -168,6 +168,29 @@ WHERE user_configs.user_id = @user_id
 	AND user_configs.key = 'terminal_font'
 RETURNING *;

+-- name: GetUserTaskNotificationAlertDismissed :one
+SELECT
+	value::boolean as task_notification_alert_dismissed
+FROM
+	user_configs
+WHERE
+	user_id = @user_id
+	AND key = 'preference_task_notification_alert_dismissed';
+
+-- name: UpdateUserTaskNotificationAlertDismissed :one
+INSERT INTO
+	user_configs (user_id, key, value)
+VALUES
+	(@user_id, 'preference_task_notification_alert_dismissed', (@task_notification_alert_dismissed::boolean)::text)
+ON CONFLICT
+	ON CONSTRAINT user_configs_pkey
+DO UPDATE
+SET
+	value = @task_notification_alert_dismissed
+WHERE user_configs.user_id = @user_id
+	AND user_configs.key = 'preference_task_notification_alert_dismissed'
+RETURNING value::boolean AS task_notification_alert_dismissed;
+
 -- name: UpdateUserRoles :one
 UPDATE
 	users
@@ -17,6 +17,8 @@ WHERE
 	auth_instance_id = @auth_instance_id :: TEXT
 	-- Filter out deleted sub agents.
 	AND deleted = FALSE
+	-- Filter out sub agents, they do not authenticate with auth_instance_id.
+	AND parent_id IS NULL
 ORDER BY
 	created_at DESC;

@@ -21,7 +21,6 @@ import (
 	"github.com/coder/coder/v2/coderd/pubsub"
 	markdown "github.com/coder/coder/v2/coderd/render"
 	"github.com/coder/coder/v2/codersdk"
-	"github.com/coder/coder/v2/codersdk/wsjson"
 	"github.com/coder/websocket"
 )

@@ -127,6 +126,7 @@ func (api *API) watchInboxNotifications(rw http.ResponseWriter, r *http.Request)
 		templates  = p.UUIDs(vals, []uuid.UUID{}, "templates")
 		readStatus = p.String(vals, "all", "read_status")
 		format     = p.String(vals, notificationFormatMarkdown, "format")
+		logger     = api.Logger.Named("inbox_notifications_watcher")
 	)
 	p.ErrorExcessParams(vals)
 	if len(p.Errors) > 0 {
@@ -214,11 +214,17 @@ func (api *API) watchInboxNotifications(rw http.ResponseWriter, r *http.Request)
 		return
 	}

-	go httpapi.Heartbeat(ctx, conn)
-	defer conn.Close(websocket.StatusNormalClosure, "connection closed")
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()

-	encoder := wsjson.NewEncoder[codersdk.GetInboxNotificationResponse](conn, websocket.MessageText)
-	defer encoder.Close(websocket.StatusNormalClosure)
+	_ = conn.CloseRead(context.Background())
+
+	ctx, wsNetConn := codersdk.WebsocketNetConn(ctx, conn, websocket.MessageText)
+	defer wsNetConn.Close()
+
+	go httpapi.HeartbeatClose(ctx, logger, cancel, conn)
+
+	encoder := json.NewEncoder(wsNetConn)

 	// Log the request immediately instead of after it completes.
 	if rl := loggermw.RequestLoggerFromContext(ctx); rl != nil {
@@ -227,8 +233,12 @@ func (api *API) watchInboxNotifications(rw http.ResponseWriter, r *http.Request)

 	for {
 		select {
+		case <-api.ctx.Done():
+			return
+
 		case <-ctx.Done():
 			return
+
 		case notif := <-notificationCh:
 			unreadCount, err := api.Database.CountUnreadInboxNotificationsByUserID(ctx, apikey.UserID)
 			if err != nil {
@@ -63,6 +63,7 @@ type StateSnapshotter interface {
 type Claimer interface {
 	Claim(
 		ctx context.Context,
+		store database.Store,
 		now time.Time,
 		userID uuid.UUID,
 		name string,
@@ -34,7 +34,7 @@ var DefaultReconciler ReconciliationOrchestrator = NoopReconciler{}

 type NoopClaimer struct{}

-func (NoopClaimer) Claim(context.Context, time.Time, uuid.UUID, string, uuid.UUID, sql.NullString, sql.NullTime, sql.NullInt64) (*uuid.UUID, error) {
+func (NoopClaimer) Claim(context.Context, database.Store, time.Time, uuid.UUID, string, uuid.UUID, sql.NullString, sql.NullTime, sql.NullInt64) (*uuid.UUID, error) {
 	// Not entitled to claim prebuilds in AGPL version.
 	return nil, ErrAGPLDoesNotSupportPrebuiltWorkspaces
 }
@@ -2026,13 +2026,11 @@ func (s *server) completeWorkspaceBuildJob(ctx context.Context, job database.Pro
 		}

 		var (
-			hasAITask    bool
 			unknownAppID string
 			taskAppID    uuid.NullUUID
 			taskAgentID  uuid.NullUUID
 		)
 		if tasks := jobType.WorkspaceBuild.GetAiTasks(); len(tasks) > 0 {
-			hasAITask = true
 			task := tasks[0]
 			if task == nil {
 				return xerrors.Errorf("update ai task: task is nil")
@@ -2048,7 +2046,6 @@ func (s *server) completeWorkspaceBuildJob(ctx context.Context, job database.Pro

 			if !slices.Contains(appIDs, appID) {
 				unknownAppID = appID
-				hasAITask = false
 			} else {
 				// Only parse for valid app and agent to avoid fk violation.
 				id, err := uuid.Parse(appID)
@@ -2083,7 +2080,7 @@ func (s *server) completeWorkspaceBuildJob(ctx context.Context, job database.Pro
 				Level:     []database.LogLevel{database.LogLevelWarn, database.LogLevelWarn, database.LogLevelWarn, database.LogLevelWarn},
 				Stage:     []string{"Cleaning Up", "Cleaning Up", "Cleaning Up", "Cleaning Up"},
 				Output: []string{
-					fmt.Sprintf("Unknown ai_task_app_id %q. This workspace will be unable to run AI tasks. This may be due to a template configuration issue, please check with the template author.", taskAppID.UUID.String()),
+					fmt.Sprintf("Unknown ai_task_app_id %q. This workspace will be unable to run AI tasks. This may be due to a template configuration issue, please check with the template author.", unknownAppID),
 					"Template author: double-check the following:",
 					"  - You have associated the coder_ai_task with a valid coder_app in your template (ref: https://registry.terraform.io/providers/coder/coder/latest/docs/resources/ai_task).",
 					"  - You have associated the coder_agent with at least one other compute resource. Agents with no other associated resources are not inserted into the database.",
@@ -2098,21 +2095,23 @@ func (s *server) completeWorkspaceBuildJob(ctx context.Context, job database.Pro
 			}
 		}

-		if hasAITask && workspaceBuild.Transition == database.WorkspaceTransitionStart {
-			// Insert usage event for managed agents.
-			usageInserter := s.UsageInserter.Load()
-			if usageInserter != nil {
-				event := usagetypes.DCManagedAgentsV1{
-					Count: 1,
-				}
-				err = (*usageInserter).InsertDiscreteUsageEvent(ctx, db, event)
-				if err != nil {
-					return xerrors.Errorf("insert %q event: %w", event.EventType(), err)
+		var hasAITask bool
+		if task, err := db.GetTaskByWorkspaceID(ctx, workspace.ID); err == nil {
+			hasAITask = true
+			if workspaceBuild.Transition == database.WorkspaceTransitionStart {
+				// Insert usage event for managed agents.
+				usageInserter := s.UsageInserter.Load()
+				if usageInserter != nil {
+					event := usagetypes.DCManagedAgentsV1{
+						Count: 1,
+					}
+					err = (*usageInserter).InsertDiscreteUsageEvent(ctx, db, event)
+					if err != nil {
+						return xerrors.Errorf("insert %q event: %w", event.EventType(), err)
+					}
 				}
 			}
-		}

-		if task, err := db.GetTaskByWorkspaceID(ctx, workspace.ID); err == nil {
 			// Irrespective of whether the agent or sidebar app is present,
 			// perform the upsert to ensure a link between the task and
 			// workspace build. Linking the task to the build is typically
@@ -2878,7 +2878,7 @@ func TestCompleteJob(t *testing.T) {
 			sidebarAppID := uuid.New()
 			for _, tc := range []testcase{
 				{
-					name:       "has_ai_task is false by default",
+					name:       "has_ai_task is false if task_id is nil",
 					transition: database.WorkspaceTransitionStart,
 					input:      &proto.CompletedJob_WorkspaceBuild{
 						// No AiTasks defined.
@@ -2887,6 +2887,37 @@ func TestCompleteJob(t *testing.T) {
 					expectHasAiTask:  false,
 					expectUsageEvent: false,
 				},
+				{
+					name:       "has_ai_task is false even if there are coder_ai_task resources, but no task_id",
+					transition: database.WorkspaceTransitionStart,
+					input: &proto.CompletedJob_WorkspaceBuild{
+						AiTasks: []*sdkproto.AITask{
+							{
+								Id:    uuid.NewString(),
+								AppId: sidebarAppID.String(),
+							},
+						},
+						Resources: []*sdkproto.Resource{
+							{
+								Agents: []*sdkproto.Agent{
+									{
+										Id:   uuid.NewString(),
+										Name: "a",
+										Apps: []*sdkproto.App{
+											{
+												Id:   sidebarAppID.String(),
+												Slug: "test-app",
+											},
+										},
+									},
+								},
+							},
+						},
+					},
+					isTask:           false,
+					expectHasAiTask:  false,
+					expectUsageEvent: false,
+				},
 				{
 					name:       "has_ai_task is set to true",
 					transition: database.WorkspaceTransitionStart,
@@ -2964,15 +2995,17 @@ func TestCompleteJob(t *testing.T) {
 							{
 								Id: uuid.NewString(),
 								// Non-existing app ID would previously trigger a FK violation.
-								// Now it should just be ignored.
+								// Now it will trigger a warning instead in the provisioner logs.
 								AppId: sidebarAppID.String(),
 							},
 						},
 					},
 					isTask:           true,
 					expectTaskStatus: database.TaskStatusInitializing,
-					expectHasAiTask:  false,
-					expectUsageEvent: false,
+					// You can still "sort of" use a task in this state, but as we don't have
+					// the correct app ID you won't be able to communicate with it via Coder.
+					expectHasAiTask:  true,
+					expectUsageEvent: true,
 				},
 				{
 					name:       "has_ai_task is set to true, but transition is not start",
@@ -3007,19 +3040,6 @@ func TestCompleteJob(t *testing.T) {
 					expectHasAiTask:  true,
 					expectUsageEvent: false,
 				},
-				{
-					name:       "current build does not have ai task but previous build did",
-					seedFunc:   seedPreviousWorkspaceStartWithAITask,
-					transition: database.WorkspaceTransitionStop,
-					input: &proto.CompletedJob_WorkspaceBuild{
-						AiTasks:   []*sdkproto.AITask{},
-						Resources: []*sdkproto.Resource{},
-					},
-					isTask:           true,
-					expectTaskStatus: database.TaskStatusPaused,
-					expectHasAiTask:  false, // We no longer inherit this from the previous build.
-					expectUsageEvent: false,
-				},
 			} {
 				t.Run(tc.name, func(t *testing.T) {
 					t.Parallel()
@@ -4410,62 +4430,3 @@ func (f *fakeUsageInserter) InsertDiscreteUsageEvent(_ context.Context, _ databa
 	f.collectedEvents = append(f.collectedEvents, event)
 	return nil
 }
-
-func seedPreviousWorkspaceStartWithAITask(ctx context.Context, t testing.TB, db database.Store) error {
-	t.Helper()
-	// If the below looks slightly convoluted, that's because it is.
-	// The workspace doesn't yet have a latest build, so querying all
-	// workspaces will fail.
-	tpls, err := db.GetTemplates(ctx)
-	if err != nil {
-		return xerrors.Errorf("seedFunc: get template: %w", err)
-	}
-	if len(tpls) != 1 {
-		return xerrors.Errorf("seedFunc: expected exactly one template, got %d", len(tpls))
-	}
-	ws, err := db.GetWorkspacesByTemplateID(ctx, tpls[0].ID)
-	if err != nil {
-		return xerrors.Errorf("seedFunc: get workspaces: %w", err)
-	}
-	if len(ws) != 1 {
-		return xerrors.Errorf("seedFunc: expected exactly one workspace, got %d", len(ws))
-	}
-	w := ws[0]
-	prevJob := dbgen.ProvisionerJob(t, db, nil, database.ProvisionerJob{
-		OrganizationID: w.OrganizationID,
-		InitiatorID:    w.OwnerID,
-		Type:           database.ProvisionerJobTypeWorkspaceBuild,
-	})
-	tvs, err := db.GetTemplateVersionsByTemplateID(ctx, database.GetTemplateVersionsByTemplateIDParams{
-		TemplateID: tpls[0].ID,
-	})
-	if err != nil {
-		return xerrors.Errorf("seedFunc: get template version: %w", err)
-	}
-	if len(tvs) != 1 {
-		return xerrors.Errorf("seedFunc: expected exactly one template version, got %d", len(tvs))
-	}
-	if tpls[0].ActiveVersionID == uuid.Nil {
-		return xerrors.Errorf("seedFunc: active version id is nil")
-	}
-	res := dbgen.WorkspaceResource(t, db, database.WorkspaceResource{
-		JobID: prevJob.ID,
-	})
-	agt := dbgen.WorkspaceAgent(t, db, database.WorkspaceAgent{
-		ResourceID: res.ID,
-	})
-	_ = dbgen.WorkspaceApp(t, db, database.WorkspaceApp{
-		AgentID: agt.ID,
-	})
-	_ = dbgen.WorkspaceBuild(t, db, database.WorkspaceBuild{
-		BuildNumber:       1,
-		HasAITask:         sql.NullBool{Valid: true, Bool: true},
-		ID:                w.ID,
-		InitiatorID:       w.OwnerID,
-		JobID:             prevJob.ID,
-		TemplateVersionID: tvs[0].ID,
-		Transition:        database.WorkspaceTransitionStart,
-		WorkspaceID:       w.ID,
-	})
-	return nil
-}
@@ -1077,6 +1077,74 @@ func (api *API) putUserAppearanceSettings(rw http.ResponseWriter, r *http.Reques
 	})
 }

+// @Summary Get user preference settings
+// @ID get-user-preference-settings
+// @Security CoderSessionToken
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Success 200 {object} codersdk.UserPreferenceSettings
+// @Router /users/{user}/preferences [get]
+func (api *API) userPreferenceSettings(rw http.ResponseWriter, r *http.Request) {
+	var (
+		ctx  = r.Context()
+		user = httpmw.UserParam(r)
+	)
+
+	taskAlertDismissed, err := api.Database.GetUserTaskNotificationAlertDismissed(ctx, user.ID)
+	if err != nil {
+		if !errors.Is(err, sql.ErrNoRows) {
+			httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+				Message: "Error reading user preference settings.",
+				Detail:  err.Error(),
+			})
+			return
+		}
+	}
+
+	httpapi.Write(ctx, rw, http.StatusOK, codersdk.UserPreferenceSettings{
+		TaskNotificationAlertDismissed: taskAlertDismissed,
+	})
+}
+
+// @Summary Update user preference settings
+// @ID update-user-preference-settings
+// @Security CoderSessionToken
+// @Accept json
+// @Produce json
+// @Tags Users
+// @Param user path string true "User ID, name, or me"
+// @Param request body codersdk.UpdateUserPreferenceSettingsRequest true "New preference settings"
+// @Success 200 {object} codersdk.UserPreferenceSettings
+// @Router /users/{user}/preferences [put]
+func (api *API) putUserPreferenceSettings(rw http.ResponseWriter, r *http.Request) {
+	var (
+		ctx  = r.Context()
+		user = httpmw.UserParam(r)
+	)
+
+	var params codersdk.UpdateUserPreferenceSettingsRequest
+	if !httpapi.Read(ctx, rw, r, &params) {
+		return
+	}
+
+	updatedTaskAlertDismissed, err := api.Database.UpdateUserTaskNotificationAlertDismissed(ctx, database.UpdateUserTaskNotificationAlertDismissedParams{
+		UserID:                         user.ID,
+		TaskNotificationAlertDismissed: params.TaskNotificationAlertDismissed,
+	})
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error updating user task notification alert dismissed.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	httpapi.Write(ctx, rw, http.StatusOK, codersdk.UserPreferenceSettings{
+		TaskNotificationAlertDismissed: updatedTaskAlertDismissed,
+	})
+}
+
 func isValidFontName(font codersdk.TerminalFontName) bool {
 	return slices.Contains(codersdk.TerminalFontNames, font)
 }
@@ -2192,16 +2192,16 @@ func TestUserTerminalFont(t *testing.T) {
 		firstUser := coderdtest.CreateFirstUser(t, adminClient)
 		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)

-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 		defer cancel()

 		// given
-		initial, err := client.GetUserAppearanceSettings(ctx, "me")
+		initial, err := client.GetUserAppearanceSettings(ctx, codersdk.Me)
 		require.NoError(t, err)
 		require.Equal(t, codersdk.TerminalFontName(""), initial.TerminalFont)

 		// when
-		updated, err := client.UpdateUserAppearanceSettings(ctx, "me", codersdk.UpdateUserAppearanceSettingsRequest{
+		updated, err := client.UpdateUserAppearanceSettings(ctx, codersdk.Me, codersdk.UpdateUserAppearanceSettingsRequest{
 			ThemePreference: "light",
 			TerminalFont:    "fira-code",
 		})
@@ -2218,16 +2218,16 @@ func TestUserTerminalFont(t *testing.T) {
 		firstUser := coderdtest.CreateFirstUser(t, adminClient)
 		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)

-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 		defer cancel()

 		// given
-		initial, err := client.GetUserAppearanceSettings(ctx, "me")
+		initial, err := client.GetUserAppearanceSettings(ctx, codersdk.Me)
 		require.NoError(t, err)
 		require.Equal(t, codersdk.TerminalFontName(""), initial.TerminalFont)

 		// when
-		_, err = client.UpdateUserAppearanceSettings(ctx, "me", codersdk.UpdateUserAppearanceSettingsRequest{
+		_, err = client.UpdateUserAppearanceSettings(ctx, codersdk.Me, codersdk.UpdateUserAppearanceSettingsRequest{
 			ThemePreference: "light",
 			TerminalFont:    "foobar",
 		})
@@ -2243,16 +2243,16 @@ func TestUserTerminalFont(t *testing.T) {
 		firstUser := coderdtest.CreateFirstUser(t, adminClient)
 		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)

-		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitLong)
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
 		defer cancel()

 		// given
-		initial, err := client.GetUserAppearanceSettings(ctx, "me")
+		initial, err := client.GetUserAppearanceSettings(ctx, codersdk.Me)
 		require.NoError(t, err)
 		require.Equal(t, codersdk.TerminalFontName(""), initial.TerminalFont)

 		// when
-		_, err = client.UpdateUserAppearanceSettings(ctx, "me", codersdk.UpdateUserAppearanceSettingsRequest{
+		_, err = client.UpdateUserAppearanceSettings(ctx, codersdk.Me, codersdk.UpdateUserAppearanceSettingsRequest{
 			ThemePreference: "light",
 			TerminalFont:    "",
 		})
@@ -2262,6 +2262,75 @@ func TestUserTerminalFont(t *testing.T) {
 	})
 }

+func TestUserTaskNotificationAlertDismissed(t *testing.T) {
+	t.Parallel()
+
+	t.Run("defaults to false", func(t *testing.T) {
+		t.Parallel()
+
+		adminClient := coderdtest.New(t, nil)
+		firstUser := coderdtest.CreateFirstUser(t, adminClient)
+		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		// When: getting user preference settings for a user
+		settings, err := client.GetUserPreferenceSettings(ctx, codersdk.Me)
+		require.NoError(t, err)
+
+		// Then: the task notification alert dismissed should default to false
+		require.False(t, settings.TaskNotificationAlertDismissed)
+	})
+
+	t.Run("update to true", func(t *testing.T) {
+		t.Parallel()
+
+		adminClient := coderdtest.New(t, nil)
+		firstUser := coderdtest.CreateFirstUser(t, adminClient)
+		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		// When: user dismisses the task notification alert
+		updated, err := client.UpdateUserPreferenceSettings(ctx, codersdk.Me, codersdk.UpdateUserPreferenceSettingsRequest{
+			TaskNotificationAlertDismissed: true,
+		})
+		require.NoError(t, err)
+
+		// Then: the setting is updated to true
+		require.True(t, updated.TaskNotificationAlertDismissed)
+	})
+
+	t.Run("update to false", func(t *testing.T) {
+		t.Parallel()
+
+		adminClient := coderdtest.New(t, nil)
+		firstUser := coderdtest.CreateFirstUser(t, adminClient)
+		client, _ := coderdtest.CreateAnotherUser(t, adminClient, firstUser.OrganizationID)
+
+		ctx, cancel := context.WithTimeout(context.Background(), testutil.WaitShort)
+		defer cancel()
+
+		// Given: user has dismissed the task notification alert
+		_, err := client.UpdateUserPreferenceSettings(ctx, codersdk.Me, codersdk.UpdateUserPreferenceSettingsRequest{
+			TaskNotificationAlertDismissed: true,
+		})
+		require.NoError(t, err)
+
+		// When: the task notification alert dismissal is cleared
+		// (e.g., when user enables a task notification in the UI settings)
+		updated, err := client.UpdateUserPreferenceSettings(ctx, codersdk.Me, codersdk.UpdateUserPreferenceSettingsRequest{
+			TaskNotificationAlertDismissed: false,
+		})
+		require.NoError(t, err)
+
+		// Then: the setting is updated to false
+		require.False(t, updated.TaskNotificationAlertDismissed)
+	})
+}
+
 func TestWorkspacesByUser(t *testing.T) {
 	t.Parallel()
 	t.Run("Empty", func(t *testing.T) {
@@ -132,7 +132,7 @@ func (api *API) workspaceAgentRPC(rw http.ResponseWriter, r *http.Request) {
 		WorkspaceID:    workspace.ID,
 		OrganizationID: workspace.OrganizationID,

-		Ctx:                               api.ctx,
+		AuthenticatedCtx:                  ctx,
 		Log:                               logger,
 		Clock:                             api.Clock,
 		Database:                          api.Database,
@@ -849,6 +849,63 @@ func (api *API) workspaceBuildState(rw http.ResponseWriter, r *http.Request) {
 	_, _ = rw.Write(workspaceBuild.ProvisionerState)
 }

+// @Summary Update workspace build state
+// @ID update-workspace-build-state
+// @Security CoderSessionToken
+// @Accept json
+// @Tags Builds
+// @Param workspacebuild path string true "Workspace build ID" format(uuid)
+// @Param request body codersdk.UpdateWorkspaceBuildStateRequest true "Request body"
+// @Success 204
+// @Router /workspacebuilds/{workspacebuild}/state [put]
+func (api *API) workspaceBuildUpdateState(rw http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+	workspaceBuild := httpmw.WorkspaceBuildParam(r)
+	workspace, err := api.Database.GetWorkspaceByID(ctx, workspaceBuild.WorkspaceID)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "No workspace exists for this job.",
+		})
+		return
+	}
+	template, err := api.Database.GetTemplateByID(ctx, workspace.TemplateID)
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Failed to get template",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	// You must have update permissions on the template to update the state.
+	if !api.Authorize(r, policy.ActionUpdate, template.RBACObject()) {
+		httpapi.ResourceNotFound(rw)
+		return
+	}
+
+	var req codersdk.UpdateWorkspaceBuildStateRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	// Use system context since we've already verified authorization via template permissions.
+	// nolint:gocritic // System access required for provisioner state update.
+	err = api.Database.UpdateWorkspaceBuildProvisionerStateByID(dbauthz.AsSystemRestricted(ctx), database.UpdateWorkspaceBuildProvisionerStateByIDParams{
+		ID:               workspaceBuild.ID,
+		ProvisionerState: req.State,
+		UpdatedAt:        dbtime.Now(),
+	})
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Failed to update workspace build state.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	rw.WriteHeader(http.StatusNoContent)
+}
+
 // @Summary Get workspace build timings by ID
 // @ID get-workspace-build-timings-by-id
 // @Security CoderSessionToken
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jakub Domeracki	8a097ee635	feat(site)!: add consent prompt for auto-creation with prefilled parameters (#22256 ) Cherry-pick of `60e3ab7632` from main. Workspace created via mode=auto links now require explicit user confirmation before provisioning. A warning dialog shows all prefilled param.* values from the URL and blocks creation until the user clicks `Confirm and Create`. Clicking `Cancel` falls back to the standard form view. ### Breaking behavior change Links using `mode=auto` (e.g., "Open in Coder" buttons) will no longer silently create workspaces. Users will now see a consent dialog and must explicitly confirm before the workspace is provisioned. Original PR: #22011 Co-authored-by: Kacper Sawicki <kacper@coder.com> Co-authored-by: Jake Howell <jacob@coder.com>	2026-02-23 17:37:57 -05:00
Danielle Maywood	2ca88b0f07	fix: avoid re-using `AuthInstanceID` for sub agents (#22196 ) (#22212 ) Parent agents were re-using AuthInstanceID when spawning child agents. This caused GetWorkspaceAgentByInstanceID to return the most recently created sub agent instead of the parent when the parent tried to refetch its own manifest. Fix by not reusing AuthInstanceID for sub agents, and updating GetWorkspaceAgentByInstanceID to filter them out entirely. --- Cherry picked from `911d734df9`	2026-02-23 17:37:41 -05:00
Jake Howell	79a0ff8249	feat: convert `soft_limit` to `limit` (cherry-pick/v2.29) (#22207 ) Related [`internal#1281`](https://github.com/coder/internal/issues/1281) Cherry picks two pull-requests in `release/2.29`. * https://github.com/coder/coder/pull/22048 * https://github.com/coder/coder/pull/21998 * https://github.com/coder/coder/pull/22210	2026-02-23 17:37:15 -05:00
Lukasz	7819c471f7	chore: bump bundled terraform to 1.14.5 for 2.29 (#22193 ) Description: This PR updates the bundled Terraform binary and related version pins from 1.13.4 to 1.14.5 (base image, installer fallback, and CI/test fixtures). Terraform is statically built with an embedded Go runtime. Moving to 1.14.5 updates the embedded toolchain and is intended to address Go stdlib CVEs reported by security scanning. Notes: - Change is version-only; no functional Coder logic changes. - Backport-friendly: intended to be cherry-picked to release branches after merge. --------- Co-authored-by: Jakub Domeracki <jakub@coder.com> Co-authored-by: Dean Sheather <dean@deansheather.com>	2026-02-23 15:32:41 +01:00
Lukasz	3aa8212aac	chore: bump versions of gh actions for 2.29 (#22218 ) Update gh actions: - aquasecurity/trivy-action v0.34.0 - harden-runner v2.14.2	2026-02-20 12:49:36 +01:00
Jon Ayers	8b2f472f71	chore: use old slog (#21959 )	2026-02-05 16:35:41 -06:00
Jon Ayers	13337a193c	chore: fix go.mod (#21958 )	2026-02-05 16:23:04 -06:00
Jon Ayers	b275be2e7a	chore: backport fixes (#21957 )	2026-02-05 16:09:41 -06:00
Lukasz	72afd3677c	chore: bump alpine to 3.23.3 in release/2.29 (#21879 ) (cherry picked from commit `3d97f677e5`) Co-authored-by: Jon Ayers <jon@coder.com>	2026-02-03 09:12:15 -06:00
Dean Sheather	7dfaa606ee	fix: fix various AI task usage accounting bugs (#21723 ) <!-- 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. --> --------- Co-authored-by: Cian Johnston <cian@coder.com> Co-authored-by: Steven Masley <Emyrk@users.noreply.github.com>	2026-01-29 10:06:45 -06:00
Cian Johnston	0c3144fc32	fix(coderd): ensure inbox WebSocket is closed when client disconnects… (#21684 ) … (#21652) Relates to https://github.com/coder/coder/issues/19715 This is similar to https://github.com/coder/coder/pull/19711 This endpoint works by doing the following: - Subscribing to the database's with pubsub - Accepts a WebSocket upgrade - Starts a `httpapi.Heartbeat` - Creates a json encoder - Infinitely loops waiting for notification until request context cancelled The critical issue here is that `httpapi.Heartbeat` silently fails when the client has disconnected. This means we never cancel the request context, leaving the WebSocket alive until we receive a notification from the database and fail to write that down the pipe. By replacing usage of `httpapi.Heartbeat` with `httpapi.HeartbeatClose`, we cancel the context _when the heartbeat fails to write_ due to the client disconnecting. This allows us to cleanup without waiting for a notification to come through the pubsub channel. (cherry picked from commit `409360c62d`) <!-- 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. --> Co-authored-by: Danielle Maywood <danielle@themaywoods.com>	2026-01-26 09:28:04 -06:00
Cian Johnston	b5360a9180	fix: backport migration fixes (#21611 ) * https://github.com/coder/coder/pull/21493 * https://github.com/coder/coder/pull/21496 * https://github.com/coder/coder/pull/21530 NB these commits were originally authored by Blink on behalf of @dannykopping, so amended to reflect actual authorship. Repro/Verification Steps: * Created a Coder deployment with a non-public schema via Docker compose on v2.28.6: * Created a DB init script under `db-init/01-create-schema.sql` with the following: ```sql CREATE SCHEMA IF NOT EXISTS coder AUTHORIZATION coder; GRANT ALL PRIVILEGES ON SCHEMA coder TO coder; ALTER ROLE coder SET search_path TO coder; ``` * Mounted above inside the `postgres` container: ```diff volumes: - coder_data:/var/lib/postgresql/data + - ./db-init:/docker-entrypoint-initdb.d:ro ``` * Edited `CODER_PG_CONNECTION_URL` to update the search path: ```diff environment: - CODER_PG_CONNECTION_URL: "postgresql://${POSTGRES_USER:-username}:${POSTGRES_PASSWORD:-password}@database/${POSTGRES_DB:-coder}?sslmode=disable" + CODER_PG_CONNECTION_URL: "postgresql://${POSTGRES_USER:-username}:${POSTGRES_PASSWORD:-password}@database/${POSTGRES_DB:-coder}?sslmode=disable&search_path=coder" ``` * Brought up the deployment: ```shell CODER_VERSION=v2.28.6 CODER_ACCESS_URL=http://localhost:7080 POSTGRES_USER=coder POSTGRES_PASSWORD=coder docker compose up` ``` * Created user / template / workspace * Updated to `v2.29.1`: * ```shell CODER_VERSION=v2.29.1 CODER_ACCESS_URL=http://localhost:7080 POSTGRES_USER=coder POSTGRES_PASSWORD=coder docker compose up` ``` * Observed following error: ``` database-1 \| 2026-01-21 15:07:17.629 UTC [102] ERROR: relation "public.workspace_agents" does not exist coder-1 \| Encountered an error running "coder server", see "coder server --help" for more information database-1 \| 2026-01-21 15:07:17.629 UTC [102] STATEMENT: CREATE INDEX IF NOT EXISTS workspace_agents_auth_instance_id_deleted_idx ON public.workspace_agents (auth_instance_id, deleted); coder-1 \| error: connect to postgres: connect to postgres: migrate up: up: 2 errors occurred: coder-1 \| * run statement: migration failed: relation "public.workspace_agents" does not exist in line 0: CREATE INDEX IF NOT EXISTS workspace_agents_auth_instance_id_deleted_idx ON public.workspace_agents (auth_instance_id, deleted); coder-1 \| (details: pq: relation "public.workspace_agents" does not exist) coder-1 \| * commit tx on unlock: pq: Could not complete operation in a failed transaction coder-1 exited with code 1 ``` * Built image locally: ```console $ make build/coder_$(./scripts/version.sh)_linux_amd64.tag ... ghcr.io/coder/coder:v2.29.1-devel-e8c482a98a67-amd64 ``` * Started with new image: ```shell CODER_VERSION=v2.29.1-devel-e8c482a98a67-amd64 CODER_ACCESS_URL=http://localhost:7080 POSTGRES_USER=coder POSTGRES_PASSWORD=coder docker compose up ``` * Observed migrations ran successfully and Coder came up successfully --------- Signed-off-by: Danny Kopping <danny@coder.com> Co-authored-by: Danny Kopping <danny@coder.com> Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>	2026-01-21 15:45:58 +00:00
Kacper Sawicki	2e2d0dde44	feat(cli): backport #21374 to 2.29 (#21561 ) backport #21374 to 2.29 feat(cli): add --no-build flag to state push for state-only updates #21374	2026-01-20 15:46:46 -06:00
Kacper Sawicki	2314e4a94e	fix: backport update boundary version to 2.29 (#21290 ) (#21575 ) fix: update boundary version https://github.com/coder/coder/pull/21290 required by https://github.com/coder/coder/pull/21561 Co-authored-by: Yevhenii Shcherbina <evgeniy.shcherbina.es@gmail.com>	2026-01-20 11:19:53 +01:00
blinkagent[bot]	bd76c602e4	chore: add antigravity to allowed protocols list (#20873 ) (#21122 ) Co-authored-by: DevCats <christofer@coder.com> Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: Atif Ali <atif@coder.com>	2025-12-29 13:29:28 +05:00
Jakub Domeracki	59cdd7e21f	chore: update react to apply patch for CVE-2025-55182 (#21084 ) (#21168 ) Reference: https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components > Please note that coder deployments aren't vulnerable since [React Server Components](https://react.dev/reference/rsc/server-components) aren't in use --------- Co-authored-by: blinkagent[bot] <237617714+blinkagent[bot]@users.noreply.github.com> Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com>	2025-12-09 09:34:16 -06:00
blinkagent[bot]	ba71b321bc	fix: remove a sensitive field from an agent log line (#20968 ) (#21063 ) This PR removes a log field that could expose sensitive information in agent logs for workspaces that pass such information to the agent via its manifest. (cherry picked from commit `1d726c81bb`) Co-authored-by: Sas Swart <sas.swart.cdk@gmail.com>	2025-12-02 11:33:50 -06:00
Callum Styan	c94c470aae	fix: pass context with authorization to agentapi (#21045 ) cherry pick 20959 into release branch Signed-off-by: Callum Styan <callumstyan@gmail.com>	2025-12-01 14:16:30 -06:00
Zach	8430dd648a	fix(cli): remove defaulting to keyring when --global-config set (cherry-pick) (#20953 ) (cherry picked from commit `bbf7b137da`)	2025-12-01 14:09:54 -06:00
Susana Ferreira	0bd0990e14	feat: add notification warning alert to Tasks page (#20900 ) (#20981 ) Related to PR: https://github.com/coder/coder/pull/20900 (cherry picked from commit `f8d9a8046f`)	2025-12-01 14:08:50 -06:00
Susana Ferreira	10e70f8c51	fix: show task display name in task topbar (#20957 ) (#20980 ) Related to PR: https://github.com/coder/coder/pull/20957 (cherry picked from commit `21efebeadc`)	2025-12-01 14:08:01 -06:00
Sas Swart	abe66a38eb	feat: implement agent socket api, client and cli (#20758 ) (#20976 )	2025-12-01 14:07:40 -06:00
Jake Howell	cd9d3ef46f	fix: ensure we check if the user can actually see `ai bridge` (#20964 )	2025-12-01 14:07:18 -06:00
Mathias Fredriksson	c0a2522bd6	fix(site): only show active tasks in waiting for input tab (#20933 ) (#20955 )	2025-12-01 14:06:44 -06:00
Danny Kopping	dfa25d5f00	chore: document bedrock setup process for `aibridge` (#20956 ) (#20966 ) Cherry-pick of https://github.com/coder/coder/pull/20956 Signed-off-by: Danny Kopping <danny@coder.com>	2025-11-28 13:09:10 +05:00