dsh-computers 0.0.0-stage → 1.3.0

package/lib/runtime.js

@@ -0,0 +1,469 @@
+/**
+ * Embedded runtime mode (PROTOCOL §10.2–§10.4).
+ *
+ * The plugin can also BE a controlled machine: this manager persists
+ * `${stateDir}/runtime.json`, enrolls this machine with one hub, and drives
+ * the agent's exported `startRuntime()` — it never reimplements the SSE/exec
+ * wire protocol, it only owns the user's switch and the process lifecycle.
+ *
+ * Topology stays hub-and-spoke: the runtime half only ever dials out to the
+ * single configured `serverUrl`, never to another machine.
+ *
+ * Node builtins only.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { arch, cpus, hostname, platform, totalmem } from 'node:os'
+import { join } from 'node:path'
+
+import { HttpError, postJson } from './http.js'
+import { platformLabel } from './keys.js'
+
+/** On-disk schema version for runtime.json. */
+export const RUNTIME_STATE_VERSION = 1
+
+/** File name inside the plugin state directory. */
+export const RUNTIME_FILE_NAME = 'runtime.json'
+
+/** Enroll POST timeout: the hub is a remote machine, so be patient but bounded. */
+const ENROLL_TIMEOUT_MS = 10_000
+
+/** Normalize an ISO-ish timestamp or null. */
+const asIsoOrNull = (value) => {
+  if (typeof value !== 'string') return null
+  const at = Date.parse(value)
+  return Number.isFinite(at) ? new Date(at).toISOString() : null
+}
+
+/**
+ * Validate and normalize a hub server URL: absolute http(s), no trailing slash.
+ * @param {unknown} raw - candidate from the config/route body.
+ * @returns {string} canonical origin.
+ */
+export function normalizeServerUrl(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new HttpError(400, 'bad-request', 'serverUrl is required')
+  }
+  let parsed
+  try {
+    parsed = new URL(raw.trim())
+  } catch {
+    throw new HttpError(400, 'bad-request', `serverUrl is not a valid URL: ${JSON.stringify(raw)}`)
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new HttpError(400, 'bad-request', 'serverUrl must use http or https')
+  }
+  return `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}`
+}
+
+/**
+ * Coerce a parsed runtime.json into the documented shape, or null when it is
+ * not a usable record. A corrupt file is set aside, never fatal.
+ * @param {unknown} raw - parsed JSON.
+ * @returns {object | null} normalized document.
+ */
+export function normalizeRuntimeState(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  if (typeof raw.serverUrl !== 'string' || raw.serverUrl.trim() === '') return null
+  if (typeof raw.computerId !== 'string' || raw.computerId.trim() === '') return null
+  if (typeof raw.token !== 'string' || raw.token.trim() === '') return null
+  return {
+    version: RUNTIME_STATE_VERSION,
+    serverUrl: raw.serverUrl.trim().replace(/\/+$/, ''),
+    computerId: raw.computerId.trim(),
+    token: raw.token.trim(),
+    name: typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name.trim() : null,
+    enabled: raw.enabled === true,
+    enrolledAt: asIsoOrNull(raw.enrolledAt),
+    lastConnectedAt: asIsoOrNull(raw.lastConnectedAt),
+    lastError: typeof raw.lastError === 'string' && raw.lastError !== '' ? raw.lastError : null,
+  }
+}
+
+/** Machine facts sent in the §3.1 enroll body. */
+function machineInfo(version) {
+  const osName = platform()
+  return {
+    hostname: hostname(),
+    name: hostname(),
+    os: osName,
+    arch: arch(),
+    platform: platformLabel(osName),
+    cpuModel: cpus()[0]?.model ?? null,
+    memoryBytes: totalmem(),
+    nodeVersion: process.version,
+    agentVersion: version,
+  }
+}
+
+/** Map a hub enroll answer onto the §10.5 error vocabulary. */
+function mapEnrollFailure(response) {
+  const data = response.data !== null && typeof response.data === 'object' ? response.data : {}
+  const hubError = typeof data.error === 'string' ? data.error : ''
+  const message = typeof data.message === 'string' && data.message !== ''
+    ? data.message
+    : hubError !== ''
+      ? hubError
+      : `the hub answered ${response.status}`
+  switch (hubError) {
+    case 'invalid-key': return new HttpError(401, 'invalid-key', message)
+    case 'key-expired': return new HttpError(410, 'key-expired', message)
+    case 'key-used': return new HttpError(409, 'key-used', message)
+    case 'bad-request': return new HttpError(400, 'bad-request', message)
+    default: break
+  }
+  switch (response.status) {
+    case 401: return new HttpError(401, 'invalid-key', message)
+    case 409: return new HttpError(409, 'key-used', message)
+    case 410: return new HttpError(410, 'key-expired', message)
+    case 400: return new HttpError(400, 'bad-request', message)
+    default: return new HttpError(502, 'hub-unreachable', `the hub answered ${response.status}: ${message}`)
+  }
+}
+
+/**
+ * Create the runtime manager for one plugin mount.
+ *
+ * All methods are total for lifecycle paths (they never throw into the host);
+ * only `configure()`/`enable()` throw `HttpError`s that the routes translate,
+ * because those are direct answers to a user action.
+ *
+ * @param {object} options - manager options.
+ * @param {object} options.config - resolved plugin config (heartbeatMs).
+ * @param {string} options.stateDir - directory holding runtime.json.
+ * @param {string} [options.version] - plugin version reported at enroll.
+ * @param {URL} [options.agentModuleUrl] - agent bundle (default: ../agent/...).
+ * @param {(message: string) => void} [options.onWarn] - host warning sink.
+ * @returns {object} the manager.
+ */
+export function createRuntimeManager({ config, stateDir, version = '1.0.0', agentModuleUrl, onWarn = () => {} }) {
+  const file = join(stateDir, RUNTIME_FILE_NAME)
+  const moduleUrl = agentModuleUrl ?? new URL('../agent/dsh-computers-agent.mjs', import.meta.url)
+
+  /** @type {object | null} */
+  let doc = null
+  /** @type {{ stop: () => Promise<void>, status?: () => object } | null} */
+  let handle = null
+  let connected = false
+  let since = null
+  let lastError = null
+  let disposed = false
+  let agentModulePromise = null
+  let warnedLine = null
+
+  /** Warn once per distinct line so a flapping runtime cannot spam the host. */
+  const warnOnce = (message) => {
+    if (message === warnedLine) return
+    warnedLine = message
+    try {
+      onWarn(message)
+    } catch {
+      // A broken log sink must not break the runtime.
+    }
+  }
+
+  const log = (level, message) => {
+    // Embedded mode: agent info stays quiet; warnings/errors go to the host
+    // sink, deduped until the next different line.
+    if (level === 'warn' || level === 'error') warnOnce(`dsh-computers runtime: ${message}`)
+  }
+
+  /** Read runtime.json; corrupt files are set aside and treated as unconfigured. */
+  const load = () => {
+    let raw
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') warnOnce(`dsh-computers: cannot read ${file}: ${error.message}`)
+      return null
+    }
+    try {
+      return normalizeRuntimeState(JSON.parse(raw))
+    } catch {
+      const aside = `${file}.corrupt-${Date.now()}`
+      try {
+        renameSync(file, aside)
+        warnOnce(`dsh-computers: ${file} was not valid JSON; moved to ${aside}`)
+      } catch {
+        warnOnce(`dsh-computers: ${file} was not valid JSON`)
+      }
+      return null
+    }
+  }
+
+  /** Write runtime.json atomically (tmp + rename, 0600). */
+  const persist = () => {
+    if (doc === null) return
+    try {
+      mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+      const tmp = join(stateDir, `.runtime.json.${process.pid}.${randomBytes(4).toString('hex')}.tmp`)
+      writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+      try {
+        chmodSync(tmp, 0o600)
+      } catch {
+        // Platforms without POSIX modes simply skip this.
+      }
+      renameSync(tmp, file)
+    } catch (error) {
+      warnOnce(`dsh-computers: cannot write ${file}: ${error && error.message ? error.message : error}`)
+    }
+  }
+
+  /** Track one agent state transition; persistence only on real changes. */
+  const applyAgentState = (state) => {
+    if (state === null || typeof state !== 'object') return
+    const nextConnected = state.connected === true
+    const nextSince = asIsoOrNull(state.since)
+    const nextError = typeof state.lastError === 'string' && state.lastError !== '' ? state.lastError : null
+    const changed = nextConnected !== connected
+    connected = nextConnected
+    since = nextConnected ? (nextSince ?? since ?? new Date().toISOString()) : null
+    if (nextError !== null) lastError = nextError
+    else if (nextConnected) lastError = null
+    if (changed && doc !== null) {
+      if (connected) {
+        doc.lastConnectedAt = since
+        doc.lastError = null
+        warnedLine = null
+      } else if (lastError !== null) {
+        doc.lastError = lastError
+        warnOnce(`dsh-computers runtime: disconnected (${lastError})`)
+      }
+      persist()
+    }
+  }
+
+  /** Import the agent bundle once; it must stay side-effect free when imported. */
+  const loadAgentModule = async () => {
+    if (agentModulePromise === null) {
+      agentModulePromise = import(moduleUrl.href)
+        .catch((error) => {
+          agentModulePromise = null
+          throw error
+        })
+    }
+    return await agentModulePromise
+  }
+
+  /** Start the embedded runtime if the user enabled it. Never throws. */
+  const start = async () => {
+    if (disposed) return
+    if (doc === null || doc.enabled !== true) return
+    if (handle !== null) return
+    let startRuntime
+    try {
+      const module = await loadAgentModule()
+      startRuntime = module.startRuntime
+    } catch (error) {
+      lastError = `the embedded runtime module could not be loaded: ${error && error.message ? error.message : error}`
+      warnOnce(`dsh-computers runtime: ${lastError}`)
+      return
+    }
+    if (typeof startRuntime !== 'function') {
+      // Older agent bundle (or a partial install): the enrollment still
+      // succeeded, so keep the configuration and explain the missing piece.
+      lastError = 'the embedded runtime is unavailable: the agent bundle does not export startRuntime'
+      warnOnce(`dsh-computers runtime: ${lastError}`)
+      if (doc !== null) {
+        doc.lastError = lastError
+        persist()
+      }
+      return
+    }
+    try {
+      const live = startRuntime({
+        serverUrl: doc.serverUrl,
+        token: doc.token,
+        computerId: doc.computerId,
+        name: doc.name ?? undefined,
+        heartbeatMs: config.heartbeatMs,
+        log,
+        onState: applyAgentState,
+      })
+      if (live === null || typeof live !== 'object' || typeof live.stop !== 'function') {
+        throw new Error('startRuntime() did not return { stop(), status() }')
+      }
+      handle = live
+      // A synchronous initial status keeps `connected` honest even when the
+      // agent only reports transitions later.
+      try {
+        applyAgentState(live.status?.() ?? { connected: false })
+      } catch {
+        // A status() that throws is the agent's bug; the loop still runs.
+      }
+    } catch (error) {
+      handle = null
+      lastError = `the embedded runtime could not start: ${error && error.message ? error.message : error}`
+      warnOnce(`dsh-computers runtime: ${lastError}`)
+    }
+  }
+
+  /** Stop the embedded runtime; keeps runtime.json and the user's switch. */
+  const stop = async () => {
+    const current = handle
+    handle = null
+    connected = false
+    since = null
+    if (current === null) return
+    try {
+      await current.stop()
+    } catch (error) {
+      warnOnce(`dsh-computers runtime: stop() failed: ${error && error.message ? error.message : error}`)
+    }
+  }
+
+  /** Current §10.3 status object. */
+  const status = () => {
+    const live = (() => {
+      try {
+        return handle?.status?.() ?? null
+      } catch {
+        return null
+      }
+    })()
+    const liveConnected = typeof live?.connected === 'boolean' ? live.connected : connected
+    const liveSince = asIsoOrNull(live?.since) ?? (liveConnected ? since : null)
+    const liveError = typeof live?.lastError === 'string' && live.lastError !== '' ? live.lastError : lastError
+    // The client contract (§10.6, implemented by ui-dev) reads `serverUrl` as a
+    // string even when unconfigured, so the three identity fields are always
+    // strings and only the timestamps are nullable.
+    return {
+      configured: doc !== null,
+      enabled: doc !== null && doc.enabled === true,
+      connected: liveConnected === true,
+      serverUrl: doc?.serverUrl ?? '',
+      computerId: doc?.computerId ?? '',
+      name: doc?.name ?? '',
+      since: liveConnected === true ? liveSince : null,
+      lastError: liveError ?? doc?.lastError ?? null,
+    }
+  }
+
+  doc = load()
+  if (doc !== null) {
+    lastError = doc.lastError ?? null
+    // A persisted `lastError` describes the previous process; it is diagnostic
+    // only and must not look like a live failure before we try again.
+    if (doc.enabled === true) lastError = null
+  }
+
+  return {
+    /** Absolute runtime.json path (diagnostics + smoke assertions). */
+    file,
+    /**
+     * Enroll this machine with `serverUrl` using a hub-minted key, persist the
+     * result enabled, and start the runtime (PROTOCOL §10.3).
+     * @param {{ serverUrl: string, key: string }} input - hub URL and key.
+     * @returns {Promise<object>} the new status.
+     */
+    async configure({ serverUrl, key }) {
+      const hubUrl = normalizeServerUrl(serverUrl)
+      const enrollmentKey = typeof key === 'string' ? key.trim() : ''
+      if (enrollmentKey === '') throw new HttpError(400, 'bad-request', 'key is required')
+      // Release the previous runtime first: its token is about to be replaced.
+      await stop()
+      const response = await postJson(`${hubUrl}/api/dsh-computers/agent/enroll`, {
+        key: enrollmentKey,
+        agentVersion: version,
+        machine: machineInfo(version),
+      }, { timeoutMs: ENROLL_TIMEOUT_MS })
+      if (response.status !== 200) throw mapEnrollFailure(response)
+      const data = response.data !== null && typeof response.data === 'object' ? response.data : {}
+      const computerId = typeof data.computerId === 'string' ? data.computerId.trim() : ''
+      const token = typeof data.token === 'string' ? data.token.trim() : ''
+      if (computerId === '' || token === '') {
+        throw new HttpError(502, 'hub-unreachable', 'the hub returned an unexpected enrollment response')
+      }
+      const enrolledName = typeof data.name === 'string' && data.name.trim() !== ''
+        ? data.name.trim()
+        : (machineInfo(version).hostname ?? 'this machine')
+      doc = {
+        version: RUNTIME_STATE_VERSION,
+        // Prefer the server URL the hub reported (it knows how clients reach it).
+        serverUrl: typeof data.serverUrl === 'string' && data.serverUrl.trim() !== ''
+          ? data.serverUrl.trim().replace(/\/+$/, '')
+          : hubUrl,
+        computerId,
+        token,
+        name: enrolledName,
+        enabled: true,
+        enrolledAt: new Date().toISOString(),
+        lastConnectedAt: null,
+        lastError: null,
+      }
+      connected = false
+      since = null
+      lastError = null
+      warnedLine = null
+      persist()
+      await start()
+      return status()
+    },
+    /** Start the embedded runtime when configured and enabled (never throws). */
+    async start() {
+      await start()
+      return status()
+    },
+    /** Stop the runtime but keep the configuration and the switch (never throws). */
+    async stop() {
+      await stop()
+      return status()
+    },
+    /** Persist and apply the user's `启用` switch (PROTOCOL §10.3). */
+    async enable(enabled) {
+      if (typeof enabled !== 'boolean') throw new HttpError(400, 'bad-request', 'enabled must be a boolean')
+      if (doc === null) {
+        if (enabled === true) throw new HttpError(400, 'bad-request', 'connect this computer to a hub first')
+        return status()
+      }
+      doc.enabled = enabled
+      if (enabled) doc.lastError = null
+      persist()
+      if (enabled) await start()
+      else await stop()
+      return status()
+    },
+    /** Stop and forget the configuration (deletes runtime.json). */
+    async disconnect() {
+      await stop()
+      if (doc !== null) {
+        try {
+          unlinkSync(file)
+        } catch (error) {
+          if (!error || error.code !== 'ENOENT') {
+            warnOnce(`dsh-computers: cannot remove ${file}: ${error && error.message ? error.message : error}`)
+          }
+        }
+      }
+      doc = null
+      connected = false
+      since = null
+      lastError = null
+      warnedLine = null
+      return status()
+    },
+    /** Protocol status object (§10.3). */
+    status,
+    /** Start automatically when the persisted switch says enabled. */
+    async autoStart() {
+      if (doc === null || doc.enabled !== true) return status()
+      try {
+        await start()
+      } catch (error) {
+        // start() is total, but a future refactor must not crash the host load.
+        warnOnce(`dsh-computers runtime: auto-start failed: ${error && error.message ? error.message : error}`)
+      }
+      return status()
+    },
+    /** Plugin unload: stop the loop, keep runtime.json for the next load. */
+    async dispose() {
+      disposed = true
+      await stop()
+    },
+    /** What the agent currently reports (diagnostics). */
+    get connected() {
+      return connected
+    },
+  }
+}

package/lib/selection.js

@@ -0,0 +1,205 @@
+/**
+ * Per-session target-computer selection (task-9).
+ *
+ * The settings page pins which machine the agent should act on for one chat
+ * session; `computer_exec` without an explicit `computer` argument uses that
+ * pin. The store is a tiny persisted map `sessionId → computerId` at
+ * `${stateDir}/selections.json` (atomic write, mode 0600, corrupt-file
+ * tolerant), pruned to the 200 most recently updated entries so a long-lived
+ * deployment cannot grow it without bound.
+ *
+ * Node builtins only.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** On-disk schema version. */
+export const SELECTION_STATE_VERSION = 1
+
+/** File name inside the plugin state directory. */
+export const SELECTION_FILE_NAME = 'selections.json'
+
+/** How many session selections survive pruning (most recently updated win). */
+export const MAX_SELECTIONS = 200
+
+/** Session ids are opaque GUI identifiers; 256 chars is already generous. */
+export const MAX_SESSION_ID_CHARS = 256
+
+/**
+ * Normalize a session id: non-empty, trimmed, no control characters, bounded
+ * length. Returns null for anything else so routes answer 400.
+ * @param {unknown} value - candidate (route query/body, agent id).
+ * @returns {string | null} the normalized id.
+ */
+export function normalizeSessionId(value) {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (trimmed === '' || trimmed.length > MAX_SESSION_ID_CHARS) return null
+  if (/[\u0000-\u001f\u007f]/.test(trimmed)) return null
+  return trimmed
+}
+
+/** A fresh, empty selection document. */
+export function emptySelectionState() {
+  return { version: SELECTION_STATE_VERSION, selections: {} }
+}
+
+/**
+ * Coerce an arbitrary parsed value into a usable selection document.
+ * Invalid session keys and malformed entries are dropped, never fatal.
+ * @param {unknown} raw - parsed JSON (or undefined when the file was missing).
+ * @returns {object} a valid document.
+ */
+export function normalizeSelectionState(raw) {
+  const doc = emptySelectionState()
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return doc
+  const source = raw.selections !== null && typeof raw.selections === 'object' && !Array.isArray(raw.selections)
+    ? raw.selections
+    : {}
+  for (const [rawSessionId, entry] of Object.entries(source)) {
+    const sessionId = normalizeSessionId(rawSessionId)
+    if (sessionId === null) continue
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
+    const computerId = typeof entry.computerId === 'string' ? entry.computerId.trim() : ''
+    if (computerId === '') continue
+    const parsed = typeof entry.updatedAt === 'string' ? Date.parse(entry.updatedAt) : Number.NaN
+    doc.selections[sessionId] = {
+      computerId,
+      updatedAt: Number.isFinite(parsed) ? new Date(parsed).toISOString() : null,
+    }
+  }
+  return doc
+}
+
+/**
+ * Keep only the `max` most recently updated selections (missing timestamps
+ * sort last). Mutates in place.
+ * @param {object} doc - selection document.
+ * @param {number} [max] - entry budget.
+ * @returns {number} how many entries were dropped.
+ */
+export function pruneSelections(doc, max = MAX_SELECTIONS) {
+  const entries = Object.entries(doc.selections)
+  if (entries.length <= max) return 0
+  const age = (entry) => {
+    const parsed = typeof entry?.[1]?.updatedAt === 'string' ? Date.parse(entry[1].updatedAt) : Number.NaN
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+  entries.sort((left, right) => age(right) - age(left))
+  const keep = new Set(entries.slice(0, max).map(([sessionId]) => sessionId))
+  let dropped = 0
+  for (const sessionId of Object.keys(doc.selections)) {
+    if (keep.has(sessionId)) continue
+    delete doc.selections[sessionId]
+    dropped += 1
+  }
+  return dropped
+}
+
+/**
+ * Create the selection store for one plugin mount.
+ * @param {object} options - store options.
+ * @param {string} options.stateDir - directory holding selections.json.
+ * @param {() => number} [options.now] - epoch-millisecond clock (testable).
+ * @param {(message: string) => void} [options.onWarn] - warning sink.
+ * @returns {object} the store.
+ */
+export function createSelectionStore({ stateDir, now = Date.now, onWarn = () => {} }) {
+  const file = join(stateDir, SELECTION_FILE_NAME)
+  let doc = emptySelectionState()
+
+  /** Read the document; a corrupt file is set aside, never fatal. */
+  const load = () => {
+    let raw
+    try {
+      raw = readFileSync(file, 'utf8')
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') onWarn(`dsh-computers: cannot read ${file}: ${error.message}`)
+      return emptySelectionState()
+    }
+    try {
+      return normalizeSelectionState(JSON.parse(raw))
+    } catch {
+      const aside = `${file}.corrupt-${now()}`
+      try {
+        renameSync(file, aside)
+        onWarn(`dsh-computers: ${file} was not valid JSON; moved to ${aside}`)
+      } catch {
+        onWarn(`dsh-computers: ${file} was not valid JSON`)
+      }
+      return emptySelectionState()
+    }
+  }
+
+  /** Write the document atomically: tmp file in the same directory, then rename. */
+  const persist = () => {
+    try {
+      mkdirSync(stateDir, { recursive: true, mode: 0o700 })
+      const tmp = join(stateDir, `.selections.json.${process.pid}.${randomBytes(4).toString('hex')}.tmp`)
+      writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+      try {
+        chmodSync(tmp, 0o600)
+      } catch {
+        // Platforms without POSIX modes (Windows) skip this.
+      }
+      renameSync(tmp, file)
+    } catch (error) {
+      onWarn(`dsh-computers: cannot write ${file}: ${error && error.message ? error.message : error}`)
+    }
+  }
+
+  doc = load()
+  pruneSelections(doc)
+  if (Object.keys(doc.selections).length > 0) persist()
+
+  /**
+   * Store one selection (or clear it with null), prune and persist.
+   * @param {string} sessionId - session identity.
+   * @param {string | null} computerId - target computer or null to clear.
+   */
+  const set = (sessionId, computerId) => {
+    const key = normalizeSessionId(sessionId)
+    if (key === null) throw new TypeError('dsh-computers selection: sessionId must be a non-empty string')
+    if (computerId === null) {
+      delete doc.selections[key]
+    } else {
+      if (typeof computerId !== 'string' || computerId.trim() === '') {
+        throw new TypeError('dsh-computers selection: computerId must be a non-empty string or null')
+      }
+      doc.selections[key] = { computerId: computerId.trim(), updatedAt: new Date(now()).toISOString() }
+    }
+    pruneSelections(doc)
+    persist()
+  }
+
+  return {
+    /** Absolute selections.json path (diagnostics + smoke assertions). */
+    file,
+    /**
+     * The selected computer id for one session, or null.
+     * @param {string} sessionId - session identity.
+     * @returns {string | null} the computer id.
+     */
+    get(sessionId) {
+      const key = normalizeSessionId(sessionId)
+      if (key === null) return null
+      return doc.selections[key]?.computerId ?? null
+    },
+    /** Store one selection. */
+    set,
+    /** Clear one session's selection. */
+    clear(sessionId) {
+      set(sessionId, null)
+    },
+    /** Copy of every selection (diagnostics). */
+    all() {
+      return JSON.parse(JSON.stringify(doc.selections))
+    },
+    /** Re-read the file (tooling). */
+    reload() {
+      doc = load()
+    },
+  }
+}