@kontextmind/kxm 0.6.0 → 0.7.10

package/docs/browser-automation.md

@@ -0,0 +1,116 @@
+---
+schema: "kxm.doc.v1"
+id: "GUIDE-BROWSER-001"
+type: "guide"
+title: "KXM Browser Automation Guide"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Comprehensive guide to browser automation in KXM using self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover."
+tags: ["browser", "automation", "steel", "playwright", "agent-browser", "doks"]
+related: ["docs/adr/ADR-0002-browser-automation-steel-doks.md", "docs/agent-skills.md"]
+---
+
+# KXM Browser Automation Guide
+
+This guide describes how to use KXM's browser automation capability powered by self-hosted Steel on DigitalOcean Kubernetes (DOKS), `agent-browser` for exploratory inspection, `Playwright` for automated regression testing, and `pass-cli` for credential security.
+
+---
+
+## 1. Architecture & Trust Boundaries
+
+```text
+Herdr / Pi / Agent Harness
+  │
+  ├──► KXM Browser Skills & Prompts (kxm-browser-*)
+  │
+  ├──► pass-cli (Authoritative Vault: "AI Provider Keys")
+  │
+  ├──► agent-browser (Exploratory CLI) ──┐
+  │                                      │ (CDP WebSocket)
+  ├──► Playwright (E2E Test Suites) ────┼──► DOKS Steel Browser Cluster
+  │                                      │   (https://steel.kontextmind.com)
+  └──► Human Operator (Takeover UI) ─────┘   (https://steel.kontextmind.com/ui)
+```
+
+### Key Components
+
+1. **Steel on DOKS (`https://steel.kontextmind.com`)**:
+   - Primary browser execution environment.
+   - Isolated Chromium containers with dedicated shared memory (`/dev/shm`).
+   - Exposed endpoints: REST API (port 443 / 3000), CDP WebSocket proxy (port 443 / 9223), Web UI (`/ui`), OpenAPI docs (`/documentation`).
+2. **`pass-cli`**:
+   - The authoritative store for all long-lived passwords, session tokens, and the `STEEL_API_KEY`.
+   - Never write credentials to tracked git files.
+3. **`agent-browser`**:
+   - Fast, token-efficient terminal CLI for accessibility snapshots, interactive navigation, and exploratory testing.
+4. **`Playwright`**:
+   - High-fidelity assertion engine for bug reproduction, visual proofs, and permanent regression suites.
+
+---
+
+## 2. Getting Started: The First Browser Workflow
+
+### Step 1: Verify Prerequisites
+
+Check that `pass-cli` can access the Steel configuration:
+
+```bash
+pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)"
+```
+
+### Step 2: Launch a Steel Browser Session
+
+```bash
+STEEL_KEY=$(pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY)
+
+# Create a 5-minute session
+SESSION_RESP=$(curl -s -X POST https://steel.kontextmind.com/v1/sessions \
+  -H "Content-Type: application/json" \
+  -H "x-steel-api-key: $STEEL_KEY" \
+  -d '{"timeout": 300000}')
+
+SESSION_ID=$(echo "$SESSION_RESP" | jq -r .id)
+echo "Session created: $SESSION_ID"
+```
+
+### Step 3: Run Exploratory Automation or Scrapes
+
+To run a fast scrape without managing sessions:
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/scrape \
+  -H "Content-Type: application/json" \
+  -H "x-steel-api-key: $STEEL_KEY" \
+  -d '{"url": "https://example.com"}'
+```
+
+### Step 4: Release the Session
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/sessions/$SESSION_ID/release \
+  -H "x-steel-api-key: $STEEL_KEY"
+```
+
+---
+
+## 3. Human Takeover Protocol
+
+When authentication challenges (MFA, CAPTCHA, SSO) are encountered:
+
+1. **Agent Pauses**: The agent stops automated actions and sets state to `HUMAN_CONTROL`.
+2. **Emits Link**: Emits the protected URL: `https://steel.kontextmind.com/ui?sessionId=<SESSION_ID>`.
+3. **Human Interacts**: The operator opens the session viewer, completes the login/MFA action, and confirms in the terminal (`auth complete`).
+4. **Agent Verifies**: The agent inspects the resulting page, confirms dashboard/user state, refreshes DOM observations, and returns to `AGENT_CONTROL`.
+
+---
+
+## 4. Resource Controls & Cost Safety
+
+- **Session Timeouts**: Default 300s (5m), max 1800s (30m). Sessions terminate automatically on expiry.
+- **Orphan Sweeping**: Periodically sweep untracked sessions via `GET /v1/sessions` and release idle processes.
+- **Memory Protection**: Kubernetes mounts a 2Gi `emptyDir` memory volume at `/dev/shm` to prevent Chromium tab crashes without exhausting node memory.

package/docs/configuration.md

@@ -74,6 +74,15 @@ rewrites it.
 
 The hub refuses a non-loopback bind without `KXM_AUTH_TOKEN`. Use a long random administrative token even when project tokens are configured, because administrative endpoints such as `/metrics` require it outside loopback.
 
+When `KXM_AUTH_TOKEN` is unset, `kxm hub start` resolves credentials from the
+persisted `kxm.hub-env.v1` file under the user state root
+(`~/.local/state/kxm/hub-env.json`; honors `KXM_STATE_HOME` and platform
+equivalents). A missing admin token is generated once, persisted with `0600`
+permissions, and reused across hub restarts so workers and dashboards on the
+same machine share one stable credential. Explicit `KXM_AUTH_TOKEN` or
+`KXM_PROJECT_TOKENS` environment values take precedence and are persisted for
+later restarts. Delete the file and restart to rotate the generated token.
+
 Project tokens are an authorization boundary. A project-specific token can register only in its mapped project and see only that project's agents and messages. The administrative token remains a fallback for projects without an explicit entry. For provenance-gated workflows, configure an explicit project token and give workers only that token; reserve a distinct administrative token for operations such as quorum degradation approval.
 
 PowerShell example:
@@ -269,7 +278,7 @@ Global flags: `--json`, `--dry-run`, `--workspace`. Project-root `kxm init` disc
 
 Configure either `KXM_WEBHOOK_WORKFLOWS` or `KXM_WEBHOOK_WORKFLOWS_FILE`, never both. A definition selects a provider source, project, coordinator, event and payload filters, prompt template, and ordered stages. Use `secretEnv` to resolve the workflow-start HMAC secret from another environment variable. Use the optional `signalSecretEnv` for a separate callback secret; otherwise external signals use the workflow-start secret. Do not store either secret in JSON.
 
-See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/config/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
+See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
 
 ## Delivery modes
 
@@ -279,7 +288,7 @@ See [Webhook workflows](webhook-workflows.md) for the base schema and the comple
 | `steer` | An active blocker requires a course change | Deliver at the next decision boundary |
 | `nextTurn` | Information should wait for a later turn | Queue context without immediate work |
 
-`followUp` is the safe default. Use [`.kxm/config/env.example`](../.kxm/config/env.example) as a reference, but load values through your shell, supervisor, container platform, or secret manager. Never commit real tokens.
+`followUp` is the safe default. Load values through your shell, supervisor, container platform, or secret manager using the variables documented on this page and in the [KXM Handbook](kxm-handbook.md). Never commit real tokens.
 
 ## Nous providers (opt-in)
 

package/docs/getting-started.md

@@ -61,6 +61,27 @@ kxm init
 
 `kxm init` never copies the package repository's dogfood roster or workflows into a consumer workspace.
 
+When `kxm init` succeeds in an interactive terminal, it offers to install shell
+completion for the detected shell. Accepting writes the completion script
+under the user config directory, appends one idempotent stanza to the shell
+rc file, and, when the kxm bin directory is not already on `PATH`, adds a
+`PATH` export. Declining is safe: run `kxm completion install` later, or set
+`KXM_SKIP_COMPLETION_PROMPT=1` to suppress the offer. Non-interactive,
+`--json`, and `--dry-run` runs never prompt or write shell files.
+
+After the completion offer, an interactive `kxm init` also offers to set up
+workflow-guide agents and workflows for the harnesses you have installed and
+authenticated. Accepting lists the software-engineering workflows from
+[`workflow-guide.md`](workflow-guide.md); pick by number or slug (`all` works
+too). kxm resolves each role's first guide candidate whose harness is
+authenticated and writes only current vNext project resources —
+`.kxm/agents/<role>.yaml` (`kxm.agent.v1`) and `.kxm/workflows/<slug>.yaml`
+(`kxm.workflow.v1`). It never writes retired legacy authority (`.kxm/config`,
+`.kxm/roster.json`). Roles whose candidates have no authenticated harness are
+reported as skipped, not silently downgraded. Guide candidates are dated
+research — verify them before dispatch. Declining is safe: set
+`KXM_SKIP_GUIDE_SETUP_PROMPT=1` to suppress the offer.
+
 ## 3. Start the hub in another terminal
 
 `kxm hub start` is foreground. Keep that terminal running.

package/docs/kb/how-credentials-retrieved-safely.md

@@ -0,0 +1,31 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-003"
+type: "kb"
+title: "How are credentials retrieved without exposing them to the model?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Explains safe pass-cli credential delivery and environment piping patterns that avoid LLM context leakage."
+tags: ["browser", "credentials", "pass-cli", "security"]
+related: ["docs/browser-automation.md", "docs/agent-skills.md"]
+---
+
+# How are credentials retrieved without exposing them to the model?
+
+To protect passwords, MFA secrets, and API tokens from leaking into model reasoning traces, KXM enforces strict credential-reference boundaries:
+
+## Mechanisms
+
+1. **Authoritative Store**: All secrets reside in `pass-cli` (Proton Pass).
+2. **In-Process Environment Piping**:
+   - Automated test scripts use `pass-cli run -- npm test` or retrieve credentials directly into child process memory via standard environment variables.
+   - The LLM prompt only receives credential references (e.g., `vault: "AI Provider Keys", item: "Steel Browser (KontextMind DOKS)"`), never raw secret values.
+3. **Log Sanitization**:
+   - The KXM browser client strips API keys and token parameters (`apiKey=[REDACTED]`, `steel_[REDACTED]`) before logging or emitting outputs.
+4. **Human Handoff for High-Privilege Auth**:
+   - For sensitive production accounts or MFA, the agent never touches the credential at all; it invokes `kxm-browser-takeover` and lets the human authenticate directly in the UI.

package/docs/kb/how-to-capture-and-annotate-section.md

@@ -0,0 +1,60 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-009"
+type: "kb"
+title: "How do I capture a UI section and annotate changes for an agent?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Guide to capturing specific DOM elements, attaching visual annotations, and submitting structured change feedback to the agent."
+tags: ["browser", "annotation", "screenshot", "feedback", "ui"]
+related: ["docs/browser-automation.md", "docs/prompts/browser-annotate-feedback.md"]
+---
+
+# How do I capture a UI section and annotate changes for an agent?
+
+When reviewing a web interface in a Steel session, you can isolate a specific component, attach annotations, and deliver structured change requests directly back to an agent.
+
+## Workflow
+
+1. **Capture the Component**:
+   Use Playwright element screenshotting to crop only the affected container:
+
+   ```typescript
+   await page.locator('.billing-card').screenshot({ path: '.kxm/artifacts/browser/billing-card.png' });
+   ```
+
+2. **Draft the Annotation Feedback**:
+   Record the target selector, observed issues, and required fixes:
+
+   ```typescript
+   import { createAnnotationFeedback, formatAnnotationFeedbackPrompt } from "@kontextmind/kxm/runtime";
+
+   const feedback = createAnnotationFeedback({
+     url: "https://app.example.com/settings/billing",
+     sectionSelector: ".billing-card",
+     screenshotPath: ".kxm/artifacts/browser/billing-card.png",
+     overallSummary: "Billing tier layout breaks on mobile viewport",
+     annotations: [
+       {
+         label: "Tier Name Overflow",
+         selector: ".tier-title",
+         note: "Truncate or wrap long tier titles with ellipsis",
+         severity: "fix"
+       }
+     ],
+     requestedChanges: [
+       "Update `.tier-title` CSS to include `truncate` or `break-words`",
+       "Adjust padding on small viewports to `px-4`"
+     ]
+   });
+
+   const prompt = formatAnnotationFeedbackPrompt(feedback);
+   ```
+
+3. **Send to the Agent**:
+   Feed the rendered prompt into the agent session or KXM workflow run. The agent reads the screenshot, navigates to the source code, applies the changes, and verifies the result with Playwright.

package/docs/kb/how-to-connect-playwright-to-steel.md

@@ -0,0 +1,54 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-007"
+type: "kb"
+title: "How do I connect Playwright to the existing Steel session?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Guide to attaching Playwright tests to an active remote Steel browser session using chromium.connectOverCDP()."
+tags: ["browser", "playwright", "cdp", "steel", "testing"]
+related: ["docs/browser-automation.md", "docs/kb/why-automation-opened-different-browser.md"]
+---
+
+# How do I connect Playwright to the existing Steel session?
+
+To run Playwright tests against self-hosted Steel on DOKS instead of a local browser:
+
+## 1. Retrieve the CDP Endpoint
+
+Format the WebSocket CDP URL using the active session ID and API key:
+
+```typescript
+import { formatCDPEndpoint, resolveSteelConfig } from "@kontextmind/kxm/runtime";
+
+const config = resolveSteelConfig();
+const cdpUrl = formatCDPEndpoint({ id: sessionId, websocketUrl: "" }, config);
+```
+
+The resulting URL will look like:
+`wss://steel.kontextmind.com/v1/devtools?sessionId=<SESSION_ID>&apiKey=<STEEL_API_KEY>`
+
+## 2. Connect in Playwright
+
+```typescript
+import { test, expect, chromium } from "@playwright/test";
+
+test("execute test on remote steel session", async () => {
+  const browser = await chromium.connectOverCDP(process.env.STEEL_CDP_URL!);
+  
+  // Use existing context or create one
+  const context = browser.contexts()[0] || await browser.newContext();
+  const page = context.pages()[0] || await context.newPage();
+
+  await page.goto("https://app.example.com");
+  await expect(page.getByRole("heading", { level: 1 })).toBeVisible();
+
+  // Disconnecting closes the Playwright CDP socket without terminating the remote container
+  await browser.close();
+});
+```

package/docs/kb/how-to-recover-expired-session-or-orphan.md

@@ -0,0 +1,54 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-008"
+type: "kb"
+title: "How do I recover an expired session or remove an orphaned browser?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Procedures for detecting and releasing stale or orphaned browser sessions on Steel."
+tags: ["browser", "cleanup", "orphans", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/why-authentication-disappeared.md"]
+---
+
+# How do I recover an expired session or remove an orphaned browser?
+
+If an automation run crashed or disconnected without calling `/release`, a browser container may remain idling on DOKS.
+
+## 1. List Active Remote Sessions
+
+```bash
+STEEL_KEY=$(pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY)
+
+curl -s https://steel.kontextmind.com/v1/sessions \
+  -H "x-steel-api-key: $STEEL_KEY" | jq .
+```
+
+## 2. Release Orphaned Sessions
+
+To terminate a specific stale session:
+
+```bash
+curl -s -X POST https://steel.kontextmind.com/v1/sessions/<SESSION_ID>/release \
+  -H "x-steel-api-key: $STEEL_KEY"
+```
+
+## 3. Automatic Orphan Sweeping via KXM Client
+
+The KXM client provides `checkOrphanedSessions(maxIdleMs)` to automate this:
+
+```typescript
+import { SteelClient } from "@kontextmind/kxm/runtime";
+
+const client = new SteelClient();
+const orphans = await client.checkOrphanedSessions(600000); // > 10 min idle
+
+for (const sessionId of orphans) {
+  console.log(`Releasing orphaned session: ${sessionId}`);
+  await client.releaseSession(sessionId);
+}
+```

package/docs/kb/how-to-resume-after-mfa.md

@@ -0,0 +1,28 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-002"
+type: "kb"
+title: "How does an agent resume after MFA?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Details the verification and observation refresh sequence when resuming automation after MFA."
+tags: ["browser", "mfa", "resume", "verification"]
+related: ["docs/kb/how-to-take-over-session.md", "docs/browser-automation.md"]
+---
+
+# How does an agent resume after MFA?
+
+Once the human completes the MFA challenge in the browser viewer, the agent must not immediately execute blind clicks. It follows this sequence:
+
+1. **State Transition**: Moves from `HUMAN_CONTROL` to `VERIFY_AUTHENTICATION`.
+2. **CDP Re-attachment**: Re-queries the active tab target from the remote Steel CDP endpoint.
+3. **App State Verification**:
+   - Inspects `page.url()` to confirm the browser navigated away from the MFA prompt to the intended destination (e.g. `/dashboard` or `/overview`).
+   - Checks for authenticated elements (e.g. account menu, logout button, user profile avatar).
+4. **Observation Refresh**: Runs a fresh `agent-browser snapshot` or queries fresh DOM locators before executing the next action.
+5. **Restore Control**: Returns to `AGENT_CONTROL` and proceeds with the task.

package/docs/kb/how-to-take-over-session.md

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-001"
+type: "kb"
+title: "How do I take over a browser session to log in?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Instructions for taking over an active Steel browser session during an authentication gate."
+tags: ["browser", "takeover", "auth", "mfa"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-resume-after-mfa.md"]
+---
+
+# How do I take over a browser session to log in?
+
+When an agent encounters a login screen, OAuth prompt, or security challenge, it triggers the `kxm-browser-takeover` protocol.
+
+## Steps
+
+1. **Copy the Takeover URL**:
+   The agent will emit a message in the terminal with a link like:
+   `https://steel.kontextmind.com/ui?sessionId=<SESSION_ID>`
+2. **Open the Session Viewer**:
+   Open that URL in your desktop browser. You will see the live screencast of the exact remote Chrome container the agent was operating.
+3. **Interact and Authenticate**:
+   Enter the username, password, or security key into the session, or use the devtools inspector (`https://steel.kontextmind.com/v1/devtools/inspector.html`) to trigger the submission.
+4. **Signal Completion**:
+   Return to your Herdr or Pi terminal session and notify the agent: `auth complete` or `proceed`.

package/docs/kb/why-authentication-disappeared.md

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-004"
+type: "kb"
+title: "Why did authentication disappear?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Diagnosing lost authentication state, session expiration, and ephemeral container recreation."
+tags: ["browser", "authentication", "cookies", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/why-automation-opened-different-browser.md"]
+---
+
+# Why did authentication disappear?
+
+If an agent was authenticated on a previous step or run and suddenly encounters a login screen again, the root causes are typically:
+
+## Root Causes & Fixes
+
+1. **Session Released or Expired**:
+   - Steel sessions are ephemeral by default. Once a session reaches its timeout (e.g. 5–30 minutes) or is released via `POST /v1/sessions/:id/release`, all memory cookies and local storage are cleared.
+   - **Fix**: To reuse state across tasks, save `storageState` via Playwright and reload it on the next session initialization.
+2. **New Session Launched Instead of Attaching**:
+   - If the agent created a brand-new session instead of passing the existing `sessionId`, it opened a clean Chrome profile.
+   - **Fix**: Verify that the task passes `sessionId` to `getSession()` or uses the existing CDP endpoint.
+3. **Domain / Subdomain Cookie Scoping**:
+   - OAuth flows often set cookies on subdomains (e.g., `auth.example.com`) that do not automatically share with `app.example.com`.
+   - **Fix**: Ensure cookies were issued for the primary domain or that SSO redirect completed fully before saving state.

package/docs/kb/why-automation-opened-different-browser.md

@@ -0,0 +1,32 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-005"
+type: "kb"
+title: "Why did automation open a different browser?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Preventing accidental local browser launches and ensuring Playwright and agent-browser connect to remote Steel."
+tags: ["browser", "cdp", "playwright", "agent-browser", "troubleshooting"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-connect-playwright-to-steel.md"]
+---
+
+# Why did automation open a different browser?
+
+If you expected automation to run on DOKS Steel but saw a local Chrome window pop up or failed to see the agent's actions in the Steel session viewer:
+
+## Root Causes
+
+1. **Called `chromium.launch()` Instead of `chromium.connectOverCDP()`**:
+   - `chromium.launch()` spawns a local browser process on the workstation.
+   - **Fix**: In Playwright, always use `chromium.connectOverCDP(cdpUrl)`.
+2. **Missing `--cdp` Flag in `agent-browser`**:
+   - Running `agent-browser open <url>` without `--cdp` spawns a local headless browser.
+   - **Fix**: Always pass `--cdp "wss://steel.kontextmind.com/v1/devtools?sessionId=<id>&apiKey=<key>"`.
+3. **Missing Environment Variables**:
+   - If `STEEL_CDP_URL` is undefined, scripts that fall back to local execution will launch a local browser.
+   - **Fix**: Ensure `STEEL_CDP_URL` or `STEEL_API_KEY` is loaded from `pass-cli`.

package/docs/kb/why-session-viewer-cannot-control.md

@@ -0,0 +1,31 @@
+---
+schema: "kxm.doc.v1"
+id: "KB-BROWSER-006"
+type: "kb"
+title: "Why can I view a session but not control it?"
+project: "kxm"
+status: "accepted"
+owner: "@operator"
+created: "2026-09-14"
+updated: "2026-09-14"
+authority: "instruction"
+confidence: "verified"
+summary: "Understanding self-hosted Steel OSS screencast viewer capabilities vs devtools inspector input modes."
+tags: ["browser", "takeover", "steel", "ui"]
+related: ["docs/browser-automation.md", "docs/kb/how-to-take-over-session.md"]
+---
+
+# Why can I view a session but not control it?
+
+In self-hosted open-source Steel (`steel-dev/steel-browser`), the web UI at `/ui` provides a real-time screencast stream, event logs, and network tracking. Depending on browser canvas capture modes, direct clicks on the video canvas may not send synthetic mouse events.
+
+## Resolution
+
+1. **Use the Chrome DevTools Inspector**:
+   Navigate to the devtools inspector page for the session:
+   `https://steel.kontextmind.com/v1/devtools/inspector.html`
+   or open the remote debugger on port 9223.
+2. **Interact via the DOM Console**:
+   The devtools inspector gives full interactive control over the DOM, console, network, and storage.
+3. **Agent Automation Coexistence**:
+   Ensure the agent is in `HUMAN_CONTROL` state so automation does not race or override your clicks.

package/docs/kxm-handbook.md

@@ -695,7 +695,7 @@ Claude MCP also exposes:
 Set exactly one of:
 
 ```text
-KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/config/workflows/product.json
+KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/workflows/default.yaml
 ```
 
 or:
@@ -712,7 +712,7 @@ required evidence, attempt limits, and optional peer policies.
 Validate before restart:
 
 ```powershell
-kxm gate validate --file .kxm/config/workflows/product.json
+kxm gate validate --file .kxm/workflows/default.yaml
 ```
 
 Secrets belong in environment variables named by `secretEnv` and
@@ -921,7 +921,7 @@ with content hashes. See `docs/skills.md` for the full lifecycle.
 
 ### Reference /fix workflow
 
-`.kxm/config/workflows/fix.json` implements the reference bug-fix flow:
+`.kxm/workflows/default.yaml` implements the reference bug-fix flow:
 read-only exploration, a tests-only reproduction draft, independent two-critic
 `repro-review` that captures the immutable oracle (a sibling API is invalid),
 plan review by independent critics, a human approval gate, bounded rework

package/docs/operations.md

@@ -21,10 +21,34 @@ These operator commands assume the packed release CLI installation from
 [Getting started](getting-started.md#install-the-operator-command). From a
 source clone, use `npm run hub` instead.
 
+When `KXM_AUTH_TOKEN` is not set, `kxm hub start` loads the persisted hub
+credential file (schema `kxm.hub-env.v1`) under the user state root
+(`~/.local/state/kxm/hub-env.json` on Linux, honoring `KXM_STATE_HOME` and
+platform equivalents). If no persisted token exists, a long random
+administrative token is generated, saved there with `0600` permissions, and
+used. The hub therefore never silently starts with `auth=none` because a
+token was forgotten; a missing token is created once and reused by every
+later restart, worker, and dashboard on the same machine. Explicit
+`KXM_AUTH_TOKEN` / `KXM_PROJECT_TOKENS` environment values always win and are
+persisted so restarts keep them. The generated value is never printed in
+full; kxm only reports which file it came from.
+
 Stop with `Ctrl+C` or `SIGTERM`. The hub stops accepting connections, closes SSE streams, waits for active HTTP connections, and closes SQLite.
 
 For unattended service, use a supervisor that sets a stable working directory, injects secrets, captures stdout, restarts after failure, and allows at least five seconds for graceful shutdown.
 
+### PID claims and restart recovery
+
+The hub wrapper records its own PID and the server child PID in
+`.kxm/state/hub.pid`. A claim whose wrapper is dead is reclaimed automatically
+on the next `kxm hub start`; when the dead wrapper left an orphaned server
+child behind (for example after `SIGKILL` or a machine crash), the new
+wrapper terminates that orphan before reclaiming. `kxm hub stop` also
+recovers orphans directly: it signals a still-running recorded server child
+of a dead wrapper, waits for exit, and removes the stale claim. Malformed or
+foreign PID claims stay fail-closed; remove those only after verifying no
+hub process is running.
+
 Run each long-lived coordinator with `kxm agent worker --name <stable-name> --project <project> [--model <provider/model>] [--fallback-models <provider/model,...>] [--tools <name,...>]` under a separate service-manager unit. Use distinct worktrees for concurrent writers, explicit CPU and memory limits, and restart throttling outside the built-in bounded backoff. Enforce role ownership with the Pi tool allowlist: omit `bash`, `edit`, and `write` from read-only reviewers, even if their prompt also says not to edit. The worker launches Pi RPC mode and retains the most recent session unless configured otherwise. Use `--fresh-start` for a clean first session that may still resume after a later provider failure; reserve `--no-continue` for a worker that must never resume. For release verification, configure the [exact extension and skill sets](configuration.md#long-lived-worker-settings), including every required provider extension; configured categories disable discovery and fail closed on invalid paths. `kxm hub stop` writes a generation-matched control request; the worker asks Pi RPC to abort, waits for confirmation and state flush, and only force-stops the process tree after the bounded drain deadline. A final provider error leaves the inbound hub message delivered, gracefully restarts Pi, rotates to an unused fallback model, and preserves the session; Pi's own automatic retries always finish first. A tool that exceeds `KXM_WORKER_TOOL_TIMEOUT_MS` follows the same durable restart path without changing models. If `--continue` reports an invalid tool-result session, the worker retries once fresh, journals a redacted recovery envelope, and injects a bounded resume instruction for the durable run and stage. Do not copy `pi-agent-*.log` into journals or retrospectives.
 
 ### Workflow-specific Pi sessions