@huynle/hub 0.7.4 → 0.8.1

package/src/central/main.ts

@@ -68,7 +68,7 @@ Usage: hub-server [--help | --version]   (also installed as opencode-hub and ope
 Configuration: environment variables over ~/.config/hub/hub.json ($HUB_CONFIG).
   HUB_HOST / HUB_PORT       listen address (default 127.0.0.1 / 4097)
   HUB_PUBLIC_URL            origin used in links and cookies (default http://<host>:<port>)
-  HUB_STATE_DIR             machines, devices, keys (default ~/.local/state/hub)
+  HUB_STATE_DIR             machines, devices, keys (default $XDG_STATE_HOME/hub or ~/.local/state/hub)
   OPENROUTER_API_KEY        default speech key; or set speech providers in the web app (Settings → Speech)
   HUB_CONFIG                path of hub.json
 

package/src/central/mcp-http.ts

@@ -10,6 +10,7 @@
 // refused (DNS rebinding); requests without one (servers, gateways) are fine. Tokens are never echoed.
 import { createMcpServer, MCP_PROTOCOL_VERSIONS, NOT_FROM_USER, RPC, rpcError, type RpcResponse } from "../../packages/cli/src/mcp"
 import { readCredentials } from "./agent/actor"
+import { bodyError, readBounded } from "./agent/body"
 
 export const MCP_PATH = "/mcp"
 
@@ -44,25 +45,12 @@ const answer = (response: RpcResponse) =>
   // A message the server could not take (parse error, not a request, a batch) carries no id: HTTP 400.
   Response.json(response, { status: response.error && response.id === null ? 400 : 200, headers: NO_STORE })
 
-/** The body as text, or undefined when it is over `max` bytes (read no further). */
-async function readCapped(request: Request, max: number): Promise<string | undefined> {
-  const length = Number(request.headers.get("content-length") ?? "")
-  if (Number.isFinite(length) && length > max) return undefined
-  if (!request.body) return ""
-  const reader = request.body.getReader()
-  const chunks: Uint8Array[] = []
-  let size = 0
-  for (;;) {
-    const { done, value } = await reader.read()
-    if (done) break
-    size += value.byteLength
-    if (size > max) {
-      void reader.cancel().catch(() => {})
-      return undefined
-    }
-    chunks.push(value)
-  }
-  return new TextDecoder().decode(Buffer.concat(chunks))
+/** The body as text, or why not (over `max` bytes or too slow; agent/body.ts bounds the bytes and time read). */
+async function readCapped(request: Request, max: number): Promise<{ readonly text: string } | { readonly status: 400 | 413; readonly message: string; readonly close: boolean }> {
+  const body = await readBounded(request, max)
+  if (body.ok) return { text: new TextDecoder().decode(body.bytes) }
+  if (body.reason === "timeout") return { status: 400, message: bodyError(body, max).message, close: true }
+  return { status: 413, message: `Request body over ${max} bytes`, close: body.close }
 }
 
 const acceptsJSON = (accept: string | null) => {
@@ -89,8 +77,9 @@ export function mcpHttp(deps: McpHttpDeps): (request: Request) => Promise<Respon
     const type = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase()
     if (type !== "application/json") return failure(415, "invalid", "Content-Type must be application/json")
     if (!acceptsJSON(request.headers.get("accept"))) return failure(406, "invalid", "Accept must allow application/json")
-    const text = await readCapped(request, max)
-    if (text === undefined) return failure(413, "invalid", `Request body over ${max} bytes`)
+    const read = await readCapped(request, max)
+    if (!("text" in read)) return failure(read.status, "invalid", read.message, read.close ? { connection: "close" } : {})
+    const text = read.text
     let message: unknown
     try {
       message = JSON.parse(text)

package/src/central/profiles/apply.ts

@@ -0,0 +1,333 @@
+// Profile application (HWA-15; contract: Profiles in docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md and
+// packages/protocol/src/profiles.ts). Plugs into ProfileStore's `ack` seam and applies a session's pinned version
+// through the session's spoke:
+//
+// - Only the spoke that owns the session (registry.owner) and belongs to the pin's tenant is ever sent the op, and
+//   only when it announced the spoke feature `profileApply` (never implied for older spokes). Otherwise the pin is
+//   recorded `unsupported` (naming the harness) or `pending` with `offline` (no spoke reports the session now).
+// - The PUT answers at once with `pending`; the spoke's ProfileApplyResult is recorded when it arrives: applied,
+//   partial, rejected, restart_required or unsupported. A result that names another session, profile, version or
+//   digest, or is malformed, is recorded as `rejected` ("invalid acknowledgment"), never as applied. A result for a
+//   pin that changed meanwhile is dropped (recordAck checks the revision). applied/partial become the session's
+//   `effective` version; restart_required does not (it becomes effective when the restarted session's spoke is
+//   sent the pin again).
+// - Per session, sends are serialized: a newer pin waits for the one in flight, and pins superseded while waiting
+//   are skipped (only the latest is sent). Sends overall are bounded (`concurrency`).
+// - Reconnect: when a sessions frame shows a session's owner on a connection the pin was not last sent through, the
+//   pin is sent again (adapters treat a repeated digest as idempotent), except a `rejected` one (the harness refused
+//   that digest; the user re-pins) and an `unsupported` one the new connection still cannot serve. The last-sent
+//   map is in memory and bounded (`trackedSessions`); losing it (hub restart, another pod) only costs an idempotent
+//   re-send. Each pod handles the spokes connected to it; requests to another pod's spoke go through SpokeHub's pod
+//   RPC with the pin's tenant.
+// - Errors: the spoke's own error is `rejected` with its reason (bounded, control characters removed); a timeout
+//   or unreachable spoke stays `pending` (re-sent on the spoke's next sessions frame or reconnect); a disconnect is
+//   `pending` + `offline`.
+// - Events: `profile.ack` (family manage) carries IDs, version, revision and status only, never notes.
+// - Launch: applyAtLaunch pins the launch's explicit version and waits (bounded) for the acknowledgment so the
+//   launch's prompt runs with it; every outcome becomes a launch note, never a failed launch.
+// - Authority: pinning confers nothing. An app token pinning a profile also needs a usable prompt grant on the
+//   session (pinAuthorizer), which is spent like a prompt; the acting switch pauses it.
+// - Secrets: the op carries `{{secret:NAME}}` references only. Central never resolves them; the spoke/adapter
+//   resolves them on its machine when a command is rendered, and never reports values back (notes name secrets at
+//   most).
+import {
+  type AgentProfileVersion,
+  type LaunchAgentProfile,
+  PROFILE_APPLY_FEATURE,
+  PROFILE_APPLY_LIMITS,
+  type ProfileAck,
+  type ProfileApplyRequest,
+  type ProfileApplyResult,
+  profileApplyResultProblem,
+  type ProfileAssignment,
+  type ServerRequest,
+  type SpokeFeature,
+} from "../../protocol"
+import type { ActingSwitch } from "../agent/acting-switch"
+import type { AgentActor } from "../agent/actor"
+import { AgentError } from "../agent/errors"
+import type { AgentEvents } from "../agent/events"
+import type { Grants } from "../agent/grants"
+import type { Clock } from "../backend/types"
+import { RequestTimeoutError, RequestTooLargeError, SpokeError } from "../spoke-ws"
+import { profileAckEvent } from "./events"
+import type { ProfileStore } from "./store"
+
+/** What the service reads of the registry (Registry implements it). */
+export interface ApplyRegistry {
+  owner(sessionID: string): string | undefined
+  supports(connID: string, feature: SpokeFeature): boolean
+  harnessOf(connID: string): string | undefined
+  sessionTenant(sessionID: string): string | undefined
+  reportedSessions(connID: string): string[]
+  session(sessionID: string): { readonly directory: string } | undefined
+  onSessions(listener: (connID: string) => void): () => void
+}
+
+/** Hub → spoke requests (SpokeHub.request). */
+export interface ApplySpokes {
+  request(connID: string, req: ServerRequest, options?: { readonly tenant?: string }): Promise<unknown>
+}
+
+export interface ProfileApplyLimits {
+  /** Spoke requests in flight at once (per hub process). */
+  readonly concurrency: number
+  /** Sessions whose last-sent connection is remembered for reconnects. */
+  readonly trackedSessions: number
+  /** How long a launch waits for its profile's acknowledgment before prompting anyway. */
+  readonly launchWaitMs: number
+}
+
+export const PROFILE_APPLY_SERVICE_LIMITS: ProfileApplyLimits = { concurrency: 4, trackedSessions: 10_000, launchWaitMs: 30_000 }
+
+export interface ProfileApplierDeps {
+  readonly profiles: Pick<ProfileStore, "assignment" | "version" | "recordAck" | "assign">
+  readonly registry: ApplyRegistry
+  readonly spokes: ApplySpokes
+  readonly events?: Pick<AgentEvents, "append">
+  readonly now?: Clock
+  readonly limits?: Partial<ProfileApplyLimits>
+}
+
+type Target = { readonly kind: "offline" } | { readonly kind: "unsupported"; readonly connID: string; readonly harness: string } | { readonly kind: "online"; readonly connID: string }
+
+interface SendOptions {
+  /** Send only while the pin still has this revision (a pin's own send); absent: the current pin (reconnect). */
+  readonly revision?: number
+  /** Sent because the session showed up on a new connection. */
+  readonly reconnect?: boolean
+}
+
+const OFFLINE_NOTE = "no spoke reports this session now; the hub applies the pin when one does"
+const TIMEOUT_NOTE = "the spoke did not answer in time; the hub sends the pin again with the spoke's next sessions update or when it reconnects"
+
+/** Plain text of at most noteChars characters (control and format characters become spaces). */
+export function noteText(text: string): string {
+  const clean = text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ")
+  return clean.length <= PROFILE_APPLY_LIMITS.noteChars ? clean : `${clean.slice(0, PROFILE_APPLY_LIMITS.noteChars - 1)}…`
+}
+
+const key = (userID: string, sessionID: string) => `${userID}\u0000${sessionID}`
+
+export class ProfileApplier {
+  private readonly deps: ProfileApplierDeps
+  private readonly now: Clock
+  private readonly limits: ProfileApplyLimits
+  /** Per session: the tail of its serialized sends. */
+  private readonly chains = new Map<string, Promise<void>>()
+  private readonly inflight = new Set<Promise<void>>()
+  /** Per session: the connection its pin was last sent through (or checked against); insertion order = age. */
+  private readonly sentVia = new Map<string, string>()
+  private active = 0
+  private readonly waiting: Array<() => void> = []
+  private unsubscribe: (() => void) | undefined
+
+  constructor(deps: ProfileApplierDeps) {
+    this.deps = deps
+    this.now = deps.now ?? Date.now
+    this.limits = { ...PROFILE_APPLY_SERVICE_LIMITS, ...deps.limits }
+  }
+
+  /** ProfileStore's `ack` option: the immediate status of a new pin; the spoke's answer is recorded later. */
+  readonly ackFor = async (userID: string, assignment: ProfileAssignment, version: AgentProfileVersion): Promise<ProfileAck> => {
+    const at = this.now()
+    const target = this.target(userID, assignment.sessionID)
+    if (target.kind === "offline") return offlineAck(version.digest, at)
+    if (target.kind === "unsupported") {
+      this.remember(key(userID, assignment.sessionID), target.connID)
+      return unsupportedAck(version.digest, target.harness, at)
+    }
+    void this.schedule(userID, assignment.sessionID, { revision: assignment.revision })
+    return { status: "pending", digest: version.digest, at }
+  }
+
+  /** Starts re-applying pins when sessions show up on a new connection. */
+  start(): void {
+    this.unsubscribe ??= this.deps.registry.onSessions((connID) => this.sessionsFrom(connID))
+  }
+
+  stop(): void {
+    this.unsubscribe?.()
+    this.unsubscribe = undefined
+  }
+
+  /** Resolves when every send started so far has finished (tests, shutdown). */
+  async idle(): Promise<void> {
+    while (this.inflight.size) await Promise.allSettled([...this.inflight])
+  }
+
+  /** Sessions whose last-sent connection is remembered (bounded by trackedSessions). */
+  tracked(): number {
+    return this.sentVia.size
+  }
+
+  /**
+   * Pins the launch's explicit profile version to its new session and waits (at most launchWaitMs) for the
+   * acknowledgment. Returns notes for the launch reason; never throws.
+   */
+  async applyAtLaunch(userID: string, sessionID: string, ref: LaunchAgentProfile): Promise<string[]> {
+    const label = `profile ${ref.profileID} v${ref.version}`
+    try {
+      const current = await this.deps.profiles.assignment(userID, sessionID)
+      const pinned = await this.deps.profiles.assign(userID, sessionID, { profileID: ref.profileID, version: ref.version, expectedRevision: current?.revision ?? 0 })
+      const chain = this.chains.get(key(userID, sessionID))
+      if (chain) await withTimeout(chain, this.limits.launchWaitMs)
+      const after = await this.deps.profiles.assignment(userID, sessionID)
+      const ack = after?.revision === pinned.revision ? after.ack : pinned.ack
+      return [`${label} ${ack?.status ?? "pending"}${ack?.offline ? " (offline)" : ""}`]
+    } catch (cause) {
+      return [`${label} not applied: ${noteText(cause instanceof Error ? cause.message : String(cause))}`]
+    }
+  }
+
+  // ---------- internals ----------
+
+  private target(userID: string, sessionID: string): Target {
+    const { registry } = this.deps
+    const connID = registry.owner(sessionID)
+    if (!connID || registry.sessionTenant(sessionID) !== userID) return { kind: "offline" }
+    if (!registry.supports(connID, PROFILE_APPLY_FEATURE)) return { kind: "unsupported", connID, harness: registry.harnessOf(connID) ?? "unknown" }
+    return { kind: "online", connID }
+  }
+
+  /** A sessions frame: re-applies pins of sessions this connection now owns and was not last sent through. */
+  private sessionsFrom(connID: string): void {
+    const { registry } = this.deps
+    for (const sessionID of registry.reportedSessions(connID)) {
+      if (registry.owner(sessionID) !== connID) continue
+      const userID = registry.sessionTenant(sessionID)
+      if (!userID) continue
+      const k = key(userID, sessionID)
+      if (this.sentVia.get(k) === connID) continue
+      this.remember(k, connID)
+      void this.schedule(userID, sessionID, { reconnect: true })
+    }
+  }
+
+  private remember(k: string, connID: string): void {
+    this.sentVia.delete(k)
+    this.sentVia.set(k, connID)
+    while (this.sentVia.size > this.limits.trackedSessions) this.sentVia.delete(this.sentVia.keys().next().value!)
+  }
+
+  /** Queues a send behind the session's previous one. */
+  private schedule(userID: string, sessionID: string, options: SendOptions): Promise<void> {
+    const k = key(userID, sessionID)
+    const previous = this.chains.get(k) ?? Promise.resolve()
+    const next = previous
+      .then(() => this.limited(() => this.send(userID, sessionID, options)))
+      .catch((cause) => console.error(`[hub] profile apply for ${sessionID} failed: ${cause instanceof Error ? cause.message : String(cause)}`))
+    this.chains.set(k, next)
+    this.inflight.add(next)
+    void next.finally(() => {
+      this.inflight.delete(next)
+      if (this.chains.get(k) === next) this.chains.delete(k)
+    })
+    return next
+  }
+
+  private async limited<T>(run: () => Promise<T>): Promise<T> {
+    if (this.active >= this.limits.concurrency) await new Promise<void>((resolve) => this.waiting.push(resolve))
+    this.active++
+    try {
+      return await run()
+    } finally {
+      this.active--
+      this.waiting.shift()?.()
+    }
+  }
+
+  private async send(userID: string, sessionID: string, options: SendOptions): Promise<void> {
+    const { profiles, spokes } = this.deps
+    const assignment = await profiles.assignment(userID, sessionID)
+    if (!assignment || (options.revision !== undefined && assignment.revision !== options.revision)) return
+    if (options.reconnect && assignment.ack?.status === "rejected") return
+    const version = await profiles.version(userID, assignment.profileID, assignment.version)
+    if (!version) return
+    const k = key(userID, sessionID)
+    const target = this.target(userID, sessionID)
+    if (target.kind === "offline") {
+      this.sentVia.delete(k)
+      return this.record(userID, assignment, offlineAck(version.digest, this.now()))
+    }
+    this.remember(k, target.connID)
+    if (target.kind === "unsupported") {
+      if (options.reconnect && assignment.ack?.status === "unsupported") return
+      return this.record(userID, assignment, unsupportedAck(version.digest, target.harness, this.now()))
+    }
+    const req: ProfileApplyRequest = { op: PROFILE_APPLY_FEATURE, sessionID, profileID: assignment.profileID, version: assignment.version, digest: version.digest, content: version.content }
+    let result: unknown
+    try {
+      result = await spokes.request(target.connID, req, { tenant: userID })
+    } catch (cause) {
+      const ack = this.failure(cause, version.digest)
+      if (ack.status === "pending") this.sentVia.delete(k)
+      return this.record(userID, assignment, ack)
+    }
+    const problem = profileApplyResultProblem(result, req)
+    if (problem) return this.record(userID, assignment, { status: "rejected", digest: version.digest, notes: [noteText(`invalid acknowledgment from the spoke: ${problem}`)], at: this.now() })
+    const answer = result as ProfileApplyResult
+    await this.record(userID, assignment, { status: answer.status, digest: version.digest, ...(answer.notes?.length ? { notes: [...answer.notes] } : {}), at: this.now() })
+  }
+
+  private failure(cause: unknown, digest: string): ProfileAck {
+    const at = this.now()
+    if (cause instanceof RequestTimeoutError) return { status: "pending", digest, notes: [TIMEOUT_NOTE], at }
+    if (cause instanceof RequestTooLargeError) return { status: "rejected", digest, notes: ["the profile version is too large to send in one frame"], at }
+    if (cause instanceof SpokeError) {
+      if (/disconnected/i.test(cause.message)) return offlineAck(digest, at)
+      return { status: "rejected", digest, notes: [noteText(`the spoke refused: ${cause.message}`)], at }
+    }
+    return { status: "pending", digest, notes: [noteText(`the spoke could not be reached (${cause instanceof Error ? cause.name : "error"}); the hub sends the pin again when it reconnects`)], at }
+  }
+
+  private async record(userID: string, assignment: ProfileAssignment, ack: ProfileAck): Promise<void> {
+    const written = await this.deps.profiles.recordAck(userID, assignment.sessionID, assignment.revision, ack)
+    if (!written || written.ack?.status !== ack.status || written.ack.at !== ack.at) return
+    await this.deps.events
+      ?.append(userID, profileAckEvent(assignment.sessionID, assignment.profileID, assignment.version, assignment.revision, ack.status))
+      .catch((cause) => console.error(`[hub] profile.ack event failed: ${(cause as Error).message}`))
+  }
+}
+
+const offlineAck = (digest: string, at: number): ProfileAck => ({ status: "pending", digest, notes: [OFFLINE_NOTE], at, offline: true })
+const unsupportedAck = (digest: string, harness: string, at: number): ProfileAck => ({
+  status: "unsupported",
+  digest,
+  notes: [noteText(`the ${harness} spoke does not announce ${PROFILE_APPLY_FEATURE}; update it or its harness adapter`)],
+  at,
+})
+
+async function withTimeout(promise: Promise<unknown>, ms: number): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  await Promise.race([promise, new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)))])
+  clearTimeout(timer)
+}
+
+// ---------- authority ----------
+
+export interface PinAuthorizerDeps {
+  readonly registry: Pick<ApplyRegistry, "session" | "sessionTenant">
+  readonly grants: Pick<Grants, "usable" | "consume">
+  readonly acting?: Pick<ActingSwitch, "ensureActing">
+}
+
+/** Checks a pin's caller beyond its scopes: (actor, userID, sessionID) → throws the agent error. */
+export type PinAuthorizer = (actor: AgentActor, userID: string, sessionID: string) => Promise<void>
+
+/**
+ * An app token that pins a profile (which changes what a running session is told) also needs a usable prompt grant
+ * on the session, and spends one action of it. Users need nothing more; sessions never pin (routes refuse them).
+ */
+export function pinAuthorizer(deps: PinAuthorizerDeps): PinAuthorizer {
+  return async (actor, userID, sessionID) => {
+    if (actor.kind === "user") return
+    if (actor.kind !== "app") throw new AgentError("forbidden", "Only users and app tokens pin profiles")
+    deps.acting?.ensureActing(userID)
+    const live = deps.registry.sessionTenant(sessionID) === userID ? deps.registry.session(sessionID) : undefined
+    if (!live) throw new AgentError("offline", "No spoke reports this session now, so the prompt grant a pin needs cannot be checked")
+    const usable = await deps.grants.usable(actor, "prompt", { directory: live.directory })
+    if (!usable.length) throw new AgentError("forbidden", "Pinning a profile as an app also needs a prompt grant on the session")
+    await deps.grants.consume(usable[0]!)
+  }
+}

package/src/central/profiles/content.ts

@@ -0,0 +1,174 @@
+// Profile content rules of the registry (HWA-14), on top of the frozen protocol check (profileContentProblem):
+//
+// - Command templates: literal text with `{{name}}` parameters (lowercase, digits, `_`; `{{arguments}}` is the
+//   whole argument string by convention) and `{{secret:NAME}}` secret references. Nothing else: no expressions,
+//   conditionals, loops, filters or includes. `\{{` writes a literal `{{`. Rendering substitutes each value
+//   literally, once; a value is never parsed again, so it cannot inject placeholders.
+// - Secrets: profiles carry secret REFERENCES only (`{{secret:NAME}}`), which central never resolves; the harness
+//   side resolves them, or leaves them, as it reports. A literal credential anywhere (instructions, skills,
+//   commands) is refused, and the refusal names where and what kind, never the value.
+// - No setup hooks or dependency installation: such fields are `unsupported` (refused, never ignored); other
+//   unknown fields are `invalid`. Content is normalized to the known fields.
+// - The digest is the sha256 hex of the canonical JSON (keys sorted at every level) of the normalized content.
+import { createHash } from "node:crypto"
+import { canonicalProfileJSON, isText, PROFILE_LIMITS, profileContentProblem, profileTemplateParts, type ProfileCommand, type ProfileSkill, type ProfileTemplatePart, type ProfileVersionContent } from "../../protocol"
+
+export const TEMPLATE_LIMITS = {
+  /** Distinct parameters per template. */
+  params: 16,
+  /** Characters of one parameter value. */
+  valueChars: 4_000,
+  /** Characters of a rendered command. */
+  renderedChars: 16_000,
+} as const
+
+/** A refused profile body: `invalid` (400) or `unsupported` (422, feature `setupHooks`). */
+export class ProfileContentError extends Error {
+  constructor(
+    readonly code: "invalid" | "unsupported",
+    message: string,
+  ) {
+    super(message)
+    this.name = "ProfileContentError"
+  }
+}
+
+const PARAM = /^[a-z][a-z0-9_]{0,39}$/
+
+export type TemplateParse = { readonly ok: true; readonly params: string[]; readonly secrets: string[] } | { readonly ok: false; readonly problem: string }
+
+type Piece = ProfileTemplatePart
+
+/** Splits a template into literal text, parameters and secret references (the shared protocol tokenizer). */
+const pieces = (template: string): Piece[] | string => profileTemplateParts(template)
+
+/** The parameters and secret references of a template, or why it is refused. */
+export function parseTemplate(template: string): TemplateParse {
+  const parsed = pieces(template)
+  if (typeof parsed === "string") return { ok: false, problem: parsed }
+  const params: string[] = []
+  const secrets: string[] = []
+  for (const piece of parsed) {
+    if ("param" in piece && !params.includes(piece.param)) params.push(piece.param)
+    if ("secret" in piece && !secrets.includes(piece.secret)) secrets.push(piece.secret)
+  }
+  if (params.length > TEMPLATE_LIMITS.params) return { ok: false, problem: `at most ${TEMPLATE_LIMITS.params} parameters` }
+  return { ok: true, params, secrets }
+}
+
+/**
+ * Renders a template with exactly its parameters. Values are text up to TEMPLATE_LIMITS.valueChars; secret
+ * references stay as written (central never resolves them); the result is bounded by renderedChars.
+ */
+export function renderTemplate(template: string, values: Readonly<Record<string, unknown>>): string {
+  const parsed = pieces(template)
+  if (typeof parsed === "string") throw new ProfileContentError("invalid", `template: ${parsed}`)
+  const { params } = parseTemplate(template) as { params: string[] }
+  const missing = params.filter((name) => !Object.hasOwn(values, name))
+  if (missing.length) throw new ProfileContentError("invalid", `missing parameter(s) ${missing.join(", ")}`)
+  const unknown = Object.keys(values).filter((name) => !params.includes(name))
+  if (unknown.length) throw new ProfileContentError("invalid", `unknown parameter(s) ${unknown.map((n) => (PARAM.test(n) ? n : "?")).join(", ")}`)
+  for (const name of params) {
+    const value = values[name]
+    if (typeof value !== "string" || !isText(value, TEMPLATE_LIMITS.valueChars)) throw new ProfileContentError("invalid", `parameter ${name} must be text of at most ${TEMPLATE_LIMITS.valueChars} characters`)
+  }
+  let out = ""
+  for (const piece of parsed) {
+    out += "text" in piece ? piece.text : "param" in piece ? (values[piece.param] as string) : piece.raw
+    if (out.length > TEMPLATE_LIMITS.renderedChars) throw new ProfileContentError("invalid", `rendered command is too long (more than ${TEMPLATE_LIMITS.renderedChars} characters)`)
+  }
+  return out
+}
+
+/** Distinctive credential formats; prose about secrets ("set API_KEY=…") is not matched. */
+const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["hub app token", /\bhat_[0-9a-f]{16}_[A-Za-z0-9_-]{43,}/],
+  ["github token", /\bgh[pousr]_[A-Za-z0-9]{36,}/],
+  ["github token", /\bgithub_pat_[A-Za-z0-9_]{22,}/],
+  ["api key", /\bsk-[A-Za-z0-9_-]{20,}/],
+  ["api key", /\bAIza[0-9A-Za-z_-]{35}/],
+  ["aws access key", /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ["slack token", /\bxox[abposr]-[A-Za-z0-9-]{10,}/],
+  ["jwt", /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/],
+  ["bearer token", /\b[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}/],
+]
+
+/** The kind of literal credential in a text, or undefined. */
+export function credentialFinding(text: string): string | undefined {
+  for (const [kind, pattern] of CREDENTIALS) if (pattern.test(text)) return kind
+  return undefined
+}
+
+/** Fields that would run code or install things on a machine: refused as unsupported. */
+const HOOK_FIELDS = new Set(["hooks", "hook", "setup", "install", "postinstall", "preinstall", "dependencies", "devdependencies", "requirements", "scripts"])
+const CONTENT_FIELDS = new Set(["instructions", "model", "skills", "commands"])
+const SKILL_FIELDS = new Set(["name", "description", "body"])
+const COMMAND_FIELDS = new Set(["name", "description", "template"])
+
+const fieldLabel = (key: string) => (/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)")
+
+function checkFields(record: Record<string, unknown>, allowed: ReadonlySet<string>, where: string): void {
+  for (const key of Object.keys(record)) {
+    if (allowed.has(key)) continue
+    if (HOOK_FIELDS.has(key.toLowerCase())) {
+      throw new ProfileContentError("unsupported", `${where}${fieldLabel(key)}: profiles carry no setup hooks, scripts or dependency installation`)
+    }
+    throw new ProfileContentError("invalid", `${where}unknown field ${fieldLabel(key)}`)
+  }
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** Validates a profile version body and returns it normalized to the known fields; throws ProfileContentError. */
+export function checkContent(v: unknown): ProfileVersionContent {
+  if (!isRecord(v)) throw new ProfileContentError("invalid", "content must be an object")
+  checkFields(v, CONTENT_FIELDS, "")
+  if (Array.isArray(v.skills)) for (const item of v.skills) if (isRecord(item)) checkFields(item, SKILL_FIELDS, "skills: ")
+  if (Array.isArray(v.commands)) for (const item of v.commands) if (isRecord(item)) checkFields(item, COMMAND_FIELDS, "commands: ")
+  const problem = profileContentProblem(v)
+  if (problem) throw new ProfileContentError("invalid", problem)
+  const skills = (v.skills as ProfileSkill[]).map(({ name, description, body }) => ({ name, description, body }))
+  const commands = (v.commands as ProfileCommand[]).map(({ name, description, template }) => ({ name, description, template }))
+  const content: ProfileVersionContent = {
+    ...(v.instructions !== undefined ? { instructions: v.instructions as string } : {}),
+    ...(v.model !== undefined ? { model: v.model as string } : {}),
+    skills,
+    commands,
+  }
+  for (const command of commands) {
+    const parsed = parseTemplate(command.template)
+    if (!parsed.ok) throw new ProfileContentError("invalid", `commands.${command.name}.template: ${parsed.problem}`)
+  }
+  const texts: [string, string][] = [
+    ...(content.instructions !== undefined ? [["instructions", content.instructions] as [string, string]] : []),
+    ...skills.flatMap((s): [string, string][] => [[`skills.${s.name}.description`, s.description], [`skills.${s.name}.body`, s.body]]),
+    ...commands.flatMap((c): [string, string][] => [[`commands.${c.name}.description`, c.description], [`commands.${c.name}.template`, c.template]]),
+  ]
+  for (const [where, text] of texts) {
+    const kind = credentialFinding(text)
+    if (kind) throw new ProfileContentError("invalid", `${where} contains what looks like a ${kind}; keep credentials out of profiles and use a secret reference {{secret:NAME}}`)
+  }
+  return content
+}
+
+/** JSON with object keys sorted at every level (arrays keep their order); shared with spokes through the protocol. */
+export const canonicalJSON = canonicalProfileJSON
+
+/** sha256 hex of the canonical JSON of a version's content (what adapters echo in their acknowledgment). */
+export const contentDigest = (content: unknown): string => createHash("sha256").update(canonicalJSON(content)).digest("hex")
+
+/** Serialized size of a version's content in bytes (the storage quota counts it). */
+export const contentBytes = (content: ProfileVersionContent): number => new TextEncoder().encode(JSON.stringify(content)).length
+
+/** Secret names a version references (all command templates); for views, never values. */
+export function secretReferences(content: ProfileVersionContent): string[] {
+  const out = new Set<string>()
+  for (const command of content.commands) {
+    const parsed = parseTemplate(command.template)
+    if (parsed.ok) for (const name of parsed.secrets) out.add(name)
+  }
+  return [...out]
+}
+
+export { PROFILE_LIMITS }

package/src/central/profiles/events.ts

@@ -0,0 +1,40 @@
+// Compact journal events of the profile registry (contract: PROFILE_EVENT_TYPES, family `manage`). Allowlisted
+// payloads only: IDs, revisions, version numbers and flags; never names, titles, descriptions, instructions,
+// skills, command templates or parameters.
+import type { EventInput } from "../agent/events"
+
+export const profileCreatedEvent = (profileID: string, revision: number): EventInput => ({
+  type: "profile.created",
+  family: "manage",
+  subject: { profileID },
+  data: { version: 1, revision },
+})
+
+export const profileVersionEvent = (profileID: string, version: number, revision: number): EventInput => ({
+  type: "profile.version.created",
+  family: "manage",
+  subject: { profileID },
+  data: { version, revision },
+})
+
+export const profileArchivedEvent = (profileID: string, archived: boolean, revision: number): EventInput => ({
+  type: "profile.archived",
+  family: "manage",
+  subject: { profileID },
+  data: { archived, revision },
+})
+
+export const profileAssignedEvent = (sessionID: string, profileID: string, version: number, revision: number): EventInput => ({
+  type: "profile.assigned",
+  family: "manage",
+  subject: { sessionID, profileID },
+  data: { version, revision },
+})
+
+/** A spoke's (or the hub's) application status of a pin (HWA-15): never its notes, which may quote the harness. */
+export const profileAckEvent = (sessionID: string, profileID: string, version: number, revision: number, status: string): EventInput => ({
+  type: "profile.ack",
+  family: "manage",
+  subject: { sessionID, profileID },
+  data: { version, revision, status },
+})

package/src/central/profiles/idempotency.ts

@@ -0,0 +1,14 @@
+// Idempotent profile creates: the shared route-level helper (../agent/idempotency.ts, extracted by HWA-06) over
+// the StateStore collection "profile-idempotency", so records written before the extraction keep replaying.
+import type { Clock, StateStore } from "../backend/types"
+import { RouteIdempotency } from "../agent/idempotency"
+
+export { IDEMPOTENCY_LIMITS, type Answer } from "../agent/idempotency"
+
+export const PROFILE_IDEMPOTENCY = "profile-idempotency"
+
+export class Idempotency extends RouteIdempotency {
+  constructor(options: { readonly state: StateStore; readonly now?: Clock }) {
+    super({ ...options, collection: PROFILE_IDEMPOTENCY })
+  }
+}