@humwick/server 0.130.2 → 0.130.4

package/src/routes/agent-sessions.ts

@@ -4,7 +4,7 @@ import { isHumanAgentId, PROVIDER_SUBMIT_UNCONFIRMED, RELAY_TOKEN_HEADER, SUBMIT
 import { authorizeAgentControl } from "../agent-authz";
 import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, canViewAgentRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, requestUserId, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { arbitrateDrive, currentDriver, drivingMessage, releaseDrive, type DriveArbitration } from "../agent-drive-arbiter";
-import { ValidationError, getAgent, getAgentTimelineAsync, getOrchestrator, markReadyAsync, mergeAgentMetaAsync, sendMessage } from "../db";
+import { sendMessageAsync, ValidationError, getAgent, getAgentTimelineAsync, getOrchestrator, markReadyAsync, mergeAgentMetaAsync } from "../db";
 import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { cleanString, optionalEnum } from "../validation";
 import { createCommandAsync } from "../commands-write";
@@ -40,10 +40,10 @@ export const postAgentSelfRestartRecheck: Handler = async (req, params) => {
   // orchestrator's own runtime token authorizes this exactly as it authorizes the agent.restart it
   // is executing — no over-refusal that would silently abort every self-restart.
   const orchestrator = agent ? managedControlOrchestrator(agent) : null;
-  const denied = authorizeRoute(req, {
+  const denied = (await authorizeRoute(req, {
     scope: "command:write",
     resource: { agentId: params.id!, orchestratorId: orchestrator?.id, policyName: metaString(agent?.meta, "policyName"), spawnRequestId: metaString(agent?.meta, "spawnRequestId") },
-  });
+  }));
   if (denied) return denied;
   if (!agent) return json({ ok: false, reason: `self-restart safe-point re-check: agent ${params.id} not found` });
   const violation = await evaluateSelfRestartSafePoint(agent);
@@ -161,11 +161,11 @@ export const postAgentAction: Handler = async (req, params) => {
     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", action);
+    const driveDenied = (await authorizeAgentRoute(req, agent.id, "drive", action));
     if (driveDenied) return driveDenied;
     // #3567 — the one lifecycle-control check (the services re-run it for bus/MCP); self excepted.
     const actionCtx = authContextFromRequest(req);
-    const controlDenied = actionCtx.callerAgentId === agent.id ? null : authorizeAgentControl(actionCtx, agent, action);
+    const controlDenied = actionCtx.callerAgentId === agent.id ? null : (await authorizeAgentControl(actionCtx, agent, action));
     if (controlDenied) return error(controlDenied.message, 403);
     // #2664 — releasing a hold that is already gone (recovered, or a double click) is an idempotent no-op.
     if (action === "releaseSubmitHold" && agentIsControlEligible(agent) && !agentSubmitHoldActive(agent)) return json({ ok: true, action, released: false }, 200);
@@ -181,10 +181,10 @@ export const postAgentAction: Handler = async (req, params) => {
     if (action === "interrupt") {
       const arb = await arbitrateDrive(requestUserId(req), agent.id);
       if (!arb.allowed) return driveBlockedResponse(arb);
-      const denied = authorizeRoute(req, {
+      const denied = (await authorizeRoute(req, {
         scope: "agent:write",
         resource: controlResource,
-      });
+      }));
       if (denied) return denied;
       try {
         const result = await dispatchInterrupt({
@@ -208,10 +208,10 @@ export const postAgentAction: Handler = async (req, params) => {
     // bus + MCP surfaces. The route still enforces the coarse `agent:write` scope +
     // constraint-list; the service adds the fine parent→child gate.
     if (action === "shutdown") {
-      const denied = authorizeRoute(req, {
+      const denied = (await authorizeRoute(req, {
         scope: "agent:write",
         resource: controlResource,
-      });
+      }));
       if (denied) return denied;
       try {
         if (parsed.body.hard !== undefined && typeof parsed.body.hard !== "boolean") throw new ValidationError("hard must be a boolean");
@@ -243,10 +243,10 @@ export const postAgentAction: Handler = async (req, params) => {
     const resumeId = action === "resume" ? await latestResumeIdForAgent(agent) : undefined;
     if (action === "resume" && !orchestrator) return error("no online orchestrator available to resume agent", 409);
     if (action === "resume" && !resumeId) return error("no resume id recorded for agent", 422);
-    const denied = authorizeRoute(req, {
+    const denied = (await authorizeRoute(req, {
       scope: "agent:write",
       resource: { ...controlResource, orchestratorId: orchestrator?.id },
-    });
+    }));
     if (denied) return denied;
     // #1953 RC3 — a dashboard restart/resume of a disabled steward is refused (see helper).
     // #1955 (#1953-review nit 2) — AFTER authorizeRoute: run pre-auth, the 409 disclosed to an
@@ -320,7 +320,7 @@ export const postAgentPrompt: Handler = async (req, params) => {
     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");
+    const driveDenied = (await authorizeAgentRoute(req, agent.id, "drive"));
     if (driveDenied) return driveDenied;
     // #394: submitting a prompt takes/refreshes the drive lease. A second human driving the same
     // agent is blocked here (single-user is a no-op), so two operators can't double-submit into one
@@ -328,10 +328,10 @@ export const postAgentPrompt: Handler = async (req, params) => {
     const arb = await arbitrateDrive(requestUserId(req), agent.id);
     if (!arb.allowed) return driveBlockedResponse(arb);
     if (agent.status === "offline") return error("agent is offline", 422);
-    const denied = authorizeRoute(req, {
+    const denied = (await authorizeRoute(req, {
       scope: "message:send",
       resource: { target: agent.id, agentId: requestUserAddress(req) },
-    });
+    }));
     if (denied) return denied;
     // #2664 — the runner holds exactly one unconfirmed prompt for the operator's resend; a new one
     // must not queue behind (or replace) it. Refused before any message row exists.
@@ -341,13 +341,13 @@ export const postAgentPrompt: Handler = async (req, params) => {
     // 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({
+    const message = (await sendMessageAsync({
       from: fromUser,
       to: agent.id,
       kind: "session",
       body,
       ...(attachments ? { payload: { attachments } } : {}),
-    });
+    }));
     const command = await createCommandAsync({
       type: "prompt.inject",
       source: "dashboard",
@@ -397,7 +397,7 @@ 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");
+    const driveDenied = (await authorizeAgentRoute(req, agent.id, "drive"));
     if (driveDenied) return driveDenied;
     // #394: a plan-approve / AskUserQuestion answer drives the turn — only the lease holder (or an
     // admin override) may answer, so two humans can't race competing decisions into one prompt.
@@ -405,10 +405,10 @@ export const postAgentPermissionDecision: Handler = async (req, params) => {
     if (!arb.allowed) return driveBlockedResponse(arb);
     const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
     const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
-    const denied = authorizeRoute(req, {
+    const denied = (await authorizeRoute(req, {
       scope: "agent:write",
       resource: { agentId: agent.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId },
-    });
+    }));
     if (denied) return denied;
     const result = await dispatchAgentPermissionDecision({
       agentId: agent.id,
@@ -487,7 +487,7 @@ export const postAgentDrive: Handler = async (req, params) => {
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
     // Driving the wheel requires the same #392 drive authorization the prompt/interrupt routes use.
-    const driveDenied = authorizeAgentRoute(req, agent.id, "drive");
+    const driveDenied = (await authorizeAgentRoute(req, agent.id, "drive"));
     if (driveDenied) return driveDenied;
     const userId = requestUserId(req);
 
@@ -545,10 +545,10 @@ export const postAgentTerminalSession: Handler = async (req, params) => {
     const metaTmuxSession = typeof agent.meta?.tmuxSession === "string" ? agent.meta.tmuxSession : undefined;
     const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
     const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
-    const denied = authorizeRoute(req, {
+    const denied = (await authorizeRoute(req, {
       scope: "terminal:attach",
       resource: { agentId: agent.id, orchestratorId: orchestrator.id, policyName: metaPolicyName, spawnRequestId: metaSpawnRequestId, terminalAttach: true },
-    });
+    }));
     if (denied) return denied;
     // Provider-owned attach surfaces are more specific than the runner's tmux pane.
     // Codex runs its real interactive TUI as a guest attached to the app-server thread;
@@ -588,7 +588,7 @@ export const deleteAgentTerminalSession: Handler = async (req, params) => {
   if (!agent) return error("agent not found", 404);
   const orchestrator = managedControlOrchestrator(agent);
   if (!orchestrator) return error("agent does not have an online orchestrator", 422);
-  const denied = authorizeRoute(req, {
+  const denied = (await authorizeRoute(req, {
     scope: "terminal:attach",
     resource: {
       agentId: agent.id,
@@ -597,7 +597,7 @@ export const deleteAgentTerminalSession: Handler = async (req, params) => {
       spawnRequestId: typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined,
       terminalAttach: true,
     },
-  });
+  }));
   if (denied) return denied;
   const session = params.session!;
   return proxyOrchestratorDelete(req, orchestrator.id, `/api/terminal-guests/${encodeURIComponent(session)}`);

package/src/routes/agents-spawn.ts

@@ -85,7 +85,7 @@ export const postAgent: Handler = async (req) => {
     // timeline note, parent-wake, audit) live in src/services/register-agent.ts so the HTTP,
     // bus, and orchestrator-report paths cannot drift (epic #342).
     const input = normalizeAgentInput(parsed.body);
-    const agent = registerAgent(input, authContextFromRequest(req));
+    const agent = await registerAgent(input, authContextFromRequest(req));
     return json(agent, 201);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);

package/src/routes/agents.ts

@@ -1,8 +1,8 @@
 // Auto-split from routes.ts (#299). Domain: agents.
 import { messageViewerForRequest, visibleMessages } from "./message-viewer";
 import { attachPrincipal, attachPrincipals } from "../agent-principal";
-import { VALID_AGENT_STATUSES, agentSessionStatus, auditEvent, canViewAgentRoute, error, json, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, visibleAgentIdsForRequest, type Handler } from "./_shared";
-import { ValidationError, deleteAgentAsync, getAgent, getAgentAsync, getAgentIdentityAsync, getAgentQuotaSnapshotsAsync, getAgentTimelineAsync, getCrashReport, recordHeartbeatAsync, listAgentChatHistoryAsync, listAgents, listAgentsAsync, listArtifactsForEntityAsync, listContextSnapshotsAsync, listPendingReplyObligationsAsync, markReadyAsync, searchAgentsAsync, setLabelAsync, setStatusAsync, setTagsAsync, validateAgentSession } from "../db";
+import { agentSessionStatus, auditEvent, authorizeRoute, canViewAgentRoute, error, json, normalizeAgentSessionGuard, parseBody, parseId, parseQueryInt, visibleAgentIdsForRequest, type Handler } from "./_shared";
+import { ValidationError, deleteAgentAsync, getAgent, getAgentAsync, getAgentIdentityAsync, getAgentQuotaSnapshotsAsync, getAgentTimelineAsync, getCrashReport, listAgentChatHistoryAsync, listAgents, listAgentsAsync, listArtifactsForEntityAsync, listContextSnapshotsAsync, listPendingReplyObligationsAsync, searchAgentsAsync, setLabelAsync, setTagsAsync, validateAgentSession } from "../db";
 import { attachBranchState, attachBranchStates } from "../agent-branch-state";
 import { redactAgentCardLaunchShape } from "../agent-launch-shape-redaction";
 import { attachChannelBinding, attachChannelBindings } from "../agent-channel-binding";
@@ -10,47 +10,16 @@ import { attachCommandActivities, attachCommandActivity } from "../agent-command
 import { attachIssueRepo, attachIssueRepos } from "../agent-issue-repo";
 import { cleanStringArray } from "../validation";
 import { emitAgentRemoved, emitAgentStatus } from "../sse";
-import { announceSpawnedAgentReady } from "../services/register-agent";
-import { flushQueuedDirectMessages } from "../services/managed-running";
-import { acquireTeamOnReady } from "../services/team";
 import { artifactReadScopeForRequest } from "../services/artifact-access";
-import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "@humwick/sdk";
 import { getComponentAuth, hasComponentScope } from "../security";
-import { type AgentCard, type AgentSessionGuard } from "../types";
+import { type AgentCard } from "../types";
 import { attachToolchain } from "../project-toolchain";
 import { listEffortChangesAsync } from "../commands-write";
 import { markAgentWorkFinal } from "../services/work-finality";
-
-type AgentActivityState = {
-  key: "available" | "busy" | "not-ready" | "offline";
-  title: string;
-  icon: string;
-};
-
-function agentActivityState(agent?: Pick<AgentCard, "ready" | "status"> | null): AgentActivityState | null {
-  if (!agent) return null;
-  if (agent.status === "offline") return { key: "offline", title: "Agent offline", icon: "ti-plug-off" };
-  if (!agent.ready) return { key: "not-ready", title: "Agent not ready", icon: "ti-loader" };
-  if (agent.status === "busy") return { key: "busy", title: "Agent busy", icon: "ti-activity" };
-  return { key: "available", title: "Agent available", icon: "ti-circle-check" };
-}
-
-async function auditAgentStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): Promise<void> {
-  const previous = agentActivityState(before);
-  const next = agentActivityState(after);
-  if (!next || previous?.key === next.key) return;
-  await auditEvent({
-    clientId: "server-agent-" + agentId + "-state-" + next.key + "-" + Date.now(),
-    kind: "state",
-    title: next.title,
-    meta: agentId,
-    icon: next.icon,
-    view: "agents",
-    agentId,
-  });
-}
+import { authorizeProviderQuotaWrite } from "./provider-quotas";
+import { applyAgentHeartbeat, applyAgentReady, applyAgentStatus, cleanAgentStatus, cleanHeartbeatReport, noteUnchangedLifecycle } from "../services/agent-heartbeat";
 
 // #1797 round 2 (F1b) — the agent roster carried `meta.policyName` + `meta.spawnRequestId` in the
 // clear to any `agent:read` holder. Those two strings are the ADDRESSING for every managed-agent
@@ -248,56 +217,6 @@ export const getTaskArtifactsRoute: Handler = async (req, params) => {
   return json(await listArtifactsForEntityAsync("task", id, artifactReadScopeForRequest(req)));
 };
 
-type AgentStatusValue = (typeof VALID_AGENT_STATUSES)[number];
-
-function cleanAgentStatus(value: unknown): AgentStatusValue {
-  if (!VALID_AGENT_STATUSES.includes(value as AgentStatusValue)) throw new ValidationError(`status must be one of: ${VALID_AGENT_STATUSES.join(", ")}`);
-  return value as AgentStatusValue;
-}
-
-// #3606 — a reported status/readiness equal to the live card is a liveness tick, not a transition: no
-// row write, no agent.status event. Presence still advances through the coalescing heartbeat buffer,
-// except for a terminal row, which a beat would resurrect.
-async function noteUnchangedLifecycle(agentId: string, current: AgentCard, guard: AgentSessionGuard | undefined): Promise<void> {
-  if (current.status !== "offline" && current.status !== "stale") await recordHeartbeatAsync(agentId, { guard });
-}
-
-async function applyAgentStatus(agentId: string, status: AgentStatusValue, guard: AgentSessionGuard | undefined, before: AgentCard | null): Promise<boolean> {
-  // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
-  if (!(await setStatusAsync(agentId, status, guard))) return false;
-  await auditAgentStateTransition(agentId, before, getAgent(agentId));
-  await emitAgentStatus(agentId);
-  return true;
-}
-
-async function applyAgentReady(agentId: string, ready: boolean, guard: AgentSessionGuard | undefined, before: AgentCard | null): Promise<boolean> {
-  // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
-  if (!(await markReadyAsync(agentId, ready, guard))) return false;
-  await auditAgentStateTransition(agentId, before, getAgent(agentId));
-  // #308 — a spawned child flipping false→true ready is "genuinely ready" (past onboarding):
-  // wake its parent so it can stop block-polling and stamp the durable readiness. #2432 —
-  // announceSpawnedAgentReady is the shared seam; it no-ops for non-spawned agents and dedups
-  // repeat readies (e.g. a later bus status frame or PATCH for an already-announced child).
-  // #1927 review round 2 (HIGH 1) — the audit above now awaits the async gateway, widening the
-  // window for a concurrent same-instance PATCH to flip ready back to false before we get here.
-  // Re-read the LIVE card (and re-check the session guard) right before firing these effects
-  // instead of trusting the pre-audit snapshot, so a superseded transition never fires a false
-  // durable agent.ready.
-  if (ready && !before?.ready) {
-    const live = getAgent(agentId);
-    const stillCurrentInstance = validateAgentSession(agentId, guard).ok;
-    if (live?.ready === true && stillCurrentInstance) {
-      announceSpawnedAgentReady(agentId, "agent-ready");
-      acquireTeamOnReady(agentId); // #3107 — before the flush, so seat mail reaches a new holder
-      // #416 — also flush queued direct messages: a not-ready agent that becomes ready
-      // may have queued messages waiting (e.g. starting up, clearing context).
-      flushQueuedDirectMessages(agentId);
-    }
-  }
-  await emitAgentStatus(agentId);
-  return true;
-}
-
 export const patchAgentStatus: Handler = async (req, params) => {
   const parsed = await parseBody<{ status: string }>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -322,40 +241,19 @@ export const postHeartbeat: Handler = async (req, params) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
-    // #3606 — the runner's liveness tick reports status and readiness on this one call (it used to
-    // be status PATCH + ready PATCH + heartbeat). Only a value that differs from the live card takes
-    // the transition path; the rest is a coalesced beat.
-    const body = isRecord(parsed.body) ? parsed.body : {};
-    const status = body.status === undefined ? undefined : cleanAgentStatus(body.status);
-    if (body.ready !== undefined && typeof body.ready !== "boolean") return error("ready must be a boolean");
-    const ready = body.ready as boolean | undefined;
-    const guard = normalizeAgentSessionGuard(req, parsed.body);
-    const session = validateAgentSession(params.id!, guard);
-    if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
-    // #416 — capture unavailability before heartbeat to detect the transition.
-    const beforeHeartbeat = getAgent(params.id!);
-    if (beforeHeartbeat?.kind === "channel" && !beforeHeartbeat.ready) {
-      return error("channel agent not ready; re-register required", 409);
-    }
-    const wasUnavailable = beforeHeartbeat ? isAgentUnavailable(beforeHeartbeat) : false;
-    let current = beforeHeartbeat;
-    if (status !== undefined && status !== current?.status) {
-      if (!(await applyAgentStatus(params.id!, status, guard, current))) return error("agent not found", 404);
-      current = getAgent(params.id!);
-    }
-    if (ready !== undefined && ready !== current?.ready) {
-      if (!(await applyAgentReady(params.id!, ready, guard, current))) return error("agent not found", 404);
-    }
-    // A reported terminal status must not be undone by the beat's offline/stale resurrection.
-    if (status !== "offline" && status !== "stale") {
-      // #1468 — route the API heartbeat through the same coalescing buffer as the bus path.
-      if (!(await recordHeartbeatAsync(params.id!, { guard }))) return error("agent not found", 404);
+    // #3606 — the runner's liveness tick reports status and readiness on this one call; the bus
+    // `agent.heartbeat` frame (#3618) is the same exchange through the same service.
+    const report = cleanHeartbeatReport(params.id!, parsed.body);
+    if (report.unread) {
+      const denied = await authorizeRoute(req, { scope: "message:read", resource: { agentId: params.id!, target: params.id! } });
+      if (denied) return denied;
     }
-    if (wasUnavailable) {
-      const after = getAgent(params.id!);
-      if (after && !isAgentUnavailable(after)) flushQueuedDirectMessages(params.id!);
+    if (report.providerQuota) {
+      const denied = (await authorizeRoute(req, { scope: "quota:write", resource: { agentId: params.id! } })) ?? await authorizeProviderQuotaWrite(req, report.providerQuota);
+      if (denied) return denied;
     }
-    return json({ ok: true });
+    const outcome = await applyAgentHeartbeat(params.id!, report, normalizeAgentSessionGuard(req, parsed.body), messageViewerForRequest(req));
+    return outcome.ok ? json(outcome.result) : error(outcome.error, outcome.status);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -439,7 +337,7 @@ export const patchAgentReady: Handler = async (req, params) => {
 };
 
 export const deleteAgentById: Handler = async (_req, params) => {
-  markAgentWorkFinal(params.id!, "edge-fallback");
+  (await markAgentWorkFinal(params.id!, "edge-fallback"));
   // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
   const result = await deleteAgentAsync(params.id!);
   if (!result.ok) {

package/src/routes/auth.ts

@@ -3,10 +3,10 @@ import { authorityDenied, recordUserManagement } from "../authority-audit";
 // (src/index.ts) so they are reachable unauthenticated — each handler owns its own auth: login
 // verifies credentials, refresh validates the refresh token, logout revokes the presented session.
 // Everything else on the relay still flows through the existing component-token gate.
-import { isRecord, type User } from "@humwick/sdk";
-import { error, json, parseBody, type Handler } from "./_shared";
+import { DEFAULT_USER_ID, isRecord, type User } from "@humwick/sdk";
+import { error, isAdminRequest, json, parseBody, requestUserId, type Handler } from "./_shared";
 import { getAuthProvider, listAuthProviders, mintUserSession, type MintedSession } from "../auth";
-import { getAuthIdentity, getUser } from "../db";
+import { getAuthIdentity, getUser, InviteUnavailableError, ValidationError } from "../db";
 import { revokeTokenAsync } from "../token-db-write.ts";
 import { refreshUserSession } from "../auth/session-refresh";
 import { revokeUserSession } from "../auth/session";
@@ -14,7 +14,7 @@ import { readSessionCookie, sessionOriginAllowed, withSessionCookie } from "../a
 import { getComponentAuth } from "../security";
 import { acceptInvite, userInvitesEnabled } from "../services/user-onboarding";
 import { invitesDisabled } from "./users";
-import { InviteUnavailableError, ValidationError } from "../db";
+import { mintLoginLink, redeemLoginLink } from "../auth/login-link";
 
 /** Public projection of a user for login/refresh responses — never leaks internal-only columns. */
 function userView(user: User): Record<string, unknown> {
@@ -60,7 +60,7 @@ export const getAuthProvidersRoute: Handler = () =>
  * session. Every failure returns the same generic 401 (no provider/user/credential enumeration).
  */
 export const postAuthLoginRoute: Handler = async (req) => {
-  if (!sessionOriginAllowed(req, false)) return authorityDenied(req, "origin not allowed", 403);
+  if (!sessionOriginAllowed(req, false)) return (await authorityDenied(req, "origin not allowed", 403));
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   if (!isRecord(parsed.body)) return error("login body required", 400);
@@ -68,33 +68,33 @@ export const postAuthLoginRoute: Handler = async (req) => {
   if (typeof providerId !== "string" || !providerId) return error("provider required", 400);
 
   const provider = getAuthProvider(providerId);
-  if (!provider) return authorityDenied(req, "invalid credentials", 401);
+  if (!provider) return (await authorityDenied(req, "invalid credentials", 401));
 
   const result = await provider.verify(parsed.body);
-  if (!result) return authorityDenied(req, "invalid credentials", 401);
+  if (!result) return (await authorityDenied(req, "invalid credentials", 401));
 
   const identity = getAuthIdentity(provider.id, result.providerSubject);
-  if (!identity) return authorityDenied(req, "invalid credentials", 401);
+  if (!identity) return (await authorityDenied(req, "invalid credentials", 401));
 
   const user = getUser(identity.userId);
-  if (!user || user.status !== "active") return authorityDenied(req, "invalid credentials", 401);
+  if (!user || user.status !== "active") return (await authorityDenied(req, "invalid credentials", 401));
 
-  return sessionResponse(req, user, mintUserSession(user));
+  return sessionResponse(req, user, (await mintUserSession(user)));
 };
 
 /** POST /api/auth/refresh — cookie only, same-origin, with a short concurrent-request grace. */
 export const postAuthRefreshRoute: Handler = async (req) => {
-  if (!sessionOriginAllowed(req)) return authorityDenied(req, "origin not allowed", 403);
+  if (!sessionOriginAllowed(req)) return (await authorityDenied(req, "origin not allowed", 403));
   const refreshToken = readSessionCookie(req);
   const result = refreshToken ? await refreshUserSession(refreshToken) : null;
   // A stale response must never delete the cookie just rotated by another tab (#3567).
-  if (!result) return authorityDenied(req, "invalid refresh token", 401);
+  if (!result) return (await authorityDenied(req, "invalid refresh token", 401));
   return sessionResponse(req, result.user, result.session);
 };
 
 /** POST /api/auth/logout — bearer authenticates the session; the refresh-only cookie is cleared. */
 export const postAuthLogoutRoute: Handler = async (req) => {
-  if (!sessionOriginAllowed(req, false)) return authorityDenied(req, "origin not allowed", 403);
+  if (!sessionOriginAllowed(req, false)) return (await authorityDenied(req, "origin not allowed", 403));
   const component = getComponentAuth(req);
   if (component?.jti && !(await revokeUserSession(component))) await revokeTokenAsync(component.jti, "admin");
   return withSessionCookie(req, new Response(null, { status: 204 }));
@@ -105,7 +105,7 @@ export const postAuthLogoutRoute: Handler = async (req) => {
  * the single-use code is the credential. Creates the user and returns their first session.
  */
 export const postAcceptInviteRoute: Handler = async (req) => {
-  if (!sessionOriginAllowed(req, false)) return authorityDenied(req, "origin not allowed", 403);
+  if (!sessionOriginAllowed(req, false)) return (await authorityDenied(req, "origin not allowed", 403));
   if (!userInvitesEnabled()) return invitesDisabled();
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
@@ -113,11 +113,38 @@ export const postAcceptInviteRoute: Handler = async (req) => {
   const body = parsed.body;
   try {
     const user = await acceptInvite({ code: body.code, handle: body.handle, password: body.password, displayName: typeof body.displayName === "string" ? body.displayName.trim().slice(0, 120) || undefined : undefined });
-    recordUserManagement(req, user.id, "accept invite", { role: user.role }, user.id);
-    return sessionResponse(req, user, mintUserSession(user), 201);
+    (await recordUserManagement(req, user.id, "accept invite", { role: user.role }, user.id));
+    return sessionResponse(req, user, (await mintUserSession(user)), 201);
   } catch (e) {
-    if (e instanceof InviteUnavailableError) return authorityDenied(req, e.message, 410);
+    if (e instanceof InviteUnavailableError) return (await authorityDenied(req, e.message, 410));
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
   }
 };
+
+/**
+ * POST /api/auth/login-links — admin only (#2680). Body `{ userId? }`, default the seeded admin user.
+ * `humwick init` calls this with the admin token so the first login needs no token at all.
+ */
+export const postLoginLinkRoute: Handler = async (req) => {
+  if (!isAdminRequest(req)) return (await authorityDenied(req, "only an admin can mint a login link"));
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const userId = isRecord(parsed.body) && typeof parsed.body.userId === "string" ? parsed.body.userId : DEFAULT_USER_ID;
+  const user = getUser(userId);
+  if (!user || user.status !== "active") return error("user not found or not active", 404);
+  const link = await mintLoginLink(user, `auth:login-link:${requestUserId(req)}`);
+  recordUserManagement(req, user.id, "mint login link");
+  return json(link, 201);
+};
+
+/** POST /api/auth/login-links/redeem — public; the single-use link code is the credential. */
+export const postRedeemLoginLinkRoute: Handler = async (req) => {
+  if (!sessionOriginAllowed(req, false)) return (await authorityDenied(req, "origin not allowed", 403));
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  const code = isRecord(parsed.body) ? parsed.body.code : undefined;
+  const user = typeof code === "string" && code ? await redeemLoginLink(code) : null;
+  if (!user) return (await authorityDenied(req, "login link is invalid, expired or already used", 401));
+  return sessionResponse(req, user, (await mintUserSession(user)));
+};

package/src/routes/authority-audit.ts

@@ -5,9 +5,9 @@ import { isAdminRequest } from "./users";
 
 /** GET /api/users/authority-denials — private, bounded admin audit list. */
 export const getAuthorityDenials: Handler = async (req) => {
-  const denied = authorizeRoute(req, { scope: "system:admin" });
+  const denied = (await authorizeRoute(req, { scope: "system:admin" }));
   if (denied) return denied;
-  if (!isAdminRequest(req)) return authorityDenied(req, "only admins can read authority denials");
+  if (!isAdminRequest(req)) return (await authorityDenied(req, "only admins can read authority denials"));
   const limit = parseQueryInt(new URL(req.url).searchParams.get("limit"), { min: 1, max: 500 });
   if (Number.isNaN(limit)) return error("limit must be an integer between 1 and 500");
   return json(await listActivityEventsAsync({ title: AUTHORITY_DENIED, limit: limit ?? 100 }));

package/src/routes/automations.ts

@@ -1,6 +1,7 @@
 // Auto-split from routes.ts (#299). Domain: automations.
 import { ValidationError } from "../db";
-import { createAutomationAsync, deleteAutomation, getAutomation, listAutomationRuns, listAutomations, runAutomationNowAsync, updateAutomationAsync, type AutomationDispatchResult } from "../automations";
+import { listAutomationRunsAsync } from "../automations/read-async";
+import { createAutomationAsync, deleteAutomationAsync, getAutomation, listAutomations, runAutomationNowAsync, updateAutomationAsync, type AutomationDispatchResult } from "../automations";
 import { emitCommand, error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
 import { emitNewMessage, emitTaskChanged } from "../sse";
 import { emitRelayEvent } from "../events";
@@ -53,8 +54,8 @@ export const patchAutomation: Handler = async (req, params) => {
   }
 };
 
-export const deleteAutomationById: Handler = (_req, params) => {
-  if (!deleteAutomation(params.id!)) return error("automation not found", 404);
+export const deleteAutomationById: Handler = async (_req, params) => {
+  if (!(await deleteAutomationAsync(params.id!))) return error("automation not found", 404);
   emitRelayEvent({ type: "automation.deleted", source: "server", subject: params.id!, data: { automationId: params.id! } });
   return json({ ok: true });
 };
@@ -71,11 +72,11 @@ export const postAutomationRun: Handler = async (_req, params) => {
   }
 };
 
-export const getAutomationRuns: Handler = (req) => {
+export const getAutomationRuns: Handler = async (req) => {
   const url = new URL(req.url);
   const limitRaw = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500 });
   if (Number.isNaN(limitRaw)) return error("limit must be an integer between 1 and 500");
-  return json(listAutomationRuns({
+  return json(await listAutomationRunsAsync({
     automationId: url.searchParams.get("automationId") ?? undefined,
     status: url.searchParams.get("status") ?? undefined,
     limit: limitRaw ?? 100,

package/src/routes/channel-binding-delete.ts

@@ -5,7 +5,7 @@ import { ValidationError } from "../db/connection";
 import { authorizeRoute, error, json, normalizeAgentSessionGuard, parseBody, type Handler } from "./_shared";
 
 export const deleteChannelBinding: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "channel:write" });
+  const denied = (await authorizeRoute(req, { scope: "channel:write" }));
   if (denied) return denied;
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);

package/src/routes/channel-output.ts

@@ -3,12 +3,12 @@ import { authContextFromRequest } from "../services/auth-context";
 import { ValidationError } from "../db/connection";
 import { authorizeRoute, error, json, parseBody, type Handler } from "./_shared";
 
-export const getChannelOutput: Handler = (req, params) => {
-  const denied = authorizeRoute(req, { scope: "channel:read", resource: { channel: params.id } });
+export const getChannelOutput: Handler = async (req, params) => {
+  const denied = (await authorizeRoute(req, { scope: "channel:read", resource: { channel: params.id } }));
   return denied ?? json(channelOutputControl(params.id!));
 };
 export const postChannelOutput: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "channel:egress", resource: { channel: params.id } });
+  const denied = (await authorizeRoute(req, { scope: "channel:egress", resource: { channel: params.id } }));
   if (denied) return denied;
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);

package/src/routes/claude-api-budget.ts

@@ -5,7 +5,7 @@ import { authorizeRoute, error, json, parseBody, type Handler } from "./_shared"
 import { apiBudgetId, isRecord } from "@humwick/sdk";
 
 export const apiBudgetStatusRoute: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "system:admin" });
+  const denied = (await authorizeRoute(req, { scope: "system:admin" }));
   if (denied) return denied;
   try { return json(await apiBudgetStatusAsync(apiBudgetId(params.budgetId))); }
   catch { return error("Unknown API budget", 404); }
@@ -16,7 +16,7 @@ export const apiBudgetStatusRoute: Handler = async (req, params) => {
  * it returns the status snapshot only and exposes no mutation.
  */
 export const apiBudgetSummaryRoute: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "agent:read" });
+  const denied = (await authorizeRoute(req, { scope: "agent:read" }));
   if (denied) return denied;
   try {
     const summary: ApiBudgetSummary = await apiBudgetStatusAsync(apiBudgetId(params.budgetId));
@@ -24,7 +24,7 @@ export const apiBudgetSummaryRoute: Handler = async (req, params) => {
   } catch { return error("Unknown API budget", 404); }
 };
 export const apiBudgetConfigureRoute: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "system:admin" });
+  const denied = (await authorizeRoute(req, { scope: "system:admin" }));
   if (denied) return denied;
   const body = await parseBody<unknown>(req);
   if (!body.ok) return error(body.error, body.status);
@@ -37,7 +37,7 @@ export const apiBudgetConfigureRoute: Handler = async (req, params) => {
 export const apiBudgetSessionRoute: Handler = async (req, params) => {
   if (params.action !== "reserve" && params.action !== "report") return error("Unknown budget operation", 404);
   const agentId = params.id!;
-  const denied = authorizeRoute(req, { scope: "agent:write", resource: { agentId } });
+  const denied = (await authorizeRoute(req, { scope: "agent:write", resource: { agentId } }));
   if (denied) return denied;
   const body = await parseBody<unknown>(req);
   if (!body.ok) return error(body.error, body.status);
@@ -55,7 +55,7 @@ export const apiBudgetSessionRoute: Handler = async (req, params) => {
 };
 
 export const apiBudgetAgentRoute: Handler = async (req, params) => {
-  const denied = authorizeRoute(req, { scope: "agent:read", resource: { agentId: params.id! } });
+  const denied = (await authorizeRoute(req, { scope: "agent:read", resource: { agentId: params.id! } }));
   if (denied) return denied;
   try {
     const budgetId = apiBudgetId(new URL(req.url).searchParams.get("budgetId") ?? "openai-api");

package/src/routes/commands-listing.ts

@@ -42,7 +42,7 @@ export const getCommands: Handler = async (req) => {
 
 // The host only needs existence, not historical command params/results (#3063).
 export const getActiveCleanup: Handler = async (req) => {
-  const denied = authorizeRoute(req, { scope: "command:read" });
+  const denied = (await authorizeRoute(req, { scope: "command:read" }));
   if (denied) return denied;
   try {
     const target = cleanString(new URL(req.url).searchParams.get("target"), "target", { required: true, max: 240 });