@kontextmind/kxm/docs/prompts/browser-diagnose-recover.md

KXM local-first multi-agent orchestration and operator dashboard

---
schema: "kxm.doc.v1"
id: "PROMPT-BROWSER-004"
type: "prompt"
title: "Diagnose and recover a failed browser session"
project: "kxm"
status: "accepted"
owner: "@operator"
created: "2026-09-14"
updated: "2026-09-27"
authority: "instruction"
confidence: "verified"
summary: "Troubleshoot unresponsive Steel sessions, CDP attachment errors, auth loops, and orphaned browser containers."
tags: ["browser", "diagnostics", "recovery", "prompt"]
related: ["docs/guides/browser-automation.md", "docs/kb/how-to-recover-expired-session-or-orphan.md"]
---

# Task template: diagnose and recover a failed browser session

## Purpose

Use this prompt to troubleshoot unresponsive sessions, CDP attachment errors, authentication loops, or orphaned browser containers on your Steel deployment.

## Canonical skill references

- `kxm-browser-diagnostics`
- `kxm-browser-session`

## Parameters and placeholders

- **PROJECT_ID**: `{{PROJECT_ID}}`
- **STEEL_API_URL**: `{{STEEL_API_URL}}` (your Steel API base URL, from `STEEL_API_URL`)
- **SESSION_ID**: `{{SESSION_ID}}` (Optional, if specific session is failing)
- **FAILURE_SYMPTOM**: `{{FAILURE_SYMPTOM}}` (e.g. `CDP_ATTACHMENT_FAILED` | `TIMEOUT_EXPIRED` | `AUTH_LOOP` | `ORPHAN_CLEANUP`)
- **MAX_IDLE_MINUTES**: `{{MAX_IDLE_MINUTES}}` (Default: `10`)

---

## Instructions for the agent

1. **Check Steel Health**:
   - Query `{{STEEL_API_URL}}/v1/health`.
   - If HTTP 200, Steel server and Chromium engine are healthy.

2. **Inspect Session Status**:
   - If `{{SESSION_ID}}` is provided: query `GET /v1/sessions/{{SESSION_ID}}`.
   - If status is `released`, report that the session expired and launch a fresh replacement.

3. **Check for Orphaned Sessions**:
   - Query all active sessions: `GET /v1/sessions`.
   - Identify sessions older than `{{MAX_IDLE_MINUTES}}` minutes that are not actively bound to a running task.
   - For each orphan, invoke `POST /v1/sessions/:id/release`.

4. **Verify WebSocket / CDP Ingress**:
   - Steel is reached only through Caddy and Authentik forward auth. Direct LAN, tailnet, and host-forward connections are blocked. The CDP path is `/v1/devtools` with an `Authorization` header.
   - If the response is a 302 to `id.kxmd.dev`, or CDP fails with 401 or 403, send `Authorization: Basic` from `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. A Bearer token is not accepted. Do not put the credential in the URL. `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. Sessions return `websocketUrl` `wss://steel.kontextmind.com/`. `kxm` 0.7.135 or newer is required.