@huynle/hub 0.7.1 → 0.7.2

package/packages/sdk/src/client.ts

@@ -5,6 +5,9 @@ import { sseEvents } from "./sse.ts"
 import type {
   Approved,
   AppTokenView,
+  Archived,
+  ArchiveInactivePreview,
+  ArchiveInactiveResult,
   Asked,
   CreatedAppToken,
   Decision,
@@ -30,6 +33,7 @@ import type {
   Named,
   PromptDelivery,
   Prompted,
+  Pinned,
   Replied,
   RoleClaim,
   RoleRelease,
@@ -40,7 +44,10 @@ import type {
   Status,
   Stopped,
   WatchEvent,
+  EventsPage,
   Whoami,
+  WebhookDelivery,
+  WebhookView,
 } from "./types.ts"
 
 const AGENT = "/api/agent"
@@ -296,15 +303,16 @@ export class HubClient {
   }
 
   /**
-   * GET /api/agent/watch: the events (session.*, blocker.*, …) as they happen, until the hub closes the stream or
-   * `signal` aborts (which ends the iteration quietly). blocked: only blocker events; session: one address.
+   * GET /api/agent/watch: the journal's compact events (the same as events()) as they happen, until the hub closes
+   * the stream or `signal` aborts (which ends the iteration quietly). blocked: only blocker events; session: one
+   * address; cursor: resume after an event's `id` (or an events() cursor).
    */
-  async *watch(options: CallOptions & { readonly blocked?: boolean; readonly session?: string } = {}): AsyncGenerator<WatchEvent, void, undefined> {
+  async *watch(options: CallOptions & { readonly blocked?: boolean; readonly session?: string; readonly cursor?: string } = {}): AsyncGenerator<WatchEvent, void, undefined> {
     const { signal } = options
     if (signal?.aborted) return
     let response: Response
     try {
-      response = await this.request("GET", `${AGENT}/watch`, { query: { blocked: options.blocked ? "1" : undefined, session: options.session }, ...signalOf(options) })
+      response = await this.request("GET", `${AGENT}/watch`, { query: { blocked: options.blocked ? "1" : undefined, session: options.session, cursor: options.cursor }, ...signalOf(options) })
     } catch (cause) {
       if (signal?.aborted) return
       throw cause
@@ -312,6 +320,49 @@ export class HubClient {
     yield* sseEvents(response, signal)
   }
 
+  /**
+   * GET /api/agent/events: the compact events after `cursor` (none: start at the latest). wait: seconds (0–60) to
+   * hold while nothing matches; limit 1–200; types (exact, or `launch.*`) and sessions filter but still advance the
+   * cursor. App tokens need events:subscribe plus each family's scope.
+   */
+  events(options: CallOptions & { readonly cursor?: string; readonly wait?: number; readonly limit?: number; readonly types?: readonly string[]; readonly sessions?: readonly string[] } = {}): Promise<EventsPage> {
+    return this.call("GET", `${AGENT}/events`, { query: { cursor: options.cursor, wait: options.wait, limit: options.limit, type: options.types, session: options.sessions }, ...signalOf(options) })
+  }
+
+  webhookCreate(input: { readonly url: string; readonly events?: readonly string[]; readonly label?: string }, options: CallOptions = {}): Promise<{ webhook: WebhookView; secret: string }> {
+    return this.call("POST", `${AGENT}/webhooks`, { body: input, ...signalOf(options) })
+  }
+
+  webhooks(options: CallOptions = {}): Promise<{ webhooks: WebhookView[] }> {
+    return this.call("GET", `${AGENT}/webhooks`, signalOf(options))
+  }
+
+  webhook(id: string, options: CallOptions = {}): Promise<{ webhook: WebhookView; deliveries: WebhookDelivery[] }> {
+    return this.call("GET", `${AGENT}/webhooks/${segment(id)}`, signalOf(options))
+  }
+
+  webhookDelete(id: string, options: CallOptions = {}): Promise<void> {
+    return this.call("DELETE", `${AGENT}/webhooks/${segment(id)}`, signalOf(options))
+  }
+
+  // Organization (sessions:manage).
+
+  setArchived(addr: string, archived: boolean, options: CallOptions = {}): Promise<Archived> {
+    return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/archive`, { body: { archived }, ...signalOf(options) })
+  }
+
+  setPinned(addr: string, pinned: boolean, options: CallOptions = {}): Promise<Pinned> {
+    return this.call("PUT", `${AGENT}/sessions/${segment(addr)}/pin`, { body: { pinned }, ...signalOf(options) })
+  }
+
+  previewArchiveInactive(inactiveFor: string, limit: number, options: CallOptions = {}): Promise<ArchiveInactivePreview> {
+    return this.call("POST", `${AGENT}/sessions/archive-inactive`, { body: { preview: true, inactiveFor, limit }, ...signalOf(options) })
+  }
+
+  archiveInactive(previewToken: string, options: CallOptions = {}): Promise<ArchiveInactiveResult> {
+    return this.call("POST", `${AGENT}/sessions/archive-inactive`, { body: { previewToken, confirm: true }, ...signalOf(options) })
+  }
+
   // Naming.
 
   name(name: string, options: TargetOptions = {}): Promise<Named> {

package/packages/sdk/src/errors.ts

@@ -6,6 +6,7 @@ import type { Evaluation } from "./types.ts"
 /** The codes the hub answers with (src/central/agent/errors.ts); later phases may add more, so any string is kept. */
 export type ErrorCode =
   | "invalid"
+  | "invalid_cursor"
   | "unauthorized"
   | "token_expired"
   | "needs_user"

package/packages/sdk/src/sse.ts

@@ -5,6 +5,8 @@ import type { WatchEvent } from "./types.ts"
 /** Parses SSE text incrementally: feed chunks, get complete events (events without data are skipped). */
 export class SseParser {
   #buffer = ""
+  /** The last `id:` seen (it carries over to later events, as in EventSource). */
+  #id = ""
 
   push(chunk: string): WatchEvent[] {
     this.#buffer += chunk.replace(/\r\n?/g, "\n")
@@ -22,8 +24,9 @@ export class SseParser {
         const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "")
         if (field === "event") event = value
         else if (field === "data") data.push(value)
+        else if (field === "id" && !value.includes("\0")) this.#id = value
       }
-      if (data.length) out.push({ event, data: data.join("\n") })
+      if (data.length) out.push({ event, data: data.join("\n"), ...(this.#id ? { id: this.#id } : {}) })
     }
     return out
   }

package/packages/sdk/src/types.ts

@@ -121,6 +121,43 @@ export interface DirectoryEntry {
   readonly roles: readonly RoleView[]
 }
 
+/** One compact event of GET /api/agent/events (no free text). Unknown types are valid: ignore them. */
+export interface AgentEvent {
+  readonly id: string
+  readonly at: number
+  readonly type: string
+  readonly subject: Readonly<Record<string, string>>
+  readonly data: Readonly<Record<string, string | number | boolean>>
+}
+
+/**
+ * A page of GET /api/agent/events: pass `cursor` to the next call. `more`: records remain unread. `reset`: the
+ * cursor was no longer covered (expired, trimmed, hub restarted); re-read the `refresh` snapshots, then go on.
+ */
+export interface EventsPage {
+  readonly events: AgentEvent[]
+  readonly cursor: string
+  readonly more: boolean
+  readonly reset: boolean
+  readonly refresh?: string[]
+}
+
+export interface Archived {
+  readonly sessionID: string
+  readonly archived: boolean
+  readonly changed: boolean
+}
+
+export interface Pinned {
+  readonly sessionID: string
+  readonly pinned: boolean
+  readonly changed: boolean
+}
+
+export type ArchiveSkipReason = "active" | "pinned" | "open" | "archived" | "not_found"
+export interface ArchiveInactivePreview { readonly candidates: readonly string[]; readonly previewToken: string; readonly expiresAt: number }
+export interface ArchiveInactiveResult { readonly changed: readonly string[]; readonly skipped: readonly { readonly sessionID: string; readonly reason: ArchiveSkipReason }[] }
+
 export interface Named {
   readonly sessionID: string
   readonly name: string
@@ -271,6 +308,8 @@ export interface Inbox {
 export interface WatchEvent {
   readonly event: string
   readonly data: string
+  /** The stream's cursor at this event (GET /api/agent/watch?cursor= resumes after it). */
+  readonly id?: string
 }
 
 // Acting (POST /api/agent/sessions/:addr/{approve,deny,answer,prompt,stop}; src/central/agent/acting.ts).
@@ -430,6 +469,26 @@ export interface LaunchArtifacts {
   readonly dirty?: boolean
 }
 
+export interface WebhookView {
+  readonly id: string
+  readonly url: string
+  readonly events: readonly string[]
+  readonly by: string
+  readonly label?: string
+  readonly created: number
+}
+
+export interface WebhookDelivery {
+  readonly id: string
+  readonly event: string
+  readonly type: string
+  readonly state: "pending" | "delivered" | "failed"
+  readonly attempts: number
+  readonly created: number
+  readonly nextAt?: number
+  readonly last?: { readonly at: number; readonly status?: number; readonly error?: string }
+}
+
 /** A launch as the hub reports it (the spec with its defaults filled in). */
 export interface LaunchView {
   readonly id: string

package/packages/spoke-sdk/package.json

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

package/packages/spoke-sdk/src/enroll.ts

@@ -10,19 +10,40 @@ export interface EnrollOptions {
   readonly signal?: AbortSignal
   readonly fetch?: typeof fetch
   readonly now?: () => number
+  /**
+   * "follow" (default) follows HTTP redirects. "error" refuses them: a redirect could send the device code to
+   * another origin or downgrade to plain http. A refused redirect throws EnrollmentRefused, which polling does not
+   * retry.
+   */
+  readonly redirect?: "follow" | "error"
+  /**
+   * The hub hands out an approved credential exactly once. With keepRedeemed, `signal` never aborts a poll request
+   * in flight (its reply may carry that credential); it still stops polling before the next request.
+   */
+  readonly keepRedeemed?: boolean
+}
+
+/** The hub answered in a way the caller's policy refuses (a redirect under redirect: "error"); not retried. */
+export class EnrollmentRefused extends Error {
+  override readonly name = "EnrollmentRefused"
 }
 
 const REQUEST_TIMEOUT_MS = 15_000
 
-async function post(server: string, path: string, body: unknown, options: EnrollOptions): Promise<unknown> {
+async function post(server: string, path: string, body: unknown, options: EnrollOptions, abortable = true): Promise<unknown> {
   const doFetch = options.fetch ?? fetch
-  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal ? [options.signal] : [])]
+  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), ...(options.signal && abortable ? [options.signal] : [])]
+  const strict = options.redirect === "error"
   const response = await doFetch(`${server.replace(/\/+$/, "")}${path}`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify(body),
     signal: AbortSignal.any(signals),
+    ...(strict ? { redirect: "manual" as const } : {}),
   })
+  if (strict && (response.type === "opaqueredirect" || (response.status >= 300 && response.status < 400))) {
+    throw new EnrollmentRefused(`${path} was redirected; enrollment does not follow redirects`)
+  }
   if (!response.ok) throw new Error(`${path} failed: HTTP ${response.status}`)
   return response.json()
 }
@@ -67,8 +88,9 @@ export async function pollEnrollment(server: string, start: EnrollStart, options
     if (options.signal?.aborted) return { status: "cancelled" }
     let reply: Partial<EnrollPoll> & Record<string, unknown>
     try {
-      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options)) as typeof reply
-    } catch {
+      reply = (await post(server, "/spoke/enroll/poll", { deviceCode: start.deviceCode }, options, !options.keepRedeemed)) as typeof reply
+    } catch (cause) {
+      if (cause instanceof EnrollmentRefused) throw cause
       continue
     }
     if (reply?.status === "approved" && typeof reply.machineID === "string" && typeof reply.machineToken === "string") {

package/src/central/agent/app-tokens.ts

@@ -19,8 +19,10 @@ import type { AgentRoute } from "./routes"
  * acting on sessions (approve, deny, answer, prompt, stop) and launching sessions (phase 4), each of which still
  * needs a grant held by the token (with the act verb, or `launch` covering the repo).
  */
-export const APP_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read", "sessions:act", "sessions:launch"]
+export const APP_SCOPES: readonly string[] = ["sessions:read", "sessions:manage", "messages:send", "messages:read", "sessions:act", "sessions:launch", "events:subscribe"]
 export const DEFAULT_APP_SCOPES: readonly string[] = ["sessions:read"]
+/** What `hub login` (the CLI login device code) asks for unless it asks for more: reading sessions and messaging. */
+export const DEFAULT_CLI_LOGIN_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read"]
 export const MAX_APP_TOKENS = 50
 export const MAX_APP_TOKEN_LABEL = 100
 
@@ -88,6 +90,29 @@ const view = (token: AppToken) => ({
   ...(typeof token.created === "number" ? { created: token.created } : {}),
 })
 
+/**
+ * Issues an app token of `userID` (the POST route below, and an approved CLI login): the record stored (sha256 of the
+ * token only) and the token, which the caller hands out once and never logs. rate_limited at MAX_APP_TOKENS.
+ */
+export async function issueAppToken(store: Store, userID: string, input: { readonly label?: string; readonly scopes: readonly string[] }): Promise<{ record: AppToken; token: string }> {
+  const id = randomBytes(8).toString("hex")
+  const token = `hat_${id}_${randomBytes(32).toString("base64url")}`
+  const record: AppToken = { id, tokenHash: hashToken(token), ...(input.label ? { label: input.label } : {}), scopes: [...input.scopes], created: Date.now() }
+  let full = false
+  await store.updateAgentData(userID, (data) => {
+    const tokens = data.appTokens ?? []
+    full = false
+    if (tokens.length >= MAX_APP_TOKENS) {
+      full = true
+      return
+    }
+    data.appTokens = [...tokens, record]
+  })
+  if (full) throw new AgentError("rate_limited", `At most ${MAX_APP_TOKENS} app tokens per user`, { hint: "Revoke unused tokens" })
+  await store.audit({ actor: userID, action: "app-token.create", target: id, ...(input.label ? { detail: input.label } : {}) })
+  return { record, token }
+}
+
 /** POST, GET and DELETE /api/agent/app-tokens: user actors only. */
 export function appTokenRoutes(store: Store): AgentRoute[] {
   return [
@@ -96,22 +121,7 @@ export function appTokenRoutes(store: Store): AgentRoute[] {
       path: PREFIX,
       allow: {},
       async handle({ request, user }) {
-        const input = parseCreate(await request.json())
-        const id = randomBytes(8).toString("hex")
-        const token = `hat_${id}_${randomBytes(32).toString("base64url")}`
-        const record: AppToken = { id, tokenHash: hashToken(token), ...(input.label ? { label: input.label } : {}), scopes: input.scopes, created: Date.now() }
-        let full = false
-        await store.updateAgentData(user.id, (data) => {
-          const tokens = data.appTokens ?? []
-          full = false
-          if (tokens.length >= MAX_APP_TOKENS) {
-            full = true
-            return
-          }
-          data.appTokens = [...tokens, record]
-        })
-        if (full) throw new AgentError("rate_limited", `At most ${MAX_APP_TOKENS} app tokens per user`, { hint: "Revoke unused tokens" })
-        await store.audit({ actor: user.id, action: "app-token.create", target: id, ...(input.label ? { detail: input.label } : {}) })
+        const { record, token } = await issueAppToken(store, user.id, parseCreate(await request.json()))
         return Response.json({ ...view(record), token }, { status: 201, headers: NO_STORE })
       },
     },

package/src/central/agent/archive-inactive.ts

@@ -0,0 +1,66 @@
+import { createHmac, timingSafeEqual } from "node:crypto"
+import type { DirectoryEntry } from "./directory"
+import { AgentError } from "./errors"
+
+const PREFIX = "hai1_"
+const DOMAIN = "hub-archive-inactive/v1"
+const TTL_MS = 5 * 60_000
+const invalid = () => new AgentError("invalid", "This inactive-archive preview is invalid or expired; preview again")
+
+interface Payload { readonly userID: string; readonly at: number; readonly inactiveForMs: number; readonly candidates: readonly string[] }
+export interface ArchiveSets { readonly pinned: ReadonlySet<string>; readonly archived: ReadonlySet<string> }
+export type SkipReason = "active" | "pinned" | "open" | "archived" | "not_found"
+
+export class ArchiveInactive {
+  constructor(private readonly options: { readonly secret: Buffer; readonly now?: () => number }) {}
+  private now() { return (this.options.now ?? Date.now)() }
+
+  preview(userID: string, sessions: readonly DirectoryEntry[], options: ArchiveSets & { readonly inactiveForMs: number; readonly limit: number }) {
+    const candidates = sessions
+      .filter((s) => !s.online && typeof s.lastSeen === "number" && this.now() - s.lastSeen >= options.inactiveForMs && !options.pinned.has(s.sessionID) && !options.archived.has(s.sessionID))
+      .map((s) => s.sessionID).slice(0, options.limit)
+    const payload: Payload = { userID, at: this.now(), inactiveForMs: options.inactiveForMs, candidates }
+    return { candidates, previewToken: this.encode(payload), expiresAt: payload.at + TTL_MS }
+  }
+
+  decode(userID: string, token: string): Payload {
+    if (!token.startsWith(PREFIX) || token.length > 10_000) throw invalid()
+    const [body, tag, ...rest] = token.slice(PREFIX.length).split(".")
+    if (rest.length || !body || !tag) throw invalid()
+    const expected = createHmac("sha256", this.options.secret).update(`${DOMAIN}\n${body}`).digest().subarray(0, 16)
+    const given = Buffer.from(tag, "base64url")
+    if (given.length !== expected.length || !timingSafeEqual(given, expected)) throw invalid()
+    let payload: Payload
+    try { payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as Payload } catch { throw invalid() }
+    if (payload.userID !== userID || !Array.isArray(payload.candidates) || this.now() - payload.at > TTL_MS) throw invalid()
+    return payload
+  }
+
+  revalidate(userID: string, token: string, sessions: readonly DirectoryEntry[], options: ArchiveSets & { readonly open: ReadonlySet<string>; readonly active: ReadonlySet<string> }) {
+    const payload = this.decode(userID, token)
+    const byID = new Map(sessions.map((s) => [s.sessionID, s]))
+    const candidates: string[] = []
+    const skipped: Array<{ sessionID: string; reason: SkipReason }> = []
+    for (const sessionID of payload.candidates) {
+      const s = byID.get(sessionID)
+      const reason: SkipReason | undefined = !s ? "not_found" : options.archived.has(sessionID) ? "archived" : options.pinned.has(sessionID) ? "pinned" : options.open.has(sessionID) ? "open" : options.active.has(sessionID) || s.online ? "active" : undefined
+      if (reason) skipped.push({ sessionID, reason }); else candidates.push(sessionID)
+    }
+    return { candidates, skipped }
+  }
+
+  private encode(payload: Payload) {
+    const body = Buffer.from(JSON.stringify(payload)).toString("base64url")
+    const tag = createHmac("sha256", this.options.secret).update(`${DOMAIN}\n${body}`).digest().subarray(0, 16).toString("base64url")
+    return `${PREFIX}${body}.${tag}`
+  }
+}
+
+export function parseInactiveFor(value: unknown): number {
+  if (typeof value !== "string") throw new AgentError("invalid", "inactiveFor must be a duration such as 7d")
+  const m = /^(\d+)(h|d)$/.exec(value)
+  if (!m) throw new AgentError("invalid", "inactiveFor must be a duration such as 7d")
+  const ms = Number(m[1]) * (m[2] === "d" ? 86_400_000 : 3_600_000)
+  if (ms < 3_600_000 || ms > 365 * 86_400_000) throw new AgentError("invalid", "inactiveFor must be from 1h to 365d")
+  return ms
+}

package/src/central/agent/directory-routes.ts

@@ -7,15 +7,30 @@
 //   POST /api/agent/name           {name, session?}
 //   POST /api/agent/roles/claim    {role, exclusive?, project?, session?}
 //   POST /api/agent/roles/release  {role, project?, session?}
+//   PUT  /api/agent/sessions/:addr/archive {archived}
 // `session` is an address (ses_…, ID prefix, @name, …) resolved for the caller; a session token defaults to
-// its own session, a user must name one.
+// its own session, a user or app must name one. Foreign and unknown sessions are both not_found.
+//
+// App tokens (lifecycle design, decision xwzersmm): naming and archiving need sessions:manage; a role claim or
+// release also needs a grant allowing `roles` whose projects cover the (live) session's directory, in the acting
+// order (kill switch → grant → hourly cap → kill switch), with every outcome in the agent audit (verb roles or
+// roles.release). Reserved roles stay the user's to assign. Each change is in the admin audit and the event
+// journal once (session.named, role.claimed, role.released, session.archived); a no-op is neither.
+import type { ActingSwitch } from "./acting-switch"
+import { auditOf } from "./acting"
+import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
+import { partyFromActor } from "./envelope"
+import { type AgentEvents, archiveEvent, type EventInput, namedEvent, pinnedEvent, roleEvent } from "./events"
+import type { Grant, Grants } from "./grants"
 import path from "node:path"
-import type { CatalogMachine, RegistryMessage } from "../registry"
+import type { CatalogMachine, Registry, RegistryMessage } from "../registry"
 import type { Store } from "../store"
 import { Directory, type ReportedSession, type SessionSource } from "./directory"
 import { AgentError } from "./errors"
+import { ArchiveInactive, parseInactiveFor } from "./archive-inactive"
 import { slugify } from "./names"
 import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
+import type { CursorKeys } from "./event-cursor"
 
 /** What the directory reads from the Registry. */
 export interface DirectoryRegistry {
@@ -127,8 +142,120 @@ function target(directory: Directory, { actor, user }: AgentContext, addr: strin
 const NO_STORE = { "cache-control": "no-store" }
 const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
 
-export function directoryRoutes(directory: Directory): AgentRoute[] {
+export interface DirectoryRoutesDeps {
+  readonly directory: Directory
+  readonly store: Pick<Store, "setSessionArchived" | "setSessionPinned" | "archiveSessionIfUnpinned" | "viewPrefs" | "agentData" | "audit">
+  readonly events?: Pick<AgentEvents, "append">
+  /** App role writes: the live session (its directory, for the grant's projects). */
+  readonly registry?: Pick<Registry, "sessionTenant" | "session">
+  readonly grants?: Pick<Grants, "usable" | "consume">
+  readonly acting?: Pick<ActingSwitch, "ensureActing">
+  readonly audit?: Pick<AgentAudit, "record">
+  readonly previewKeys?: CursorKeys
+}
+
+const MANAGE = { session: true, scope: "sessions:manage" } as const
+
+export function directoryRoutes(deps: DirectoryRoutesDeps): AgentRoute[] {
+  const { directory, store, events } = deps
+
+  /** The admin audit and the journal, once per change. */
+  async function changed(context: AgentContext, action: string, sessionID: string, event: EventInput): Promise<void> {
+    await store.audit({ actor: context.user.id, action, target: sessionID, detail: context.actor.kind })
+    await events?.append(context.user.id, event).catch((cause) => console.error(`[hub] ${event.type} event failed: ${(cause as Error).message}`))
+  }
+
+  /** A role write: users and sessions as before; an app under a `roles` grant on the session's project, audited. */
+  async function roleWrite<T>(context: AgentContext, verb: "roles" | "roles.release", sessionID: string, run: () => Promise<T>): Promise<T> {
+    const { actor, user } = context
+    if (actor.kind !== "app") return run()
+    const { registry, grants, acting, audit } = deps
+    if (!registry || !grants || !acting || !audit) throw new AgentError("forbidden", "This hub does not let app tokens change roles")
+    let grant: Grant | undefined
+    const record = (decision: AuditDecision, outcome: AuditOutcome, reason?: string) =>
+      audit.record(user.id, { actor: partyFromActor(actor), verb, target: { sessionID }, ...(grant ? { grant: grant.id } : {}), decision, ...(reason ? { reason } : {}), outcome })
+    try {
+      acting.ensureActing(user.id)
+      const live = registry.sessionTenant(sessionID) === user.id ? registry.session(sessionID) : undefined
+      if (!live) throw new AgentError("offline", "No spoke reports this session now, so its project cannot be checked against a grant")
+      const usable = await grants.usable(actor, "roles", { directory: live.directory })
+      if (!usable.length) throw new AgentError("forbidden", "No grant lets this app change roles in this session's project")
+      grant = usable[0]!
+      await grants.consume(grant)
+      acting.ensureActing(user.id)
+      const result = await run()
+      await record("allow", "ok")
+      return result
+    } catch (cause) {
+      const [decision, outcome] = auditOf(cause)
+      await record(decision, outcome, cause instanceof Error ? cause.message : undefined)
+      throw cause
+    }
+  }
+
   return [
+    ...(deps.previewKeys ? [{
+      method: "POST" as const,
+      path: `${AGENT_PREFIX}/sessions/archive-inactive`,
+      allow: { scope: "sessions:manage" },
+      async handle(context: AgentContext) {
+        const inactive = new ArchiveInactive({ secret: deps.previewKeys!.active().secret })
+        const body = await readBody(context.request)
+        const prefs = store.viewPrefs(context.user.id)
+        const entries = (store.agentData(context.user.id).sessions ?? []).map((s) => ({ sessionID: s.sessionID, online: !!deps.registry?.session(s.sessionID), ...(s.lastSeen !== undefined ? { lastSeen: s.lastSeen } : {}), roles: [] }))
+        if (body.preview === true) {
+          const limit = body.limit
+          if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 200) throw new AgentError("invalid", "limit must be a whole number from 1 to 200")
+          return ok(inactive.preview(context.user.id, entries, { pinned: new Set(prefs.pinnedSessions), archived: new Set(prefs.hiddenSessions), inactiveForMs: parseInactiveFor(body.inactiveFor), limit: Number(limit) }))
+        }
+        if (body.confirm !== true || typeof body.previewToken !== "string") throw new AgentError("invalid", "Use preview:true first, then confirm:true with its previewToken")
+        const open = new Set(entries.filter((s) => deps.registry?.session(s.sessionID)?.open).map((s) => s.sessionID))
+        const active = new Set(entries.filter((s) => { const v = deps.registry?.session(s.sessionID); return !!v && (v.busy || v.status.some((x) => x.state === "working" || x.state === "blocked")) }).map((s) => s.sessionID))
+        const checked = inactive.revalidate(context.user.id, body.previewToken, entries, { pinned: new Set(prefs.pinnedSessions), archived: new Set(prefs.hiddenSessions), open, active })
+        const changedIDs: string[] = []
+        const skipped = [...checked.skipped]
+        for (const sessionID of checked.candidates) {
+          const result = await store.archiveSessionIfUnpinned(context.user.id, sessionID)
+          if (result === "changed") { changedIDs.push(sessionID); await changed(context, "session.archive", sessionID, archiveEvent(sessionID, true)) }
+          else skipped.push({ sessionID, reason: result === "pinned" ? "pinned" : result === "not_found" ? "not_found" : "archived" })
+        }
+        if (changedIDs.length) await directory.sync(context.user.id)
+        return ok({ changed: changedIDs, skipped })
+      },
+    }] : []),
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/sessions/:addr/pin`,
+      allow: { scope: "sessions:manage" },
+      async handle(context) {
+        const body = await readBody(context.request)
+        if (flag(body, "pinned") === undefined) throw new AgentError("invalid", "pinned must be true or false")
+        const sessionID = target(directory, context, context.params.addr)
+        const pinned = body.pinned === true
+        const result = await store.setSessionPinned(context.user.id, sessionID, pinned)
+        if (!result) throw new AgentError("not_found", `No session ${context.params.addr}`)
+        if (result.changed) await changed(context, pinned ? "session.pin" : "session.unpin", sessionID, pinnedEvent(sessionID, pinned))
+        return ok({ sessionID, pinned, changed: result.changed })
+      },
+    },
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/sessions/:addr/archive`,
+      allow: { scope: "sessions:manage" },
+      async handle(context) {
+        const body = await readBody(context.request)
+        if (flag(body, "archived") === undefined) throw new AgentError("invalid", "archived must be true or false")
+        const sessionID = target(directory, context, context.params.addr)
+        const archived = body.archived === true
+        const result = await store.setSessionArchived(context.user.id, sessionID, archived)
+        if (!result) throw new AgentError("invalid", "The archive is full; unarchive a session first")
+        if (result.changed) {
+          await directory.sync(context.user.id)
+          await changed(context, archived ? "session.archive" : "session.unarchive", sessionID, archiveEvent(sessionID, archived))
+        }
+        return ok({ sessionID, archived, changed: result.changed })
+      },
+    },
     {
       method: "GET",
       path: `${AGENT_PREFIX}/who`,
@@ -143,28 +270,39 @@ export function directoryRoutes(directory: Directory): AgentRoute[] {
     {
       method: "POST",
       path: `${AGENT_PREFIX}/name`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const name = text(body, "name", true)
         const sessionID = target(directory, context, text(body, "session"))
-        return ok(await directory.setName(context.user.id, sessionID, name))
+        const before = directory.resolveOne(context.user.id, sessionID).name
+        const named = await directory.setName(context.user.id, sessionID, name)
+        if (named.name !== before) await changed(context, "session.name", sessionID, namedEvent(sessionID, named.name))
+        return ok(named)
       },
     },
     {
       method: "POST",
       path: `${AGENT_PREFIX}/roles/claim`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const role = text(body, "role", true)
         const exclusive = flag(body, "exclusive")
         const project = text(body, "project")
         const sessionID = target(directory, context, text(body, "session"))
-        const claim = await directory.claimRole(context.user.id, sessionID, role, {
-          ...(exclusive !== undefined ? { exclusive } : {}),
-          ...(project !== undefined ? { project } : {}),
-          byUser: context.actor.kind === "user",
+        const claim = await roleWrite(context, "roles", sessionID, async () => {
+          const before = directory.resolveOne(context.user.id, sessionID).roles
+          const claim = await directory.claimRole(context.user.id, sessionID, role, {
+            ...(exclusive !== undefined ? { exclusive } : {}),
+            ...(project !== undefined ? { project } : {}),
+            byUser: context.actor.kind === "user",
+          })
+          const prev = before.find((r) => r.role === claim.role && r.project === claim.project)
+          if (!prev || prev.generation !== claim.generation || !!prev.exclusive !== !!claim.exclusive) {
+            await changed(context, "role.claim", sessionID, roleEvent(sessionID, true, claim))
+          }
+          return claim
         })
         return ok({ sessionID, ...claim })
       },
@@ -172,13 +310,18 @@ export function directoryRoutes(directory: Directory): AgentRoute[] {
     {
       method: "POST",
       path: `${AGENT_PREFIX}/roles/release`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const role = text(body, "role", true)
         const project = text(body, "project")
         const sessionID = target(directory, context, text(body, "session"))
-        return ok({ sessionID, ...(await directory.releaseRole(context.user.id, sessionID, role, project)), released: true })
+        const released = await roleWrite(context, "roles.release", sessionID, async () => {
+          const released = await directory.releaseRole(context.user.id, sessionID, role, project)
+          await changed(context, "role.release", sessionID, roleEvent(sessionID, false, released))
+          return released
+        })
+        return ok({ sessionID, ...released, released: true })
       },
     },
   ]

package/src/central/agent/directory.ts

@@ -207,7 +207,7 @@ export class Directory {
   /**
    * Claims `role` (or `role.project`) for a session. Each new holder gets the next holder generation of
    * (role, project). An exclusive claim fails (name_taken) while another live holder exists, and nobody else
-   * can claim while an exclusive holder is live. Reserved roles (orchestrator…, concierge…) need `byUser`
+   * can claim while an exclusive holder is live. Reserved roles (orchestrator…) need `byUser`
    * (grants with `roles` come in phase 3). Exclusivity and generations are per (role, project scope).
    */
   async claimRole(userID: string, sessionID: string, requested: string, options: { exclusive?: boolean; project?: string; byUser?: boolean } = {}): Promise<RoleView> {

package/src/central/agent/errors.ts

@@ -5,6 +5,8 @@
 export const AGENT_ERROR_STATUS = {
   /** Malformed request (bad JSON, bad fields, cookie and bearer together). */
   invalid: 400,
+  /** An events cursor this hub did not give this user, or cannot read (start again without one). */
+  invalid_cursor: 400,
   /** No credential, or an unknown, revoked or disabled one. */
   unauthorized: 401,
   /** A session or app token that expired: get a new one. */