@huynle/hub 0.7.4 → 0.8.0

package/src/central/concierge/service.ts

@@ -0,0 +1,243 @@
+// CON-04 the Concierge service (contract "Concierge service: settings, launch, supervise, hide, context"): what the
+// Settings routes do, on top of the settings and notes records, the supervisor (state record, launch, relaunch,
+// disable) and the grant. Users only (routes.ts); every operation is keyed by the user (the tenant).
+//
+// - Machine eligibility (eligibilityOf, pure): one of the user's machines with a hub node (host runtime with OpenCode,
+//   workspace roots, not draining) and a connected OpenCode service spoke announcing `launch` and `sessionContext`.
+//   Each "no" has a reason Settings shows. An offline machine is not eligible now but may be enabled: the state is
+//   waiting_machine until it is back.
+// - Enable: entitlements.check (403 with its reason), machineID and directory required (400), the machine must be
+//   the user's (404 otherwise, like anything of another user), an online machine must qualify and the directory be
+//   under its node's workspace roots (422 unsupported {feature: "conciergeMachine", reason}). Then the grant (when
+//   settings.grant: Grants.create/update, holder @@concierge), the settings (enabled, version-checked), and the
+//   supervisor starts it. A grant created for a refused enable is revoked again.
+// - A settings change that picks a machine that is not the user's (unknown or another user's, alike): 404 (CON-09b).
+// - A settings change while enabled: a new or removed grant applies at once (update restarts its expiry: Renew);
+//   another machine, directory or model restarts the Concierge.
+// - Disable: settings first (enabled false, version-checked), then the supervisor's idempotent steps.
+import type { ConciergeSettings, ConciergeStatus } from "../../../packages/protocol/src/concierge"
+import type { NodeRuntimeInfo } from "../../protocol"
+import { AgentError } from "../agent/errors"
+import type { Grants } from "../agent/grants"
+import type { ConciergeEntitlements } from "./entitlements"
+import type { ConciergeNotes, NotesStore } from "./notes"
+import { grantInput, parseSettingsPatch, type SettingsStore, validTimeZone } from "./settings"
+import type { Eligibility, Supervisor } from "./supervisor"
+
+/** What the hub knows about one of the user's machines (http.ts gathers it from the store, nodes and registry). */
+export interface MachineFacts {
+  readonly id: string
+  readonly name: string
+  /** A process of the machine is connected (spoke or node). */
+  readonly online: boolean
+  readonly node?: { readonly runtimes: readonly NodeRuntimeInfo[]; readonly workspaceRoots: readonly string[]; readonly draining: boolean }
+  /** The machine's OpenCode service spoke and what it announces. */
+  readonly service?: { readonly launch: boolean; readonly sessionContext: boolean }
+}
+
+export interface MachineView extends Eligibility {
+  readonly id: string
+  readonly name: string
+  /** The node's workspace roots (the directory picker's start points). */
+  readonly roots: readonly string[]
+}
+
+/** Whether a machine can host the Concierge now, and why not. */
+export function eligibilityOf(facts: Omit<MachineFacts, "id" | "name">): Eligibility {
+  const no = (reason: string): Eligibility => ({ eligible: false, online: facts.online, reason })
+  if (!facts.node && !facts.online) return no("Offline")
+  if (!facts.node) return no("No hub node runs on it: start `hub node` there with a workspace root")
+  if (facts.node.draining) return no("Its hub node is draining")
+  if (!facts.node.runtimes.some((r) => r.kind === "host" && r.harnesses?.includes("opencode"))) return no("Its hub node has no host runtime with OpenCode")
+  if (!facts.node.workspaceRoots.length) return no("Its hub node has no workspace roots")
+  if (!facts.service) return no("No OpenCode service runs on it (the hub plugin's background service)")
+  if (!facts.service.launch) return no("Its OpenCode plugin cannot launch sessions: update the hub plugin")
+  if (!facts.service.sessionContext) return no("Its OpenCode plugin is too old for the Concierge: update the hub plugin")
+  return { eligible: true, online: true }
+}
+
+const underRoot = (dir: string, root: string) => {
+  const base = root.replace(/\/+$/, "")
+  return dir === base || dir.startsWith(`${base}/`)
+}
+
+export interface ConciergeView {
+  readonly settings: ConciergeSettings
+  readonly status: ConciergeStatus
+  readonly machines: readonly MachineView[]
+}
+
+export interface ServiceDeps {
+  readonly settings: SettingsStore
+  readonly notes: NotesStore
+  readonly supervisor: Supervisor
+  readonly grants: Pick<Grants, "create" | "update" | "revoke">
+  /** The user's machines (not revoked) with their facts. */
+  readonly machines: (userID: string) => readonly MachineFacts[]
+  readonly entitlements: ConciergeEntitlements
+  /** The admin audit: {actor: owner, action: concierge.*} only. */
+  readonly audit: (userID: string, action: string) => Promise<void>
+  /**
+   * Makes buffered state writes durable (StateStore.flush; a write-through store has none). Awaited before every
+   * security-relevant answer (settings, enable, disable, restart): a 200 is never lost to a crash.
+   */
+  readonly flush?: () => Promise<void>
+}
+
+const ignorable = (cause: unknown) => cause instanceof AgentError && (cause.code === "gone" || cause.code === "not_found")
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+function revisionOf(body: unknown, allowed: readonly string[] = []): number {
+  if (!isObject(body)) throw new AgentError("invalid", "The body is {expectedRevision}")
+  for (const key of Object.keys(body)) if (key !== "expectedRevision" && !allowed.includes(key)) throw new AgentError("invalid", `Unknown field ${key.slice(0, 40)}`)
+  if (!Number.isSafeInteger(body.expectedRevision)) throw new AgentError("invalid", "expectedRevision is required")
+  return body.expectedRevision as number
+}
+
+const checkRevision = (settings: ConciergeSettings, expected: number) => {
+  if (settings.revision !== expected) throw new AgentError("conflict", "The Concierge settings changed meanwhile", { extra: { currentRevision: settings.revision } })
+}
+
+export class ConciergeService {
+  constructor(private readonly deps: ServiceDeps) {}
+
+  get supervisor(): Supervisor {
+    return this.deps.supervisor
+  }
+
+  /** The user's machines with their eligibility. */
+  machineViews(userID: string): MachineView[] {
+    return this.deps.machines(userID).map((m) => ({ id: m.id, name: m.name, ...eligibilityOf(m), roots: m.node ? [...m.node.workspaceRoots] : [] }))
+  }
+
+  /** The supervisor's eligibility port. */
+  eligibility(userID: string, machineID: string): Eligibility {
+    const facts = this.deps.machines(userID).find((m) => m.id === machineID)
+    return facts ? eligibilityOf(facts) : { eligible: false, online: false, reason: "Not one of your machines" }
+  }
+
+  async view(userID: string): Promise<ConciergeView> {
+    const [settings, status] = await Promise.all([this.deps.settings.get(userID), this.deps.supervisor.status(userID)])
+    return { settings, status, machines: this.machineViews(userID) }
+  }
+
+  /** Refuses a machine or directory that cannot host the Concierge (an offline machine is fine). */
+  private checkPlacement(userID: string, settings: ConciergeSettings): void {
+    if (settings.machineID === undefined || settings.directory === undefined) throw new AgentError("invalid", "Pick a machine and a directory (a git repo on it) first")
+    const facts = this.deps.machines(userID).find((m) => m.id === settings.machineID)
+    if (!facts) throw new AgentError("not_found", "No such machine")
+    const unsupported = (reason: string) => new AgentError("unsupported", `This machine cannot host the Concierge: ${reason}`, { extra: { feature: "conciergeMachine", reason } })
+    const verdict = eligibilityOf(facts)
+    if (!verdict.eligible && verdict.online) throw unsupported(verdict.reason ?? "not eligible")
+    if (facts.node && !facts.node.workspaceRoots.some((root) => underRoot(settings.directory!, root))) throw unsupported("The directory is not under the machine's workspace roots")
+  }
+
+  /** Creates, renews or revokes the @@concierge grant for the settings; the grant ID (undefined: none). */
+  private async applyGrant(userID: string, settings: ConciergeSettings): Promise<string | undefined> {
+    if (!settings.grant) {
+      if (settings.grantID !== undefined) await this.deps.grants.revoke(userID, settings.grantID).catch((cause) => (ignorable(cause) ? undefined : Promise.reject(cause)))
+      return undefined
+    }
+    if (settings.grantID !== undefined) {
+      try {
+        await this.deps.grants.update(userID, settings.grantID, grantInput(settings.grant), { managed: true })
+        return settings.grantID
+      } catch (cause) {
+        if (!ignorable(cause)) throw cause
+      }
+    }
+    return (await this.deps.grants.create(userID, grantInput(settings.grant), { managed: true })).id
+  }
+
+  private async withGrantID(userID: string, expected: number, grantID: string | undefined, change: (s: ConciergeSettings) => ConciergeSettings): Promise<ConciergeSettings> {
+    return this.deps.settings.update(userID, (current) => {
+      checkRevision(current, expected)
+      const next = change(current)
+      const { grantID: _old, ...rest } = next
+      return grantID !== undefined ? { ...rest, grantID } : rest
+    })
+  }
+
+  async updateSettings(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const current = await this.deps.settings.get(userID)
+    const next = parseSettingsPatch(body, current)
+    // CON-09b: a machine that is not the user's is refused when it is saved, not only at enable. An unknown ID and
+    // another user's answer alike (no oracle). A machine saved earlier and removed since is only checked at enable.
+    if (next.machineID !== undefined && next.machineID !== current.machineID && !this.deps.machines(userID).some((m) => m.id === next.machineID)) {
+      throw new AgentError("not_found", "That machine is not one of yours: pick one of your machines")
+    }
+    const placementChanged = next.machineID !== current.machineID || next.directory !== current.directory || next.model !== current.model
+    if (current.enabled && placementChanged) this.checkPlacement(userID, next)
+    const grantTouched = isObject(body) && "grant" in body
+    const grantID = current.enabled && grantTouched ? await this.applyGrant(userID, next) : current.grantID
+    const settings = await this.withGrantID(userID, current.revision, grantID, () => next)
+    await this.deps.audit(userID, "concierge.settings")
+    const status = current.enabled && placementChanged ? await this.deps.supervisor.restart(userID) : await this.deps.supervisor.status(userID)
+    await this.durable()
+    return { settings, status }
+  }
+
+  async enable(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const expected = revisionOf(body, ["timeZone"])
+    const timeZone = (body as { timeZone?: unknown }).timeZone
+    if (timeZone !== undefined && !validTimeZone(timeZone)) throw new AgentError("invalid", "timeZone is an IANA time zone")
+    const entitled = await this.deps.entitlements.check(userID)
+    if (!entitled.ok) throw new AgentError("forbidden", entitled.reason)
+    const current = await this.deps.settings.get(userID)
+    checkRevision(current, expected)
+    this.checkPlacement(userID, current)
+    const grantID = await this.applyGrant(userID, current)
+    let settings: ConciergeSettings
+    try {
+      settings = await this.withGrantID(userID, expected, grantID, (s) => ({ ...s, enabled: true, ...(typeof timeZone === "string" && s.updatedAt === undefined ? { timeZone } : {}) }))
+    } catch (cause) {
+      if (grantID !== undefined && grantID !== current.grantID) await this.deps.grants.revoke(userID, grantID).catch(() => undefined)
+      throw cause
+    }
+    await this.deps.audit(userID, "concierge.enable")
+    const status = await this.deps.supervisor.enable(userID)
+    await this.durable()
+    return { settings, status }
+  }
+
+  async disable(userID: string, body: unknown): Promise<{ settings: ConciergeSettings; status: ConciergeStatus }> {
+    const expected = revisionOf(body)
+    const current = await this.deps.settings.get(userID)
+    checkRevision(current, expected)
+    if (current.enabled) await this.withGrantID(userID, expected, current.grantID, (s) => ({ ...s, enabled: false }))
+    const status = await this.deps.supervisor.disable(userID)
+    await this.durable()
+    return { settings: await this.deps.settings.get(userID), status }
+  }
+
+  async restart(userID: string): Promise<{ status: ConciergeStatus }> {
+    const settings = await this.deps.settings.get(userID)
+    if (!settings.enabled) throw new AgentError("conflict", "The Concierge is disabled: enable it first")
+    const entitled = await this.deps.entitlements.check(userID)
+    if (!entitled.ok) throw new AgentError("forbidden", entitled.reason)
+    // A suspended Concierge lost its grant: the user's Restart grants it again (the standing setting).
+    if (settings.grant && settings.grantID === undefined) {
+      const grantID = await this.applyGrant(userID, settings)
+      if (grantID !== undefined) await this.deps.settings.update(userID, (s) => ({ ...s, grantID }))
+    }
+    const status = await this.deps.supervisor.restart(userID)
+    await this.durable()
+    return { status }
+  }
+
+  /** Flushes the state store (see ServiceDeps.flush). */
+  private async durable(): Promise<void> {
+    await this.deps.flush?.()
+  }
+
+  notes(userID: string): Promise<ConciergeNotes> {
+    return this.deps.notes.get(userID)
+  }
+
+  async setNotes(userID: string, body: unknown): Promise<ConciergeNotes> {
+    const expected = revisionOf(body, ["text"])
+    const text = (body as { text?: unknown }).text
+    if (typeof text !== "string") throw new AgentError("invalid", "text is required (a string, at most 32 KiB)")
+    return this.deps.notes.put(userID, text, expected)
+  }
+}

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

@@ -0,0 +1,69 @@
+// CON-04 the routes a Concierge session may call (round-3 verify): its session tokens (act AND shell, the current
+// session and every previous one) reach ONLY the routes listed here; every other /api/agent route answers 403
+// forbidden {policy: "concierge"} before its handler runs. The check is central (agentApi's gate), so a route added
+// later is refused until it is listed here (fail closed).
+//
+// What the list keeps: reads (who, status, sessions, its inbox and messages), messages to @me and replies/declines
+// to asks addressed to it (the outbound rule narrows msg/ask/reply/decline further, inbound.ts), the grant-gated act
+// verbs, its own notes, its board and Decision reads, and the watchlist verbs. Nothing that puts its text in front
+// of another session (intake, artifacts, workspaces, side chats, profiles, names, intents, webhooks, teams…).
+// CON-06's own routes are added through the tiers slot (ConciergeTiers.routes), which are Concierge routes by design.
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+import type { AgentRoute } from "../agent/routes"
+import type { ConciergeIdentity } from "./watchlist-routes"
+
+const A = "/api/agent"
+const C = `${A}/concierge`
+
+export const CONCIERGE_SESSION_ROUTES: readonly { readonly method: string; readonly path: string }[] = [
+  { method: "GET", path: `${A}/whoami` },
+  { method: "GET", path: `${A}/who` },
+  { method: "GET", path: `${A}/status` },
+  { method: "GET", path: `${A}/sessions` },
+  { method: "GET", path: `${A}/sessions/:addr` },
+  { method: "POST", path: `${A}/msg` },
+  { method: "POST", path: `${A}/ask` },
+  { method: "POST", path: `${A}/reply` },
+  { method: "POST", path: `${A}/decline` },
+  { method: "GET", path: `${A}/inbox` },
+  { method: "GET", path: `${A}/messages/:id` },
+  ...["approve", "deny", "answer", "prompt", "stop"].map((verb) => ({ method: "POST", path: `${A}/sessions/:addr/${verb}` })),
+  { method: "GET", path: `${C}/notes` },
+  { method: "PUT", path: `${C}/notes` },
+  { method: "GET", path: `${C}/board` },
+  { method: "GET", path: `${C}/decisions` },
+  { method: "GET", path: `${C}/decisions/:id` },
+  { method: "GET", path: `${C}/watchlist` },
+  ...["watch", "unwatch", "mute", "unmute"].map((verb) => ({ method: "POST", path: `${C}/watchlist/${verb}` })),
+  // CON-06 (tiers.ts): proposals and arming. Proposals put no Concierge text in front of another session: free text
+  // (prompt, form answers) runs only after the user's tap.
+  { method: "POST", path: `${C}/proposals` },
+  { method: "GET", path: `${C}/arm` },
+  { 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` },
+]
+
+const key = (method: string, path: string) => `${method} ${path}`
+
+/**
+ * The gate agentApi runs for every session actor before the route's own checks: a Concierge session (current or
+ * previous) may call only the allow-list and `extra` (the tiers slot's routes). A failed identity read refuses.
+ */
+export function conciergeSessionGate(identity: ConciergeIdentity, extra: () => readonly AgentRoute[] = () => []): (actor: AgentActor, route: Pick<AgentRoute, "method" | "path">) => Promise<void> {
+  const allowed = new Set(CONCIERGE_SESSION_ROUTES.map((r) => key(r.method, r.path)))
+  return async (actor, route) => {
+    if (actor.kind !== "session") return
+    let concierge: boolean
+    try {
+      const current = await identity.current(actor.userID)
+      concierge = current.sessionID === actor.sessionID || current.hiddenSessionIDs.includes(actor.sessionID)
+    } catch {
+      concierge = true
+    }
+    if (!concierge) return
+    if (allowed.has(key(route.method, route.path)) || extra().some((r) => r.method === route.method && r.path === route.path)) return
+    throw new AgentError("forbidden", "The Concierge cannot use this route", { extra: { policy: "concierge" } })
+  }
+}

package/src/central/concierge/settings.ts

@@ -0,0 +1,217 @@
+// CON-04 Concierge settings (contract "Concierge service: settings, launch, supervise, hide, context"): one record
+// per user (collection `concierge`, key `settings`), edited only by the user (Settings → Concierge). A partial update
+// names `expectedRevision` (409 conflict {currentRevision} on a mismatch); unknown and read-only fields (enabled,
+// grantID, revision, updatedAt) are 400 invalid: enabling goes through POST /concierge/enable, the grant ID is the
+// hub's. `where: "hosted"` is reserved for C2 (422 unsupported {feature: "conciergeHosted"}). The grant spec becomes
+// a real grant held by @@concierge (grantInput); `launch` and `roles` are refused in C1. No grant is the default (a
+// read-and-notify Concierge); PRESET_GRANT is the conservative one Settings offers.
+import { CONCIERGE_LIMITS, CONCIERGE_ROLE, type ConciergeDigest, type ConciergeGrantSpec, type ConciergeGrantVerb, type ConciergeQuietHours, type ConciergeSettings } from "../../../packages/protocol/src/concierge"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "../agent/errors"
+import { canonicalProject, GRANT_MAX_ACTIONS_PER_HOUR, GRANT_PROJECTS_MAX, parseDuration, validateGrant } from "../agent/policy"
+import { CONCIERGE_COLLECTION } from "./notes"
+
+const KEY = "settings"
+export const BRAIN_UNSUPPORTED = "Brain is not available to the Concierge yet: its tools are an exact allow-list, and Brain's MCP tools cannot be pinned by name"
+const FIELDS = new Set(["where", "machineID", "directory", "model", "grant", "connectors", "timeZone", "quietHours", "quietAllowsUrgent", "digests", "expectedRevision"])
+const GRANT_FIELDS = new Set(["allow", "projects", "permissions", "allowAlways", "expires", "maxActionsPerHour"])
+export const CONCIERGE_GRANT_VERBS: readonly ConciergeGrantVerb[] = ["approve", "deny", "answer", "prompt", "stop"]
+const MACHINE = /^[A-Za-z0-9._-]{1,80}$/
+const MODEL = /^[A-Za-z0-9._-]{1,80}\/[!-~]{1,200}$/
+const CLOCK = /^([01]\d|2[0-3]):[0-5]\d$/
+const EXPIRES = /^(\d{1,4})([hd])$/
+const DIRECTORY_MAX = 4096
+const HOUR_MS = 3_600_000
+const EXPIRES_MAX_MS = 30 * 24 * HOUR_MS
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+export function defaultSettings(timeZone = "UTC"): ConciergeSettings {
+  return { enabled: false, where: "machine", connectors: { brain: false }, timeZone, quietAllowsUrgent: true, digests: [], revision: 0 }
+}
+
+/** The conservative grant Settings offers: answer and deny; approve read/edit inside the projects; never shell push/rm; 7 days. */
+export const PRESET_GRANT = (projects: readonly string[]): ConciergeGrantSpec => ({
+  allow: ["answer", "deny", "approve"],
+  projects: [...projects],
+  permissions: { allow: ["read", "edit"], never: ["shell:git push*", "shell:rm *"] },
+  allowAlways: false,
+  expires: "7d",
+  maxActionsPerHour: 60,
+})
+
+/** The grant routes' body for a Concierge grant spec (holder @@concierge). */
+export function grantInput(spec: ConciergeGrantSpec): Record<string, unknown> {
+  return {
+    holder: `@@${CONCIERGE_ROLE}`,
+    scope: { projects: [...spec.projects] },
+    allow: [...spec.allow],
+    permissions: { allow: [...spec.permissions.allow], never: [...spec.permissions.never] },
+    // (CON-13 decision) Never "always" for the Concierge, whatever an older stored spec says.
+    allowAlways: false,
+    expires: spec.expires,
+    maxActionsPerHour: spec.maxActionsPerHour,
+  }
+}
+
+export function validTimeZone(value: unknown): value is string {
+  if (typeof value !== "string" || !value || value.length > 64) return false
+  try {
+    new Intl.DateTimeFormat("en-GB", { timeZone: value })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function grantSpec(raw: unknown): ConciergeGrantSpec {
+  if (!isObject(raw)) throw invalid("grant is {allow, projects, permissions?, allowAlways?, expires?, maxActionsPerHour?}")
+  for (const key of Object.keys(raw)) if (!GRANT_FIELDS.has(key)) throw invalid(`Unknown grant field ${key.slice(0, 40)}`)
+  if (!Array.isArray(raw.allow) || raw.allow.length === 0) throw invalid(`grant.allow lists the verbs: ${CONCIERGE_GRANT_VERBS.join(", ")}`)
+  const allow: ConciergeGrantVerb[] = []
+  for (const verb of raw.allow) {
+    if (verb === "launch" || verb === "roles") throw invalid(`grant.allow: the Concierge cannot hold ${verb} in this version`)
+    if (!CONCIERGE_GRANT_VERBS.includes(verb)) throw invalid(`grant.allow: unknown verb ${String(verb).slice(0, 40)}`)
+    if (!allow.includes(verb)) allow.push(verb)
+  }
+  if (!Array.isArray(raw.projects) || raw.projects.length === 0 || raw.projects.length > GRANT_PROJECTS_MAX) throw invalid(`grant.projects lists 1–${GRANT_PROJECTS_MAX} project directories`)
+  const projects: string[] = []
+  for (const item of raw.projects) {
+    const canonical = canonicalProject(item as string)
+    if (canonical === undefined) throw invalid(`grant.projects: ${String(item).slice(0, 80)} is not an absolute project directory`)
+    if (!projects.includes(canonical)) projects.push(canonical)
+  }
+  let permissions = { allow: [] as string[], never: [] as string[] }
+  if (raw.permissions !== undefined) {
+    if (!isObject(raw.permissions)) throw invalid("grant.permissions is {allow?, never?}")
+    permissions = { allow: (raw.permissions.allow ?? []) as string[], never: (raw.permissions.never ?? []) as string[] }
+  }
+  if (raw.allowAlways !== undefined && typeof raw.allowAlways !== "boolean") throw invalid("grant.allowAlways is true or false")
+  if (raw.allowAlways === true) throw invalid("grant.allowAlways: the Concierge never approves “always” (that is always your tap)")
+  const expires = raw.expires ?? "30d"
+  const match = typeof expires === "string" ? EXPIRES.exec(expires) : null
+  const ms = match ? parseDuration(expires) : undefined
+  if (ms === undefined || ms < HOUR_MS || ms > EXPIRES_MAX_MS) throw invalid('grant.expires is "1h" to "30d"')
+  const cap = raw.maxActionsPerHour ?? 60
+  if (!Number.isInteger(cap) || (cap as number) < 1 || (cap as number) > GRANT_MAX_ACTIONS_PER_HOUR) throw invalid(`grant.maxActionsPerHour is a whole number 1–${GRANT_MAX_ACTIONS_PER_HOUR}`)
+  const spec: ConciergeGrantSpec = { allow, projects, permissions, allowAlways: false, expires: expires as string, maxActionsPerHour: cap as number }
+  // The grant validator has the last word on patterns (the same rules as every grant).
+  const checked = validateGrant(grantInput(spec))
+  return { ...spec, permissions: { allow: [...checked.permissions.allow], never: [...checked.permissions.never] } }
+}
+
+function quietHours(raw: unknown): ConciergeQuietHours {
+  if (!isObject(raw) || Object.keys(raw).some((k) => !["start", "end", "timeZone"].includes(k))) throw invalid("quietHours is {start, end, timeZone}")
+  if (typeof raw.start !== "string" || !CLOCK.test(raw.start) || typeof raw.end !== "string" || !CLOCK.test(raw.end)) throw invalid("quietHours start and end are HH:MM")
+  if (!validTimeZone(raw.timeZone)) throw invalid("quietHours.timeZone is an IANA time zone")
+  return { start: raw.start, end: raw.end, timeZone: raw.timeZone }
+}
+
+function digests(raw: unknown): ConciergeDigest[] {
+  if (!Array.isArray(raw) || raw.length > CONCIERGE_LIMITS.digests) throw invalid(`digests lists at most ${CONCIERGE_LIMITS.digests} entries`)
+  return raw.map((d) => {
+    if (!isObject(d) || Object.keys(d).some((k) => k !== "at" && k !== "days")) throw invalid("a digest is {at, days?}")
+    if (typeof d.at !== "string" || !CLOCK.test(d.at)) throw invalid("digest.at is HH:MM")
+    if (d.days === undefined) return { at: d.at }
+    if (!Array.isArray(d.days) || d.days.length === 0 || d.days.length > 7 || d.days.some((n) => !Number.isInteger(n) || n < 0 || n > 6) || new Set(d.days).size !== d.days.length) {
+      throw invalid("digest.days lists weekdays 0–6 (Sunday is 0)")
+    }
+    return { at: d.at, days: [...(d.days as (0 | 1 | 2 | 3 | 4 | 5 | 6)[])].sort() }
+  })
+}
+
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/
+
+/**
+ * The settings after a partial update by the user. Throws invalid, unsupported (hosted) or conflict (revision).
+ * Does not bump the revision (the store does).
+ */
+export function parseSettingsPatch(body: unknown, current: ConciergeSettings): ConciergeSettings {
+  if (!isObject(body)) throw invalid("The body is a partial settings object with expectedRevision")
+  for (const key of Object.keys(body)) {
+    if (key === "enabled") throw invalid("enabled changes through POST /api/agent/concierge/enable or /disable")
+    if (!FIELDS.has(key)) throw invalid(`Unknown or read-only field ${key.slice(0, 40)}`)
+  }
+  const expected = body.expectedRevision
+  if (!Number.isSafeInteger(expected)) throw invalid("expectedRevision is required")
+  if (expected !== current.revision) throw new AgentError("conflict", "The Concierge settings changed meanwhile", { extra: { currentRevision: current.revision } })
+  let next: { -readonly [K in keyof ConciergeSettings]: ConciergeSettings[K] } = { ...current }
+  const drop = (key: "machineID" | "directory" | "model" | "grant" | "quietHours") => {
+    const { [key]: _gone, ...rest } = next
+    next = rest as typeof next
+  }
+  if (body.where !== undefined) {
+    if (body.where === "hosted") throw new AgentError("unsupported", "A hosted Concierge is not available", { extra: { feature: "conciergeHosted" } })
+    if (body.where !== "machine") throw invalid('where is "machine"')
+  }
+  if (body.machineID !== undefined) {
+    if (body.machineID === null) drop("machineID")
+    else if (typeof body.machineID !== "string" || !MACHINE.test(body.machineID)) throw invalid("machineID is malformed")
+    else next.machineID = body.machineID
+  }
+  if (body.directory !== undefined) {
+    if (body.directory === null) drop("directory")
+    else {
+      const raw = body.directory
+      const canonical = typeof raw === "string" && raw.length <= DIRECTORY_MAX && !CONTROL.test(raw) ? canonicalProject(raw) : undefined
+      if (canonical === undefined || !canonical.startsWith("/")) throw invalid("directory is an absolute directory on the machine (a git repo under its workspace roots)")
+      next.directory = canonical
+    }
+  }
+  if (body.model !== undefined) {
+    if (body.model === null) drop("model")
+    else if (typeof body.model !== "string" || !MODEL.test(body.model)) throw invalid("model is provider/model")
+    else next.model = body.model
+  }
+  if (body.grant !== undefined) {
+    if (body.grant === null) drop("grant")
+    else next.grant = grantSpec(body.grant)
+  }
+  if (body.connectors !== undefined) {
+    const c = body.connectors
+    if (!isObject(c) || Object.keys(c).some((k) => k !== "brain") || typeof c.brain !== "boolean") throw invalid("connectors is {brain: true|false}")
+    // The Concierge's tools are an exact allow-list; Brain's MCP tools cannot be named exactly across machines (and
+    // Code Mode would expose every MCP tool), so Brain is not offered in C1.
+    if (c.brain) throw new AgentError("unsupported", BRAIN_UNSUPPORTED, { extra: { feature: "conciergeBrain", reason: BRAIN_UNSUPPORTED } })
+    next.connectors = { brain: false }
+  }
+  if (body.timeZone !== undefined) {
+    if (!validTimeZone(body.timeZone)) throw invalid("timeZone is an IANA time zone")
+    next.timeZone = body.timeZone
+  }
+  if (body.quietHours !== undefined) {
+    if (body.quietHours === null) drop("quietHours")
+    else next.quietHours = quietHours(body.quietHours)
+  }
+  if (body.quietAllowsUrgent !== undefined) {
+    if (typeof body.quietAllowsUrgent !== "boolean") throw invalid("quietAllowsUrgent is true or false")
+    next.quietAllowsUrgent = body.quietAllowsUrgent
+  }
+  if (body.digests !== undefined) next.digests = digests(body.digests)
+  return next
+}
+
+/** The user's settings record: version-checked writes, revision bumped by every write. */
+export class SettingsStore {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock = Date.now,
+  ) {}
+
+  async get(userID: string): Promise<ConciergeSettings> {
+    return (await this.state.get<ConciergeSettings>(userID, CONCIERGE_COLLECTION, KEY))?.value ?? defaultSettings()
+  }
+
+  /** Applies `change` to the stored settings (re-read on a lost race; `change` may throw) and stores revision + 1. */
+  async update(userID: string, change: (current: ConciergeSettings) => ConciergeSettings): Promise<ConciergeSettings> {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const stored = await this.state.get<ConciergeSettings>(userID, CONCIERGE_COLLECTION, KEY)
+      const current = stored?.value ?? defaultSettings()
+      const next: ConciergeSettings = { ...change(current), revision: current.revision + 1, updatedAt: this.now() }
+      const put = await this.state.put(userID, CONCIERGE_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
+      if (put.ok) return next
+    }
+    throw new AgentError("conflict", "The Concierge settings kept changing; retry")
+  }
+}