@humwick/server 0.130.2 → 0.130.4

package/src/cd-deploy-notify.ts

@@ -41,7 +41,7 @@ export async function notifyCdDeployLive(input: CdDeployLiveInput = {}): Promise
   const version = input.version ?? VERSION;
   const gitSha = input.gitSha ?? reportedGitSha();
   if (!gitSha) {
-    routeNotification({ type: "cd.deploy_live", scope: {}, recipients: [], message: {
+    await routeNotification({ type: "cd.deploy_live", scope: {}, recipients: [], message: {
       body: `Humwick v${version} is now running.`, payload: { kind: "cd.deploy-live", version },
       idempotencyKey: `release-deploy-live:${version}`, replyExpected: false,
     } });
@@ -50,7 +50,7 @@ export async function notifyCdDeployLive(input: CdDeployLiveInput = {}): Promise
   const shortSha = gitSha.slice(0, 12);
   const contents = await deployNoticeContents(gitSha, input.repoRoot ?? resolve(import.meta.dir, ".."));
 
-  routeNotification({
+  await routeNotification({
     type: "cd.deploy_live",
     scope: {},
     ttlMs: null,

package/src/ci/notifications.ts

@@ -120,13 +120,13 @@ export interface RouteCiIncidentNotificationResult {
  * through routeNotification so its TTL, idempotency, routing explanation, and
  * Activity audit behavior stay identical to every other Relay notification.
  */
-export function routeCiIncidentNotification(input: RouteCiIncidentNotificationInput): RouteCiIncidentNotificationResult {
+export async function routeCiIncidentNotification(input: RouteCiIncidentNotificationInput): Promise<RouteCiIncidentNotificationResult> {
   const { payload } = input;
   const subject = input.subject ?? defaultSubject(input.type, payload.repository, payload.branch);
   const body = input.body ?? defaultBody(input);
   const recipients = input.recipients ?? [payload.coordinatorAgentId];
   const idempotencyKey = input.idempotencyKey ?? defaultIdempotencyKey(input);
-  const messages = routeNotification({
+  const messages = await routeNotification({
     type: input.type,
     scope: {
       repoRoot: payload.repoRoot ?? payload.repository,
@@ -148,14 +148,14 @@ export function routeCiIncidentNotification(input: RouteCiIncidentNotificationIn
   });
 
   if (!input.alertHuman) return { messages };
-  const humanFallback = notifyWorkspaceHumanEscalation({
+  const humanFallback = (await notifyWorkspaceHumanEscalation({
     subject,
     body,
     payload: { kind: input.type, ...payload },
     priority: humanAlertPriority(input.type),
     tags: ["agent-relay", "ci", humanAlertTag(input.type)],
     source: "ci-incident",
-  });
+  }));
   return { messages, humanFallback };
 }
 

package/src/ci/root-missing.ts

@@ -11,11 +11,11 @@ export interface CiRootMissing {
 
 type Deps = Pick<CiTransitionNotifyDeps, "resolveCoordinator" | "route" | "now">;
 
-function notify(input: CiRootMissing, deps: Deps, fired: boolean): boolean {
+async function notify(input: CiRootMissing, deps: Deps, fired: boolean): Promise<boolean> {
   if (!fired) return false;
   const route = deps.route ?? routeCiIncidentNotification;
   const observedAt = deps.now ?? Date.now();
-  route({
+  await route({
     type: "ci.root_missing",
     payload: { provider: "github-actions", repository: input.repository, repoRoot: input.rootPath, branch: "*", coordinatorAgentId: resolveCoordinator(deps), observedAt },
     alertHuman: true,
@@ -26,5 +26,5 @@ function notify(input: CiRootMissing, deps: Deps, fired: boolean): boolean {
 }
 
 export async function notifyCiRootMissing(input: CiRootMissing, deps: Deps = {}): Promise<boolean> {
-  return notify(input, deps, await markCiRootMissingNotifiedAsync(input.repository, deps.now));
+  return await notify(input, deps, await markCiRootMissingNotifiedAsync(input.repository, deps.now));
 }

package/src/ci/transition-notify.ts

@@ -42,7 +42,7 @@ export const CI_MAIN_WATCH_COORDINATOR = "cd-watcher";
 
 export interface CiTransitionNotifyDeps {
   ingest?: (observation: CiObservation, now?: number) => CiIncidentIngestResult | Promise<CiIncidentIngestResult>;
-  route?: (input: Parameters<typeof routeCiIncidentNotification>[0]) => RouteCiIncidentNotificationResult;
+  route?: (input: Parameters<typeof routeCiIncidentNotification>[0]) => RouteCiIncidentNotificationResult | Promise<RouteCiIncidentNotificationResult>;
   /** Resolve the coordinator/owner agent the relay message addresses. Defaults to the configured
    * steward fallback, then the system watch actor. */
   resolveCoordinator?: () => string | undefined;
@@ -93,7 +93,7 @@ export async function notifyCiTransition(
       failingRunIds: observation.failingRuns.map((run) => run.id),
       failingJobNames: failingJobNames(observation),
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.failed",
       payload,
       alertHuman: true,
@@ -117,7 +117,7 @@ export async function notifyCiTransition(
       greenHeadSha: observation.headSha,
       ...(result.incident.resolution ? { resolution: result.incident.resolution } : {}),
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.recovered",
       payload,
       alertHuman: true,
@@ -138,7 +138,7 @@ export async function notifyCiTransition(
       firstSeenAt: result.firstSeenAt,
       observedAt: observation.observedAt,
     };
-    const routed = route({
+    const routed = await route({
       type: "ci.never_matched",
       payload,
       alertHuman: true,
@@ -149,7 +149,7 @@ export async function notifyCiTransition(
   }
 
   if (result.kind === "config_mismatch") {
-    const routed = route(configMismatchRoute(observation, resolveCoordinator(deps), result.unmatchedJobs));
+    const routed = await route(configMismatchRoute(observation, resolveCoordinator(deps), result.unmatchedJobs));
     return { transition: "config_mismatch", notified: true, messages: routed.messages.length, ...(routed.humanFallback ? { humanFallback: routed.humanFallback } : {}) };
   }
 

package/src/claude-app/oauth-http.ts

@@ -68,12 +68,12 @@ async function getRuntime(): Promise<Runtime> {
       removeShutdownHook = onShutdown("claude-app-oauth", stopClaudeAppOAuth);
       outcome = { status: "ok", detail: "OAuth available" };
       return { provider, server, base: `http://127.0.0.1:${address.port}` };
-    })().catch(error => withRelayEventDrain(() => {
+    })().catch(error => withRelayEventDrain(async () => {
       runtime = undefined;
       const detail = `OAuth unavailable: ${errMessage(error)}`;
       outcome = { status: "error", detail };
-      raiseOperatorAlarm({ clientId: `claude-app-oauth:${detail}`, source: "claude-app-oauth",
-        subject: "Claude app OAuth unavailable", detail, view: "overview", dedupeEvent: true });
+      (await raiseOperatorAlarm({ clientId: `claude-app-oauth:${detail}`, source: "claude-app-oauth",
+        subject: "Claude app OAuth unavailable", detail, view: "overview", dedupeEvent: true }));
       throw error;
     }));
   }

package/src/cli/index.ts

@@ -22,6 +22,7 @@ import { handleUpgradeCommand } from "./upgrade";
 import { handleProviderCommand } from "./provider";
 import { handleContextProbeCommand } from "./context-probe";
 import { handleSetupCommand } from "./setup";
+import { handleInitCommand } from "./init";
 import { handleDaemonCommand } from "./daemon";
 import { handleOrchestratorCommand } from "./orchestrator";
 import { handleDevCommand } from "./dev";
@@ -68,6 +69,7 @@ Usage:
   humwick run --status <runId>
   ${CHANNEL_OUTPUT_USAGE}
   humwick [start]
+  humwick init [--yes] [--json] [--tarball-dir DIR] [--env-file PATH] [--runtime-prefix DIR] [--host HOST] [--port PORT] [--db-path PATH]   (install or repair the server as a user service)
   humwick setup [--yes] [--dry-run] [--force] [--env-file PATH] [--runtime-prefix DIR] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
   humwick upgrade [--dry-run] [--version VERSION] [--runtime-prefix DIR] [--providers auto|all|codex|claude|opencode|orchestrator] [--no-restart] [--yes]
   humwick upgrade --host ID [--host ID2 ...] [--version VERSION] [--providers ...]   (upgrade remote orchestrator hosts over the relay)
@@ -281,10 +283,14 @@ export async function handleCli(args: string[]): Promise<"start" | "handled"> {
     await handleUpgradeCommand(command === "setup" ? args.slice(2) : args.slice(1));
     return "handled";
   }
-  if (command === "setup" || command === "init") {
+  if (command === "setup") {
     await handleSetupCommand(args.slice(1));
     return "handled";
   }
+  if (command === "init") {
+    await handleInitCommand(args.slice(1));
+    return "handled";
+  }
   if (command === "channels-host") {
     const { handleChannelsHostCommand } = await import("./channels-host");
     await handleChannelsHostCommand(args.slice(1));

package/src/cli/init.ts

@@ -0,0 +1,53 @@
+// `humwick init` (#2680): install or repair a persistent server; the same code serves --yes/--json.
+import { InitStepError, runInit, type InitOptions } from "../init";
+import { errMessage } from "@humwick/sdk";
+import { confirm } from "./_shared";
+
+export async function handleInitCommand(args: string[]): Promise<void> {
+  const options: InitOptions = {};
+  let yes = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const value = () => {
+      const next = args[++i];
+      if (!next) throw new Error(`${arg} needs a value`);
+      return next;
+    };
+    if (arg === "--tarball-dir") options.tarballDir = value();
+    else if (arg === "--runtime-prefix") options.runtimePrefix = value();
+    else if (arg === "--env-file") options.envFile = value();
+    else if (arg === "--host") options.host = value();
+    else if (arg === "--port") options.port = parseInt(value(), 10);
+    else if (arg === "--db-path") options.dbPath = value();
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown init option "${arg}"`);
+  }
+
+  if (!yes && !json && !(await confirm("Install the Humwick server as a user service on this machine?"))) {
+    console.log("Init cancelled.");
+    return;
+  }
+  // With --json, stdout carries only the result object; progress goes to stderr.
+  const log = (line: string) => (json ? console.error : console.log)(`✓ ${line}`);
+  try {
+    const result = await runInit(options, log);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    for (const warning of result.warnings) console.log(`! ${warning}`);
+    console.log(`\nHumwick ${result.version} is running as ${result.service.unit}.`);
+    console.log(`Dashboard:  ${result.dashboardUrl}`);
+    console.log(`Login link: ${result.loginUrl}`);
+    console.log("\nNext:");
+    for (const step of result.next) console.log(`- ${step}`);
+  } catch (e) {
+    const step = e instanceof InitStepError ? e.step : "init";
+    const repair = e instanceof InitStepError ? e.repair : "Rerun init; it resumes where it stopped.";
+    if (json) console.log(JSON.stringify({ ok: false, step, error: errMessage(e), repair }, null, 2));
+    else console.error(`init failed at ${step}: ${errMessage(e)}\nRepair: ${repair}`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/orchestrator.ts

@@ -20,7 +20,7 @@ import { createUserPathPlan, executeUserPathPlan, purgeUserPath } from "../user-
 import { VERSION } from "../config";
 import { shellQuote } from "@humwick/sdk/shell-utils";
 import { RELAY_TOKEN_HEADER } from "@humwick/sdk";
-import { expandTilde } from "../utils";
+import { expandTilde, sanitizeOrchestratorId } from "../utils";
 import { confirm } from "./_shared";
 
 const ORCHESTRATOR_USAGE =
@@ -310,12 +310,6 @@ async function exchangeOrchestratorBootstrapToken(relayUrl: string, bootstrapTok
   return payload.token;
 }
 
-function sanitizeOrchestratorId(value: string): string {
-  const clean = value.trim().replace(/\./g, "-").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-  if (!clean) throw new Error("--id must contain at least one letter or number");
-  return clean.slice(0, 120);
-}
-
 function detectProviderPathPrefixes(providers: string[]): string[] {
   const prefixes: string[] = [];
   for (const provider of providers) {

package/src/cli/setup.ts

@@ -1,5 +1,5 @@
 // Setup command — auto-split from cli.ts (#294). Generates the relay env file.
-import { createSetupPlan, executeSetupPlan, formatSetupPlan, pathExists } from "../setup";
+import { executeSetupPlan, formatSetupPlan, pathExists, redactSetupPlan, resolveSetupPlan } from "../setup";
 import { confirm } from "./_shared";
 
 export async function handleSetupCommand(args: string[]): Promise<void> {
@@ -32,7 +32,7 @@ export async function handleSetupCommand(args: string[]): Promise<void> {
     else throw new Error(`Unknown setup option "${arg}"`);
   }
 
-  const plan = createSetupPlan({
+  const plan = await resolveSetupPlan({
     ...(envFile ? { envFile } : {}),
     ...(host ? { host } : {}),
     ...(port !== undefined ? { port } : {}),
@@ -43,7 +43,8 @@ export async function handleSetupCommand(args: string[]): Promise<void> {
     force,
   });
 
-  if (!dryRun && !yes && await pathExists(plan.envFile)) {
+  // A managed env file is reused (same token), so only a foreign file needs consent.
+  if (!dryRun && !yes && !plan.reused && await pathExists(plan.envFile)) {
     const ok = await confirm(`Overwrite ${plan.envFile}?`);
     if (!ok) {
       console.log("Setup cancelled.");
@@ -52,6 +53,7 @@ export async function handleSetupCommand(args: string[]): Promise<void> {
   }
 
   const result = await executeSetupPlan(plan, { dryRun, force });
-  if (json) console.log(JSON.stringify({ plan, output: result }, null, 2));
+  // The admin token never goes to stdout; it stays in the 0600 env file (#2680).
+  if (json) console.log(JSON.stringify({ plan: redactSetupPlan(plan), output: result }, null, 2));
   else console.log(dryRun ? formatSetupPlan(plan) : result);
 }

package/src/cli/workflow.ts

@@ -1,7 +1,7 @@
 import { apiRequest } from "./_shared";
 import { probeWorkflowDeployment } from "../../scripts/wait-for-deploy";
 
-export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>] | workflow pause <runId> --reason <text> | workflow unpause <runId>";
+export const WORKFLOW_USAGE = "Usage: humwick workflow start <workflow> <taskId> [--json] | workflow get <runId> [--verbose] [--include-held] [--results-ref <id>] [--results-cursor <cursor>] [--json] | workflow resume <runId> [--activation <id>] [--step <step>] [--pins <json>] [--note <text>] | workflow pause <runId> --reason <text> | workflow unpause <runId>";
 
 export async function handleWorkflowCommand(args: string[]): Promise<void> {
   const [command, runId, ...flags] = args;
@@ -33,8 +33,17 @@ export async function handleWorkflowCommand(args: string[]): Promise<void> {
     return;
   }
   if (command === "resume") {
-    if (flags.length && (flags[0] !== "--activation" || flags.length !== 2 || !flags[1])) throw new Error(WORKFLOW_USAGE);
-    console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/resume`, { ...(flags[1] ? { activationId: flags[1] } : {}) }), null, 2));
+    const body: Record<string, unknown> = {};
+    const fields: Record<string, string> = { "--activation": "activationId", "--step": "step", "--pins": "pins", "--note": "note" };
+    for (let index = 0; index < flags.length; index++) {
+      const flag = flags[index]!;
+      if (flag === "--json") continue;
+      const field = fields[flag];
+      const value = flags[++index];
+      if (!field || !value || value.startsWith("--")) throw new Error(WORKFLOW_USAGE);
+      body[field] = field === "pins" ? JSON.parse(value) : value;
+    }
+    console.log(JSON.stringify(await apiRequest("POST", `/api/workflows/runs/${encodeURIComponent(runId)}/resume`, body), null, 2));
     return;
   }
   const query = new URLSearchParams();

package/src/commands-db.ts

@@ -834,13 +834,13 @@ export function deleteCommand(id: string): boolean {
 
 // Race the host claim on the same pending row; only the winning cancellation records stop intent.
 // Legacy landing cancellation stays confined to its unfenced rows.
-export function cancelPendingCommand(id: string, expectedType: string, reason = "canceled before dispatch"): boolean {
+export function cancelPendingCommand(id: string, expectedType: string, reason = "canceled before dispatch", submittedAt: number = Date.now()): boolean {
   if (expectedType === "workspace.merge") {
     const existing = getCommand(id);
     if (!existing || !isLegacyUnfencedWorkspaceMerge(existing)) return false;
   }
   return inWriteTransaction(() => {
-    const now = Date.now();
+    const now = submittedAt;
     const changes = getDb()
       .query(`UPDATE commands SET status = 'canceled', result = ${canceledSpawnResultSql()}, error = ?, updated_at = ? WHERE id = ? AND status = 'pending' AND type = ?`)
       .run(reason, now, id, expectedType).changes;
@@ -978,7 +978,7 @@ export const EXPIRED_PENDING_COMMANDS_SQL = `SELECT * FROM commands WHERE (type
 
 export function expireCommands(
   now: number = Date.now(),
-  opts: { isTargetGone?: (command: Command) => boolean } = {},
+  opts: { isTargetGone?: (command: Command) => boolean; update?: typeof updateCommand } = {},
 ): Command[] {
   const activeRows = getDb().query(EXPIRED_CLAIMED_COMMANDS_SQL).all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
   const pendingCandidates = getDb().query(EXPIRED_PENDING_COMMANDS_SQL).all(now) as CommandRow[];
@@ -998,7 +998,7 @@ export function expireCommands(
     // #1452 round-13 — the TTL sweep is an AUTHORIZED terminalizer of a claimed publish (executor:true):
     // it is the fail-closed path that lets the reconciler clean a host-death-after-claim, and timed_out is
     // ambiguous (ref retained), never a ref-drop. External surfaces get no such flag (see updateCommand).
-    updateCommand(row.id, {
+    (opts.update ?? updateCommand)(row.id, {
       status: "timed_out",
       error: row.status === "pending"
         ? ((row.type === "agent.spawn" || row.type === "agent.restart") && hostSpawnsDrained(row.target) ? "host draining: spawns disabled; expired before dispatch" : "command target gone; expired before dispatch")

package/src/commands-write.ts

@@ -49,6 +49,10 @@ export async function createCommandAsync(
   vaultProjectId?: string,
 ): Promise<Command> {
   const args = await prepareCommandWriteAsync(input, options, vaultActor, vaultProjectId);
+  return submitPreparedCommandAsync(args);
+}
+
+export function submitPreparedCommandAsync(args: CreateCommandWriteArgs): Promise<Command> {
   return getGateway().coalesce(
     "commands.create",
     args,
@@ -82,6 +86,10 @@ export function getCommandAsync(id: string): Promise<Command | null> {
   return getGateway().read("commands.get", { id }) as unknown as Promise<Command | null>;
 }
 
+export function findLatestCommandByCorrelationAsync(type: string, correlationId: string): Promise<Command | null> {
+  return getGateway().read("commands.latestByCorrelation", { type, correlationId }) as unknown as Promise<Command | null>;
+}
+
 /** #2969 — an agent's confirmed effort changes within a chat window's time range, read off-loop. */
 export function listEffortChangesAsync(agentId: string, from: number, to: number, after?: EffortChangeCursor): Promise<{ changes: EffortChange[]; next?: EffortChangeCursor }> {
   return getGateway().read("commands.effortChanges", { agentId, from, to, ...(after ? { after } : {}) }) as unknown as Promise<{ changes: EffortChange[]; next?: EffortChangeCursor }>;

package/src/compaction-watch.ts

@@ -1,6 +1,8 @@
+import { framed } from "./hub-metrics";
+import { createActivityEventAsync } from "./db/activity-async";
 import { timePostBindPhase } from "./post-bind-startup";
 import { guardedInterval, isRecord } from "@humwick/sdk";
-import { getAgent, createActivityEvent } from "./db";
+import { getAgent } from "./db";
 import { emitRelayEvent } from "./events";
 import { isContinuationSelfResumeCommand } from "./self-resume-command";
 import type { AgentCard, Command } from "./types";
@@ -74,7 +76,7 @@ export class CompactionWatch {
   start(): void {
     if (this.timer) return;
     // #3643 — the tick writes an activity event; a BUSY from a bare timer would exit the hub.
-    this.timer = guardedInterval("[compaction-watch] tick", this.tickMs, () => timePostBindPhase("compaction-watch.tick", () => this.tick()));
+    this.timer = guardedInterval("[compaction-watch] tick", this.tickMs, framed("timer compaction-watch", () => timePostBindPhase("compaction-watch.tick", async () => (await this.tick()))));
   }
 
   stop(): void {
@@ -116,7 +118,7 @@ export class CompactionWatch {
     this.pending.delete(agentId);
   }
 
-  tick(): void {
+  async tick(): Promise<void> {
     const now = this.now();
     for (const [agentId, watch] of this.pending) {
       if (watch.deadline > now) continue;
@@ -138,15 +140,15 @@ export class CompactionWatch {
           continue;
         }
         this.pending.delete(agentId);
-        this.emitStalled(watch, true);
+        (await this.emitStalled(watch, true));
         continue;
       }
       this.pending.delete(agentId);
-      this.emitStalled(watch);
+      (await this.emitStalled(watch));
     }
   }
 
-  private emitStalled(watch: PendingWatch, busyCapped = false): void {
+  private async emitStalled(watch: PendingWatch, busyCapped = false): Promise<void> {
     const verb = watch.kind === "compact" ? "Compaction" : "Context clear";
     // #2043 F3 — the busy-capped variant means the agent is STILL taking turns (not stuck at a menu)
     // yet the compaction never started after a bounded wait — the runaway shape from #2043.
@@ -159,7 +161,7 @@ export class CompactionWatch {
       subject: watch.agentId,
       data: { agentId: watch.agentId, commandId: watch.commandId, kind: watch.kind, detail, busyCapped },
     });
-    createActivityEvent({
+    (await createActivityEventAsync({
       clientId: `command-stalled-${watch.commandId}-${this.now()}-${++this.seq}`,
       kind: "state",
       title: `${verb} stalled: ${watch.agentId}`,
@@ -168,7 +170,7 @@ export class CompactionWatch {
       view: "agents",
       agentId: watch.agentId,
       metadata: { source: "compaction-watch", commandId: watch.commandId, kind: watch.kind, stalled: true, detail, busyCapped },
-    });
+    }));
   }
 }
 

package/src/config-store-write.ts

@@ -45,7 +45,7 @@ export async function setAgentProfileAsync(profile: AgentProfile, updatedBy?: st
 }
 
 /** `deleteAgentProfile` on the writer thread (#1870 S7). */
-export function deleteAgentProfileAsync(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): Promise<boolean> {
+export async function deleteAgentProfileAsync(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): Promise<boolean> {
   const target = agentProfileDeleteTarget(name, opts);
-  return deleteConfigAsync(target.namespace, target.key, updatedBy);
+  return (await deleteConfigAsync(target.namespace, target.key, updatedBy));
 }

package/src/config.ts

@@ -637,21 +637,14 @@ export const DB_READER_JOB_TIMEOUT_MS = envPositiveInt("AGENT_RELAY_DB_READER_JO
 export const DB_READER_MARSHAL_IN_PROCESS =
   process.env.NODE_ENV === "test" || relayEnv(process.env, "AGENT_RELAY_DB_MARSHAL") === "1";
 
-/**
- * Phase-R rollout gate (#1960 T2 — ADR 0001 §7 Phase 1) for the gateway's READER half only. The
- * writer stays in-process unconditionally: Phase W (a worker writer taking the sole RW connection) is
- * a separate, much larger burn-down (#1870) and is deliberately NOT wired here. Any value other than
- * the literal `"worker"` — unset included — resolves to `"in-process"`, so this is behavior-preserving
- * by default; an operator opts in explicitly per the same string-literal convention as
- * `parseKernelTimersMode`.
- */
+/** Explicit reader placement override. Otherwise file databases use workers (#3339). */
 export type GatewayReaderBackendMode = "in-process" | "worker";
 
-export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode {
-  return value === "worker" ? "worker" : "in-process";
+export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode | undefined {
+  return value === "worker" || value === "in-process" ? value : undefined;
 }
 
-export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode {
+export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode | undefined {
   return parseGatewayReaderBackend(relayEnv(process.env, "AGENT_RELAY_GATEWAY_READER_BACKEND"));
 }
 

package/src/connectors.ts

@@ -1,10 +1,12 @@
+import { framed } from "./hub-metrics";
+import { upsertAgentAsync } from "./db/agents-async";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { timePostBindPhase } from "./post-bind-startup";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
-import { upsertAgent, ValidationError } from "./db";
+import { ValidationError } from "./db";
 import { CHANNELS_HOST_SECRETS } from "@humwick/sdk/channels-host-service";
 import { fireAndForget, guardedInterval, isRecord } from "@humwick/sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
@@ -274,11 +276,11 @@ export function startConnectorStatusPoller(): void {
   //    deploy that took down the relay/orchestrator tree) BEFORE the first status
   //    poll overwrites their persisted "running" flag with the now-dead reality.
   void fireAndForget("[connectors] boot reconcile", async () => {
-    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", () => ensureChannelsHostOnBoot()));
+    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", async () => (await ensureChannelsHostOnBoot())));
     await fireAndForget("[connectors] reconcile on boot", () => timePostBindPhase("connectors.reconcileConnectorsOnBoot", reconcileConnectorsOnBoot));
     await timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses);
   });
-  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses));
+  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, framed("timer connector-status", () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses)));
 }
 
 const CHANNELS_HOST_ID = "channels-host";
@@ -386,14 +388,14 @@ function configuredNtfyTopic(): string | null {
  * adapter's own gate — an unconfigured relay genuinely has no escalation target and must
  * still warn. Returns true when the row was (re)registered.
  */
-export function ensureEscalationChannelRegistered(): boolean {
+export async function ensureEscalationChannelRegistered(): Promise<boolean> {
   if (isEphemeralMode()) return false;
   const topic = configuredNtfyTopic();
   if (!topic) return false;
   // Shape matches the channels-host adapter's registration (channels-host/src/relay.ts
   // registerChannel + adapters/ntfy.ts channels()), so its later re-registration updates
   // the same row in place rather than churning it.
-  upsertAgent({
+  (await upsertAgentAsync({
     id: ESCALATION_NTFY_CHANNEL_ID,
     name: "ntfy",
     kind: "channel",
@@ -411,7 +413,7 @@ export function ensureEscalationChannelRegistered(): boolean {
       displayName: "ntfy",
       topicChannels: [topic],
     },
-  });
+  }));
   return true;
 }
 
@@ -429,7 +431,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
   // Register the escalation channel row now that config (incl. any legacy-migrated topic)
   // is persisted, so the escalation-target check passes without waiting for the async
   // channels-host SSE connect (#1510).
-  ensureEscalationChannelRegistered();
+  (await ensureEscalationChannelRegistered());
 
 
 }
@@ -437,7 +439,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
 /** Boot wrapper: a failed bring-up is logged with its stack and raised to /api/health, never swallowed (#3393). */
 export async function ensureChannelsHostOnBoot(entry?: string | null): Promise<void> {
   try {
-    await (entry === undefined ? ensureChannelsHostConnector() : ensureChannelsHostConnector(entry));
+    await (entry === undefined ? (await ensureChannelsHostConnector()) : (await ensureChannelsHostConnector(entry)));
     clearChannelsHostEnsureFailure();
   } catch (error) {
     console.error("[connectors] ensureChannelsHostConnector failed:", error instanceof Error ? (error.stack ?? error.message) : error);