fix(server): size agent JWT TTL to the run's own wall-clock budget (RBR-1035 AC1/AC4) (#29)

RBR-1014 root cause: a flat instance-wide JWT TTL (default 3600s) that agent
runs routinely outlive, causing a 401 mid-run that the client's retry/timeout
path was masking as host-saturation.

RBR-1034 (CISO) decided agents must not hold or mint their own JWT signing
secret, which forecloses in-process refresh (option b from the RBR-1035
plan). This lands option (a): mint the token with a TTL derived from the
run's own configured max wall clock (adapter timeoutSec) plus a 5-minute
margin, falling back to the existing instance default when no run timeout is
configured (unbounded runs) or when the derived minimum does not exceed the
default.

- server/src/agent-auth-jwt.ts: createLocalAgentJwt takes an optional
  minTtlSeconds and uses it when it exceeds the configured default TTL.
- server/src/services/heartbeat.ts: derive minTtlSeconds from
  resolveHeartbeatRunTimeoutPolicy(agent.adapterType, runtimeConfig) +
  AGENT_JWT_RUN_TIMEOUT_MARGIN_SECONDS at the JWT-minting call site.
- server/src/__tests__/agent-auth-jwt.test.ts: RBR-1035 AC1/AC4 regression
  tests — long-budget run gets a TTL that outlives the flat 1h default and
  is still valid past it; short-budget run keeps the tighter default and is
  provably dead before a long-budget token minted at the same instant;
  non-finite/non-positive minTtlSeconds falls back to the default.

AC #2 (401 fail-fast taxonomy) and AC #3 (JWT-secret exposure policy) are out
of scope here per the CEO's rescoping comment on this issue: AC#2 is already
in progress on RBR-1036 (cli/src/client/http.ts, separate worktree) and AC#3
is closed by RBR-1034's decision, which this change complies with (no
agent-held or agent-minted signing secret anywhere in this path).

Verification: `npx vitest run src/__tests__/agent-auth-jwt.test.ts` — 21/21
passing (17 pre-existing + 4 new). Touched files parse clean under esbuild.
Full `tsc --noEmit` was not run this pass — host load was 13-19 on a 12-core
box (RBR-974 guardrail) and a prior foreground tsc attempt exceeded the
600s budget without completing; a narrower, targeted check was used per the
AGENTS.md verification guidance instead of forcing a full workspace
typecheck under saturation.

Co-authored-by: Ben Hamilton <benhami@gmail.com>

Author: PraeSynBH

server/src/__tests__/agent-auth-jwt.test.ts

@@ -218,4 +218,121 @@ describe("agent local JWT", () => {
       run_id: "run-1",
     });
   });
+
+  // RBR-1035 AC1 + AC4 regression test: the JWT TTL must be sized to the
+  // run's own configured max wall clock (+ margin, computed by the caller
+  // in heartbeat.ts) instead of always trusting the flat instance-wide
+  // default. This is the fix for RBR-1014: a hard 1h default TTL that agent
+  // runs routinely outlive. Note this is distinct from RBR-1036's AC4
+  // (which tests the client's fail-fast-on-401 behavior, not TTL sizing) —
+  // this suite only asserts token-minting/expiry behavior. `minTtlSeconds`
+  // is the 5th positional arg on this fork/master signature (no
+  // responsibleUserId/keyScope params here yet).
+  describe("run-derived TTL (RBR-1035 AC1)", () => {
+    it("mints a token whose exp covers a long-budget run when minTtlSeconds exceeds the default TTL", () => {
+      process.env[ttlEnv] = "3600"; // instance-wide default: 1h
+      vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+      // Simulate a run configured with a wall-clock budget well beyond the
+      // 1h default (e.g. timeoutSec 21600 + a 300s margin, as computed by
+      // resolveHeartbeatRunTimeoutPolicy + AGENT_JWT_RUN_TIMEOUT_MARGIN_SECONDS
+      // in heartbeat.ts) and assert the minted token's lifetime is sized to
+      // that run budget, not clamped to the shorter instance default.
+      const runBudgetSeconds = 21600 + 300; // 6h05m
+      const token = createLocalAgentJwt(
+        "agent-1",
+        "company-1",
+        "claude_local",
+        "run-long",
+        runBudgetSeconds,
+      );
+      expect(token).not.toBeNull();
+
+      const claims = verifyLocalAgentJwt(token!);
+      expect(claims).not.toBeNull();
+      // exp - iat must equal the run's budget, not the 3600s instance default.
+      expect(claims!.exp - claims!.iat).toBe(runBudgetSeconds);
+      expect(claims!.exp - claims!.iat).toBeGreaterThan(3600);
+
+      // Prove the token is actually alive at the moment the flat 1h default
+      // would have already expired it — this is the exact RBR-1014 failure
+      // mode (401 mid-run masquerading as a timeout) that this fix closes.
+      vi.setSystemTime(new Date("2026-01-01T01:30:00.000Z")); // +90 minutes
+      expect(verifyLocalAgentJwt(token!)).not.toBeNull();
+    });
+
+    it("keeps the tighter instance default TTL for a short-budget run (does not raise the floor for every run)", () => {
+      process.env[ttlEnv] = "3600";
+      vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+      // A short-budget run (e.g. timeoutSec 60 + margin = 360s) must NOT
+      // widen the token lifetime beyond the instance default — only runs
+      // whose own budget exceeds the default should get a longer-lived
+      // token.
+      const shortRunBudgetSeconds = 360;
+      const token = createLocalAgentJwt(
+        "agent-1",
+        "company-1",
+        "claude_local",
+        "run-short",
+        shortRunBudgetSeconds,
+      );
+      expect(token).not.toBeNull();
+
+      const claims = verifyLocalAgentJwt(token!);
+      expect(claims).not.toBeNull();
+      expect(claims!.exp - claims!.iat).toBe(3600);
+    });
+
+    it("expires a short-budget-run token sooner than a long-budget-run token minted at the same instant", () => {
+      process.env[ttlEnv] = "3600";
+      vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+      const longToken = createLocalAgentJwt(
+        "agent-1",
+        "company-1",
+        "claude_local",
+        "run-long",
+        14400,
+      );
+      const shortToken = createLocalAgentJwt(
+        "agent-1",
+        "company-1",
+        "claude_local",
+        "run-short",
+        300,
+      );
+
+      const longClaims = verifyLocalAgentJwt(longToken!);
+      const shortClaims = verifyLocalAgentJwt(shortToken!);
+      expect(longClaims).not.toBeNull();
+      expect(shortClaims).not.toBeNull();
+      expect(longClaims!.exp).toBeGreaterThan(shortClaims!.exp);
+
+      // Advance past the short run's ceiling (3600s default, since 300 <
+      // default) but well before the long run's 14400s budget elapses: the
+      // short-budget token must be dead while the long-budget token is
+      // still alive.
+      vi.setSystemTime(new Date("2026-01-01T02:00:00.000Z")); // +2h
+      expect(verifyLocalAgentJwt(shortToken!)).toBeNull();
+      expect(verifyLocalAgentJwt(longToken!)).not.toBeNull();
+    });
+
+    it("ignores a non-finite or non-positive minTtlSeconds and falls back to the instance default", () => {
+      process.env[ttlEnv] = "3600";
+      vi.setSystemTime(new Date("2026-01-01T00:00:00.000Z"));
+
+      for (const invalid of [NaN, -100, 0]) {
+        const token = createLocalAgentJwt(
+          "agent-1",
+          "company-1",
+          "claude_local",
+          "run-1",
+          invalid,
+        );
+        const claims = verifyLocalAgentJwt(token!);
+        expect(claims!.exp - claims!.iat).toBe(3600);
+      }
+    });
+  });
 });

server/src/agent-auth-jwt.ts

@@ -88,18 +88,39 @@ function safeCompare(a: string, b: string) {
   return timingSafeEqual(left, right);
 }
 
-export function createLocalAgentJwt(agentId: string, companyId: string, adapterType: string, runId: string) {
+export function createLocalAgentJwt(
+  agentId: string,
+  companyId: string,
+  adapterType: string,
+  runId: string,
+  minTtlSeconds?: number | null,
+) {
   const config = jwtConfig();
   if (!config) return null;
 
+  // RBR-1035 AC1: the token must outlive the run it authenticates, not just
+  // the instance-wide default TTL. `minTtlSeconds` is derived by the caller
+  // from the run's own configured max wall clock (adapter `timeoutSec`) plus
+  // a safety margin — see the JWT-minting call site in heartbeat.ts. A hard
+  // 1h default TTL is what caused RBR-1014: agent runs routinely exceed one
+  // hour, especially under host load, and once the token expires mid-run
+  // every subsequent Paperclip API call fails with no recovery path. Using
+  // the larger of the configured default and the run-derived minimum means a
+  // bounded run is always covered without raising the TTL floor for every
+  // run (e.g. short-lived ones keep the tighter default expiry).
+  const ttlSeconds =
+    typeof minTtlSeconds === "number" && Number.isFinite(minTtlSeconds) && minTtlSeconds > config.ttlSeconds
+      ? Math.floor(minTtlSeconds)
+      : config.ttlSeconds;
+
   const now = Math.floor(Date.now() / 1000);
   const claims: LocalAgentJwtClaims = {
     sub: agentId,
     company_id: companyId,
     adapter_type: adapterType,
     run_id: runId,
     iat: now,
-    exp: now + config.ttlSeconds,
+    exp: now + ttlSeconds,
     iss: config.issuer,
     aud: config.audience,
   };

server/src/services/heartbeat.ts

@@ -92,6 +92,7 @@ import {
   buildHeartbeatRunStopMetadata,
   mergeHeartbeatRunStopMetadata,
   normalizeMaxTurnStopReason,
+  resolveHeartbeatRunTimeoutPolicy,
 } from "./heartbeat-stop-metadata.js";
 import {
   classifyRunLiveness,
@@ -255,6 +256,12 @@ const PAPERCLIP_HARNESS_CHECKOUT_KEY = "paperclipHarnessCheckedOut";
 const DETACHED_PROCESS_ERROR_CODE = "process_detached";
 const REPO_ONLY_CWD_SENTINEL = "/__paperclip_repo_only__";
 const MANAGED_WORKSPACE_GIT_CLONE_TIMEOUT_MS = 10 * 60 * 1000;
+// RBR-1035 AC1: margin added on top of a run's configured max wall clock
+// (`timeoutSec`) when sizing that run's agent JWT TTL. Covers clock skew
+// between the token-minting request and the adapter process actually
+// starting, plus any tail-end API calls the run makes right up against its
+// own timeout (e.g. a final disposition PATCH).
+const AGENT_JWT_RUN_TIMEOUT_MARGIN_SECONDS = 5 * 60;
 const MAX_INLINE_WAKE_COMMENTS = 8;
 const MAX_INLINE_WAKE_COMMENT_BODY_CHARS = 4_000;
 const MAX_INLINE_WAKE_COMMENT_BODY_TOTAL_CHARS = 12_000;
@@ -10915,8 +10922,25 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
       };
 
       const adapter = getServerAdapter(agent.adapterType);
+      // RBR-1035 AC1: derive the JWT TTL from the run's own configured max
+      // wall clock (adapter `timeoutSec`) plus a safety margin, rather than
+      // trusting the instance-wide 1h default to always outlive the run.
+      // This is deliberately (a) from the RBR-1035 plan — a fixed max-TTL
+      // computed from the run's own bound — not (b) an in-process refresh:
+      // refreshing would require the agent process to either hold a signing
+      // secret (the exact anti-pattern under CISO review in RBR-1034) or
+      // call a not-yet-built orchestrator-brokered refresh endpoint. No new
+      // runtime moving parts are needed for a run whose maximum duration is
+      // already known up front. Runs with no configured timeout (`timeoutSec`
+      // unset/0, i.e. unbounded) keep the default TTL — there is no run
+      // duration to size the token to.
+      const runTimeoutPolicy = resolveHeartbeatRunTimeoutPolicy(agent.adapterType, runtimeConfig);
+      const jwtMinTtlSeconds =
+        runTimeoutPolicy.timeoutConfigured && runTimeoutPolicy.effectiveTimeoutSec
+          ? Math.ceil(runTimeoutPolicy.effectiveTimeoutSec) + AGENT_JWT_RUN_TIMEOUT_MARGIN_SECONDS
+          : null;
       const authToken = adapter.supportsLocalAgentJwt
-        ? createLocalAgentJwt(agent.id, agent.companyId, agent.adapterType, run.id)
+        ? createLocalAgentJwt(agent.id, agent.companyId, agent.adapterType, run.id, jwtMinTtlSeconds)
         : null;
       if (adapter.supportsLocalAgentJwt && !authToken) {
         logger.warn(