@humwick/server 0.130.2 → 0.130.4

package/src/dev.ts

@@ -1,7 +1,8 @@
 import { writeChildEnv } from "@humwick/sdk/env";
+import { instanceDirectoryEnv } from "@humwick/sdk/isolated-env";
 import { execFile } from "node:child_process";
 import { shellQuote } from "@humwick/sdk/shell-utils";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir, hostname as osHostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -9,6 +10,7 @@ import { promisify } from "node:util";
 import { packPackage, privateWorkspaceDependencies, workspaceDependencyClosure } from "./package-pack";
 import { generateToken, renderEnvFile } from "./setup";
 import { createDaemonPlan, executeDaemonPlan, MANAGED_MARKER } from "./daemon";
+import { npmInstallIntoPrefix } from "./runtime-install";
 
 const execFileAsync = promisify(execFile);
 const DEV_MARKER = "agent-relay-dev-profile";
@@ -148,13 +150,10 @@ export function createDevInstallPlan(options: {
 export async function executeDevInstallPlan(plan: DevInstallPlan, options: { dryRun?: boolean } = {}): Promise<DevInstallResult> {
   if (options.dryRun) return { plan, tarballs: [], output: formatDevInstallPlan(plan) };
   const packed = await executeDevPackPlan(plan.packPlan);
-  await mkdir(plan.prefix, { recursive: true });
-  ensureDevPrefixPackageJson(plan.prefix);
-  const command = ["install", "--prefix", plan.prefix, "--no-audit", "--no-fund", "--force", ...packed.tarballs];
-  const result = await execFileAsync("npm", command, { cwd: plan.prefix });
+  const installed = await npmInstallIntoPrefix(plan.prefix, packed.tarballs);
   const output = [
     packed.output,
-    result.stdout.trim(),
+    installed,
     `Installed into ${plan.prefix}`,
   ].filter(Boolean).join("\n");
   return { plan, tarballs: packed.tarballs, output };
@@ -209,7 +208,8 @@ export function createDevServicePlan(options: {
   }
   const envContent = `# ${DEV_MARKER}\n` + renderEnvFile(writeChildEnv({}, {
     AGENT_RELAY_TOKEN: token,
-    AGENT_RELAY_HOME: rootDir,
+    ...instanceDirectoryEnv(rootDir, prefix),
+    AGENT_RELAY_DEV_PROFILE: "1",
     DB_PATH: join(rootDir, "state", "agent-relay.db"),
     HOST: host,
     PORT: String(port),
@@ -229,6 +229,7 @@ export function createDevServicePlan(options: {
     apiPort,
     tmuxPrefix: "ar-dev",
     env: writeChildEnv({}, {
+      ...instanceDirectoryEnv(rootDir, prefix),
       AGENT_RELAY_DEV_PROFILE: "1",
     }),
   };
@@ -296,8 +297,10 @@ export async function executeDevServicePlan(plan: DevServicePlan, options: { dry
   const output: string[] = [];
   if (plan.action === "start" || plan.action === "restart") {
     // Upgrade installed environments before either service can adopt execution records (#3139).
-    const existing = readFileSync(plan.envFile, "utf8").replace(/^(?:export\s+)?AGENT_RELAY_HOME=.*$/gm, "").trimEnd();
-    await writeFile(plan.envFile, `${existing}\n${Object.entries(writeChildEnv({}, { AGENT_RELAY_HOME: plan.rootDir })).map(([key, value]) => `${key}=${shellQuote(value)}\n`).join("")}`, "utf8");
+    const paths = writeChildEnv(instanceDirectoryEnv(plan.rootDir, plan.prefix), { AGENT_RELAY_DEV_PROFILE: "1" });
+    const keys = Object.keys(paths).map((key) => key.replace("AGENT_RELAY_", "(?:AGENT_RELAY_|HUMWICK_)"));
+    const existing = readFileSync(plan.envFile, "utf8").replace(new RegExp(`^(?:export\\s+)?(?:${keys.join("|")})=.*$`, "gm"), "").trimEnd();
+    await writeFile(plan.envFile, `${existing}\n${Object.entries(paths).map(([key, value]) => `${key}=${shellQuote(value)}\n`).join("")}`, "utf8");
   }
   if (plan.action === "install") {
     for (const file of plan.files) {
@@ -421,13 +424,6 @@ function devEnvFile(rootDir = defaultDevRoot()): string {
   return join(rootDir, "env");
 }
 
-function ensureDevPrefixPackageJson(prefix: string): void {
-  mkdirSync(prefix, { recursive: true });
-  const path = join(prefix, "package.json");
-  if (existsSync(path)) return;
-  writeFileSync(path, JSON.stringify({ private: true, name: "agent-relay-dev-install" }, null, 2) + "\n", "utf8");
-}
-
 function devServiceCommands(action: DevServiceAction, options: {
   serverUnit: string;
   orchestratorUnit: string;

package/src/event-loop-lag.ts

@@ -1,3 +1,4 @@
+import { trackRelayEvent } from "./relay-event-drain";
 import { errMessage } from "@humwick/sdk";
 import type { HealthCheck } from "./types";
 import {
@@ -166,7 +167,7 @@ export function setLagRegressionObserver(fn: EventLoopLagRegressionObserver | un
  * threshold rather than the diagnostic log threshold, and is a separate registration a caller can
  * leave unset (e.g. ephemeral mode) with no effect.
  */
-export type EventLoopLagBreakerObserver = (gapStartAt: number, gapEndAt: number, lagMs: number) => void;
+export type EventLoopLagBreakerObserver = (gapStartAt: number, gapEndAt: number, lagMs: number) => void | Promise<void>;
 
 let breakerObserver: EventLoopLagBreakerObserver | undefined;
 
@@ -283,7 +284,8 @@ export function recordEventLoopLagSample(
     // timer callback, so a throw here would become an uncaught exception in the interval — guard it:
     // the breaker degrading is never worth killing the loop-lag sampler that watches for the freeze.
     try {
-      breakerObserver(sampledAt - Math.max(0, elapsedMs), sampledAt, normalized);
+      const outcome = breakerObserver(sampledAt - Math.max(0, elapsedMs), sampledAt, normalized);
+      if (outcome) trackRelayEvent(outcome, "maintenance.lag-breaker");
     } catch (error) {
       console.warn(`[health] event-loop-lag breaker observer threw: ${errMessage(error)}`);
     }

package/src/event-loop-yield.ts

@@ -11,7 +11,7 @@ export function yieldToEventLoop(): Promise<void> {
  *  `moreWork`, so a backlog drains over runs instead of overrunning the deadline (a breaker strike). */
 export async function forEachPaced<T>(
   items: () => Iterable<T>,
-  unit: (item: T) => void,
+  unit: (item: T) => unknown,
   opts: { signal?: AbortSignal; budgetMs: number; ready?: () => boolean },
 ): Promise<{ moreWork: boolean }> {
   await yieldToEventLoop();
@@ -20,7 +20,7 @@ export async function forEachPaced<T>(
   for (const item of items()) {
     if (opts.signal?.aborted) return { moreWork: false };
     if (performance.now() >= stopAt || opts.ready?.() === false) return { moreWork: true };
-    unit(item);
+    await unit(item);
     await yieldToEventLoop();
   }
   return { moreWork: false };

package/src/events.ts

@@ -19,7 +19,7 @@ export interface RelayEvent {
 
 type Listener = (event: RelayEvent) => void;
 
-const listeners = new Set<Listener>();
+const listeners = new Map<Listener, string>();
 const fanoutQueue: Array<{ event: RelayEvent; lastSeq: number }> = [];
 let notifying = false;
 
@@ -33,12 +33,13 @@ export function emitRelayEvent(input: Omit<RelayEvent, "seq" | "timestamp">): Pr
       const appended = appendRelayEventInternal(input.type, input.source, input.data, input.subject, timestamp)!;
       return Promise.resolve(fanOutAppendedEvent(input, appended, timestamp));
     }
-    return emitRelayEventAsync(structuredClone(input), { idempotencyKey: crypto.randomUUID() });
+    // #3614 — keyless: nothing resubmits this append, so a ledger row would only cost writes.
+    return trackRelayEvent(appendAndFanOut(structuredClone(input), {}), input.type);
   });
 }
 
 /** #3606 — fan out to the current listeners only: no bus_outbox row, no idempotency-ledger row, no
- * replay. For state the next tick supersedes anyway (dashboard viewer presence). */
+ * replay. For state the next tick supersedes anyway (dashboard viewer presence, agent liveness ticks). */
 export function emitEphemeralRelayEvent(input: Omit<RelayEvent, "seq" | "timestamp" | "ephemeral">): RelayEvent {
   return fanOutAppendedEvent({ ...input, ephemeral: true }, { seq: 0, lastSeq: 0 }, Date.now());
 }
@@ -71,7 +72,8 @@ async function appendAndFanOut(
   } catch (error) {
     // H5: a lost acknowledgement says nothing about commit. Re-submit the exact logical append
     // with the same durable key; the writer returns the first result without a second insert.
-    if (!(error instanceof WriteIndeterminateError)) throw error;
+    // A keyless emit is at-most-once: it surfaces the error, and a committed row stays replayable.
+    if (!(error instanceof WriteIndeterminateError) || !options.idempotencyKey) throw error;
     appended = await getGateway().write("bus.append", args, { critical: true, idempotencyKey: options.idempotencyKey }) as unknown as typeof appended;
   }
   // A retry ledger result proves durable storage, not that this process owns a fresh live edge.
@@ -122,19 +124,19 @@ export function fanOutAppendedEvent(
 
 function notify(event: RelayEvent): void {
   measureEmit(event.type, true, () => {
-    for (const listener of listeners) {
+    for (const [listener, name] of listeners) {
       try {
         listener(event);
       } catch (error) {
         // Event projections are isolated so one transport cannot block another; a failed one (e.g. a
         // BUSY write in a projection, #3643) is logged, not swallowed.
-        console.warn(`[events] ${event.type} listener failed: ${errMessage(error)}`);
+        console.warn(`[events] ${event.type} listener ${name} failed: ${errMessage(error)}`, error instanceof Error ? error.stack : error);
       }
     }
   });
 }
 
-export function subscribeRelayEvents(listener: Listener): () => void {
-  listeners.add(listener);
+export function subscribeRelayEvents(listener: Listener, name = listener.name || "<anonymous>"): () => void {
+  listeners.set(listener, name);
   return () => listeners.delete(listener);
 }

package/src/host-provider-store.ts

@@ -1,8 +1,9 @@
+import { setConfigAsync } from "./config-store-write";
 // #2855 — DB-backed readers for per-host provider enablement. Separate from
 // host-provider-enablement.ts (a config-store-imported leaf) so this module can
 // import getConfig/listConfig without closing a cycle.
 import { errMessage, type SpawnProvider } from "@humwick/sdk";
-import { getConfig, listConfig, setConfig } from "./config-store";
+import { getConfig, listConfig } from "./config-store";
 import { listOrchestratorIds } from "./db";
 import {
   HOST_PROVIDER_ENABLEMENT_NAMESPACE,
@@ -75,11 +76,11 @@ export function hostProviderRefusal(hostId: string, provider: SpawnProvider): st
 /** One-time env migration: missing/unmarked rows merge omitted disables
  * without touching operator entries. In-env opt-ins store explicit true;
  * everything else outside env seeds as disabled. */
-export function seedHostProvidersFromEnv(
+export async function seedHostProvidersFromEnv(
   hostId: string,
   envProviders: readonly string[],
   switchableCatalog: readonly SpawnProvider[],
-): HostProviderEnablementSetting | null {
+): Promise<HostProviderEnablementSetting | null> {
   const existing = getHostProviderSetting(hostId);
   if (existing?.seeded) return null;
   const env = new Set(envProviders);
@@ -98,5 +99,5 @@ export function seedHostProvidersFromEnv(
       providers[provider] = { enabled: false, reason: "migrated from host env list" };
     }
   }
-  return setConfig(HOST_PROVIDER_ENABLEMENT_NAMESPACE, hostId, { providers, seeded: true }, "migration-seed").value;
+  return (await setConfigAsync(HOST_PROVIDER_ENABLEMENT_NAMESPACE, hostId, { providers, seeded: true }, "migration-seed")).value;
 }

package/src/hub-metrics-report.ts

@@ -20,6 +20,7 @@ export function hubMetricsReport(now = Date.now()) {
   const emits = emitTable.snapshot(now);
   const readerOps = readerOpTable.snapshot(now);
   const cpuMs = callers.reduce((total, row) => total + row.cpuMs, 0);
+  const backgroundCpuMs = callers.find((row) => row.key === BACKGROUND_KEY)?.cpuMs ?? 0;
   const calls = callers.reduce((total, row) => total + row.count, 0);
   return {
     generatedAt: now,
@@ -28,7 +29,9 @@ export function hubMetricsReport(now = Date.now()) {
     mainThread: {
       cpuMs: Math.round(cpuMs),
       cpuPct: Math.round((cpuMs / windowMs) * 10_000) / 100,
-      backgroundCpuMs: Math.round(callers.find((row) => row.key === BACKGROUND_KEY)?.cpuMs ?? 0),
+      backgroundCpuMs: Math.round(backgroundCpuMs),
+      // #3798 — the share of main-thread CPU a named frame (route, bus frame, timer, job) accounts for.
+      namedCpuPct: cpuMs > 0 ? Math.round(((cpuMs - backgroundCpuMs) / cpuMs) * 10_000) / 100 : 100,
     },
     callers: {
       count: calls,
@@ -62,6 +65,7 @@ export function hubLoadCheck(now = Date.now()): HealthCheck {
       busConnections: report.connections.bus,
       callsPerSec: report.callers.perSec,
       mainThreadCpuPct: report.mainThread.cpuPct,
+      mainThreadNamedCpuPct: report.mainThread.namedCpuPct,
     },
   };
 }

package/src/hub-metrics.ts

@@ -4,7 +4,7 @@
 // so caller CPU is split at marks (caller start/end, reader resumes): the CPU between two marks goes
 // to the caller that ran. docs/operations.md "Hub load metrics" describes the model and its limits.
 
-import { runWithLoopCallsite } from "./loop-block-attribution";
+import { resolveLoopCallsite, runWithLoopCallsite, type LoopCallsiteContext } from "./loop-block-attribution";
 
 const BUCKET_MS = 10_000;
 const BUCKETS = 6;
@@ -109,25 +109,45 @@ export function markCallerResume(owner: string | undefined): void {
   ledgerOwner = owner;
 }
 
-/** Run `run` as caller `key`: one request or frame, its wall time and its main-thread CPU segments. */
-export async function trackCaller<T>(key: string, run: () => T | Promise<T>): Promise<T> {
-  const startedAt = performance.now();
-  markCallerResume(key);
-  try {
-    return await run();
-  } finally {
-    // The code finishing the caller is the caller itself, so the segment since the last mark is its own.
-    const now = Date.now();
-    settleCpu(key, now);
-    ledgerOwner = undefined;
-    callerTable.add(key, now, 1, performance.now() - startedAt);
-  }
+/** #3798 — run `run` as named frame `ctx.callsite` (request, bus frame, timer tick, job): its count, wall
+ *  time and main-thread CPU. Opens the loop callsite scope, so reader and writer results inside it are
+ *  charged back to it. Returns what `run` returns (a sync body stays sync); on exit the ledger goes back
+ *  to the enclosing frame (a job inside the scheduler tick). */
+export function runInFrame<T>(ctx: LoopCallsiteContext & { callsite: string }, run: () => T): T {
+  const outer = resolveLoopCallsite();
+  return runWithLoopCallsite(ctx, () => {
+    const key = ctx.callsite;
+    const startedAt = performance.now();
+    markCallerResume(key);
+    const end = () => {
+      // The code finishing the frame is the frame itself, so the segment since the last mark is its own.
+      const now = Date.now();
+      settleCpu(key, now);
+      ledgerOwner = outer;
+      callerTable.add(key, now, 1, performance.now() - startedAt);
+    };
+    let result: T;
+    try {
+      result = run();
+    } catch (error) {
+      end();
+      throw error;
+    }
+    if (result instanceof Promise) return result.finally(end) as T;
+    end();
+    return result;
+  });
+}
+
+/** `runInFrame` as a callback, for a timer or interval body: `setInterval(framed("timer x", tick), ms)`. */
+export function framed<A extends unknown[], T>(key: string, fn: (...args: A) => T): (...args: A) => T {
+  const ctx = { callsite: key };
+  return (...args: A) => runInFrame(ctx, () => fn(...args));
 }
 
-/** `trackCaller` for a caller with no request scope of its own (a bus frame): also opens the loop
- *  callsite scope, so reader resumes and on-loop frames inside it are attributed to it. */
-export function runAsCaller<T>(callsite: string, run: () => T | Promise<T>): Promise<T> {
-  return runWithLoopCallsite({ callsite }, () => trackCaller(callsite, run));
+/** A bus frame: always a promise, so a sync throw reaches the frame queue's `catch`. */
+export async function runAsCaller<T>(callsite: string, run: () => T | Promise<T>): Promise<T> {
+  return runInFrame({ callsite }, run);
 }
 
 // ── Emits ─────────────────────────────────────────────────────────────────────────────────────────

package/src/init.ts

@@ -0,0 +1,299 @@
+// `humwick init` (#2680): one resumable install of a persistent server. It composes the existing
+// primitives (setup env file, runtime install, daemon planner) and ends with a one-time dashboard
+// login link, so nobody copies the admin token. Every failure names its step and a repair command.
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir, hostname, userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { RELAY_TOKEN_HEADER, errMessage } from "@humwick/sdk";
+import { VERSION } from "./config";
+import { createDaemonPlan, detectDaemonEnvironment, executeDaemonPlan } from "./daemon";
+import { installChannelsHostService } from "./channels-host-service";
+import { executeSetupPlan, resolveSetupPlan, setupPlanToken } from "./setup";
+import { runtimeBinPath, runtimeTarballDir } from "./runtime-prefix";
+import { isServerTarball, npmInstallIntoPrefix } from "./runtime-install";
+import { sanitizeOrchestratorId } from "./utils";
+
+const execFileAsync = promisify(execFile);
+const SERVER_PACKAGE = "@humwick/server";
+const ORCHESTRATOR_UNIT = "agent-relay-orchestrator.service";
+
+export type InitStep = "preflight" | "setup" | "runtime" | "service" | "health" | "host" | "login";
+
+export class InitStepError extends Error {
+  constructor(readonly step: InitStep, message: string, readonly repair: string) { super(message); }
+}
+
+export type InitOptions = {
+  tarballDir?: string;
+  runtimePrefix?: string;
+  envFile?: string;
+  host?: string;
+  port?: number;
+  dbPath?: string;
+  healthTimeoutMs?: number;
+};
+
+export type InitResult = {
+  ok: true;
+  version: string;
+  dashboardUrl: string;
+  loginUrl: string;
+  loginExpiresAt?: string;
+  service: { unit: string; kind: string; scope: string; file?: string };
+  envFile: string;
+  dbPath: string;
+  runtimePrefix: string;
+  runtime: { source: "registry" | "tarballs"; installed: boolean };
+  linger: "yes" | "no" | "unknown";
+  resumed: boolean;
+  /** This machine, joined as the server's first orchestrator host. */
+  host: { id: string; unit: string; joined: boolean };
+  warnings: string[];
+  next: string[];
+};
+
+type Log = (line: string) => void;
+
+async function run(command: string[], timeoutMs = 15_000): Promise<{ ok: boolean; out: string }> {
+  try {
+    const { stdout, stderr } = await execFileAsync(command[0]!, command.slice(1), { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+    return { ok: true, out: `${stdout}${stderr}`.trim() };
+  } catch (e) {
+    const err = e as { stdout?: string; stderr?: string; message: string };
+    return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}`.trim() || err.message };
+  }
+}
+
+function probeHost(host: string): string {
+  return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+
+/** True when something accepts TCP connections on host:port. */
+export function portInUse(host: string, port: number, timeoutMs = 2_000): Promise<boolean> {
+  return new Promise((done) => {
+    const socket = connect({ host: probeHost(host), port });
+    const finish = (inUse: boolean) => { socket.destroy(); done(inUse); };
+    socket.setTimeout(timeoutMs, () => finish(false));
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+  });
+}
+
+async function healthy(baseUrl: string): Promise<boolean> {
+  try {
+    return (await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(5_000) })).ok;
+  } catch {
+    return false;
+  }
+}
+
+async function unitActive(unit: string): Promise<boolean> {
+  return (await run(["systemctl", "--user", "is-active", unit])).out === "active";
+}
+
+async function preflight(port: number, host: string, unit: string, log: Log): Promise<{ linger: InitResult["linger"]; resumed: boolean }> {
+  if (process.platform === "win32") throw new InitStepError("preflight", "native Windows is not supported", "Install WSL2 (wsl --install), then run init inside the Linux distribution.");
+  if (process.platform !== "linux") throw new InitStepError("preflight", `init installs a systemd user service; ${process.platform} is not supported yet`, "Run the server in the foreground: humwick");
+  const bun = Bun.which("bun");
+  if (!bun) throw new InitStepError("preflight", "bun is not on PATH", "curl -fsSL https://bun.sh/install | bash, then open a new shell");
+  if (!Bun.which("npm")) throw new InitStepError("preflight", "npm is not on PATH (the runtime installs with npm)", "Install Node.js 20 or newer with npm, e.g. sudo apt install nodejs npm");
+  const node = await run(["node", "--version"]);
+  const nodeMajor = Number(/^v(\d+)/.exec(node.out)?.[1] ?? 0);
+  if (!node.ok || nodeMajor < 20) throw new InitStepError("preflight", `Node.js 20 or newer is required (found ${node.ok ? node.out : "none"})`, "Install Node.js 20 or newer with npm");
+  const manager = await run(["systemctl", "--user", "show-environment"]);
+  if (!manager.ok) throw new InitStepError("preflight", `no systemd user manager is reachable: ${manager.out.split("\n")[0]}`, `Log in through a real session (ssh or console), or run: sudo loginctl enable-linger ${userInfo().username}`);
+  const lingerOut = await run(["loginctl", "show-user", userInfo().username, "--property=Linger", "--value"]);
+  const linger = lingerOut.ok ? (lingerOut.out === "yes" ? "yes" : "no") : "unknown";
+  const resumed = await unitActive(unit);
+  if (!resumed && await portInUse(host, port)) {
+    const other = await healthy(`http://${probeHost(host)}:${port}`) ? "a Humwick server that init does not manage (a foreground trial?)" : "another program";
+    throw new InitStepError("preflight", `port ${port} is in use by ${other}`, `Stop it, or pass --port <free port>. To keep a trial server's data, pass --db-path <its agent-relay.db>.`);
+  }
+  log(`preflight: bun ${Bun.version}, node ${node.out}, systemd user manager, linger ${linger}, port ${port} ${resumed ? "held by this install" : "free"}`);
+  return { linger, resumed };
+}
+
+function fileDigest(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/** Copy the tarballs into the runtime's tarball dir; false when the runtime already has these exact files. */
+function stageTarballs(sourceDir: string, prefix: string): { tarballs: string[]; changed: boolean } {
+  const names = readdirSync(sourceDir).filter((name) => name.endsWith(".tgz")).sort();
+  if (!names.some(isServerTarball)) throw new InitStepError("runtime", `no humwick-server-*.tgz in ${sourceDir}`, "Pack the packages: humwick dev pack --packages sdk,server,runner,orchestrator");
+  const target = runtimeTarballDir(prefix);
+  const existing = existsSync(target) ? readdirSync(target).filter((name) => name.endsWith(".tgz")).sort() : [];
+  const same = existing.join("\n") === names.join("\n")
+    && names.every((name) => fileDigest(join(sourceDir, name)) === fileDigest(join(target, name)));
+  if (!same) {
+    mkdirSync(target, { recursive: true });
+    for (const name of existing) rmSync(join(target, name), { force: true });
+    for (const name of names) copyFileSync(join(sourceDir, name), join(target, name));
+  }
+  return { tarballs: names.map((name) => join(target, name)), changed: !same };
+}
+
+function installedServerVersion(prefix: string): string | undefined {
+  try {
+    return (JSON.parse(readFileSync(join(prefix, "node_modules", SERVER_PACKAGE, "package.json"), "utf8")) as { version?: string }).version;
+  } catch {
+    return undefined;
+  }
+}
+
+async function installRuntime(prefix: string, tarballDir: string | undefined, log: Log): Promise<boolean> {
+  const binPresent = existsSync(runtimeBinPath("agent-relay", prefix));
+  const staged = tarballDir ? stageTarballs(resolve(tarballDir), prefix) : undefined;
+  const upToDate = binPresent && installedServerVersion(prefix) === VERSION && (staged ? !staged.changed : true);
+  if (upToDate) {
+    log(`runtime: ${SERVER_PACKAGE}@${VERSION} already installed in ${prefix}`);
+    return false;
+  }
+  const specs = staged ? staged.tarballs : [`${SERVER_PACKAGE}@${VERSION}`];
+  try {
+    await npmInstallIntoPrefix(prefix, specs);
+  } catch (e) {
+    throw new InitStepError("runtime", errMessage(e), `Check network access to the npm registry, then rerun: humwick init${tarballDir ? ` --tarball-dir ${tarballDir}` : ""}`);
+  }
+  if (!existsSync(runtimeBinPath("agent-relay", prefix))) throw new InitStepError("runtime", `the install finished but ${runtimeBinPath("agent-relay", prefix)} is missing`, "Rerun init; if it repeats, remove the runtime prefix and rerun");
+  log(`runtime: installed ${staged ? `${staged.tarballs.length} packed tarballs` : `${SERVER_PACKAGE}@${VERSION}`} into ${prefix}`);
+  return true;
+}
+
+async function waitHealthy(baseUrl: string, timeoutMs: number, unit: string): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await healthy(baseUrl) && await unitActive(unit)) return;
+    await Bun.sleep(1_000);
+  }
+  throw new InitStepError("health", `${unit} is not healthy at ${baseUrl}/api/health after ${Math.round(timeoutMs / 1000)} s`, `journalctl --user -u ${unit} -n 50 --no-pager`);
+}
+
+/** A call to the local server with the admin token from the env file; it never leaves this machine. */
+async function adminRequest(step: InitStep, baseUrl: string, token: string, method: string, path: string, body?: unknown): Promise<Response> {
+  try {
+    return await fetch(`${baseUrl}${path}`, {
+      method,
+      headers: { [RELAY_TOKEN_HEADER]: token, "content-type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (e) {
+    throw new InitStepError(step, `could not reach ${baseUrl}: ${errMessage(e)}`, "Rerun init; it resumes where it stopped.");
+  }
+}
+
+/**
+ * Join this machine as an orchestrator host (#2680 v1 bar): a host-scoped, single-use bootstrap
+ * token from the local server, then the runtime's own `orchestrator install`. Gate slots and the
+ * agent cap default to sizes derived from the host's CPUs and RAM.
+ */
+async function joinLocalHost(baseUrl: string, token: string, prefix: string, fromTarballs: boolean, log: Log): Promise<InitResult["host"]> {
+  const id = sanitizeOrchestratorId(hostname());
+  const repair = "Rerun init, or in the dashboard open Orchestrators → Add";
+  const joined = !(await unitActive(ORCHESTRATOR_UNIT));
+  if (joined) {
+    const baseDir = join(homedir(), "projects");
+    const minted = await adminRequest("host", baseUrl, token, "POST", "/api/orchestrators/bootstrap", { id, baseDir, relayUrl: baseUrl });
+    if (minted.status !== 201) throw new InitStepError("host", `host bootstrap returned ${minted.status}: ${(await minted.text()).slice(0, 200)}`, repair);
+    const { bootstrapToken } = await minted.json() as { bootstrapToken: string };
+    const install = await run([runtimeBinPath("humwick", prefix), "orchestrator", "install", "--relay-url", baseUrl, "--bootstrap-token", bootstrapToken,
+      "--id", id, "--base-dir", baseDir, "--runtime-prefix", prefix, "--yes", ...(fromTarballs ? ["--skip-install"] : ["--version", VERSION])], 10 * 60_000);
+    if (!install.ok) throw new InitStepError("host", `orchestrator install failed:\n${install.out.split("\n").slice(-20).join("\n")}`, repair);
+  }
+  const deadline = Date.now() + 120_000;
+  for (;;) {
+    const list = await (await adminRequest("host", baseUrl, token, "GET", "/api/orchestrators")).json().catch(() => []) as Array<{ id: string; status?: string }>;
+    if (list.some((h) => h.id === id && h.status === "online")) break;
+    if (Date.now() > deadline) throw new InitStepError("host", `host ${id} did not come online within 120 s`, `journalctl --user -u ${ORCHESTRATOR_UNIT} -n 50 --no-pager`);
+    await Bun.sleep(1_000);
+  }
+  log(`host: ${id} ${joined ? "joined" : "already joined"} and online`);
+  return { id, unit: ORCHESTRATOR_UNIT, joined };
+}
+
+async function mintLoginLink(baseUrl: string, token: string): Promise<{ url: string; expiresAt?: string }> {
+  const response = await adminRequest("login", baseUrl, token, "POST", "/api/auth/login-links", {});
+  if (response.status !== 201) throw new InitStepError("login", `login link request returned ${response.status}: ${(await response.text()).slice(0, 200)}`, "Rerun init to get a fresh login link");
+  const body = await response.json() as { path: string; expiresAt?: number };
+  return { url: `${baseUrl}${body.path}`, ...(body.expiresAt ? { expiresAt: new Date(body.expiresAt * 1000).toISOString() } : {}) };
+}
+
+/** Install or repair a persistent server for this user and return how to open its dashboard. */
+export async function runInit(options: InitOptions = {}, log: Log = () => {}): Promise<InitResult> {
+  const plan = await resolveSetupPlan({
+    ...(options.envFile ? { envFile: options.envFile } : {}),
+    ...(options.host ? { host: options.host } : {}),
+    ...(options.port !== undefined ? { port: options.port } : {}),
+    ...(options.dbPath ? { dbPath: options.dbPath } : {}),
+    ...(options.runtimePrefix ? { runtimePrefix: options.runtimePrefix } : {}),
+  });
+  const port = Number(plan.values.PORT);
+  const host = plan.values.HOST!;
+  const daemonEnv = await detectDaemonEnvironment();
+  const bunDir = dirname(Bun.which("bun") ?? process.execPath);
+  const daemon = createDaemonPlan({ action: "install", envFile: plan.envFile, runtimePrefix: plan.runtimePrefix, port, host, pathPrefix: [bunDir], enable: true, start: true }, daemonEnv);
+  const unit = `${daemon.name}.service`;
+
+  const { linger, resumed } = await preflight(port, host, unit, log);
+
+  try {
+    await executeSetupPlan(plan);
+  } catch (e) {
+    throw new InitStepError("setup", errMessage(e), `Move the file aside, or rerun with an explicit --env-file`);
+  }
+  log(`setup: ${plan.reused ? "kept" : "wrote"} ${plan.envFile} (admin token ${plan.reused ? "unchanged" : "generated"})`);
+
+  const installed = await installRuntime(plan.runtimePrefix, options.tarballDir, log);
+
+  const previousUnit = daemon.file && existsSync(daemon.file.path) ? readFileSync(daemon.file.path, "utf8") : undefined;
+  const restart = resumed && (installed || previousUnit !== daemon.file?.content);
+  try {
+    await executeDaemonPlan(daemon);
+    if (restart) {
+      const restarted = await run(["systemctl", "--user", "restart", unit], 60_000);
+      if (!restarted.ok) throw new Error(restarted.out);
+    }
+    // The server supervises a channels-host service; `daemon install` sets it up the same way.
+    log(await installChannelsHostService({ ownerServiceName: daemon.name, runtimePrefix: plan.runtimePrefix, legacyEnvFile: plan.envFile, start: true, env: daemonEnv, onlyIfConfigured: false }));
+  } catch (e) {
+    throw new InitStepError("service", errMessage(e), `systemctl --user status ${unit} agent-relay-channels-host.service`);
+  }
+  log(`service: ${unit} enabled and ${restart ? "restarted" : resumed ? "running" : "started"}`);
+
+  const baseUrl = `http://${probeHost(host)}:${port}`;
+  await waitHealthy(baseUrl, options.healthTimeoutMs ?? 60_000, unit);
+  log(`health: ${baseUrl}/api/health ok`);
+
+  const token = setupPlanToken(plan);
+  if (!token) throw new InitStepError("setup", `${plan.envFile} has no admin token; init needs it to join this host and mint the login link`, `humwick init --env-file <a new path>, or add a token to ${plan.envFile}`);
+  const localHost = await joinLocalHost(baseUrl, token, plan.runtimePrefix, Boolean(options.tarballDir), log);
+  const login = await mintLoginLink(baseUrl, token);
+  const warnings = [...plan.warnings, ...daemon.warnings.filter((w) => !w.startsWith("Runtime binary is not installed"))];
+  if (linger !== "yes") warnings.push(`Linger is ${linger}: the service stops when you log out. Keep it running with: sudo loginctl enable-linger ${userInfo().username}`);
+  return {
+    ok: true,
+    version: VERSION,
+    dashboardUrl: `${baseUrl}/`,
+    loginUrl: login.url,
+    ...(login.expiresAt ? { loginExpiresAt: login.expiresAt } : {}),
+    service: { unit, kind: daemon.kind, scope: daemon.scope, ...(daemon.serviceFilePath ? { file: daemon.serviceFilePath } : {}) },
+    envFile: plan.envFile,
+    dbPath: plan.values.DB_PATH!,
+    runtimePrefix: plan.runtimePrefix,
+    runtime: { source: options.tarballDir ? "tarballs" : "registry", installed },
+    linger,
+    resumed,
+    host: localHost,
+    warnings,
+    next: [
+      `Open the login link (one use, 15 minutes) on this machine, or from yours through: ssh -L ${port}:127.0.0.1:${port} ${userInfo().username}@<this-host>`,
+      `This machine runs agents as host ${localHost.id}. Set up a provider in the dashboard, then spawn your first agent. More machines: Orchestrators → Add.`,
+      "Lost the link? Rerun init: it repairs the install and prints a fresh one, without changing the admin token.",
+    ],
+  };
+}

package/src/injection-sweep-pacing.ts

@@ -2,23 +2,21 @@
 // one boundary per macrotask (`forEachPaced`); a backlog (a long pause, a crash that lost many settles)
 // is drained in runs of this budget, well inside the 30s job deadline, re-run this soon while a run
 // reports `moreWork`.
-import { isSqliteBusyError, withFastFailConnection, writerLockAvailable } from "./db/connection";
+import { isSqliteBusyError } from "./db/connection";
 import { forEachPaced } from "./event-loop-yield";
 
 export const INJECTION_SWEEP_RUN_BUDGET_MS = 10_000;
 export const INJECTION_SWEEP_BACKLOG_INTERVAL_MS = 5_000;
-const SWEEP_BUSY_TIMEOUT_MS = 40;
 
-/** Each unit runs on the fast-fail connection, so a write under another writer's lock fails in 40ms
- *  instead of the shared connection's ~1s; the run then stops with `moreWork` and retries soon. */
-export async function pacedInjectionSweep<T>(items: () => Iterable<T>, unit: (item: T) => void, signal?: AbortSignal): Promise<{ moreWork: boolean }> {
+/** The gateway owns write contention; wait for each unit before continuing the bounded sweep. */
+export async function pacedInjectionSweep<T>(items: () => Iterable<T>, unit: (item: T) => unknown, signal?: AbortSignal): Promise<{ moreWork: boolean }> {
   let contended = false;
-  return forEachPaced(items, (item) => {
+  return forEachPaced(items, async (item) => {
     try {
-      withFastFailConnection(SWEEP_BUSY_TIMEOUT_MS, () => unit(item));
+      await unit(item);
     } catch (error) {
       if (!isSqliteBusyError(error)) throw error;
       contended = true;
     }
-  }, { signal, budgetMs: INJECTION_SWEEP_RUN_BUDGET_MS, ready: () => !contended && writerLockAvailable(SWEEP_BUSY_TIMEOUT_MS) });
+  }, { signal, budgetMs: INJECTION_SWEEP_RUN_BUDGET_MS, ready: () => !contended });
 }