@huynle/hub 0.9.1 → 0.10.0

package/src/central/concierge/grant-request.ts

@@ -0,0 +1,216 @@
+// Concierge grant requests (plan o9zx7u68 follow-up; the user decided 2026-11-08): the Concierge may ASK the user for
+// a grant in a project it cannot act in, through the existing grant-request path (agent/grant-requests.ts
+// requestManaged): a tap Decision to @me (never armable, never by voice); the user's approval creates the grant AS
+// THE USER, holder @@concierge (the managed holder only this path and Settings may name). It never widens a grant
+// itself: each request is a new, separate grant the user approves or denies.
+//
+//   POST /api/agent/concierge/grant-requests {projects, verbs, permissions?, never?, hours?, userAsked?, why}
+//        the user's CURRENT Concierge session (act token) → 201 {decision, message}; anyone else 404, the user 403.
+//
+// Clamps (the hub's, whatever the model asks):
+// - holder: always @@concierge (no holder field).
+// - verbs: approve, deny, answer; prompt and stop only with userAsked: true (the user asked for them explicitly).
+// - expiry: hours, 8 by default, at most 24 (whole minutes, at least one).
+// - projects: explicit, each one a project the Concierge watches now: a watched folder itself, or its name as the
+//   board shows it (a name two watched folders share is invalid, naming both). No wildcards, no parents.
+// - permissions: action[:glob] allow patterns; a wildcard action ("*", "re*d") is invalid.
+// - never: the default list (shell:git push*, shell:rm *), the Settings grant's never rules, the last @@concierge
+//   grant's (any state) and the asked ones, once each, in that order. allowAlways is always false.
+// - maxActionsPerHour: 60.
+// - one open request for the user's Concierge (all its sessions share the key "concierge"); after the user denies
+//   one, no new request for 24 hours (rate_limited); GRANT_REQUESTS_PER_HOUR an hour.
+import type { ConciergeSettings } from "../../../packages/protocol/src/concierge"
+import { CONCIERGE_ROLE } from "../../../packages/protocol/src/concierge"
+import { type AgentActor, canActAsSession, type SessionActor } from "../agent/actor"
+import { boundedJson } from "../agent/body"
+import { type Decision, WHY_MAX } from "../agent/decisions"
+import { sanitizeLabel } from "../agent/envelope"
+import { AgentError } from "../agent/errors"
+import type { GrantRequests } from "../agent/grant-requests"
+import type { Grants } from "../agent/grants"
+import type { Message } from "../agent/messages"
+import { canonicalProject, formatPattern, GRANT_PROJECTS_MAX, parsePattern } from "../agent/policy"
+import type { AgentRoute } from "../agent/routes"
+import { resolveWatchlist } from "./watchlist"
+import { type ConciergeIdentity, watchFacts, type WatchFactDeps, WatchlistStore } from "./watchlist-routes"
+import path from "node:path"
+
+const HOUR_MS = 3_600_000
+export const CONCIERGE_GRANT_HOLDER = `@@${CONCIERGE_ROLE}`
+/** The never rules every Concierge grant request carries (the Settings preset's). */
+export const CONCIERGE_GRANT_DEFAULT_NEVER: readonly string[] = ["shell:git push*", "shell:rm *"]
+export const CONCIERGE_GRANT_REQUEST_LIMITS = { hoursDefault: 8, hoursMax: 24, maxActionsPerHour: 60, denialCooldownMs: 24 * HOUR_MS } as const
+/** The request record's key: one for all the user's Concierge sessions. */
+export const CONCIERGE_GRANT_REQUESTER = "concierge"
+/** Verbs the Concierge may request; prompt and stop only when the user asked for them. */
+export const CONCIERGE_REQUEST_VERBS = ["approve", "deny", "answer"] as const
+export const CONCIERGE_ASKED_VERBS = ["prompt", "stop"] as const
+const FIELDS: ReadonlySet<string> = new Set(["projects", "verbs", "permissions", "never", "hours", "userAsked", "why"])
+const PATH = "/api/agent/concierge/grant-requests"
+const NO_STORE = { "cache-control": "no-store" }
+
+/** A project folder the Concierge watches now, with the names the board shows for it. */
+export interface WatchedProject {
+  readonly directory: string
+  readonly labels: readonly string[]
+}
+
+export interface ConciergeGrantRequestDeps {
+  readonly requests: Pick<GrantRequests, "requestManaged">
+  readonly grants: Pick<Grants, "list">
+  /** The user's Concierge settings (the Settings grant's never rules). */
+  readonly settings: (userID: string) => Promise<Pick<ConciergeSettings, "grant">>
+  /** The project folders of the watched sessions now. */
+  readonly watched: (userID: string) => Promise<readonly WatchedProject[]>
+}
+
+const invalid = (message: string, hint?: string) => new AgentError("invalid", message, hint ? { hint } : {})
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+function strings(value: unknown, what: string, options: { readonly required?: boolean } = {}): string[] {
+  if (value === undefined && !options.required) return []
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) throw invalid(`${what} is a list of texts`)
+  if (options.required && value.length === 0) throw invalid(`${what} lists at least one`)
+  return value as string[]
+}
+
+/** A pattern as grants store it (bash: → shell:); invalid otherwise. */
+function pattern(text: string, what: string, options: { readonly noWildcardAction?: boolean } = {}): string {
+  const parsed = parsePattern(text)
+  if (!parsed) throw invalid(`${what}: ${sanitizeLabel(text, 80)} is not an action[:glob] pattern`)
+  if (options.noWildcardAction && /[*?[\]]/.test(parsed.action)) throw invalid(`${what}: ${sanitizeLabel(text, 80)} names every action: name the action (read, edit, …)`)
+  return formatPattern(parsed)
+}
+
+function verbsOf(raw: unknown, userAsked: boolean): string[] {
+  const verbs: string[] = []
+  for (const verb of strings(raw, "verbs", { required: true })) {
+    const asked = (CONCIERGE_ASKED_VERBS as readonly string[]).includes(verb)
+    if (!asked && !(CONCIERGE_REQUEST_VERBS as readonly string[]).includes(verb)) throw invalid(`verbs: the Concierge may request ${[...CONCIERGE_REQUEST_VERBS, ...CONCIERGE_ASKED_VERBS].join(", ")}, not ${sanitizeLabel(verb, 40)}`)
+    if (asked && !userAsked) throw invalid(`verbs: ${verb} only when the user asked for it (userAsked: true)`)
+    if (!verbs.includes(verb)) verbs.push(verb)
+  }
+  return verbs
+}
+
+function expiresOf(hours: unknown): number {
+  if (hours === undefined) return CONCIERGE_GRANT_REQUEST_LIMITS.hoursDefault * 3600
+  const max = CONCIERGE_GRANT_REQUEST_LIMITS.hoursMax
+  if (typeof hours !== "number" || !Number.isFinite(hours) || hours <= 0 || hours > max) throw invalid(`hours is a number above 0, at most ${max}`)
+  const minutes = Math.round(hours * 60)
+  if (minutes < 1) throw invalid("hours is at least one minute (1/60)")
+  return minutes * 60
+}
+
+const slug = (text: string) => text.trim().toLowerCase()
+
+/** The watched folders the asked projects name (see the header). */
+function projectsOf(raw: unknown, watched: readonly WatchedProject[]): string[] {
+  const asked = strings(raw, "projects", { required: true })
+  if (asked.length > GRANT_PROJECTS_MAX) throw invalid(`projects lists at most ${GRANT_PROJECTS_MAX}`)
+  const folders = new Map<string, Set<string>>()
+  for (const w of watched) {
+    const dir = canonicalProject(w.directory)
+    if (dir === undefined) continue
+    const names = folders.get(dir) ?? new Set<string>()
+    for (const label of [...w.labels, path.posix.basename(dir)]) if (label) names.add(slug(label))
+    folders.set(dir, names)
+  }
+  const out: string[] = []
+  for (const item of asked) {
+    const text = item.trim()
+    if (!text) throw invalid("projects: an empty name")
+    if (/[*?]/.test(text)) throw invalid(`projects: ${sanitizeLabel(text, 80)} is a wildcard: name each project`)
+    let dir: string | undefined
+    const canonical = canonicalProject(text)
+    if (canonical !== undefined) {
+      if (folders.has(canonical)) dir = canonical
+    } else {
+      const named = [...folders].filter(([, names]) => names.has(slug(text))).map(([d]) => d)
+      if (named.length > 1) throw invalid(`projects: ${sanitizeLabel(text, 80)} names ${named.length} watched folders (${named.join(", ")}): name the folder`)
+      dir = named[0]
+    }
+    if (dir === undefined) throw invalid(`projects: ${sanitizeLabel(text, 80)} is not a project you watch`, "Request only projects of watched sessions (concierge_watch first)")
+    if (!out.includes(dir)) out.push(dir)
+  }
+  return out
+}
+
+export class ConciergeGrantRequests {
+  constructor(private readonly deps: ConciergeGrantRequestDeps) {}
+
+  /** Opens the Decision for the Concierge's request. Throws invalid or rate_limited. */
+  async request(userID: string, actor: SessionActor, body: unknown): Promise<{ decision: Decision; message: Message }> {
+    if (!isObject(body)) throw invalid("A grant request is {projects, verbs, permissions?, never?, hours?, userAsked?, why}")
+    for (const key of Object.keys(body)) if (!FIELDS.has(key)) throw invalid(`Unknown grant request field ${sanitizeLabel(key, 40)}`, key === "holder" ? "The holder is always @@concierge" : undefined)
+    const why = typeof body.why === "string" && body.why.length <= WHY_MAX * 4 ? sanitizeLabel(body.why, WHY_MAX) : ""
+    if (!why) throw invalid(`why is the reason the user reads (1–${WHY_MAX} characters)`)
+    if (body.userAsked !== undefined && typeof body.userAsked !== "boolean") throw invalid("userAsked is true or false")
+    const verbs = verbsOf(body.verbs, body.userAsked === true)
+    const expires = expiresOf(body.hours)
+    const allow = [...new Set(strings(body.permissions, "permissions").map((p) => pattern(p, "permissions", { noWildcardAction: true })))]
+    const askedNever = strings(body.never, "never").map((p) => pattern(p, "never"))
+    const projects = projectsOf(body.projects, await this.deps.watched(userID))
+    const never = await this.neverRules(userID, askedNever)
+    const grant = {
+      holder: CONCIERGE_GRANT_HOLDER,
+      scope: { projects },
+      allow: verbs,
+      permissions: { allow, never },
+      allowAlways: false,
+      maxActionsPerHour: CONCIERGE_GRANT_REQUEST_LIMITS.maxActionsPerHour,
+      expires,
+    }
+    return this.deps.requests.requestManaged(userID, actor, { grant, why }, { key: CONCIERGE_GRANT_REQUESTER, cooldownMs: CONCIERGE_GRANT_REQUEST_LIMITS.denialCooldownMs })
+  }
+
+  /** The default list, the Settings grant's, the last @@concierge grant's and the asked ones, once each. */
+  private async neverRules(userID: string, asked: readonly string[]): Promise<string[]> {
+    const [settings, grants] = await Promise.all([this.deps.settings(userID), this.deps.grants.list(userID)])
+    const last = grants.find((g) => g.holder === CONCIERGE_GRANT_HOLDER)
+    const out: string[] = []
+    for (const rule of [...CONCIERGE_GRANT_DEFAULT_NEVER, ...(settings.grant?.permissions.never ?? []), ...(last?.permissions.never ?? []), ...asked]) {
+      const parsed = parsePattern(rule)
+      const text = parsed ? formatPattern(parsed) : undefined
+      if (text !== undefined && !out.includes(text)) out.push(text)
+    }
+    return out
+  }
+}
+
+/** The project folders of the user's watched sessions now (each watched root's project, else its folder), with its slug. */
+export async function watchedProjects(deps: WatchFactDeps & { readonly state: ConstructorParameters<typeof WatchlistStore>[0] }, userID: string, hidden: readonly string[]): Promise<WatchedProject[]> {
+  const [config, facts] = await Promise.all([new WatchlistStore(deps.state).get(userID), watchFacts(deps, userID, hidden)])
+  const byID = new Map(facts.sessions.map((f) => [f.sessionID, f]))
+  const out: WatchedProject[] = []
+  for (const entry of resolveWatchlist(config, facts).entries) {
+    const fact = byID.get(entry.sessionID)
+    const directory = fact?.project ?? fact?.directory
+    if (directory) out.push({ directory, labels: fact?.projectSlug ? [fact.projectSlug] : [] })
+  }
+  return out
+}
+
+/** The route (see the header): the user's current Concierge only. */
+export function conciergeGrantRequestRoutes(deps: { readonly requests: ConciergeGrantRequests; readonly identity: ConciergeIdentity }): AgentRoute[] {
+  return [
+    {
+      method: "POST",
+      path: PATH,
+      allow: { session: true, app: true },
+      handle: async ({ actor, request, user }) => {
+        await admitCurrent(deps.identity, actor, user.id)
+        return Response.json(await deps.requests.request(user.id, actor as SessionActor, await boundedJson(request)), { status: 201, headers: NO_STORE })
+      },
+    },
+  ]
+}
+
+async function admitCurrent(identity: ConciergeIdentity, actor: AgentActor, userID: string): Promise<void> {
+  if (actor.kind === "user") throw new AgentError("forbidden", "Only the Concierge requests its grant: change it in Settings → Concierge")
+  if (actor.kind === "session" && canActAsSession(actor) && actor.userID === userID) {
+    const current = await identity.current(userID)
+    if (current.sessionID !== undefined && current.sessionID === actor.sessionID) return
+  }
+  throw new AgentError("not_found", "Not found")
+}

package/src/central/concierge/prompt.ts

@@ -3,7 +3,7 @@
 // text lives here (src/central/concierge/**) and nowhere else (contract open question 1).
 import { zonedStamp } from "./board-render"
 
-export const CONCIERGE_PROMPT_VERSION = 8
+export const CONCIERGE_PROMPT_VERSION = 9
 
 /** Facts about the user the instructions depend on (hub-known, never model text). */
 export interface InstructionFacts {
@@ -25,7 +25,7 @@ export interface InstructionFacts {
  * project folder name is fine, full paths are not; a refused act is said with the hub's reason. (FX-07, v7) An
  * action's why is read by the user in Activity: plain words, never board fields or codes (inGrant, auto, IDs).
  * (R-03, v8) Only an approve escalates (also with no grant); the other verbs outside the grant are proposed; an
- * approve recommends only with recommend: true.
+ * approve recommends only with recommend: true. (v9) Grant requests: GRANT_REQUEST_RULES (the block at the end).
  */
 export function conciergeInstructions(facts: InstructionFacts): string {
   const { voice } = facts
@@ -76,6 +76,8 @@ export function conciergeInstructions(facts: InstructionFacts): string {
     "- Every action is audited as yours, and the user reads its why in Activity. Give a short why for each, in plain words: never board fields or codes (inGrant, auto, revisions, IDs).",
     '- A proposal\'s why is your own reason, in your words. Never say the user asked for it unless they did in this conversation; when they only asked you to propose, say so ("You asked me to propose this").',
     "",
+    ...GRANT_REQUEST_RULES,
+    "",
     "Rules:",
     voice
       ? "- Never act on a Decision yourself: the user answers Decisions, by tap, or by voice on their own device. Their spoken yes or no is matched on their device, never by you: never claim a Decision was answered unless the hub says so."
@@ -132,3 +134,48 @@ export const NOTES_HEADER = "Your notes (written by you, the Concierge; they may
  * still exists on the machine): no board, no notes, no tools. It only says so.
  */
 export const RETIRED_INSTRUCTIONS = "This Concierge session was retired: the hub replaced it with a new Concierge session. You have no tools, no board and no authority here. In one short sentence, tell the user to open the Concierge from the Concierge button instead."
+
+// ---- (Concierge grant requests, v9) asking the user for a grant ------------------------------------------------
+// The rules for concierge_request_grant (concierge/grant-request.ts: the hub's clamps) and the line naming the grants
+// the user approved on the Concierge's request (after the grant line). Kept in one block (merge isolation).
+
+/** (v9) When and how the Concierge asks the user for a grant. */
+export const GRANT_REQUEST_RULES: readonly string[] = [
+  "Asking the user for a grant (hub tool verb concierge_request_grant: projects = the watched projects by the name your sessions show, verbs, permissions, never, hours, userAsked, why):",
+  "- Offer it only when the user asks you to help or act in a project no grant of yours covers (its sessions show project inGrant=no), or after you had to propose or escalate there several times. Offer it in one sentence first (for example \"Shall I ask you for a grant to approve reads and edits in toy-truck for 8 hours?\") and request it only after the user says yes.",
+  "- Ask for the least: only the projects, verbs and permissions needed, for a short time (8 hours by default, at most 24). Verbs approve, deny and answer; prompt or stop only when the user explicitly asked for them (then userAsked: true). You never ask for more than the user agreed to, and never for 'always'; the hub adds the user's never rules.",
+  "- After the user denied a grant request, do not ask again that day (the hub refuses it too). One request at a time; when the hub refuses a request, tell the user its reason and do not retry.",
+  "- A grant request is a Decision that waits for the user's tap on the card in the Concierge panel: say so. It cannot be armed. Never say you have the grant until the hub says it was created or your sessions show inGrant=yes.",
+]
+
+/** An active grant the user approved on the Concierge's request (not the Settings grant). */
+export interface RequestedGrantInput {
+  readonly id: string
+  readonly allow: readonly string[]
+  readonly projects: readonly string[]
+  readonly expiresAt: number
+}
+
+const requestedList = (grants: readonly RequestedGrantInput[], timeZone?: string) => {
+  const when = (at: number) => (timeZone !== undefined ? zonedStamp(at, timeZone) : new Date(at).toISOString())
+  return grants.map((g) => `${g.id}: ${g.allow.join(", ")} in ${g.projects.length} project(s), until ${when(g.expiresAt)}`).join("; ")
+}
+
+/** (v9) The line after the grant line naming the requested grants (hub-written); undefined when there are none. */
+export function requestedGrantsLine(grants: readonly RequestedGrantInput[], timeZone?: string): string | undefined {
+  if (!grants.length) return undefined
+  return `Grants the user approved at your request: ${requestedList(grants, timeZone)}. Your sessions' project inGrant shows where your grants apply.`
+}
+
+/**
+ * (hardening, verify round 4) The grant lines heading the board: the Settings grant's line, then the requested
+ * grants. Without an active Settings grant but with requested ones, one line names both (never a bare "Grant: none"
+ * or "every action is a Decision" next to grants that do apply).
+ */
+export function grantLines(grant: GrantLineInput, requested: readonly RequestedGrantInput[], timeZone?: string): string {
+  if (!requested.length) return grantLine(grant, timeZone)
+  if (grant.state === "active") return `${grantLine(grant, timeZone)}\n${requestedGrantsLine(requested, timeZone)}`
+  const when = (at: number) => (timeZone !== undefined ? zonedStamp(at, timeZone) : new Date(at).toISOString())
+  const settings = grant.state === "none" ? "Grant: none from Settings" : `Grant ${grant.id} from Settings ended ${when(grant.at)}`
+  return `${settings}; approved at your request: ${requestedList(requested, timeZone)}. Your sessions' project inGrant shows where these grants apply. Outside them, an approve you try becomes a Decision for the user; propose stop, deny, prompt or answer with concierge_propose.`
+}

package/src/central/concierge/session-routes.ts

@@ -43,6 +43,9 @@ export const CONCIERGE_SESSION_ROUTES: readonly { readonly method: string; reado
   { method: "POST", path: `${C}/arm` },
   // CON-13 (tiers.ts): a pending form's schema (fields, options), so its answers fit the form.
   { method: "GET", path: `${C}/sessions/:addr/forms/:form` },
+  // (Concierge grant requests, grant-request.ts) The Concierge asks the user for a scoped grant: a tap Decision, the
+  // hub's clamps. The generic POST /api/agent/grants/requests stays closed to it.
+  { method: "POST", path: `${C}/grant-requests` },
 ]
 
 const key = (method: string, path: string) => `${method} ${path}`

package/src/central/config.ts

@@ -7,8 +7,11 @@ import path from "node:path"
 import { hubEnv } from "../env"
 import { isLoopbackHost } from "../loopback"
 import { formatPattern, parsePattern } from "./agent/policy"
+import type { SpeechQuotaOverrides } from "./agent/speech-routes"
+import { SPEECH_RATE_LIMITS } from "../protocol"
 import { APP_DIR, configBase, legacyPaths, migrateFirst, migrateStateDir, resolveHubStateDir, stateLegacyPaths } from "../migrate"
 import { updateSpeech, type StoredSpeech } from "./speech/settings"
+import { readContextCards, type ContextCardsConfig } from "./context-cards/config"
 import { checkReleaseBase } from "./install/render"
 import { cspMode, type CspMode } from "./csp"
 import { parseDenyCidrs } from "./fetcher"
@@ -71,6 +74,10 @@ export interface CentralConfig {
   readonly launchCaps?: HubLaunches
   /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
   readonly webhooksAllowPrivate?: true
+  /** hub.json `agents.webhooks.allowPrivateHosts`: exact hostnames whose https webhook URLs may resolve privately. */
+  readonly webhooksPrivateHosts?: readonly string[]
+  /** (AF2) hub.json `agents.speechQuotas`: per-credential app speech quotas over SPEECH_RATE_LIMITS (only those set). */
+  readonly speechQuotas?: SpeechQuotaOverrides
   /**
    * HUB_RELEASE_BASE: where /install.sh and /install.ps1 tell machines to download hubctl (default: this version's
    * hub-releases GitHub release). https, or plain http on loopback or a private-network IP address.
@@ -82,6 +89,13 @@ export interface CentralConfig {
   readonly remoteFetch?: boolean
   /** HUB_FETCH_DENY_CIDRS: CIDRs the hub's outbound fetcher refuses on top of its built-in ranges (validated). */
   readonly fetchDenyCidrs?: readonly string[]
+  /** hub.json `contextCards` (context-cards/config.ts); HUB_CONTEXT_CARDS on/off sets enabled (off: the kill switch). */
+  readonly contextCards?: ContextCardsConfig
+  /**
+   * HUB_TRUSTED_PROXIES: reverse proxies (CIDRs or addresses, validated) whose X-Forwarded-For names the client for
+   * per-address rate limits (connect-app). Unset: the TCP peer is the client; X-Forwarded-For is never read.
+   */
+  readonly trustedProxies?: readonly string[]
 }
 
 /**
@@ -126,12 +140,16 @@ export interface HubAgents {
   readonly never?: readonly string[]
   readonly launches?: HubLaunches
   readonly webhooks?: HubWebhooks
+  /** (AF2) Per-credential app speech quotas: any subset of SPEECH_RATE_LIMITS. */
+  readonly speechQuotas?: SpeechQuotaOverrides
 }
 
 /** hub.json `agents.webhooks` (decision znbg8xa5 #8). */
 export interface HubWebhooks {
   /** Lets webhook URLs use http and private or local targets (self-hosted receivers); off by default (SSRF). */
   readonly allowPrivate?: boolean
+  /** Exact hostnames whose https webhook URLs may resolve to private addresses (a LAN-hosted receiver), nothing else. */
+  readonly allowPrivateHosts?: readonly string[]
 }
 
 /** hub.json, validated. */
@@ -144,14 +162,19 @@ export interface HubFile {
   readonly auth?: HubAuth
   readonly agents?: HubAgents
   readonly cluster?: HubCluster
+  readonly contextCards?: ContextCardsConfig
 }
 
 type Env = Readonly<Record<string, string | undefined>>
 
-const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster"])
+const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster", "contextCards"])
 const CLUSTER_KEYS = ["database", "valkey"] as const
-const AGENTS_KEYS = new Set(["never", "launches", "webhooks"])
-const WEBHOOK_KEYS = new Set(["allowPrivate"])
+const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas"])
+/** The largest speech quota hub.json may set (counts and characters). */
+const SPEECH_QUOTA_MAX = 1_000_000_000
+const WEBHOOK_KEYS = new Set(["allowPrivate", "allowPrivateHosts"])
+const PRIVATE_HOSTS_MAX = 50
+const HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/
 const LAUNCH_CAP_KEYS = ["maxQueued", "maxActive", "perHour", "lostAfterMinutes"] as const
 /** The longest lostAfterMinutes (a day): far below setTimeout's 32-bit limit. */
 const LOST_AFTER_MAX = 1440
@@ -245,6 +268,7 @@ export function readHubFile(file: string, home: string = homedir()): { file?: Hu
   if (raw.auth !== undefined) hub.auth = readHubAuth(raw.auth, file, warnings, fail)
   if (raw.agents !== undefined) hub.agents = readHubAgents(raw.agents, file, warnings, fail)
   if (raw.cluster !== undefined) hub.cluster = readHubCluster(raw.cluster, file, warnings, fail)
+  if (raw.contextCards !== undefined) hub.contextCards = readContextCards(raw.contextCards, file, warnings, fail, (statSync(file).mode & 0o044) !== 0)
   if (raw.speech !== undefined) {
     if (!isObj(raw.speech)) fail("speech must be an object with stt and/or tts")
     const speech = { ...(raw.speech as Record<string, unknown>) }
@@ -329,7 +353,33 @@ function readHubAgents(raw: unknown, file: string, warnings: string[], fail: (me
   const launches = input.launches === undefined ? undefined : readHubLaunches(input.launches, file, warnings, fail)
   const never = input.never === undefined ? undefined : readNever(input.never, fail)
   const webhooks = input.webhooks === undefined ? undefined : readHubWebhooks(input.webhooks, file, warnings, fail)
-  return { ...(never ? { never } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}) }
+  const speechQuotas = input.speechQuotas === undefined ? undefined : readSpeechQuotas(input.speechQuotas, file, warnings, fail)
+  return { ...(never ? { never } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
+}
+
+/** (AF2) `agents.speechQuotas`: {transcribe?: {perMinute?, perHour?}, speak?: {perMinute?, perHour?, charsPerHour?}}. */
+function readSpeechQuotas(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): SpeechQuotaOverrides {
+  if (!isObj(raw)) fail("agents.speechQuotas must be an object with transcribe and/or speak")
+  const out: Record<string, Record<string, number>> = {}
+  for (const [kind, section] of Object.entries(raw as Record<string, unknown>)) {
+    if (!Object.hasOwn(SPEECH_RATE_LIMITS, kind)) {
+      warnings.push(`${file}: unknown key "agents.speechQuotas.${kind}" ignored`)
+      continue
+    }
+    if (!isObj(section)) fail(`agents.speechQuotas.${kind} must be an object`)
+    const known = Object.keys(SPEECH_RATE_LIMITS[kind as keyof typeof SPEECH_RATE_LIMITS])
+    const quotas: Record<string, number> = {}
+    for (const [name, value] of Object.entries(section as Record<string, unknown>)) {
+      if (!known.includes(name) || !Object.hasOwn(section as object, name)) {
+        warnings.push(`${file}: unknown key "agents.speechQuotas.${kind}.${name}" ignored`)
+        continue
+      }
+      if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > SPEECH_QUOTA_MAX) fail(`agents.speechQuotas.${kind}.${name} must be a whole number from 1 to ${SPEECH_QUOTA_MAX}`)
+      quotas[name] = value as number
+    }
+    out[kind] = quotas
+  }
+  return out as SpeechQuotaOverrides
 }
 
 function readHubWebhooks(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubWebhooks {
@@ -337,7 +387,22 @@ function readHubWebhooks(raw: unknown, file: string, warnings: string[], fail: (
   const input = raw as Record<string, unknown>
   for (const key of Object.keys(input)) if (!WEBHOOK_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.webhooks.${key}" ignored`)
   if (input.allowPrivate !== undefined && typeof input.allowPrivate !== "boolean") fail("agents.webhooks.allowPrivate must be true or false")
-  return input.allowPrivate === undefined ? {} : { allowPrivate: input.allowPrivate as boolean }
+  const hosts = input.allowPrivateHosts === undefined ? undefined : readPrivateHosts(input.allowPrivateHosts, fail)
+  return { ...(input.allowPrivate === undefined ? {} : { allowPrivate: input.allowPrivate as boolean }), ...(hosts ? { allowPrivateHosts: hosts } : {}) }
+}
+
+/** Plain DNS hostnames with a dot (no IPs, wildcards, schemes, ports or paths), lowercase, trailing dot dropped, deduplicated. */
+function readPrivateHosts(raw: unknown, fail: (message: string) => never): string[] {
+  if (!Array.isArray(raw)) fail("agents.webhooks.allowPrivateHosts must be a list of hostnames")
+  const list = raw as unknown[]
+  if (list.length > PRIVATE_HOSTS_MAX) fail(`agents.webhooks.allowPrivateHosts holds at most ${PRIVATE_HOSTS_MAX} hostnames`)
+  const out: string[] = []
+  for (const item of list) {
+    const host = typeof item === "string" ? item.trim().toLowerCase().replace(/\.$/, "") : ""
+    if (!HOSTNAME.test(host) || /^[0-9.]+$/.test(host)) fail(`agents.webhooks.allowPrivateHosts: ${JSON.stringify(item)} is not a hostname (no IPs, wildcards, schemes, ports or paths)`)
+    if (!out.includes(host)) out.push(host)
+  }
+  return out
 }
 
 function readHubLaunches(raw: unknown, file: string, warnings: string[], fail: (message: string) => never): HubLaunches {
@@ -516,6 +581,8 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
   const remoteFetch = remoteFetchSetting(env).enabled ? "on" : "off"
   parseDenyCidrs(env.HUB_FETCH_DENY_CIDRS) // throws on an invalid entry: a startup error
   const fetchDenyCidrs = (env.HUB_FETCH_DENY_CIDRS ?? "").split(",").map((entry) => entry.trim()).filter(Boolean)
+  parseDenyCidrs(env.HUB_TRUSTED_PROXIES, "HUB_TRUSTED_PROXIES")
+  const trustedProxies = (env.HUB_TRUSTED_PROXIES ?? "").split(",").map((entry) => entry.trim()).filter(Boolean)
   return {
     host,
     port,
@@ -536,13 +603,29 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     agentsNever: [...(file.agents?.never ?? [])],
     ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
+    ...(file.agents?.webhooks?.allowPrivateHosts?.length ? { webhooksPrivateHosts: [...file.agents.webhooks.allowPrivateHosts] } : {}),
+    ...(file.agents?.speechQuotas ? { speechQuotas: file.agents.speechQuotas } : {}),
     ...(releaseBase ? { releaseBase } : {}),
     ...(cluster ? { cluster } : {}),
     ...(remoteFetch === "off" ? { remoteFetch: false } : {}),
     ...(fetchDenyCidrs.length ? { fetchDenyCidrs } : {}),
+    ...contextCardsSetting(env.HUB_CONTEXT_CARDS, file.contextCards),
+    ...(trustedProxies.length ? { trustedProxies } : {}),
   }
 }
 
+/**
+ * hub.json `contextCards` with HUB_CONTEXT_CARDS over its `enabled`: on/true/1/yes or off/false/0/no (any case; off is
+ * the hub-wide kill switch). Unset or empty leaves the file alone; any other value throws (startup stops).
+ */
+function contextCardsSetting(raw: string | undefined, file: ContextCardsConfig | undefined): { contextCards?: ContextCardsConfig } {
+  const value = raw?.trim().toLowerCase()
+  if (value === undefined || value === "") return file ? { contextCards: file } : {}
+  if (/^(on|true|1|yes)$/.test(value)) return { contextCards: { ...file, enabled: true } }
+  if (/^(off|false|0|no)$/.test(value)) return { contextCards: { ...file, enabled: false } }
+  throw new Error(`HUB_CONTEXT_CARDS must be on/true/1/yes or off/false/0/no, got ${JSON.stringify(raw)}`)
+}
+
 export interface LoadOptions {
   /** Where one-time migration notices go (default console). */
   readonly log?: (message: string) => void

package/src/central/context-cards/budget.ts

@@ -0,0 +1,121 @@
+// The context cards' per-user daily budget (decision 9604b0a1: "implement the entitlements hook for real"): model
+// calls and tokens per user per UTC day, in the StateStore collection `context-card-usage` (key = the day,
+// "2026-11-08"; older days are dropped on write). reserve() BEFORE a model call checks both limits and counts the
+// call in one version-checked write (serialised per user in this process, so concurrent runs cannot all pass a
+// check first); settle() after it adds the tokens the call reported, also when it failed. A failed or timed-out call
+// keeps its reservation: attempts count. Manual refreshes count too: the budget is the cost ceiling.
+import type { StateStore } from "../backend/types"
+import { updateVersioned } from "../agent/versioned"
+
+export const CONTEXT_CARD_USAGE = "context-card-usage"
+
+export interface BudgetLimits {
+  /** Model calls per user per UTC day. */
+  readonly calls: number
+  /** Input + output tokens per user per UTC day. */
+  readonly tokens: number
+}
+
+/** Defaults: ~200 pick-up summaries a day at ≈ 2k tokens each. */
+export const DEFAULT_BUDGET: BudgetLimits = { calls: 200, tokens: 400_000 }
+
+export type BudgetCheck = { readonly ok: true } | { readonly ok: false; readonly reason: string }
+
+export interface CardBudget {
+  /** Counts one call if both limits allow it (atomically); refused otherwise. */
+  reserve(userID: string): Promise<BudgetCheck>
+  /** Adds the tokens a reserved call used. */
+  settle(userID: string, tokens: number): Promise<void>
+}
+
+export interface BudgetUsage {
+  readonly day: string
+  readonly calls: number
+  readonly tokens: number
+  readonly limits: BudgetLimits
+}
+
+interface DayUsage {
+  readonly calls: number
+  readonly tokens: number
+}
+
+const dayOf = (at: number) => new Date(at).toISOString().slice(0, 10)
+
+export class DailyBudget implements CardBudget {
+  private readonly now: () => number
+
+  constructor(private readonly deps: { readonly state: StateStore; readonly now?: () => number; readonly limits: BudgetLimits | (() => BudgetLimits) }) {
+    this.now = deps.now ?? Date.now
+  }
+
+  private limits(): BudgetLimits {
+    return typeof this.deps.limits === "function" ? this.deps.limits() : this.deps.limits
+  }
+
+  async usage(userID: string): Promise<BudgetUsage> {
+    const day = dayOf(this.now())
+    const value = (await this.deps.state.get<DayUsage>(userID, CONTEXT_CARD_USAGE, day))?.value
+    return { day, calls: value?.calls ?? 0, tokens: value?.tokens ?? 0, limits: this.limits() }
+  }
+
+  async check(userID: string): Promise<BudgetCheck> {
+    const { calls, tokens, limits } = await this.usage(userID)
+    if (calls >= limits.calls) return { ok: false, reason: "Daily context card budget used up (calls)" }
+    if (tokens >= limits.tokens) return { ok: false, reason: "Daily context card budget used up (tokens)" }
+    return { ok: true }
+  }
+
+  /** Per-user chain: this process's reservations run one at a time (the versioned write covers other pods). */
+  private readonly chains = new Map<string, Promise<unknown>>()
+
+  private serial<T>(userID: string, run: () => Promise<T>): Promise<T> {
+    const next = (this.chains.get(userID) ?? Promise.resolve()).then(run, run)
+    const tail = next.catch(() => undefined)
+    this.chains.set(userID, tail)
+    void tail.then(() => {
+      if (this.chains.get(userID) === tail) this.chains.delete(userID)
+    })
+    return next
+  }
+
+  reserve(userID: string): Promise<BudgetCheck> {
+    return this.serial(userID, async () => {
+      const limits = this.limits()
+      let refused: BudgetCheck | undefined
+      await this.update(userID, (current) => {
+        refused = undefined
+        if ((current?.calls ?? 0) >= limits.calls) refused = { ok: false, reason: "Daily context card budget used up (calls)" }
+        else if ((current?.tokens ?? 0) >= limits.tokens) refused = { ok: false, reason: "Daily context card budget used up (tokens)" }
+        return refused ? undefined : { calls: (current?.calls ?? 0) + 1, tokens: current?.tokens ?? 0 }
+      })
+      return refused ?? { ok: true }
+    })
+  }
+
+  settle(userID: string, tokens: number): Promise<void> {
+    if (!(tokens > 0)) return Promise.resolve()
+    return this.serial(userID, () => this.update(userID, (current) => ({ calls: current?.calls ?? 0, tokens: (current?.tokens ?? 0) + tokens })))
+  }
+
+  /** One version-checked change of today's record; a new day's first write drops the older days. */
+  private async update(userID: string, change: (current: DayUsage | undefined) => DayUsage | undefined): Promise<void> {
+    const day = dayOf(this.now())
+    let fresh = false
+    const written = await updateVersioned<DayUsage>(this.deps.state, userID, CONTEXT_CARD_USAGE, day, (current) => {
+      fresh = current === undefined
+      return change(current)
+    })
+    if (written && fresh) {
+      for (const entry of await this.deps.state.list(userID, CONTEXT_CARD_USAGE)) {
+        if (entry.key !== day) await this.deps.state.delete(userID, CONTEXT_CARD_USAGE, entry.key).catch(() => {})
+      }
+    }
+  }
+
+  /** Adds usage directly (tests, imports); reserve/settle are the call path. */
+  record(userID: string, usage: { readonly calls: number; readonly tokens: number }): Promise<void> {
+    return this.serial(userID, () => this.update(userID, (current) => ({ calls: (current?.calls ?? 0) + usage.calls, tokens: (current?.tokens ?? 0) + usage.tokens })))
+  }
+
+}

package/src/central/context-cards/changes.ts

@@ -0,0 +1,29 @@
+// The `changes` context card: the session's working-tree changes from the spoke summary (files, +/−, branch),
+// deterministic (no model, no budget). It proves the registry's modularity and is cheap to keep fresh.
+import type { CardDraft, ContextCardProvider } from "./types"
+
+/** Files listed as fields (the most-changed first, as the spoke lists them). */
+const FILES_SHOWN = 4
+
+export function changesProvider(): ContextCardProvider {
+  return {
+    id: "changes",
+    label: "Changes",
+    version: 1,
+    usesModel: false,
+    triggers: ["turn-end", "user-return", "sweep"],
+    minIntervalMs: 60_000,
+    needs: ["changes"],
+    async generate({ inputs }): Promise<CardDraft | undefined> {
+      const c = inputs.changes
+      if (!c) return undefined
+      if (!c.totalFiles && !c.files.length) return { headline: c.branch ? `No changes on ${c.branch}` : "No changes", body: "" }
+      const n = c.totalFiles || c.files.length
+      return {
+        headline: `${n} file${n === 1 ? "" : "s"} changed · +${c.additions} −${c.deletions}${c.branch ? ` on ${c.branch}` : ""}`,
+        body: "",
+        fields: [...(c.branch ? [{ label: "Branch", value: c.branch }] : []), ...c.files.slice(0, FILES_SHOWN).map((f) => ({ label: f.file, value: `+${f.additions} −${f.deletions}` }))],
+      }
+    },
+  }
+}