@app-vitals/agent-lib 0.0.1 → 0.1.0

package/claude-timeout.ts

@@ -0,0 +1,10 @@
+/**
+ * The `claude -p` hard ceiling timeout (1hr) — a backstop, not the primary
+ * timeout. The idle-reset timer (`SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS`, default
+ * 25min, see `agent/src/runtime/config.ts`) is cleared/restarted on every stdout line
+ * and is what fires for the vast majority of hung/stuck sessions. This
+ * ceiling only fires for a session that stays continuously active (so the
+ * idle timer keeps resetting) but never converges — e.g. a runaway loop that
+ * keeps emitting output without ever finishing.
+ */
+export const DEFAULT_CLAUDE_TIMEOUT_MS = 3_600_000;

package/claude-timeout.unit.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CLAUDE_TIMEOUT_MS } from "./claude-timeout.ts";
+
+describe("claude-timeout", () => {
+  test("DEFAULT_CLAUDE_TIMEOUT_MS is 3_600_000 (1hr hard ceiling)", () => {
+    expect(DEFAULT_CLAUDE_TIMEOUT_MS).toBe(3_600_000);
+  });
+});

package/cli-flags.ts

@@ -0,0 +1,83 @@
+/**
+ * lib/cli-flags.ts
+ * Generalized CLI flag parser: supports both `--flag value` and
+ * `--flag=value` syntax. Generalizes `agent/src/runtime/cli-args.ts`'s narrow,
+ * hand-rolled `parseCliArgs` (which only supports `--flag value` for exactly
+ * three flags) so any script can declare the flags it cares about.
+ *
+ * Pure argv parsing — no env var fallback. Beyond string flags it supports
+ * boolean (presence) flags and repeatable (multi-value) flags. Unknown flags (not declared in
+ * `flagSpecs`) are silently ignored, matching `parseCliArgs`'s tolerant
+ * behavior. Callers that want an env var fallback (see `parseCliArgs` for
+ * that pattern) layer it on top of this helper's result.
+ */
+
+/** Parsed string-flag values, keyed by the exact flag string passed in `flagSpecs` (e.g. `"--agent-id"`). */
+type ParsedFlags<Flags extends readonly string[]> = Record<
+  Flags[number],
+  string | undefined
+>;
+
+/** Optional flag kinds beyond the plain `--flag value` string flags. */
+interface FlagKinds<
+  Bools extends readonly string[],
+  Multi extends readonly string[],
+> {
+  /** Presence-only flags: `true` when passed (bare, or `--flag=true`/`--flag=false`), else `false`. Never consume the next token. */
+  booleans?: Bools;
+  /** Repeatable value flags: every occurrence is collected in order; `[]` when absent. */
+  multi?: Multi;
+}
+
+type ParsedKinds<
+  Bools extends readonly string[],
+  Multi extends readonly string[],
+> = Record<Bools[number], boolean> & Record<Multi[number], string[]>;
+
+/**
+ * Parses `argv` for the flags declared in `flagSpecs`, supporting both
+ * `--flag value` and `--flag=value` syntax. Flags not declared in
+ * `flagSpecs` are ignored without error. A declared flag absent from `argv`
+ * (or a `--flag value` form flag with no following value) resolves to
+ * `undefined`.
+ *
+ * `kinds.booleans` and `kinds.multi` declare additional flag kinds, returned
+ * alongside the string flags (see `FlagKinds`).
+ */
+export function parseFlags<
+  const Flags extends readonly string[],
+  const Bools extends readonly string[] = readonly [],
+  const Multi extends readonly string[] = readonly [],
+>(
+  argv: readonly string[],
+  flagSpecs: Flags,
+  kinds: FlagKinds<Bools, Multi> = {},
+): ParsedFlags<Flags> & ParsedKinds<Bools, Multi> {
+  const strings = new Set<string>(flagSpecs);
+  const booleans = new Set<string>(kinds.booleans ?? []);
+  const multi = new Set<string>(kinds.multi ?? []);
+  const result: Record<string, string | boolean | string[] | undefined> = {};
+  for (const flag of strings) result[flag] = undefined;
+  for (const flag of booleans) result[flag] = false;
+  for (const flag of multi) result[flag] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    const eqIdx = arg.indexOf("=");
+    const flag = eqIdx === -1 ? arg : arg.slice(0, eqIdx);
+    const inline = eqIdx === -1 ? undefined : arg.slice(eqIdx + 1);
+
+    if (booleans.has(flag)) {
+      result[flag] = inline === undefined ? true : inline !== "false";
+    } else if (strings.has(flag) || multi.has(flag)) {
+      const value = inline ?? argv[i + 1];
+      if (value === undefined) continue;
+      if (inline === undefined) i++;
+      if (multi.has(flag)) (result[flag] as string[]).push(value);
+      else result[flag] = value;
+    }
+  }
+
+  return result as ParsedFlags<Flags> & ParsedKinds<Bools, Multi>;
+}

package/cli-flags.unit.test.ts

@@ -0,0 +1,137 @@
+/**
+ * lib/cli-flags.unit.test.ts
+ *
+ * Unit tests for the generalized CLI flag parser.
+ * Pure logic — no I/O, no env side effects.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { parseFlags } from "./cli-flags.ts";
+
+describe("parseFlags — `--flag value` syntax", () => {
+  test("parses a single flag", () => {
+    const result = parseFlags(["--agent-id", "agent-123"], ["--agent-id"]);
+    expect(result["--agent-id"]).toBe("agent-123");
+  });
+
+  test("parses multiple flags together", () => {
+    const result = parseFlags(
+      ["--agent-id", "agent-abc", "--api-url", "https://api.test.com"],
+      ["--agent-id", "--api-url", "--api-key"],
+    );
+    expect(result["--agent-id"]).toBe("agent-abc");
+    expect(result["--api-url"]).toBe("https://api.test.com");
+  });
+});
+
+describe("parseFlags — `--flag=value` syntax", () => {
+  test("parses a single flag", () => {
+    const result = parseFlags(["--db-url=postgres://localhost"], ["--db-url"]);
+    expect(result["--db-url"]).toBe("postgres://localhost");
+  });
+
+  test("parses multiple flags together", () => {
+    const result = parseFlags(
+      ["--agent-id=agent-abc", "--api-url=https://api.test.com"],
+      ["--agent-id", "--api-url"],
+    );
+    expect(result["--agent-id"]).toBe("agent-abc");
+    expect(result["--api-url"]).toBe("https://api.test.com");
+  });
+
+  test("handles an empty value after the equals sign", () => {
+    const result = parseFlags(["--db-url="], ["--db-url"]);
+    expect(result["--db-url"]).toBe("");
+  });
+});
+
+describe("parseFlags — mixed syntax", () => {
+  test("parses one flag in `--flag value` form and another in `--flag=value` form", () => {
+    const result = parseFlags(
+      ["--agent-id", "agent-abc", "--api-url=https://api.test.com"],
+      ["--agent-id", "--api-url"],
+    );
+    expect(result["--agent-id"]).toBe("agent-abc");
+    expect(result["--api-url"]).toBe("https://api.test.com");
+  });
+});
+
+describe("parseFlags — missing flag", () => {
+  test("returns undefined for a declared flag that is not present in argv", () => {
+    const result = parseFlags(
+      ["--agent-id", "agent-abc"],
+      ["--agent-id", "--api-url"],
+    );
+    expect(result["--api-url"]).toBeUndefined();
+  });
+
+  test("returns undefined for every declared flag when argv is empty", () => {
+    const result = parseFlags([], ["--agent-id", "--api-url"]);
+    expect(result["--agent-id"]).toBeUndefined();
+    expect(result["--api-url"]).toBeUndefined();
+  });
+
+  test("returns undefined when a `--flag value` form flag has no following value (end of argv)", () => {
+    const result = parseFlags(["--agent-id"], ["--agent-id"]);
+    expect(result["--agent-id"]).toBeUndefined();
+  });
+});
+
+describe("parseFlags — unknown flags are ignored (tolerant behavior)", () => {
+  test("skips a flag not declared in flagSpecs", () => {
+    const result = parseFlags(
+      ["--unknown", "value", "--agent-id", "x"],
+      ["--agent-id"],
+    );
+    expect(result["--agent-id"]).toBe("x");
+    expect(result).not.toHaveProperty("--unknown");
+  });
+
+  test("skips an unknown flag in `--flag=value` form", () => {
+    const result = parseFlags(
+      ["--unknown=value", "--agent-id=x"],
+      ["--agent-id"],
+    );
+    expect(result["--agent-id"]).toBe("x");
+    expect(result).not.toHaveProperty("--unknown");
+  });
+});
+
+describe("parseFlags — boolean flags", () => {
+  test("true when present, false when absent, never consumes next token", () => {
+    const r = parseFlags(["--dry-run", "--name", "x"], ["--name"], {
+      booleans: ["--dry-run", "--verbose"],
+    });
+    expect(r["--dry-run"]).toBe(true);
+    expect(r["--verbose"]).toBe(false);
+    expect(r["--name"]).toBe("x");
+  });
+
+  test("honours --flag=false", () => {
+    const r = parseFlags(["--dry-run=false"], [], { booleans: ["--dry-run"] });
+    expect(r["--dry-run"]).toBe(false);
+  });
+});
+
+describe("parseFlags — repeatable flags", () => {
+  test("collects every occurrence in order, both syntaxes", () => {
+    const r = parseFlags(["--repo", "a/b", "--repo=c/d", "--repo", "e/f"], [], {
+      multi: ["--repo"],
+    });
+    expect(r["--repo"]).toEqual(["a/b", "c/d", "e/f"]);
+  });
+
+  test("empty array when absent; trailing flag without value is skipped", () => {
+    expect(parseFlags([], [], { multi: ["--repo"] })["--repo"]).toEqual([]);
+    expect(parseFlags(["--repo"], [], { multi: ["--repo"] })["--repo"]).toEqual(
+      [],
+    );
+  });
+
+  test("string-only call shape is unchanged", () => {
+    expect(parseFlags(["--a", "1"], ["--a", "--b"])).toEqual({
+      "--a": "1",
+      "--b": undefined,
+    });
+  });
+});

package/clone-plan.ts

@@ -0,0 +1,73 @@
+/**
+ * lib/clone-plan.ts
+ * Pure planning helper for "which repos still need `gh repo clone`" —
+ * shared by scripts/hitl.ts (local dev-loop bootstrap),
+ * scripts/agent-workspace-pull.ts (mirrors a real agent's repos locally),
+ * and agent/src/runtime/sync-config-clone.ts (the deployed agent's config-sync
+ * auto-clone step).
+ *
+ * Extracted out of hitl.ts (AWP-1.1) so neither script reaches into the
+ * other's module — both import this shared helper instead. Lives in `lib/`
+ * (not `scripts/`) because the deployed agent imports it too and the
+ * runtime stage of agent/Dockerfile copies `lib/` but not `scripts/` — a
+ * `scripts/` import would resolve locally and crash-loop in the container.
+ */
+
+import { join } from "node:path";
+
+/**
+ * Given the configured "org/repo" list, the repos dir, and an injectable
+ * existence check, reports which repos still need cloning (and their
+ * destination path). Repos already present under reposDir are left
+ * untouched. Kept side-effect free so it's unit-testable without touching
+ * the filesystem or network.
+ */
+export function computeMissingClones(
+  repos: string[],
+  reposDir: string,
+  exists: (path: string) => boolean,
+): { repo: string; dest: string }[] {
+  return repos
+    .map((repo) => ({
+      repo,
+      dest: join(reposDir, repo.slice(repo.lastIndexOf("/") + 1)),
+    }))
+    .filter(({ dest }) => !exists(dest));
+}
+
+interface RepoNameCollision {
+  /** The later-listed repo — the one a sync should skip. */
+  repo: string;
+  /** The earlier-listed repo that already claimed the `repos/<name>` folder. */
+  collidesWith: string;
+}
+
+function splitRepo(repo: string): { owner: string; name: string } {
+  const i = repo.lastIndexOf("/");
+  return {
+    owner: repo.slice(0, i).toLowerCase(),
+    name: repo.slice(i + 1).toLowerCase(),
+  };
+}
+
+/**
+ * Reports repos whose basename matches an earlier-listed repo under a
+ * different owner (case-insensitive). `repos/<name>` is keyed by basename
+ * alone, so two such repos would share one folder and a clone/push could
+ * land on the wrong customer's repo. The later-listed repo is the collider;
+ * identical repos (same owner and name) are not collisions.
+ */
+export function findRepoNameCollisions(repos: string[]): RepoNameCollision[] {
+  const firstByName = new Map<string, { repo: string; owner: string }>();
+  const collisions: RepoNameCollision[] = [];
+  for (const repo of repos) {
+    const { owner, name } = splitRepo(repo);
+    const first = firstByName.get(name);
+    if (!first) {
+      firstByName.set(name, { repo, owner });
+    } else if (first.owner !== owner) {
+      collisions.push({ repo, collidesWith: first.repo });
+    }
+  }
+  return collisions;
+}

package/clone-plan.unit.test.ts

@@ -0,0 +1,69 @@
+/**
+ * lib/clone-plan.unit.test.ts
+ * Unit tests for computeMissingClones() — relocated from hitl.unit.test.ts
+ * (AWP-1.1) when the function was extracted out of scripts/hitl.ts into this
+ * shared module. Same assertions, moved not duplicated.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { computeMissingClones, findRepoNameCollisions } from "./clone-plan.ts";
+
+describe("computeMissingClones", () => {
+  test("returns [] for an empty repos list", () => {
+    expect(computeMissingClones([], "/ws/repos", () => false)).toEqual([]);
+  });
+
+  test("skips repos already cloned under reposDir", () => {
+    const existing = new Set(["/ws/repos/shipwright"]);
+    const missing = computeMissingClones(
+      ["app-vitals/shipwright"],
+      "/ws/repos",
+      (path) => existing.has(path),
+    );
+    expect(missing).toEqual([]);
+  });
+
+  test("includes missing repos with the correct dest path", () => {
+    const missing = computeMissingClones(
+      ["app-vitals/shipwright"],
+      "/ws/repos",
+      () => false,
+    );
+    expect(missing).toEqual([
+      { repo: "app-vitals/shipwright", dest: "/ws/repos/shipwright" },
+    ]);
+  });
+
+  test("mix of already-cloned and missing repos — only missing ones are returned", () => {
+    const existing = new Set(["/ws/repos/shipwright"]);
+    const missing = computeMissingClones(
+      ["app-vitals/shipwright", "some-org/other-repo"],
+      "/ws/repos",
+      (path) => existing.has(path),
+    );
+    expect(missing).toEqual([
+      { repo: "some-org/other-repo", dest: "/ws/repos/other-repo" },
+    ]);
+  });
+});
+
+describe("findRepoNameCollisions", () => {
+  test("reports the later-listed same-basename repo under a different owner", () => {
+    expect(
+      findRepoNameCollisions(["acme/api", "other/web", "globex/api"]),
+    ).toEqual([{ repo: "globex/api", collidesWith: "acme/api" }]);
+  });
+
+  test("is case-insensitive on owner and name", () => {
+    expect(findRepoNameCollisions(["Acme/API", "globex/api"])).toEqual([
+      { repo: "globex/api", collidesWith: "Acme/API" },
+    ]);
+    expect(findRepoNameCollisions(["Acme/api", "acme/API"])).toEqual([]);
+  });
+
+  test("ignores identical repos and distinct names", () => {
+    expect(findRepoNameCollisions(["acme/api", "acme/api"])).toEqual([]);
+    expect(findRepoNameCollisions(["acme/api", "acme/web"])).toEqual([]);
+    expect(findRepoNameCollisions([])).toEqual([]);
+  });
+});

package/default-agent-env.ts

@@ -0,0 +1,15 @@
+/**
+ * lib/default-agent-env.ts
+ * Non-secret env vars seeded onto every newly created agent so they're visible
+ * (and editable) in the agent's env view instead of being an invisible runtime
+ * fallback. Secrets (CLAUDE_CODE_OAUTH_TOKEN, GH_TOKEN, ...) are never defaulted
+ * here — see secret-env-vars.ts.
+ */
+
+/** Model used when an agent has no ANTHROPIC_MODEL set. */
+export const DEFAULT_ANTHROPIC_MODEL = "claude-sonnet-5-5";
+
+/** Env vars written to a new agent's AgentEnv at creation. Operator-supplied values win. */
+export const DEFAULT_AGENT_ENV: Readonly<Record<string, string>> = {
+  ANTHROPIC_MODEL: DEFAULT_ANTHROPIC_MODEL,
+};

package/default-agent-env.unit.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { DEFAULT_AGENT_ENV } from "./default-agent-env.ts";
+import { SECRET_ENV_VARS } from "./secret-env-vars.ts";
+
+describe("DEFAULT_AGENT_ENV", () => {
+  it("never defaults a secret-shaped env var", () => {
+    for (const key of Object.keys(DEFAULT_AGENT_ENV)) {
+      expect(SECRET_ENV_VARS as readonly string[]).not.toContain(key);
+    }
+  });
+
+  it("defaults ANTHROPIC_MODEL to a non-empty value", () => {
+    expect(DEFAULT_AGENT_ENV.ANTHROPIC_MODEL).toMatch(/^claude-/);
+  });
+
+  it("defaults ANTHROPIC_MODEL to claude-sonnet-5-5", () => {
+    expect(DEFAULT_AGENT_ENV.ANTHROPIC_MODEL).toBe("claude-sonnet-5-5");
+  });
+});

package/github-login.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns true when `s` is a valid GitHub login: alphanumeric characters and
+ * single hyphens only, no leading/trailing hyphen, no consecutive hyphens,
+ * and a max length of 39 characters (GitHub's own username constraints).
+ *
+ * Also accepts GitHub App bot logins in the format "app/<slug>", where slug
+ * follows the same validation rules as regular logins.
+ */
+export function isGithubLogin(s: string): boolean {
+  const LOGIN_PATTERN = /^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$/;
+
+  if (s.startsWith("app/")) {
+    const slug = s.slice(4);
+    return slug.length > 0 && slug.length <= 39 && LOGIN_PATTERN.test(slug);
+  }
+
+  return (
+    s.length > 0 && s.length <= 39 && LOGIN_PATTERN.test(s)
+  );
+}

package/github-login.unit.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { isGithubLogin } from "./github-login.ts";
+
+describe("isGithubLogin — valid strings", () => {
+  test("returns true for a simple login", () => {
+    expect(isGithubLogin("octocat")).toBe(true);
+  });
+
+  test("returns true for a login with hyphens and numbers", () => {
+    expect(isGithubLogin("my-org-1")).toBe(true);
+  });
+
+  test("returns true for a single character login", () => {
+    expect(isGithubLogin("a")).toBe(true);
+  });
+
+  test("returns true for a login at the max length of 39 characters", () => {
+    expect(isGithubLogin("a".repeat(39))).toBe(true);
+  });
+
+  test("returns true for app/renovate bot login", () => {
+    expect(isGithubLogin("app/renovate")).toBe(true);
+  });
+
+  test("returns true for app/dependabot bot login", () => {
+    expect(isGithubLogin("app/dependabot")).toBe(true);
+  });
+
+  test("returns true for app/<slug> with hyphens", () => {
+    expect(isGithubLogin("app/my-bot-name")).toBe(true);
+  });
+});
+
+describe("isGithubLogin — invalid strings", () => {
+  test("returns false for an empty string", () => {
+    expect(isGithubLogin("")).toBe(false);
+  });
+
+  test("returns false for a login over 39 characters", () => {
+    expect(isGithubLogin("a".repeat(40))).toBe(false);
+  });
+
+  test("returns false for a login with a leading hyphen", () => {
+    expect(isGithubLogin("-octocat")).toBe(false);
+  });
+
+  test("returns false for a login with a trailing hyphen", () => {
+    expect(isGithubLogin("octocat-")).toBe(false);
+  });
+
+  test("returns false for a login with consecutive hyphens", () => {
+    expect(isGithubLogin("octo--cat")).toBe(false);
+  });
+
+  test("returns false for a login containing an underscore", () => {
+    expect(isGithubLogin("octo_cat")).toBe(false);
+  });
+
+  test("returns false for a login containing a space", () => {
+    expect(isGithubLogin("octo cat")).toBe(false);
+  });
+
+  test("returns false for a login containing a slash", () => {
+    expect(isGithubLogin("octo/cat")).toBe(false);
+  });
+
+  test("returns false for app/ with no slug", () => {
+    expect(isGithubLogin("app/")).toBe(false);
+  });
+
+  test("returns false for app/<slug> with leading hyphen in slug", () => {
+    expect(isGithubLogin("app/-bad")).toBe(false);
+  });
+
+  test("returns false for app/<slug> with double slash", () => {
+    expect(isGithubLogin("app//x")).toBe(false);
+  });
+});

package/graceful-shutdown.ts

@@ -0,0 +1,143 @@
+/**
+ * lib/graceful-shutdown.ts
+ *
+ * Wires SIGTERM/SIGINT into a coordinated shutdown for a `Bun.serve()`-backed
+ * service: stop accepting new connections (letting in-flight requests
+ * finish), run ordered cleanup (e.g. `prisma.$disconnect()`), then exit.
+ *
+ * A hard deadline forces a non-graceful `server.stop(true)` + `exit(1)` so a
+ * stuck cleanup fn can never outlive the pod's terminationGracePeriod (30s in
+ * the Helm chart — see DBE-1.x/DBE-3.1, out of scope here).
+ *
+ * Every I/O-adjacent collaborator — the server, the signal source, the exit
+ * call, and the deadline timer — is injectable so this is unit-testable with
+ * fakes: no real signals sent, no real waiting, no `mock.module()` / global
+ * overrides (see CLAUDE.md's test isolation rule).
+ */
+
+/** Below the pod's terminationGracePeriod (30s) so a stuck cleanup can't outlive it. */
+const DEFAULT_HARD_DEADLINE_MS = 20_000;
+
+/** Mirrors Bun.serve()'s return value: stop() waits for in-flight requests, stop(true) force-closes. */
+interface ShutdownServer {
+  stop(closeActiveConnections?: boolean): unknown;
+}
+
+/** Run in order on shutdown; a throw is logged and does not block later cleanup fns or the final exit. */
+type CleanupFn = () => Promise<void>;
+
+/** Narrowed to the one method this module needs — satisfied by the real `process`. */
+interface SignalSource {
+  on(event: "SIGTERM" | "SIGINT", listener: () => void): unknown;
+}
+
+interface GracefulShutdownLogger {
+  log: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+interface GracefulShutdownOptions {
+  /** The Bun.serve() return value (or anything shaped like it). */
+  server: ShutdownServer;
+  /** Cleanup fns run sequentially, in order, after the server stops accepting new work. */
+  cleanup: CleanupFn[];
+  /** Forces stop(true) + exit(1) if the graceful path hasn't finished by then. Default 20s. */
+  hardDeadlineMs?: number;
+  /** Defaults to the real `process.exit`. */
+  exit?: (code: number) => void;
+  /** Defaults to the real global `setTimeout`. Injectable so tests can trigger the deadline manually. */
+  setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+  /** Defaults to the real global `clearTimeout`. */
+  clearTimeoutFn?: (handle: unknown) => void;
+  /** Defaults to the real `process`. Injectable so tests can fire signals without touching the real process. */
+  process?: SignalSource;
+  logger?: GracefulShutdownLogger;
+  /** Used only to prefix log lines, e.g. "admin", "task-store", "chat". */
+  serviceName?: string;
+}
+
+interface GracefulShutdown {
+  /** True once a shutdown signal has been received — gate readiness probes on this. */
+  isShuttingDown: () => boolean;
+}
+
+export function registerGracefulShutdown(
+  options: GracefulShutdownOptions,
+): GracefulShutdown {
+  const {
+    server,
+    cleanup,
+    hardDeadlineMs = DEFAULT_HARD_DEADLINE_MS,
+    exit = process.exit.bind(process),
+    // Wrapped (rather than assigned the raw global) so the interface can
+    // stay in terms of `unknown` for the timer handle without TypeScript
+    // narrowing these bindings to the global setTimeout/clearTimeout
+    // overloads' own parameter types.
+    setTimeoutFn = (fn: () => void, ms: number): unknown => setTimeout(fn, ms),
+    clearTimeoutFn = (handle: unknown): void =>
+      clearTimeout(handle as Parameters<typeof clearTimeout>[0]),
+    process: signalSource = process,
+    logger = console,
+    serviceName = "service",
+  } = options;
+
+  let shuttingDown = false;
+  let settled = false;
+
+  // Declared via `let` (not inline in the setTimeoutFn call) so a fake
+  // setTimeoutFn that invokes its callback synchronously never hits a
+  // temporal-dead-zone reference to this variable.
+  let deadlineHandle: unknown;
+
+  const finish = (code: number) => {
+    if (settled) return;
+    settled = true;
+    clearTimeoutFn(deadlineHandle);
+    exit(code);
+  };
+
+  const handleSignal = (signal: string) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    logger.log(`[${serviceName}] received ${signal}, shutting down gracefully`);
+
+    deadlineHandle = setTimeoutFn(() => {
+      logger.error(
+        `[${serviceName}] graceful shutdown exceeded ${hardDeadlineMs}ms — forcing stop`,
+      );
+      try {
+        server.stop(true);
+      } catch (err) {
+        logger.error(`[${serviceName}] error force-stopping server:`, err);
+      }
+      finish(1);
+    }, hardDeadlineMs);
+
+    void (async () => {
+      try {
+        await server.stop();
+      } catch (err) {
+        logger.error(`[${serviceName}] error stopping server:`, err);
+      }
+
+      for (const fn of cleanup) {
+        try {
+          await fn();
+        } catch (err) {
+          logger.error(`[${serviceName}] cleanup fn failed:`, err);
+        }
+      }
+
+      logger.log(`[${serviceName}] graceful shutdown complete`);
+      finish(0);
+    })();
+  };
+
+  signalSource.on("SIGTERM", () => handleSignal("SIGTERM"));
+  signalSource.on("SIGINT", () => handleSignal("SIGINT"));
+
+  return {
+    isShuttingDown: () => shuttingDown,
+  };
+}