@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/core/lifecycle.ts

@@ -0,0 +1,312 @@
+import type { Server } from 'node:http';
+import type { Database } from '../modules/database/connection.js';
+import type { AdvisoryLease } from '../modules/database/advisory-lock.js';
+import { logger } from '../shared/logging.js';
+
+/**
+ * The process lifecycle: who may drain the commit queue, and how the process
+ * stops.
+ *
+ * Hexis is single-replica by design, and nothing used to enforce it — while
+ * the deployment topology guarantees two processes on every redeploy, for as
+ * long as the outgoing container takes to exit. Two commit workers sharing
+ * one `workspaces` volume run two in-process mutexes, which is no mutual
+ * exclusion at all: `SKIP LOCKED` keeps them off the same ROW, and nothing
+ * keeps them out of the same working tree. The lease loop below is what
+ * does: the worker drains only while this process holds the commit-worker
+ * lease, and a process that does not hold it serves HTTP and declines to
+ * drain, retrying until the holder exits.
+ *
+ * And a process that could not stop cleanly dropped everything it held on
+ * the way out: an in-flight push killed mid-write, SSE streams cut without a
+ * word, the pool's connections left for the server to time out. The shutdown
+ * sequence is the order those things are let go in, bounded so a step that
+ * hangs cannot outlive the orchestrator's patience.
+ */
+
+/** The worker as the lease loop drives it. */
+export interface LeasedWorker {
+  start(): void;
+  stop(): Promise<void>;
+}
+
+export interface LeaseLoopOptions {
+  /** How often a process that does not hold the lease asks again. Default 5s. */
+  retryMs?: number;
+  /** Test seam — defaults to `setTimeout` wrapped as a promise. */
+  sleep?: (ms: number) => Promise<void>;
+  log?: (message: string) => void;
+}
+
+export interface LeaseLoopHandle {
+  /** Whether THIS process holds the lease, and so is the one draining. */
+  readonly held: boolean;
+  /** End the loop: stop the worker if it runs, release the lease. Idempotent. */
+  stop(): Promise<void>;
+}
+
+const DEFAULT_RETRY_MS = 5_000;
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Run `worker` for exactly as long as this process holds `lease`.
+ *
+ * Acquire is a poll rather than a blocking wait, because the process has
+ * other work to do meanwhile — every request it serves is served whether or
+ * not it is the one draining. On loss the worker is stopped and the loop goes
+ * back to asking; on acquisition it starts. A worker mid-`stop` is awaited
+ * before any restart, so a loss-then-reacquire within one commit's duration
+ * cannot leave two drain loops running in one process.
+ *
+ * THE ONE WINDOW THIS LEAVES OPEN. A loss is the holding session dying, and
+ * from that instant Postgres no longer holds the lock for anyone: the commit
+ * in flight here finishes (it cannot be abandoned mid-write without leaving
+ * the clone worse), and a replacement that asks in the meantime is granted.
+ * Fencing that window would need every git write to carry a token the
+ * volume checked, which a filesystem does not do. What bounds it instead:
+ * the replacement asks every `retryMs`, a commit takes seconds, and the
+ * session dies only when the database or the network does — a fault the
+ * whole deployment is already reporting, not a redeploy, where the outgoing
+ * holder releases only after its worker has stopped.
+ *
+ * THE OTHER WINDOW, ON EVERY REDEPLOY. The knowledge-base startup phase — the
+ * boot's maintenance of the protected-branch clones, and its retry while the
+ * remote is unreachable — runs in the process that is booting, whether or
+ * not that process holds the lease (see `createCoreServer`). For the seconds
+ * the phase takes, the replacement writes to the shared clones while the
+ * outgoing holder may still be committing to them. This is known and left
+ * open here: closing it means running the phase only in the holder — before
+ * the routes open when the lease is free, as the first leased task when it
+ * is not — since waiting for the lease at boot would deadlock the redeploy
+ * (the outgoing container stops only once the new one is healthy, and the
+ * new one is healthy only after boot). That reshapes the boot and is its own
+ * change.
+ */
+export function holdCommitWorkerLease(
+  lease: AdvisoryLease,
+  worker: LeasedWorker,
+  opts: LeaseLoopOptions = {},
+): LeaseLoopHandle {
+  const retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+  const sleep = opts.sleep ?? defaultSleep;
+  const log = opts.log ?? ((message: string) => logger('lifecycle').info(message));
+
+  let running = true;
+  let workerRunning = false;
+  let stopping: Promise<void> | null = null;
+  let wake: (() => void) | null = null;
+
+  const stopWorker = (): Promise<void> => {
+    if (!workerRunning) return stopping ?? Promise.resolve();
+    workerRunning = false;
+    stopping = worker
+      .stop()
+      .catch((err: unknown) => log(`commit worker stop failed: ${String(err)}`))
+      .finally(() => {
+        stopping = null;
+      });
+    return stopping;
+  };
+
+  lease.onLost(() => {
+    if (!running) return;
+    log('the commit-worker lease was lost — stopping the worker until it is held again');
+    void stopWorker();
+    wake?.();
+  });
+
+  const loop = (async () => {
+    while (running) {
+      if (stopping) await stopping;
+      if (running && !lease.held) {
+        let acquired = false;
+        try {
+          acquired = await lease.tryAcquire();
+        } catch (err) {
+          log(`could not ask for the commit-worker lease: ${String(err)}`);
+        }
+        if (acquired && running) {
+          workerRunning = true;
+          worker.start();
+          log('this process holds the commit-worker lease and is draining the queue');
+        }
+      }
+      if (!running) break;
+      await Promise.race([
+        sleep(retryMs),
+        new Promise<void>((resolve) => {
+          wake = resolve;
+        }),
+      ]);
+      wake = null;
+    }
+  })();
+
+  let stopped: Promise<void> | null = null;
+  return {
+    get held() {
+      return lease.held;
+    },
+    stop() {
+      stopped ??= (async () => {
+        running = false;
+        wake?.();
+        await loop;
+        await stopWorker();
+        await lease.release();
+      })();
+      return stopped;
+    },
+  };
+}
+
+/**
+ * A worker whose start is preceded by one asynchronous task, run under the
+ * same lease: the commit queue's recovery, which resets rows a dead holder
+ * left `running` and must therefore run only once this process IS the holder
+ * — run at boot, before the lease, it would reset rows the outgoing process
+ * is still committing. A task that fails is logged and the worker starts
+ * anyway; a stop during the task waits for it, then stops the worker.
+ */
+export function withStartupTask(
+  worker: LeasedWorker,
+  task: () => Promise<void>,
+  log: (message: string) => void = (message) => logger('lifecycle').warn(message),
+): LeasedWorker {
+  let starting: Promise<void> | null = null;
+  return {
+    start() {
+      starting ??= task()
+        .catch((err: unknown) => log(`startup task failed; the worker starts regardless: ${String(err)}`))
+        .then(() => worker.start())
+        .finally(() => {
+          starting = null;
+        });
+    },
+    async stop() {
+      if (starting) await starting;
+      await worker.stop();
+    },
+  };
+}
+
+export interface ShutdownDeps {
+  /** The listening server — stops accepting, then drops what is connected. */
+  server: Pick<Server, 'close' | 'closeAllConnections'>;
+  /** The lease loop from {@link holdCommitWorkerLease}: its stop finishes the in-flight commit and releases the lease. */
+  commitWorker: Pick<LeaseLoopHandle, 'stop'>;
+  /**
+   * Background work to wind down before the pool goes — the join-request
+   * sweep and its jobs, today. The timer is stopped after the server so
+   * nothing new is scheduled, then the jobs already running are awaited
+   * (within the budget) so the pool is not ended under a clone or a push
+   * that is still writing to it. Optional: a caller that has not built them
+   * yet passes nothing.
+   */
+  backgroundJobs?: { stopSweeping(): void; drain(): Promise<void> };
+  /** The database — its pool is ended last, once nothing above can still need it. */
+  db: Pick<Database, '$client'>;
+  log?: (message: string) => void;
+}
+
+export interface ShutdownOptions {
+  /**
+   * Total time the sequence may take. Default 8s: Docker's `stop_grace_period`
+   * is 10s and none of the compose files raise it, so past that the container
+   * is killed anyway, and a sequence still running then has achieved nothing
+   * a kill would not.
+   */
+  deadlineMs?: number;
+}
+
+const DEFAULT_SHUTDOWN_DEADLINE_MS = 8_000;
+
+/** Await `promise` for at most `ms`; on expiry log and move on rather than hang the exit. */
+async function bounded(promise: Promise<unknown>, ms: number, label: string, log: (m: string) => void): Promise<void> {
+  let timer: NodeJS.Timeout | undefined;
+  const expired = new Promise<'expired'>((resolve) => {
+    timer = setTimeout(() => resolve('expired'), Math.max(0, ms));
+  });
+  try {
+    const outcome = await Promise.race([promise.then(() => 'done' as const), expired]);
+    if (outcome === 'expired') log(`${label} did not finish within ${ms}ms — continuing the shutdown`);
+  } catch (err) {
+    log(`${label} failed: ${String(err)}`);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * The shutdown sequence, as a function the process's signal handlers call.
+ * Idempotent: a second signal awaits the sequence already running rather than
+ * starting another.
+ *
+ * The order is the point:
+ *
+ *   1. Stop accepting, and drop every open connection. SSE streams end here;
+ *      the browser's EventSource reconnects on its own, and the replacement
+ *      process — whose replay buffer is empty — answers the reconnect with a
+ *      resync, which is the behaviour the event bus already defines for it.
+ *      No stream is told anything, because nothing it could be told would
+ *      beat that.
+ *   2. Stop the commit worker, which finishes the commit it is in the middle
+ *      of, then release the lease so the replacement can take it. A commit
+ *      that cannot finish inside the deadline is abandoned as `running` in the
+ *      queue, and the startup reconcile of the next boot returns it to
+ *      `pending` — the recovery the queue has always had for a process that
+ *      died mid-commit, now the exception rather than the rule.
+ *   3. End the pool.
+ */
+export function createShutdown(
+  deps: ShutdownDeps,
+  opts: ShutdownOptions = {},
+): (reason: string) => Promise<void> {
+  const log = deps.log ?? ((message: string) => logger('lifecycle').info(message));
+  const deadlineMs = opts.deadlineMs ?? DEFAULT_SHUTDOWN_DEADLINE_MS;
+  let inFlight: Promise<void> | null = null;
+
+  return (reason: string) => {
+    inFlight ??= (async () => {
+      const startedAt = Date.now();
+      const remaining = () => Math.max(0, deadlineMs - (Date.now() - startedAt));
+      log(`shutting down: ${reason}`);
+
+      await bounded(
+        new Promise<void>((resolve) => {
+          deps.server.close(() => resolve());
+          deps.server.closeAllConnections();
+        }),
+        remaining(),
+        'closing the server',
+        log,
+      );
+      // Immediately after the server, and BEFORE the commit worker is stopped.
+      // Stopping that worker awaits an in-flight commit and can spend most of
+      // the remaining budget doing it; a sweep tick firing inside that window
+      // reads the still-open pool and starts fresh clone/commit/push work that
+      // the `process.exit()` at the end of the sequence then kills mid-git.
+      // Nothing new can be recorded once the server is closed, so this is the
+      // earliest point the interval is dead weight. Synchronous and unfailing
+      // — it just clears an interval — so it needs no budget of its own.
+      deps.backgroundJobs?.stopSweeping();
+      // Clearing the interval stops future ticks; it does nothing to a job a
+      // tick already started, which holds a claim it heartbeats through the
+      // pool and is mid-clone or mid-push. Awaited here, in the budget: a job
+      // that finishes releases or marks its row; one that cannot in time is
+      // killed with the process and its claim goes stale for the next sweep
+      // — which is the recovery every crash already gets.
+      if (deps.backgroundJobs) {
+        await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
+      }
+      await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
+      await bounded(deps.db.$client.end(), remaining(), 'ending the database pool', log);
+
+      log(`shutdown complete in ${Date.now() - startedAt}ms`);
+    })();
+    return inFlight;
+  };
+}

package/src/core/public-config.ts

@@ -0,0 +1,86 @@
+import { DEFAULT_BRANCH, PROTECTED_BRANCHES, currentKbLayout } from '@bevel-software/platform-shared';
+
+/** The two addresses the server derives once and hands to {@link publicConfig}. */
+export interface PublicConfigAddresses {
+  /** The per-user marketplace git remote, userinfo stripped. */
+  marketplaceGitUrl: string;
+  /** This deployment's MCP endpoint, the same value the OAuth metadata publishes. */
+  mcpUrl: string;
+}
+
+/**
+ * The body of the unauthenticated `GET /api/config`: the handful of facts the
+ * browser needs BEFORE it can render anything, and what a local bridge
+ * learns about a deployment from one request.
+ *
+ * Unauthenticated on purpose. The login screen, the router and every module
+ * that reads `DEFAULT_BRANCH` are loaded before a session exists, so a gated
+ * endpoint could not answer in time. What it discloses is two branch names,
+ * which every change request and every URL already shows to anyone who does
+ * get in, and nothing about the repository they live in.
+ *
+ * This replaces baking the values into the frontend bundle at build time.
+ * One artifact now serves any deployment, and renaming a branch no longer
+ * means a rebuild.
+ *
+ * A pure function of its inputs, so the payload is testable without a server.
+ */
+export function publicConfig({ marketplaceGitUrl, mcpUrl }: PublicConfigAddresses) {
+  return {
+    branchModel: {
+      defaultBranch: DEFAULT_BRANCH,
+      protectedBranches: [...PROTECTED_BRANCHES],
+    },
+    /**
+     * The three renameable KB roots, for the same reason as the branch
+     * model: the file tree, the library router and every path rule read
+     * them, and they used to be compile-time constants.
+     */
+    kbLayout: currentKbLayout(),
+    /**
+     * The per-user marketplace git remote (see modules/marketplace). Same
+     * derivation as `mcpUrl`: our address, userinfo stripped; the caller
+     * adds their own connection key.
+     */
+    marketplaceGitUrl,
+    /**
+     * The same value the OAuth metadata publishes (see `mcpResourceUrl`).
+     *
+     * The frontend used to build this from `window.location.origin`, which
+     * is the browser's idea of our address rather than ours. The two agree
+     * on a simple deployment and disagree behind a proxy, on a second
+     * domain, or on an internal hostname, and the one that decides whether
+     * a connection works is this one.
+     *
+     * That was survivable while every surface was copy-paste: a human sees
+     * the host before pasting it. It stops being survivable the moment we
+     * hand the URL to a third party (a connector install link), where
+     * nobody reads it and the failure surfaces inside someone else's UI.
+     */
+    mcpUrl,
+    /**
+     * This deployment serves `GET /api/agent/instructions` and sends
+     * instructions on every MCP handshake (see modules/agent-instructions).
+     * The local `hexis-mcp` bridge fetches the text only when this is
+     * advertised; its absence is how an older deployment looks. A capability
+     * flag rather than a probe, because an unknown `/api/*` path on an older
+     * deployment falls through to the JWT mounts and answers 401, which the
+     * bridge would read as an expired sign-in.
+     */
+    agentInstructions: true as const,
+    /**
+     * This deployment serves `GET /api/agent/catalog-revision`, the per-caller
+     * fingerprint of the released tool manuals and skills (see
+     * core/catalog-revision.ts). The local `hexis-mcp` bridge polls it to
+     * learn that a manual or a skill changed under a connection nobody can
+     * push to; without it the bridge keeps the toolset it started with.
+     *
+     * A capability flag rather than a probe, for exactly the reason above: an
+     * unknown `/api/*` path on an older deployment falls through to the JWT
+     * mounts and answers 401, and a poller reading that as a dead credential
+     * would tell the user to mint a new key for a route that simply is not
+     * there.
+     */
+    catalogRevision: true as const,
+  };
+}

package/src/core/readiness.ts

@@ -0,0 +1,123 @@
+import { sql } from 'drizzle-orm';
+import type { Database } from '../modules/database/connection.js';
+
+/**
+ * The readiness answer: what `GET /api/ready` reports, computed when asked.
+ *
+ * `/api/health` says the process is up, and that is all it has ever said —
+ * it answers `ok` whenever Express does. Nothing about the deployment told
+ * anyone when it had stopped committing: a queue that no longer drains looks
+ * exactly like an idle one from outside, and the one signal the worker
+ * raises for a terminal failure goes to stderr in a core deployment. This
+ * endpoint exists so that a deployment can say it has degraded, and so that
+ * one number — the age of the oldest commit still waiting — can be alerted on.
+ *
+ * EVERY FACT IS COMPUTED ON THE REQUEST. None is stored, because a stored
+ * verdict is stale the moment its inputs change and brings invalidation and
+ * retention along with it for nothing: each of these is a cheap read, and the
+ * probe is the one place that asks.
+ *
+ * WHAT DEGRADES AND WHAT FAILS. Only an unreachable database fails the
+ * probe with a 503: without it nothing here can serve. Everything else marks
+ * the answer `degraded` and stays 200. This is deliberate. An orchestrator
+ * treats a failing readiness probe as "restart me", and a restart cures none
+ * of the other conditions — a git host that has stopped answering, a full
+ * volume, a queue that has fallen behind — while it does throw away every
+ * in-flight request and the replay buffer. Those are conditions to page on,
+ * not to restart for; the numbers are in the body for exactly that.
+ *
+ * WHAT IS DISCLOSED. The probe is unauthenticated, as a probe must be for the
+ * thing that calls it, so it discloses only what an operator needs and nothing
+ * that names a person, a path or a workspace: booleans, ages and byte counts.
+ * The build sha is already public on `/api/health`.
+ */
+
+export interface ReadinessDeps {
+  db: Pick<Database, 'execute'>;
+  /** When the oldest commit still waiting was queued, or null when none waits. */
+  oldestQueuedAt(): Promise<Date | null>;
+  /** Whether THIS process holds the commit-worker lease and is draining. */
+  drains(): boolean;
+  /** The most recent attempt to reach the git remote, and whether it succeeded. */
+  lastRemoteContact(): { at: number; ok: boolean } | null;
+  /** Bytes still writable on the volume holding the workspaces. */
+  freeBytes(): Promise<number | null>;
+  now?: () => number;
+}
+
+export interface ReadinessReport {
+  status: 'ok' | 'degraded' | 'unavailable';
+  checks: {
+    database: { ok: boolean };
+    /** Age in seconds of the oldest waiting commit; null when nothing waits. */
+    commitQueue: { ok: boolean; oldestPendingSeconds: number | null; draining: boolean };
+    /** Seconds since the last attempt to reach the remote; null before the first. */
+    gitRemote: { ok: boolean; lastContactSeconds: number | null };
+    disk: { ok: boolean; freeBytes: number | null };
+  };
+  timestamp: number;
+}
+
+/**
+ * A commit older than this is one the deployment should be paged about: at a
+ * healthy pace a save lands in seconds, and a backlog of minutes means either
+ * the worker is not draining or its remote is refusing it. Ten minutes leaves
+ * room for a large bulk change and a slow push without crying wolf.
+ */
+export const QUEUE_AGE_DEGRADED_MS = 10 * 60 * 1000;
+
+/**
+ * Below this much free space the next clone or pack write is a coin toss.
+ * One gibibyte is more than any single operation here needs and well under
+ * any volume a deployment would provision, so crossing it is a warning with
+ * time left to act.
+ */
+export const DISK_FREE_DEGRADED_BYTES = 1024 * 1024 * 1024;
+
+export function createReadiness(deps: ReadinessDeps): () => Promise<ReadinessReport> {
+  const now = deps.now ?? Date.now;
+
+  return async () => {
+    const at = now();
+
+    const database = await deps.db
+      .execute(sql`select 1`)
+      .then(() => ({ ok: true }))
+      .catch(() => ({ ok: false }));
+
+    // Each fact is asked for independently and a failure to answer counts
+    // against that fact alone, never against the others.
+    const oldest = await deps.oldestQueuedAt().catch(() => null);
+    const oldestPendingSeconds = oldest === null ? null : Math.max(0, Math.floor((at - oldest.getTime()) / 1000));
+    const commitQueue = {
+      ok: oldestPendingSeconds === null || oldestPendingSeconds * 1000 < QUEUE_AGE_DEGRADED_MS,
+      oldestPendingSeconds,
+      draining: deps.drains(),
+    };
+
+    const contact = deps.lastRemoteContact();
+    const gitRemote = {
+      // No attempt yet is not a failure: a freshly booted process has had no
+      // reason to reach the remote, and saying "degraded" for that would
+      // page on every deploy.
+      ok: contact === null || contact.ok,
+      lastContactSeconds: contact === null ? null : Math.max(0, Math.floor((at - contact.at) / 1000)),
+    };
+
+    const free = await deps.freeBytes().catch(() => null);
+    const disk = {
+      // A volume that cannot say is not known to be full; the number is null
+      // and the fact stays ok rather than paging on an unanswerable probe.
+      ok: free === null || free >= DISK_FREE_DEGRADED_BYTES,
+      freeBytes: free,
+    };
+
+    const status: ReadinessReport['status'] = !database.ok
+      ? 'unavailable'
+      : commitQueue.ok && gitRemote.ok && disk.ok
+        ? 'ok'
+        : 'degraded';
+
+    return { status, checks: { database, commitQueue, gitRemote, disk }, timestamp: at };
+  };
+}

package/src/core-config.ts

@@ -3,10 +3,17 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultKbTemplateDir } from './assets.js';
 import { assertKeyDecodesTo32Bytes } from './shared/token-crypto.js';
+import { DEFAULT_GIT_TIMEOUT_MS } from './modules/workflow/git/node-git-runner.js';
+import { logger } from './shared/logging.js';
+
+const log = logger('config');
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 dotenv.config({ path: path.resolve(__dirname, '../../../.env') });
 
+/** The largest delay a Node timer honours; anything larger fires at once. */
+const MAX_TIMER_MS = 2_147_483_647;
+
 /**
  * The Postgres connection string: `DATABASE_URL` if given, otherwise built
  * from the `POSTGRES_*` parts.
@@ -36,6 +43,20 @@ export function resolveDatabaseUrl(env: NodeJS.ProcessEnv = process.env): string
   return `postgresql://${user}:${password}@${host}:${port}/${database}`;
 }
 
+/**
+ * `url` with any `user:pass@` removed and EVERY OTHER BYTE KEPT. Not a
+ * `new URL(...).toString()` round-trip: that drops a default port, lowercases
+ * the host and re-encodes, and a provider comparing redirect URIs as exact
+ * strings (Entra, Okta) would refuse the one an admin registered.
+ *
+ * Through the LAST `@` before the path, query or fragment: a password can
+ * carry an unencoded `@` of its own (`https://u:p@ss@host`), and stopping at
+ * the first would leave `ss@` — most of the credential — in what is kept.
+ */
+export function withoutUserinfo(url: string): string {
+  return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, '$1');
+}
+
 /**
  * Configuration for the CORE platform: the git-backed workspace/workflow,
  * skills, tools, secrets vault, access control, and the MCP surface. Contains
@@ -225,6 +246,17 @@ export class CoreConfig {
    * to `1` instead — see the derivation in the constructor.
    */
   readonly trustProxy: string;
+  /**
+   * Deadline in milliseconds on every git command, after which the child is
+   * killed and the call fails (see `modules/workflow/git/node-git-runner.ts`).
+   *
+   * Configurable because the right ceiling depends on the deployment's own git
+   * host and the size of its knowledge base: a first clone over a slow link can
+   * legitimately take minutes, and a deadline that cuts it off turns a working
+   * deployment into a broken one. Without a knob the remedy for a false timeout
+   * would be a release.
+   */
+  readonly gitTimeoutMs: number;
   /**
    * Public base URL of THIS backend, used to build OAuth redirect URIs.
    * Must match a redirect URI registered with the OAuth provider(s).
@@ -238,6 +270,14 @@ export class CoreConfig {
    * development.
    */
   readonly publicFrontendUrl: string;
+  /**
+   * The public frontend address when one is actually configured
+   * (`PUBLIC_FRONTEND_URL`, `https://<DOMAIN>`, or a production
+   * `PUBLIC_BACKEND_URL`), else null. Unlike `publicFrontendUrl` it never
+   * falls back to a local default, so a link built from it is one a person
+   * outside the deployment can open.
+   */
+  readonly configuredPublicFrontendUrl: string | null;
 
   constructor() {
     this.port = parseInt(process.env.PORT || '3001', 10);
@@ -369,12 +409,30 @@ export class CoreConfig {
     // stays expressible.
     const domain = (process.env.DOMAIN || '').trim();
     this.trustProxy = (process.env.TRUST_PROXY || (domain ? '1' : '')).trim();
-    this.publicBackendUrl = (
-      process.env.PUBLIC_BACKEND_URL ||
-      (domain ? `https://${domain}` : `http://localhost:${this.port}`)
-    )
+    // A non-numeric or non-positive value is a misconfiguration whose effect
+    // would be "no deadline at all", so it falls back to the default rather
+    // than being honoured. So does one past Node's largest timer delay
+    // (2^31-1 ms, ~24.8 days): `setTimeout` silently coerces that to 1ms,
+    // which would time every git command out on the spot.
+    const gitTimeout = Number(process.env.GIT_TIMEOUT_MS);
+    this.gitTimeoutMs =
+      Number.isFinite(gitTimeout) && gitTimeout > 0 && gitTimeout <= MAX_TIMER_MS
+        ? gitTimeout
+        : DEFAULT_GIT_TIMEOUT_MS;
+    // Userinfo stripped HERE, once, so no consumer can hand it on: a
+    // `PUBLIC_BACKEND_URL` spelled with `user:pass@` (a basic-auth proxy in
+    // front of the deployment) must not reach an identity provider in a
+    // redirect URI, a third-party OAuth provider, or `/api/config`.
+    const backendUrl = (process.env.PUBLIC_BACKEND_URL || (domain ? `https://${domain}` : `http://localhost:${this.port}`))
       .trim()
       .replace(/\/+$/, '');
+    this.publicBackendUrl = withoutUserinfo(backendUrl);
+    if (this.publicBackendUrl !== backendUrl) {
+      // Said out loud — it is likely a mistake — but never with the credential.
+      log.warn(
+        `PUBLIC_BACKEND_URL contains credentials (user:pass@); they are ignored and the public address is ${this.publicBackendUrl}.`,
+      );
+    }
     // Unset, the frontend origin is the backend's own in production (the
     // backend serves the built SPA — under docker compose this is what makes
     // a bare `up -d` bounce logins back to the right place), and Vite's dev
@@ -389,6 +447,14 @@ export class CoreConfig {
     )
       .trim()
       .replace(/\/+$/, '');
+    // Only an address someone set counts — the localhost fallbacks above are
+    // no link to hand a person. In production an explicit backend origin is
+    // the frontend's too (the backend serves the SPA).
+    const frontendConfigured =
+      Boolean((process.env.PUBLIC_FRONTEND_URL || '').trim()) ||
+      Boolean(domain) ||
+      (this.nodeEnv === 'production' && Boolean((process.env.PUBLIC_BACKEND_URL || '').trim()));
+    this.configuredPublicFrontendUrl = frontendConfigured ? this.publicFrontendUrl : null;
     // Parse-validate so a malformed URL fails at boot rather than producing a
     // broken OAuth redirect later. (We intentionally don't force https / reject
     // localhost in production: local Docker runs prod mode over http://localhost.)

package/src/index.ts

@@ -25,6 +25,20 @@ export {
   type ToolSurfaceCtx,
 } from './core/create-core-server.js';
 export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+// Logging: the contract, the slot a shell installs its sink into, and the
+// tagged-logger lookup every module logs through. See shared/logging.ts.
+export { setLogger, logger, createConsoleLogger } from './shared/logging.js';
+export type { ILogger, LogFields } from './shared/logger.contract.js';
+// The shutdown sequence a shell's signal handlers call, and the lease-loop
+// handle type `CoreServices.commitWorker` carries.
+export {
+  createShutdown,
+  withStartupTask,
+  type ShutdownDeps,
+  type ShutdownOptions,
+  type LeaseLoopHandle,
+  type LeasedWorker,
+} from './core/lifecycle.js';
 
 // Packaged assets (migrations/, kb-template/) + the migration runners.
 export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
@@ -49,6 +63,7 @@ export {
 export type {
   IExternalApiKeyService,
   ExternalApiKeySummary,
+  AdminExternalApiKeySummary,
 } from './modules/tool-auth/external-api-key.interface.js';
 
 // Key port/seam types an overlay implements.