dsh-computers 1.1.0 → 1.3.0

package/lib/routes.js

@@ -21,6 +21,7 @@ import {
   optionalCount, optionalString, platformLabel, sha256Hex, tokenMatches,
 } from './keys.js'
 import { normalizeSessionId } from './selection.js'
+import { versionAtLeast, versionsDiffer } from './version.js'
 
 /** Base path shared by every route (PROTOCOL §3). */
 export const API_BASE = '/api/dsh-computers'
@@ -34,6 +35,12 @@ const CONTROL_MAX_BYTES = 16 * 1024
 /** Result posts carry two ≤1 MiB streams plus JSON escaping. */
 const RESULT_MAX_BYTES = 8 * 1024 * 1024
 
+/** Streaming chunk frames are small (≤32 KiB output, base64 + JSON). */
+const CHUNK_MAX_BYTES = 1024 * 1024
+
+/** File responses can carry 5 000 entries / 500 matches; stay generous but bounded. */
+const FS_RESULT_MAX_BYTES = 16 * 1024 * 1024
+
 /** Platform names an agent may report → the label the settings page shows. */
 const PLATFORM_LABELS = new Map([
   ['macos', 'macOS'],
@@ -107,7 +114,7 @@ function createRouteRegistrar(ctx, onWarn) {
  * @param {URL} options.agentUrl - machine agent bundle location.
  * @param {(message: string) => void} [options.onWarn] - warning sink.
  */
-export function createRoutes({ ctx, config, store, hub, selections, version, agentUrl, role = 'both', onWarn = () => {} }) {
+export function createRoutes({ ctx, config, store, hub, selections, access, fsOps = null, version, agentUrl, role = 'both', onWarn = () => {} }) {
   /** Current clock as ISO text. */
   const nowIso = () => new Date().toISOString()
   /** Parsed request URL (pathname + query). */
@@ -115,6 +122,102 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
   /** Exact-route registrar shared with the runtime surface. */
   const route = createRouteRegistrar(ctx, onWarn)
 
+  /** Agent features reported by the computer (v1 agents report none = exec). */
+  const capabilitiesOf = (computer) => (Array.isArray(computer.capabilities) && computer.capabilities.length > 0
+    ? computer.capabilities.filter((entry) => typeof entry === 'string')
+    : ['exec'])
+
+  /** The computer's default working directory, when its agent reported one. */
+  const workspaceBaseOf = (computer) => (typeof computer.workspaceBase === 'string' && computer.workspaceBase !== ''
+    ? computer.workspaceBase
+    : null)
+
+  /** §11.6.4: an enrollment is pending until its first successful stream. */
+  const isActivated = (computer) => typeof computer.activatedAt === 'string'
+
+  /** Computers the browser/tools may see (activated only). */
+  const visibleComputers = () => store.read().computers.filter(isActivated)
+
+  /** Whether the computer's agentVersion is behind this plugin's. */
+  const isDrift = (computer) => versionsDiffer(computer.agentVersion, version)
+
+  /** §11.6.5: whether the agent is older than the configured minimum. */
+  const needsUpdate = (computer) => !versionAtLeast(computer.agentVersion, config.minAgentVersion)
+
+  /** Coerce one reported capability list. */
+  const cleanCapabilities = (value) => (Array.isArray(value)
+    ? [...new Set(value.filter((entry) => typeof entry === 'string').map((entry) => entry.trim()).filter((entry) => ['exec', 'fs', 'pty'].includes(entry)))]
+    : null)
+
+  /** Coerce a reported workspace base (absolute POSIX or Windows path). */
+  const cleanWorkspaceBase = (value) => {
+    if (typeof value !== 'string') return null
+    const trimmed = value.trim()
+    if (trimmed === '' || trimmed.length > 1024) return null
+    return /^(\/|[A-Za-z]:[\\/])/.test(trimmed) ? trimmed : null
+  }
+
+  /**
+   * Handshake metadata from a stream open (§11.6.1): query `?meta=<json>` and/or
+   * `x-dsh-*` headers. Unknown fields are ignored.
+   */
+  const handshakeFromRequest = (req) => {
+    let meta = {}
+    // The agent's own transport (§11.6.1): base64url JSON in one header.
+    const encoded = req.headers?.['x-dsh-computers-metadata']
+    const encodedText = Array.isArray(encoded) ? encoded[0] : encoded
+    if (typeof encodedText === 'string' && encodedText.trim() !== '') {
+      try {
+        const parsed = JSON.parse(Buffer.from(encodedText.trim(), 'base64url').toString('utf8'))
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) meta = parsed
+      } catch {
+        // A malformed handshake header simply contributes nothing.
+      }
+    }
+    const rawMeta = urlOf(req).searchParams.get('meta')
+    if (rawMeta !== null && rawMeta !== '') {
+      try {
+        const parsed = JSON.parse(rawMeta)
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) meta = parsed
+      } catch {
+        // A malformed meta blob simply contributes nothing.
+      }
+    }
+    const headerField = {
+      'x-dsh-agent-version': 'agentVersion',
+      'x-dsh-hostname': 'hostname',
+      'x-dsh-os': 'os',
+      'x-dsh-arch': 'arch',
+      'x-dsh-workspace-base': 'workspaceBase',
+      'x-dsh-capabilities': 'capabilities',
+    }
+    for (const [header, field] of Object.entries(headerField)) {
+      const raw = req.headers?.[header]
+      const text = Array.isArray(raw) ? raw[0] : raw
+      if (typeof text !== 'string' || text.trim() === '') continue
+      meta[field] = field === 'capabilities'
+        ? text.split(',').map((entry) => entry.trim()).filter((entry) => entry !== '')
+        : text.trim()
+    }
+    return meta
+  }
+
+  /** The §3.1 enrollment metadata fields present in one body. */
+  const enrollMetadata = (body, machine) => {
+    const source = machine !== null && typeof machine === 'object' ? machine : {}
+    const metadata = body.metadata !== null && typeof body.metadata === 'object' && !Array.isArray(body.metadata) ? body.metadata : {}
+    const capabilities = cleanCapabilities(body.capabilities)
+      ?? cleanCapabilities(metadata.capabilities)
+      ?? cleanCapabilities(source.capabilities)
+    const workspaceBase = cleanWorkspaceBase(body.workspaceBase)
+      ?? cleanWorkspaceBase(metadata.workspaceBase)
+      ?? cleanWorkspaceBase(source.workspaceBase)
+    return {
+      ...(capabilities === null ? {} : { capabilities }),
+      ...(workspaceBase === null ? {} : { workspaceBase }),
+    }
+  }
+
   /** Ask the host's browser gate; true when the request was already refused. */
   const refuseBrowser = (req, res) => refuseBrowserRequest(ctx, req, res)
 
@@ -149,9 +252,10 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     return null
   }
 
-  /** Protocol §4.1 projection of one registry record. */
+  /** Protocol §4.1 + §11.1 projection of one registry record. */
   const publicComputer = (computer) => {
     const online = hub.isOnline(computer)
+    const capabilities = capabilitiesOf(computer)
     return {
       id: computer.id,
       name: computer.name,
@@ -161,7 +265,13 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
       online,
       lastSeenAt: computer.lastSeenAt ?? null,
       createdAt: computer.createdAt ?? null,
+      activatedAt: computer.activatedAt ?? null,
       agentVersion: computer.agentVersion ?? null,
+      capabilities,
+      capabilitiesUpdatedAt: computer.capabilitiesUpdatedAt ?? null,
+      workspaceBase: workspaceBaseOf(computer),
+      drift: isDrift(computer),
+      updateRequired: needsUpdate(computer),
       cpuModel: computer.cpuModel ?? null,
       memoryBytes: computer.memoryBytes ?? null,
       // Display sugar for the "1/1 Bot" badge (PROTOCOL §4.1).
@@ -222,33 +332,43 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
       : null
     const hostname = optionalString(machine?.hostname, 255)
     if (hostname === null) throw new HttpError(400, 'bad-request', 'machine.hostname is required')
-    const osName = optionalString(machine?.os, 64) ?? 'unknown'
-    const displayName = normalizeDisplayName(pendingKey.label)
+    const osName = optionalString(machine?.os, 64)
+    const explicitName = normalizeDisplayName(pendingKey.label)
       ?? normalizeDisplayName(optionalString(machine?.name, 255))
-      ?? hostname
+    const displayName = explicitName ?? hostname
     const requestedPlatform = optionalString(machine?.platform, 64)
     const label = requestedPlatform !== null
-      ? PLATFORM_LABELS.get(requestedPlatform.toLowerCase()) ?? platformLabel(osName)
-      : platformLabel(osName)
+      ? PLATFORM_LABELS.get(requestedPlatform.toLowerCase()) ?? (osName === null ? null : platformLabel(osName))
+      : (osName === null ? null : platformLabel(osName))
 
+    // Only fields the agent actually reported are merged. A re-enroll on a
+    // reconnecting stream must not downgrade unknown fields to "unknown".
     const fields = {
       name: displayName,
       hostname,
       os: osName,
-      arch: optionalString(machine?.arch, 64) ?? 'unknown',
+      arch: optionalString(machine?.arch, 64),
       platformLabel: label,
-      cpuModel: optionalString(machine?.cpuModel, 256) ?? null,
-      memoryBytes: optionalCount(machine?.memoryBytes) ?? null,
-      nodeVersion: optionalString(machine?.nodeVersion, 64) ?? null,
-      agentVersion: optionalString(body.agentVersion, 64) ?? optionalString(machine?.agentVersion, 64) ?? 'unknown',
+      cpuModel: optionalString(machine?.cpuModel, 256),
+      memoryBytes: optionalCount(machine?.memoryBytes),
+      nodeVersion: optionalString(machine?.nodeVersion, 64),
+      agentVersion: optionalString(body.agentVersion, 64) ?? optionalString(machine?.agentVersion, 64),
     }
+    const definedFields = Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== null))
+    const metadata = enrollMetadata(body, machine)
+    const nowEnroll = nowIso()
     const token = mintSecret()
     const tokenHash = sha256Hex(token)
-    // Re-enroll in place only when the key asked for it (PROTOCOL §3.1).
-    const replaceTarget = pendingKey.replace === true
-      ? doc.computers.find((computer) => computer.hostname === hostname
-        || computer.name.toLowerCase() === displayName.toLowerCase())
-      : undefined
+    // Re-enroll in place when the key asked for it (PROTOCOL §3.1) or when
+    // this still-pending key is already bound to a computer (retry before the
+    // first successful stream, §11.6.4).
+    const boundId = typeof pendingKey.computerId === 'string' ? pendingKey.computerId : null
+    const replaceTarget = boundId !== null
+      ? doc.computers.find((computer) => computer.id === boundId)
+      : pendingKey.replace === true
+        ? doc.computers.find((computer) => computer.hostname === hostname
+          || computer.name.toLowerCase() === displayName.toLowerCase())
+        : undefined
 
     const enrolled = store.mutate((document) => {
       const keyEntry = document.pendingKeys.find((entry) => entry.key === keyValue)
@@ -260,21 +380,45 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
         computer = document.computers.find((entry) => entry.id === replaceTarget.id)
       }
       if (computer !== undefined) {
-        // Same id, same name unless the agent reported a new one: the old
-        // token hash is replaced so the previous install stops working.
-        Object.assign(computer, fields, { tokenHash, lastSeenAt: nowIso() })
+        // Same id: replace the token so the previous install stops working.
+        // A re-enroll that reports no machine.name must NOT rename the record
+        // to the hostname (the user's chosen name survives reconnects).
+        const previousName = computer.name
+        Object.assign(computer, definedFields, metadata, {
+          tokenHash,
+          lastSeenAt: nowEnroll,
+          capabilities: metadata.capabilities ?? computer.capabilities ?? ['exec'],
+          capabilitiesUpdatedAt: nowEnroll,
+        })
+        if (explicitName === null) computer.name = previousName
       } else {
         computer = {
           id: newComputerId(),
-          ...fields,
+          version: 1,
+          name: displayName,
+          hostname,
+          os: osName ?? 'unknown',
+          arch: optionalString(machine?.arch, 64) ?? 'unknown',
+          platformLabel: label ?? 'Unknown',
+          cpuModel: optionalString(machine?.cpuModel, 256),
+          memoryBytes: optionalCount(machine?.memoryBytes),
+          nodeVersion: optionalString(machine?.nodeVersion, 64),
+          agentVersion: optionalString(body.agentVersion, 64) ?? optionalString(machine?.agentVersion, 64) ?? 'unknown',
+          ...metadata,
+          capabilities: metadata.capabilities ?? ['exec'],
+          capabilitiesUpdatedAt: nowEnroll,
+          workspaceBase: metadata.workspaceBase ?? null,
           tokenHash,
-          createdAt: nowIso(),
-          lastSeenAt: nowIso(),
+          createdAt: nowEnroll,
+          lastSeenAt: nowEnroll,
+          // §11.6.4: hidden from the list until the first successful stream.
+          activatedAt: null,
         }
         document.computers.push(computer)
       }
-      keyEntry.usedAt = nowIso()
+      // The key stays unused/pending until the agent's first stream activates it.
       keyEntry.computerId = computer.id
+      keyEntry.enrolledAt = nowEnroll
       return { computerId: computer.id, name: computer.name, replaced: replaceTarget !== undefined }
     })
 
@@ -295,8 +439,53 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     const computer = requireComputer(req, res)
     if (computer === undefined) return
     if (!requireMethod(req, res, 'GET')) return
-    store.touch(computer.id)
-    hub.openStream(computer.id, computer.name, req, res)
+    const handshake = handshakeFromRequest(req)
+    const capabilities = cleanCapabilities(handshake.capabilities)
+    const workspaceBase = cleanWorkspaceBase(handshake.workspaceBase)
+    const agentVersion = optionalString(handshake.agentVersion, 64)
+    const handshakeHost = optionalString(handshake.hostname, 255)
+    const handshakeOs = optionalString(handshake.os, 64)
+    const handshakeArch = optionalString(handshake.arch, 64)
+    const activated = store.mutate((document) => {
+      const record = document.computers.find((entry) => entry.id === computer.id)
+      if (record === undefined) return null
+      const now = nowIso()
+      record.lastSeenAt = now
+      // §11.6.1: every reconnect refreshes the stored handshake metadata.
+      if (agentVersion !== null) record.agentVersion = agentVersion
+      if (handshakeHost !== null) record.hostname = handshakeHost
+      if (handshakeOs !== null) record.os = handshakeOs
+      if (handshakeArch !== null) record.arch = handshakeArch
+      if (capabilities !== null) {
+        record.capabilities = capabilities
+        record.capabilitiesUpdatedAt = now
+      }
+      if (workspaceBase !== null) record.workspaceBase = workspaceBase
+      const firstStream = typeof record.activatedAt !== 'string'
+      if (firstStream) record.activatedAt = now
+      // §11.6.4: the first successful stream activates the enrollment.
+      if (firstStream) {
+        for (const key of document.pendingKeys) {
+          if (key.computerId === record.id && typeof key.usedAt !== 'string') key.usedAt = now
+        }
+      }
+      return {
+        name: record.name,
+        capabilities: Array.isArray(record.capabilities) && record.capabilities.length > 0 ? record.capabilities : ['exec'],
+      }
+    })
+    if (activated === null) {
+      jsonError(res, 401, 'invalid-token', 'authorization: Bearer <agent token> is required')
+      return
+    }
+    hub.openStream(computer.id, activated.name, req, res, { capabilities: activated.capabilities })
+    if (fsOps !== null) {
+      // Abandon file requests whose stream died (but not one replaced by a
+      // reconnecting stream for the same computer).
+      res.on('close', () => {
+        if (!hub.isLive(computer.id)) fsOps.failComputer(computer.id)
+      })
+    }
   })
 
   route('/agent/results', async (req, res) => {
@@ -315,6 +504,32 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     sendJson(res, 200, { ok: true })
   })
 
+  route('/agent/results/chunk', async (req, res) => {
+    const computer = requireComputer(req, res)
+    if (computer === undefined) return
+    if (!requireMethod(req, res, 'POST')) return
+    const body = await readObjectBody(req, CHUNK_MAX_BYTES)
+    store.touch(computer.id)
+    if (!hub.settleChunk(computer.id, body)) {
+      jsonError(res, 404, 'unknown-request', 'this execution is no longer pending (already settled or timed out)')
+      return
+    }
+    sendJson(res, 200, { ok: true })
+  })
+
+  route('/agent/fs/result', async (req, res) => {
+    const computer = requireComputer(req, res)
+    if (computer === undefined) return
+    if (!requireMethod(req, res, 'POST')) return
+    const body = await readObjectBody(req, FS_RESULT_MAX_BYTES)
+    store.touch(computer.id)
+    if (fsOps === null || !fsOps.settle(computer.id, body)) {
+      jsonError(res, 404, 'unknown-request', 'this file request is no longer pending')
+      return
+    }
+    sendJson(res, 200, { ok: true })
+  })
+
   route('/agent/heartbeat', async (req, res) => {
     // Authenticate before anything else on machine routes (PROTOCOL §3).
     const computer = requireComputer(req, res)
@@ -322,22 +537,30 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     if (!requireMethod(req, res, 'POST')) return
     let body = {}
     try {
-      body = await readObjectBody(req, 64 * 1024)
+      body = await readObjectBody(req, 256 * 1024)
     } catch (error) {
       // An empty heartbeat body is legal; anything else is still a 400.
       if (!(error instanceof HttpError) || error.code !== 'bad-request' || !/empty/.test(error.message)) throw error
     }
     const meta = body.meta !== null && typeof body.meta === 'object' && !Array.isArray(body.meta) ? body.meta : null
+    const reportedCapabilities = cleanCapabilities(body.capabilities) ?? cleanCapabilities(meta?.capabilities)
+    const reportedWorkspaceBase = cleanWorkspaceBase(body.workspaceBase) ?? cleanWorkspaceBase(meta?.workspaceBase)
     const name = store.mutate((document) => {
       const record = document.computers.find((entry) => entry.id === computer.id)
       if (record === undefined) return computer.name
-      record.lastSeenAt = nowIso()
+      const now = nowIso()
+      record.lastSeenAt = now
+      if (reportedCapabilities !== null) {
+        record.capabilities = reportedCapabilities
+        record.capabilitiesUpdatedAt = now
+      }
+      if (reportedWorkspaceBase !== null) record.workspaceBase = reportedWorkspaceBase
+      const agentVersion = optionalString(body.agentVersion, 64) ?? optionalString(meta?.agentVersion, 64)
+      if (agentVersion !== null) record.agentVersion = agentVersion
       if (meta !== null) {
         const cpuModel = optionalString(meta.cpuModel, 256)
-        const agentVersion = optionalString(meta.agentVersion, 64)
         const memoryBytes = optionalCount(meta.memoryBytes)
         if (cpuModel !== null) record.cpuModel = cpuModel
-        if (agentVersion !== null) record.agentVersion = agentVersion
         if (memoryBytes !== null) record.memoryBytes = memoryBytes
       }
       return record.name
@@ -360,7 +583,8 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
       role,
       serverUrl: resolveBaseUrl({ ctx, config, req }),
       heartbeatMs: config.heartbeatMs,
-      computers: doc.computers.map(publicComputer),
+      // §11.6.4: a computer appears only after its first successful stream.
+      computers: visibleComputers().map(publicComputer),
       pendingKey: pendingKey === null
         ? null
         : { key: pendingKey.key, expiresAt: pendingKey.expiresAt ?? null, os: pendingKey.os ?? 'macos' },
@@ -433,7 +657,11 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
       const linked = typeof entry.computerId === 'string'
         ? doc.computers.find((candidate) => candidate.id === entry.computerId)
         : undefined
-      if (linked !== undefined) {
+      if (linked !== undefined && !isActivated(linked)) {
+        // Enrolled but the agent never completed a stream: the dialog keeps
+        // polling (§11.6.4).
+        status = 'waiting'
+      } else if (linked !== undefined) {
         status = 'connected'
         computer = { id: linked.id, name: linked.name, online: hub.isOnline(linked) }
       } else if (typeof entry.usedAt === 'string') {
@@ -457,9 +685,11 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     const found = store.read().computers.some((computer) => computer.id === id)
     if (!found) throw new HttpError(404, 'not-found', `no computer with id ${JSON.stringify(id)}`)
     hub.closeStream(id)
+    if (fsOps !== null) fsOps.failComputer(id, 'the computer was deleted')
     store.mutate((document) => {
       document.computers = document.computers.filter((computer) => computer.id !== id)
     })
+    access.store.forgetComputer(id)
     sendJson(res, 200, { ok: true })
   })
 
@@ -483,6 +713,148 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
     sendJson(res, 200, { ok: true, name })
   })
 
+  // ---------------------------------------------------------------------------
+  // Access control (the two access dialogs)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Payload for the conversation-level dialog ("它可以使用哪些电脑?"): every
+   * computer with the EFFECTIVE answer for this session's preset + allow-list.
+   * `sessionAllowed` is the raw rule (null = "all"), so the client can tell a
+   * customized list from the default.
+   */
+  const accessPayload = async (sessionId) => {
+    const presetId = access.presetIdForSession(sessionId)
+    const presets = await access.presets()
+    const sessionAllowed = access.store.sessionAllow(sessionId)
+    return {
+      sessionId,
+      presetId,
+      presets,
+      computers: visibleComputers().map((computer) => {
+        const presetOk = access.presetAllows(computer.id, presetId)
+        const sessionOk = access.sessionAllows(sessionId, computer.id)
+        return {
+          id: computer.id,
+          name: computer.name,
+          online: hub.isOnline(computer),
+          platformLabel: computer.platformLabel ?? 'Unknown',
+          allowed: presetOk && sessionOk,
+          sessionAllowed: sessionOk,
+          presetAllowed: presetOk,
+        }
+      }),
+      sessionAllowed,
+    }
+  }
+
+  /** Payload for the computer-level dialog ("哪些 Bot 可以使用它?"). */
+  const accessComputerPayload = async (computerId) => {
+    const computer = visibleComputers().find((candidate) => candidate.id === computerId)
+    if (computer === undefined) {
+      throw new HttpError(404, 'not-found', `no computer with id ${JSON.stringify(computerId)}`)
+    }
+    const presets = await access.presets()
+    const allowedPresets = access.store.computerPresets(computerId)
+    return {
+      computer: {
+        id: computer.id,
+        name: computer.name,
+        online: hub.isOnline(computer),
+        platformLabel: computer.platformLabel ?? 'Unknown',
+      },
+      presets: presets.map((preset) => ({
+        id: preset.id,
+        name: preset.name,
+        allowed: allowedPresets === null || allowedPresets.includes(preset.id),
+      })),
+      allowedPresets,
+    }
+  }
+
+  route('/access', async (req, res) => {
+    // The host's request gate runs first on every browser route (PROTOCOL §4).
+    if (refuseBrowser(req, res)) return
+    const method = typeof req.method === 'string' ? req.method.toUpperCase() : ''
+    if (method === 'GET' || method === 'HEAD') {
+      const sessionId = normalizeSessionId(urlOf(req).searchParams.get('sessionId'))
+      if (sessionId === null) {
+        throw new HttpError(400, 'bad-request', 'sessionId must be a non-empty string (max 256 characters)')
+      }
+      sendJson(res, 200, await accessPayload(sessionId))
+      return
+    }
+    if (method === 'POST') {
+      const body = await readObjectBody(req, CONTROL_MAX_BYTES)
+      const sessionId = normalizeSessionId(body.sessionId)
+      if (sessionId === null) {
+        throw new HttpError(400, 'bad-request', 'sessionId must be a non-empty string (max 256 characters)')
+      }
+      if (!Object.hasOwn(body, 'allowedComputers')) {
+        throw new HttpError(400, 'bad-request', 'allowedComputers is required (an array of computer ids or null)')
+      }
+      if (body.allowedComputers !== null) {
+        if (!Array.isArray(body.allowedComputers)) {
+          throw new HttpError(400, 'bad-request', 'allowedComputers must be an array of computer ids or null')
+        }
+        const known = new Set(visibleComputers().map((computer) => computer.id))
+        for (const entry of body.allowedComputers) {
+          if (typeof entry !== 'string' || !known.has(entry.trim())) {
+            throw new HttpError(400, 'bad-request', `unknown computer id ${JSON.stringify(entry)}`)
+          }
+        }
+      }
+      access.store.setSessionAllow(sessionId, body.allowedComputers)
+      sendJson(res, 200, await accessPayload(sessionId))
+      return
+    }
+    methodNotAllowed(res, 'GET / POST')
+  })
+
+  route('/access/computer', async (req, res) => {
+    // The host's request gate runs first on every browser route (PROTOCOL §4).
+    if (refuseBrowser(req, res)) return
+    const method = typeof req.method === 'string' ? req.method.toUpperCase() : ''
+    if (method === 'GET' || method === 'HEAD') {
+      const computerId = typeof urlOf(req).searchParams.get('computerId') === 'string'
+        ? urlOf(req).searchParams.get('computerId').trim()
+        : ''
+      if (computerId === '') {
+        throw new HttpError(400, 'bad-request', 'computerId is required')
+      }
+      sendJson(res, 200, await accessComputerPayload(computerId))
+      return
+    }
+    if (method === 'POST') {
+      const body = await readObjectBody(req, CONTROL_MAX_BYTES)
+      const computerId = typeof body.computerId === 'string' ? body.computerId.trim() : ''
+      if (computerId === '') {
+        throw new HttpError(400, 'bad-request', 'computerId is required')
+      }
+      const known = visibleComputers().some((computer) => computer.id === computerId)
+      if (!known) throw new HttpError(404, 'not-found', `no computer with id ${JSON.stringify(computerId)}`)
+      if (!Object.hasOwn(body, 'allowedPresets')) {
+        throw new HttpError(400, 'bad-request', 'allowedPresets is required (an array of preset ids or null)')
+      }
+      if (body.allowedPresets !== null) {
+        if (!Array.isArray(body.allowedPresets)) {
+          throw new HttpError(400, 'bad-request', 'allowedPresets must be an array of preset ids or null')
+        }
+        const roster = await access.presets()
+        const knownPresets = new Set(roster.map((preset) => preset.id))
+        for (const entry of body.allowedPresets) {
+          if (typeof entry !== 'string' || !knownPresets.has(entry.trim())) {
+            throw new HttpError(400, 'bad-request', `unknown Agent preset id ${JSON.stringify(entry)}`)
+          }
+        }
+      }
+      access.store.setComputerPresets(computerId, body.allowedPresets)
+      sendJson(res, 200, await accessComputerPayload(computerId))
+      return
+    }
+    methodNotAllowed(res, 'GET / POST')
+  })
+
   // ---------------------------------------------------------------------------
   // Per-session target selection (task-9)
   // ---------------------------------------------------------------------------
@@ -495,7 +867,7 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
   const selectionPayload = (sessionId, selectedId) => {
     const computer = selectedId === null
       ? undefined
-      : store.read().computers.find((candidate) => candidate.id === selectedId)
+      : visibleComputers().find((candidate) => candidate.id === selectedId)
     return {
       sessionId,
       computerId: computer === undefined ? null : computer.id,
@@ -540,8 +912,14 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
         throw new HttpError(400, 'bad-request', 'computerId must be a non-empty string or null')
       }
       const computerId = body.computerId.trim()
-      const known = store.read().computers.some((candidate) => candidate.id === computerId)
-      if (!known) throw new HttpError(404, 'not-found', `no computer with id ${JSON.stringify(computerId)}`)
+      const computer = visibleComputers().find((candidate) => candidate.id === computerId)
+      if (computer === undefined) throw new HttpError(404, 'not-found', `no computer with id ${JSON.stringify(computerId)}`)
+      // Pinning is itself an authorization decision: a conversation may not
+      // pin a machine its preset rule or allow-list denies.
+      const presetId = access.presetIdForSession(sessionId)
+      if (!access.isAllowed({ sessionId, presetId, computerId })) {
+        throw new HttpError(403, 'forbidden', access.denialMessage(computer, presetId))
+      }
       selections.set(sessionId, computerId)
       sendJson(res, 200, selectionPayload(sessionId, computerId))
       return
@@ -576,12 +954,21 @@ export function createRoutes({ ctx, config, store, hub, selections, version, age
 
   route('/health', async (req, res) => {
     if (!requireMethod(req, res, 'GET')) return
-    const computers = store.read().computers
+    const computers = visibleComputers()
     sendJson(res, 200, {
       ok: true,
       version,
       computers: computers.length,
-      online: hub.onlineCount(),
+      online: computers.filter((computer) => hub.isOnline(computer)).length,
+      // §11.1: expose each agent's version/capabilities + drift inline.
+      agents: computers.map((computer) => ({
+        id: computer.id,
+        name: computer.name,
+        agentVersion: computer.agentVersion ?? null,
+        capabilities: capabilitiesOf(computer),
+        drift: isDrift(computer),
+        updateRequired: needsUpdate(computer),
+      })),
     })
   })
 }
@@ -692,6 +1079,6 @@ export function createRuntimeStatusRoutes({ ctx, config, role = 'runtime', versi
 
   route('/health', async (req, res) => {
     if (!requireMethod(req, res, 'GET')) return
-    sendJson(res, 200, { ok: true, version, computers: 0, online: 0 })
+    sendJson(res, 200, { ok: true, version, computers: 0, online: 0, agents: [] })
   })
 }

package/lib/state.js

@@ -65,11 +65,20 @@ export function prunePendingKeys(doc, nowMs) {
  * @param {unknown} raw - parsed JSON (or undefined when the file was missing).
  * @returns {object} a valid registry document.
  */
-export function normalizeState(raw) {
+export function normalizeState(raw, now = undefined) {
   const doc = emptyState()
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return doc
   if (Array.isArray(raw.computers)) {
     doc.computers = raw.computers.filter((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry))
+    for (const computer of doc.computers) {
+      // §11.6.4 migration: records written before the activation lifecycle have
+      // no `activatedAt` property at all. They were activated by definition, so
+      // backfill it from createdAt instead of hiding a working machine. A v1.1
+      // enrollment sets `activatedAt: null` explicitly and stays pending.
+      if (computer.activatedAt === undefined) {
+        computer.activatedAt = typeof computer.createdAt === 'string' ? computer.createdAt : new Date(now ?? Date.now()).toISOString()
+      }
+    }
   }
   if (Array.isArray(raw.pendingKeys)) {
     doc.pendingKeys = raw.pendingKeys.filter((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry))
@@ -104,7 +113,7 @@ export function createStore({ stateDir, now = Date.now, onWarn = () => {} }) {
       return
     }
     try {
-      doc = normalizeState(JSON.parse(raw))
+      doc = normalizeState(JSON.parse(raw), now())
     } catch {
       // A half-written legacy file must not brick the plugin: keep it for
       // inspection and start from an empty registry.