fix(agents-server): release pull-wake claim row even when in-memory token is missing

.changeset/desktop-default-pull-wake-principal.md

@@ -0,0 +1,5 @@
+---
+'@electric-ax/agents-desktop': patch
+---
+
+Align the default pull-wake `owner_principal` in agents-desktop with the agents-server dev fallback (`system:dev-local`), so connecting to a local server without auth no longer fails with `owner_principal must match the authenticated principal`.

.changeset/harden-pull-wake-runner.md

@@ -0,0 +1,7 @@
+---
+'@electric-ax/agents-runtime': patch
+'@electric-ax/agents-server': patch
+'@electric-ax/agents': patch
+---
+
+Harden pull-wake runner lifecycle with a state machine, concurrent claim limits (`maxConcurrentClaims`), and exponential reconnect backoff (1s–30s). Add granular `status` field to `PullWakeRunnerHealth` (`stopped | starting | connecting | streaming | reconnecting | stopping`). The `onError` callback is now reporting-only (`(Error) => void`) — it can no longer control runner lifecycle. `stop()` rethrows `drainWakes` errors so callers observe wake handler failures. Event-driven heartbeat throttling avoids stale diagnostics between fixed-interval heartbeats.

.changeset/pull-wake-health-diagnostics.md

@@ -0,0 +1,9 @@
+---
+'@electric-ax/agents-server': patch
+'@electric-ax/agents-runtime': patch
+'@electric-ax/agents-desktop': patch
+'@electric-ax/agents': patch
+'electric-ax': patch
+---
+
+Add pull-wake runner health check endpoint and rename `owner_user_id` to `owner_principal` across the runners system. The `GET /_electric/runners/:id/health` endpoint returns comprehensive diagnostics including runner state, client-reported stream/heartbeat/claim metrics, active claims, and dispatch stats with a derived health status (healthy/degraded/unhealthy). The `PullWakeRunner` now tracks internal diagnostics and reports them to the server via heartbeats, stored in a new `diagnostics` JSONB column on the runners table. The `owner_user_id` → `owner_principal` rename stores canonical principal URLs instead of keys, with strict validation via `principalKeyFromUrl()`. This is a breaking change with no backward compatibility — all callers must send principal URLs.

.changeset/pull-wake-session-startup-ui.md

@@ -0,0 +1,5 @@
+---
+'@electric-ax/agents-server-ui': patch
+---
+
+Send new-session initial messages through the spawn request so pull-wake sessions can start without waiting for the UI to preload the entity stream.

.changeset/release-pull-wake-claim-after-dispatch.md

@@ -0,0 +1,5 @@
+---
+'@electric-ax/agents-server': patch
+---
+
+Fix pull-wake claims leaking in `consumer_claims` after dispatch. The release path in `callback-forward` was gated entirely on the in-memory write-token state, so any condition that lost or evicted the token (server restart, a newer wake on the same stream) would prevent `materializeReleasedClaim` from running and leave the DB row pinned at `status='active'`. The fix decouples the durable-row release (keyed by `consumerId + epoch`) from in-memory token cleanup, and uses `entityCleared || stillOwnsClaim` to gate the entity status transition back to `idle`. Includes regression tests in `test/webhook-forward-routing.test.ts`.

docs/agents-principals-implementation-plan.md

@@ -82,7 +82,8 @@ Helpers:
 ```ts
 export function parsePrincipalKey(input: string): Principal
 export function principalUrl(key: string): string
-export function principalKeyFromUrl(url: string): string | null
+export function parsePrincipalUrl(url: string): Principal | null
+export function isPrincipalUrl(url: string): boolean
 export function getPrincipalFromRequest(request: Request): Principal | null
 export function getDevPrincipal(): Principal
 ```
@@ -575,7 +576,7 @@ entity: {
 principal: entity.created_by
   ? {
       url: entity.created_by,
-      key: principalKeyFromUrl(entity.created_by),
+      key: parsePrincipalUrl(entity.created_by)?.key ?? null,
     }
   : undefined,
 ```

packages/agents-desktop/README.md

@@ -18,12 +18,12 @@ This starts both the UI dev server (with HMR) and the Electron main process.
 
 ### Environment variables
 
-| Variable                                     | Default            | Description                                                                                                                                               |
-| -------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ELECTRIC_DESKTOP_PRINCIPAL`                 | _(none)_           | Sets the `electric-principal` header on all requests to the agents-server. Use `system:dev-local` for local development without auth.                     |
-| `ELECTRIC_DESKTOP_PULL_WAKE_OWNER_USER_ID`   | `local-desktop`    | Override the `owner_user_id` used when registering the pull-wake runner. When `ELECTRIC_DESKTOP_PRINCIPAL` is set, this is derived from it automatically. |
-| `ELECTRIC_DESKTOP_PULL_WAKE_RUNNER_ID`       | _(auto-generated)_ | Fixed runner ID for the pull-wake runner.                                                                                                                 |
-| `ELECTRIC_DESKTOP_PULL_WAKE_REGISTER_RUNNER` | `true`             | Set to `false` to skip runner registration (runner must already exist on the server).                                                                     |
+| Variable                                     | Default                         | Description                                                                                                                                                 |
+| -------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ELECTRIC_DESKTOP_PRINCIPAL`                 | _(none)_                        | Sets the `electric-principal` header on all requests to the agents-server. Use `system:dev-local` for local development without auth.                       |
+| `ELECTRIC_DESKTOP_PULL_WAKE_OWNER_PRINCIPAL` | `/principal/system%3Adev-local` | Override the `owner_principal` used when registering the pull-wake runner. When `ELECTRIC_DESKTOP_PRINCIPAL` is set, this is derived from it automatically. |
+| `ELECTRIC_DESKTOP_PULL_WAKE_RUNNER_ID`       | _(auto-generated)_              | Fixed runner ID for the pull-wake runner.                                                                                                                   |
+| `ELECTRIC_DESKTOP_PULL_WAKE_REGISTER_RUNNER` | `true`                          | Set to `false` to skip runner registration (runner must already exist on the server).                                                                       |
 
 ### Settings
 

packages/agents-desktop/src/main.ts

@@ -224,9 +224,9 @@ const PULL_WAKE_REGISTER_RUNNER =
     : [`1`, `true`].includes(
         process.env.ELECTRIC_DESKTOP_PULL_WAKE_REGISTER_RUNNER.trim().toLowerCase()
       )
-const PULL_WAKE_OWNER_USER_ID =
-  process.env.ELECTRIC_DESKTOP_PULL_WAKE_OWNER_USER_ID?.trim() ||
-  `local-desktop`
+const PULL_WAKE_OWNER_PRINCIPAL =
+  process.env.ELECTRIC_DESKTOP_PULL_WAKE_OWNER_PRINCIPAL?.trim() ||
+  `/principal/system%3Adev-local`
 const DEV_PRINCIPAL = ((): string | null => {
   const raw = process.env.ELECTRIC_DESKTOP_PRINCIPAL?.trim() || null
   if (!raw) return null
@@ -262,15 +262,18 @@ function hasHeader(
   return headers ? new Headers(headers).has(name) : false
 }
 
-function runnerOwnerUserIdFromHeaders(
+function runnerOwnerPrincipalFromHeaders(
   headers: Record<string, string> | undefined
-): string {
+): string | undefined {
   const normalized = new Headers(headers)
-  return (
-    normalized.get(`authorization`)?.trim() ||
-    normalized.get(ELECTRIC_PRINCIPAL_HEADER)?.trim() ||
-    PULL_WAKE_OWNER_USER_ID
-  )
+  const principalKey = normalized.get(ELECTRIC_PRINCIPAL_HEADER)?.trim()
+  if (principalKey) {
+    return principalKey.startsWith(`/principal/`)
+      ? principalKey
+      : `/principal/${encodeURIComponent(principalKey)}`
+  }
+  if (normalized.has(`authorization`)) return undefined
+  return PULL_WAKE_OWNER_PRINCIPAL
 }
 
 /**
@@ -1541,14 +1544,14 @@ async function startRuntime(serverId: string): Promise<void> {
 
   const serverWithPrincipal = injectDevPrincipalHeaders(activeServer)
   const runtimeHeaders = mergeHeaders(serverWithPrincipal.headers)
-  const runnerOwnerUserId = runnerOwnerUserIdFromHeaders(runtimeHeaders)
+  const runnerOwnerPrincipal = runnerOwnerPrincipalFromHeaders(runtimeHeaders)
   console.info(
     `[agents-desktop] Starting built-in agents runtime for server ${activeServer.url}`
   )
   console.info(`[agents-desktop] Pull-wake runner id: ${runnerId}`)
   if (PULL_WAKE_REGISTER_RUNNER) {
     console.info(
-      `[agents-desktop] Pull-wake runner registration enabled; owner user id: ${runnerOwnerUserId}`
+      `[agents-desktop] Pull-wake runner registration enabled; owner principal: ${runnerOwnerPrincipal ?? `(derived from auth)`}`
     )
   } else {
     console.info(
@@ -1572,7 +1575,9 @@ async function startRuntime(serverId: string): Promise<void> {
     pullWake: {
       runnerId,
       registerRunner: PULL_WAKE_REGISTER_RUNNER,
-      ownerUserId: PULL_WAKE_REGISTER_RUNNER ? runnerOwnerUserId : undefined,
+      ownerPrincipal: PULL_WAKE_REGISTER_RUNNER
+        ? runnerOwnerPrincipal
+        : undefined,
       label: `Electric Agents Desktop`,
       headers: runtimeHeaders,
       claimHeaders: runtimeHeaders,

packages/agents-runtime/src/create-handler.ts

@@ -4,7 +4,7 @@
  */
 
 import { zodToJsonSchema } from 'zod-to-json-schema'
-import { processWebhookWake } from './process-wake'
+import { processWake } from './process-wake'
 import { getEntityType, listEntityTypes } from './define-entity'
 import { DEFAULT_OUTPUT_SCHEMAS } from './default-output-schemas'
 import { passthrough } from './entity-schema'
@@ -118,13 +118,11 @@ export interface RuntimeRouter {
     options?: Pick<ProcessWakeConfig, `claimHeaders` | `claimTokenHeader`>
   ) => void
 
-  /**
-   * Dispatch an already-parsed webhook wake notification.
-   */
+  /** Dispatch an already-parsed webhook wake notification. */
   dispatchWebhookWake: (notification: WebhookNotification) => void
 
   /**
-   * Wait for all in-flight webhook wake handlers to settle.
+   * Wait for all in-flight wake handlers to settle.
    * Throws any wake errors instead of hiding them behind logs.
    */
   drainWakes: () => Promise<void>
@@ -240,7 +238,7 @@ export function createRuntimeRouter(
     const wakeLabel = notification.entity?.url ?? notification.streamPath
     const controller = new AbortController()
     const wake: Promise<void> = Promise.resolve(
-      processWebhookWake(notification, {
+      processWake(notification, {
         ...wakeConfig,
         ...options,
         shutdownSignal: controller.signal,

packages/agents-runtime/src/index.ts

@@ -205,7 +205,7 @@ export type {
   TaggedQuery,
 } from './observation-sources'
 
-export { processWake, processWebhookWake } from './process-wake'
+export { processWake } from './process-wake'
 export type { ProcessWakeConfig } from './types'
 
 export { DEFAULT_OUTPUT_SCHEMAS } from './default-output-schemas'
@@ -239,6 +239,8 @@ export type {
   PullWakeEvent,
   PullWakeRunner,
   PullWakeRunnerConfig,
+  PullWakeRunnerHealth,
+  PullWakeRunnerStatus,
   PullWakeStreamResponse,
 } from './pull-wake-runner'
 

packages/agents-runtime/src/process-wake.ts

@@ -297,7 +297,7 @@ function createInFlightTracker() {
   }
 }
 
-export async function processWebhookWake(
+export async function processWake(
   notification: WebhookNotification,
   config: ProcessWakeConfig
 ): Promise<WakeResult | null> {
@@ -1820,8 +1820,6 @@ export async function processWebhookWake(
   return result
 }
 
-export const processWake: typeof processWebhookWake = processWebhookWake
-
 async function sendDone(
   callback: string,
   token: string,