@huynle/hub 0.7.4 → 0.8.1

package/src/central/profiles/usage-ports.ts

@@ -0,0 +1,120 @@
+// The hub's sources for profile usage (RP-08; usage.ts): one bounded read per source, never one per session.
+// - sessions: one directory read (Directory.entries) for every pinned session; the harness only for a session a
+//   connection of the same tenant owns now (registry.owner + harnessOf, tenant-checked).
+// - team roles: the user's active teams (one paged list, ≤ teamsPerUser) and, when a role names a profile, one
+//   scan of the seats (TeamSeatStore.currentCounts).
+// - launches: the user's retained launches (one list; the launch store prunes ended ones).
+// - workspaces: one scan of the memberships (MembershipStore.membershipsOfMany) and one paged workspace list for
+//   the titles, only when a pinned session is a member somewhere.
+import { LIST_LIMIT_MAX } from "../../protocol"
+import type { Directory } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { RouteLaunches } from "../agent/launch-routes"
+import type { ReadRegistry } from "../agent/read-routes"
+import type { TeamSeatStore } from "../teams/seats"
+import type { Team, TeamStore } from "../teams/store"
+import type { MembershipStore } from "../workspaces/members"
+import type { WorkspaceStore } from "../workspaces/store"
+import type { UsagePorts, UsageSessionInfo, UsageTeamRoleRef } from "./usage"
+
+export interface UsagePortDeps {
+  readonly directory?: Pick<Directory, "entries">
+  readonly registry?: Pick<ReadRegistry, "owner" | "sessionTenant" | "harnessOf">
+  readonly teams?: { readonly teams: Pick<TeamStore, "list">; readonly seats: Pick<TeamSeatStore, "currentCounts"> }
+  readonly launches?: Pick<RouteLaunches, "list">
+  readonly workspaces?: { readonly workspaces: Pick<WorkspaceStore, "list">; readonly members: Pick<MembershipStore, "membershipsOfMany"> }
+}
+
+export function usagePorts(deps: UsagePortDeps): UsagePorts {
+  const { directory, registry, teams, launches, workspaces } = deps
+  return {
+    ...(directory
+      ? {
+          sessions(userID: string, sessionIDs: readonly string[]) {
+            let entries
+            try {
+              entries = directory.entries(userID, sessionIDs)
+            } catch (cause) {
+              if (cause instanceof AgentError) return new Map()
+              throw cause
+            }
+            const out = new Map<string, UsageSessionInfo>()
+            for (const [id, e] of entries) {
+              const conn = e.online && registry && registry.sessionTenant(id) === userID ? registry.owner(id) : undefined
+              const harness = conn ? registry?.harnessOf?.(conn) : undefined
+              out.set(id, {
+                ...(e.name !== undefined ? { name: e.name } : {}),
+                ...(e.title !== undefined ? { title: e.title } : {}),
+                ...(e.machineID !== undefined ? { machineID: e.machineID } : {}),
+                ...(harness !== undefined ? { harness } : {}),
+                ...(e.project !== undefined ? { project: e.project } : {}),
+                online: e.online,
+                ...(e.lastSeen !== undefined ? { lastSeen: e.lastSeen } : {}),
+              })
+            }
+            return out
+          },
+        }
+      : {}),
+    ...(teams
+      ? {
+          async teamRoles(userID: string) {
+            const active: Team[] = []
+            let cursor: string | undefined
+            do {
+              const page = await teams.teams.list(userID, { state: "active", limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+              active.push(...page.items)
+              cursor = page.cursor
+            } while (cursor)
+            const named = active.flatMap((t) => t.roles.filter((r) => r.profile).map((r) => ({ team: t, role: r })))
+            if (!named.length) return []
+            const counts = await teams.seats.currentCounts(userID)
+            return named.map(({ team, role }): UsageTeamRoleRef => ({
+              teamID: team.id,
+              teamName: team.name,
+              teamTitle: team.title,
+              role: role.name,
+              ...(role.label !== undefined ? { label: role.label } : {}),
+              profileID: role.profile!.profileID,
+              ...(role.profile!.version !== undefined ? { version: role.profile!.version } : {}),
+              staffed: counts.get(team.id)?.get(role.name) ?? 0,
+            }))
+          },
+        }
+      : {}),
+    ...(launches
+      ? {
+          async launches(userID: string) {
+            return (await launches.list(userID)).map((l) => ({
+              id: l.id,
+              state: l.state,
+              ...(l.outcome !== undefined ? { outcome: l.outcome } : {}),
+              ...(l.by !== undefined ? { by: l.by } : {}),
+              ...(l.sessionID !== undefined ? { sessionID: l.sessionID } : {}),
+              created: l.created,
+              at: l.at,
+              ...(l.spec.agentProfile ? { agentProfile: { profileID: l.spec.agentProfile.profileID, version: l.spec.agentProfile.version } } : {}),
+            }))
+          },
+        }
+      : {}),
+    ...(workspaces
+      ? {
+          async workspaces(userID: string, sessionIDs: readonly string[]) {
+            const memberships = await workspaces.members.membershipsOfMany(userID, sessionIDs)
+            if (!memberships.size) return new Map()
+            const titles = new Map<string, string>()
+            let cursor: string | undefined
+            do {
+              const page = await workspaces.workspaces.list(userID, { limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+              for (const w of page.items) titles.set(w.id, w.title)
+              cursor = page.cursor
+            } while (cursor)
+            return new Map(
+              [...memberships].map(([sessionID, ids]) => [sessionID, ids.map((workspaceID) => ({ workspaceID, ...(titles.has(workspaceID) ? { title: titles.get(workspaceID)! } : {}) }))] as const),
+            )
+          },
+        }
+      : {}),
+  }
+}

package/src/central/profiles/usage.ts

@@ -0,0 +1,364 @@
+// Where a profile is used (RP-08): GET /api/agent/profiles/:id/usage and the per-profile counts of
+// GET /api/agent/profiles?include=usage. Read-only; it changes nothing and confers nothing.
+//
+// Sources (one bounded pass each, never one read per session — no N+1):
+// - pins: ONE scan of the user's `profile-assignments` collection (ProfileStore.assignmentsScan), capped at
+//   `limits.assignments`. No reverse index: assignments are keyed by session and bounded by the user's sessions
+//   (the directory keeps at most SESSION_LIMIT), so a capped scan is cheaper than keeping a second index consistent
+//   with every pin, unpin and retention write. Past the cap the answer says `truncated: ["sessions"]`.
+// - sessions: one directory read for all pinned session IDs (name, title, machine, project, presence), with the
+//   harness of the session's owning connection when it is online (ports.sessions).
+// - team roles: the published roles of the user's active teams that name the profile, with their current staffed
+//   seat counts (ports.teamRoles: one team list and one seats scan).
+// - launches: the user's retained launches whose spec named the profile (ports.launches: one list).
+// - workspaces: the current workspace memberships of the pinned sessions (ports.workspaces: one members scan).
+//
+// Authorization: the route needs profiles:read (users always; session tokens never). Each category then mirrors the
+// existing read rule of what it shows, and a category the caller may not read is left out entirely (no counts
+// either) and named in `hidden`:
+//   sessions    apps need sessions:read                         (session IDs, presence, machine, harness, project)
+//   teams       apps need teams:read or teams:manage            (team, role; no session IDs)
+//               seat occupancy (`staffed`, `staffedSeats`) also needs sessions:read, like the team seat, roster,
+//               status and staffing routes; without it the roles are shown without those fields
+//   launches    apps need sessions:launch, and see only the launches they started (launch.by), like GET /launches;
+//               a launch's session ID also needs sessions:read
+//   workspaces  apps need workspaces:read and sessions:read      (derived from the sessions' memberships)
+// Another user's or an unknown profile is the same 404 (the profile is looked up under the caller's user first).
+import { LIST_LIMIT_DEFAULT, LIST_LIMIT_MAX, type ProfileAssignment } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+import type { ProfileStore } from "./store"
+
+/** One pinned session as the directory and registry know it (absent: not in the directory any more). */
+export interface UsageSessionInfo {
+  readonly name?: string
+  readonly title?: string
+  readonly machineID?: string
+  /** The harness of the connection that owns the session (online sessions only). */
+  readonly harness?: string
+  readonly project?: string
+  readonly online: boolean
+  readonly lastSeen?: number
+}
+
+/** A published team role that names a profile. */
+export interface UsageTeamRoleRef {
+  readonly teamID: string
+  readonly teamName: string
+  readonly teamTitle: string
+  readonly role: string
+  readonly label?: string
+  readonly profileID: string
+  /** The role's requested version; absent: the latest at staffing time. */
+  readonly version?: number
+  /** Current seats in that role. */
+  readonly staffed: number
+}
+
+/** A retained launch, as far as usage needs it. */
+export interface UsageLaunch {
+  readonly id: string
+  readonly state: string
+  readonly outcome?: string
+  /** Who launched it (`user`, `app:<token>`, a session ID): the launch read rule. */
+  readonly by?: string
+  readonly sessionID?: string
+  readonly created: number
+  /** When it entered its state. */
+  readonly at: number
+  readonly agentProfile?: { readonly profileID: string; readonly version: number }
+}
+
+export interface UsageLimits {
+  /** Pins scanned per request. */
+  readonly assignments: number
+  /** Team roles, launches and workspaces listed (counts stay exact). */
+  readonly teamRoles: number
+  readonly launches: number
+  readonly workspaces: number
+  /** Distinct team IDs per profile in the list counts. */
+  readonly teamsPerCount: number
+}
+
+export const USAGE_LIMITS: UsageLimits = { assignments: 10_000, teamRoles: 100, launches: 50, workspaces: 50, teamsPerCount: 16 }
+
+type Memberships = ReadonlyMap<string, readonly { readonly workspaceID: string; readonly title?: string }[]>
+
+/** The hub's sources; a missing port reads as "nothing uses it there". */
+export interface UsagePorts {
+  sessions?(userID: string, sessionIDs: readonly string[]): ReadonlyMap<string, UsageSessionInfo>
+  teamRoles?(userID: string): Promise<readonly UsageTeamRoleRef[]>
+  launches?(userID: string): Promise<readonly UsageLaunch[]>
+  workspaces?(userID: string, sessionIDs: readonly string[]): Promise<Memberships>
+}
+
+/** What one caller may see. */
+export interface UsageView {
+  readonly sessions: boolean
+  readonly teams: boolean
+  /** false: hidden; otherwise every launch, or (apps) only the ones `by` started. */
+  readonly launches: false | { readonly by?: string }
+  readonly workspaces: boolean
+}
+
+export type UsageCategory = "sessions" | "teams" | "launches" | "workspaces"
+
+/** The caller's view: users see everything; apps by scope (see the header); session tokens never get here. */
+export function usageView(actor: AgentActor): UsageView {
+  if (actor.kind === "user") return { sessions: true, teams: true, launches: {}, workspaces: true }
+  if (actor.kind === "session") return { sessions: false, teams: false, launches: false, workspaces: false }
+  const has = (scope: string) => actor.scopes.includes(scope)
+  return {
+    sessions: has("sessions:read"),
+    teams: has("teams:read") || has("teams:manage"),
+    launches: has("sessions:launch") ? { by: `app:${actor.tokenID}` } : false,
+    workspaces: has("workspaces:read") && has("sessions:read"),
+  }
+}
+
+/** Seat occupancy is session information: team roles plus sessions:read (the team seat/roster/status rule). */
+const seatsVisible = (view: UsageView): boolean => view.teams && view.sessions
+
+function hiddenOf(view: UsageView, categories: readonly UsageCategory[]): UsageCategory[] {
+  const shown: Record<UsageCategory, boolean> = { sessions: view.sessions, teams: view.teams, launches: view.launches !== false, workspaces: view.workspaces }
+  return categories.filter((c) => !shown[c])
+}
+
+export interface UsageSessionItem {
+  readonly sessionID: string
+  readonly name?: string
+  readonly title?: string
+  readonly machineID?: string
+  readonly harness?: string
+  readonly project?: string
+  readonly online: boolean
+  readonly lastSeen?: number
+  /** Not in the directory any more (deleted); the pin is still stored. */
+  readonly known?: false
+  /** The requested (pinned) version and the pin's revision (for an explicit upgrade with expectedRevision). */
+  readonly version: number
+  readonly revision: number
+  /** Pinned to a version older than the profile's latest. */
+  readonly olderVersion: boolean
+  readonly ack?: { readonly status: string; readonly at: number; readonly offline?: true }
+  /** What the session last confirmed running. */
+  readonly effective?: { readonly version: number; readonly status: string; readonly at: number }
+}
+
+export interface UsageCounts {
+  sessions?: number
+  online?: number
+  olderVersion?: number
+  teamRoles?: number
+  staffedSeats?: number
+  launches?: number
+  liveLaunches?: number
+  workspaces?: number
+}
+
+/** The list's per-profile counts (no workspaces: that would need the members scan for every page). */
+export interface UsageListCounts extends UsageCounts {
+  /** Names (the #team slug, which team routes also accept) of the active teams whose roles name the profile. */
+  teams?: string[]
+  harnesses?: string[]
+}
+
+export interface ProfileUsageAnswer {
+  readonly profileID: string
+  readonly latestVersion: number
+  readonly counts: UsageCounts
+  readonly sessions?: { readonly items: UsageSessionItem[]; readonly cursor?: string }
+  readonly projects?: string[]
+  /** `staffed` only when seats are visible (sessions:read). */
+  readonly teamRoles?: (Omit<UsageTeamRoleRef, "profileID" | "staffed"> & { staffed?: number })[]
+  readonly launches?: { id: string; state: string; outcome?: string; version: number; sessionID?: string; created: number; updated: number }[]
+  readonly workspaces?: { workspaceID: string; title?: string; sessions: number }[]
+  readonly hidden?: UsageCategory[]
+  readonly truncated?: ("sessions" | "teamRoles" | "launches" | "workspaces")[]
+}
+
+const encodeCursor = (sessionID: string) => Buffer.from(JSON.stringify({ k: sessionID })).toString("base64url")
+function decodeCursor(cursor: string): string {
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as { k?: unknown }
+    if (typeof parsed.k === "string") return parsed.k
+  } catch {
+    // answered below
+  }
+  throw new AgentError("invalid", "Bad cursor; start again without one")
+}
+
+function pageLimit(limit: number | undefined): number {
+  if (limit === undefined) return LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+  return limit
+}
+
+const LIVE = (l: UsageLaunch) => l.state !== "ended"
+const byNewest = (a: UsageLaunch, b: UsageLaunch) => b.created - a.created || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0)
+
+export class ProfileUsage {
+  private readonly profiles: Pick<ProfileStore, "get" | "assignmentsScan">
+  private readonly ports: UsagePorts
+  readonly limits: UsageLimits
+
+  constructor(options: { readonly profiles: Pick<ProfileStore, "get" | "assignmentsScan">; readonly ports?: UsagePorts; readonly limits?: Partial<UsageLimits> }) {
+    this.profiles = options.profiles
+    this.ports = options.ports ?? {}
+    this.limits = { ...USAGE_LIMITS, ...options.limits }
+  }
+
+  /** One profile's usage for `view`; not_found for an unknown or another user's profile. */
+  async usage(userID: string, profileID: string, view: UsageView, page: { readonly limit?: number; readonly cursor?: string } = {}): Promise<ProfileUsageAnswer> {
+    const limit = pageLimit(page.limit)
+    const after = page.cursor === undefined ? undefined : decodeCursor(page.cursor)
+    const profile = await this.profiles.get(userID, profileID)
+    if (!profile) throw new AgentError("not_found", `No profile ${profileID}`)
+    const counts: UsageCounts = {}
+    const truncated: NonNullable<ProfileUsageAnswer["truncated"]> = []
+    const answer: { -readonly [K in keyof ProfileUsageAnswer]: ProfileUsageAnswer[K] } = { profileID: profile.id, latestVersion: profile.latestVersion, counts }
+
+    let pins: ProfileAssignment[] = []
+    if (view.sessions || view.workspaces) {
+      const scan = await this.profiles.assignmentsScan(userID, this.limits.assignments)
+      if (scan.truncated) truncated.push("sessions")
+      pins = scan.items.filter((a) => a.profileID === profile.id).sort((a, b) => (a.sessionID < b.sessionID ? -1 : a.sessionID > b.sessionID ? 1 : 0))
+    }
+    const ids = pins.map((p) => p.sessionID)
+
+    if (view.sessions) {
+      const info = ids.length && this.ports.sessions ? this.ports.sessions(userID, ids) : new Map<string, UsageSessionInfo>()
+      const items = pins.map((pin) => sessionItem(pin, info.get(pin.sessionID), profile.latestVersion))
+      counts.sessions = items.length
+      counts.online = items.filter((s) => s.online).length
+      counts.olderVersion = items.filter((s) => s.olderVersion).length
+      const rest = after === undefined ? items : items.filter((s) => s.sessionID > after)
+      const shown = rest.slice(0, limit)
+      answer.sessions = { items: shown, ...(rest.length > limit ? { cursor: encodeCursor(shown.at(-1)!.sessionID) } : {}) }
+      answer.projects = [...new Set(items.map((s) => s.project).filter((p): p is string => !!p))].sort()
+    }
+
+    if (view.teams) {
+      const refs = this.ports.teamRoles ? (await this.ports.teamRoles(userID)).filter((r) => r.profileID === profile.id) : []
+      const seats = seatsVisible(view)
+      counts.teamRoles = refs.length
+      if (seats) counts.staffedSeats = refs.reduce((n, r) => n + r.staffed, 0)
+      if (refs.length > this.limits.teamRoles) truncated.push("teamRoles")
+      answer.teamRoles = refs.slice(0, this.limits.teamRoles).map(({ profileID: _p, staffed, ...role }) => (seats ? { ...role, staffed } : role))
+    }
+
+    if (view.launches !== false) {
+      const by = view.launches.by
+      const named = this.ports.launches ? (await this.ports.launches(userID)).filter((l) => l.agentProfile?.profileID === profile.id && (by === undefined || l.by === by)) : []
+      counts.launches = named.length
+      counts.liveLaunches = named.filter(LIVE).length
+      if (named.length > this.limits.launches) truncated.push("launches")
+      answer.launches = [...named]
+        .sort(byNewest)
+        .slice(0, this.limits.launches)
+        .map((l) => ({
+          id: l.id,
+          state: l.state,
+          ...(l.outcome !== undefined ? { outcome: l.outcome } : {}),
+          version: l.agentProfile!.version,
+          ...(view.sessions && l.sessionID !== undefined ? { sessionID: l.sessionID } : {}),
+          created: l.created,
+          updated: l.at,
+        }))
+    }
+
+    if (view.workspaces) {
+      const memberships = ids.length && this.ports.workspaces ? await this.ports.workspaces(userID, ids) : new Map()
+      const found = new Map<string, { workspaceID: string; title?: string; sessions: number }>()
+      for (const id of ids) {
+        for (const m of memberships.get(id) ?? []) {
+          const entry = found.get(m.workspaceID) ?? { workspaceID: m.workspaceID, ...(m.title !== undefined ? { title: m.title } : {}), sessions: 0 }
+          entry.sessions++
+          found.set(m.workspaceID, entry)
+        }
+      }
+      const all = [...found.values()].sort((a, b) => b.sessions - a.sessions || (a.workspaceID < b.workspaceID ? -1 : 1))
+      counts.workspaces = all.length
+      if (all.length > this.limits.workspaces) truncated.push("workspaces")
+      answer.workspaces = all.slice(0, this.limits.workspaces)
+    }
+
+    const hidden = hiddenOf(view, ["sessions", "teams", "launches", "workspaces"])
+    if (hidden.length) answer.hidden = hidden
+    if (truncated.length) answer.truncated = truncated
+    return answer
+  }
+
+  /** Per-profile counts for a page of the list (one pass per source, whatever the page size). */
+  async counts(
+    userID: string,
+    profiles: readonly { readonly id: string; readonly latestVersion: number }[],
+    view: UsageView,
+  ): Promise<{ usage: Record<string, UsageListCounts>; hidden?: UsageCategory[]; truncated?: ["sessions"] }> {
+    const usage: Record<string, UsageListCounts> = {}
+    const latest = new Map(profiles.map((p) => [p.id, p.latestVersion]))
+    for (const p of profiles) usage[p.id] = {}
+    let truncated = false
+    if (profiles.length && view.sessions) {
+      const scan = await this.profiles.assignmentsScan(userID, this.limits.assignments)
+      truncated = scan.truncated
+      const pins = scan.items.filter((a) => latest.has(a.profileID))
+      const info = pins.length && this.ports.sessions ? this.ports.sessions(userID, pins.map((p) => p.sessionID)) : new Map<string, UsageSessionInfo>()
+      for (const p of profiles) Object.assign(usage[p.id]!, { sessions: 0, online: 0, olderVersion: 0, harnesses: [] })
+      const harnesses = new Map<string, Set<string>>()
+      for (const pin of pins) {
+        const c = usage[pin.profileID]!
+        const s = info.get(pin.sessionID)
+        c.sessions!++
+        if (s?.online) c.online!++
+        if (pin.version < latest.get(pin.profileID)!) c.olderVersion!++
+        if (s?.harness) harnesses.set(pin.profileID, (harnesses.get(pin.profileID) ?? new Set()).add(s.harness))
+      }
+      for (const [id, set] of harnesses) usage[id]!.harnesses = [...set].sort()
+    }
+    if (profiles.length && view.teams) {
+      const refs = this.ports.teamRoles ? await this.ports.teamRoles(userID) : []
+      const seats = seatsVisible(view)
+      for (const p of profiles) Object.assign(usage[p.id]!, { teamRoles: 0, ...(seats ? { staffedSeats: 0 } : {}), teams: [] })
+      for (const ref of refs) {
+        const c = usage[ref.profileID]
+        if (!c) continue
+        c.teamRoles!++
+        if (seats) c.staffedSeats! += ref.staffed
+        if (!c.teams!.includes(ref.teamName) && c.teams!.length < this.limits.teamsPerCount) c.teams!.push(ref.teamName)
+      }
+    }
+    if (profiles.length && view.launches !== false) {
+      const by = view.launches.by
+      const all = this.ports.launches ? await this.ports.launches(userID) : []
+      for (const p of profiles) Object.assign(usage[p.id]!, { launches: 0, liveLaunches: 0 })
+      for (const l of all) {
+        const c = l.agentProfile && usage[l.agentProfile.profileID]
+        if (!c || (by !== undefined && l.by !== by)) continue
+        c.launches!++
+        if (LIVE(l)) c.liveLaunches!++
+      }
+    }
+    const hidden = hiddenOf(view, ["sessions", "teams", "launches"])
+    return { usage, ...(hidden.length ? { hidden } : {}), ...(truncated ? { truncated: ["sessions"] as ["sessions"] } : {}) }
+  }
+}
+
+function sessionItem(pin: ProfileAssignment, info: UsageSessionInfo | undefined, latestVersion: number): UsageSessionItem {
+  return {
+    sessionID: pin.sessionID,
+    ...(info?.name !== undefined ? { name: info.name } : {}),
+    ...(info?.title !== undefined ? { title: info.title } : {}),
+    ...(info?.machineID !== undefined ? { machineID: info.machineID } : {}),
+    ...(info?.harness !== undefined ? { harness: info.harness } : {}),
+    ...(info?.project !== undefined ? { project: info.project } : {}),
+    online: info?.online === true,
+    ...(info?.lastSeen !== undefined ? { lastSeen: info.lastSeen } : {}),
+    ...(info ? {} : { known: false as const }),
+    version: pin.version,
+    revision: pin.revision,
+    olderVersion: pin.version < latestVersion,
+    ...(pin.ack ? { ack: { status: pin.ack.status, at: pin.ack.at, ...(pin.ack.offline ? { offline: true as const } : {}) } } : {}),
+    ...(pin.effective && pin.effective.profileID === pin.profileID ? { effective: { version: pin.effective.version, status: pin.effective.status, at: pin.effective.at } } : {}),
+  }
+}

package/src/central/push.ts

@@ -33,6 +33,7 @@ export const NOTIFICATION_LABELS: Readonly<Record<NotificationKind, string>> = O
   decision: "Decision",
   message: "Message",
   providerError: "Model provider error",
+  concierge: "Concierge",
 })
 
 /** True for a known notification kind (API input). */
@@ -63,6 +64,8 @@ export interface PushPayload {
   readonly test?: true
   /** Per-session kinds (providerError, subagentFailed): the session it is about, so the service worker tags each apart. */
   readonly tagKey?: string
+  /** (CON-04) Where a tap opens, when not the session page (kind concierge: /concierge). */
+  readonly url?: string
 }
 
 const minutes = (clock: string): number => Number(clock.slice(0, 2)) * 60 + Number(clock.slice(3, 5))
@@ -213,6 +216,9 @@ export function pushPayload(kind: NotificationKind, sessionID: string, sessionTi
       return { kind, sessionID, title, body: "A decision waits for you. Tap to answer.", ...(extra.decisionID ? { decisionID: extra.decisionID } : {}) }
     case "message":
       return { kind, sessionID, title, body: "Tap to see it." }
+    // The Concierge's session is hidden: the tap opens the Concierge, never its session page; no text.
+    case "concierge":
+      return { kind, sessionID, title: "Concierge", body: "The Concierge has something for you. Tap to open it.", url: "/concierge" }
     case "permission":
       // Never the request's summary (it may be a command line); the service worker fetches it from the hub.
       return { kind, sessionID, title, body: "Tap to review and answer.", ...(extra.requestID ? { requestID: extra.requestID } : {}) }
@@ -240,6 +246,7 @@ export function sendOptionsFor(kind: NotificationKind | "test"): { TTL: number;
     case "decision":
     case "message":
     case "providerError":
+    case "concierge":
       return { TTL: URGENT_TTL_SECONDS, urgency: "high" }
     case "done":
     case "stopped":