feat(gateway): warn when a worker joins with a lower lease.maxTtlMs

ADR 0005 §15 tells the operator to keep a gateway's lease.maxTtlMs at or
below every worker's, because a fleet lease's width is decided at the
gateway (admission) but dispatched as an ordinary lease.request a
lower-capped worker still refuses. Nothing enforced or surfaced that
mismatch: an operator who got it wrong only saw gateway-accepted requests
fail on some machines and not others, with the cause sitting unreported at
the exact point (a worker's view) where it was already visible.

The user decided: warn, don't clamp. Clamping the gateway's cap to the
minimum of its workers' would contradict "a fleet lease's width is decided
at the gateway" and make fleet policy drift as machines connect and
disconnect.

What changed:
- workerViewSchema gains an optional `lease: { maxTtlMs }` (schemas.ts),
  projected in WorkerLink#rebuildView alongside the existing
  `downloads.policy` -- the same already-fetched config.get payload, no new
  round trip.
- WorkerRegistry#refresh compares an incoming worker's lease.maxTtlMs
  against the gateway's own (threaded in as `leaseMaxTtlMs`, from
  GatewayService down to config.lease.maxTtlMs in daemon/main.ts) and logs
  a warning naming the worker (id + label), both values, and what it means.
  No bus event: this is an operator configuration warning, not a business
  fact about the fleet (docs/agent-rules/events.md), matching the
  precedent in core/config.ts's worker-only-key warning.

Where the transition is detected, and why: inside WorkerRegistry#refresh,
by comparing the incoming lease.maxTtlMs against the *previous* view's own
value rather than tracking separate state. config.get (and so
lease.maxTtlMs) is re-read on every periodic backstop tick alongside the
catalog, not only at connect (GatewayService#runTick calls
link.refresh({ includeCatalog: true }) for every link) -- so "only warn
once per connect" would have been wrong. Comparing against the previous
value gets the right behavior for free: a worker's first refresh after
connecting has no previous lease.maxTtlMs to match, so it warns the moment
a low cap is first reported; an unchanged later refresh finds the same
value already recorded and says nothing new; a cap that drops further
warns again, since that is itself a new fact.

Tests (worker-registry.test.ts, service.test.ts at both the registry-unit
and full GatewayService-integration levels): a worker below the gateway's
cap warns; one at or above it does not; one reporting no cap at all
(config === undefined, the same condition that already leaves
downloads.policy unset) neither warns nor throws; an unchanged refresh
does not repeat the warning; a cap dropping further while already below
warns again. Reverted the registry/service/schema/link changes and
re-ran: all six new tests fail with named assertions (`expected [] to
have a length of 1`, `expected undefined to be defined`), never a bare
timeout.

Docs updated as part of this same change (the ADR is the specification
here): ADR 0005 §15 gets the warn-not-clamp sentence, and §7's "exactly
one field" becomes "two fields" now that lease.maxTtlMs travels the same
path as downloads.policy; docs/CONFIGURATION.md's lease.maxTtlMs section
gets a paragraph on the new warning. docs/adr/0005-gateway-and-worker-modes.md
has not been merged to main -- amending it here revises an unmerged record
in place, not an accepted decision. No known-pitfalls.md entry: this is a
decided, warn-only design (not an accepted gap with a planned fix), so
there is nothing pending to record there.

pnpm check is green (typecheck, typecheck:e2e, lint, format:check, unit
tests, e2e tests). Protocol range unchanged ({ min: 5, max: 5 }) -- this
is an additive schema field, no wire renegotiation involved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MA98m7ua7qvDFZjxFaww6Z

Author: claude

docs/CONFIGURATION.md

@@ -198,6 +198,15 @@ worker's**, or requests that the gateway happily accepts will fail on
 whichever machine they land on, which is the least debuggable version of this
 mistake.
 
+The gateway does not enforce this for you — clamping its own cap to the
+minimum of its workers' would make fleet policy shift as machines come and
+go, and the gateway's cap is meant to be explicit policy, not a computed
+minimum. What it does instead: when a worker's own reported `lease.maxTtlMs`
+is below the gateway's, the gateway logs a warning naming the worker and
+both values the moment that worker's view is built (at join, and again if
+the mismatch changes on a later refresh) — loud enough to catch the
+misconfiguration without silently overriding it.
+
 Everything else — `capacity.*`, `idle.*`, `warmPool.*`, `health.*`,
 `stalledTransition.*`, `drivers.*`, `ios.slim.*`, `diskPressure.*`,
 `downloads.*`, and the worker-side `gateway.url`/`gateway.token`/

docs/adr/0005-gateway-and-worker-modes.md

@@ -178,11 +178,13 @@ physical machine.
    slow periodic tick as a backstop. `config.get` is read **once per
    connect** and not on the refresh path — config is daemon input, read at
    start, so a worker whose configuration changed has restarted and
-   reconnected anyway — and the gateway keeps exactly one field out of it:
-   the worker's effective `downloads.policy`, which the view carries and
-   routing (requirement 13) needs in order to know whether a worker may
-   install a missing runtime at all. It is a routing input, never an
-   override: the worker still clamps `allowDownload` through its own policy.
+   reconnected anyway — and the gateway keeps two fields out of it: the
+   worker's effective `downloads.policy`, which the view carries and routing
+   (requirement 13) needs in order to know whether a worker may install a
+   missing runtime at all (a routing input, never an override: the worker
+   still clamps `allowDownload` through its own policy); and the worker's own
+   `lease.maxTtlMs`, which the view also carries so the gateway can warn when
+   it is lower than the gateway's own (requirement 15).
 
 ### Worker registry (gateway side)
 
@@ -283,7 +285,17 @@ physical machine.
     lease's width is decided at the gateway — but what it dispatches is an
     ordinary `lease.request`, so a worker with a lower cap still refuses it.
     Keep a gateway's `lease.maxTtlMs` at or below every worker's, or
-    requests the gateway accepts fail on whichever machine they land on.
+    requests the gateway accepts fail on whichever machine they land on. The
+    gateway warns rather than clamps: when a worker's view is built and its
+    own reported `lease.maxTtlMs` is below the gateway's, the gateway logs a
+    warning naming the worker and both values, at join and again if the
+    mismatch changes on a later refresh. It does not lower its own cap to
+    match — that would make a fleet's policy drift with whichever machines
+    happen to be connected, contradicting "a fleet lease's width is decided
+    at the gateway" two sentences up — so the requests already described
+    above still fail on the low-capped worker; the warning only makes the
+    cause visible where it was decided, rather than leaving an operator to
+    find it from the failures downstream.
 16. A gateway lease id names its worker, so renew, release, and reads route
     without consulting any state of its own: it is the owning worker's id,
     then a `.`, then the worker's own lease id, and routing **splits on the

src/contract/schemas.ts

@@ -557,6 +557,18 @@ export const workerViewSchema = z.object({
    * that failed).
    */
   downloads: z.object({ policy: z.enum(["never", "on-request", "always"]) }).optional(),
+  /**
+   * The worker's own `lease.maxTtlMs`, read once with `config.get` when the uplink connects
+   * (and again on the periodic backstop tick, alongside the catalog and `downloads.policy`
+   * above -- see `WorkerLink#rebuildView`). ADR 0005 §15: a fleet lease's width is decided at
+   * the gateway's own `lease.maxTtlMs`, but what the gateway dispatches is an ordinary
+   * `lease.request`, so a worker whose own cap is lower still refuses a request the gateway
+   * already accepted -- this field is what lets the gateway notice that at the worker, rather
+   * than only in the operator's documentation. Absent for a worker whose `config.get` the
+   * gateway could not read (an incompatible worker, a call that failed, or one older than this
+   * field).
+   */
+  lease: z.object({ maxTtlMs: z.number() }).optional(),
   /** The worker's *own* queue depth -- local agents on that machine. The gateway's fleet queue
    * is reported separately by `status.get` and arrives with #118. */
   queueDepth: z.number().optional(),

src/daemon/main.ts

@@ -538,6 +538,9 @@ async function startGatewayDaemon(options: GatewayDaemonOptions): Promise<Daemon
       path: join(dataDirectory, "workers.json"),
     }),
     eventBus,
+    // ADR 0005 §15: this gateway's own cap, compared against every connected worker's own
+    // reported one so the registry can warn when a worker's is lower.
+    leaseMaxTtlMs: config.lease.maxTtlMs,
     logger: logger.child("gateway"),
     principal: `gw:${instanceId}`,
     retentionMs: config.gateway.disconnectedRetentionMs,

src/gateway/dispatcher.test.ts

@@ -72,6 +72,7 @@ function harness() {
     clock,
     drainStore: new MemoryDrainStore(),
     eventBus,
+    leaseMaxTtlMs: gatewayConfig.lease.maxTtlMs,
     retentionMs: 24 * 60 * 60_000,
   });
   const tokens = new FakeTokens();

src/gateway/service.test.ts

@@ -23,6 +23,8 @@ import { MAX_CONSECUTIVE_REFRESH_TIMEOUTS, WORKER_CALL_TIMEOUT_MS } from "./work
 
 const RETENTION_MS = 24 * 60 * 60_000;
 const REFRESH_MS = 30_000;
+/** Matches `core/config.ts`'s own default (ADR 0005 §15's own cap). */
+const DEFAULT_LEASE_MAX_TTL_MS = 4 * 60 * 60_000;
 
 /** H4: records every line at `warn` and `error` (the levels a link's own failure paths use), so
  * a test can assert what a failure was actually logged *as* -- not just that something failed. */
@@ -45,6 +47,7 @@ function fleet(
     readonly authenticate?: (
       credential: string | undefined,
     ) => UplinkAuthOutcome | UplinkAuthResult;
+    readonly leaseMaxTtlMs?: number;
     readonly logger?: Logger;
     readonly refreshIntervalMs?: number;
   } = {},
@@ -73,6 +76,7 @@ function fleet(
     },
     drainStore: new MemoryDrainStore(),
     eventBus,
+    leaseMaxTtlMs: options.leaseMaxTtlMs ?? DEFAULT_LEASE_MAX_TTL_MS,
     ...(options.logger === undefined ? {} : { logger: options.logger }),
     principal: "gw:instance-1",
     refreshIntervalMs: options.refreshIntervalMs ?? REFRESH_MS,
@@ -300,6 +304,75 @@ describe("GatewayService", () => {
     await harness.service.stop();
   });
 
+  describe("warning on a worker's lower lease.maxTtlMs (ADR 0005 §15)", () => {
+    it("warns once the joining worker's own config.get reports a lower cap", async () => {
+      const logger = new RecordingLogger();
+      const harness = fleet({ leaseMaxTtlMs: 3_600_000, logger });
+      await harness.service.start();
+      const worker = new ScriptedWorkerClient();
+      worker.leaseMaxTtlMs = 1_800_000;
+
+      await harness.join("wrk_1", worker, "mac-mini-1");
+      await vi.waitFor(() => expect(harness.service.workers.view("wrk_1")?.lease).toBeDefined());
+
+      const warning = logger.warnings.find((entry) => entry.fields?.workerId === "wrk_1");
+      expect(warning?.fields).toMatchObject({
+        gatewayMaxTtlMs: 3_600_000,
+        label: "mac-mini-1",
+        workerMaxTtlMs: 1_800_000,
+      });
+
+      await harness.service.stop();
+    });
+
+    it("does not warn when the joining worker's own cap is at or above the gateway's", async () => {
+      const logger = new RecordingLogger();
+      const harness = fleet({ leaseMaxTtlMs: 3_600_000, logger });
+      await harness.service.start();
+      const worker = new ScriptedWorkerClient();
+      worker.leaseMaxTtlMs = 3_600_000;
+
+      await harness.join("wrk_1", worker);
+      await vi.waitFor(() => expect(harness.service.workers.view("wrk_1")?.lease).toBeDefined());
+
+      expect(logger.warnings.some((entry) => entry.fields?.workerId === "wrk_1")).toBe(false);
+
+      await harness.service.stop();
+    });
+
+    it("does not repeat the warning on the periodic tick's re-read of an unchanged cap", async () => {
+      const logger = new RecordingLogger();
+      const harness = fleet({ leaseMaxTtlMs: 3_600_000, logger });
+      await harness.service.start();
+      const worker = new ScriptedWorkerClient();
+      worker.leaseMaxTtlMs = 1_800_000;
+
+      await harness.join("wrk_1", worker);
+      await vi.waitFor(() => expect(harness.service.workers.view("wrk_1")?.lease).toBeDefined());
+      const warningsAfterJoin = logger.warnings.filter(
+        (entry) => entry.fields?.workerId === "wrk_1",
+      ).length;
+      expect(warningsAfterJoin).toBe(1);
+
+      // The periodic backstop tick re-reads config.get alongside the catalog
+      // (`#runTick` -> `link.refresh({ includeCatalog: true })`) -- the worker's cap has not
+      // moved, so this must not warn again.
+      const callsBefore = worker.calls.filter((call) => call === "config.get").length;
+      harness.clock.advance(REFRESH_MS);
+      await vi.waitFor(() =>
+        expect(worker.calls.filter((call) => call === "config.get").length).toBeGreaterThan(
+          callsBefore,
+        ),
+      );
+
+      expect(logger.warnings.filter((entry) => entry.fields?.workerId === "wrk_1").length).toBe(
+        warningsAfterJoin,
+      );
+
+      await harness.service.stop();
+    });
+  });
+
   it("marks a worker incompatible when hello finds no overlapping range, and asks it nothing else", async () => {
     const harness = fleet();
     await harness.service.start();

src/gateway/service.ts

@@ -68,6 +68,9 @@ export interface GatewayServiceOptions {
   readonly authenticate: (credential: string | undefined) => Promise<UplinkAuthResult>;
   /** `gateway.disconnectedRetentionMs` (§6). */
   readonly retentionMs: number;
+  /** This gateway's own `lease.maxTtlMs` (§15) -- threaded straight into the registry, which
+   * warns when a connected worker's own reported cap is lower. */
+  readonly leaseMaxTtlMs: number;
   /** Where drained worker ids survive a restart (Decision 3). */
   readonly drainStore?: DrainStore;
   /** The principal the gateway announces to each worker at `hello`. */
@@ -101,6 +104,7 @@ export class GatewayService {
       // exactly `gw:<this gateway's instance id>`, the same shape requirement 27 stamps on
       // every requester id this gateway forwards, just without the trailing `:<requester>`.
       gatewayRequesterPrefix: `${options.principal}:`,
+      leaseMaxTtlMs: options.leaseMaxTtlMs,
       logger: this.#logger,
       retentionMs: options.retentionMs,
       ...(options.drainStore === undefined ? {} : { drainStore: options.drainStore }),

src/gateway/test-support.ts

@@ -80,6 +80,15 @@ export class ScriptedWorkerClient {
   catalog: CatalogOutput = catalogFixture([]);
   /** What `config.get` reports; the view carries it as a routing input (ADR 0005 §13). */
   downloadPolicy: DownloadPolicy = "on-request";
+  /** What `config.get` reports for `lease.maxTtlMs` (ADR 0005 §15) -- the routing-adjacent
+   * counterpart to `downloadPolicy` above. Defaults comfortably above every gateway cap this
+   * suite's fixtures use, so a test that never sets it cannot accidentally trip the new warning;
+   * a test exercising §15 sets it explicitly. `config.get` always answers with a real
+   * `lease.maxTtlMs` when it answers at all (the field predates this change and is not
+   * optional on `Config`), so unlike `downloadPolicy` there is no "unset" state to script here
+   * -- the workerViewSchema field's own optionality is `config === undefined`, exercised at
+   * `WorkerRegistry`'s own level in `worker-registry.test.ts`, not through this fake. */
+  leaseMaxTtlMs = 24 * 60 * 60_000;
   readonly calls: string[] = [];
   /** Set to reject every call with this error -- e.g. a protocol mismatch. */
   failWith: unknown;
@@ -152,11 +161,14 @@ export class ScriptedWorkerClient {
   }
 
   // fallow-ignore-next-line unused-class-member -- reached structurally through the `SimlockAdminClient` the cast in `asClient()` produces; the audit cannot follow a member access through that.
-  async getConfig(): Promise<{ readonly downloads: { readonly policy: DownloadPolicy } }> {
+  async getConfig(): Promise<{
+    readonly downloads: { readonly policy: DownloadPolicy };
+    readonly lease: { readonly maxTtlMs: number };
+  }> {
     this.calls.push("config.get");
     if (this.hangingCalls.has("config.get")) return new Promise<never>(() => {});
     this.#throwIfFailing();
-    return { downloads: { policy: this.downloadPolicy } };
+    return { downloads: { policy: this.downloadPolicy }, lease: { maxTtlMs: this.leaseMaxTtlMs } };
   }
 
   // fallow-ignore-next-line unused-class-member -- reached structurally through the `SimlockAdminClient` the cast in `asClient()` produces; the audit cannot follow a member access through that.

src/gateway/worker-link.ts

@@ -360,7 +360,15 @@ export class WorkerLink {
       queueDepth: status.queueDepth,
       version: client.daemonVersion,
       ...(catalog === undefined ? {} : { catalog: catalog.platforms }),
-      ...(config === undefined ? {} : { downloads: { policy: config.downloads.policy } }),
+      ...(config === undefined
+        ? {}
+        : {
+            downloads: { policy: config.downloads.policy },
+            // ADR 0005 §15: the one other field this gateway keeps out of a worker's config,
+            // alongside `downloads.policy` above -- `WorkerRegistry#refresh` is where it is
+            // compared against the gateway's own `lease.maxTtlMs` and warned about.
+            lease: { maxTtlMs: config.lease.maxTtlMs },
+          }),
     });
   }
 

src/gateway/worker-registry.test.ts

@@ -2,22 +2,45 @@ import { describe, expect, it } from "vitest";
 
 import { EventBus, type EventEnvelope } from "../bus/index.js";
 import { PROTOCOL_VERSION_RANGE } from "../contract/index.js";
-import { FakeClock } from "../ports/index.js";
+import { FakeClock, type Logger } from "../ports/index.js";
 import { MemoryDrainStore } from "./drain-store.js";
 import { leaseFixture } from "./test-support.js";
 import { WorkerRegistry } from "./worker-registry.js";
 
 const RETENTION_MS = 24 * 60 * 60_000;
+/** Matches `core/config.ts`'s own default, so a test that does not care about ADR 0005 §15's
+ * warning gets a cap no fixture's `ttlMs` ever comes near. */
+const DEFAULT_LEASE_MAX_TTL_MS = 4 * 60 * 60_000;
 /** Matches `service.test.ts`'s `principal: "gw:instance-1"` -- ADR 0005 §14/§27's own-lease
  * prefix is that principal plus a trailing `:`. */
 const GATEWAY_REQUESTER_PREFIX = "gw:instance-1:";
 
+/** Records every `warn` call, the same shape `service.test.ts`'s own `RecordingLogger` uses --
+ * §15's warning is asserted on directly rather than only on the view it leaves behind. */
+class RecordingLogger implements Logger {
+  readonly warnings: Array<{ message: string; fields?: Record<string, unknown> }> = [];
+
+  debug(): void {}
+  info(): void {}
+  warn(message: string, fields?: Record<string, unknown>): void {
+    this.warnings.push(fields === undefined ? { message } : { fields, message });
+  }
+  error(): void {}
+  child(): Logger {
+    return this;
+  }
+}
+
 function registry(
   options: {
     readonly drainStore?: MemoryDrainStore;
     /** Omit to get the default fixture prefix; pass `null` explicitly (H3) to build a registry
      * with no `gatewayRequesterPrefix` at all, the way `dispatcher.test.ts`'s harness does. */
     readonly gatewayRequesterPrefix?: string | null;
+    /** ADR 0005 §15's own cap. Defaults to `core/config.ts`'s own default so a test that never
+     * reports a worker `lease.maxTtlMs` cannot accidentally trip the new warning. */
+    readonly leaseMaxTtlMs?: number;
+    readonly logger?: Logger;
   } = {},
 ) {
   const clock = new FakeClock(1_000);
@@ -31,9 +54,11 @@ function registry(
   const workers = new WorkerRegistry({
     clock,
     eventBus,
+    leaseMaxTtlMs: options.leaseMaxTtlMs ?? DEFAULT_LEASE_MAX_TTL_MS,
     retentionMs: RETENTION_MS,
     ...(gatewayRequesterPrefix === undefined ? {} : { gatewayRequesterPrefix }),
     ...(options.drainStore === undefined ? {} : { drainStore: options.drainStore }),
+    ...(options.logger === undefined ? {} : { logger: options.logger }),
   });
   return { clock, events, workers };
 }
@@ -113,6 +138,79 @@ describe("WorkerRegistry", () => {
     expect(workers.view("wrk_1")).toBeUndefined();
   });
 
+  describe("warning on a worker's lower lease.maxTtlMs (ADR 0005 §15)", () => {
+    it("warns once a worker's own cap is refreshed in below the gateway's", () => {
+      const logger = new RecordingLogger();
+      const { workers } = registry({ leaseMaxTtlMs: 3_600_000, logger });
+      workers.connected("wrk_1", "mac-mini-1", "0.3.0");
+
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 1_800_000 } });
+
+      expect(logger.warnings).toHaveLength(1);
+      expect(logger.warnings[0]).toMatchObject({
+        fields: {
+          gatewayMaxTtlMs: 3_600_000,
+          label: "mac-mini-1",
+          workerId: "wrk_1",
+          workerMaxTtlMs: 1_800_000,
+        },
+      });
+    });
+
+    it("does not warn when a worker's own cap is at or above the gateway's", () => {
+      const logger = new RecordingLogger();
+      const { workers } = registry({ leaseMaxTtlMs: 3_600_000, logger });
+      workers.connected("wrk_1", undefined, "0.3.0");
+
+      // Exactly equal, and then strictly above -- neither is "below".
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 3_600_000 } });
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 7_200_000 } });
+
+      expect(logger.warnings).toEqual([]);
+    });
+
+    it("does not warn, and does not crash, when a worker reports no cap at all", () => {
+      const logger = new RecordingLogger();
+      const { workers } = registry({ leaseMaxTtlMs: 3_600_000, logger });
+      workers.connected("wrk_1", undefined, "0.3.0");
+
+      // No `lease` key on the snapshot: exactly what an event-driven refresh sends today
+      // (`config.get` is only read alongside the catalog), and what an incompatible or
+      // config.get-failed worker's view carries forever.
+      expect(() => workers.refresh("wrk_1", { queueDepth: 1 })).not.toThrow();
+
+      expect(workers.view("wrk_1")?.lease).toBeUndefined();
+      expect(logger.warnings).toEqual([]);
+    });
+
+    it("does not repeat the warning on a later refresh reporting the same lower cap", () => {
+      const logger = new RecordingLogger();
+      const { workers } = registry({ leaseMaxTtlMs: 3_600_000, logger });
+      workers.connected("wrk_1", undefined, "0.3.0");
+
+      // The periodic backstop tick re-reads config.get (and so `lease.maxTtlMs`) on every
+      // refresh alongside the catalog (`WorkerLink#rebuildView`) -- an unchanged report must
+      // not turn into a warning every `refreshIntervalMs`.
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 1_800_000 } });
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 1_800_000 } });
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 1_800_000 } });
+
+      expect(logger.warnings).toHaveLength(1);
+    });
+
+    it("warns again if the cap drops further while already below the gateway's", () => {
+      const logger = new RecordingLogger();
+      const { workers } = registry({ leaseMaxTtlMs: 3_600_000, logger });
+      workers.connected("wrk_1", undefined, "0.3.0");
+
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 1_800_000 } });
+      workers.refresh("wrk_1", { lease: { maxTtlMs: 900_000 } });
+
+      expect(logger.warnings).toHaveLength(2);
+      expect(logger.warnings[1]?.fields).toMatchObject({ workerMaxTtlMs: 900_000 });
+    });
+  });
+
   it("marks a version-mismatched worker incompatible with both ranges, and rejects it", () => {
     const { events, workers } = registry();