@huynle/hub 0.7.4 → 0.8.1

package/packages/protocol/src/hub-workspace.ts

@@ -0,0 +1,201 @@
+// Coordination workspaces (HWA-02 contract; implemented by HWA-03..13). A "hub workspace" is a durable, owner-
+// tenanted coordination record, distinct from a launch's LaunchWorkspace (a repo/worktree on one machine) and from
+// any directory or Herdr key. It outlives sessions and launches: members, a replaceable master, supervision links,
+// checkpoints and side chats are separate records that reference sessions by ID.
+//
+// Invariants frozen here:
+// - Tenancy: one owner (the hub user). No implicit human sharing; membership grants nothing (grants stay explicit).
+// - Supervision is a separate relationship, never a rewrite of native parentID/rootID.
+// - The master is an ordinary public-API session; replacing it is an explicit mutation (HWA-12).
+// - Events about these records are compact and text-free (IDs, kinds, revisions, counts only).
+import { DESCRIPTION_MAX, isContractID, isExpectedRevision, isLabel, isText, metadataProblem, tagsProblem, type RecordState, type Revisioned } from "./contracts.ts"
+import { isObj } from "./wire.ts"
+
+export const WORKSPACE_LIMITS = {
+  /** Active (non-archived) workspaces per user. */
+  workspacesPerUser: 200,
+  /** Members (sessions) per workspace, current and departed generations together. */
+  membersPerWorkspace: 200,
+  /** Host repository bindings per workspace. */
+  bindingsPerWorkspace: 16,
+  /** Supervision links per workspace and the maximum supervision depth (master = depth 0). */
+  supervisionLinksPerWorkspace: 400,
+  supervisionDepth: 6,
+  /** Retained checkpoints per supervisor (oldest dropped). */
+  checkpointsPerSupervisor: 50,
+  /** Side chats per workspace and context items per side chat snapshot. */
+  sideChatsPerWorkspace: 100,
+  sideChatContextItems: 20,
+  /** Bytes of quoted text a side-chat context snapshot may carry, total. */
+  sideChatContextBytes: 64 * 1024,
+  /** Panes in one split layout. */
+  panes: 4,
+} as const
+
+/** Scopes for app tokens (registered by HWA-06 together with the routes; existing tokens gain nothing). */
+export const WORKSPACE_SCOPES = ["workspaces:read", "workspaces:manage"] as const
+
+export type WorkspaceRole = "master" | "worker" | "observer"
+export const WORKSPACE_ROLES: readonly WorkspaceRole[] = ["master", "worker", "observer"]
+
+export interface HubWorkspace extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly title: string
+  readonly description?: string
+  readonly state: RecordState
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  /** The current master membership (absent: no master; the workspace still exists). */
+  readonly masterMemberID?: string
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+/** Binds a workspace to a repository on a machine (explicit; logical IDs never derive from paths). */
+export interface HostRepoBinding extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly machineID: string
+  /** Absolute normal repo path on that machine (same checks as LaunchWorkspace.repo). */
+  readonly repo: string
+  readonly label?: string
+}
+
+/** A session's membership. A replaced session keeps its record (`leftAt`); a re-join is a new generation. */
+export interface WorkspaceMember extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly sessionID: string
+  readonly role: WorkspaceRole
+  /** Increments each time the same logical slot is re-staffed with a new session (master replacement, restart). */
+  readonly generation: number
+  readonly joinedAt: number
+  readonly leftAt?: number
+  readonly leftReason?: "removed" | "replaced" | "ended" | "archived"
+}
+
+/** A versioned unit of work given to a member (status only; instructions travel as messages). */
+export interface WorkspaceAssignment extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly memberID: string
+  readonly title: string
+  readonly status: "open" | "in_progress" | "blocked" | "done" | "cancelled"
+  /** External reference (e.g. a Brain task ID, a team intake ID); opaque to the hub. */
+  readonly ref?: string
+  readonly updatedAt: number
+}
+
+/** Supervisor → supervised member. Acyclic within a workspace; depth ≤ supervisionDepth. */
+export interface SupervisionLink extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly supervisorMemberID: string
+  readonly memberID: string
+  /** Sibling order for the dashboard tree (drag reorder); dense integers are not required. */
+  readonly order: number
+}
+
+/**
+ * A supervisor's durable acknowledgment of the events it has processed (HWA-11). `cursor` is the agent-events
+ * position; delivery of batched updates resumes after it. Written through (not debounced) in standalone mode.
+ */
+export interface SupervisorCheckpoint {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly supervisorMemberID: string
+  readonly cursor: string
+  readonly at: number
+}
+
+/**
+ * A side chat: a new session started with an explicit, bounded, authorized snapshot of source context. The
+ * snapshot is copied at creation (never live access) and only from sources the creator could read.
+ */
+export interface SideChat extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly workspaceID: string
+  readonly sessionID: string
+  readonly sourceSessionID: string
+  /** Message IDs / artifact revision IDs the snapshot was taken from (text lives in the snapshot, not events). */
+  readonly sources: readonly { readonly kind: "message" | "artifact_revision"; readonly id: string }[]
+  readonly createdAt: number
+}
+
+/** Pane layout persisted per device (HWA-07/08); a pane names a session or a side chat. */
+export interface PaneLayout {
+  readonly v: 1
+  readonly split: "single" | "vertical" | "horizontal" | "grid"
+  readonly panes: readonly { readonly sessionID: string; readonly sideChatID?: string }[]
+  readonly focused: number
+}
+
+/** Compact, text-free event types (family "manage"); data carries only IDs, kinds, revisions and counts. */
+export const WORKSPACE_EVENT_TYPES = [
+  "workspace.created",
+  "workspace.updated",
+  "workspace.archived",
+  "workspace.member.joined",
+  "workspace.member.left",
+  "workspace.master.replaced",
+  "workspace.supervision.changed",
+  "workspace.assignment.changed",
+  "workspace.sidechat.created",
+] as const
+export type WorkspaceEventType = (typeof WORKSPACE_EVENT_TYPES)[number]
+
+/** Why a create-workspace body is not acceptable, or undefined. */
+export function workspaceInputProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "body must be an object"
+  if (!isLabel(v.title)) return "title must be 1–120 characters of text"
+  if (v.description !== undefined && !isText(v.description, DESCRIPTION_MAX)) return `description must be at most ${DESCRIPTION_MAX} characters`
+  return tagsProblem(v.tags) ?? metadataProblem(v.metadata)
+}
+
+/** Why a supervision mutation is not acceptable (shape only; cycle/depth checks need the graph, see wouldCycle). */
+export function supervisionInputProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "body must be an object"
+  if (!isContractID("member", v.memberID)) return "memberID must be a workspace member ID"
+  if (v.supervisorMemberID !== null && !isContractID("member", v.supervisorMemberID)) return "supervisorMemberID must be a member ID or null (detach)"
+  if (v.supervisorMemberID === v.memberID) return "a member cannot supervise itself"
+  if (!isExpectedRevision(v.expectedRevision)) return "expectedRevision must be the workspace revision you read"
+  return undefined
+}
+
+/**
+ * True when making `supervisor` supervise `member` would create a cycle or exceed `maxDepth`, given the current
+ * links (member → supervisor). The graph is small (≤ supervisionLinksPerWorkspace), so a walk is fine.
+ */
+export function supervisionViolation(
+  links: ReadonlyMap<string, string>,
+  member: string,
+  supervisor: string,
+  maxDepth: number = WORKSPACE_LIMITS.supervisionDepth,
+): "cycle" | "depth" | undefined {
+  const next = new Map(links)
+  next.set(member, supervisor)
+  const depthOf = (start: string): number | "cycle" => {
+    const seen = new Set<string>()
+    let depth = 0
+    for (let at: string | undefined = start; at !== undefined; at = next.get(at)) {
+      if (seen.has(at)) return "cycle"
+      seen.add(at)
+      if (next.has(at)) depth++
+    }
+    return depth
+  }
+  let deepest = 0
+  for (const node of next.keys()) {
+    const d = depthOf(node)
+    if (d === "cycle") return "cycle"
+    deepest = Math.max(deepest, d)
+  }
+  return deepest > maxDepth ? "depth" : undefined
+}

package/packages/protocol/src/index.ts

@@ -12,16 +12,27 @@
 // Modules: harness-events.ts (the forwarded events a non-OpenCode spoke may send, with their shapes), launch.ts
 // (launch vocabulary and workspace checks), node.ts (the `hub node` hello, frames and ops on the same socket),
 // preset.ts (the harness preset schema), webhook.ts (webhook signature format), wire.ts (shared frame primitives).
+// Workspaces/artifacts/teams contracts (HWA-02, docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md):
+// contracts.ts (shared IDs, limits, revisions), hub-workspace.ts, profiles.ts, artifacts.ts, teams.ts, graph.ts.
 // All are re-exported here.
 
 import { featureList, HUB_URL_MAX_CHARS, ID, isByeFrame as isBye, isHubURL, isObj, isResFrame as isRes, isWelcomeFrame, MAX_FRAME, MAX_RETRY_AFTER_MS, nonEmpty, num, parseFrame as parse, str, token, UNSAFE_CHARS } from "./wire.ts"
 import type { NodeMessage, NodeServerMessage } from "./node.ts"
+import { PROFILE_APPLY_FEATURE, profileApplyRequestProblem, type ProfileApplyRequest, type ProfileApplyResult } from "./profiles.ts"
+import { SESSION_CONTEXT_FEATURE, sessionContextProblem, type SessionContextRequest, type SessionContextResult } from "./concierge.ts"
 
 export * from "./harness-events.ts"
 export * from "./launch.ts"
 export * from "./node.ts"
 export * from "./preset.ts"
 export * from "./webhook.ts"
+export * from "./contracts.ts"
+export * from "./hub-workspace.ts"
+export * from "./concierge.ts"
+export * from "./profiles.ts"
+export * from "./artifacts.ts"
+export * from "./teams.ts"
+export * from "./graph.ts"
 export { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
 
 export const PROTOCOL_VERSION = 1
@@ -137,6 +148,57 @@ export interface SessionInfo {
   /** Open in a terminal right now (a Herdr pane or an OpenCode TUI showing it). */
   readonly open?: boolean
   readonly terminal?: TerminalInfo
+  /**
+   * A staged revert (feature "revert"): the session's history from `messageID` on is hidden and the files it changed
+   * since then are restored until the revert is restored (cleared) or committed (the next prompt commits it).
+   * Older hubs ignore it.
+   */
+  readonly revert?: SessionRevertInfo
+  /**
+   * (CON-04, feature "sessionContext") Sessions the hub gave a locked context (the Concierge): the agent the spoke
+   * last saw the session run on, and the context revision it holds now (absent: none, e.g. after a restart). The hub
+   * re-sends a context the spoke does not hold and suspends a Concierge seen on another agent.
+   */
+  readonly agent?: string
+  readonly contextRevision?: number
+  /**
+   * (FX-07) The session is locked as a Concierge session on this spoke (sent from the first sessions frame after a
+   * restart, before `agent` or `contextRevision` are known). The hub treats it as a Concierge session.
+   */
+  readonly locked?: true
+}
+
+/** Most files a revert summary or preview lists (`filesTotal` counts them all). */
+export const REVERT_FILES_MAX = 50
+/** Longest file path a revert summary carries. */
+export const REVERT_FILE_MAX_CHARS = 1000
+
+/** A file a revert restores (or would restore): its path in the session's directory and, when known, how it changes. */
+export interface RevertFile {
+  readonly file: string
+  readonly status?: "added" | "deleted" | "modified"
+  readonly additions?: number
+  readonly deletions?: number
+}
+
+/** A staged revert as the spoke reports it (SessionInfo.revert, the revert op's result). */
+export interface SessionRevertInfo {
+  /** The reverted user message (it and everything after it are hidden). */
+  readonly messageID: string
+  /** User messages hidden: the reverted one and those after it. */
+  readonly hidden: number
+  /** When the reverted message was created (epoch ms), when known. */
+  readonly at?: number
+  /** Restored files (at most REVERT_FILES_MAX). */
+  readonly files: readonly RevertFile[]
+  readonly filesTotal: number
+}
+
+/** An attachment of a user message, by its position in the message's files (fetched through timelineFile). */
+export interface MessageAttachment {
+  readonly index: number
+  readonly mime: string
+  readonly name?: string
 }
 
 export interface TerminalInfo {
@@ -355,8 +417,12 @@ export const IMPLIED_OPENCODE_FEATURES = [
  * environment, for its own act verbs only (the OpenCode hub tool).
  * "launch": its create op takes a launch's `launchID`, `agent` and `model` (see isLaunchCreate); a launch create's
  * directory may be a new workspace under the machine's node workspace roots rather than one the spoke reported.
+ * "fork": it forks a session before one of its user messages (fork op). "revert": it stages, restores and commits
+ * a revert of a session from one of its user messages (revertPreview, revert, revertRestore, revertCommit ops) and
+ * reports a staged one as SessionInfo.revert. Announced only when the spoke's harness can (OpenCode: a process that
+ * reaches its own server).
  */
-const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch"] as const
+const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert"] as const
 
 /**
  * The core ops. An OpenCode spoke serves them all without announcing them; a spoke of another harness announces
@@ -370,15 +436,17 @@ export type CoreOp = (typeof CORE_OPS)[number]
  * Every feature a spoke may serve: the core ops, the optional features, and "turnEvents": a spoke of another
  * harness reports every turn's end as the harness confirms it (session.execution.succeeded, failed or interrupted,
  * never inferred), so the hub trusts its "rpc" evidence for idle (e.g. a Codex app-server spoke's turn/completed).
- * Not in SPOKE_FEATURES: an OpenCode spoke's native evidence already counts.
+ * Not in SPOKE_FEATURES: an OpenCode spoke's native evidence already counts. "profileApply" (HWA-15, profiles.ts):
+ * the spoke applies a pinned profile version to one session; announced only (never implied); the OpenCode spoke
+ * serves it since HWA-16 (src/spoke/profile-apply.ts).
  */
-export const KNOWN_SPOKE_FEATURES = [...CORE_OPS, ...OPTIONAL_SPOKE_FEATURES, "turnEvents"] as const
+export const KNOWN_SPOKE_FEATURES = [...CORE_OPS, ...OPTIONAL_SPOKE_FEATURES, "turnEvents", PROFILE_APPLY_FEATURE, SESSION_CONTEXT_FEATURE] as const
 export type SpokeFeature = (typeof KNOWN_SPOKE_FEATURES)[number]
 /**
  * What this package's OpenCode spoke announces (without "deliver" and "hubPrompt" when its OpenCode has no synthetic
  * messages). No core op: an OpenCode spoke implies them.
  */
-export const SPOKE_FEATURES: readonly SpokeFeature[] = OPTIONAL_SPOKE_FEATURES
+export const SPOKE_FEATURES: readonly SpokeFeature[] = [...OPTIONAL_SPOKE_FEATURES, PROFILE_APPLY_FEATURE, SESSION_CONTEXT_FEATURE]
 
 /**
  * Features the hub announces in its welcome. "harness": it reads hello `harness`, `harnessVersion` and `evidence`.
@@ -585,6 +653,28 @@ export type ServerRequest =
    * `meta.from` and `meta.grant` around it, so the session never sees it as the user's prompt.
    */
   | { readonly op: "deliver"; readonly sessionID: string; readonly messageID: string; readonly text: string; readonly wake: boolean; readonly meta: DeliverMeta }
+  /** Apply a pinned profile version to one session (feature "profileApply", HWA-15; see profiles.ts). */
+  | ProfileApplyRequest
+  /** A session's per-turn context (feature "sessionContext", CON-04; see concierge.ts). */
+  | SessionContextRequest
+  /**
+   * Fork the session before `messageID`, one of its user messages (feature "fork"): a new session with the
+   * conversation before that message. The result names it and carries the message's text and attachments, which
+   * the console puts in the new session's composer.
+   */
+  | { readonly op: "fork"; readonly sessionID: string; readonly messageID: string }
+  /** What reverting from `messageID` would hide and which files the session changed since then (feature "revert"). */
+  | { readonly op: "revertPreview"; readonly sessionID: string; readonly messageID: string }
+  /**
+   * Stage a revert from `messageID`, one of the session's user messages (feature "revert"): it and everything after
+   * it are hidden and, with `files`, the files the session changed since then are restored. Refused while the
+   * session runs. The result carries the message's text and attachments for the composer.
+   */
+  | { readonly op: "revert"; readonly sessionID: string; readonly messageID: string; readonly files: boolean }
+  /** Undo a staged revert: the messages and files come back (feature "revert"). */
+  | { readonly op: "revertRestore"; readonly sessionID: string }
+  /** Make a staged revert permanent: the hidden messages are removed (feature "revert"). */
+  | { readonly op: "revertCommit"; readonly sessionID: string }
 
 /**
  * The feature a spoke must serve (spokeFeatures) for the hub to send `op`: the op itself for a core op (CORE_OPS,
@@ -594,6 +684,10 @@ export function featureForOp(op: ServerRequest["op"]): SpokeFeature {
   switch (op) {
     case "setModelPrefs":
       return "modelPrefs"
+    case "revertPreview":
+    case "revertRestore":
+    case "revertCommit":
+      return "revert"
     default:
       return op
   }
@@ -710,6 +804,15 @@ export interface ResultFor {
   /** As sessionTokens. */
   actTokens: { readonly applied: readonly string[]; readonly skipped: ReadonlyArray<{ readonly sessionID: string; readonly reason: SessionTokenSkipReason }> }
   deliver: DeliverResult
+  profileApply: ProfileApplyResult
+  sessionContext: SessionContextResult
+  /** `sessionID`: the new session; `text` and `attachments`: the user message it was forked before. */
+  fork: { readonly sessionID: string; readonly title?: string; readonly text: string; readonly attachments: readonly MessageAttachment[] }
+  /** `hidden`: user messages a revert would hide; `files`: files the session changed since then (at most REVERT_FILES_MAX). */
+  revertPreview: { readonly hidden: number; readonly files: readonly RevertFile[]; readonly filesTotal: number }
+  revert: { readonly revert: SessionRevertInfo; readonly text: string; readonly attachments: readonly MessageAttachment[] }
+  revertRestore: Record<string, never>
+  revertCommit: Record<string, never>
 }
 
 // ---------- both directions ----------
@@ -810,7 +913,42 @@ function isSession(v: unknown): v is SessionInfo {
     (v.projectName === undefined || str(v.projectName)) &&
     (v.archived === undefined || typeof v.archived === "boolean") &&
     (v.open === undefined || typeof v.open === "boolean") &&
-    (v.terminal === undefined || isTerminal(v.terminal))
+    (v.terminal === undefined || isTerminal(v.terminal)) &&
+    (v.revert === undefined || isSessionRevert(v.revert)) &&
+    (v.agent === undefined || (nonEmpty(v.agent) && v.agent.length <= AGENT_NAME_MAX)) &&
+    (v.contextRevision === undefined || (Number.isSafeInteger(v.contextRevision) && (v.contextRevision as number) >= 0)) &&
+    (v.locked === undefined || v.locked === true)
+  )
+}
+
+const REVERT_STATUS = new Set(["added", "deleted", "modified"])
+const count = (v: unknown) => Number.isSafeInteger(v) && (v as number) >= 0
+
+/** A file of a revert summary or preview. */
+export function isRevertFile(v: unknown): v is RevertFile {
+  return (
+    isObj(v) &&
+    nonEmpty(v.file) &&
+    v.file.length <= REVERT_FILE_MAX_CHARS &&
+    (v.status === undefined || REVERT_STATUS.has(v.status as string)) &&
+    (v.additions === undefined || count(v.additions)) &&
+    (v.deletions === undefined || count(v.deletions))
+  )
+}
+
+/** A staged revert as a spoke reports it. */
+export function isSessionRevert(v: unknown): v is SessionRevertInfo {
+  return (
+    isObj(v) &&
+    nonEmpty(v.messageID) &&
+    v.messageID.length <= 300 &&
+    count(v.hidden) &&
+    (v.at === undefined || num(v.at)) &&
+    Array.isArray(v.files) &&
+    v.files.length <= REVERT_FILES_MAX &&
+    v.files.every(isRevertFile) &&
+    count(v.filesTotal) &&
+    (v.filesTotal as number) >= v.files.length
   )
 }
 
@@ -1008,6 +1146,18 @@ function isServerRequest(v: unknown): v is ServerRequest {
       return Array.isArray(v.tokens) && v.tokens.length <= SESSION_TOKENS_MAX && v.tokens.every(isSessionToken) && !("hubURL" in v)
     case "deliver":
       return deliverProblem(v) === undefined
+    case "profileApply":
+      return profileApplyRequestProblem(v) === undefined
+    case "sessionContext":
+      return sessionContextProblem(v) === undefined
+    case "fork":
+    case "revertPreview":
+      return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300
+    case "revert":
+      return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300 && typeof v.files === "boolean"
+    case "revertRestore":
+    case "revertCommit":
+      return nonEmpty(v.sessionID)
     default:
       return false
   }
@@ -1102,15 +1252,34 @@ export const ACTIVITY_SUMMARY_MAX = 160
 /** Longest reasoning delta forwarded; longer deltas are cut (they are normally a few tokens). */
 export const REASONING_DELTA_MAX = 2000
 
+/** The hub tool's input fields that name its target (never `text`, `why` or answers: those are free text). */
+const HUB_TARGET_KEYS = ["propose", "to", "session", "id", "name", "role"] as const
+/** At most ACTIVITY_SUMMARY_MAX UTF-16 units, cut on a code point boundary (CON-10: never half an emoji). */
+function clipLine(line: string): string {
+  if (line.length <= ACTIVITY_SUMMARY_MAX) return line
+  let out = ""
+  for (const ch of line) {
+    if (out.length + ch.length > ACTIVITY_SUMMARY_MAX - 1) break
+    out += ch
+  }
+  // A joiner or variation selector left dangling would glue the ellipsis to half a sequence.
+  return `${out.replace(/[\u200d\ufe0f]+$/u, "")}…`
+}
+
 /** Short human summary of a tool input, e.g. the shell command or file path. Never the full input. */
 export function summarizeToolInput(input: unknown): string {
   if (typeof input !== "object" || input === null) return ""
   const record = input as Record<string, unknown>
+  // (CON-09b) The hub tool: its verb and target, e.g. "msg @me", "approve @engineer per_1", "concierge_board".
+  if (typeof record.verb === "string" && /^[a-z][a-z_]{0,39}$/.test(record.verb)) {
+    const target = HUB_TARGET_KEYS.map((key) => record[key]).filter((v): v is string => typeof v === "string" && v.trim() !== "" && !/\s/.test(v.trim()))
+    return clipLine([record.verb, ...target.map((v) => v.trim())].join(" "))
+  }
   for (const key of SUMMARY_KEYS) {
     const value = record[key]
     if (typeof value === "string" && value.trim()) {
       const line = value.trim().split("\n")[0]!
-      return line.length > ACTIVITY_SUMMARY_MAX ? `${line.slice(0, ACTIVITY_SUMMARY_MAX - 1)}…` : line
+      return clipLine(line)
     }
   }
   return ""

package/packages/protocol/src/launch.ts

@@ -59,6 +59,15 @@ export interface LaunchEnd {
   readonly cleanup?: CleanupPolicy
 }
 
+/**
+ * (HWA-15, additive) The agent profile version a launched session gets before its first prompt. The version is
+ * explicit: a launch never follows a profile's latest version silently.
+ */
+export interface LaunchAgentProfile {
+  readonly profileID: string
+  readonly version: number
+}
+
 /** A launch request body (POST /api/agent/launches). Phase 4 has no `grant` field: a launch gets no powers beyond its launcher's. */
 export interface LaunchSpec {
   /** Idempotency key: the same key and body return the same launch. */
@@ -73,9 +82,13 @@ export interface LaunchSpec {
   readonly runtime?: LaunchRuntime
   readonly placement?: LaunchPlacement
   readonly prompt?: string
+  /** (CON-02) What the session is for: one line, at most 280 characters, untrusted; stored as its intent (source "launch"). */
+  readonly intent?: string
   /** Free-form; never interpreted by the hub. */
   readonly labels?: Readonly<Record<string, string>>
   readonly end?: LaunchEnd
+  /** (HWA-15) Pin and apply this profile version to the session before its prompt (spokes that announce profileApply). */
+  readonly agentProfile?: LaunchAgentProfile
 }
 
 /** What a node collected from a launch's workspace. */
@@ -90,6 +103,14 @@ export interface LaunchArtifacts {
   readonly dirty?: boolean
 }
 
+/** Why a queued launch waits (FX-02): capacity (a fitting node is full), no_match (no node fits), active (the per-user cap). */
+export interface LaunchWaitingInfo {
+  readonly wait: "capacity" | "no_match" | "active"
+  readonly reason: string
+  /** ms epoch: since when it has waited for this kind of reason. */
+  readonly since: number
+}
+
 /** A launch as the API reports it. */
 export interface LaunchInfo {
   readonly id: string
@@ -105,6 +126,12 @@ export interface LaunchInfo {
   readonly name?: string
   readonly outcome?: LaunchOutcome
   readonly artifacts?: LaunchArtifacts
+  /** Only while queued: why it waits (`reason` is the same text). */
+  readonly waiting?: LaunchWaitingInfo
+  /** The launcher's label when it launched (an app token's label). */
+  readonly byLabel?: string
+  /** The app token that launched it was revoked: it still runs and counts toward the cap until stopped. */
+  readonly launcherRevoked?: boolean
 }
 
 // ---------- checks ----------
@@ -170,3 +197,12 @@ export function labelsProblem(v: unknown): string | undefined {
   }
   return undefined
 }
+
+/** Why `v` is not an acceptable launch agentProfile ({profileID, version}), or undefined. */
+export function launchAgentProfileProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "agentProfile must be {profileID, version}"
+  if (Object.keys(v).some((k) => k !== "profileID" && k !== "version")) return "agentProfile holds only profileID and version"
+  if (typeof v.profileID !== "string" || !/^[A-Za-z0-9_.:-]{1,100}$/.test(v.profileID)) return "agentProfile.profileID must be a profile ID"
+  if (typeof v.version !== "number" || !Number.isSafeInteger(v.version) || v.version < 1) return "agentProfile.version must be a version number (explicit; never latest)"
+  return undefined
+}