@humwick/server 0.130.0 → 0.130.2

package/src/runtime-tokens.ts

@@ -2,8 +2,9 @@ import { registryToolName } from "@humwick/sdk";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { deriveRunnerGrant, successorGrant } from "./runtime-grant";
 export { runnerSpawnGrantForAgent } from "./runtime-grant";
-import { TOKEN_RECOVERY_WINDOW_SECONDS, createToken, getToken, getTokenProfile, type CreateTokenInput } from "./token-db";
-import { handoffTokenAsync } from "./token-db-write";
+import { TOKEN_RECOVERY_WINDOW_SECONDS, createToken, getToken, getTokenProfile, type CreateTokenInput, type HandoffTokenInput, type TokenHandoff } from "./token-db";
+import { runnerTokenMintLimit } from "./runner-token-mint-limit";
+import { createRunnerTokenAsync, createTokenAsync, handoffTokenAsync } from "./token-db-write";
 import { FLEET_SCOPE, verifyComponentTokenAllowExpired } from "./security";
 import { getAgentProfile, hostPinForProfile, spawnGrantForProfile, toolGroupsForProfile } from "./config-store";
 import { toolAllowlistForRunner } from "./mcp-tool-allowlist";
@@ -38,6 +39,22 @@ interface RuntimeTokenResult {
   record: TokenRecord;
 }
 
+/** A refused successor mint; `retryAfterSeconds` marks a per-subject rate limit (HTTP 429). */
+export type RunnerTokenMintRefusal = { error: string; retryAfterSeconds?: number };
+
+/** #3775 — the one way a runner token's successor is minted: within the subject's mint limit, charged per new token. */
+export async function handoffRunnerTokenAsync(sub: string, input: HandoffTokenInput): Promise<TokenHandoff | null | { retryAfterSeconds: number }> {
+  const retryAfterSeconds = runnerTokenMintLimit.refusal(sub);
+  if (retryAfterSeconds !== undefined) return { retryAfterSeconds };
+  const handoff = await handoffTokenAsync(input);
+  if (handoff && !handoff.replayed) runnerTokenMintLimit.charge(sub);
+  return handoff;
+}
+
+function mintRateLimited(handoff: object | null): handoff is { retryAfterSeconds: number } {
+  return handoff !== null && "retryAfterSeconds" in handoff;
+}
+
 function runnerTokenOwnedByOrchestratorHost(
   constraints: NonNullable<ReturnType<typeof verifyComponentTokenAllowExpired>>["constraints"],
   orchestratorId: string,
@@ -68,7 +85,7 @@ export async function reissueRunnerRuntimeToken(input: {
   expiredToken: string;
   orchestratorId: string;
   createdBy?: string;
-}): Promise<RuntimeTokenResult | { error: string }> {
+}): Promise<RuntimeTokenResult | RunnerTokenMintRefusal> {
   const payload = verifyComponentTokenAllowExpired(input.expiredToken, { allowStaleRevoked: true });
   // #3133 — recovery hands off from the token's record, which holds its standing; a token without one recovers nothing.
   if (!payload?.jti) return { error: "invalid or revoked runner token" };
@@ -95,7 +112,8 @@ export async function reissueRunnerRuntimeToken(input: {
     constraints: payload.constraints,
     createdBy: input.createdBy ?? `remint:${payload.jti}`,
   };
-  const handoff = await handoffTokenAsync({ jti: payload.jti, successor, recoverExpiredWithinSeconds: TOKEN_RECOVERY_WINDOW_SECONDS, createdBy: successor.createdBy });
+  const handoff = await handoffRunnerTokenAsync(payload.sub, { jti: payload.jti, successor, recoverExpiredWithinSeconds: TOKEN_RECOVERY_WINDOW_SECONDS, createdBy: successor.createdBy });
+  if (mintRateLimited(handoff)) return { error: "runner token mint rate limited", retryAfterSeconds: handoff.retryAfterSeconds };
   return handoff ?? { error: "invalid or revoked runner token" };
 }
 
@@ -122,7 +140,7 @@ function runnerGrantKey(scope: readonly string[] | undefined, constraints: Token
  * (current profile, lineage ceiling) and the presented token's launch identity. An identical grant is left
  * alone; otherwise the token is handed off like a renewal, so a lost response is recovered by a retry.
  */
-export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy: string): Promise<RunnerTokenRemint | { unchanged: true; jti: string } | { error: string }> {
+export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy: string): Promise<RunnerTokenRemint | { unchanged: true; jti: string } | RunnerTokenMintRefusal> {
   const previous = auth.jti ? getToken(auth.jti) : null;
   const c = auth.constraints ?? {};
   const agentId = c.agents?.length === 1 ? c.agents[0] : undefined;
@@ -149,7 +167,8 @@ export async function remintRunnerRuntimeToken(auth: ComponentToken, createdBy:
   });
   if (token.constraints?.orchestrators?.includes("")) return { error: "the agent's host is unknown, so its host pin cannot be kept" };
   if (runnerGrantKey(previous.scope, previous.constraints) === runnerGrantKey(token.scope, token.constraints)) return { unchanged: true, jti: previous.jti };
-  const handoff = await handoffTokenAsync({ jti: previous.jti, allowedProfileIds: ["provider-agent"], successor: token, createdBy });
+  const handoff = await handoffRunnerTokenAsync(auth.sub, { jti: previous.jti, allowedProfileIds: ["provider-agent"], successor: token, createdBy });
+  if (mintRateLimited(handoff)) return { error: "runner token mint rate limited", retryAfterSeconds: handoff.retryAfterSeconds };
   if (!handoff) return { error: "the presented token was already rotated" };
   const { record } = handoff;
   return {
@@ -171,7 +190,16 @@ export function issueOrchestratorRuntimeToken(input: {
   baseDir: string;
   createdBy?: string;
 }): RuntimeTokenResult {
-  return createToken({
+  return createToken(orchestratorTokenSpec(input));
+}
+
+/** #1870 S6c — the mint on the writer thread, for the async routes. */
+export function issueOrchestratorRuntimeTokenAsync(input: Parameters<typeof issueOrchestratorRuntimeToken>[0]): Promise<RuntimeTokenResult> {
+  return createTokenAsync(orchestratorTokenSpec(input));
+}
+
+function orchestratorTokenSpec(input: Parameters<typeof issueOrchestratorRuntimeToken>[0]): CreateTokenInput {
+  return {
     profileId: "orchestrator-host",
     sub: `orchestrator:${input.orchestratorId}`,
     role: "orchestrator",
@@ -184,7 +212,7 @@ export function issueOrchestratorRuntimeToken(input: {
       terminalWrite: true,
     },
     createdBy: input.createdBy ?? "runtime",
-  });
+  };
 }
 
 export interface RunnerRuntimeTokenInput {
@@ -297,6 +325,7 @@ function runnerTokenSpec(input: RunnerRuntimeTokenInput): { token: CreateTokenIn
     : { kind: "root", ...(authority.kind === "delegated" ? { launcherScopes: authority.callerScopes } : {}), ...(profile ? { profile } : {}) } };
 }
 
+/** Sync twin for in-process tests; every runtime launch path mints through the writer op below. */
 export function issueRunnerRuntimeToken(input: RunnerRuntimeTokenInput): RuntimeTokenResult {
   const spec = runnerTokenSpec(input);
   const issued = createToken(spec.token);
@@ -305,6 +334,11 @@ export function issueRunnerRuntimeToken(input: RunnerRuntimeTokenInput): Runtime
   return issued;
 }
 
+export function issueRunnerRuntimeTokenAsync(input: RunnerRuntimeTokenInput): Promise<RuntimeTokenResult> {
+  const spec = runnerTokenSpec(input);
+  return createRunnerTokenAsync(spec.token, spec.launchFact ? { agentId: input.agentId, fact: spec.launchFact } : undefined);
+}
+
 export function issueInteractiveRunnerRuntimeToken(input: {
   provider: string;
   cwd: string;
@@ -384,7 +418,14 @@ export function issueIntegrationRuntimeToken(input: {
 }
 
 export function runnerRuntimeTokenEnv(input: RunnerRuntimeTokenInput): Record<string, string> {
-  const issued = issueRunnerRuntimeToken(input);
+  return runnerTokenEnv(input, issueRunnerRuntimeToken(input));
+}
+
+export async function runnerRuntimeTokenEnvAsync(input: RunnerRuntimeTokenInput): Promise<Record<string, string>> {
+  return runnerTokenEnv(input, await issueRunnerRuntimeTokenAsync(input));
+}
+
+function runnerTokenEnv(input: RunnerRuntimeTokenInput, issued: RuntimeTokenResult): Record<string, string> {
   return writeChildEnv({}, {
     AGENT_RELAY_TOKEN: issued.token,
     AGENT_RELAY_TOKEN_JTI: issued.record.jti,

package/src/security.ts

@@ -233,6 +233,8 @@ export function isOrchestratorRegistrationAuthorized(req: Request): boolean {
 }
 
 const SHARED_UI_ROUTE_SCOPES: Record<string, string> = {
+  "/api/orchestrators/bootstrap": "token:write",
+  "/api/orchestrators/bootstrap/exchange": "token:write",
   "/api/claude-api-budget/summary": "agent:read",
   "/api/claude-api-budget": "system:admin",
   "/api/stats": "stats:read",
@@ -252,6 +254,15 @@ function sharedUiRouteScope(pathname: string, method: string): string | undefine
   if (/^\/api\/api-budgets\/[^/]+\/summary$/.test(pathname)) return "agent:read";
   if (/^\/api\/api-budgets\/[^/]+$/.test(pathname)) return "system:admin";
   if (/^\/api\/shipping\/incidents\/[^/]+\/abandon$/.test(pathname)) return "command:write";
+  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
+  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
+  if (pathname === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
+  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
+  if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
+  if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
+  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   return Object.hasOwn(SHARED_UI_ROUTE_SCOPES, pathname) ? SHARED_UI_ROUTE_SCOPES[pathname] : undefined;
 }
 
@@ -266,8 +277,6 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/route") return "agent:read";
   if (pathname === "/api/notifications/preview") return "notifications:read";
   if (pathname === "/api/mcp") return "mcp:use";
-  if (pathname === "/api/orchestrators/bootstrap/exchange") return "token:write";
-  if (pathname === "/api/orchestrators/bootstrap") return "token:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/logs\//)) return "logs:read";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\/[^/]+\/input$/)) return "terminal:write";
   if (pathname.match(/^\/api\/orchestrators\/[^/]+\/terminal\//)) return "terminal:read";
@@ -323,16 +332,8 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.match(/^\/api\/provider-quotas\/[^/]+\/reset-fired$/)) return "quota:write";
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname === "/api/routing-policy") return method === "GET" ? "agent:read" : "settings:write:routing";
-  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) return method === "GET" ? "agent:read" : "system:admin";
-  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
-  if (pathname === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
-  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
-  if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
-  if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
+  if (/^\/api\/projects\/[^/]+\/profile-instructions(?:\/|$)/.test(pathname)) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
@@ -466,7 +467,6 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname === "/api/routing-policy") {
     return method === "GET" ? "agent:read" : "settings:write:routing";
   }
-  if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
   if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) {
     return method === "GET" ? "agent:read" : versionedPromptsEnabled() ? "agent:write" : "system:admin";
   }
@@ -477,16 +477,9 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/workflows")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command:write";
   if (pathname.startsWith("/api/plans")) return method === "GET" ? "plans:read" : "plans:write";
-  if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
-  if (pathname === "/api/decisions" && method === "POST") return "teams:write"; // #2914: filing = the relay_decision scope
-  if (pathname.startsWith("/api/decisions")) return method === "GET" ? "teams:read" : "message:send"; // #2885: answering = messaging the coordinator
-  if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
-  if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-activity")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-lifecycle")) return method === "GET" ? "issue:read" : "issue:write";
-  if (pathname.startsWith("/api/issue-refs")) return method === "GET" ? "issue:read" : "issue:write";
   // Fail-closed default returns system:admin, so this case is load-bearing: without it
   // every /api/projects call from a scoped component token would 403-blackhole (#405).
+  if (/^\/api\/projects\/[^/]+\/profile-instructions(?:\/|$)/.test(pathname)) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/projects")) return method === "GET" ? "project:read" : "project:write";
   // The Runner posts the #184 context-gathering signal here (source:"server") via its
   // provider token. Without this case the path fell through to the system:admin default

package/src/server-background.ts

@@ -19,6 +19,6 @@ export function startServerBackgroundJobs(): void {
     { name: "connectors", start: startConnectorStatusPoller },
     { name: "maintenance", start: startMaintenanceScheduler },
     { name: "steward-rekey-notices", start: async () => (await import("./workspace-rekey")).drainStewardRekeyNotices() },
-    { name: "deploy-notice", start: () => { if (!isEphemeralMode()) notifyCdDeployLive(); } },
+    { name: "deploy-notice", start: async () => { if (!isEphemeralMode()) await notifyCdDeployLive(); } },
   ]);
 }

package/src/server.ts

@@ -7,6 +7,8 @@ import { inviteLinkRedirect } from "./invite-link";
 import { claudeAppBoundary, CLAUDE_APP_PATH, isClaudeAppPath } from "./claude-app-auth";
 import { handleClaudeApp } from "./claude-app-gateway";
 import { handleClaudeAppOAuth } from "./claude-app/oauth-http";
+import { installTimerIngressSchema } from "./db/timer-ingress";
+import { beginMainWriteBootPhase, endMainWriteBootPhase } from "./db/main-connection-writes";
 import { markServerBound, timePostBindPhase } from "./post-bind-startup";
 import type { ServerWebSocket } from "bun";
 import { beginStartupPhase, enableStartupTiming, timeStartupPhase } from "./startup-timing";
@@ -24,7 +26,6 @@ import { reconcileAutomationRuns, runDueAutomationsAsync, type AutomationDispatc
 import { getLifecycleManager } from "./lifecycle-manager";
 import { reconcileStewardPolicyModels } from "./steward-policy-model-reconcile";
 import { getConfig, setConfig } from "./config-store";
-import { reconcileProviderModelSeed } from "./provider-model-seed";
 export { reconcileProviderModelSeed } from "./provider-model-seed";
 import { ensureEscalationChannelRegistered } from "./connectors";
 import { installNotificationSubscriptionRule } from "./notification-subscription-rules";
@@ -111,6 +112,7 @@ export async function startServer(): Promise<void> {
   startArtifactCheckoutLease();
 
   assertSafeNetworkConfig(HOST);
+  beginMainWriteBootPhase();
   timeStartupPhase("server.database", () => initDb(DB_PATH));
   // #1960 T2 — stand the gateway up EXPLICITLY here rather than leaving it to the lazy self-init
   // (`getGateway()` on first call, gateway.ts), which would race the rest of this boot sequence.
@@ -136,7 +138,6 @@ export async function startServer(): Promise<void> {
   installNotificationSubscriptionRule();
   startPlanLiveBindings();
   reconcileRelayVersion();
-  if (!isEphemeralMode()) reconcileProviderModelSeed();
   // Register the ntfy escalation channel row from persisted connector config BEFORE the
   // warning check, so a correctly-configured relay doesn't spuriously warn while the async
   // channels-host connect is still in flight (#1510).
@@ -174,7 +175,9 @@ export async function startServer(): Promise<void> {
     }, AUTOMATION_INTERVAL_MS);
   }
 
+  installTimerIngressSchema();
   finishServices();
+  endMainWriteBootPhase();
   timeStartupPhase("server.bind", () => Bun.serve<RelaySocketData>({
     port: PORT,
     hostname: HOST,

package/src/services/host-utilization.ts

@@ -11,10 +11,14 @@
 //   2. the §4.4 in-memory last-hour series, ONLY once the durable write landed, so the Monitor
 //      chart can never show a point the Fleet card cannot corroborate;
 //   3. #2822 — the one operator page a gate-capacity transition owes, decided by that same write.
+//   4. #3762 — the one low-disk page (ntfy + coordinator) a disk level change owes, same write.
 import type { HostDaemonSample, HostMachineSample } from "@humwick/sdk";
 import { recordHostUtilizationAsync } from "../db";
 import { recordHostUtilizationSample } from "../host/utilization-buffer";
 import { composeGateCapacityNotice, type GateCapacityAlert } from "../host/gate-capacity-alert";
+import { composeDiskNotice, type DiskAlert } from "../host/disk-alert";
+import { stewardFallbackTarget } from "../config";
+import { notifyTarget } from "../maintenance/events";
 import { notifyWorkspaceHumanEscalation } from "../workspace-human-escalation";
 
 export interface RecordHostUtilizationInput {
@@ -52,9 +56,28 @@ export async function recordHostUtilization(input: RecordHostUtilizationInput):
   }
   recordHostUtilizationSample(input.hostId, input.machine, input.now ?? Date.now());
   if (recorded?.gateAlert) notifyGateCapacity(input.hostId, recorded.hostLabel ?? input.hostId, recorded.gateAlert, input.now ?? Date.now());
+  if (recorded?.diskAlert) notifyDisk(input.hostId, recorded.hostLabel ?? input.hostId, recorded.diskAlert);
   return true;
 }
 
+/** Operator ntfy plus the steward/coordinator target — the same two recipients as the critical-job watchdog. */
+function notifyDisk(hostId: string, label: string, alert: DiskAlert): void {
+  const notice = composeDiskNotice(hostId, label, alert);
+  const payload = { ...alert, kind: `host-disk.${alert.kind}`, hostId };
+  const human = notifyWorkspaceHumanEscalation({
+    subject: notice.subject,
+    body: notice.body,
+    priority: notice.priority,
+    tags: ["agent-relay", "host-disk"],
+    source: "host-disk",
+    payload,
+    idempotencyKey: notice.idempotencyKey,
+  });
+  const target = stewardFallbackTarget();
+  const routed = target ? notifyTarget("maintenance.degraded", {}, target, notice.subject, notice.body, payload, notice.idempotencyKey) : null;
+  console.warn(`[relay] ${notice.subject}${human.accepted || routed ? "" : " — nobody was notified (no ntfy channel or steward target)"}`);
+}
+
 function notifyGateCapacity(hostId: string, label: string, alert: GateCapacityAlert, now: number): void {
   const notice = composeGateCapacityNotice(hostId, label, alert, now);
   const result = notifyWorkspaceHumanEscalation({

package/src/services/idle-epics.ts

@@ -3,8 +3,8 @@ import { isTerminalTaskStatus } from "./task-entity";
 import { errMessage } from "@humwick/sdk";
 import { coordinatedTeamIds } from "../db/coordinator-seat";
 import { teamEpicWork } from "../db/team-epics";
-import { clearIssueTrackerNotFound, issueTrackerNotFoundCount, recordIssueTrackerNotFound, getIssueHierarchy, putIssueHierarchy } from "../db/long-running-work";
-import { updateIssueRef } from "../db/issue-refs";
+import { issueTrackerNotFoundCount, getIssueHierarchy } from "../db/long-running-work";
+import { putIssueHierarchyAsync, recordIssueRefLiveStatusAsync, recordIssueTrackerNotFoundAsync } from "../db/issue-refs-async";
 import { resolveIssueTrackerAdapter } from "../issue-tracker";
 import { GitHubApiError } from "../issue-tracker/github";
 import { routeNotification } from "../notification-router";
@@ -41,14 +41,13 @@ export async function refreshTeamEpicHierarchy(teamId: string, signal?: AbortSig
       const live = await adapter.getStatus(issue);
       if (signal?.aborted) break;
       statusLoaded = true;
-      clearIssueTrackerNotFound(issue.id);
-      updateIssueRef(issue.id, { status: live.status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() });
+      await recordIssueRefLiveStatusAsync(issue.id, { status: live.status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() });
       if (live.status !== "open") continue;
       const children = adapter.listSubIssues ? await adapter.listSubIssues(issue) : await adapter.listOpenSubIssues?.(issue);
-      if (children) putIssueHierarchy(issue.id, children);
+      if (children) await putIssueHierarchyAsync(issue.id, children);
     } catch (error) {
       if (!statusLoaded && error instanceof GitHubApiError && error.statusCode === 404
-        && recordIssueTrackerNotFound(issue.id) >= 2) {
+        && await recordIssueTrackerNotFoundAsync(issue.id) >= 2) {
         reportUnresolvable(teamId, issue);
         continue;
       }

package/src/services/issue-lifecycle.ts

@@ -8,9 +8,9 @@ import { listEntitiesForIssue, listIssuesForEntity } from "../db/issue-associati
 import {
   getSuccessfulIssueLifecycleAction,
   listSuccessfulCloseActionsForCommit,
-  upsertIssueLifecycleAction,
 } from "../db/issue-lifecycle";
-import { getIssueRef, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef } from "../db/issue-refs";
+import { getIssueRef } from "../db/issue-refs";
+import { resolveIssueRefByExternalKeyAsync, resolveIssueRefFromStringAsync, updateIssueRefAsync, upsertIssueLifecycleActionAsync } from "../db/issue-refs-async";
 import { associateIssue } from "../db/issue-associations";
 import { resolveIssueTrackerAdapter } from "../issue-tracker";
 import { defaultIssueRepo } from "../config";
@@ -141,42 +141,53 @@ const ISSUE_REF_AT_START_RE = /^(https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z
 const REF_SEPARATOR_RE = /^(?:\s*,\s*|\s+(?:and|&)\s+)/i;
 
 // A run of issue refs ("#1, #2 and owner/repo#3") starting at the head of `segment`.
-// Bare refs resolve against `fallbackDefaultRepo`; unresolvable ones are skipped so a
-// land never fails here.
-function collectRefRun(segment: string, fallbackDefaultRepo: string | undefined, into: IssueRef[]): void {
+function refRun(segment: string): string[] {
+  const refs: string[] = [];
   let rest = segment;
   while (rest.trim()) {
     rest = rest.trimStart();
     const refMatch = rest.match(ISSUE_REF_AT_START_RE);
     if (!refMatch) break;
-    try {
-      into.push(resolveIssueRefFromString({ ref: refMatch[1]!, defaultRepo: fallbackDefaultRepo }));
-    } catch {
-      // Invalid or bare-without-default refs are ignored; the land itself must never fail here.
-    }
+    refs.push(refMatch[1]!);
     rest = rest.slice(refMatch[0].length);
     const separator = rest.match(REF_SEPARATOR_RE);
     if (!separator) break;
     rest = rest.slice(separator[0].length);
   }
+  return refs;
 }
 
-export function parseClosingIssueRefs(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): IssueRef[] {
-  if (!text) return [];
+// Bare refs resolve against `fallbackDefaultRepo`; unresolvable ones are skipped so a land never fails here.
+async function resolveRefRuns(segments: Iterable<string>, fallbackDefaultRepo: string | undefined): Promise<IssueRef[]> {
   const refs: IssueRef[] = [];
-  for (const match of text.matchAll(CLOSING_KEYWORD_RE)) collectRefRun(match[1] ?? "", fallbackDefaultRepo, refs);
+  for (const segment of segments) {
+    for (const ref of refRun(segment)) {
+      try {
+        refs.push(await resolveIssueRefFromStringAsync({ ref, defaultRepo: fallbackDefaultRepo }));
+      } catch {
+        // Invalid or bare-without-default refs are ignored; the land itself must never fail here.
+      }
+    }
+  }
   return issueRefMap(refs);
 }
 
+export function parseClosingIssueRefsAsync(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): Promise<IssueRef[]> {
+  return resolveRefRuns(text ? [...text.matchAll(CLOSING_KEYWORD_RE)].map((match) => match[1] ?? "") : [], fallbackDefaultRepo);
+}
+
 // Parenthesized backlink groups: the trailing `(#NNN)` convention agents (and a squash merge)
 // stamp on a subject without a closing keyword. Non-issue parens (conventional-commit scopes
 // like `fix(tokens)`, notes like `(see also)`) carry no `#` and fall out.
 const BACKLINK_GROUP_RE = /\(([^()]*#[0-9]+[^()]*)\)/g;
 
-export function parseBacklinkIssueRefs(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): IssueRef[] {
-  if (!text) return [];
+export function parseBacklinkIssueRefsAsync(text: string | undefined, fallbackDefaultRepo = defaultIssueRepo()): Promise<IssueRef[]> {
+  return resolveRefRuns(text ? [...text.matchAll(BACKLINK_GROUP_RE)].map((group) => group[1] ?? "") : [], fallbackDefaultRepo);
+}
+
+async function eachSubject(subjects: string[], parse: (text: string) => Promise<IssueRef[]>): Promise<IssueRef[]> {
   const refs: IssueRef[] = [];
-  for (const group of text.matchAll(BACKLINK_GROUP_RE)) collectRefRun(group[1] ?? "", fallbackDefaultRepo, refs);
+  for (const subject of subjects) refs.push(...await parse(subject));
   return issueRefMap(refs);
 }
 
@@ -190,13 +201,13 @@ async function resolveIssueRefsForLand(input: LandedIssueLifecycleInput, links:
   const associated = issueRefMap(links.flatMap((link) => link.issues.filter((issue) => issue.relation === "delivers").map((issue) => issue.ref)));
   const fallbackDefaultRepo = await landDefaultRepo(input.workspace);
   const subjects = landedSubjectTexts(input);
-  const keyworded = issueRefMap(subjects.flatMap((subject) => parseClosingIssueRefs(subject, fallbackDefaultRepo)));
+  const keyworded = await eachSubject(subjects, (subject) => parseClosingIssueRefsAsync(subject, fallbackDefaultRepo));
   // A commit declaration is authored at the change boundary, unlike a Task association
   // which can legitimately be historical or span several work items. It is the sole close
   // target when present (#1694).
   if (keyworded.length > 0) return { source: "commit", refs: keyworded, declared: keyworded };
   if (!input.prLand && links.some((link) => link.buildLike)) {
-    const backlinks = issueRefMap(subjects.flatMap((subject) => parseBacklinkIssueRefs(subject, fallbackDefaultRepo)))
+    const backlinks = (await eachSubject(subjects, (subject) => parseBacklinkIssueRefsAsync(subject, fallbackDefaultRepo)))
       .filter((ref) => canCloseBacklink(ref, links));
     if (backlinks.length) return { source: "backlink", refs: backlinks, declared: backlinks };
   }
@@ -348,7 +359,7 @@ async function reconcileClosedIssueRefBeforeSkip(issueRef: IssueRef, opts: Issue
       // LOW-4 (#2520 review) — thread the live closeReason through: a completed close observed
       // here was dropped, so the cached ref stayed reason-less and could never count as a
       // completed close. updateIssueRef preserves the cached reason when live carries none.
-      issueRef: updateIssueRef(issueRef.id, { status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() }) ?? issueRef,
+      issueRef: await updateIssueRefAsync(issueRef.id, { status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() }) ?? issueRef,
       liveStatus: live.status,
     };
   } catch (error) {
@@ -406,7 +417,7 @@ export async function closeIssueRefForLand(
         logFailure(opts, `issue lifecycle epic-guard title lookup returned no title for ${latest.id} on ${key}`);
         return { issueRef: latest, action: "skipped", reason: "title-unavailable", landKey: key };
       }
-      latest = updateIssueRef(latest.id, { title, statusSyncedAt: Date.now() }) ?? latest;
+      latest = await updateIssueRefAsync(latest.id, { title, statusSyncedAt: Date.now() }) ?? latest;
     } catch (error) {
       logFailure(opts, `issue lifecycle epic-guard title lookup failed for ${latest.id} on ${key}: ${errMessage(error)}`);
       return { issueRef: latest, action: "skipped", reason: "title-unavailable", landKey: key };
@@ -423,22 +434,25 @@ export async function closeIssueRefForLand(
     return { issueRef: latest, action: "skipped", reason: "epic-issue", landKey: key };
   }
 
+  const closeAction = {
+    issueRefId: latest.id,
+    action: "close" as const,
+    landKey: key,
+    workspaceId: input.workspace.id,
+    branch: input.workspace.branch,
+    baseRef: input.workspace.baseRef ?? "main",
+    commitSha: input.mergedSha,
+    commitSubject: input.subject,
+    agentId: input.workspace.ownerAgentId,
+    source,
+  };
   let openSubIssues: IssueTrackerIssueSummary[];
   try {
     openSubIssues = await listOpenSubIssuesForLand(latest, opts);
   } catch (error) {
     const message = `sub-issue lookup failed: ${errMessage(error)}`;
-    upsertIssueLifecycleAction({
-      issueRefId: latest.id,
-      action: "close",
-      landKey: key,
-      workspaceId: input.workspace.id,
-      branch: input.workspace.branch,
-      baseRef: input.workspace.baseRef ?? "main",
-      commitSha: input.mergedSha,
-      commitSubject: input.subject,
-      agentId: input.workspace.ownerAgentId,
-      source,
+    await upsertIssueLifecycleActionAsync({
+      ...closeAction,
       status: "failed",
       error: message,
     });
@@ -458,18 +472,9 @@ export async function closeIssueRefForLand(
   const comment = closeAuditComment(input);
   try {
     await adapterFor(latest, opts).close(latest, { comment, labels: ["fixed"], closeReason: "completed" });
-    const closed = updateIssueRef(latest.id, { status: "closed", closeReason: "completed", statusSyncedAt: Date.now() }) ?? latest;
-    upsertIssueLifecycleAction({
-      issueRefId: latest.id,
-      action: "close",
-      landKey: key,
-      workspaceId: input.workspace.id,
-      branch: input.workspace.branch,
-      baseRef: input.workspace.baseRef ?? "main",
-      commitSha: input.mergedSha,
-      commitSubject: input.subject,
-      agentId: input.workspace.ownerAgentId,
-      source,
+    const closed = await updateIssueRefAsync(latest.id, { status: "closed", closeReason: "completed", statusSyncedAt: Date.now() }) ?? latest;
+    await upsertIssueLifecycleActionAsync({
+      ...closeAction,
       comment,
       status: "succeeded",
     });
@@ -494,17 +499,8 @@ export async function closeIssueRefForLand(
     return { issueRef: closed, action: "closed", source, landKey: key };
   } catch (error) {
     const message = errMessage(error);
-    upsertIssueLifecycleAction({
-      issueRefId: latest.id,
-      action: "close",
-      landKey: key,
-      workspaceId: input.workspace.id,
-      branch: input.workspace.branch,
-      baseRef: input.workspace.baseRef ?? "main",
-      commitSha: input.mergedSha,
-      commitSubject: input.subject,
-      agentId: input.workspace.ownerAgentId,
-      source,
+    await upsertIssueLifecycleActionAsync({
+      ...closeAction,
       comment,
       status: "failed",
       error: message,
@@ -564,15 +560,15 @@ export async function handleLandedIssueLifecycle(input: LandedIssueLifecycleInpu
   return { source: resolved.source, closed, reopened, skipped: [], mismatches };
 }
 
-function resolveReopenRef(input: ReopenIssueLifecycleInput): IssueRef {
+async function resolveReopenRef(input: ReopenIssueLifecycleInput): Promise<IssueRef> {
   if (input.issueRefId) {
     const issueRef = getIssueRef(input.issueRefId);
     if (!issueRef) throw new Error(`issue ref ${input.issueRefId} not found`);
     return issueRef;
   }
-  if (input.ref) return resolveIssueRefFromString({ ref: input.ref, defaultRepo: input.defaultRepo ?? input.repo, provider: input.provider, title: input.title });
+  if (input.ref) return resolveIssueRefFromStringAsync({ ref: input.ref, defaultRepo: input.defaultRepo ?? input.repo, provider: input.provider, title: input.title });
   if (input.provider && input.repo && input.externalKey) {
-    return resolveIssueRefByExternalKey({
+    return resolveIssueRefByExternalKeyAsync({
       provider: input.provider,
       repo: input.repo,
       externalKey: input.externalKey,
@@ -584,14 +580,14 @@ function resolveReopenRef(input: ReopenIssueLifecycleInput): IssueRef {
 }
 
 export async function reopenIssueLifecycle(input: ReopenIssueLifecycleInput, opts: IssueLifecycleOptions = {}): Promise<ReopenIssueLifecycleResult> {
-  const issueRef = resolveReopenRef(input);
+  const issueRef = await resolveReopenRef(input);
   const key = manualReopenKey(issueRef);
   if (issueRef.status === "open") return { issueRef, action: "skipped", reason: "already-open", landKey: key };
   const comment = input.comment ?? "Reopened by Humwick issue lifecycle.";
   try {
     await adapterFor(issueRef, opts).reopen(issueRef, { comment });
-    const opened = updateIssueRef(issueRef.id, { status: "open", statusSyncedAt: Date.now() }) ?? issueRef;
-    upsertIssueLifecycleAction({
+    const opened = await updateIssueRefAsync(issueRef.id, { status: "open", statusSyncedAt: Date.now() }) ?? issueRef;
+    await upsertIssueLifecycleActionAsync({
       issueRefId: issueRef.id,
       action: "reopen",
       landKey: key,
@@ -604,7 +600,7 @@ export async function reopenIssueLifecycle(input: ReopenIssueLifecycleInput, opt
     return { issueRef: opened, action: "reopened", landKey: key };
   } catch (error) {
     const message = errMessage(error);
-    upsertIssueLifecycleAction({
+    await upsertIssueLifecycleActionAsync({
       issueRefId: issueRef.id,
       action: "reopen",
       landKey: key,

package/src/services/issue-refs.ts

@@ -1,11 +1,7 @@
+import { deleteIssueRefAsync, resolveIssueRefByExternalKeyAsync, resolveIssueRefFromStringAsync, updateIssueRefAsync, upsertIssueRefAsync } from "../db/issue-refs-async";
 import {
-  deleteIssueRef,
   getIssueRef,
   listIssueRefs,
-  resolveIssueRefByExternalKey,
-  resolveIssueRefFromString,
-  updateIssueRef,
-  upsertIssueRef,
   type ListIssueRefsOptions,
   type ResolveIssueRefByExternalKeyInput,
   type ResolveIssueRefFromStringInput,
@@ -15,20 +11,20 @@ import {
 
 export { getIssueRef, listIssueRefs, type ListIssueRefsOptions };
 
-export function upsertIssueRefMapping(input: UpsertIssueRefInput) {
-  return upsertIssueRef(input);
+export function upsertIssueRefMappingAsync(input: UpsertIssueRefInput) {
+  return upsertIssueRefAsync(input);
 }
 
-export function resolveIssueRefMapping(input: ResolveIssueRefByExternalKeyInput | ResolveIssueRefFromStringInput) {
-  return "ref" in input ? resolveIssueRefFromString(input) : resolveIssueRefByExternalKey(input);
+export function resolveIssueRefMappingAsync(input: ResolveIssueRefByExternalKeyInput | ResolveIssueRefFromStringInput) {
+  return "ref" in input ? resolveIssueRefFromStringAsync(input) : resolveIssueRefByExternalKeyAsync(input);
 }
 
-export function patchIssueRefMapping(id: string, input: UpdateIssueRefInput) {
-  return updateIssueRef(id, input);
+export function patchIssueRefMappingAsync(id: string, input: UpdateIssueRefInput) {
+  return updateIssueRefAsync(id, input);
 }
 
-export function deleteIssueRefMapping(id: string) {
-  return deleteIssueRef(id);
+export function deleteIssueRefMappingAsync(id: string) {
+  return deleteIssueRefAsync(id);
 }
 
 // --- Caller-supplied issue-ref normalization (#2214/#1930) ---------------------------------