@humwick/server 0.130.2 → 0.130.4

package/src/agent-lifecycle-events.ts

@@ -1,9 +1,10 @@
-import { clearAgentNotice, hasAgentExitNotice, recordAgentNoticeOnce, recordAgentReadyNoticeOnce } from "./db/terminal-events";
+import { clearAgentNoticeAsync, recordCrashReportAsync, recordTerminalEventAsync } from "./db/lifecycle-tail-async";
+import { hasAgentExitNotice } from "./db/terminal-events";
 import { requestAgentExitCleanup } from "./agent-exit-cleanup";
 import { emitRelayEvent } from "./events";
-import { routeNotification } from "./notification-router";
+import { routeAgentNotice, routeNotification } from "./notification-router";
 import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "./lifecycle-signal-registry";
-import { currentCoordinatorOf, deliverableTaskIdsBySpawnRequestId, getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent, workflowRunIdOf } from "./db";
+import { currentCoordinatorOf, deliverableTaskIdsBySpawnRequestId, getAgent, markAgentReadyNotifiedAsync, workflowRunIdOf } from "./db";
 import { crashReportFor } from "./agent-death-diagnosis";
 import { renderTemplate } from "./prompt-resolver";
 import { markAgentWorkFinal } from "./services/work-finality";
@@ -57,6 +58,19 @@ function diagnosisSuffix(diagnosis?: AgentDeathDiagnosis): string {
 // it guards is same-moment, so a relay restart between the two is not a concern.
 type SpawnTerminal = "agent.ready" | "agent.spawn_failed";
 const spawnTerminalBySpawnRequest = new Map<string, SpawnTerminal>();
+const pendingSpawnNotices = new Map<string, Promise<void>>();
+function spawnQueueKey(agentId: string): string {
+  const child = getAgent(agentId);
+  return (child && spawnRequestIdOf(child)) || agentId;
+}
+// #1870 — terminal guards advance only after commit; serialize one generation across writer awaits.
+function serializeSpawnNotice(key: string, work: () => Promise<void>): Promise<void> {
+  const prior = pendingSpawnNotices.get(key);
+  const result = prior ? prior.catch(() => {}).then(work) : work();
+  pendingSpawnNotices.set(key, result);
+  void result.finally(() => { if (pendingSpawnNotices.get(key) === result) pendingSpawnNotices.delete(key); }).catch(() => {});
+  return result;
+}
 
 // #1513 — spawns we've already told the spawner are queued-for-host-memory, keyed by spawnRequestId
 // (falling back to the parent id when a request has no id). The orchestrator re-reports the whole
@@ -76,13 +90,6 @@ function recordSpawnTerminal(spawnRequestId: string | undefined, outcome: SpawnT
   spawnTerminalBySpawnRequest.set(spawnRequestId, outcome);
 }
 
-function tryRecordSpawnFailed(spawnRequestId: string | undefined): boolean {
-  if (spawnRequestId === undefined) return true;
-  if (spawnTerminalBySpawnRequest.has(spawnRequestId)) return false;
-  spawnTerminalBySpawnRequest.set(spawnRequestId, "agent.spawn_failed");
-  return true;
-}
-
 /** A child counts as "had become ready" once its durable readiness stamp exists. */
 function everReady(child: AgentCard): boolean {
   return typeof child.meta?.readyNotifiedAt === "number";
@@ -128,50 +135,49 @@ function stampChildLifecycleSignal(parent: string, child: AgentCard): void {
  * `spawned_by` parent a one-shot notice so it can stop block-polling. No-op for non-spawned agents
  * and for a child whose ready was already announced (reconnect / heartbeat re-registration).
  */
-export function notifyAgentReady(childId: string): void {
+export async function notifyAgentReady(childId: string): Promise<void> {
+  return serializeSpawnNotice(spawnQueueKey(childId), () => notifyAgentReadyBody(childId));
+}
+
+async function notifyAgentReadyBody(childId: string): Promise<void> {
   const child = getAgent(childId);
   const parent = child?.spawnedBy;
   // A workflow step agent with no spawner (a run a dashboard user started) still records its ready edge on its run (#3160).
   if (!child || (!parent && !workflowRunIdOf(child))) return;
   if (isSpawnIntentCanceled(child.meta?.spawnRequestId)) return;
   // Idempotent — only stamped on first ready; classifies a later offline edge as exited.
-  markAgentReadyNotified(childId);
+  await markAgentReadyNotifiedAsync(childId);
   // #2899 — a self-compact flips ready again; the generation slot keeps the push one-shot.
-  recordAgentReadyNoticeOnce(child, () => announceReady(child, parent));
+  await announceReady(child, parent);
 }
 
-function announceReady(child: AgentCard, spawner: string | undefined): void {
+async function announceReady(child: AgentCard, spawner: string | undefined): Promise<void> {
   const childId = child.id;
   const spawnRequestId = spawnRequestIdOf(child);
   // #648 — if a spawn_failed was already emitted for this request, this ready RETRACTS it: the agent
   // actually came up, so the earlier failure was a false negative. Emit a corrective recovery instead
   // of a plain ready notice so a coordinator that acted on the failure can reconcile.
   const recovered = spawnTerminalOf(spawnRequestId) === "agent.spawn_failed";
-  recordSpawnTerminal(spawnRequestId, "agent.ready");
 
   const workflowRunId = workflowRunIdOf(child);
-  emitRelayEvent({
-    type: "agent.ready",
-    source: "server",
-    subject: childId,
-    data: { agentId: childId, parent: spawner, provider: providerOf(child), label: child.label, spawnRequestId, ...(workflowRunId ? { workflowRunId } : {}) },
-  });
-  if (!spawner) return;
-  const parent = noticeRecipient(child, spawner);
-
-  if (recovered) {
-    emitRelayEvent({
-      type: "agent.spawn_recovered",
-      source: "server",
-      subject: childId,
-      data: { agentId: childId, parent: spawner, provider: providerOf(child), label: child.label, spawnRequestId, supersedes: "agent.spawn_failed" },
-    });
+  const readyEvent = () => {
+    emitRelayEvent({ type: "agent.ready", source: "server", subject: childId,
+      data: { agentId: childId, parent: spawner, provider: providerOf(child), label: child.label, spawnRequestId, ...(workflowRunId ? { workflowRunId } : {}) } });
+    if (recovered && spawner) emitRelayEvent({ type: "agent.spawn_recovered", source: "server", subject: childId,
+      data: { agentId: childId, parent: spawner, provider: providerOf(child), label: child.label, spawnRequestId, supersedes: "agent.spawn_failed" } });
+  };
+  const slot = { child, kind: "agent.ready" };
+  if (!spawner) {
+    const created = await routeAgentNotice(slot);
+    recordSpawnTerminal(spawnRequestId, "agent.ready");
+    if (created) readyEvent();
+    return;
   }
-
+  const parent = noticeRecipient(child, spawner);
   if (recovered) {
     // A correction must always reach a parent that got the (false) failure — gate only on the global
     // switch, NOT the agentReady sub-toggle, so the retraction lands even if ready pushes are off.
-    routeNotification({
+    const created = await routeAgentNotice(slot, {
       type: "agent.spawn_recovered",
       scope: { agentId: childId, parent },
       recipients: [parent],
@@ -186,9 +192,11 @@ function announceReady(child: AgentCard, spawner: string | undefined): void {
         replyExpected: false,
       },
     });
+    recordSpawnTerminal(spawnRequestId, "agent.ready");
+    if (created) readyEvent();
     return;
   }
-  routeNotification({
+  const created = await routeAgentNotice(slot, {
     type: "agent.ready",
     scope: { agentId: childId, parent },
     recipients: [parent],
@@ -199,7 +207,8 @@ function announceReady(child: AgentCard, spawner: string | undefined): void {
       replyExpected: false,
     },
   });
-  stampChildLifecycleSignal(parent, child);
+  recordSpawnTerminal(spawnRequestId, "agent.ready");
+  if (created) { readyEvent(); stampChildLifecycleSignal(parent, child); }
 }
 
 /**
@@ -209,16 +218,20 @@ function announceReady(child: AgentCard, spawner: string | undefined): void {
  * No-op for non-spawned agents.
  * `reason` is the offline cause (e.g. "heartbeat lost", "shutdown").
  */
-export function notifyAgentOffline(childId: string, reason: string, diagnosis?: AgentDeathDiagnosis): void {
-  requestAgentExitCleanup(childId);
+export async function notifyAgentOffline(childId: string, reason: string, diagnosis?: AgentDeathDiagnosis): Promise<void> {
+  return serializeSpawnNotice(spawnQueueKey(childId), () => notifyAgentOfflineBody(childId, reason, diagnosis));
+}
+
+async function notifyAgentOfflineBody(childId: string, reason: string, diagnosis?: AgentDeathDiagnosis): Promise<void> {
+  (await requestAgentExitCleanup(childId));
   const child = getAgent(childId);
   const parent = child?.spawnedBy;
   if (!child) return;
   if (!parent) {
     // A workflow step agent with no spawner records its exit on its run (#3160); nobody else is told.
     if (workflowRunIdOf(child) && everReady(child)) {
-      clearAgentNotice(child, "agent.ready");
-      notifyAgentExit(child, reason, diagnosis);
+      await clearAgentNoticeAsync(child, "agent.ready");
+      await notifyAgentExit(child, reason, diagnosis);
     }
     return;
   }
@@ -228,38 +241,32 @@ export function notifyAgentOffline(childId: string, reason: string, diagnosis?:
   // later signal (relay_workspace_ready, task→done) is coming from a process that no longer exists.
   // Idempotent (flushWorkFinalReports no-ops once the ring is empty), so a redundant call from a
   // second offline classification of the same agent is harmless.
-  markAgentWorkFinal(childId, "edge-fallback");
+  (await markAgentWorkFinal(childId, "edge-fallback"));
   // Classify from the durable readiness stamp; re-arm this generation's ready push for a return.
   const wasReady = everReady(child);
-  clearAgentNotice(child, "agent.ready");
+  await clearAgentNoticeAsync(child, "agent.ready");
   // #636 — persist the post-mortem keyed by agentId so the WHY survives the reaper, regardless of
   // whether the parent push is enabled. Recorded once per terminal-event emission.
-  if (diagnosis) recordCrashReport(crashReportFor(child, reason, diagnosis));
+  if (diagnosis) await recordCrashReportAsync(crashReportFor(child, reason, diagnosis));
   if (hasAgentExitNotice(child)) return;
 
   // #645 — persist a terminal marker for ANY offline terminus (clean exit or spawn-fail) keyed by
   // agentId so it outlives the reaper. The #634 watchdog reads this to skip a benign shutdown; it
   // must fire ONLY on a genuine silent death that emitted no terminal event at all.
-  recordTerminalEvent({ agentId: childId, reason, kind: wasReady ? "agent.exited" : "agent.spawn_failed", epoch: child.epoch, createdAt: Date.now() });
+  await recordTerminalEventAsync({ agentId: childId, reason, kind: wasReady ? "agent.exited" : "agent.spawn_failed", epoch: child.epoch, createdAt: Date.now() });
 
   if (wasReady) {
-    notifyAgentExit(child, reason, diagnosis);
+    await notifyAgentExit(child, reason, diagnosis);
     return;
   }
 
-  recordAgentNoticeOnce(child, () => {
+
     const recipient = noticeRecipient(child, parent);
     // #648 — record the terminal outcome so a (defensive) later ready for the same request is detected
     // as a recovery and corrected, keeping the one-terminal-per-spawn invariant across both fail paths.
     const spawnRequestId = spawnRequestIdOf(child);
-    if (!tryRecordSpawnFailed(spawnRequestId)) return;
-    emitRelayEvent({
-      type: "agent.spawn_failed",
-      source: "server",
-      subject: childId,
-      data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId, neverReady: true, ...(diagnosis ? { diagnosis } : {}) },
-    });
-    routeNotification({
+    if (spawnTerminalOf(spawnRequestId)) return;
+    const created = await routeAgentNotice({ child, kind: "agent.spawn_failed" }, {
       type: "agent.spawn_failed",
       scope: { agentId: childId, parent: recipient },
       recipients: [recipient],
@@ -274,7 +281,15 @@ export function notifyAgentOffline(childId: string, reason: string, diagnosis?:
         replyExpected: false,
       },
     });
-  }, "agent.spawn_failed");
+    recordSpawnTerminal(spawnRequestId, "agent.spawn_failed");
+    if (created) {
+    emitRelayEvent({
+      type: "agent.spawn_failed",
+      source: "server",
+      subject: childId,
+      data: { agentId: childId, parent, reason, provider: providerOf(child), spawnRequestId, neverReady: true, ...(diagnosis ? { diagnosis } : {}) },
+    });
+    }
 }
 
 /**
@@ -286,21 +301,19 @@ export function notifyAgentOffline(childId: string, reason: string, diagnosis?:
  * the subsequent agent.ready / agent.spawn_failed — no separate "admitted" event needed. Non-terminal:
  * it deliberately does NOT touch the one-terminal-per-spawn guard.
  */
-export function notifyAgentSpawnQueued(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): void {
+export async function notifyAgentSpawnQueued(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): Promise<void> {
+  return serializeSpawnNotice(input.spawnRequestId ?? `parent:${input.parent}`, () => notifyAgentSpawnQueuedBody(input));
+}
+
+async function notifyAgentSpawnQueuedBody(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): Promise<void> {
   const dedupeKey = input.spawnRequestId ?? `parent:${input.parent}`;
   if (spawnQueuedNotified.has(dedupeKey)) return;
   // A queued spawn whose terminal outcome already landed (a fast admit→ready, or a fail) must not now
   // emit a stale "queued" notice out of order. Ready/failed is authoritative; suppress a late queue.
   if (spawnTerminalOf(input.spawnRequestId)) return;
-  spawnQueuedNotified.add(dedupeKey);
-  emitRelayEvent({
-    type: "agent.spawn_queued",
-    source: "server",
-    subject: input.spawnRequestId ?? input.parent,
-    data: { parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
-  });
+
   const recipient = spawnerRecipient(input.parent, input.spawnRequestId);
-  routeNotification({
+  await routeNotification({
     type: "agent.spawn_queued",
     scope: { parent: recipient },
     recipients: [recipient],
@@ -314,6 +327,13 @@ export function notifyAgentSpawnQueued(input: { parent: string; spawnRequestId?:
       replyExpected: false,
     },
   });
+  spawnQueuedNotified.add(dedupeKey);
+  emitRelayEvent({
+    type: "agent.spawn_queued",
+    source: "server",
+    subject: input.spawnRequestId ?? input.parent,
+    data: { parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
+  });
 }
 
 /**
@@ -321,18 +341,17 @@ export function notifyAgentSpawnQueued(input: { parent: string; spawnRequestId?:
  * (provider unavailable, bad cwd, launch error) before any child agent registered. Routes directly
  * to the spawning parent threaded on the command, since there is no child agent record to resolve.
  */
-export function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): void {
+export async function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): Promise<void> {
+  return serializeSpawnNotice(input.spawnRequestId ?? `parent:${input.parent}`, () => notifyAgentSpawnFailedBody(input));
+}
+
+async function notifyAgentSpawnFailedBody(input: { parent: string; spawnRequestId?: string; provider?: string; reason: string }): Promise<void> {
   // #648/#864 — if the spawn already reached any terminal outcome, a later command-failure report
   // for the same request is stale or duplicate. Ready is authoritative; failed is already reported.
-  if (!tryRecordSpawnFailed(input.spawnRequestId)) return;
-  emitRelayEvent({
-    type: "agent.spawn_failed",
-    source: "server",
-    subject: input.spawnRequestId ?? input.parent,
-    data: { parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
-  });
+  if (spawnTerminalOf(input.spawnRequestId)) return;
+
   const recipient = spawnerRecipient(input.parent, input.spawnRequestId);
-  routeNotification({
+  await routeNotification({
     type: "agent.spawn_failed",
     scope: { parent: recipient },
     recipients: [recipient],
@@ -346,6 +365,13 @@ export function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?:
       replyExpected: false,
     },
   });
+  recordSpawnTerminal(input.spawnRequestId, "agent.spawn_failed");
+  emitRelayEvent({
+    type: "agent.spawn_failed",
+    source: "server",
+    subject: input.spawnRequestId ?? input.parent,
+    data: { parent: input.parent, spawnRequestId: input.spawnRequestId, provider: input.provider, reason: input.reason },
+  });
 }
 
 /**
@@ -353,7 +379,7 @@ export function notifyAgentSpawnFailed(input: { parent: string; spawnRequestId?:
  * deliberately non-terminal: the runner can still register after the watchdog fires, so callers
  * must not retry or infer that a new spawn is safe.
  */
-export function notifyAgentSpawnUnconfirmed(input: { parent: string; spawnRequestId: string; provider?: string; reason: string; phase: "dispatch_unacknowledged" | "registration_unconfirmed" }): void {
+export async function notifyAgentSpawnUnconfirmed(input: { parent: string; spawnRequestId: string; provider?: string; reason: string; phase: "dispatch_unacknowledged" | "registration_unconfirmed" }): Promise<void> {
   emitRelayEvent({
     type: "agent.spawn_unconfirmed",
     source: "server",
@@ -361,7 +387,7 @@ export function notifyAgentSpawnUnconfirmed(input: { parent: string; spawnReques
     data: input,
   });
   const recipient = spawnerRecipient(input.parent, input.spawnRequestId);
-  routeNotification({
+  await routeNotification({
     type: "agent.spawn_unconfirmed",
     scope: { parent: recipient },
     recipients: [recipient],
@@ -392,24 +418,18 @@ export function notifyAgentRegistered(agent: AgentCard): void {
 }
 
 /** Emit one parent exit notice per generation, including automatic reaps before the offline report. */
-export function notifyAgentExit(child: AgentCard, reason: string, diagnosis?: AgentDeathDiagnosis, context: { workspaceId?: string; workspaceStatus?: string } = {}): void {
+export async function notifyAgentExit(child: AgentCard, reason: string, diagnosis?: AgentDeathDiagnosis, context: { workspaceId?: string; workspaceStatus?: string } = {}): Promise<void> {
   const parent = child.spawnedBy;
   const workflowRunId = workflowRunIdOf(child);
-  recordAgentNoticeOnce(child, () => {
-    emitRelayEvent({
-      type: "agent.exited",
-      source: "server",
-      subject: child.id,
-      data: { ...context, agentId: child.id, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child), ...(workflowRunId ? { workflowRunId } : {}), ...(diagnosis ? { diagnosis } : {}) },
-    });
+
     // The parent already got a shutdown command receipt for requesting this exit, so the
     // exit itself is expected — including a non-zero code from a force-reap kill. Keep the
     // terminal event for timeline consumers; only skip the parent wake-up. An exit nobody
     // requested (no shutdown command from the parent) still wakes: crashes and spawn failures
     // keep their notice.
-    if (parent && parentRequestedShutdown(child.id, spawnRequestIdOf(child) ?? "", parent, Date.now() - 5 * 60_000)) return;
+    const suppressed = parent && parentRequestedShutdown(child.id, spawnRequestIdOf(child) ?? "", parent, Date.now() - 5 * 60_000);
     const recipient = parent ? noticeRecipient(child, parent) : undefined;
-    routeNotification({
+    const created = await routeAgentNotice({ child, kind: "agent.exited" }, suppressed ? undefined : {
       type: "agent.exited",
       scope: { agentId: child.id, parent: recipient },
       recipients: [recipient],
@@ -424,5 +444,12 @@ export function notifyAgentExit(child: AgentCard, reason: string, diagnosis?: Ag
         replyExpected: false,
       },
     });
-  });
+    if (created) {
+    emitRelayEvent({
+      type: "agent.exited",
+      source: "server",
+      subject: child.id,
+      data: { ...context, agentId: child.id, parent, reason, provider: providerOf(child), spawnRequestId: spawnRequestIdOf(child), ...(workflowRunId ? { workflowRunId } : {}), ...(diagnosis ? { diagnosis } : {}) },
+    });
+    }
 }

package/src/agent-ref.ts

@@ -160,8 +160,9 @@ export function resolveAgentRef(ref: string, agents: AgentCard[], opts: ResolveO
   return { status: "not_found", offlineMatches: matches };
 }
 
-export function targetMatchesAgent(target: string, agentId: string, agent?: AgentCard | null): boolean {
-  if (!agent) return false;
+export function targetMatchesAgent(target: string | null | undefined, agentId: string, agent?: AgentCard | null): boolean {
+  // Untargeted task events have no agent recipient, on live streams or replay (#3801).
+  if (!agent || typeof target !== "string" || !target) return false;
   if (target.startsWith("coordinator:")) return resolveTeamCoordinatorAgentId(target.slice(12)) === agentId;
   return targetMatchesAgentIdentity(target, {
     id: agentId,

package/src/agent-status-events.ts

@@ -1,18 +1,41 @@
-// The ONE agent.status emitter (#3606): every seam lands here, so "unchanged card → no event" holds on all.
-// A card equal to the last one emitted, ignoring lastSeen and statusSeq, is dropped before persistence:
-// liveness ticks only moved those two (39% of prod agent.status events), the dashboard reads heartbeat
-// age from its 5–15 s roster poll, and no consumer orders by statusSeq.
+// The ONE agent.status emitter (#3606): every seam lands here. A card unchanged but for lastSeen and
+// statusSeq is dropped (the dashboard reads heartbeat age from its roster poll; nothing orders by
+// statusSeq). #3614 — a change only in liveness telemetry (timestamps, ages, gauges the next tick
+// supersedes) goes out live-only, with no outbox row; replay keeps every real state change.
 
 import { getAgentRuntimeAsync } from "./db";
 import { projectAgentStatusData } from "./agent-card-projection";
-import { emitRelayEvent } from "./events";
+import { emitEphemeralRelayEvent, emitRelayEvent } from "./events";
 import { emitNotificationCreated, notificationForAgentStatus } from "./dashboard-notifications";
 
-const lastEmitted = new Map<string, number | bigint>();
+type Fingerprint = number | bigint;
 
-function cardFingerprint(data: Record<string, unknown>): number | bigint {
-  const { lastSeen: _lastSeen, statusSeq: _statusSeq, ...card } = data;
-  return Bun.hash(JSON.stringify(card));
+const UNEMITTED_KEYS = [["lastSeen"], ["statusSeq"]] as const;
+const LIVENESS_KEYS = [
+  ...UNEMITTED_KEYS,
+  ["context", "lastUpdatedAt"], ["context", "tokensUsed"], ["context", "utilization"],
+  ["meta", "unreportedTokenUsage"], ["meta", "lastProviderEventAt"],
+  ["meta", "transport", "lastServerFrameAt"], ["meta", "transport", "lastHeartbeatAckAt"],
+  ["meta", "liveness", "transportLiveAt"], ["meta", "liveness", "lastProgressAt"],
+  ["meta", "busyHealth", "activeWorkAgeMs"], ["meta", "busyHealth", "staleForMs"], ["meta", "busyHealth", "lastProgressAt"],
+  ["meta", "busyHealth", "transportLiveAt"], ["meta", "busyHealth", "transportStaleForMs"],
+] as const;
+
+const lastEmitted = new Map<string, { card: Fingerprint; durable: Fingerprint }>();
+
+/** Hash of the card without `paths`; copies only the objects on a stripped path. */
+function fingerprint(data: Record<string, unknown>, paths: ReadonlyArray<readonly string[]>): Fingerprint {
+  const root = { ...data };
+  for (const path of paths) {
+    let parent: Record<string, unknown> = root;
+    for (const key of path.slice(0, -1)) {
+      const child = parent[key];
+      if (!child || typeof child !== "object" || Array.isArray(child)) { parent = {}; break; }
+      parent = parent[key] = { ...child as Record<string, unknown> };
+    }
+    delete parent[path[path.length - 1]!];
+  }
+  return Bun.hash(JSON.stringify(root));
 }
 
 export async function emitAgentStatus(agentId: string): Promise<void> {
@@ -20,15 +43,21 @@ export async function emitAgentStatus(agentId: string): Promise<void> {
   // Enrich with the branch-state badge fields (#236) and the resolved issueRepo (#533) so
   // the dashboard's live agent updates carry the same projection as GET /api/agents (#560).
   const data = await projectAgentStatusData(agentId, agent) as unknown as Record<string, unknown>;
-  const fingerprint = cardFingerprint(data);
-  if (lastEmitted.get(agentId) === fingerprint) return;
-  lastEmitted.set(agentId, fingerprint);
+  const next = { card: fingerprint(data, UNEMITTED_KEYS), durable: fingerprint(data, LIVENESS_KEYS) };
+  const previous = lastEmitted.get(agentId);
+  if (previous?.card === next.card) return;
+  lastEmitted.set(agentId, next);
+  const event = { type: "agent.status", source: "server", subject: agentId, data };
+  if (previous?.durable === next.durable) {
+    emitEphemeralRelayEvent(event);
+    return;
+  }
   try {
     // Awaited: a bus registration must not install its socket before its own status event is durable.
-    await emitRelayEvent({ type: "agent.status", source: "server", subject: agentId, data });
+    await emitRelayEvent(event);
   } catch (error) {
     // Never let an append that did not happen suppress the next identical card.
-    if (lastEmitted.get(agentId) === fingerprint) lastEmitted.delete(agentId);
+    if (lastEmitted.get(agentId) === next) lastEmitted.delete(agentId);
     throw error;
   }
   const notification = agent ? notificationForAgentStatus(agent) : undefined;

package/src/auth/login-link.ts

@@ -0,0 +1,35 @@
+// One-time dashboard login links (#2680): `humwick init` hands the first user a signed-in dashboard
+// without an env-file edit or a copied admin token. A link carries a short-lived token whose only
+// scope matches no route, so it cannot act as an access token; redeeming revokes it (single use)
+// and mints a normal user session.
+import { userSinkId, isHumanAgentId, userIdFromAddress, type User } from "@humwick/sdk";
+import { createTokenAsync, revokeTokenAsync } from "../token-db-write.ts";
+import { verifyComponentToken } from "../security.ts";
+import { getUser } from "../db/users.ts";
+import { USER_TOKEN_ROLE } from "./admin-routes.ts";
+
+export const LOGIN_LINK_SCOPE = "auth:login-link";
+export const LOGIN_LINK_TTL_SECONDS = 15 * 60;
+
+/** Mint a single-use login link for `user`. The path opens the dashboard signed in as them. */
+export async function mintLoginLink(user: User, createdBy: string): Promise<{ path: string; expiresAt: number }> {
+  const { token, record } = await createTokenAsync({
+    sub: userSinkId(user.id),
+    role: USER_TOKEN_ROLE,
+    scope: [LOGIN_LINK_SCOPE],
+    ttlSeconds: LOGIN_LINK_TTL_SECONDS,
+    createdBy,
+  });
+  return { path: `/login/${token}`, expiresAt: record.expiresAt! };
+}
+
+/** The active user a valid, unused login link names, consuming the link; null otherwise. */
+export async function redeemLoginLink(code: string): Promise<User | null> {
+  const payload = verifyComponentToken(code);
+  if (!payload?.jti || !payload.scope.includes(LOGIN_LINK_SCOPE) || !isHumanAgentId(payload.sub)) return null;
+  const userId = userIdFromAddress(payload.sub);
+  const user = userId ? getUser(userId) : undefined;
+  if (!user || user.status !== "active") return null;
+  // The revoke is the single-use gate: only the first redeemer flips the row.
+  return (await revokeTokenAsync(payload.jti, "rotation")) ? user : null;
+}

package/src/auth/password.ts

@@ -1,9 +1,10 @@
+import { createAuthIdentityAsync } from "../db/runtime-tail-async";
 // Password authentication provider (#389). The only built-in provider in Phase 1. Secrets are
 // hashed with scrypt (node:crypto — no dependency) and compared with `timingSafeEqual`, the same
 // constant-time primitive the token layer uses. The hash is stored in `auth_identities.secret_hash`
 // keyed by (provider="password", provider_subject=<username>).
 import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
-import { createAuthIdentity, getAuthIdentity, type AuthIdentity } from "../db/auth-identities.ts";
+import { getAuthIdentity, type AuthIdentity } from "../db/auth-identities.ts";
 import { isRecord } from "@humwick/sdk";
 import type { AuthProvider, AuthVerifyResult } from "./provider.ts";
 
@@ -98,13 +99,13 @@ export async function createPasswordIdentity(input: {
   password: string;
   metadata?: Record<string, unknown>;
 }): Promise<AuthIdentity> {
-  return createAuthIdentity({
+  return (await createAuthIdentityAsync({
     userId: input.userId,
     provider: PASSWORD_PROVIDER_ID,
     providerSubject: input.username,
     secretHash: await hashPassword(input.password),
     metadata: input.metadata,
-  });
+  }));
 }
 
 /** Parse `{ username, password }` from a login request body. */

package/src/auth/session-refresh.ts

@@ -31,7 +31,7 @@ export async function refreshUserSession(refreshToken: string, nowMs = Date.now(
       expiresAt: Math.min(nowMs + REFRESH_GRACE_MS, (resolved.payload.exp ?? Infinity) * 1000),
       result: (async () => {
         if (!(await revokeTokenAsync(jti, "rotation"))) return null;
-        const session = mintUserSession(resolved.user, resolved.payload.constraints?.sessionId);
+        const session = (await mintUserSession(resolved.user, resolved.payload.constraints?.sessionId));
         return { accessJti: session.accessJti, refreshJti: session.refreshJti };
       })(),
     };

package/src/auth/session.test-fixture.ts

@@ -4,7 +4,7 @@ import { mintUserSession } from "./session.ts";
 
 /** An `authorization` header carrying a fresh access token for `userId`. An unknown id models a
  *  session whose user no longer exists (it carries operator scopes). */
-export function sessionAuthHeader(userId: string): Record<string, string> {
+export async function sessionAuthHeader(userId: string): Promise<Record<string, string>> {
   const user = getUser(userId) ?? { id: userId, handle: userId, displayName: userId, role: "operator" as const, status: "active" as const, tenantId: "default", avatarArtifactId: null, avatarUrl: null, createdAt: 0, updatedAt: 0 };
-  return { authorization: `Bearer ${mintUserSession(user).accessToken}` };
+  return { authorization: `Bearer ${(await mintUserSession(user)).accessToken}` };
 }

package/src/auth/session.ts

@@ -5,8 +5,8 @@
 // `role` ("user"), so no machine-token path branches on it.
 import { userSinkId, userIdFromAddress, isHumanAgentId, type User, type UserRole } from "@humwick/sdk";
 import { randomUUID } from "node:crypto";
-import { revokeTokenAsync } from "../token-db-write.ts";
-import { createToken, liveTokenJtisForSession } from "../token-db.ts";
+import { createTokenAsync, revokeTokenAsync } from "../token-db-write.ts";
+import { liveTokenJtisForSession } from "../token-db.ts";
 import { verifyComponentToken } from "../security.ts";
 import { getUser } from "../db/users.ts";
 import { scopesForRole } from "./role-scopes";
@@ -50,25 +50,25 @@ export interface MintedSession {
  * SaaS seam (identity-only — enforces nothing). Both tokens share the `user:<id>` sub so a single
  * "sign out everywhere" revoke (by sub) kills the whole session family.
  */
-export function mintUserSession(user: User, sessionId: string = randomUUID()): MintedSession {
+export async function mintUserSession(user: User, sessionId: string = randomUUID()): Promise<MintedSession> {
   const sub = userSinkId(user.id);
   const constraints = { sessionId, ...(user.tenantId ? { tenantId: user.tenantId } : {}) };
-  const access = createToken({
+  const access = (await createTokenAsync({
     sub,
     role: USER_TOKEN_ROLE,
     scope: scopesForUserRole(user.role),
     constraints,
     ttlSeconds: ACCESS_TTL_SECONDS,
     createdBy: `auth:login:${user.id}`,
-  });
-  const refresh = createToken({
+  }));
+  const refresh = (await createTokenAsync({
     sub,
     role: USER_TOKEN_ROLE,
     scope: [REFRESH_SCOPE],
     constraints,
     ttlSeconds: REFRESH_TTL_SECONDS,
     createdBy: `auth:refresh:${user.id}`,
-  });
+  }));
   return {
     accessToken: access.token,
     refreshToken: refresh.token,