@huynle/hub 0.7.4 → 0.8.1

package/packages/cli/src/bootstrap/enrollment/policy.ts

@@ -1,15 +1,74 @@
-// The network policy of machine enrollment: which hub URLs a machine credential may be sent to, and which approval
-// link may be shown to the user.
+// The network policy of machine enrollment (and of `hub login`'s device code): which hub URLs a machine credential
+// or a login may be sent to, and which approval link may be shown to the user.
+//
+// Plain http (RP-10, Brain decision m5bzlmfq): refused unless the hub is on loopback, or the caller opted in with
+// --allow-insecure-http (allowInsecureHTTP) AND the hub is a private-network IP address: RFC 1918 (10/8,
+// 172.16/12, 192.168/16), IPv4 link-local (169.254/16), IPv6 unique-local (fc00::/7) or link-local (fe80::/10).
+// Host names never qualify, `.local` included: what a name resolves to is not known here, and a name could point at
+// a public address. Neither do public, shared (100.64/10, CGNAT/Tailscale), unspecified or IPv4-mapped addresses.
+// The opt-in is per command and never stored; every use warns (insecureHTTPWarning).
+import { networkInterfaces } from "node:os"
 
 const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"])
 const MAX_URL = 2048
 
+export interface ServerURLOptions {
+  /** --allow-insecure-http: also plain http to a private-network IP address (isPrivateNetworkHost). */
+  readonly allowInsecureHTTP?: boolean
+}
+
+/** An IPv4 address in dotted-quad form (as the URL parser normalizes it), or undefined. */
+function ipv4(host: string): number[] | undefined {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+  if (!m) return undefined
+  const parts = m.slice(1).map(Number)
+  return parts.every((n) => n <= 255) ? parts : undefined
+}
+
+/**
+ * Whether a URL host name (URL.hostname: IPv6 in brackets) is a private-network IP address: RFC 1918, IPv4
+ * link-local, IPv6 unique-local (fc00::/7) or link-local (fe80::/10). Never a name, loopback or a public address.
+ */
+export function isPrivateNetworkHost(host: string): boolean {
+  const v4 = ipv4(host)
+  if (v4) {
+    const [a, b] = v4 as [number, number]
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254)
+  }
+  const v6 = /^\[([0-9a-f:]+)\]$/i.exec(host)?.[1]?.toLowerCase()
+  if (!v6) return false
+  // The URL parser compresses IPv6 (no leading zeros, the longest zero run as ::): the first group leads.
+  const first = v6.startsWith(":") ? 0 : Number.parseInt(v6.split(":")[0]!, 16)
+  if (!Number.isFinite(first)) return false
+  return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80
+}
+
+/** What every command that uses a plain-http hub (allowed by the opt-in) says, each time. */
+export function insecureHTTPWarning(server: string): string {
+  return `plain http to ${server} (--allow-insecure-http): the code, the credential and everything after it travel unencrypted, so anyone on this network can read or change them; use https unless this network is trusted`
+}
+
+/** Why a plain-http hub URL was refused, for the usage error (undefined when it was not refused for that). */
+export function insecureHTTPRefusal(value: unknown, options: ServerURLOptions = {}): string | undefined {
+  if (typeof value !== "string" || checkServerURL(value, options)) return undefined
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return undefined
+  }
+  if (url.protocol !== "http:") return undefined
+  if (!isPrivateNetworkHost(url.hostname)) return "the hub URL must be https: plain http is allowed only for a loopback hub, or with --allow-insecure-http for a private-network IP address (10.x, 172.16–31.x, 192.168.x, 169.254.x, fc00::/7, fe80::/10), never a public address or a host name"
+  return options.allowInsecureHTTP ? undefined : "plain http to a private-network address needs --allow-insecure-http (the traffic is unencrypted; prefer https)"
+}
+
 /**
  * The normalized hub URL (origin + path, no trailing slash), or undefined when it is not allowed: https only, plain
- * http only for a loopback hub (a local hub, and the tests); no user info, query, fragment or whitespace. Matches the
- * contract's hubURL check, and what src/config.ts normalize() keeps.
+ * http only for a loopback hub (a local hub, and the tests) or, with allowInsecureHTTP, a private-network IP address;
+ * no user info, query, fragment or whitespace. Without the opt-in this matches the contract's hubURL check, and what
+ * src/config.ts normalize() keeps.
  */
-export function checkServerURL(value: unknown): string | undefined {
+export function checkServerURL(value: unknown, options: ServerURLOptions = {}): string | undefined {
   if (typeof value !== "string" || value.length === 0 || value.length > MAX_URL) return undefined
   if (/[\s?#]/.test(value)) return undefined
   let url: URL
@@ -19,7 +78,8 @@ export function checkServerURL(value: unknown): string | undefined {
     return undefined
   }
   if (url.username || url.password) return undefined
-  if (!(url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK.has(url.hostname)))) return undefined
+  const plainOK = LOOPBACK.has(url.hostname) || (options.allowInsecureHTTP === true && isPrivateNetworkHost(url.hostname))
+  if (!(url.protocol === "https:" || (url.protocol === "http:" && plainOK))) return undefined
   if (!/^https?:\/\/[^\s/]+/.test(value)) return undefined
   return `${url.origin}${url.pathname.replace(/\/+$/, "")}`
 }
@@ -36,19 +96,85 @@ const USER_CODE = /^[A-Za-z0-9-]{4,32}$/
 
 export const isUserCode = (value: unknown): value is string => typeof value === "string" && USER_CODE.test(value)
 
+/** Whether a URL is plain http (an opted-in insecure hub gets a warning). */
+export const isPlainHTTP = (server: string): boolean => server.startsWith("http:")
+
+/** This machine's IP addresses (IPv6 without brackets or zone). */
+export function localAddresses(): string[] {
+  return Object.values(networkInterfaces())
+    .flat()
+    .flatMap((a) => (a ? [a.address.replace(/%.*$/, "")] : []))
+}
+
+/** An address without IPv6 brackets, lower case, for comparing a URL host with localAddresses(). */
+const bare = (host: string): string => host.replace(/^\[(.*)\]$/, "$1").toLowerCase()
+
+const portOf = (url: URL): string => url.port || (url.protocol === "https:" ? "443" : "80")
+
+export interface ApprovalLinkOptions {
+  /** This machine's addresses (default: localAddresses()). */
+  readonly localAddresses?: readonly string[]
+}
+
 /**
- * The approval link to show. The hub's own link is used only when it is on the hub's origin (scheme, host and port)
- * and passes the URL policy: anything else could send the user (and their hub login) to a phishing page. Otherwise
- * the link is rebuilt on the hub URL, with a warning.
+ * The approval link to show (`server` must already have passed checkServerURL, with the caller's opt-in). The hub's
+ * own link is used when it is on the hub's origin (scheme, host and port). A loopback hub (on this machine) whose public URL is this machine's own private-network
+ * address on the same port (a LAN preview: `HUB_PUBLIC_URL=http://<lan ip>:<port>`, the hub listening on all
+ * addresses) gets its link shown, with the loopback one as `localURL`, so a user on another device of the LAN can
+ * open it: it reaches the same listener, so it is no other party's page. Anything else could send the user (and their
+ * hub login) to a phishing page: the link is rebuilt on the hub URL, with a warning.
  */
-export function approvalURL(server: string, approveURL: unknown, userCode: string): { url: string; warning?: string } {
+export function approvalURL(server: string, approveURL: unknown, userCode: string, options: ApprovalLinkOptions = {}): { url: string; warning?: string; localURL?: string } {
   const own = `${server}/approve?code=${encodeURIComponent(userCode)}`
   if (typeof approveURL !== "string" || approveURL.length > MAX_URL || /\s/.test(approveURL)) return { url: own, warning: "the hub sent no usable approval link; showing one on the hub URL" }
   try {
     const link = new URL(approveURL)
     const base = new URL(server)
-    const allowed = checkServerURL(`${link.origin}${link.pathname}`) !== undefined && !link.username && !link.password
-    if (allowed && link.origin === base.origin) return { url: link.href }
+    const clean = !link.username && !link.password
+    // The hub URL itself already passed the caller's policy (with or without the opt-in): its own origin is fine.
+    if (clean && link.origin === base.origin && checkServerURL(`${link.origin}${link.pathname}`, { allowInsecureHTTP: true }) !== undefined) return { url: link.href }
+    const sameListener =
+      clean &&
+      isLoopbackServer(server) &&
+      link.protocol === "http:" &&
+      base.protocol === "http:" &&
+      portOf(link) === portOf(base) &&
+      isPrivateNetworkHost(link.hostname) &&
+      (options.localAddresses ?? localAddresses()).some((a) => bare(a) === bare(link.hostname))
+    if (sameListener) return { url: link.href, localURL: own }
   } catch {}
   return { url: own, warning: "the hub's approval link is on another origin; showing one on the hub URL instead" }
 }
+
+/** A stored login URL that is plain http and not on loopback (an opted-in LAN hub, or an older login). */
+export function isInsecureStoredURL(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return url.protocol === "http:" && !LOOPBACK.has(url.hostname)
+  } catch {
+    return false
+  }
+}
+
+/** What every command that uses such a stored login says on stderr (verify D5). */
+export function storedInsecureWarning(value: string): string {
+  let shown = value.slice(0, 200)
+  try {
+    const url = new URL(value)
+    shown = `${url.origin}${url.pathname.replace(/\/+$/, "")}`
+  } catch {}
+  return `the stored hub URL ${shown} is plain http: your app token and everything this command sends or receives travel unencrypted on the network; log in again with an https URL (hub login --url https://<hub>)`
+}
+
+/**
+ * A URL as typed, for a refusal message, at most 200 characters: anything before an `@` in its authority-looking
+ * part (user info: a password or token) is replaced by ***. The authority starts after an http(s) scheme or any
+ * scheme followed by slashes or backslashes (`http:u:p@h`, `http:/u:p@h`, `http:\\u:p@h`), else at the start
+ * (`user:pass@h`), and ends at the first /, \\, ? or #. Leading whitespace is dropped.
+ */
+export function shownURL(value: string): string {
+  return value
+    .trimStart()
+    .replace(/^((?:https?:|[a-z][a-z0-9+.-]*:(?=[\/\\]))?[\/\\]*)[^\/\\?#]*@/i, "$1***@")
+    .slice(0, 200)
+}

package/packages/cli/src/bootstrap/enrollment/status.ts

@@ -3,7 +3,8 @@
 // upgrades, so it answers 426 (Expected a WebSocket upgrade) to a token it accepts and 401 to one it rejects. No
 // central change is needed; nothing is opened. The token goes only to a hub URL that passes checkServerURL, never
 // across a redirect, and never into the output. v1.1: a credential already stored for a plain-http hub that is not on
-// loopback is reported as `insecure`, with a warning, and never sent there (a new enrollment to it stays refused).
+// loopback is reported as `insecure`, with a warning, and not sent there by `machine status` (the spoke and hub node do
+// use it there; a new enrollment to it needs --allow-insecure-http and a private-network address).
 import { enrollmentStatusFrom, isInsecureHubURL, validateEnrollmentStatus, type CredentialProbe, type CredentialStore, type EnrollmentStatus, type MachineCredential } from "../contracts/index.ts"
 import { checkServerURL } from "./policy.ts"
 import { failure, line, success, type MachineResult } from "./result.ts"
@@ -102,7 +103,7 @@ export async function machineStatus(options: MachineStatusOptions): Promise<Mach
     const status = statusOf(credential, undefined, now())
     if (!validateEnrollmentStatus(status).ok) return failure(COMMAND, "internal", `${store.location} holds a machine identity this hubctl cannot report`)
     return success(COMMAND, status, [
-      `the stored hub URL ${line(credential.server, 300)} is plain http and not on loopback, so the credential was not checked (it is never sent over plain http); enroll again with an https hub URL: hubctl machine enroll --server https://<hub> --reenroll`,
+      `the stored hub URL ${line(credential.server, 300)} is plain http and not on loopback, so the credential was not checked here (machine status does not send it there); the OpenCode spoke and hub node do send this machine token to that hub, unencrypted (allowed with --allow-insecure-http); enroll again with an https hub URL: hubctl machine enroll --server https://<hub> --reenroll`,
     ])
   }
   if (!checkServerURL(credential.server)) {

package/packages/cli/src/cli.ts

@@ -8,10 +8,12 @@ import { loginFile, readLogin, removeLogin, resolveCredentials, writeLogin, type
 import { atName, logText, whoamiText, type Actor, roleText, sessionsText, showText, statusText, whoText } from "./format"
 import { CliError, EXIT, withHub } from "./http"
 import { deviceLogin, promptText, scopeNotes } from "./login"
+import { checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isInsecureStoredURL, isLoopbackServer, isPlainHTTP, shownURL, storedInsecureWarning } from "./bootstrap/enrollment/policy.ts"
 import { defaultMachineName } from "./bootstrap/enrollment/enroll.ts"
 import { readSpokeCredentials } from "../../node/src/config.ts"
 import { hostname } from "node:os"
 import { serveMcp } from "./mcp"
+import { intentLine, writeIntent } from "./intents"
 import { ASK_EXPIRES_DEFAULT_S, askOutcome, declinedText, durationArg, inboxText, mutedText, repliedText, sentText, textArg } from "./messaging"
 import { watch } from "./watch"
 import { DECISION_FLAGS, decisionOptions, decisionsText, openedText, stateArg } from "./decisions"
@@ -20,6 +22,7 @@ import { answeredText, approvedText, deliveryArg, deniedText, formAnswerArg, nee
 import { currentProgram, installNode, nodeStatus, nodeStatusText, runNodeCommand, uninstallNode, type NodeIo, type Program } from "./node"
 import { checkOpenShell, openShellCheckText } from "./openshell"
 import { LAUNCH_FLAGS, launchedText, launchesText, launchSpecArg, launchText, stoppedLaunchText } from "./launches"
+import { watchlistText, watchlistVerbText } from "./watchlist"
 import { claudeCodeMain } from "../../claude-code/src/main.ts"
 import { runClaude } from "../../claude-code/src/wrapper.ts"
 import { presetMain } from "../../preset/src/main.ts"
@@ -70,8 +73,10 @@ Reading
 
 Identity
   hub whoami                          who this credential is
-  hub who [--project P] [--role R]    named and role-holding sessions
+  hub who [--project P] [--role R] [--team T]  named and role-holding sessions (team members: their teams)
   hub name <@name> [--session <addr>]
+  hub intent <addr> [text… | --clear]  what the session is for (one line, ≤ 280 characters, untrusted);
+                                      no text: show it (else its title); a session token sets only its own
   hub role claim <role[.project]> [--exclusive] [--session <addr>]
   hub role release <role[.project]> [--session <addr>]
 
@@ -121,10 +126,13 @@ Launching (users; agents and app tokens with sessions:launch under a grant with
   hub launches show <launchID> · hub launches stop <launchID>   (stop: exit 8 when it already ended)
 
 Machine (this machine's one identity; no harness needed)
-  hub machine enroll --server <hub URL> [--name N] [--reenroll] [--no-verify]
-                                      device-code enrollment: approve the code on the hub (Ctrl-C cancels)
+  hub machine enroll --server <hub URL> [--name N] [--reenroll] [--no-verify] [--allow-insecure-http]
+                                      device-code enrollment: approve the code on the hub (Ctrl-C cancels);
+                                      --allow-insecure-http: plain http to a private-network IP address (status
+                                      insecure: the credential is never checked over it; not stored as a default)
   hub machine status [--no-verify]    unconfigured, configured, verified, revoked (exit 9), offline (exit 7)
-                                      or insecure (a plain-http hub: reported, never sent the credential)
+                                      or insecure (a plain-http hub: status does not check it; the spoke and
+                                      hub node still send the machine token to it, unencrypted)
 
 Setup (discover → preview → explicit apply; docs/bootstrap-contracts.md)
   hub setup discover                  what this host has (read-only)
@@ -178,23 +186,32 @@ Codex (app-server spoke)
   hub codex-spoke install|uninstall [--dry-run] | status
                                       the spoke service as a launchd agent / systemd user unit (printed, never loaded)
 
+Concierge watchlist (users; app tokens: sessions:read to show, sessions:manage to change)
+  hub watchlist [show]                what the Concierge watches now, and why; its config and revision
+  hub watchlist watch|unwatch <addr>  watch a session (a subagent: its root), or stop
+  hub watchlist mute|unmute <addr>    never watch it (not a notification mute), or undo
+
 MCP
   hub mcp                             an MCP server on stdio: these verbs as tools, with this CLI's credential
+                                      plus workspaces, artifacts and teams (teams, team_show, team_status,
+                                      team_create, team_publish, team_staff, team_submit, …: docs/teams.md)
 
 Login (outside a hub session; a machine enrollment is not a user login)
-  hub login [--url URL] [--scope S]... [--name N]
+  hub login [--url URL] [--scope S]... [--name N] [--allow-insecure-http]
                                       device code: approve it in the console as yourself and choose the scopes
                                       (default sessions:read, messages:send, messages:read; launching needs
                                       --scope sessions:launch, or tick it on the page, plus a grant with verb launch);
-                                      the URL defaults to HUB_URL, the last login, else this machine's enrollment
+                                      the URL defaults to HUB_URL, the last login, else this machine's enrollment;
+                                      https, or plain http on loopback (--allow-insecure-http: also a private-network
+                                      IP address such as a LAN preview, unencrypted, with a warning; never stored)
   hub login [--url URL] --token APP_TOKEN|-   store an app token (- or a pipe: read from stdin)
   hub logout
 
 Options: --json (raw responses), --help, --version
-Addresses: ses_… (or an unambiguous prefix), @name, @@role, @name.project, @me (the user)
+Addresses: ses_… (or an unambiguous prefix), @name, @@role, @@role#team (quote it: '@@dev#team'), @name.project, @me (the user)
 Credentials: HUB_URL + HUB_SESSION_TOKEN (set in a session's shells), else the \`hub login\` file.
 Exit codes: 0 ok, 1 other, 2 usage, 3 not found/ambiguous/taken, 4 needs user, 5 forbidden/paused,
-  6 rate limited, 7 unsupported/offline, 8 gone, 9 unauthorized/expired`
+  6 rate limited, 7 unsupported/offline/busy, 8 gone, 9 unauthorized/expired`
 
 interface Context {
   readonly io: Io
@@ -326,12 +343,12 @@ const COMMANDS: Record<string, Command> = {
   },
   who: {
     args: ["@@role?"],
-    flags: { project: "string", role: "string" },
+    flags: { project: "string", role: "string", team: "string" },
     async handle(context) {
       const { flags, args } = context.parsed
       const role = str(flags, "role") ?? args[0]
-      const body = await context.hub((hub) => hub.who({ project: str(flags, "project"), role }))
-      answer(context, body, (b) => whoText(b.sessions ?? []))
+      const body = await context.hub((hub) => hub.who({ project: str(flags, "project"), role, team: str(flags, "team") }))
+      answer(context, body, (b) => whoText(b.sessions ?? [], b))
     },
   },
   name: {
@@ -343,6 +360,18 @@ const COMMANDS: Record<string, Command> = {
       answer(context, body, (b) => `${b.sessionID} is ${atName(b.name)}${b.alias ? ` (was ${atName(b.alias)}, kept as an alias for 24 h)` : ""}`)
     },
   },
+  intent: {
+    args: ["<addr>", "text..."],
+    flags: { clear: "bool" },
+    async handle(context) {
+      const [addr, ...words] = context.parsed.args
+      const clear = context.parsed.flags.clear === true
+      if (clear && words.length) throw new UsageError("Give a text or --clear, not both")
+      const text = words.join(" ")
+      const body = await context.hub(async (hub) => (clear || text ? { intent: await writeIntent(hub, addr!, clear ? null : text) } : hub.intent(addr!)))
+      answer(context, body, (b) => intentLine(addr!, b.intent))
+    },
+  },
   "role claim": {
     args: ["<role>"],
     flags: { exclusive: "bool", session: "string" },
@@ -651,7 +680,7 @@ const COMMANDS: Record<string, Command> = {
     },
   },
   login: {
-    flags: { url: "string", token: "string", scope: "multi", name: "string" },
+    flags: { url: "string", token: "string", scope: "multi", name: "string", "allow-insecure-http": "bool" },
     async handle(context) {
       const { io, parsed } = context
       const file = loginFile(io.env, io.home)
@@ -672,6 +701,15 @@ const COMMANDS: Record<string, Command> = {
       let scopes: readonly string[] | undefined
       if (given !== undefined || piped) {
         if (parsed.flags.scope !== undefined) throw new UsageError("--scope is for the device code (without --token); an app token's scopes are set when it is created")
+        // The device code's URL policy (decision m5bzlmfq): https, plain http on loopback, or with
+        // --allow-insecure-http a private-network IP address (warned); checked before the token is read or sent.
+        const allow = { allowInsecureHTTP: parsed.flags["allow-insecure-http"] === true }
+        const server = checkServerURL(url, allow)
+        if (!server) {
+          const why = insecureHTTPRefusal(url, allow)
+          throw new UsageError(why ? `${why}: ${shownURL(url)}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${shownURL(url)}`)
+        }
+        if (isPlainHTTP(server) && !isLoopbackServer(server)) io.stderr(`hub: warning: ${insecureHTTPWarning(server)}\n`)
         token = (given !== undefined && given !== "-" ? given : io.stdin ? await io.stdin() : "").trim()
         if (!token) throw new UsageError("needs an app token: --token, or on stdin (create one in the console: Settings → Agents), or run `hub login` in a terminal for a device code")
       } else {
@@ -680,6 +718,7 @@ const COMMANDS: Record<string, Command> = {
           server: url,
           clientName: str(parsed.flags, "name") ?? io.login?.clientName ?? defaultMachineName(hostname()),
           scopes: requested,
+          ...(parsed.flags["allow-insecure-http"] === true ? { allowInsecureHTTP: true } : {}),
           ...(io.signal ? { signal: io.signal } : {}),
           ...(io.login?.fetch ? { fetch: io.login.fetch } : {}),
           ...(io.login?.intervalMs !== undefined ? { intervalMs: io.login.intervalMs } : {}),
@@ -689,12 +728,46 @@ const COMMANDS: Record<string, Command> = {
         scopes = login.scopes
         notes = scopeNotes(login.scopes, login.tokenID)
       }
-      const credentials: Credentials = { url, token, source: "login" }
+      const credentials: Credentials = { url, token, source: "login", ...(io.login?.fetch ? { fetch: io.login.fetch } : {}) }
       const body = await withHub(credentials, (hub) => hub.whoami())
       writeLogin(file, { url, token })
       answer(context, body, (b) => [`logged in to ${url}`, whoamiText(b), ...(scopes ? [`scopes: ${scopes.join(", ")}`] : []), `saved in ${file}`, ...notes].join("\n"))
     },
   },
+  "watchlist show": {
+    async handle(context) {
+      const body = await context.hub((hub) => hub.concierge.watchlist.get())
+      answer(context, body, watchlistText)
+    },
+  },
+  "watchlist watch": {
+    args: ["<addr>"],
+    async handle(context) {
+      const body = await context.hub((hub) => hub.concierge.watchlist.watch(context.parsed.args[0]!))
+      answer(context, body, (b) => watchlistVerbText("watch", b))
+    },
+  },
+  "watchlist unwatch": {
+    args: ["<addr>"],
+    async handle(context) {
+      const body = await context.hub((hub) => hub.concierge.watchlist.unwatch(context.parsed.args[0]!))
+      answer(context, body, (b) => watchlistVerbText("unwatch", b))
+    },
+  },
+  "watchlist mute": {
+    args: ["<addr>"],
+    async handle(context) {
+      const body = await context.hub((hub) => hub.concierge.watchlist.mute(context.parsed.args[0]!))
+      answer(context, body, (b) => watchlistVerbText("mute", b))
+    },
+  },
+  "watchlist unmute": {
+    args: ["<addr>"],
+    async handle(context) {
+      const body = await context.hub((hub) => hub.concierge.watchlist.unmute(context.parsed.args[0]!))
+      answer(context, body, (b) => watchlistVerbText("unmute", b))
+    },
+  },
   logout: {
     async handle(context) {
       const file = loginFile(context.io.env, context.io.home)
@@ -723,7 +796,7 @@ for (const label of Object.keys(BOOTSTRAP_FLAGS))
   }
 
 /** Commands with sub-verbs (`hub role claim`). */
-const GROUPS: Record<string, string[]> = { machine: [...MACHINE_VERBS], setup: [...SETUP_VERBS], "claude-code": [...SERVICE_VERBS], "codex-spoke": [...SERVICE_VERBS], role: ["claim", "release"], decisions: ["list"], grant: ["list", "show", "create", "revoke", "request"], launches: ["list", "show", "stop"], node: ["run", "install", "uninstall", "status", "openshell"], "node openshell": ["check"] }
+const GROUPS: Record<string, string[]> = { machine: [...MACHINE_VERBS], setup: [...SETUP_VERBS], "claude-code": [...SERVICE_VERBS], "codex-spoke": [...SERVICE_VERBS], role: ["claim", "release"], decisions: ["list"], grant: ["list", "show", "create", "revoke", "request"], launches: ["list", "show", "stop"], watchlist: ["show", "watch", "unwatch", "mute", "unmute"], node: ["run", "install", "uninstall", "status", "openshell"], "node openshell": ["check"] }
 
 const groupVerbs = (label: string): string[] | undefined => (Object.hasOwn(GROUPS, label) ? GROUPS[label] : undefined)
 
@@ -766,6 +839,8 @@ export async function run(argv: string[], io: Io): Promise<number> {
   // `hub codex` passes every other argument to Codex; `hub codex-spoke serve` is the spoke service it starts.
   if (name === "codex") return runCodex(rest, { env: io.env, home: io.home, stderr: io.stderr, program: io.program ?? currentProgram() })
   if (name === "codex-spoke" && !isServiceVerb(rest[0])) return codexMain(rest, io)
+  // `hub watchlist` alone (or with only flags) shows it.
+  if (name === "watchlist" && (rest[0] === undefined || rest[0].startsWith("-"))) rest.unshift("show")
   let label = name
   // Groups nest (`hub node openshell check`): each level picks one of its sub-verbs.
   for (let verbs = groupVerbs(label); verbs; verbs = groupVerbs(label)) {
@@ -793,9 +868,16 @@ export async function run(argv: string[], io: Io): Promise<number> {
       return EXIT.ok
     }
     json = parsed.flags.json === true
+    let warned = false
     const credentials = () => {
       const found = resolveCredentials(io.env, io.home)
       if (!found) throw notLoggedIn(io, label)
+      // A stored login on a plain-http, non-loopback hub (--allow-insecure-http, or an older login): every command
+      // says so, once, on stderr (never in --json output).
+      if (found.source === "login" && !warned && isInsecureStoredURL(found.url)) {
+        warned = true
+        io.stderr(`hub: warning: ${storedInsecureWarning(found.url)}\n`)
+      }
       return found
     }
     return (await command.handle({ io, parsed, json, credentials, hub: (use) => withHub(credentials(), use) })) ?? EXIT.ok

package/packages/cli/src/format.ts

@@ -136,6 +136,11 @@ export function logText(rows: readonly Row[]): string {
     .join("\n")
 }
 
+interface WhoReach {
+  readonly send: readonly string[]
+  readonly receive: readonly string[]
+}
+
 interface WhoEntry {
   readonly sessionID: string
   readonly name?: string
@@ -144,19 +149,52 @@ interface WhoEntry {
   readonly state?: string
   readonly online: boolean
   readonly roles: readonly { role: string; project?: string }[]
+  /** HWA-40 (additive). */
+  readonly teams?: readonly { team: string; roles: readonly string[]; reach?: WhoReach }[]
+  readonly reach?: WhoReach
+}
+
+/** HWA-40: the team groups of a who answer. */
+interface WhoGroups {
+  readonly teams?: readonly { name: string; mode: string; paused?: boolean; yourRoles?: readonly string[]; members: readonly { sessionID: string }[] }[]
+  readonly scope?: string
+}
+
+const reachText = (r: WhoReach | undefined): string | undefined =>
+  !r ? undefined : r.send.length === 2 && r.receive.length === 2 ? "two-way" : `${r.send.length ? `send ${r.send.join("/")}` : "unreachable"}, receive ${r.receive.length ? r.receive.join("/") : "none"}`
+
+function whoLine(e: WhoEntry, roles: string[], reach: WhoReach | undefined): string {
+  const parts = [[e.name ? at(e.name) : undefined, e.sessionID].filter(Boolean).join(" "), e.online ? (e.state ?? "online") : "offline"]
+  if (roles.length) parts.push(roles.join(" "))
+  const r = reachText(reach)
+  if (r) parts.push(r)
+  if (e.project) parts.push(e.project)
+  if (e.title) parts.push(oneLine(e.title, 60))
+  return parts.join("  ")
 }
 
-export function whoText(entries: readonly WhoEntry[]): string {
+/** One line per session; with team groups (HWA-40) a section per team (roles there, your reach), then the rest. */
+export function whoText(entries: readonly WhoEntry[], groups: WhoGroups = {}): string {
   if (!entries.length) return "no sessions"
-  return entries
-    .map((e) => {
-      const parts = [[e.name ? at(e.name) : undefined, e.sessionID].filter(Boolean).join(" "), e.online ? (e.state ?? "online") : "offline"]
-      if (e.roles.length) parts.push(e.roles.map((r) => `@@${r.role}${r.project !== undefined ? `.${r.project}` : ""}`).join(" "))
-      if (e.project) parts.push(e.project)
-      if (e.title) parts.push(oneLine(e.title, 60))
-      return parts.join("  ")
-    })
-    .join("\n")
+  const globalRoles = (e: WhoEntry) => e.roles.map((r) => `@@${r.role}${r.project !== undefined ? `.${r.project}` : ""}`)
+  if (!groups.teams?.length) return entries.map((e) => whoLine(e, globalRoles(e), e.reach)).join("\n")
+  const byID = new Map(entries.map((e) => [e.sessionID, e]))
+  const grouped = new Set<string>()
+  const lines: string[] = []
+  for (const t of groups.teams) {
+    lines.push(`#${t.name} (${t.mode}${t.paused ? ", paused" : ""})${t.yourRoles?.length ? `  you: ${t.yourRoles.map((r) => `@@${r}`).join(" ")}` : ""}`)
+    for (const id of new Set(t.members.map((m) => m.sessionID))) {
+      const e = byID.get(id)
+      if (!e) continue
+      grouped.add(id)
+      const ref = e.teams?.find((x) => x.team === t.name)
+      lines.push(`  ${whoLine(e, (ref?.roles ?? []).map((r) => `@@${r}`), ref?.reach)}`)
+    }
+  }
+  const rest = entries.filter((e) => !grouped.has(e.sessionID))
+  if (rest.length) lines.push(groups.scope === "team" ? "outside your teams" : "in no team", ...rest.map((e) => `  ${whoLine(e, globalRoles(e), e.reach)}`))
+  if (groups.scope === "team") lines.push("@me  the user  always reachable")
+  return lines.join("\n")
 }
 
 /** A caller as whoami / status `you` report it. */

package/packages/cli/src/http.ts

@@ -24,12 +24,14 @@ const EXIT_OF: Record<string, number> = {
   not_found: EXIT.notFound,
   ambiguous: EXIT.notFound,
   name_taken: EXIT.notFound,
+  conflict: EXIT.notFound,
   needs_user: EXIT.needsUser,
   forbidden: EXIT.forbidden,
   paused: EXIT.forbidden,
   rate_limited: EXIT.rateLimited,
   unsupported: EXIT.unavailable,
   offline: EXIT.unavailable,
+  busy: EXIT.unavailable,
   gone: EXIT.gone,
   unauthorized: EXIT.unauthorized,
   token_expired: EXIT.unauthorized,

package/packages/cli/src/intents.ts

@@ -0,0 +1,23 @@
+// Session intents in the CLI and `hub mcp` (CON-02): `hub intent <addr> [text… | --clear]` and the MCP tools
+// session_intent_get / session_intent_set. The intent is untrusted text from the hub: printed sanitised on one line.
+import { sanitizeLabel, type HubClient, type SessionIntent } from "../../sdk/src/index.ts"
+
+/** INTENT_MAX of the hub (packages/protocol). */
+const INTENT_MAX = 280
+
+/** `ses_1 intent (user, r2): Ship it`, or that it has none. */
+export function intentLine(addr: string, intent: SessionIntent | null): string {
+  if (!intent) return `${addr} has no intent (and no title to fall back on)`
+  const by = intent.by ? `, by ${sanitizeLabel(intent.by)}` : ""
+  return `${intent.sessionID} intent (${intent.source}${by}, r${intent.revision}): ${sanitizeLabel(intent.text, INTENT_MAX)}`
+}
+
+/**
+ * Sets (text) or clears (null) the caller's intent layer. Without `expectedRevision` the current revision is read
+ * first (a concurrent change between the two still answers conflict).
+ */
+export async function writeIntent(hub: HubClient, addr: string, text: string | null, options: { readonly expectedRevision?: number; readonly signal?: AbortSignal } = {}): Promise<SessionIntent | null> {
+  const signal = options.signal ? { signal: options.signal } : {}
+  const revision = options.expectedRevision ?? (await hub.intent(addr, signal)).intent?.revision ?? 0
+  return (await hub.setIntent(addr, text, revision, signal)).intent
+}

package/packages/cli/src/launches.ts

@@ -121,10 +121,15 @@ export function launchedText(launch: LaunchView, created: boolean, key: string |
 
 export const stoppedLaunchText = (launch: LaunchView): string => `stopped ${summary(launch)}`
 
-/** `lch_1  running  @api ses_1  /repo (branch)  app=brain` */
+/** The app token that launched it: `app "label"` or `app <token id>`. */
+const launcherText = (l: LaunchView) => (l.byLabel ? `app ${JSON.stringify(l.byLabel)}` : `app ${l.by?.replace(/^app:/, "") ?? "?"}`)
+
+/** `lch_1  running  @api ses_1  /repo (branch)  app=brain`; a queued one says why it waits, a revoked launcher is flagged. */
 export function launchLine(l: LaunchView): string {
   const where = l.directory ?? `${l.spec.workspace.repo}${l.spec.workspace.branch ? ` (${l.spec.workspace.branch})` : ""}`
-  return [l.id, stateText(l), sessionText(l) || undefined, where, labelsText(l.spec.labels) || undefined].filter(Boolean).join("  ")
+  const waits = l.state === "queued" && l.waiting ? `waits: ${l.waiting.reason}` : undefined
+  const revoked = l.launcherRevoked && l.state !== "ended" ? `launcher revoked (${launcherText(l)}): stop it with hub launches stop ${l.id}` : undefined
+  return [l.id, stateText(l), sessionText(l) || undefined, where, labelsText(l.spec.labels) || undefined, waits, revoked].filter(Boolean).join("  ")
 }
 
 export const launchesText = (launches: readonly LaunchView[]): string => (launches.length ? launches.map(launchLine).join("\n") : "no launches")
@@ -149,7 +154,8 @@ export function launchText(l: LaunchView): string {
   const run = [l.spec.harness, l.spec.agent, l.spec.model, l.spec.runtime ? `${l.spec.runtime.kind}${l.spec.runtime.profile ? `/${l.spec.runtime.profile}` : ""}` : undefined].filter(Boolean)
   if (run.length) lines.push(`runs: ${run.join(" ")}`)
   if (l.spec.end) lines.push(`ends: ${[l.spec.end.when, l.spec.end.timeout ? `timeout ${l.spec.end.timeout}` : undefined, l.spec.end.cleanup ? `cleanup ${l.spec.end.cleanup}` : undefined].filter(Boolean).join(", ")}`)
-  if (l.by) lines.push(`by: ${l.by}`)
+  if (l.state === "queued" && l.waiting) lines.push(`waits (${l.waiting.wait}) since ${new Date(l.waiting.since).toISOString()}: ${l.waiting.reason}`)
+  if (l.by) lines.push(`by: ${l.by}${l.byLabel ? ` (${l.byLabel})` : ""}${l.launcherRevoked ? ", launcher revoked" : ""}`)
   if (labelsText(l.spec.labels)) lines.push(`labels: ${labelsText(l.spec.labels)}`)
   if (l.artifacts && artifactsText(l.artifacts)) lines.push(`artifacts: ${artifactsText(l.artifacts)}`)
   if (l.history?.length) lines.push("steps:", ...l.history.map(stepText))