@huynle/hub 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.7.4
+
+Release downloads move to a public repository. The source repository is private now, so the standalone `hub`
+binaries, `hubctl`, its signed manifest and the checksums are published to
+[`huynle/hub-releases`](https://github.com/huynle/hub-releases) (the release workflow mirrors every release there,
+byte for byte, so the signed manifest and checksums stay valid). The image `ghcr.io/huynle/hub` and the npm package
+`@huynle/hub` are unchanged.
+
+- **Install**: the README, the Ansible role README and the web shell hint use `huynle/hub-releases`; pass
+  `--release-url https://github.com/huynle/hub-releases/releases/download/v<version>` to `hubctl setup ansible`.
+- **Plugin rename notice** no longer suggests installing from `github:huynle/hub`.
+
+## 0.7.3
+
+Session errors are visible: a quota, auth or rate-limit error in an OpenCode session now shows up in the hub.
+
+- **Retries with OpenCode 2.2**: OpenCode 2.2 no longer sends `session.status`; the plugin translates
+  `session.retry.scheduled` into a `session.status` retry with `next` (time of the next try), `errorType` and
+  `errorStatus`, so older hubs keep working. `session.execution.failed` errors go out as `{message, type, status}` (no
+  provider response body). A pending retry and the last failure are re-sent after a reconnect.
+- **Console**: an alert banner in the session header ("Quota exceeded (HTTP 429): …"), error and retry rows in the
+  transcript (with a live countdown), a "!" badge in session lists; a failed session is listed under Needs you until
+  it runs again or is archived.
+- **Where a session runs**: the session header names machine · project › folder · git branch (a line under the
+  header on phones).
+- **Notifications**: new `providerError` ("Model provider error", on by default) for quota, billing, auth, no-route
+  and unknown provider errors in any session of the tree, once per session per run. Devices with it off still get
+  `failed`. A root's and a subagent's notifications no longer replace each other on the phone.
+
 ## 0.7.2
 
 First release with signed standalone `hubctl` binaries (`hubctl-<target>`, `hubctl-manifest.json` signed by `hub-release-1`, `HUBCTL_SHA256SUMS`) and pinned OpenCode 2.2.0 for `hubctl setup`.

package/README.md

@@ -145,8 +145,8 @@ shell, and the hub never gets a way to run commands here.
 # 1. Download hubctl for your platform (darwin-arm64, darwin-x64, linux-x64, linux-arm64) and the signed manifest
 #    from the release, then install the binary yourself (the first apply installs the release's copy as
 #    ~/.local/bin/hubctl, with `hub` linked to it):
-curl -fsSLo hubctl https://github.com/huynle/hub/releases/download/v<version>/hubctl-darwin-arm64 && chmod +x hubctl
-curl -fsSLO https://github.com/huynle/hub/releases/download/v<version>/hubctl-manifest.json
+curl -fsSLo hubctl https://github.com/huynle/hub-releases/releases/download/v<version>/hubctl-darwin-arm64 && chmod +x hubctl
+curl -fsSLO https://github.com/huynle/hub-releases/releases/download/v<version>/hubctl-manifest.json
 
 # 2. Enroll this machine (device code: approve it on the hub; Ctrl-C cancels). One identity for every spoke here.
 ./hubctl machine enroll --server https://hub.example.com
@@ -209,7 +209,7 @@ The hub serves the web app, pairs devices, enrolls machines, and does push and (
 | Way | For | How |
 |---|---|---|
 | **`/hub` → On this computer** | Local use; nothing to install (plugin from npm) | started by the plugin with OpenCode's own runtime (`BUN_BE_BUN=1 opencode bin/hub.ts`), or `bun` when installed |
-| **Standalone binary** | Any server or laptop, no runtime needed | `hub-<os>-<arch>` from the [releases](https://github.com/huynle/hub/releases) |
+| **Standalone binary** | Any server or laptop, no runtime needed | `hub-<os>-<arch>` from the [releases](https://github.com/huynle/hub-releases/releases) (the source repository is private; releases are mirrored to the public `huynle/hub-releases`) |
 | **Docker** | Servers | `ghcr.io/huynle/hub` (linux/amd64, linux/arm64) |
 | **bunx / from source** | Bun users, development | `bunx --package @huynle/hub hub-server` · `bun bin/hub.ts` |
 | **Kubernetes (cluster mode)** | Several pods on Postgres + Valkey, rolling updates | [docs/cluster.md](docs/cluster.md), manifests in [`deploy/k8s/`](deploy/k8s/) |
@@ -221,8 +221,8 @@ answers `--help` and `--version`. While no device is paired, the hub logs a pair
 `hub-<darwin|linux>-<arm64|x64>` and `hub-windows-x64.exe`, plus `SHA256SUMS`.
 
 ```sh
-curl -LO https://github.com/huynle/hub/releases/latest/download/hub-linux-x64
-curl -LO https://github.com/huynle/hub/releases/latest/download/SHA256SUMS
+curl -LO https://github.com/huynle/hub-releases/releases/latest/download/hub-linux-x64
+curl -LO https://github.com/huynle/hub-releases/releases/latest/download/SHA256SUMS
 sha256sum --check --ignore-missing SHA256SUMS && chmod +x hub-linux-x64
 HUB_PUBLIC_URL=https://hub.example.com ./hub-linux-x64
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Hub: a harness-agnostic central hub your AI agent harnesses connect to (OpenCode first). Follow, steer and stop sessions from your phone or browser, with notifications, optional hands-free Voice and a self-hostable server.",
   "license": "MIT",
   "author": "Huy Le",

package/packages/claude-code/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-claude-code",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/dist/hub-cli.js

@@ -7,7 +7,7 @@ import { createInterface } from "readline";
 // packages/cli/package.json
 var package_default = {
   name: "@huynle/hub-cli",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   license: "MIT",
@@ -3292,7 +3292,7 @@ var FORWARDED_EVENTS = new Set([
   "pty.deleted",
   "session.seed"
 ]);
-var COMPACTED_EVENTS = new Set(["session.tool.progress"]);
+var COMPACTED_EVENTS = new Set(["session.tool.progress", "session.retry.scheduled"]);
 var HARNESS_OPENCODE = "opencode";
 var EVIDENCE_LEVELS = ["native", "hooks", "rpc", "screen"];
 var IMPLIED_OPENCODE_FEATURES = [
@@ -5919,7 +5919,7 @@ import { arch as osArch, platform as osPlatform } from "node:os";
 // packages/node/package.json
 var package_default2 = {
   name: "@huynle/hub-node",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -7010,7 +7010,7 @@ import path10 from "node:path";
 // packages/runtime-openshell/package.json
 var package_default3 = {
   name: "@huynle/hub-runtime-openshell",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -10395,7 +10395,7 @@ import path18 from "node:path";
 // packages/claude-code/package.json
 var package_default4 = {
   name: "@huynle/hub-claude-code",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "The Claude Code hooks spoke: per-user daemon, hook bridge, plugin dir, `hub claude` wrapper and daemon-backed MCP server (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -10684,7 +10684,7 @@ import path21 from "node:path";
 // packages/preset/package.json
 var package_default5 = {
   name: "@huynle/hub-preset",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",
@@ -11185,7 +11185,7 @@ import { openSync as openSync4, closeSync as closeSync4, readFileSync as readFil
 // packages/codex/package.json
 var package_default6 = {
   name: "@huynle/hub-codex",
-  version: "0.7.2",
+  version: "0.7.4",
   private: true,
   description: "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   license: "MIT",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/harness-events.ts

@@ -74,10 +74,10 @@ export interface HarnessEventData {
   /** A turn started (the session is busy). `turnID`: the harness's turn, when it has one. */
   "session.execution.started": Turn
   "session.execution.succeeded": Turn
-  "session.execution.failed": Turn & { readonly error?: { readonly message: string } }
+  "session.execution.failed": Turn & { readonly error?: { readonly message: string; readonly type?: string; readonly status?: number } }
   /** `inferred`: the harness reported no interruption; the spoke found it later (see the header). */
   "session.execution.interrupted": Turn & { readonly inferred?: true }
-  "session.status": { readonly sessionID: string; readonly status: { readonly type: "idle" | "busy" } | { readonly type: "retry"; readonly attempt?: number; readonly message?: string } }
+  "session.status": { readonly sessionID: string; readonly status: { readonly type: "idle" | "busy" } | { readonly type: "retry"; readonly attempt?: number; readonly message?: string; readonly next?: number; readonly errorType?: string; readonly errorStatus?: number } }
   /** The turn's reply (e.g. Claude Code's Stop last_assistant_message); `ordinal` counts replies in the message. */
   "session.text.ended": { readonly sessionID: string; readonly assistantMessageID: string; readonly ordinal: number; readonly text: string }
   /** A prompt entered the session: typed by the user, or a message the hub delivered. */

package/packages/protocol/src/index.ts

@@ -91,7 +91,7 @@ export interface TimelinePage {
 }
 
 /** Timeline row kinds. "message": a hub message (src/spoke/timeline.ts has the others). */
-export const TIMELINE_KINDS = ["user", "assistant", "reasoning", "tool", "message"] as const
+export const TIMELINE_KINDS = ["user", "assistant", "reasoning", "tool", "message", "error", "retry"] as const
 export type TimelineKind = (typeof TIMELINE_KINDS)[number]
 
 /** A message row's direction from the session's point of view: delivered to it (in) or sent by it (out). */
@@ -230,15 +230,21 @@ export interface InboxDeliveredData {
 }
 
 /**
- * OpenCode events the spoke forwards only in another (compact) form: a subagent tool's progress, which names the
- * child session, goes out as a `session.tool.called` with `childSessionID` (a type every hub accepts).
+ * OpenCode events the spoke forwards only in another (compact) form, as a type every hub accepts: a subagent tool's
+ * progress, which names the child session, goes out as a `session.tool.called` with `childSessionID`; a scheduled
+ * retry (OpenCode 2.2 publishes no session.status) goes out as a `session.status` of type retry. Never add these to
+ * FORWARDED_EVENTS: older hubs close the connection on an event type they do not know.
  */
-export const COMPACTED_EVENTS: ReadonlySet<string> = new Set(["session.tool.progress"])
+export const COMPACTED_EVENTS: ReadonlySet<string> = new Set(["session.tool.progress", "session.retry.scheduled"])
 
 /** Longest job command forwarded. */
 export const JOB_COMMAND_MAX = 200
 /** Longest retry reason forwarded. */
 export const RETRY_MESSAGE_MAX = 200
+/** Longest run error message forwarded (session.execution.failed; as HARNESS_ERROR_MAX). */
+export const ERROR_MESSAGE_MAX = 1000
+/** Longest error type forwarded (e.g. "provider.quota"). */
+export const ERROR_TYPE_MAX = 64
 /** Most running jobs one seed event carries. */
 export const SEED_JOBS_MAX = 20
 
@@ -258,7 +264,27 @@ export interface JobInfo {
 }
 
 /** OpenCode's session status, compact. */
-export type CompactSessionStatus = { readonly type: "idle" | "busy" } | { readonly type: "retry"; readonly attempt?: number; readonly message?: string }
+export type CompactSessionStatus =
+  | { readonly type: "idle" | "busy" }
+  | {
+      readonly type: "retry"
+      readonly attempt?: number
+      /** Why it retries (the error's message, ≤ RETRY_MESSAGE_MAX). */
+      readonly message?: string
+      /** When the next attempt runs (epoch ms). */
+      readonly next?: number
+      /** The error's type, e.g. "provider.rate-limit" (≤ ERROR_TYPE_MAX). */
+      readonly errorType?: string
+      /** The error's HTTP status (100–599). */
+      readonly errorStatus?: number
+    }
+
+/** A run's error as forwarded (session.execution.failed, and a seed's last failure): no response body. */
+export interface CompactRunError {
+  readonly message: string
+  readonly type?: string
+  readonly status?: number
+}
 
 // ---------- spoke → server ----------
 
@@ -1097,6 +1123,7 @@ export function summarizeToolInput(input: unknown): string {
 export function compactActivity(event: ForwardedEvent, sessionOf?: (jobID: string) => string | undefined, now: number = Date.now()): ForwardedEvent | undefined {
   const d = event.data
   if (JOB_EVENTS.has(event.type) || event.type === "session.status") return compactJob(event, sessionOf, now)
+  if (event.type === "session.retry.scheduled") return compactRetry(d)
   const base = { sessionID: d.sessionID, assistantMessageID: d.assistantMessageID, id: d.id }
   switch (event.type) {
     case "session.tool.input.started":
@@ -1115,6 +1142,11 @@ export function compactActivity(event: ForwardedEvent, sessionOf?: (jobID: strin
       const message = typeof (d.error as any)?.message === "string" ? String((d.error as any).message).slice(0, ACTIVITY_SUMMARY_MAX) : "failed"
       return { type: event.type, data: { ...base, error: message } }
     }
+    case "session.execution.failed":
+      return {
+        type: event.type,
+        data: { sessionID: d.sessionID, ...(typeof d.turnID === "string" && d.turnID ? { turnID: d.turnID } : {}), error: compactRunError(d.error) ?? { message: "failed" } },
+      }
     case "session.reasoning.started":
     case "session.reasoning.ended":
       return { type: event.type, data: { sessionID: d.sessionID, assistantMessageID: d.assistantMessageID } }
@@ -1146,7 +1178,10 @@ function clipText(value: unknown, max: number): string | undefined {
 
 const finite = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
 
-/** OpenCode's SessionStatus reduced to its type and (retry) attempt and short reason. */
+const errorType = (v: unknown): string | undefined => (typeof v === "string" && v.length > 0 && v.length <= ERROR_TYPE_MAX ? v : undefined)
+const httpStatus = (v: unknown): number | undefined => (Number.isInteger(v) && (v as number) >= 100 && (v as number) <= 599 ? (v as number) : undefined)
+
+/** OpenCode's SessionStatus reduced to its type and (retry) attempt, short reason, next try and error kind. */
 export function compactStatus(raw: unknown): CompactSessionStatus | undefined {
   const status = raw as Record<string, unknown> | null
   if (!status || typeof status !== "object") return undefined
@@ -1154,7 +1189,35 @@ export function compactStatus(raw: unknown): CompactSessionStatus | undefined {
   if (status.type !== "retry") return undefined
   const attempt = finite(status.attempt)
   const message = clipText(status.message, RETRY_MESSAGE_MAX)
-  return { type: "retry", ...(attempt !== undefined ? { attempt } : {}), ...(message ? { message } : {}) }
+  const next = finite(status.next)
+  const type = errorType(status.errorType)
+  const code = httpStatus(status.errorStatus)
+  return {
+    type: "retry",
+    ...(attempt !== undefined ? { attempt } : {}),
+    ...(message ? { message } : {}),
+    ...(next !== undefined ? { next } : {}),
+    ...(type ? { errorType: type } : {}),
+    ...(code !== undefined ? { errorStatus: code } : {}),
+  }
+}
+
+/** An OpenCode run error ({type, message, status?, response?, retryAfterMs?}) as its message, type and status only. */
+export function compactRunError(raw: unknown): CompactRunError | undefined {
+  const error = raw as Record<string, unknown> | null
+  if (!error || typeof error !== "object") return undefined
+  const message = typeof error.message === "string" && error.message.trim() ? error.message.trim().slice(0, ERROR_MESSAGE_MAX) : "failed"
+  const type = errorType(error.type)
+  const status = httpStatus(error.status)
+  return { message, ...(type ? { type } : {}), ...(status !== undefined ? { status } : {}) }
+}
+
+/** OpenCode 2.2's session.retry.scheduled as the session.status retry every hub accepts. */
+function compactRetry(d: Record<string, unknown>): ForwardedEvent | undefined {
+  if (typeof d.sessionID !== "string" || !d.sessionID) return undefined
+  const error = (d.error && typeof d.error === "object" ? d.error : {}) as Record<string, unknown>
+  const status = compactStatus({ type: "retry", attempt: d.attempt, message: error.message, next: d.at, errorType: error.type, errorStatus: error.status })
+  return { type: "session.status", data: { sessionID: d.sessionID, status } }
 }
 
 /** A ShellInfo or Pty (OpenCode) as a JobInfo. */

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/http.ts

@@ -251,7 +251,7 @@ const WEB_NOT_BUILT = [
   "This hub has no built web app (web/dist).",
   "",
   "To run a hub, install it from npm (`opencode plugin add @huynle/hub`, or `bunx --package @huynle/hub hub-server`)",
-  "or use a release binary (https://github.com/huynle/hub/releases), which ship the web app.",
+  "or use a release binary (https://github.com/huynle/hub-releases/releases), which ship the web app.",
   "In a source checkout, run `npm install && npm run build:web` first.",
 ].join("\n")
 /** Preview text for POST /api/settings/speech/test. */
@@ -541,6 +541,7 @@ export function startCentral(options: CentralOptions): Central {
       ...(alert.requestID ? { requestID: alert.requestID } : {}),
       ...(alert.subject ? { subject: alert.subject } : {}),
       ...(alert.key ? { key: alert.key } : {}),
+      ...(alert.unlessPref ? { unlessPref: alert.unlessPref } : {}),
     }
     notifier.notify(alert.kind, alert.sessionID, alert.title, alert.text, alert.owner, extra).catch((cause) => {
       console.error("[hub] push notification failed:", cause instanceof Error ? cause.message : cause)

package/src/central/push.ts

@@ -32,6 +32,7 @@ export const NOTIFICATION_LABELS: Readonly<Record<NotificationKind, string>> = O
   activity: "Activity",
   decision: "Decision",
   message: "Message",
+  providerError: "Model provider error",
 })
 
 /** True for a known notification kind (API input). */
@@ -47,6 +48,8 @@ export interface PushExtra {
   readonly key?: string
   /** decision: the Decision, so a tap opens its card. */
   readonly decisionID?: string
+  /** Skip devices that have this kind on (they were notified through it instead). Not sent. */
+  readonly unlessPref?: NotificationKind
 }
 
 export interface PushPayload {
@@ -58,6 +61,8 @@ export interface PushPayload {
   readonly decisionID?: string
   /** A test notification shaped like `kind`. */
   readonly test?: true
+  /** Per-session kinds (providerError, subagentFailed): the session it is about, so the service worker tags each apart. */
+  readonly tagKey?: string
 }
 
 const minutes = (clock: string): number => Number(clock.slice(0, 2)) * 60 + Number(clock.slice(3, 5))
@@ -188,6 +193,8 @@ function kindTitle(kind: NotificationKind, subject: string | undefined): string
 }
 
 const OPEN = "Tap to open the session."
+/** A session ID: the only key a payload may carry (job and tool IDs stay on the hub). */
+const SESSION_ID = /^ses_[A-Za-z0-9]{1,64}$/
 
 export function pushPayload(kind: NotificationKind, sessionID: string, sessionTitle: string, text?: string, extra: PushExtra = {}): PushPayload {
   const name = shorten(sessionTitle)
@@ -213,6 +220,9 @@ export function pushPayload(kind: NotificationKind, sessionID: string, sessionTi
       return { kind, sessionID, title, body: detail || "Nothing is running or waiting. Tap to open." }
     case "activity":
       return { kind, sessionID, title, body: detail || "New activity." }
+    case "providerError":
+    case "subagentFailed":
+      return { kind, sessionID, title, body: detail || OPEN, ...(extra.key && SESSION_ID.test(extra.key) ? { tagKey: extra.key } : {}) }
     default:
       return { kind, sessionID, title, body: detail || OPEN }
   }
@@ -229,6 +239,7 @@ export function sendOptionsFor(kind: NotificationKind | "test"): { TTL: number;
     case "failed":
     case "decision":
     case "message":
+    case "providerError":
       return { TTL: URGENT_TTL_SECONDS, urgency: "high" }
     case "done":
     case "stopped":
@@ -385,7 +396,9 @@ export class Push {
     const targets = this.store.pushSubscriptions().filter((s) => {
       const owner = owners.get(s.deviceID)
       if (ownerID !== undefined && owner !== ownerID) return false
-      if (!this.store.pushPrefs(s.deviceID)[precise]) return false
+      const prefs = this.store.pushPrefs(s.deviceID)
+      if (!prefs[precise]) return false
+      if (extra?.unlessPref && prefs[extra.unlessPref]) return false
       if (precise === "handoff") return true
       const quiet = this.store.quietHours(s.deviceID)
       return !isMuted(owner) && !(quiet && inQuietHours(quiet, at))

package/src/central/registry.ts

@@ -12,7 +12,7 @@
 // holds the connection; remote state is never re-exported.
 import path from "node:path"
 import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
-import { StatusBoard, permissionRequest, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
+import { StatusBoard, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
 import { sanitizeLabel } from "./agent/envelope"
 import { DoneWatch } from "./done"
 import { SentenceStream } from "./say-stream"
@@ -150,6 +150,8 @@ export interface Alert {
   /** Tenant (user ID) that owns the session; push goes to this user's devices only. */
   readonly owner?: string
   readonly step?: ActivityStep
+  /** Skip devices that have this kind on (they were told through it instead). */
+  readonly unlessPref?: NotificationKind
 }
 
 /** Notifications that reach a session even while some device shows it. */
@@ -407,6 +409,8 @@ export class Registry {
   private readonly forms = new Map<string, { connIDs: string[]; sessionID: string }>()
   /** Form IDs already alerted (forms may be forwarded by several processes). */
   private readonly alertedForms = new Set<string>()
+  /** Sessions whose current run raised a providerError notification (once per run; cleared when a run starts). */
+  private readonly providerAlerted = new Set<string>()
   /** Sessions in conversation mode → the connection last told so (re-sent when another one takes over). */
   private readonly conversations = new Map<string, string | undefined>()
   /** `messageID ordinal` of texts already sent as say events (several processes forward the same text). */
@@ -1433,15 +1437,27 @@ export class Registry {
     if (!rootID) return
     const root = rootID === sessionID
     const wasRunning = before?.state === "working" || before?.state === "blocked"
-    if (type === "session.execution.started") return this.doneWatch.started(rootID, root)
+    if (type === "session.execution.started") {
+      this.providerAlerted.delete(sessionID)
+      return this.doneWatch.started(rootID, root)
+    }
     if (type === "session.text.delta" || type === "session.reasoning.delta") return
     const ended = type === "session.execution.succeeded" ? "succeeded" : type === "session.execution.failed" ? "failed" : type === "session.execution.interrupted" ? "interrupted" : undefined
     const reason = (data.error as { message?: unknown } | undefined)?.message
     const error = typeof reason === "string" && reason.trim() ? reason : undefined
+    const errorType = (data.error as { type?: unknown } | undefined)?.type
+    // A provider error the user must act on replaces the root's "failed" (raised once per run).
+    const providerFailure = ended === "failed" && typeof errorType === "string" && providerFailureNeedsUser(errorType)
+    if (providerFailure) this.providerError(rootID, sessionID, error ?? errorTypeLabel(errorType) ?? "Model provider error")
+    if (type === "session.status") {
+      const retry = this.status(rootID)?.find((s) => s.id === sessionID)?.retry
+      if (retry && providerRetryNeedsUser(retry.errorType)) this.providerError(rootID, sessionID, retry.message ?? errorTypeLabel(retry.errorType)!)
+    }
     if (ended && root) {
       this.doneWatch.rootEnded(rootID, ended, wasRunning)
       if (ended === "succeeded" && wasRunning && !this.active.has(rootID)) this.alert("turn", rootID)
-      if (ended === "failed") this.alert("failed", rootID, error ? { text: error } : {})
+      // Devices with providerError on got that instead; the rest still hear about the failure.
+      if (ended === "failed") this.alert("failed", rootID, { ...(error ? { text: error } : {}), ...(providerFailure ? { unlessPref: "providerError" as const } : {}) })
       const stopped = ended === "interrupted" ? STOP_REASONS[String(data.reason)] : undefined
       if (stopped) this.alert("stopped", rootID, { text: stopped })
       return
@@ -1456,7 +1472,10 @@ export class Registry {
     }
     if (type === "session.status" && root && !before?.retry) {
       const retry = this.status(rootID)?.find((s) => s.id === rootID)?.retry
-      if (retry) this.alert("retry", rootID, { text: [retry.attempt !== undefined ? `Attempt ${retry.attempt}` : "", retry.message ?? ""].filter(Boolean).join(": ") || "Retrying" })
+      if (retry) {
+        const why = [retry.attempt !== undefined ? `Attempt ${retry.attempt}` : "", errorTypeLabel(retry.errorType) ?? ""].filter(Boolean).join(" · ")
+        this.alert("retry", rootID, { text: [why, retry.message ?? ""].filter(Boolean).join(": ") || "Retrying" })
+      }
       return
     }
     if (type === "shell.exited" || type === "session.shell.ended" || type === "pty.exited") {
@@ -1469,6 +1488,15 @@ export class Registry {
     }
   }
 
+  /** A model provider error of `sessionID` (root or subagent) needs the user: "<session title>: <message>", once per run. */
+  private providerError(rootID: string, sessionID: string, message: string): void {
+    if (this.providerAlerted.has(sessionID)) return
+    this.providerAlerted.add(sessionID)
+    if (this.providerAlerted.size > 1000) this.providerAlerted.delete(this.providerAlerted.values().next().value!)
+    const title = this.status(rootID)?.find((s) => s.id === sessionID)?.title?.trim() || "Session"
+    this.alert("providerError", rootID, { text: `${title}: ${message}`, key: sessionID })
+  }
+
   /** Fires when a root's tree stayed settled after its run (DoneWatch). */
   private settledTree(rootID: string): boolean {
     const board = this.boards.get(rootID)
@@ -1938,7 +1966,7 @@ export class Registry {
    * Raises a notification for the root of `sessionID`'s tree. Only hand-offs, questions and permissions reach a
    * session some device shows (spoken replies check that themselves: the watching device speaks them).
    */
-  private alert(kind: NotificationKind, sessionID: string, fields: { text?: string; requestID?: string; subject?: string; key?: string } = {}): void {
+  private alert(kind: NotificationKind, sessionID: string, fields: { text?: string; requestID?: string; subject?: string; key?: string; unlessPref?: NotificationKind } = {}): void {
     const entry = [...this.boards].find(([, board]) => board.get(sessionID))
     if (!entry) return
     const [rootID, board] = entry
@@ -1951,6 +1979,7 @@ export class Registry {
       ...(fields.text !== undefined ? { text: fields.text } : {}),
       ...(fields.requestID !== undefined ? { requestID: fields.requestID } : {}),
       ...(fields.key !== undefined ? { key: fields.key } : {}),
+      ...(fields.unlessPref !== undefined ? { unlessPref: fields.unlessPref } : {}),
     }
     const owner = this.sessionTenant(rootID)
     for (const listener of this.alertListeners) listener(owner ? { ...alert, owner } : alert)

package/src/central/store.ts

@@ -121,6 +121,11 @@ export interface PushPrefs {
   decision: boolean
   /** Agent messaging needs you: a message to @me, an ask left unanswered after every re-wake, or a message loop. */
   message: boolean
+  /**
+   * A model provider error needs you: a quota, free-tier, budget, auth or no-route failure of any session in the tree
+   * (once per run), or a retry for a quota, free-tier or auth error. Replaces the root's "failed" for that failure.
+   */
+  providerError: boolean
 }
 
 export const PUSH_PREF_KEYS = [
@@ -141,6 +146,7 @@ export const PUSH_PREF_KEYS = [
   "activity",
   "decision",
   "message",
+  "providerError",
 ] as const satisfies readonly (keyof PushPrefs)[]
 
 /** Defaults: anything that needs you, all done, failed, hand-offs and spoken replies; the finer kinds are opt-in. */
@@ -163,6 +169,7 @@ export const DEFAULT_PUSH_PREFS: Readonly<PushPrefs> = Object.freeze({
   activity: false,
   decision: true,
   message: true,
+  providerError: true,
 })
 
 /** Default and allowed range of a device's activity update interval, in minutes. */

package/src/spoke/spoke.ts

@@ -15,6 +15,7 @@ import {
   type DeliverRequest,
   type DeliverResult,
   type DeliveryMode,
+  type CompactSessionStatus,
   type JobInfo,
   type HerdrWorkspace,
   type FormAnswer,
@@ -1571,7 +1572,7 @@ export class Spoke {
     try {
       const snapshot = await activity.call(this.host, this.tracker.directories(SEED_DIRECTORIES))
       const active = new Set(snapshot.active)
-      const ids = new Set([...snapshot.active, ...snapshot.jobs.map((j) => j.sessionID), ...this.tracker.working()])
+      const ids = new Set([...snapshot.active, ...snapshot.jobs.map((j) => j.sessionID), ...this.tracker.working(), ...this.tracker.failed()])
       const now = Date.now()
       for (const id of ids) {
         if (active.has(id)) this.tracker.ensure(id, now)
@@ -1580,9 +1581,12 @@ export class Spoke {
           .filter((j) => j.sessionID === id && j.status === "running")
           .slice(0, SEED_JOBS_MAX)
           .map(({ sessionID: _, ...job }) => job)
-        const status = active.has(id) ? "busy" : "idle"
-        this.tracker.seed(id, { status, jobs })
-        const event = { type: "session.seed", data: { sessionID: id, status: { type: status }, jobs } }
+        // An active session waiting to retry is seeded with its retry (attempt, reason, next try); the last failure
+        // (no run started since) goes along so a reconnected hub still shows it.
+        const status: CompactSessionStatus = active.has(id) ? (this.tracker.retryOf(id) ?? { type: "busy" }) : { type: "idle" }
+        const error = this.tracker.errorOf(id)
+        this.tracker.seed(id, { status: status.type, jobs })
+        const event = { type: "session.seed", data: { sessionID: id, status, jobs, ...(error ? { error } : {}) } }
         if (this.connection?.state === "connected" && shouldForward(this.config, this.tracker, event)) this.connection.send({ t: "event", event })
       }
       void this.fetchInfo()