@huynle/hub 0.8.3 → 0.8.5

package/src/central/install/install.sh

@@ -0,0 +1,266 @@
+#!/bin/sh
+# Hub machine setup for macOS and Linux, served by the hub as GET /install.sh (see CONTRACT.md):
+#
+#   curl -fsSL '<hub>/install.sh?<choices>' | sh
+#
+# Downloads the hubctl release this hub pins, checks its sha256, enrolls this machine with the hub (device code,
+# approved in the console), then runs `hubctl setup preview`, `setup apply` and `setup verify` for the chosen
+# profile. Nothing runs until the last line: a truncated download only defines functions. Every child process reads
+# /dev/null, never the script on stdin. Re-running it is safe: an enrolled machine is not enrolled again, and apply
+# converges.
+
+hub_say() {
+  printf 'hub setup: %s\n' "$*" >&2
+}
+
+# hub_die <exit code> <message...>
+hub_die() {
+  hub_code=$1
+  shift
+  hub_say "$*"
+  exit "$hub_code"
+}
+
+hub_has() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+hub_is_musl() {
+  if ldd --version 2>&1 </dev/null | grep -qi musl; then
+    return 0
+  fi
+  for hub_f in /lib/ld-musl-* /usr/lib/ld-musl-*; do
+    if [ -e "$hub_f" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Sets HUB_TARGET (darwin-arm64, darwin-x64, linux-x64, linux-arm64) or stops with the reason.
+hub_target() {
+  hub_os=$(uname -s 2>/dev/null || echo unknown)
+  hub_arch=$(uname -m 2>/dev/null || echo unknown)
+  case "$hub_os" in
+    Darwin) hub_os=darwin ;;
+    Linux) hub_os=linux ;;
+    *) hub_die 7 "this system ($hub_os) is not supported: use macOS or Linux (on Windows, use the PowerShell command)" ;;
+  esac
+  case "$hub_arch" in
+    x86_64 | amd64) hub_arch=x64 ;;
+    arm64 | aarch64) hub_arch=arm64 ;;
+    *) hub_die 7 "this processor ($hub_arch) is not supported: hubctl is built for x86_64 and arm64" ;;
+  esac
+  if [ "$hub_os" = linux ]; then
+    if hub_is_musl; then
+      hub_die 7 "this Linux uses musl libc (Alpine?), which hubctl does not support yet: use a glibc distribution"
+    fi
+    if [ -r /proc/version ] && grep -qi microsoft /proc/version && ! grep -qi wsl2 /proc/version; then
+      hub_die 7 "this is WSL 1, which hubctl does not support: convert the distribution to WSL 2 (wsl --set-version <distro> 2)"
+    fi
+  fi
+  HUB_TARGET="$hub_os-$hub_arch"
+}
+
+# hub_fetch <url> <file>: https stays https across redirects.
+hub_fetch() {
+  case "$1" in
+    https://*) hub_tls=1 ;;
+    *) hub_tls=0 ;;
+  esac
+  if hub_has curl; then
+    if [ "$hub_tls" = 1 ]; then
+      curl -fsSL --proto '=https' --proto-redir '=https' -o "$2" "$1" </dev/null
+    else
+      curl -fsSL -o "$2" "$1" </dev/null
+    fi
+  elif hub_has wget; then
+    if [ "$hub_tls" = 1 ]; then
+      wget -q --https-only -O "$2" "$1" </dev/null
+    else
+      wget -q -O "$2" "$1" </dev/null
+    fi
+  else
+    hub_die 1 "needs curl or wget to download hubctl"
+  fi
+}
+
+# hub_sha256 <file>: the lower-case hex digest on stdout.
+hub_sha256() {
+  if hub_has sha256sum; then
+    sha256sum "$1" </dev/null | awk '{print tolower($1)}'
+  elif hub_has shasum; then
+    shasum -a 256 "$1" </dev/null | awk '{print tolower($1)}'
+  else
+    hub_die 1 "needs sha256sum or shasum to check the hubctl download; nothing was run"
+  fi
+}
+
+# hub_json_field <name> <file>: the first string value of "name" (hubctl's --json output is one field per line).
+hub_json_field() {
+  sed -n "s/^[[:space:]]*\"$1\":[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" "$2" | head -n 1
+}
+
+hub_on_path() {
+  case ":$PATH:" in
+    *":$1:"* | *":$1/:"*) return 0 ;;
+  esac
+  return 1
+}
+
+# hub_run <command...>: runs hubctl with stdin from /dev/null; its exit code in hub_rc (set -e never trips).
+hub_run() {
+  if "$hub_bin" "$@" </dev/null; then
+    hub_rc=0
+  else
+    hub_rc=$?
+  fi
+}
+
+main() {
+  set -eu
+  umask 077
+
+  HUB_URL='{{HUB_URL}}'
+  HUB_VERSION='{{HUB_VERSION}}'
+  RELEASE_BASE='{{RELEASE_BASE}}'
+  PROFILE='{{PROFILE}}'
+  # A leading ~/ is kept literal here and expanded to $HOME before preview.
+  # shellcheck disable=SC2088
+  WORKSPACE_ROOT='{{WORKSPACE_ROOT}}'
+  ACTIVATE='{{ACTIVATE}}'
+  INSECURE_HTTP='{{INSECURE_HTTP}}'
+
+  hub_release=${HUB_INSTALL_RELEASE_BASE:-$RELEASE_BASE}
+  hub_release=${hub_release%/}
+
+  hub_say "setting up this machine for $HUB_URL (hub $HUB_VERSION, profile $PROFILE)"
+  if [ "$INSECURE_HTTP" = 1 ]; then
+    hub_say "warning: $HUB_URL is plain http: this machine's token travels unencrypted on your network"
+  fi
+
+  hub_target
+
+  HUB_TMP=$(mktemp -d 2>/dev/null || mktemp -d -t hub-setup)
+  if [ -z "$HUB_TMP" ] || [ ! -d "$HUB_TMP" ]; then
+    hub_die 1 "cannot create a private temporary directory"
+  fi
+  trap 'rm -rf "$HUB_TMP"' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM HUP
+
+  # ---------- download and check hubctl ----------
+  hub_asset="hubctl-$HUB_TARGET"
+  hub_bin="$HUB_TMP/hubctl"
+  hub_manifest="$HUB_TMP/hubctl-manifest.json"
+  hub_say "downloading $hub_asset from $hub_release"
+  hub_fetch "$hub_release/HUBCTL_SHA256SUMS" "$HUB_TMP/HUBCTL_SHA256SUMS" || hub_die 1 "could not download $hub_release/HUBCTL_SHA256SUMS"
+  hub_fetch "$hub_release/$hub_asset" "$hub_bin" || hub_die 1 "could not download $hub_release/$hub_asset"
+  hub_fetch "$hub_release/hubctl-manifest.json" "$hub_manifest" || hub_die 1 "could not download $hub_release/hubctl-manifest.json"
+
+  # "<sha256>  <file>" lines (sha256sum or shasum; a leading * marks binary mode); exactly this file's name.
+  hub_expected=$(awk -v f="$hub_asset" '{ n = $2; sub(/^\*/, "", n) } NF == 2 && n == f { print tolower($1); exit }' "$HUB_TMP/HUBCTL_SHA256SUMS")
+  case "$hub_expected" in
+    "") hub_die 11 "HUBCTL_SHA256SUMS has no checksum for $hub_asset; nothing was run" ;;
+    *[!0-9a-f]*) hub_die 11 "HUBCTL_SHA256SUMS has a malformed checksum for $hub_asset; nothing was run" ;;
+  esac
+  if [ "${#hub_expected}" -ne 64 ]; then
+    hub_die 11 "HUBCTL_SHA256SUMS has a malformed checksum for $hub_asset; nothing was run"
+  fi
+  hub_actual=$(hub_sha256 "$hub_bin")
+  if [ "$hub_actual" != "$hub_expected" ]; then
+    hub_die 11 "the sha256 of $hub_asset does not match HUBCTL_SHA256SUMS (got $hub_actual); nothing was run"
+  fi
+  chmod 700 "$hub_bin"
+  hub_say "checksum ok (hubctl checks the release manifest signature itself)"
+
+  # ---------- enrollment ----------
+  # Skipped only when hubctl reports this exact hub; otherwise `machine enroll` decides (it is a no-op for the
+  # same hub and refuses another hub without --reenroll). A credential this hub revoked is replaced.
+  hub_enroll=1
+  hub_reenroll=0
+  hub_run machine status --json >"$HUB_TMP/status.json" 2>"$HUB_TMP/status.err"
+  hub_state=$(hub_json_field state "$HUB_TMP/status.json")
+  hub_server=$(hub_json_field server "$HUB_TMP/status.json")
+  if [ "$hub_server" = "$HUB_URL" ]; then
+    case "$hub_rc:$hub_state" in
+      0:verified | 0:configured | 0:insecure)
+        hub_enroll=0
+        hub_say "this machine is already enrolled with $HUB_URL ($hub_state); not enrolling again"
+        ;;
+      9:revoked)
+        hub_reenroll=1
+        hub_say "$HUB_URL revoked this machine's credential; enrolling it again"
+        ;;
+    esac
+  fi
+  if [ "$hub_enroll" = 1 ]; then
+    set -- machine enroll --server "$HUB_URL"
+    if [ "$INSECURE_HTTP" = 1 ]; then
+      set -- "$@" --allow-insecure-http
+    fi
+    if [ "$hub_reenroll" = 1 ]; then
+      set -- "$@" --reenroll
+    fi
+    hub_say "enrolling: approve the code below in the hub console"
+    hub_run "$@"
+    case "$hub_rc" in
+      0) ;;
+      5) hub_die 5 "the enrollment was denied on the hub; nothing was set up. Run the command again to start over" ;;
+      4) hub_die 4 "the enrollment did not complete (expired, cancelled, or this machine is enrolled with another hub: see above); nothing was set up" ;;
+      *) hub_die "$hub_rc" "enrollment failed (hubctl exit $hub_rc); nothing was set up" ;;
+    esac
+  fi
+
+  # ---------- preview and apply ----------
+  case "$WORKSPACE_ROOT" in
+    \~) WORKSPACE_ROOT=$HOME ;;
+    \~/*) WORKSPACE_ROOT="$HOME/${WORKSPACE_ROOT#\~/}" ;;
+  esac
+  hub_preview="$HUB_TMP/preview.json"
+  set -- setup preview --profile "$PROFILE" --enrollment separate --manifest "$hub_manifest" --out "$hub_preview"
+  if [ -n "$WORKSPACE_ROOT" ]; then
+    set -- "$@" --workspace-root "$WORKSPACE_ROOT"
+  fi
+  if [ "$ACTIVATE" = 1 ]; then
+    set -- "$@" --confirm-activation
+  fi
+  hub_run "$@"
+  if [ "$hub_rc" != 0 ]; then
+    hub_die "$hub_rc" "setup preview failed (hubctl exit $hub_rc); nothing was changed"
+  fi
+  if [ ! -s "$hub_preview" ]; then
+    hub_die 1 "setup preview wrote no preview; nothing was changed"
+  fi
+
+  # Manual edits (a config behind a symlink, a format hubctl cannot edit losslessly) are blockers, and apply
+  # refuses the whole plan while any remains (contracts §3.12, exit 10). The preview above printed them.
+  if grep -Eq '"blockers":[[:space:]]*\[[[:space:]]*$' "$hub_preview"; then
+    hub_die 10 "nothing was applied: make the edits listed above by hand (hubctl does not write those files), then run this command again"
+  fi
+
+  set -- setup apply --preview "$hub_preview" --manifest "$hub_manifest"
+  if [ "$ACTIVATE" = 1 ]; then
+    set -- "$@" --confirm-activation
+  fi
+  hub_run "$@"
+  case "$hub_rc" in
+    0) ;;
+    10) hub_die 10 "setup apply needs edits by hand or found a conflict (see above); resolve them, then run this command again" ;;
+    *) hub_die "$hub_rc" "setup apply failed (hubctl exit $hub_rc); see above" ;;
+  esac
+
+  # ---------- verify ----------
+  hub_run setup verify --profile "$PROFILE"
+  if ! hub_on_path "$HOME/.local/bin"; then
+    hub_say "note: $HOME/.local/bin is not on your PATH; add it (for example in ~/.profile) to run hub and hubctl by name"
+  fi
+  case "$hub_rc" in
+    0) hub_say "done: this machine is set up for $HUB_URL" ;;
+    15) hub_say "installed, not ready yet: finish the next steps above, then check with: hubctl setup verify" ;;
+    *) hub_die "$hub_rc" "setup verify failed (hubctl exit $hub_rc)" ;;
+  esac
+  return 0
+}
+
+main "$@"

package/src/central/install/render.ts

@@ -0,0 +1,146 @@
+// GET /install.sh and /install.ps1 (CONTRACT.md): the query allowlist, the values put into a template, and the
+// rendering. Pure: the route in http.ts passes the hub's public URL, version and HUB_RELEASE_BASE.
+//
+// Every value is checked against UNSAFE before it reaches a template: the templates put them inside single quotes,
+// so none may contain ' " ` $ \ or a line break. A value that does is a server bug and throws (the route answers 500),
+// never a script.
+import { checkServerURL, isLoopbackServer, isPrivateNetworkHost } from "../../../packages/cli/src/bootstrap/enrollment/policy.ts"
+import { INSTALL_TEMPLATES } from "./templates"
+
+export type InstallScript = "sh" | "ps1"
+export type InstallProfile = "session-only" | "launch-node" | "full-harness"
+
+export interface InstallChoices {
+  readonly profile: InstallProfile
+  /** The workspace root for launch-node, else "". */
+  readonly root: string
+  readonly activate: "0" | "1"
+}
+
+export const PLACEHOLDERS = ["HUB_URL", "HUB_VERSION", "RELEASE_BASE", "PROFILE", "WORKSPACE_ROOT", "ACTIVATE", "INSECURE_HTTP"] as const
+export type Placeholder = (typeof PLACEHOLDERS)[number]
+
+const PROFILES: readonly InstallProfile[] = ["session-only", "launch-node", "full-harness"]
+const KEYS = new Set(["profile", "root", "activate"])
+const DEFAULT_ROOT = "~/projects"
+const ROOT = /^(?:\/|~\/)[A-Za-z0-9._/~-]*$/
+const ROOT_MAX = 200
+const SEMVER = /^\d+\.\d+\.\d+$/
+const UNSAFE = /['"`$\\\r\n]/
+const RELEASES = "https://github.com/huynle/hub-releases/releases/download"
+
+type Parsed = { readonly ok: true; readonly choices: InstallChoices } | { readonly ok: false; readonly reason: string }
+
+const refuse = (reason: string): Parsed => ({ ok: false, reason })
+
+function rootProblem(root: string): string | undefined {
+  if (root.length < 1 || root.length > ROOT_MAX) return `root must be 1-${ROOT_MAX} characters`
+  if (!ROOT.test(root)) return "root must start with / or ~/ and use only letters, digits and . _ / ~ -"
+  if (root.includes("//")) return "root must not contain //"
+  if (root.split("/").includes("..")) return "root must not contain a .. segment"
+  return undefined
+}
+
+/** The choices of an install query, or why it is refused (a one-line reason for the 400). */
+export function parseInstallQuery(script: InstallScript, search: URLSearchParams): Parsed {
+  const seen = new Map<string, string>()
+  for (const [key, value] of search) {
+    if (!KEYS.has(key)) return refuse(`unknown query parameter ${JSON.stringify(key.slice(0, 40))} (allowed: profile, root, activate)`)
+    if (seen.has(key)) return refuse(`query parameter ${key} given more than once`)
+    seen.set(key, value)
+  }
+  const profile = seen.get("profile") ?? "session-only"
+  if (!PROFILES.includes(profile as InstallProfile)) return refuse(`profile must be one of ${PROFILES.join(", ")}`)
+  const activate = seen.get("activate") ?? "0"
+  if (activate !== "0" && activate !== "1") return refuse("activate must be 0 or 1")
+  const root = seen.get("root")
+  if (script === "ps1") {
+    if (profile !== "session-only") return refuse("install.ps1 supports only profile=session-only for now")
+    if (root !== undefined) return refuse("install.ps1 takes no root (no launch-node on Windows yet)")
+    if (activate !== "0") return refuse("install.ps1 supports only activate=0 for now")
+  }
+  if (root !== undefined && profile !== "launch-node") return refuse("root is only for profile=launch-node")
+  if (root !== undefined) {
+    const problem = rootProblem(root)
+    if (problem) return refuse(problem)
+  }
+  return { ok: true, choices: { profile: profile as InstallProfile, root: profile === "launch-node" ? (root ?? DEFAULT_ROOT) : "", activate } }
+}
+
+/**
+ * HUB_RELEASE_BASE, normalized (no trailing slash), or undefined when not allowed: https, or plain http on loopback
+ * or a private-network IP address (the enrollment policy's rule, policy.ts); no user info, query, fragment or
+ * whitespace, and none of the characters a template cannot quote.
+ */
+export function checkReleaseBase(value: string): string | undefined {
+  if (UNSAFE.test(value)) return undefined
+  const base = checkServerURL(value, { allowInsecureHTTP: true })
+  return base && !UNSAFE.test(base) ? base : undefined
+}
+
+export interface InstallContext {
+  /** The hub's public URL (config.publicURL). */
+  readonly publicURL: string
+  /** The hub version (as /api/me reports it). */
+  readonly version: string
+  /** HUB_RELEASE_BASE, already checked (checkReleaseBase). */
+  readonly releaseBase?: string
+}
+
+type Values = { readonly ok: true; readonly values: Record<Placeholder, string> } | { readonly ok: false; readonly status: 400 | 503; readonly reason: string }
+
+/** The placeholder values for these choices, or why there is no script (400 plain-http hub, 503 no release). */
+export function installValues(input: InstallContext & { readonly choices: InstallChoices }): Values {
+  const hub = checkServerURL(input.publicURL, { allowInsecureHTTP: true })
+  if (!hub) {
+    return { ok: false, status: 400, reason: "this hub's public URL must be https to install from it (plain http only on loopback or a private-network IP address)" }
+  }
+  const insecure = hub.startsWith("http:") && (isLoopbackServer(hub) || isPrivateNetworkHost(new URL(hub).hostname))
+  const release = input.releaseBase ?? (SEMVER.test(input.version) && input.version !== "0.0.0" ? `${RELEASES}/v${input.version}` : undefined)
+  if (!release) {
+    return { ok: false, status: 503, reason: `this hub (version ${input.version.slice(0, 40)}) has no published release to install; set HUB_RELEASE_BASE on the hub` }
+  }
+  const values: Record<Placeholder, string> = {
+    HUB_URL: hub,
+    HUB_VERSION: input.version,
+    RELEASE_BASE: release,
+    PROFILE: input.choices.profile,
+    WORKSPACE_ROOT: input.choices.root,
+    ACTIVATE: input.choices.activate,
+    INSECURE_HTTP: insecure ? "1" : "0",
+  }
+  assertSafe(values)
+  return { ok: true, values }
+}
+
+function assertSafe(values: Readonly<Record<string, string>>): void {
+  for (const [name, value] of Object.entries(values)) {
+    if (UNSAFE.test(value)) throw new Error(`install script value ${name} contains a character the template cannot quote`)
+  }
+}
+
+/** The template with every {{NAME}} replaced. Throws on an unsafe value, or a placeholder without a value or left over. */
+export function renderTemplate(template: string, values: Readonly<Record<string, string>>): string {
+  assertSafe(values)
+  const out = template.replace(/\{\{([A-Z_]+)\}\}/g, (match, name: string) => {
+    const value = values[name]
+    if (value === undefined) throw new Error(`install template placeholder {{${name}}} has no value`)
+    return value
+  })
+  const left = /\{\{[^}\n]*\}\}/.exec(out)
+  if (left) throw new Error(`install template has a leftover placeholder ${left[0].slice(0, 60)}`)
+  return out
+}
+
+const TEXT_HEADERS = { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" }
+
+const text = (status: number, body: string): Response => new Response(body, { status, headers: TEXT_HEADERS })
+
+/** The answer to GET /install.sh or /install.ps1: the rendered script, or a 400/503 one-line reason. */
+export function installResponse(script: InstallScript, url: URL, ctx: InstallContext & { readonly template?: string }): Response {
+  const parsed = parseInstallQuery(script, url.searchParams)
+  if (!parsed.ok) return text(400, `${parsed.reason}\n`)
+  const values = installValues({ ...ctx, choices: parsed.choices })
+  if (!values.ok) return text(values.status, `${values.reason}\n`)
+  return text(200, renderTemplate(ctx.template ?? INSTALL_TEMPLATES[script], values.values))
+}

package/src/central/install/templates.ts

@@ -0,0 +1,6 @@
+// The install script templates (CONTRACT.md), imported as text so `bun build --compile` and the npm package carry
+// them. The bodies belong to the scripts workstream; the server only fills their {{…}} placeholders (render.ts).
+import sh from "./install.sh" with { type: "text" }
+import ps1 from "./install.ps1" with { type: "text" }
+
+export const INSTALL_TEMPLATES: { readonly sh: string; readonly ps1: string } = { sh, ps1 }

package/src/central/install/text-assets.d.ts

@@ -0,0 +1,9 @@
+// Install script templates imported `with { type: "text" }` (templates.ts): Bun gives their contents as a string.
+declare module "*.sh" {
+  const text: string
+  export default text
+}
+declare module "*.ps1" {
+  const text: string
+  export default text
+}

package/src/central/registry.ts

@@ -12,7 +12,7 @@
 // holds the connection; remote state is never re-exported.
 import path from "node:path"
 import { HARNESS_OPENCODE, helloHarness, spokeFeatures, type EvidenceLevel, type ForwardedEvent, type Hello, type HerdrWorkspace, type ProcessKind, type SessionInfo, type RevertCommitted, type SessionRevertInfo, type SpokeFeature, type SpokeMode, type TerminalInfo, type Terminals } from "../protocol"
-import { StatusBoard, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
+import { BLOCKER_ID_MAX, StatusBoard, askBlocker, errorTypeLabel, permissionRequest, providerFailureNeedsUser, providerRetryNeedsUser, type Blocker, type BlockerRecommendation, type PermissionRequest, type SessionStatus } from "../status"
 import { sanitizeLabel } from "./agent/envelope"
 import { DoneWatch } from "./done"
 import { SentenceStream } from "./say-stream"
@@ -187,6 +187,17 @@ interface PendingPermission {
   readonly tenant?: string
   readonly request?: PermissionRequest
   recommendation?: BlockerRecommendation
+  /** Its blocker (bounded, askBlocker), to put back on a status board that lost it (see restoreBlockers). */
+  readonly blocker?: Blocker
+}
+
+/** A pending form and the processes that forwarded it. */
+interface PendingForm {
+  connIDs: string[]
+  readonly sessionID: string
+  readonly tenant?: string
+  /** Its blocker (bounded, askBlocker), to put back on a status board that lost it (see restoreBlockers). */
+  readonly blocker?: Blocker
 }
 
 /** Characters of a recommendation's author and reason on a blocker. */
@@ -399,6 +410,8 @@ interface WorkerSpeech {
 
 /** How many spoken texts, utterances and early deliveries are remembered for dedupe and matching. */
 const MEMORY = 1000
+/** Pending permissions, and pending forms, kept per tenant (oldest dropped). */
+export const PENDING_PER_TENANT = 200
 
 /** Adds to a bounded insertion-ordered map, dropping the oldest entry when full. */
 function remember<K, V>(map: Map<K, V>, key: K, value: V, limit = MEMORY): void {
@@ -406,6 +419,12 @@ function remember<K, V>(map: Map<K, V>, key: K, value: V, limit = MEMORY): void
   if (map.size > limit) map.delete(map.keys().next().value!)
 }
 
+/** Adds an ID to a bounded set of IDs (oldest dropped). */
+function rememberID(set: Set<string>, id: string, limit = 1000): void {
+  set.add(id)
+  if (set.size > limit) set.delete(set.values().next().value!)
+}
+
 const eventSessionID = (event: ForwardedEvent): string | undefined => {
   const data = event.data as Record<string, any>
   const id = event.type === "form.created" ? data.form?.sessionID : data.sessionID
@@ -440,9 +459,11 @@ export class Registry {
   private readonly humanTurnListeners = new Set<(sessionID: string, tenant?: string) => void>()
   private readonly sessionDeletedListeners = new Set<(sessionID: string, tenant: string) => void>()
   /** Pending form ID → its session and every connection that forwarded it, first first (like permissions). */
-  private readonly forms = new Map<string, { connIDs: string[]; sessionID: string }>()
-  /** Form IDs already alerted (forms may be forwarded by several processes). */
+  private readonly forms = new Map<string, PendingForm>()
+  /** Form IDs already alerted (forms may be forwarded by several processes, and re-announced after a reconnect). */
   private readonly alertedForms = new Set<string>()
+  /** Permission IDs already alerted (a reconnecting spoke re-announces what is still pending). */
+  private readonly alertedPermissions = new Set<string>()
   /** Sessions whose current run raised a providerError notification (once per run; cleared when a run starts). */
   private readonly providerAlerted = new Set<string>()
   /** Sessions in conversation mode → the connection last told so (re-sent when another one takes over). */
@@ -719,6 +740,8 @@ export class Registry {
       const owner = this.sessionTenant(id)
       if (owner !== undefined && owner !== tenant) return
     }
+    // A question or permission whose ID no card can carry is never kept (no card, no answer; unbounded memory).
+    if (oversizedBlockerID(event.type, data)) return
     if (sessionID) conn.activity.set(sessionID, this.tick())
     if (sessionID && event.type.startsWith("session.execution.")) {
       if (event.type === "session.execution.interrupted" && data.inferred === true) remember(this.inferredEnds, sessionID, this.now())
@@ -733,34 +756,46 @@ export class Registry {
     if (event.type === "permission.asked" && typeof data.id === "string" && sessionID) {
       const known = this.permissions.get(data.id)
       if (known) {
-        // The same request forwarded by another process: one more place to answer it.
+        // The same request forwarded by another process (or re-announced): one more place to answer it, and its
+        // blocker back on a status board that lost it.
         if (!known.connIDs.includes(connID)) known.connIDs.push(connID)
+        this.observeBoards(event, tenant)
         return
       }
       const request = permissionRequest(data)
-      this.permissions.set(data.id, { connIDs: [connID], sessionID, tenant, ...(request ? { request } : {}) })
-      this.alert("permission", sessionID, { requestID: data.id })
+      const blocker = askBlocker(event)
+      this.permissions.set(data.id, { connIDs: [connID], sessionID, tenant, ...(request ? { request } : {}), ...(blocker ? { blocker } : {}) })
+      this.capPending(this.permissions, tenant, (id) => this.dropPermission(id))
+      if (!this.alertedPermissions.has(data.id) && this.alert("permission", sessionID, { requestID: data.id })) rememberID(this.alertedPermissions, data.id)
     }
     if (event.type === "form.created" && sessionID) {
       const formID = (data.form as Record<string, unknown> | undefined)?.id
       if (typeof formID === "string") {
         const known = this.forms.get(formID)
         if (known && !known.connIDs.includes(connID)) known.connIDs.push(connID)
-        else if (!known) remember(this.forms, formID, { connIDs: [connID], sessionID })
-      }
-      if (typeof formID === "string" && !this.alertedForms.has(formID)) {
-        this.alertedForms.add(formID)
-        if (this.alertedForms.size > 1000) this.alertedForms.delete(this.alertedForms.values().next().value!)
-        this.alert("question", sessionID)
+        else if (!known) {
+          const blocker = askBlocker(event)
+          this.forms.set(formID, { connIDs: [connID], sessionID, tenant, ...(blocker ? { blocker } : {}) })
+          this.capPending(this.forms, tenant, (id) => this.dropForm(id))
+        }
       }
+      if (typeof formID === "string" && !this.alertedForms.has(formID) && this.alert("question", sessionID)) rememberID(this.alertedForms, formID)
     }
     let closedPermission: [string, PendingPermission] | undefined
-    if (event.type === "permission.replied" && typeof data.requestID === "string") {
-      const origin = this.permissions.get(data.requestID)
-      if (origin && this.permissions.delete(data.requestID)) closedPermission = [data.requestID, origin]
-    }
-    if ((event.type === "form.replied" || event.type === "form.cancelled") && typeof data.id === "string") {
-      this.forms.delete(data.id)
+    const permissionClose = event.type === "permission.replied" && typeof data.requestID === "string"
+    const formClose = (event.type === "form.replied" || event.type === "form.cancelled") && typeof data.id === "string"
+    if (permissionClose || formClose) {
+      const id = (permissionClose ? data.requestID : data.id) as string
+      const map: Map<string, PendingPermission | PendingForm> = permissionClose ? this.permissions : this.forms
+      const origin = map.get(id)
+      // Only the tenant that asked closes it (IDs are not secret enough to let another tenant end it).
+      const own = origin !== undefined && (origin.tenant === undefined || origin.tenant === tenant)
+      if (own && data.unlisted === true) {
+        // A spoke found it no longer listed by its own harness: only that process stops holding it.
+        origin.connIDs = origin.connIDs.filter((c) => c !== connID)
+        if (origin.connIDs.length) return
+      }
+      if (own && map.delete(id) && permissionClose) closedPermission = [id, origin as PendingPermission]
     }
 
     if (sessionID) this.trackRun(event.type, sessionID)
@@ -1951,6 +1986,33 @@ export class Registry {
       if (next.length === pending.length) break
       pending = next
     }
+    this.restoreBlockers()
+  }
+
+  /** Keeps at most PENDING_PER_TENANT entries of the tenant in a pending map: the oldest are dropped (with their blocker). */
+  private capPending(map: Map<string, PendingPermission | PendingForm>, tenant: string, drop: (id: string) => void): void {
+    const own = [...map].filter(([, origin]) => (origin.tenant ?? this.sessionTenant(origin.sessionID)) === tenant)
+    for (const [id] of own.slice(0, Math.max(0, own.length - PENDING_PER_TENANT))) drop(id)
+  }
+
+  /**
+   * Puts pending permissions and forms back on the status boards that lost them: a board recreated after its
+   * session left the reported sessions for a moment, or one created after the question was asked (events reach
+   * only existing boards). OpenCode still waits for them; only a reply, a cancel or their processes going away
+   * end them (production 2026-11-05: a question card vanished while the session still waited).
+   */
+  private restoreBlockers(): void {
+    const restored = new Set<string>()
+    const restore = ({ sessionID, tenant, blocker }: PendingPermission | PendingForm) => {
+      if (!blocker) return
+      const rootID = this.rootOf(sessionID)
+      const board = rootID === undefined ? undefined : this.boards.get(rootID)
+      if (!rootID || !board || (tenant !== undefined && this.sessionTenant(rootID) !== tenant)) return
+      if (board.restoreBlocker(sessionID, blocker)) restored.add(rootID)
+    }
+    for (const origin of this.permissions.values()) restore(origin)
+    for (const origin of this.forms.values()) restore(origin)
+    for (const rootID of restored) this.emit({ type: "status", sessionID: rootID, sessions: this.live(this.boards.get(rootID)!.snapshot().sessions) })
   }
 
   // ---------- cluster (design §9) ----------
@@ -1978,7 +2040,7 @@ export class Registry {
     const add = (tenant: string | undefined) => tenant !== undefined && tenants.add(tenant)
     for (const rootID of this.boards.keys()) add(this.sessionTenant(rootID))
     for (const origin of this.permissions.values()) add(origin.tenant ?? this.sessionTenant(origin.sessionID))
-    for (const origin of this.forms.values()) add(this.sessionTenant(origin.sessionID))
+    for (const origin of this.forms.values()) add(origin.tenant ?? this.sessionTenant(origin.sessionID))
     for (const entry of this.presence.values()) add(this.sessionTenant(entry.sessionID))
     for (const sessionID of this.active.keys()) add(this.sessionTenant(sessionID))
     return [...tenants]
@@ -2113,11 +2175,12 @@ export class Registry {
    * Raises a notification for the root of `sessionID`'s tree. Only hand-offs, questions and permissions reach a
    * session some device shows (spoken replies check that themselves: the watching device speaks them).
    */
-  private alert(kind: NotificationKind, sessionID: string, fields: { text?: string; requestID?: string; subject?: string; key?: string; unlessPref?: NotificationKind } = {}): void {
+  /** True when it was raised (or skipped because a device shows the session); false for a session on no board. */
+  private alert(kind: NotificationKind, sessionID: string, fields: { text?: string; requestID?: string; subject?: string; key?: string; unlessPref?: NotificationKind } = {}): boolean {
     const entry = [...this.boards].find(([, board]) => board.get(sessionID))
-    if (!entry) return
+    if (!entry) return false
     const [rootID, board] = entry
-    if (!ALWAYS_ALERT.has(kind) && this.watched(rootID)) return
+    if (!ALWAYS_ALERT.has(kind) && this.watched(rootID)) return true
     const alert: Alert = {
       kind,
       sessionID: rootID,
@@ -2130,6 +2193,7 @@ export class Registry {
     }
     const owner = this.sessionTenant(rootID)
     for (const listener of this.alertListeners) listener(owner ? { ...alert, owner } : alert)
+    return true
   }
 
   private emit(message: RegistryMessage): void {
@@ -2137,3 +2201,10 @@ export class Registry {
     for (const listener of this.listeners) listener(message, tenant)
   }
 }
+
+/** A permission.asked / form.created (or their closes) with an ID longer than any card keeps. */
+function oversizedBlockerID(type: string, data: Record<string, unknown>): boolean {
+  const ids =
+    type === "permission.asked" ? [data.id] : type === "form.created" ? [(data.form as Record<string, unknown> | undefined)?.id] : []
+  return ids.some((id) => typeof id === "string" && id.length > BLOCKER_ID_MAX)
+}