Services refuse to boot without their required config, and cluster-agent routes split one per file (#2082)

Every service now fails fast at startup when a required environment
variable or database parameter is missing, instead of booting
half-configured. `requiredEnv` and new enforce helpers in `libs/shared`
do the checking, and `pg-pool` refuses a connection with missing
parameters. Request body limits and the event drain timeout now come
from shared constants, so the Floor, lore-api, the event-router and
cluster-agent can no longer disagree about them.

cluster-agent's 235-line `routes/cluster.ts` is split into one file per
endpoint under `routes/cluster/` (agents, jobs, pods, pod listing,
per-task tokens, restart), with the shared dependencies in
`cluster-route-deps.ts`. The heartbeat loop and registrant were tidied
along the way.

The branch also adds the `collaborative-feature-planning` spec.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: gedaiu

adrs/ADR-024-ubiquitous-language-execution-model.md

@@ -114,10 +114,10 @@ and lose the update; no `resourceVersion` ever crosses the wire.
   describes the read surface, which callers do still reach over HTTP.)*
   ([validated by reports created:false for code 409, so a redelivered claim is idempotent](apps/cluster-agent/src/outbound/kube-agent-api.test.ts#L26), [`kube-agent-api.test.ts:19`](apps/cluster-agent/src/outbound/kube-agent-api.test.ts#L19), [`kube-agent-api.test.ts:33`](apps/cluster-agent/src/outbound/kube-agent-api.test.ts#L33), [`kube-agent-api.test.ts:39`](apps/cluster-agent/src/outbound/kube-agent-api.test.ts#L39), [`kube-agent-api.test.ts:47`](apps/cluster-agent/src/outbound/kube-agent-api.test.ts#L47))
 - A missing CR is an ordinary answer — `found:false` at 200, not a 404 that
-  would be indistinguishable from the route itself being absent. ([validated by answers 200 with found:false for a missing CR, not 404](apps/cluster-agent/src/transport/routes/cluster.test.ts#L73), [`cluster.test.ts:131`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L131))
+  would be indistinguishable from the route itself being absent. ([validated by answers 200 with found:false for a missing CR, not 404](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L73), [`cluster-routes.test.ts:131`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L131))
 - The list serves ONE apiserver page per call and the caller drives `continue`.
   A one-shot list is not a convenience: 180 accumulated CRs at ~1.4MB of status
-  each blew Node's heap and crash-looped the Floor on 2026-07-24. ([validated by passes the caller's continue token straight through, one page per call](apps/cluster-agent/src/transport/routes/cluster.test.ts#L84), [`cluster.test.ts:97`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L97), [`cluster.test.ts:228`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L228), [`cluster.test.ts:218`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L218))
+  each blew Node's heap and crash-looped the Floor on 2026-07-24. ([validated by passes the caller's continue token straight through, one page per call](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L84), [`cluster-routes.test.ts:97`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L97), [`cluster-routes.test.ts:228`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L228), [`cluster-routes.test.ts:218`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L218))
 - The paging the route requires is walked by the CLIENT, not pushed onto every
   caller: `listByLabel` follows `continue` to the end and returns the whole
   match. A truncated list is worse than a failed one — it answers, and the
@@ -148,7 +148,7 @@ and lose the update; no `resourceVersion` ever crosses the wire.
 - `DELETE /api/cluster/per-task-tokens/{taskId}` reclaims a terminal task's
   Secret key and catalog clones — the one per-task-token operation that stays
   a route, since a settled task's cleanup runs from the Floor, not the cluster
-  that provisioned. ([validated by reclaims a task's token and catalog clones](apps/cluster-agent/src/transport/routes/cluster.test.ts#L207))
+  that provisioned. ([validated by reclaims a task's token and catalog clones](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L207))
 - One call also means one OUTCOME: a provision whose recipe pair fails to land
   takes back everything it had already provisioned — the Secret key AND any
   catalog object that landed before the failure — before it throws. `cleanup`
@@ -165,9 +165,9 @@ and lose the update; no `resourceVersion` ever crosses the wire.
   from being amputated by a merge split across the network.
   ([validated by writes the station before the agent definition that points at it](apps/cluster-agent/src/outbound/paired-writes.test.ts#L27), [`paired-writes.test.ts:35`](apps/cluster-agent/src/outbound/paired-writes.test.ts#L35), [`paired-writes.test.ts:54`](apps/cluster-agent/src/outbound/paired-writes.test.ts#L54))
 - The log tail is clamped by the AGENT, because the Floor's clamp no longer
-  protects this process's heap. ([validated by clamps the tail server-side rather than trusting the caller](apps/cluster-agent/src/transport/routes/cluster.test.ts#L121), [`cluster.test.ts:187`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L187), [`cluster.test.ts:197`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L197), [`cluster.test.ts:177`](apps/cluster-agent/src/transport/routes/cluster.test.ts#L177))
+  protects this process's heap. ([validated by clamps the tail server-side rather than trusting the caller](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L121), [`cluster-routes.test.ts:187`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L187), [`cluster-routes.test.ts:197`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L197), [`cluster-routes.test.ts:177`](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L177))
 - Every route requires the same bearer token every other service-to-service
-  call presents. ([validated by refuses every route without a bearer token](apps/cluster-agent/src/transport/routes/cluster.test.ts#L143), [validated by refuses to restart without a bearer token](apps/cluster-agent/src/transport/routes/cluster.test.ts#L266))
+  call presents. ([validated by refuses every route without a bearer token](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L143), [validated by refuses to restart without a bearer token](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L266))
 - A CR the controller has not stamped yet reads as Pending rather than absent —
   the distinction a watcher acts on. ([validated by a CR the controller has not stamped yet maps to Pending, not absence](libs/shared/src/outbound/cluster/agent-node-status.test.ts#L6), [`agent-node-status.test.ts:12`](libs/shared/src/outbound/cluster/agent-node-status.test.ts#L12))
 - An empty minted token is refused where the cause is legible, rather than
@@ -189,7 +189,7 @@ scoped settling a run to the one cluster this Floor can reach; it now settles
 from the event's own report, which carries the full status. The distinction
 above still governs the READ surface — the reconcile pass, the reaper's status
 probe, the pod-log reads — where a caller genuinely has to ask.*
-  ([validated by answers 200 with found:false for a missing CR, not 404](apps/cluster-agent/src/transport/routes/cluster.test.ts#L73), [`k8s-errors.test.ts:28`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L31), [`k8s-errors.test.ts:44`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L47), [`k8s-errors.test.ts:56`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L59), [`kubernetes.test.ts:21`](apps/floor/src/events/handlers/kubernetes.test.ts#L21), [`kubernetes.test.ts:49`](apps/floor/src/events/handlers/kubernetes.test.ts#L49), [`kubernetes.test.ts:55`](apps/floor/src/events/handlers/kubernetes.test.ts#L55))
+  ([validated by answers 200 with found:false for a missing CR, not 404](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L73), [`k8s-errors.test.ts:28`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L31), [`k8s-errors.test.ts:44`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L47), [`k8s-errors.test.ts:56`](apps/cluster-agent/src/lib/k8s-errors.test.ts#L59), [`kubernetes.test.ts:21`](apps/floor/src/events/handlers/kubernetes.test.ts#L21), [`kubernetes.test.ts:49`](apps/floor/src/events/handlers/kubernetes.test.ts#L49), [`kubernetes.test.ts:55`](apps/floor/src/events/handlers/kubernetes.test.ts#L55))
 
 The reconcile pass keeps paging, and its seam narrowed with the cut: it now
 depends on one page-fetch method rather than a slice of a Kubernetes client, so
@@ -200,7 +200,7 @@ The Role this service carries also closes two gaps the Floor had been silently
 living with: it never held `delete` on `agents` or `agents/status`, yet issued
 both at sites that swallowed the failure — which is why the CR prune could
 never actually shrink the pile it was written to shrink.
-  ([validated by deletes a CR — the verb the Floor's RBAC never granted](apps/cluster-agent/src/transport/routes/cluster.test.ts#L108))
+  ([validated by deletes a CR — the verb the Floor's RBAC never granted](apps/cluster-agent/src/transport/routes/cluster/cluster-routes.test.ts#L108))
 
 Hierarchy: **Factory ⊃ Floor(s) ⊃ AssemblyLines ⊃ Stations ⊃ Agents** — the design
 side; its runtime shadow is **AssemblyRun ⊃ StationRuns ⊃ Agents**.

apps/cluster-agent/README.md

@@ -83,7 +83,7 @@ probe the apiserver.
 | `LORE_AGENTS_NAMESPACE` | Namespace it acts on (default `ai-agents`) |
 | `LORE_AGENT_SECRETS_NAME` | Secret holding per-task token keys (default `agent-secrets`) |
 | `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | The GitHub App triple used to mint per-task installation tokens |
-| `LORE_CLUSTER_AGENT_IDENTITY_SECRET` / `_NAMESPACE` / `_KEY` | Where the registered `{id, token}` persists; local runs fall back to `LORE_CLUSTER_AGENT_IDENTITY_FILE` |
+| `LORE_CLUSTER_AGENT_IDENTITY_SECRET` / `_NAMESPACE` / `_KEY` | Required. The Kubernetes Secret the registered `{id, token}` persists in (`_KEY` defaults to `identity.json`); `npm start` points it at minikube |
 
 The first three have no defaults and no off switch: the process exits naming
 whichever are missing.

apps/cluster-agent/src/domain/cluster-deps.ts

@@ -1,24 +1,18 @@
 /** The cluster surface this agent exposes: what the Kubernetes clients in `outbound` provide and what the `transport` routes call — a contract owned by neither side. */
 
-import type {
-  Agent as AgentCr,
-  AgentDefinition,
-  Station,
-} from "@re-cinq/agent-contracts";
+import type { Agent as AgentCr } from "@re-cinq/agent-contracts";
 import type {
   AgentPodInfo,
   PodSummary,
   RunningPodInfo,
 } from "@re-cinq/lore-shared";
+import type { Page, PageRequest } from "@re-cinq/lore-shared/lib/paginate.js";
+import type { CrdPair } from "@re-cinq/lore-shared/project/agents/agent-crd.js";
 
 export interface ClusterDeps {
   agents: {
     get(name: string): Promise<AgentCr | null>;
-    list(opts: {
-      labelSelector?: string;
-      limit: number;
-      continue?: string;
-    }): Promise<{ items: AgentCr[]; continueToken?: string }>;
+    list(request: PageRequest): Promise<Page<AgentCr>>;
     remove(name: string): Promise<void>;
   };
   pods: {
@@ -32,10 +26,7 @@ export interface ClusterDeps {
     cleanup(taskId: string): Promise<void>;
   };
   catalog: {
-    applyPair(pair: {
-      agentDefinition: AgentDefinition;
-      station: Station;
-    }): Promise<void>;
+    applyPair(pair: CrdPair): Promise<void>;
     deletePair(name: string): Promise<void>;
   };
 }

apps/cluster-agent/src/domain/identity.ts

@@ -10,7 +10,9 @@ export interface IdentityStore {
   save(identity: ClusterAgentIdentity): Promise<void>;
 }
 
-/** Where the identity persists — decided at boot so a half-configured Secret store refuses to start instead of idling behind a green /healthz. */
-export type IdentityStoreConfig =
-  | { kind: "file"; path: string }
-  | { kind: "secret"; name: string; namespace: string; key: string };
+/** The Secret the identity persists in — decided at boot so a half-configured store refuses to start instead of idling behind a green /healthz. */
+export interface IdentityStoreConfig {
+  name: string;
+  namespace: string;
+  key: string;
+}

apps/cluster-agent/src/events/claim/heartbeat-loop.test.ts

@@ -3,6 +3,7 @@ import {
   heartbeatIntervalMs,
   heartbeatOnce,
   runHeartbeatLoop,
+  type HeartbeatOutcome,
 } from "./heartbeat-loop.js";
 
 const IDENTITY = { id: "agent-1", token: "lca_tok" };
@@ -110,11 +111,7 @@ describe("heartbeatOnce", () => {
 
 describe("runHeartbeatLoop", () => {
   it("beats at the fixed interval and re-registers on an unauthorized beat", async () => {
-    const outcomes: Array<"ok" | "unauthorized" | "error"> = [
-      "ok",
-      "unauthorized",
-      "error",
-    ];
+    const outcomes: HeartbeatOutcome[] = ["ok", "unauthorized", "error"];
     const sleeps: number[] = [];
     let reRegistered = 0;
     let ticks = 0;

apps/cluster-agent/src/events/claim/heartbeat-loop.ts

@@ -19,10 +19,13 @@ export interface HeartbeatDeps {
   log?: (line: string) => void;
 }
 
-/** One beat. Returns "ok" | "unauthorized" | "error"; never throws. */
+/** What one beat concluded: the cluster answered, refused the credential, or could not be reached. */
+export type HeartbeatOutcome = "ok" | "unauthorized" | "error";
+
+/** One beat; never throws. */
 export async function heartbeatOnce(
   deps: HeartbeatDeps,
-): Promise<"ok" | "unauthorized" | "error"> {
+): Promise<HeartbeatOutcome> {
   const { id, token } = deps.identity();
   const log = heartbeatLog(deps);
 
@@ -79,9 +82,11 @@ export async function runHeartbeatLoop(deps: HeartbeatLoopDeps): Promise<void> {
   await runPollLoop<"ok" | "unauthorized" | "error">({
     tick: deps.beat,
     onOutcome: async (outcome) => {
-      if (outcome === "unauthorized") {
-        await deps.reRegister();
+      if (outcome !== "unauthorized") {
+        return;
       }
+
+      await deps.reRegister();
     },
     delayFor: () => deps.intervalMs,
     sleep: deps.sleep,

apps/cluster-agent/src/events/claim/registrant.ts

@@ -42,6 +42,13 @@ export interface RegistrantOpts {
   running: () => boolean;
 }
 
+/** What registering takes: the triple to register with, where to persist the identity, and how to hand the minted token to the run pods. Named because both `establishIdentity` and the single-flight re-registration take exactly this. */
+export interface RegistrationOpts {
+  config: RegistrationConfig;
+  store: IdentityStore;
+  publishTelemetryCredential: (id: ClusterAgentIdentity) => Promise<void>;
+}
+
 // What both side loops need: where to talk, who this cluster is, and whether the process is still up. One shape because they are started together and stopped together.
 interface SideLoopOpts {
   env: NodeJS.ProcessEnv;
@@ -77,10 +84,8 @@ export async function runRegistrant(opts: RegistrantOpts): Promise<void> {
   });
 }
 
-/** Registers, and hands back the identity as a GETTER rather than a value: a 401 rotates it mid-run, and every loop must read the current one rather than the one it captured at startup. */
-async function establishIdentity(
-  opts: Pick<RegistrantOpts, "config" | "store" | "publishTelemetryCredential">,
-): Promise<{
+/** Hands back the identity as a GETTER: a 401 rotates it mid-run, and every loop must read the current one, not the one it captured at startup. */
+async function establishIdentity(opts: RegistrationOpts): Promise<{
   identity: () => ClusterAgentIdentity;
   reRegister: () => Promise<ClusterAgentIdentity | null>;
 }> {
@@ -100,7 +105,7 @@ async function establishIdentity(
 
 // The first registration, with the line that says this cluster is now claiming. Announced here rather than by the caller because the id only exists once registration has succeeded.
 async function registerAndAnnounce(
-  opts: Pick<RegistrantOpts, "config" | "store" | "publishTelemetryCredential">,
+  opts: RegistrationOpts,
 ): Promise<ClusterAgentIdentity> {
   const identity = await registerWithBackoff({
     config: opts.config,

apps/cluster-agent/src/events/claim/start-claim-loop.ts

@@ -10,10 +10,7 @@ import { writeAgentEventsAuth } from "./agent-events-secret.js";
 import { stopLatch } from "../../lib/stop-latch.js";
 import { runRegistrant, type RegistrantOpts } from "./registrant.js";
 import { enforceCatalogProfile } from "../../work/catalog/catalog-sync-loop.js";
-import {
-  FileIdentityStore,
-  identityStoreConfig,
-} from "../../outbound/identity-store.js";
+import { identityStoreConfig } from "../../outbound/identity-store.js";
 import type {
   ClusterAgentIdentity,
   IdentityStore,
@@ -90,13 +87,15 @@ function rotationSlot(): {
   };
 }
 
-/** Detached on purpose: `startClaimLoop` returns a handle immediately so a caller can stop the agent before it has finished registering. The catch is unreachable by design — register and claim never throw — but a defect here must surface as a log rather than an unhandled rejection that kills the process. */
+/** Detached so a caller can stop the agent before it registers; register and claim never throw, so the catch only turns a defect into a log instead of a process-killing unhandled rejection. */
 function launchRegistrant(
   storeConfig: IdentityStoreConfig,
   opts: Omit<RegistrantOpts, "store">,
 ): void {
-  void buildIdentityStore(storeConfig)
-    .then((store) => runRegistrant({ ...opts, store }))
+  void Promise.resolve(storeConfig)
+    .then((config) =>
+      runRegistrant({ ...opts, store: buildIdentityStore(config) }),
+    )
     .catch((err) => {
       console.error(
         "[cluster-agent] claim loop crashed — this agent will not register or claim until restarted:",
@@ -138,14 +137,8 @@ function publishCredential(
   };
 }
 
-/** In a cluster the identity persists through the Kubernetes Secret API — the chart mounts the container read-only, so a file write would EROFS and strand the identity. File store only for local runs. */
-async function buildIdentityStore(
-  config: IdentityStoreConfig,
-): Promise<IdentityStore> {
-  if (config.kind === "file") {
-    return new FileIdentityStore(config.path);
-  }
-
+/** Through the Kubernetes Secret API, never a file: the chart mounts the container read-only, so a file write would EROFS and strand the identity. */
+function buildIdentityStore(config: IdentityStoreConfig): IdentityStore {
   return new KubeIdentityStore(
     kubeIdentitySecretsApi(config.namespace),
     config.name,