agent-relay-server 0.80.0 → 0.82.0

package/src/db/users.ts

@@ -0,0 +1,120 @@
+// First-class human users (#388 keystone #393). The relational identity store behind the
+// per-user `user:<id>` addressing namespace. Addressing/alias logic lives in the SDK
+// (agent-relay-sdk `users.ts`, the single resolver home); this module owns persistence.
+import { DEFAULT_USER_ID } from "agent-relay-sdk";
+import { ValidationError, getDb } from "./connection.ts";
+import type { CreateUserInput, User, UserRole, UserStatus } from "../types";
+
+interface UserRow {
+  id: string;
+  handle: string;
+  display_name: string;
+  role: string;
+  status: string;
+  tenant_id: string | null;
+  avatar_artifact_id: string | null;
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Single DDL home for the `users` table (#388 keystone #393). Called from initDb (fresh DBs)
+ * and applyMigrations (existing DBs gain it on upgrade), mirroring the
+ * `ensureContinuationArchiveSearchSchema` pattern. `tenant_id` is the SaaS multi-tenant seam
+ * (nullable, defaulted — multi-tenant becomes an additive migration, not a refactor);
+ * `avatar_artifact_id` is the column-only avatar FK toward the artifact stack (#395/#630).
+ */
+export function ensureUsersSchema(): void {
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY,
+      handle TEXT NOT NULL,
+      display_name TEXT NOT NULL,
+      role TEXT NOT NULL DEFAULT 'operator',
+      status TEXT NOT NULL DEFAULT 'active',
+      tenant_id TEXT DEFAULT 'default',
+      avatar_artifact_id TEXT REFERENCES artifacts(id) ON DELETE SET NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE UNIQUE INDEX IF NOT EXISTS idx_users_handle ON users(coalesce(tenant_id, ''), handle)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_users_tenant ON users(tenant_id)");
+}
+
+function rowToUser(row: UserRow): User {
+  return {
+    id: row.id,
+    handle: row.handle,
+    displayName: row.display_name,
+    role: row.role as UserRole,
+    status: row.status as UserStatus,
+    tenantId: row.tenant_id,
+    avatarArtifactId: row.avatar_artifact_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+export function getUser(id: string): User | undefined {
+  const row = getDb().query("SELECT * FROM users WHERE id = ?").get(id) as UserRow | null;
+  return row ? rowToUser(row) : undefined;
+}
+
+export function getUserByHandle(handle: string, tenantId: string | null = "default"): User | undefined {
+  const row = getDb()
+    .query("SELECT * FROM users WHERE handle = ? AND coalesce(tenant_id, '') = coalesce(?, '')")
+    .get(handle, tenantId) as UserRow | null;
+  return row ? rowToUser(row) : undefined;
+}
+
+export function listUsers(): User[] {
+  const rows = getDb().query("SELECT * FROM users ORDER BY created_at").all() as UserRow[];
+  return rows.map(rowToUser);
+}
+
+export function createUser(input: CreateUserInput): User {
+  if (!input.id) throw new ValidationError("user id is required");
+  if (!input.handle) throw new ValidationError("user handle is required");
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO users (id, handle, display_name, role, status, tenant_id, avatar_artifact_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      input.id,
+      input.handle,
+      input.displayName || input.handle,
+      input.role ?? "operator",
+      input.status ?? "active",
+      input.tenantId === undefined ? "default" : input.tenantId,
+      input.avatarArtifactId ?? null,
+      now,
+      now,
+    );
+  const created = getUser(input.id);
+  if (!created) throw new ValidationError(`failed to create user ${input.id}`);
+  return created;
+}
+
+/**
+ * Seed the admin-level default user mapped to the existing single human (#393 P0).
+ * Idempotent (ON CONFLICT DO NOTHING) so it runs safely on every boot/migration — the
+ * existing human is NEVER locked out, and the relational identity all later #388 waves FK to
+ * (`users.id='default'`, role=admin, tenant_id='default') exists from day one. Bare `'user'`
+ * and `user:default` both resolve to this row (see the SDK resolver helpers).
+ */
+export function seedDefaultUser(): User {
+  const now = Date.now();
+  getDb()
+    .query(
+      `INSERT INTO users (id, handle, display_name, role, status, tenant_id, avatar_artifact_id, created_at, updated_at)
+       VALUES (?, 'admin', 'User', 'admin', 'active', 'default', NULL, ?, ?)
+       ON CONFLICT(id) DO NOTHING`,
+    )
+    .run(DEFAULT_USER_ID, now, now);
+  const seeded = getUser(DEFAULT_USER_ID);
+  if (!seeded) throw new ValidationError("failed to seed default user");
+  return seeded;
+}

package/src/maintenance/teams.ts

@@ -13,13 +13,7 @@ import { dissolveTeamById } from "../services/team";
 import { getTeamsConfig } from "../teams-config-store";
 import { teamReapGraceMs } from "./constants";
 import { notifyTarget } from "./events";
-
-interface TeamIdleTrackerEntry {
-  firstNoBusyAt: number;
-  pinged: boolean;
-}
-
-const teamIdleTracker = new Map<string, TeamIdleTrackerEntry>();
+import { teamIdleTracker } from "../team-idle-tracker";
 
 export function resetTeamIdleWatchdogForTests(): void {
   teamIdleTracker.clear();

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/teams.ts

@@ -1,9 +1,10 @@
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { authContextFromRequest } from "../services/auth-context";
-import { getTeam, getTeamOutcomeAggregates, listAllTeams, ValidationError } from "../db";
-import { dissolveCallerTeam, dissolveTeamById, getCallerTeam, setCallerTeamBrief, TeamAuthError, TeamNotFoundError, type TeamDissolveServiceInput } from "../services/team";
+import { getTeam, getTeamOutcomeAggregates, getPlanByTeam, listAllTeams, ValidationError } from "../db";
+import { dissolveCallerTeam, dissolveTeamById, deriveTeamRuntimeState, getCallerTeam, setCallerTeamBrief, TeamAuthError, TeamNotFoundError, type TeamDissolveServiceInput } from "../services/team";
 import { cleanString, optionalEnum } from "../validation";
 import { authorizeRoute, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import { STALE_TTL_MS } from "../config";
 import type { Team } from "../types";
 
 const OUTCOME_STATUSES = ["success", "partial", "failed"] as const;
@@ -43,8 +44,14 @@ export const getTeamsRoute: Handler = (req) => {
   if (denied) return denied;
   try {
     const status = optionalEnum(new URL(req.url).searchParams.get("status") ?? undefined, "status", TEAM_STATUSES) as Team["status"] | undefined;
-    const teams = listAllTeams();
-    return json({ teams: status ? teams.filter((team) => team.status === status) : teams });
+    const cutoff = Date.now() - STALE_TTL_MS;
+    const all = listAllTeams();
+    const filtered = status ? all.filter((team) => team.status === status) : all;
+    const teams = filtered.map((team) => {
+      const plan = team.status === "active" ? getPlanByTeam(team.id) ?? null : null;
+      return { ...team, runtimeState: deriveTeamRuntimeState(team, plan, cutoff) };
+    });
+    return json({ teams });
   } catch (err) {
     return routeError(err);
   }

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`.