agent-relay-server 0.81.0 → 0.82.0

package/src/routes/_shared.ts

@@ -5,7 +5,8 @@ import { ValidationError, createActivityEvent, createCallbackDelivery, finishCal
 import { cleanEpoch, cleanString, optionalEnum } from "../validation";
 import { emitActivityEvent, emitMessageQueued, emitNewMessage } from "../sse";
 import { emitRelayEvent } from "../events";
-import { errMessage, isRecord } from "agent-relay-sdk";
+import { canonicalHumanAgentId, DEFAULT_USER_ID, errMessage, isRecord, userSinkId } from "agent-relay-sdk";
+import { authorizeAgentForUser, visibleAgentIdsForUser, type AgentAction } from "../agent-authz";
 import { generateSpawnRequestId } from "../spawn-command";
 import { getComponentAuth, getIntegrationAuth, isAuthorized, isRequestAuthorizedFor } from "../security";
 import { readBodyBytes } from "../http-body";
@@ -87,6 +88,79 @@ export function dashboardAttribution(req: Request, surface?: unknown): Record<st
   return { surface: out };
 }
 
+type RequestUserResolver = (req: Request) => string;
+
+// The active resolver behind requestUserId. The default returns the seeded admin
+// (`DEFAULT_USER_ID`) and NEVER reads a client header, so the relay stays single-user until
+// auth/sessions (#389) install a real session→users.id resolver via setRequestUserResolver.
+const defaultRequestUserResolver: RequestUserResolver = () => DEFAULT_USER_ID;
+let requestUserResolver: RequestUserResolver = defaultRequestUserResolver;
+
+/**
+ * The #389 wiring point: install the authenticated-session → `users.id` resolver. ONE call here
+ * turns on per-user enforcement + attribution across every route — no route edits — because all
+ * three seams already funnel through {@link requestUserId}. Also the seam tests use to exercise
+ * the multi-user gates that #389 will switch on (no client header is ever trusted).
+ */
+export function setRequestUserResolver(resolver: RequestUserResolver): void {
+  requestUserResolver = resolver;
+}
+
+/** Restore the default single-user resolver (test teardown / #389 rollback). */
+export function resetRequestUserResolver(): void {
+  requestUserResolver = defaultRequestUserResolver;
+}
+
+/**
+ * THE canonical server-side resolver for "which human is acting in this request" (#388 Wave A
+ * integration), returning the relational `users.id`. Settings (#391), authz (#392), and
+ * attribution/presence (#390) ALL resolve through this one path, so the three "who is the user"
+ * seams can never disagree or drift into different id-spaces.
+ *
+ * It deliberately does NOT trust the additive `X-Dashboard-User-Id` header. That header is a
+ * dormant #389 seam — auth/sessions will wire it to the *authenticated* session; today it is
+ * trusted by NOTHING, so a crafted header can forge neither attribution, presence, settings,
+ * nor an authz decision. Until #389 calls {@link setRequestUserResolver} this resolves to the
+ * seeded admin `DEFAULT_USER_ID` ('default'): authz fail-opens (single-user world), settings
+ * read the lone human's row, and attribution stamps the legacy `user` sink — byte-for-byte the
+ * pre-Wave-A behavior.
+ */
+export function requestUserId(req: Request): string {
+  return requestUserResolver(req);
+}
+
+/**
+ * The canonical human MESSAGE ADDRESS (`user` / `user:<id>`) for the acting user, derived from
+ * {@link requestUserId} via the SDK resolver (never a hand-rolled namespace). Use ONLY where
+ * message routing/attribution genuinely needs an address — a message `from`, an audit
+ * `requestedByUser`, presence — while authz/settings/ownership use the relational
+ * {@link requestUserId}. For the default user this collapses to the legacy bare `user` sink, so
+ * existing message/operator/presence rows match byte-for-byte.
+ */
+export function requestUserAddress(req: Request): string {
+  return canonicalHumanAgentId(userSinkId(requestUserId(req)));
+}
+
+/**
+ * Gate a per-agent route on the acting user's authorization (#392, wired by Wave-A integration).
+ * Returns a 403 when the user may not perform `action` on the agent, else null to proceed.
+ * Single-user worlds fail-open inside {@link authorizeAgentForUser}, so existing routes are
+ * unchanged until #389 upgrades {@link requestUserId} to the real session user.
+ */
+export function authorizeAgentRoute(req: Request, agentId: string, action: AgentAction): Response | null {
+  return authorizeAgentForUser(requestUserId(req), agentId, action) ? null : error("forbidden", 403);
+}
+
+/** True iff the acting user may observe `agentId` (drives detail/chat-read existence-hiding). */
+export function canViewAgentRoute(req: Request, agentId: string): boolean {
+  return authorizeAgentForUser(requestUserId(req), agentId, "view");
+}
+
+/** Filter `agentIds` to the subset the acting user may observe, preserving input order. */
+export function visibleAgentIdsForRequest(req: Request, agentIds: readonly string[]): Set<string> {
+  return new Set(visibleAgentIdsForUser(requestUserId(req), agentIds));
+}
+
 type ParseBodyResult<T> =
   | { ok: true; body: T | null }
   | { ok: false; status: number; error: string };

package/src/routes/agent-sessions.ts

@@ -1,12 +1,13 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
-import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage, withResolvedProvisioning } from "../db";
+import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
 import { cleanString, optionalEnum } from "../validation";
 import { createCommand } from "../commands-db";
-import { emitAgentStatus, emitNewMessage } from "../sse";
+import { emitAgentStatus, emitDashboardPresence, emitNewMessage } from "../sse";
 import { getAgentProfile, getSpawnPolicy } from "../config-store";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { runnerRuntimeTokenEnv } from "../runtime-tokens";
@@ -208,6 +209,10 @@ export const postAgentAction: Handler = async (req, params) => {
     if (!action) return error("action required");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
+    // #392: the acting user must be allowed to drive this agent (fail-open single-user). Gated
+    // before the capability probe so an unauthorized user learns nothing about what the agent supports.
+    const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
+    if (driveDenied) return driveDenied;
     if (!agentCanReceiveControlAction(agent, action)) return error(`agent does not support ${action}`, 400);
 
     // Shutdown converges on the shutdownAgent service (epic #342, #347): one #221
@@ -273,6 +278,7 @@ export const postAgentAction: Handler = async (req, params) => {
         ...(action === "compact" ? compactMemoryParams(agent) : {}),
         ...(resumeId ? { claudeResumeId: resumeId } : {}),
         requestedBy: "dashboard",
+        requestedByUser: requestUserAddress(req),
         requestedAt: Date.now(),
       },
     });
@@ -292,7 +298,7 @@ export const postAgentAction: Handler = async (req, params) => {
       icon: agentControlActionIcon(action),
       view: "agents",
       agentId: agent.id,
-      metadata: { action, commandId: command.id, ...(orchestrator ? { orchestratorId: orchestrator.id } : {}), ...authAuditMetadata(req), ...dashboardAttribution(req, parsed.body.surface) },
+      metadata: { action, commandId: command.id, requestedByUser: requestUserAddress(req), ...(orchestrator ? { orchestratorId: orchestrator.id } : {}), ...authAuditMetadata(req), ...dashboardAttribution(req, parsed.body.surface) },
     });
     return json({ ok: true, action, command }, 202);
   } catch (e) {
@@ -310,14 +316,22 @@ export const postAgentPrompt: Handler = async (req, params) => {
     const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
+    // #392: only a user authorized to drive this agent may prompt it (fail-open single-user).
+    const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
+    if (driveDenied) return driveDenied;
     if (agent.status === "offline") return error("agent is offline", 422);
     const denied = authorizeRoute(req, {
       scope: "message:send",
       resource: { target: agent.id, agentId: "user" },
     });
     if (denied) return denied;
+    // Attribute the prompt to the acting human, derived from the TRUSTED requestUserId — never
+    // an echo of the client `X-Dashboard-User-Id` header (#390 forgery fix). Defaults to the
+    // canonical `user` sink, so today's single operator routes/renders exactly as before; once
+    // auth (#389) sets the real session user, the bubble carries the real `user:<id>`.
+    const fromUser = requestUserAddress(req);
     const message = sendMessage({
-      from: "user",
+      from: fromUser,
       to: agent.id,
       kind: "session",
       body,
@@ -336,7 +350,7 @@ export const postAgentPrompt: Handler = async (req, params) => {
       kind: "message",
       title: "Prompt injected",
       body,
-      meta: `user -> ${agent.id}`,
+      meta: `${fromUser} -> ${agent.id}`,
       icon: "ti-message-bolt",
       view: "messages",
       messageId: message.id,
@@ -371,6 +385,9 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
     }
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
+    // #392: approving/denying a permission is driving the agent (fail-open single-user).
+    const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
+    if (driveDenied) return driveDenied;
     if (!agentIsControlEligible(agent)) return error("agent cannot receive permission decisions", 400);
     const pendingApproval = isRecord(agent.meta?.providerState) && isRecord(agent.meta.providerState.pendingApproval)
       ? agent.meta.providerState.pendingApproval
@@ -397,6 +414,7 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
         ...(reason ? { reason } : {}),
         ...(answers ? { answers } : {}),
         requestedBy: "dashboard",
+        requestedByUser: requestUserAddress(req),
         requestedAt: Date.now(),
       },
     });
@@ -410,7 +428,7 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
       icon: decision === "deny" || decision === "abort" ? "ti-circle-x" : "ti-circle-check",
       view: "chat",
       agentId: agent.id,
-      metadata: { decision, approvalId, commandId: command.id, ...authAuditMetadata(req) },
+      metadata: { decision, approvalId, commandId: command.id, requestedByUser: requestUserAddress(req), ...authAuditMetadata(req) },
     });
     return json({ ok: true, decision, command }, 202);
   } catch (e) {
@@ -419,6 +437,39 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
   }
 };
 
+// Dashboard viewer presence heartbeat (#390): "I am viewing/typing in this agent's chat".
+// The client re-announces on an interval and on a `leaving` beacon. Keyed by the existing
+// X-Dashboard-Client-Id so multiple tabs of one browser collapse to one viewer; the acting
+// human comes from the TRUSTED requestUserAddress (NOT the client X-Dashboard-User-Id header),
+// so a crafted header can't make presence show you as someone else (#390 forgery fix). We
+// broadcast the live viewer set so every open dashboard updates without polling. No auth gate —
+// these are non-secret opaque ids and the view-state of a chat already streams over the same SSE
+// channel.
+export const postAgentPresence: Handler = async (req, params) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  const clientId = req.headers.get("x-dashboard-client-id")?.trim();
+  if (!clientId) return error("X-Dashboard-Client-Id required");
+  const body = isRecord(parsed.body) ? parsed.body : {};
+  const viewers = announcePresence({
+    agentId: agent.id,
+    clientId,
+    userId: requestUserAddress(req),
+    typing: body.typing === true,
+    leaving: body.leaving === true,
+  });
+  emitDashboardPresence(agent.id, viewers);
+  return json({ ok: true, agentId: agent.id, viewers });
+};
+
+export const getAgentPresence: Handler = (_req, params) => {
+  const agent = getAgent(params.id!);
+  if (!agent) return error("agent not found", 404);
+  return json({ agentId: agent.id, viewers: viewersForAgent(agent.id) });
+};
+
 export const postAgentTerminalSession: Handler = async (req, params) => {
   try {
     const agent = getAgent(params.id!);

package/src/routes/agents.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents.
-import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent, error, json, memoryContext, memoryErrorResponse, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, type Handler } from "./_shared";
+import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent, canViewAgentRoute, error, json, memoryContext, memoryErrorResponse, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, visibleAgentIdsForRequest, type Handler } from "./_shared";
 import { ValidationError, deleteAgent, getAgent, getAgentTimeline, heartbeat, listAgentChatHistory, listAgents, listArtifactsForEntity, listContextSnapshots, listPendingReplyObligations, listQuotaSnapshots, markReady, searchAgents, setLabel, setStatus, setTags, validateAgentSession } from "../db";
 import { attachBranchState, attachBranchStates } from "../agent-branch-state";
 import { attachIssueRepo, attachIssueRepos } from "../agent-issue-repo";
@@ -45,7 +45,11 @@ export const getAgents: Handler = (req) => {
   const tag = url.searchParams.get("tag") ?? undefined;
   const machine = url.searchParams.get("machine") ?? undefined;
   const status = url.searchParams.get("status") ?? undefined;
-  return json(attachIssueRepos(attachBranchStates(listAgents({ tag, machine, status }))));
+  // #392: hide agents the acting user may not see. Fail-open in the single-user world
+  // (visibleAgentIdsForRequest returns every id), so today's list is byte-for-byte unchanged.
+  const agents = listAgents({ tag, machine, status });
+  const visible = visibleAgentIdsForRequest(req, agents.map((a) => a.id));
+  return json(attachIssueRepos(attachBranchStates(agents.filter((a) => visible.has(a.id)))));
 };
 
 export const findAgents: Handler = (req) => {
@@ -56,9 +60,12 @@ export const findAgents: Handler = (req) => {
   return json(searchAgents({ capability, status: includeAll ? "all" : "running" }));
 };
 
-export const getAgentById: Handler = (_req, params) => {
+export const getAgentById: Handler = (req, params) => {
   const agent = getAgent(params.id!);
-  return agent ? json(attachIssueRepo(attachBranchState(agent))) : error("agent not found", 404);
+  if (!agent) return error("agent not found", 404);
+  // #392: a non-visible agent must look indistinguishable from a missing one (no existence leak).
+  if (!canViewAgentRoute(req, agent.id)) return error("agent not found", 404);
+  return json(attachIssueRepo(attachBranchState(agent)));
 };
 
 export const getAgentReplyObligations: Handler = (_req, params) => {
@@ -69,6 +76,8 @@ export const getAgentReplyObligations: Handler = (_req, params) => {
 export const getAgentChatHistory: Handler = (req, params) => {
   const agent = getAgent(params.id!);
   if (!agent) return error("agent not found", 404);
+  // #392: chat history is only readable for agents the user may see (existence-hiding 404).
+  if (!canViewAgentRoute(req, agent.id)) return error("agent not found", 404);
   const url = new URL(req.url);
   const beforeRaw = parseQueryInt(url.searchParams.get("before"), { min: 1, max: Number.MAX_SAFE_INTEGER });
   if (Number.isNaN(beforeRaw)) return error("before must be a positive integer");

package/src/routes/index.ts

@@ -1,7 +1,8 @@
 // Auto-split from routes.ts (#299). Router: route table + matchRoute dispatch.
 import { deleteAgentActiveMemories, deleteAgentById, findAgents, getAgentActiveMemories, getAgentById, getAgentChatHistory, getAgentContextSnapshots, getAgentQuotaSnapshots, getAgentReplyObligations, getAgentTimelineRoute, getAgents, getMessageArtifactsRoute, getTaskArtifactsRoute, patchAgentLabel, patchAgentReady, patchAgentStatus, patchAgentTags, postHeartbeat } from "./agents";
 import { deleteAgentProfileRoute, getAgentProfileRoute, getAgentProfilesRoute, putAgentProfileRoute } from "./agent-profiles";
-import { deleteAgentTerminalSession, postAgentAction, postAgentPermissionDecision, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
+import { deleteAgentTerminalSession, getAgentPresence, postAgentAction, postAgentPermissionDecision, postAgentPresence, postAgentPrompt, postAgentTerminalSession } from "./agent-sessions";
+import { getUsers } from "./users";
 import { deleteArtifactById, getArtifactById, getArtifactContent, getArtifacts, headArtifactContent, postArtifact } from "./artifacts";
 import { deleteAutomationById, getAutomationById, getAutomationRuns, getAutomations, patchAutomation, postAutomation, postAutomationRun } from "./automations";
 import { deleteCommandById, deleteProviderModelRoute, getProviderConfigRoute, getProviderConfigsRoute, getProvidersRoute, patchProviderModelRoute, postProviderConfigTestRoute, putProviderConfigRoute, putProviderModelRoute } from "./provider-config";
@@ -85,6 +86,8 @@ const routes: Route[] = [
   route("PATCH", "/api/memories/:id", patchMemory),
   route("DELETE", "/api/memories/:id", deleteMemoryRoute),
 
+  route("GET", "/api/users", getUsers),
+
   route("POST", "/api/agents", postAgent),
   route("POST", "/api/agents/spawn", postAgentSpawn),
   route("GET", "/api/agents", getAgents),
@@ -111,6 +114,8 @@ const routes: Route[] = [
   route("POST", "/api/agents/:id/actions", postAgentAction),
   route("POST", "/api/agents/:id/prompt", postAgentPrompt),
   route("POST", "/api/agents/:id/permission-decision", postAgentPermissionDecision),
+  route("GET", "/api/agents/:id/presence", getAgentPresence),
+  route("POST", "/api/agents/:id/presence", postAgentPresence),
   route("POST", "/api/agents/:id/terminal-session", postAgentTerminalSession),
   route("DELETE", "/api/agents/:id/terminal-session/:session", deleteAgentTerminalSession),
   route("DELETE", "/api/agents/:id", deleteAgentById),

package/src/routes/settings.ts

@@ -1,16 +1,23 @@
 // Auto-split from routes.ts (#299). Domain: schema-driven settings.
 import { ValidationError } from "../db";
 import { getConfig, setConfig } from "../config-store";
+import { getUserSetting, setUserSetting } from "../user-settings-store";
 import { ensureProviderConfigDescriptors, migrateLocalProviderConfigs } from "../provider-config-store";
 import { getSettingDescriptor, listSettingDescriptors, validateSettingValue, PROVIDER_CONFIG_NAMESPACE } from "../settings/registry";
 import { isRequestAuthorizedFor } from "../security";
 import { cleanString } from "../validation";
 import { emitConfigChanged } from "../sse";
-import { error, json, normalizeConfigPathParam, parseBody, type Handler } from "./_shared";
-import { isRecord, type ConfigEntry, type SettingDescriptor, type SettingEntry } from "agent-relay-sdk";
+import { error, json, normalizeConfigPathParam, parseBody, requestUserId, type Handler } from "./_shared";
+import { DEFAULT_USER_ID, isRecord, type ConfigEntry, type SettingDescriptor, type SettingEntry } from "agent-relay-sdk";
 
 type SettingEnvelope = SettingEntry;
 
+// Which human a `tier:"user"` (#391) read/write resolves to: the ONE canonical
+// `requestUserId` resolver (#388 Wave A integration), shared with authz (#392) and
+// attribution (#390) so the three seams never diverge. Until sessions (#389) upgrade it,
+// every request resolves to the seeded admin `user:default` (#393), so prefs read back exactly
+// as before the migration (back-compat). Server-runtime/bootstrap/browser tiers ignore this.
+
 export const getSettingsRoute: Handler = (req) => {
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors();
@@ -42,7 +49,9 @@ export const putSettingRoute: Handler = (req, params) => putSetting(req, params.
 export function getRegisteredSettingEntry(namespace: string, key: string): ConfigEntry | null {
   ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
   const descriptor = getSettingDescriptor(namespace, key);
-  return descriptor ? currentSettingEntry(descriptor) : null;
+  // Programmatic (no request) reads have no session, so a user-tier descriptor resolves to the
+  // default human (#393) — the single human today; matches the HTTP path's back-compat default.
+  return descriptor ? currentSettingEntry(descriptor, DEFAULT_USER_ID) : null;
 }
 
 export function setRegisteredSettingValue(namespace: string, key: string, value: unknown, updatedBy?: string): ConfigEntry {
@@ -52,6 +61,7 @@ export function setRegisteredSettingValue(namespace: string, key: string, value:
   const merged = mergeSettingDefaults(descriptor.defaults, value);
   const validation = validateSettingValue(namespace, key, merged);
   if (!validation.valid) throw new ValidationError(validation.errors.join("; "));
+  if (descriptor.tier === "user") return setUserSetting(DEFAULT_USER_ID, namespace, key, merged, updatedBy);
   return setConfig(namespace, key, merged, updatedBy);
 }
 
@@ -68,11 +78,17 @@ async function putSetting(req: Request, namespaceRaw: string | undefined, keyRaw
     ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
     const descriptor = getSettingDescriptor(namespace, key);
     if (!descriptor) return error("setting not found", 404);
-    if (descriptor.tier !== "server-runtime") return error("setting is read-only", 403);
+    if (descriptor.tier !== "server-runtime" && descriptor.tier !== "user") return error("setting is read-only", 403);
     if (!canAccessSetting(req, descriptor.scope.write)) return error("forbidden", 403);
     const updatedBy = cleanString(parsed.body.updatedBy, "updatedBy", { max: 200 });
     const validation = validateSettingValue(namespace, key, parsed.body.value);
     if (!validation.valid) return json({ error: "invalid setting value", details: validation.errors }, 400);
+    if (descriptor.tier === "user") {
+      const userId = requestUserId(req);
+      const userEntry = setUserSetting(userId, namespace, key, parsed.body.value, updatedBy);
+      emitConfigChanged(userEntry.namespace, userEntry.key, userEntry.version);
+      return json(settingEnvelope(req, descriptor, userEntry), userEntry.version === 1 ? 201 : 200);
+    }
     const entry = setConfig(namespace, key, parsed.body.value, updatedBy);
     emitConfigChanged(entry.namespace, entry.key, entry.version);
     return json(settingEnvelope(req, descriptor, entry), entry.version === 1 ? 201 : 200);
@@ -88,7 +104,12 @@ function listVisibleSettings(req: Request): SettingEnvelope[] {
     .filter((setting) => setting.readable);
 }
 
-function settingEnvelope(req: Request, descriptor: SettingDescriptor, entry = currentSettingEntry(descriptor)): SettingEnvelope {
+function settingEnvelope(
+  req: Request,
+  descriptor: SettingDescriptor,
+  entry = currentSettingEntry(descriptor, requestUserId(req)),
+): SettingEnvelope {
+  const mutableTier = descriptor.tier === "server-runtime" || descriptor.tier === "user";
   return {
     ...descriptor,
     value: entry.value,
@@ -96,12 +117,16 @@ function settingEnvelope(req: Request, descriptor: SettingDescriptor, entry = cu
     updatedAt: entry.updatedAt,
     updatedBy: entry.updatedBy,
     readable: canAccessSetting(req, descriptor.scope.read),
-    writable: descriptor.tier === "server-runtime" && canAccessSetting(req, descriptor.scope.write),
+    writable: mutableTier && canAccessSetting(req, descriptor.scope.write),
   };
 }
 
-function currentSettingEntry(descriptor: SettingDescriptor): ConfigEntry {
-  const entry = getConfig(descriptor.namespace, descriptor.key);
+// Resolve the current stored value for a descriptor. `tier:"user"` (#391) reads the per-user row
+// for `userId`; every other tier reads the instance-global `config` table. Unset → descriptor defaults.
+function currentSettingEntry(descriptor: SettingDescriptor, userId: string): ConfigEntry {
+  const entry = descriptor.tier === "user"
+    ? getUserSetting(userId, descriptor.namespace, descriptor.key)
+    : getConfig(descriptor.namespace, descriptor.key);
   if (entry) return entry;
   return {
     namespace: descriptor.namespace,

package/src/routes/users.ts

@@ -0,0 +1,8 @@
+// Public user directory for dashboard attribution & presentation (#390). Surfaces the
+// keystone `users` table (#393) so the dashboard can resolve a `user:<id>` message address
+// to a human name/avatar. Read-only; the user row holds no secrets (auth credentials land
+// separately in #389), so the whole row is dashboard-safe to return.
+import { listUsers } from "../db";
+import { json, type Handler } from "./_shared";
+
+export const getUsers: Handler = () => json(listUsers());

package/src/services/register-agent.ts

@@ -9,7 +9,8 @@
 // managed came-up-running reconcile (delegated to managed-running.ts), the single
 // status broadcast, the single timeline note, the spawned-child parent-wake, and
 // the first-registration audit row.
-import { createActivityEvent, getAgent, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
+import { isReservedAgentId } from "agent-relay-sdk";
+import { ValidationError, createActivityEvent, getAgent, seedSpawnPromptMirror, seedSpawnReplyObligation, upsertAgent } from "../db";
 import { emitAgentStatus, emitNewMessage } from "../sse";
 import { noteAgentTimelineEvent } from "../compaction-watch";
 import { notifyAgentReady } from "../agent-lifecycle-events";
@@ -24,6 +25,15 @@ function metaStr(meta: Record<string, unknown> | undefined, key: string): string
 }
 
 export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): AgentCard {
+  // Reserved built-in identities — the `system` lifecycle sender and the whole `user:` human
+  // namespace (legacy bare `'user'`, `user:default`, every `user:<id>`) — are mechanical sinks,
+  // never registrable agents. THIS is the one external-registration boundary (HTTP `postAgent`
+  // and bus `handleRegister` both land here); rejecting them closes the spoof where a provider
+  // token squats a human address to receive human-addressed mail (#393). Internal built-in
+  // seeding writes straight through `upsertAgent`, bypassing this gate, so it stays unaffected.
+  if (isReservedAgentId(input.id)) {
+    throw new ValidationError(`agent id "${input.id}" is reserved and cannot be registered`);
+  }
   // Lineage is authoritative from the registering token's signed constraints — never
   // the client-sent body (a child can't forge its own parent). Set by relay at spawn.
   const lineage = resolveSpawnLineage(ctx.constraints);

package/src/services/send-message.ts

@@ -21,7 +21,7 @@
 //
 // OUT OF SCOPE (transport-edge, excluded from the parity facet): automatic memory injection
 // (needs request-derived context) and per-transport audit (HTTP domain row vs MCP tool-call row).
-import { isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
+import { canonicalHumanAgentId, isHumanAgentId, isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
 import {
   ValidationError,
   getMessage,
@@ -159,6 +159,12 @@ export function sendMessageService(
 ): SendMessageResult {
   applyReplyRouting(input);
   if (!input.to) throw new ValidationError("to is required (or provide replyTo to auto-route)");
+  // De-singletoned human addressing (#393): collapse a human address to its stored/canonical
+  // form so `user:default` is a fully WORKING alias of the legacy bare `'user'` sink — it routes
+  // to the same agent row + inbox + thread, with zero live-byte movement. Per-user `user:<id>`
+  // addresses pass through unchanged for the later #388 waves; non-human ids are untouched.
+  if (isHumanAgentId(input.to)) input.to = canonicalHumanAgentId(input.to);
+  if (input.from && isHumanAgentId(input.from)) input.from = canonicalHumanAgentId(input.from);
   // The reserved-sink observability lane (#284) governs both `from` resolution (wire `from` is
   // authoritative — the runner reports an agent's turn) and authorization (drop the recipient
   // predicate). Compute once, after reply-routing has settled `to`.

package/src/settings/registry.ts

@@ -241,6 +241,41 @@ const LANDING_SCHEMA: JSONSchema = {
   },
 };
 
+// Per-user preference schemas (#391, tier:"user"). These follow the human across devices via the
+// `user_settings` table (keyed by `users.id`), replacing per-browser localStorage for genuinely
+// user-level prefs. Field names mirror the dashboard store (dashboard/src/store) so the client
+// migration is a lift, not a rename. Truly device-local view state stays in the browser.
+const DISPLAY_PREFS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["theme", "showReasoning"],
+  properties: {
+    theme: { type: "string", enum: ["light", "dark", "midnight", "nord", "ember", "parchment"] },
+    showReasoning: { type: "boolean" },
+  },
+};
+
+const VOICE_PREFS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "voiceTtsEnabled",
+    "voiceTtsLang",
+    "voiceTtsMode",
+    "voiceTtsKokoroVoice",
+    "voiceTtsBrowserVoice",
+    "voiceInputMode",
+  ],
+  properties: {
+    voiceTtsEnabled: { type: "boolean" },
+    voiceTtsLang: { type: "string", maxLength: 35 },
+    voiceTtsMode: { type: "string", enum: ["kokoro", "browser"] },
+    voiceTtsKokoroVoice: { type: "string", maxLength: 80 },
+    voiceTtsBrowserVoice: { type: "string", maxLength: 200 },
+    voiceInputMode: { type: "string", enum: ["compose", "autosend", "handsfree"] },
+  },
+};
+
 // Provider chat/reasoning capture toggles (source: runner/src/adapter.ts ProviderConfig).
 // NOTE (#383 coordination): provider config storage is being centralized in #383;
 // these are seeded instance-global under namespace "provider". Per-provider
@@ -393,6 +428,34 @@ function seedBuiltInSettings(): void {
     tier: "server-runtime",
     display: { group: "Providers", label: "Reasoning capture", description: "Stream reasoning/tool steps into chat.", order: 51 },
   });
+
+  // Per-user prefs (#391) — tier:"user", stored per `users.id` so they follow the human across devices.
+  registerSetting({
+    namespace: "display",
+    key: "default",
+    schema: DISPLAY_PREFS_SCHEMA,
+    defaults: { theme: "dark", showReasoning: false },
+    scope: { read: "settings:read:display", write: "settings:write:display" },
+    tier: "user",
+    display: { group: "Preferences", label: "Display", description: "Per-user theme and reasoning visibility (follows you across devices).", order: 70 },
+  });
+
+  registerSetting({
+    namespace: "voice",
+    key: "default",
+    schema: VOICE_PREFS_SCHEMA,
+    defaults: {
+      voiceTtsEnabled: false,
+      voiceTtsLang: "en-US",
+      voiceTtsMode: "kokoro",
+      voiceTtsKokoroVoice: "am_michael",
+      voiceTtsBrowserVoice: "",
+      voiceInputMode: "compose",
+    },
+    scope: { read: "settings:read:voice", write: "settings:write:voice" },
+    tier: "user",
+    display: { group: "Preferences", label: "Voice", description: "Per-user text-to-speech and voice-input preferences.", order: 71 },
+  });
 }
 
 export function registerProviderConfigSetting(input: {

package/src/sse.ts

@@ -233,6 +233,13 @@ export function getConnectionCount(): number {
   return connections.size;
 }
 
+// Dashboard viewer presence for an agent thread (#390): broadcast the live set of humans
+// currently viewing/typing so every open dashboard can show "X is viewing". Ephemeral — the
+// viewer list comes from the in-memory presence registry, not the DB.
+export function emitDashboardPresence(agentId: string, viewers: unknown) {
+  emitRelayEvent({ type: "dashboard.presence", source: "server", subject: agentId, data: { agentId, viewers } });
+}
+
 export function emitOrchestratorStatus(orchestratorId: string) {
   const orch = getOrchestrator(orchestratorId);
   const data = orch ?? { id: orchestratorId, status: "offline" };

package/src/user-settings-store.ts

@@ -0,0 +1,86 @@
+// Per-user settings storage (#391, epic #388). The user dimension the global `config`
+// table lacks: `tier:"user"` descriptors (settings/registry.ts) resolve the SAME
+// `(namespace, key)` address to a per-user value, keyed by the resolved `users.id` (#393),
+// so a human's pref follows them across devices. This is the storage seam ONLY — schema
+// validation + scope enforcement stay in the registry/route; this module just persists the
+// per-user JSON value and mirrors the `config`-table ConfigEntry shape so the settings API
+// treats user-tier and server-runtime values uniformly.
+//
+// Deliberately NOT folded into config-store.ts: the global `config` table keeps its exact
+// `(namespace, key)` PK + history semantics untouched (#391 back-compat), and the
+// transport-thinness/file-size ratchets keep config-store as the instance-global home. Per-user
+// prefs are low-stakes display state, so no config_history mirror — last-write-wins with a
+// monotonic version is enough.
+
+import { getDb } from "./db";
+import type { ConfigEntry } from "agent-relay-sdk";
+
+interface UserSettingRow {
+  user_id: string;
+  namespace: string;
+  key: string;
+  value: string;
+  version: number;
+  updated_at: string;
+  updated_by: string | null;
+}
+
+function rowToConfigEntry<T>(row: UserSettingRow): ConfigEntry<T> {
+  return {
+    namespace: row.namespace,
+    key: row.key,
+    value: JSON.parse(row.value) as T,
+    version: row.version,
+    updatedAt: row.updated_at,
+    updatedBy: row.updated_by ?? undefined,
+  };
+}
+
+/** A single user's stored value for a `tier:"user"` descriptor, or null when unset (→ defaults). */
+export function getUserSetting<T = unknown>(userId: string, namespace: string, key: string): ConfigEntry<T> | null {
+  const row = getDb()
+    .query("SELECT * FROM user_settings WHERE user_id = ? AND namespace = ? AND key = ?")
+    .get(userId, namespace, key) as UserSettingRow | undefined;
+  return row ? rowToConfigEntry<T>(row) : null;
+}
+
+/** All of a user's stored values in a namespace (ascending key). */
+export function listUserSettings<T = unknown>(userId: string, namespace: string): ConfigEntry<T>[] {
+  const rows = getDb()
+    .query("SELECT * FROM user_settings WHERE user_id = ? AND namespace = ? ORDER BY key ASC")
+    .all(userId, namespace) as UserSettingRow[];
+  return rows.map(rowToConfigEntry<T>);
+}
+
+/** Upsert a user's value for a descriptor. Value is persisted verbatim — validate via the registry first. */
+export function setUserSetting<T = unknown>(
+  userId: string,
+  namespace: string,
+  key: string,
+  value: T,
+  updatedBy?: string,
+): ConfigEntry<T> {
+  const existing = getUserSetting(userId, namespace, key);
+  const now = new Date().toISOString();
+  const nextVersion = existing ? existing.version + 1 : 1;
+  getDb()
+    .query(`
+      INSERT INTO user_settings (user_id, namespace, key, value, version, updated_at, updated_by)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(user_id, namespace, key) DO UPDATE SET
+        value = excluded.value,
+        version = excluded.version,
+        updated_at = excluded.updated_at,
+        updated_by = excluded.updated_by
+    `)
+    .run(userId, namespace, key, JSON.stringify(value), nextVersion, now, updatedBy ?? null);
+  return getUserSetting<T>(userId, namespace, key)!;
+}
+
+/** Drop a user's stored value (reverts to descriptor defaults). Returns false when nothing was stored. */
+export function deleteUserSetting(userId: string, namespace: string, key: string): boolean {
+  const existing = getUserSetting(userId, namespace, key);
+  if (!existing) return false;
+  getDb().query("DELETE FROM user_settings WHERE user_id = ? AND namespace = ? AND key = ?").run(userId, namespace, key);
+  return true;
+}